merging tmk

1 files changed, 172 insertions, 0 deletions

diff --git a/tmk_core/protocol/vusb/usbdrv/Readme.txt b/tmk_core/protocol/vusb/usbdrv/Readme.txt
new file mode 100644
index 0000000000..970dc66b2f
--- /dev/null
+++ b/tmk_core/protocol/vusb/usbdrv/Readme.txt
@@ -0,0 +1,172 @@
+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.
+