Книга: Writing Windows WDM Device Drivers

The HID Model

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.

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.

Each control also has a usage. The eight single-bit input values in a keyboard report represent the modifier keys (i.e., whether a Shift, Ctrl, or Alt key is pressed at the same time). These modifiers are defined in the "Keyboard" Usage Page (HID_USAGE_PAGE_KEYBOARD). The first single bit value represents the state of the left control key and has a Usage of HID_USAGE_ KEYBOARD_LCTRL.

The HID Specification defines Usage values in the "Keyboard" Usage Page that represent all the common keyboard key scan codes. PC-AT keyboards return usages in the range 0 to 101.

However, the left control key has a usage of 240, HID_USAGE_KEYBOARD_LCTRL As described previously, this is usually returned as a bit value to indicate whether the key is pressed or not.

The HID Specification lets you define several reports in a report descriptor, each with different report IDs. However most Report descriptors do not use report IDs at all. For example, the keyboard Application collection just defines one report with both input and output controls in it. However, a keyboard with a built-in pointing device may have two Application collections with two reports, a keyboard report, and a pointer report.

When first used, a HID device needs to be interrogated to find out what it is. The client gets the device capabilities, the list of reports that the device may generate or accept. The client then decides whether the device is of interest. The capabilities are in a slightly opaque format, so Windows provides a parser to help clients analyze them. The parser functions are described in the next chapter.

You may also want to read a HID device's string descriptors and physical descriptors. Both are not necessary for most HID interactions, so they are only covered briefly here. See the HID specification for more details.

Controls may optionally have a string index. You can ask the device for the corresponding string, identified by the string index and a language ID. The string descriptor for index zero is special; it provides a list of the language IDs that are supported. HID string descriptors are identical to their USB equivalent, described in the previous two chapters.

Physical descriptors describe which parts of the body can be used to activate a device's controls. Each control may optionally have a designator index that can be used to look up the appropriate physical descriptor.

Then…

After this, the device generates input reports whenever appropriate, perhaps regularly. You can send output reports to the device. It may be able to send and receive feature reports.

Оглавление книги