usbdlib.c

This the USB source code for vxworks5.5. It has OSS library source code and also the complete targ

    /* Return result */

    if (pPipeHandle != NULL)
	*pPipeHandle = urb.pipeHandle;

    return s;
    }


/***************************************************************************
*
* usbdPipeDestroy - Destroys a USB data transfer pipe
*
* This function destroys a pipe previous created by calling usbdPipeCreate().  
* The caller must pass the <pipeHandle> originally returned by usbdPipeCreate().
*
* If there are any outstanding transfer requests for the pipe, the USBD will 
* abort those transfers prior to destroying the pipe.  
*
* RETURNS: OK, or ERROR if unable to destroy pipe.
*/

STATUS usbdPipeDestroy
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_PIPE_HANDLE pipeHandle 	/* pipe handle */
    )

    {
    URB_PIPE_DESTROY urb;


    /* Initalize URB */

    urbInit (&urb.header, clientHandle, USBD_FNC_PIPE_DESTROY, NULL, NULL,
	sizeof (urb));

    urb.pipeHandle = pipeHandle;


    /* Execute URB */

    return urbExecBlock (&urb.header);
    }


/***************************************************************************
*
* usbdTransfer - Initiates a transfer on a USB pipe
*
* A client uses this function to initiate an transfer on the pipe indicated 
* by <pipeHandle>.  The transfer is described by an IRP, or I/O request 
* packet, which must be allocated and initialized by the caller prior to 
* invoking usbdTransfer().
*
* The USB_IRP structure is defined in usb.h as:
*
* .CS
* typedef struct usb_bfr_list
*     {
*     UINT16 pid;
*     pUINT8 pBfr;
*     UINT16 bfrLen;
*     UINT16 actLen;
*     } USB_BFR_LIST;
*
* typedef struct usb_irp
*     {
*     LINK usbdLink;		    // used by USBD
*     pVOID usbdPtr;		    // used by USBD
*     LINK hcdLink;		    // used by HCD
*     pVOID hcdPtr;		    // used by HCD
*     pVOID userPtr;
*     UINT16 irpLen;
*     int result;		    // returned by USBD/HCD
*     IRP_CALLBACK usbdCallback;    // used by USBD
*     IRP_CALLBACK userCallback;
*     UINT16 dataToggle;	    // filled in by USBD
*     UINT16 flags; 
*     UINT32 timeout;		    // defaults to 5 seconds if zero
*     UINT16 startFrame;
*     UINT16 transferLen;
*     UINT16 dataBlockSize;
*     UINT16 bfrCount;
*     USB_BFR_LIST bfrList [1];
*     } USB_IRP, *pUSB_IRP;
* .CE
*
* The length of the USB_IRP structure must be stored in <irpLen> 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.  
*
* <flags> define additional transfer options.  The currently defined flags are:
*
* .IP "USB_FLAG_SHORT_OK"
* Treats receive (IN) data underrun as OK.
* .IP "USB_FLAG_SHORT_FAIL"
* Treats receive (IN) data underrun as error.
* .IP "USB_FLAG_ISO_ASAP"
* Start an isochronous transfer immediately.
*
* When the USB is transferring data from a device to the host the data may 
* "underrun".  That is, the device may transmit less data than anticipated by 
* the host.  This may or may not indicate an error condition depending on the 
* design of the device.  For many devices, the underrun is completely normal 
* and indicates the end of data stream from the device.  For other devices, 
* the underrun indicates a transfer failure.  By default, the USBD and 
* underlying USB HCD (Host Controller Driver) treat underrun as the end-of-data 
* indicator and do not declare an error.  If the USB_FLAG_SHORT_FAIL flag is 
* set, then the USBD/HCD will instead treat underrun as an error condition.
*
* For isochronous transfers the USB_FLAG_ISO_ASAP specifies that the 
* isochronous transfer should begin as soon as possible.  If USB_FLAG_ISO_ASAP
* is not specified, then <startFrame> must specify the starting frame number 
* for the transfer.  The usbdCurrentFrameGet() function allows a client to
* retrieve the current frame number and a value called the frame scheduling 
* window for the underlying USB host controller.  The frame window specifies 
* the maximum number of frames into the future (relative to the current frame 
* number) which may be specified by <startFrame>.  <startFrame> should be 
* specified only for isochronous transfers.
*
* <dataBlockSize> may also be specified for isochronous transfers.  If non-0,
* the <dataBlockSize> defines the granularity of isochronous data being sent.
* When the underlying Host Controller Driver (HCD) breaks up the transfer into
* individual frames, it will ensure that the amount of data transferred in 
* each frame is a multiple of this value.  
*
* <timeout> specifies the IRP timeout in milliseconds.	If the caller passes
* a value of zero, then the USBD sets a default timeout of USB_TIMEOUT_DEFAULT.
* If no timeout is desired, then <timeout> should be set to USB_TIMEOUT_NONE.
* Timeouts apply only to control and bulk transfers.  Isochronous and
* interrupt transfers do not time out.
*
* <bfrList> is an array of buffer descriptors which describe data buffers to 
* be associated with this IRP.	If more than the one <bfrList> element is 
* required then the caller must allocate the IRP by calculating the size as 
*
* .CS
* irpLen = sizeof (USB_IRP) + (sizeof (USB_BFR_DESCR) * (bfrCount - 1))
* .CE
*
* <transferLen> must be the total length of data to be transferred.  In other 
* words, transferLen is the sum of all <bfrLen> entries in the <bfrList>.
*
* <pid> specifies the packet type to use for the indicated buffer and is
* specified as USB_PID_xxxx.
*
* The IRP <userCallback> routine must point to a client-supplied IRP_CALLBACK
* routine.  The usbdTransfer() function returns as soon as the IRP has been
* successfully enqueued.  If there is a failure in delivering the IRP to the
* HCD, then usbdTransfer() returns an error.  The actual result of the IRP
* should be checked after the <userCallback> routine has been invoked.
*
* RETURNS: OK, or ERROR if unable to submit IRP for transfer.
*/

STATUS usbdTransfer
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_PIPE_HANDLE pipeHandle,	/* Pipe handle */
    pUSB_IRP pIrp			/* ptr to I/O request packet */
    )

    {
    URB_TRANSFER urb;


    /* Initalize URB */

    urbInit (&urb.header, clientHandle, USBD_FNC_TRANSFER, NULL, NULL,
	sizeof (urb));

    urb.pipeHandle = pipeHandle;
    urb.pIrp = pIrp;


    /* Execute URB */

    return urbExecBlock (&urb.header);
    }


/***************************************************************************
*
* usbdTransferAbort - Aborts a transfer
*
* This function aborts an IRP which was previously submitted through
* a call to usbdTransfer().  
*
* RETURNS: OK, or ERROR if unable to abort transfer.
*/

STATUS usbdTransferAbort
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_PIPE_HANDLE pipeHandle,	    /* Pipe handle */
    pUSB_IRP pIrp			/* ptr to I/O to abort */
    )

    {
    URB_TRANSFER urb;


    /* Initalize URB */

    urbInit (&urb.header, clientHandle, USBD_FNC_TRANSFER_ABORT, NULL, NULL,
	sizeof (urb));

    urb.pipeHandle = pipeHandle;
    urb.pIrp = pIrp;


    /* Execute URB */

    return urbExecBlock (&urb.header);
    }


/***************************************************************************
*
* usbdSynchFrameGet - Returns a device's isochronous synch. frame
*
* It is sometimes necessary for clients to re-synchronize with devices when 
* the two are exchanging data isochronously.  This function allows a client
* to query a reference frame number maintained by the device.  Please refer 
* to the USB Specification for more detail.
*
* <nodeId> specifies the node to query and <endpoint> specifies the endpoint 
* on that device.  Upon return the device抯 frame number for the specified 
* endpoint is returned in <pFrameNo>.
*
* RETURNS: OK, or ERROR if unable to retrieve synch. frame.
*/

STATUS usbdSynchFrameGet
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client Handle */
    USBD_NODE_ID nodeId,		/* Node Id of device/hub */
    UINT16 endpoint,			/* Endpoint to be queried */
    pUINT16 pFrameNo			/* Frame number returned by device */
    )

    {
    URB_SYNCH_FRAME_GET urb;
    STATUS s;


    /* Initalize URB */

    urbInit (&urb.header, clientHandle, USBD_FNC_SYNCH_FRAME_GET, NULL, NULL,
	sizeof (urb));

    urb.nodeId = nodeId;
    urb.endpoint = endpoint;


    /* Execute URB */

    s = urbExecBlock (&urb.header);


    /* Return result */

    if (pFrameNo != NULL)
	*pFrameNo = urb.frameNo;

    return s;
    }


/***************************************************************************
*
* usbdCurrentFrameGet - Returns the current frame number for a USB
*
* It is sometimes necessary for clients to retrieve the current USB frame 
* number for a specified host controller.  This function allows a client to 
* retrieve the current USB frame number for the host controller to which
* <nodeId> is connected.  Upon return, the current frame number is stored 
* in <pFrameNo>.
*
* If <pFrameWindow> is not NULL, the USBD will also return the maximum frame 
* scheduling window for the indicated USB host controller.  The frame 
* scheduling window is essentially the number of unique frame numbers 
* tracked by the USB host controller.  Most USB host controllers maintain an 
* internal frame count which is a 10- or 11-bit number, allowing them to 
* track typically 1024 or 2048 unique frames.  When starting an isochronous 
* transfer, a client may wish to specify that the transfer will begin in a 
* specific USB frame.  For the given USB host controller, the starting frame 
* number can be no more than <frameWindow> frames from the current <frameNo>.
*
* Note: The USBD is capable of simultaneously managing multiple USB host 
* controllers, each of which operates independently.  Therefore, it is 
* important that the client specify the correct <nodeId> when retrieving the 
* current frame number.  Typically, a client will be interested in the 
* current frame number for the host controller to which a specific device is 
* attached.
*
* RETURNS: OK, or ERROR if unable to retrieve current frame number.
*/

STATUS usbdCurrentFrameGet
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_NODE_ID nodeId,		/* Node Id of node on desired USB */
    pUINT32 pFrameNo,			/* bfr to receive current frame no. */
    pUINT32 pFrameWindow		/* bfr to receive frame window */
    )

    {
    URB_CURRENT_FRAME_GET urb;
    STATUS s;


    /* Initalize URB */

    urbInit (&urb.header, clientHandle, USBD_FNC_CURRENT_FRAME_GET, NULL, NULL,
	sizeof (urb));

    urb.nodeId = nodeId;


    /* Execute URB */

    s = urbExecBlock (&urb.header);


    /* Return result */

    if (pFrameNo != NULL)
	*pFrameNo = urb.frameNo;

    if (pFrameWindow != NULL)
	*pFrameWindow = urb.frameWindow;

    return s;
    }


/***************************************************************************
*
* usbdSofMasterTake - Takes SOF master ownership
*
* A client which is performing isochronous transfers may need to adjust
* the USB frame time by a small amount in order to synchronize correctly
* with one or more devices.  In order to adjust the USB frame interval,
* a client must first attempt to become the "SOF Master" for bus to which
* a device is attached.
*
* <nodeId> specifies the id of a node on the bus for which the client
* wishes to become the SOF master.  Each USB managed by the USBD may have
* a different SOF master.
*
* RETURNS: OK, or ERROR if client cannot become SOF master
*/

STATUS usbdSofMasterTake
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_NODE_ID nodeId 		/* Node Id of node on desired USB */
    )
    
    {
    URB_SOF_MASTER urb;

    /* Initalize URB */

    urbInit (&urb.header, clientHandle, USBD_FNC_SOF_MASTER_TAKE, NULL, NULL,
	sizeof (urb));

    urb.nodeId = nodeId;

    /* Execute URB */

    return urbExecBlock (&urb.header);
    }


/***************************************************************************
*
* usbdSofMasterRelease - Releases ownership of SOF master
*
* A client which has previously become the SOF master for a given USB
* may release SOF master status by calling this function.  <nodeId> should
* identify a node on the USB for which SOF master ownership should be 
* released.
*
* RETURNS: OK, or ERROR if SOF ownership cannot be released
*/

STATUS usbdSofMasterRelease
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_NODE_ID nodeId 		/* Node Id of node on desired USB */
    )
    
    {
    URB_SOF_MASTER urb;

    /* Initalize URB */

    urbInit (&urb.header, clientHandle, USBD_FNC_SOF_MASTER_RELEASE, NULL, NULL,
	sizeof (urb));

    urb.nodeId = nodeId;

    /* Execute URB */

    return urbExecBlock (&urb.header);
    }


/***************************************************************************
*
* usbdSofIntervalGet - Retrieves current SOF interval for a bus
*
* This function retrieves the current SOF interval for the bus to which
* <nodeId> is connected.  The SOF interval returned in <pSofInterval> is
* expressed in high speed bit times in a frame, with 12,000 being the 
* typical default value.
*
* NOTE: A client does not need to be the current SOF master in order to
* retrieve the SOF interval for a bus.
*
* RETURNS: OK, or ERROR if SOF interval cannot be retrieved.
*/

STATUS usbdSofIntervalGet
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_NODE_ID nodeId,		/* Node Id of node on desired USB */
    pUINT16