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