Книга: Writing Windows WDM Device Drivers
USBDI Structure Reference
USBDI Structure Reference
This section provides a reference for the USB Driver Interface (USBDI). The basic URB structure has been covered in enough detail in earlier sections of this chapter. Therefore, I first describe various other USBDI structures. Then, I go on to detail each of the URB function codes, the corresponding URB structures and any useful build routines.
Structures
Device Descriptor
A device descriptor is returned in a USB_DEVICE_DESCRIPTOR structure. Table 21.4 shows the fields of interest in the device descriptor. The device class, subclass, and protocol fields are not used by Windows and are often zeroes. However, they may be used to indicate which new common class specification features are used.
Table 21.4 USB DEVICE DESCRIPTOR fields
bDeviceClass bDeviceSubClass bDeviceProtocol |
The USB class codes |
idVendor idProduct bcdDevice |
Vendor, product, and version numbers |
iManufacturer iProduct iSerialNumber |
Indexes into the string descriptor for the relevant strings |
bMaxPacketSize0 |
The maximum packet size for Endpoint 0 |
bNumConfigurations |
The number of configurations |
Configuration Descriptor
A configuration descriptor is returned in a USB_CONFIGURATION_DESCRIPTOR structure, with fields as shown in Table 21.5.
A request for a configuration descriptor will also get any other descriptors associated with this configuration (interface-, endpoint-, class-, and vendor-defined descriptors), if there is enough room in your buffer. You will usually get the configuration descriptor twice. First, get the basic USB_CONFIGURATION_DESCRIPTOR structure. The wTotalLength field tells you how big a buffer to allocate to retrieve all the descriptors in your next get configuration request.
Table 21.5 USB CONFIGURATION DESCRIPTOR fields
wTotalLength |
Total length of all data for the configuration |
bNumInterfaces |
Number of interfaces |
iConfiguration |
Configuration number |
bmAttributes |
bit 5 set: supports remote wake up |
| bit 6 set: self-powered | |
| bit 7 set: powered from bus | |
maxPower |
Maximum power required, in 2mA units |
Interface Descriptor
An interface descriptor is returned in a USB_INTERFACE_DESCRIPTOR structure, with fields shown Table 21.6. Interface descriptors are returned as a part of a get configuration descriptor request.
Table 21.6 USB_INTERFACE DESCRIPTOR fields
bInterfaceNumber |
Interface number |
bAlternateSetting |
Alternate setting |
bNumEndpoints |
Number of endpoints |
bInterfaceClass bInterfaceSubClass bInterfaceProtocol |
USB class codes |
iInterface |
Index of string descriptor describing the interface |
Interface Selection Structures
Various structures are needed when you select a configuration. An array of USB_INTERFACE_LIST_ENTRY structures, shown in Table 21.7, is passed to USBD_CreateConfigurationRequestEx. The InterfaceDescriptor field points to the interface descriptor that you want enabled in the configuration. When the Select Configuration URB has completed, the Interface pointer is valid and refers to valid data.
Table 21.7 USB INTERFACE LIST ENTRY fields
InterfaceDescriptor |
Points to interface descriptor |
Interface |
USB_INTERFACE_INFORMATION pointer |
The Select Configuration URB fills a USB_INTERFACE_INFORMATION structure for each interface that it enables. Table 21.8 shows this structure, whose size increases as there are more pipes.
Table 21.8 USB INTERFACE INFORMATION fields
InterfaceNumber |
Interface number |
AlternateSetting |
Alternate setting |
Class Subclass Protocol |
USB class codes |
NumberOfPipes |
Number of pipes |
PipeInformation |
Array of USB_PIPE_INFORMATION structures |
Table 21.9 shows the USB_PIPE_INFORMATION structure. All fields apart from MaximumTransferSize and PipeFlags fields are filled in by the Select Configuration URB.
Table 21.9 USB_PIPE INFORMATION fields
MaximumPacketSize |
Maximum packet size |
EndpointAddress |
Endpoint number The top bit is set for input pipes. |
Interval |
Polling interval in ms for Interrupt pipes |
PipeType |
UsbdPipeTypeControl UsbdPipeTypeIsochronous UsbdPipeTypeBulk UsbdPipeTypeInterrupt |
PipeHandle |
Handle for later USBDI calls |
MaximumTransferSize |
Maximum transfer size |
PipeFlags |
Flags |
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.
Оглавление книги
