Documentation/hid/hidintro.rst

4 Introduction to HID report descriptors
7 This chapter is meant to give a broad overview of what HID report
9 with HID devices that are not working well with Linux.
24 HID stands for Human Interface Device, and can be whatever device you
28 Many HID devices work out the box, even if their hardware is different.
35 This is because modern HID devices do advertise their capabilities
36 through the *HID report descriptor*, a fixed set of bytes describing
37 exactly what *HID reports* may be sent between the device and the host
39 a HID Report Descriptor may specify that "in a report with ID 3 the
42 The HID report itself then merely carries the actual data values
43 without any extra meta information. Note that HID reports may be sent
46 ("Feature reports"). A device may support one or more HID reports.
48 The HID subsystem is in charge of parsing the HID report descriptors,
49 and converts HID events into normal input device interfaces (see
51 HID report descriptor provided by the device is wrong, or because it
55 The format of HID report descriptors is described by two documents,
57 `HID web page <https://www.usb.org/hid>`_ address:
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)
63 The HID subsystem can deal with different transport drivers
66 Parsing HID report descriptors
69 The current list of HID devices can be found at ``/sys/bus/hid/devices/``.
80 Optional: the HID report descriptor can be read also by
83 The basic structure of HID report descriptors is defined in the HID
86 HID report". Each entry is defined by at least two bytes, where the
88 the HID spec, while the second one carries the actual value and is
91 HID report descriptors can, in principle, be painstakingly parsed by
96 if you need to patch HID report descriptors.
98 In practice you should not parse HID report descriptors by hand; rather,
105     (verbosity can be useful if you are not familiar with HID report
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.
113 Parsing the mouse HID report descriptor with `hid-tools
151 See HID spec Sec. 6.2.2.5 "Input, Output, and Feature Items" ::
252 HID devices can have Input Reports, like in the mouse example, Output
268 different types of collections (see the HID spec 6.2.2.6
275 any report. A device with only one supported HID report (like the mouse
278 Consider the following HID report descriptor::
420 * The HID report descriptor provided by the HID device may be wrong
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
428 * the HID report descriptor may need some "quirks" (see later on).
438 There are some known peculiarities of HID devices that the kernel
439 knows how to fix - these are called the HID quirks and a list of those
443 in the kernel, for the HID device at hand. This can be done in the file
450    :doc: HID quirks
458 Fixing HID report descriptors
461 Should you need to patch HID report descriptors the easiest way is to
464 Basically, you can change any byte of the original HID report
482 navigating the HID manuals and understanding the exact meaning of
483 the HID report descriptor hex numbers.
486 fix to the HID maintainers**, so that it can be directly integrated in
487 the kernel and that particular HID device will start working for