comparison: usbdrv/usbdrv.h
usbdrv/usbdrv.h
- changeset 0
- 9e9b2c78bd31
equal
deleted
inserted
replaced
| -1:000000000000 | 0:9e9b2c78bd31 |
|---|---|
| 1 /* Name: usbdrv.h | |
| 2 * Project: V-USB, virtual USB port for Atmel's(r) AVR(r) microcontrollers | |
| 3 * Author: Christian Starkjohann | |
| 4 * Creation Date: 2004-12-29 | |
| 5 * Tabsize: 4 | |
| 6 * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH | |
| 7 * License: GNU GPL v2 (see License.txt), GNU GPL v3 or proprietary (CommercialLicense.txt) | |
| 8 */ | |
| 9 | |
| 10 #ifndef __usbdrv_h_included__ | |
| 11 #define __usbdrv_h_included__ | |
| 12 #include "usbconfig.h" | |
| 13 #include "usbportability.h" | |
| 14 | |
| 15 /* | |
| 16 Hardware Prerequisites: | |
| 17 ======================= | |
| 18 USB lines D+ and D- MUST be wired to the same I/O port. We recommend that D+ | |
| 19 triggers the interrupt (best achieved by using INT0 for D+), but it is also | |
| 20 possible to trigger the interrupt from D-. If D- is used, interrupts are also | |
| 21 triggered by SOF packets. D- requires a pull-up of 1.5k to +3.5V (and the | |
| 22 device must be powered at 3.5V) to identify as low-speed USB device. A | |
| 23 pull-down or pull-up of 1M SHOULD be connected from D+ to +3.5V to prevent | |
| 24 interference when no USB master is connected. If you use Zener diodes to limit | |
| 25 the voltage on D+ and D-, you MUST use a pull-down resistor, not a pull-up. | |
| 26 We use D+ as interrupt source and not D- because it does not trigger on | |
| 27 keep-alive and RESET states. If you want to count keep-alive events with | |
| 28 USB_COUNT_SOF, you MUST use D- as an interrupt source. | |
| 29 | |
| 30 As a compile time option, the 1.5k pull-up resistor on D- can be made | |
| 31 switchable to allow the device to disconnect at will. See the definition of | |
| 32 usbDeviceConnect() and usbDeviceDisconnect() further down in this file. | |
| 33 | |
| 34 Please adapt the values in usbconfig.h according to your hardware! | |
| 35 | |
| 36 The device MUST be clocked at exactly 12 MHz, 15 MHz, 16 MHz or 20 MHz | |
| 37 or at 12.8 MHz resp. 16.5 MHz +/- 1%. See usbconfig-prototype.h for details. | |
| 38 | |
| 39 | |
| 40 Limitations: | |
| 41 ============ | |
| 42 Robustness with respect to communication errors: | |
| 43 The driver assumes error-free communication. It DOES check for errors in | |
| 44 the PID, but does NOT check bit stuffing errors, SE0 in middle of a byte, | |
| 45 token CRC (5 bit) and data CRC (16 bit). CRC checks can not be performed due | |
| 46 to timing constraints: We must start sending a reply within 7 bit times. | |
| 47 Bit stuffing and misplaced SE0 would have to be checked in real-time, but CPU | |
| 48 performance does not permit that. The driver does not check Data0/Data1 | |
| 49 toggling, but application software can implement the check. | |
| 50 | |
| 51 Input characteristics: | |
| 52 Since no differential receiver circuit is used, electrical interference | |
| 53 robustness may suffer. The driver samples only one of the data lines with | |
| 54 an ordinary I/O pin's input characteristics. However, since this is only a | |
| 55 low speed USB implementation and the specification allows for 8 times the | |
| 56 bit rate over the same hardware, we should be on the safe side. Even the spec | |
| 57 requires detection of asymmetric states at high bit rate for SE0 detection. | |
| 58 | |
| 59 Number of endpoints: | |
| 60 The driver supports the following endpoints: | |
| 61 | |
| 62 - Endpoint 0, the default control endpoint. | |
| 63 - Any number of interrupt- or bulk-out endpoints. The data is sent to | |
| 64 usbFunctionWriteOut() and USB_CFG_IMPLEMENT_FN_WRITEOUT must be defined | |
| 65 to 1 to activate this feature. The endpoint number can be found in the | |
| 66 global variable 'usbRxToken'. | |
| 67 - One default interrupt- or bulk-in endpoint. This endpoint is used for | |
| 68 interrupt- or bulk-in transfers which are not handled by any other endpoint. | |
| 69 You must define USB_CFG_HAVE_INTRIN_ENDPOINT in order to activate this | |
| 70 feature and call usbSetInterrupt() to send interrupt/bulk data. | |
| 71 - One additional interrupt- or bulk-in endpoint. This was endpoint 3 in | |
| 72 previous versions of this driver but can now be configured to any endpoint | |
| 73 number. You must define USB_CFG_HAVE_INTRIN_ENDPOINT3 in order to activate | |
| 74 this feature and call usbSetInterrupt3() to send interrupt/bulk data. The | |
| 75 endpoint number can be set with USB_CFG_EP3_NUMBER. | |
| 76 | |
| 77 Please note that the USB standard forbids bulk endpoints for low speed devices! | |
| 78 Most operating systems allow them anyway, but the AVR will spend 90% of the CPU | |
| 79 time in the USB interrupt polling for bulk data. | |
| 80 | |
| 81 Maximum data payload: | |
| 82 Data payload of control in and out transfers may be up to 254 bytes. In order | |
| 83 to accept payload data of out transfers, you need to implement | |
| 84 'usbFunctionWrite()'. | |
| 85 | |
| 86 USB Suspend Mode supply current: | |
| 87 The USB standard limits power consumption to 500uA when the bus is in suspend | |
| 88 mode. This is not a problem for self-powered devices since they don't need | |
| 89 bus power anyway. Bus-powered devices can achieve this only by putting the | |
| 90 CPU in sleep mode. The driver does not implement suspend handling by itself. | |
| 91 However, the application may implement activity monitoring and wakeup from | |
| 92 sleep. The host sends regular SE0 states on the bus to keep it active. These | |
| 93 SE0 states can be detected by using D- as the interrupt source. Define | |
| 94 USB_COUNT_SOF to 1 and use the global variable usbSofCount to check for bus | |
| 95 activity. | |
| 96 | |
| 97 Operation without an USB master: | |
| 98 The driver behaves neutral without connection to an USB master if D- reads | |
| 99 as 1. To avoid spurious interrupts, we recommend a high impedance (e.g. 1M) | |
| 100 pull-down or pull-up resistor on D+ (interrupt). If Zener diodes are used, | |
| 101 use a pull-down. If D- becomes statically 0, the driver may block in the | |
| 102 interrupt routine. | |
| 103 | |
| 104 Interrupt latency: | |
| 105 The application must ensure that the USB interrupt is not disabled for more | |
| 106 than 25 cycles (this is for 12 MHz, faster clocks allow longer latency). | |
| 107 This implies that all interrupt routines must either have the "ISR_NOBLOCK" | |
| 108 attribute set (see "avr/interrupt.h") or be written in assembler with "sei" | |
| 109 as the first instruction. | |
| 110 | |
| 111 Maximum interrupt duration / CPU cycle consumption: | |
| 112 The driver handles all USB communication during the interrupt service | |
| 113 routine. The routine will not return before an entire USB message is received | |
| 114 and the reply is sent. This may be up to ca. 1200 cycles @ 12 MHz (= 100us) if | |
| 115 the host conforms to the standard. The driver will consume CPU cycles for all | |
| 116 USB messages, even if they address another (low-speed) device on the same bus. | |
| 117 | |
| 118 */ | |
| 119 | |
| 120 /* ------------------------------------------------------------------------- */ | |
| 121 /* --------------------------- Module Interface ---------------------------- */ | |
| 122 /* ------------------------------------------------------------------------- */ | |
| 123 | |
| 124 #define USBDRV_VERSION 20121206 | |
| 125 /* This define uniquely identifies a driver version. It is a decimal number | |
| 126 * constructed from the driver's release date in the form YYYYMMDD. If the | |
| 127 * driver's behavior or interface changes, you can use this constant to | |
| 128 * distinguish versions. If it is not defined, the driver's release date is | |
| 129 * older than 2006-01-25. | |
| 130 */ | |
| 131 | |
| 132 | |
| 133 #ifndef USB_PUBLIC | |
| 134 #define USB_PUBLIC | |
| 135 #endif | |
| 136 /* USB_PUBLIC is used as declaration attribute for all functions exported by | |
| 137 * the USB driver. The default is no attribute (see above). You may define it | |
| 138 * to static either in usbconfig.h or from the command line if you include | |
| 139 * usbdrv.c instead of linking against it. Including the C module of the driver | |
| 140 * directly in your code saves a couple of bytes in flash memory. | |
| 141 */ | |
| 142 | |
| 143 #ifndef __ASSEMBLER__ | |
| 144 #ifndef uchar | |
| 145 #define uchar unsigned char | |
| 146 #endif | |
| 147 #ifndef schar | |
| 148 #define schar signed char | |
| 149 #endif | |
| 150 /* shortcuts for well defined 8 bit integer types */ | |
| 151 | |
| 152 #if USB_CFG_LONG_TRANSFERS /* if more than 254 bytes transfer size required */ | |
| 153 # define usbMsgLen_t unsigned | |
| 154 #else | |
| 155 # define usbMsgLen_t uchar | |
| 156 #endif | |
| 157 /* usbMsgLen_t is the data type used for transfer lengths. By default, it is | |
| 158 * defined to uchar, allowing a maximum of 254 bytes (255 is reserved for | |
| 159 * USB_NO_MSG below). If the usbconfig.h defines USB_CFG_LONG_TRANSFERS to 1, | |
| 160 * a 16 bit data type is used, allowing up to 16384 bytes (the rest is used | |
| 161 * for flags in the descriptor configuration). | |
| 162 */ | |
| 163 #define USB_NO_MSG ((usbMsgLen_t)-1) /* constant meaning "no message" */ | |
| 164 | |
| 165 #ifndef usbMsgPtr_t | |
| 166 #define usbMsgPtr_t uchar * | |
| 167 #endif | |
| 168 /* Making usbMsgPtr_t a define allows the user of this library to define it to | |
| 169 * an 8 bit type on tiny devices. This reduces code size, especially if the | |
| 170 * compiler supports a tiny memory model. | |
| 171 * The type can be a pointer or scalar type, casts are made where necessary. | |
| 172 * Although it's paradoxical, Gcc 4 generates slightly better code for scalar | |
| 173 * types than for pointers. | |
| 174 */ | |
| 175 | |
| 176 struct usbRequest; /* forward declaration */ | |
| 177 | |
| 178 USB_PUBLIC void usbInit(void); | |
| 179 /* This function must be called before interrupts are enabled and the main | |
| 180 * loop is entered. We exepct that the PORT and DDR bits for D+ and D- have | |
| 181 * not been changed from their default status (which is 0). If you have changed | |
| 182 * them, set both back to 0 (configure them as input with no internal pull-up). | |
| 183 */ | |
| 184 USB_PUBLIC void usbPoll(void); | |
| 185 /* This function must be called at regular intervals from the main loop. | |
| 186 * Maximum delay between calls is somewhat less than 50ms (USB timeout for | |
| 187 * accepting a Setup message). Otherwise the device will not be recognized. | |
| 188 * Please note that debug outputs through the UART take ~ 0.5ms per byte | |
| 189 * at 19200 bps. | |
| 190 */ | |
| 191 extern usbMsgPtr_t usbMsgPtr; | |
| 192 /* This variable may be used to pass transmit data to the driver from the | |
| 193 * implementation of usbFunctionWrite(). It is also used internally by the | |
| 194 * driver for standard control requests. | |
| 195 */ | |
| 196 USB_PUBLIC usbMsgLen_t usbFunctionSetup(uchar data[8]); | |
| 197 /* This function is called when the driver receives a SETUP transaction from | |
| 198 * the host which is not answered by the driver itself (in practice: class and | |
| 199 * vendor requests). All control transfers start with a SETUP transaction where | |
| 200 * the host communicates the parameters of the following (optional) data | |
| 201 * transfer. The SETUP data is available in the 'data' parameter which can | |
| 202 * (and should) be casted to 'usbRequest_t *' for a more user-friendly access | |
| 203 * to parameters. | |
| 204 * | |
| 205 * If the SETUP indicates a control-in transfer, you should provide the | |
| 206 * requested data to the driver. There are two ways to transfer this data: | |
| 207 * (1) Set the global pointer 'usbMsgPtr' to the base of the static RAM data | |
| 208 * block and return the length of the data in 'usbFunctionSetup()'. The driver | |
| 209 * will handle the rest. Or (2) return USB_NO_MSG in 'usbFunctionSetup()'. The | |
| 210 * driver will then call 'usbFunctionRead()' when data is needed. See the | |
| 211 * documentation for usbFunctionRead() for details. | |
| 212 * | |
| 213 * If the SETUP indicates a control-out transfer, the only way to receive the | |
| 214 * data from the host is through the 'usbFunctionWrite()' call. If you | |
| 215 * implement this function, you must return USB_NO_MSG in 'usbFunctionSetup()' | |
| 216 * to indicate that 'usbFunctionWrite()' should be used. See the documentation | |
| 217 * of this function for more information. If you just want to ignore the data | |
| 218 * sent by the host, return 0 in 'usbFunctionSetup()'. | |
| 219 * | |
| 220 * Note that calls to the functions usbFunctionRead() and usbFunctionWrite() | |
| 221 * are only done if enabled by the configuration in usbconfig.h. | |
| 222 */ | |
| 223 USB_PUBLIC usbMsgLen_t usbFunctionDescriptor(struct usbRequest *rq); | |
| 224 /* You need to implement this function ONLY if you provide USB descriptors at | |
| 225 * runtime (which is an expert feature). It is very similar to | |
| 226 * usbFunctionSetup() above, but it is called only to request USB descriptor | |
| 227 * data. See the documentation of usbFunctionSetup() above for more info. | |
| 228 */ | |
| 229 #if USB_CFG_HAVE_INTRIN_ENDPOINT | |
| 230 USB_PUBLIC void usbSetInterrupt(uchar *data, uchar len); | |
| 231 /* This function sets the message which will be sent during the next interrupt | |
| 232 * IN transfer. The message is copied to an internal buffer and must not exceed | |
| 233 * a length of 8 bytes. The message may be 0 bytes long just to indicate the | |
| 234 * interrupt status to the host. | |
| 235 * If you need to transfer more bytes, use a control read after the interrupt. | |
| 236 */ | |
| 237 #define usbInterruptIsReady() (usbTxLen1 & 0x10) | |
| 238 /* This macro indicates whether the last interrupt message has already been | |
| 239 * sent. If you set a new interrupt message before the old was sent, the | |
| 240 * message already buffered will be lost. | |
| 241 */ | |
| 242 #if USB_CFG_HAVE_INTRIN_ENDPOINT3 | |
| 243 USB_PUBLIC void usbSetInterrupt3(uchar *data, uchar len); | |
| 244 #define usbInterruptIsReady3() (usbTxLen3 & 0x10) | |
| 245 /* Same as above for endpoint 3 */ | |
| 246 #endif | |
| 247 #endif /* USB_CFG_HAVE_INTRIN_ENDPOINT */ | |
| 248 #if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH /* simplified interface for backward compatibility */ | |
| 249 #define usbHidReportDescriptor usbDescriptorHidReport | |
| 250 /* should be declared as: PROGMEM char usbHidReportDescriptor[]; */ | |
| 251 /* If you implement an HID device, you need to provide a report descriptor. | |
| 252 * The HID report descriptor syntax is a bit complex. If you understand how | |
| 253 * report descriptors are constructed, we recommend that you use the HID | |
| 254 * Descriptor Tool from usb.org, see http://www.usb.org/developers/hidpage/. | |
| 255 * Otherwise you should probably start with a working example. | |
| 256 */ | |
| 257 #endif /* USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH */ | |
| 258 #if USB_CFG_IMPLEMENT_FN_WRITE | |
| 259 USB_PUBLIC uchar usbFunctionWrite(uchar *data, uchar len); | |
| 260 /* This function is called by the driver to provide a control transfer's | |
| 261 * payload data (control-out). It is called in chunks of up to 8 bytes. The | |
| 262 * total count provided in the current control transfer can be obtained from | |
| 263 * the 'length' property in the setup data. If an error occurred during | |
| 264 * processing, return 0xff (== -1). The driver will answer the entire transfer | |
| 265 * with a STALL token in this case. If you have received the entire payload | |
| 266 * successfully, return 1. If you expect more data, return 0. If you don't | |
| 267 * know whether the host will send more data (you should know, the total is | |
| 268 * provided in the usbFunctionSetup() call!), return 1. | |
| 269 * NOTE: If you return 0xff for STALL, 'usbFunctionWrite()' may still be called | |
| 270 * for the remaining data. You must continue to return 0xff for STALL in these | |
| 271 * calls. | |
| 272 * In order to get usbFunctionWrite() called, define USB_CFG_IMPLEMENT_FN_WRITE | |
| 273 * to 1 in usbconfig.h and return 0xff in usbFunctionSetup().. | |
| 274 */ | |
| 275 #endif /* USB_CFG_IMPLEMENT_FN_WRITE */ | |
| 276 #if USB_CFG_IMPLEMENT_FN_READ | |
| 277 USB_PUBLIC uchar usbFunctionRead(uchar *data, uchar len); | |
| 278 /* This function is called by the driver to ask the application for a control | |
| 279 * transfer's payload data (control-in). It is called in chunks of up to 8 | |
| 280 * bytes each. You should copy the data to the location given by 'data' and | |
| 281 * return the actual number of bytes copied. If you return less than requested, | |
| 282 * the control-in transfer is terminated. If you return 0xff, the driver aborts | |
| 283 * the transfer with a STALL token. | |
| 284 * In order to get usbFunctionRead() called, define USB_CFG_IMPLEMENT_FN_READ | |
| 285 * to 1 in usbconfig.h and return 0xff in usbFunctionSetup().. | |
| 286 */ | |
| 287 #endif /* USB_CFG_IMPLEMENT_FN_READ */ | |
| 288 | |
| 289 extern uchar usbRxToken; /* may be used in usbFunctionWriteOut() below */ | |
| 290 #if USB_CFG_IMPLEMENT_FN_WRITEOUT | |
| 291 USB_PUBLIC void usbFunctionWriteOut(uchar *data, uchar len); | |
| 292 /* This function is called by the driver when data is received on an interrupt- | |
| 293 * or bulk-out endpoint. The endpoint number can be found in the global | |
| 294 * variable usbRxToken. You must define USB_CFG_IMPLEMENT_FN_WRITEOUT to 1 in | |
| 295 * usbconfig.h to get this function called. | |
| 296 */ | |
| 297 #endif /* USB_CFG_IMPLEMENT_FN_WRITEOUT */ | |
| 298 #ifdef USB_CFG_PULLUP_IOPORTNAME | |
| 299 #define usbDeviceConnect() ((USB_PULLUP_DDR |= (1<<USB_CFG_PULLUP_BIT)), \ | |
| 300 (USB_PULLUP_OUT |= (1<<USB_CFG_PULLUP_BIT))) | |
| 301 #define usbDeviceDisconnect() ((USB_PULLUP_DDR &= ~(1<<USB_CFG_PULLUP_BIT)), \ | |
| 302 (USB_PULLUP_OUT &= ~(1<<USB_CFG_PULLUP_BIT))) | |
| 303 #else /* USB_CFG_PULLUP_IOPORTNAME */ | |
| 304 #define usbDeviceConnect() (USBDDR &= ~(1<<USBMINUS)) | |
| 305 #define usbDeviceDisconnect() (USBDDR |= (1<<USBMINUS)) | |
| 306 #endif /* USB_CFG_PULLUP_IOPORTNAME */ | |
| 307 /* The macros usbDeviceConnect() and usbDeviceDisconnect() (intended to look | |
| 308 * like a function) connect resp. disconnect the device from the host's USB. | |
| 309 * If the constants USB_CFG_PULLUP_IOPORT and USB_CFG_PULLUP_BIT are defined | |
| 310 * in usbconfig.h, a disconnect consists of removing the pull-up resisitor | |
| 311 * from D-, otherwise the disconnect is done by brute-force pulling D- to GND. | |
| 312 * This does not conform to the spec, but it works. | |
| 313 * Please note that the USB interrupt must be disabled while the device is | |
| 314 * in disconnected state, or the interrupt handler will hang! You can either | |
| 315 * turn off the USB interrupt selectively with | |
| 316 * USB_INTR_ENABLE &= ~(1 << USB_INTR_ENABLE_BIT) | |
| 317 * or use cli() to disable interrupts globally. | |
| 318 */ | |
| 319 extern unsigned usbCrc16(unsigned data, uchar len); | |
| 320 #define usbCrc16(data, len) usbCrc16((unsigned)(data), len) | |
| 321 /* This function calculates the binary complement of the data CRC used in | |
| 322 * USB data packets. The value is used to build raw transmit packets. | |
| 323 * You may want to use this function for data checksums or to verify received | |
| 324 * data. We enforce 16 bit calling conventions for compatibility with IAR's | |
| 325 * tiny memory model. | |
| 326 */ | |
| 327 extern unsigned usbCrc16Append(unsigned data, uchar len); | |
| 328 #define usbCrc16Append(data, len) usbCrc16Append((unsigned)(data), len) | |
| 329 /* This function is equivalent to usbCrc16() above, except that it appends | |
| 330 * the 2 bytes CRC (lowbyte first) in the 'data' buffer after reading 'len' | |
| 331 * bytes. | |
| 332 */ | |
| 333 #if USB_CFG_HAVE_MEASURE_FRAME_LENGTH | |
| 334 extern unsigned usbMeasureFrameLength(void); | |
| 335 /* This function MUST be called IMMEDIATELY AFTER USB reset and measures 1/7 of | |
| 336 * the number of CPU cycles during one USB frame minus one low speed bit | |
| 337 * length. In other words: return value = 1499 * (F_CPU / 10.5 MHz) | |
| 338 * Since this is a busy wait, you MUST disable all interrupts with cli() before | |
| 339 * calling this function. | |
| 340 * This can be used to calibrate the AVR's RC oscillator. | |
| 341 */ | |
| 342 #endif | |
| 343 extern uchar usbConfiguration; | |
| 344 /* This value contains the current configuration set by the host. The driver | |
| 345 * allows setting and querying of this variable with the USB SET_CONFIGURATION | |
| 346 * and GET_CONFIGURATION requests, but does not use it otherwise. | |
| 347 * You may want to reflect the "configured" status with a LED on the device or | |
| 348 * switch on high power parts of the circuit only if the device is configured. | |
| 349 */ | |
| 350 #if USB_COUNT_SOF | |
| 351 extern volatile uchar usbSofCount; | |
| 352 /* This variable is incremented on every SOF packet. It is only available if | |
| 353 * the macro USB_COUNT_SOF is defined to a value != 0. | |
| 354 */ | |
| 355 #endif | |
| 356 #if USB_CFG_CHECK_DATA_TOGGLING | |
| 357 extern uchar usbCurrentDataToken; | |
| 358 /* This variable can be checked in usbFunctionWrite() and usbFunctionWriteOut() | |
| 359 * to ignore duplicate packets. | |
| 360 */ | |
| 361 #endif | |
| 362 | |
| 363 #define USB_STRING_DESCRIPTOR_HEADER(stringLength) ((2*(stringLength)+2) | (3<<8)) | |
| 364 /* This macro builds a descriptor header for a string descriptor given the | |
| 365 * string's length. See usbdrv.c for an example how to use it. | |
| 366 */ | |
| 367 #if USB_CFG_HAVE_FLOWCONTROL | |
| 368 extern volatile schar usbRxLen; | |
| 369 #define usbDisableAllRequests() usbRxLen = -1 | |
| 370 /* Must be called from usbFunctionWrite(). This macro disables all data input | |
| 371 * from the USB interface. Requests from the host are answered with a NAK | |
| 372 * while they are disabled. | |
| 373 */ | |
| 374 #define usbEnableAllRequests() usbRxLen = 0 | |
| 375 /* May only be called if requests are disabled. This macro enables input from | |
| 376 * the USB interface after it has been disabled with usbDisableAllRequests(). | |
| 377 */ | |
| 378 #define usbAllRequestsAreDisabled() (usbRxLen < 0) | |
| 379 /* Use this macro to find out whether requests are disabled. It may be needed | |
| 380 * to ensure that usbEnableAllRequests() is never called when requests are | |
| 381 * enabled. | |
| 382 */ | |
| 383 #endif | |
| 384 | |
| 385 #define USB_SET_DATATOKEN1(token) usbTxBuf1[0] = token | |
| 386 #define USB_SET_DATATOKEN3(token) usbTxBuf3[0] = token | |
| 387 /* These two macros can be used by application software to reset data toggling | |
| 388 * for interrupt-in endpoints 1 and 3. Since the token is toggled BEFORE | |
| 389 * sending data, you must set the opposite value of the token which should come | |
| 390 * first. | |
| 391 */ | |
| 392 | |
| 393 #endif /* __ASSEMBLER__ */ | |
| 394 | |
| 395 | |
| 396 /* ------------------------------------------------------------------------- */ | |
| 397 /* ----------------- Definitions for Descriptor Properties ----------------- */ | |
| 398 /* ------------------------------------------------------------------------- */ | |
| 399 /* This is advanced stuff. See usbconfig-prototype.h for more information | |
| 400 * about the various methods to define USB descriptors. If you do nothing, | |
| 401 * the default descriptors will be used. | |
| 402 */ | |
| 403 #define USB_PROP_IS_DYNAMIC (1u << 14) | |
| 404 /* If this property is set for a descriptor, usbFunctionDescriptor() will be | |
| 405 * used to obtain the particular descriptor. Data directly returned via | |
| 406 * usbMsgPtr are FLASH data by default, combine (OR) with USB_PROP_IS_RAM to | |
| 407 * return RAM data. | |
| 408 */ | |
| 409 #define USB_PROP_IS_RAM (1u << 15) | |
| 410 /* If this property is set for a descriptor, the data is read from RAM | |
| 411 * memory instead of Flash. The property is used for all methods to provide | |
| 412 * external descriptors. | |
| 413 */ | |
| 414 #define USB_PROP_LENGTH(len) ((len) & 0x3fff) | |
| 415 /* If a static external descriptor is used, this is the total length of the | |
| 416 * descriptor in bytes. | |
| 417 */ | |
| 418 | |
| 419 /* all descriptors which may have properties: */ | |
| 420 #ifndef USB_CFG_DESCR_PROPS_DEVICE | |
| 421 #define USB_CFG_DESCR_PROPS_DEVICE 0 | |
| 422 #endif | |
| 423 #ifndef USB_CFG_DESCR_PROPS_CONFIGURATION | |
| 424 #define USB_CFG_DESCR_PROPS_CONFIGURATION 0 | |
| 425 #endif | |
| 426 #ifndef USB_CFG_DESCR_PROPS_STRINGS | |
| 427 #define USB_CFG_DESCR_PROPS_STRINGS 0 | |
| 428 #endif | |
| 429 #ifndef USB_CFG_DESCR_PROPS_STRING_0 | |
| 430 #define USB_CFG_DESCR_PROPS_STRING_0 0 | |
| 431 #endif | |
| 432 #ifndef USB_CFG_DESCR_PROPS_STRING_VENDOR | |
| 433 #define USB_CFG_DESCR_PROPS_STRING_VENDOR 0 | |
| 434 #endif | |
| 435 #ifndef USB_CFG_DESCR_PROPS_STRING_PRODUCT | |
| 436 #define USB_CFG_DESCR_PROPS_STRING_PRODUCT 0 | |
| 437 #endif | |
| 438 #ifndef USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER | |
| 439 #define USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER 0 | |
| 440 #endif | |
| 441 #ifndef USB_CFG_DESCR_PROPS_HID | |
| 442 #define USB_CFG_DESCR_PROPS_HID 0 | |
| 443 #endif | |
| 444 #if !(USB_CFG_DESCR_PROPS_HID_REPORT) | |
| 445 # undef USB_CFG_DESCR_PROPS_HID_REPORT | |
| 446 # if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH /* do some backward compatibility tricks */ | |
| 447 # define USB_CFG_DESCR_PROPS_HID_REPORT USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH | |
| 448 # else | |
| 449 # define USB_CFG_DESCR_PROPS_HID_REPORT 0 | |
| 450 # endif | |
| 451 #endif | |
| 452 #ifndef USB_CFG_DESCR_PROPS_UNKNOWN | |
| 453 #define USB_CFG_DESCR_PROPS_UNKNOWN 0 | |
| 454 #endif | |
| 455 | |
| 456 /* ------------------ forward declaration of descriptors ------------------- */ | |
| 457 /* If you use external static descriptors, they must be stored in global | |
| 458 * arrays as declared below: | |
| 459 */ | |
| 460 #ifndef __ASSEMBLER__ | |
| 461 extern | |
| 462 #if !(USB_CFG_DESCR_PROPS_DEVICE & USB_PROP_IS_RAM) | |
| 463 PROGMEM const | |
| 464 #endif | |
| 465 char usbDescriptorDevice[]; | |
| 466 | |
| 467 extern | |
| 468 #if !(USB_CFG_DESCR_PROPS_CONFIGURATION & USB_PROP_IS_RAM) | |
| 469 PROGMEM const | |
| 470 #endif | |
| 471 char usbDescriptorConfiguration[]; | |
| 472 | |
| 473 extern | |
| 474 #if !(USB_CFG_DESCR_PROPS_HID_REPORT & USB_PROP_IS_RAM) | |
| 475 PROGMEM const | |
| 476 #endif | |
| 477 char usbDescriptorHidReport[]; | |
| 478 | |
| 479 extern | |
| 480 #if !(USB_CFG_DESCR_PROPS_STRING_0 & USB_PROP_IS_RAM) | |
| 481 PROGMEM const | |
| 482 #endif | |
| 483 char usbDescriptorString0[]; | |
| 484 | |
| 485 extern | |
| 486 #if !(USB_CFG_DESCR_PROPS_STRING_VENDOR & USB_PROP_IS_RAM) | |
| 487 PROGMEM const | |
| 488 #endif | |
| 489 int usbDescriptorStringVendor[]; | |
| 490 | |
| 491 extern | |
| 492 #if !(USB_CFG_DESCR_PROPS_STRING_PRODUCT & USB_PROP_IS_RAM) | |
| 493 PROGMEM const | |
| 494 #endif | |
| 495 int usbDescriptorStringDevice[]; | |
| 496 | |
| 497 extern | |
| 498 #if !(USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER & USB_PROP_IS_RAM) | |
| 499 PROGMEM const | |
| 500 #endif | |
| 501 int usbDescriptorStringSerialNumber[]; | |
| 502 | |
| 503 #endif /* __ASSEMBLER__ */ | |
| 504 | |
| 505 /* ------------------------------------------------------------------------- */ | |
| 506 /* ------------------------ General Purpose Macros ------------------------- */ | |
| 507 /* ------------------------------------------------------------------------- */ | |
| 508 | |
| 509 #define USB_CONCAT(a, b) a ## b | |
| 510 #define USB_CONCAT_EXPANDED(a, b) USB_CONCAT(a, b) | |
| 511 | |
| 512 #define USB_OUTPORT(name) USB_CONCAT(PORT, name) | |
| 513 #define USB_INPORT(name) USB_CONCAT(PIN, name) | |
| 514 #define USB_DDRPORT(name) USB_CONCAT(DDR, name) | |
| 515 /* The double-define trick above lets us concatenate strings which are | |
| 516 * defined by macros. | |
| 517 */ | |
| 518 | |
| 519 /* ------------------------------------------------------------------------- */ | |
| 520 /* ------------------------- Constant definitions -------------------------- */ | |
| 521 /* ------------------------------------------------------------------------- */ | |
| 522 | |
| 523 #if !defined __ASSEMBLER__ && (!defined USB_CFG_VENDOR_ID || !defined USB_CFG_DEVICE_ID) | |
| 524 #warning "You should define USB_CFG_VENDOR_ID and USB_CFG_DEVICE_ID in usbconfig.h" | |
| 525 /* If the user has not defined IDs, we default to obdev's free IDs. | |
| 526 * See USB-IDs-for-free.txt for details. | |
| 527 */ | |
| 528 #endif | |
| 529 | |
| 530 /* make sure we have a VID and PID defined, byte order is lowbyte, highbyte */ | |
| 531 #ifndef USB_CFG_VENDOR_ID | |
| 532 # define USB_CFG_VENDOR_ID 0xc0, 0x16 /* = 0x16c0 = 5824 = voti.nl */ | |
| 533 #endif | |
| 534 | |
| 535 #ifndef USB_CFG_DEVICE_ID | |
| 536 # if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH | |
| 537 # define USB_CFG_DEVICE_ID 0xdf, 0x05 /* = 0x5df = 1503, shared PID for HIDs */ | |
| 538 # elif USB_CFG_INTERFACE_CLASS == 2 | |
| 539 # define USB_CFG_DEVICE_ID 0xe1, 0x05 /* = 0x5e1 = 1505, shared PID for CDC Modems */ | |
| 540 # else | |
| 541 # define USB_CFG_DEVICE_ID 0xdc, 0x05 /* = 0x5dc = 1500, obdev's free PID */ | |
| 542 # endif | |
| 543 #endif | |
| 544 | |
| 545 /* Derive Output, Input and DataDirection ports from port names */ | |
| 546 #ifndef USB_CFG_IOPORTNAME | |
| 547 #error "You must define USB_CFG_IOPORTNAME in usbconfig.h, see usbconfig-prototype.h" | |
| 548 #endif | |
| 549 | |
| 550 #define USBOUT USB_OUTPORT(USB_CFG_IOPORTNAME) | |
| 551 #define USB_PULLUP_OUT USB_OUTPORT(USB_CFG_PULLUP_IOPORTNAME) | |
| 552 #define USBIN USB_INPORT(USB_CFG_IOPORTNAME) | |
| 553 #define USBDDR USB_DDRPORT(USB_CFG_IOPORTNAME) | |
| 554 #define USB_PULLUP_DDR USB_DDRPORT(USB_CFG_PULLUP_IOPORTNAME) | |
| 555 | |
| 556 #define USBMINUS USB_CFG_DMINUS_BIT | |
| 557 #define USBPLUS USB_CFG_DPLUS_BIT | |
| 558 #define USBIDLE (1<<USB_CFG_DMINUS_BIT) /* value representing J state */ | |
| 559 #define USBMASK ((1<<USB_CFG_DPLUS_BIT) | (1<<USB_CFG_DMINUS_BIT)) /* mask for USB I/O bits */ | |
| 560 | |
| 561 /* defines for backward compatibility with older driver versions: */ | |
| 562 #define USB_CFG_IOPORT USB_OUTPORT(USB_CFG_IOPORTNAME) | |
| 563 #ifdef USB_CFG_PULLUP_IOPORTNAME | |
| 564 #define USB_CFG_PULLUP_IOPORT USB_OUTPORT(USB_CFG_PULLUP_IOPORTNAME) | |
| 565 #endif | |
| 566 | |
| 567 #ifndef USB_CFG_EP3_NUMBER /* if not defined in usbconfig.h */ | |
| 568 #define USB_CFG_EP3_NUMBER 3 | |
| 569 #endif | |
| 570 | |
| 571 #ifndef USB_CFG_HAVE_INTRIN_ENDPOINT3 | |
| 572 #define USB_CFG_HAVE_INTRIN_ENDPOINT3 0 | |
| 573 #endif | |
| 574 | |
| 575 #define USB_BUFSIZE 11 /* PID, 8 bytes data, 2 bytes CRC */ | |
| 576 | |
| 577 /* ----- Try to find registers and bits responsible for ext interrupt 0 ----- */ | |
| 578 | |
| 579 #ifndef USB_INTR_CFG /* allow user to override our default */ | |
| 580 # if defined EICRA | |
| 581 # define USB_INTR_CFG EICRA | |
| 582 # else | |
| 583 # define USB_INTR_CFG MCUCR | |
| 584 # endif | |
| 585 #endif | |
| 586 #ifndef USB_INTR_CFG_SET /* allow user to override our default */ | |
| 587 # if defined(USB_COUNT_SOF) || defined(USB_SOF_HOOK) | |
| 588 # define USB_INTR_CFG_SET (1 << ISC01) /* cfg for falling edge */ | |
| 589 /* If any SOF logic is used, the interrupt must be wired to D- where | |
| 590 * we better trigger on falling edge | |
| 591 */ | |
| 592 # else | |
| 593 # define USB_INTR_CFG_SET ((1 << ISC00) | (1 << ISC01)) /* cfg for rising edge */ | |
| 594 # endif | |
| 595 #endif | |
| 596 #ifndef USB_INTR_CFG_CLR /* allow user to override our default */ | |
| 597 # define USB_INTR_CFG_CLR 0 /* no bits to clear */ | |
| 598 #endif | |
| 599 | |
| 600 #ifndef USB_INTR_ENABLE /* allow user to override our default */ | |
| 601 # if defined GIMSK | |
| 602 # define USB_INTR_ENABLE GIMSK | |
| 603 # elif defined EIMSK | |
| 604 # define USB_INTR_ENABLE EIMSK | |
| 605 # else | |
| 606 # define USB_INTR_ENABLE GICR | |
| 607 # endif | |
| 608 #endif | |
| 609 #ifndef USB_INTR_ENABLE_BIT /* allow user to override our default */ | |
| 610 # define USB_INTR_ENABLE_BIT INT0 | |
| 611 #endif | |
| 612 | |
| 613 #ifndef USB_INTR_PENDING /* allow user to override our default */ | |
| 614 # if defined EIFR | |
| 615 # define USB_INTR_PENDING EIFR | |
| 616 # else | |
| 617 # define USB_INTR_PENDING GIFR | |
| 618 # endif | |
| 619 #endif | |
| 620 #ifndef USB_INTR_PENDING_BIT /* allow user to override our default */ | |
| 621 # define USB_INTR_PENDING_BIT INTF0 | |
| 622 #endif | |
| 623 | |
| 624 /* | |
| 625 The defines above don't work for the following chips | |
| 626 at90c8534: no ISC0?, no PORTB, can't find a data sheet | |
| 627 at86rf401: no PORTB, no MCUCR etc, low clock rate | |
| 628 atmega103: no ISC0? (maybe omission in header, can't find data sheet) | |
| 629 atmega603: not defined in avr-libc | |
| 630 at43usb320, at43usb355, at76c711: have USB anyway | |
| 631 at94k: is different... | |
| 632 | |
| 633 at90s1200, attiny11, attiny12, attiny15, attiny28: these have no RAM | |
| 634 */ | |
| 635 | |
| 636 /* ------------------------------------------------------------------------- */ | |
| 637 /* ----------------- USB Specification Constants and Types ----------------- */ | |
| 638 /* ------------------------------------------------------------------------- */ | |
| 639 | |
| 640 /* USB Token values */ | |
| 641 #define USBPID_SETUP 0x2d | |
| 642 #define USBPID_OUT 0xe1 | |
| 643 #define USBPID_IN 0x69 | |
| 644 #define USBPID_DATA0 0xc3 | |
| 645 #define USBPID_DATA1 0x4b | |
| 646 | |
| 647 #define USBPID_ACK 0xd2 | |
| 648 #define USBPID_NAK 0x5a | |
| 649 #define USBPID_STALL 0x1e | |
| 650 | |
| 651 #ifndef USB_INITIAL_DATATOKEN | |
| 652 #define USB_INITIAL_DATATOKEN USBPID_DATA1 | |
| 653 #endif | |
| 654 | |
| 655 #ifndef __ASSEMBLER__ | |
| 656 | |
| 657 typedef struct usbTxStatus{ | |
| 658 volatile uchar len; | |
| 659 uchar buffer[USB_BUFSIZE]; | |
| 660 }usbTxStatus_t; | |
| 661 | |
| 662 extern usbTxStatus_t usbTxStatus1, usbTxStatus3; | |
| 663 #define usbTxLen1 usbTxStatus1.len | |
| 664 #define usbTxBuf1 usbTxStatus1.buffer | |
| 665 #define usbTxLen3 usbTxStatus3.len | |
| 666 #define usbTxBuf3 usbTxStatus3.buffer | |
| 667 | |
| 668 | |
| 669 typedef union usbWord{ | |
| 670 unsigned word; | |
| 671 uchar bytes[2]; | |
| 672 }usbWord_t; | |
| 673 | |
| 674 typedef struct usbRequest{ | |
| 675 uchar bmRequestType; | |
| 676 uchar bRequest; | |
| 677 usbWord_t wValue; | |
| 678 usbWord_t wIndex; | |
| 679 usbWord_t wLength; | |
| 680 }usbRequest_t; | |
| 681 /* This structure matches the 8 byte setup request */ | |
| 682 #endif | |
| 683 | |
| 684 /* bmRequestType field in USB setup: | |
| 685 * d t t r r r r r, where | |
| 686 * d ..... direction: 0=host->device, 1=device->host | |
| 687 * t ..... type: 0=standard, 1=class, 2=vendor, 3=reserved | |
| 688 * r ..... recipient: 0=device, 1=interface, 2=endpoint, 3=other | |
| 689 */ | |
| 690 | |
| 691 /* USB setup recipient values */ | |
| 692 #define USBRQ_RCPT_MASK 0x1f | |
| 693 #define USBRQ_RCPT_DEVICE 0 | |
| 694 #define USBRQ_RCPT_INTERFACE 1 | |
| 695 #define USBRQ_RCPT_ENDPOINT 2 | |
| 696 | |
| 697 /* USB request type values */ | |
| 698 #define USBRQ_TYPE_MASK 0x60 | |
| 699 #define USBRQ_TYPE_STANDARD (0<<5) | |
| 700 #define USBRQ_TYPE_CLASS (1<<5) | |
| 701 #define USBRQ_TYPE_VENDOR (2<<5) | |
| 702 | |
| 703 /* USB direction values: */ | |
| 704 #define USBRQ_DIR_MASK 0x80 | |
| 705 #define USBRQ_DIR_HOST_TO_DEVICE (0<<7) | |
| 706 #define USBRQ_DIR_DEVICE_TO_HOST (1<<7) | |
| 707 | |
| 708 /* USB Standard Requests */ | |
| 709 #define USBRQ_GET_STATUS 0 | |
| 710 #define USBRQ_CLEAR_FEATURE 1 | |
| 711 #define USBRQ_SET_FEATURE 3 | |
| 712 #define USBRQ_SET_ADDRESS 5 | |
| 713 #define USBRQ_GET_DESCRIPTOR 6 | |
| 714 #define USBRQ_SET_DESCRIPTOR 7 | |
| 715 #define USBRQ_GET_CONFIGURATION 8 | |
| 716 #define USBRQ_SET_CONFIGURATION 9 | |
| 717 #define USBRQ_GET_INTERFACE 10 | |
| 718 #define USBRQ_SET_INTERFACE 11 | |
| 719 #define USBRQ_SYNCH_FRAME 12 | |
| 720 | |
| 721 /* USB descriptor constants */ | |
| 722 #define USBDESCR_DEVICE 1 | |
| 723 #define USBDESCR_CONFIG 2 | |
| 724 #define USBDESCR_STRING 3 | |
| 725 #define USBDESCR_INTERFACE 4 | |
| 726 #define USBDESCR_ENDPOINT 5 | |
| 727 #define USBDESCR_HID 0x21 | |
| 728 #define USBDESCR_HID_REPORT 0x22 | |
| 729 #define USBDESCR_HID_PHYS 0x23 | |
| 730 | |
| 731 //#define USBATTR_BUSPOWER 0x80 // USB 1.1 does not define this value any more | |
| 732 #define USBATTR_BUSPOWER 0 | |
| 733 #define USBATTR_SELFPOWER 0x40 | |
| 734 #define USBATTR_REMOTEWAKE 0x20 | |
| 735 | |
| 736 /* USB HID Requests */ | |
| 737 #define USBRQ_HID_GET_REPORT 0x01 | |
| 738 #define USBRQ_HID_GET_IDLE 0x02 | |
| 739 #define USBRQ_HID_GET_PROTOCOL 0x03 | |
| 740 #define USBRQ_HID_SET_REPORT 0x09 | |
| 741 #define USBRQ_HID_SET_IDLE 0x0a | |
| 742 #define USBRQ_HID_SET_PROTOCOL 0x0b | |
| 743 | |
| 744 /* ------------------------------------------------------------------------- */ | |
| 745 | |
| 746 #endif /* __usbdrv_h_included__ */ |
