VxWorks API Reference : USB libraries
usbTargLib [USB] - USB Target Library
usbTargVersionGet( ) - Retrieve usbTargLib version
usbTargInitialize( ) - Initializes usbTargLib
usbTargShutdown( ) - Shuts down usbTargLib
usbTargTcdAttach( ) - Attaches and initializes a USB target controller driver
usbTargTcdDetach( ) - Detaches a USB target controller driver
usbTargEndpointInfoGet( ) - Retrieves endpoint information for channel
usbTargEnable( ) - Enables target channel onto USB
usbTargDisable( ) - Disables a target channel
usbTargPipeCreate( ) - Creates a pipe for communication on an endpoint
usbTargPipeDestroy( ) - Destroys an endpoint pipe
usbTargTransfer( ) - Submits a USB_ERP for transfer through a pipe
usbTargTransferAbort( ) - Cancels a previously submitted USB_ERP
usbTargControlResponseSend( ) - Sends a response on the control pipe
usbTargControlPayloadRcv( ) - Receives data on the default control pipe
usbTargPipeStatusSet( ) - sets pipe stalled/unstalled status
usbTargCurrentFrameGet( ) - Retrieves the current USB frame number
usbTargSignalResume( ) - Drives RESUME signalling on USB
This module implements the hardware-independent USB target API.
usbTargLib can manage one or more USB TCDs (Target Controller Drivers). usbTargLib provides hardware-independent target services and management while the USB TCDs provide the hardware-dependent USB interface.
usbTargLib must be initialized by calling usbTargInitialize( ). Before operation can begin, at least one TCD must be attached to usbTargLib by calling usbTargTcdAttach( ). In response to a successful TCD attachment, usbTargLib returns a USB_TARG_CHANNEL handle to the caller. This handle must be used in all subsequent calls to usbTargLib to identify a given target channel.
USB devices (targets) almost never initiate activity on the USB (the exception being RESUME signalling). So, as part of the call to usbTargTcdAttach( ), the caller must provide a pointer to a USB_TARG_CALLBACK_TABLE structure. This table contains a collection of callback function pointers initialized by the caller prior to invoking the usbTargTcdAttach( ) function. Through these callbacks, usbTargLib notifies the calling application of various USB events and requests from the host. The calling application is not required to provide callback functions for all possible events. The callback pointers for which the calling application has no interest should be NULL.
usbTargLib automatically establishes the default control pipe for each attached target channel and monitors all control pipe requests. If the calling application provides a non-NULL callback for the corresponding request, usbTargLib invokes the function. If the callback function chooses to handle the control pipe request itself, then it returns OK, and usbTargLib generally performs no further automatic processing. If the callback instead returns FALSE, then usbTargLib handles the control pipe request automatically using a default behavior.
Generally, requests through the control pipe will result in the need for the target to establish one or more additional pipes to the host. Each pipe is assigned to a particular endpoint on the device. The calling application then submits USB_ERPs (endpoint request packets) which cause data transfers to be performed on specific pipes.
usbTargVersionGet( ) - Retrieve usbTargLib version
STATUS usbTargVersionGet ( pUINT16 pVersion, /* usbTargLib version */ pCHAR pMfg /* usbTargLib manufacturer */ )
This function returns the usbTargLib version. If pVersion is not NULL, the usbTargLib returns its version in BCD in pVersion. For example, version "1.02" would be coded as 01h in the high byte and 02h in the low byte.
If pMfg is not NULL it must point to a buffer of at least USBT_NAME_LEN bytes in length in which the USBD will store the NULL terminated name of the usbTargLib manufacturer (e.g., "Wind River Systems" + \0).
OK
usbTargInitialize( ) - Initializes usbTargLib
STATUS usbTargInitialize (void)
usbTargInitialize( ) must be called at least once prior to calling other usbTargLib functions except for usbTargVersionGet( ). usbTargLib maintains an internal initialization count, so calls to usbTargInitialize( ) may be nested.
OK, or ERROR if unable to initialize usbTargLib.
S_usbTargLib_OUT_OF_RESOURCES
S_usbTargLib_GENERAL_FAULT;
usbTargShutdown( ) - Shuts down usbTargLib
STATUS usbTargShutdown (void)
usbTargShutdown( ) should be called once for every successful call to usbTargInitialize( ). usbTargShutdown( ) closes any open target channels and releases resources allocated by the usbTargLib.
OK, or ERROR if unable to shut down usbTargLib.
S_usbTargLib_NOT_INITIALIZED
usbTargTcdAttach( ) - Attaches and initializes a USB target controller driver
STATUS usbTargTcdAttach ( USB_TCD_EXEC_FUNC tcdExecFunc, /* TCD entry point */ pVOID tcdParam, /* TCD parameter */ pUSB_TARG_CALLBACK_TABLE pCallbacks, /* caller-supplied callbacks */ pVOID callbackParam, /* caller-defined callback param */ pUSB_TARG_CHANNEL pTargChannel, /* handle to target on return */ pUINT16 pNumEndpoints, /* bfr to receive nbr of */ /* endpoints */ pUSB_TARG_ENDPOINT_INFO * ppEndpoints /* bfr to rcv ptr to endpt array */ )
This function attaches a USB TCD (Target Controller Driver) to usbTargLib. A TCD needs to be attached to usbTargLib before any other USB operations may be performed on the target channel it manages.
tcdExecFunc is the primary entry point of the TCD being attached and tcdParam is a TCD-defined parameter which is passed to the TCD's attach function. Generally, the tcdParam is points to a TCD-defined structure which identifies the characteristics of the target controller hardware (i.e., base I/O address, IRQ channel, etc.). Each call to usbTargTcdAttach( ) enables one and only one target channel.
pCallbacks points to a USB_TARG_CALLBACK_TABLE structure in which the caller has stored the addresses of callbacks for events in which it is interested in being notified. callbackParam is a caller-defined parameter which is passed to each callback function when the callbacks are invoked by usbTargLib.
pTargChannel points to a USB_TARG_CHANNEL variable allocated by the caller which receives a handle to the target channel created by this call to usbTargTcdAttach( ).
pNumEndpoints and ppEndpoints receive the count of target endpoints and a pointer to an array of USB_TARG_ENDPOINT_INFO structures, respectively. The caller can use this information to assign endpoints to pipes.
OK, or ERROR if unable to attach/initialize TCD.
S_usbTargLib_BAD_PARAM
S_usbTargLib_OUT_OF_MEMORY
S_usbTargLib_OUT_OF_RESOURCES
S_usbTargLib_TCD_FAULT
S_usbTargLib_APP_FAULT
usbTargTcdDetach( ) - Detaches a USB target controller driver
STATUS usbTargTcdDetach ( USB_TARG_CHANNEL targChannel /* target to detach */ )
This function detaches a USB TCD which was previously attached to the usbTargLib by calling usbTargTcdAttach( ). targChannel is the handle of the target channel originally returned by usbTargTcdAttach( ).
The usbTargLib automatically terminates any pending transactions on the target channel being detached and releases all internal usbTargLib resources allocated on behalf of the channel. Once a target channel has been detached by calling this function, the targChannel is no longer valid.
OK, or ERROR if unable to detach TCD.
usbTargEndpointInfoGet( ) - Retrieves endpoint information for channel
STATUS usbTargEndpointInfoGet ( USB_TARG_CHANNEL targChannel, /* target channel */ pUINT16 pNumEndpoints, /* receives nbr of endpoints */ pUSB_TARG_ENDPOINT_INFO * ppEndpoints /* receives ptr to array */ )
This function retrieves the number of endpoints on targChannel and returns a pointer to the base of the USB_TARG_ENDPOINT_INFO array.
OK, or ERROR if unable to return target endpoint information
usbTargEnable( ) - Enables target channel onto USB
STATUS usbTargEnable ( USB_TARG_CHANNEL targChannel /* target to enable */ )
After attaching a TCD to usbTargLib and performing any other application- specific initialization that might be necessary, this function should be called to enable a target channel. The USB target controlled by the TCD will not appear as a device on the USB until this function has been called.
OK, or ERROR if unable to enable target channel.
S_usbTargLib_TCD_FAULT
usbTargDisable( ) - Disables a target channel
STATUS usbTargDisable ( USB_TARG_CHANNEL targChannel /* target to disable */ )
This function is the counterpart to the usbTargEnable( ) function. This function disables the indicated target channel.
OK, or ERROR if unable to disable the target channel.
S_usbTargLib_TCD_FAULT
usbTargPipeCreate( ) - Creates a pipe for communication on an endpoint
STATUS usbTargPipeCreate ( USB_TARG_CHANNEL targChannel, /* target channel */ UINT16 endpointId, /* endpoint ID to use for pipe */ UINT16 endpointId2, /* needed for control pipes only */ UINT16 endpointNum, /* endpoint number to assign */ UINT16 configuration, /* associated configuration */ UINT16 interface, /* associated interface */ UINT16 transferType, /* USB_XFRTYPE_xxxx */ UINT16 direction, /* USB_DIR_xxxx */ pUSB_TARG_PIPE pPipeHandle /* returned pipe handle */ )
This function creates a pipe attached to a specific target endpoint. endpointId is the TCD-assigned ID of the target endpoint to be used for this pipe and endpointNum is the device endpoint number to which the endpoint will respond. Some TCDs allow the flexible assignment of endpoints to specific endpoint numbers while others do not. The endpointNumMask field in the USB_TARG_ENDPOINT_INFO structure is a bit mask that reveals which endpoint numbers are supported by a given endpoint. (e.g., If bit 0 is 1, then the corresponding endpoint can be assigned to endpoint #0, and so forth).
By convention, each of the endpoints exposed by the TCD is unidirectional. Control pipes are bidirectional, and therefore logically occupy two endpoints, one IN endpoint and one OUT endpoint, both with the same endpointNum. When creating a control pipe, the caller must specify the second endpoint Id in endpointId2. In this case, endpointId must specify the OUT endpoint, and endpointId2 must specify the IN endpoint. endpointId2 should be 0 for other types of pipes.
configuration and interface specify the device configuration and interface with which the endpoint (and pipe) is associated. The usbTargLib uses these values to reset pipes as appropriate when USB "configuration events" are detected. (In response to a USB configuration event, the data toggle for a given endpoint is always reset to DATA0.)
transferType specifies the type of transfers to be performed as USB_XFRTYPE_xxxx. direction specifies the direction of the pipe as USB_DIR_xxxx. Control pipes specify direction as USB_DIR_INOUT.
The caller must be aware that not all endpoints are capable of all types of transfers. Prior to assigning an endpoint for a particular purpose, the caller should interrogate the USB_TARG_ENDPOINT_INFO structure for the endpoint to ensure that it supports the indicated type of transfer.
OK, or ERROR if unable to create pipe
S_usbTargLib_BAD_PARAM
S_usbTargLib_ENDPOINT_IN_USE
S_usbTargLib_OUT_OF_MEMORY
S_usbTargLib_OUT_OF_RESOURCES
S_usbTargLib_TCD_FAULT
usbTargPipeDestroy( ) - Destroys an endpoint pipe
STATUS usbTargPipeDestroy ( USB_TARG_PIPE pipeHandle /* pipe to be destroyed */ )
This function tears down a pipe previously created by calling usbTargPipeCreate( ). Any pending transfers on the pipe are canceled and all resources allocated to the pipe are released.
OK, or ERROR if unable to destroy pipe.
usbTargTransfer( ) - Submits a USB_ERP for transfer through a pipe
STATUS usbTargTransfer ( USB_TARG_PIPE pipeHandle, /* pipe for transfer */ pUSB_ERP pErp /* ERP describing transfer */ )
A client uses this function to initiate an transfer on the pipe indicated by pipeHandle. The transfer is described by an ERP, or endpoint request packet, which must be allocated and initialized by the caller prior to invoking usbdTargTransfer( ).
The USB_ERP structure is defined in usb.h as:
typedef struct usb_bfr_list { UINT16 pid; pUINT8 pBfr; UINT32 bfrLen; UINT32 actLen; } USB_BFR_LIST; typedef struct usb_erp { LINK targLink; // used by usbTargLib pVOID targPtr; // used by usbTargLib LINK tcdLink; // used by TCD pVOID tcdPtr; // used by TCD pVOID userPtr; UINT16 erpLen; int result; // returned by usbTargLib/TCD ERP_CALLBACK targCallback; // used by usbTargLib ERP_CALLBACK userCallback; UINT16 endpointId; // filled in by usbTargLib UINT16 transferType; // filled in by usbTargLib UINT16 dataToggle; // filled in by usbTargLib UINT16 bfrCount; USB_BFR_LIST bfrList [1]; } USB_ERP, *pUSB_ERP;The length of the USB_ERP structure must be stored in erpLen and varies depending on the number of bfrList elements allocated at the end of the structure. By default, the default structure contains a single bfrList element, but clients may allocate a longer structure to accommodate a larger number of bfrList elements.endpointId and transferType are filled in automatically by the usbTargLib using values recorded when the pipe was created.
dataToggle is filled in automatically except for control pipes. For these pipes, the caller is required to store the next data toggle as USB_DATA0 or USB_DATA1. The Setup packet is always a DATA0. The first packet of the data phase is always DATA1, with data packets alternating thereafter, and the Status phase packet is always DATA1. When using the functions usbTargLibResponseSend( ) and usbTargLibPayloadRcv( ), usbTargLib handles the dataToggle value automatically.
bfrList is an array of buffer descriptors which describe data buffers to be associated with this ERP. If more than the one bfrList element is required then the caller must allocate the ERP by calculating the size as
erpLen = sizeof (USB_ERP) + (sizeof (USB_BFR_DESCR) * (bfrCount - 1))pid specifies the packet type to use for the indicated buffer and is specified as USB_PID_xxxx. Note that packet types are specified from the perspective of the host. For example, USB_PID_IN indicates a transfer from the device (target) to the host.The ERP userCallback routine must point to a client-supplied ERP_CALLBACK routine. The usbdTargTransfer( ) function returns as soon as the ERP has been successfully enqueued. If there is a failure in delivering the ERP to the TCD, then usbdTargTransfer( ) returns an error. The actual result of the ERP should be checked after the userCallback routine has been invoked.
OK, or ERROR if unable to submit USB_ERP for execution
S_usbTargLib_BAD_PARAM
S_usbTargLib_TCD_FAULT
usbTargTransferAbort( ) - Cancels a previously submitted USB_ERP
STATUS usbTargTransferAbort ( USB_TARG_PIPE pipeHandle, /* pipe for transfer to abort */ pUSB_ERP pErp /* ERP to be aborted */ )
This function aborts an ERP which was previously submitted through a call to usbdTargTransfer( ).
OK, or ERROR if unable to cancel USB_ERP
S_usbTargLib_BAD_PARAM
usbTargControlResponseSend( ) - Sends a response on the control pipe
STATUS usbTargControlResponseSend ( USB_TARG_CHANNEL targChannel, /* target channel */ UINT16 bfrLen, /* length of response, or 0 */ pUINT8 pBfr /* ptr to bfr or NULL */ )
usbTargLib automatically creates a pipe to manage communication on the default control endpoint (#0) defined by the USB. Certain application callbacks (e.g., the USB_TARG_VENDOR_SPECIFIC callback) may need to formulate a response and send it to the host. This function allows a caller to respond to a host control pipe request.
There are two kinds of responses, those that involve a data phase and those that do not. This function may be used to handle both types. If a data phase is required, the caller passes a non-NULL pBfr for the usbTargTransfer( ) function. The usbTargControlResponseSend( ) function sends the data described by the USB_ERP and then automatically accepts the "status phase" transfer sent the by the host to acknowledge the transfer. If there is no data phase, the pBfr parameter should be NULL, in which case usbTargLib generates just the Status phase automatically.
The contents of the pBfr passed by the caller are copied into a private usbTargLib buffer. bfrLen must not exceed USB_MAX_DESCR_LEN.
This function returns as soon as the transfer is enqueued.
OK, or ERROR if unable to submit response to host.
S_usbTargLib_GENERAL_FAULT
S_usbTargLib_BAD_PARAM
usbTargControlPayloadRcv( ) - Receives data on the default control pipe
STATUS usbTargControlPayloadRcv ( USB_TARG_CHANNEL targChannel, pUSB_ERP pErp )
usbTargLib automatically creates a pipe to manage communication on the default control pipe (#0) defined by the USB. Certain application callbacks (e.g., USB_TARG_VENDOR_SPECIFIC or USB_TARG_DESCRIPTOR_SET) may need to receive additional data on the control OUT endpoint in order to complete processing of the control pipe request. This function allows a caller to receive data on a control pipe.
The pErp parameter must point to an ERP which will receive the additional data.
This function returns as soon as the USB_ERP is enqueued. Completion of the USB_ERP is indicated when the ERP's callback is invoked. After the ERP completes, the application should terminate the USB request by invoking the usbTargControlResponseSend( ) function with a NULL pBfr parameter. This will direct usbTargLib to generate a Status IN phase, signalling the end of the transaction.
The caller must ensure that the ERP remains valid until the ERP userCallback has been invoked - signalling completion of the ERP.
OK, or ERROR if unable to submit ERP to receive additional data
usbTargPipeStatusSet( ) - sets pipe stalled/unstalled status
STATUS usbTargPipeStatusSet ( USB_TARG_CHANNEL targChannel, USB_TARG_PIPE pipeHandle, UINT16 state )
If the target application detects an error while servicing a pipe, including the default control pipe, it may choose to stall the endpoint(s) associated with that pipe. This function allows the caller to set the state of a pipe as "stalled" or "un-stalled".
pipeHandle should be the handle of a pipe to be stalled. A NULL pipeHandle indicates the default control pipe. state indicates the endpoint state as TCD_ENDPOINT_STALL/UNSTALL/DATA0.
Note that the default control pipe will automatically "un-stall" upon receipt of a new Setup packet.
OK, or ERROR if unable to set indicated state
S_usbTargLib_TCD_FAULT
usbTargCurrentFrameGet( ) - Retrieves the current USB frame number
STATUS usbTargCurrentFrameGet ( USB_TARG_CHANNEL targChannel, /* target channel */ pUINT16 pFrameNo /* current frame number */ )
It is sometimes necessary for callers to retrieve the current USB frame number. This function allows a caller to retrieve the current USB frame number for the bus to which targChannel is connected. Upon return, the current frame number is stored in pFrameNo.
OK, or ERROR if unable to retrieve USB frame number
S_usbTargLib_TCD_FAULT
usbTargSignalResume( ) - Drives RESUME signalling on USB
STATUS usbTargSignalResume ( USB_TARG_CHANNEL targChannel /* target channel */ )
If a USB is in the SUSPENDed state, it is possible for a device (target) to request the bus to wake up (called remote wakeup). This function allows the caller to drive USB resume signalling. The function will return after resume signalling has completed.
There is no guarantee that a host will honor RESUME signalling. Therefore, the caller should make no assumptions about the state of the USB after calling this function. Instead, the "management callback" for this target channel will be invoked if the USB changes state in response to the RESUME signalling.
OK, or ERROR if unable to drive RESUME signalling
S_usbTargLib_TCD_FAULT