mirror of
https://github.com/torvalds/linux.git
synced 2024-11-10 06:01:57 +00:00
HID: Add introduction about HID for non-kernel programmers
Add an introduction about HID meant for the casual programmer that is trying either to fix his device or to understand what is going wrong. Signed-off-by: Marco Morandini <marco.morandini@polimi.it> Co-authored-by: Peter Hutterer <peter.hutterer@who-t.net> Signed-off-by: Jiri Kosina <jkosina@suse.cz>
This commit is contained in:
Marco Morandini
Jiri Kosina
parent
1d7546042f
commit
2326dee41c
524
Documentation/hid/hidintro.rst
Normal file
524
Documentation/hid/hidintro.rst
Normal file
@ -0,0 +1,524 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
======================================
|
||||
Introduction to HID report descriptors
|
||||
======================================
|
||||
|
||||
This chapter is meant to give a broad overview of what HID report
|
||||
descriptors are, and of how a casual (non-kernel) programmer can deal
|
||||
with HID devices that are not working well with Linux.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 2
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
hidreport-parsing
|
||||
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
HID stands for Human Interface Device, and can be whatever device you
|
||||
are using to interact with a computer, be it a mouse, a touchpad, a
|
||||
tablet, a microphone.
|
||||
|
||||
Many HID devices work out the box, even if their hardware is different.
|
||||
For example, mice can have any number of buttons; they may have a
|
||||
wheel; movement sensitivity differs between different models, and so
|
||||
on. Nonetheless, most of the time everything just works, without the
|
||||
need to have specialized code in the kernel for every mouse model
|
||||
developed since 1970.
|
||||
|
||||
This is because modern HID devices do advertise their capabilities
|
||||
through the *HID report descriptor*, a fixed set of bytes describing
|
||||
exactly what *HID reports* may be sent between the device and the host
|
||||
and the meaning of each individual bit in those reports. For example,
|
||||
a HID Report Descriptor may specify that "in a report with ID 3 the
|
||||
bits from 8 to 15 is the delta x coordinate of a mouse".
|
||||
|
||||
The HID report itself then merely carries the actual data values
|
||||
without any extra meta information. Note that HID reports may be sent
|
||||
from the device ("Input Reports", i.e. input events), to the device
|
||||
("Output Reports" to e.g. change LEDs) or used for device configuration
|
||||
("Feature reports"). A device may support one or more HID reports.
|
||||
|
||||
The HID subsystem is in charge of parsing the HID report descriptors,
|
||||
and converts HID events into normal input device interfaces (see
|
||||
Documentation/hid/hid-transport.rst). Devices may misbehave because the
|
||||
HID report descriptor provided by the device is wrong, or because it
|
||||
needs to be dealt with in a special way, or because some special
|
||||
device or interaction mode is not handled by the default code.
|
||||
|
||||
The format of HID report descriptors is described by two documents,
|
||||
available from the `USB Implementers Forum <https://www.usb.org/>`_
|
||||
`HID web page <https://www.usb.org/hid>`_ address:
|
||||
|
||||
* the `HID USB Device Class Definition
|
||||
<https://www.usb.org/document-library/device-class-definition-hid-111>`_ (HID Spec from now on)
|
||||
* the `HID Usage Tables <https://usb.org/document-library/hid-usage-tables-14>`_ (HUT from now on)
|
||||
|
||||
The HID subsystem can deal with different transport drivers
|
||||
(USB, I2C, Bluetooth, etc.). See Documentation/hid/hid-transport.rst.
|
||||
|
||||
Parsing HID report descriptors
|
||||
==============================
|
||||
|
||||
The current list of HID devices can be found at ``/sys/bus/hid/devices/``.
|
||||
For each device, say ``/sys/bus/hid/devices/0003\:093A\:2510.0002/``,
|
||||
one can read the corresponding report descriptor::
|
||||
|
||||
$ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor
|
||||
00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).|
|
||||
00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....|
|
||||
00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...|
|
||||
00000030 81 06 c0 c0 |....|
|
||||
00000034
|
||||
|
||||
Optional: the HID report descriptor can be read also by
|
||||
directly accessing the hidraw driver [#hidraw]_.
|
||||
|
||||
The basic structure of HID report descriptors is defined in the HID
|
||||
spec, while HUT "defines constants that can be interpreted by an
|
||||
application to identify the purpose and meaning of a data field in a
|
||||
HID report". Each entry is defined by at least two bytes, where the
|
||||
first one defines what type of value is following and is described in
|
||||
the HID spec, while the second one carries the actual value and is
|
||||
described in the HUT.
|
||||
|
||||
HID report descriptors can, in principle, be painstakingly parsed by
|
||||
hand, byte by byte.
|
||||
|
||||
A short introduction on how to do this is sketched in
|
||||
Documentation/hid/hidreport-parsing.rst; you only need to understand it
|
||||
if you need to patch HID report descriptors.
|
||||
|
||||
In practice you should not parse HID report descriptors by hand; rather,
|
||||
you should use an existing parser. Among all the available ones
|
||||
|
||||
* the online `USB Descriptor and Request Parser
|
||||
<http://eleccelerator.com/usbdescreqparser/>`_;
|
||||
* `hidrdd <https://github.com/abend0c1/hidrdd>`_,
|
||||
that provides very detailed and somewhat verbose descriptions
|
||||
(verbosity can be useful if you are not familiar with HID report
|
||||
descriptors);
|
||||
* `hid-tools <https://gitlab.freedesktop.org/libevdev/hid-tools>`_,
|
||||
a complete utility set that allows, among other things,
|
||||
to record and replay the raw HID reports and to debug
|
||||
and replay HID devices.
|
||||
It is being actively developed by the Linux HID subsystem maintainers.
|
||||
|
||||
Parsing the mouse HID report descriptor with `hid-tools
|
||||
<https://gitlab.freedesktop.org/libevdev/hid-tools>`_ leads to
|
||||
(explanations interposed)::
|
||||
|
||||
$ ./hid-decode /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor
|
||||
# device 0:0
|
||||
# 0x05, 0x01, // Usage Page (Generic Desktop) 0
|
||||
# 0x09, 0x02, // Usage (Mouse) 2
|
||||
# 0xa1, 0x01, // Collection (Application) 4
|
||||
# 0x09, 0x01, // Usage (Pointer) 6
|
||||
# 0xa1, 0x00, // Collection (Physical) 8
|
||||
# 0x05, 0x09, // Usage Page (Button) 10
|
||||
|
||||
what follows is a button ::
|
||||
|
||||
# 0x19, 0x01, // Usage Minimum (1) 12
|
||||
# 0x29, 0x03, // Usage Maximum (3) 14
|
||||
|
||||
first button is button number 1, last button is button number 3 ::
|
||||
|
||||
# 0x15, 0x00, // Logical Minimum (0) 16
|
||||
# 0x25, 0x01, // Logical Maximum (1) 18
|
||||
|
||||
each button can send values from 0 up to including 1
|
||||
(i.e. they are binary buttons) ::
|
||||
|
||||
# 0x75, 0x01, // Report Size (1) 20
|
||||
|
||||
each button is sent as exactly one bit ::
|
||||
|
||||
# 0x95, 0x03, // Report Count (3) 22
|
||||
|
||||
and there are three of those bits (matching the three buttons) ::
|
||||
|
||||
# 0x81, 0x02, // Input (Data,Var,Abs) 24
|
||||
|
||||
it's actual Data (not constant padding), they represent
|
||||
a single variable (Var) and their values are Absolute (not relative);
|
||||
See HID spec Sec. 6.2.2.5 "Input, Output, and Feature Items" ::
|
||||
|
||||
# 0x75, 0x05, // Report Size (5) 26
|
||||
|
||||
five additional padding bits, needed to reach a byte ::
|
||||
|
||||
# 0x95, 0x01, // Report Count (1) 28
|
||||
|
||||
those five bits are repeated only once ::
|
||||
|
||||
# 0x81, 0x01, // Input (Cnst,Arr,Abs) 30
|
||||
|
||||
and take Constant (Cnst) values i.e. they can be ignored. ::
|
||||
|
||||
# 0x05, 0x01, // Usage Page (Generic Desktop) 32
|
||||
# 0x09, 0x30, // Usage (X) 34
|
||||
# 0x09, 0x31, // Usage (Y) 36
|
||||
# 0x09, 0x38, // Usage (Wheel) 38
|
||||
|
||||
The mouse has also two physical positions (Usage (X), Usage (Y))
|
||||
and a wheel (Usage (Wheel)) ::
|
||||
|
||||
# 0x15, 0x81, // Logical Minimum (-127) 40
|
||||
# 0x25, 0x7f, // Logical Maximum (127) 42
|
||||
|
||||
each of them can send values ranging from -127 up to including 127 ::
|
||||
|
||||
# 0x75, 0x08, // Report Size (8) 44
|
||||
|
||||
which is represented by eight bits ::
|
||||
|
||||
# 0x95, 0x03, // Report Count (3) 46
|
||||
|
||||
and there are three of those eight bits, matching X, Y and Wheel. ::
|
||||
|
||||
# 0x81, 0x06, // Input (Data,Var,Rel) 48
|
||||
|
||||
This time the data values are Relative (Rel), i.e. they represent
|
||||
the change from the previously sent report (event) ::
|
||||
|
||||
# 0xc0, // End Collection 50
|
||||
# 0xc0, // End Collection 51
|
||||
#
|
||||
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 01 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 81 06 c0 c0
|
||||
N: device 0:0
|
||||
I: 3 0001 0001
|
||||
|
||||
|
||||
This Report Descriptor tells us that the mouse input will be
|
||||
transmitted using four bytes: the first one for the buttons (three
|
||||
bits used, five for padding), the last three for the mouse X, Y and
|
||||
wheel changes, respectively.
|
||||
|
||||
Indeed, for any event, the mouse will send a *report* of four bytes.
|
||||
We can check the values sent by resorting e.g. to the `hid-recorder`
|
||||
tool, from `hid-tools <https://gitlab.freedesktop.org/libevdev/hid-tools>`_:
|
||||
The sequence of bytes sent by clicking and releasing button 1, then button 2, then button 3 is::
|
||||
|
||||
$ sudo ./hid-recorder /dev/hidraw1
|
||||
|
||||
....
|
||||
output of hid-decode
|
||||
....
|
||||
|
||||
# Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0
|
||||
E: 000000.000000 4 01 00 00 00
|
||||
# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0
|
||||
E: 000000.183949 4 00 00 00 00
|
||||
# Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0
|
||||
E: 000001.959698 4 02 00 00 00
|
||||
# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0
|
||||
E: 000002.103899 4 00 00 00 00
|
||||
# Button: 0 0 1 | # | X: 0 | Y: 0 | Wheel: 0
|
||||
E: 000004.855799 4 04 00 00 00
|
||||
# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0
|
||||
E: 000005.103864 4 00 00 00 00
|
||||
|
||||
This example shows that when button 2 is clicked,
|
||||
the bytes ``02 00 00 00`` are sent, and the immediately subsequent
|
||||
event (``00 00 00 00``) is the release of button 2 (no buttons are
|
||||
pressed, remember that the data values are *absolute*).
|
||||
|
||||
If instead one clicks and holds button 1, then clicks and holds button
|
||||
2, releases button 1, and finally releases button 2, the reports are::
|
||||
|
||||
# Button: 1 0 0 | # | X: 0 | Y: 0 | Wheel: 0
|
||||
E: 000044.175830 4 01 00 00 00
|
||||
# Button: 1 1 0 | # | X: 0 | Y: 0 | Wheel: 0
|
||||
E: 000045.975997 4 03 00 00 00
|
||||
# Button: 0 1 0 | # | X: 0 | Y: 0 | Wheel: 0
|
||||
E: 000047.407930 4 02 00 00 00
|
||||
# Button: 0 0 0 | # | X: 0 | Y: 0 | Wheel: 0
|
||||
E: 000049.199919 4 00 00 00 00
|
||||
|
||||
where with ``03 00 00 00`` both buttons are pressed, and with the
|
||||
subsequent ``02 00 00 00`` button 1 is released while button 2 is still
|
||||
active.
|
||||
|
||||
Output, Input and Feature Reports
|
||||
---------------------------------
|
||||
|
||||
HID devices can have Input Reports, like in the mouse example, Output
|
||||
Reports, and Feature Reports. "Output" means that the information is
|
||||
sent to the device. For example, a joystick with force feedback will
|
||||
have some output; the led of a keyboard would need an output as well.
|
||||
"Input" means that data come from the device.
|
||||
|
||||
"Feature"s are not meant to be consumed by the end user and define
|
||||
configuration options for the device. They can be queried from the host;
|
||||
when declared as *Volatile* they should be changed by the host.
|
||||
|
||||
|
||||
Collections, Report IDs and Evdev events
|
||||
========================================
|
||||
|
||||
A single device can logically group data into different independent
|
||||
sets, called a *Collection*. Collections can be nested and there are
|
||||
different types of collections (see the HID spec 6.2.2.6
|
||||
"Collection, End Collection Items" for details).
|
||||
|
||||
Different reports are identified by means of different *Report ID*
|
||||
fields, i.e. a number identifying the structure of the immediately
|
||||
following report.
|
||||
Whenever a Report ID is needed it is transmitted as the first byte of
|
||||
any report. A device with only one supported HID report (like the mouse
|
||||
example above) may omit the report ID.
|
||||
|
||||
Consider the following HID report descriptor::
|
||||
|
||||
05 01 09 02 A1 01 85 01 05 09 19 01 29 05 15 00
|
||||
25 01 95 05 75 01 81 02 95 01 75 03 81 01 05 01
|
||||
09 30 09 31 16 00 F8 26 FF 07 75 0C 95 02 81 06
|
||||
09 38 15 80 25 7F 75 08 95 01 81 06 05 0C 0A 38
|
||||
02 15 80 25 7F 75 08 95 01 81 06 C0 05 01 09 02
|
||||
A1 01 85 02 05 09 19 01 29 05 15 00 25 01 95 05
|
||||
75 01 81 02 95 01 75 03 81 01 05 01 09 30 09 31
|
||||
16 00 F8 26 FF 07 75 0C 95 02 81 06 09 38 15 80
|
||||
25 7F 75 08 95 01 81 06 05 0C 0A 38 02 15 80 25
|
||||
7F 75 08 95 01 81 06 C0 05 01 09 07 A1 01 85 05
|
||||
05 07 15 00 25 01 09 29 09 3E 09 4B 09 4E 09 E3
|
||||
09 E8 09 E8 09 E8 75 01 95 08 81 02 95 00 81 01
|
||||
C0 05 0C 09 01 A1 01 85 06 15 00 25 01 75 01 95
|
||||
01 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81
|
||||
06 09 3F 81 06 09 3F 81 06 09 3F 81 06 09 3F 81
|
||||
06 C0 05 0C 09 01 A1 01 85 03 09 05 15 00 26 FF
|
||||
00 75 08 95 02 B1 02 C0
|
||||
|
||||
After parsing it (try to parse it on your own using the suggested
|
||||
tools!) one can see that the device presents two ``Mouse`` Application
|
||||
Collections (with reports identified by Reports IDs 1 and 2,
|
||||
respectively), a ``Keypad`` Application Collection (whose report is
|
||||
identified by the Report ID 5) and two ``Consumer Controls`` Application
|
||||
Collections, (with Report IDs 6 and 3, respectively). Note, however,
|
||||
that a device can have different Report IDs for the same Application
|
||||
Collection.
|
||||
|
||||
The data sent will begin with the Report ID byte, and will be followed
|
||||
by the corresponding information. For example, the data transmitted for
|
||||
the last consumer control::
|
||||
|
||||
0x05, 0x0C, // Usage Page (Consumer)
|
||||
0x09, 0x01, // Usage (Consumer Control)
|
||||
0xA1, 0x01, // Collection (Application)
|
||||
0x85, 0x03, // Report ID (3)
|
||||
0x09, 0x05, // Usage (Headphone)
|
||||
0x15, 0x00, // Logical Minimum (0)
|
||||
0x26, 0xFF, 0x00, // Logical Maximum (255)
|
||||
0x75, 0x08, // Report Size (8)
|
||||
0x95, 0x02, // Report Count (2)
|
||||
0xB1, 0x02, // Feature (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
|
||||
0xC0, // End Collection
|
||||
|
||||
will be of three bytes: the first for the Report ID (3), the next two
|
||||
for the headphone, with two (``Report Count (2)``) bytes
|
||||
(``Report Size (8)``), each ranging from 0 (``Logical Minimum (0)``)
|
||||
to 255 (``Logical Maximum (255)``).
|
||||
|
||||
All the Input data sent by the device should be translated into
|
||||
corresponding Evdev events, so that the remaining part of the stack can
|
||||
know what is going on, e.g. the bit for the first button translates into
|
||||
the ``EV_KEY/BTN_LEFT`` evdev event and relative X movement translates
|
||||
into the ``EV_REL/REL_X`` evdev event".
|
||||
|
||||
Events
|
||||
======
|
||||
|
||||
In Linux, one ``/dev/input/event*`` is created for each ``Application
|
||||
Collection``. Going back to the mouse example, and repeating the
|
||||
sequence where one clicks and holds button 1, then clicks and holds
|
||||
button 2, releases button 1, and finally releases button 2, one gets::
|
||||
|
||||
$ sudo libinput record /dev/input/event1
|
||||
# libinput record
|
||||
version: 1
|
||||
ndevices: 1
|
||||
libinput:
|
||||
version: "1.23.0"
|
||||
git: "unknown"
|
||||
system:
|
||||
os: "opensuse-tumbleweed:20230619"
|
||||
kernel: "6.3.7-1-default"
|
||||
dmi: "dmi:bvnHP:bvrU77Ver.01.05.00:bd03/24/2022:br5.0:efr20.29:svnHP:pnHPEliteBook64514inchG9NotebookPC:pvr:rvnHP:rn89D2:rvrKBCVersion14.1D.00:cvnHP:ct10:cvr:sku5Y3J1EA#ABZ:"
|
||||
devices:
|
||||
- node: /dev/input/event1
|
||||
evdev:
|
||||
# Name: PixArt HP USB Optical Mouse
|
||||
# ID: bus 0x3 vendor 0x3f0 product 0x94a version 0x111
|
||||
# Supported Events:
|
||||
# Event type 0 (EV_SYN)
|
||||
# Event type 1 (EV_KEY)
|
||||
# Event code 272 (BTN_LEFT)
|
||||
# Event code 273 (BTN_RIGHT)
|
||||
# Event code 274 (BTN_MIDDLE)
|
||||
# Event type 2 (EV_REL)
|
||||
# Event code 0 (REL_X)
|
||||
# Event code 1 (REL_Y)
|
||||
# Event code 8 (REL_WHEEL)
|
||||
# Event code 11 (REL_WHEEL_HI_RES)
|
||||
# Event type 4 (EV_MSC)
|
||||
# Event code 4 (MSC_SCAN)
|
||||
# Properties:
|
||||
name: "PixArt HP USB Optical Mouse"
|
||||
id: [3, 1008, 2378, 273]
|
||||
codes:
|
||||
0: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] # EV_SYN
|
||||
1: [272, 273, 274] # EV_KEY
|
||||
2: [0, 1, 8, 11] # EV_REL
|
||||
4: [4] # EV_MSC
|
||||
properties: []
|
||||
hid: [
|
||||
0x05, 0x01, 0x09, 0x02, 0xa1, 0x01, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 0x19, 0x01, 0x29, 0x03,
|
||||
0x15, 0x00, 0x25, 0x01, 0x95, 0x08, 0x75, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31,
|
||||
0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75, 0x08, 0x95, 0x03, 0x81, 0x06, 0xc0, 0xc0
|
||||
]
|
||||
udev:
|
||||
properties:
|
||||
- ID_INPUT=1
|
||||
- ID_INPUT_MOUSE=1
|
||||
- LIBINPUT_DEVICE_GROUP=3/3f0/94a:usb-0000:05:00.3-2
|
||||
quirks:
|
||||
events:
|
||||
# Current time is 12:31:56
|
||||
- evdev:
|
||||
- [ 0, 0, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated)
|
||||
- [ 0, 0, 1, 272, 1] # EV_KEY / BTN_LEFT 1
|
||||
- [ 0, 0, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +0ms
|
||||
- evdev:
|
||||
- [ 1, 207892, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated)
|
||||
- [ 1, 207892, 1, 273, 1] # EV_KEY / BTN_RIGHT 1
|
||||
- [ 1, 207892, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1207ms
|
||||
- evdev:
|
||||
- [ 2, 367823, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated)
|
||||
- [ 2, 367823, 1, 272, 0] # EV_KEY / BTN_LEFT 0
|
||||
- [ 2, 367823, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +1160ms
|
||||
# Current time is 12:32:00
|
||||
- evdev:
|
||||
- [ 3, 247617, 4, 4, 30] # EV_MSC / MSC_SCAN 30 (obfuscated)
|
||||
- [ 3, 247617, 1, 273, 0] # EV_KEY / BTN_RIGHT 0
|
||||
- [ 3, 247617, 0, 0, 0] # ------------ SYN_REPORT (0) ---------- +880ms
|
||||
|
||||
Note: if ``libinput record`` is not available on your system try using
|
||||
``evemu-record``.
|
||||
|
||||
When something does not work
|
||||
============================
|
||||
|
||||
There can be a number of reasons why a device does not behave
|
||||
correctly. For example
|
||||
|
||||
* The HID report descriptor provided by the HID device may be wrong
|
||||
because e.g.
|
||||
|
||||
* it does not follow the standard, so that the kernel
|
||||
will not able to make sense of the HID report descriptor;
|
||||
* the HID report descriptor *does not match* what is actually
|
||||
sent by the device (this can be verified by reading the raw HID
|
||||
data);
|
||||
* the HID report descriptor may need some "quirks" (see later on).
|
||||
|
||||
As a consequence, a ``/dev/input/event*`` may not be created
|
||||
for each Application Collection, and/or the events
|
||||
there may not match what you would expect.
|
||||
|
||||
|
||||
Quirks
|
||||
------
|
||||
|
||||
There are some known peculiarities of HID devices that the kernel
|
||||
knows how to fix - these are called the HID quirks and a list of those
|
||||
is available in `include/linux/hid.h`.
|
||||
|
||||
Should this be the case, it should be enough to add the required quirk
|
||||
in the kernel, for the HID device at hand. This can be done in the file
|
||||
`drivers/hid/hid-quirks.c`. How to do it should be relatively
|
||||
straightforward after looking into the file.
|
||||
|
||||
The list of currently defined quirks, from `include/linux/hid.h`, is
|
||||
|
||||
.. kernel-doc:: include/linux/hid.h
|
||||
:doc: HID quirks
|
||||
|
||||
Quirks for USB devices can be specified while loading the usbhid module,
|
||||
see ``modinfo usbhid``, although the proper fix should go into
|
||||
hid-quirks.c and **be submitted upstream**.
|
||||
See Documentation/process/submitting-patches.rst for guidelines on how
|
||||
to submit a patch. Quirks for other busses need to go into hid-quirks.c.
|
||||
|
||||
Fixing HID report descriptors
|
||||
-----------------------------
|
||||
|
||||
Should you need to patch HID report descriptors the easiest way is to
|
||||
resort to eBPF, as described in Documentation/hid/hid-bpf.rst.
|
||||
|
||||
Basically, you can change any byte of the original HID report
|
||||
descriptor. The examples in samples/hid should be a good starting point
|
||||
for your code, see e.g. `samples/hid/hid_mouse.bpf.c`::
|
||||
|
||||
SEC("fmod_ret/hid_bpf_rdesc_fixup")
|
||||
int BPF_PROG(hid_rdesc_fixup, struct hid_bpf_ctx *hctx)
|
||||
{
|
||||
....
|
||||
data[39] = 0x31;
|
||||
data[41] = 0x30;
|
||||
return 0;
|
||||
}
|
||||
|
||||
Of course this can be also done within the kernel source code, see e.g.
|
||||
`drivers/hid/hid-aureal.c` or `drivers/hid/hid-samsung.c` for a slightly
|
||||
more complex file.
|
||||
|
||||
Check Documentation/hid/hidreport-parsing.rst if you need any help
|
||||
navigating the HID manuals and understanding the exact meaning of
|
||||
the HID report descriptor hex numbers.
|
||||
|
||||
Whatever solution you come up with, please remember to **submit the
|
||||
fix to the HID maintainers**, so that it can be directly integrated in
|
||||
the kernel and that particular HID device will start working for
|
||||
everyone else. See Documentation/process/submitting-patches.rst for
|
||||
guidelines on how to do this.
|
||||
|
||||
|
||||
Modifying the transmitted data on the fly
|
||||
-----------------------------------------
|
||||
|
||||
Using eBPF it is also possible to modify the data exchanged with the
|
||||
device. See again the examples in `samples/hid`.
|
||||
|
||||
Again, **please post your fix**, so that it can be integrated in the
|
||||
kernel!
|
||||
|
||||
Writing a specialized driver
|
||||
----------------------------
|
||||
|
||||
This should really be your last resort.
|
||||
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#hidraw] read hidraw: see Documentation/hid/hidraw.rst and
|
||||
file `samples/hidraw/hid-example.c` for an example.
|
||||
The output of ``hid-example`` would be, for the same mouse::
|
||||
|
||||
$ sudo ./hid-example
|
||||
Report Descriptor Size: 52
|
||||
Report Descriptor:
|
||||
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 81 25 7f 75 8 95 3 81 6 c0 c0
|
||||
|
||||
Raw Name: PixArt USB Optical Mouse
|
||||
Raw Phys: usb-0000:05:00.4-2.3/input0
|
||||
Raw Info:
|
||||
bustype: 3 (USB)
|
||||
vendor: 0x093a
|
||||
product: 0x2510
|
||||
...
|
||||
49
Documentation/hid/hidreport-parsing.rst
Normal file
49
Documentation/hid/hidreport-parsing.rst
Normal file
@ -0,0 +1,49 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
========================================
|
||||
Manual parsing of HID report descriptors
|
||||
========================================
|
||||
|
||||
Consider again the mouse HID report descriptor
|
||||
introduced in Documentation/hid/hidintro.rst::
|
||||
|
||||
$ hexdump -C /sys/bus/hid/devices/0003\:093A\:2510.0002/report_descriptor
|
||||
00000000 05 01 09 02 a1 01 09 01 a1 00 05 09 19 01 29 03 |..............).|
|
||||
00000010 15 00 25 01 75 01 95 03 81 02 75 05 95 01 81 01 |..%.u.....u.....|
|
||||
00000020 05 01 09 30 09 31 09 38 15 81 25 7f 75 08 95 03 |...0.1.8..%.u...|
|
||||
00000030 81 06 c0 c0 |....|
|
||||
00000034
|
||||
|
||||
and try to parse it by hand.
|
||||
|
||||
Start with the first number, 0x05: it carries 2 bits for the
|
||||
length of the item, 2 bits for the type of the item and 4 bits for the
|
||||
function::
|
||||
|
||||
+----------+
|
||||
| 00000101 |
|
||||
+----------+
|
||||
^^
|
||||
---- Length of data (see HID spec 6.2.2.2)
|
||||
^^
|
||||
------ Type of the item (see HID spec 6.2.2.2, then jump to 6.2.2.7)
|
||||
^^^^
|
||||
--------- Function of the item (see HID spec 6.2.2.7, then HUT Sec 3)
|
||||
|
||||
In our case, the length is 1 byte, the type is ``Global`` and the
|
||||
function is ``Usage Page``, thus for parsing the value 0x01 in the second byte
|
||||
we need to refer to HUT Sec 3.
|
||||
|
||||
The second number is the actual data, and its meaning can be found in
|
||||
the HUT. We have a ``Usage Page``, thus we need to refer to HUT
|
||||
Sec. 3, "Usage Pages"; from there, one sees that ``0x01`` stands for
|
||||
``Generic Desktop Page``.
|
||||
|
||||
Moving now to the second two bytes, and following the same scheme,
|
||||
``0x09`` (i.e. ``00001001``) will be followed by one byte (``01``)
|
||||
and is a ``Local`` item (``10``). Thus, the meaning of the remaining four bits
|
||||
(``0000``) is given in the HID spec Sec. 6.2.2.8 "Local Items", so that
|
||||
we have a ``Usage``. From HUT, Sec. 4, "Generic Desktop Page", we see that
|
||||
0x02 stands for ``Mouse``.
|
||||
|
||||
The following numbers can be parsed in the same way.
|
||||
@ -7,6 +7,7 @@ Human Interface Devices (HID)
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
hidintro
|
||||
hiddev
|
||||
hidraw
|
||||
hid-sensor
|
||||
|
||||
@ -341,6 +341,29 @@ struct hid_item {
|
||||
*/
|
||||
#define MAX_USBHID_BOOT_QUIRKS 4
|
||||
|
||||
/**
|
||||
* DOC: HID quirks
|
||||
* | @HID_QUIRK_NOTOUCH:
|
||||
* | @HID_QUIRK_IGNORE: ignore this device
|
||||
* | @HID_QUIRK_NOGET:
|
||||
* | @HID_QUIRK_HIDDEV_FORCE:
|
||||
* | @HID_QUIRK_BADPAD:
|
||||
* | @HID_QUIRK_MULTI_INPUT:
|
||||
* | @HID_QUIRK_HIDINPUT_FORCE:
|
||||
* | @HID_QUIRK_ALWAYS_POLL:
|
||||
* | @HID_QUIRK_INPUT_PER_APP:
|
||||
* | @HID_QUIRK_X_INVERT:
|
||||
* | @HID_QUIRK_Y_INVERT:
|
||||
* | @HID_QUIRK_SKIP_OUTPUT_REPORTS:
|
||||
* | @HID_QUIRK_SKIP_OUTPUT_REPORT_ID:
|
||||
* | @HID_QUIRK_NO_OUTPUT_REPORTS_ON_INTR_EP:
|
||||
* | @HID_QUIRK_HAVE_SPECIAL_DRIVER:
|
||||
* | @HID_QUIRK_INCREMENT_USAGE_ON_DUPLICATE:
|
||||
* | @HID_QUIRK_FULLSPEED_INTERVAL:
|
||||
* | @HID_QUIRK_NO_INIT_REPORTS:
|
||||
* | @HID_QUIRK_NO_IGNORE:
|
||||
* | @HID_QUIRK_NO_INPUT_SYNC:
|
||||
*/
|
||||
/* BIT(0) reserved for backward compatibility, was HID_QUIRK_INVERT */
|
||||
#define HID_QUIRK_NOTOUCH BIT(1)
|
||||
#define HID_QUIRK_IGNORE BIT(2)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user