usbdlib.c

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

* reason for the callback.  Attach codes are defined as:
*
* .IP "USBD_DYNA_ATTACH"
* USBD is notifying the client that nodeId is a device which is now attached 
* to the system.
* .IP "USBD_DYNA_REMOVE"
* USBD is notifying the client that nodeId has been detached (removed) from 
* the system.
*
* When the <attachAction> is USBD_DYNA_REMOVE the <nodeId> refers to a Node Id 
* which is no longer valid.  The client should interrogate its internal data 
* structures and delete any references to the specified Node Id.  If the client 
* had outstanding requests to the specified <nodeId>, such as data transfer 
* requests, then the USBD will fail those outstanding requests prior to calling 
* the <attachCallback> to notify the client that the device has been removed.  
* In general, therefore, transfer requests related to removed devices should 
* already be taken care of before the <attachCallback> is called.
*
* A client may re-use a single <attachCallback> for multiple notification 
* registrations.  As a convenience to the <attachCallback> routine, the USBD 
* also passes the <deviceClass>, <deviceSubClass>, and <deviceProtocol> of the 
* attached/removed <nodeId> each time it calls the <attachCallback>.  
*
* Finally, clients need to be aware that not all USB devices report their class
* information at the "device" level.  Rather, some devices report class types
* on an interface-by-interface basis.  When the device reports class information
* at the device level, then the USBD passes a <configuration> value of zero to 
* the attach callback and calls the callback only a single time for each device.
* When the device reports class information at the interface level, then the
* USBD invokes the attach callback once for each interface which matches the
* client's <deviceClass>/<deviceSubClass>/<deviceProtocol> specification.  In this
* case, the USBD also passes the corresponding configuration & interface numbers
* in <configuration> and <interface> each time it invokes the callback.
*
* RETURNS: OK, or ERROR if unable to register for attach/removal notification.
*/

STATUS usbdDynamicAttachRegister
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    UINT16 deviceClass, 		/* USB class code */
    UINT16 deviceSubClass,		/* USB sub-class code */
    UINT16 deviceProtocol,		/* USB device protocol code */
    USBD_ATTACH_CALLBACK attachCallback /* User-supplied callback routine */
    )

    {
    URB_DYNA_ATTACH_REG_UNREG urb;


    /* Initalize URB */

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

    urb.deviceClass = deviceClass;
    urb.deviceSubClass = deviceSubClass;
    urb.deviceProtocol = deviceProtocol;
    urb.attachCallback = attachCallback;


    /* Execute URB */

    return urbExecBlock (&urb.header);
    }


/***************************************************************************
*
* usbdDynamicAttachUnRegister - Unregisters client for attach notification
*
* This function cancels a client抯 earlier request to be notified for the 
* attachment and removal of devices within the specified class.  <deviceClass>,
* <deviceSubClass>, <deviceProtocol>, and <attachCallback> are defined as for the 
* usbdDynamicAttachRegister() function and must match exactly the parameters
* passed in an earlier call to usbdDynamicAttachRegister.
*
* RETURNS: OK, or ERROR if unable to unregister for attach/removal notification.
*/

STATUS usbdDynamicAttachUnRegister
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    UINT16 deviceClass, 		/* USB class code */
    UINT16 deviceSubClass,		/* USB sub-class code */
    UINT16 deviceProtocol,		/* USB device protocol code */
    USBD_ATTACH_CALLBACK attachCallback /* user-supplied callback routine */
    )

    {
    URB_DYNA_ATTACH_REG_UNREG urb;


    /* Initalize URB */

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

    urb.deviceClass = deviceClass;
    urb.deviceSubClass = deviceSubClass;
    urb.deviceProtocol = deviceProtocol;
    urb.attachCallback = attachCallback;


    /* Execute URB */

    return urbExecBlock (&urb.header);
    }


/***************************************************************************
*
* usbdFeatureClear - Clears a USB feature
*
* This function allows a client to "clear" a USB feature.  <nodeId> specifies 
* the Node Id of the desired device and <requestType> specifies whether the 
* feature is related to the device, to an interface, or to an endpoint as:
*
* .IP "USB_RT_DEVICE"
* Device
* .IP "USB_RT_INTERFACE"
* Interface
* .IP "USB_RT_ENDPOINT"
* Endpoint
*
* <requestType> also specifies if the request is standard, class-specific,
* etc., as:
*
* .IP "USB_RT_STANDARD"
* Standard
* .IP "USB_RT_CLASS"
* Class-specific
* .IP "USB_RT_VENDOR"
* Vendor-specific
*
* For example, USB_RT_STANDARD | USB_RT_DEVICE in <requestType> specifies a
* standard device request.  
*
* The client must pass the device抯 feature selector in <feature>.  If 
* <featureType> specifies an interface or endpoint, then <index> must contain 
* the interface or endpoint index.  <index> should be zero when <featureType> 
* is USB_SELECT_DEVICE.
*
* RETURNS: OK, or ERROR if unable to clear feature.
*/

STATUS usbdFeatureClear
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_NODE_ID nodeId,		/* Node Id of device/hub */
    UINT16 requestType, 		/* Selects request type */
    UINT16 feature,			/* Feature selector */
    UINT16 index			/* Interface/endpoint index */
    )

    {
    URB_FEATURE_CLEAR_SET urb;


    /* Initalize URB */

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

    urb.nodeId = nodeId;
    urb.requestType = requestType;
    urb.feature = feature;
    urb.index = index;


    /* Execute URB */

    return urbExecBlock (&urb.header);
    }


/***************************************************************************
*
* usbdFeatureSet - Sets a USB feature
*
* This function allows a client to "set" a USB feature.  <nodeId> specifies 
* the Node Id of the desired device and <requestType> specifies the nature
* of the feature feature as defined for the usbdFeatureClear() function.
* 
* The client must pass the device抯 feature selector in <feature>.  If 
* <requestType> specifies an interface or endpoint, then <index> must contain 
* the interface or endpoint index.  <index> should be zero when <requestType>
* includes USB_SELECT_DEVICE.
*
* RETURNS: OK, or ERROR if unable to set feature.
*/

STATUS usbdFeatureSet
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_NODE_ID nodeId,		/* Node Id of device/hub */
    UINT16 requestType, 		/* Selects request type */
    UINT16 feature,			/* Feature selector */
    UINT16 index			/* Interface/endpoint index */
    )

    {
    URB_FEATURE_CLEAR_SET urb;


    /* Initalize URB */

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

    urb.nodeId = nodeId;
    urb.requestType = requestType;
    urb.feature = feature;
    urb.index = index;


    /* Execute URB */

    return urbExecBlock (&urb.header);
    }


/***************************************************************************
*
* usbdConfigurationGet - Gets USB configuration for a device
*
* This function returns the currently selected configuration for the device 
* or hub indicated by <nodeId>.  The current configuration value is returned 
* in the low byte of <pConfiguration>.	The high byte is currently reserved 
* and will be 0.
*
* RETURNS: OK, or ERROR if unable to get configuration.
*/

STATUS usbdConfigurationGet
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_NODE_ID nodeId,		/* Node Id of device/hub */
    pUINT16 pConfiguration		/* bfr to receive config value */
    )

    {
    URB_CONFIG_GET_SET urb;
    STATUS s;


    /* Initalize URB */

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

    urb.nodeId = nodeId;


    /* Execute URB */

    s = urbExecBlock (&urb.header);


    /* Return result */

    if (pConfiguration != NULL)
	*pConfiguration = urb.configuration;

    return s;
    }


/***************************************************************************
*
* usbdConfigurationSet - Sets USB configuration for a device
*
* This function sets the current configuration for the device identified 
* by <nodeId>.	The client should pass the desired configuration value in 
* the low byte of <configuration>.  The high byte is currently reserved and 
* should be 0.
*
* The client must also pass the maximum current which will be used by this
* configuration in <maxPower>.	Typically, the maximum power will be
* determined by reading the corresponding configuration descriptor for a
* device.  Prior to setting the chosen configuration, the USBD will verify
* that the hub port to which <pNode> is connected is capable of providing
* the requested current.  If the port cannot provide <maxPower>, then
* the configuration will not be set and the function will return an error.
* <maxPower> should be expressed in milliamps (e.g., 100 = 100mA).  For
* self-powered devices, the caller may pass zero in <maxPower>.
*
* RETURNS: OK, or ERROR if unable to set configuration.
*/

STATUS usbdConfigurationSet
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_NODE_ID nodeId,		/* Node Id of device/hub */
    UINT16 configuration,		/* New configuration to be set */
    UINT16 maxPower			/* max power this config will draw */
    )

    {
    URB_CONFIG_GET_SET urb;


    /* Initalize URB */

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

    urb.nodeId = nodeId;
    urb.configuration = configuration;
    urb.maxPower = maxPower;


    /* Execute URB */

    return urbExecBlock (&urb.header);
    }


/***************************************************************************
*
* usbdDescriptorGet - Retrieves a USB descriptor
*
* A client uses this function to retrieve a descriptor from the USB device 
* identified by <nodeId>.  <requestType> is defined as documented for the
* usbdFeatureClear() function.	<descriptorType> specifies the type of the 
* descriptor to be retrieved and must be one of the following values:
*
* .IP "USB_DESCR_DEVICE"
* Specifies the DEVICE descriptor.
* .IP "USB_DESCR_CONFIG"
* Specifies the CONFIGURATION descriptor.
* .IP "USB_DESCR_STRING"
* Specifies a STRING descriptor.
* .IP "USB_DESCR_INTERFACE"
* Specifies an INTERFACE descriptor.
* .IP "USB_DESCR_ENDPOINT"
* Specifies an ENDPOINT descriptor.
*
* <descriptorIndex> is the index of the desired descriptor.
*
* For string descriptors the <languageId> should specify the desired 
* language for the string.  According to the USB Specification, strings 
* descriptors are returned in UNICODE format and the <languageId> should 
* be the "sixteen-bit language ID (LANGID) defined by Microsoft for 
* Windows as described in .I "Developing International Software for Windows 
* 95 and Windows NT."  Please refer to Section 9.6.5 of revision 1.1 of the 
* USB Specification for more detail.  For device and configuration 
* descriptors, <languageId> should be 0.
*
* The caller must provide a buffer to receive the descriptor data.  <pBfr> 
* is a pointer to a caller-supplied buffer of length <bfrLen>.	If the 
* descriptor is too long to fit in the buffer provided, the descriptor will 
* be truncated.  If a non-NULL pointer is passed in <pActLen>, the actual 
* length of the data transferred will be stored in <pActLen> upon return.
*
* RETURNS: OK, or ERROR if unable to get descriptor.
*/

STATUS usbdDescriptorGet
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_NODE_ID nodeId,		/* Node Id of device/hub */
    UINT8 requestType,			/* specifies type of request */
    UINT8 descriptorType,		/* Type of descriptor */
    UINT8 descriptorIndex,		/* Index of descriptor */
    UINT16 languageId,			/* Language ID */
    UINT16 bfrLen,			/* Max length of data to be returned */
    pUINT8 pBfr,			/* Pointer to bfr to receive data */
    pUINT16 pActLen			/* bfr to receive actual length */
    )

    {
    URB_DESCRIPTOR_GET_SET urb;
    STATUS s;


    /* Initalize URB */

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

    urb.nodeId = nodeId;
    urb.requestType = requestType;
    urb.descriptorType = descriptorType;
    urb.descriptorIndex = descriptorIndex;
    urb.languageId = languageId;
    urb.bfrLen = bfrLen;
    urb.pBfr = pBfr;


    /* Execute URB */

    s = urbExecBlock (&urb.header);


    /* Return result */

    if (pActLen != NULL)
	*pActLen = urb.actLen;

    return s;
    }


/***************************************************************************
*
* usbdDescriptorSet - Sets a USB descriptor
*
* A client uses this function to set a descriptor on the USB device identified 
* by <nodeId>.	The parameters <requestType>, <descriptorType>, 
* <descriptorIndex>, and <languageId> are the same as those described for the 
* usbdDescriptorGet() function.  <pBfr> is a pointer to a buffer of length 
* <bfrLen> which contains the descriptor data to be sent to the device.
*
* RETURNS: OK, or ERROR if unable to set descriptor.
*/

STATUS usbdDescriptorSet
    (
    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */
    USBD_NODE_ID nodeId,		/* Node Id of device/hub */
    UINT8 requestType,			/* selects request type */
    UINT8 descriptorType,		/* Type of descriptor */
    UINT8 descriptorIndex,		/* Index of descriptor */
    UINT16 languageId,			/* Language ID */
    UINT16 bfrLen,			/* Max length of data to be returned */
    pUINT8 pBfr 			/* Pointer to bfr to receive data */
    )

    {
    URB_DESCRIPTOR_GET_SET urb;


    /* Initalize URB */

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