<!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>Care and feeding of your Human Interface Devices — 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="HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices" href="hidraw.html" />
<link rel="prev" title="Manual parsing of HID report descriptors" href="hidreport-parsing.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/hiddev.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="care-and-feeding-of-your-human-interface-devices">
<h1>Care and feeding of your Human Interface Devices<a class="headerlink" href="#care-and-feeding-of-your-human-interface-devices" title="Link to this heading">¶</a></h1>
<section id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>
<p>In addition to the normal input type HID devices, USB also uses the
human interface device protocols for things that are not really human
interfaces, but have similar sorts of communication needs. The two big
examples for this are power devices (especially uninterruptible power
supplies) and monitor control on higher end monitors.</p>
<p>To support these disparate requirements, the Linux USB system provides
HID events to two separate interfaces:
* the input subsystem, which converts HID events into normal input
device interfaces (such as keyboard, mouse and joystick) and a
normalised event interface - see <a class="reference internal" href="../input/input.html"><span class="doc">Introduction</span></a>
* the hiddev interface, which provides fairly raw HID events</p>
<p>The data flow for a HID event produced by a device is something like
the following:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>usb.c ---> hid-core.c ----> hid-input.c ----> [keyboard/mouse/joystick/event]
|
|
--> hiddev.c ----> POWER / MONITOR CONTROL
</pre></div>
</div>
<p>In addition, other subsystems (apart from USB) can potentially feed
events into the input subsystem, but these have no effect on the HID
device interface.</p>
</section>
<section id="using-the-hid-device-interface">
<h2>Using the HID Device Interface<a class="headerlink" href="#using-the-hid-device-interface" title="Link to this heading">¶</a></h2>
<p>The hiddev interface is a char interface using the normal USB major,
with the minor numbers starting at 96 and finishing at 111. Therefore,
you need the following commands:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>mknod /dev/usb/hiddev0 c 180 96
mknod /dev/usb/hiddev1 c 180 97
mknod /dev/usb/hiddev2 c 180 98
mknod /dev/usb/hiddev3 c 180 99
mknod /dev/usb/hiddev4 c 180 100
mknod /dev/usb/hiddev5 c 180 101
mknod /dev/usb/hiddev6 c 180 102
mknod /dev/usb/hiddev7 c 180 103
mknod /dev/usb/hiddev8 c 180 104
mknod /dev/usb/hiddev9 c 180 105
mknod /dev/usb/hiddev10 c 180 106
mknod /dev/usb/hiddev11 c 180 107
mknod /dev/usb/hiddev12 c 180 108
mknod /dev/usb/hiddev13 c 180 109
mknod /dev/usb/hiddev14 c 180 110
mknod /dev/usb/hiddev15 c 180 111
</pre></div>
</div>
<p>So you point your hiddev compliant user-space program at the correct
interface for your device, and it all just works.</p>
<p>Assuming that you have a hiddev compliant user-space program, of
course. If you need to write one, read on.</p>
</section>
<section id="the-hiddev-api">
<h2>The HIDDEV API<a class="headerlink" href="#the-hiddev-api" title="Link to this heading">¶</a></h2>
<p>This description should be read in conjunction with the HID
specification, freely available from <a class="reference external" href="https://www.usb.org">https://www.usb.org</a>, and
conveniently linked of <a class="reference external" href="http://www.linux-usb.org">http://www.linux-usb.org</a>.</p>
<p>The hiddev API uses a read() interface, and a set of ioctl() calls.</p>
<p>HID devices exchange data with the host computer using data
bundles called “reports”. Each report is divided into “fields”,
each of which can have one or more “usages”. In the hid-core,
each one of these usages has a single signed 32-bit value.</p>
<section id="read">
<h3>read():<a class="headerlink" href="#read" title="Link to this heading">¶</a></h3>
<p>This is the event interface. When the HID device’s state changes,
it performs an interrupt transfer containing a report which contains
the changed value. The hid-core.c module parses the report, and
returns to hiddev.c the individual usages that have changed within
the report. In its basic mode, the hiddev will make these individual
usage changes available to the reader using a <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_event</span></code>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct hiddev_event {
unsigned hid;
signed int value;
};
</pre></div>
</div>
<p>containing the HID usage identifier for the status that changed, and
the value that it was changed to. Note that the structure is defined
within <linux/hiddev.h>, along with some other useful #defines and
structures. The HID usage identifier is a composite of the HID usage
page shifted to the 16 high order bits ORed with the usage code. The
behavior of the read() function can be modified using the HIDIOCSFLAG
ioctl() described below.</p>
</section>
<section id="ioctl">
<h3>ioctl():<a class="headerlink" href="#ioctl" title="Link to this heading">¶</a></h3>
<p>This is the control interface. There are a number of controls:</p>
<dl>
<dt>HIDIOCGVERSION</dt><dd><blockquote>
<div><ul class="simple">
<li><p>int (read)</p></li>
</ul>
</div></blockquote>
<p>Gets the version code out of the hiddev driver.</p>
</dd>
<dt>HIDIOCAPPLICATION</dt><dd><ul class="simple">
<li><p>(none)</p></li>
</ul>
</dd>
</dl>
<p>This ioctl call returns the HID application usage associated with the
HID device. The third argument to ioctl() specifies which application
index to get. This is useful when the device has more than one
application collection. If the index is invalid (greater or equal to
the number of application collections this device has) the ioctl
returns -1. You can find out beforehand how many application
collections the device has from the num_applications field from the
hiddev_devinfo structure.</p>
<dl class="simple">
<dt>HIDIOCGCOLLECTIONINFO</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_collection_info</span></code> (read/write)</p></li>
</ul>
</dd>
</dl>
<p>This returns a superset of the information above, providing not only
application collections, but all the collections the device has. It
also returns the level the collection lives in the hierarchy.
The user passes in a hiddev_collection_info <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">with</span></code> the index
field set to the index that should be returned. The ioctl fills in
the other fields. If the index is larger than the last collection
index, the ioctl returns -1 and sets errno to -EINVAL.</p>
<dl class="simple">
<dt>HIDIOCGDEVINFO</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_devinfo</span></code> (read)</p></li>
</ul>
</dd>
</dl>
<p>Gets a hiddev_devinfo structure which describes the device.</p>
<dl class="simple">
<dt>HIDIOCGSTRING</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_string_descriptor</span></code> (read/write)</p></li>
</ul>
</dd>
</dl>
<p>Gets a string descriptor from the device. The caller must fill in the
“index” field to indicate which descriptor should be returned.</p>
<dl class="simple">
<dt>HIDIOCINITREPORT</dt><dd><ul class="simple">
<li><p>(none)</p></li>
</ul>
</dd>
</dl>
<p>Instructs the kernel to retrieve all input and feature report values
from the device. At this point, all the usage structures will contain
current values for the device, and will maintain it as the device
changes. Note that the use of this ioctl is unnecessary in general,
since later kernels automatically initialize the reports from the
device at attach time.</p>
<dl class="simple">
<dt>HIDIOCGNAME</dt><dd><ul class="simple">
<li><p>string (variable length)</p></li>
</ul>
</dd>
</dl>
<p>Gets the device name</p>
<dl class="simple">
<dt>HIDIOCGREPORT</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_report_info</span></code> (write)</p></li>
</ul>
</dd>
</dl>
<p>Instructs the kernel to get a feature or input report from the device,
in order to selectively update the usage structures (in contrast to
INITREPORT).</p>
<dl class="simple">
<dt>HIDIOCSREPORT</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_report_info</span></code> (write)</p></li>
</ul>
</dd>
</dl>
<p>Instructs the kernel to send a report to the device. This report can
be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
individual usage values in the report before sending the report in full
to the device.</p>
<dl class="simple">
<dt>HIDIOCGREPORTINFO</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_report_info</span></code> (read/write)</p></li>
</ul>
</dd>
</dl>
<p>Fills in a hiddev_report_info structure for the user. The report is
looked up by type (input, output or feature) and id, so these fields
must be filled in by the user. The ID can be absolute -- the actual
report id as reported by the device -- or relative --
HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT |
report_id) for the next report after report_id. Without a priori
information about report ids, the right way to use this ioctl is to
use the relative IDs above to enumerate the valid IDs. The ioctl
returns non-zero when there is no more next ID. The real report ID is
filled into the returned hiddev_report_info structure.</p>
<dl class="simple">
<dt>HIDIOCGFIELDINFO</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_field_info</span></code> (read/write)</p></li>
</ul>
</dd>
</dl>
<p>Returns the field information associated with a report in a
hiddev_field_info structure. The user must fill in report_id and
report_type in this structure, as above. The field_index should also
be filled in, which should be a number from 0 and maxfield-1, as
returned from a previous HIDIOCGREPORTINFO call.</p>
<dl class="simple">
<dt>HIDIOCGUCODE</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_usage_ref</span></code> (read/write)</p></li>
</ul>
</dd>
</dl>
<p>Returns the usage_code in a hiddev_usage_ref structure, given that
its report type, report id, field index, and index within the
field have already been filled into the structure.</p>
<dl class="simple">
<dt>HIDIOCGUSAGE</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_usage_ref</span></code> (read/write)</p></li>
</ul>
</dd>
</dl>
<p>Returns the value of a usage in a hiddev_usage_ref structure. The
usage to be retrieved can be specified as above, or the user can
choose to fill in the report_type field and specify the report_id as
HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
filled in with the report and field information associated with this
usage if it is found.</p>
<dl class="simple">
<dt>HIDIOCSUSAGE</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_usage_ref</span></code> (write)</p></li>
</ul>
</dd>
</dl>
<p>Sets the value of a usage in an output report. The user fills in
the hiddev_usage_ref structure as above, but additionally fills in
the value field.</p>
<dl class="simple">
<dt>HIDIOGCOLLECTIONINDEX</dt><dd><ul class="simple">
<li><p><code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_usage_ref</span></code> (write)</p></li>
</ul>
</dd>
</dl>
<p>Returns the collection index associated with this usage. This
indicates where in the collection hierarchy this usage sits.</p>
<dl class="simple">
<dt>HIDIOCGFLAG</dt><dd><ul class="simple">
<li><p>int (read)</p></li>
</ul>
</dd>
<dt>HIDIOCSFLAG</dt><dd><ul class="simple">
<li><p>int (write)</p></li>
</ul>
</dd>
</dl>
<p>These operations respectively inspect and replace the mode flags
that influence the read() call above. The flags are as follows:</p>
<blockquote>
<div><dl class="simple">
<dt>HIDDEV_FLAG_UREF</dt><dd><ul class="simple">
<li><p>read() calls will now return
<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_usage_ref</span></code> instead of <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_event</span></code>.
This is a larger structure, but in situations where the
device has more than one usage in its reports with the
same usage code, this mode serves to resolve such
ambiguity.</p></li>
</ul>
</dd>
<dt>HIDDEV_FLAG_REPORT</dt><dd><ul class="simple">
<li><p>This flag can only be used in conjunction
with HIDDEV_FLAG_UREF. With this flag set, when the device
sends a report, a <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">hiddev_usage_ref</span></code> will be returned
to read() filled in with the report_type and report_id, but
with field_index set to FIELD_INDEX_NONE. This serves as
additional notification when the device has sent a report.</p></li>
</ul>
</dd>
</dl>
</div></blockquote>
</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/hiddev.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>