Chris Cant - Writing Windows WDM Device Drivers

The Select Configuration URB is then issued. This may fail if there is not enough USB bandwidth available. If it works, a configuration handle is returned. You can use this to select a different alternate interface setting. UsbKbd stores the configuration handle in its device extension, but does not use it.

UsbKbd does need to store the pipe handle for the HID keyboard's interrupt pipe. For a HID USB keyboard, this is the first and only pipe in the USBD_INTERFACE_INFORMATION structure. UsbKbd makes DebugPrint calls to display other potentially useful information. UsbKbd finally frees the URB and configuration descriptor memory.

Listing 21.5 Selecting a configuration and interface

NTSTATUS UsbSelectConfiguration(IN PUSBKBD_DEVICE_EXTENSION dx) {

dx->UsbPipeHandle = NULL;

// Get all first configuration descriptors

PUSB_CONFIGURATIONDESCRIPTOR Descriptors = NULL;

ULONG size;

NTSTATUS status = UsbGetConfigurationDescriptors(dx, Descriptors, 0, size);

if (!NT_SUCCESS(status)) {

DebugPrint("UsbGetConfigurationDescriptors failed %x", status);

FreeIfAllocated(Descriptors);

return status;

}

// Search for an interface with HID keyboard device class

PUSB_INTERFACE_DESCRIPTOR id = USBD_ParseConfigurationDescriptorEx(Descriptors, Descriptors,

-1, –1, // Do not search by InterfaceNumber or AlternateSetting

3, 1, 1); // Search for a HID device, boot protocol, keyboard

if (id==NULL) {

DebugPrintMsg("No matching interface found");

FreeIfAllocated(Descriptors);

return STATUS_NO_SUCH_DEVICE;

}

// Build list of interfaces we are interested in

USBD_INTERFACE_LIST_ENTRY ilist[2];

ilist[0].InterfaceDescriptor = id;

ilist[0].Interface = NULL; // Will point to

// urb->UrbUsbSelectConfiguration.Interface

ilist[1].InterfaceDescriptor = NULL;

// Create select configuration URB

PURB urb = USBD_CreateConfigurationRequestEx(Descriptors, ilist);

// Call the USB driver

DebugPrintMsg("Select ing configuration");

status = CallUSBDI(dx, urb);

// Check statuses

if (!NT_SUCCESS(status) || !USBD_SUCCESS( urb->UrbHeader.Status)) {

DebugPrint("status %x URB status %x", status, urb->UrbHeader.Status);

status = STATUS_UNSUCCESSFUL;

} else {

// Select config worked

DebugPrintMsg("Select configuration worked");

dx->UsbConfigurationHandle = urb->UrbSelectConfiguration.ConfigurationHandle;

// Find pipe handle of first pipe,

// ie interrupt pipe that returns input HID reports

PUSBD_INTERFACE_INFORMATION InterfaceInfo = &urb->UrbSelectConfiguration.Interface;

DebugPrint("interface Class %d NumberOfPipes %d", InterfaceInfo->Class, InterfaceInfo->NumberOfPipes);

if (InterfaceInfo->NumberOfPipes>0) {

PUSBD_PIPE_INFORMATION pi = &InterfaceInfo->Pipes[0];

dx->UsbPipeHandle = pi->PipeHandle;

DebugPrint("PipeHandle = %x", dx->UsbPipeHandle);

DebugPrint("Pipes[0] EndpointAddress %2x"

"Interval %dms PipeType %d MaximumTransferSize %c",

pi->EndpointAddress, pi->Interval, pi->PipeType, pi->MaximumTransferSize);

}

if (dx->UsbPipeHandle==NULL) status = STATUS_UNSUCCESSFUL;

}

FreeIfAllocated(urb);

FreeIfAllocated(Descriptors);

return status;

}

As mentioned earlier, having selected your configuration and interface, there may be some more steps needed to initialize your USB peripheral. You may want to read other descriptors. The UsbKbd Create IRP handler shows how this might be done by getting the first string descriptor. This in fact just returns the language ID that the device supports. You will have to issue further Get Descriptor requests to get each String Descriptor. The UsbGetSpecifiedDescriptor routine in Usb.cpp can be used to get any descriptor. This routine is also used by the IOCTL_USBKBD_GET_SPECIFIED_DESCRIPTOR handler. The UsbKbdTest test program issues this IOCTL to get the HID Descriptor.

The UsbKbd Create IRP handler, UsbKbdCreate , also retrieves some general information about the USB bus, such as the amount of bandwidth used and the host controller device name. The required Internal IOCTLs are only implemented in Windows 2000, so preprocessor directives are used to remove the body of the function that does this job, UsbGetUsbInfo , when compiled for Windows 98.

Most USB device drivers will now want to talk to their devices over control or other pipes. Shortly, I describe how to perform such transfers.

When a driver wants to stop accessing its device, it should deselect its configuration. In UsbKbd, the Close file handle IRP handler does this job. The UsbDeselectConfiguration routine uses UsbBuildSelectConfigurationRequest to build a Select Configuration URB with a NULL configuration descriptor. This disables the configuration and its interfaces.

The specification for UsbKbd says that it reports raw keyboard data in response to ReadFile Win32 requests. It also must implement a time-out, which defaults to 10 seconds.

Before I describe how to handle the Read IRPs, I must discuss how a USB HID keyboard produces data. The keyboard responds to USB Interrupt transfers with an 8-byte data report. The exact format of this block is discussed in the next chapter on Human Input Devices (HID).

A keyboard report is produced whenever a keypress or release occurs. A report is also produced regularly even if no keypresses occur. This is what happens on the USB bus. The USB class drivers initiate an Interrupt transfer regularly. My USB keyboard specifies that interrupt transfers should occur every 8ms. However, USB HID keyboards implement an idle rate. If there are no state changes during the idle period, the keyboard NAKs each Interrupt request. At the end of the idle period (every 500ms or so), the keyboard returns data regardless. The idle rate can be read and changed using class specific control transfers on the default pipe [53] The UsbGetIdleRate routine shows how to read the idle rate. .

UsbKbd issues a Do Bulk or Interrupt Transfer URB to receive any keyboard reports. Keyboard reports are not "saved up" ready to fulfil any interrupt transfer requests. It is not clear whether the USB class drivers simply do not do any transfers, or whether they do the transfers but just dump the data. Any keypresses before an interrupt transfer is requested are ignored. I understand that the Microsoft keyboard drivers always try to leave two Interrupt transfer requests outstanding; the hope is that this should ensure that no keypresses are lost.

It turns out that the 8-byte keyboard report is all zeroes if no keys are pressed. The UsbKbd Read IRP handler ignores any keyboard reports that are all zero. A real driver would return read data when any key is pressed or released. A higher-level driver would have to implement an auto-repeat feature.