Lines Matching full:hid
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
50 Documentation/hid/hid-transport.rst). Devices may misbehave because the
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
64 (USB, I2C, Bluetooth, etc.). See Documentation/hid/hid-transport.rst.
66 Parsing HID report descriptors
69 The current list of HID devices can be found at ``/sys/bus/hid/devices/``.
70 For each device, say ``/sys/bus/hid/devices/0003\:093A\:2510.0002/``,
73 $ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor
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
95 Documentation/hid/hidreport-parsing.rst; you only need to understand it
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
107 * `hid-tools <https://gitlab.freedesktop.org/libevdev/hid-tools>`_,
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
114 <https://gitlab.freedesktop.org/libevdev/hid-tools>`_ leads to
117 $ ./hid-decode /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor
151 See HID spec Sec. 6.2.2.5 "Input, Output, and Feature Items" ::
205 We can check the values sent by resorting e.g. to the `hid-recorder`
206 tool, from `hid-tools <https://gitlab.freedesktop.org/libevdev/hid-tools>`_:
209 $ sudo ./hid-recorder /dev/hidraw1
212 output of hid-decode
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::
380 hid: [
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
440 is available in `include/linux/hid.h`.
443 in 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
447 The list of currently defined quirks, from `include/linux/hid.h`, is
449 .. kernel-doc:: include/linux/hid.h
450 :doc: HID quirks
454 hid-quirks.c and **be submitted upstream**.
456 to submit a patch. Quirks for other busses need to go into hid-quirks.c.
458 Fixing HID report descriptors
461 Should you need to patch HID report descriptors the easiest way is to
462 resort to eBPF, as described in Documentation/hid/hid-bpf.rst.
464 Basically, you can change any byte of the original HID report
465 descriptor. The examples in samples/hid should be a good starting point
466 for your code, see e.g. `samples/hid/hid_mouse.bpf.c`::
478 `drivers/hid/hid-aureal.c` or `drivers/hid/hid-samsung.c` for a slightly
481 Check Documentation/hid/hidreport-parsing.rst if you need any help
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
496 device. See again the examples in `samples/hid`.
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::
513 $ sudo ./hid-example