Chris Cant - Writing Windows WDM Device Drivers

Table 21.9 USB_PIPE INFORMATION fields

String Descriptor

A device may optionally provide string descriptors. Each string descriptor contains just one Unicode string, so the driver must request each string one by one. String index zero is special. Instead of a string, it contains a list of two-byte language ID codes. Language ID 0x0009 is usually used for generic English.

As has been seen, various other descriptors contain string index numbers. If these numbers are non-zero, there is an associated string. When you request a string descriptor using the GetDescriptor URB, you must specify both the string index and the language ID that you want.

A USB_STRING_DESCRIPTOR structure simply has one useful field, bString, that contains the Unicode string for which you asked. The maximum string length (MAXIMUM_USB_STRING_ LENGTH) is 255 characters. When you request string index zero, bString instead contains the supported language ID.

Isochronous Packet Descriptor

The USBD_ISO_PACKET_DESCRIPTOR structure is used to describe an isochronous transfer packet. An isochronous transfer request URB has a single transfer buffer that may contain several individual packets.

For writes, set the Offset field of each packet descriptor to indicate the offset into this buffer of this packet.

For reads, the packet descriptor Length field is filled with the number of bytes read and the Status field returns the status of this transfer packet.

All these URBs use standard USB control transfers over the default pipe. I will later explain the details of how to set or clear features, or do class or vendor defined control transfers over the default pipe.

Get Descriptor

Function codes URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE

Build routine UsbBuildGetDescriptorRequest

URB Structure _URB_CONTROL_DESCRIPTOR_REQUEST

Use this function to get any descriptor from a device. The DescriptorType URB field determines which descriptor is retrieved. A suitably sized buffer must be provided. If asking for a configuration descriptor, specify an appropriate value for the URB Index field. If you are getting a string descriptor, specify a LanguageId field, as well.

If you ask for a configuration descriptor, you also get all the associated interface, endpoint, and class– and vendor-defined descriptors.

Other Get/Set Descriptors

Function codes URB_FUNCTION_GET_DESCRIPTOR_FROM_ENDPOINT URB_FUNCTION_SET_DESCRIPTOR_TO_ENDPOINT URB_FUNCTION_SET_DESCRIPTOR_TO_OTHER

Build routinenone available

URB Structure _URB_CONTROL_DESCRIPTOR_REQUEST

This function gets or sets other descriptors.

Get Status

Function codes URB_FUNCTION_GET_STATUS_FROM_DEVICE URB_FUNCTION_GET_STATUS_FROM_INTERFACE URB_FUNCTION_GET_STATUS_FROM_ENDPOINT URB_FUNCTION_GET_STATUS_FROM_OTHER

Build routine UsbBuildGetStatusRequest

URB Structure _URB_CONTROL_GET_STATUS_REQUEST

This function gets a status word.

The device status word has self-powered and remote wakeup bits (USB_GETSTATUS_SELF_POWERED and USB_GETSTATUS_REMOTE_WAKEUP_ENABLED are the bit masks). The interface status currently has no bits defined. The endpoint status word has its bit zero set if the Halt feature has been set.

Select Configuration

Function codes URB_FUNCTION_SELECT_CONFIGURATION

Build routine USBD_CreateConfigurationRequestEx UsbBuildSelectConfigurationRequest

URB Structure _URB_SELECT_CONFIGURATION

Use USBD_CreateConfigurationRequestEx to select a configuration and an interface, as described earlier.

If deselecting a configuration, use the simpler UsbBuildSelectConfigurationRequest to pass a NULL configuration descriptor.

Get Configuration

Function codes URB_FUNCTION_GET_CONFIGURATION

Build routinenone available

URB Structure _URB_CONTROL_GET_CONFIGURATION_REQUEST

This function gets the current configuration descriptors.

Select Alternate Interface

Function codes URB_FUNCTION_SELECT_INTERFACE

Build routine UsbBuildSelectInterfaceRequest

URB Structure _URB_SELECT_INTERFACE

Use this URB function code to select an interface's alternate setting. Pass the configuration handle, the interface number, and the alternate setting.

Changing to an alternate interface setting discards any queued data on the interface endpoints.

Get Interface

Function codes URB_FUNCTION_GET_INTERFACE

Build routinenone available

URB Structure _URB_CONTROL_GET_INTERFACE_REQUEST

This function gets the current alternate interface setting for an interface in the current configuration.

Reset Pipe

Function codes URB_FUNCTION_RESET_PIPE

Build routinenone available

URB Structure _URB_HEADER

This function can clear a stall condition on the pipe with the given PipeHandle.

Do Control Transfer

Function codes URB_FUNCTION_CONTROL_TRANSFER

Build routinenone available

URB Structure _URB_CONTROL_TRANSFER

This function can transmit or receive data on a control pipe with the given PipeHandle. Fill the SetupPacket 8-byte array with the information for the SETUP packet. The TransferBuffer fields specify the extra data. The USBD_TRANSFER_DIRECTION_IN bit in the TransferFlags field specifies the direction in which the extra data flows. Specify the USBD_SHORT_TRANSFER_OK flag bit if a short input transfer is acceptable.

Do not use his function for transfers over the default pipe.

Do Bulk or Interrupt Transfer

Function codes URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER

Build routine UsbBuildInterruptOrBulkTransferRequest

URB Structure _URB_BULK_OR_INTERRUPT_TRANSFER

Use this function to transmit or receive data on a bulk pipe, or receive data on an interrupt pipe. Specify the pipe using the PipeHandle field. The TransferBuffer fields specify the data. The USBD_TRANSFER_DIRECTION_IN bit in the TransferFlags field specifies the direction in which the data flows. Specify the USBD_SHORT_TRANSFER_OK flag bit if a short input transfer is acceptable.