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