<!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>1. Introduction — 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="2. Input event codes" href="event-codes.html" />
<link rel="prev" title="Linux Input Subsystem userspace API" href="input_uapi.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 current"><a class="reference internal" href="index.html">Input Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../hid/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/input/input.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">
<h1><span class="section-number">1. </span>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Copyright<span class="colon">:</span></dt>
<dd class="field-odd"><p>© 1999-2001 Vojtech Pavlik <<a class="reference external" href="mailto:vojtech%40ucw.cz">vojtech<span>@</span>ucw<span>.</span>cz</a>> - Sponsored by SuSE</p>
</dd>
</dl>
<section id="architecture">
<h2><span class="section-number">1.1. </span>Architecture<a class="headerlink" href="#architecture" title="Link to this heading">¶</a></h2>
<p>Input subsystem is a collection of drivers that is designed to support
all input devices under Linux. Most of the drivers reside in
drivers/input, although quite a few live in drivers/hid and
drivers/platform.</p>
<p>The core of the input subsystem is the input module, which must be
loaded before any other of the input modules - it serves as a way of
communication between two groups of modules:</p>
<section id="device-drivers">
<h3><span class="section-number">1.1.1. </span>Device drivers<a class="headerlink" href="#device-drivers" title="Link to this heading">¶</a></h3>
<p>These modules talk to the hardware (for example via USB), and provide
events (keystrokes, mouse movements) to the input module.</p>
</section>
<section id="event-handlers">
<h3><span class="section-number">1.1.2. </span>Event handlers<a class="headerlink" href="#event-handlers" title="Link to this heading">¶</a></h3>
<p>These modules get events from input core and pass them where needed
via various interfaces - keystrokes to the kernel, mouse movements via
a simulated PS/2 interface to GPM and X, and so on.</p>
</section>
</section>
<section id="simple-usage">
<h2><span class="section-number">1.2. </span>Simple Usage<a class="headerlink" href="#simple-usage" title="Link to this heading">¶</a></h2>
<p>For the most usual configuration, with one USB mouse and one USB keyboard,
you’ll have to load the following modules (or have them built in to the
kernel):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>input
mousedev
usbcore
uhci_hcd or ohci_hcd or ehci_hcd
usbhid
hid_generic
</pre></div>
</div>
<p>After this, the USB keyboard will work straight away, and the USB mouse
will be available as a character device on major 13, minor 63:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice
</pre></div>
</div>
<p>This device is usually created automatically by the system. The commands
to create it by hand are:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd /dev
mkdir input
mknod input/mice c 13 63
</pre></div>
</div>
<p>After that you have to point GPM (the textmode mouse cut&paste tool) and
XFree to this device to use it - GPM should be called like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>gpm -t ps2 -m /dev/input/mice
</pre></div>
</div>
<p>And in X:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Section "Pointer"
Protocol "ImPS/2"
Device "/dev/input/mice"
ZAxisMapping 4 5
EndSection
</pre></div>
</div>
<p>When you do all of the above, you can use your USB mouse and keyboard.</p>
</section>
<section id="detailed-description">
<h2><span class="section-number">1.3. </span>Detailed Description<a class="headerlink" href="#detailed-description" title="Link to this heading">¶</a></h2>
<section id="id1">
<h3><span class="section-number">1.3.1. </span>Event handlers<a class="headerlink" href="#id1" title="Link to this heading">¶</a></h3>
<p>Event handlers distribute the events from the devices to userspace and
in-kernel consumers, as needed.</p>
<section id="evdev">
<h4><span class="section-number">1.3.1.1. </span>evdev<a class="headerlink" href="#evdev" title="Link to this heading">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">evdev</span></code> is the generic input event interface. It passes the events
generated in the kernel straight to the program, with timestamps. The
event codes are the same on all architectures and are hardware
independent.</p>
<p>This is the preferred interface for userspace to consume user
input, and all clients are encouraged to use it.</p>
<p>See <a class="reference internal" href="#event-interface"><span class="std std-ref">Event interface</span></a> for notes on API.</p>
<p>The devices are in /dev/input:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0
crw-r--r-- 1 root root 13, 65 Apr 1 10:50 event1
crw-r--r-- 1 root root 13, 66 Apr 1 10:50 event2
crw-r--r-- 1 root root 13, 67 Apr 1 10:50 event3
...
</pre></div>
</div>
<p>There are two ranges of minors: 64 through 95 is the static legacy
range. If there are more than 32 input devices in a system, additional
evdev nodes are created with minors starting with 256.</p>
</section>
<section id="keyboard">
<h4><span class="section-number">1.3.1.2. </span>keyboard<a class="headerlink" href="#keyboard" title="Link to this heading">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">keyboard</span></code> is in-kernel input handler and is a part of VT code. It
consumes keyboard keystrokes and handles user input for VT consoles.</p>
</section>
<section id="mousedev">
<h4><span class="section-number">1.3.1.3. </span>mousedev<a class="headerlink" href="#mousedev" title="Link to this heading">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">mousedev</span></code> is a hack to make legacy programs that use mouse input
work. It takes events from either mice or digitizers/tablets and makes
a PS/2-style (a la /dev/psaux) mouse device available to the
userland.</p>
<p>Mousedev devices in /dev/input (as shown above) are:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>crw-r--r-- 1 root root 13, 32 Mar 28 22:45 mouse0
crw-r--r-- 1 root root 13, 33 Mar 29 00:41 mouse1
crw-r--r-- 1 root root 13, 34 Mar 29 00:41 mouse2
crw-r--r-- 1 root root 13, 35 Apr 1 10:50 mouse3
...
...
crw-r--r-- 1 root root 13, 62 Apr 1 10:50 mouse30
crw-r--r-- 1 root root 13, 63 Apr 1 10:50 mice
</pre></div>
</div>
<p>Each <code class="docutils literal notranslate"><span class="pre">mouse</span></code> device is assigned to a single mouse or digitizer, except
the last one - <code class="docutils literal notranslate"><span class="pre">mice</span></code>. This single character device is shared by all
mice and digitizers, and even if none are connected, the device is
present. This is useful for hotplugging USB mice, so that older programs
that do not handle hotplug can open the device even when no mice are
present.</p>
<p>CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
the size of your screen (in pixels) in XFree86. This is needed if you
want to use your digitizer in X, because its movement is sent to X
via a virtual PS/2 mouse and thus needs to be scaled
accordingly. These values won’t be used if you use a mouse only.</p>
<p>Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
program reading the data wishes. You can set GPM and X to any of
these. You’ll need ImPS/2 if you want to make use of a wheel on a USB
mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.</p>
</section>
<section id="joydev">
<h4><span class="section-number">1.3.1.4. </span>joydev<a class="headerlink" href="#joydev" title="Link to this heading">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">joydev</span></code> implements v0.x and v1.x Linux joystick API. See
<a class="reference internal" href="joydev/joystick-api.html#joystick-api"><span class="std std-ref">Programming Interface</span></a> for details.</p>
<p>As soon as any joystick is connected, it can be accessed in /dev/input on:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>crw-r--r-- 1 root root 13, 0 Apr 1 10:50 js0
crw-r--r-- 1 root root 13, 1 Apr 1 10:50 js1
crw-r--r-- 1 root root 13, 2 Apr 1 10:50 js2
crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3
...
</pre></div>
</div>
<p>And so on up to js31 in legacy range, and additional nodes with minors
above 256 if there are more joystick devices.</p>
</section>
</section>
<section id="id2">
<h3><span class="section-number">1.3.2. </span>Device drivers<a class="headerlink" href="#id2" title="Link to this heading">¶</a></h3>
<p>Device drivers are the modules that generate events.</p>
<section id="hid-generic">
<h4><span class="section-number">1.3.2.1. </span>hid-generic<a class="headerlink" href="#hid-generic" title="Link to this heading">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">hid-generic</span></code> is one of the largest and most complex driver of the
whole suite. It handles all HID devices, and because there is a very
wide variety of them, and because the USB HID specification isn’t
simple, it needs to be this big.</p>
<p>Currently, it handles USB mice, joysticks, gamepads, steering wheels,
keyboards, trackballs and digitizers.</p>
<p>However, USB uses HID also for monitor controls, speaker controls, UPSs,
LCDs and many other purposes.</p>
<p>The monitor and speaker controls should be easy to add to the hid/input
interface, but for the UPSs and LCDs it doesn’t make much sense. For this,
the hiddev interface was designed. See <a class="reference internal" href="../hid/hiddev.html"><span class="doc">Care and feeding of your Human Interface Devices</span></a>
for more information about it.</p>
<p>The usage of the usbhid module is very simple, it takes no parameters,
detects everything automatically and when a HID device is inserted, it
detects it appropriately.</p>
<p>However, because the devices vary wildly, you might happen to have a
device that doesn’t work well. In that case #define DEBUG at the beginning
of hid-core.c and send me the syslog traces.</p>
</section>
<section id="usbmouse">
<h4><span class="section-number">1.3.2.2. </span>usbmouse<a class="headerlink" href="#usbmouse" title="Link to this heading">¶</a></h4>
<p>For embedded systems, for mice with broken HID descriptors and just any
other use when the big usbhid wouldn’t be a good choice, there is the
usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
protocol. This also means the mice must support this simpler protocol. Not
all do. If you don’t have any strong reason to use this module, use usbhid
instead.</p>
</section>
<section id="usbkbd">
<h4><span class="section-number">1.3.2.3. </span>usbkbd<a class="headerlink" href="#usbkbd" title="Link to this heading">¶</a></h4>
<p>Much like usbmouse, this module talks to keyboards with a simplified
HIDBP protocol. It’s smaller, but doesn’t support any extra special keys.
Use usbhid instead if there isn’t any special reason to use this.</p>
</section>
<section id="psmouse">
<h4><span class="section-number">1.3.2.4. </span>psmouse<a class="headerlink" href="#psmouse" title="Link to this heading">¶</a></h4>
<p>This is driver for all flavors of pointing devices using PS/2
protocol, including Synaptics and ALPS touchpads, Intellimouse
Explorer devices, Logitech PS/2 mice and so on.</p>
</section>
<section id="atkbd">
<h4><span class="section-number">1.3.2.5. </span>atkbd<a class="headerlink" href="#atkbd" title="Link to this heading">¶</a></h4>
<p>This is driver for PS/2 (AT) keyboards.</p>
</section>
<section id="iforce">
<h4><span class="section-number">1.3.2.6. </span>iforce<a class="headerlink" href="#iforce" title="Link to this heading">¶</a></h4>
<p>A driver for I-Force joysticks and wheels, both over USB and RS232.
It includes Force Feedback support now, even though Immersion
Corp. considers the protocol a trade secret and won’t disclose a word
about it.</p>
</section>
</section>
</section>
<section id="verifying-if-it-works">
<h2><span class="section-number">1.4. </span>Verifying if it works<a class="headerlink" href="#verifying-if-it-works" title="Link to this heading">¶</a></h2>
<p>Typing a couple keys on the keyboard should be enough to check that
a keyboard works and is correctly connected to the kernel keyboard
driver.</p>
<p>Doing a <code class="docutils literal notranslate"><span class="pre">cat</span> <span class="pre">/dev/input/mouse0</span></code> (c, 13, 32) will verify that a mouse
is also emulated; characters should appear if you move it.</p>
<p>You can test the joystick emulation with the <code class="docutils literal notranslate"><span class="pre">jstest</span></code> utility,
available in the joystick package (see <a class="reference internal" href="joydev/joystick.html#joystick-doc"><span class="std std-ref">Introduction</span></a>).</p>
<p>You can test the event devices with the <code class="docutils literal notranslate"><span class="pre">evtest</span></code> utility.</p>
</section>
<section id="event-interface">
<span id="id3"></span><h2><span class="section-number">1.5. </span>Event interface<a class="headerlink" href="#event-interface" title="Link to this heading">¶</a></h2>
<p>You can use blocking and nonblocking reads, and also select() on the
/dev/input/eventX devices, and you’ll always get a whole number of input
events on a read. Their layout is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct input_event {
struct timeval time;
unsigned short type;
unsigned short code;
int value;
};
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">time</span></code> is the timestamp, it returns the time at which the event happened.
Type is for example EV_REL for relative movement, EV_KEY for a keypress or
release. More types are defined in include/uapi/linux/input-event-codes.h.</p>
<p><code class="docutils literal notranslate"><span class="pre">code</span></code> is event code, for example REL_X or KEY_BACKSPACE, again a complete
list is in include/uapi/linux/input-event-codes.h.</p>
<p><code class="docutils literal notranslate"><span class="pre">value</span></code> is the value the event carries. Either a relative change for
EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
release, 1 for keypress and 2 for autorepeat.</p>
<p>See <a class="reference internal" href="event-codes.html#input-event-codes"><span class="std std-ref">Input event codes</span></a> for more information about various even codes.</p>
</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/input/input.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>