Rev 3332 Rev 3333
Line 1... Line 1...
1 /* Name: usbdrv.h 1 /* Name: usbdrv.h
2 * Project: AVR USB driver 2 * Project: V-USB, virtual USB port for Atmel's(r) AVR(r) microcontrollers
3 * Author: Christian Starkjohann 3 * Author: Christian Starkjohann
4 * Creation Date: 2004-12-29 4 * Creation Date: 2004-12-29
5 * Tabsize: 4 5 * Tabsize: 4
6 * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH 6 * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH
7 * License: GNU GPL v2 (see License.txt) or proprietary (CommercialLicense.txt) 7 * License: GNU GPL v2 (see License.txt), GNU GPL v3 or proprietary (CommercialLicense.txt)
8 * This Revision: $Id: usbdrv.h,v 1.2 2007/05/19 12:30:11 harbaum Exp $ -  
9 */ 8 */
10   9  
11 #ifndef __usbdrv_h_included__ 10 #ifndef __usbdrv_h_included__
12 #define __usbdrv_h_included__ 11 #define __usbdrv_h_included__
13 #include "usbconfig.h" 12 #include "usbconfig.h"
14 #include "iarcompat.h" 13 #include "usbportability.h"
15   14  
16 /* 15 /*
17 Hardware Prerequisites: 16 Hardware Prerequisites:
18 ======================= 17 =======================
19 USB lines D+ and D- MUST be wired to the same I/O port. D+ must (also) be 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
20 connected to INT0. D- requires a pullup of 1.5k to +3.5V (and the device 21 triggered by SOF packets. D- requires a pull-up of 1.5k to +3.5V (and the
21 must be powered at 3.5V) to identify as low-speed USB device. A pullup of 22 device must be powered at 3.5V) to identify as low-speed USB device. A
22 1M SHOULD be connected from D+ to +3.5V to prevent interference when no USB 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.
23 master is connected. We use D+ as interrupt source and not D- because it 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
24 does not trigger on keep-alive and RESET states. 28 USB_COUNT_SOF, you MUST use D- as an interrupt source.
25   29  
26 As a compile time option, the 1.5k pullup resistor on D- can be made 30 As a compile time option, the 1.5k pull-up resistor on D- can be made
27 switchable to allow the device to disconnect at will. See the definition of 31 switchable to allow the device to disconnect at will. See the definition of
28 usbDeviceConnect() and usbDeviceDisconnect() further down in this file. 32 usbDeviceConnect() and usbDeviceDisconnect() further down in this file.
29   33  
30 Please adapt the values in usbconfig.h according to your hardware! 34 Please adapt the values in usbconfig.h according to your hardware!
31   35  
32 The device MUST be clocked at 12 MHz. This is more than the 10 MHz allowed by 36 The device MUST be clocked at exactly 12 MHz, 15 MHz, 16 MHz or 20 MHz
33 an AT90S2313 powered at 4.5V. However, if the supply voltage to maximum clock 37 or at 12.8 MHz resp. 16.5 MHz +/- 1%. See usbconfig-prototype.h for details.
34 relation is interpolated linearly, an ATtiny2313 meets the requirement by -  
35 specification. In practice, the AT90S2313 can be overclocked and works well. -  
36   38  
37   39  
38 Limitations: 40 Limitations:
39 ============ 41 ============
40 Robustness with respect to communication errors: 42 Robustness with respect to communication errors:
Line 53... Line 55...
53 low speed USB implementation and the specification allows for 8 times the 55 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 56 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. 57 requires detection of asymmetric states at high bit rate for SE0 detection.
56   58  
57 Number of endpoints: 59 Number of endpoints:
58 The driver supports up to four endpoints: One control endpoint (endpoint 0), 60 The driver supports the following endpoints:
-   61  
-   62 - Endpoint 0, the default control endpoint.
59 two interrupt-in (or bulk-in) endpoints (endpoint 1 and 3) and one 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'.
60 interrupt-out (or bulk-out) endpoint (endpoint 1). Please note that the USB 67 - One default interrupt- or bulk-in endpoint. This endpoint is used for
61 standard forbids bulk endpoints for low speed devices! Most operating systems 68 interrupt- or bulk-in transfers which are not handled by any other endpoint.
62 allow them anyway, but the AVR will spend 90% of the CPU time in the USB 69 You must define USB_CFG_HAVE_INTRIN_ENDPOINT in order to activate this
63 interrupt polling for bulk data. 70 feature and call usbSetInterrupt() to send interrupt/bulk data.
64 By default, only the control endpoint 0 is enabled. To get the other endpoints, 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
65 define USB_CFG_HAVE_INTRIN_ENDPOINT, USB_CFG_HAVE_INTRIN_ENDPOINT3 and/or 73 number. You must define USB_CFG_HAVE_INTRIN_ENDPOINT3 in order to activate
66 USB_CFG_IMPLEMENT_FN_WRITEOUT respectively (see usbconfig-prototype.h for 74 this feature and call usbSetInterrupt3() to send interrupt/bulk data. The
-   75 endpoint number can be set with USB_CFG_EP3_NUMBER.
67 details). 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.
68   80  
69 Maximum data payload: 81 Maximum data payload:
70 Data payload of control in and out transfers may be up to 254 bytes. In order 82 Data payload of control in and out transfers may be up to 254 bytes. In order
71 to accept payload data of out transfers, you need to implement 83 to accept payload data of out transfers, you need to implement
72 'usbFunctionWrite()'. 84 'usbFunctionWrite()'.
Line 76... Line 88...
76 mode. This is not a problem for self-powered devices since they don't need 88 mode. This is not a problem for self-powered devices since they don't need
77 bus power anyway. Bus-powered devices can achieve this only by putting the 89 bus power anyway. Bus-powered devices can achieve this only by putting the
78 CPU in sleep mode. The driver does not implement suspend handling by itself. 90 CPU in sleep mode. The driver does not implement suspend handling by itself.
79 However, the application may implement activity monitoring and wakeup from 91 However, the application may implement activity monitoring and wakeup from
80 sleep. The host sends regular SE0 states on the bus to keep it active. These 92 sleep. The host sends regular SE0 states on the bus to keep it active. These
81 SE0 states can be detected by wiring the INT1 pin to D-. It is not necessary 93 SE0 states can be detected by using D- as the interrupt source. Define
82 to enable the interrupt, checking the interrupt pending flag should suffice. -  
83 Before entering sleep mode, the application should enable INT1 for a wakeup 94 USB_COUNT_SOF to 1 and use the global variable usbSofCount to check for bus
84 on the next bus activity. 95 activity.
85   96  
86 Operation without an USB master: 97 Operation without an USB master:
87 The driver behaves neutral without connection to an USB master if D- reads 98 The driver behaves neutral without connection to an USB master if D- reads
88 as 1. To avoid spurious interrupts, we recommend a high impedance (e.g. 1M) 99 as 1. To avoid spurious interrupts, we recommend a high impedance (e.g. 1M)
-   100 pull-down or pull-up resistor on D+ (interrupt). If Zener diodes are used,
89 pullup resistor on D+. If D- becomes statically 0, the driver may block in 101 use a pull-down. If D- becomes statically 0, the driver may block in the
90 the interrupt routine. 102 interrupt routine.
91   103  
92 Interrupt latency: 104 Interrupt latency:
93 The application must ensure that the USB interrupt is not disabled for more 105 The application must ensure that the USB interrupt is not disabled for more
-   106 than 25 cycles (this is for 12 MHz, faster clocks allow longer latency).
94 than 20 cycles. This implies that all interrupt routines must either be 107 This implies that all interrupt routines must either have the "ISR_NOBLOCK"
95 declared as "INTERRUPT" instead of "SIGNAL" (see "avr/signal.h") or that they 108 attribute set (see "avr/interrupt.h") or be written in assembler with "sei"
96 are written in assembler with "sei" as the first instruction. 109 as the first instruction.
97   110  
98 Maximum interrupt duration / CPU cycle consumption: 111 Maximum interrupt duration / CPU cycle consumption:
99 The driver handles all USB communication during the interrupt service 112 The driver handles all USB communication during the interrupt service
100 routine. The routine will not return before an entire USB message is received 113 routine. The routine will not return before an entire USB message is received
101 and the reply is sent. This may be up to ca. 1200 cycles = 100us if the host 114 and the reply is sent. This may be up to ca. 1200 cycles @ 12 MHz (= 100us) if
102 conforms to the standard. The driver will consume CPU cycles for all USB 115 the host conforms to the standard. The driver will consume CPU cycles for all
103 messages, even if they address another (low-speed) device on the same bus. 116 USB messages, even if they address another (low-speed) device on the same bus.
104   117  
105 */ 118 */
106   119  
107 /* ------------------------------------------------------------------------- */ 120 /* ------------------------------------------------------------------------- */
108 /* --------------------------- Module Interface ---------------------------- */ 121 /* --------------------------- Module Interface ---------------------------- */
109 /* ------------------------------------------------------------------------- */ 122 /* ------------------------------------------------------------------------- */
110   123  
111 #define USBDRV_VERSION 20070319 124 #define USBDRV_VERSION 20121206
112 /* This define uniquely identifies a driver version. It is a decimal number 125 /* This define uniquely identifies a driver version. It is a decimal number
113 * constructed from the driver's release date in the form YYYYMMDD. If the 126 * constructed from the driver's release date in the form YYYYMMDD. If the
114 * driver's behavior or interface changes, you can use this constant to 127 * driver's behavior or interface changes, you can use this constant to
115 * distinguish versions. If it is not defined, the driver's release date is 128 * distinguish versions. If it is not defined, the driver's release date is
116 * older than 2006-01-25. 129 * older than 2006-01-25.
117 */ 130 */
118   131  
119 #ifndef __ASSEMBLER__ -  
120   132  
-   133 #ifndef USB_PUBLIC
-   134 #define USB_PUBLIC
-   135 #endif
-   136 /* USB_PUBLIC is used as declaration attribute for all functions exported by
-   137 * the USB driver. The default is no attribute (see above). You may define it
-   138 * to static either in usbconfig.h or from the command line if you include
-   139 * usbdrv.c instead of linking against it. Including the C module of the driver
-   140 * directly in your code saves a couple of bytes in flash memory.
-   141 */
-   142  
-   143 #ifndef __ASSEMBLER__
121 #ifndef uchar 144 #ifndef uchar
122 #define uchar unsigned char 145 #define uchar unsigned char
123 #endif 146 #endif
124 #ifndef schar 147 #ifndef schar
125 #define schar signed char 148 #define schar signed char
126 #endif 149 #endif
127 /* shortcuts for well defined 8 bit integer types */ 150 /* shortcuts for well defined 8 bit integer types */
128   151  
-   152 #if USB_CFG_LONG_TRANSFERS /* if more than 254 bytes transfer size required */
-   153 # define usbMsgLen_t unsigned
-   154 #else
-   155 # define usbMsgLen_t uchar
-   156 #endif
-   157 /* usbMsgLen_t is the data type used for transfer lengths. By default, it is
-   158 * defined to uchar, allowing a maximum of 254 bytes (255 is reserved for
-   159 * USB_NO_MSG below). If the usbconfig.h defines USB_CFG_LONG_TRANSFERS to 1,
-   160 * a 16 bit data type is used, allowing up to 16384 bytes (the rest is used
-   161 * for flags in the descriptor configuration).
-   162 */
-   163 #define USB_NO_MSG ((usbMsgLen_t)-1) /* constant meaning "no message" */
-   164  
-   165 #ifndef usbMsgPtr_t
-   166 #define usbMsgPtr_t uchar *
-   167 #endif
-   168 /* Making usbMsgPtr_t a define allows the user of this library to define it to
-   169 * an 8 bit type on tiny devices. This reduces code size, especially if the
-   170 * compiler supports a tiny memory model.
-   171 * The type can be a pointer or scalar type, casts are made where necessary.
-   172 * Although it's paradoxical, Gcc 4 generates slightly better code for scalar
-   173 * types than for pointers.
-   174 */
-   175  
129 struct usbRequest; /* forward declaration */ 176 struct usbRequest; /* forward declaration */
130   177  
131 extern void usbInit(void); 178 USB_PUBLIC void usbInit(void);
132 /* This function must be called before interrupts are enabled and the main 179 /* This function must be called before interrupts are enabled and the main
133 * loop is entered. 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).
134 */ 183 */
135 extern void usbPoll(void); 184 USB_PUBLIC void usbPoll(void);
136 /* This function must be called at regular intervals from the main loop. 185 /* This function must be called at regular intervals from the main loop.
137 * Maximum delay between calls is somewhat less than 50ms (USB timeout for 186 * Maximum delay between calls is somewhat less than 50ms (USB timeout for
138 * accepting a Setup message). Otherwise the device will not be recognized. 187 * accepting a Setup message). Otherwise the device will not be recognized.
139 * Please note that debug outputs through the UART take ~ 0.5ms per byte 188 * Please note that debug outputs through the UART take ~ 0.5ms per byte
140 * at 19200 bps. 189 * at 19200 bps.
141 */ 190 */
142 extern uchar *usbMsgPtr; 191 extern usbMsgPtr_t usbMsgPtr;
143 /* This variable may be used to pass transmit data to the driver from the 192 /* This variable may be used to pass transmit data to the driver from the
144 * implementation of usbFunctionWrite(). It is also used internally by the 193 * implementation of usbFunctionWrite(). It is also used internally by the
145 * driver for standard control requests. 194 * driver for standard control requests.
146 */ 195 */
147 extern uchar usbFunctionSetup(uchar data[8]); 196 USB_PUBLIC usbMsgLen_t usbFunctionSetup(uchar data[8]);
148 /* This function is called when the driver receives a SETUP transaction from 197 /* This function is called when the driver receives a SETUP transaction from
149 * the host which is not answered by the driver itself (in practice: class and 198 * the host which is not answered by the driver itself (in practice: class and
150 * vendor requests). All control transfers start with a SETUP transaction where 199 * vendor requests). All control transfers start with a SETUP transaction where
151 * the host communicates the parameters of the following (optional) data 200 * the host communicates the parameters of the following (optional) data
152 * transfer. The SETUP data is available in the 'data' parameter which can 201 * transfer. The SETUP data is available in the 'data' parameter which can
Line 155... Line 204...
155 * 204 *
156 * If the SETUP indicates a control-in transfer, you should provide the 205 * If the SETUP indicates a control-in transfer, you should provide the
157 * requested data to the driver. There are two ways to transfer this data: 206 * requested data to the driver. There are two ways to transfer this data:
158 * (1) Set the global pointer 'usbMsgPtr' to the base of the static RAM data 207 * (1) Set the global pointer 'usbMsgPtr' to the base of the static RAM data
159 * block and return the length of the data in 'usbFunctionSetup()'. The driver 208 * block and return the length of the data in 'usbFunctionSetup()'. The driver
160 * will handle the rest. Or (2) return 0xff in 'usbFunctionSetup()'. The driver 209 * will handle the rest. Or (2) return USB_NO_MSG in 'usbFunctionSetup()'. The
161 * will then call 'usbFunctionRead()' when data is needed. See the 210 * driver will then call 'usbFunctionRead()' when data is needed. See the
162 * documentation for usbFunctionRead() for details. 211 * documentation for usbFunctionRead() for details.
163 * 212 *
164 * If the SETUP indicates a control-out transfer, the only way to receive the 213 * If the SETUP indicates a control-out transfer, the only way to receive the
165 * data from the host is through the 'usbFunctionWrite()' call. If you 214 * data from the host is through the 'usbFunctionWrite()' call. If you
166 * implement this function, you must return 0xff in 'usbFunctionSetup()' to 215 * implement this function, you must return USB_NO_MSG in 'usbFunctionSetup()'
167 * indicate that 'usbFunctionWrite()' should be used. See the documentation of 216 * to indicate that 'usbFunctionWrite()' should be used. See the documentation
168 * this function for more information. If you just want to ignore the data sent 217 * of this function for more information. If you just want to ignore the data
169 * by the host, return 0 in 'usbFunctionSetup()'. 218 * sent by the host, return 0 in 'usbFunctionSetup()'.
170 * 219 *
171 * Note that calls to the functions usbFunctionRead() and usbFunctionWrite() 220 * Note that calls to the functions usbFunctionRead() and usbFunctionWrite()
172 * are only done if enabled by the configuration in usbconfig.h. 221 * are only done if enabled by the configuration in usbconfig.h.
173 */ 222 */
174 extern uchar usbFunctionDescriptor(struct usbRequest *rq); 223 USB_PUBLIC usbMsgLen_t usbFunctionDescriptor(struct usbRequest *rq);
175 /* You need to implement this function ONLY if you provide USB descriptors at 224 /* You need to implement this function ONLY if you provide USB descriptors at
176 * runtime (which is an expert feature). It is very similar to 225 * runtime (which is an expert feature). It is very similar to
177 * usbFunctionSetup() above, but it is called only to request USB descriptor 226 * usbFunctionSetup() above, but it is called only to request USB descriptor
178 * data. See the documentation of usbFunctionSetup() above for more info. 227 * data. See the documentation of usbFunctionSetup() above for more info.
179 */ 228 */
180 #if USB_CFG_HAVE_INTRIN_ENDPOINT 229 #if USB_CFG_HAVE_INTRIN_ENDPOINT
181 void usbSetInterrupt(uchar *data, uchar len); 230 USB_PUBLIC void usbSetInterrupt(uchar *data, uchar len);
182 /* This function sets the message which will be sent during the next interrupt 231 /* This function sets the message which will be sent during the next interrupt
183 * IN transfer. The message is copied to an internal buffer and must not exceed 232 * IN transfer. The message is copied to an internal buffer and must not exceed
184 * a length of 8 bytes. The message may be 0 bytes long just to indicate the 233 * a length of 8 bytes. The message may be 0 bytes long just to indicate the
185 * interrupt status to the host. 234 * interrupt status to the host.
186 * If you need to transfer more bytes, use a control read after the interrupt. 235 * If you need to transfer more bytes, use a control read after the interrupt.
187 */ 236 */
188 extern volatile uchar usbTxLen1; -  
189 #define usbInterruptIsReady() (usbTxLen1 & 0x10) 237 #define usbInterruptIsReady() (usbTxLen1 & 0x10)
190 /* This macro indicates whether the last interrupt message has already been 238 /* This macro indicates whether the last interrupt message has already been
191 * sent. If you set a new interrupt message before the old was sent, the 239 * sent. If you set a new interrupt message before the old was sent, the
192 * message already buffered will be lost. 240 * message already buffered will be lost.
193 */ 241 */
194 #if USB_CFG_HAVE_INTRIN_ENDPOINT3 242 #if USB_CFG_HAVE_INTRIN_ENDPOINT3
195 void usbSetInterrupt3(uchar *data, uchar len); 243 USB_PUBLIC void usbSetInterrupt3(uchar *data, uchar len);
196 extern volatile uchar usbTxLen3; -  
197 #define usbInterruptIsReady3() (usbTxLen3 & 0x10) 244 #define usbInterruptIsReady3() (usbTxLen3 & 0x10)
198 /* Same as above for endpoint 3 */ 245 /* Same as above for endpoint 3 */
199 #endif 246 #endif
200 #endif /* USB_CFG_HAVE_INTRIN_ENDPOINT */ 247 #endif /* USB_CFG_HAVE_INTRIN_ENDPOINT */
201 #if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH /* simplified interface for backward compatibility */ 248 #if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH /* simplified interface for backward compatibility */
Line 207... Line 254...
207 * Descriptor Tool from usb.org, see http://www.usb.org/developers/hidpage/. 254 * Descriptor Tool from usb.org, see http://www.usb.org/developers/hidpage/.
208 * Otherwise you should probably start with a working example. 255 * Otherwise you should probably start with a working example.
209 */ 256 */
210 #endif /* USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH */ 257 #endif /* USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH */
211 #if USB_CFG_IMPLEMENT_FN_WRITE 258 #if USB_CFG_IMPLEMENT_FN_WRITE
212 extern uchar usbFunctionWrite(uchar *data, uchar len); 259 USB_PUBLIC uchar usbFunctionWrite(uchar *data, uchar len);
213 /* This function is called by the driver to provide a control transfer's 260 /* This function is called by the driver to provide a control transfer's
214 * payload data (control-out). It is called in chunks of up to 8 bytes. The 261 * payload data (control-out). It is called in chunks of up to 8 bytes. The
215 * total count provided in the current control transfer can be obtained from 262 * total count provided in the current control transfer can be obtained from
216 * the 'length' property in the setup data. If an error occurred during 263 * the 'length' property in the setup data. If an error occurred during
217 * processing, return 0xff (== -1). The driver will answer the entire transfer 264 * processing, return 0xff (== -1). The driver will answer the entire transfer
Line 225... Line 272...
225 * In order to get usbFunctionWrite() called, define USB_CFG_IMPLEMENT_FN_WRITE 272 * In order to get usbFunctionWrite() called, define USB_CFG_IMPLEMENT_FN_WRITE
226 * to 1 in usbconfig.h and return 0xff in usbFunctionSetup().. 273 * to 1 in usbconfig.h and return 0xff in usbFunctionSetup()..
227 */ 274 */
228 #endif /* USB_CFG_IMPLEMENT_FN_WRITE */ 275 #endif /* USB_CFG_IMPLEMENT_FN_WRITE */
229 #if USB_CFG_IMPLEMENT_FN_READ 276 #if USB_CFG_IMPLEMENT_FN_READ
230 extern uchar usbFunctionRead(uchar *data, uchar len); 277 USB_PUBLIC uchar usbFunctionRead(uchar *data, uchar len);
231 /* This function is called by the driver to ask the application for a control 278 /* This function is called by the driver to ask the application for a control
232 * transfer's payload data (control-in). It is called in chunks of up to 8 279 * transfer's payload data (control-in). It is called in chunks of up to 8
233 * bytes each. You should copy the data to the location given by 'data' and 280 * bytes each. You should copy the data to the location given by 'data' and
234 * return the actual number of bytes copied. If you return less than requested, 281 * return the actual number of bytes copied. If you return less than requested,
235 * the control-in transfer is terminated. If you return 0xff, the driver aborts 282 * the control-in transfer is terminated. If you return 0xff, the driver aborts
236 * the transfer with a STALL token. 283 * the transfer with a STALL token.
237 * In order to get usbFunctionRead() called, define USB_CFG_IMPLEMENT_FN_READ 284 * In order to get usbFunctionRead() called, define USB_CFG_IMPLEMENT_FN_READ
238 * to 1 in usbconfig.h and return 0xff in usbFunctionSetup().. 285 * to 1 in usbconfig.h and return 0xff in usbFunctionSetup()..
239 */ 286 */
240 #endif /* USB_CFG_IMPLEMENT_FN_READ */ 287 #endif /* USB_CFG_IMPLEMENT_FN_READ */
-   288  
-   289 extern uchar usbRxToken; /* may be used in usbFunctionWriteOut() below */
241 #if USB_CFG_IMPLEMENT_FN_WRITEOUT 290 #if USB_CFG_IMPLEMENT_FN_WRITEOUT
242 extern void usbFunctionWriteOut(uchar *data, uchar len); 291 USB_PUBLIC void usbFunctionWriteOut(uchar *data, uchar len);
243 /* This function is called by the driver when data on interrupt-out or bulk- 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
244 * out endpoint 1 is received. You must define USB_CFG_IMPLEMENT_FN_WRITEOUT 294 * variable usbRxToken. You must define USB_CFG_IMPLEMENT_FN_WRITEOUT to 1 in
245 * to 1 in usbconfig.h to get this function called. 295 * usbconfig.h to get this function called.
246 */ 296 */
247 #endif /* USB_CFG_IMPLEMENT_FN_WRITEOUT */ 297 #endif /* USB_CFG_IMPLEMENT_FN_WRITEOUT */
248 #ifdef USB_CFG_PULLUP_IOPORTNAME 298 #ifdef USB_CFG_PULLUP_IOPORTNAME
249 #define usbDeviceConnect() ((USB_PULLUP_DDR |= (1<<USB_CFG_PULLUP_BIT)), \ 299 #define usbDeviceConnect() ((USB_PULLUP_DDR |= (1<<USB_CFG_PULLUP_BIT)), \
250 (USB_PULLUP_OUT |= (1<<USB_CFG_PULLUP_BIT))) 300 (USB_PULLUP_OUT |= (1<<USB_CFG_PULLUP_BIT)))
251 /* This macro (intended to look like a function) connects the device to the -  
252 * USB bus. It is only available if you have defined the constants -  
253 * USB_CFG_PULLUP_IOPORT and USB_CFG_PULLUP_BIT in usbconfig.h. -  
254 */ -  
255 #define usbDeviceDisconnect() ((USB_PULLUP_DDR &= ~(1<<USB_CFG_PULLUP_BIT)), \ 301 #define usbDeviceDisconnect() ((USB_PULLUP_DDR &= ~(1<<USB_CFG_PULLUP_BIT)), \
256 (USB_PULLUP_OUT &= ~(1<<USB_CFG_PULLUP_BIT))) 302 (USB_PULLUP_OUT &= ~(1<<USB_CFG_PULLUP_BIT)))
-   303 #else /* USB_CFG_PULLUP_IOPORTNAME */
-   304 #define usbDeviceConnect() (USBDDR &= ~(1<<USBMINUS))
-   305 #define usbDeviceDisconnect() (USBDDR |= (1<<USBMINUS))
-   306 #endif /* USB_CFG_PULLUP_IOPORTNAME */
257 /* This macro (intended to look like a function) disconnects the device from 307 /* The macros usbDeviceConnect() and usbDeviceDisconnect() (intended to look
258 * the USB bus. It is only available if you have defined the constants 308 * like a function) connect resp. disconnect the device from the host's USB.
259 * USB_CFG_PULLUP_IOPORT and USB_CFG_PULLUP_BIT in usbconfig.h. 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.
260 */ 318 */
261 #endif /* USB_CFG_PULLUP_IOPORT */ -  
262 extern unsigned usbCrc16(unsigned data, uchar len); 319 extern unsigned usbCrc16(unsigned data, uchar len);
263 #define usbCrc16(data, len) usbCrc16((unsigned)(data), len) 320 #define usbCrc16(data, len) usbCrc16((unsigned)(data), len)
264 /* This function calculates the binary complement of the data CRC used in 321 /* This function calculates the binary complement of the data CRC used in
265 * USB data packets. The value is used to build raw transmit packets. 322 * USB data packets. The value is used to build raw transmit packets.
266 * You may want to use this function for data checksums or to verify received 323 * You may want to use this function for data checksums or to verify received
Line 271... Line 328...
271 #define usbCrc16Append(data, len) usbCrc16Append((unsigned)(data), len) 328 #define usbCrc16Append(data, len) usbCrc16Append((unsigned)(data), len)
272 /* This function is equivalent to usbCrc16() above, except that it appends 329 /* This function is equivalent to usbCrc16() above, except that it appends
273 * the 2 bytes CRC (lowbyte first) in the 'data' buffer after reading 'len' 330 * the 2 bytes CRC (lowbyte first) in the 'data' buffer after reading 'len'
274 * bytes. 331 * bytes.
275 */ 332 */
-   333 #if USB_CFG_HAVE_MEASURE_FRAME_LENGTH
-   334 extern unsigned usbMeasureFrameLength(void);
-   335 /* This function MUST be called IMMEDIATELY AFTER USB reset and measures 1/7 of
-   336 * the number of CPU cycles during one USB frame minus one low speed bit
-   337 * length. In other words: return value = 1499 * (F_CPU / 10.5 MHz)
-   338 * Since this is a busy wait, you MUST disable all interrupts with cli() before
-   339 * calling this function.
-   340 * This can be used to calibrate the AVR's RC oscillator.
-   341 */
-   342 #endif
276 extern uchar usbConfiguration; 343 extern uchar usbConfiguration;
277 /* This value contains the current configuration set by the host. The driver 344 /* This value contains the current configuration set by the host. The driver
278 * allows setting and querying of this variable with the USB SET_CONFIGURATION 345 * allows setting and querying of this variable with the USB SET_CONFIGURATION
279 * and GET_CONFIGURATION requests, but does not use it otherwise. 346 * and GET_CONFIGURATION requests, but does not use it otherwise.
280 * You may want to reflect the "configured" status with a LED on the device or 347 * You may want to reflect the "configured" status with a LED on the device or
281 * switch on high power parts of the circuit only if the device is configured. 348 * switch on high power parts of the circuit only if the device is configured.
282 */ 349 */
-   350 #if USB_COUNT_SOF
-   351 extern volatile uchar usbSofCount;
-   352 /* This variable is incremented on every SOF packet. It is only available if
-   353 * the macro USB_COUNT_SOF is defined to a value != 0.
-   354 */
-   355 #endif
-   356 #if USB_CFG_CHECK_DATA_TOGGLING
-   357 extern uchar usbCurrentDataToken;
-   358 /* This variable can be checked in usbFunctionWrite() and usbFunctionWriteOut()
-   359 * to ignore duplicate packets.
-   360 */
-   361 #endif
-   362  
283 #define USB_STRING_DESCRIPTOR_HEADER(stringLength) ((2*(stringLength)+2) | (3<<8)) 363 #define USB_STRING_DESCRIPTOR_HEADER(stringLength) ((2*(stringLength)+2) | (3<<8))
284 /* This macro builds a descriptor header for a string descriptor given the 364 /* This macro builds a descriptor header for a string descriptor given the
285 * string's length. See usbdrv.c for an example how to use it. 365 * string's length. See usbdrv.c for an example how to use it.
286 */ 366 */
287 #if USB_CFG_HAVE_FLOWCONTROL 367 #if USB_CFG_HAVE_FLOWCONTROL
Line 303... Line 383...
303 #endif 383 #endif
304   384  
305 #define USB_SET_DATATOKEN1(token) usbTxBuf1[0] = token 385 #define USB_SET_DATATOKEN1(token) usbTxBuf1[0] = token
306 #define USB_SET_DATATOKEN3(token) usbTxBuf3[0] = token 386 #define USB_SET_DATATOKEN3(token) usbTxBuf3[0] = token
307 /* These two macros can be used by application software to reset data toggling 387 /* These two macros can be used by application software to reset data toggling
308 * for interrupt-in endpoints 1 and 3. 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.
309 */ 391 */
310   392  
311 #endif /* __ASSEMBLER__ */ 393 #endif /* __ASSEMBLER__ */
312   394  
313   395  
Line 316... Line 398...
316 /* ------------------------------------------------------------------------- */ 398 /* ------------------------------------------------------------------------- */
317 /* This is advanced stuff. See usbconfig-prototype.h for more information 399 /* This is advanced stuff. See usbconfig-prototype.h for more information
318 * about the various methods to define USB descriptors. If you do nothing, 400 * about the various methods to define USB descriptors. If you do nothing,
319 * the default descriptors will be used. 401 * the default descriptors will be used.
320 */ 402 */
321 #define USB_PROP_IS_DYNAMIC (1 << 8) 403 #define USB_PROP_IS_DYNAMIC (1u << 14)
322 /* If this property is set for a descriptor, usbFunctionDescriptor() will be 404 /* If this property is set for a descriptor, usbFunctionDescriptor() will be
323 * used to obtain the particular descriptor. 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.
324 */ 408 */
325 #define USB_PROP_IS_RAM (1 << 9) 409 #define USB_PROP_IS_RAM (1u << 15)
326 /* If this property is set for a descriptor, the data is read from RAM 410 /* If this property is set for a descriptor, the data is read from RAM
327 * memory instead of Flash. The property is used for all methods to provide 411 * memory instead of Flash. The property is used for all methods to provide
328 * external descriptors. 412 * external descriptors.
329 */ 413 */
330 #define USB_PROP_LENGTH(len) ((len) & 0xff) 414 #define USB_PROP_LENGTH(len) ((len) & 0x3fff)
331 /* If a static external descriptor is used, this is the total length of the 415 /* If a static external descriptor is used, this is the total length of the
332 * descriptor in bytes. 416 * descriptor in bytes.
333 */ 417 */
334   418  
335 /* all descriptors which may have properties: */ 419 /* all descriptors which may have properties: */
Line 346... Line 430...
346 #define USB_CFG_DESCR_PROPS_STRING_0 0 430 #define USB_CFG_DESCR_PROPS_STRING_0 0
347 #endif 431 #endif
348 #ifndef USB_CFG_DESCR_PROPS_STRING_VENDOR 432 #ifndef USB_CFG_DESCR_PROPS_STRING_VENDOR
349 #define USB_CFG_DESCR_PROPS_STRING_VENDOR 0 433 #define USB_CFG_DESCR_PROPS_STRING_VENDOR 0
350 #endif 434 #endif
351 #ifndef USB_CFG_DESCR_PROPS_STRING_DEVICE 435 #ifndef USB_CFG_DESCR_PROPS_STRING_PRODUCT
352 #define USB_CFG_DESCR_PROPS_STRING_DEVICE 0 436 #define USB_CFG_DESCR_PROPS_STRING_PRODUCT 0
353 #endif 437 #endif
354 #ifndef USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER 438 #ifndef USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER
355 #define USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER 0 439 #define USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER 0
356 #endif 440 #endif
357 #ifndef USB_CFG_DESCR_PROPS_HID 441 #ifndef USB_CFG_DESCR_PROPS_HID
Line 374... Line 458...
374 * arrays as declared below: 458 * arrays as declared below:
375 */ 459 */
376 #ifndef __ASSEMBLER__ 460 #ifndef __ASSEMBLER__
377 extern 461 extern
378 #if !(USB_CFG_DESCR_PROPS_DEVICE & USB_PROP_IS_RAM) 462 #if !(USB_CFG_DESCR_PROPS_DEVICE & USB_PROP_IS_RAM)
379 PROGMEM 463 PROGMEM const
380 #endif 464 #endif
381 char usbDescriptorDevice[]; 465 char usbDescriptorDevice[];
382   466  
383 extern 467 extern
384 #if !(USB_CFG_DESCR_PROPS_CONFIGURATION & USB_PROP_IS_RAM) 468 #if !(USB_CFG_DESCR_PROPS_CONFIGURATION & USB_PROP_IS_RAM)
385 PROGMEM 469 PROGMEM const
386 #endif 470 #endif
387 char usbDescriptorConfiguration[]; 471 char usbDescriptorConfiguration[];
388   472  
389 extern 473 extern
390 #if !(USB_CFG_DESCR_PROPS_HID_REPORT & USB_PROP_IS_RAM) 474 #if !(USB_CFG_DESCR_PROPS_HID_REPORT & USB_PROP_IS_RAM)
391 PROGMEM 475 PROGMEM const
392 #endif 476 #endif
393 char usbDescriptorHidReport[]; 477 char usbDescriptorHidReport[];
394   478  
395 extern 479 extern
396 #if !(USB_CFG_DESCR_PROPS_STRING_0 & USB_PROP_IS_RAM) 480 #if !(USB_CFG_DESCR_PROPS_STRING_0 & USB_PROP_IS_RAM)
397 PROGMEM 481 PROGMEM const
398 #endif 482 #endif
399 char usbDescriptorString0[]; 483 char usbDescriptorString0[];
400   484  
401 extern 485 extern
402 #if !(USB_CFG_DESCR_PROPS_STRING_VENDOR & USB_PROP_IS_RAM) 486 #if !(USB_CFG_DESCR_PROPS_STRING_VENDOR & USB_PROP_IS_RAM)
403 PROGMEM 487 PROGMEM const
404 #endif 488 #endif
405 int usbDescriptorStringVendor[]; 489 int usbDescriptorStringVendor[];
406   490  
407 extern 491 extern
408 #if !(USB_CFG_DESCR_PROPS_STRING_PRODUCT & USB_PROP_IS_RAM) 492 #if !(USB_CFG_DESCR_PROPS_STRING_PRODUCT & USB_PROP_IS_RAM)
409 PROGMEM 493 PROGMEM const
410 #endif 494 #endif
411 int usbDescriptorStringDevice[]; 495 int usbDescriptorStringDevice[];
412   496  
413 extern 497 extern
414 #if !(USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER & USB_PROP_IS_RAM) 498 #if !(USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER & USB_PROP_IS_RAM)
415 PROGMEM 499 PROGMEM const
416 #endif 500 #endif
417 int usbDescriptorStringSerialNumber[]; 501 int usbDescriptorStringSerialNumber[];
418   502  
419 #endif /* __ASSEMBLER__ */ 503 #endif /* __ASSEMBLER__ */
420   504  
Line 437... Line 521...
437 /* ------------------------------------------------------------------------- */ 521 /* ------------------------------------------------------------------------- */
438   522  
439 #if !defined __ASSEMBLER__ && (!defined USB_CFG_VENDOR_ID || !defined USB_CFG_DEVICE_ID) 523 #if !defined __ASSEMBLER__ && (!defined USB_CFG_VENDOR_ID || !defined USB_CFG_DEVICE_ID)
440 #warning "You should define USB_CFG_VENDOR_ID and USB_CFG_DEVICE_ID in usbconfig.h" 524 #warning "You should define USB_CFG_VENDOR_ID and USB_CFG_DEVICE_ID in usbconfig.h"
441 /* If the user has not defined IDs, we default to obdev's free IDs. 525 /* If the user has not defined IDs, we default to obdev's free IDs.
442 * See USBID-License.txt for details. 526 * See USB-IDs-for-free.txt for details.
443 */ 527 */
444 #endif 528 #endif
445   529  
446 /* make sure we have a VID and PID defined, byte order is lowbyte, highbyte */ 530 /* make sure we have a VID and PID defined, byte order is lowbyte, highbyte */
447 #ifndef USB_CFG_VENDOR_ID 531 #ifndef USB_CFG_VENDOR_ID
448 # define USB_CFG_VENDOR_ID 0xc0, 0x16 /* 5824 in dec, stands for VOTI */ 532 # define USB_CFG_VENDOR_ID 0xc0, 0x16 /* = 0x16c0 = 5824 = voti.nl */
449 #endif 533 #endif
450   534  
451 #ifndef USB_CFG_DEVICE_ID 535 #ifndef USB_CFG_DEVICE_ID
452 # if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH 536 # if USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH
453 # define USB_CFG_DEVICE_ID 0xdf, 0x05 /* 1503 in dec, shared PID for HIDs */ 537 # define USB_CFG_DEVICE_ID 0xdf, 0x05 /* = 0x5df = 1503, shared PID for HIDs */
454 # elif USB_CFG_INTERFACE_CLASS == 2 538 # elif USB_CFG_INTERFACE_CLASS == 2
455 # define USB_CFG_DEVICE_ID 0xe1, 0x05 /* 1505 in dec, shared PID for CDC Modems */ 539 # define USB_CFG_DEVICE_ID 0xe1, 0x05 /* = 0x5e1 = 1505, shared PID for CDC Modems */
456 # else 540 # else
457 # define USB_CFG_DEVICE_ID 0xdc, 0x05 /* 1500 in dec, obdev's free PID */ 541 # define USB_CFG_DEVICE_ID 0xdc, 0x05 /* = 0x5dc = 1500, obdev's free PID */
458 # endif 542 # endif
459 #endif 543 #endif
460   544  
461 /* Derive Output, Input and DataDirection ports from port names */ 545 /* Derive Output, Input and DataDirection ports from port names */
462 #ifndef USB_CFG_IOPORTNAME 546 #ifndef USB_CFG_IOPORTNAME
Line 478... Line 562...
478 #define USB_CFG_IOPORT USB_OUTPORT(USB_CFG_IOPORTNAME) 562 #define USB_CFG_IOPORT USB_OUTPORT(USB_CFG_IOPORTNAME)
479 #ifdef USB_CFG_PULLUP_IOPORTNAME 563 #ifdef USB_CFG_PULLUP_IOPORTNAME
480 #define USB_CFG_PULLUP_IOPORT USB_OUTPORT(USB_CFG_PULLUP_IOPORTNAME) 564 #define USB_CFG_PULLUP_IOPORT USB_OUTPORT(USB_CFG_PULLUP_IOPORTNAME)
481 #endif 565 #endif
482   566  
-   567 #ifndef USB_CFG_EP3_NUMBER /* if not defined in usbconfig.h */
-   568 #define USB_CFG_EP3_NUMBER 3
-   569 #endif
-   570  
-   571 #ifndef USB_CFG_HAVE_INTRIN_ENDPOINT3
-   572 #define USB_CFG_HAVE_INTRIN_ENDPOINT3 0
-   573 #endif
483   574  
484 #define USB_BUFSIZE 11 /* PID, 8 bytes data, 2 bytes CRC */ 575 #define USB_BUFSIZE 11 /* PID, 8 bytes data, 2 bytes CRC */
485   576  
486 /* ----- Try to find registers and bits responsible for ext interrupt 0 ----- */ 577 /* ----- Try to find registers and bits responsible for ext interrupt 0 ----- */
487   578  
Line 491... Line 582...
491 # else 582 # else
492 # define USB_INTR_CFG MCUCR 583 # define USB_INTR_CFG MCUCR
493 # endif 584 # endif
494 #endif 585 #endif
495 #ifndef USB_INTR_CFG_SET /* allow user to override our default */ 586 #ifndef USB_INTR_CFG_SET /* allow user to override our default */
-   587 # if defined(USB_COUNT_SOF) || defined(USB_SOF_HOOK)
-   588 # define USB_INTR_CFG_SET (1 << ISC01) /* cfg for falling edge */
-   589 /* If any SOF logic is used, the interrupt must be wired to D- where
-   590 * we better trigger on falling edge
-   591 */
-   592 # else
496 # define USB_INTR_CFG_SET ((1 << ISC00) | (1 << ISC01)) /* cfg for rising edge */ 593 # define USB_INTR_CFG_SET ((1 << ISC00) | (1 << ISC01)) /* cfg for rising edge */
-   594 # endif
497 #endif 595 #endif
498 #ifndef USB_INTR_CFG_CLR /* allow user to override our default */ 596 #ifndef USB_INTR_CFG_CLR /* allow user to override our default */
499 # define USB_INTR_CFG_CLR 0 /* no bits to clear */ 597 # define USB_INTR_CFG_CLR 0 /* no bits to clear */
500 #endif 598 #endif
501   599  
Line 548... Line 646...
548   646  
549 #define USBPID_ACK 0xd2 647 #define USBPID_ACK 0xd2
550 #define USBPID_NAK 0x5a 648 #define USBPID_NAK 0x5a
551 #define USBPID_STALL 0x1e 649 #define USBPID_STALL 0x1e
552   650  
-   651 #ifndef USB_INITIAL_DATATOKEN
-   652 #define USB_INITIAL_DATATOKEN USBPID_DATA1
-   653 #endif
-   654  
553 #ifndef __ASSEMBLER__ 655 #ifndef __ASSEMBLER__
554   656  
-   657 typedef struct usbTxStatus{
-   658 volatile uchar len;
-   659 uchar buffer[USB_BUFSIZE];
-   660 }usbTxStatus_t;
-   661  
555 extern uchar usbTxBuf1[USB_BUFSIZE], usbTxBuf3[USB_BUFSIZE]; 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  
556   668  
557 typedef union usbWord{ 669 typedef union usbWord{
558 unsigned word; 670 unsigned word;
559 uchar bytes[2]; 671 uchar bytes[2];
560 }usbWord_t; 672 }usbWord_t;
Line 614... Line 726...
614 #define USBDESCR_ENDPOINT 5 726 #define USBDESCR_ENDPOINT 5
615 #define USBDESCR_HID 0x21 727 #define USBDESCR_HID 0x21
616 #define USBDESCR_HID_REPORT 0x22 728 #define USBDESCR_HID_REPORT 0x22
617 #define USBDESCR_HID_PHYS 0x23 729 #define USBDESCR_HID_PHYS 0x23
618   730  
-   731 //#define USBATTR_BUSPOWER 0x80 // USB 1.1 does not define this value any more
619 #define USBATTR_BUSPOWER 0x80 732 #define USBATTR_BUSPOWER 0
620 #define USBATTR_SELFPOWER 0x40 733 #define USBATTR_SELFPOWER 0x40
621 #define USBATTR_REMOTEWAKE 0x20 734 #define USBATTR_REMOTEWAKE 0x20
622   735  
623 /* USB HID Requests */ 736 /* USB HID Requests */
624 #define USBRQ_HID_GET_REPORT 0x01 737 #define USBRQ_HID_GET_REPORT 0x01