Rev Author Line No. Line
3471 miho 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 * This Revision: $Id: usbdrv.h 793 2010-07-15 15:58:11Z 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 have the "ISR_NOBLOCK"
109 attribute set (see "avr/interrupt.h") or be written in assembler with "sei"
110 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 20100715
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. We exepct that the PORT and DDR bits for D+ and D- have
171 * not been changed from their default status (which is 0). If you have changed
172 * them, set both back to 0 (configure them as input with no internal pull-up).
173 */
174 USB_PUBLIC void usbPoll(void);
175 /* This function must be called at regular intervals from the main loop.
176 * Maximum delay between calls is somewhat less than 50ms (USB timeout for
177 * accepting a Setup message). Otherwise the device will not be recognized.
178 * Please note that debug outputs through the UART take ~ 0.5ms per byte
179 * at 19200 bps.
180 */
181 extern uchar *usbMsgPtr;
182 /* This variable may be used to pass transmit data to the driver from the
183 * implementation of usbFunctionWrite(). It is also used internally by the
184 * driver for standard control requests.
185 */
186 USB_PUBLIC usbMsgLen_t usbFunctionSetup(uchar data[8]);
187 /* This function is called when the driver receives a SETUP transaction from
188 * the host which is not answered by the driver itself (in practice: class and
189 * vendor requests). All control transfers start with a SETUP transaction where
190 * the host communicates the parameters of the following (optional) data
191 * transfer. The SETUP data is available in the 'data' parameter which can
192 * (and should) be casted to 'usbRequest_t *' for a more user-friendly access
193 * to parameters.
194 *
195 * If the SETUP indicates a control-in transfer, you should provide the
196 * requested data to the driver. There are two ways to transfer this data:
197 * (1) Set the global pointer 'usbMsgPtr' to the base of the static RAM data
198 * block and return the length of the data in 'usbFunctionSetup()'. The driver
199 * will handle the rest. Or (2) return USB_NO_MSG in 'usbFunctionSetup()'. The
200 * driver will then call 'usbFunctionRead()' when data is needed. See the
201 * documentation for usbFunctionRead() for details.
202 *
203 * If the SETUP indicates a control-out transfer, the only way to receive the
204 * data from the host is through the 'usbFunctionWrite()' call. If you
205 * implement this function, you must return USB_NO_MSG in 'usbFunctionSetup()'
206 * to indicate that 'usbFunctionWrite()' should be used. See the documentation
207 * of this function for more information. If you just want to ignore the data
208 * sent by the host, return 0 in 'usbFunctionSetup()'.
209 *
210 * Note that calls to the functions usbFunctionRead() and usbFunctionWrite()
211 * are only done if enabled by the configuration in usbconfig.h.
212 */
213 USB_PUBLIC usbMsgLen_t usbFunctionDescriptor(struct usbRequest *rq);
214 /* You need to implement this function ONLY if you provide USB descriptors at
215 * runtime (which is an expert feature). It is very similar to
216 * usbFunctionSetup() above, but it is called only to request USB descriptor
217 * data. See the documentation of usbFunctionSetup() above for more info.
218 */
219 #if USB_CFG_HAVE_INTRIN_ENDPOINT
220 USB_PUBLIC void usbSetInterrupt(uchar *data, uchar len);
221 /* This function sets the message which will be sent during the next interrupt
222 * IN transfer. The message is copied to an internal buffer and must not exceed
223 * a length of 8 bytes. The message may be 0 bytes long just to indicate the
224 * interrupt status to the host.
225 * If you need to transfer more bytes, use a control read after the interrupt.
226 */
227 #define usbInterruptIsReady() (usbTxLen1 & 0x10)
228 /* This macro indicates whether the last interrupt message has already been
229 * sent. If you set a new interrupt message before the old was sent, the
230 * message already buffered will be lost.
231 */
232 #if USB_CFG_HAVE_INTRIN_ENDPOINT3
233 USB_PUBLIC void usbSetInterrupt3(uchar *data, uchar len);
234 #define usbInterruptIsReady3() (usbTxLen3 & 0x10)
235 /* Same as above for endpoint 3 */
236 #endif
237 #endif /* USB_CFG_HAVE_INTRIN_ENDPOINT */
238 #if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH /* simplified interface for backward compatibility */
239 #define usbHidReportDescriptor usbDescriptorHidReport
240 /* should be declared as: PROGMEM char usbHidReportDescriptor[]; */
241 /* If you implement an HID device, you need to provide a report descriptor.
242 * The HID report descriptor syntax is a bit complex. If you understand how
243 * report descriptors are constructed, we recommend that you use the HID
244 * Descriptor Tool from usb.org, see http://www.usb.org/developers/hidpage/.
245 * Otherwise you should probably start with a working example.
246 */
247 #endif /* USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH */
248 #if USB_CFG_IMPLEMENT_FN_WRITE
249 USB_PUBLIC uchar usbFunctionWrite(uchar *data, uchar len);
250 /* This function is called by the driver to provide a control transfer's
251 * payload data (control-out). It is called in chunks of up to 8 bytes. The
252 * total count provided in the current control transfer can be obtained from
253 * the 'length' property in the setup data. If an error occurred during
254 * processing, return 0xff (== -1). The driver will answer the entire transfer
255 * with a STALL token in this case. If you have received the entire payload
256 * successfully, return 1. If you expect more data, return 0. If you don't
257 * know whether the host will send more data (you should know, the total is
258 * provided in the usbFunctionSetup() call!), return 1.
259 * NOTE: If you return 0xff for STALL, 'usbFunctionWrite()' may still be called
260 * for the remaining data. You must continue to return 0xff for STALL in these
261 * calls.
262 * In order to get usbFunctionWrite() called, define USB_CFG_IMPLEMENT_FN_WRITE
263 * to 1 in usbconfig.h and return 0xff in usbFunctionSetup()..
264 */
265 #endif /* USB_CFG_IMPLEMENT_FN_WRITE */
266 #if USB_CFG_IMPLEMENT_FN_READ
267 USB_PUBLIC uchar usbFunctionRead(uchar *data, uchar len);
268 /* This function is called by the driver to ask the application for a control
269 * transfer's payload data (control-in). It is called in chunks of up to 8
270 * bytes each. You should copy the data to the location given by 'data' and
271 * return the actual number of bytes copied. If you return less than requested,
272 * the control-in transfer is terminated. If you return 0xff, the driver aborts
273 * the transfer with a STALL token.
274 * In order to get usbFunctionRead() called, define USB_CFG_IMPLEMENT_FN_READ
275 * to 1 in usbconfig.h and return 0xff in usbFunctionSetup()..
276 */
277 #endif /* USB_CFG_IMPLEMENT_FN_READ */
278  
279 extern uchar usbRxToken; /* may be used in usbFunctionWriteOut() below */
280 #if USB_CFG_IMPLEMENT_FN_WRITEOUT
281 USB_PUBLIC void usbFunctionWriteOut(uchar *data, uchar len);
282 /* This function is called by the driver when data is received on an interrupt-
283 * or bulk-out endpoint. The endpoint number can be found in the global
284 * variable usbRxToken. You must define USB_CFG_IMPLEMENT_FN_WRITEOUT to 1 in
285 * usbconfig.h to get this function called.
286 */
287 #endif /* USB_CFG_IMPLEMENT_FN_WRITEOUT */
288 #ifdef USB_CFG_PULLUP_IOPORTNAME
289 #define usbDeviceConnect() ((USB_PULLUP_DDR |= (1<<USB_CFG_PULLUP_BIT)), \
290 (USB_PULLUP_OUT |= (1<<USB_CFG_PULLUP_BIT)))
291 #define usbDeviceDisconnect() ((USB_PULLUP_DDR &= ~(1<<USB_CFG_PULLUP_BIT)), \
292 (USB_PULLUP_OUT &= ~(1<<USB_CFG_PULLUP_BIT)))
293 #else /* USB_CFG_PULLUP_IOPORTNAME */
294 #define usbDeviceConnect() (USBDDR &= ~(1<<USBMINUS))
295 #define usbDeviceDisconnect() (USBDDR |= (1<<USBMINUS))
296 #endif /* USB_CFG_PULLUP_IOPORTNAME */
297 /* The macros usbDeviceConnect() and usbDeviceDisconnect() (intended to look
298 * like a function) connect resp. disconnect the device from the host's USB.
299 * If the constants USB_CFG_PULLUP_IOPORT and USB_CFG_PULLUP_BIT are defined
300 * in usbconfig.h, a disconnect consists of removing the pull-up resisitor
301 * from D-, otherwise the disconnect is done by brute-force pulling D- to GND.
302 * This does not conform to the spec, but it works.
303 * Please note that the USB interrupt must be disabled while the device is
304 * in disconnected state, or the interrupt handler will hang! You can either
305 * turn off the USB interrupt selectively with
306 * USB_INTR_ENABLE &= ~(1 << USB_INTR_ENABLE_BIT)
307 * or use cli() to disable interrupts globally.
308 */
309 extern unsigned usbCrc16(unsigned data, uchar len);
310 #define usbCrc16(data, len) usbCrc16((unsigned)(data), len)
311 /* This function calculates the binary complement of the data CRC used in
312 * USB data packets. The value is used to build raw transmit packets.
313 * You may want to use this function for data checksums or to verify received
314 * data. We enforce 16 bit calling conventions for compatibility with IAR's
315 * tiny memory model.
316 */
317 extern unsigned usbCrc16Append(unsigned data, uchar len);
318 #define usbCrc16Append(data, len) usbCrc16Append((unsigned)(data), len)
319 /* This function is equivalent to usbCrc16() above, except that it appends
320 * the 2 bytes CRC (lowbyte first) in the 'data' buffer after reading 'len'
321 * bytes.
322 */
323 #if USB_CFG_HAVE_MEASURE_FRAME_LENGTH
324 extern unsigned usbMeasureFrameLength(void);
325 /* This function MUST be called IMMEDIATELY AFTER USB reset and measures 1/7 of
326 * the number of CPU cycles during one USB frame minus one low speed bit
327 * length. In other words: return value = 1499 * (F_CPU / 10.5 MHz)
328 * Since this is a busy wait, you MUST disable all interrupts with cli() before
329 * calling this function.
330 * This can be used to calibrate the AVR's RC oscillator.
331 */
332 #endif
333 extern uchar usbConfiguration;
334 /* This value contains the current configuration set by the host. The driver
335 * allows setting and querying of this variable with the USB SET_CONFIGURATION
336 * and GET_CONFIGURATION requests, but does not use it otherwise.
337 * You may want to reflect the "configured" status with a LED on the device or
338 * switch on high power parts of the circuit only if the device is configured.
339 */
340 #if USB_COUNT_SOF
341 extern volatile uchar usbSofCount;
342 /* This variable is incremented on every SOF packet. It is only available if
343 * the macro USB_COUNT_SOF is defined to a value != 0.
344 */
345 #endif
346 #if USB_CFG_CHECK_DATA_TOGGLING
347 extern uchar usbCurrentDataToken;
348 /* This variable can be checked in usbFunctionWrite() and usbFunctionWriteOut()
349 * to ignore duplicate packets.
350 */
351 #endif
352  
353 #define USB_STRING_DESCRIPTOR_HEADER(stringLength) ((2*(stringLength)+2) | (3<<8))
354 /* This macro builds a descriptor header for a string descriptor given the
355 * string's length. See usbdrv.c for an example how to use it.
356 */
357 #if USB_CFG_HAVE_FLOWCONTROL
358 extern volatile schar usbRxLen;
359 #define usbDisableAllRequests() usbRxLen = -1
360 /* Must be called from usbFunctionWrite(). This macro disables all data input
361 * from the USB interface. Requests from the host are answered with a NAK
362 * while they are disabled.
363 */
364 #define usbEnableAllRequests() usbRxLen = 0
365 /* May only be called if requests are disabled. This macro enables input from
366 * the USB interface after it has been disabled with usbDisableAllRequests().
367 */
368 #define usbAllRequestsAreDisabled() (usbRxLen < 0)
369 /* Use this macro to find out whether requests are disabled. It may be needed
370 * to ensure that usbEnableAllRequests() is never called when requests are
371 * enabled.
372 */
373 #endif
374  
375 #define USB_SET_DATATOKEN1(token) usbTxBuf1[0] = token
376 #define USB_SET_DATATOKEN3(token) usbTxBuf3[0] = token
377 /* These two macros can be used by application software to reset data toggling
378 * for interrupt-in endpoints 1 and 3. Since the token is toggled BEFORE
379 * sending data, you must set the opposite value of the token which should come
380 * first.
381 */
382  
383 #endif /* __ASSEMBLER__ */
384  
385  
386 /* ------------------------------------------------------------------------- */
387 /* ----------------- Definitions for Descriptor Properties ----------------- */
388 /* ------------------------------------------------------------------------- */
389 /* This is advanced stuff. See usbconfig-prototype.h for more information
390 * about the various methods to define USB descriptors. If you do nothing,
391 * the default descriptors will be used.
392 */
393 #define USB_PROP_IS_DYNAMIC (1 << 14)
394 /* If this property is set for a descriptor, usbFunctionDescriptor() will be
395 * used to obtain the particular descriptor. Data directly returned via
396 * usbMsgPtr are FLASH data by default, combine (OR) with USB_PROP_IS_RAM to
397 * return RAM data.
398 */
399 #define USB_PROP_IS_RAM (1 << 15)
400 /* If this property is set for a descriptor, the data is read from RAM
401 * memory instead of Flash. The property is used for all methods to provide
402 * external descriptors.
403 */
404 #define USB_PROP_LENGTH(len) ((len) & 0x3fff)
405 /* If a static external descriptor is used, this is the total length of the
406 * descriptor in bytes.
407 */
408  
409 /* all descriptors which may have properties: */
410 #ifndef USB_CFG_DESCR_PROPS_DEVICE
411 #define USB_CFG_DESCR_PROPS_DEVICE 0
412 #endif
413 #ifndef USB_CFG_DESCR_PROPS_CONFIGURATION
414 #define USB_CFG_DESCR_PROPS_CONFIGURATION 0
415 #endif
416 #ifndef USB_CFG_DESCR_PROPS_STRINGS
417 #define USB_CFG_DESCR_PROPS_STRINGS 0
418 #endif
419 #ifndef USB_CFG_DESCR_PROPS_STRING_0
420 #define USB_CFG_DESCR_PROPS_STRING_0 0
421 #endif
422 #ifndef USB_CFG_DESCR_PROPS_STRING_VENDOR
423 #define USB_CFG_DESCR_PROPS_STRING_VENDOR 0
424 #endif
425 #ifndef USB_CFG_DESCR_PROPS_STRING_PRODUCT
426 #define USB_CFG_DESCR_PROPS_STRING_PRODUCT 0
427 #endif
428 #ifndef USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER
429 #define USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER 0
430 #endif
431 #ifndef USB_CFG_DESCR_PROPS_HID
432 #define USB_CFG_DESCR_PROPS_HID 0
433 #endif
434 #if !(USB_CFG_DESCR_PROPS_HID_REPORT)
435 # undef USB_CFG_DESCR_PROPS_HID_REPORT
436 # if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH /* do some backward compatibility tricks */
437 # define USB_CFG_DESCR_PROPS_HID_REPORT USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH
438 # else
439 # define USB_CFG_DESCR_PROPS_HID_REPORT 0
440 # endif
441 #endif
442 #ifndef USB_CFG_DESCR_PROPS_UNKNOWN
443 #define USB_CFG_DESCR_PROPS_UNKNOWN 0
444 #endif
445  
446 /* ------------------ forward declaration of descriptors ------------------- */
447 /* If you use external static descriptors, they must be stored in global
448 * arrays as declared below:
449 */
450 #ifndef __ASSEMBLER__
451 extern
452 #if !(USB_CFG_DESCR_PROPS_DEVICE & USB_PROP_IS_RAM)
453 PROGMEM
454 #endif
455 char usbDescriptorDevice[];
456  
457 extern
458 #if !(USB_CFG_DESCR_PROPS_CONFIGURATION & USB_PROP_IS_RAM)
459 PROGMEM
460 #endif
461 char usbDescriptorConfiguration[];
462  
463 extern
464 #if !(USB_CFG_DESCR_PROPS_HID_REPORT & USB_PROP_IS_RAM)
465 PROGMEM
466 #endif
467 char usbDescriptorHidReport[];
468  
469 extern
470 #if !(USB_CFG_DESCR_PROPS_STRING_0 & USB_PROP_IS_RAM)
471 PROGMEM
472 #endif
473 char usbDescriptorString0[];
474  
475 extern
476 #if !(USB_CFG_DESCR_PROPS_STRING_VENDOR & USB_PROP_IS_RAM)
477 PROGMEM
478 #endif
479 int usbDescriptorStringVendor[];
480  
481 extern
482 #if !(USB_CFG_DESCR_PROPS_STRING_PRODUCT & USB_PROP_IS_RAM)
483 PROGMEM
484 #endif
485 int usbDescriptorStringDevice[];
486  
487 extern
488 #if !(USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER & USB_PROP_IS_RAM)
489 PROGMEM
490 #endif
491 int usbDescriptorStringSerialNumber[];
492  
493 #endif /* __ASSEMBLER__ */
494  
495 /* ------------------------------------------------------------------------- */
496 /* ------------------------ General Purpose Macros ------------------------- */
497 /* ------------------------------------------------------------------------- */
498  
499 #define USB_CONCAT(a, b) a ## b
500 #define USB_CONCAT_EXPANDED(a, b) USB_CONCAT(a, b)
501  
502 #define USB_OUTPORT(name) USB_CONCAT(PORT, name)
503 #define USB_INPORT(name) USB_CONCAT(PIN, name)
504 #define USB_DDRPORT(name) USB_CONCAT(DDR, name)
505 /* The double-define trick above lets us concatenate strings which are
506 * defined by macros.
507 */
508  
509 /* ------------------------------------------------------------------------- */
510 /* ------------------------- Constant definitions -------------------------- */
511 /* ------------------------------------------------------------------------- */
512  
513 #if !defined __ASSEMBLER__ && (!defined USB_CFG_VENDOR_ID || !defined USB_CFG_DEVICE_ID)
514 #warning "You should define USB_CFG_VENDOR_ID and USB_CFG_DEVICE_ID in usbconfig.h"
515 /* If the user has not defined IDs, we default to obdev's free IDs.
516 * See USB-IDs-for-free.txt for details.
517 */
518 #endif
519  
520 /* make sure we have a VID and PID defined, byte order is lowbyte, highbyte */
521 #ifndef USB_CFG_VENDOR_ID
522 # define USB_CFG_VENDOR_ID 0xc0, 0x16 /* = 0x16c0 = 5824 = voti.nl */
523 #endif
524  
525 #ifndef USB_CFG_DEVICE_ID
526 # if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH
527 # define USB_CFG_DEVICE_ID 0xdf, 0x05 /* = 0x5df = 1503, shared PID for HIDs */
528 # elif USB_CFG_INTERFACE_CLASS == 2
529 # define USB_CFG_DEVICE_ID 0xe1, 0x05 /* = 0x5e1 = 1505, shared PID for CDC Modems */
530 # else
531 # define USB_CFG_DEVICE_ID 0xdc, 0x05 /* = 0x5dc = 1500, obdev's free PID */
532 # endif
533 #endif
534  
535 /* Derive Output, Input and DataDirection ports from port names */
536 #ifndef USB_CFG_IOPORTNAME
537 #error "You must define USB_CFG_IOPORTNAME in usbconfig.h, see usbconfig-prototype.h"
538 #endif
539  
540 #define USBOUT USB_OUTPORT(USB_CFG_IOPORTNAME)
541 #define USB_PULLUP_OUT USB_OUTPORT(USB_CFG_PULLUP_IOPORTNAME)
542 #define USBIN USB_INPORT(USB_CFG_IOPORTNAME)
543 #define USBDDR USB_DDRPORT(USB_CFG_IOPORTNAME)
544 #define USB_PULLUP_DDR USB_DDRPORT(USB_CFG_PULLUP_IOPORTNAME)
545  
546 #define USBMINUS USB_CFG_DMINUS_BIT
547 #define USBPLUS USB_CFG_DPLUS_BIT
548 #define USBIDLE (1<<USB_CFG_DMINUS_BIT) /* value representing J state */
549 #define USBMASK ((1<<USB_CFG_DPLUS_BIT) | (1<<USB_CFG_DMINUS_BIT)) /* mask for USB I/O bits */
550  
551 /* defines for backward compatibility with older driver versions: */
552 #define USB_CFG_IOPORT USB_OUTPORT(USB_CFG_IOPORTNAME)
553 #ifdef USB_CFG_PULLUP_IOPORTNAME
554 #define USB_CFG_PULLUP_IOPORT USB_OUTPORT(USB_CFG_PULLUP_IOPORTNAME)
555 #endif
556  
557 #ifndef USB_CFG_EP3_NUMBER /* if not defined in usbconfig.h */
558 #define USB_CFG_EP3_NUMBER 3
559 #endif
560  
561 #ifndef USB_CFG_HAVE_INTRIN_ENDPOINT3
562 #define USB_CFG_HAVE_INTRIN_ENDPOINT3 0
563 #endif
564  
565 #define USB_BUFSIZE 11 /* PID, 8 bytes data, 2 bytes CRC */
566  
567 /* ----- Try to find registers and bits responsible for ext interrupt 0 ----- */
568  
569 #ifndef USB_INTR_CFG /* allow user to override our default */
570 # if defined EICRA
571 # define USB_INTR_CFG EICRA
572 # else
573 # define USB_INTR_CFG MCUCR
574 # endif
575 #endif
576 #ifndef USB_INTR_CFG_SET /* allow user to override our default */
577 # if defined(USB_COUNT_SOF) || defined(USB_SOF_HOOK)
578 # define USB_INTR_CFG_SET (1 << ISC01) /* cfg for falling edge */
579 /* If any SOF logic is used, the interrupt must be wired to D- where
580 * we better trigger on falling edge
581 */
582 # else
583 # define USB_INTR_CFG_SET ((1 << ISC00) | (1 << ISC01)) /* cfg for rising edge */
584 # endif
585 #endif
586 #ifndef USB_INTR_CFG_CLR /* allow user to override our default */
587 # define USB_INTR_CFG_CLR 0 /* no bits to clear */
588 #endif
589  
590 #ifndef USB_INTR_ENABLE /* allow user to override our default */
591 # if defined GIMSK
592 # define USB_INTR_ENABLE GIMSK
593 # elif defined EIMSK
594 # define USB_INTR_ENABLE EIMSK
595 # else
596 # define USB_INTR_ENABLE GICR
597 # endif
598 #endif
599 #ifndef USB_INTR_ENABLE_BIT /* allow user to override our default */
600 # define USB_INTR_ENABLE_BIT INT0
601 #endif
602  
603 #ifndef USB_INTR_PENDING /* allow user to override our default */
604 # if defined EIFR
605 # define USB_INTR_PENDING EIFR
606 # else
607 # define USB_INTR_PENDING GIFR
608 # endif
609 #endif
610 #ifndef USB_INTR_PENDING_BIT /* allow user to override our default */
611 # define USB_INTR_PENDING_BIT INTF0
612 #endif
613  
614 /*
615 The defines above don't work for the following chips
616 at90c8534: no ISC0?, no PORTB, can't find a data sheet
617 at86rf401: no PORTB, no MCUCR etc, low clock rate
618 atmega103: no ISC0? (maybe omission in header, can't find data sheet)
619 atmega603: not defined in avr-libc
620 at43usb320, at43usb355, at76c711: have USB anyway
621 at94k: is different...
622  
623 at90s1200, attiny11, attiny12, attiny15, attiny28: these have no RAM
624 */
625  
626 /* ------------------------------------------------------------------------- */
627 /* ----------------- USB Specification Constants and Types ----------------- */
628 /* ------------------------------------------------------------------------- */
629  
630 /* USB Token values */
631 #define USBPID_SETUP 0x2d
632 #define USBPID_OUT 0xe1
633 #define USBPID_IN 0x69
634 #define USBPID_DATA0 0xc3
635 #define USBPID_DATA1 0x4b
636  
637 #define USBPID_ACK 0xd2
638 #define USBPID_NAK 0x5a
639 #define USBPID_STALL 0x1e
640  
641 #ifndef USB_INITIAL_DATATOKEN
642 #define USB_INITIAL_DATATOKEN USBPID_DATA1
643 #endif
644  
645 #ifndef __ASSEMBLER__
646  
647 typedef struct usbTxStatus{
648 volatile uchar len;
649 uchar buffer[USB_BUFSIZE];
650 }usbTxStatus_t;
651  
652 extern usbTxStatus_t usbTxStatus1, usbTxStatus3;
653 #define usbTxLen1 usbTxStatus1.len
654 #define usbTxBuf1 usbTxStatus1.buffer
655 #define usbTxLen3 usbTxStatus3.len
656 #define usbTxBuf3 usbTxStatus3.buffer
657  
658  
659 typedef union usbWord{
660 unsigned word;
661 uchar bytes[2];
662 }usbWord_t;
663  
664 typedef struct usbRequest{
665 uchar bmRequestType;
666 uchar bRequest;
667 usbWord_t wValue;
668 usbWord_t wIndex;
669 usbWord_t wLength;
670 }usbRequest_t;
671 /* This structure matches the 8 byte setup request */
672 #endif
673  
674 /* bmRequestType field in USB setup:
675 * d t t r r r r r, where
676 * d ..... direction: 0=host->device, 1=device->host
677 * t ..... type: 0=standard, 1=class, 2=vendor, 3=reserved
678 * r ..... recipient: 0=device, 1=interface, 2=endpoint, 3=other
679 */
680  
681 /* USB setup recipient values */
682 #define USBRQ_RCPT_MASK 0x1f
683 #define USBRQ_RCPT_DEVICE 0
684 #define USBRQ_RCPT_INTERFACE 1
685 #define USBRQ_RCPT_ENDPOINT 2
686  
687 /* USB request type values */
688 #define USBRQ_TYPE_MASK 0x60
689 #define USBRQ_TYPE_STANDARD (0<<5)
690 #define USBRQ_TYPE_CLASS (1<<5)
691 #define USBRQ_TYPE_VENDOR (2<<5)
692  
693 /* USB direction values: */
694 #define USBRQ_DIR_MASK 0x80
695 #define USBRQ_DIR_HOST_TO_DEVICE (0<<7)
696 #define USBRQ_DIR_DEVICE_TO_HOST (1<<7)
697  
698 /* USB Standard Requests */
699 #define USBRQ_GET_STATUS 0
700 #define USBRQ_CLEAR_FEATURE 1
701 #define USBRQ_SET_FEATURE 3
702 #define USBRQ_SET_ADDRESS 5
703 #define USBRQ_GET_DESCRIPTOR 6
704 #define USBRQ_SET_DESCRIPTOR 7
705 #define USBRQ_GET_CONFIGURATION 8
706 #define USBRQ_SET_CONFIGURATION 9
707 #define USBRQ_GET_INTERFACE 10
708 #define USBRQ_SET_INTERFACE 11
709 #define USBRQ_SYNCH_FRAME 12
710  
711 /* USB descriptor constants */
712 #define USBDESCR_DEVICE 1
713 #define USBDESCR_CONFIG 2
714 #define USBDESCR_STRING 3
715 #define USBDESCR_INTERFACE 4
716 #define USBDESCR_ENDPOINT 5
717 #define USBDESCR_HID 0x21
718 #define USBDESCR_HID_REPORT 0x22
719 #define USBDESCR_HID_PHYS 0x23
720  
721 //#define USBATTR_BUSPOWER 0x80 // USB 1.1 does not define this value any more
722 #define USBATTR_SELFPOWER 0x40
723 #define USBATTR_REMOTEWAKE 0x20
724  
725 /* USB HID Requests */
726 #define USBRQ_HID_GET_REPORT 0x01
727 #define USBRQ_HID_GET_IDLE 0x02
728 #define USBRQ_HID_GET_PROTOCOL 0x03
729 #define USBRQ_HID_SET_REPORT 0x09
730 #define USBRQ_HID_SET_IDLE 0x0a
731 #define USBRQ_HID_SET_PROTOCOL 0x0b
732  
733 /* ------------------------------------------------------------------------- */
734  
735 #endif /* __usbdrv_h_included__ */