Introduction to HID report descriptors¶
This chapter is meant to give a broad overview of what HID reportdescriptors are, and of how a casual (non-kernel) programmer can dealwith HID devices that are not working well with Linux.
Introduction¶
HID stands for Human Interface Device, and can be whatever device youare using to interact with a computer, be it a mouse, a touchpad, atablet, a microphone.
Many HID devices work out the box, even if their hardware is different.For example, mice can have any number of buttons; they may have awheel; movement sensitivity differs between different models, and soon. Nonetheless, most of the time everything just works, without theneed to have specialized code in the kernel for every mouse modeldeveloped since 1970.
This is because modern HID devices do advertise their capabilitiesthrough theHID report descriptor, a fixed set of bytes describingexactly whatHID reports may be sent between the device and the hostand the meaning of each individual bit in those reports. For example,a HID Report Descriptor may specify that “in a report with ID 3 thebits from 8 to 15 is the delta x coordinate of a mouse”.
The HID report itself then merely carries the actual data valueswithout any extra meta information. Note that HID reports may be sentfrom the device (“Input Reports”, i.e. input events), to the device(“Output Reports” to e.g. change LEDs) or used for device configuration(“Feature reports”). A device may support one or more HID reports.
The HID subsystem is in charge of parsing the HID report descriptors,and converts HID events into normal input device interfaces (seeHID I/O Transport Drivers). Devices may misbehave because theHID report descriptor provided by the device is wrong, or because itneeds to be dealt with in a special way, or because some specialdevice or interaction mode is not handled by the default code.
The format of HID report descriptors is described by two documents,available from theUSB Implementers ForumHID web page address:
theHID USB Device Class Definition (HID Spec from now on)
theHID Usage Tables (HUT from now on)
The HID subsystem can deal with different transport drivers(USB, I2C, Bluetooth, etc.). SeeHID I/O Transport Drivers.
Parsing HID report descriptors¶
The current list of HID devices can be found at/sys/bus/hid/devices/.For each device, say/sys/bus/hid/devices/0003\:093A\:2510.0002/,one can read the corresponding report descriptor:
$ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).|00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....|00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...|00000030 81 06 c0 c0 |....|00000034
Optional: the HID report descriptor can be read also bydirectly accessing the hidraw driver[1].
The basic structure of HID report descriptors is defined in the HIDspec, while HUT “defines constants that can be interpreted by anapplication to identify the purpose and meaning of a data field in aHID report”. Each entry is defined by at least two bytes, where thefirst one defines what type of value is following and is described inthe HID spec, while the second one carries the actual value and isdescribed in the HUT.
HID report descriptors can, in principle, be painstakingly parsed byhand, byte by byte.
A short introduction on how to do this is sketched inManual parsing of HID report descriptors; you only need to understand itif you need to patch HID report descriptors.
In practice you should not parse HID report descriptors by hand; rather,you should use an existing parser. Among all the available ones
the onlineUSB Descriptor and Request Parser;
hidrdd,that provides very detailed and somewhat verbose descriptions(verbosity can be useful if you are not familiar with HID reportdescriptors);
hid-tools,a complete utility set that allows, among other things,to record and replay the raw HID reports and to debugand replay HID devices.It is being actively developed by the Linux HID subsystem maintainers.
Parsing the mouse HID report descriptor withhid-tools leads to(explanations interposed):
$ ./hid-decode /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor# device 0:0# 0x05, 0x01, // Usage Page (Generic Desktop) 0# 0x09, 0x02, // Usage (Mouse) 2# 0xa1, 0x01, // Collection (Application) 4# 0x09, 0x01, // Usage (Pointer) 6# 0xa1, 0x00, // Collection (Physical) 8# 0x05, 0x09, // Usage Page (Button) 10
what follows is a button
# 0x19, 0x01, // Usage Minimum (1) 12# 0x29, 0x03, // Usage Maximum (3) 14
first button is button number 1, last button is button number 3
# 0x15, 0x00, // Logical Minimum (0) 16# 0x25, 0x01, // Logical Maximum (1) 18
each button can send values from 0 up to including 1(i.e. they are binary buttons)
# 0x75, 0x01, // Report Size (1) 20
each button is sent as exactly one bit
# 0x95, 0x03, // Report Count (3) 22
and there are three of those bits (matching the three buttons)
# 0x81, 0x02, // Input (Data,Var,Abs) 24
it’s actual Data (not constant padding), they representa single variable (Var) and their values are Absolute (not relative);See HID spec Sec. 6.2.2.5 “Input, Output, and Feature Items”
# 0x75, 0x05, // Report Size (5) 26
five additional padding bits, needed to reach a byte
# 0x95, 0x01, // Report Count (1) 28
those five bits are repeated only once
# 0x81, 0x01, // Input (Cnst,Arr,Abs) 30
and take Constant (Cnst) values i.e. they can be ignored.
# 0x05, 0x01, // Usage Page (Generic Desktop) 32# 0x09, 0x30, // Usage (X) 34# 0x09, 0x31, // Usage (Y) 36# 0x09, 0x38, // Usage (Wheel) 38
The mouse has also two physical positions (Usage (X), Usage (Y))and a wheel (Usage (Wheel))
# 0x15, 0x81, // Logical Minimum (-127) 40# 0x25, 0x7f, // Logical Maximum (127) 42
each of them can send values ranging from -127 up to including 127
# 0x75, 0x08, // Report Size (8) 44
which is represented by eight bits
# 0x95, 0x03, // Report Count (3) 46
and there are three of those eight bits, matching X, Y and Wheel.
# 0x81, 0x06, // Input (Data,Var,Rel) 48
This time the data values are Relative (Rel), i.e. they representthe change from the previously sent report (event)
# 0xc0, // End Collection 50# 0xc0, // End Collection 51#R: 52 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 81 06 c0 c0N: device 0:0I: 3 0001 0001
This Report Descriptor tells us that the mouse input will betransmitted using four bytes: the first one for the buttons (threebits used, five for padding), the last three for the mouse X, Y andwheel changes, respectively.
Indeed, for any event, the mouse will send areport of four bytes.We can check the values sent by resorting e.g. to thehid-recordertool, fromhid-tools:The sequence of bytes sent by clicking and releasing button 1, then button 2, then button 3 is:
$ sudo ./hid-recorder /dev/hidraw1....output of hid-decode....# Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0E: 000000.000000 4 01 00 00 00# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0E: 000000.183949 4 00 00 00 00# Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0E: 000001.959698 4 02 00 00 00# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0E: 000002.103899 4 00 00 00 00# Button: 0 0 1 | # | X: 0 | Y: 0 | Wheel: 0E: 000004.855799 4 04 00 00 00# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0E: 000005.103864 4 00 00 00 00
This example shows that when button 2 is clicked,the bytes02000000 are sent, and the immediately subsequentevent (00000000) is the release of button 2 (no buttons arepressed, remember that the data values areabsolute).
If instead one clicks and holds button 1, then clicks and holds button2, releases button 1, and finally releases button 2, the reports are:
# Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0E: 000044.175830 4 01 00 00 00# Button: 1 1 0 | # | X: 0 | Y: 0 | Wheel: 0E: 000045.975997 4 03 00 00 00# Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0E: 000047.407930 4 02 00 00 00# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0E: 000049.199919 4 00 00 00 00
where with03000000 both buttons are pressed, and with thesubsequent02000000 button 1 is released while button 2 is stillactive.
Output, Input and Feature Reports¶
HID devices can have Input Reports, like in the mouse example, OutputReports, and Feature Reports. “Output” means that the information issent to the device. For example, a joystick with force feedback willhave some output; the led of a keyboard would need an output as well.“Input” means that data come from the device.
“Feature”s are not meant to be consumed by the end user and defineconfiguration options for the device. They can be queried from the host;when declared asVolatile they should be changed by the host.
Collections, Report IDs and Evdev events¶
A single device can logically group data into different independentsets, called aCollection. Collections can be nested and there aredifferent types of collections (see the HID spec 6.2.2.6“Collection, End Collection Items” for details).
Different reports are identified by means of differentReport IDfields, i.e. a number identifying the structure of the immediatelyfollowing report.Whenever a Report ID is needed it is transmitted as the first byte ofany report. A device with only one supported HID report (like the mouseexample above) may omit the report ID.
Consider the following HID report descriptor:
05 01 09 02 A1 01 85 01 05 09 19 01 29 05 15 0025 01 95 05 75 01 81 02 95 01 75 03 81 01 05 0109 30 09 31 16 00 F8 26 FF 07 75 0C 95 02 81 0609 38 15 80 25 7F 75 08 95 01 81 06 05 0C 0A 3802 15 80 25 7F 75 08 95 01 81 06 C0 05 01 09 02A1 01 85 02 05 09 19 01 29 05 15 00 25 01 95 0575 01 81 02 95 01 75 03 81 01 05 01 09 30 09 3116 00 F8 26 FF 07 75 0C 95 02 81 06 09 38 15 8025 7F 75 08 95 01 81 06 05 0C 0A 38 02 15 80 257F 75 08 95 01 81 06 C0 05 01 09 07 A1 01 85 0505 07 15 00 25 01 09 29 09 3E 09 4B 09 4E 09 E309 E8 09 E8 09 E8 75 01 95 08 81 02 95 00 81 01C0 05 0C 09 01 A1 01 85 06 15 00 25 01 75 01 9501 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 8106 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 8106 C0 05 0C 09 01 A1 01 85 03 09 05 15 00 26 FF00 75 08 95 02 B1 02 C0
After parsing it (try to parse it on your own using the suggestedtools!) one can see that the device presents twoMouse ApplicationCollections (with reports identified by Reports IDs 1 and 2,respectively), aKeypad Application Collection (whose report isidentified by the Report ID 5) and twoConsumerControls ApplicationCollections, (with Report IDs 6 and 3, respectively). Note, however,that a device can have different Report IDs for the same ApplicationCollection.
The data sent will begin with the Report ID byte, and will be followedby the corresponding information. For example, the data transmitted forthe last consumer control:
0x05, 0x0C, // Usage Page (Consumer)0x09, 0x01, // Usage (Consumer Control)0xA1, 0x01, // Collection (Application)0x85, 0x03, // Report ID (3)0x09, 0x05, // Usage (Headphone)0x15, 0x00, // Logical Minimum (0)0x26, 0xFF, 0x00, // Logical Maximum (255)0x75, 0x08, // Report Size (8)0x95, 0x02, // Report Count (2)0xB1, 0x02, // Feature (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)0xC0, // End Collection
will be of three bytes: the first for the Report ID (3), the next twofor the headphone, with two (ReportCount(2)) bytes(ReportSize(8)), each ranging from 0 (LogicalMinimum(0))to 255 (LogicalMaximum(255)).
All the Input data sent by the device should be translated intocorresponding Evdev events, so that the remaining part of the stack canknow what is going on, e.g. the bit for the first button translates intotheEV_KEY/BTN_LEFT evdev event and relative X movement translatesinto theEV_REL/REL_X evdev event”.
Events¶
In Linux, one/dev/input/event* is created for eachApplicationCollection. Going back to the mouse example, and repeating thesequence where one clicks and holds button 1, then clicks and holdsbutton 2, releases button 1, and finally releases button 2, one gets:
$ sudo libinput record /dev/input/event1# libinput recordversion: 1ndevices: 1libinput: version: "1.23.0" git: "unknown"system: os: "opensuse-tumbleweed:20230619" kernel: "6.3.7-1-default" dmi: "dmi:bvnHP:bvrU77Ver.01.05.00:bd03/24/2022:br5.0:efr20.29:svnHP:pnHPEliteBook64514inchG9NotebookPC:pvr:rvnHP:rn89D2:rvrKBCVersion14.1D.00:cvnHP:ct10:cvr:sku5Y3J1EA#ABZ:"devices:- node: /dev/input/event1 evdev: # Name: PixArt HP USB Optical Mouse # ID: bus 0x3 vendor 0x3f0 product 0x94a version 0x111 # Supported Events: # Event type 0 (EV_SYN) # Event type 1 (EV_KEY) # Event code 272 (BTN_LEFT) # Event code 273 (BTN_RIGHT) # Event code 274 (BTN_MIDDLE) # Event type 2 (EV_REL) # Event code 0 (REL_X) # Event code 1 (REL_Y) # Event code 8 (REL_WHEEL) # Event code 11 (REL_WHEEL_HI_RES) # Event type 4 (EV_MSC) # Event code 4 (MSC_SCAN) # Properties: name: "PixArt HP USB Optical Mouse" id: [3, 1008, 2378, 273] codes: 0: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] # EV_SYN 1: [272, 273, 274] # EV_KEY 2: [0, 1, 8, 11] # EV_REL 4: [4] # EV_MSC properties: [] hid: [ 0x05, 0x01, 0x09, 0x02, 0xa1, 0x01, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 0x19, 0x01, 0x29, 0x03, 0x15, 0x00, 0x25, 0x01, 0x95, 0x08, 0x75, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75, 0x08, 0x95, 0x03, 0x81, 0x06, 0xc0, 0xc0 ] udev: properties: - ID_INPUT=1 - ID_INPUT_MOUSE=1 - LIBINPUT_DEVICE_GROUP=3/3f0/94a:usb-0000:05:00.3-2 quirks: events: # Current time is 12:31:56 - evdev: - [ 0, 0, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 0, 0, 1, 272, 1] # EV_KEY / BTN_LEFT 1 - [ 0, 0, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +0ms - evdev: - [ 1, 207892, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 1, 207892, 1, 273, 1] # EV_KEY / BTN_RIGHT 1 - [ 1, 207892, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1207ms - evdev: - [ 2, 367823, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 2, 367823, 1, 272, 0] # EV_KEY / BTN_LEFT 0 - [ 2, 367823, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1160ms # Current time is 12:32:00 - evdev: - [ 3, 247617, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) - [ 3, 247617, 1, 273, 0] # EV_KEY / BTN_RIGHT 0 - [ 3, 247617, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +880ms
Note: iflibinputrecord is not available on your system try usingevemu-record.
When something does not work¶
There can be a number of reasons why a device does not behavecorrectly. For example
The HID report descriptor provided by the HID device may be wrongbecause e.g.
it does not follow the standard, so that the kernelwill not able to make sense of the HID report descriptor;
the HID report descriptordoes not match what is actuallysent by the device (this can be verified by reading the raw HIDdata);
the HID report descriptor may need some “quirks” (see later on).
As a consequence, a/dev/input/event* may not be createdfor each Application Collection, and/or the eventsthere may not match what you would expect.
Quirks¶
There are some known peculiarities of HID devices that the kernelknows how to fix - these are called the HID quirks and a list of thoseis available ininclude/linux/hid.h.
Should this be the case, it should be enough to add the required quirkin the kernel, for the HID device at hand. This can be done in the filedrivers/hid/hid-quirks.c. How to do it should be relativelystraightforward after looking into the file.
The list of currently defined quirks, frominclude/linux/hid.h, is
Quirks for USB devices can be specified while loading the usbhid module,seemodinfousbhid, although the proper fix should go intohid-quirks.c andbe submitted upstream.SeeSubmitting patches: the essential guide to getting your code into the kernel for guidelines on howto submit a patch. Quirks for other busses need to go into hid-quirks.c.
Fixing HID report descriptors¶
Should you need to patch HID report descriptors the easiest way is toresort to eBPF, as described inHID-BPF.
Basically, you can change any byte of the original HID reportdescriptor. The examples in samples/hid should be a good starting pointfor your code, see e.g.samples/hid/hid_mouse.bpf.c:
SEC("fmod_ret/hid_bpf_rdesc_fixup")int BPF_PROG(hid_rdesc_fixup, struct hid_bpf_ctx *hctx){ .... data[39] = 0x31; data[41] = 0x30; return 0;}Of course this can be also done within the kernel source code, see e.g.drivers/hid/hid-aureal.c ordrivers/hid/hid-samsung.c for a slightlymore complex file.
CheckManual parsing of HID report descriptors if you need any helpnavigating the HID manuals and understanding the exact meaning ofthe HID report descriptor hex numbers.
Whatever solution you come up with, please remember tosubmit thefix to the HID maintainers, so that it can be directly integrated inthe kernel and that particular HID device will start working foreveryone else. SeeSubmitting patches: the essential guide to getting your code into the kernel forguidelines on how to do this.
Modifying the transmitted data on the fly¶
Using eBPF it is also possible to modify the data exchanged with thedevice. See again the examples insamples/hid.
Again,please post your fix, so that it can be integrated in thekernel!
Writing a specialized driver¶
This should really be your last resort.
Footnotes
[1]read hidraw: seeHIDRAW - Raw Access to USB and Bluetooth Human Interface Devices andfilesamples/hidraw/hid-example.c for an example.The output ofhid-example would be, for the same mouse:
$ sudo ./hid-exampleReport Descriptor Size: 52Report Descriptor:5 1 9 2 a1 1 9 1 a1 0 5 9 19 1 29 3 15 0 25 1 75 1 95 3 81 2 75 5 95 1 81 1 5 1 9 30 9 31 9 38 15 81 25 7f 75 8 95 3 81 6 c0 c0Raw Name: PixArt USB Optical MouseRaw Phys: usb-0000:05:00.4-2.3/input0Raw Info: bustype: 3 (USB) vendor: 0x093a product: 0x2510...