Writing Windows WDM Device Drivers

Telephony

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.

Getting HID Capabilities

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.

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.

HID Descriptors

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

Field	Description	Typical values
bLength	length of HID descriptor	9
bDescriptorType	descriptor type	HID_HID_DESCRIPTOR_TYPE, 0x21
bcdHID	HID spec release	0x0100
bCountry	country code	0 == Not Specified
bNumDescriptors	number of HID class descriptors	1
struct _HID_DESCRIPTOR_DESC_LIST { UCHAR bDescriptorType; USHORT wDescriptorLength; } DescriptorList[1];	descriptor type; total length of descriptor	HID_REPORT_DESCRIPTOR TYPE, 0x22, sizeof(MyReportDescriptor)

Device Attributes

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