?lang_form? ?lang_select? ?lang_submit? ?lang_endform?
{HEADER END}
{BLAME START}

library

?curdirlinks? -

Blame information for rev 32

Line No. Rev Author Line
1 32 kaklik /******************************************************************************
2  
3 Common USB Library Definitions (Header File)
4  
5 Summary:
6 This file defines data types, constants, and macros that are common to
7 multiple layers of the Microchip USB Firmware Stack.
8  
9 Description:
10 This file defines data types, constants, and macros that are common to
11 multiple layers of the Microchip USB Firmware Stack.
12  
13 This file is located in the "\<Install Directory\>\\Microchip\\Include\\USB"
14 directory.
15  
16 When including this file in a new project, this file can either be
17 referenced from the directory in which it was installed or copied
18 directly into the user application folder. If the first method is
19 chosen to keep the file located in the folder in which it is installed
20 then include paths need to be added so that the library and the
21 application both know where to reference each others files. If the
22 application folder is located in the same folder as the Microchip
23 folder (like the current demo folders), then the following include
24 paths need to be added to the application's project:
25  
26 .
27 ..\\..\\MicrochipInclude
28  
29 If a different directory structure is used, modify the paths as
30 required. An example using absolute paths instead of relative paths
31 would be the following:
32  
33 C:\\Microchip Solutions\\Microchip\\Include
34  
35 C:\\Microchip Solutions\\My Demo Application
36 *******************************************************************************/
37 //DOM-IGNORE-BEGIN
38 /*******************************************************************************
39  
40 FileName: usb_common.h
41 Dependencies: See included files, below.
42 Processor: PIC18/PIC24/PIC32MX microcontrollers with USB module
43 Compiler: C18 v3.13+/C30 v2.01+/C32 v0.00.18+
44 Company: Microchip Technology, Inc.
45  
46 Software License Agreement
47  
48 The software supplied herewith by Microchip Technology Incorporated
49 (the “Company”) for its PICmicro® Microcontroller is intended and
50 supplied to you, the Company’s customer, for use solely and
51 exclusively on Microchip PICmicro Microcontroller products. The
52 software is owned by the Company and/or its supplier, and is
53 protected under applicable copyright laws. All rights are reserved.
54 Any use in violation of the foregoing restrictions may subject the
55 user to criminal sanctions under applicable laws, as well as to
56 civil liability for the breach of the terms and conditions of this
57 license.
58  
59 THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
60 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
61 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
62 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
63 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
64 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
65  
66 *******************************************************************************/
67 //DOM-IGNORE-END
68  
69 //DOM-IGNORE-BEGIN
70 /********************************************************************
71 Change History:
72 Rev Description
73 ---- -----------
74 2.6 Moved many of the USB events
75 2.6a Changed the limit of USB_EVENT from UINT_MAX to INT_MAX
76 2.7 No change
77 2.7a Minor changes to include isochronous events
78 ********************************************************************/
79 //DOM-IGNORE-END
80  
81  
82 //DOM-IGNORE-BEGIN
83 #ifndef _USB_COMMON_H_
84 #define _USB_COMMON_H_
85 //DOM-IGNORE-END
86  
87 #include <limits.h>
88  
89 // *****************************************************************************
90 // *****************************************************************************
91 // Section: USB Constants
92 // *****************************************************************************
93 // *****************************************************************************
94  
95 // Section: Error Code Values
96  
97 #define USB_SUCCESS 0x00 // USB operation successful.
98 #define USB_INVALID_STATE 0x01 // Operation cannot be performed in current state.
99 #define USB_BUSY 0x02 // A transaction is already in progress.
100 #define USB_ILLEGAL_REQUEST 0x03 // Cannot perform requested operation.
101 #define USB_INVALID_CONFIGURATION 0x04 // Configuration descriptor not found.
102 #define USB_MEMORY_ALLOCATION_ERROR 0x05 // Out of dynamic memory.
103 #define USB_UNKNOWN_DEVICE 0x06 // Device with specified address is not attached.
104 #define USB_CANNOT_ENUMERATE 0x07 // Cannot enumerate the attached device.
105 #define USB_EVENT_QUEUE_FULL 0x08 // Event queue was full when an event occured.
106 #define USB_ENDPOINT_BUSY 0x10 // Endpoint is currently processing a transaction.
107 #define USB_ENDPOINT_STALLED 0x11 // Endpoint is currently stalled. User must clear the condition.
108 #define USB_ENDPOINT_ERROR 0x12 // Will need more than this eventually
109 #define USB_ENDPOINT_ERROR_ILLEGAL_PID 0x13 // Illegal PID received.
110 #define USB_ENDPOINT_NOT_FOUND 0x14 // Requested endpoint does not exist on device.
111 #define USB_ENDPOINT_ILLEGAL_DIRECTION 0x15 // Reads must be performe on IN endpoints, writes on OUT endpoints.
112 //#define USB_ENDPOINT_TRANSACTION_IN_PROGRESS 0x16
113 #define USB_ENDPOINT_NAK_TIMEOUT 0x17 // Too many NAK's occurred while waiting for the current transaction.
114 #define USB_ENDPOINT_ILLEGAL_TYPE 0x18 // Transfer type must match endpoint description.
115 #define USB_ENDPOINT_UNRESOLVED_STATE 0x19 // Endpoint is in an unknown state after completing a transaction.
116 #define USB_ENDPOINT_ERROR_BIT_STUFF 0x20 // USB Module - Bit stuff error.
117 #define USB_ENDPOINT_ERROR_DMA 0x21 // USB Module - DMA error.
118 #define USB_ENDPOINT_ERROR_TIMEOUT 0x22 // USB Module - Bus timeout.
119 #define USB_ENDPOINT_ERROR_DATA_FIELD 0x23 // USB Module - Data field size error.
120 #define USB_ENDPOINT_ERROR_CRC16 0x24 // USB Module - CRC16 failure.
121 #define USB_ENDPOINT_ERROR_END_OF_FRAME 0x25 // USB Module - End of Frame error.
122 #define USB_ENDPOINT_ERROR_PID_CHECK 0x26 // USB Module - Illegal PID received.
123 #define USB_ENDPOINT_ERROR_BMX 0x27 // USB Module - Bus Matrix error.
124 #define USB_ERROR_INSUFFICIENT_POWER 0x28 // Too much power was requested
125  
126 // Section: Return values for USBHostDeviceStatus()
127  
128 #define USB_DEVICE_STATUS 0x30 // Offset for USBHostDeviceStatus() return codes
129 #define USB_DEVICE_ATTACHED (USB_DEVICE_STATUS | 0x30) // Device is attached and running
130 #define USB_DEVICE_DETACHED (USB_DEVICE_STATUS | 0x01) // No device is attached
131 #define USB_DEVICE_ENUMERATING (USB_DEVICE_STATUS | 0x02) // Device is enumerating
132 #define USB_HOLDING_OUT_OF_MEMORY (USB_DEVICE_STATUS | 0x03) // Not enough heap space available
133 #define USB_HOLDING_UNSUPPORTED_DEVICE (USB_DEVICE_STATUS | 0x04) // Invalid configuration or unsupported class
134 #define USB_HOLDING_UNSUPPORTED_HUB (USB_DEVICE_STATUS | 0x05) // Hubs are not supported
135 #define USB_HOLDING_INVALID_CONFIGURATION (USB_DEVICE_STATUS | 0x06) // Invalid configuration requested
136 #define USB_HOLDING_PROCESSING_CAPACITY (USB_DEVICE_STATUS | 0x07) // Processing requirement excessive
137 #define USB_HOLDING_POWER_REQUIREMENT (USB_DEVICE_STATUS | 0x08) // Power requirement excessive
138 #define USB_HOLDING_CLIENT_INIT_ERROR (USB_DEVICE_STATUS | 0x09) // Client driver failed to initialize
139 #define USB_DEVICE_SUSPENDED (USB_DEVICE_STATUS | 0x0A) // Device is suspended
140  
141 #define USB_ERROR_CLASS_DEFINED 0x50 // Offset for application defined errors
142  
143 #define USB_SINGLE_DEVICE_ADDRESS 0x01 // Default USB device address (single device support)
144  
145  
146 // *****************************************************************************
147 // *****************************************************************************
148 // Section: USB Data Types
149 // *****************************************************************************
150 // *****************************************************************************
151  
152 // *****************************************************************************
153 /* Data Transfer Flags
154  
155 The following flags are used in the flags parameter of the "USBDEVTransferData"
156 and "USBHALTransferData" routines. They can be accessed by the bitfield
157 definitions or the macros can be OR'd together to identify the endpoint number
158 and properties of the data transfer.
159  
160 <code>
161 7 6 5 4 3 2 1 0 - Field name
162 | | | | \_____/
163 | | | | +----- ep_num - Endpoint number
164 | | | +---------- zero_pkt - End transfer with short or zero-sized packet
165 | | +------------ dts - 0=DATA0 packet, 1=DATA1 packet
166 | +-------------- force_dts - Force data toggle sync to match dts field
167 +---------------- direction - Transfer direction: 0=Receive, 1=Transmit
168 </code>
169 */
170  
171 typedef union
172 {
173 BYTE bitmap;
174 struct
175 {
176 BYTE ep_num: 4;
177 BYTE zero_pkt: 1;
178 BYTE dts: 1;
179 BYTE force_dts: 1;
180 BYTE direction: 1;
181 }field;
182  
183 } TRANSFER_FLAGS;
184  
185 // *****************************************************************************
186 /* Data Transfer Flags, Endpoint Number Constants
187  
188 These macros can be used as values for the "ep_num" field of the TRANSFER_FLAGS
189 data type.
190 */
191 #define USB_EP0 0 //
192 #define USB_EP1 1 //
193 #define USB_EP2 2 //
194 #define USB_EP3 3 //
195 #define USB_EP4 4 //
196 #define USB_EP5 5 //
197 #define USB_EP6 6 //
198 #define USB_EP7 7 //
199 #define USB_EP8 8 //
200 #define USB_EP9 9 //
201 #define USB_EP10 10 //
202 #define USB_EP11 11 //
203 #define USB_EP12 12 //
204 #define USB_EP13 13 //
205 #define USB_EP14 14 //
206 #define USB_EP15 15 //
207  
208 // *****************************************************************************
209 /* Data Transfer Flags, Bitmap Constants
210  
211 These macros can be used as values for the "bitmap" field of the TRANSFER_FLAGS
212 data type.
213 */
214 #define USB_TRANSMIT 0x80 // Data will be transmitted to the USB
215 #define USB_RECEIVE 0x00 // Data will be received from the USB
216 #define USB_FORCE_DTS 0x40 // Forces data toggle sync as below:
217 #define USB_DTS_MASK 0x20 // Mask for DTS bit (below)
218 #define USB_ZERO_PKT 0x10 // End transfer w/a short or zero-length packet
219 #define USB_DATA0 0x00|USB_FORCE_DTS // Force DATA0
220 #define USB_DATA1 0x20|USB_FORCE_DTS // Force DATA1
221 #define USB_SETUP_PKT USB_RECEIVE|USB_DATA0|USB_EP0 // Setup Packet
222 #define USB_SETUP_DATA USB_DATA1|USB_ZERO_PKT|USB_EP0 // Setup-transfer Data Packet
223 #define USB_SETUP_STATUS USB_DATA1|USB_EP0 // Setup-transfer Status Packet
224 #define USB_EP_NUM_MASK 0x0F // Endpoint number (ep_num) mask
225  
226 // *****************************************************************************
227 /* Data Transfer Flags, Initialization Macro
228  
229 This macro can be used with the above bitmap constants to initialize a
230 TRANSFER_FLAGS value. It provides the correct data type to avoid compiler
231 warnings.
232 */
233 #define XFLAGS(f) ((TRANSFER_FLAGS)((BYTE)(f))) // Initialization Macro
234  
235  
236 // *****************************************************************************
237 /* USB Events
238  
239 This enumeration identifies USB events that occur. It is used to
240 inform USB drivers and applications of events on the bus. It is passed
241 as a parameter to the event-handling routine, which must match the
242 prototype of the USB_CLIENT_EVENT_HANDLER data type, when an event occurs.
243 */
244  
245 typedef enum
246 {
247 // No event occured (NULL event)
248 EVENT_NONE = 0,
249  
250 EVENT_DEVICE_STACK_BASE = 1,
251  
252 EVENT_HOST_STACK_BASE = 100,
253  
254 // A USB hub has been attached. Hub support is not currently available.
255 EVENT_HUB_ATTACH,
256  
257 // A stall has occured. This event is not used by the Host stack.
258 EVENT_STALL,
259  
260 // VBus SRP Pulse, (VBus > 2.0v), Data: BYTE Port Number (For future support)
261 EVENT_VBUS_SES_REQUEST,
262  
263 // The voltage on Vbus has dropped below 4.4V/4.7V. The application is
264 // responsible for monitoring Vbus and calling USBHostVbusEvent() with this
265 // event. This event is not generated by the stack.
266 EVENT_VBUS_OVERCURRENT,
267  
268 // An enumerating device is requesting power. The data associated with this
269 // event is of the data type USB_VBUS_POWER_EVENT_DATA. Note that
270 // the requested current is specified in 2mA units, identical to the power
271 // specification in a device's Configuration Descriptor.
272 EVENT_VBUS_REQUEST_POWER,
273  
274 // Release power from a detaching device. The data associated with this
275 // event is of the data type USB_VBUS_POWER_EVENT_DATA. The current value
276 // specified in the data can be ignored.
277 EVENT_VBUS_RELEASE_POWER,
278  
279 // The voltage on Vbus is good, and the USB OTG module can be powered on.
280 // The application is responsible for monitoring Vbus and calling
281 // USBHostVbusEvent() with this event. This event is not generated by the
282 // stack. If the application issues an EVENT_VBUS_OVERCURRENT, then no
283 // power will be applied to that port, and no device can attach to that
284 // port, until the application issues the EVENT_VBUS_POWER_AVAILABLE for
285 // the port.
286 EVENT_VBUS_POWER_AVAILABLE,
287  
288 // The attached device is not supported by the application. The attached
289 // device is not allowed to enumerate.
290 EVENT_UNSUPPORTED_DEVICE,
291  
292 // Cannot enumerate the attached device. This is generated if communication
293 // errors prevent the device from enumerating.
294 EVENT_CANNOT_ENUMERATE,
295  
296 // The client driver cannot initialize the the attached device. The
297 // attached is not allowed to enumerate.
298 EVENT_CLIENT_INIT_ERROR,
299  
300 // The Host stack does not have enough heap space to enumerate the device.
301 // Check the amount of heap space allocated to the application. In MPLAB,
302 // select Project> Build Options...> Project. Select the appropriate
303 // linker tab, and inspect the "Heap size" entry.
304 EVENT_OUT_OF_MEMORY,
305  
306 // Unspecified host error. (This error should not occur).
307 EVENT_UNSPECIFIED_ERROR,
308  
309 // USB cable has been detached. The data associated with this event is the
310 // address of detached device, a single BYTE.
311 EVENT_DETACH,
312  
313 // A USB transfer has completed. The data associated with this event is of
314 // the data type HOST_TRANSFER_DATA if the event is generated from the host
315 // stack.
316 EVENT_TRANSFER,
317  
318 // A USB Start of Frame token has been received. This event is not
319 // used by the Host stack.
320 EVENT_SOF,
321  
322 // Device-mode resume received. This event is not used by the Host stack.
323 EVENT_RESUME,
324  
325 // Device-mode suspend/idle event received. This event is not used by the
326 // Host stack.
327 EVENT_SUSPEND,
328  
329 // Device-mode bus reset received. This event is not used by the Host
330 // stack.
331 EVENT_RESET,
332  
333 // In Host mode, an isochronous data read has completed. This event will only
334 // be passed to the DataEventHandler, which is only utilized if it is defined.
335 // Note that the DataEventHandler is called from within the USB interrupt, so
336 // it is critical that it return in time for the next isochronous data packet.
337 EVENT_DATA_ISOC_READ,
338  
339 // In Host mode, an isochronous data write has completed. This event will only
340 // be passed to the DataEventHandler, which is only utilized if it is defined.
341 // Note that the DataEventHandler is called from within the USB interrupt, so
342 // it is critical that it return in time for the next isochronous data packet.
343 EVENT_DATA_ISOC_WRITE,
344  
345 // Class-defined event offsets start here:
346 EVENT_GENERIC_BASE = 400, // Offset for Generic class events
347  
348 EVENT_MSD_BASE = 500, // Offset for Mass Storage Device class events
349  
350 EVENT_HID_BASE = 600, // Offset for Human Interface Device class events
351  
352 EVENT_PRINTER_BASE = 700, // Offset for Printer class events
353  
354 EVENT_CDC_BASE = 800, // Offset for CDC class events
355  
356 EVENT_CHARGER_BASE = 900, // Offset for Charger client driver events.
357  
358 EVENT_AUDIO_BASE = 1000, // Offset for Audio client driver events.
359  
360 EVENT_USER_BASE = 10000, // Add integral values to this event number
361 // to create user-defined events.
362  
363 // There was a transfer error on the USB. The data associated with this
364 // event is of data type HOST_TRANSFER_DATA.
365 EVENT_BUS_ERROR = INT_MAX
366  
367 } USB_EVENT;
368  
369  
370 // *****************************************************************************
371 /* EVENT_TRANSFER Data
372  
373 This data structure is passed to the appropriate layer's
374 USB_EVENT_HANDLER when an EVT_XFER event has occured, indicating
375 that a transfer has completed on the USB. It provides the endpoint,
376 direction, and actual size of the transfer.
377 */
378  
379 typedef struct _transfer_event_data
380 {
381 TRANSFER_FLAGS flags; // Transfer flags (see above)
382 UINT32 size; // Actual number of bytes transferred
383 BYTE pid; // Packet ID
384  
385 } USB_TRANSFER_EVENT_DATA;
386  
387  
388 // *****************************************************************************
389 /* EVENT_VBUS_REQUEST_POWER and EVENT_VBUS_RELEASE_POWER Data
390  
391 This data structure is passed to the appropriate layer's
392 USB_EVENT_HANDLER when an EVENT_VBUS_REQUEST_POWER or EVENT_VBUS_RELEASE_POWER
393 event has occured, indicating that a change in Vbus power is being requested.
394 */
395  
396 typedef struct _vbus_power_data
397 {
398 BYTE port; // Physical port number
399 BYTE current; // Current in 2mA units
400 } USB_VBUS_POWER_EVENT_DATA;
401  
402  
403 // *****************************************************************************
404 /* EVT_STALL Data
405  
406 The EVT_STALL event has a 16-bit data value associated with it where
407 a bit is set in the position for each endpoint that is currently
408 stalled (ie. bit 0 = EP0, bit 1 = EP1, etc.)
409 */
410  
411  
412 // *****************************************************************************
413 // *****************************************************************************
414 // Section: Event Handling Routines
415 // *****************************************************************************
416 // *****************************************************************************
417  
418 /*******************************************************************************
419 Function:
420 BOOL <Event-handling Function Name> ( USB_EVENT event,
421 void *data, unsigned int size )
422  
423 Description:
424 This routine is a "call out" routine that must be implemented by
425 any layer of the USB SW Stack (except the HAL which is at the
426 root of the event-call tree that needs to receive events. When
427 an event occurs, the HAL calls the next higher layer in the
428 stack to handle the event. Each layer either handles the event
429 or calls the layer above it to handle the event. Events are
430 identified by the "event" parameter and may have associated
431 data. If the higher layer was able to handle the event, it
432 should return TRUE. If not, it should return FALSE.
433  
434 Preconditions:
435 USBInitialize must have been called to initialize the USB SW
436 Stack.
437  
438 Paramters:
439 USB_EVENT event - Identifies the bus event that occured
440 void *data - Pointer to event-specific data
441 unsigned int size - Size of the event-specific data
442  
443 Return Values:
444 None
445  
446 Remarks:
447 The function is name is defined by the layer that implements
448 it. A pointer to the function will be placed by into a table
449 that the lower-layer will use to call it. This requires the
450 function to use a specific call "signature" (return data type
451 and values and data parameter types and values).
452  
453 *******************************************************************************/
454  
455 typedef BOOL (*USB_EVENT_HANDLER) ( USB_EVENT event, void *data, unsigned int size );
456  
457  
458 // *****************************************************************************
459 // *****************************************************************************
460 // Section: USB Application Program Interface (API) Routines
461 // *****************************************************************************
462 // *****************************************************************************
463  
464 /****************************************************************************
465 Function:
466 BOOL USBInitialize ( unsigned long flags )
467  
468 Summary:
469 This interface initializes the variables of the USB host stack.
470  
471 Description:
472 This interface initializes the USB stack.
473  
474 Precondition:
475 None
476  
477 Parameters:
478 flags - reserved
479  
480 Return Values:
481 TRUE - Initialization successful
482 FALSE - Initialization failure
483  
484 Remarks:
485 This interface is implemented as a macro that can be defined by the
486 application or by default is defined correctly for the stack mode.
487  
488 ***************************************************************************/
489  
490 #ifndef USBInitialize
491 #if defined( USB_SUPPORT_DEVICE )
492 #if defined( USB_SUPPORT_HOST )
493 #if defined( USB_SUPPORT_OTG )
494 #error "USB OTG is not yet supported."
495 #else
496 #define USBInitialize(f) \
497 (USBDEVInitialize(f) && USBHostInit(f)) ? \
498 TRUE : FALSE
499 #endif
500 #else
501 #define USBInitialize(f) USBDeviceInit()
502 #endif
503 #else
504 #if defined( USB_SUPPORT_HOST )
505 #define USBInitialize(f) USBHostInit(f)
506 #else
507 #error "Application must define support mode in usb_config.h"
508 #endif
509 #endif
510 #endif
511  
512  
513 /****************************************************************************
514 Function:
515 void USBTasks( void )
516  
517 Summary:
518 This function executes the tasks for USB operation.
519  
520 Description:
521 This function executes the tasks for USB host operation. It must be
522 executed on a regular basis to keep everything functioning.
523  
524 Precondition:
525 USBInitialize() has been called.
526  
527 Parameters:
528 None
529  
530 Returns:
531 None
532  
533 Remarks:
534 This interface is implemented as a macro that can be defined by the
535 application or by default is defined correctly for the stack mode.
536  
537 ***************************************************************************/
538  
539 #ifndef USBTasks // Implemented as a macro that can be overridden.
540 #if defined( USB_SUPPORT_DEVICE )
541 #if defined( USB_SUPPORT_HOST )
542 #if defined( USB_SUPPORT_OTG )
543 #error "USB OTG is not yet supported."
544 #else
545 #define USBTasks() {USBHostTasks(); USBHALHandleBusEvent();}
546 #endif
547 #else
548 #define USBTasks() USBDeviceTasks()
549 #endif
550 #else
551 #if defined( USB_SUPPORT_HOST )
552 #define USBTasks() USBHostTasks()
553 #else
554 #error "Application must define support mode in usb_config.h"
555 #endif
556 #endif
557 #endif
558  
559 #define USB_PING_PONG__NO_PING_PONG 0x00 //0b00
560 #define USB_PING_PONG__EP0_OUT_ONLY 0x01 //0b01
561 #define USB_PING_PONG__FULL_PING_PONG 0x02 //0b10
562 #define USB_PING_PONG__ALL_BUT_EP0 0x03 //0b11
563  
564 #endif // _USB_COMMON_H_
565 /*************************************************************************
566 * EOF
567 */
568  
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3