Writing Windows WDM Device Drivers

The ReservedBits field is usually zero, but if it is a value between 4 and 31 this value is used for bits 4 to 0 in the SETUP packet bmRequestType field (see Table 20.3 in the last chapter).

The Request, Value, Index, and TransferBuffer fields are set appropriately for the vendor– or class-defined request.

URB Isochronous Frame Functions

Request Control of Frame Length

Function codes URB_FUNCTION_TAKE_FRAME_LENGTH_CONTROL URB_FUNCTION_RELEASE_FRAME_LENGTH_CONTROL

Build routine none available

URB Structure _URB_FRAME_LENGTH_CONTROL

Use this function to request control of the frame length (i.e., SOF mastership).

Only one client can have control of frame length at any time.

Get Current Frame Length

Function codes URB_FUNCTION_GET_FRAME_LENGTH

Build routine none available

URB Structure _URB_GET_FRAME_LENGTH

Use this function to get the current frame length in the FrameLength field. It also indicates in FrameNumber the first frame in which the frame length can be changed.

Set Current Frame Length

Function codes URB_FUNCTION_SET_FRAME_LENGTH

Build routine none available

URB Structure _URB_SET_FRAME_LENGTH

Use this function to specify the amount to change the current frame length (i.e., 1 or –1 in the FrameLengthDelta field).

You must have control of frame length to issue this URB.

Get Current Frame Number

Function codes URB_FUNCTION_GET_CURRENT_FRAME_NUMBER

Build routine none available

URB Structure _URB_GET_CURRENT_FRAME_NUMBER

Use this function to get the current frame number in FrameNumber.

Gets Beginning Frame of Pattern Transfer

Function codes URB_FUNCTION_SYNC_FRAME

Build routine none available

URB Structure _URB_CONTROL_SYNC_FRAME_REQUEST

This function retrieves the beginning frame of a pattern transfer from an isochronous pipe.

This function is documented, but both the function code and the URB structure are not defined in the W98 and W2000 DDK USB headers.

Conclusion

The chapter has looked in detail at the Windows USB Device Interface (USBDI) and shown how to use it to talk to a USB HID keyboard. The USB class drivers make several Internal IOCTLs available to USB client device drivers. The most important of these lets you issue USB Request Blocks (URBs). Use URBs to do most interactions with your USB device.

The next chapter looks at the core theory of Human Input Devices (HID). The following chapter shows how to use a HID device in a client device driver and Win32 application.

Chapter 22 The Human Input Device Model

HID Hides

This chapter describes the Human Input Device (HID) model, a standard way of interacting with user input devices. A HID device uses various descriptors to define its capabilities. A Report descriptor details the input reports that it can generate and the output reports it can receive. The next chapter describes how to write Windows client device drivers and user mode applications that can talk to HID devices.

The HID specification is an abstract model for most types of input device that people will use to control their computers. An input device can be a plain old keyboard, for example, a vehicle simulation rudder, or the soft on/off button for the computer.

The HID specification was written originally for USB devices and closely follows the USB descriptor model. However, it is sufficiently generic for HID to be used with other types of device.

Naturally, most of the time a HID device provides input data to the computer. However, you can output to a HID device (e.g., to turn on the NumLock LED on a keyboard). You can also control a feature of the device, such as the font used on a display device or an LED color.

In Windows, the system HID class driver provides an abstract view of the input device. The HID device itself can be a USB device, a IEEE 1394 device or even a plain PC-compatible device, provided an appropriate HID minidriver is written to interface to the bus or device.

In this chapter and the next, quite a few of the examples are about getting input from a keyboard. It does not matter whether you are using a USB keyboard or a (hypothetical) IEEE 1394 keyboard. The system still gets keystrokes in exactly the same way, from the HID class driver. As the next chapter shows, Windows does get input from an old PC-compatible keyboard by a different route. Perhaps eventually a minidriver will be written so that HID will provide all the keyboard input.

HID in Windows

Figure 22.1 shows how HID devices are used in Windows. A user mode or kernel mode HID client program calls the HID device stack. The stack always contains the system HID class driver, Hidсlass.sys, optionally with HID filter drivers above it. The HID class driver uses HID minidrivers to interface to hardware. In the figure, one of the minidrivers, HidUsb.sys. uses the USB stack to talk to a device.

Figure 22.1 HID drivers and clients

HID provides an abstract model of input devices, so client programs are not concerned with the details of where input comes from. HID models a device as various controls representing the device. A keyboard, therefore, usually has single-bit control representing the state of each modifier key, such as the left Shift key, and it has an array of scan code byte controls representing the other keys that are currently pressed.

Underlying the HID model are compact, but complicated, structures for passing information. HID device engineers and minidriver writers will need to know these structures. However, clients can just use various Windows parsing routines to access the relevant data. There are parsers for HID reports available to both kernel mode, Hidparse.dll, and user mode clients, Hid.dll.

The system HID class driver does most of the hard work. It delegates its hardware interactions to HID minidrivers. Windows includes a HID minidriver HidUsb.sys for the devices on the USB bus, but new minidrivers can be written, if necessary. New USB devices that have the appropriate HID Interface class constants and HID descriptors will not need a new minidriver. The system USB HID minidriver calls the system USB driver USBD.sys, optionally through any lower-level USB filter drivers. The system USB driver then talks to the device, etc.

A HID client, therefore, just talks to the HID class driver. The Windows operating system itself is an example of a kernel client, as it can get its keyboard and mouse input via HID. You can write kernel mode client drivers to use a HID device. However, it is often easier to write a Win32 program that talks directly to the HID class driver.

The HID Model

This section is a summary of the HID Model, particularly as seen by Windows device drivers and clients users. For full details, please read the HID specifications.

The HID specification documents are found on the USB website, www.usb.org/developers/. The 'USB: Device Class Definition for HID' document usbhid10.pdf is referred to as the 'HID Specification'. The USB Compatibility Test software, also available there, includes the HIDView program to inspect and test HID devices. The 'Ignore hubs (Memphis only)' box should be checked for Windows 98. The USB website also contains a tool for generating report descriptors, the Descriptor Tool dt. This contains several useful example report descriptors, as well as letting you build your own and check them for errors.

Reports

A computer primarily reads input data from a HID device. It can also send output data to it, and send and receive feature data.

Input data might represent a mouse movement or a keyboard keypress. Output data might mean setting the NumLock LED on a keyboard. A feature is something that controls the general operation of a device, such as the display character size. A feature is usually set by a Control Panel type application and not used by ordinary HID clients.

An individual transaction with a device is called a report, which groups several controls together. An input report from a keyboard says which