Chris Cant - Writing Windows WDM Device Drivers

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.