/* 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: GNU GPL v2 (see License.txt) or proprietary (CommercialLicense.txt) * This Revision: $Id: usbdrv.h 283 2007-03-29 16:31:19Z cs $ */#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) beconnected to INT0. D- requires a pullup of 1.5k to +3.5V (and the devicemust be powered at 3.5V) to identify as low-speed USB device. A pullup of1M SHOULD be connected from D+ to +3.5V to prevent interference when no USBmaster is connected. We use D+ as interrupt source and not D- because itdoes not trigger on keep-alive and RESET states.As a compile time option, the 1.5k pullup resistor on D- can be madeswitchable to allow the device to disconnect at will. See the definition ofusbDeviceConnect() 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 byan AT90S2313 powered at 4.5V. However, if the supply voltage to maximum clockrelation is interpolated linearly, an ATtiny2313 meets the requirement byspecification. In practice, the AT90S2313 can be overclocked and works well.Limitations:============Robustness with respect to communication errors:The driver assumes error-free communication. It DOES check for errors inthe 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 dueto 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 CPUperformance does not permit that. The driver does not check Data0/Data1toggling, but application software can implement the check.Input characteristics:Since no differential receiver circuit is used, electrical interferencerobustness may suffer. The driver samples only one of the data lines withan ordinary I/O pin's input characteristics. However, since this is only alow speed USB implementation and the specification allows for 8 times thebit rate over the same hardware, we should be on the safe side. Even the specrequires 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 oneinterrupt-out (or bulk-out) endpoint (endpoint 1). Please note that the USBstandard forbids bulk endpoints for low speed devices! Most operating systemsallow them anyway, but the AVR will spend 90% of the CPU time in the USBinterrupt 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/orUSB_CFG_IMPLEMENT_FN_WRITEOUT respectively (see usbconfig-prototype.h fordetails).Maximum data payload:Data payload of control in and out transfers may be up to 254 bytes. In orderto 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 suspendmode. This is not a problem for self-powered devices since they don't needbus power anyway. Bus-powered devices can achieve this only by putting theCPU in sleep mode. The driver does not implement suspend handling by itself.However, the application may implement activity monitoring and wakeup fromsleep. The host sends regular SE0 states on the bus to keep it active. TheseSE0 states can be detected by wiring the INT1 pin to D-. It is not necessaryto enable the interrupt, checking the interrupt pending flag should suffice.Before entering sleep mode, the application should enable INT1 for a wakeupon the next bus activity.Operation without an USB master:The driver behaves neutral without connection to an USB master if D- readsas 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 inthe interrupt routine.Interrupt latency:The application must ensure that the USB interrupt is not disabled for morethan 20 cycles. This implies that all interrupt routines must either bedeclared as "INTERRUPT" instead of "SIGNAL" (see "avr/signal.h") or that theyare written in assembler with "sei" as the first instruction.Maximum interrupt duration / CPU cycle consumption:The driver handles all USB communication during the interrupt serviceroutine. The routine will not return before an entire USB message is receivedand the reply is sent. This may be up to ca. 1200 cycles = 100us if the hostconforms to the standard. The driver will consume CPU cycles for all USBmessages, even if they address another (low-speed) device on the same bus.*//* ------------------------------------------------------------------------- *//* --------------------------- Module Interface ---------------------------- *//* ------------------------------------------------------------------------- */#define USBDRV_VERSION  20070329/* 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_ENDPOINTvoid    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_ENDPOINT3void    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_WRITEextern 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_READextern 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_WRITEOUTextern 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<<USB_CFG_PULLUP_BIT)), \                                  (USB_PULLUP_OUT |= (1<<USB_CFG_PULLUP_BIT)))/* This macro (intended to look like a function) connects the device to the * USB bus. It is only available if you have defined the constants * USB_CFG_PULLUP_IOPORT and USB_CFG_PULLUP_BIT in usbconfig.h. */#define usbDeviceDisconnect()   ((USB_PULLUP_DDR &= ~(1<<USB_CFG_PULLUP_BIT)), \                                  (USB_PULLUP_OUT &= ~(1<<USB_CFG_PULLUP_BIT)))/* This macro (intended to look like a function) disconnects the device from * the USB bus. It is only available if you have defined the constants * USB_CFG_PULLUP_IOPORT and USB_CFG_PULLUP_BIT in usbconfig.h. */#endif /* USB_CFG_PULLUP_IOPORT */extern unsigned usbCrc16(unsigned data, uchar len);#define usbCrc16(data, len) usbCrc16((unsigned)(data), len)/* This function calculates the binary complement of the data CRC used in * USB data packets. The value is used to build raw transmit packets. * You may want to use this function for data checksums or to verify received * data. We enforce 16 bit calling conventions for compatibility with IAR's * tiny memory model. */extern unsigned usbCrc16Append(unsigned data, uchar len);#define usbCrc16Append(data, len)    usbCrc16Append((unsigned)(data), len)/* This function is equivalent to usbCrc16() above, except that it appends * the 2 bytes CRC (lowbyte first) in the 'data' buffer after reading 'len' * bytes. */extern uchar    usbConfiguration;/* This value contains the current configuration set by the host. The driver * allows setting and querying of this variable with the USB SET_CONFIGURATION * and GET_CONFIGURATION requests, but does not use it otherwise. * You may want to reflect the "configured" status with a LED on the device or * switch on high power parts of the circuit only if the device is configured. */#define USB_STRING_DESCRIPTOR_HEADER(stringLength) ((2*(stringLength)+2) | (3<<8))/* This macro builds a descriptor header for a string descriptor given the * string's length. See usbdrv.c for an example how to use it. */#if USB_CFG_HAVE_FLOWCONTROLextern volatile schar   usbRxLen;#define usbDisableAllRequests()     usbRxLen = -1/* Must be called from usbFunctionWrite(). This macro disables all data input * from the USB interface. Requests from the host are answered with a NAK * while they are disabled. */#define usbEnableAllRequests()      usbRxLen = 0/* May only be called if requests are disabled. This macro enables input from * the USB interface after it has been disabled with usbDisableAllRequests(). */#define usbAllRequestsAreDisabled() (usbRxLen < 0)/* Use this macro to find out whether requests are disabled. It may be needed * to ensure that usbEnableAllRequests() is never called when requests are * enabled. */#endif#define USB_SET_DATATOKEN1(token)   usbTxBuf1[0] = token#define USB_SET_DATATOKEN3(token)   usbTxBuf3[0] = token/* These two macros can be used by application software to reset data toggling * for interrupt-in endpoints 1 and 3. */#endif  /* __ASSEMBLER__ *//* ------------------------------------------------------------------------- *//* ----------------- Definitions for Descriptor Properties ----------------- *//* ------------------------------------------------------------------------- *//* This is advanced stuff. See usbconfig-prototype.h for more information * about the various methods to define USB descriptors. If you do nothing, * the default descriptors will be used.