?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 USB Host Driver (Header File)
4  
5 Description:
6 This file provides the hardware interface for a USB Embedded Host
7 application. Most applications will not make direct use of the functions
8 in this file. Instead, one or more client driver files should also be
9 included in the project to support the devices that will be attached to the
10 host. Application interface will be through the client drivers.
11  
12 This header file must be included after the application-specific
13 usb_config.h file, as usb_config.h configures parts of this file.
14  
15 Summary:
16 This file provides the hardware interface for a USB Embedded Host
17 application.
18  
19 *******************************************************************************/
20 //DOM-IGNORE-BEGIN
21 /******************************************************************************
22  
23 * FileName: usb_host.h
24 * Dependencies: None
25 * Processor: PIC24/dsPIC30/dsPIC33/PIC32MX
26 * Compiler: C30 v2.01/C32 v0.00.18
27 * Company: Microchip Technology, Inc.
28  
29 Software License Agreement
30  
31 The software supplied herewith by Microchip Technology Incorporated
32 (the “Company”) for its PICmicro® Microcontroller is intended and
33 supplied to you, the Company’s customer, for use solely and
34 exclusively on Microchip PICmicro Microcontroller products. The
35 software is owned by the Company and/or its supplier, and is
36 protected under applicable copyright laws. All rights are reserved.
37 Any use in violation of the foregoing restrictions may subject the
38 user to criminal sanctions under applicable laws, as well as to
39 civil liability for the breach of the terms and conditions of this
40 license.
41  
42 THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
43 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
44 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
45 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
46 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
47 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
48  
49 Change History
50 Rev Description
51 ----- ----------------------------------
52 2.6a- No change
53 2.7
54  
55 2.7a Added USB_HOST_APP_DATA_EVENT_HANDLER().
56 *******************************************************************************/
57  
58 #ifndef __USBHOST_H__
59 #define __USBHOST_H__
60 //DOM-IGNORE-END
61  
62 #include <limits.h>
63 #include "GenericTypeDefs.h"
64  
65 // *****************************************************************************
66 // *****************************************************************************
67 // Section: Host Firmware Version
68 // *****************************************************************************
69 // *****************************************************************************
70  
71 #define USB_HOST_FW_MAJOR_VER 1 // Firmware version, major release number.
72 #define USB_HOST_FW_MINOR_VER 0 // Firmware version, minor release number.
73 #define USB_HOST_FW_DOT_VER 0 // Firmware version, dot release number.
74  
75  
76 // *****************************************************************************
77 // *****************************************************************************
78 // Section: Set Default Configuration Constants
79 // *****************************************************************************
80 // *****************************************************************************
81  
82 #ifndef USB_NUM_BULK_NAKS
83 #define USB_NUM_BULK_NAKS 10000 // Define how many NAK's are allowed
84 // during a bulk transfer before erroring.
85 #endif
86  
87 #ifndef USB_NUM_COMMAND_TRIES
88 #define USB_NUM_COMMAND_TRIES 3 // During enumeration, define how many
89 // times each command will be tried before
90 // giving up and resetting the device.
91 #endif
92  
93 #ifndef USB_NUM_CONTROL_NAKS
94 #define USB_NUM_CONTROL_NAKS 20 // Define how many NAK's are allowed
95 // during a control transfer before erroring.
96 #endif
97  
98 #ifndef USB_NUM_ENUMERATION_TRIES
99 #define USB_NUM_ENUMERATION_TRIES 3 // Define how many times the host will try
100 // to enumerate the device before giving
101 // up and setting the state to DETACHED.
102 #endif
103  
104 #ifndef USB_NUM_INTERRUPT_NAKS
105 #define USB_NUM_INTERRUPT_NAKS 3 // Define how many NAK's are allowed
106 // during an interrupt OUT transfer before
107 // erroring. Interrupt IN transfers that
108 // are NAK'd are terminated without error.
109 #endif
110  
111  
112 #ifndef USB_INITIAL_VBUS_CURRENT
113 #error The application must define USB_INITIAL_VBUS_CURRENT as 100 mA for Host or 8-100 mA for OTG.
114 #endif
115  
116 #if defined (USB_SUPPORT_HOST)
117 #if defined (USB_SUPPORT_OTG)
118 #if (USB_INITIAL_VBUS_CURRENT < 8/2) || (USB_INITIAL_VBUS_CURRENT > 100/2)
119 #warning USB_INITIAL_VBUS_CURRENT is in violation of the USB specification.
120 #endif
121 #else
122 #if (USB_INITIAL_VBUS_CURRENT != 100/2)
123 #warning USB_INITIAL_VBUS_CURRENT is in violation of the USB specification.
124 #endif
125 #endif
126 #endif
127  
128  
129 // *****************************************************************************
130 // *****************************************************************************
131 // Section: USB Constants
132 // *****************************************************************************
133 // *****************************************************************************
134  
135 // Section: Values for USBHostIssueDeviceRequest(), dataDirection
136  
137 #define USB_DEVICE_REQUEST_SET 0 // USBHostIssueDeviceRequest() will set information.
138 #define USB_DEVICE_REQUEST_GET 1 // USBHostIssueDeviceRequest() will get information.
139  
140 // Section: Dummy Device ID's
141  
142 #define USB_ROOT_HUB 255 // Invalid Device ID used to indicate the root hub.
143  
144  
145 // *****************************************************************************
146 // *****************************************************************************
147 // Section: USB Data Structures
148 // *****************************************************************************
149 // *****************************************************************************
150  
151 // *****************************************************************************
152 /* Transfer Attributes
153  
154 This structure describes the transfer attributes of an endpoint.
155 */
156 typedef union
157 {
158 BYTE val; //
159 struct
160 {
161 BYTE bfTransferType : 2; // See USB_TRANSFER_TYPE_* for values.
162 BYTE bfSynchronizationType : 2; // For isochronous endpoints only.
163 BYTE bfUsageType : 2; // For isochronous endpoints only.
164 };
165 } TRANSFER_ATTRIBUTES;
166  
167  
168 // *****************************************************************************
169 /* Host Transfer Information
170  
171 This structure is used when the event handler is used to notify the upper layer
172 of transfer completion.
173 */
174  
175 typedef struct _HOST_TRANSFER_DATA
176 {
177 DWORD dataCount; // Count of bytes transferred.
178 BYTE *pUserData; // Pointer to transfer data.
179 BYTE bEndpointAddress; // Transfer endpoint.
180 BYTE bErrorCode; // Transfer error code.
181 TRANSFER_ATTRIBUTES bmAttributes; // INTERNAL USE ONLY - Endpoint transfer attributes.
182 BYTE clientDriver; // INTERNAL USE ONLY - Client driver index for sending the event.
183 } HOST_TRANSFER_DATA;
184  
185  
186 // *****************************************************************************
187 /* Isochronous Data Buffer
188  
189 Isochronous data transfers are continuous, until they are explicitly terminated.
190 The maximum transfer size is given in the endpoint descriptor, but a single
191 transfer may contain less data than the maximum. Also, the USB peripheral can
192 store data to RAM in a linear fashion only. Therefore, we cannot use a simple
193 circular buffer for the data. Instead, the application or client driver must
194 allocate multiple independent data buffers. These buffers must be the
195 maximum transfer size. This structure contains a pointer to an allocated
196 buffer, plus the valid data length of the buffer.
197 */
198  
199 typedef struct _ISOCHRONOUS_DATA_BUFFER
200 {
201 BYTE *pBuffer; // Data buffer pointer.
202 WORD dataLength; // Amount of valid data in the buffer.
203 BYTE bfDataLengthValid : 1; // dataLength value is valid.
204 } ISOCHRONOUS_DATA_BUFFER;
205  
206  
207 // *****************************************************************************
208 /* Isochronous Data
209  
210 Isochronous data transfers are continuous, until they are explicitly terminated.
211 This requires a tighter integration between the host layer and the application
212 layer to manage the streaming data.
213  
214 If an application uses isochronous transfers, it must allocate one variable
215 of type ISOCHRONOUS_DATA for each concurrent transfer. When the device
216 attaches, the client driver must inform the application layer of the maximum
217 transfer size. At this point, the application must allocate space for the
218 data buffers, and set the data buffer points in this structure to point to them.
219 */
220  
221 #if !defined( USB_MAX_ISOCHRONOUS_DATA_BUFFERS )
222 #define USB_MAX_ISOCHRONOUS_DATA_BUFFERS 2
223 #endif
224 #if USB_MAX_ISOCHRONOUS_DATA_BUFFERS < 2
225 #error At least two buffers must be defined for isochronous data.
226 #endif
227  
228 typedef struct _ISOCHRONOUS_DATA
229 {
230 BYTE totalBuffers; // Total number of buffers available.
231 BYTE currentBufferUSB; // The current buffer the USB peripheral is accessing.
232 BYTE currentBufferUser; // The current buffer the user is reading/writing.
233 BYTE *pDataUser; // User pointer for accessing data.
234  
235 ISOCHRONOUS_DATA_BUFFER buffers[USB_MAX_ISOCHRONOUS_DATA_BUFFERS]; // Data buffer information.
236 } ISOCHRONOUS_DATA;
237  
238  
239 // *****************************************************************************
240 /* Targeted Peripheral List
241  
242 This structure is used to define the devices that this host can support. If the
243 host is a USB Embedded Host or Dual Role Device that does not support OTG, the
244 TPL may contain both specific devices and generic classes. If the host supports
245 OTG, then the TPL may contain ONLY specific devices.
246 */
247 typedef struct _USB_TPL
248 {
249 union
250 {
251 DWORD val; //
252 struct
253 {
254 WORD idVendor; // Vendor ID
255 WORD idProduct; // Product ID
256 };
257 struct
258 {
259 BYTE bClass; // Class ID
260 BYTE bSubClass; // SubClass ID
261 BYTE bProtocol; // Protocol ID
262 };
263 } device; //
264 BYTE bConfiguration; // Initial device configuration
265 BYTE ClientDriver; // Index of client driver in the Client Driver table
266 union
267 {
268 BYTE val; //
269 struct
270 {
271 BYTE bfAllowHNP : 1; // Is HNP allowed?
272 BYTE bfIsClassDriver : 1; // Client driver is a class-level driver
273 BYTE bfSetConfiguration : 1; // bConfiguration is valid
274 };
275 } flags; //
276 } USB_TPL;
277  
278 // Section: TPL Initializers
279 #define INIT_VID_PID(v,p) {((v)|((p)<<16))} // Set VID/PID support in the TPL.
280 #define INIT_CL_SC_P(c,s,p) {((c)|((s)<<8)|((p)<<16))} // Set class support in the TPL (non-OTG only).
281  
282 // Section: TPL Flags
283 #define TPL_ALLOW_HNP 0x01 // Bitmask for Host Negotiation Protocol.
284 #define TPL_CLASS_DRV 0x02 // Bitmask for class driver support.
285 #define TPL_SET_CONFIG 0x04 // Bitmask for setting the configuration.
286  
287  
288 // *****************************************************************************
289 // *****************************************************************************
290 // Section: USB Host - Client Driver Interface
291 // *****************************************************************************
292 // *****************************************************************************
293  
294 /****************************************************************************
295 Function:
296 BOOL (*USB_CLIENT_EVENT_HANDLER) ( BYTE address, USB_EVENT event,
297 void *data, DWORD size )
298  
299 Summary:
300 This is a typedef to use when defining a client driver event handler.
301  
302 Description:
303 This data type defines a pointer to a call-back function that must be
304 implemented by a client driver if it needs to be aware of events on the
305 USB. When an event occurs, the Host layer will call the client driver
306 via this pointer to handle the event. Events are identified by the
307 "event" parameter and may have associated data. If the client driver was
308 able to handle the event, it should return TRUE. If not (or if
309 additional processing is required), it should return FALSE.
310  
311 Precondition:
312 The client must have been initialized.
313  
314 Parameters:
315 BYTE address - Address of device where event occurred
316 USB_EVENT event - Identifies the event that occured
317 void *data - Pointer to event-specific data
318 DWORD size - Size of the event-specific data
319  
320 Return Values:
321 TRUE - The event was handled
322 FALSE - The event was not handled
323  
324 Remarks:
325 The application may also implement an event handling routine if it
326 requires knowledge of events. To do so, it must implement a routine that
327 matches this function signature and define the USB_HOST_APP_EVENT_HANDLER
328 macro as the name of that function.
329 ***************************************************************************/
330  
331 typedef BOOL (*USB_CLIENT_EVENT_HANDLER) ( BYTE address, USB_EVENT event, void *data, DWORD size );
332  
333  
334 /****************************************************************************
335 Function:
336 BOOL (*USB_CLIENT_INIT) ( BYTE address, DWORD flags, BYTE clientDriverID )
337  
338 Summary:
339 This is a typedef to use when defining a client driver initialization
340 handler.
341  
342 Description:
343 This routine is a call out from the host layer to a USB client driver.
344 It is called when the system has been configured as a USB host and a new
345 device has been attached to the bus. Its purpose is to initialize and
346 activate the client driver.
347  
348 Precondition:
349 The device has been configured.
350  
351 Parameters:
352 BYTE address - Device's address on the bus
353 DWORD flags - Initialization flags
354 BYTE clientDriverID - ID to send when issuing a Device Request via
355 USBHostIssueDeviceRequest() or USBHostSetDeviceConfiguration().
356  
357 Return Values:
358 TRUE - Successful
359 FALSE - Not successful
360  
361 Remarks:
362 There may be multiple client drivers. If so, the USB host layer will
363 call the initialize routine for each of the clients that are in the
364 selected configuration.
365 ***************************************************************************/
366  
367 typedef BOOL (*USB_CLIENT_INIT) ( BYTE address, DWORD flags, BYTE clientDriverID );
368  
369  
370 /****************************************************************************
371 Function:
372 BOOL USB_HOST_APP_EVENT_HANDLER ( BYTE address, USB_EVENT event,
373 void *data, DWORD size )
374  
375 Summary:
376 This is a typedef to use when defining the application level events
377 handler.
378  
379 Description:
380 This function is implemented by the application. The function name can
381 be anything - the macro USB_HOST_APP_EVENT_HANDLER must be set in
382 usb_config.h to the name of the application function.
383  
384 In the application layer, this function is responsible for handling all
385 application-level events that are generated by the stack. See the
386 enumeration USB_EVENT for a complete list of all events that can occur.
387 Note that some of these events are intended for client drivers
388 (e.g. EVENT_TRANSFER), while some are intended for for the application
389 layer (e.g. EVENT_UNSUPPORTED_DEVICE).
390  
391 If the application can handle the event successfully, the function
392 should return TRUE. For example, if the function receives the event
393 EVENT_VBUS_REQUEST_POWER and the system can allocate that much power to
394 an attached device, the function should return TRUE. If, however, the
395 system cannot allocate that much power to an attached device, the
396 function should return FALSE.
397  
398 Precondition:
399 None
400  
401 Parameters:
402 BYTE address - Address of the USB device generating the event
403 USB_EVENT event - Event that occurred
404 void *data - Optional pointer to data for the event
405 DWORD size - Size of the data pointed to by *data
406  
407 Return Values:
408 TRUE - Event was processed successfully
409 FALSE - Event was not processed successfully
410  
411 Remarks:
412 If this function is not provided by the application, then all application
413 events are assumed to function without error.
414 ***************************************************************************/
415 #if defined( USB_HOST_APP_EVENT_HANDLER )
416 BOOL USB_HOST_APP_EVENT_HANDLER ( BYTE address, USB_EVENT event, void *data, DWORD size );
417 #else
418 // If the application does not provide an event handler, then we will
419 // assume that all events function without error.
420 #define USB_HOST_APP_EVENT_HANDLER(a,e,d,s) TRUE
421 #endif
422  
423  
424 /****************************************************************************
425 Function:
426 BOOL USB_HOST_APP_DATA_EVENT_HANDLER ( BYTE address, USB_EVENT event,
427 void *data, DWORD size )
428  
429 Summary:
430 This is a typedef to use when defining the application level data events
431 handler.
432  
433 Description:
434 This function is implemented by the application. The function name can
435 be anything - the macro USB_HOST_APP_EVENT_HANDLER must be set in
436 usb_config.h to the name of the application function.
437  
438 In the application layer, this function is responsible for handling all
439 application-level data events that are generated by the stack. See the
440 enumeration USB_EVENT for a complete list of all events that can occur.
441 Note that only data events, such as EVENT_DATA_ISOC_READ, will be
442 passed to this event handler.
443  
444 If the application can handle the event successfully, the function
445 should return TRUE.
446  
447 Precondition:
448 None
449  
450 Parameters:
451 BYTE address - Address of the USB device generating the event
452 USB_EVENT event - Event that occurred
453 void *data - Optional pointer to data for the event
454 DWORD size - Size of the data pointed to by *data
455  
456 Return Values:
457 TRUE - Event was processed successfully
458 FALSE - Event was not processed successfully
459  
460 Remarks:
461 If this function is not provided by the application, then all application
462 events are assumed to function without error.
463 ***************************************************************************/
464 #if defined( USB_HOST_APP_DATA_EVENT_HANDLER )
465 BOOL USB_HOST_APP_DATA_EVENT_HANDLER ( BYTE address, USB_EVENT event, void *data, DWORD size );
466 #else
467 // If the application does not provide an event handler, then we will
468 // assume that all events function without error.
469 #define USB_HOST_APP_DATA_EVENT_HANDLER(a,e,d,s) TRUE
470 #endif
471  
472  
473 // *****************************************************************************
474 /* Client Driver Table Structure
475  
476 This structure is used to define an entry in the client-driver table.
477 Each entry provides the information that the Host layer needs to
478 manage a particular USB client driver, including pointers to the
479 interface routines that the Client Driver must implement.
480 */
481  
482 typedef struct _CLIENT_DRIVER_TABLE
483 {
484 USB_CLIENT_INIT Initialize; // Initialization routine
485 USB_CLIENT_EVENT_HANDLER EventHandler; // Event routine
486  
487 #ifdef USB_HOST_APP_DATA_EVENT_HANDLER
488 USB_CLIENT_EVENT_HANDLER DataEventHandler; // Data Event routine
489 #endif
490  
491 DWORD flags; // Initialization flags
492  
493 } CLIENT_DRIVER_TABLE;
494  
495  
496 // *****************************************************************************
497 // *****************************************************************************
498 // Section: USB Host - Device Information Hooks
499 // *****************************************************************************
500 // *****************************************************************************
501  
502 extern BYTE *pCurrentConfigurationDescriptor; // Pointer to the current Configuration Descriptor of the attached device.
503 extern BYTE *pDeviceDescriptor; // Pointer to the Device Descriptor of the attached device.
504 extern USB_TPL usbTPL[]; // Application's Targeted Peripheral List.
505 extern CLIENT_DRIVER_TABLE usbClientDrvTable[]; // Application's client driver table.
506  
507  
508 // *****************************************************************************
509 // *****************************************************************************
510 // Section: Function Prototypes and Macro Functions
511 // *****************************************************************************
512 // *****************************************************************************
513  
514 /****************************************************************************
515 Function:
516 BYTE USBHostClearEndpointErrors( BYTE deviceAddress, BYTE endpoint )
517  
518 Summary:
519 This function clears an endpoint's internal error condition.
520  
521 Description:
522 This function is called to clear the internal error condition of a device's
523 endpoint. It should be called after the application has dealt with the
524 error condition on the device. This routine clears internal status only;
525 it does not interact with the device.
526  
527 Precondition:
528 None
529  
530 Parameters:
531 BYTE deviceAddress - Address of device
532 BYTE endpoint - Endpoint to clear error condition
533  
534 Return Values:
535 USB_SUCCESS - Errors cleared
536 USB_UNKNOWN_DEVICE - Device not found
537 USB_ENDPOINT_NOT_FOUND - Specified endpoint not found
538  
539 Remarks:
540 None
541 ***************************************************************************/
542  
543 BYTE USBHostClearEndpointErrors( BYTE deviceAddress, BYTE endpoint );
544  
545  
546 /****************************************************************************
547 Function:
548 BOOL USBHostDeviceSpecificClientDriver( BYTE deviceAddress )
549  
550 Summary:
551 This function indicates if the specified device has explicit client
552 driver support specified in the TPL.
553  
554 Description:
555 This function indicates if the specified device has explicit client
556 driver support specified in the TPL. It is used in client drivers'
557 USB_CLIENT_INIT routines to indicate that the client driver should be
558 used even though the class, subclass, and protocol values may not match
559 those normally required by the class. For example, some printing devices
560 do not fulfill all of the requirements of the printer class, so their
561 class, subclass, and protocol fields indicate a custom driver rather than
562 the printer class. But the printer class driver can still be used, with
563 minor limitations.
564  
565 Precondition:
566 None
567  
568 Parameters:
569 BYTE deviceAddress - Address of device
570  
571 Return Values:
572 TRUE - This device is listed in the TPL by VID andPID, and has explicit
573 client driver support.
574 FALSE - This device is not listed in the TPL by VID and PID.
575  
576 Remarks:
577 This function is used so client drivers can allow certain
578 devices to enumerate. For example, some printer devices indicate a custom
579 class rather than the printer class, even though the device has only minor
580 limitations from the full printer class. The printer client driver will
581 fail to initialize the device if it does not indicate printer class support
582 in its interface descriptor. The printer client driver could allow any
583 device with an interface that matches the printer class endpoint
584 configuration, but both printer and mass storage devices utilize one bulk
585 IN and one bulk OUT endpoint. So a mass storage device would be
586 erroneously initialized as a printer device. This function allows a
587 client driver to know that the client driver support was specified
588 explicitly in the TPL, so for this particular device only, the class,
589 subclass, and protocol fields can be safely ignored.
590 ***************************************************************************/
591  
592 BOOL USBHostDeviceSpecificClientDriver( BYTE deviceAddress );
593  
594  
595 /****************************************************************************
596 Function:
597 BYTE USBHostDeviceStatus( BYTE deviceAddress )
598  
599 Summary:
600 This function returns the current status of a device.
601  
602 Description:
603 This function returns the current status of a device. If the device is
604 in a holding state due to an error, the error is returned.
605  
606 Precondition:
607 None
608  
609 Parameters:
610 BYTE deviceAddress - Device address
611  
612 Return Values:
613 USB_DEVICE_ATTACHED - Device is attached and running
614 USB_DEVICE_DETACHED - No device is attached
615 USB_DEVICE_ENUMERATING - Device is enumerating
616 USB_HOLDING_OUT_OF_MEMORY - Not enough heap space available
617 USB_HOLDING_UNSUPPORTED_DEVICE - Invalid configuration or
618 unsupported class
619 USB_HOLDING_UNSUPPORTED_HUB - Hubs are not supported
620 USB_HOLDING_INVALID_CONFIGURATION - Invalid configuration requested
621 USB_HOLDING_PROCESSING_CAPACITY - Processing requirement excessive
622 USB_HOLDING_POWER_REQUIREMENT - Power requirement excessive
623 USB_HOLDING_CLIENT_INIT_ERROR - Client driver failed to initialize
624 Other - Device is holding in an error
625 state. The return value
626 indicates the error.
627  
628 Remarks:
629 None
630 ***************************************************************************/
631  
632 BYTE USBHostDeviceStatus( BYTE deviceAddress );
633  
634  
635 /****************************************************************************
636 Function:
637 BYTE * USBHostGetCurrentConfigurationDescriptor( BYTE deviceAddress )
638  
639 Description:
640 This function returns a pointer to the current configuration descriptor
641 of the requested device.
642  
643 Precondition:
644 None
645  
646 Parameters:
647 BYTE deviceAddress - Address of device
648  
649 Returns:
650 BYTE * - Pointer to the Configuration Descriptor.
651  
652 Remarks:
653 This will need to be expanded to a full function when multiple device
654 support is added.
655 ***************************************************************************/
656  
657 #define USBHostGetCurrentConfigurationDescriptor( deviceAddress) ( pCurrentConfigurationDescriptor )
658  
659  
660 /****************************************************************************
661 Function:
662 BYTE * USBHostGetDeviceDescriptor( BYTE deviceAddress )
663  
664 Description:
665 This function returns a pointer to the device descriptor of the
666 requested device.
667  
668 Precondition:
669 None
670  
671 Parameters:
672 BYTE deviceAddress - Address of device
673  
674 Returns:
675 BYTE * - Pointer to the Device Descriptor.
676  
677 Remarks:
678 This will need to be expanded to a full function when multiple device
679 support is added.
680 ***************************************************************************/
681  
682 #define USBHostGetDeviceDescriptor( deviceAddress ) ( pDeviceDescriptor )
683  
684  
685 /****************************************************************************
686 Function:
687 BYTE USBHostGetStringDescriptor ( BYTE deviceAddress, BYTE stringNumber,
688 BYTE LangID, BYTE *stringDescriptor, BYTE stringLength,
689 BYTE clientDriverID )
690  
691 Summary:
692 This routine initiates a request to obtains the requested string
693 descriptor.
694  
695 Description:
696 This routine initiates a request to obtains the requested string
697 descriptor. If the request cannot be started, the routine returns an
698 error. Otherwise, the request is started, and the requested string
699 descriptor is stored in the designated location.
700  
701 Example Usage:
702 <code>
703 USBHostGetStringDescriptor(
704 deviceAddress,
705 stringDescriptorNum,
706 LangID,
707 stringDescriptorBuffer,
708 sizeof(stringDescriptorBuffer),
709 0xFF
710 );
711  
712 while(1)
713 {
714 if(USBHostTransferIsComplete( deviceAddress , 0, &errorCode, &byteCount))
715 {
716 if(errorCode)
717 {
718 //There was an error reading the string, bail out of loop
719 }
720 else
721 {
722 //String is located in specified buffer, do something with it.
723  
724 //The length of the string is both in the byteCount variable
725 // as well as the first byte of the string itself
726 }
727 break;
728 }
729 USBTasks();
730 }
731 </code>
732  
733 Precondition:
734 None
735  
736 Parameters:
737 deviceAddress - Address of the device
738 stringNumber - Index of the desired string descriptor
739 LangID - The Language ID of the string to read (should be 0
740 if trying to read the language ID list
741 *stringDescriptor - Pointer to where to store the string.
742 stringLength - Maximum length of the returned string.
743 clientDriverID - Client driver to return the completion event to.
744  
745 Return Values:
746 USB_SUCCESS - The request was started successfully.
747 USB_UNKNOWN_DEVICE - Device not found
748 USB_INVALID_STATE - We must be in a normal running state.
749 USB_ENDPOINT_BUSY - The endpoint is currently processing a request.
750  
751 Remarks:
752 The returned string descriptor will be in the exact format as obtained
753 from the device. The length of the entire descriptor will be in the
754 first byte, and the descriptor type will be in the second. The string
755 itself is represented in UNICODE. Refer to the USB 2.0 Specification
756 for more information about the format of string descriptors.
757 ***************************************************************************/
758  
759 #define USBHostGetStringDescriptor( deviceAddress, stringNumber, LangID, stringDescriptor, stringLength, clientDriverID ) \
760 USBHostIssueDeviceRequest( deviceAddress, USB_SETUP_DEVICE_TO_HOST | USB_SETUP_TYPE_STANDARD | USB_SETUP_RECIPIENT_DEVICE, \
761 USB_REQUEST_GET_DESCRIPTOR, (USB_DESCRIPTOR_STRING << 8) | stringNumber, \
762 LangID, stringLength, stringDescriptor, USB_DEVICE_REQUEST_GET, clientDriverID )
763  
764  
765 /****************************************************************************
766 Function:
767 BOOL USBHostInit( unsigned long flags )
768  
769 Summary:
770 This function initializes the variables of the USB host stack.
771  
772 Description:
773 This function initializes the variables of the USB host stack. It does
774 not initialize the hardware. The peripheral itself is initialized in one
775 of the state machine states. Therefore, USBHostTasks() should be called
776 soon after this function.
777  
778 Precondition:
779 None
780  
781 Parameters:
782 flags - reserved
783  
784 Return Values:
785 TRUE - Initialization successful
786 FALSE - Could not allocate memory.
787  
788 Remarks:
789 If the endpoint list is empty, an entry is created in the endpoint list
790 for EP0. If the list is not empty, free all allocated memory other than
791 the EP0 node. This allows the routine to be called multiple times by the
792 application.
793 ***************************************************************************/
794  
795 BOOL USBHostInit( unsigned long flags );
796  
797  
798 /****************************************************************************
799 Function:
800 BOOL USBHostIsochronousBuffersCreate( ISOCHRONOUS_DATA * isocData,
801 BYTE numberOfBuffers, WORD bufferSize )
802  
803 Description:
804 This function initializes the isochronous data buffer information and
805 allocates memory for each buffer. This function will not allocate memory
806 if the buffer pointer is not NULL.
807  
808 Precondition:
809 None
810  
811 Parameters:
812 None
813  
814 Return Values:
815 TRUE - All buffers are allocated successfully.
816 FALSE - Not enough heap space to allocate all buffers - adjust the
817 project to provide more heap space.
818  
819 Remarks:
820 This function is available only if USB_SUPPORT_ISOCHRONOUS_TRANSFERS
821 is defined in usb_config.h.
822 ***************************************************************************/
823  
824 #ifdef USB_SUPPORT_ISOCHRONOUS_TRANSFERS
825 BOOL USBHostIsochronousBuffersCreate( ISOCHRONOUS_DATA * isocData, BYTE numberOfBuffers, WORD bufferSize );
826 #endif
827  
828  
829 /****************************************************************************
830 Function:
831 void USBHostIsochronousBuffersDestroy( ISOCHRONOUS_DATA * isocData, BYTE numberOfBuffers )
832  
833 Description:
834 This function releases all of the memory allocated for the isochronous
835 data buffers. It also resets all other information about the buffers.
836  
837 Precondition:
838 None
839  
840 Parameters:
841 None
842  
843 Returns:
844 None
845  
846 Remarks:
847 This function is available only if USB_SUPPORT_ISOCHRONOUS_TRANSFERS
848 is defined in usb_config.h.
849 ***************************************************************************/
850  
851 #ifdef USB_SUPPORT_ISOCHRONOUS_TRANSFERS
852 void USBHostIsochronousBuffersDestroy( ISOCHRONOUS_DATA * isocData, BYTE numberOfBuffers );
853 #endif
854  
855  
856 /****************************************************************************
857 Function:
858 void USBHostIsochronousBuffersReset( ISOCHRONOUS_DATA * isocData, BYTE numberOfBuffers )
859  
860 Description:
861 This function resets all the isochronous data buffers. It does not do
862 anything with the space allocated for the buffers.
863  
864 Precondition:
865 None
866  
867 Parameters:
868 None
869  
870 Returns:
871 None
872  
873 Remarks:
874 This function is available only if USB_SUPPORT_ISOCHRONOUS_TRANSFERS
875 is defined in usb_config.h.
876 ***************************************************************************/
877  
878 #ifdef USB_SUPPORT_ISOCHRONOUS_TRANSFERS
879 void USBHostIsochronousBuffersReset( ISOCHRONOUS_DATA * isocData, BYTE numberOfBuffers );
880 #endif
881  
882  
883 /****************************************************************************
884 Function:
885 BYTE USBHostIssueDeviceRequest( BYTE deviceAddress, BYTE bmRequestType,
886 BYTE bRequest, WORD wValue, WORD wIndex, WORD wLength,
887 BYTE *data, BYTE dataDirection, BYTE clientDriverID )
888  
889 Summary:
890 This function sends a standard device request to the attached device.
891  
892 Description:
893 This function sends a standard device request to the attached device.
894 The user must pass in the parameters of the device request. If there is
895 input or output data associated with the request, a pointer to the data
896 must be provided. The direction of the associated data (input or output)
897 must also be indicated.
898  
899 This function does no special processing in regards to the request except
900 for three requests. If SET INTERFACE is sent, then DTS is reset for all
901 endpoints. If CLEAR FEATURE (ENDPOINT HALT) is sent, then DTS is reset
902 for that endpoint. If SET CONFIGURATION is sent, the request is aborted
903 with a failure. The function USBHostSetDeviceConfiguration() must be
904 called to change the device configuration, since endpoint definitions may
905 change.
906  
907 Precondition:
908 The host state machine should be in the running state, and no reads or
909 writes to EP0 should be in progress.
910  
911 Parameters:
912 BYTE deviceAddress - Device address
913 BYTE bmRequestType - The request type as defined by the USB
914 specification.
915 BYTE bRequest - The request as defined by the USB specification.
916 WORD wValue - The value for the request as defined by the USB
917 specification.
918 WORD wIndex - The index for the request as defined by the USB
919 specification.
920 WORD wLength - The data length for the request as defined by the
921 USB specification.
922 BYTE *data - Pointer to the data for the request.
923 BYTE dataDirection - USB_DEVICE_REQUEST_SET or USB_DEVICE_REQUEST_GET
924 BYTE clientDriverID - Client driver to send the event to.
925  
926 Return Values:
927 USB_SUCCESS - Request processing started
928 USB_UNKNOWN_DEVICE - Device not found
929 USB_INVALID_STATE - The host must be in a normal running state
930 to do this request
931 USB_ENDPOINT_BUSY - A read or write is already in progress
932 USB_ILLEGAL_REQUEST - SET CONFIGURATION cannot be performed with
933 this function.
934  
935 Remarks:
936 DTS reset is done before the command is issued.
937 ***************************************************************************/
938  
939 BYTE USBHostIssueDeviceRequest( BYTE deviceAddress, BYTE bmRequestType, BYTE bRequest,
940 WORD wValue, WORD wIndex, WORD wLength, BYTE *data, BYTE dataDirection,
941 BYTE clientDriverID );
942  
943  
944 /****************************************************************************
945 Function:
946 BYTE USBHostRead( BYTE deviceAddress, BYTE endpoint, BYTE *pData,
947 DWORD size )
948 Summary:
949 This function initiates a read from the attached device.
950  
951 Description:
952 This function initiates a read from the attached device.
953  
954 If the endpoint is isochronous, special conditions apply. The pData and
955 size parameters have slightly different meanings, since multiple buffers
956 are required. Once started, an isochronous transfer will continue with
957 no upper layer intervention until USBHostTerminateTransfer() is called.
958 The ISOCHRONOUS_DATA_BUFFERS structure should not be manipulated until
959 the transfer is terminated.
960  
961 To clarify parameter usage and to simplify casting, use the macro
962 USBHostReadIsochronous() when reading from an isochronous endpoint.
963  
964 Precondition:
965 None
966  
967 Parameters:
968 BYTE deviceAddress - Device address
969 BYTE endpoint - Endpoint number
970 BYTE *pData - Pointer to where to store the data. If the endpoint
971 is isochronous, this points to an
972 ISOCHRONOUS_DATA_BUFFERS structure, with multiple
973 data buffer pointers.
974 DWORD size - Number of data bytes to read. If the endpoint is
975 isochronous, this is the number of data buffer
976 pointers pointed to by pData.
977  
978 Return Values:
979 USB_SUCCESS - Read started successfully.
980 USB_UNKNOWN_DEVICE - Device with the specified address not found.
981 USB_INVALID_STATE - We are not in a normal running state.
982 USB_ENDPOINT_ILLEGAL_TYPE - Must use USBHostControlRead to read
983 from a control endpoint.
984 USB_ENDPOINT_ILLEGAL_DIRECTION - Must read from an IN endpoint.
985 USB_ENDPOINT_STALLED - Endpoint is stalled. Must be cleared
986 by the application.
987 USB_ENDPOINT_ERROR - Endpoint has too many errors. Must be
988 cleared by the application.
989 USB_ENDPOINT_BUSY - A Read is already in progress.
990 USB_ENDPOINT_NOT_FOUND - Invalid endpoint.
991  
992 Remarks:
993 None
994 ***************************************************************************/
995  
996 BYTE USBHostRead( BYTE deviceAddress, BYTE endpoint, BYTE *data, DWORD size );
997  
998  
999 /****************************************************************************
1000 Function:
1001 BYTE USBHostReadIsochronous( BYTE deviceAddress, BYTE endpoint,
1002 ISOCHRONOUS_DATA *pIsochronousData )
1003  
1004 Summary:
1005 This function initiates a read from an isochronous endpoint on the
1006 attached device.
1007  
1008 Description:
1009 This function initiates a read from an isochronous endpoint on the
1010 attached device. If the endpoint is not isochronous, use USBHostRead().
1011  
1012 Once started, an isochronous transfer will continue with no upper layer
1013 intervention until USBHostTerminateTransfer() is called.
1014  
1015 Precondition:
1016 None
1017  
1018 Parameters:
1019 BYTE deviceAddress - Device address
1020 BYTE endpoint - Endpoint number
1021 ISOCHRONOUS_DATA *pIsochronousData - Pointer to an ISOCHRONOUS_DATA
1022 structure, containing information for the
1023 application and the host driver for the
1024 isochronous transfer.
1025  
1026 Return Values:
1027 USB_SUCCESS - Read started successfully.
1028 USB_UNKNOWN_DEVICE - Device with the specified address not found.
1029 USB_INVALID_STATE - We are not in a normal running state.
1030 USB_ENDPOINT_ILLEGAL_TYPE - Must use USBHostControlRead to read
1031 from a control endpoint.
1032 USB_ENDPOINT_ILLEGAL_DIRECTION - Must read from an IN endpoint.
1033 USB_ENDPOINT_STALLED - Endpoint is stalled. Must be cleared
1034 by the application.
1035 USB_ENDPOINT_ERROR - Endpoint has too many errors. Must be
1036 cleared by the application.
1037 USB_ENDPOINT_BUSY - A Read is already in progress.
1038 USB_ENDPOINT_NOT_FOUND - Invalid endpoint.
1039  
1040 Remarks:
1041 None
1042 ***************************************************************************/
1043  
1044 #define USBHostReadIsochronous( a, e, p ) USBHostRead( a, e, (BYTE *)p, (DWORD)0 );
1045  
1046  
1047 /****************************************************************************
1048 Function:
1049 BYTE USBHostResetDevice( BYTE deviceAddress )
1050  
1051 Summary:
1052 This function resets an attached device.
1053  
1054 Description:
1055 This function places the device back in the RESET state, to issue RESET
1056 signaling. It can be called only if the state machine is not in the
1057 DETACHED state.
1058  
1059 Precondition:
1060 None
1061  
1062 Parameters:
1063 BYTE deviceAddress - Device address
1064  
1065 Return Values:
1066 USB_SUCCESS - Success
1067 USB_UNKNOWN_DEVICE - Device not found
1068 USB_ILLEGAL_REQUEST - Device cannot RESUME unless it is suspended
1069  
1070 Remarks:
1071 In order to do a full clean-up, the state is set back to STATE_DETACHED
1072 rather than a reset state. The ATTACH interrupt will automatically be
1073 triggered when the module is re-enabled, and the proper reset will be
1074 performed.
1075 ***************************************************************************/
1076  
1077 BYTE USBHostResetDevice( BYTE deviceAddress );
1078  
1079  
1080 /****************************************************************************
1081 Function:
1082 BYTE USBHostResumeDevice( BYTE deviceAddress )
1083  
1084 Summary:
1085 This function issues a RESUME to the attached device.
1086  
1087 Description:
1088 This function issues a RESUME to the attached device. It can called only
1089 if the state machine is in the suspend state.
1090  
1091 Precondition:
1092 None
1093  
1094 Parameters:
1095 BYTE deviceAddress - Device address
1096  
1097 Return Values:
1098 USB_SUCCESS - Success
1099 USB_UNKNOWN_DEVICE - Device not found
1100 USB_ILLEGAL_REQUEST - Device cannot RESUME unless it is suspended
1101  
1102 Remarks:
1103 None
1104 ***************************************************************************/
1105  
1106 BYTE USBHostResumeDevice( BYTE deviceAddress );
1107  
1108  
1109 /****************************************************************************
1110 Function:
1111 BYTE USBHostSetDeviceConfiguration( BYTE deviceAddress, BYTE configuration )
1112  
1113 Summary:
1114 This function changes the device's configuration.
1115  
1116 Description:
1117 This function is used by the application to change the device's
1118 Configuration. This function must be used instead of
1119 USBHostIssueDeviceRequest(), because the endpoint definitions may change.
1120  
1121 To see when the reconfiguration is complete, use the USBHostDeviceStatus()
1122 function. If configuration is still in progress, this function will
1123 return USB_DEVICE_ENUMERATING.
1124  
1125 Precondition:
1126 The host state machine should be in the running state, and no reads or
1127 writes should be in progress.
1128  
1129 Parameters:
1130 BYTE deviceAddress - Device address
1131 BYTE configuration - Index of the new configuration
1132  
1133 Return Values:
1134 USB_SUCCESS - Process of changing the configuration was started
1135 successfully.
1136 USB_UNKNOWN_DEVICE - Device not found
1137 USB_INVALID_STATE - This function cannot be called during enumeration
1138 or while performing a device request.
1139 USB_BUSY - No IN or OUT transfers may be in progress.
1140  
1141 Example:
1142 <code>
1143 rc = USBHostSetDeviceConfiguration( attachedDevice, configuration );
1144 if (rc)
1145 {
1146 // Error - cannot set configuration.
1147 }
1148 else
1149 {
1150 while (USBHostDeviceStatus( attachedDevice ) == USB_DEVICE_ENUMERATING)
1151 {
1152 USBHostTasks();
1153 }
1154 }
1155 if (USBHostDeviceStatus( attachedDevice ) != USB_DEVICE_ATTACHED)
1156 {
1157 // Error - cannot set configuration.
1158 }
1159 </code>
1160  
1161 Remarks:
1162 If an invalid configuration is specified, this function cannot return
1163 an error. Instead, the event USB_UNSUPPORTED_DEVICE will the sent to the
1164 application layer and the device will be placed in a holding state with a
1165 USB_HOLDING_UNSUPPORTED_DEVICE error returned by USBHostDeviceStatus().
1166 ***************************************************************************/
1167  
1168 BYTE USBHostSetDeviceConfiguration( BYTE deviceAddress, BYTE configuration );
1169  
1170  
1171 /****************************************************************************
1172 Function:
1173 BYTE USBHostSetNAKTimeout( BYTE deviceAddress, BYTE endpoint, WORD flags,
1174 WORD timeoutCount )
1175  
1176 Summary:
1177 This function specifies NAK timeout capability.
1178  
1179 Description:
1180 This function is used to set whether or not an endpoint on a device
1181 should time out a transaction based on the number of NAKs received, and
1182 if so, how many NAKs are allowed before the timeout.
1183  
1184 Precondition:
1185 None
1186  
1187 Parameters:
1188 BYTE deviceAddress - Device address
1189 BYTE endpoint - Endpoint number to configure
1190 WORD flags - Bit 0:
1191 * 0 = disable NAK timeout
1192 * 1 = enable NAK timeout
1193 WORD timeoutCount - Number of NAKs allowed before a timeout
1194  
1195 Return Values:
1196 USB_SUCCESS - NAK timeout was configured successfully.
1197 USB_UNKNOWN_DEVICE - Device not found.
1198 USB_ENDPOINT_NOT_FOUND - The specified endpoint was not found.
1199  
1200 Remarks:
1201 None
1202 ***************************************************************************/
1203  
1204 BYTE USBHostSetNAKTimeout( BYTE deviceAddress, BYTE endpoint, WORD flags, WORD timeoutCount );
1205  
1206  
1207 /****************************************************************************
1208 Function:
1209 void USBHostShutdown( void )
1210  
1211 Description:
1212 This function turns off the USB module and frees all unnecessary memory.
1213 This routine can be called by the application layer to shut down all
1214 USB activity, which effectively detaches all devices. The event
1215 EVENT_DETACH will be sent to the client drivers for the attached device,
1216 and the event EVENT_VBUS_RELEASE_POWER will be sent to the application
1217 layer.
1218  
1219 Precondition:
1220 None
1221  
1222 Parameters:
1223 None - None
1224  
1225 Returns:
1226 None
1227  
1228 Remarks:
1229 None
1230 ***************************************************************************/
1231  
1232 void USBHostShutdown( void );
1233  
1234  
1235 /****************************************************************************
1236 Function:
1237 BYTE USBHostSuspendDevice( BYTE deviceAddress )
1238  
1239 Summary:
1240 This function suspends a device.
1241  
1242 Description:
1243 This function put a device into an IDLE state. It can only be called
1244 while the state machine is in normal running mode. After 3ms, the
1245 attached device should go into SUSPEND mode.
1246  
1247 Precondition:
1248 None
1249  
1250 Parameters:
1251 BYTE deviceAddress - Device to suspend
1252  
1253 Return Values:
1254 USB_SUCCESS - Success
1255 USB_UNKNOWN_DEVICE - Device not found
1256 USB_ILLEGAL_REQUEST - Cannot suspend unless device is in normal run mode
1257  
1258 Remarks:
1259 None
1260 ****************************************************************************/
1261  
1262 BYTE USBHostSuspendDevice( BYTE deviceAddress );
1263  
1264  
1265 /****************************************************************************
1266 Function:
1267 void USBHostTasks( void )
1268  
1269 Summary:
1270 This function executes the host tasks for USB host operation.
1271  
1272 Description:
1273 This function executes the host tasks for USB host operation. It must be
1274 executed on a regular basis to keep everything functioning.
1275  
1276 The primary purpose of this function is to handle device attach/detach
1277 and enumeration. It does not handle USB packet transmission or
1278 reception; that must be done in the USB interrupt handler to ensure
1279 timely operation.
1280  
1281 This routine should be called on a regular basis, but there is no
1282 specific time requirement. Devices will still be able to attach,
1283 enumerate, and detach, but the operations will occur more slowly as the
1284 calling interval increases.
1285  
1286 Precondition:
1287 USBHostInit() has been called.
1288  
1289 Parameters:
1290 None
1291  
1292 Returns:
1293 None
1294  
1295 Remarks:
1296 None
1297 ***************************************************************************/
1298  
1299 void USBHostTasks( void );
1300  
1301  
1302 /****************************************************************************
1303 Function:
1304 void USBHostTerminateTransfer( BYTE deviceAddress, BYTE endpoint )
1305  
1306  
1307 Summary:
1308 This function terminates the current transfer for the given endpoint.
1309  
1310 Description:
1311 This function terminates the current transfer for the given endpoint. It
1312 can be used to terminate reads or writes that the device is not
1313 responding to. It is also the only way to terminate an isochronous
1314 transfer.
1315  
1316 Precondition:
1317 None
1318  
1319 Parameters:
1320 BYTE deviceAddress - Device address
1321 BYTE endpoint - Endpoint number
1322  
1323 Returns:
1324 None
1325  
1326 Remarks:
1327 None
1328 ***************************************************************************/
1329  
1330 void USBHostTerminateTransfer( BYTE deviceAddress, BYTE endpoint );
1331  
1332  
1333 /****************************************************************************
1334 Function:
1335 BOOL USBHostTransferIsComplete( BYTE deviceAddress, BYTE endpoint,
1336 BYTE *errorCode, DWORD *byteCount )
1337  
1338 Summary:
1339 This function initiates whether or not the last endpoint transaction is
1340 complete.
1341  
1342 Description:
1343 This function initiates whether or not the last endpoint transaction is
1344 complete. If it is complete, an error code and the number of bytes
1345 transferred are returned.
1346  
1347 For isochronous transfers, byteCount is not valid. Instead, use the
1348 returned byte counts for each EVENT_TRANSFER event that was generated
1349 during the transfer.
1350  
1351 Precondition:
1352 None
1353  
1354 Parameters:
1355 BYTE deviceAddress - Device address
1356 BYTE endpoint - Endpoint number
1357 BYTE *errorCode - Error code indicating the status of the transfer.
1358 Only valid if the transfer is complete.
1359 DWORD *byteCount - The number of bytes sent or received. Invalid
1360 for isochronous transfers.
1361  
1362 Return Values:
1363 TRUE - Transfer is complete.
1364 FALSE - Transfer is not complete.
1365  
1366 Remarks:
1367 Possible values for errorCode are:
1368 * USB_SUCCESS - Transfer successful
1369 * USB_UNKNOWN_DEVICE - Device not attached
1370 * USB_ENDPOINT_STALLED - Endpoint STALL'd
1371 * USB_ENDPOINT_ERROR_ILLEGAL_PID - Illegal PID returned
1372 * USB_ENDPOINT_ERROR_BIT_STUFF
1373 * USB_ENDPOINT_ERROR_DMA
1374 * USB_ENDPOINT_ERROR_TIMEOUT
1375 * USB_ENDPOINT_ERROR_DATA_FIELD
1376 * USB_ENDPOINT_ERROR_CRC16
1377 * USB_ENDPOINT_ERROR_END_OF_FRAME
1378 * USB_ENDPOINT_ERROR_PID_CHECK
1379 * USB_ENDPOINT_ERROR - Other error
1380 ***************************************************************************/
1381  
1382 BOOL USBHostTransferIsComplete( BYTE deviceAddress, BYTE endpoint, BYTE *errorCode, DWORD *byteCount );
1383  
1384  
1385 /****************************************************************************
1386 Function:
1387 BYTE USBHostVbusEvent( USB_EVENT vbusEvent, BYTE hubAddress,
1388 BYTE portNumber)
1389  
1390 Summary:
1391 This function handles Vbus events that are detected by the application.
1392  
1393 Description:
1394 This function handles Vbus events that are detected by the application.
1395 Since Vbus management is application dependent, the application is
1396 responsible for monitoring Vbus and detecting overcurrent conditions
1397 and removal of the overcurrent condition. If the application detects
1398 an overcurrent condition, it should call this function with the event
1399 EVENT_VBUS_OVERCURRENT with the address of the hub and port number that
1400 has the condition. When a port returns to normal operation, the
1401 application should call this function with the event
1402 EVENT_VBUS_POWER_AVAILABLE so the stack knows that it can allow devices
1403 to attach to that port.
1404  
1405 Precondition:
1406 None
1407  
1408 Parameters:
1409 USB_EVENT vbusEvent - Vbus event that occured. Valid events:
1410 * EVENT_VBUS_OVERCURRENT
1411 * EVENT_VBUS_POWER_AVAILABLE
1412 BYTE hubAddress - Address of the hub device (USB_ROOT_HUB for the
1413 root hub)
1414 BYTE portNumber - Number of the physical port on the hub (0 - based)
1415  
1416 Return Values:
1417 USB_SUCCESS - Event handled
1418 USB_ILLEGAL_REQUEST - Invalid event, hub, or port
1419  
1420 Remarks:
1421 None
1422 ***************************************************************************/
1423  
1424 BYTE USBHostVbusEvent(USB_EVENT vbusEvent, BYTE hubAddress, BYTE portNumber);
1425  
1426  
1427 /****************************************************************************
1428 Function:
1429 BYTE USBHostWrite( BYTE deviceAddress, BYTE endpoint, BYTE *data,
1430 DWORD size )
1431  
1432 Summary:
1433 This function initiates a write to the attached device.
1434  
1435 Description:
1436 This function initiates a write to the attached device. The data buffer
1437 pointed to by *data must remain valid during the entire time that the
1438 write is taking place; the data is not buffered by the stack.
1439  
1440 If the endpoint is isochronous, special conditions apply. The pData and
1441 size parameters have slightly different meanings, since multiple buffers
1442 are required. Once started, an isochronous transfer will continue with
1443 no upper layer intervention until USBHostTerminateTransfer() is called.
1444 The ISOCHRONOUS_DATA_BUFFERS structure should not be manipulated until
1445 the transfer is terminated.
1446  
1447 To clarify parameter usage and to simplify casting, use the macro
1448 USBHostWriteIsochronous() when writing to an isochronous endpoint.
1449  
1450 Precondition:
1451 None
1452  
1453 Parameters:
1454 BYTE deviceAddress - Device address
1455 BYTE endpoint - Endpoint number
1456 BYTE *data - Pointer to where the data is stored. If the endpoint
1457 is isochronous, this points to an
1458 ISOCHRONOUS_DATA_BUFFERS structure, with multiple
1459 data buffer pointers.
1460 DWORD size - Number of data bytes to send. If the endpoint is
1461 isochronous, this is the number of data buffer
1462 pointers pointed to by pData.
1463  
1464 Return Values:
1465 USB_SUCCESS - Write started successfully.
1466 USB_UNKNOWN_DEVICE - Device with the specified address not found.
1467 USB_INVALID_STATE - We are not in a normal running state.
1468 USB_ENDPOINT_ILLEGAL_TYPE - Must use USBHostControlWrite to write
1469 to a control endpoint.
1470 USB_ENDPOINT_ILLEGAL_DIRECTION - Must write to an OUT endpoint.
1471 USB_ENDPOINT_STALLED - Endpoint is stalled. Must be cleared
1472 by the application.
1473 USB_ENDPOINT_ERROR - Endpoint has too many errors. Must be
1474 cleared by the application.
1475 USB_ENDPOINT_BUSY - A Write is already in progress.
1476 USB_ENDPOINT_NOT_FOUND - Invalid endpoint.
1477  
1478 Remarks:
1479 None
1480 ***************************************************************************/
1481  
1482 BYTE USBHostWrite( BYTE deviceAddress, BYTE endpoint, BYTE *data, DWORD size );
1483  
1484  
1485 /****************************************************************************
1486 Function:
1487 BYTE USBHostWriteIsochronous( BYTE deviceAddress, BYTE endpoint,
1488 ISOCHRONOUS_DATA *pIsochronousData )
1489  
1490 Summary:
1491 This function initiates a write to an isochronous endpoint on the
1492 attached device.
1493  
1494 Description:
1495 This function initiates a write to an isochronous endpoint on the
1496 attached device. If the endpoint is not isochronous, use USBHostWrite().
1497  
1498 Once started, an isochronous transfer will continue with
1499 no upper layer intervention until USBHostTerminateTransfer() is called.
1500  
1501 Precondition:
1502 None
1503  
1504 Parameters:
1505 BYTE deviceAddress - Device address
1506 BYTE endpoint - Endpoint number
1507 ISOCHRONOUS_DATA *pIsochronousData - Pointer to an ISOCHRONOUS_DATA
1508 structure, containing information for the
1509 application and the host driver for the
1510 isochronous transfer.
1511  
1512 Return Values:
1513 USB_SUCCESS - Write started successfully.
1514 USB_UNKNOWN_DEVICE - Device with the specified address not found.
1515 USB_INVALID_STATE - We are not in a normal running state.
1516 USB_ENDPOINT_ILLEGAL_TYPE - Must use USBHostControlWrite to write
1517 to a control endpoint.
1518 USB_ENDPOINT_ILLEGAL_DIRECTION - Must write to an OUT endpoint.
1519 USB_ENDPOINT_STALLED - Endpoint is stalled. Must be cleared
1520 by the application.
1521 USB_ENDPOINT_ERROR - Endpoint has too many errors. Must be
1522 cleared by the application.
1523 USB_ENDPOINT_BUSY - A Write is already in progress.
1524 USB_ENDPOINT_NOT_FOUND - Invalid endpoint.
1525  
1526 Remarks:
1527 None
1528 ***************************************************************************/
1529  
1530 #define USBHostWriteIsochronous( a, e, p ) USBHostWrite( a, e, (BYTE *)p, (DWORD)0 );
1531  
1532  
1533 #endif
1534  
1535 // *****************************************************************************
1536 // EOF
1537  
1538  
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3