firmware/usbdrv/usbdrv.h

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