Writing Windows WDM Device Drivers

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

Tag Bits	Name	Data bytes
0000	Usage Page	1
0001	Logical Minimum	1-4
0010	Logical Maximum	1-4
0011	Physical Minimum	1-4
0100	Physical Maximum	1-4
0101	Unit Exponent	1-4
0110	Unit	1-4
0111	Report Size	1+
1000	Report ID	1
1001	Report Count	1+
1010	Push	0
1011	Pop	0
others	reserved

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.