git.zerfleddert.de Git - fnordlicht-mini/blob - firmware/fnordlicht-controller/usbdrv/Readme.txt

   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 usbdrv.h unless you use the default
  53 12 MHz.
  54
  55 12 MHz Clock
  56 This is the traditional clock rate of V-USB because it's the lowest clock
  57 rate where the timing constraints of the USB spec can be met.
  58
  59 15 MHz Clock
  60 Similar to 12 MHz, but some NOPs inserted. On the other hand, the higher clock
  61 rate allows for some loops which make the resulting code size somewhat smaller
  62 than the 12 MHz version.
  63
  64 16 MHz Clock
  65 This clock rate has been added for users of the Arduino board and other
  66 ready-made boards which come with a fixed 16 MHz crystal. It's also an option
  67 if you need the slightly higher clock rate for performance reasons. Since
  68 16 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the code
  69 is somewhat tricky and has to insert a leap cycle every third byte.
  70
  71 12.8 MHz and 16.5 MHz Clock
  72 The assembler modules for these clock rates differ from the other modules
  73 because they have been built for an RC oscillator with only 1% precision. The
  74 receiver code inserts leap cycles to compensate for clock deviations. 1% is
  75 also the precision which can be achieved by calibrating the internal RC
  76 oscillator of the AVR. Please note that only AVRs with internal 64 MHz PLL
  77 oscillator can reach 16.5 MHz with the RC oscillator. This includes the very
  78 popular ATTiny25, ATTiny45, ATTiny85 series as well as the ATTiny26. Almost
  79 all AVRs can reach 12.8 MHz, although this is outside the specified range.
  80
  81 See the EasyLogger example at http://www.obdev.at/vusb/easylogger.html for
  82 code which calibrates the RC oscillator based on the USB frame clock.
  83
  84 18 MHz Clock
  85 This module is closer to the USB specification because it performs an on the
  86 fly CRC check for incoming packets. Packets with invalid checksum are
  87 discarded as required by the spec. If you also implement checks for data
  88 PID toggling on application level (see option USB_CFG_CHECK_DATA_TOGGLING
  89 in usbconfig.h for more info), this ensures data integrity. Due to the CRC
  90 tables and alignment requirements, this code is bigger than modules for other
  91 clock rates. To activate this module, you must define USB_CFG_CHECK_CRC to 1
  92 and USB_CFG_CLOCK_KHZ to 18000 in usbconfig.h.
  93
  94 20 MHz Clock
  95 This module is for people who won't do it with less than the maximum. Since
  96 20 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the code
  97 uses similar tricks as the 16 MHz module to insert leap cycles.
  98
  99
 100 USB IDENTIFIERS
 101 ===============
 102 Every USB device needs a vendor- and a product-identifier (VID and PID). VIDs
 103 are obtained from usb.org for a price of 1,500 USD. Once you have a VID, you
 104 can assign PIDs at will.
 105
 106 Since an entry level cost of 1,500 USD is too high for most small companies
 107 and hobbyists, we provide some VID/PID pairs for free. See the file
 108 USB-IDs-for-free.txt for details.
 109
 110 Objective Development also has some license offerings which include product
 111 IDs. See http://www.obdev.at/vusb/ for details.
 112
 113
 114 DEVELOPMENT SYSTEM
 115 ==================
 116 This driver has been developed and optimized for the GNU compiler version 3
 117 (gcc 3). It does work well with gcc 4, but with bigger code size. We recommend
 118 that you use the GNU compiler suite because it is freely available. V-USB
 119 has also been ported to the IAR compiler and assembler. It has been tested
 120 with IAR 4.10B/W32 and 4.12A/W32 on an ATmega8 with the "small" and "tiny"
 121 memory model. Not every release is tested with IAR CC and the driver may
 122 therefore fail to compile with IAR. Please note that gcc is more efficient for
 123 usbdrv.c because this module has been deliberately optimized for gcc.
 124
 125
 126 USING V-USB FOR FREE
 127 ====================
 128 The AVR firmware driver is published under the GNU General Public License
 129 Version 2 (GPL2) and the GNU General Public License Version 3 (GPL3). It is
 130 your choice whether you apply the terms of version 2 or version 3.
 131
 132 If you decide for the free GPL2 or GPL3, we STRONGLY ENCOURAGE you to do the
 133 following things IN ADDITION to the obligations from the GPL:
 134
 135 (1) Publish your entire project on a web site and drop us a note with the URL.
 136 Use the form at http://www.obdev.at/vusb/feedback.html for your submission.
 137 If you don't have a web site, you can publish the project in obdev's
 138 documentation wiki at
 139 http://www.obdev.at/goto.php?t=vusb-wiki&p=hosted-projects.
 140
 141 (2) Adhere to minimum publication standards. Please include AT LEAST:
 142     - a circuit diagram in PDF, PNG or GIF format
 143     - full source code for the host software
 144     - a Readme.txt file in ASCII format which describes the purpose of the
 145       project and what can be found in which directories and which files
 146     - a reference to http://www.obdev.at/vusb/
 147
 148 (3) If you improve the driver firmware itself, please give us a free license
 149 to your modifications for our commercial license offerings.
 150
 151
 152 COMMERCIAL LICENSES FOR V-USB
 153 =============================
 154 If you don't want to publish your source code under the terms of the GPL,
 155 you can simply pay money for V-USB. As an additional benefit you get
 156 USB PIDs for free, reserved exclusively to you. See the file
 157 "CommercialLicense.txt" for details.
 158