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
40 bits from 8 to 15 is the delta x coordinate of a mouse".
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
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...|
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 …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…
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
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
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
290   05 07 15 00 25 01 09 29 09 3E 09 4B 09 4E 09 E3
292   C0 05 0C 09 01 A1 01 85 06 15 00 25 01 75 01 95
295   06 C0 05 0C 09 01 A1 01 85 03 09 05 15 00 26 FF
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
375   	0: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] # EV_SYN
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