VxWorks API Reference : USB libraries
usbHcdLib [USB] - Implements HCD functional API
usbHcdAttach( ) - Attach to the HCD
usbHcdDetach( ) - Detach from the HCD
usbHcdSetBusState( ) - sets bus suspend/resume state
usbHcdCurrentFrameGet( ) - Returns current frame number for a bus
usbHcdIrpSubmit( ) - Submits an IRP to the HCD for execution
usbHcdIrpCancel( ) - Requests the HCD to cancel a pending IRP
usbHcdPipeCreate( ) - create a pipe and calculate / reserve bus bandwidth
usbHcdPipeDestroy( ) - destroys pipe and releases previously allocated bandwidth
usbHcdPipeModify( ) - modify characteristics of an existing pipe
usbHcdSofIntervalGet( ) - retrieves SOF interval for a bus
usbHcdSofIntervalSet( ) - sets SOF interval for a bus
This file implements the functional interface to the HCD.
usbHcdAttach( ) - Attach to the HCD
STATUS usbHcdAttach ( HCD_EXEC_FUNC hcdExecFunc, /* HCD's primary entry point */ pVOID param, /* HCD-specific param */ USB_HCD_MNGMT_CALLBACK callback, /* management callback */ pVOID callbackParam, /* parameter to management callback */ pHCD_NEXUS pNexus, /* nexus will be initialized on */ /* return */ pUINT16 pBusCount )
Attempts to connect the caller to the HCD. The param value is HCD- implementation-specific. Returns an HCD_CLIENT_HANDLE if the HCD was able to initialize properly. If pBusCount is not NULL, also returns number of buses managed through this nexus.
callback is an optional pointer to a routine which should be invoked if the HCD detects "management events" (e.g., remote wakeup/resume). callbackParam is a caller-defined parameter which will be passed to the callback routine each time it is invoked.
OK, or ERROR if unable to initialize HCD.
usbHcdDetach( ) - Detach from the HCD
STATUS usbHcdDetach ( pHCD_NEXUS pNexus /* client's nexus */ )
Disconnects a caller which has previously attached to an HCD.
OK, or ERROR if unable to shutdown HCD.
usbHcdSetBusState( ) - sets bus suspend/resume state
STATUS usbHcdSetBusState ( pHCD_NEXUS pNexus, /* client's nexus */ UINT16 busNo, /* bus number */ UINT16 busState /* desired bus state */ )
Sets the state for bus no as specified in busState. busState is a bit mask. Typically, the caller will set USB_BUS_SUSPEND or USB_BUS_RESUME to suspend or resume the indicated bus.
OK, or ERROR if unable to place bus in specified state
usbHcdCurrentFrameGet( ) - Returns current frame number for a bus
STATUS usbHcdCurrentFrameGet ( pHCD_NEXUS pNexus, /* client's nexus */ UINT16 busNo, /* bus number */ pUINT32 pFrameNo, /* current frame number */ pUINT32 pFrameWindow /* size of frame window */ )
Returns the current pFrameNo and the frame window, pFrameWindow for the specified bus.
OK, or ERROR if unable to retrieve current frame number.
usbHcdIrpSubmit( ) - Submits an IRP to the HCD for execution
STATUS usbHcdIrpSubmit ( pHCD_NEXUS pNexus, /* client's nexus */ HCD_PIPE_HANDLE pipeHandle, /* pipe to which IRP is directed */ pUSB_IRP pIrp /* IRP to be executed */ )
This function passes the pIrp to the HCD for scheduling. The function returns as soon as the HCD has queued/scheduled the IRP. The pIrp must include a non-NULL callback which will be invoked upon IRP completion.
OK, or ERROR if unable to submit IRP for transfer.
usbHcdIrpCancel( ) - Requests the HCD to cancel a pending IRP
STATUS usbHcdIrpCancel ( pHCD_NEXUS pNexus, /* client's nexus */ pUSB_IRP pIrp /* IRP to be canceled */ )
This function requests the HCD to cancel the specified pIrp. If the IRP can be canceled before it completes execution normally, its result will be set to S_usbHcdLib_IRP_CANCELED and the IRPs callback will be invoked.
There is no guarantee that an IRP, once submitted to the HCD, can be canceled before it otherwise completes normally (or times out).
OK, or ERROR if unable to cancel transfer.
usbHcdPipeCreate( ) - create a pipe and calculate / reserve bus bandwidth
STATUS usbHcdPipeCreate ( pHCD_NEXUS pNexus, /* client's nexus */ UINT16 busNo, /* bus number for IRP */ UINT16 busAddress, /* bus address of USB device */ UINT16 endpoint, /* endpoint on device */ UINT16 transferType, /* transfer type */ UINT16 direction, /* pipe/transfer direction */ UINT16 speed, /* transfer speed */ UINT16 maxPacketSize, /* packet size */ UINT32 bandwidth, /* bandwidth required by pipe */ UINT16 interval, /* service interval */ pUINT32 pTime, /* calculated packet time on return */ pHCD_PIPE_HANDLE pPipeHandle /* HCD pipe handle */ )
The USBD calls this function to notify the HCD that it is attempting to create a new pipe. The USBD passes the type of pipe in transferType.
If the pipe is an interrupt or isochronous pipe, the HCD 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.
If enough bus bandwidth is available, then that amount of bandwidth will be reserved by the HCD. Reserved bandwidth must later be released using usbHcdPipeDestroy( ).
transferType, direction, and speed should describe the characteristics of the pipe/transfer as USB_XFRTYPE_xxxx, USB_DIR_xxxx, and USB_SPEED_xxxx, repsectively. packetSize is the size of packets to be used.
For interrupt pipes, bandwidth is the total number of bytes which will be sent each frame. For isochronous pipes, bandwidth is the number of bytes per second. bandwidth should be 0 for control and bulk pipes.
The worst-case transfer time is returned in pTime.
The HCD will return an HCD_PIPE_HANDLE in pPipeHandle. The USBD will use this HCD_PIPE_HANDLE to identify the pipe in the future.
OK, or ERROR if unable to reserve bandwdith.
usbHcdPipeDestroy( ) - destroys pipe and releases previously allocated bandwidth
STATUS usbHcdPipeDestroy ( pHCD_NEXUS pNexus, /* client's nexus */ HCD_PIPE_HANDLE pipeHandle /* pipe to be destroyed */ )
Destroys the pipe identified by pipeHandle and releases any bandwidth used by the pipe.
OK, or ERROR if HCD fails to destroy pipe.
usbHcdPipeModify( ) - modify characteristics of an existing pipe
STATUS usbHcdPipeModify ( pHCD_NEXUS pNexus, /* client's nexus */ HCD_PIPE_HANDLE pipeHandle, /* pipe to be modified */ UINT16 busAddress, /* new bus address or 0 */ UINT16 maxPacketSize /* new max packet size or 0 */ )
Two characteristics of a pipe, the device's USB bus address and the maximum packet size, may change after a pipe is first created. Typically, this will happen only with the default control pipe for a given device, which must be created before issuing SET_ADDRESS to the device and before reading the device descriptor to determine the maximum packet size supported by the default control endpoint. The USBD will typically use this function to update either the busAddress or the maxPacketSize for the indicated pipeHandle. If either busAddress or maxPacketSize is 0, then the corresponding pipe attribute remains unchanged.
OK, or ERROR if HCD fails to modify pipe
usbHcdSofIntervalGet( ) - retrieves SOF interval for a bus
STATUS usbHcdSofIntervalGet ( pHCD_NEXUS pNexus, /* client's nexus */ UINT16 busNo, /* bus number */ pUINT16 pSofInterval /* bfr to receive SOF interval */ )
Returns the SOF interval for busNo in pSofInterval. The SOF interval is expressed in terms of high-speed bit times, and is typically close to 12,000.
OK, or ERROR if HCD failed to retrieve SOF interval
usbHcdSofIntervalSet( ) - sets SOF interval for a bus
STATUS usbHcdSofIntervalSet ( pHCD_NEXUS pNexus, /* client's nexus */ UINT16 busNo, /* bus number */ UINT16 sofInterval /* new SOF interval */ )
Sets the SOF interval for busNo to sofInterval. sofInterval must express the new SOF interval in terms of high-speed bit times, and should be in the neighborhood of 12,000. Certain HCD implementations may impose narrower or wider limits on the allowable sofInterval.
OK, or ERROR if HCD failed to set SOF interval.