1.. SPDX-License-Identifier: GPL-2.0 2 3====================================== 4Introduction to HID report descriptors 5====================================== 6 7This chapter is meant to give a broad overview of what HID report 8descriptors are, and of how a casual (non-kernel) programmer can deal 9with HID devices that are not working well with Linux. 10 11.. contents:: 12 :local: 13 :depth: 2 14 15.. toctree:: 16 :maxdepth: 2 17 18 hidreport-parsing 19 20 21Introduction 22============ 23 24HID stands for Human Interface Device, and can be whatever device you 25are using to interact with a computer, be it a mouse, a touchpad, a 26tablet, a microphone. 27 28Many HID devices work out the box, even if their hardware is different. 29For example, mice can have any number of buttons; they may have a 30wheel; movement sensitivity differs between different models, and so 31on. Nonetheless, most of the time everything just works, without the 32need to have specialized code in the kernel for every mouse model 33developed since 1970. 34 35This is because modern HID devices do advertise their capabilities 36through the *HID report descriptor*, a fixed set of bytes describing 37exactly what *HID reports* may be sent between the device and the host 38and the meaning of each individual bit in those reports. For example, 39a HID Report Descriptor may specify that "in a report with ID 3 the 40bits from 8 to 15 is the delta x coordinate of a mouse". 41 42The HID report itself then merely carries the actual data values 43without any extra meta information. Note that HID reports may be sent 44from the device ("Input Reports", i.e. input events), to the device 45("Output Reports" to e.g. change LEDs) or used for device configuration 46("Feature reports"). A device may support one or more HID reports. 47 48The HID subsystem is in charge of parsing the HID report descriptors, 49and converts HID events into normal input device interfaces (see 50Documentation/hid/hid-transport.rst). Devices may misbehave because the 51HID report descriptor provided by the device is wrong, or because it 52needs to be dealt with in a special way, or because some special 53device or interaction mode is not handled by the default code. 54 55The format of HID report descriptors is described by two documents, 56available from the `USB Implementers Forum <https://www.usb.org/>`_ 57`HID web page <https://www.usb.org/hid>`_ address: 58 59 * the `HID USB Device Class Definition 60 <https://www.usb.org/document-library/device-class-definition-hid-111>`_ (HID Spec from now on) 61 * the `HID Usage Tables <https://usb.org/document-library/hid-usage-tables-14>`_ (HUT from now on) 62 63The HID subsystem can deal with different transport drivers 64(USB, I2C, Bluetooth, etc.). See Documentation/hid/hid-transport.rst. 65 66Parsing HID report descriptors 67============================== 68 69The current list of HID devices can be found at ``/sys/bus/hid/devices/``. 70For each device, say ``/sys/bus/hid/devices/0003\:093A\:2510.0002/``, 71one can read the corresponding report descriptor:: 72 73 $ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor 74 00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).| 75 00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....| 76 00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...| 77 00000030 81 06 c0 c0 |....| 78 00000034 79 80Optional: the HID report descriptor can be read also by 81directly accessing the hidraw driver [#hidraw]_. 82 83The basic structure of HID report descriptors is defined in the HID 84spec, while HUT "defines constants that can be interpreted by an 85application to identify the purpose and meaning of a data field in a 86HID report". Each entry is defined by at least two bytes, where the 87first one defines what type of value is following and is described in 88the HID spec, while the second one carries the actual value and is 89described in the HUT. 90 91HID report descriptors can, in principle, be painstakingly parsed by 92hand, byte by byte. 93 94A short introduction on how to do this is sketched in 95Documentation/hid/hidreport-parsing.rst; you only need to understand it 96if you need to patch HID report descriptors. 97 98In practice you should not parse HID report descriptors by hand; rather, 99you should use an existing parser. Among all the available ones 100 101 * the online `USB Descriptor and Request Parser 102 <http://eleccelerator.com/usbdescreqparser/>`_; 103 * `hidrdd <https://github.com/abend0c1/hidrdd>`_, 104 that provides very detailed and somewhat verbose descriptions 105 (verbosity can be useful if you are not familiar with HID report 106 descriptors); 107 * `hid-tools <https://gitlab.freedesktop.org/libevdev/hid-tools>`_, 108 a complete utility set that allows, among other things, 109 to record and replay the raw HID reports and to debug 110 and replay HID devices. 111 It is being actively developed by the Linux HID subsystem maintainers. 112 113Parsing the mouse HID report descriptor with `hid-tools 114<https://gitlab.freedesktop.org/libevdev/hid-tools>`_ leads to 115(explanations interposed):: 116 117 $ ./hid-decode /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor 118 # device 0:0 119 # 0x05, 0x01, // Usage Page (Generic Desktop) 0 120 # 0x09, 0x02, // Usage (Mouse) 2 121 # 0xa1, 0x01, // Collection (Application) 4 122 # 0x09, 0x01, // Usage (Pointer) 6 123 # 0xa1, 0x00, // Collection (Physical) 8 124 # 0x05, 0x09, // Usage Page (Button) 10 125 126what follows is a button :: 127 128 # 0x19, 0x01, // Usage Minimum (1) 12 129 # 0x29, 0x03, // Usage Maximum (3) 14 130 131first button is button number 1, last button is button number 3 :: 132 133 # 0x15, 0x00, // Logical Minimum (0) 16 134 # 0x25, 0x01, // Logical Maximum (1) 18 135 136each button can send values from 0 up to including 1 137(i.e. they are binary buttons) :: 138 139 # 0x75, 0x01, // Report Size (1) 20 140 141each button is sent as exactly one bit :: 142 143 # 0x95, 0x03, // Report Count (3) 22 144 145and there are three of those bits (matching the three buttons) :: 146 147 # 0x81, 0x02, // Input (Data,Var,Abs) 24 148 149it's actual Data (not constant padding), they represent 150a single variable (Var) and their values are Absolute (not relative); 151See HID spec Sec. 6.2.2.5 "Input, Output, and Feature Items" :: 152 153 # 0x75, 0x05, // Report Size (5) 26 154 155five additional padding bits, needed to reach a byte :: 156 157 # 0x95, 0x01, // Report Count (1) 28 158 159those five bits are repeated only once :: 160 161 # 0x81, 0x01, // Input (Cnst,Arr,Abs) 30 162 163and take Constant (Cnst) values i.e. they can be ignored. :: 164 165 # 0x05, 0x01, // Usage Page (Generic Desktop) 32 166 # 0x09, 0x30, // Usage (X) 34 167 # 0x09, 0x31, // Usage (Y) 36 168 # 0x09, 0x38, // Usage (Wheel) 38 169 170The mouse has also two physical positions (Usage (X), Usage (Y)) 171and a wheel (Usage (Wheel)) :: 172 173 # 0x15, 0x81, // Logical Minimum (-127) 40 174 # 0x25, 0x7f, // Logical Maximum (127) 42 175 176each of them can send values ranging from -127 up to including 127 :: 177 178 # 0x75, 0x08, // Report Size (8) 44 179 180which is represented by eight bits :: 181 182 # 0x95, 0x03, // Report Count (3) 46 183 184and there are three of those eight bits, matching X, Y and Wheel. :: 185 186 # 0x81, 0x06, // Input (Data,Var,Rel) 48 187 188This time the data values are Relative (Rel), i.e. they represent 189the change from the previously sent report (event) :: 190 191 # 0xc0, // End Collection 50 192 # 0xc0, // End Collection 51 193 # 194 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 c0 195 N: device 0:0 196 I: 3 0001 0001 197 198 199This Report Descriptor tells us that the mouse input will be 200transmitted using four bytes: the first one for the buttons (three 201bits used, five for padding), the last three for the mouse X, Y and 202wheel changes, respectively. 203 204Indeed, for any event, the mouse will send a *report* of four bytes. 205We can check the values sent by resorting e.g. to the `hid-recorder` 206tool, from `hid-tools <https://gitlab.freedesktop.org/libevdev/hid-tools>`_: 207The sequence of bytes sent by clicking and releasing button 1, then button 2, then button 3 is:: 208 209 $ sudo ./hid-recorder /dev/hidraw1 210 211 .... 212 output of hid-decode 213 .... 214 215 # Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0 216 E: 000000.000000 4 01 00 00 00 217 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 218 E: 000000.183949 4 00 00 00 00 219 # Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0 220 E: 000001.959698 4 02 00 00 00 221 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 222 E: 000002.103899 4 00 00 00 00 223 # Button: 0 0 1 | # | X: 0 | Y: 0 | Wheel: 0 224 E: 000004.855799 4 04 00 00 00 225 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 226 E: 000005.103864 4 00 00 00 00 227 228This example shows that when button 2 is clicked, 229the bytes ``02 00 00 00`` are sent, and the immediately subsequent 230event (``00 00 00 00``) is the release of button 2 (no buttons are 231pressed, remember that the data values are *absolute*). 232 233If instead one clicks and holds button 1, then clicks and holds button 2342, releases button 1, and finally releases button 2, the reports are:: 235 236 # Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0 237 E: 000044.175830 4 01 00 00 00 238 # Button: 1 1 0 | # | X: 0 | Y: 0 | Wheel: 0 239 E: 000045.975997 4 03 00 00 00 240 # Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0 241 E: 000047.407930 4 02 00 00 00 242 # Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0 243 E: 000049.199919 4 00 00 00 00 244 245where with ``03 00 00 00`` both buttons are pressed, and with the 246subsequent ``02 00 00 00`` button 1 is released while button 2 is still 247active. 248 249Output, Input and Feature Reports 250--------------------------------- 251 252HID devices can have Input Reports, like in the mouse example, Output 253Reports, and Feature Reports. "Output" means that the information is 254sent to the device. For example, a joystick with force feedback will 255have some output; the led of a keyboard would need an output as well. 256"Input" means that data come from the device. 257 258"Feature"s are not meant to be consumed by the end user and define 259configuration options for the device. They can be queried from the host; 260when declared as *Volatile* they should be changed by the host. 261 262 263Collections, Report IDs and Evdev events 264======================================== 265 266A single device can logically group data into different independent 267sets, called a *Collection*. Collections can be nested and there are 268different types of collections (see the HID spec 6.2.2.6 269"Collection, End Collection Items" for details). 270 271Different reports are identified by means of different *Report ID* 272fields, i.e. a number identifying the structure of the immediately 273following report. 274Whenever a Report ID is needed it is transmitted as the first byte of 275any report. A device with only one supported HID report (like the mouse 276example above) may omit the report ID. 277 278Consider the following HID report descriptor:: 279 280 05 01 09 02 A1 01 85 01 05 09 19 01 29 05 15 00 281 25 01 95 05 75 01 81 02 95 01 75 03 81 01 05 01 282 09 30 09 31 16 00 F8 26 FF 07 75 0C 95 02 81 06 283 09 38 15 80 25 7F 75 08 95 01 81 06 05 0C 0A 38 284 02 15 80 25 7F 75 08 95 01 81 06 C0 05 01 09 02 285 A1 01 85 02 05 09 19 01 29 05 15 00 25 01 95 05 286 75 01 81 02 95 01 75 03 81 01 05 01 09 30 09 31 287 16 00 F8 26 FF 07 75 0C 95 02 81 06 09 38 15 80 288 25 7F 75 08 95 01 81 06 05 0C 0A 38 02 15 80 25 289 7F 75 08 95 01 81 06 C0 05 01 09 07 A1 01 85 05 290 05 07 15 00 25 01 09 29 09 3E 09 4B 09 4E 09 E3 291 09 E8 09 E8 09 E8 75 01 95 08 81 02 95 00 81 01 292 C0 05 0C 09 01 A1 01 85 06 15 00 25 01 75 01 95 293 01 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 294 06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81 295 06 C0 05 0C 09 01 A1 01 85 03 09 05 15 00 26 FF 296 00 75 08 95 02 B1 02 C0 297 298After parsing it (try to parse it on your own using the suggested 299tools!) one can see that the device presents two ``Mouse`` Application 300Collections (with reports identified by Reports IDs 1 and 2, 301respectively), a ``Keypad`` Application Collection (whose report is 302identified by the Report ID 5) and two ``Consumer Controls`` Application 303Collections, (with Report IDs 6 and 3, respectively). Note, however, 304that a device can have different Report IDs for the same Application 305Collection. 306 307The data sent will begin with the Report ID byte, and will be followed 308by the corresponding information. For example, the data transmitted for 309the last consumer control:: 310 311 0x05, 0x0C, // Usage Page (Consumer) 312 0x09, 0x01, // Usage (Consumer Control) 313 0xA1, 0x01, // Collection (Application) 314 0x85, 0x03, // Report ID (3) 315 0x09, 0x05, // Usage (Headphone) 316 0x15, 0x00, // Logical Minimum (0) 317 0x26, 0xFF, 0x00, // Logical Maximum (255) 318 0x75, 0x08, // Report Size (8) 319 0x95, 0x02, // Report Count (2) 320 0xB1, 0x02, // Feature (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile) 321 0xC0, // End Collection 322 323will be of three bytes: the first for the Report ID (3), the next two 324for the headphone, with two (``Report Count (2)``) bytes 325(``Report Size (8)``), each ranging from 0 (``Logical Minimum (0)``) 326to 255 (``Logical Maximum (255)``). 327 328All the Input data sent by the device should be translated into 329corresponding Evdev events, so that the remaining part of the stack can 330know what is going on, e.g. the bit for the first button translates into 331the ``EV_KEY/BTN_LEFT`` evdev event and relative X movement translates 332into the ``EV_REL/REL_X`` evdev event". 333 334Events 335====== 336 337In Linux, one ``/dev/input/event*`` is created for each ``Application 338Collection``. Going back to the mouse example, and repeating the 339sequence where one clicks and holds button 1, then clicks and holds 340button 2, releases button 1, and finally releases button 2, one gets:: 341 342 $ sudo libinput record /dev/input/event1 343 # libinput record 344 version: 1 345 ndevices: 1 346 libinput: 347 version: "1.23.0" 348 git: "unknown" 349 system: 350 os: "opensuse-tumbleweed:20230619" 351 kernel: "6.3.7-1-default" 352 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:" 353 devices: 354 - node: /dev/input/event1 355 evdev: 356 # Name: PixArt HP USB Optical Mouse 357 # ID: bus 0x3 vendor 0x3f0 product 0x94a version 0x111 358 # Supported Events: 359 # Event type 0 (EV_SYN) 360 # Event type 1 (EV_KEY) 361 # Event code 272 (BTN_LEFT) 362 # Event code 273 (BTN_RIGHT) 363 # Event code 274 (BTN_MIDDLE) 364 # Event type 2 (EV_REL) 365 # Event code 0 (REL_X) 366 # Event code 1 (REL_Y) 367 # Event code 8 (REL_WHEEL) 368 # Event code 11 (REL_WHEEL_HI_RES) 369 # Event type 4 (EV_MSC) 370 # Event code 4 (MSC_SCAN) 371 # Properties: 372 name: "PixArt HP USB Optical Mouse" 373 id: [3, 1008, 2378, 273] 374 codes: 375 0: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] # EV_SYN 376 1: [272, 273, 274] # EV_KEY 377 2: [0, 1, 8, 11] # EV_REL 378 4: [4] # EV_MSC 379 properties: [] 380 hid: [ 381 0x05, 0x01, 0x09, 0x02, 0xa1, 0x01, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 0x19, 0x01, 0x29, 0x03, 382 0x15, 0x00, 0x25, 0x01, 0x95, 0x08, 0x75, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 383 0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75, 0x08, 0x95, 0x03, 0x81, 0x06, 0xc0, 0xc0 384 ] 385 udev: 386 properties: 387 - ID_INPUT=1 388 - ID_INPUT_MOUSE=1 389 - LIBINPUT_DEVICE_GROUP=3/3f0/94a:usb-0000:05:00.3-2 390 quirks: 391 events: 392 # Current time is 12:31:56 393 - evdev: 394 - [ 0, 0, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) 395 - [ 0, 0, 1, 272, 1] # EV_KEY / BTN_LEFT 1 396 - [ 0, 0, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +0ms 397 - evdev: 398 - [ 1, 207892, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) 399 - [ 1, 207892, 1, 273, 1] # EV_KEY / BTN_RIGHT 1 400 - [ 1, 207892, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1207ms 401 - evdev: 402 - [ 2, 367823, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) 403 - [ 2, 367823, 1, 272, 0] # EV_KEY / BTN_LEFT 0 404 - [ 2, 367823, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1160ms 405 # Current time is 12:32:00 406 - evdev: 407 - [ 3, 247617, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated) 408 - [ 3, 247617, 1, 273, 0] # EV_KEY / BTN_RIGHT 0 409 - [ 3, 247617, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +880ms 410 411Note: if ``libinput record`` is not available on your system try using 412``evemu-record``. 413 414When something does not work 415============================ 416 417There can be a number of reasons why a device does not behave 418correctly. For example 419 420* The HID report descriptor provided by the HID device may be wrong 421 because e.g. 422 423 * it does not follow the standard, so that the kernel 424 will not able to make sense of the HID report descriptor; 425 * the HID report descriptor *does not match* what is actually 426 sent by the device (this can be verified by reading the raw HID 427 data); 428* the HID report descriptor may need some "quirks" (see later on). 429 430As a consequence, a ``/dev/input/event*`` may not be created 431for each Application Collection, and/or the events 432there may not match what you would expect. 433 434 435Quirks 436------ 437 438There are some known peculiarities of HID devices that the kernel 439knows how to fix - these are called the HID quirks and a list of those 440is available in `include/linux/hid.h`. 441 442Should this be the case, it should be enough to add the required quirk 443in the kernel, for the HID device at hand. This can be done in the file 444`drivers/hid/hid-quirks.c`. How to do it should be relatively 445straightforward after looking into the file. 446 447The list of currently defined quirks, from `include/linux/hid.h`, is 448 449.. kernel-doc:: include/linux/hid.h 450 :doc: HID quirks 451 452Quirks for USB devices can be specified while loading the usbhid module, 453see ``modinfo usbhid``, although the proper fix should go into 454hid-quirks.c and **be submitted upstream**. 455See Documentation/process/submitting-patches.rst for guidelines on how 456to submit a patch. Quirks for other busses need to go into hid-quirks.c. 457 458Fixing HID report descriptors 459----------------------------- 460 461Should you need to patch HID report descriptors the easiest way is to 462resort to eBPF, as described in Documentation/hid/hid-bpf.rst. 463 464Basically, you can change any byte of the original HID report 465descriptor. The examples in samples/hid should be a good starting point 466for your code, see e.g. `samples/hid/hid_mouse.bpf.c`:: 467 468 SEC("fmod_ret/hid_bpf_rdesc_fixup") 469 int BPF_PROG(hid_rdesc_fixup, struct hid_bpf_ctx *hctx) 470 { 471 .... 472 data[39] = 0x31; 473 data[41] = 0x30; 474 return 0; 475 } 476 477Of course this can be also done within the kernel source code, see e.g. 478`drivers/hid/hid-aureal.c` or `drivers/hid/hid-samsung.c` for a slightly 479more complex file. 480 481Check Documentation/hid/hidreport-parsing.rst if you need any help 482navigating the HID manuals and understanding the exact meaning of 483the HID report descriptor hex numbers. 484 485Whatever solution you come up with, please remember to **submit the 486fix to the HID maintainers**, so that it can be directly integrated in 487the kernel and that particular HID device will start working for 488everyone else. See Documentation/process/submitting-patches.rst for 489guidelines on how to do this. 490 491 492Modifying the transmitted data on the fly 493----------------------------------------- 494 495Using eBPF it is also possible to modify the data exchanged with the 496device. See again the examples in `samples/hid`. 497 498Again, **please post your fix**, so that it can be integrated in the 499kernel! 500 501Writing a specialized driver 502---------------------------- 503 504This should really be your last resort. 505 506 507.. rubric:: Footnotes 508 509.. [#hidraw] read hidraw: see Documentation/hid/hidraw.rst and 510 file `samples/hidraw/hid-example.c` for an example. 511 The output of ``hid-example`` would be, for the same mouse:: 512 513 $ sudo ./hid-example 514 Report Descriptor Size: 52 515 Report Descriptor: 516 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 c0 517 518 Raw Name: PixArt USB Optical Mouse 519 Raw Phys: usb-0000:05:00.4-2.3/input0 520 Raw Info: 521 bustype: 3 (USB) 522 vendor: 0x093a 523 product: 0x2510 524 ... 525