Книга: Writing Windows WDM Device Drivers

HID Model Representation

HID Model Representation

This section gives explicit details of how the HID model is represented in descriptors and reports. This is useful background for HID client programmers. Minidriver writers and firmware engineers will need to know these details.

HID minidrivers need to return specific data structures to the HID class driver to tell it the device's capabilities. For many new devices, these are provided by the device itself. The crucial data structures are:

• HID descriptor,

• device attributes,

• report descriptor,

• physical descriptors, and

• string descriptors.

The actual data is in little endian format, lowest byte first. A field cannot span more than four bytes in a report.

In a HID USB device, these descriptors will be hard-coded into the device ROM. If you are providing a HID minidriver for a different bus and device, your minidriver may need to synthesize these descriptors internally.

A HID descriptor provides the first information about a device. It mainly confirms that it is a HID device and gives the lengths of its report descriptor and any physical descriptors.

Table 22.2 shows the HID_DESCRIPTOR structure along with typical values. The Descrip-torList field usually just has one element, detailing "report descriptor" and its length. However, it may also specify physical descriptor sets that provide information about the part or parts of the human body used to activate the controls on a device.

Most hardware is not localized, and so should just specify zero for the Country Code.

Table 22.2 HID descriptor

A Device Attributes HID_DEVICE_ATTRIBUTES structure simply has VendorID, ProductID, and VersionNumber fields, along with a Size.

A Report Descriptor is a somewhat complicated (but compact) structure detailing the device's capabilities. It may describe more than one report. A parser is provided by Windows to make sense of the format.

A Report Descriptor is a variable length structure made up of items that provide information about a device. A group of items might describe a single input, output, feature, or collection.

Overview

A Report descriptor usually has an Application collection defining one or more reports. Each report describes the input, output, or feature controls, and collections that it contains.

Each control has a data size and a usage. Controls can be given units, ranges, and scaling exponents. The data structure allows more than one control to be given usages, units, and exponents easily.

Table 22.3 Keyboard modifier keys example

As an example, Table 22.3 shows how three single-bit input controls are specified, the first three modifier keys on a keyboard. The last item, Input, declares the control(s) and states that they are data values (i.e., not constants). Preceding items give more details of the control(s). The preceding Report Size item says that each control has 1 bit and the Report Count item says that there are 3 controls. The preceding Usage Page item specifies the "keyboard" usage page, while the Usage Minimum and Usage Maximum items say that the first input bit corresponds to the left control key of a keyboard and that the last is the left Alt key.

Note that the Item data is actually a byte (e.g., "keyboard" is the constant 07, HID_USAGE_PAGEKEYBOARD).

Item Parts

An item consists of one or more bytes that define an item type, an item tag, an item size, and possibly item data bytes.

An item may be in Short or Long format. Long format is not used yet, so it is not discussed here.

Figure 22.3 shows that the first byte of an item has a Tag of four bits, a Type of two bits and a Data size of two bits. Table 22.4 shows the interpretation of the size and type fields.

Figure 22.3 Short item format

Table 22.4 Short item values

Main Item Tags

The Main item type is used for the Input, Output, Feature, Collection, and End Collection tags. A Main item is usually preceded by one or more Global or Local items that provide the rest of the description of the Main item.

Table 22.5 shows the set of possible item tags if the item type is Main (0). The number of data bytes and their definition is also shown. See the HID specification for full details.

Table 22.5 Main item tags

The Input, Output, and Feature tags allow for up to four data bytes. However, if all the data bits in the top bytes are 0, they can be missed out. So, if bits 8-31 are 0 then the item data size can be given as 1 byte. Further, if no data bits are set at all, the data size can be zero.

For example, two bytes A1 01 (1010 0001 0000 0001) represent "Collection, Main, 1 data byte". The data byte is 0x01 (i.e., Application). Therefore, A1 01 is interpreted as "Collection (Application)".

The one byte C0 (1100 0000) is "End collection, Main, 0 data bytes", and so just means "End Collection".

The two bytes 81 02 (1000 0001 0000 0010) represent "Input, Main, 1 data byte". The data byte just has bit 1 set and so means Data, Variable, Absolute, etc. So 81 02 can be written as "Input (Data, Variable, Absolute)".

Input, Output, and Feature Controls

As shown in the earlier example, an Input, an Output, or a Feature item must be preceded by various other items that further describe the controls. The preceding items can be Global if the setting lasts for more than one control. They can be Local if they provide just the setting for one control.

Input, Output, and Feature items must have Report Size and Report Count preceding Global items. Report Count specifies the number of controls, each of Report Size number of bits.

There must be a preceding Usage Page item. Then specify either a Usage for a single control or a Usage Minimum and Usage Maximum pair if more than one control is being defined.

Logical Minimum and Logical Maximum specify the range of values that may be returned. For example, even though a Report Size is eight bits, the actual values returned might be specified as being between Logical Minimum 0 and Logical Maximum 101 inclusive.

"Constant" bit values are often used to pad out a report so that controls are byte-aligned.

When "Array" is specified, it means that the actual report will contain an array of usage values that apply at the time of the report. Report Count sets the maximum number of usages that may be returned. If fewer usages apply then the array is padded with zeroes.

The full example below shows how various types of control are defined.

Collections

A Physical collection is used to group controls that represent related physical data. A mouse movement might consist of X and Y coordinates and various bit fields to indicate which buttons are pressed.

An Application or top-level collection groups together all the reports, controls and collections in a report descriptor. This is preceded by Usage Pace and usage items. The Application collection usage is often used by a client to determine whether the device is of any interest. For example, the Application collection usage might be "keyboard" or "mouse". A keyboard with an integrated pointing device could be defined as two different Application collections.

Collections may be nested.

Global Item Tags

Global item type tags define the attributes of any following Main items. The appropriate Global value remains in force for the rest of the report descriptor unless replaced.

Table 22.6 shows the set of possible item tags if the item type is Global (1). I have already described most of these tags.

Table 22.6 Global item tags

While Logical Minimum and Logical Maximum bound the values returned by a device, Physical Minimum and Physical Maximum give meaning to those bounds. Physical values are logical values with units applied. For example, a thermometer might have logical extents of 0 and 999, but physical extents of 32 and 212 degrees. Logical 0 corresponds to 32 degrees and logical 999 with 212 degrees.

The Unit and Unit Exponent items further define the type and scaling of the subsequent control(s).

Push and Pop items allow the state of the item stack to be saved and restored.

Local Item Tags

Local item type tags define the attributes of the following Main item. The Local value is only in force for the following Main item.

Table 22.7 shows the set of possible item tags if the item type is Local (2).

Table 22.7 Local item tags

The Usage or Usage Minimum and Usage Maximum give the definition of the following Input, Output, or Feature items.

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

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