summaryrefslogtreecommitdiff
path: root/usbdrv/Readme.txt
diff options
context:
space:
mode:
Diffstat (limited to 'usbdrv/Readme.txt')
-rw-r--r--usbdrv/Readme.txt172
1 files changed, 0 insertions, 172 deletions
diff --git a/usbdrv/Readme.txt b/usbdrv/Readme.txt
deleted file mode 100644
index 970dc66b2f..0000000000
--- a/usbdrv/Readme.txt
+++ /dev/null
@@ -1,172 +0,0 @@
-This is the Readme file to Objective Development's firmware-only USB driver
-for Atmel AVR microcontrollers. For more information please visit
-http://www.obdev.at/vusb/
-
-This directory contains the USB firmware only. Copy it as-is to your own
-project and add all .c and .S files to your project (these files are marked
-with an asterisk in the list below). Then copy usbconfig-prototype.h as
-usbconfig.h to your project and edit it according to your configuration.
-
-
-TECHNICAL DOCUMENTATION
-=======================
-The technical documentation (API) for the firmware driver is contained in the
-file "usbdrv.h". Please read all of it carefully! Configuration options are
-documented in "usbconfig-prototype.h".
-
-The driver consists of the following files:
- Readme.txt ............. The file you are currently reading.
- Changelog.txt .......... Release notes for all versions of the driver.
- usbdrv.h ............... Driver interface definitions and technical docs.
-* usbdrv.c ............... High level language part of the driver. Link this
- module to your code!
-* usbdrvasm.S ............ Assembler part of the driver. This module is mostly
- a stub and includes one of the usbdrvasm*.S files
- depending on processor clock. Link this module to
- your code!
- usbdrvasm*.inc ......... Assembler routines for particular clock frequencies.
- Included by usbdrvasm.S, don't link it directly!
- asmcommon.inc .......... Common assembler routines. Included by
- usbdrvasm*.inc, don't link it directly!
- usbconfig-prototype.h .. Prototype for your own usbdrv.h file.
-* oddebug.c .............. Debug functions. Only used when DEBUG_LEVEL is
- defined to a value greater than 0. Link this module
- to your code!
- oddebug.h .............. Interface definitions of the debug module.
- usbportability.h ....... Header with compiler-dependent stuff.
- usbdrvasm.asm .......... Compatibility stub for IAR-C-compiler. Use this
- module instead of usbdrvasm.S when you assembler
- with IAR's tools.
- License.txt ............ Open Source license for this driver.
- CommercialLicense.txt .. Optional commercial license for this driver.
- USB-ID-FAQ.txt ......... General infos about USB Product- and Vendor-IDs.
- USB-IDs-for-free.txt ... List and terms of use for free shared PIDs.
-
-(*) ... These files should be linked to your project.
-
-
-CPU CORE CLOCK FREQUENCY
-========================
-We supply assembler modules for clock frequencies of 12 MHz, 12.8 MHz, 15 MHz,
-16 MHz, 16.5 MHz 18 MHz and 20 MHz. Other clock rates are not supported. The
-actual clock rate must be configured in usbconfig.h.
-
-12 MHz Clock
-This is the traditional clock rate of V-USB because it's the lowest clock
-rate where the timing constraints of the USB spec can be met.
-
-15 MHz Clock
-Similar to 12 MHz, but some NOPs inserted. On the other hand, the higher clock
-rate allows for some loops which make the resulting code size somewhat smaller
-than the 12 MHz version.
-
-16 MHz Clock
-This clock rate has been added for users of the Arduino board and other
-ready-made boards which come with a fixed 16 MHz crystal. It's also an option
-if you need the slightly higher clock rate for performance reasons. Since
-16 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the code
-is somewhat tricky and has to insert a leap cycle every third byte.
-
-12.8 MHz and 16.5 MHz Clock
-The assembler modules for these clock rates differ from the other modules
-because they have been built for an RC oscillator with only 1% precision. The
-receiver code inserts leap cycles to compensate for clock deviations. 1% is
-also the precision which can be achieved by calibrating the internal RC
-oscillator of the AVR. Please note that only AVRs with internal 64 MHz PLL
-oscillator can reach 16.5 MHz with the RC oscillator. This includes the very
-popular ATTiny25, ATTiny45, ATTiny85 series as well as the ATTiny26. Almost
-all AVRs can reach 12.8 MHz, although this is outside the specified range.
-
-See the EasyLogger example at http://www.obdev.at/vusb/easylogger.html for
-code which calibrates the RC oscillator based on the USB frame clock.
-
-18 MHz Clock
-This module is closer to the USB specification because it performs an on the
-fly CRC check for incoming packets. Packets with invalid checksum are
-discarded as required by the spec. If you also implement checks for data
-PID toggling on application level (see option USB_CFG_CHECK_DATA_TOGGLING
-in usbconfig.h for more info), this ensures data integrity. Due to the CRC
-tables and alignment requirements, this code is bigger than modules for other
-clock rates. To activate this module, you must define USB_CFG_CHECK_CRC to 1
-and USB_CFG_CLOCK_KHZ to 18000 in usbconfig.h.
-
-20 MHz Clock
-This module is for people who won't do it with less than the maximum. Since
-20 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the code
-uses similar tricks as the 16 MHz module to insert leap cycles.
-
-
-USB IDENTIFIERS
-===============
-Every USB device needs a vendor- and a product-identifier (VID and PID). VIDs
-are obtained from usb.org for a price of 1,500 USD. Once you have a VID, you
-can assign PIDs at will.
-
-Since an entry level cost of 1,500 USD is too high for most small companies
-and hobbyists, we provide some VID/PID pairs for free. See the file
-USB-IDs-for-free.txt for details.
-
-Objective Development also has some license offerings which include product
-IDs. See http://www.obdev.at/vusb/ for details.
-
-
-DEVELOPMENT SYSTEM
-==================
-This driver has been developed and optimized for the GNU compiler version 3
-and 4. We recommend that you use the GNU compiler suite because it is freely
-available. V-USB has also been ported to the IAR compiler and assembler. It
-has been tested with IAR 4.10B/W32 and 4.12A/W32 on an ATmega8 with the
-"small" and "tiny" memory model. Not every release is tested with IAR CC and
-the driver may therefore fail to compile with IAR. Please note that gcc is
-more efficient for usbdrv.c because this module has been deliberately
-optimized for gcc.
-
-Gcc version 3 produces smaller code than version 4 due to new optimizing
-capabilities which don't always improve things on 8 bit CPUs. The code size
-generated by gcc 4 can be reduced with the compiler options
--fno-move-loop-invariants, -fno-tree-scev-cprop and
--fno-inline-small-functions in addition to -Os. On devices with more than
-8k of flash memory, we also recommend the linker option --relax (written as
--Wl,--relax for gcc) to convert absolute calls into relative where possible.
-
-For more information about optimizing options see:
-
- http://www.tty1.net/blog/2008-04-29-avr-gcc-optimisations_en.html
-
-These optimizations are good for gcc 4.x. Version 3.x of gcc does not support
-most of these options and produces good code anyway.
-
-
-USING V-USB FOR FREE
-====================
-The AVR firmware driver is published under the GNU General Public License
-Version 2 (GPL2) and the GNU General Public License Version 3 (GPL3). It is
-your choice whether you apply the terms of version 2 or version 3.
-
-If you decide for the free GPL2 or GPL3, we STRONGLY ENCOURAGE you to do the
-following things IN ADDITION to the obligations from the GPL:
-
-(1) Publish your entire project on a web site and drop us a note with the URL.
-Use the form at http://www.obdev.at/vusb/feedback.html for your submission.
-If you don't have a web site, you can publish the project in obdev's
-documentation wiki at
-http://www.obdev.at/goto.php?t=vusb-wiki&p=hosted-projects.
-
-(2) Adhere to minimum publication standards. Please include AT LEAST:
- - a circuit diagram in PDF, PNG or GIF format
- - full source code for the host software
- - a Readme.txt file in ASCII format which describes the purpose of the
- project and what can be found in which directories and which files
- - a reference to http://www.obdev.at/vusb/
-
-(3) If you improve the driver firmware itself, please give us a free license
-to your modifications for our commercial license offerings.
-
-
-COMMERCIAL LICENSES FOR V-USB
-=============================
-If you don't want to publish your source code under the terms of the GPL,
-you can simply pay money for V-USB. As an additional benefit you get
-USB PIDs for free, reserved exclusively to you. See the file
-"CommercialLicense.txt" for details.
-