Chris Cant - Writing Windows WDM Device Drivers

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.

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.

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.

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 keys are pressed and which modifier keys are pressed (i.e., Shift, etc.).

A control is a value of one or more bits. Control values can be converted from logical to physical form (i.e., scaled and given units). (Windows refers to some controls as buttons, while it calls others values.).

Reports may be grouped together in Collections. An Application top-level collection usually describes all the reports that a device can produce. More than one Application collection can be given. For example, if a keyboard has a built-in pointer (i.e., a mouse), it might well have an Application collection for a keyboard report and an Application collection for a pointer report. Reports and collections may contain other collections.

Figure 22.2 shows an overview of the Report descriptor for a HID keyboard. An input report contains eight control bits for the modifier keys and six byte values for all the keys that are simultaneously pressed. An output report just contains five output control bits for the keyboard LEDs. The full keyboard report descriptor also contains a "reserved" input control byte and a 3-bit control that pads out the output report.

Figure 22.2 Keyboard report descriptor overview

A HID device needs a standard way to tell programmers what their device is: what Input. Output, and Feature reports it can send and receive. Discovering this information is known as getting a device's capabilities.

Each control or collection of controls is assigned a usage that describes its purpose. The HID Specifications list a large number of usages for a range of standard devices. (I have yet to see a device with a "Do Not Disturb" LED. Did you know that a magic carpet has standard controls?)

A usage is, in fact, represented by two bytes: a Usage Page and a Usage. Table 22.1 shows the main usage categories.

Table 22.1 Main Usage categories

Note that usages are used both to specify the general characteristics of a device (i.e., of an Application collection) and the specifics of each control or group of controls.

The Application collection usage defines the overall purpose of a report. For example, a keyboard usually has an Application collection with a Usage Page of "Generic Desktop" and a Usage of "keyboard". The hidusage.h file defines these as byte constants HID_USAGE_PAGE_GENERIC and HID_USAGE_GENERIC_KEYBOARD, respectively. In most Usage Pages, Usage values in the range 1 to 0x1F usually indicate the overall purpose of a device.

The Application collection usage sometimes implies what controls should be in the report. A keyboard usually has eight input single-bit values, eight reserved bits, five output bits, three padding output bits and six input 8-bit values. Although some clients rely on devices having specific controls, most should be able to cope with different devices (e.g., with more controls) or controls in different reports.