From b282d4a32cef1230b1a2626e27058afe04eb3414 Mon Sep 17 00:00:00 2001 From: Ronald Schaten Date: Tue, 26 Sep 2006 18:18:27 +0000 Subject: [PATCH] Erste CVS-Version --- License.txt | 346 +++++++ Readme.txt | 297 ++++++ circuit/circuit.brd | Bin 0 -> 17638 bytes circuit/circuit.sch | Bin 0 -> 260890 bytes circuit/partlist.txt | 30 + commandline/Makefile | 23 + commandline/usb-led-fader.c | 426 +++++++++ common/channels.h | 16 + common/usbledfader.h | 466 +++++++++ firmware/Makefile | 48 + firmware/boolean.h | 34 + firmware/config_message_queue.h | 26 + firmware/config_message_queue_impl.h | 23 + firmware/config_pwm_timer_impl.h | 27 + firmware/main.c | 278 ++++++ firmware/message_queue.c | 95 ++ firmware/message_queue.h | 37 + firmware/pwm_channels.c | 108 +++ firmware/pwm_channels.h | 39 + firmware/pwm_timer.c | 139 +++ firmware/pwm_timer.h | 70 ++ firmware/usbconfig.h | 170 ++++ firmware/usbdrv/Changelog.txt | 115 +++ firmware/usbdrv/License.txt | 458 +++++++++ firmware/usbdrv/Readme.txt | 88 ++ firmware/usbdrv/USBID-License.txt | 143 +++ firmware/usbdrv/iarcompat.h | 70 ++ firmware/usbdrv/oddebug.c | 53 ++ firmware/usbdrv/oddebug.h | 126 +++ firmware/usbdrv/usbconfig-prototype.h | 265 ++++++ firmware/usbdrv/usbdrv.c | 572 +++++++++++ firmware/usbdrv/usbdrv.h | 657 +++++++++++++ firmware/usbdrv/usbdrvasm.S | 784 ++++++++++++++++ firmware/usbdrv/usbdrvasm.asm | 21 + usb-led-fader.doxygen | 1252 +++++++++++++++++++++++++ 35 files changed, 7302 insertions(+) create mode 100644 License.txt create mode 100644 Readme.txt create mode 100644 circuit/circuit.brd create mode 100644 circuit/circuit.sch create mode 100644 circuit/partlist.txt create mode 100644 commandline/Makefile create mode 100644 commandline/usb-led-fader.c create mode 100644 common/channels.h create mode 100644 common/usbledfader.h create mode 100644 firmware/Makefile create mode 100644 firmware/boolean.h create mode 100644 firmware/config_message_queue.h create mode 100644 firmware/config_message_queue_impl.h create mode 100644 firmware/config_pwm_timer_impl.h create mode 100644 firmware/main.c create mode 100644 firmware/message_queue.c create mode 100644 firmware/message_queue.h create mode 100644 firmware/pwm_channels.c create mode 100644 firmware/pwm_channels.h create mode 100644 firmware/pwm_timer.c create mode 100644 firmware/pwm_timer.h create mode 100644 firmware/usbconfig.h create mode 100644 firmware/usbdrv/Changelog.txt create mode 100644 firmware/usbdrv/License.txt create mode 100644 firmware/usbdrv/Readme.txt create mode 100644 firmware/usbdrv/USBID-License.txt create mode 100644 firmware/usbdrv/iarcompat.h create mode 100644 firmware/usbdrv/oddebug.c create mode 100644 firmware/usbdrv/oddebug.h create mode 100644 firmware/usbdrv/usbconfig-prototype.h create mode 100644 firmware/usbdrv/usbdrv.c create mode 100644 firmware/usbdrv/usbdrv.h create mode 100644 firmware/usbdrv/usbdrvasm.S create mode 100644 firmware/usbdrv/usbdrvasm.asm create mode 100644 usb-led-fader.doxygen diff --git a/License.txt b/License.txt new file mode 100644 index 0000000..9ba8721 --- /dev/null +++ b/License.txt @@ -0,0 +1,346 @@ +The following license applies to all but the firmware/usbdrv directories. For +that directory, please refer to the firmware/usbdrv/License.txt file for +additional license restrictions. + +------------------------------------------------------------------------------- + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/Readme.txt b/Readme.txt new file mode 100644 index 0000000..5f48d52 --- /dev/null +++ b/Readme.txt @@ -0,0 +1,297 @@ +$Id: Readme.txt,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + +For full documentation and examples, take a look at htmldoc/index.html. + + +Introduction +============ + +The USB-LED-Fader is a device to control a number of LEDs via USB. I built it +to display the online-status of my internet-connection, the recording-status of +my videorecorder, and warnings if the available disc-space is low. You can +imagine an endless number of applications for this. + +The LEDs are controlled with pulse width modulation (PWM). That way, they are +not only on or off, it is possible to control the brightness. Included in the +device is a number of 'waveforms' that can be displayed on the LEDs. That way, +one LED can display some kind of a sinus- or triangular wave without any +interaction with the controlling host. + +Every LED can be controlled individually, each one can display it's own +waveforms. + +You can assign three different waves to every LED: two 'eternal' waves (0 & 1). +They are displayed alternating until anything different is required. The third +wave (2) is only displayed once, afterwards the device will switch back to +alternating between the first two waves. + +One wave is described by three parameters: the waveform, the duration for one +repetition of the wave and the number of repetitions before switching to the +next wave. + +This version supports four LEDs, it should be quite easy to change that number +between one and eight. I have not tested any number greater than four, but I +can imagine that the load on the controller can be too high to reliably +communicate via USB. + +There are three parts included in the distribution: The firmware for an ATmega8 +microcontroller, a commandline-client that can be run under Linux, and the +circuits needed to build the device. + +This project is based on the PowerSwitch example application by Objective +Development. Like that, it uses Objective Development's firmware-only USB +driver for Atmel's AVR microcontrollers. + +Objective Development's USB driver is a firmware-only implementation of the USB +1.1 standard (low speed device) on cheap single chip microcomputers of Atmel's +AVR series, such as the ATtiny2313 or even some of the small 8 pin devices. It +implements the standard to the point where useful applications can be +implemented. See the file "firmware/usbdrv/usbdrv.h" for features and +limitations. + + +Building and installing +======================= + +Both, the firmware and Unix command line tool are built with "make". You may +need to customize both makefiles. + + +Firmware +-------- + +The firmware for this project requires avr-gcc and avr-libc (a C-library for +the AVR controller). Please read the instructions at +http://www.nongnu.org/avr-libc/user-manual/install_tools.html for how to +install the GNU toolchain (avr-gcc, assembler, linker etc.) and avr-libc. + +Once you have the GNU toolchain for AVR microcontrollers installed, you can run +"make" in the subdirectory "firmware". You may have to edit the Makefile to use +your preferred downloader with "make program". The current version is built for +avrdude with a parallel connection to an stk200-compatible programmer. + +If working with a brand-new controller, you may have to set the fuse-bits to +use the external crystal: + + avrdude -p atmega8 -P /dev/parport0 -c sp12 -U hfuse:w:0xC9:m \ + -U lfuse:w:0x9F:m + +Afterwards, you can compile and flash to the device: + + make program + + +Commandline client +------------------ + +The command line tool requires libusb. Please download libusb from +http://libusb.sourceforge.net/ and install it before you compile. Change to +directory "commandline", check the Makefile and edit the settings if required +and type + + make + +This will build the unix executable "usb-led-fader" which can be used to +control the device. + + +Usage +===== + +Connect the device to the USB-port. All LED should flash up to indicate that +the device is initialized. + +Then use the commandline-client as follows: + + usb-led-fader status + usb-led-fader set + usb-led-fader clear + usb-led-fader reset + usb-led-fader show + usb-led-fader test + +When using the set-function, it is possible to define several waves at once. +You simply have to give the parameters for all waves. See examples below. + + +Parameters +---------- + +- ledId: ID of the LED (0-n, depending on the number of LEDs in your circuit). +- waveId: ID of the wave (0-1: constant waves, 2: override). +- waveformId: ID of the waveform (0-31: brightness, 32-37: patterns). For a + reference to the patterns, consult the function fade_calculateWaveform() in + the file "firmware/main.c". +- periodDuration: Time in sec/10 for one repetition of the waveform. A value of + 0 can be used to reset the wave. +- repetitionCount: Number of repetitions before switching to the next wave. A + value of 0 can be used to repeat this forever. + + +Examples +-------- + +-> Get the status of all LEDs: + usb-led-fader status +This will result in an output similar to this: + LED 0 curid curvalue curpos currep nextupd + 0 2 26 0 23 + wave waveform length repeat duration updtime + 0 38 32 1 20 45 + 1 0 1 1 0 1 + 2 0 1 1 0 1 + LED 1 curid curvalue curpos currep nextupd + 0 14 19 0 19 + wave waveform length repeat duration updtime + 0 38 32 1 20 45 + 1 0 1 1 0 1 + 2 0 1 1 0 1 + LED 2 curid curvalue curpos currep nextupd + 0 31 16 0 43 + wave waveform length repeat duration updtime + 0 38 32 1 20 45 + 1 0 1 1 0 1 + 2 0 1 1 0 1 + LED 3 curid curvalue curpos currep nextupd + 0 6 9 0 39 + wave waveform length repeat duration updtime + 0 38 32 1 20 45 + 1 0 1 1 0 1 + 2 0 1 1 0 1 +In this output, the values curvalue, curpos, nextupd and updtime are for +debugging purposes only. They shouldn't be of interest to the common user. The +meaning of the other values should be clear. + +-> Set the first LED to keep a middle brightness: + usb-led-fader set 0 0 15 10 1 +So, on LED 0 the wave 0 is set to waveform 15. It will stay there for one +second and will be repeated once before switching to the next wave. There is no +next wave because we didn't define one, so this waveform will stay forever. + +-> Now set a second wave on the first LED, a little brighter than the one + before: + usb-led-fader set 0 1 25 10 1 +This is wave 1 on LED 0, waveform 25 indicates a constant level of brightness. +After setting the second wave, it will alternate with the first one after every +second, because both waves have the same duration and the same number of +repetitions. + +-> Set a third wave on the first LED: + usb-led-fader set 0 2 36 20 5 +This sets the third wave (wave 2) on the first LED. Waveform 36 is a nice +sinus-like wave, so the LED starts to fade. One period of the fading takes 2 +seconds, it is repeated for 5 times. Since this is the third wave, after the +repetitions the LED returns to alternating between wave 0 and wave 1, this wave +is discarded. + +-> Set multiple waves at once: + usb-led-fader set 0 0 15 10 1 0 1 25 10 1 0 2 36 20 5 +This will set all of the above waves at once. Thus, the first LED will first +fade the sinus-wave five times, then start alternating between the two +brightnesses in one-second-rhythm. + +Clear the first LED: + usb-led-fader clear 0 +This will clear all three waves on the first LED. + +-> Reset the device: + usb-led-fader reset +All LEDs will flash once, to indicate that the device is reset and the LEDs are +working. + +-> Show a waveform on the screen: + usb-led-fader show 36 +This will lead to an output like the following: + wave 36 - length 64 + 31: ***** + 30: ********* + 29: *********** + 28: *************** + 27: ***************** + 26: ******************* + 25: ******************* + 24: ********************* + 23: *********************** + 22: ************************* + 21: ************************* + 20: *************************** + 19: ***************************** + 18: ***************************** + 17: ******************************* + 16: ********************************* + 15: *********************************** + 14: *********************************** + 13: ************************************* + 12: *************************************** + 11: *************************************** + 10: ***************************************** + 9: ******************************************* + 8: ********************************************* + 7: ********************************************* + 6: *********************************************** + 5: ************************************************* + 4: ***************************************************** + 3: ******************************************************* + 2: *********************************************************** + 1: **************************************************************** + ================================================================ +Keep in mind that the width of the displayed wave corresponds to the length of +the waveform. If you display a very simple one like the constant brightness +levels (0-31), the length is 1. Therefore only one column is displayed. + +-> Test the device: + usb-led-fader test +This function sends many random numbers to the device. The device returns the +packages, and the client looks for differences in the sent and the received +numbers. + + +Drawbacks +========= + +As mentioned above, controlling the PWM for several LEDs is a lot of work for +one small microcontroller. Speaking the USB protocol is so, either. Both +combined result in a lot of load on the device, so the communication with the +device is not 100% reliable. More than 99% though, at least in our tests. + +SO BE WARNED: You should not use this device to control the state of your +nuclear reactor. If you intend to use it in that way despite of this warning, +please let me know... ;-) + + +Files in the distribution +========================= + +- Readme.txt: The file you are currently reading. +- firmware: Source code of the controller firmware. +- firmware/usbdrv: USB driver -- See Readme.txt in this directory for info +- commandline: Source code of the host software (needs libusb). +- common: Files needed by the firmware and the commandline-client. +- circuit: Circuit diagrams in PDF and EAGLE 4 format. A free version of EAGLE + is available for Linux, Mac OS X and Windows from http://www.cadsoft.de/. +- License.txt: Public license for all contents of this project, except for the + USB driver. Look in firmware/usbdrv/License.txt for further info. +- Changelog.txt: Logfile documenting changes in soft-, firm- and hardware. + + +Thanks! +======= + +I'd like to thank Objective Development for the possibility to use their driver +for my project. In fact, this project wouldn't exist without the driver. + +And I'd like to give special credits to Thomas Stegemann. He wrote the +PWM-stuff, and I guess it would have been nearly to impossible to me to write +the rest of the project without his help since C isn't my natural language. + + +About the license +================= + +Our work - all contents except for the USB driver - are licensed under the GNU +General Public License (GPL). A copy of the GPL is included in License.txt. The +driver itself is licensed under a special license by Objective Development. See +firmware/usbdrv/License.txt for further info. + + +(c) 2006 by Ronald Schaten - http://www.schatenseite.de diff --git a/circuit/circuit.brd b/circuit/circuit.brd new file mode 100644 index 0000000000000000000000000000000000000000..4a8bd9f521dc3200b36a88a497999a2827e75712 GIT binary patch literal 17638 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 literal 0 HcmV?d00001 diff --git a/circuit/circuit.sch b/circuit/circuit.sch new file mode 100644 index 0000000000000000000000000000000000000000..b324f24ebf0d01270c9e22359a0e48ff435acf93 GIT binary patch literal 260890 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

  • P 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
    *6LSA<|`8mTF_MjROhs2K6e2HnRx~ zlZ{n>ce~v>zuxvQY{I!kE(NC?%EIb8xHI9bMDX}FwN6tc>&~XU^s>#P5q(U9GG@V* z!{ViOYe!nJX4u}vi`!aWjCat6?zpRGMG-O;WSg@yF|7?n`u|1=lQVOb!m_M*om#BS z%1H&BJc905un4ja8*SsrOZ%Qu`xT7!{_5t6e_^e?zUrOC2QHh-la*#|xj8di^CmY} zcF|^b{JGuB=i6IPdM76rD@!wTQ_FJzr&D?6^z4F}&?Qp4+vhWAJ(&wFEWUf^ulkFd z8?AM;J$wsur@i5cc=(|0cgF93?1`H_-^b@XSKAj_yX!mhVb4da?Z57R;q!m|#uxv_ z?;d&UKaf{GNzCuEc4Inm>8XPu6F(~2jp;W&c=>%H6TcYUjcMes{>l9z)6G4Y{^c$I qIAY>AYP%t2GoQUTM7p&H)1!BNB4Xm#WxFB0dDqtu{0e@!?EPQI+udvc literal 0 HcmV?d00001 diff --git a/circuit/partlist.txt b/circuit/partlist.txt new file mode 100644 index 0000000..ce77983 --- /dev/null +++ b/circuit/partlist.txt @@ -0,0 +1,30 @@ +Partlist + +Exported from circuit.sch at 9/15/2006 14:21:25 + +EAGLE Version 4.16 Copyright (c) 1988-2005 CadSoft + +Part Value Device Package Library Sheet + +C1 4,7u CPOL-EUE2.5-5 E2,5-5 rcl 1 +C2 100n C-EU025-024X044 C025-024X044 rcl 1 +C3 22p C-EU025-024X044 C025-024X044 rcl 1 +C4 22p C-EU025-024X044 C025-024X044 rcl 1 +IC1 MEGA8-P MEGA8-P DIL28-3 avr 1 +IC2 LM317LZ LM317LZ TO92 linear 1 +JP1 ISP JP5Q JP5Q jumper 1 +LED1 LED5MM LED5MM led 1 +LED2 LED5MM LED5MM led 1 +LED3 LED5MM LED5MM led 1 +LED4 LED5MM LED5MM led 1 +Q1 12MHz CRYTALHC18U-V HC18U-V crystal 1 +R1 432 R-EU_0207/10 0207/10 rcl 1 +R2 240 R-EU_0207/10 0207/10 rcl 1 +R3 1k5 R-EU_0207/10 0207/10 rcl 1 +R4 68 R-EU_0207/10 0207/10 rcl 1 +R5 68 R-EU_0207/10 0207/10 rcl 1 +R6 1k R-EU_0207/10 0207/10 rcl 1 +R7 1k R-EU_0207/10 0207/10 rcl 1 +R8 1k R-EU_0207/10 0207/10 rcl 1 +R9 1k R-EU_0207/10 0207/10 rcl 1 +X1 PN61729 PN61729 con-berg 1 diff --git a/commandline/Makefile b/commandline/Makefile new file mode 100644 index 0000000..6680c62 --- /dev/null +++ b/commandline/Makefile @@ -0,0 +1,23 @@ +# $Id: Makefile,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + +CC = gcc +LIBUSB_CONFIG = libusb-config +# Make sure that libusb-config is in the search path or specify a full path. On +# Windows, there is no libusb-config and you must configure the options below +# manually. See examples. + +CFLAGS = `$(LIBUSB_CONFIG) --cflags` -O -Wall -I../common + +LIBS = `$(LIBUSB_CONFIG) --libs` + +all: usb-led-fader + +.c.o: + $(CC) $(CFLAGS) -c $< + +usb-led-fader: usb-led-fader.o + $(CC) -o usb-led-fader usb-led-fader.o $(LIBS) + +clean: + rm -f *.o + rm -f usb-led-fader diff --git a/commandline/usb-led-fader.c b/commandline/usb-led-fader.c new file mode 100644 index 0000000..b2682a8 --- /dev/null +++ b/commandline/usb-led-fader.c @@ -0,0 +1,426 @@ +/** + * \file usb-led-fader.c + * \brief Commandline-tool for the USB-LED-Fader. + * \author Ronald Schaten + * \version $Id: usb-led-fader.c,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + */ + +#include +#include +#include +#include /* this is libusb, see http://libusb.sourceforge.net/ */ + +#include "usbledfader.h" +#include "channels.h" + +#define USBDEV_SHARED_VENDOR 0x16C0 /**< VOTI */ +#define USBDEV_SHARED_PRODUCT 0x05DC /**< Obdev's free shared PID. Use obdev's generic shared VID/PID pair and follow the rules outlined in firmware/usbdrv/USBID-License.txt. */ + +/* These are error codes for the communication via USB. */ +#define USB_ERROR_NOTFOUND 1 /**< Error code if the device isn't found. */ +#define USB_ERROR_ACCESS 2 /**< Error code if the device isn't accessible. */ +#define USB_ERROR_IO 3 /**< Error code if errors in the communication with the device occur. */ + +/** + * Displays usage-informations. This function is called if the parameters + * cannot be parsed. + * \param name The name of this application. + */ +void usage(char *name) +{ + fprintf(stderr, "usage:\n"); + fprintf(stderr, " %s status\n", name); + fprintf(stderr, " %s set ledId waveId waveformId periodDuration repetitionCount\n", name); + fprintf(stderr, " %s clear ledId\n", name); + fprintf(stderr, " %s reset\n", name); + fprintf(stderr, " %s show waveformId\n", name); + fprintf(stderr, " %s test\n\n", name); + fprintf(stderr, "parameters:\n"); + fprintf(stderr, " ledId: ID of the LED (0-%d).\n", CHANNELS - 1); + fprintf(stderr, " waveId: ID of the wave (0-1: constant waves, 2: override).\n"); + fprintf(stderr, " waveformId: ID of the waveform (0-31: brightness, 32-37: patterns).\n"); + fprintf(stderr, " periodDuration: Time in sec/10 for one repetition of the waveform.\n"); + fprintf(stderr, " A value of 0 can be used to reset the wave.\n"); + fprintf(stderr, " repetitionCount: Number of repetitions before switching to the next wave.\n"); + fprintf(stderr, " A value of 0 can be used to repeat this forever.\n"); +} + +/** + * Reads and converts a string from USB. The conversion to ASCII is 'lossy' (unknown characters become '?'). + * \param dev Handle of the USB-Device. + * \param index Index of the required data. + * \param langid Index of the expected language. + * \param buf Buffer to contain the return-string. + * \param buflen Length of buf. + * \return Length of the string. + */ +int usbGetStringAscii(usb_dev_handle * dev, int index, int langid, char *buf, int buflen) { + char buffer[256]; + int rval, i; + + if ((rval = usb_control_msg(dev, USB_ENDPOINT_IN, USB_REQ_GET_DESCRIPTOR, (USB_DT_STRING << 8) + index, langid, buffer, sizeof(buffer), 1000)) < 0) { + return rval; + } + if (buffer[1] != USB_DT_STRING) { + return 0; + } + if ((unsigned char) buffer[0] < rval) { + rval = (unsigned char) buffer[0]; + } + rval /= 2; + /* lossy conversion to ISO Latin1 */ + for (i = 1; i < rval; i++) { + if (i > buflen) { + /* destination buffer overflow */ + break; + } + buf[i - 1] = buffer[2 * i]; + if (buffer[2 * i + 1] != 0) { + /* outside of ISO Latin1 range */ + buf[i - 1] = '?'; + } + } + buf[i - 1] = 0; + return i - 1; +} + +/** + * Connect to the USB-device. Loops through all connected USB-Devices and + * searches our counterpart. + * \param device Handle to address the device. + * \param vendor USBDEV_SHARED_VENDOR as defined. + * \param vendorName In our case "www.schatenseite.de". + * \param product USBDEV_SHARED_PRODUCT as defined. + * \param productName In our case "USB-LED-Fader". + * \return Error code. + */ +int usbOpenDevice(usb_dev_handle ** device, int vendor, char *vendorName, int product, char *productName) { + struct usb_bus *bus; + struct usb_device *dev; + usb_dev_handle *handle = NULL; + int errorCode = USB_ERROR_NOTFOUND; + static int didUsbInit = 0; + + if (!didUsbInit) { + didUsbInit = 1; + usb_init(); + } + usb_find_busses(); + usb_find_devices(); + for (bus = usb_get_busses(); bus; bus = bus->next) { + for (dev = bus->devices; dev; dev = dev->next) { + if (dev->descriptor.idVendor == vendor && dev->descriptor.idProduct == product) { + char string[256]; + int len; + handle = usb_open(dev); /* we need to open the device in order to query strings */ + if (!handle) { + errorCode = USB_ERROR_ACCESS; + fprintf(stderr, "Warning: cannot open USB device: %s\n", usb_strerror()); + continue; + } + if (vendorName == NULL && productName == NULL) { /* name does not matter */ + break; + } + /* now check whether the names match: */ + len = usbGetStringAscii(handle, dev->descriptor.iManufacturer, 0x0409, string, sizeof(string)); + if (len < 0) { + errorCode = USB_ERROR_IO; + fprintf(stderr, "Warning: cannot query manufacturer for device: %s\n", usb_strerror()); + } else { + errorCode = USB_ERROR_NOTFOUND; + /* fprintf(stderr, "seen device from vendor ->%s<-\n", string); */ + if (strcmp(string, vendorName) == 0) { + len = usbGetStringAscii(handle, dev->descriptor.iProduct, 0x0409, string, sizeof(string)); + if (len < 0) { + errorCode = USB_ERROR_IO; + fprintf(stderr, "Warning: cannot query product for device: %s\n", usb_strerror()); + } else { + errorCode = USB_ERROR_NOTFOUND; + /* fprintf(stderr, "seen product ->%s<-\n", string); */ + if (strcmp(string, productName) == 0) { + break; + } + } + } + } + usb_close(handle); + handle = NULL; + } + } + if (handle) { + break; + } + } + if (handle != NULL) { + errorCode = 0; + *device = handle; + } + return errorCode; +} + +/** + * Test connection to the device. The test consists of writing 1000 random + * numbers to the device and checking the echo. This should discover systematic + * bit errors (e.g. in bit stuffing). + * \param handle Handle to talk to the device. + * \param argc Number of arguments. + * \param argv Arguments. + */ +void dev_test(usb_dev_handle *handle, int argc, char** argv) { + unsigned char buffer[8]; + int nBytes; + int i, v, r; + if (argc != 2) { + usage(argv[0]); + exit(1); + } + for (i = 0; i < 1000; i++) { + v = rand() & 0xffff; + nBytes = usb_control_msg(handle, USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_IN, CMD_ECHO, v, 0, (char *) buffer, sizeof(buffer), 5000); + if (nBytes < 2) { + if (nBytes < 0) { + fprintf(stderr, "USB error: %s\n", usb_strerror()); + } + fprintf(stderr, "only %d bytes received in iteration %d\n", nBytes, i); + exit(1); + } + r = buffer[0] | (buffer[1] << 8); + if (r != v) { + fprintf(stderr, "data error: received 0x%x instead of 0x%x in iteration %d\n", r, v, i); + exit(1); + } + } + printf("test succeeded\n"); +} + +/** + * Set waves. It is possible to set any number of waves at once. + * \param handle Handle to talk to the device. + * \param argc Number of arguments. + * \param argv Arguments. + */ +void dev_set(usb_dev_handle *handle, int argc, char** argv) { + unsigned char buffer[8]; + int nBytes; + int parameter; + if ((argc < 7) || ((argc - 2) % 5 != 0)) { + usage(argv[0]); + exit(1); + } + for (parameter = 2; (parameter + 4) < argc; parameter += 5) { + int ledId = atoi(argv[parameter + 0]); + if ((ledId < 0) || (ledId > (CHANNELS - 1))) { + fprintf(stderr, "invalid ledId: %d\n", ledId); + exit(1); + } + int waveId = atoi(argv[parameter + 1]); + if ((waveId < 0) || (waveId > 2)) { + fprintf(stderr, "invalid waveId: %d\n", waveId); + exit(1); + } + int waveformId = atoi(argv[parameter + 2]); + if ((waveformId < 0) || (waveformId > 38)) { + fprintf(stderr, "invalid waveformId: %d\n", waveformId); + exit(1); + } + int periodDuration = atoi(argv[parameter + 3]); + if ((periodDuration < 0) || (periodDuration > 255)) { + fprintf(stderr, "invalid periodDuration: %d\n", periodDuration); + exit(1); + } + int repetitionCount = atoi(argv[parameter + 4]); + if ((repetitionCount < 0) || (repetitionCount > 255)) { + fprintf(stderr, "invalid repetitionCount: %d\n", repetitionCount); + exit(1); + } + + buffer[0] = CMD_SET; + buffer[1] = ledId; + buffer[2] = waveId; + buffer[3] = waveformId; + buffer[4] = periodDuration; + buffer[5] = repetitionCount; + + nBytes = usb_control_msg(handle, USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_OUT, CMD_SET, ledId, 0, (char *) buffer, sizeof(buffer), 5000); + + if (nBytes < 0) { + fprintf(stderr, "USB error: %s\n", usb_strerror()); + exit(1); + } + } +} + +/** + * Clear all waves on one LED. + * \param handle Handle to talk to the device. + * \param argc Number of arguments. + * \param argv Arguments. + */ +void dev_clear(usb_dev_handle *handle, int argc, char** argv) { + unsigned char buffer[8]; + int nBytes; + if (argc != 3) { + usage(argv[0]); + exit(1); + } + int ledId = atoi(argv[2]); + if ((ledId < 0) || (ledId > (CHANNELS - 1))) { + fprintf(stderr, "invalid LED: %d\n", ledId); + exit(1); + } + nBytes = usb_control_msg(handle, USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_OUT, CMD_CLEAR, ledId, 0, (char *) buffer, sizeof(buffer), 5000); + if (nBytes < 0) { + fprintf(stderr, "USB error: %s\n", usb_strerror()); + exit(1); + } +} + +/** + * Get the status of the device. Status information is printed in detail. + * \param handle Handle to talk to the device. + * \param argc Number of arguments. + * \param argv Arguments. + */ +void dev_status(usb_dev_handle *handle, int argc, char** argv) { + int nBytes; + int i, j; + static fade_GlobalData fade_globalData; /* contains the state of all four LEDs. */ + if (argc != 2) { + usage(argv[0]); + exit(1); + } + nBytes = usb_control_msg(handle, USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_IN, CMD_GET, 0, 0, (char *) &fade_globalData, sizeof(fade_globalData), 5000); + if (nBytes < 0) { + fprintf(stderr, "USB error: %s\n", usb_strerror()); + exit(1); + } + if (nBytes != sizeof(fade_globalData)) { + fprintf(stderr, "USB oddity: %d bytes received, %d bytes expected.\n", nBytes, sizeof(fade_globalData)); + exit(1); + } + for (i = 0; i < CHANNELS; i++) { + printf("LED %d %10s %10s %10s %10s %10s\n", i, "curid", "curvalue", "curpos", "currep", "nextupd"); + printf(" %10d %10d %10d %10d %10d\n", + fade_globalData.led[i].waveCurrentId, + fade_globalData.led[i].waveCurrentValue, + fade_globalData.led[i].waveCurrentPosition, + fade_globalData.led[i].waveCurrentRepetition, + fade_globalData.led[i].waveNextUpdate); + printf("%10s %10s %10s %10s %10s %10s\n", "wave", "waveform", "length", "repeat", "duration", "updtime"); + for (j = 0; j < 3; j++) { + printf("%10d %10d %10d %10d %10d %10d\n", + j, + fade_globalData.led[i].wave[j].waveformId, + fade_globalData.led[i].wave[j].waveformLength, + fade_globalData.led[i].wave[j].waveformRepetition, + fade_globalData.led[i].wave[j].waveformDuration, + fade_globalData.led[i].wave[j].waveformUpdateTime); + } + } +} + +/** + * Reset the device. + * \param handle Handle to talk to the device. + * \param argc Number of arguments. + * \param argv Arguments. + */ +void dev_reset(usb_dev_handle *handle, int argc, char** argv) { + unsigned char buffer[8]; + int nBytes; + if (argc != 2) { + usage(argv[0]); + exit(1); + } + nBytes = usb_control_msg(handle, USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_OUT, CMD_RESET, 0, 0, (char *) buffer, sizeof(buffer), 5000); + if (nBytes < 0) { + fprintf(stderr, "USB error: %s\n", usb_strerror()); + exit(1); + } +} + +/** + * Show a waveform. This will not send a command to the device, the waveform is + * only printed on the screen. + * \param handle Handle to talk to the device (not needed). + * \param argc Number of arguments. + * \param argv Arguments. + */ +int dev_show(int argc, char **argv) { + if (argc != 3) { + usage(argv[0]); + exit(1); + } + int waveformId = atoi(argv[2]); + if ((waveformId < 0) || (waveformId > 38)) { + fprintf(stderr, "invalid waveformId: %d\n", waveformId); + exit(1); + } + int i, j; + int length = fade_calculateWaveform(waveformId, 0); + printf("wave %2d - length %2d\n", waveformId, length); + for (i = 31; i > 0; i--) { + printf("%2d: ", i); + for (j = 1; j <= length; j++) { + if (fade_calculateWaveform(waveformId, j) >= i) { + printf("*"); + } else { + printf(" "); + } + } + printf("\n"); + } + printf(" "); + for (j = 1; j <= length; j++) { + printf("="); + } + printf("\n"); + exit(0); +} + +/** + * Main function. Initializes the USB-device, parses commandline-parameters and + * calls the functions that communicate with the device. + * \param argc Number of arguments. + * \param argv Arguments. + * \return Error code. + */ +int main(int argc, char **argv) +{ + usb_dev_handle *handle = NULL; + + if (argc < 2) { + usage(argv[0]); + exit(1); + } + usb_init(); + if (usbOpenDevice (&handle, USBDEV_SHARED_VENDOR, "www.schatenseite.de", USBDEV_SHARED_PRODUCT, "USB-LED-Fader") != 0) { + fprintf(stderr, "Could not find USB device \"USB-LED-Fader\" with vid=0x%x pid=0x%x\n", USBDEV_SHARED_VENDOR, USBDEV_SHARED_PRODUCT); + exit(1); + } + /* We have searched all devices on all busses for our USB device above. Now + * try to open it and perform the vendor specific control operations for the + * function requested by the user. + */ + if (strcmp(argv[1], "test") == 0) { + dev_test(handle, argc, argv); + } else if (strcmp(argv[1], "set") == 0) { + dev_set(handle, argc, argv); + } else if (strcmp(argv[1], "clear") == 0) { + dev_clear(handle, argc, argv); + } else if (strcmp(argv[1], "status") == 0) { + dev_status(handle, argc, argv); + } else if (strcmp(argv[1], "reset") == 0) { + dev_reset(handle, argc, argv); + } else if (strcmp(argv[1], "show") == 0) { + dev_reset(handle, argc, argv); + } else { + usage(argv[0]); + exit(1); + } + usb_close(handle); + return 0; +} + diff --git a/common/channels.h b/common/channels.h new file mode 100644 index 0000000..d517de6 --- /dev/null +++ b/common/channels.h @@ -0,0 +1,16 @@ +#ifndef __channels_h_included__ +#define __channels_h_included__ + +/** + * \file channels.h + * \brief Global definitions, used by the firmware and the commandline-client. + * \author Thomas Stegemann + * \version $Id: channels.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + */ + +#define CHANNELS 4 /**< number of output channels */ + +#endif + diff --git a/common/usbledfader.h b/common/usbledfader.h new file mode 100644 index 0000000..5095cf4 --- /dev/null +++ b/common/usbledfader.h @@ -0,0 +1,466 @@ +#ifndef __usbledfader_h_included__ +#define __usbledfader_h_included__ + +/** + * \file usbledfader.h + * \brief Global definitions and datatypes, used by the firmware and the commandline-client. Also contains the main doxygen-documentation. + * \author Ronald Schaten & Thomas Stegemann + * \version $Id: usbledfader.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + */ + +/** + * \mainpage USB-LED-Fader + * + * \section sec_intro Introduction + * + * The USB-LED-Fader is a device to control a number of LEDs via USB. I built + * it to display the online-status of my internet-connection, the + * recording-status of my videorecorder, and warnings if the available + * disc-space is low. You can imagine an endless number of applications for + * this. + * + * The LEDs are controlled with pulse width modulation (PWM). That way, they + * are not only on or off, it is possible to control the brightness. Included + * in the device is a number of 'waveforms' that can be displayed on the LEDs. + * That way, one LED can display some kind of a sinus- or triangular wave + * without any interaction with the controlling host. + * + * Every LED can be controlled individually, each one can display it's own + * waveforms. + * + * You can assign three different waves to every LED: two 'eternal' waves (0 & + * 1). They are displayed alternating until anything different is required. The + * third wave (2) is only displayed once, afterwards the device will switch + * back to alternating between the first two waves. + * + * One wave is described by three parameters: the waveform, the duration for + * one repetition of the wave and the number of repetitions before switching to + * the next wave. + * + * This version supports four LEDs, it should be quite easy to change that + * number between one and eight. I have not tested any number greater than + * four, but I can imagine that the load on the controller can be too high to + * reliably communicate via USB. + * + * There are three parts included in the distribution: The firmware for an + * ATmega8 microcontroller, a commandline-client that can be run under Linux, + * and the circuits needed to build the device. + * + * This project is based on the PowerSwitch example application by Objective + * Development. Like that, it uses Objective Development's firmware-only USB + * driver for Atmel's AVR microcontrollers. + * + * Objective Development's USB driver is a firmware-only implementation of the + * USB 1.1 standard (low speed device) on cheap single chip microcomputers of + * Atmel's AVR series, such as the ATtiny2313 or even some of the small 8 pin + * devices. It implements the standard to the point where useful applications + * can be implemented. See the file "firmware/usbdrv/usbdrv.h" for features and + * limitations. + * + * \section sec_install Building and installing + * + * Both, the firmware and Unix command line tool are built with "make". You may + * need to customize both makefiles. + * + * \subsection sec_fw Firmware + * + * The firmware for this project requires avr-gcc and avr-libc (a C-library for + * the AVR controller). Please read the instructions at + * http://www.nongnu.org/avr-libc/user-manual/install_tools.html for how to + * install the GNU toolchain (avr-gcc, assembler, linker etc.) and avr-libc. + * + * Once you have the GNU toolchain for AVR microcontrollers installed, you can + * run "make" in the subdirectory "firmware". You may have to edit the Makefile + * to use your preferred downloader with "make program". The current version is + * built for avrdude with a parallel connection to an stk200-compatible + * programmer. + * + * If working with a brand-new controller, you may have to set the fuse-bits to + * use the external crystal: + * + * \code + * avrdude -p atmega8 -P /dev/parport0 -c sp12 -U hfuse:w:0xC9:m -U lfuse:w:0x9F:m + * \endcode + * + * Afterwards, you can compile and flash to the device: + * + * \code + * make program + * \endcode + * + * \subsection sec_client Commandline client + * + * The command line tool requires libusb. Please take the packages from your + * system's distribution or download libusb from http://libusb.sourceforge.net/ + * and install it before you compile. Change to directory "commandline", check + * the Makefile and edit the settings if required and type + * + * \code + * make + * \endcode + * + * This will build the unix executable "usb-led-fader" which can be used to + * control the device. + * + * \section sec_usage Usage + * + * Connect the device to the USB-port. All LED should flash up to indicate that + * the device is initialized. + * + * Then use the commandline-client as follows: + * + * \code + * usb-led-fader status + * usb-led-fader set + * usb-led-fader clear + * usb-led-fader reset + * usb-led-fader show + * usb-led-fader test + * \endcode + * + * When using the set-function, it is possible to define several waves at once. + * You simply have to give the parameters for all waves. See examples below. + * + * \subsection sec_params Parameters + * + * - \e ledId: ID of the LED (0-n, depending on the number of LEDs in your + * circuit). + * - \e waveId: ID of the wave (0-1: constant waves, 2: override). + * - \e waveformId: ID of the waveform (0-31: brightness, 32-37: patterns). For + * a reference to the patterns, consult the function fade_calculateWaveform() + * in the file "firmware/main.c". + * - \e periodDuration: Time in sec/10 for one repetition of the waveform. A + * value of 0 can be used to reset the wave. + * - \e repetitionCount: Number of repetitions before switching to the next + * wave. A value of 0 can be used to repeat this forever. + * + * \subsection sec_examples Examples + * + * Get the status of all LEDs: + * \code + * usb-led-fader status + * \endcode + * This will result in an output similar to this: + * \code + * LED 0 curid curvalue curpos currep nextupd + * 0 2 26 0 23 + * wave waveform length repeat duration updtime + * 0 38 32 1 20 45 + * 1 0 1 1 0 1 + * 2 0 1 1 0 1 + * LED 1 curid curvalue curpos currep nextupd + * 0 14 19 0 19 + * wave waveform length repeat duration updtime + * 0 38 32 1 20 45 + * 1 0 1 1 0 1 + * 2 0 1 1 0 1 + * LED 2 curid curvalue curpos currep nextupd + * 0 31 16 0 43 + * wave waveform length repeat duration updtime + * 0 38 32 1 20 45 + * 1 0 1 1 0 1 + * 2 0 1 1 0 1 + * LED 3 curid curvalue curpos currep nextupd + * 0 6 9 0 39 + * wave waveform length repeat duration updtime + * 0 38 32 1 20 45 + * 1 0 1 1 0 1 + * 2 0 1 1 0 1 + * \endcode + * In this output, the values curvalue, curpos, nextupd and updtime are for + * debugging purposes only. They shouldn't be of interest to the common user. + * The meaning of the other values should be clear. + * + * Set the first LED to keep a middle brightness: + * \code + * usb-led-fader set 0 0 15 10 1 + * \endcode + * So, on LED 0 the wave 0 is set to waveform 15. It will stay there for one + * second and will be repeated once before switching to the next wave. There is + * no next wave because we didn't define one, so this waveform will stay + * forever. + * + * Now set a second wave on the first LED, a little brighter than the one + * before: + * \code + * usb-led-fader set 0 1 25 10 1 + * \endcode + * This is wave 1 on LED 0, waveform 25 indicates a constant level of + * brightness. After setting the second wave, it will alternate with the first + * one after every second, because both waves have the same duration and the + * same number of repetitions. + * + * Set a third wave on the first LED: + * \code + * usb-led-fader set 0 2 36 20 5 + * \endcode + * This sets the third wave (wave 2) on the first LED. Waveform 36 is a nice + * sinus-like wave, so the LED starts to fade. One period of the fading takes 2 + * seconds, it is repeated for 5 times. Since this is the third wave, after the + * repetitions the LED returns to alternating between wave 0 and wave 1, this + * wave is discarded. + * + * Set multiple waves at once: + * \code + * usb-led-fader set 0 0 15 10 1 0 1 25 10 1 0 2 36 20 5 + * \endcode + * This will set all of the above waves at once. Thus, the first LED will first + * fade the sinus-wave five times, then start alternating between the two + * brightnesses in one-second-rhythm. + * + * Clear the first LED: + * \code + * usb-led-fader clear 0 + * \endcode + * This will clear all three waves on the first LED. + * + * Reset the device: + * \code + * usb-led-fader reset + * \endcode + * All LEDs will flash once, to indicate that the device is reset and the LEDs + * are working. + * + * Show a waveform on the screen: + * \code + * usb-led-fader show 36 + * \endcode + * This will lead to an output like the following: + * \code + * wave 36 - length 64 + * 31: ***** + * 30: ********* + * 29: *********** + * 28: *************** + * 27: ***************** + * 26: ******************* + * 25: ******************* + * 24: ********************* + * 23: *********************** + * 22: ************************* + * 21: ************************* + * 20: *************************** + * 19: ***************************** + * 18: ***************************** + * 17: ******************************* + * 16: ********************************* + * 15: *********************************** + * 14: *********************************** + * 13: ************************************* + * 12: *************************************** + * 11: *************************************** + * 10: ***************************************** + * 9: ******************************************* + * 8: ********************************************* + * 7: ********************************************* + * 6: *********************************************** + * 5: ************************************************* + * 4: ***************************************************** + * 3: ******************************************************* + * 2: *********************************************************** + * 1: **************************************************************** + * ================================================================ + * \endcode + * Keep in mind that the width of the displayed wave corresponds to the length + * of the waveform. If you display a very simple one like the constant + * brightness levels (0-31), the length is 1. Therefore only one column is + * displayed. + * + * Test the device: + * \code + * usb-led-fader test + * \endcode + * This function sends many random numbers to the device. The device returns + * the packages, and the client looks for differences in the sent and the + * received numbers. + * + * \section sec_drawbacks Drawbacks + * + * As mentioned above, controlling the PWM for several LEDs is a lot of work + * for one small microcontroller. Speaking the USB protocol is so, either. Both + * combined result in a lot of load on the device, so the communication with + * the device is not 100% reliable. More than 99% though, at least in our + * tests. + * + * SO BE WARNED: You should not use this device to control the state of + * your nuclear reactor. If you intend to use it in that way despite of this + * warning, please let me know... ;-) + * + * + * \section sec_files Files in the distribution + * + * - \e Readme.txt: The file you are currently reading. + * - \e firmware: Source code of the controller firmware. + * - \e firmware/usbdrv: USB driver -- See Readme.txt in this directory for + * info + * - \e commandline: Source code of the host software (needs libusb). + * - \e common: Files needed by the firmware and the commandline-client. + * - \e circuit: Circuit diagrams in PDF and EAGLE 4 format. A free version of + * EAGLE is available for Linux, Mac OS X and Windows from + * http://www.cadsoft.de/. + * - \e License.txt: Public license for all contents of this project, except + * for the USB driver. Look in firmware/usbdrv/License.txt for further info. + * - \e Changelog.txt: Logfile documenting changes in soft-, firm- and + * hardware. + * + * \section sec_thanks Thanks! + * + * I'd like to thank Objective Development for the possibility to use + * their driver for my project. In fact, this project wouldn't exist without + * the driver. + * + * And I'd like to give special credits to Thomas Stegemann. He wrote + * the PWM-stuff, and I guess it would have been nearly to impossible to me to + * write the rest of the project without his help since C isn't my natural + * language. + * + * \section sec_license About the license + * + * Our work - all contents except for the USB driver - are licensed under the + * GNU General Public License (GPL). A copy of the GPL is included in + * License.txt. The driver itself is licensed under a special license by + * Objective Development. See firmware/usbdrv/License.txt for further info. + * + * (c) 2006 by Ronald Schaten - http://www.schatenseite.de + */ + +#include + +/* return codes for USB-communication */ +#define msgOK 0 /**< Return code for OK. */ +#define msgErr 1 /**< Return code for Error. */ + +/* These are the vendor specific SETUP commands implemented by our USB device */ +#define CMD_ECHO 0 /**< Command to echo the sent data */ +#define CMD_GET 1 /**< Command to fetch values */ +#define CMD_SET 2 /**< Command to send values */ +#define CMD_CLEAR 3 /**< Command to switch off a certain LED */ +#define CMD_RESET 4 /**< Command to reset the whole device */ + +/** Description of one waveform. */ +typedef struct S_fade_Waveform { + uint8_t waveformId; /**< ID of this waveform. */ + uint8_t waveformLength; /**< Length of this waveform. */ + uint8_t waveformRepetition; /**< How often is this waveform to be repeated? */ + uint8_t waveformDuration; /**< Duration for one cycle of this waveform, stored for status-output. */ + uint32_t waveformUpdateTime; /**< Time between two waveform-samples in calls of timerInterrupt(), calculated from waveformDuration. */ +} fade_Waveform; + +/** The state of one LED. */ +typedef struct S_fade_LedState { + fade_Waveform wave[3]; /**< Three waveforms: base-function1, base-function2 and override-function. */ + uint8_t waveCurrentId; /**< Which of the three waveforms is currently displayed? */ + uint8_t waveCurrentValue; /**< The current brightness. */ + uint8_t waveCurrentPosition; /**< Our position in the current waveform. */ + uint8_t waveCurrentRepetition; /**< We are in the n-th repetition. */ + int32_t waveNextUpdate; /**< Number of cycles till next update. */ +} fade_LedState; + +/** Contains the state of all four LEDs. */ +typedef struct S_fade_GlobalData { + fade_LedState led[4]; /**< Data for four LEDs. */ +} fade_GlobalData; + +uint8_t fade_calculateWaveform(uint8_t waveformId, uint8_t waveformPosition); + +/** + * Calculate a waveform. Returns either the length of a given waveform or the + * output-level at a certain position in the wave. + * \param waveformId ID of the waveform in question. + * \param waveformPosition 0 or position in the given waveform. + * \return If the waveformPosition is 0, the number of steps in this waveform is returned. Otherwise the resulting output-level, an integer between 0 and 31. + */ +uint8_t fade_calculateWaveform(uint8_t waveformId, uint8_t waveformPosition) { + /* + * values for sinus-wave, amplitude 31, 64 steps: + * awk 'BEGIN{ pi=3.1415927; for(i=1; i<=64; i++) { printf("%.0f, ", sin(i*pi/32)*31) } printf("\n"); }' + * 3, 6, 9, 12, 15, 17, 20, 22, 24, 26, 27, 29, 30, 30, 31, 31, 31, 30, + * 30, 29, 27, 26, 24, 22, 20, 17, 15, 12, 9, 6, 3, -0, -3, -6, -9, + * -12, -15, -17, -20, -22, -24, -26, -27, -29, -30, -30, -31, -31, -31, + * -30, -30, -29, -27, -26, -24, -22, -20, -17, -15, -12, -9, -6, -3, 0 + */ + + /* sinus-wave: + * awk 'BEGIN{ pi=3.1415927; for(i=1; i<=64; i++) { printf("%.0f, ", sin((i+48)*pi/32)*15+16) } printf("\n"); }' + */ + uint8_t sinus[] = { 1, 1, 2, 2, 3, 4, 4, 5, 6, 8, 9, 10, 12, 13, 15, 16, + 17, 19, 20, 22, 23, 24, 26, 27, 28, 28, 29, 30, 30, 31, 31, 31, 31, 31, + 30, 30, 29, 28, 28, 27, 26, 24, 23, 22, 20, 19, 17, 16, 15, 13, 12, 10, + 9, 8, 6, 5, 4, 4, 3, 2, 2, 1, 1, 1 }; + + /* + * another nice wave, wider than the original sinus: + * awk 'BEGIN{ pi=3.1415927; for(i=1; i<=32; i++) { printf("%.0f, ", sqrt(sin(i*pi/32)*31+.00001)*sqrt(32)) } printf("\n"); }' + */ + uint8_t widecurve[] = { 10, 14, 17, 19, 22, 23, 25, 26, 28, 29, 30, 30, 31, + 31, 31, 31, 31, 31, 31, 30, 30, 29, 28, 26, 25, 23, 22, 19, 17, 14, 10, + 0 }; + + if (waveformId <= 31) { + /* No fading, just a constant level */ + if (waveformPosition == 0) { + return 1; + } else { + return waveformId; + } + } else { + switch (waveformId) { + case 32: /* blink */ + if (waveformPosition == 0) { + return 2; + } else { + if (waveformPosition == 1) { + return 31; + } else { + return 0; + } + } + case 33: /* triangular */ + if (waveformPosition == 0) { + return 62; + } else { + if (waveformPosition <= 32) { + return waveformPosition - 1; + } else { + return 63 - waveformPosition; + } + } + case 34: /* sawtooth rising */ + if (waveformPosition == 0) { + return 32; + } else { + return waveformPosition - 1; + } + case 35: /* sawtooth falling */ + if (waveformPosition == 0) { + return 32; + } else { + return 31 - (waveformPosition - 1); + } + case 36: /* sinus */ + if (waveformPosition == 0) { + return 64; + } else { + return sinus[waveformPosition - 1]; + } + case 37: /* wide curve */ + if (waveformPosition == 0) { + return 32; + } else { + return widecurve[waveformPosition - 1]; + } + case 38: /* wide curve - inverted */ + if (waveformPosition == 0) { + return 32; + } else { + return 31 - widecurve[(waveformPosition + 15) % 32]; + } + } + } + return 0; +} + +#endif + diff --git a/firmware/Makefile b/firmware/Makefile new file mode 100644 index 0000000..758c563 --- /dev/null +++ b/firmware/Makefile @@ -0,0 +1,48 @@ +# $Id: Makefile,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + +AVRDUDE = avrdude -p atmega8 -P /dev/parport0 -c stk200 + +COMPILE = avr-gcc -Wall -Os -Iusbdrv -I../common -I. -mmcu=atmega8 #-DDEBUG_LEVEL=2 +# NEVER compile the final product with debugging! Any debug output will +# distort timing so that the specs can't be met. + +OBJECTS = usbdrv/usbdrv.o usbdrv/usbdrvasm.o usbdrv/oddebug.o main.o pwm_timer.o pwm_channels.o message_queue.o +# Note that we link usbdrv.o first! This is required for correct alignment of +# driver-internal global variables! + + +# symbolic targets: +all: main.hex + +.c.o: + $(COMPILE) -c $< -o $@ + +.S.o: + $(COMPILE) -x assembler-with-cpp -c $< -o $@ +# "-x assembler-with-cpp" should not be necessary since this is the default +# file type for the .S (with capital S) extension. However, upper case +# characters are not always preserved on Windows. To ensure WinAVR +# compatibility define the file type manually. + +.c.s: + $(COMPILE) -S $< -o $@ + +program: all + $(AVRDUDE) -E noreset,vcc -U flash:w:main.hex + +clean: + rm -f main.hex main.lst main.obj main.cof main.list main.map main.eep.hex main.bin *.o usbdrv/*.o main.s usbdrv/oddebug.s usbdrv/usbdrv.s + +# file targets: +main.bin: $(OBJECTS) + $(COMPILE) -o main.bin $(OBJECTS) + +main.hex: main.bin + rm -f main.hex main.eep.hex + avr-objcopy -j .text -j .data -O ihex main.bin main.hex + +disasm: main.bin + avr-objdump -d main.bin + +cpp: + $(COMPILE) -E main.c diff --git a/firmware/boolean.h b/firmware/boolean.h new file mode 100644 index 0000000..bb64fb0 --- /dev/null +++ b/firmware/boolean.h @@ -0,0 +1,34 @@ +#ifndef boolean_h +#define boolean_h + +/** + * \file boolean.h + * \brief Provides boolean variables in C. + * \author Thomas Stegemann + * \version $Id: boolean.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + */ + +/** Possible boolean values */ +typedef enum E_Boolean { + False = 0, /**< logical false */ + True = 1 /**< logical true */ +} Boolean; + +/** + * Boolean function. Returns true or false, depending on the given condition. + * \param condition The condition to evaluate, must be integer. + * \return True or false. + */ +static inline Boolean +boolean (int condition) +{ + if (condition) { + return True; + } else { + return False; + } +} + +#endif diff --git a/firmware/config_message_queue.h b/firmware/config_message_queue.h new file mode 100644 index 0000000..ad9d440 --- /dev/null +++ b/firmware/config_message_queue.h @@ -0,0 +1,26 @@ +#ifndef config_message_queue_h +#define config_message_queue_h + +/** + * \file config_message_queue.h + * \brief Configures the message-queue. + * \author Thomas Stegemann + * \version $Id: config_message_queue.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + * + * - define the size of the messageQueue(messageQueue_Size) and the type of the + * messageQueue_QueuedMessage + * - check that messageQueue_SizeType can hold 0..messageQueue_Size+1 + * - the messageQueue buffers up to messageQueue_Size messages of the type + * messageQueue_QueuedMessage + * - currently the messageQueue is used by pwm_Channels and pwm_Timer with the + * pwm_Channels_Message + */ + +#include "pwm_timer.h" + +typedef pwm_Channels_Message messageQueue_QueuedMessage; +enum { messageQueue_Size = 3 }; + +#endif diff --git a/firmware/config_message_queue_impl.h b/firmware/config_message_queue_impl.h new file mode 100644 index 0000000..4f9fa54 --- /dev/null +++ b/firmware/config_message_queue_impl.h @@ -0,0 +1,23 @@ +#ifndef config_message_queue_impl_h +#define config_message_queue_impl_h + +/** + * \file config_message_queue_impl.h + * \brief Configures the implementation of the message-queue. + * \author Thomas Stegemann + * \version $Id: config_message_queue_impl.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + * + * - define the SizeType for the messageQueue + * - the messageQueue_SizeType must hold 0..messageQueue_Size + 1, see + * config_message_queue.h + * - the messageQueue_SizeType must be read/written by the processor in an + * atomic instruction + */ + +#include + +typedef uint8_t messageQueue_SizeType; + +#endif diff --git a/firmware/config_pwm_timer_impl.h b/firmware/config_pwm_timer_impl.h new file mode 100644 index 0000000..fc4e2f2 --- /dev/null +++ b/firmware/config_pwm_timer_impl.h @@ -0,0 +1,27 @@ +#ifndef config_pwm_timer_impl_h +#define config_pwm_timer_impl_h + +/** + * \file config_pwm_timer_impl.h + * \brief Configures the implementation of the PWM-timer. + * \author Thomas Stegemann + * \version $Id: config_pwm_timer_impl.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + * + * - pwm_Timer_Cycles_Max defines the number of (prescaled) processor cycles + * for a full pwm_TimerCycle + * - pwm_Timer_Cycles_ReadMin defines the number of (prescaled) processor + * cycles the reading from the message queue may last + * - pwm_Timer_Cycles_SleepMax defines the minimum number of (prescaled) + * processor cycles for which the timer is used. for less cycles the + * pwm_Timer waits active + */ + +#include "pwm_channels.h" + +enum { pwm_Timer_Cycles_Max = pwm_Channels_Brightness_Max * pwm_Channels_Brightness_Max }; +enum { pwm_Timer_Cycles_ReadMin = 2 }; +enum { pwm_Timer_Cycles_SleepMax = 2 }; + +#endif diff --git a/firmware/main.c b/firmware/main.c new file mode 100644 index 0000000..86f27ac --- /dev/null +++ b/firmware/main.c @@ -0,0 +1,278 @@ +/** + * \file main.c + * \brief Firmware for the USB-LED-Fader. + * \author Ronald Schaten & Thomas Stegemann + * \version $Id: main.c,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + */ + +#include +#include +#include + +#include "usbdrv.h" +#include "oddebug.h" +#include "pwm_channels.h" +#include "usbledfader.h" +#include "channels.h" + +/** Global variable, contains the state of all four LEDs. */ +static fade_GlobalData fade_globalData; + +/** Global variable, contains the rest-amount of data to send to the host. */ +static uint8_t usbRead; + +/** + * Handler for the timer-interrupt. Determines the state of the four LEDs and + * calls pwm_Channels_show() if something is to be changed. This function + * contains the logic by which the waveforms are assigned to the LEDs. + */ +static void timerInterrupt(void) +{ + uint8_t i = 0, changed = 0; + for (i = 0; i < CHANNELS; i++) { + fade_LedState *pLed = &(fade_globalData.led[i]); /* fetch current LED */ + pLed->waveNextUpdate--; + if (pLed->waveNextUpdate <= 0) { /* time to update */ + fade_Waveform *pWave = &(pLed->wave[pLed->waveCurrentId]); /* fetch currently active wave */ + pLed->waveCurrentPosition++; /* go to next position */ + if (pLed->waveCurrentPosition > pWave->waveformLength) { + pLed->waveCurrentPosition = 1; /* restart wave */ + if (pWave->waveformRepetition == 0) { + /* repeat this waveform forever */ + } else { + /* next repetition */ + pLed->waveCurrentRepetition++; + if (pLed->waveCurrentRepetition >= pWave->waveformRepetition) { /* enough of this wave */ + pLed->waveCurrentRepetition = 0; /* reset repetition counter */ + switch (pLed->waveCurrentId) { /* activate next wave */ + case 0: + if (pLed->wave[1].waveformDuration > 0) { /* only activate if a wave is set */ + pLed->waveCurrentId = 1; + } + break; + case 1: + if (pLed->wave[0].waveformDuration > 0) { /* only activate if a wave is set */ + pLed->waveCurrentId = 0; + } + break; + case 2: + /* wave 2 is only to be repeated the given times, + * reset and continue with wave 0 */ + pWave->waveformId = 0; + pWave->waveformLength = fade_calculateWaveform(pWave->waveformId, 0); + pWave->waveformRepetition = 1; + pWave->waveformDuration = 0; + pWave->waveformUpdateTime = 1; + pLed->waveCurrentId = 0; + break; + } + } + } + } + uint8_t newValue = fade_calculateWaveform(pLed->wave[pLed->waveCurrentId].waveformId, pLed->waveCurrentPosition); /* fetch new value */ + if (newValue != pLed->waveCurrentValue) { /* only update if the value has changed */ + pLed->waveCurrentValue = newValue; + changed = 1; + } + pLed->waveNextUpdate = pLed->wave[pLed->waveCurrentId].waveformUpdateTime; /* next update according to the wave's settings */ + } + } + if (changed) { /* any value has changed, update all LEDs */ + pwm_Channels channels; + for (i = 0; i < CHANNELS; i++) { + channels.channel[i] = fade_globalData.led[i].waveCurrentValue; + } + pwm_Channels_show(channels); + } +} + +/** + * Start displaying a certain waveform on a single LED. + * \param ledId ID of the LED that is changed. + * \param waveId ID of the wave that to be set: 0 and 1 are the base waves, 2 is the override wave. + * \param waveformId ID of the Waveform that is to be assigned to the LED. + * \param periodDuration How long should this wave stay on display? Time in seconds/10. + * \param repetitionCount How many times should this wave be repeated while it is on display? + */ +void fade_startWaveform(uint8_t ledId, uint8_t waveId, uint8_t waveformId, uint8_t periodDuration, uint8_t repetitionCount) { + if ((ledId < CHANNELS) && (waveId < 3)) { + fade_LedState *pLed = &(fade_globalData.led[ledId]); + fade_Waveform *pWave = &(pLed->wave[waveId]); + pLed->waveCurrentId = waveId; + pLed->waveCurrentPosition = 0; + pLed->waveCurrentRepetition = 0; + pLed->waveNextUpdate = 0; + if (periodDuration > 0) { + pWave->waveformId = waveformId; + pWave->waveformLength = fade_calculateWaveform(waveformId, 0); + pWave->waveformRepetition = repetitionCount; + pWave->waveformDuration = periodDuration; + /* waveformUpdateTime in calls of timerInterrupt(). + * periodDuration in seconds/10. + * 12000000 cycles per second + * 64 cycles per timer/counter (prescaler) + * 256 timer/counter per interrupt-call + * -> (12000000 / (256 * 64)) = 732 calls per second */ + pWave->waveformUpdateTime = ((uint32_t)periodDuration * 12000000 / 256 / 64 / 10 / pWave->waveformLength ); + } else { + /* periodDuration = 0, reset the wave */ + pWave->waveformId = 0; + pWave->waveformLength = fade_calculateWaveform(pWave->waveformId, 0); + pWave->waveformRepetition = 1; + pWave->waveformDuration = 0; + pWave->waveformUpdateTime = 1; + } + } +} + +/** + * Fills fade_globalData. The state of all LEDs is initialized to off. One + * signal is displayed on all LEDs to ensure they're working. + */ +void fade_globalData_init(void) { + int i = 0, j = 0; + for (i = 0; i < CHANNELS; i++) { + fade_globalData.led[i].waveCurrentId = 0; + fade_globalData.led[i].waveCurrentPosition = 0; + fade_globalData.led[i].waveCurrentRepetition = 0; + fade_globalData.led[i].waveNextUpdate = 0; + for (j = 0; j < 3; j++) { + fade_globalData.led[i].wave[j].waveformId = 0; + fade_globalData.led[i].wave[j].waveformLength = + fade_calculateWaveform(fade_globalData.led[i].wave[j]. + waveformId, 0); + fade_globalData.led[i].wave[j].waveformRepetition = 1; + fade_globalData.led[i].wave[j].waveformDuration = 0; + fade_globalData.led[i].wave[j].waveformUpdateTime = 1; + } + } + /* show that we are ready */ + for (i = 0; i < CHANNELS; i++) { + fade_startWaveform(i, 2, 36, 10, 1); + } +} + +/** + * USB-Data-Handler (device -> host). Handles data that is to be sent to the + * host via USB-Interface. In our case the data contains the current settings + * for the LEDs. This function is called until the returned length is shorter + * than the buffer (typically 8 bytes). + * \param data Buffer for the data. + * \param len Length of the buffer. + * \return Length of the returned buffer. + */ +uchar usbFunctionRead(uchar *data, uchar len) { + uint8_t i = 0; + uint8_t *p_fade_globalData = (uint8_t*)&fade_globalData; + while ((i < len) && (usbRead < sizeof(fade_GlobalData))) { + data[i] = p_fade_globalData[usbRead]; + usbRead++; + i++; + } + return i; +} + +/** + * USB-Data-Handler (host -> device). Handles data that is received from the + * USB-Interface. In our case the data contains settings for the LEDs. + * \param data The received data, up to 8 bytes. + * \param len Length of the received data. + * \return 1 if we have received the entire payload successfully, 0 if we expect more data. We don't, so we always return 1. + */ +uchar usbFunctionWrite(uchar *data, uchar len) { + /* parameters: + * data[0]: command (0: echo, 1: read status, 2: set status, 3: clear) + * data[1]: ledId + * data[2]: waveId + * data[3]: waveformId + * data[4]: periodDuration + * data[5]: repetitionCount + */ + fade_startWaveform(data[1], data[2], data[3], data[4], data[5]); + return 1; +} + +/** + * USB-Setup-Handler. Handles setup-calls that are received from the + * USB-Interface. + * \param data Eight bytes of data. + * \return The number of returned bytes (in replyBuffer[]). + */ +uchar usbFunctionSetup(uchar data[8]) { + int i; + static uchar replyBuffer[8]; + uchar replyLength; + + replyBuffer[0] = msgOK; + switch (data[1]) { + case CMD_ECHO: /* echo */ + replyBuffer[0] = data[2]; + replyBuffer[1] = data[3]; + replyLength = 2; + break; + case CMD_GET: /* read status */ + usbRead = 0; + replyLength = 0xff; /* special value, indicates that usbFunctionRead() has to be called */ + break; + case CMD_SET: /* set status */ + replyLength = 0xff; /* special value, indicates that usbFunctionWrite() has to be called */ + break; + case CMD_CLEAR: /* clear one LED */ + for (i = 0; i <= 2; i++) { + /* clear all three waves on this LED */ + fade_startWaveform(data[2], i, 0, 0, 0); + } + replyLength = 1; + break; + case CMD_RESET: /* reset the device */ + fade_globalData_init(); + replyLength = 1; + break; + default: /* WTF? */ + replyBuffer[0] = msgErr; + replyLength = 1; + break; + } + usbMsgPtr = replyBuffer; + return replyLength; +} + +/** + * Main-function. Initializes the hardware and starts the main loop of the + * application. + * \return An integer. Whatever... :-) + */ +int main(void) { + uchar i, j; + odDebugInit(); + DDRB = ~0; /* output SE0 for USB reset */ + PORTB = 0x00; /* no pullups on USB pins */ + DDRC = 0xff; /* all outputs */ + PORTC = 0x00; + DDRD = 0x00; /* all inputs */ + PORTD = 0x00; + + j = 0; + while (--j) { /* USB Reset by device only required on Watchdog Reset */ + i = 0; + while (--i); /* delay >10ms for USB reset */ + } + DDRB = ~USBMASK; /* all outputs except USB data */ + TCCR0 = 3; /* set prescaler to 1/64 */ + usbInit(); + sei(); + + pwm_Channels_init(); + fade_globalData_init(); + + while (1) { /* main event loop */ + usbPoll(); + if (TIFR & (1 << TOV0)) { + TIFR |= 1 << TOV0; /* clear pending flag */ + timerInterrupt(); + } + } + return 0; +} diff --git a/firmware/message_queue.c b/firmware/message_queue.c new file mode 100644 index 0000000..270e6f7 --- /dev/null +++ b/firmware/message_queue.c @@ -0,0 +1,95 @@ +/** + * \file message_queue.c + * \brief A message queue used to exchange messages between two concurrent threads. + * \author Thomas Stegemann + * \version $Id: message_queue.c,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + */ + +#include +#include "message_queue.h" +#include "config_message_queue_impl.h" + +/** Structure of the global data of the queue */ +typedef struct S_messageQueue_GlobalData { + messageQueue_QueuedMessage queue[messageQueue_Size]; /**< the queue itself */ + messageQueue_SizeType begin; /**< the current start of the queue */ + messageQueue_SizeType end; /**< the current end of the queue */ +} messageQueue_GlobalData; + +/** Global data of the queue */ +static volatile messageQueue_GlobalData m_data; + +/** + * Get the next entry fron the queue. + * \param value Number of the current entry. + * \return 0 if the value is larger than the queue, otherwise the next entry. + */ +static inline messageQueue_SizeType messageQueue_next(messageQueue_SizeType value) { + value++; + if(value >= messageQueue_Size) { + value= 0; + } + return value; +} + +/** + * Initialize the queue. + */ +void messageQueue_init(void) { + m_data.begin= 0; + m_data.end= 0; +} + +/** + * Clean up the queue. Currently this does nothing. + */ +void messageQueue_cleanup(void) +{} + +/** + * Test if the queue is empty. + * \return True if it is empty, otherwise false. + */ +Boolean messageQueue_isEmpty(void) { + return boolean(m_data.begin == m_data.end); +} + +/** + * Test if the queue is full. If it is full, new entries will overwrite the + * first entries. + * \return True if it is full, otherwise false. + */ +Boolean messageQueue_isFull(void) { + return boolean(messageQueue_next(m_data.end) == m_data.begin); +} + +/** + * Read a message from the queue. + * \param pMessage Pointer to a message variable that should be set to the + * message. + * \return True if an entry could be read, otherwise false. + */ +Boolean messageQueue_read(messageQueue_QueuedMessage* pMessage) { + Boolean success= !messageQueue_isEmpty(); + if(success) { + *pMessage= m_data.queue[m_data.begin]; + m_data.begin= messageQueue_next(m_data.begin); + } + return success; +} + +/** + * Write a message to the queue. + * \param message The message to append. + * \return True if the message could be appended, otherwise false. + */ +Boolean messageQueue_write(messageQueue_QueuedMessage message) { + Boolean success= !messageQueue_isFull(); + if(success) { + m_data.queue[m_data.end]= message; + m_data.end= messageQueue_next(m_data.end); + } + return success; +} diff --git a/firmware/message_queue.h b/firmware/message_queue.h new file mode 100644 index 0000000..3ef5f16 --- /dev/null +++ b/firmware/message_queue.h @@ -0,0 +1,37 @@ +#ifndef message_queue_h +#define message_queue_h + +/** + * \file message_queue.h + * \brief A message queue used to exchange messages between two concurrent + * threads. + * \author Thomas Stegemann + * \version $Id: message_queue.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + * + * - exchange messages between two concurrent threads (e.g.: main thread and + * interrupt calls) + * - before using any other function of the messageQueue, init must be called + * - one thread must be data source (use isFull and write) + * - the other thread must be the data sink (use isEmpty and read) + * - two concurrent threads must not use both the write functions and two + * concurrent threads must not use both the read functions + * - read/write return True on success and False if the message could not be + * read/written because the queue is empty/full + * - the size of the messageQueue and the type of the + * messageQueue_QueuedMessage are defined in config_message_queue.h + * - only one messageQueue can be used in a project + */ + +#include "boolean.h" +#include "config_message_queue.h" + +void messageQueue_init (void); +void messageQueue_cleanup(void); +Boolean messageQueue_isEmpty(void); +Boolean messageQueue_isFull (void); +Boolean messageQueue_read (messageQueue_QueuedMessage* pMessage); +Boolean messageQueue_write (messageQueue_QueuedMessage message); + +#endif diff --git a/firmware/pwm_channels.c b/firmware/pwm_channels.c new file mode 100644 index 0000000..9b20c7b --- /dev/null +++ b/firmware/pwm_channels.c @@ -0,0 +1,108 @@ +/** + * \file pwm_channels.c + * \brief Manages the values of the displayed channels. + * \author Thomas Stegemann + * \version $Id: pwm_channels.c,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + */ + +#include + +#include "pwm_channels.h" +#include "pwm_timer.h" +#include "config_pwm_timer_impl.h" +#include "message_queue.h" + +/** Structure to contain the state of one channel */ +typedef struct S_pwm_Channels_ChannelBrightness { + pwm_Channels_Bitfield field; /**< Bitfield resembling one channel */ + pwm_Timer_Cycles cycle; /**< Number of on-cycles */ +} pwm_Channels_ChannelBrightness; + +/** + * Initialize channels. Basically, only the PWM-timer is started. + */ +void pwm_Channels_init(void) { + pwm_Timer_init(); +} + +/** + * Clean up channels. Basically, the PWM-timer gets cleaned. + */ +void pwm_Channels_cleanup(void) { + pwm_Timer_cleanup(); +} + +/** + * Calculate the Channels_Message. Requires the channel-list to be sorted by + * cycles. + * \param channels Array of the channels. + * \return Current message. + */ +static pwm_Channels_Message pwm_Channels_Message_get(pwm_Channels_ChannelBrightness channels[CHANNELS]) { + int j; + pwm_Channels_StepCounter i= 0; + pwm_Channels_Message message; + message.step[i].field = 0; + for (j = 0; j < CHANNELS; j++) { + message.step[i].field |= channels[j].field; + } + message.step[i].cycle= 0; + + for (j = 0; j < CHANNELS; j++) { + if(channels[j].cycle == message.step[i].cycle) { + message.step[i].field&= ~channels[j].field; + } else { + message.step[i].cycle= channels[j].cycle; + i++; + message.step[i]= message.step[i-1]; + message.step[i].field&= ~channels[j].field; + } + } + message.step[i].cycle= pwm_Timer_Cycles_Max; + return message; +} + +/** + * Calculate number of cycles from a brightness. + * \param brightness The brightness. + * \return The number of cycles. + */ +pwm_Timer_Cycles pwm_Channels_BrightnessToCycles(pwm_Channels_Brightness brightness) { + return brightness * brightness; +} + +/** + * Compare the number of cycles in two channels. This is needed for the + * qsort-call in pwm_Channels_show(). + * \param cmp1 First channel. + * \param cmp2 Second channel. + * \return A value <0 if cmp1 is smaller than cmp2, 0 if they are of the same + * length and a value >0 if cmp1 is larger than cmp2. + */ +int pwm_Channels_CompareChannels(const void * cmp1, const void * cmp2) { + return ((const pwm_Channels_ChannelBrightness*)cmp1)->cycle - ((const pwm_Channels_ChannelBrightness*)cmp2)->cycle; +} + +/** + * Writes the current pattern to the message-queue. The pattern is built from + * the state of all channels. + * \param channels Array with the channel-states. + */ +void pwm_Channels_show(pwm_Channels channels) { + int i; + pwm_Channels_Message message; + pwm_Channels_ChannelBrightness channel_brightness[CHANNELS]; + for (i = 0; i < CHANNELS; i++) { + channel_brightness[i].field = 1 << i; // 1 << i equals 2^i + channel_brightness[i].cycle = pwm_Channels_BrightnessToCycles(channels.channel[i]); + } + + qsort(channel_brightness, CHANNELS, sizeof(pwm_Channels_ChannelBrightness), pwm_Channels_CompareChannels); + message= pwm_Channels_Message_get(channel_brightness); + while(!messageQueue_write(message)) { + pwm_Timer_idle(); + } +} + diff --git a/firmware/pwm_channels.h b/firmware/pwm_channels.h new file mode 100644 index 0000000..cb73fd1 --- /dev/null +++ b/firmware/pwm_channels.h @@ -0,0 +1,39 @@ +#ifndef pwm_Channels_h +#define pwm_Channels_h + +/** + * \file pwm_channels.h + * \brief Manages the values of the displayed channels. + * \author Thomas Stegemann + * \version $Id: pwm_channels.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + * + * - display the specified channels for a cycle of pwm_timer + * - before using the function show, init must be called + * - for every cycle of pwm_timer, show must be called + * - show buffers the selected channels, so it returns immediatly, as long as + * the internal buffer is not full + * - when the buffer is full the function blocks until another pwm_timer cycle + * has processed the current channels + */ +#include +#include "channels.h" + +/** Type to contain the brightness of one channel. */ +typedef uint8_t pwm_Channels_Brightness; + +/** Definition of the maximum brightness. */ +enum { pwm_Channels_Brightness_Max = 31 }; + +/** Structure to contain the state of several channels. */ +typedef struct S_pwm_Channels { + pwm_Channels_Brightness channel[CHANNELS]; /**< Array of channels. */ +} pwm_Channels; + +void pwm_Channels_init(void); +void pwm_Channels_cleanup(void); +void pwm_Channels_show(pwm_Channels channels); + +#endif + diff --git a/firmware/pwm_timer.c b/firmware/pwm_timer.c new file mode 100644 index 0000000..c7893c2 --- /dev/null +++ b/firmware/pwm_timer.c @@ -0,0 +1,139 @@ +/** + * \file pwm_timer.c + * \brief Controls the actual PWM-output. + * \author Thomas Stegemann + * \version $Id: pwm_timer.c,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + */ + +#include +#include +#include + +#include "boolean.h" +#include "message_queue.h" +#include "pwm_timer.h" +#include "config_pwm_timer_impl.h" + +/** Structure to contain the global data for the timer. */ +typedef struct S_pwm_Timer_GlobalData { + pwm_Channels_Message message[2]; /**< Array of two messages */ + pwm_Channels_Message* pActive; /**< Pointer to the active message */ + pwm_Channels_Message* pRead; /**< Pointer to the message to read */ + pwm_Channels_StepCounter step; /**< Current step in the cycle */ + pwm_Timer_Cycles currentCycle; /**< Current cycle */ + Boolean readDone; /**< Indicates if something is read from the queue */ +} pwm_Timer_GlobalData; + +static pwm_Timer_GlobalData m_data; /**< Global data for the timer. */ + +/** + * Initialize the PWM-Timer. Sets basic values, starts the timer and + * initializes output-pins. + */ +void pwm_Timer_init(void) { + messageQueue_init(); + m_data.step= 0; + m_data.currentCycle= 0; + m_data.pActive= &m_data.message[0]; + m_data.pRead= &m_data.message[1]; + m_data.readDone= False; + m_data.pActive->step[0].cycle= pwm_Channels_Brightness_Max; + m_data.pActive->step[0].field= 0; + /* clk/64 prescaling, CTC mode */ + /* enable timer1 overflow (=output compare 1a) */ + TCCR1B= _BV(CS11) | _BV(CS10) | _BV(WGM12); + TCCR1A= 0; + TIMSK|= _BV(OCIE1A); + /* load initial delay */ + OCR1A= pwm_Timer_Cycles_Max; + /* initialize output pin */ + DDRC = (1 << CHANNELS) - 1; // set all used channel-pins to output + PORTC = 0; + sei(); +} + +/** + * Clean up the timer. Basically, the message-queue is cleaned. + */ +void pwm_Timer_cleanup(void) { + messageQueue_cleanup(); +} + +/** + * Do nothing. + */ +void pwm_Timer_idle(void) +{} + +/** + * Sleeps the required number of cycles. There are two possible ways of + * sleeping: 'active' and 'passive'. If we are required to sleep less than the + * number of cycles defined in pwm_Timer_Cycles_SleepMax, we execute an empty + * loop until we are ready (active sleeping). Otherwise, we set the timer to + * wake us after the given number of cycles (passive sleeping). + * \param sleep Number of cycles. + * \return True if we slept 'actively' (doing the while-loop), otherwise false. + */ +static Boolean pwm_Timer_sleep(pwm_Timer_Cycles sleep) { + Boolean sleepDone= False; + if((sleep < pwm_Timer_Cycles_SleepMax)) { + while (TCNT1 < sleep) + {} + sleepDone= True; + } else { + OCR1A= sleep; + } + return sleepDone; +} + +/** + * Switch the output-pins to the given pattern. + * \param field 8-bit output-pattern. + */ +static void pwm_Timer_switchLed(pwm_Channels_Bitfield field) { + PORTC= field; +} + +/** + * Timer interrupt routine. Determines the pattern to set and handles the times + * to do PWM. + */ +SIGNAL(SIG_OUTPUT_COMPARE1A) { + pwm_Timer_Cycles sleep= pwm_Timer_Cycles_Max; + OCR1A= pwm_Timer_Cycles_Max; + sei(); + do { + if((m_data.step == pwm_Channels_StepCounter_Max) || (m_data.currentCycle == pwm_Timer_Cycles_Max)) { + if(m_data.readDone) { + pwm_Channels_Message* pSwap= m_data.pActive; + m_data.pActive= m_data.pRead; + m_data.pRead= pSwap; + m_data.readDone= False; + m_data.currentCycle= 0; + m_data.step= 0; + sleep= 0; + } else { + /* error could not read a new channels message in a whole cycle */ + /* wait a complete cycle for the next message */ + //sleep= pwm_Timer_Cycles_Max; + m_data.currentCycle= 0; + m_data.step= 0; + sleep= 0; + } + } else { + pwm_Timer_switchLed(m_data.pActive->step[m_data.step].field); + sleep= m_data.pActive->step[m_data.step].cycle - m_data.currentCycle; + m_data.currentCycle= m_data.pActive->step[m_data.step].cycle; + m_data.step++; + } + } while(pwm_Timer_sleep(sleep)); + + if(!m_data.readDone && (sleep > pwm_Timer_Cycles_ReadMin)) { + if(messageQueue_read(m_data.pRead)) { + m_data.readDone= True; + } + } +} + diff --git a/firmware/pwm_timer.h b/firmware/pwm_timer.h new file mode 100644 index 0000000..b92adc5 --- /dev/null +++ b/firmware/pwm_timer.h @@ -0,0 +1,70 @@ +#ifndef pwm_timer_h +#define pwm_timer_h + +/** + * \file pwm_timer.h + * \brief Controls the actual PWM-output. + * \author Thomas Stegemann + * \version $Id: pwm_timer.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + * + * License: See documentation. + * + * - read and process the pwm_Channels_Message from the messageQueue (written + * by pwm_Channels) + * - use a timed interrupt to switch the led at a specified processor cycle + * - init starts the processing and the timer + * - idle is called by the pwm_Channels when the internal buffer is full + * - at every pwm_timer cycle the leds can be switched in up to four steps + * every step defines which leds are switched on/off and up to which + * processor cycle the status is hold so the brightness for the three leds + * can be switched independently + * - example: + * - start with all leds for 10 cycles: + * \code + * step[0]= {10, 1|2|4}; + * \endcode + * - switch off the red led for further 10 cycles + * \code + * step[1]= {20, 2|4}; + * \endcode + * - switch off the green led for further 10 cycles + * \code + * step[2]= {30, 4}; + * \endcode + * - switch off all leds for the remaining time + * \code + * step[3]= {pwm_Timer_Cycles_Max, 0}; + * \endcode + */ + +#include "pwm_channels.h" + +/** 8-bit-field to contain the state of the channels. */ +typedef uint8_t pwm_Channels_Bitfield; + +/** Value to count the steps in one channel. */ +typedef uint8_t pwm_Channels_StepCounter; + +/** Contains a number of controller-cycles. */ +typedef uint16_t pwm_Timer_Cycles; + +/** Definition of the maximum number of steps. */ +enum{pwm_Channels_StepCounter_Max= CHANNELS + 1}; + +/** Structure to contain one step. */ +typedef struct S_pwm_Channels_Step { + pwm_Timer_Cycles cycle; /**< Number of cycles to complete this step. */ + pwm_Channels_Bitfield field; /**< The state of all channels. */ +} pwm_Channels_Step; + +/** Structure to contain an array of steps. */ +typedef struct S_pwm_Channels_Message { + pwm_Channels_Step step[pwm_Channels_StepCounter_Max]; /**< Array of steps. */ +} pwm_Channels_Message; + +void pwm_Timer_init(void); +void pwm_Timer_cleanup(void); +void pwm_Timer_idle(void); + +#endif + diff --git a/firmware/usbconfig.h b/firmware/usbconfig.h new file mode 100644 index 0000000..b4ee077 --- /dev/null +++ b/firmware/usbconfig.h @@ -0,0 +1,170 @@ +/* Name: usbconfig.h + * Project: AVR USB driver + * Author: Christian Starkjohann + * Creation Date: 2005-04-01 + * Tabsize: 4 + * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH + * License: Proprietary, free under certain conditions. See Documentation. + * This Revision: $Id: usbconfig.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + */ + +#ifndef __usbconfig_h_included__ +#define __usbconfig_h_included__ + +/** + * \file usbconfig.h + * \brief Configuration of the USB-driver. + * \version $Id: usbconfig.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + */ + + +/* +General Description: +This file contains parts of the USB driver which can be configured and can or +must be adapted to your hardware. + +Please note that the usbdrv contains a usbconfig-prototype.h file now. We +recommend that you use that file as a template because it will always list +the newest features and options. +*/ + +/* ---------------------------- Hardware Config ---------------------------- */ + +#define USB_CFG_IOPORTNAME B +/* This is the port where the USB bus is connected. When you configure it to + * "PORTB", the registers PORTB, PINB (=PORTB-2) and DDRB (=PORTB-1) will be + * used. + */ +#define USB_CFG_DMINUS_BIT 0 +/* This is the bit number in USB_CFG_IOPORT where the USB D- line is connected. + * This MUST be bit 0 or 7. All other values will result in a compile error! + */ +#define USB_CFG_DPLUS_BIT 1 +/* This is the bit number in USB_CFG_IOPORT where the USB D+ line is connected. + * This may be any bit in the port. Please note that D+ must also be connected + * to interrupt pin INT0! + */ + +/* #define USB_CFG_PULLUP_IOPORTNAME B */ +/* This is the port where the USB D- pullup resistor is connected. When you + * configure it to "PORTB", the registers PORTB and DDRB (=PORTB-1) will be + * used. If this constant is defined, the macros usbDeviceConnect() and + * usbDeviceDisconnect will be available. + */ +/* #define USB_CFG_PULLUP_BIT 2 */ +/* This is the bit number in USB_CFG_PULLUP_IOPORT where the USB D- 1.5 kOhm + * pullup resistor is connected instead of VBUS. This may be any bit in + * the port. + */ + +/* --------------------------- Functional Range ---------------------------- */ + +#define USB_CFG_HAVE_INTRIN_ENDPOINT 0 +/* Define this to 1 if you want to compile a version with two endpoints: The + * default control endpoint 0 and an interrupt-in endpoint 1. + */ +#define USB_CFG_IMPLEMENT_HALT 0 +/* Define this to 1 if you also want to implement the ENDPOINT_HALT feature + * for endpoint 1 (interrupt endpoint). Although you may not need this feature, + * it is required by the standard. We have made it a config option because it + * bloats the code considerably. + */ +#define USB_CFG_INTR_POLL_INTERVAL 10 +/* If you compile a version with endpoint 1 (interrupt-in), this is the poll + * interval. The value is in milliseconds and must not be less than 10 ms for + * low speed devices. + */ +#define USB_CFG_IS_SELF_POWERED 1 +/* Define this to 1 if the device has its own power supply. Set it to 0 if the + * device is powered from the USB bus. + */ +#define USB_CFG_MAX_BUS_POWER 20 +/* Set this variable to the maximum USB bus power consumption of your device. + * The value is in milliamperes. [It will be divided by two since USB + * communicates power requirements in units of 2 mA.] + */ +#define USB_CFG_SAMPLE_EXACT 0 +/* This variable affects Sampling Jitter for USB receiving. When it is 0, the + * driver guarantees a sampling window of 1/2 bit. The USB spec requires + * that the receiver has at most 1/4 bit sampling window. The 1/2 bit window + * should still work reliably enough because we work at low speed. If you want + * to meet the spec, set this value to 1. This will unroll a loop which + * results in bigger code size. + * If you have problems with long cables, try setting this value to 1. + */ +#define USB_CFG_IMPLEMENT_FN_WRITE 1 +/* Set this to 1 if you want usbFunctionWrite() to be called for control-out + * transfers. Set it to 0 if you don't need it and want to save a couple of + * bytes. + */ +#define USB_CFG_IMPLEMENT_FN_READ 1 +/* Set this to 1 if you need to send control replies which are generated + * "on the fly" when usbFunctionRead() is called. If you only want to send + * data from a static buffer, set it to 0 and return the data from + * usbFunctionSetup(). This saves a couple of bytes. + */ + +/* -------------------------- Device Description --------------------------- */ + +#define USB_CFG_VENDOR_ID 0xc0, 0x16 /* 5824 in dec, stands for VOTI */ +/* USB vendor ID for the device, low byte first. If you have registered your + * own Vendor ID, define it here. Otherwise you use obdev's free shared + * VID/PID pair. Be sure to read USBID-License.txt for rules! + */ +#define USB_CFG_DEVICE_ID 0xdc, 0x05 /* 1500 in dec, obdev's free PID */ +/* This is the ID of the product, low byte first. It is interpreted in the + * scope of the vendor ID. If you have registered your own VID with usb.org + * or if you have licensed a PID from somebody else, define it here. Otherwise + * you use obdev's free shared VID/PID pair. Be sure to read the rules in + * USBID-License.txt! + */ +#define USB_CFG_DEVICE_VERSION 0x00, 0x01 +/* Version number of the device: Minor number first, then major number. + */ +#define USB_CFG_VENDOR_NAME 'w', 'w', 'w', '.', 's', 'c', 'h', 'a', 't', 'e', 'n', 's', 'e', 'i', 't', 'e', '.', 'd', 'e' +#define USB_CFG_VENDOR_NAME_LEN 19 +/* These two values define the vendor name returned by the USB device. The name + * must be given as a list of characters under single quotes. The characters + * are interpreted as Unicode (UTF-16) entities. + * If you don't want a vendor name string, undefine these macros. + * ALWAYS define a vendor name containing your Internet domain name if you use + * obdev's free shared VID/PID pair. See the file USBID-License.txt for + * details. + */ +#define USB_CFG_DEVICE_NAME 'U', 'S', 'B', '-', 'L', 'E', 'D', '-', 'F', 'a', 'd', 'e', 'r' +#define USB_CFG_DEVICE_NAME_LEN 13 +/* Same as above for the device name. If you don't want a device name, undefine + * the macros. See the file USBID-License.txt before you assign a name. + */ +#define USB_CFG_SERIAL_NUMBER_LENGTH 0 +/* Set this define to the number of charcters in the serial number if your + * device should have a serial number to uniquely identify each hardware + * instance. You must supply the serial number in a string descriptor with the + * name "usbCfgSerialNumberStringDescriptor", e.g.: + * #define USB_CFG_SERIAL_NUMBER_LENGTH 5 + * int usbCfgSerialNumberStringDescriptor[] PROGMEM = { + * USB_STRING_DESCRIPTOR_HEADER(USB_CFG_SERIAL_NUMBER_LENGTH), + * '1', '2', '3', '4', '5' + * }; + * See usbdrv.h for more information about the USB_STRING_DESCRIPTOR_HEADER() + * macro or usbdrv.c for example string descriptors. + * You may want to put "usbCfgSerialNumberStringDescriptor" at a constant + * flash memory address (with magic linker commands) so that you don't need + * to recompile if you change it. + */ +#define USB_CFG_DEVICE_CLASS 0xff +#define USB_CFG_DEVICE_SUBCLASS 0 +/* See USB specification if you want to conform to an existing device class. + */ +#define USB_CFG_INTERFACE_CLASS 0 +#define USB_CFG_INTERFACE_SUBCLASS 0 +#define USB_CFG_INTERFACE_PROTOCOL 0 +/* See USB specification if you want to conform to an existing device class or + * protocol. + */ +#define USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH 0 /* total length of report descriptor */ +/* Define this to the length of the HID report descriptor, if you implement + * an HID device. Otherwise don't define it or define it to 0. + */ + +#endif /* __usbconfig_h_included__ */ diff --git a/firmware/usbdrv/Changelog.txt b/firmware/usbdrv/Changelog.txt new file mode 100644 index 0000000..fa381ca --- /dev/null +++ b/firmware/usbdrv/Changelog.txt @@ -0,0 +1,115 @@ +This file documents changes in the firmware-only USB driver for atmel's AVR +microcontrollers. New entries are always appended to the end of the file. +Scroll down to the bottom to see the most recent changes. + +2005-04-01: + - Implemented endpoint 1 as interrupt-in endpoint. + - Moved all configuration options to usbconfig.h which is not part of the + driver. + - Changed interface for usbVendorSetup(). + - Fixed compatibility with ATMega8 device. + - Various minor optimizations. + +2005-04-11: + - Changed interface to application: Use usbFunctionSetup(), usbFunctionRead() + and usbFunctionWrite() now. Added configuration options to choose which + of these functions to compile in. + - Assembler module delivers receive data non-inverted now. + - Made register and bit names compatible with more AVR devices. + +2005-05-03: + - Allow address of usbRxBuf on any memory page as long as the buffer does + not cross 256 byte page boundaries. + - Better device compatibility: works with Mega88 now. + - Code optimization in debugging module. + - Documentation updates. + +2006-01-02: + - Added (free) default Vendor- and Product-IDs bought from voti.nl. + - Added USBID-License.txt file which defines the rules for using the free + shared VID/PID pair. + - Added Readme.txt to the usbdrv directory which clarifies administrative + issues. + +2006-01-25: + - Added "configured state" to become more standards compliant. + - Added "HALT" state for interrupt endpoint. + - Driver passes the "USB Command Verifier" test from usb.org now. + - Made "serial number" a configuration option. + - Minor optimizations, we now recommend compiler option "-Os" for best + results. + - Added a version number to usbdrv.h + +2006-02-03: + - New configuration variable USB_BUFFER_SECTION for the memory section where + the USB rx buffer will go. This defaults to ".bss" if not defined. Since + this buffer MUST NOT cross 256 byte pages (not even touch a page at the + end), the user may want to pass a linker option similar to + "-Wl,--section-start=.mybuffer=0x800060". + - Provide structure for usbRequest_t. + - New defines for USB constants. + - Prepared for HID implementations. + - Increased data size limit for interrupt transfers to 8 bytes. + - New macro usbInterruptIsReady() to query interrupt buffer state. + +2006-02-18: + - Ensure that the data token which is sent as an ack to an OUT transfer is + always zero sized. This fixes a bug where the host reports an error after + sending an out transfer to the device, although all data arrived at the + device. + - Updated docs in usbdrv.h to reflect changed API in usbFunctionWrite(). + +* Release 2006-02-20 + + - Give a compiler warning when compiling with debugging turned on. + - Added Oleg Semyonov's changes for IAR-cc compatibility. + - Added new (optional) functions usbDeviceConnect() and usbDeviceDisconnect() + (also thanks to Oleg!). + - Rearranged tests in usbPoll() to save a couple of instructions in the most + likely case that no actions are pending. + - We need a delay between the SET ADDRESS request until the new address + becomes active. This delay was handled in usbPoll() until now. Since the + spec says that the delay must not exceed 2ms, previous versions required + aggressive polling during the enumeration phase. We have now moved the + handling of the delay into the interrupt routine. + - We must not reply with NAK to a SETUP transaction. We can only achieve this + by making sure that the rx buffer is empty when SETUP tokens are expected. + We therefore don't pass zero sized data packets from the status phase of + a transfer to usbPoll(). This change MAY cause troubles if you rely on + receiving a less than 8 bytes long packet in usbFunctionWrite() to + identify the end of a transfer. usbFunctionWrite() will NEVER be called + with a zero length. + +* Release 2006-03-14 + + - Improved IAR C support: tiny memory model, more devices + - Added template usbconfig.h file under the name usbconfig-prototype.h + +* Release 2006-03-26 + + - Added provision for one more interrupt-in endpoint (endpoint 3). + - Added provision for one interrupt-out endpoint (endpoint 1). + - Added flowcontrol macros for USB. + - Added provision for custom configuration descriptor. + - Allow ANY two port bits for D+ and D-. + - Merged (optional) receive endpoint number into global usbRxToken variable. + - Use USB_CFG_IOPORTNAME instead of USB_CFG_IOPORT. We now construct the + variable name from the single port letter instead of computing the address + of related ports from the output-port address. + +* Release 2006-06-26 + + - Updated documentation in usbdrv.h and usbconfig-prototype.h to reflect the + new features. + - Removed "#warning" directives because IAR does not understand them. Use + unused static variables instead to generate a warning. + - Do not include when compiling with IAR. + - Introduced USB_CFG_DESCR_PROPS_* in usbconfig.h to configure how each + USB descriptor should be handled. It is now possible to provide descriptor + data in Flash, RAM or dynamically at runtime. + - STALL is now a status in usbTxLen* instead of a message. We can now conform + to the spec and leave the stall status pending until it is cleared. + - Made usbTxPacketCnt1 and usbTxPacketCnt3 public. This allows the + application code to reset data toggling on interrupt pipes. + +* Release 2006-07-18 diff --git a/firmware/usbdrv/License.txt b/firmware/usbdrv/License.txt new file mode 100644 index 0000000..400d2e5 --- /dev/null +++ b/firmware/usbdrv/License.txt @@ -0,0 +1,458 @@ +PREFACE + +Conceiving and understanding a new license is not an easy task. To make things +easier for both, the author and the licensee, we have decided to base our +license for the USB driver on an existing license with well-understood +properties. + +Our favorite choice for the base license was the GNU General Public License +(GPL). However, we cannot use the GNU GPL directly for the following reasons: + +(1) It was not intended for projects involving hardware -- we must extend the + term "source code" to at least the circuit diagram. +(2) The GNU GPL does not require publication. Only if a binary is published, + it requires that the source is published as well. This is reasonable for + software because unpublished software is of little relevance. For projects + involving hardware, we want to REQUIRE publication. More than that, we + even want to define HOW the publication must be done (files contained, + file formats etc). +(3) As the author of the software, we can distribute it under more than one + license. For people who don't want to meet the obligations of the GNU GPL, + we want to offer commercial licenses. To avoid a split in revisions of + the driver, we need special privileges to distribute contributed + modifications under proprietary licenses. + +We can not simply modify the GNU GPL and incorporate our changes because the +Free Software Foundation (FSF) who holds the copyright for the text of the +GNU GPL does not allow modifications. We therefore set up our own small +license which incorporates the GNU GPL by reference: + + + +LICENSE FOR PROJECTS BUILT WITH "OBJECTIVE DEVELOPMENT'S +FIRMWARE-ONLY USB-DRIVER FOR ATMEL'S AVR MICROCONTROLLERS" +Version 2006-01 + + +I. Definitions + +"OBDEV" shall mean OBJECTIVE DEVELOPMENT Software GmbH or any legal successor +thereof. + +"Software Source Code" shall mean the preferred form of the software for +making modifications to it. + +"USB Driver" shall mean the Software Source Code for OBDEV's firmware-only +USB-driver for Atmel's AVR microcontrollers. + +"Function" shall mean the Software Source Code for all software executed on +the microcontroller except the USB Driver. + +"Host Software" shall mean the Software Source Code for all software required +to control the USB device from the USB host running any operating system. + +"Project" shall mean the USB Driver, the Function, the Host Software, circuit +diagrams of the controller based hardware and accompanying documentation. + +"source code" shall have the same meaning as the term "Project" above. + +"Web Site" shall mean a collection of text and multimedia documents accessible +worldwide over internet through the HyperText Transfer Protocol (HTTP) on +TCP port 80 (standard HTTP port). + + +II. General License Terms +The general terms of this license consist of the GNU General Public License +Version 2 (GNU GPL2) which is hereby incorporated into this section as though +it were fully set forth here. A copy of the GNU GPL2 is included for your +convenience in appendix A of this license. + +The term "source code" in the GNU GPL2 is to be understood as defined in +section I above. If any term or definition in section I, III, IV or V +conflicts with the GNU GPL2, the term or definition in section I, III, IV or +V has precedence of the GNU GPL2. + + +III. Distribution of the Project +The distributed form of a Project must contain at least the following files: +(a) Software Source Code files for the USB Driver, the Function and the Host + Software. +(b) Circuit diagrams for the hardware in PDF, PNG or GIF image file format. +(c) A file with name "Readme.txt" in ASCII format with at least the following + content (in English language): + - An explanation what the Project does. + - What to do with the distributed files (installation procedure etc.). + - A reference to Objective Development's USB driver. + - Your (author's) name and contact information. E-mail and/or URL is + sufficient. +(d) Optionally a text file with a description of the circuit diagram, an + explanation of special (software) techniques used etc. +(e) A copy of this license in a file with the name "License.txt". This copy + can be in the "usbdrv" subdirectory which contains the driver. + + +IV. Requirement for Publication +All modifications and derived work (Projects using the USB Driver) MUST be +distributed (published) as described in section III above on a Web Site. The +main page must reproduce at least a description of the Project (e.g. as +contained in the "Readme.txt" file distributed) and a download link for the +entire Project. The URL of the main page must be submitted to OBDEV. OBDEV +will provide a mechanism for submitting Project URLs and for publishing +Projects on their Web Site. The Project must remain available for at least +twelve (12) months after the initial publication or at least six (6) months +after a subsequent version of that particular Project has been published. + + +V. Author Privileges +OBDEV reserves the right to distribute the USB Driver and all modified +versions under other (proprietary) licenses. If you modify the USB Driver +under the grants of this license, you therefore grant OBDEV (in addition to +the grants of the GNU GPL2) a worldwide, perpetual, irrevocable royalty free +license for your modifications. OBDEV shall not automatically gain rights +other than those of the GNU GPL2 in the other parts of the Project. This +section V overrides possibly contradicting terms in the GNU GPL2 referenced +in section II. + + +APPENDIX A + + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/firmware/usbdrv/Readme.txt b/firmware/usbdrv/Readme.txt new file mode 100644 index 0000000..b309b3e --- /dev/null +++ b/firmware/usbdrv/Readme.txt @@ -0,0 +1,88 @@ +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/avrusb/ + +This directory contains the USB firmware only. Copy it as-is to your own +project and add your own version of "usbconfig.h". A template for your own +"usbconfig.h" can be found in "usbconfig-prototype.h" in this directory. + + +TECHNICAL DOCUMENTATION +======================= +The technical documentation for the firmware driver is contained in the file +"usbdrv.h". Please read all of it carefully! + + +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 a single VID/PID pair for free. If you want to use +your own VID and PID instead of our's, define the macros "USB_CFG_VENDOR_ID" +and "USB_CFG_DEVICE_ID" accordingly in "usbconfig.h". + +To use our predefined VID/PID pair, you MUST conform to a couple of +requirements. See the file "USBID-License.txt" for details. + + +HOST DRIVER +=========== +You have received this driver together with an example device implementation +and an example host driver. The host driver is based on libusb and compiles +on various Unix flavors (Linux, BSD, Mac OS X). It also compiles natively on +Windows using MinGW (see www.mingw.org) and libusb-win32 (see +libusb-win32.sourceforge.net). The "Automator" project contains a native +Windows host driver (not based on libusb) for Human Interface Devices. + + +DEVELOPMENT SYSTEM +================== +This driver has been developed and optimized for the GNU compiler version 3 +(gcc 3). It does work well with gcc 4 and future versions will probably be +optimized for gcc 4. We recommend that you use the GNU compiler suite because +it is freely available. AVR-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. Please note that gcc is more +efficient for usbdrv.c because this module has been deliberately optimized +for gcc. + + +USING AVR-USB FOR FREE +====================== +The AVR firmware driver is published under an Open Source compliant license. +See the file "License.txt" for details. Since it is not obvious for many +people how this license applies to their own projects, here's a short guide: + +(1) The USB driver and all your modifications to the driver itself are owned +by Objective Development. You must give us a worldwide, perpetual, +irrevocable royalty free license for your modifications. + +(2) Since you own the code you have written (except where you modify our +driver), you can (at least in principle) determine the license for it freely. +However, to "pay" for the USB driver code you link against, we demand that +you choose an Open Source compliant license (compatible with our license) for +your source code and the hardware circuit diagrams. Simply attach your +license of choice to your parts of the project and leave our "License.txt" in +the "usbdrv" subdirectory. + +(3) We also demand that you publish your work on the Internet and drop us a +note with the URL. The publication must meet certain formal criteria (files +distributed, file formats etc.). See the file "License.txt" for details. + +Other than that, you are allowed to manufacture any number of units and sell +them for any price. If you like our driver, we also encourage you to make a +donation on our web site. + + +COMMERCIAL LICENSES FOR AVR-USB +=============================== +If you don't want to publish your source code and the circuit diagrams under +an Open Source license, you can simply pay money for AVR-USB. As an +additional benefit you get USB PIDs for free, licensed exclusively to you. +See http://www.obdev.at/products/avrusb/license.html for details. + + + diff --git a/firmware/usbdrv/USBID-License.txt b/firmware/usbdrv/USBID-License.txt new file mode 100644 index 0000000..4739a57 --- /dev/null +++ b/firmware/usbdrv/USBID-License.txt @@ -0,0 +1,143 @@ +Royalty-Free Non-Exclusive License USB Product-ID +================================================= + +Version 2006-06-19 + +OBJECTIVE DEVELOPMENT Software GmbH hereby grants you the non-exclusive +right to use three USB.org vendor-ID (VID) / product-ID (PID) pairs with +products based on Objective Development's firmware-only USB driver for +Atmel AVR microcontrollers: + + * VID = 5824 (=0x16c0) / PID = 1500 (=0x5dc) for devices implementing no + USB device class (vendor-class devices with USB class = 0xff). Devices + using this pair will be referred to as "VENDOR CLASS" devices. + + * VID = 5824 (=0x16c0) / PID = 1503 (=0x5df) for HID class devices + (excluding mice and keyboards). Devices using this pair will be referred + to as "HID CLASS" devices. + + * VID = 5824 (=0x16c0) / PID = 1505 (=0x5e1) for CDC class modem devices + Devices using this pair will be referred to as "CDC-ACM CLASS" devices. + +Since the granted right is non-exclusive, the same VID/PID pairs may be +used by many companies and individuals for different products. To avoid +conflicts, your device and host driver software MUST adhere to the rules +outlined below. + +OBJECTIVE DEVELOPMENT Software GmbH has licensed these VID/PID pairs from +Wouter van Ooijen (see www.voti.nl), who has licensed the VID from the USB +Implementers Forum, Inc. (see www.usb.org). The VID is registered for the +company name "Van Ooijen Technische Informatica". + + +RULES AND RESTRICTIONS +====================== + +(1) The USB device MUST provide a textual representation of the +manufacturer and product identification. The manufacturer identification +MUST be available at least in USB language 0x0409 (English/US). + +(2) The textual manufacturer identification MUST contain either an Internet +domain name (e.g. "mycompany.com") registered and owned by you, or an +e-mail address under your control (e.g. "myname@gmx.net"). You can embed +the domain name or e-mail address in any string you like, e.g. "Objective +Development http://www.obdev.at/avrusb/". + +(3) You are responsible for retaining ownership of the domain or e-mail +address for as long as any of your products are in use. + +(4) You may choose any string for the textual product identification, as +long as this string is unique within the scope of your textual manufacturer +identification. + +(5) Matching of device-specific drivers MUST be based on the textual +manufacturer and product identification in addition to the usual VID/PID +matching. This means that operating system features which are based on +VID/PID matching only (e.g. Windows kernel level drivers, automatic actions +when the device is plugged in etc) MUST NOT be used. The driver matching +MUST be a comparison of the entire strings, NOT a sub-string match. For +CDC-ACM CLASS devices, a generic class driver should be used and the +matching is based on the USB device class. + +(6) The extent to which VID/PID matching is allowed for non device-specific +drivers or features depends on the operating system and particular VID/PID +pair used: + + * Mac OS X, Linux, FreeBSD and other Unixes: No VID/PID matching is + required and hence no VID/PID-only matching is allowed at all. + + * Windows: The operating system performs VID/PID matching for the kernel + level driver. You are REQUIRED to use libusb-win32 (see + http://libusb-win32.sourceforge.net/) as the kernel level driver for + VENDOR CLASS devices. HID CLASS devices all use the generic HID class + driver shipped with Windows, except mice and keyboards. You therefore + MUST NOT use any of the shared VID/PID pairs for mice or keyboards. + CDC-ACM CLASS devices require a ".inf" file which matches on the VID/PID + pair. This ".inf" file MUST load the "usbser" driver to configure the + device as modem (COM-port). + +(7) OBJECTIVE DEVELOPMENT Software GmbH disclaims all liability for any +problems which are caused by the shared use of these VID/PID pairs. You +have been warned that the sharing of VID/PID pairs may cause problems. If +you want to avoid them, get your own VID/PID pair for exclusive use. + + +HOW TO IMPLEMENT THESE RULES +============================ + +The following rules are for VENDOR CLASS and HID CLASS devices. CDC-ACM +CLASS devices use the operating system's class driver and don't need a +custom driver. + +The host driver MUST iterate over all devices with the given VID/PID +numbers in their device descriptors and query the string representation for +the manufacturer name in USB language 0x0409 (English/US). It MUST compare +the ENTIRE string with your textual manufacturer identification chosen in +(2) above. A substring search for your domain or e-mail address is NOT +acceptable. The driver MUST NOT touch the device (other than querying the +descriptors) unless the strings match. + +For all USB devices with matching VID/PID and textual manufacturer +identification, the host driver must query the textual product +identification and string-compare it with the name of the product it can +control. It may only initialize the device if the product matches exactly. + +Objective Development provides examples for these matching rules with the +"PowerSwitch" project (using libusb) and with the "Automator" project +(using Windows calls on Windows and libusb on Unix). + + +Technical Notes: +================ + +Sharing the same VID/PID pair among devices is possible as long as ALL +drivers which match the VID/PID also perform matching on the textual +identification strings. This is easy on all operating systems except +Windows, since Windows establishes a static connection between the VID/PID +pair and a kernel level driver. All devices with the same VID/PID pair must +therefore use THE SAME kernel level driver. + +We therefore demand that you use libusb-win32 for VENDOR CLASS devices. +This is a generic kernel level driver which allows all types of USB access +for user space applications. This is only a partial solution of the +problem, though, because different device drivers may come with different +versions of libusb-win32 and they may not work with the libusb version of +the respective other driver. You are therefore encouraged to test your +driver against a broad range of libusb-win32 versions. Do not use new +features in new versions, or check for their existence before you use them. +When a new libusb-win32 becomes available, make sure that your driver is +compatible with it. + +For HID CLASS devices it is necessary that all those devices bind to the +same kernel driver: Microsoft's generic USB HID driver. This is true for +all HID devices except those with a specialized driver. Currently, the only +HIDs with specialized drivers are mice and keyboards. You therefore MUST +NOT use a shared VID/PID with mouse and keyboard devices. + +Sharing the same VID/PID among different products is unusual and probably +violates the USB specification. If you do it, you do it at your own risk. + +To avoid possible incompatibilities, we highly recommend that you get your +own VID/PID pair if you intend to sell your product. Objective +Development's commercial licenses for AVR-USB include a PID for +unrestricted exclusive use. diff --git a/firmware/usbdrv/iarcompat.h b/firmware/usbdrv/iarcompat.h new file mode 100644 index 0000000..ced2877 --- /dev/null +++ b/firmware/usbdrv/iarcompat.h @@ -0,0 +1,70 @@ +/* Name: iarcompat.h + * Project: AVR USB driver + * Author: Christian Starkjohann + * Creation Date: 2006-03-01 + * Tabsize: 4 + * Copyright: (c) 2006 by OBJECTIVE DEVELOPMENT Software GmbH + * License: Proprietary, free under certain conditions. See Documentation. + * This Revision: $Id: iarcompat.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + */ + +/* +General Description: +This header is included when we compile with the IAR C-compiler and assembler. +It defines macros for cross compatibility between gcc and IAR-cc. + +Thanks to Oleg Semyonov for his help with the IAR tools port! +*/ + +#ifndef __iarcompat_h_INCLUDED__ +#define __iarcompat_h_INCLUDED__ + +#if defined __IAR_SYSTEMS_ICC__ || defined __IAR_SYSTEMS_ASM__ + +/* Enable bit definitions */ +#ifndef ENABLE_BIT_DEFINITIONS +# define ENABLE_BIT_DEFINITIONS 1 +#endif + +/* Include IAR headers */ +#include +#ifndef __IAR_SYSTEMS_ASM__ +# include +#endif + +#define __attribute__(arg) +#define IAR_SECTION(section) @ section + +#ifndef USB_BUFFER_SECTION +# define USB_BUFFER_SECTION "TINY_Z" /* if user has not selected a named section */ +#endif + +#ifdef __IAR_SYSTEMS_ASM__ +# define __ASSEMBLER__ +#endif + +#ifdef __HAS_ELPM__ +# define PROGMEM __farflash +#else +# define PROGMEM __flash +#endif + +#define PRG_RDB(addr) (*(PROGMEM char *)(addr)) + +/* The following definitions are not needed by the driver, but may be of some + * help if you port a gcc based project to IAR. + */ +#define cli() __disable_interrupt() +#define sei() __enable_interrupt() +#define wdt_reset() __watchdog_reset() + +/* Depending on the device you use, you may get problems with the way usbdrv.h + * handles the differences between devices. Since IAR does not use #defines + * for MCU registers, we can't check for the existence of a particular + * register with an #ifdef. If the autodetection mechanism fails, include + * definitions for the required USB_INTR_* macros in your usbconfig.h. See + * usbconfig-prototype.h and usbdrv.h for details. + */ + +#endif /* defined __IAR_SYSTEMS_ICC__ || defined __IAR_SYSTEMS_ASM__ */ +#endif /* __iarcompat_h_INCLUDED__ */ diff --git a/firmware/usbdrv/oddebug.c b/firmware/usbdrv/oddebug.c new file mode 100644 index 0000000..261fe6a --- /dev/null +++ b/firmware/usbdrv/oddebug.c @@ -0,0 +1,53 @@ +/* Name: oddebug.c + * Project: AVR library + * Author: Christian Starkjohann + * Creation Date: 2005-01-16 + * Tabsize: 4 + * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH + * License: Proprietary, free under certain conditions. See Documentation. + * This Revision: $Id: oddebug.c,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + */ + +#include "oddebug.h" + +#if DEBUG_LEVEL > 0 + +static uchar Warning__Never_compile_production_devices_with_debugging; +/* The "#warning" preprocessor directive is non-standard. The unused static + * variable above should give a compiler warning on all compilers. + */ + +static void uartPutc(char c) +{ + while(!(ODDBG_USR & (1 << ODDBG_UDRE))); /* wait for data register empty */ + ODDBG_UDR = c; +} + +static uchar hexAscii(uchar h) +{ + h &= 0xf; + if(h >= 10) + h += 'a' - (uchar)10 - '0'; + h += '0'; + return h; +} + +static void printHex(uchar c) +{ + uartPutc(hexAscii(c >> 4)); + uartPutc(hexAscii(c)); +} + +void odDebug(uchar prefix, uchar *data, uchar len) +{ + printHex(prefix); + uartPutc(':'); + while(len--){ + uartPutc(' '); + printHex(*data++); + } + uartPutc('\r'); + uartPutc('\n'); +} + +#endif diff --git a/firmware/usbdrv/oddebug.h b/firmware/usbdrv/oddebug.h new file mode 100644 index 0000000..3d29579 --- /dev/null +++ b/firmware/usbdrv/oddebug.h @@ -0,0 +1,126 @@ +/* Name: oddebug.h + * Project: AVR library + * Author: Christian Starkjohann + * Creation Date: 2005-01-16 + * Tabsize: 4 + * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH + * License: Proprietary, free under certain conditions. See Documentation. + * This Revision: $Id: oddebug.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + */ + +#ifndef __oddebug_h_included__ +#define __oddebug_h_included__ + +/* +General Description: +This module implements a function for debug logs on the serial line of the +AVR microcontroller. Debugging can be configured with the define +'DEBUG_LEVEL'. If this macro is not defined or defined to 0, all debugging +calls are no-ops. If it is 1, DBG1 logs will appear, but not DBG2. If it is +2, DBG1 and DBG2 logs will be printed. + +A debug log consists of a label ('prefix') to indicate which debug log created +the output and a memory block to dump in hex ('data' and 'len'). +*/ + + +#ifndef F_CPU +# define F_CPU 12000000 /* 12 MHz */ +#endif + +/* make sure we have the UART defines: */ +#include "iarcompat.h" +#ifndef __IAR_SYSTEMS_ICC__ +# include +#endif + +#ifndef uchar +# define uchar unsigned char +#endif + +#if DEBUG_LEVEL > 0 && !(defined TXEN || defined TXEN0) /* no UART in device */ +# warning "Debugging disabled because device has no UART" +# undef DEBUG_LEVEL +#endif + +#ifndef DEBUG_LEVEL +# define DEBUG_LEVEL 0 +#endif + +/* ------------------------------------------------------------------------- */ + +#if DEBUG_LEVEL > 0 +# define DBG1(prefix, data, len) odDebug(prefix, data, len) +#else +# define DBG1(prefix, data, len) +#endif + +#if DEBUG_LEVEL > 1 +# define DBG2(prefix, data, len) odDebug(prefix, data, len) +#else +# define DBG2(prefix, data, len) +#endif + +/* ------------------------------------------------------------------------- */ + +#if DEBUG_LEVEL > 0 +extern void odDebug(uchar prefix, uchar *data, uchar len); + +/* Try to find our control registers; ATMEL likes to rename these */ + +#if defined UBRR +# define ODDBG_UBRR UBRR +#elif defined UBRRL +# define ODDBG_UBRR UBRRL +#elif defined UBRR0 +# define ODDBG_UBRR UBRR0 +#elif defined UBRR0L +# define ODDBG_UBRR UBRR0L +#endif + +#if defined UCR +# define ODDBG_UCR UCR +#elif defined UCSRB +# define ODDBG_UCR UCSRB +#elif defined UCSR0B +# define ODDBG_UCR UCSR0B +#endif + +#if defined TXEN +# define ODDBG_TXEN TXEN +#else +# define ODDBG_TXEN TXEN0 +#endif + +#if defined USR +# define ODDBG_USR USR +#elif defined UCSRA +# define ODDBG_USR UCSRA +#elif defined UCSR0A +# define ODDBG_USR UCSR0A +#endif + +#if defined UDRE +# define ODDBG_UDRE UDRE +#else +# define ODDBG_UDRE UDRE0 +#endif + +#if defined UDR +# define ODDBG_UDR UDR +#elif defined UDR0 +# define ODDBG_UDR UDR0 +#endif + +static inline void odDebugInit(void) +{ + ODDBG_UCR |= (1< +# include +#endif +#include "usbdrv.h" +#include "oddebug.h" + +/* +General Description: +This module implements the C-part of the USB driver. See usbdrv.h for a +documentation of the entire driver. +*/ + +#ifndef IAR_SECTION +#define IAR_SECTION(arg) +#define __no_init +#endif +/* The macro IAR_SECTION is a hack to allow IAR-cc compatibility. On gcc, it + * is defined to nothing. __no_init is required on IAR. + */ + +/* ------------------------------------------------------------------------- */ + +/* raw USB registers / interface to assembler code: */ +/* usbRxBuf MUST be in 1 byte addressable range (because usbInputBuf is only 1 byte) */ +__no_init uchar usbRxBuf[2][USB_BUFSIZE] __attribute__ ((section (USB_BUFFER_SECTION))) IAR_SECTION(USB_BUFFER_SECTION);/* raw RX buffer: PID, 8 bytes data, 2 bytes CRC */ +uchar usbDeviceAddr; /* assigned during enumeration, defaults to 0 */ +uchar usbNewDeviceAddr; /* device ID which should be set after status phase */ +uchar usbConfiguration; /* currently selected configuration. Administered by driver, but not used */ +uchar usbInputBuf; /* ptr to raw buffer used for receiving */ +uchar usbAppBuf; /* ptr to raw buffer passed to app for processing */ +volatile schar usbRxLen; /* = 0; number of bytes in usbAppBuf; 0 means free */ +uchar usbCurrentTok; /* last token received, if more than 1 rx endpoint: MSb=endpoint */ +uchar usbRxToken; /* token for data we received; if more than 1 rx endpoint: MSb=endpoint */ +uchar usbMsgLen = 0xff; /* remaining number of bytes, no msg to send if -1 (see usbMsgPtr) */ +volatile uchar usbTxLen = USBPID_NAK; /* number of bytes to transmit with next IN token or handshake token */ +uchar usbTxBuf[USB_BUFSIZE];/* data to transmit with next IN, free if usbTxLen contains handshake token */ +#if USB_CFG_HAVE_INTRIN_ENDPOINT +volatile uchar usbTxLen1 = USBPID_NAK; /* TX count for endpoint 1 */ +uchar usbTxBuf1[USB_BUFSIZE]; /* TX data for endpoint 1 */ +#if USB_CFG_HAVE_INTRIN_ENDPOINT3 +volatile uchar usbTxLen3 = USBPID_NAK; /* TX count for endpoint 1 */ +uchar usbTxBuf3[USB_BUFSIZE]; /* TX data for endpoint 1 */ +#endif +#endif + +/* USB status registers / not shared with asm code */ +uchar *usbMsgPtr; /* data to transmit next -- ROM or RAM address */ +static uchar usbMsgFlags; /* flag values see below */ +static uchar usbIsReset; /* = 0; USB bus is in reset phase */ + +#define USB_FLG_TX_PACKET (1<<0) +/* Leave free 6 bits after TX_PACKET. This way we can increment usbMsgFlags to toggle TX_PACKET */ +#define USB_FLG_MSGPTR_IS_ROM (1<<6) +#define USB_FLG_USE_DEFAULT_RW (1<<7) + +/* +optimizing hints: +- do not post/pre inc/dec integer values in operations +- assign value of PRG_RDB() to register variables and don't use side effects in arg +- use narrow scope for variables which should be in X/Y/Z register +- assign char sized expressions to variables to force 8 bit arithmetics +*/ + +/* ------------------------------------------------------------------------- */ + +#if USB_CFG_DESCR_PROPS_STRINGS == 0 + +#if USB_CFG_DESCR_PROPS_STRING_0 == 0 +#undef USB_CFG_DESCR_PROPS_STRING_0 +#define USB_CFG_DESCR_PROPS_STRING_0 sizeof(usbDescriptorString0) +PROGMEM char usbDescriptorString0[] = { /* language descriptor */ + 4, /* sizeof(usbDescriptorString0): length of descriptor in bytes */ + 3, /* descriptor type */ + 0x09, 0x04, /* language index (0x0409 = US-English) */ +}; +#endif + +#if USB_CFG_DESCR_PROPS_STRING_VENDOR == 0 && USB_CFG_VENDOR_NAME_LEN +#undef USB_CFG_DESCR_PROPS_STRING_VENDOR +#define USB_CFG_DESCR_PROPS_STRING_VENDOR sizeof(usbDescriptorStringVendor) +PROGMEM int usbDescriptorStringVendor[] = { + USB_STRING_DESCRIPTOR_HEADER(USB_CFG_VENDOR_NAME_LEN), + USB_CFG_VENDOR_NAME +}; +#endif + +#if USB_CFG_DESCR_PROPS_STRING_DEVICE == 0 && USB_CFG_DEVICE_NAME_LEN +#undef USB_CFG_DESCR_PROPS_STRING_DEVICE +#define USB_CFG_DESCR_PROPS_STRING_DEVICE sizeof(usbDescriptorStringDevice) +PROGMEM int usbDescriptorStringDevice[] = { + USB_STRING_DESCRIPTOR_HEADER(USB_CFG_DEVICE_NAME_LEN), + USB_CFG_DEVICE_NAME +}; +#endif + +#if USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER == 0 && USB_CFG_SERIAL_NUMBER_LEN +#undef USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER +#define USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER sizeof(usbDescriptorStringSerialNumber) +PROGMEM int usbDescriptorStringSerialNumber[] = { + USB_STRING_DESCRIPTOR_HEADER(USB_CFG_SERIAL_NUMBER_LEN), + USB_CFG_SERIAL_NUMBER +}; +#endif + +#endif /* USB_CFG_DESCR_PROPS_STRINGS == 0 */ + +#if USB_CFG_DESCR_PROPS_DEVICE == 0 +#undef USB_CFG_DESCR_PROPS_DEVICE +#define USB_CFG_DESCR_PROPS_DEVICE sizeof(usbDescriptorDevice) +PROGMEM char usbDescriptorDevice[] = { /* USB device descriptor */ + 18, /* sizeof(usbDescriptorDevice): length of descriptor in bytes */ + USBDESCR_DEVICE, /* descriptor type */ + 0x01, 0x01, /* USB version supported */ + USB_CFG_DEVICE_CLASS, + USB_CFG_DEVICE_SUBCLASS, + 0, /* protocol */ + 8, /* max packet size */ + USB_CFG_VENDOR_ID, /* 2 bytes */ + USB_CFG_DEVICE_ID, /* 2 bytes */ + USB_CFG_DEVICE_VERSION, /* 2 bytes */ + USB_CFG_DESCR_PROPS_STRING_VENDOR != 0 ? 1 : 0, /* manufacturer string index */ + USB_CFG_DESCR_PROPS_STRING_DEVICE != 0 ? 2 : 0, /* product string index */ + USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER != 0 ? 3 : 0, /* serial number string index */ + 1, /* number of configurations */ +}; +#endif + +#if USB_CFG_DESCR_PROPS_HID_REPORT != 0 && USB_CFG_DESCR_PROPS_HID == 0 +#undef USB_CFG_DESCR_PROPS_HID +#define USB_CFG_DESCR_PROPS_HID 9 /* length of HID descriptor in config descriptor below */ +#endif + +#if USB_CFG_DESCR_PROPS_CONFIGURATION == 0 +#undef USB_CFG_DESCR_PROPS_CONFIGURATION +#define USB_CFG_DESCR_PROPS_CONFIGURATION sizeof(usbDescriptorConfiguration) +PROGMEM char usbDescriptorConfiguration[] = { /* USB configuration descriptor */ + 9, /* sizeof(usbDescriptorConfiguration): length of descriptor in bytes */ + USBDESCR_CONFIG, /* descriptor type */ + 18 + 7 * USB_CFG_HAVE_INTRIN_ENDPOINT + (USB_CFG_DESCR_PROPS_HID & 0xff), 0, + /* total length of data returned (including inlined descriptors) */ + 1, /* number of interfaces in this configuration */ + 1, /* index of this configuration */ + 0, /* configuration name string index */ +#if USB_CFG_IS_SELF_POWERED + USBATTR_SELFPOWER, /* attributes */ +#else + USBATTR_BUSPOWER, /* attributes */ +#endif + USB_CFG_MAX_BUS_POWER/2, /* max USB current in 2mA units */ +/* interface descriptor follows inline: */ + 9, /* sizeof(usbDescrInterface): length of descriptor in bytes */ + USBDESCR_INTERFACE, /* descriptor type */ + 0, /* index of this interface */ + 0, /* alternate setting for this interface */ + USB_CFG_HAVE_INTRIN_ENDPOINT, /* endpoints excl 0: number of endpoint descriptors to follow */ + USB_CFG_INTERFACE_CLASS, + USB_CFG_INTERFACE_SUBCLASS, + USB_CFG_INTERFACE_PROTOCOL, + 0, /* string index for interface */ +#if (USB_CFG_DESCR_PROPS_HID & 0xff) /* HID descriptor */ + 9, /* sizeof(usbDescrHID): length of descriptor in bytes */ + USBDESCR_HID, /* descriptor type: HID */ + 0x01, 0x01, /* BCD representation of HID version */ + 0x00, /* target country code */ + 0x01, /* number of HID Report (or other HID class) Descriptor infos to follow */ + 0x22, /* descriptor type: report */ + USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH, 0, /* total length of report descriptor */ +#endif +#if USB_CFG_HAVE_INTRIN_ENDPOINT /* endpoint descriptor for endpoint 1 */ + 7, /* sizeof(usbDescrEndpoint) */ + USBDESCR_ENDPOINT, /* descriptor type = endpoint */ + 0x81, /* IN endpoint number 1 */ + 0x03, /* attrib: Interrupt endpoint */ + 8, 0, /* maximum packet size */ + USB_CFG_INTR_POLL_INTERVAL, /* in ms */ +#endif +}; +#endif + +/* We don't use prog_int or prog_int16_t for compatibility with various libc + * versions. Here's an other compatibility hack: + */ +#ifndef PRG_RDB +#define PRG_RDB(addr) pgm_read_byte(addr) +#endif + +typedef union{ + unsigned word; + uchar *ptr; + uchar bytes[2]; +}converter_t; +/* We use this union to do type conversions. This is better optimized than + * type casts in gcc 3.4.3 and much better than using bit shifts to build + * ints from chars. Byte ordering is not a problem on an 8 bit platform. + */ + +/* ------------------------------------------------------------------------- */ + +#if USB_CFG_HAVE_INTRIN_ENDPOINT +uchar usbTxPacketCnt1; + +void usbSetInterrupt(uchar *data, uchar len) +{ +uchar *p, i; + +#if USB_CFG_IMPLEMENT_HALT + if(usbTxLen1 == USBPID_STALL) + return; +#endif +#if 0 /* No runtime checks! Caller is responsible for valid data! */ + if(len > 8) /* interrupt transfers are limited to 8 bytes */ + len = 8; +#endif + i = USBPID_DATA1; + if(usbTxPacketCnt1 & 1) + i = USBPID_DATA0; + if(usbTxLen1 & 0x10){ /* packet buffer was empty */ + usbTxPacketCnt1++; + }else{ + usbTxLen1 = USBPID_NAK; /* avoid sending incomplete interrupt data */ + } + p = usbTxBuf1; + *p++ = i; + for(i=len;i--;) + *p++ = *data++; + usbCrc16Append(&usbTxBuf1[1], len); + usbTxLen1 = len + 4; /* len must be given including sync byte */ + DBG2(0x21, usbTxBuf1, len + 3); +} +#endif + +#if USB_CFG_HAVE_INTRIN_ENDPOINT3 +uchar usbTxPacketCnt3; + +void usbSetInterrupt3(uchar *data, uchar len) +{ +uchar *p, i; + + i = USBPID_DATA1; + if(usbTxPacketCnt3 & 1) + i = USBPID_DATA0; + if(usbTxLen3 & 0x10){ /* packet buffer was empty */ + usbTxPacketCnt3++; + }else{ + usbTxLen3 = USBPID_NAK; /* avoid sending incomplete interrupt data */ + } + p = usbTxBuf3; + *p++ = i; + for(i=len;i--;) + *p++ = *data++; + usbCrc16Append(&usbTxBuf3[1], len); + usbTxLen3 = len + 4; /* len must be given including sync byte */ + DBG2(0x23, usbTxBuf3, len + 3); +} +#endif + + +static uchar usbRead(uchar *data, uchar len) +{ +#if USB_CFG_IMPLEMENT_FN_READ + if(usbMsgFlags & USB_FLG_USE_DEFAULT_RW){ +#endif + uchar i = len, *r = usbMsgPtr; + if(usbMsgFlags & USB_FLG_MSGPTR_IS_ROM){ /* ROM data */ + while(i--){ + uchar c = PRG_RDB(r); /* assign to char size variable to enforce byte ops */ + *data++ = c; + r++; + } + }else{ /* RAM data */ + while(i--) + *data++ = *r++; + } + usbMsgPtr = r; + return len; +#if USB_CFG_IMPLEMENT_FN_READ + }else{ + if(len != 0) /* don't bother app with 0 sized reads */ + return usbFunctionRead(data, len); + return 0; + } +#endif +} + + +#define GET_DESCRIPTOR(cfgProp, staticName) \ + if(cfgProp){ \ + if((cfgProp) & USB_PROP_IS_RAM) \ + flags &= ~USB_FLG_MSGPTR_IS_ROM; \ + if((cfgProp) & USB_PROP_IS_DYNAMIC){ \ + replyLen = usbFunctionDescriptor(rq); \ + }else{ \ + replyData = (uchar *)(staticName); \ + SET_REPLY_LEN((cfgProp) & 0xff); \ + } \ + } +/* We use if() instead of #if in the macro above because #if can't be used + * in macros and the compiler optimizes constant conditions anyway. + */ + + +/* Don't make this function static to avoid inlining. + * The entire function would become too large and exceed the range of + * relative jumps. + * 2006-02-25: Either gcc 3.4.3 is better than the gcc used when the comment + * above was written, or other parts of the code have changed. We now get + * better results with an inlined function. Test condition: PowerSwitch code. + */ +static void usbProcessRx(uchar *data, uchar len) +{ +usbRequest_t *rq = (void *)data; +uchar replyLen = 0, flags = USB_FLG_USE_DEFAULT_RW; +/* We use if() cascades because the compare is done byte-wise while switch() + * is int-based. The if() cascades are therefore more efficient. + */ + DBG2(0x10 + ((usbRxToken >> 6) & 3), data, len); +#if USB_CFG_IMPLEMENT_FN_WRITEOUT + if(usbRxToken & 0x80){ + usbFunctionWriteOut(data, len); + return; /* no reply expected, hence no usbMsgPtr, usbMsgFlags, usbMsgLen set */ + } + if(usbRxToken == (uchar)(USBPID_SETUP & 0x7f)){ /* MSb contains endpoint (== 0) */ +#else + if(usbRxToken == (uchar)USBPID_SETUP){ +#endif + if(len == 8){ /* Setup size must be always 8 bytes. Ignore otherwise. */ + uchar type = rq->bmRequestType & USBRQ_TYPE_MASK; + if(type == USBRQ_TYPE_STANDARD){ + #define SET_REPLY_LEN(len) replyLen = (len); usbMsgPtr = replyData + /* This macro ensures that replyLen and usbMsgPtr are always set in the same way. + * That allows optimization of common code in if() branches */ + uchar *replyData = usbTxBuf + 9; /* there is 3 bytes free space at the end of the buffer */ + replyData[0] = 0; /* common to USBRQ_GET_STATUS and USBRQ_GET_INTERFACE */ + if(rq->bRequest == USBRQ_GET_STATUS){ /* 0 */ + uchar __attribute__((__unused__)) recipient = rq->bmRequestType & USBRQ_RCPT_MASK; /* assign arith ops to variables to enforce byte size */ +#if USB_CFG_IS_SELF_POWERED + if(recipient == USBRQ_RCPT_DEVICE) + replyData[0] = USB_CFG_IS_SELF_POWERED; +#endif +#if USB_CFG_HAVE_INTRIN_ENDPOINT && USB_CFG_IMPLEMENT_HALT + if(recipient == USBRQ_RCPT_ENDPOINT && rq->wIndex.bytes[0] == 0x81) /* request status for endpoint 1 */ + replyData[0] = usbTxLen1 == USBPID_STALL; +#endif + replyData[1] = 0; + SET_REPLY_LEN(2); + }else if(rq->bRequest == USBRQ_SET_ADDRESS){ /* 5 */ + usbNewDeviceAddr = rq->wValue.bytes[0]; + }else if(rq->bRequest == USBRQ_GET_DESCRIPTOR){ /* 6 */ + flags = USB_FLG_MSGPTR_IS_ROM | USB_FLG_USE_DEFAULT_RW; + if(rq->wValue.bytes[1] == USBDESCR_DEVICE){ /* 1 */ + GET_DESCRIPTOR(USB_CFG_DESCR_PROPS_DEVICE, usbDescriptorDevice) + }else if(rq->wValue.bytes[1] == USBDESCR_CONFIG){ /* 2 */ + GET_DESCRIPTOR(USB_CFG_DESCR_PROPS_CONFIGURATION, usbDescriptorConfiguration) + }else if(rq->wValue.bytes[1] == USBDESCR_STRING){ /* 3 */ +#if USB_CFG_DESCR_PROPS_STRINGS & USB_PROP_IS_DYNAMIC + if(USB_CFG_DESCR_PROPS_STRINGS & USB_PROP_IS_RAM) + flags &= ~USB_FLG_MSGPTR_IS_ROM; + replyLen = usbFunctionDescriptor(rq); +#else /* USB_CFG_DESCR_PROPS_STRINGS & USB_PROP_IS_DYNAMIC */ + if(rq->wValue.bytes[0] == 0){ /* descriptor index */ + GET_DESCRIPTOR(USB_CFG_DESCR_PROPS_STRING_0, usbDescriptorString0) + }else if(rq->wValue.bytes[0] == 1){ + GET_DESCRIPTOR(USB_CFG_DESCR_PROPS_STRING_VENDOR, usbDescriptorStringVendor) + }else if(rq->wValue.bytes[0] == 2){ + GET_DESCRIPTOR(USB_CFG_DESCR_PROPS_STRING_DEVICE, usbDescriptorStringDevice) + }else if(rq->wValue.bytes[0] == 3){ + GET_DESCRIPTOR(USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER, usbDescriptorStringSerialNumber) + }else if(USB_CFG_DESCR_PROPS_UNKNOWN & USB_PROP_IS_DYNAMIC){ + replyLen = usbFunctionDescriptor(rq); + } +#endif /* USB_CFG_DESCR_PROPS_STRINGS & USB_PROP_IS_DYNAMIC */ + }else if(rq->wValue.bytes[1] == USBDESCR_HID){ /* 0x21 */ + GET_DESCRIPTOR(USB_CFG_DESCR_PROPS_HID, usbDescriptorConfiguration + 18) + }else if(rq->wValue.bytes[1] == USBDESCR_HID_REPORT){ /* 0x22 */ + GET_DESCRIPTOR(USB_CFG_DESCR_PROPS_HID_REPORT, usbDescriptorHidReport) + }else if(USB_CFG_DESCR_PROPS_UNKNOWN & USB_PROP_IS_DYNAMIC){ + replyLen = usbFunctionDescriptor(rq); + } + }else if(rq->bRequest == USBRQ_GET_CONFIGURATION){ /* 8 */ + replyData = &usbConfiguration; /* send current configuration value */ + SET_REPLY_LEN(1); + }else if(rq->bRequest == USBRQ_SET_CONFIGURATION){ /* 9 */ + usbConfiguration = rq->wValue.bytes[0]; +#if USB_CFG_IMPLEMENT_HALT + usbTxLen1 = USBPID_NAK; +#endif + }else if(rq->bRequest == USBRQ_GET_INTERFACE){ /* 10 */ + SET_REPLY_LEN(1); +#if USB_CFG_HAVE_INTRIN_ENDPOINT + }else if(rq->bRequest == USBRQ_SET_INTERFACE){ /* 11 */ + usbTxPacketCnt1 = 0; /* reset data toggling for interrupt endpoint */ +# if USB_CFG_HAVE_INTRIN_ENDPOINT3 + usbTxPacketCnt3 = 0; /* reset data toggling for interrupt endpoint */ +# endif +# if USB_CFG_IMPLEMENT_HALT + usbTxLen1 = USBPID_NAK; + }else if(rq->bRequest == USBRQ_CLEAR_FEATURE || rq->bRequest == USBRQ_SET_FEATURE){ /* 1|3 */ + if(rq->wValue.bytes[0] == 0 && rq->wIndex.bytes[0] == 0x81){ /* feature 0 == HALT for endpoint == 1 */ + usbTxLen1 = rq->bRequest == USBRQ_CLEAR_FEATURE ? USBPID_NAK : USBPID_STALL; + usbTxPacketCnt1 = 0; /* reset data toggling for interrupt endpoint */ +# if USB_CFG_HAVE_INTRIN_ENDPOINT3 + usbTxPacketCnt3 = 0; /* reset data toggling for interrupt endpoint */ +# endif + } +# endif +#endif + }else{ + /* the following requests can be ignored, send default reply */ + /* 1: CLEAR_FEATURE, 3: SET_FEATURE, 7: SET_DESCRIPTOR */ + /* 12: SYNCH_FRAME */ + } + #undef SET_REPLY_LEN + }else{ /* not a standard request -- must be vendor or class request */ + replyLen = usbFunctionSetup(data); + } +#if USB_CFG_IMPLEMENT_FN_READ || USB_CFG_IMPLEMENT_FN_WRITE + if(replyLen == 0xff){ /* use user-supplied read/write function */ + if((rq->bmRequestType & USBRQ_DIR_MASK) == USBRQ_DIR_DEVICE_TO_HOST){ + replyLen = rq->wLength.bytes[0]; /* IN transfers only */ + } + flags &= ~USB_FLG_USE_DEFAULT_RW; /* we have no valid msg, use user supplied read/write functions */ + }else /* The 'else' prevents that we limit a replyLen of 0xff to the maximum transfer len. */ +#endif + if(!rq->wLength.bytes[1] && replyLen > rq->wLength.bytes[0]) /* limit length to max */ + replyLen = rq->wLength.bytes[0]; + } + /* make sure that data packets which are sent as ACK to an OUT transfer are always zero sized */ + }else{ /* DATA packet from out request */ +#if USB_CFG_IMPLEMENT_FN_WRITE + if(!(usbMsgFlags & USB_FLG_USE_DEFAULT_RW)){ + uchar rval = usbFunctionWrite(data, len); + replyLen = 0xff; + if(rval == 0xff){ /* an error occurred */ + usbMsgLen = 0xff; /* cancel potentially pending data packet for ACK */ + usbTxLen = USBPID_STALL; + }else if(rval != 0){ /* This was the final package */ + replyLen = 0; /* answer with a zero-sized data packet */ + } + flags = 0; /* start with a DATA1 package, stay with user supplied write() function */ + } +#endif + } + usbMsgFlags = flags; + usbMsgLen = replyLen; +} + +/* ------------------------------------------------------------------------- */ + +static void usbBuildTxBlock(void) +{ +uchar wantLen, len, txLen, token; + + wantLen = usbMsgLen; + if(wantLen > 8) + wantLen = 8; + usbMsgLen -= wantLen; + token = USBPID_DATA1; + if(usbMsgFlags & USB_FLG_TX_PACKET) + token = USBPID_DATA0; + usbMsgFlags++; + len = usbRead(usbTxBuf + 1, wantLen); + if(len <= 8){ /* valid data packet */ + usbCrc16Append(&usbTxBuf[1], len); + txLen = len + 4; /* length including sync byte */ + if(len < 8) /* a partial package identifies end of message */ + usbMsgLen = 0xff; + }else{ + txLen = USBPID_STALL; /* stall the endpoint */ + usbMsgLen = 0xff; + } + usbTxBuf[0] = token; + usbTxLen = txLen; + DBG2(0x20, usbTxBuf, txLen-1); +} + +static inline uchar isNotSE0(void) +{ +uchar rval; +/* We want to do + * return (USBIN & USBMASK); + * here, but the compiler does int-expansion acrobatics. + * We can avoid this by assigning to a char-sized variable. + */ + rval = USBIN & USBMASK; + return rval; +} + +/* ------------------------------------------------------------------------- */ + +void usbPoll(void) +{ +uchar len; + + if((len = usbRxLen) > 0){ +/* We could check CRC16 here -- but ACK has already been sent anyway. If you + * need data integrity checks with this driver, check the CRC in your app + * code and report errors back to the host. Since the ACK was already sent, + * retries must be handled on application level. + * unsigned crc = usbCrc16((uchar *)(unsigned)(usbAppBuf + 1), usbRxLen - 3); + */ + len -= 3; /* remove PID and CRC */ + if(len < 128){ /* no overflow */ + converter_t appBuf; + appBuf.ptr = (uchar *)usbRxBuf; + appBuf.bytes[0] = usbAppBuf; + appBuf.bytes[0]++; + usbProcessRx(appBuf.ptr, len); + } +#if USB_CFG_HAVE_FLOWCONTROL + if(usbRxLen > 0) /* only mark as available if not inactivated */ + usbRxLen = 0; +#else + usbRxLen = 0; /* mark rx buffer as available */ +#endif + } + if(usbMsgLen != 0xff){ /* transmit data pending? */ + if(usbTxLen & 0x10) /* transmit system idle */ + usbBuildTxBlock(); + } + if(isNotSE0()){ /* SE0 state */ + usbIsReset = 0; + }else{ + /* check whether SE0 lasts for more than 2.5us (3.75 bit times) */ + if(!usbIsReset){ + uchar i; + for(i=100;i;i--){ + if(isNotSE0()) + goto notUsbReset; + } + usbIsReset = 1; + usbNewDeviceAddr = 0; + usbDeviceAddr = 0; +#if USB_CFG_IMPLEMENT_HALT + usbTxLen1 = USBPID_NAK; +#if USB_CFG_HAVE_INTRIN_ENDPOINT3 + usbTxLen3 = USBPID_NAK; +#endif +#endif + DBG1(0xff, 0, 0); +notUsbReset:; + } + } +} + +/* ------------------------------------------------------------------------- */ + +void usbInit(void) +{ + usbInputBuf = (uchar)usbRxBuf[0]; + usbAppBuf = (uchar)usbRxBuf[1]; +#if USB_INTR_CFG_SET != 0 + USB_INTR_CFG |= USB_INTR_CFG_SET; +#endif +#if USB_INTR_CFG_CLR != 0 + USB_INTR_CFG &= ~(USB_INTR_CFG_CLR); +#endif + USB_INTR_ENABLE |= (1 << USB_INTR_ENABLE_BIT); +} + +/* ------------------------------------------------------------------------- */ diff --git a/firmware/usbdrv/usbdrv.h b/firmware/usbdrv/usbdrv.h new file mode 100644 index 0000000..aaaf199 --- /dev/null +++ b/firmware/usbdrv/usbdrv.h @@ -0,0 +1,657 @@ +/* Name: usbdrv.h + * Project: AVR USB driver + * Author: Christian Starkjohann + * Creation Date: 2004-12-29 + * Tabsize: 4 + * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH + * License: Proprietary, free under certain conditions. See Documentation. + * This Revision: $Id: usbdrv.h,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + */ + +#ifndef __usbdrv_h_included__ +#define __usbdrv_h_included__ +#include "usbconfig.h" +#include "iarcompat.h" + +/* +Hardware Prerequisites: +======================= +USB lines D+ and D- MUST be wired to the same I/O port. D+ must (also) be +connected to INT0. D- requires a pullup of 1.5k to +3.5V (and the device +must be powered at 3.5V) to identify as low-speed USB device. A pullup of +1M SHOULD be connected from D+ to +3.5V to prevent interference when no USB +master is connected. We use D+ as interrupt source and not D- because it +does not trigger on keep-alive and RESET states. + +As a compile time option, the 1.5k pullup resistor on D- can be made +switchable to allow the device to disconnect at will. See the definition of +usbDeviceConnect() and usbDeviceDisconnect() further down in this file. + +Please adapt the values in usbconfig.h according to your hardware! + +The device MUST be clocked at 12 MHz. This is more than the 10 MHz allowed by +an AT90S2313 powered at 4.5V. However, if the supply voltage to maximum clock +relation is interpolated linearly, an ATtiny2313 meets the requirement by +specification. In practice, the AT90S2313 can be overclocked and works well. + + +Limitations: +============ +Compiling: +You should link the usbdrv.o module first because it has special alignment +requirements for the receive buffer (the buffer must not cross a 256 byte +page boundary, it must not even touch it at the end). If you can't link it +first, you must use other measures to ensure alignment. +Note: gcc does not always assign variable addresses in the order as the modules +are linked or the variables are declared. You can choose a memory section for +the receive buffer with the configuration option "USB_BUFFER_SECTION". This +option defaults to ".bss". If you use your own section, you can place it at +an arbitrary location with a linker option similar to +"-Wl,--section-start=.mybuffer=0x800060". Use "avr-nm -ng" on the binary and +search for "usbRxBuf" to find tbe base address of the 22 bytes rx buffer. + +Robustness with respect to communication errors: +The driver assumes error-free communication. It DOES check for errors in +the PID, but does NOT check bit stuffing errors, SE0 in middle of a byte, +token CRC (5 bit) and data CRC (16 bit). CRC checks can not be performed due +to timing constraints: We must start sending a reply within 7 bit times. +Bit stuffing and misplaced SE0 would have to be checked in real-time, but CPU +performance does not permit that. The driver does not check Data0/Data1 +toggling, but application software can implement the check. + +Sampling jitter: +The driver guarantees a sampling window of 1/2 bit. The USB spec requires +that the receiver has at most 1/4 bit sampling window. The 1/2 bit window +should still work reliably enough because we work at low speed. If you want +to meet the spec, define the macro "USB_CFG_SAMPLE_EXACT" to 1 in usbconfig.h. +This will unroll a loop which results in bigger code size. + +Input characteristics: +Since no differential receiver circuit is used, electrical interference +robustness may suffer. The driver samples only one of the data lines with +an ordinary I/O pin's input characteristics. However, since this is only a +low speed USB implementation and the specification allows for 8 times the +bit rate over the same hardware, we should be on the safe side. Even the spec +requires detection of asymmetric states at high bit rate for SE0 detection. + +Number of endpoints: +The driver supports up to four endpoints: One control endpoint (endpoint 0), +two interrupt-in (or bulk-in) endpoints (endpoint 1 and 3) and one +interrupt-out (or bulk-out) endpoint (endpoint 1). Please note that the USB +standard forbids bulk endpoints for low speed devices! Most operating systems +allow them anyway, but the AVR will spend 90% of the CPU time in the USB +interrupt polling for bulk data. +By default, only the control endpoint 0 is enabled. To get the other endpoints, +define USB_CFG_HAVE_INTRIN_ENDPOINT, USB_CFG_HAVE_INTRIN_ENDPOINT3 and/or +USB_CFG_IMPLEMENT_FN_WRITEOUT respectively (see usbconfig-prototype.h for +details). + +Maximum data payload: +Data payload of control in and out transfers may be up to 254 bytes. In order +to accept payload data of out transfers, you need to implement +'usbFunctionWrite()'. + +USB Suspend Mode supply current: +The USB standard limits power consumption to 500uA when the bus is in suspend +mode. This is not a problem for self-powered devices since they don't need +bus power anyway. Bus-powered devices can achieve this only by putting the +CPU in sleep mode. The driver does not implement suspend handling by itself. +However, the application may implement activity monitoring and wakeup from +sleep. The host sends regular SE0 states on the bus to keep it active. These +SE0 states can be detected by wiring the INT1 pin to D-. It is not necessary +to enable the interrupt, checking the interrupt pending flag should suffice. +Before entering sleep mode, the application should enable INT1 for a wakeup +on the next bus activity. + +Operation without an USB master: +The driver behaves neutral without connection to an USB master if D- reads +as 1. To avoid spurious interrupts, we recommend a high impedance (e.g. 1M) +pullup resistor on D+. If D- becomes statically 0, the driver may block in +the interrupt routine. + +Interrupt latency: +The application must ensure that the USB interrupt is not disabled for more +than 20 cycles. This implies that all interrupt routines must either be +declared as "INTERRUPT" instead of "SIGNAL" (see "avr/signal.h") or that they +are written in assembler with "sei" as the first instruction. + +Maximum interrupt duration / CPU cycle consumption: +The driver handles all USB communication during the interrupt service +routine. The routine will not return before an entire USB message is received +and the reply is sent. This may be up to ca. 1200 cycles = 100us if the host +conforms to the standard. The driver will consume CPU cycles for all USB +messages, even if they address another (low-speed) device on the same bus. + +*/ + +/* ------------------------------------------------------------------------- */ +/* --------------------------- Module Interface ---------------------------- */ +/* ------------------------------------------------------------------------- */ + +#define USBDRV_VERSION 20060718 +/* This define uniquely identifies a driver version. It is a decimal number + * constructed from the driver's release date in the form YYYYMMDD. If the + * driver's behavior or interface changes, you can use this constant to + * distinguish versions. If it is not defined, the driver's release date is + * older than 2006-01-25. + */ + +#ifndef __ASSEMBLER__ + +#ifndef uchar +#define uchar unsigned char +#endif +#ifndef schar +#define schar signed char +#endif +/* shortcuts for well defined 8 bit integer types */ + +struct usbRequest; /* forward declaration */ + +extern void usbInit(void); +/* This function must be called before interrupts are enabled and the main + * loop is entered. + */ +extern void usbPoll(void); +/* This function must be called at regular intervals from the main loop. + * Maximum delay between calls is somewhat less than 50ms (USB timeout for + * accepting a Setup message). Otherwise the device will not be recognized. + * Please note that debug outputs through the UART take ~ 0.5ms per byte + * at 19200 bps. + */ +extern uchar *usbMsgPtr; +/* This variable may be used to pass transmit data to the driver from the + * implementation of usbFunctionWrite(). It is also used internally by the + * driver for standard control requests. + */ +extern uchar usbFunctionSetup(uchar data[8]); +/* This function is called when the driver receives a SETUP transaction from + * the host which is not answered by the driver itself (in practice: class and + * vendor requests). All control transfers start with a SETUP transaction where + * the host communicates the parameters of the following (optional) data + * transfer. The SETUP data is available in the 'data' parameter which can + * (and should) be casted to 'usbRequest_t *' for a more user-friendly access + * to parameters. + * + * If the SETUP indicates a control-in transfer, you should provide the + * requested data to the driver. There are two ways to transfer this data: + * (1) Set the global pointer 'usbMsgPtr' to the base of the static RAM data + * block and return the length of the data in 'usbFunctionSetup()'. The driver + * will handle the rest. Or (2) return 0xff in 'usbFunctionSetup()'. The driver + * will then call 'usbFunctionRead()' when data is needed. See the + * documentation for usbFunctionRead() for details. + * + * If the SETUP indicates a control-out transfer, the only way to receive the + * data from the host is through the 'usbFunctionWrite()' call. If you + * implement this function, you must return 0xff in 'usbFunctionSetup()' to + * indicate that 'usbFunctionWrite()' should be used. See the documentation of + * this function for more information. If you just want to ignore the data sent + * by the host, return 0 in 'usbFunctionSetup()'. + * + * Note that calls to the functions usbFunctionRead() and usbFunctionWrite() + * are only done if enabled by the configuration in usbconfig.h. + */ +extern uchar usbFunctionDescriptor(struct usbRequest *rq); +/* You need to implement this function ONLY if you provide USB descriptors at + * runtime (which is an expert feature). It is very similar to + * usbFunctionSetup() above, but it is called only to request USB descriptor + * data. See the documentation of usbFunctionSetup() above for more info. + */ +#if USB_CFG_HAVE_INTRIN_ENDPOINT +void usbSetInterrupt(uchar *data, uchar len); +/* This function sets the message which will be sent during the next interrupt + * IN transfer. The message is copied to an internal buffer and must not exceed + * a length of 8 bytes. The message may be 0 bytes long just to indicate the + * interrupt status to the host. + * If you need to transfer more bytes, use a control read after the interrupt. + */ +extern volatile uchar usbTxLen1; +#define usbInterruptIsReady() (usbTxLen1 & 0x10) +/* This macro indicates whether the last interrupt message has already been + * sent. If you set a new interrupt message before the old was sent, the + * message already buffered will be lost. + */ +#if USB_CFG_HAVE_INTRIN_ENDPOINT3 +void usbSetInterrupt3(uchar *data, uchar len); +extern volatile uchar usbTxLen3; +#define usbInterruptIsReady3() (usbTxLen3 & 0x10) +/* Same as above for endpoint 3 */ +#endif +#endif /* USB_CFG_HAVE_INTRIN_ENDPOINT */ +#if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH /* simplified interface for backward compatibility */ +#define usbHidReportDescriptor usbDescriptorHidReport +/* should be declared as: PROGMEM char usbHidReportDescriptor[]; */ +/* If you implement an HID device, you need to provide a report descriptor. + * The HID report descriptor syntax is a bit complex. If you understand how + * report descriptors are constructed, we recommend that you use the HID + * Descriptor Tool from usb.org, see http://www.usb.org/developers/hidpage/. + * Otherwise you should probably start with a working example. + */ +#endif /* USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH */ +#if USB_CFG_IMPLEMENT_FN_WRITE +extern uchar usbFunctionWrite(uchar *data, uchar len); +/* This function is called by the driver to provide a control transfer's + * payload data (control-out). It is called in chunks of up to 8 bytes. The + * total count provided in the current control transfer can be obtained from + * the 'length' property in the setup data. If an error occurred during + * processing, return 0xff (== -1). The driver will answer the entire transfer + * with a STALL token in this case. If you have received the entire payload + * successfully, return 1. If you expect more data, return 0. If you don't + * know whether the host will send more data (you should know, the total is + * provided in the usbFunctionSetup() call!), return 1. + * NOTE: If you return 0xff for STALL, 'usbFunctionWrite()' may still be called + * for the remaining data. You must continue to return 0xff for STALL in these + * calls. + * In order to get usbFunctionWrite() called, define USB_CFG_IMPLEMENT_FN_WRITE + * to 1 in usbconfig.h and return 0xff in usbFunctionSetup().. + */ +#endif /* USB_CFG_IMPLEMENT_FN_WRITE */ +#if USB_CFG_IMPLEMENT_FN_READ +extern uchar usbFunctionRead(uchar *data, uchar len); +/* This function is called by the driver to ask the application for a control + * transfer's payload data (control-in). It is called in chunks of up to 8 + * bytes each. You should copy the data to the location given by 'data' and + * return the actual number of bytes copied. If you return less than requested, + * the control-in transfer is terminated. If you return 0xff, the driver aborts + * the transfer with a STALL token. + * In order to get usbFunctionRead() called, define USB_CFG_IMPLEMENT_FN_READ + * to 1 in usbconfig.h and return 0xff in usbFunctionSetup().. + */ +#endif /* USB_CFG_IMPLEMENT_FN_READ */ +#if USB_CFG_IMPLEMENT_FN_WRITEOUT +extern void usbFunctionWriteOut(uchar *data, uchar len); +/* This function is called by the driver when data on interrupt-out or bulk- + * out endpoint 1 is received. You must define USB_CFG_IMPLEMENT_FN_WRITEOUT + * to 1 in usbconfig.h to get this function called. + */ +#endif /* USB_CFG_IMPLEMENT_FN_WRITEOUT */ +#ifdef USB_CFG_PULLUP_IOPORTNAME +#define usbDeviceConnect() ((USB_PULLUP_DDR |= (1<device, 1=device->host + * t ..... type: 0=standard, 1=class, 2=vendor, 3=reserved + * r ..... recipient: 0=device, 1=interface, 2=endpoint, 3=other + */ + +/* USB setup recipient values */ +#define USBRQ_RCPT_MASK 0x1f +#define USBRQ_RCPT_DEVICE 0 +#define USBRQ_RCPT_INTERFACE 1 +#define USBRQ_RCPT_ENDPOINT 2 + +/* USB request type values */ +#define USBRQ_TYPE_MASK 0x60 +#define USBRQ_TYPE_STANDARD (0<<5) +#define USBRQ_TYPE_CLASS (1<<5) +#define USBRQ_TYPE_VENDOR (2<<5) + +/* USB direction values: */ +#define USBRQ_DIR_MASK 0x80 +#define USBRQ_DIR_HOST_TO_DEVICE (0<<7) +#define USBRQ_DIR_DEVICE_TO_HOST (1<<7) + +/* USB Standard Requests */ +#define USBRQ_GET_STATUS 0 +#define USBRQ_CLEAR_FEATURE 1 +#define USBRQ_SET_FEATURE 3 +#define USBRQ_SET_ADDRESS 5 +#define USBRQ_GET_DESCRIPTOR 6 +#define USBRQ_SET_DESCRIPTOR 7 +#define USBRQ_GET_CONFIGURATION 8 +#define USBRQ_SET_CONFIGURATION 9 +#define USBRQ_GET_INTERFACE 10 +#define USBRQ_SET_INTERFACE 11 +#define USBRQ_SYNCH_FRAME 12 + +/* USB descriptor constants */ +#define USBDESCR_DEVICE 1 +#define USBDESCR_CONFIG 2 +#define USBDESCR_STRING 3 +#define USBDESCR_INTERFACE 4 +#define USBDESCR_ENDPOINT 5 +#define USBDESCR_HID 0x21 +#define USBDESCR_HID_REPORT 0x22 +#define USBDESCR_HID_PHYS 0x23 + +#define USBATTR_BUSPOWER 0x80 +#define USBATTR_SELFPOWER 0x40 +#define USBATTR_REMOTEWAKE 0x20 + +/* USB HID Requests */ +#define USBRQ_HID_GET_REPORT 0x01 +#define USBRQ_HID_GET_IDLE 0x02 +#define USBRQ_HID_GET_PROTOCOL 0x03 +#define USBRQ_HID_SET_REPORT 0x09 +#define USBRQ_HID_SET_IDLE 0x0a +#define USBRQ_HID_SET_PROTOCOL 0x0b + +/* ------------------------------------------------------------------------- */ + +#endif /* __usbdrv_h_included__ */ diff --git a/firmware/usbdrv/usbdrvasm.S b/firmware/usbdrv/usbdrvasm.S new file mode 100644 index 0000000..2d2e67a --- /dev/null +++ b/firmware/usbdrv/usbdrvasm.S @@ -0,0 +1,784 @@ +/* Name: usbdrvasm.S + * Project: AVR USB driver + * Author: Christian Starkjohann + * Creation Date: 2004-12-29 + * Tabsize: 4 + * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH + * License: Proprietary, free under certain conditions. See Documentation. + * This Revision: $Id: usbdrvasm.S,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + */ + +/* +General Description: +This module implements the assembler part of the USB driver. See usbdrv.h +for a description of the entire driver. +Since almost all of this code is timing critical, don't change unless you +really know what you are doing! Many parts require not only a maximum number +of CPU cycles, but even an exact number of cycles! + + +Timing constraints according to spec (in bit times): +timing subject min max CPUcycles +--------------------------------------------------------------------------- +EOP of OUT/SETUP to sync pattern of DATA0 (both rx) 2 16 16-128 +EOP of IN to sync pattern of DATA0 (rx, then tx) 2 7.5 16-60 +DATAx (rx) to ACK/NAK/STALL (tx) 2 7.5 16-60 +*/ + +#include "iarcompat.h" +#ifndef __IAR_SYSTEMS_ASM__ + /* configs for io.h */ +# define __SFR_OFFSET 0 +# define _VECTOR(N) __vector_ ## N /* io.h does not define this for asm */ +# include /* for CPU I/O register definitions and vectors */ +#endif /* __IAR_SYSTEMS_ASM__ */ +#include "usbdrv.h" /* for common defs */ + + +/* register names */ +#define x1 r16 +#define x2 r17 +#define shift r18 +#define cnt r19 +#define x3 r20 +#define x4 r21 + +/* Some assembler dependent definitions and declarations: */ + +#ifdef __IAR_SYSTEMS_ASM__ + +# define nop2 rjmp $+2 /* jump to next instruction */ +# define XL r26 +# define XH r27 +# define YL r28 +# define YH r29 +# define ZL r30 +# define ZH r31 +# define lo8(x) LOW(x) +# define hi8(x) ((x)>>8) /* not HIGH to allow XLINK to make a proper range check */ + + extern usbRxBuf, usbDeviceAddr, usbNewDeviceAddr, usbInputBuf + extern usbCurrentTok, usbRxLen, usbRxToken, usbAppBuf, usbTxLen + extern usbTxBuf, usbMsgLen, usbTxLen1, usbTxBuf1, usbTxLen3, usbTxBuf3 + public usbCrc16 + public usbCrc16Append + + COMMON INTVEC + ORG INT0_vect + rjmp SIG_INTERRUPT0 + RSEG CODE + +#else /* __IAR_SYSTEMS_ASM__ */ + +# define nop2 rjmp .+0 /* jump to next instruction */ + + .text + .global SIG_INTERRUPT0 + .type SIG_INTERRUPT0, @function + .global usbCrc16 + .global usbCrc16Append + +#endif /* __IAR_SYSTEMS_ASM__ */ + + +SIG_INTERRUPT0: +;Software-receiver engine. Strict timing! Don't change unless you can preserve timing! +;interrupt response time: 4 cycles + insn running = 7 max if interrupts always enabled +;max allowable interrupt latency: 32 cycles -> max 25 cycles interrupt disable +;max stack usage: [ret(2), x1, SREG, x2, cnt, shift, YH, YL, x3, x4] = 11 bytes +usbInterrupt: +;order of registers pushed: +;x1, SREG, x2, cnt, shift, [YH, YL, x3] + push x1 ;2 push only what is necessary to sync with edge ASAP + in x1, SREG ;1 + push x1 ;2 +;sync byte (D-) pattern LSb to MSb: 01010100 [1 = idle = J, 0 = K] +;sync up with J to K edge during sync pattern -- use fastest possible loops +;first part has no timeout because it waits for IDLE or SE1 (== disconnected) +#if !USB_CFG_SAMPLE_EXACT + ldi x1, 5 ;1 setup a timeout for waitForK +#endif +waitForJ: + sbis USBIN, USBMINUS ;1 wait for D- == 1 + rjmp waitForJ ;2 +#if USB_CFG_SAMPLE_EXACT +;The following code represents the unrolled loop in the else branch. It +;results in a sampling window of 1/4 bit which meets the spec. + sbis USBIN, USBMINUS + rjmp foundK + sbis USBIN, USBMINUS + rjmp foundK + sbis USBIN, USBMINUS + rjmp foundK + nop + nop2 +foundK: +#else +waitForK: + dec x1 ;1 + sbic USBIN, USBMINUS ;1 wait for D- == 0 + brne waitForK ;2 +#endif +;{2, 6} after falling D- edge, average delay: 4 cycles [we want 4 for center sampling] +;we have 1 bit time for setup purposes, then sample again: + push x2 ;2 + push cnt ;2 + push shift ;2 +shortcutEntry: + ldi cnt, 1 ;1 pre-init bit counter (-1 because no dec follows, -1 because 1 bit already sampled) + ldi x2, 1< 8 edge sync ended with D- == 0 +;now wait until SYNC byte is over. Wait for either 2 bits low (success) or 2 bits high (failure) +waitNoChange: + in x1, USBIN ;1 <-- sample, timing: edge + {2, 6} cycles + eor x2, x1 ;1 + sbrc x2, USBMINUS ;1 | 2 + ldi cnt, 2 ;1 | 0 cnt = numBits - 1 (because dec follows) + mov x2, x1 ;1 + dec cnt ;1 + brne waitNoChange ;2 | 1 + sbrc x1, USBMINUS ;2 + rjmp sofError ;0 two consecutive "1" bits -> framing error +;start reading data, but don't check for bitstuffing because these are the +;first bits. Use the cycles for initialization instead. Note that we read and +;store the binary complement of the data stream because eor results in 1 for +;a change and 0 for no change. + in x1, USBIN ;1 <-- sample bit 0, timing: edge + {3, 7} cycles + eor x2, x1 ;1 + ldi shift, 0x00 ;1 prepare for bitstuff check later on in loop + bst x2, USBMINUS ;1 + bld shift, 0 ;1 + push YH ;2 -> 7 + in x2, USBIN ;1 <-- sample bit 1, timing: edge + {2, 6} cycles + eor x1, x2 ;1 + bst x1, USBMINUS ;1 + bld shift, 1 ;1 + push YL ;2 + lds YL, usbInputBuf ;2 -> 8 + in x1, USBIN ;1 <-- sample bit 2, timing: edge + {2, 6} cycles + eor x2, x1 ;1 + bst x2, USBMINUS ;1 + bld shift, 2 ;1 + ldi cnt, USB_BUFSIZE;1 + ldi YH, hi8(usbRxBuf);1 assume that usbRxBuf does not cross a page + push x3 ;2 -> 8 + in x2, USBIN ;1 <-- sample bit 3, timing: edge + {2, 6} cycles + eor x1, x2 ;1 + bst x1, USBMINUS ;1 + bld shift, 3 ;1 + ser x3 ;1 + nop ;1 + rjmp rxbit4 ;2 -> 8 + +shortcutToStart: ;{,43} into next frame: max 5.5 sync bits missed +#if !USB_CFG_SAMPLE_EXACT + ldi x1, 5 ;2 setup timeout +#endif +waitForJ1: + sbis USBIN, USBMINUS ;1 wait for D- == 1 + rjmp waitForJ1 ;2 +#if USB_CFG_SAMPLE_EXACT +;The following code represents the unrolled loop in the else branch. It +;results in a sampling window of 1/4 bit which meets the spec. + sbis USBIN, USBMINUS + rjmp foundK1 + sbis USBIN, USBMINUS + rjmp foundK1 + sbis USBIN, USBMINUS + rjmp foundK1 + nop + nop2 +foundK1: +#else +waitForK1: + dec x1 ;1 + sbic USBIN, USBMINUS ;1 wait for D- == 0 + brne waitForK1 ;2 +#endif + pop YH ;2 correct stack alignment + nop2 ;2 delay for the same time as the pushes in the original code + rjmp shortcutEntry ;2 + +; ################# receiver loop ################# +; extra jobs done during bit interval: +; bit 6: se0 check +; bit 7: or, store, clear +; bit 0: recover from delay [SE0 is unreliable here due to bit dribbling in hubs] +; bit 1: se0 check +; bit 2: se0 check +; bit 3: overflow check +; bit 4: se0 check +; bit 5: rjmp + +; stuffed* helpers have the functionality of a subroutine, but we can't afford +; the overhead of a call. We therefore need a separate routine for each caller +; which jumps back appropriately. + +stuffed5: ;1 for branch taken + in x2, USBIN ;1 <-- sample @ +1 + andi x2, USBMASK ;1 + breq se0a ;1 + andi x3, ~0x20 ;1 + ori shift, 0x20 ;1 + rjmp rxbit6 ;2 + +stuffed6: ;1 for branch taken + in x1, USBIN ;1 <-- sample @ +1 + andi x1, USBMASK ;1 + breq se0a ;1 + andi x3, ~0x40 ;1 + ori shift, 0x40 ;1 + rjmp rxbit7 ;2 + +; This is somewhat special because it has to compensate for the delay in bit 7 +stuffed7: ;1 for branch taken + andi x1, USBMASK ;1 already sampled by caller + breq se0a ;1 + mov x2, x1 ;1 ensure correct NRZI sequence + ori shift, 0x80 ;1 no need to set reconstruction in x3: shift has already been used + in x1, USBIN ;1 <-- sample bit 0 + rjmp unstuffed7 ;2 + +stuffed0: ;1 for branch taken + in x1, USBIN ;1 <-- sample @ +1 + andi x1, USBMASK ;1 + breq se0a ;1 + andi x3, ~0x01 ;1 + ori shift, 0x01 ;1 + rjmp rxbit1 ;2 + +;----------------------------- +rxLoop: + breq stuffed5 ;1 +rxbit6: + in x1, USBIN ;1 <-- sample bit 6 + andi x1, USBMASK ;1 + breq se0a ;1 + eor x2, x1 ;1 + bst x2, USBMINUS;1 + bld shift, 6 ;1 + cpi shift, 0x02 ;1 + brlo stuffed6 ;1 +rxbit7: + in x2, USBIN ;1 <-- sample bit 7 + eor x1, x2 ;1 + bst x1, USBMINUS;1 + bld shift, 7 ;1 + eor x3, shift ;1 x3 is 0 at bit locations we changed, 1 at others + st y+, x3 ;2 the eor above reconstructed modified bits and inverted rx data + ser x3 ;1 +rxbit0: + in x1, USBIN ;1 <-- sample bit 0 + cpi shift, 0x04 ;1 + brlo stuffed7 ;1 +unstuffed7: + eor x2, x1 ;1 + bst x2, USBMINUS;1 + bld shift, 0 ;1 + andi shift, 0xf9 ;1 + breq stuffed0 ;1 +rxbit1: + in x2, USBIN ;1 <-- sample bit 1 + andi x2, USBMASK ;1 +se0a: ; enlarge jump range to SE0 + breq se0 ;1 check for SE0 more often close to start of byte + eor x1, x2 ;1 + bst x1, USBMINUS;1 + bld shift, 1 ;1 + andi shift, 0xf3 ;1 + breq stuffed1 ;1 +rxbit2: + in x1, USBIN ;1 <-- sample bit 2 + andi x1, USBMASK ;1 + breq se0 ;1 + eor x2, x1 ;1 + bst x2, USBMINUS;1 + bld shift, 2 ;1 + andi shift, 0xe7 ;1 + breq stuffed2 ;1 +rxbit3: + in x2, USBIN ;1 <-- sample bit 3 + eor x1, x2 ;1 + bst x1, USBMINUS;1 + bld shift, 3 ;1 + dec cnt ;1 check for buffer overflow + breq overflow ;1 + andi shift, 0xcf ;1 + breq stuffed3 ;1 +rxbit4: + in x1, USBIN ;1 <-- sample bit 4 + andi x1, USBMASK ;1 + breq se0 ;1 + eor x2, x1 ;1 + bst x2, USBMINUS;1 + bld shift, 4 ;1 + andi shift, 0x9f ;1 + breq stuffed4 ;1 +rxbit5: + in x2, USBIN ;1 <-- sample bit 5 + eor x1, x2 ;1 + bst x1, USBMINUS;1 + bld shift, 5 ;1 + andi shift, 0x3f ;1 + rjmp rxLoop ;2 +;----------------------------- + +stuffed1: ;1 for branch taken + in x2, USBIN ;1 <-- sample @ +1 + andi x2, USBMASK ;1 + breq se0 ;1 + andi x3, ~0x02 ;1 + ori shift, 0x02 ;1 + rjmp rxbit2 ;2 + +stuffed2: ;1 for branch taken + in x1, USBIN ;1 <-- sample @ +1 + andi x1, USBMASK ;1 + breq se0 ;1 + andi x3, ~0x04 ;1 + ori shift, 0x04 ;1 + rjmp rxbit3 ;2 + +stuffed3: ;1 for branch taken + in x2, USBIN ;1 <-- sample @ +1 + andi x2, USBMASK ;1 + breq se0 ;1 + andi x3, ~0x08 ;1 + ori shift, 0x08 ;1 + rjmp rxbit4 ;2 + +stuffed4: ;1 for branch taken + in x1, USBIN ;1 <-- sample @ +1 + andi x1, USBMASK ;1 + breq se0 ;1 + andi x3, ~0x10 ;1 + ori shift, 0x10 ;1 + rjmp rxbit5 ;2 + +;################ end receiver loop ############### + +overflow: ; ignore package if buffer overflow + rjmp rxDoReturn ; enlarge jump range + +;This is the only non-error exit point for the software receiver loop +;{4, 20} cycles after start of SE0, typically {10, 18} after SE0 start = {-6, 2} from end of SE0 +;next sync starts {16,} cycles after SE0 -> worst case start: +4 from next sync start +;we don't check any CRCs here because there is no time left. +se0: ;{-6, 2} from end of SE0 / {,4} into next frame + mov cnt, YL ;1 assume buffer in lower 256 bytes of memory + lds YL, usbInputBuf ;2 reposition to buffer start + sub cnt, YL ;1 length of message + ldi x1, 1< 19 = {13, 21} from SE0 end + cpi x1, USBPID_OUT ;1 + breq isSetupOrOut ;2 -> 22 = {16, 24} from SE0 end / {,24} into next frame + cpi x1, USBPID_IN ;1 + breq handleIn ;1 +#define USB_DATA_MASK ~(USBPID_DATA0 ^ USBPID_DATA1) + andi x1, USB_DATA_MASK ;1 + cpi x1, USBPID_DATA0 & USB_DATA_MASK ;1 + brne rxDoReturn ;1 not a data PID -- ignore +isData: + lds x2, usbCurrentTok ;2 + tst x2 ;1 + breq rxDoReturn ;1 for other device or spontaneous data -- ignore + lds x1, usbRxLen ;2 + cpi x1, 0 ;1 + brne sendNakAndReti ;1 no buffer space available / {30, 38} from SE0 end +; 2006-03-11: The following two lines fix a problem where the device was not +; recognized if usbPoll() was called less frequently than once every 4 ms. + cpi cnt, 4 ;1 zero sized data packets are status phase only -- ignore and ack + brmi sendAckAndReti ;1 keep rx buffer clean -- we must not NAK next SETUP + sts usbRxLen, cnt ;2 store received data, swap buffers + sts usbRxToken, x2 ;2 + lds x1, usbAppBuf ;2 + sts usbAppBuf, YL ;2 + sts usbInputBuf, x1 ;2 buffers now swapped + rjmp sendAckAndReti ;2 -> {43, 51} from SE0 end + +handleIn: ; {18, 26} from SE0 end + cp x2, shift ;1 shift contains our device addr + brne rxDoReturn ;1 other device +#if USB_CFG_HAVE_INTRIN_ENDPOINT + sbrc x3, 7 ;2 x3 contains addr + endpoint + rjmp handleIn1 ;0 +#endif + lds cnt, usbTxLen ;2 + sbrc cnt, 4 ;2 + rjmp sendCntAndReti ;0 -> {27, 35} from SE0 end + ldi x1, USBPID_NAK ;1 + sts usbTxLen, x1 ;2 buffer is now free + ldi YL, lo8(usbTxBuf) ;1 + ldi YH, hi8(usbTxBuf) ;1 + rjmp usbSendAndReti ;2 -> {34, 43} from SE0 end + +; Comment about when to set usbTxLen to USBPID_NAK: +; We should set it back when we receive the ACK from the host. This would +; be simple to implement: One static variable which stores whether the last +; tx was for endpoint 0 or 1 and a compare in the receiver to distinguish the +; ACK. However, we set it back immediately when we send the package, +; assuming that no error occurs and the host sends an ACK. We save one byte +; RAM this way and avoid potential problems with endless retries. The rest of +; the driver assumes error-free transfers anyway. + +otherOutOrSetup: + clr x1 + sts usbCurrentTok, x1 +rxDoReturn: + pop x3 ;2 + pop YL ;2 + pop YH ;2 + rjmp sofError ;2 + +isSetupOrOut: ; we must be fast here -- a data package may follow / {,24} into next frame + cp x2, shift ;1 shift contains our device addr + brne otherOutOrSetup ;1 other device -- ignore +#if USB_CFG_IMPLEMENT_FN_WRITEOUT /* if we need second OUT endpoint, store endpoint address */ + andi x1, 0x7f ;1 mask out MSb in token + andi x3, 0x80 ;1 mask out all but endpoint address + or x1, x3 ;1 merge endpoint into currentToken + sts usbCurrentTok, x1 ;2 + brmi dontResetEP0 ;1 endpoint 1 -> don't reset endpoint 0 input +#else + sts usbCurrentTok, x1 ;2 +#endif +;A transmission can still have data in the output buffer while we receive a +;SETUP package with an IN phase. To avoid that the old data is sent as a reply, +;we abort transmission. We don't need to reset usbMsgLen because it is used +;from the main loop only where the setup is processed anyway. + ldi x1, USBPID_NAK ;1 + sts usbTxLen, x1 ;2 abort transmission +dontResetEP0: + pop x3 ;2 + pop YL ;2 + in x1, USB_INTR_PENDING;1 + sbrc x1, USB_INTR_PENDING_BIT;1 check whether data is already arriving {,41} into next frame + rjmp shortcutToStart ;2 save the pops and pushes -- a new interrupt is aready pending +;If the jump above was not taken, we can be at {,2} into the next frame here + pop YH ;2 +txDoReturn: +sofError: ; error in start of frame -- ignore frame + ldi x1, 1< {,21} into next frame -> up to 3 sync bits missed + +sendCntAndReti: ; 19 cycles until SOP + mov x3, cnt ;1 + rjmp usbSendX3 ;2 +sendNakAndReti: ; 19 cycles until SOP + ldi x3, USBPID_NAK ;1 + rjmp usbSendX3 ;2 +sendAckAndReti: ; 17 cycles until SOP + ldi x3, USBPID_ACK ;1 +usbSendX3: + ldi YL, 20 ;1 'x3' is R20 + ldi YH, 0 ;1 + ldi cnt, 2 ;1 +;;;;rjmp usbSendAndReti fallthrough + +; USB spec says: +; idle = J +; J = (D+ = 0), (D- = 1) or USBOUT = 0x01 +; K = (D+ = 1), (D- = 0) or USBOUT = 0x02 +; Spec allows 7.5 bit times from EOP to SOP for replies (= 60 cycles) + +;usbSend: +;pointer to data in 'Y' +;number of bytes in 'cnt' -- including sync byte +;uses: x1...x4, shift, cnt, Y +usbSendAndReti: ; SOP starts 13 cycles after call + push x4 ;2 + ldi x4, USBMASK ;1 exor mask + sbi USBOUT, USBMINUS;1 prepare idle state; D+ and D- must have been 0 (no pullups) + in x1, USBOUT ;1 port mirror for tx loop + sbi USBDDR, USBMINUS;1 + sbi USBDDR, USBPLUS ;1 set D+ and D- to output: acquire bus +; need not init x2 (bitstuff history) because sync starts with 0 + ldi shift, 0x80 ;1 sync byte is first byte sent + rjmp txLoop ;2 -> 13 + 3 = 16 cycles until SOP + +#if USB_CFG_HAVE_INTRIN_ENDPOINT /* placed here due to relative jump range */ +handleIn1: ;{23, 31} from SE0 + ldi x1, USBPID_NAK ;1 +#if USB_CFG_HAVE_INTRIN_ENDPOINT3 +; 2006-06-10 as suggested by O.Tamura: support second INTR IN / BULK IN endpoint + ldd x2, y+2 ;2 + sbrc x2, 0 ;2 1 + rjmp handleIn3 ;0 2 +#endif + lds cnt, usbTxLen1 ;2 + sbrc cnt, 4 ;2 + rjmp sendCntAndReti ;0 + sts usbTxLen1, x1 ;2 + ldi YL, lo8(usbTxBuf1);1 + ldi YH, hi8(usbTxBuf1);1 + rjmp usbSendAndReti ;2 -> arrives at usbSendAndReti {34, 42} from SE0 + +#if USB_CFG_HAVE_INTRIN_ENDPOINT3 +handleIn3: + lds cnt, usbTxLen3 ;2 + sbrc cnt, 4 ;2 + rjmp sendCntAndReti ;0 + sts usbTxLen3, x1 ;2 + ldi YL, lo8(usbTxBuf3);1 + ldi YH, hi8(usbTxBuf3);1 + rjmp usbSendAndReti ;2 -> arrives at usbSendAndReti {39, 47} from SE0 +#endif +#endif + +bitstuff0: ;1 (for branch taken) + eor x1, x4 ;1 + ldi x2, 0 ;1 + out USBOUT, x1 ;1 <-- out + rjmp didStuff0 ;2 branch back 2 cycles earlier +bitstuff1: ;1 (for branch taken) + eor x1, x4 ;1 + ldi x2, 0 ;1 + sec ;1 set carry so that brsh will not jump + out USBOUT, x1 ;1 <-- out + rjmp didStuff1 ;2 jump back 1 cycle earler +bitstuff2: ;1 (for branch taken) + eor x1, x4 ;1 + ldi x2, 0 ;1 + rjmp didStuff2 ;2 jump back 3 cycles earlier and do out +bitstuff3: ;1 (for branch taken) + eor x1, x4 ;1 + ldi x2, 0 ;1 + rjmp didStuff3 ;2 jump back earlier + +txLoop: + sbrs shift, 0 ;1 + eor x1, x4 ;1 + out USBOUT, x1 ;1 <-- out + ror shift ;1 + ror x2 ;1 +didStuff0: + cpi x2, 0xfc ;1 + brsh bitstuff0 ;1 + sbrs shift, 0 ;1 + eor x1, x4 ;1 + ror shift ;1 + out USBOUT, x1 ;1 <-- out + ror x2 ;1 + cpi x2, 0xfc ;1 +didStuff1: + brsh bitstuff1 ;1 + sbrs shift, 0 ;1 + eor x1, x4 ;1 + ror shift ;1 + ror x2 ;1 +didStuff2: + out USBOUT, x1 ;1 <-- out + cpi x2, 0xfc ;1 + brsh bitstuff2 ;1 + sbrs shift, 0 ;1 + eor x1, x4 ;1 + ror shift ;1 + ror x2 ;1 +didStuff3: + cpi x2, 0xfc ;1 + out USBOUT, x1 ;1 <-- out + brsh bitstuff3 ;1 + nop2 ;2 + ld x3, y+ ;2 + sbrs shift, 0 ;1 + eor x1, x4 ;1 + out USBOUT, x1 ;1 <-- out + ror shift ;1 + ror x2 ;1 +didStuff4: + cpi x2, 0xfc ;1 + brsh bitstuff4 ;1 + sbrs shift, 0 ;1 + eor x1, x4 ;1 + ror shift ;1 + out USBOUT, x1 ;1 <-- out + ror x2 ;1 + cpi x2, 0xfc ;1 +didStuff5: + brsh bitstuff5 ;1 + sbrs shift, 0 ;1 + eor x1, x4 ;1 + ror shift ;1 + ror x2 ;1 +didStuff6: + out USBOUT, x1 ;1 <-- out + cpi x2, 0xfc ;1 + brsh bitstuff6 ;1 + sbrs shift, 0 ;1 + eor x1, x4 ;1 + ror shift ;1 + ror x2 ;1 +didStuff7: + cpi x2, 0xfc ;1 + out USBOUT, x1 ;1 <-- out + brsh bitstuff7 ;1 + mov shift, x3 ;1 + dec cnt ;1 + brne txLoop ;2 | 1 + cbr x1, USBMASK ;1 prepare SE0 [spec says EOP may be 15 to 18 cycles] + pop x4 ;2 + out USBOUT, x1 ;1 <-- out SE0 -- from now 2 bits = 16 cycles until bus idle + ldi cnt, 2 ;| takes cnt * 3 cycles +se0Delay: ;| + dec cnt ;| + brne se0Delay ;| -> 2 * 3 = 6 cycles +;2006-03-06: moved transfer of new address to usbDeviceAddr from C-Code to asm: +;set address only after data packet was sent, not after handshake + lds x2, usbNewDeviceAddr;2 + subi YL, 20 + 2 ;1 + sbci YH, 0 ;1 + breq skipAddrAssign ;2 + sts usbDeviceAddr, x2 ;0 if not skipped: SE0 is one cycle longer +skipAddrAssign: +;end of usbDeviceAddress transfer + ori x1, USBIDLE ;1 + in x2, USBDDR ;1 + cbr x2, USBMASK ;1 set both pins to input + out USBOUT, x1 ;1 <-- out J (idle) -- end of SE0 (EOP signal) + cbr x1, USBMASK ;1 configure no pullup on both pins + pop x3 ;2 + pop YL ;2 + out USBDDR, x2 ;1 <-- release bus now + out USBOUT, x1 ;1 set pullup state + pop YH ;2 + rjmp txDoReturn ;2 [we want to jump to rxDoReturn, but this saves cycles] + + +bitstuff4: ;1 (for branch taken) + eor x1, x4 ;1 + ldi x2, 0 ;1 + out USBOUT, x1 ;1 <-- out + rjmp didStuff4 ;2 jump back 2 cycles earlier +bitstuff5: ;1 (for branch taken) + eor x1, x4 ;1 + ldi x2, 0 ;1 + sec ;1 set carry so that brsh is not taken + out USBOUT, x1 ;1 <-- out + rjmp didStuff5 ;2 jump back 1 cycle earlier +bitstuff6: ;1 (for branch taken) + eor x1, x4 ;1 + ldi x2, 0 ;1 + rjmp didStuff6 ;2 jump back 3 cycles earlier and do out there +bitstuff7: ;1 (for branch taken) + eor x1, x4 ;1 + ldi x2, 0 ;1 + rjmp didStuff7 ;2 jump back 4 cycles earlier + +; ######################## utility functions ######################## + +#ifdef __IAR_SYSTEMS_ASM__ +/* Register assignments for usbCrc16 on IAR cc */ +/* Calling conventions on IAR: + * First parameter passed in r16/r17, second in r18/r19 and so on. + * Callee must preserve r4-r15, r24-r29 (r28/r29 is frame pointer) + * Result is passed in r16/r17 + * In case of the "tiny" memory model, pointers are only 8 bit with no + * padding. We therefore pass argument 1 as "16 bit unsigned". + */ +RTMODEL "__rt_version", "3" +/* The line above will generate an error if cc calling conventions change. + * The value "3" above is valid for IAR 4.10B/W32 + */ +# define argLen r18 /* argument 2 */ +# define argPtrL r16 /* argument 1 */ +# define argPtrH r17 /* argument 1 */ + +# define resCrcL r16 /* result */ +# define resCrcH r17 /* result */ + +# define ptrL ZL +# define ptrH ZH +# define ptr Z +# define byte r22 +# define bitCnt r19 +# define polyL r20 +# define polyH r21 +# define scratch r23 + +#else /* __IAR_SYSTEMS_ASM__ */ +/* Register assignments for usbCrc16 on gcc */ +/* Calling conventions on gcc: + * First parameter passed in r24/r25, second in r22/23 and so on. + * Callee must preserve r1-r17, r28/r29 + * Result is passed in r24/r25 + */ +# define argLen r22 /* argument 2 */ +# define argPtrL r24 /* argument 1 */ +# define argPtrH r25 /* argument 1 */ + +# define resCrcL r24 /* result */ +# define resCrcH r25 /* result */ + +# define ptrL XL +# define ptrH XH +# define ptr x +# define byte r18 +# define bitCnt r19 +# define polyL r20 +# define polyH r21 +# define scratch r23 + +#endif + +; extern unsigned usbCrc16(unsigned char *data, unsigned char len); +; data: r24/25 +; len: r22 +; temp variables: +; r18: data byte +; r19: bit counter +; r20/21: polynomial +; r23: scratch +; r24/25: crc-sum +; r26/27=X: ptr +usbCrc16: + mov ptrL, argPtrL + mov ptrH, argPtrH + ldi resCrcL, 0xff + ldi resCrcH, 0xff + ldi polyL, lo8(0xa001) + ldi polyH, hi8(0xa001) +crcByteLoop: + subi argLen, 1 + brcs crcReady + ld byte, ptr+ + ldi bitCnt, 8 +crcBitLoop: + mov scratch, byte + eor scratch, resCrcL + lsr resCrcH + ror resCrcL + lsr byte + sbrs scratch, 0 + rjmp crcNoXor + eor resCrcL, polyL + eor resCrcH, polyH +crcNoXor: + dec bitCnt + brne crcBitLoop + rjmp crcByteLoop +crcReady: + com resCrcL + com resCrcH + ret + +; extern unsigned usbCrc16Append(unsigned char *data, unsigned char len); +usbCrc16Append: + rcall usbCrc16 + st ptr+, resCrcL + st ptr+, resCrcH + ret diff --git a/firmware/usbdrv/usbdrvasm.asm b/firmware/usbdrv/usbdrvasm.asm new file mode 100644 index 0000000..baf4094 --- /dev/null +++ b/firmware/usbdrv/usbdrvasm.asm @@ -0,0 +1,21 @@ +/* Name: usbdrvasm.asm + * Project: AVR USB driver + * Author: Christian Starkjohann + * Creation Date: 2006-03-01 + * Tabsize: 4 + * Copyright: (c) 2006 by OBJECTIVE DEVELOPMENT Software GmbH + * License: Proprietary, free under certain conditions. See Documentation. + * This Revision: $Id: usbdrvasm.asm,v 1.1 2006/09/26 18:18:27 rschaten Exp $ + */ + +/* +General Description: +The IAR compiler/assembler system prefers assembler files with file extension +".asm". We simply provide this file as an alias for usbdrvasm.S. + +Thanks to Oleg Semyonov for his help with the IAR tools port! +*/ + +#include "usbdrvasm.S" + +end diff --git a/usb-led-fader.doxygen b/usb-led-fader.doxygen new file mode 100644 index 0000000..e840a7b --- /dev/null +++ b/usb-led-fader.doxygen @@ -0,0 +1,1252 @@ +# Doxyfile 1.4.7 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = "USB-LED-Fader" + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, +# Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, +# Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian, +# Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, +# Swedish, and Ukrainian. + +OUTPUT_LANGUAGE = English + +# This tag can be used to specify the encoding used in the generated output. +# The encoding is not always determined by the language that is chosen, +# but also whether or not the output is meant for Windows or non-Windows users. +# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES +# forces the Windows encoding (this is the default for the Windows binary), +# whereas setting the tag to NO uses a Unix-style encoding (the default for +# all platforms other than Windows). + +USE_WINDOWS_ENCODING = NO + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = YES + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like the Qt-style comments (thus requiring an +# explicit @brief command for a brief description. + +JAVADOC_AUTOBRIEF = YES + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the DETAILS_AT_TOP tag is set to YES then Doxygen +# will output the detailed description near the top, like JavaDoc. +# If set to NO, the detailed description appears after the member +# documentation. + +DETAILS_AT_TOP = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 8 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = YES + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for Java. +# For instance, namespaces will be presented as packages, qualified scopes +# will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want to +# include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. + +BUILTIN_STL_SUPPORT = NO + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = YES + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = YES + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# in the documentation. The default is NO. + +SHOW_DIRECTORIES = NO + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from the +# version control system). Doxygen will invoke the program by executing (via +# popen()) the command , where is the value of +# the FILE_VERSION_FILTER tag, and is the name of an input file +# provided by doxygen. Whatever the program writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = YES + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be abled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx +# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py + +FILE_PATTERNS = + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = firmware/usbdrv + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix filesystem feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command , where +# is the value of the INPUT_FILTER tag, and is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER +# is applied to all files. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = YES + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES (the default) +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES (the default) +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = YES + +# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) +# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from +# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will +# link to the source code. Otherwise they will link to the documentstion. + +REFERENCES_LINK_SOURCE = YES + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = NO + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = htmldoc + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# stylesheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + +ENUM_VALUES_PER_LINE = 4 + +# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be +# generated containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, +# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are +# probably better off using the HTML help feature. + +GENERATE_TREEVIEW = YES + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = YES + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latexdoc + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = YES + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtfdoc + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = YES + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. This is useful +# if you want to understand what is going on. On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# in the INCLUDE_PATH (see below) will be search if a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse +# the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option is superseded by the HAVE_DOT option below. This is only a +# fallback. It is recommended to install and use dot, since it yields more +# powerful graphs. + +CLASS_DIAGRAMS = YES + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = NO + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will +# generate a call dependency graph for every global function or class method. +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable call graphs for selected +# functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then doxygen will +# generate a caller dependency graph for every global function or class method. +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable caller graphs for selected +# functions only using the \callergraph command. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width +# (in pixels) of the graphs generated by dot. If a graph becomes larger than +# this value, doxygen will try to truncate the graph, so that it fits within +# the specified constraint. Beware that most browsers cannot cope with very +# large images. + +MAX_DOT_GRAPH_WIDTH = 1024 + +# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height +# (in pixels) of the graphs generated by dot. If a graph becomes larger than +# this value, doxygen will try to truncate the graph, so that it fits within +# the specified constraint. Beware that most browsers cannot cope with very +# large images. + +MAX_DOT_GRAPH_HEIGHT = 1024 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that a graph may be further truncated if the graph's +# image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH +# and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default), +# the graph is not depth-constrained. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, which results in a white background. +# Warning: Depending on the platform used, enabling this option may lead to +# badly anti-aliased labels on the edges of a graph (i.e. they become hard to +# read). + +DOT_TRANSPARENT = NO + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- + +# The SEARCHENGINE tag specifies whether or not a search engine should be +# used. If set to NO the values of all tags below this one will be ignored. + +SEARCHENGINE = NO