Documentation/hid/hidintro.rst

1 .. SPDX-License-Identifier: GPL-2.0
8 descriptors are, and of how a casual (non-kernel) programmer can deal
18    hidreport-parsing
44 from the device ("Input Reports", i.e. input events), to the device
49 and converts HID events into normal input device interfaces (see
50 Documentation/hid/hid-transport.rst). Devices may misbehave because the
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)
64 (USB, I2C, Bluetooth, etc.). See Documentation/hid/hid-transport.rst.
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  |..............).|
95 Documentation/hid/hidreport-parsing.rst; you only need to understand it
107   * `hid-tools <https://gitlab.freedesktop.org/libevdev/hid-tools>`_,
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
147     # 0x81, 0x02, 		     //	Input (Data,Var,Abs)		   24
151 See HID spec Sec. 6.2.2.5 "Input, Output, and Feature Items" ::
161     # 0x81, 0x01, 		     //	Input (Cnst,Arr,Abs)		   30
173     # 0x15, 0x81, 		     //	Logical Minimum (-127)  	   40
176 each of them can send values ranging from -127 up to including 127 ::
186     # 0x81, 0x06,		     // Input (Data,Var,Rel)  	    	   48
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…
199 This Report Descriptor tells us that the mouse input will be
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
249 Output, Input and Feature Reports
250 ---------------------------------
252 HID devices can have Input Reports, like in the mouse example, Output
256 "Input" means that data come from the device.
280   05 01 09 02 A1 01 85 01 05 09 19 01 29 05 15 00
285   A1 01 85 02 05 09 19 01 29 05 15 00 25 01 95 05
320 …02,        //   Feature (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
328 All the Input data sent by the device should be translated into
337 In Linux, one ``/dev/input/event*`` is created for each ``Application
342   $ sudo libinput record /dev/input/event1
350     os: "opensuse-tumbleweed:20230619"
351     kernel: "6.3.7-1-default"
354   - node: /dev/input/event1
387       - ID_INPUT=1
388       - ID_INPUT_MOUSE=1
389       - LIBINPUT_DEVICE_GROUP=3/3f0/94a:usb-0000:05:00.3-2
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
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
412 ``evemu-record``.
430 As a consequence, a ``/dev/input/event*`` may not be created
436 ------
439 knows how to fix - these are called the HID quirks and a list of those
444 `drivers/hid/hid-quirks.c`. How to do it should be relatively
449 .. kernel-doc:: include/linux/hid.h
454 hid-quirks.c and **be submitted upstream**.
455 See Documentation/process/submitting-patches.rst for guidelines on how
456 to submit a patch. Quirks for other busses need to go into hid-quirks.c.
459 -----------------------------
462 resort to eBPF, as described in Documentation/hid/hid-bpf.rst.
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
488 everyone else. See Documentation/process/submitting-patches.rst for
493 -----------------------------------------
502 ----------------------------
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
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 …
519     Raw Phys: usb-0000:05:00.4-2.3/input0