Documentation/hid/hidintro.rst

7 This chapter is meant to give a broad overview of what HID report
8 descriptors are, and of how a casual (non-kernel) programmer can deal
25 are using to interact with a computer, be it a mouse, a touchpad, a
26 tablet, a microphone.
29 For example, mice can have any number of buttons; they may have a
36 through the *HID report descriptor*, a fixed set of bytes describing
39 a HID Report Descriptor may specify that "in a report with ID 3 the
40 bits from 8 to 15 is the delta x coordinate of a mouse".
46 ("Feature reports"). A device may support one or more HID reports.
52 needs to be dealt with in a special way, or because some special
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
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...|
85 application to identify the purpose and meaning of a data field in a
94 A short introduction on how to do this is sketched in
108     a complete utility set that allows, among other things,
117     $ ./hid-decode /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor
126 what follows is a button ::
150 a single variable (Var) and their values are Absolute (not relative);
155 five additional padding bits, needed to reach a byte ::
171 and a wheel (Usage (Wheel)) ::
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…
204 Indeed, for any event, the mouse will send a *report* of four bytes.
216   E: 000000.000000 4 01 00 00 00
237   E: 000044.175830 4 01 00 00 00
254 sent to the device. For example, a joystick with force feedback will
255 have some output; the led of a keyboard would need an output as well.
266 A single device can logically group data into different independent
267 sets, called a *Collection*. Collections can be nested and there are
272 fields, i.e. a number identifying the structure of the immediately
274 Whenever a Report ID is needed it is transmitted as the first byte of
275 any report. A device with only one supported HID report (like the mouse
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
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
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
295   06 C0 05 0C 09 01 A1 01 85 03 09 05 15 00 26 FF
301 respectively), a ``Keypad`` Application Collection (whose report is
304 that a device can have different Report IDs for the same Application
389       - LIBINPUT_DEVICE_GROUP=3/3f0/94a:usb-0000:05:00.3-2
417 There can be a number of reasons why a device does not behave
430 As a consequence, a ``/dev/input/event*`` may not be created
439 knows how to fix - these are called the HID quirks and a list of those
456 to submit a patch. Quirks for other busses need to go into hid-quirks.c.
465 descriptor. The examples in samples/hid should be a good starting point
478 `drivers/hid/hid-aureal.c` or `drivers/hid/hid-samsung.c` for a slightly
501 Writing a specialized driver