VxWorks API Reference : USB libraries
usbLib [USB] - USB utility functions
usbTransferTime( ) - Calculates bus time required for a USB transfer
usbRecurringTime( ) - calculates recurring time for interrupt/isoch transfers
usbDescrParseSkip( ) - search for a descriptor and increment buffer
usbDescrParse( ) - search a buffer for the a particular USB descriptor
usbConfigCountGet( ) - Retrieves number of device configurations
usbConfigDescrGet( ) - reads full configuration descriptor from device
usbHidReportSet( ) - Issues a SET_REPORT request to a USB HID
usbHidIdleSet( ) - Issues a SET_IDLE request to a USB HID
usbHidProtocolSet( ) - Issues a SET_PROTOCOL request to a USB HID
This modules contains miscellaneous functions which may be used by the USB driver (USBD), USB HCD (USB Host Controller Driver), or by USBD clients.
usbTransferTime( ) - Calculates bus time required for a USB transfer
UINT32 usbTransferTime ( UINT16 transferType, /* transfer type */ UINT16 direction, /* transfer direction */ UINT16 speed, /* speed of pipe */ UINT32 bytes, /* number of bytes for packet to be calc'd */ UINT32 hostDelay, /* host controller delay per packet */ UINT32 hostHubLsSetup /* host controller time for low-speed setup */ )
This function calculates the amount of time a transfer of a given number of bytes will require on the bus - measured in nanoseconds (10E-9 seconds). The formulas used here are taken from Section 5.9.3 of Revision 1.1 of the USB spec.
transferType, direction, and speed should describe the characteristics of the pipe/transfer as USB_XFRTYPE_xxxx, USB_DIR_xxxx, and USB_SPEED_xxxx, repsectively. bytes is the size of the packet for which the transfer time should be calculated. hostDelay and hostHubLsSetup are the host delay and low-speed hub setup times in nanoseconds, respectively, and are host-controller specific.
Worst case number of nanoseconds required for transfer
usbRecurringTime( ) - calculates recurring time for interrupt/isoch transfers
UINT32 usbRecurringTime ( UINT16 transferType, /* transfer type */ UINT16 direction, /* transfer direction */ UINT16 speed, /* speed of pipe */ UINT16 packetSize, /* max packet size for endpoint */ UINT32 bandwidth, /* bytes/frame or bytes/sec depending on pipe */ UINT32 hostDelay, /* host controller delay per packet */ UINT32 hostHubLsSetup /* host controller time for low-speed setup */ )
For recurring transfers (e.g., interrupt or isochronous transfers) an HCD needs to be able to calculate the amount of bus time - measured in nanoseconds - which will be used by the transfer.
transferType specifies the type of transfer. For USB_XFRTYPE_CONTROL and USB_XFRTYPE_BULK, the calculated time is always 0...these are not recurring transfers. For USB_XFRTYPE_INTERRUPT, bandwidth must express the number of bytes to be transferred in each frame. For USB_XFRTYPE_ISOCH, bandwidth must express the number of bytes to be transferred in each second. The parameter is treated differently to allow greater flexibility in determining the true bandwidth requirements for each type of pipe.
worst case number of nanoseconds required for transfer.
usbDescrParseSkip( ) - search for a descriptor and increment buffer
pVOID usbDescrParseSkip ( pUINT8 * ppBfr, /* buffer to parse */ pUINT16 pBfrLen, /* length of buffer to parse */ UINT8 descriptorType /* type of descriptor being sought */ )
Searches ppBfr up to pBfrLen bytes for a descriptor of type matching descriptorType. Returns a pointer to the descriptor if found. ppBfr and pBfrLen are updated to reflect the next location in the buffer and the remaining size of the buffer, respectively.
pointer to indicated descriptor, or NULL if descr not found.
usbDescrParse( ) - search a buffer for the a particular USB descriptor
pVOID usbDescrParse ( pUINT8 pBfr, /* buffer to parse */ UINT16 bfrLen, /* length of buffer to parse */ UINT8 descriptorType /* type of descriptor being sought */ )
Searches pBfr up to bfrLen bytes for a descriptor of type matching descriptorType. Returns a pointer to the descriptor if found.
pointer to indicated descriptor, or NULL if descr not found
usbConfigCountGet( ) - Retrieves number of device configurations
STATUS usbConfigCountGet ( USBD_CLIENT_HANDLE usbdClientHandle, /* caller's USBD client handle */ USBD_NODE_ID nodeId, /* device node ID */ pUINT16 pNumConfig /* bfr to receive nbr of config */ )
Using the usbdClientHandle provided by the caller, this function reads the nodeId's device descriptor and returns the number of configurations supported by the device in pNumConfig.
OK, or ERROR if unable to read device descriptor
usbConfigDescrGet( ) - reads full configuration descriptor from device
STATUS usbConfigDescrGet ( USBD_CLIENT_HANDLE usbdClientHandle, /* caller's USBD client handle */ USBD_NODE_ID nodeId, /* device node ID */ UINT16 cfgNo, /* specifies configuration nbr */ pUINT16 pBfrLen, /* receives length of buffer */ pUINT8 * ppBfr /* receives pointer to buffer */ )
This function reads the configuration descriptor cfgNo and all associated descriptors (interface, endpoint, etc.) for the device specified by nodeId. The total amount of data returned by a device is variable, so, this function pre-reads just the configuration descriptor and uses the "totalLength" field from that descriptor to determine the total length of the configuration descriptor and its associated descriptors.
This function uses the macro OSS_MALLOC( ) to allocate a buffer for the complete descriptor. The size and location of the buffer are returned in ppBfr and pBfrLen. It is the caller's responsibility to free the buffer using the OSS_FREE( ) macro.
OK, or ERROR if unable to read descriptor
usbHidReportSet( ) - Issues a SET_REPORT request to a USB HID
STATUS usbHidReportSet ( USBD_CLIENT_HANDLE usbdClientHandle, /* caller's USBD client handle */ USBD_NODE_ID nodeId, /* desired node */ UINT16 interface, /* desired interface */ UINT16 reportType, /* report type */ UINT16 reportId, /* report Id */ pUINT8 reportBfr, /* report value */ UINT16 reportLen /* length of report */ )
Using the usbdClientHandle provided by the caller, this function issues a SET_REPORT request to the indicated nodeId. The caller must also specify the interface, reportType, reportId, reportBfr, and reportLen. Refer to Section 7.2.2 of the USB HID specification for further detail.
OK, or ERROR if unable to issue SET_REPORT request.
usbHidIdleSet( ) - Issues a SET_IDLE request to a USB HID
STATUS usbHidIdleSet ( USBD_CLIENT_HANDLE usbdClientHandle, /* caller's USBD client handle */ USBD_NODE_ID nodeId, /* desired node */ UINT16 interface, /* desired interface */ UINT16 reportId, /* desired report */ UINT16 duration /* idle duration */ )
Using the usbdClientHandle provided by the caller, this function issues a SET_IDLE request to the indicated nodeId. The caller must also specify the interface, reportId, and duration. If the duration is zero, the idle period is infinite. If duration is non-zero, then it expresses time in 4msec units (e.g., a duration of 1 = 4msec, 2 = 8msec, and so forth). Refer to Section 7.2.4 of the USB HID specification for further details.
OK, or ERROR if unable to issue SET_IDLE request.
usbHidProtocolSet( ) - Issues a SET_PROTOCOL request to a USB HID
STATUS usbHidProtocolSet ( USBD_CLIENT_HANDLE usbdClientHandle, /* caller's USBD client handle */ USBD_NODE_ID nodeId, /* desired node */ UINT16 interface, /* desired interface */ UINT16 protocol /* USB_HID_PROTOCOL_xxxx */ )
Using the usbdClientHandle provided by the caller, this function issues a SET_PROTOCOL request to the indicated nodeId. The caller must specify the interface and the desired protocol. The protocol is expressed as USB_HID_PROTOCOL_xxxx. Refer to Section 7.2.6 of the USB HID specification for further details.
OK, or ERROR if unable to issue SET_PROTOCOL request.