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__ */
|
---|