Chris Cant - Writing Windows WDM Device Drivers

For example, a keyboard uses eight one-bit values to specify the state of its Ctrl, Shift, Alt, etc., modifier keys. The report descriptor, therefore, has input controls in the HID_USAGE_ PAGE_KEYBOARD Usage Page. Its Usage Minimum is HID_USAGE_KEYBOARD_LCTRL (i.e., 224) and Usage Maximum is HID_USAGE_KEYBOARD_RGUI (i.e., 231). This means that if the first input bit is set, the left Ctrl key is pressed, etc.

The Designator items determine the body part used for each control, and refers to a Physical Descriptor.

Strings can be associated with each control. The String items give the String descriptor index.

A control may have more than one usage, string, or physical descriptor associated with it. One or more alternative sets of local items may be associated with a control by simply bracketing each set with Set Delimiter items.

Example

A 105-key keyboard should report eight modifier keys (i.e., Shift, etc.) and up to six simultaneous key presses. It has five output LEDs (i.e., for NumLock, etc.). The complete report descriptor is shown in Table 22.8.

Table 22.8 A keyboard report descriptor

The first three items specify the Application collection as being a keyboard in the generic usage page. A client will therefore know straightaway that this device is a keyboard.

The next items define the modifier input controls. There are eight single-bit inputs, each naturally reporting either 0 or 1. These inputs correspond to eight usage values in the keyboard usage page, the left Shi ft key being pressed, onwards.

The next item defines a reserved constant byte of eight single bits. Note how the Global Report Size and Report Count items persist after the previous Main item.

The next control is for the output LEDs. There are five of them, still bits needing values of 0 or 1. The LED usage page is now in force and the output bits correspond to the NumLock key, etc.

The next control is a 3-bit constant field, padding the output report to make it up to a complete byte.

The actual key presses are defined in a single Input item with its "Array" bit set. Up to 6-key scan codes may be read, each of eight bits. However, the actual values returned are in the range 0 to 101. The keyboard has 102 keys and three modifier keys, returned separately as three bits.

No Report ID items are given, and so the descriptor describes one report that contains the current state of all the input and output items. An actual input report, therefore, always contains the eight modifier bits, a reserved byte of 0x00, and one to six key scan codes padded to six bytes with zeroes. An actual output report just contains one byte with the lower five bits giving the required LED states.

Pressing Ctrl+Alt+Del might result in the six input reports shown in Table 22.9. The reserved byte values are not shown.

Table 22.9 Ctrl+Alt+Del input reports

This chapter has introduced you to the Human Input Device (HID) model. A HID device uses various descriptors to define its functionality. The most important of these, the Report descriptor, defines what input reports it generates and the output reports it can receive. The controls within a report are given "usage" values that define their function exactly. A full example of a Report descriptor was given for a HID keyboard.

The next chapter looks at how to use the HID class drivers in Windows. Both kernel mode drivers and user mode applications can access HID devices.

This chapter shows how to use the Human Input Device (HID) model in Windows. It is easy to write a user mode application to talk to a HID device through the Windows HID class driver. If need be, you can write a kernel mode HID client to do the same job. A HID kernel mode client can be layered over the HID class driver in the normal way. Alternatively, it can use Plug and Play Notification to find any suitable HID devices. Windows provides routines that make it much easier to analyze HID Report descriptors and send and receive reports.

This chapter initially looks at how to write a user mode application, called HidKbdUser, to talk to a HID keyboard. This section describes all the Windows parsing routines that are available to both user mode and kernel mode HID clients.