<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Introduction to HID report descriptors — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=3918102e" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Manual parsing of HID report descriptors" href="hidreport-parsing.html" />
<link rel="prev" title="Human Interface Devices (HID)" href="index.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#core-subsystems">Core subsystems</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../subsystem-apis.html#human-interfaces">Human interfaces</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../input/index.html">Input Documentation</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="index.html">Human Interface Devices (HID)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../sound/index.html">Sound Subsystem Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../gpu/index.html">GPU Driver Developer’s Guide</a></li>
<li class="toctree-l3"><a class="reference internal" href="../fb/index.html">Frame Buffer</a></li>
<li class="toctree-l3"><a class="reference internal" href="../leds/index.html">LEDs</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#storage-interfaces">Storage interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#other-subsystems">Other subsystems</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/hid/hidintro.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="introduction-to-hid-report-descriptors">
<h1>Introduction to HID report descriptors<a class="headerlink" href="#introduction-to-hid-report-descriptors" title="Link to this heading">¶</a></h1>
<p>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.</p>
<nav class="contents local" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#introduction" id="id4">Introduction</a></p></li>
<li><p><a class="reference internal" href="#parsing-hid-report-descriptors" id="id5">Parsing HID report descriptors</a></p>
<ul>
<li><p><a class="reference internal" href="#output-input-and-feature-reports" id="id6">Output, Input and Feature Reports</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#collections-report-ids-and-evdev-events" id="id7">Collections, Report IDs and Evdev events</a></p></li>
<li><p><a class="reference internal" href="#events" id="id8">Events</a></p></li>
<li><p><a class="reference internal" href="#when-something-does-not-work" id="id9">When something does not work</a></p>
<ul>
<li><p><a class="reference internal" href="#quirks" id="id10">Quirks</a></p></li>
<li><p><a class="reference internal" href="#fixing-hid-report-descriptors" id="id11">Fixing HID report descriptors</a></p></li>
<li><p><a class="reference internal" href="#modifying-the-transmitted-data-on-the-fly" id="id12">Modifying the transmitted data on the fly</a></p></li>
<li><p><a class="reference internal" href="#writing-a-specialized-driver" id="id13">Writing a specialized driver</a></p></li>
</ul>
</li>
</ul>
</nav>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="hidreport-parsing.html">Manual parsing of HID report descriptors</a></li>
</ul>
</div>
<section id="introduction">
<h2><a class="toc-backref" href="#id4" role="doc-backlink">Introduction</a><a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>
<p>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.</p>
<p>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.</p>
<p>This is because modern HID devices do advertise their capabilities
through the <em>HID report descriptor</em>, a fixed set of bytes describing
exactly what <em>HID reports</em> 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”.</p>
<p>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.</p>
<p>The HID subsystem is in charge of parsing the HID report descriptors,
and converts HID events into normal input device interfaces (see
<a class="reference internal" href="hid-transport.html"><span class="doc">HID I/O Transport Drivers</span></a>). 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.</p>
<p>The format of HID report descriptors is described by two documents,
available from the <a class="reference external" href="https://www.usb.org/">USB Implementers Forum</a>
<a class="reference external" href="https://www.usb.org/hid">HID web page</a> address:</p>
<blockquote>
<div><ul class="simple">
<li><p>the <a class="reference external" href="https://www.usb.org/document-library/device-class-definition-hid-111">HID USB Device Class Definition</a> (HID Spec from now on)</p></li>
<li><p>the <a class="reference external" href="https://usb.org/document-library/hid-usage-tables-14">HID Usage Tables</a> (HUT from now on)</p></li>
</ul>
</div></blockquote>
<p>The HID subsystem can deal with different transport drivers
(USB, I2C, Bluetooth, etc.). See <a class="reference internal" href="hid-transport.html"><span class="doc">HID I/O Transport Drivers</span></a>.</p>
</section>
<section id="parsing-hid-report-descriptors">
<h2><a class="toc-backref" href="#id5" role="doc-backlink">Parsing HID report descriptors</a><a class="headerlink" href="#parsing-hid-report-descriptors" title="Link to this heading">¶</a></h2>
<p>The current list of HID devices can be found at <code class="docutils literal notranslate"><span class="pre">/sys/bus/hid/devices/</span></code>.
For each device, say <code class="docutils literal notranslate"><span class="pre">/sys/bus/hid/devices/0003\:093A\:2510.0002/</span></code>,
one can read the corresponding report descriptor:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ 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
</pre></div>
</div>
<p>Optional: the HID report descriptor can be read also by
directly accessing the hidraw driver <a class="footnote-reference brackets" href="#hidraw" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>.</p>
<p>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.</p>
<p>HID report descriptors can, in principle, be painstakingly parsed by
hand, byte by byte.</p>
<p>A short introduction on how to do this is sketched in
<a class="reference internal" href="hidreport-parsing.html"><span class="doc">Manual parsing of HID report descriptors</span></a>; you only need to understand it
if you need to patch HID report descriptors.</p>
<p>In practice you should not parse HID report descriptors by hand; rather,
you should use an existing parser. Among all the available ones</p>
<blockquote>
<div><ul class="simple">
<li><p>the online <a class="reference external" href="http://eleccelerator.com/usbdescreqparser/">USB Descriptor and Request Parser</a>;</p></li>
<li><p><a class="reference external" href="https://github.com/abend0c1/hidrdd">hidrdd</a>,
that provides very detailed and somewhat verbose descriptions
(verbosity can be useful if you are not familiar with HID report
descriptors);</p></li>
<li><p><a class="reference external" href="https://gitlab.freedesktop.org/libevdev/hid-tools">hid-tools</a>,
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.</p></li>
</ul>
</div></blockquote>
<p>Parsing the mouse HID report descriptor with <a class="reference external" href="https://gitlab.freedesktop.org/libevdev/hid-tools">hid-tools</a> leads to
(explanations interposed):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ ./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
</pre></div>
</div>
<p>what follows is a button</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x19, 0x01, // Usage Minimum (1) 12
# 0x29, 0x03, // Usage Maximum (3) 14
</pre></div>
</div>
<p>first button is button number 1, last button is button number 3</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x15, 0x00, // Logical Minimum (0) 16
# 0x25, 0x01, // Logical Maximum (1) 18
</pre></div>
</div>
<p>each button can send values from 0 up to including 1
(i.e. they are binary buttons)</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x75, 0x01, // Report Size (1) 20
</pre></div>
</div>
<p>each button is sent as exactly one bit</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x95, 0x03, // Report Count (3) 22
</pre></div>
</div>
<p>and there are three of those bits (matching the three buttons)</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x81, 0x02, // Input (Data,Var,Abs) 24
</pre></div>
</div>
<p>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”</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x75, 0x05, // Report Size (5) 26
</pre></div>
</div>
<p>five additional padding bits, needed to reach a byte</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x95, 0x01, // Report Count (1) 28
</pre></div>
</div>
<p>those five bits are repeated only once</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x81, 0x01, // Input (Cnst,Arr,Abs) 30
</pre></div>
</div>
<p>and take Constant (Cnst) values i.e. they can be ignored.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x05, 0x01, // Usage Page (Generic Desktop) 32
# 0x09, 0x30, // Usage (X) 34
# 0x09, 0x31, // Usage (Y) 36
# 0x09, 0x38, // Usage (Wheel) 38
</pre></div>
</div>
<p>The mouse has also two physical positions (Usage (X), Usage (Y))
and a wheel (Usage (Wheel))</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x15, 0x81, // Logical Minimum (-127) 40
# 0x25, 0x7f, // Logical Maximum (127) 42
</pre></div>
</div>
<p>each of them can send values ranging from -127 up to including 127</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x75, 0x08, // Report Size (8) 44
</pre></div>
</div>
<p>which is represented by eight bits</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x95, 0x03, // Report Count (3) 46
</pre></div>
</div>
<p>and there are three of those eight bits, matching X, Y and Wheel.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 0x81, 0x06, // Input (Data,Var,Rel) 48
</pre></div>
</div>
<p>This time the data values are Relative (Rel), i.e. they represent
the change from the previously sent report (event)</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 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
</pre></div>
</div>
<p>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.</p>
<p>Indeed, for any event, the mouse will send a <em>report</em> of four bytes.
We can check the values sent by resorting e.g. to the <cite>hid-recorder</cite>
tool, from <a class="reference external" href="https://gitlab.freedesktop.org/libevdev/hid-tools">hid-tools</a>:
The sequence of bytes sent by clicking and releasing button 1, then button 2, then button 3 is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ 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
</pre></div>
</div>
<p>This example shows that when button 2 is clicked,
the bytes <code class="docutils literal notranslate"><span class="pre">02</span> <span class="pre">00</span> <span class="pre">00</span> <span class="pre">00</span></code> are sent, and the immediately subsequent
event (<code class="docutils literal notranslate"><span class="pre">00</span> <span class="pre">00</span> <span class="pre">00</span> <span class="pre">00</span></code>) is the release of button 2 (no buttons are
pressed, remember that the data values are <em>absolute</em>).</p>
<p>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:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># 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
</pre></div>
</div>
<p>where with <code class="docutils literal notranslate"><span class="pre">03</span> <span class="pre">00</span> <span class="pre">00</span> <span class="pre">00</span></code> both buttons are pressed, and with the
subsequent <code class="docutils literal notranslate"><span class="pre">02</span> <span class="pre">00</span> <span class="pre">00</span> <span class="pre">00</span></code> button 1 is released while button 2 is still
active.</p>
<section id="output-input-and-feature-reports">
<h3><a class="toc-backref" href="#id6" role="doc-backlink">Output, Input and Feature Reports</a><a class="headerlink" href="#output-input-and-feature-reports" title="Link to this heading">¶</a></h3>
<p>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.</p>
<p>“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 <em>Volatile</em> they should be changed by the host.</p>
</section>
</section>
<section id="collections-report-ids-and-evdev-events">
<h2><a class="toc-backref" href="#id7" role="doc-backlink">Collections, Report IDs and Evdev events</a><a class="headerlink" href="#collections-report-ids-and-evdev-events" title="Link to this heading">¶</a></h2>
<p>A single device can logically group data into different independent
sets, called a <em>Collection</em>. 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).</p>
<p>Different reports are identified by means of different <em>Report ID</em>
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.</p>
<p>Consider the following HID report descriptor:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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
</pre></div>
</div>
<p>After parsing it (try to parse it on your own using the suggested
tools!) one can see that the device presents two <code class="docutils literal notranslate"><span class="pre">Mouse</span></code> Application
Collections (with reports identified by Reports IDs 1 and 2,
respectively), a <code class="docutils literal notranslate"><span class="pre">Keypad</span></code> Application Collection (whose report is
identified by the Report ID 5) and two <code class="docutils literal notranslate"><span class="pre">Consumer</span> <span class="pre">Controls</span></code> Application
Collections, (with Report IDs 6 and 3, respectively). Note, however,
that a device can have different Report IDs for the same Application
Collection.</p>
<p>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:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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
</pre></div>
</div>
<p>will be of three bytes: the first for the Report ID (3), the next two
for the headphone, with two (<code class="docutils literal notranslate"><span class="pre">Report</span> <span class="pre">Count</span> <span class="pre">(2)</span></code>) bytes
(<code class="docutils literal notranslate"><span class="pre">Report</span> <span class="pre">Size</span> <span class="pre">(8)</span></code>), each ranging from 0 (<code class="docutils literal notranslate"><span class="pre">Logical</span> <span class="pre">Minimum</span> <span class="pre">(0)</span></code>)
to 255 (<code class="docutils literal notranslate"><span class="pre">Logical</span> <span class="pre">Maximum</span> <span class="pre">(255)</span></code>).</p>
<p>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 <code class="docutils literal notranslate"><span class="pre">EV_KEY/BTN_LEFT</span></code> evdev event and relative X movement translates
into the <code class="docutils literal notranslate"><span class="pre">EV_REL/REL_X</span></code> evdev event”.</p>
</section>
<section id="events">
<h2><a class="toc-backref" href="#id8" role="doc-backlink">Events</a><a class="headerlink" href="#events" title="Link to this heading">¶</a></h2>
<p>In Linux, one <code class="docutils literal notranslate"><span class="pre">/dev/input/event*</span></code> is created for each <code class="docutils literal notranslate"><span class="pre">Application</span>
<span class="pre">Collection</span></code>. 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:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ 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
</pre></div>
</div>
<p>Note: if <code class="docutils literal notranslate"><span class="pre">libinput</span> <span class="pre">record</span></code> is not available on your system try using
<code class="docutils literal notranslate"><span class="pre">evemu-record</span></code>.</p>
</section>
<section id="when-something-does-not-work">
<h2><a class="toc-backref" href="#id9" role="doc-backlink">When something does not work</a><a class="headerlink" href="#when-something-does-not-work" title="Link to this heading">¶</a></h2>
<p>There can be a number of reasons why a device does not behave
correctly. For example</p>
<ul class="simple">
<li><p>The HID report descriptor provided by the HID device may be wrong
because e.g.</p>
<ul>
<li><p>it does not follow the standard, so that the kernel
will not able to make sense of the HID report descriptor;</p></li>
<li><p>the HID report descriptor <em>does not match</em> what is actually
sent by the device (this can be verified by reading the raw HID
data);</p></li>
</ul>
</li>
<li><p>the HID report descriptor may need some “quirks” (see later on).</p></li>
</ul>
<p>As a consequence, a <code class="docutils literal notranslate"><span class="pre">/dev/input/event*</span></code> may not be created
for each Application Collection, and/or the events
there may not match what you would expect.</p>
<section id="quirks">
<h3><a class="toc-backref" href="#id10" role="doc-backlink">Quirks</a><a class="headerlink" href="#quirks" title="Link to this heading">¶</a></h3>
<p>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 <cite>include/linux/hid.h</cite>.</p>
<p>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
<cite>drivers/hid/hid-quirks.c</cite>. How to do it should be relatively
straightforward after looking into the file.</p>
<p>The list of currently defined quirks, from <cite>include/linux/hid.h</cite>, is</p>
<div class="line-block">
<div class="line"><strong>HID_QUIRK_NOTOUCH</strong>:</div>
<div class="line"><strong>HID_QUIRK_IGNORE</strong>: ignore this device</div>
<div class="line"><strong>HID_QUIRK_NOGET</strong>:</div>
<div class="line"><strong>HID_QUIRK_HIDDEV_FORCE</strong>:</div>
<div class="line"><strong>HID_QUIRK_BADPAD</strong>:</div>
<div class="line"><strong>HID_QUIRK_MULTI_INPUT</strong>:</div>
<div class="line"><strong>HID_QUIRK_HIDINPUT_FORCE</strong>:</div>
<div class="line"><strong>HID_QUIRK_ALWAYS_POLL</strong>:</div>
<div class="line"><strong>HID_QUIRK_INPUT_PER_APP</strong>:</div>
<div class="line"><strong>HID_QUIRK_X_INVERT</strong>:</div>
<div class="line"><strong>HID_QUIRK_Y_INVERT</strong>:</div>
<div class="line"><strong>HID_QUIRK_IGNORE_MOUSE</strong>:</div>
<div class="line"><strong>HID_QUIRK_SKIP_OUTPUT_REPORTS</strong>:</div>
<div class="line"><strong>HID_QUIRK_SKIP_OUTPUT_REPORT_ID</strong>:</div>
<div class="line"><strong>HID_QUIRK_NO_OUTPUT_REPORTS_ON_INTR_EP</strong>:</div>
<div class="line"><strong>HID_QUIRK_HAVE_SPECIAL_DRIVER</strong>:</div>
<div class="line"><strong>HID_QUIRK_INCREMENT_USAGE_ON_DUPLICATE</strong>:</div>
<div class="line"><strong>HID_QUIRK_IGNORE_SPECIAL_DRIVER</strong></div>
<div class="line"><strong>HID_QUIRK_POWER_ON_AFTER_BACKLIGHT</strong></div>
<div class="line"><strong>HID_QUIRK_FULLSPEED_INTERVAL</strong>:</div>
<div class="line"><strong>HID_QUIRK_NO_INIT_REPORTS</strong>:</div>
<div class="line"><strong>HID_QUIRK_NO_IGNORE</strong>:</div>
<div class="line"><strong>HID_QUIRK_NO_INPUT_SYNC</strong>:</div>
</div>
<p>Quirks for USB devices can be specified while loading the usbhid module,
see <code class="docutils literal notranslate"><span class="pre">modinfo</span> <span class="pre">usbhid</span></code>, although the proper fix should go into
hid-quirks.c and <strong>be submitted upstream</strong>.
See <a class="reference internal" href="../process/submitting-patches.html"><span class="doc">Submitting patches: the essential guide to getting your code into the kernel</span></a> for guidelines on how
to submit a patch. Quirks for other busses need to go into hid-quirks.c.</p>
</section>
<section id="fixing-hid-report-descriptors">
<h3><a class="toc-backref" href="#id11" role="doc-backlink">Fixing HID report descriptors</a><a class="headerlink" href="#fixing-hid-report-descriptors" title="Link to this heading">¶</a></h3>
<p>Should you need to patch HID report descriptors the easiest way is to
resort to eBPF, as described in <a class="reference internal" href="hid-bpf.html"><span class="doc">HID-BPF</span></a>.</p>
<p>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. <cite>samples/hid/hid_mouse.bpf.c</cite>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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;
}
</pre></div>
</div>
<p>Of course this can be also done within the kernel source code, see e.g.
<cite>drivers/hid/hid-aureal.c</cite> or <cite>drivers/hid/hid-samsung.c</cite> for a slightly
more complex file.</p>
<p>Check <a class="reference internal" href="hidreport-parsing.html"><span class="doc">Manual parsing of HID report descriptors</span></a> if you need any help
navigating the HID manuals and understanding the exact meaning of
the HID report descriptor hex numbers.</p>
<p>Whatever solution you come up with, please remember to <strong>submit the
fix to the HID maintainers</strong>, so that it can be directly integrated in
the kernel and that particular HID device will start working for
everyone else. See <a class="reference internal" href="../process/submitting-patches.html"><span class="doc">Submitting patches: the essential guide to getting your code into the kernel</span></a> for
guidelines on how to do this.</p>
</section>
<section id="modifying-the-transmitted-data-on-the-fly">
<h3><a class="toc-backref" href="#id12" role="doc-backlink">Modifying the transmitted data on the fly</a><a class="headerlink" href="#modifying-the-transmitted-data-on-the-fly" title="Link to this heading">¶</a></h3>
<p>Using eBPF it is also possible to modify the data exchanged with the
device. See again the examples in <cite>samples/hid</cite>.</p>
<p>Again, <strong>please post your fix</strong>, so that it can be integrated in the
kernel!</p>
</section>
<section id="writing-a-specialized-driver">
<h3><a class="toc-backref" href="#id13" role="doc-backlink">Writing a specialized driver</a><a class="headerlink" href="#writing-a-specialized-driver" title="Link to this heading">¶</a></h3>
<p>This should really be your last resort.</p>
<p class="rubric">Footnotes</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="hidraw" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>
<p>read hidraw: see <a class="reference internal" href="hidraw.html"><span class="doc">HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices</span></a> and
file <cite>samples/hidraw/hid-example.c</cite> for an example.
The output of <code class="docutils literal notranslate"><span class="pre">hid-example</span></code> would be, for the same mouse:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ 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
...
</pre></div>
</div>
</aside>
</aside>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../_sources/hid/hidintro.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>