usbdlib.c

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

    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
* and matches any value reported by the device for the corresponding field. 
*
* <attachCallback> must be a non-NULL pointer to a client-supplied callback 
* routine of the form USBD_ATTACH_CALLBACK:
*
* .CS
* typedef VOID (*USBD_ATTACH_CALLBACK) 
*     (
*     USBD_NODE_ID nodeId, 
*     UINT16 attachAction, 
*     UINT16 configuration,
*     UINT16 interface,
*     UINT16 deviceClass, 
*     UINT16 deviceSubClass, 
*     UINT16 deviceProtocol
*     );
* .CE
*
* Immediately upon registration the client should expect that it may begin 
* receiving calls to the <attachCallback> routine.  Upon registration, USBD 
* will call the <attachCallback> for each device of the specified class which 
* is already attached to the system.  Thereafter, the USBD will call the 
* <attachCallback> whenever a new device of the specified class is attached to 
* the system or an already-attached device is removed.
*
* Each time the <attachCallback> is called, USBD will pass the Node Id of the 
* device in <nodeId> and an attach code in <attachAction> which explains the