/* 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 536 2008-02-28 21:11:35Z 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. We recommend that D+ triggers the interrupt (best achieved by using INT0 for D+), but it is also possible to trigger the interrupt from D-. If D- is used, interrupts are also triggered by SOF packets. D- requires a pull-up of 1.5k to +3.5V (and the device must be powered at 3.5V) to identify as low-speed USB device. A pull-down or pull-up of 1M SHOULD be connected from D+ to +3.5V to prevent interference when no USB master is connected. If you use Zener diodes to limit the voltage on D+ and D-, you MUST use a pull-down resistor, not a pull-up. We use D+ as interrupt source and not D- because it does not trigger on keep-alive and RESET states. If you want to count keep-alive events with USB_COUNT_SOF, you MUST use D- as an interrupt source. As a compile time option, the 1.5k pull-up 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 exactly 12 MHz, 15 MHz or 16 MHz or at 16.5 MHz +/- 1%. See usbconfig-prototype.h for details. Limitations: ============ 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. 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 the following endpoints: - Endpoint 0, the default control endpoint. - Any number of interrupt- or bulk-out endpoints. The data is sent to usbFunctionWriteOut() and USB_CFG_IMPLEMENT_FN_WRITEOUT must be defined to 1 to activate this feature. The endpoint number can be found in the global variable 'usbRxToken'. - One default interrupt- or bulk-in endpoint. This endpoint is used for interrupt- or bulk-in transfers which are not handled by any other endpoint. You must define USB_CFG_HAVE_INTRIN_ENDPOINT in order to activate this feature and call usbSetInterrupt() to send interrupt/bulk data. - One additional interrupt- or bulk-in endpoint. This was endpoint 3 in previous versions of this driver but can now be configured to any endpoint number. You must define USB_CFG_HAVE_INTRIN_ENDPOINT3 in order to activate this feature and call usbSetInterrupt3() to send interrupt/bulk data. The endpoint number can be set with USB_CFG_EP3_NUMBER. 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. 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 using D- as the interrupt source. Define USB_COUNT_SOF to 1 and use the global variable usbSofCount to check for 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) pull-down or pull-up resistor on D+ (interrupt). If Zener diodes are used, use a pull-down. 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 25 cycles (this is for 12 MHz, faster clocks allow longer latency). 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 @ 12 MHz (= 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 20080228 /* 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 USB_PUBLIC #define USB_PUBLIC #endif /* USB_PUBLIC is used as declaration attribute for all functions exported by * the USB driver. The default is no attribute (see above). You may define it * to static either in usbconfig.h or from the command line if you include * usbdrv.c instead of linking against it. Including the C module of the driver * directly in your code saves a couple of bytes in flash memory. */ #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 */ #ifdef __cplusplus extern "C"{ #endif USB_PUBLIC void usbInit(void); /* This function must be called before interrupts are enabled and the main * loop is entered. */ USB_PUBLIC 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. */ USB_PUBLIC 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. */ #ifdef __cplusplus } // extern "C" #endif USB_PUBLIC 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 #ifdef __cplusplus extern "C"{ #endif USB_PUBLIC 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. */ #ifdef __cplusplus } // extern "C" #endif #if USB_CFG_HAVE_INTRIN_ENDPOINT3 USB_PUBLIC 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 USB_PUBLIC 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 USB_PUBLIC 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 USB_PUBLIC 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__ */