@ -1,25 +1,20 @@
.. include :: <isonum.txt> .. include :: <isonum.txt>
=================== ============
Linux Input drivers Introduction
=================== ============
:Copyright: |copy| 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE :Copyright: |copy| 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE
Should you need to contact me, the author, you can do so either by e-mail Architecture
- mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,
Simunkova 1594, Prague 8, 182 00 Czech Republic
Introduction
============ ============
This is a collection of drivers that is designed to support all input Input subsystem a collection of drivers that is designed to support
devices under Linux. While it is currently used only on for USB input all input devices under Linux. Most of the drivers reside in
devices, future use (say 2.5/2.6) is expected to expand to replace drivers/input, although quite a few live in drivers/hid and
most of the existing input system, which is why it lives in drivers/platform.
drivers/input/ instead of drivers/usb/.
The centre of the input drivers is the input module, which must be 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 loaded before any other of the input modules - it serves as a way of
communication between two groups of modules: communication between two groups of modules:
@ -32,9 +27,9 @@ events (keystrokes, mouse movements) to the input module.
Event handlers Event handlers
-------------- --------------
These modules get events from input and pass them where needed via These modules get events from input core and pass them where needed
various interfaces - keystrokes to the kernel, mouse movements via a via v arious interfaces - keystrokes to the kernel, mouse movements via
simulated PS/2 interface to GPM and X and so on. a simulated PS/2 interface to GPM and X, and so on.
Simple Usage Simple Usage
============ ============
@ -45,19 +40,18 @@ kernel)::
input input
mousedev mousedev
keybdev
usbcore usbcore
uhci_hcd or ohci_hcd or ehci_hcd uhci_hcd or ohci_hcd or ehci_hcd
usbhid usbhid
hid_generic
After this, the USB keyboard will work straight away, and the USB mouse 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:: will be available as a character device on major 13, minor 63::
crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice
This device has to be created. This device usually created automatically by the system. The commands
to create it by hand are::
The commands to create it by hand are::
cd /dev cd /dev
mkdir input mkdir input
@ -81,100 +75,50 @@ When you do all of the above, you can use your USB mouse and keyboard.
Detailed Description Detailed Description
==================== ====================
Device driv ersEvent handl ers
-------------- --------------
Device drivers are the modules that generate events. The events are Event handlers distribute the events from the devices to userspace and
however not useful without being handled, so you also will need to use some in-kernel consumers, as needed.
of the modules from section 3.2.
usbhid
~~~~~~
usbhid is 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.
Currently, it handles USB mice, joysticks, gamepads, steering wheels
keyboards, trackballs and digitizers.
However, USB uses HID also for monitor controls, speaker controls, UPSs,
LCDs and many other purposes.
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 Documentation/hid/hiddev.txt
for more information about it.
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.
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.
usbmouse evdev
~~~~~~~~
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.
usbkbd
~~~~~~
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.
wacom
~~~~~ ~~~~~
This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom `` evdev `` is the generic input event interface. It passes the events
PenPartner, that one is handled by the HID driver. Although the Intuos and generated in the kernel straight to the program, with timestamps. The
Graphire tablets claim that they are HID tablets as well, they are not and event codes are the same on all architectures and are hardware
thus need this specific driver .independent.
iforce This is the preferred interface for userspace to consume user
~~~~~~ input, and all clients are encouraged to use it.
A driver for I-Force joysticks and wheels, both over USB and RS232. See :ref: `event-interface` for notes on API.
It includes ForceFeedback support now, even though Immersion
Corp. considers the protocol a trade secret and won't disclose a word
about it.
Event handlers The devices are in /dev/input::
--------------
Event handlers distribute the events from the devices to userland and crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0
kernel, as needed. 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
...
keybdev 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.
keybdev is currently a rather ugly hack that translates the input keyboard
events into architecture-specific keyboard raw mode (Xlated AT Set2 on ~~~~~~~~
x86), and passes them into the handle_scancode function of the
keyboard.c module. This works well enough on all architectures that
keybdev can generate rawmode on, other architectures can be added to
it.
The right way would be to pass the events to keyboard.c directly, `` keyboard `` is in-kernel input handler ad is a part of VT code. It
best if keyboard.c would itself be an event handler. This is done in consumes keyboard keystrokes and handles user input for VT consoles.
the input patch, available on the webpage mentioned below.
mousedev mousedev
~~~~~~~~ ~~~~~~~~
mousedev is also a hack to make programs that use mouse input`` mousedev `` is a hack to make legacy
work. It takes events from either mice or digitizers/tablets and makes 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 a PS/2-style (a la /dev/psaux) mouse device available to the
userland. Ideally, the programs could use a more reasonable interface, userland.
for example evdev
Mousedev devices in /dev/input (as shown above) are:: Mousedev devices in /dev/input (as shown above) are::
@ -190,8 +134,9 @@ Mousedev devices in /dev/input (as shown above) are::
Each `` mouse `` device is assigned to a single mouse or digitizer, except Each `` mouse `` device is assigned to a single mouse or digitizer, except
the last one - `` mice `` . This single character device is shared by all the last one - `` mice `` . This single character device is shared by all
mice and digitizers, and even if none are connected, the device is mice and digitizers, and even if none are connected, the device is
present. This is useful for hotplugging USB mice, so that programs present. This is useful for hotplugging USB mice, so that older programs
can open the device even when no mice are present. that do not handle hotplug can open the device even when no mice are
present.
CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
the size of your screen (in pixels) in XFree86. This is needed if you the size of your screen (in pixels) in XFree86. This is needed if you
@ -208,11 +153,10 @@ mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.
joydev joydev
~~~~~~ ~~~~~~
Joydev implements v0.x and v1.x Linux joystick api, much like `` joydev `` implements v0.x and v1.x Linux joystick API. See
drivers/char/joystick/joystick.c used to in earlier versions. See :ref: `joystick-api` for details.
joystick-api.txt in the Documentation subdirectory for details. As
soon as any joystick is connected, it can be accessed in /dev/input As soon as any joystick is connected, it can be accessed in /dev/input on::
on::
crw-r--r-- 1 root root 13, 0 Apr 1 10:50 js0 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, 1 Apr 1 10:50 js1
@ -220,56 +164,99 @@ on::
crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3 crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3
... ...
And so on up to js31. And so on up to js31 in legacy range, and additional nodes with minors
above 256 if there are more joystick devices.
evdev Device drivers
~~~~~ --------------
evdev is the generic input event interface. It passes the events Device drivers are the modules that generate events.
generated in the kernel straight to the program, with timestamps. The
API is still evolving, but should be usable now. It's described in
section 5.
This should be the way for GPM and X to get keyboard and mouse hid-generic
events. It allows for multihead in X without any specific multihead ~~~~~~~~~~~
kernel support. The event codes are the same on all architectures and
are hardware independent.
The devices are in /dev/input:: `` hid-generic `` 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.
crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0 Currently, it handles USB mice, joysticks, gamepads, steering wheels
crw-r--r-- 1 root root 13, 65 Apr 1 10:50 event1 keyboards, trackballs and digitizers.
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 However, USB uses HID also for monitor controls, speaker controls, UPSs,
... LCDs and many other purposes.
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 Documentation/hid/hiddev.txt
for more information about it.
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.
And so on up to event31. 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.
usbmouse
~~~~~~~~
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.
usbkbd
~~~~~~
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.
psmouse
~~~~~~~
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.
atkbd
~~~~~
This is driver for PS/2 (AT) keyboards.
iforce
~~~~~~
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.
Verifying if it works Verifying if it works
===================== =====================
Typing a couple keys on the keyboard should be enough to check that Typing a couple keys on the keyboard should be enough to check that
a USB keyboard works and is correctly connected to the kernel keyboard a keyboard works and is correctly connected to the kernel keyboard
driver. driver.
Doing a `` cat /dev/input/mouse0 `` (c, 13, 32) will verify that a mouse Doing a `` cat /dev/input/mouse0 `` (c, 13, 32) will verify that a mouse
is also emulated; characters should appear if you move it. is also emulated; characters should appear if you move it.
You can test the joystick emulation with the `` jstest `` utility, You can test the joystick emulation with the `` jstest `` utility,
available in the joystick package (see Documentation/input/joystick.txt). available in the joystick package (see :ref: `joystick-doc`
You can test the event devices with the `` evtest `` utility available You can test the event devices with the `` evtest `` utility.
in the LinuxConsole project CVS archive (see the URL below).
.. _event-interface:
Event interface Event interface
=============== ===============
Should you want to add event device support into any application (X, gpm, You can use blocking and nonblocking reads, and also select() on the
svgalib ...) I <vojtech@ucw.cz> will be happy to provide you any help I
can. Here goes a description of the current state of things, which is going
to be extended, but not changed incompatibly as time goes:
You can use blocking and nonblocking reads, also select() on the
/dev/input/eventX devices, and you'll always get a whole number of input /dev/input/eventX devices, and you'll always get a whole number of input
events on a read. Their layout is:: events on a read. Their layout is::
@ -290,3 +277,5 @@ list is in include/uapi/linux/input-event-codes.h.
`` value `` is the value the event carries. Either a relative change for`` value `` 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 EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
release, 1 for keypress and 2 for autorepeat. release, 1 for keypress and 2 for autorepeat.
See :ref: `input-event-codes` for more information about various even codes.
Dmitry Torokhov
8 years ago