usbdlib.c

VxWorks下USB驱动的源代码！

    /* Initialize URB */

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


    /* Execute URB */

    return urbExecBlock (&urb.header);
}


/***************************************************************************
*
* usbdMngmtCallbackSet - sets management callback for a client
*
* Management callbacks provide a mechanism for the USBD to inform clients
* of asynchronous management events on the USB.  For example, if the USB
* is in the SUSPEND state - see usbdBusStateSet() - and a USB device
* drives RESUME signalling, that event can be reported to a client through
* its management callback.
*
* <clientHandle> is a client's registered handled with the USBD.  
* <mngmtCallback> is the management callback routine of type
* USBD_MNGMT_CALLBACK which will be invoked by the USBD when management
* events are detected.	<mngmtCallbackParam> is a client-defined parameter
* which will be passed to the <mngmtCallback> each time it is invoked.
* Passing a <mngmtCallback> of NULL cancels management event callbacks.
*
* When the <mngmtCallback> is invoked, the USBD will also pass it the
* USBD_NODE_ID of the root node on the bus for which the management event
* has been detected and a code signifying the type of management event
* as USBD_MNGMT_xxxx.
*
* Clients are not required to register a management callback routine.
* Clients that do use a management callback are permitted to register at
* most one management callback per USBD_CLIENT_HANDLE.	
*
* RETURNS: OK, or ERROR if unable to register management callback
*/

STATUS usbdMngmtCallbackSet (USBD_CLIENT_HANDLE clientHandle,   /* Client handle */
                             USBD_MNGMT_CALLBACK mngmtCallback, /* management callback */
                             pVOID mngmtCallbackParam   /* client-defined parameter */
    )
{
    URB_MNGMT_CALLBACK_SET urb;


    /* Initialize URB */

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

    urb.mngmtCallback = mngmtCallback;
    urb.mngmtCallbackParam = mngmtCallbackParam;


    /* Execute URB */

    return urbExecBlock (&urb.header);
}


/***************************************************************************
*
* usbdBusStateSet - Sets bus state (e.g., suspend/resume)
*
* This function allows a client to set the state of the bus to which
* the specified <nodeId> is attached.  The desired <busState> is specified
* as USBD_BUS_xxxx.
*
* Typically, a client will use this function to set a bus to the SUSPEND
* or RESUME state.  Clients must use this capability with care, as it will
* affect all devices on a given bus - and hence all clients communicating
* with those devices.
*
* When setting a bus to the SUSPEND state, a client must also be aware
* that the USBD will not automatically return the bus to the RESUME state...
* the client must RESUME the bus explicitly through this function.  This
* point is most important when considering the USB "remote wakeup" feature.
* This feature allows a remote device to drive RESUME signalling on the
* bus.	However, it is the client's responsibility to recognize this
* condition by monitoring management events through the use of management
* callbacks - see usbdMngmtCallbackSet().  When a USBD_MNGMT_RESUME event
* is detected, the client chooses to RESUME the bus (or not).
*
* RETURNS: OK, or ERROR if unable to set specified bus state
*/

STATUS usbdBusStateSet (USBD_CLIENT_HANDLE clientHandle,    /* Client handle */
                        USBD_NODE_ID nodeId,    /* node ID */
                        UINT16 busState /* new bus state: USBD_BUS_xxxx */
    )
{
    URB_BUS_STATE_SET urb;


    /* Initialize URB */

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

    urb.nodeId = nodeId;
    urb.busState = busState;


    /* Execute URB */

    return urbExecBlock (&urb.header);
}


/***************************************************************************
*
* usbdBusCountGet - Get number of USBs attached to the host.
*
* This function returns the total number of USB host controllers in the 
* system.  Each host controller has its own root hub as required by the USB 
* specification; and clients planning to enumerate USB devices using the Bus 
* Enumeration Functions need to know the total number of host controllers in 
* order to retrieve the Node Ids for each root hub.
*
* <pBusCount> must point to a UINT16 variable in which the total number of 
* USB host controllers will be stored.
*
* Note: The number of USB host controllers is not constant.  Bus controllers 
* can be added by calling usbdHcdAttach() and removed by calling 
* usbdHcdDetach().  Again, the Dynamic Attach Functions deal with these 
* situations automatically, and are the preferred mechanism by which most 
* clients should be informed of device attachment and removal.
*
* RETURNS: OK, or ERROR if unable to retrieve bus count
*/

STATUS usbdBusCountGet (USBD_CLIENT_HANDLE clientHandle,    /* Client handle */
                        pUINT16 pBusCount   /* Word bfr to receive bus count */
    )
{
    URB_BUS_COUNT_GET urb;
    STATUS s;


    /* Initalize URB */

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


    /* Execute URB */

    s = urbExecBlock (&urb.header);


    /* Return result */

    if (pBusCount != NULL)
        *pBusCount = urb.busCount;

    return s;
}


/***************************************************************************
*
* usbdRootNodeIdGet - Returns root node for a specific USB
*
* This function returns the Node Id for the root hub for the specified 
* USB host controller.	<busIndex> is the index of the desired USB host 
* controller.  The first host controller is index 0 and the last host 
* controller's index is the total number of USB host controllers - as 
* returned by usbdBusCountGet() - minus 1. < pRootId> must point to a 
* USBD_NODE_ID variable in which the Node Id of the root hub will be stored.
* 
* RETURNS: OK, or ERROR if unable to get root node ID.
*/

STATUS usbdRootNodeIdGet (USBD_CLIENT_HANDLE clientHandle,  /* Client handle */
                          UINT16 busIndex,  /* Bus index */
                          pUSBD_NODE_ID pRootId /* bfr to receive Root Id */
    )
{
    URB_ROOT_ID_GET urb;
    STATUS s;


    /* Initalize URB */

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

    urb.busIndex = busIndex;


    /* Execute URB */

    s = urbExecBlock (&urb.header);


    /* Return result */

    if (pRootId != NULL)
        *pRootId = urb.rootId;

    return s;
}


/***************************************************************************
*
* usbdHubPortCountGet - Returns number of ports connected to a hub
*
* usbdHubPortCountGet() provides clients with a convenient mechanism to 
* retrieve the number of downstream ports provided by the specified hub. 
* Clients can also retrieve this information by retrieving configuration 
* descriptors from the hub using the Configuration Functions describe in 
* a following section.	
*
* <hubId> must be the Node Id for the desired USB hub.	An error will be 
* returned if <hubId> does not refer to a hub.	<pPortCount> must point to 
* a UINT16 variable in which the total number of ports on the specified 
* hub will be stored.
*
* RETURNS: OK, or ERROR if unable to get hub port count.
*/

STATUS usbdHubPortCountGet (USBD_CLIENT_HANDLE clientHandle,    /* Client handle */
                            USBD_NODE_ID hubId, /* Node Id for desired hub */
                            pUINT16 pPortCount  /* bfr to receive port count */
    )
{
    URB_HUB_PORT_COUNT_GET urb;
    STATUS s;


    /* Initalize URB */

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

    urb.hubId = hubId;


    /* Execute URB */

    s = urbExecBlock (&urb.header);


    /* Return result */

    if (pPortCount != NULL)
        *pPortCount = urb.portCount;

    return s;
}


/***************************************************************************
*
* usbdNodeIdGet - Gets the id of the node connected to a hub port
*
* Clients use this function to retrieve the Node Id for devices attached to
* each of a hub抯 ports.  <hubId> and <portIndex> identify the hub and port 
* to which a device may be attached.  <pNodeType> must point to a UINT16 
* variable to receive a type code as follows:
*
* .IP "USB_NODETYPE_NONE"
* No device is attached to the specified port.
* .IP "USB_NODETYPE_HUB"
* A hub is attached to the specified port.
* .IP "USB_NODETYPE_DEVICE"
* A device (non-hub) is attached to the specified port.
*
* If the node type is returned as USBD_NODE_TYPE_NONE, then a Node Id is 
* not returned and the value returned in <pNodeId> is undefined.  If the 
* node type indicates a hub or device is attached to the port, then 
* <pNodeId> will contain that hub or device抯 nodeId upon return.
*
* RETURNS: OK, or ERROR if unable to get node ID.
*/

STATUS usbdNodeIdGet (USBD_CLIENT_HANDLE clientHandle,  /* Client handle */
                      USBD_NODE_ID hubId,   /* Node Id for desired hub */
                      UINT16 portIndex, /* Port index */
                      pUINT16 pNodeType,    /* bfr to receive node type */
                      pUSBD_NODE_ID pNodeId /* bfr to receive Node Id */
    )
{
    URB_NODE_ID_GET urb;
    STATUS s;


    /* Initalize URB */

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

    urb.hubId = hubId;
    urb.portIndex = portIndex;


    /* Execute URB */

    s = urbExecBlock (&urb.header);


    /* Return result */

    if (pNodeType != NULL)
        *pNodeType = urb.nodeType;

    if (pNodeId != NULL)
        *pNodeId = urb.nodeId;

    return s;
}


/***************************************************************************
*
* usbdNodeInfoGet - Returns information about a USB node
*
* This function retrieves information about the USB device specified by 
* <nodeId>.  The USBD copies node information into the <pNodeInfo> structure 
* provided by the caller.  This structure is of the form USBD_NODEINFO as
* shown below:
*
* .CS
* typedef struct usbd_nodeinfo
*     {
*     UINT16 nodeType;
*     UINT16 nodeSpeed;
*     USBD_NODE_ID parentHubId;
*     UINT16 parentHubPort;
*     USBD_NODE_ID rootId;
*     } USBD_NODEINFO, *pUSBD_NODEINFO;
* .CE
*
* <nodeType> specifies the type of node identified by <nodeId> and is defined 
* as USB_NODETYPE_xxxx.  <nodeSpeed> identifies the speed of the device and 
* is defined as USB_SPEED_xxxx.  <parentHubId> and <parentHubPort> identify 
* the Node Id and port of the hub to which the indicated node is attached 
* upstream.  If the indicated <nodeId> happens to be a root hub, then 
* <parentHubId> and <parentHubPort> will both be 0.  
*
* Similarly, <rootId> identifies the Node Id of the root hub for the USB to 
* which nodeId is attached.  If <nodeId> itself happens to be the root hub, 
* then the same value will be returned in <rootId>.
*
* It is anticipated that this structure may grow over time.  To provide 
* backwards compatibility, the client must pass the total size of the 
* USBD_NODEINFO structure it has allocated in <infoLen>.  The USBD will copy 
* fields into this structure only up to the <infoLen> indicated by the caller.
*
* RETURNS: OK, or ERROR if unable to retrieve node information.
*/

STATUS usbdNodeInfoGet (USBD_CLIENT_HANDLE clientHandle,    /* Client handle */
                        USBD_NODE_ID nodeId,    /* Node Id of device/hub */
                        pUSBD_NODE_INFO pNodeInfo,  /* Structure to receive node info */
                        UINT16 infoLen  /* Len of bfr allocated by client */
    )
{
    URB_NODE_INFO_GET urb;


    /* Initalize URB */

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

    urb.nodeId = nodeId;
    urb.pNodeInfo = pNodeInfo;
    urb.infoLen = infoLen;


    /* Execute URB */

    return urbExecBlock (&urb.header);
}


/***************************************************************************
*
* usbdDynamicAttachRegister - Registers client for dynamic attach notification
*
* Clients call this function to indicate to the USBD that they wish to be 
* notified whenever a device of the indicated class/sub-class/protocol is attached 
* or removed from the USB.  A client may specify that it wants to receive 
* notification for an entire device class or only for specific sub-classes
* within that class.
*
* <deviceClass>, <deviceSubClass>, and <deviceProtocol> must specify a USB 
* class/sub-class/protocol combination according to the USB specification.  For 
* the client抯 convenience, usbdLib.h automatically includes usb.h which defines a 
* number of USB device classes as USB_CLASS_xxxx and USB_SUBCLASS_xxxx.  A 
* value of USBD_NOTIFY_ALL in any/all of these parameters acts like a wildcard