comparison: usbdrv/Readme.txt
usbdrv/Readme.txt
- changeset 0
- 9e9b2c78bd31
equal
deleted
inserted
replaced
| -1:000000000000 | 0:9e9b2c78bd31 |
|---|---|
| 1 This is the Readme file to Objective Development's firmware-only USB driver | |
| 2 for Atmel AVR microcontrollers. For more information please visit | |
| 3 http://www.obdev.at/vusb/ | |
| 4 | |
| 5 This directory contains the USB firmware only. Copy it as-is to your own | |
| 6 project and add all .c and .S files to your project (these files are marked | |
| 7 with an asterisk in the list below). Then copy usbconfig-prototype.h as | |
| 8 usbconfig.h to your project and edit it according to your configuration. | |
| 9 | |
| 10 | |
| 11 TECHNICAL DOCUMENTATION | |
| 12 ======================= | |
| 13 The technical documentation (API) for the firmware driver is contained in the | |
| 14 file "usbdrv.h". Please read all of it carefully! Configuration options are | |
| 15 documented in "usbconfig-prototype.h". | |
| 16 | |
| 17 The driver consists of the following files: | |
| 18 Readme.txt ............. The file you are currently reading. | |
| 19 Changelog.txt .......... Release notes for all versions of the driver. | |
| 20 usbdrv.h ............... Driver interface definitions and technical docs. | |
| 21 * usbdrv.c ............... High level language part of the driver. Link this | |
| 22 module to your code! | |
| 23 * usbdrvasm.S ............ Assembler part of the driver. This module is mostly | |
| 24 a stub and includes one of the usbdrvasm*.S files | |
| 25 depending on processor clock. Link this module to | |
| 26 your code! | |
| 27 usbdrvasm*.inc ......... Assembler routines for particular clock frequencies. | |
| 28 Included by usbdrvasm.S, don't link it directly! | |
| 29 asmcommon.inc .......... Common assembler routines. Included by | |
| 30 usbdrvasm*.inc, don't link it directly! | |
| 31 usbconfig-prototype.h .. Prototype for your own usbdrv.h file. | |
| 32 * oddebug.c .............. Debug functions. Only used when DEBUG_LEVEL is | |
| 33 defined to a value greater than 0. Link this module | |
| 34 to your code! | |
| 35 oddebug.h .............. Interface definitions of the debug module. | |
| 36 usbportability.h ....... Header with compiler-dependent stuff. | |
| 37 usbdrvasm.asm .......... Compatibility stub for IAR-C-compiler. Use this | |
| 38 module instead of usbdrvasm.S when you assembler | |
| 39 with IAR's tools. | |
| 40 License.txt ............ Open Source license for this driver. | |
| 41 CommercialLicense.txt .. Optional commercial license for this driver. | |
| 42 USB-ID-FAQ.txt ......... General infos about USB Product- and Vendor-IDs. | |
| 43 USB-IDs-for-free.txt ... List and terms of use for free shared PIDs. | |
| 44 | |
| 45 (*) ... These files should be linked to your project. | |
| 46 | |
| 47 | |
| 48 CPU CORE CLOCK FREQUENCY | |
| 49 ======================== | |
| 50 We supply assembler modules for clock frequencies of 12 MHz, 12.8 MHz, 15 MHz, | |
| 51 16 MHz, 16.5 MHz 18 MHz and 20 MHz. Other clock rates are not supported. The | |
| 52 actual clock rate must be configured in usbconfig.h. | |
| 53 | |
| 54 12 MHz Clock | |
| 55 This is the traditional clock rate of V-USB because it's the lowest clock | |
| 56 rate where the timing constraints of the USB spec can be met. | |
| 57 | |
| 58 15 MHz Clock | |
| 59 Similar to 12 MHz, but some NOPs inserted. On the other hand, the higher clock | |
| 60 rate allows for some loops which make the resulting code size somewhat smaller | |
| 61 than the 12 MHz version. | |
| 62 | |
| 63 16 MHz Clock | |
| 64 This clock rate has been added for users of the Arduino board and other | |
| 65 ready-made boards which come with a fixed 16 MHz crystal. It's also an option | |
| 66 if you need the slightly higher clock rate for performance reasons. Since | |
| 67 16 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the code | |
| 68 is somewhat tricky and has to insert a leap cycle every third byte. | |
| 69 | |
| 70 12.8 MHz and 16.5 MHz Clock | |
| 71 The assembler modules for these clock rates differ from the other modules | |
| 72 because they have been built for an RC oscillator with only 1% precision. The | |
| 73 receiver code inserts leap cycles to compensate for clock deviations. 1% is | |
| 74 also the precision which can be achieved by calibrating the internal RC | |
| 75 oscillator of the AVR. Please note that only AVRs with internal 64 MHz PLL | |
| 76 oscillator can reach 16.5 MHz with the RC oscillator. This includes the very | |
| 77 popular ATTiny25, ATTiny45, ATTiny85 series as well as the ATTiny26. Almost | |
| 78 all AVRs can reach 12.8 MHz, although this is outside the specified range. | |
| 79 | |
| 80 See the EasyLogger example at http://www.obdev.at/vusb/easylogger.html for | |
| 81 code which calibrates the RC oscillator based on the USB frame clock. | |
| 82 | |
| 83 18 MHz Clock | |
| 84 This module is closer to the USB specification because it performs an on the | |
| 85 fly CRC check for incoming packets. Packets with invalid checksum are | |
| 86 discarded as required by the spec. If you also implement checks for data | |
| 87 PID toggling on application level (see option USB_CFG_CHECK_DATA_TOGGLING | |
| 88 in usbconfig.h for more info), this ensures data integrity. Due to the CRC | |
| 89 tables and alignment requirements, this code is bigger than modules for other | |
| 90 clock rates. To activate this module, you must define USB_CFG_CHECK_CRC to 1 | |
| 91 and USB_CFG_CLOCK_KHZ to 18000 in usbconfig.h. | |
| 92 | |
| 93 20 MHz Clock | |
| 94 This module is for people who won't do it with less than the maximum. Since | |
| 95 20 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the code | |
| 96 uses similar tricks as the 16 MHz module to insert leap cycles. | |
| 97 | |
| 98 | |
| 99 USB IDENTIFIERS | |
| 100 =============== | |
| 101 Every USB device needs a vendor- and a product-identifier (VID and PID). VIDs | |
| 102 are obtained from usb.org for a price of 1,500 USD. Once you have a VID, you | |
| 103 can assign PIDs at will. | |
| 104 | |
| 105 Since an entry level cost of 1,500 USD is too high for most small companies | |
| 106 and hobbyists, we provide some VID/PID pairs for free. See the file | |
| 107 USB-IDs-for-free.txt for details. | |
| 108 | |
| 109 Objective Development also has some license offerings which include product | |
| 110 IDs. See http://www.obdev.at/vusb/ for details. | |
| 111 | |
| 112 | |
| 113 DEVELOPMENT SYSTEM | |
| 114 ================== | |
| 115 This driver has been developed and optimized for the GNU compiler version 3 | |
| 116 and 4. We recommend that you use the GNU compiler suite because it is freely | |
| 117 available. V-USB has also been ported to the IAR compiler and assembler. It | |
| 118 has been tested with IAR 4.10B/W32 and 4.12A/W32 on an ATmega8 with the | |
| 119 "small" and "tiny" memory model. Not every release is tested with IAR CC and | |
| 120 the driver may therefore fail to compile with IAR. Please note that gcc is | |
| 121 more efficient for usbdrv.c because this module has been deliberately | |
| 122 optimized for gcc. | |
| 123 | |
| 124 Gcc version 3 produces smaller code than version 4 due to new optimizing | |
| 125 capabilities which don't always improve things on 8 bit CPUs. The code size | |
| 126 generated by gcc 4 can be reduced with the compiler options | |
| 127 -fno-move-loop-invariants, -fno-tree-scev-cprop and | |
| 128 -fno-inline-small-functions in addition to -Os. On devices with more than | |
| 129 8k of flash memory, we also recommend the linker option --relax (written as | |
| 130 -Wl,--relax for gcc) to convert absolute calls into relative where possible. | |
| 131 | |
| 132 For more information about optimizing options see: | |
| 133 | |
| 134 http://www.tty1.net/blog/2008-04-29-avr-gcc-optimisations_en.html | |
| 135 | |
| 136 These optimizations are good for gcc 4.x. Version 3.x of gcc does not support | |
| 137 most of these options and produces good code anyway. | |
| 138 | |
| 139 | |
| 140 USING V-USB FOR FREE | |
| 141 ==================== | |
| 142 The AVR firmware driver is published under the GNU General Public License | |
| 143 Version 2 (GPL2) and the GNU General Public License Version 3 (GPL3). It is | |
| 144 your choice whether you apply the terms of version 2 or version 3. | |
| 145 | |
| 146 If you decide for the free GPL2 or GPL3, we STRONGLY ENCOURAGE you to do the | |
| 147 following things IN ADDITION to the obligations from the GPL: | |
| 148 | |
| 149 (1) Publish your entire project on a web site and drop us a note with the URL. | |
| 150 Use the form at http://www.obdev.at/vusb/feedback.html for your submission. | |
| 151 If you don't have a web site, you can publish the project in obdev's | |
| 152 documentation wiki at | |
| 153 http://www.obdev.at/goto.php?t=vusb-wiki&p=hosted-projects. | |
| 154 | |
| 155 (2) Adhere to minimum publication standards. Please include AT LEAST: | |
| 156 - a circuit diagram in PDF, PNG or GIF format | |
| 157 - full source code for the host software | |
| 158 - a Readme.txt file in ASCII format which describes the purpose of the | |
| 159 project and what can be found in which directories and which files | |
| 160 - a reference to http://www.obdev.at/vusb/ | |
| 161 | |
| 162 (3) If you improve the driver firmware itself, please give us a free license | |
| 163 to your modifications for our commercial license offerings. | |
| 164 | |
| 165 | |
| 166 COMMERCIAL LICENSES FOR V-USB | |
| 167 ============================= | |
| 168 If you don't want to publish your source code under the terms of the GPL, | |
| 169 you can simply pay money for V-USB. As an additional benefit you get | |
| 170 USB PIDs for free, reserved exclusively to you. See the file | |
| 171 "CommercialLicense.txt" for details. | |
| 172 |
