linux/Documentation/input/input.txt
<<
>>
Prefs
   1                          Linux Input drivers v1.0
   2               (c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz>
   3                             Sponsored by SuSE
   4----------------------------------------------------------------------------
   5
   60. Disclaimer
   7~~~~~~~~~~~~~
   8  This program is free software; you can redistribute it and/or modify it
   9under the terms of the GNU General Public License as published by the Free
  10Software Foundation; either version 2 of the License, or (at your option)
  11any later version.
  12
  13  This program is distributed in the hope that it will be useful, but
  14WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  15or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  16more details.
  17
  18  You should have received a copy of the GNU General Public License along
  19with this program; if not, write to the Free Software Foundation, Inc., 59
  20Temple Place, Suite 330, Boston, MA 02111-1307 USA
  21
  22  Should you need to contact me, the author, you can do so either by e-mail
  23- mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,
  24Simunkova 1594, Prague 8, 182 00 Czech Republic
  25
  26  For your convenience, the GNU General Public License version 2 is included
  27in the package: See the file COPYING.
  28
  291. Introduction
  30~~~~~~~~~~~~~~~
  31  This is a collection of drivers that is designed to support all input
  32devices under Linux. While it is currently used only on for USB input
  33devices, future use (say 2.5/2.6) is expected to expand to replace
  34most of the existing input system, which is why it lives in
  35drivers/input/ instead of drivers/usb/.
  36
  37  The centre of the input drivers is the input module, which must be
  38loaded before any other of the input modules - it serves as a way of
  39communication between two groups of modules:
  40
  411.1 Device drivers
  42~~~~~~~~~~~~~~~~~~
  43  These modules talk to the hardware (for example via USB), and provide
  44events (keystrokes, mouse movements) to the input module.
  45
  461.2 Event handlers
  47~~~~~~~~~~~~~~~~~~
  48  These modules get events from input and pass them where needed via
  49various interfaces - keystrokes to the kernel, mouse movements via a
  50simulated PS/2 interface to GPM and X and so on.
  51
  522. Simple Usage
  53~~~~~~~~~~~~~~~
  54  For the most usual configuration, with one USB mouse and one USB keyboard,
  55you'll have to load the following modules (or have them built in to the
  56kernel):
  57
  58        input
  59        mousedev
  60        keybdev
  61        usbcore
  62        uhci_hcd or ohci_hcd or ehci_hcd
  63        usbhid
  64
  65  After this, the USB keyboard will work straight away, and the USB mouse
  66will be available as a character device on major 13, minor 63:
  67
  68        crw-r--r--   1 root     root      13,  63 Mar 28 22:45 mice
  69
  70  This device has to be created.
  71  The commands to create it by hand are:
  72
  73        cd /dev
  74        mkdir input
  75        mknod input/mice c 13 63
  76
  77  After that you have to point GPM (the textmode mouse cut&paste tool) and
  78XFree to this device to use it - GPM should be called like:
  79
  80        gpm -t ps2 -m /dev/input/mice
  81
  82  And in X:
  83
  84        Section "Pointer"
  85            Protocol    "ImPS/2"
  86            Device      "/dev/input/mice"
  87            ZAxisMapping 4 5
  88        EndSection
  89
  90  When you do all of the above, you can use your USB mouse and keyboard.
  91
  923. Detailed Description
  93~~~~~~~~~~~~~~~~~~~~~~~
  943.1 Device drivers
  95~~~~~~~~~~~~~~~~~~
  96  Device drivers are the modules that generate events. The events are
  97however not useful without being handled, so you also will need to use some
  98of the modules from section 3.2.
  99
 1003.1.1 usbhid
 101~~~~~~~~~~~~
 102  usbhid is the largest and most complex driver of the whole suite. It
 103handles all HID devices, and because there is a very wide variety of them,
 104and because the USB HID specification isn't simple, it needs to be this big.
 105
 106  Currently, it handles USB mice, joysticks, gamepads, steering wheels
 107keyboards, trackballs and digitizers.
 108
 109 However, USB uses HID also for monitor controls, speaker controls, UPSs,
 110LCDs and many other purposes.
 111
 112 The monitor and speaker controls should be easy to add to the hid/input
 113interface, but for the UPSs and LCDs it doesn't make much sense. For this,
 114the hiddev interface was designed. See Documentation/hid/hiddev.txt
 115for more information about it.
 116
 117  The usage of the usbhid module is very simple, it takes no parameters,
 118detects everything automatically and when a HID device is inserted, it
 119detects it appropriately.
 120
 121  However, because the devices vary wildly, you might happen to have a
 122device that doesn't work well. In that case #define DEBUG at the beginning
 123of hid-core.c and send me the syslog traces.
 124
 1253.1.2 usbmouse
 126~~~~~~~~~~~~~~
 127  For embedded systems, for mice with broken HID descriptors and just any
 128other use when the big usbhid wouldn't be a good choice, there is the
 129usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
 130protocol. This also means the mice must support this simpler protocol. Not
 131all do. If you don't have any strong reason to use this module, use usbhid
 132instead.
 133
 1343.1.3 usbkbd
 135~~~~~~~~~~~~
 136  Much like usbmouse, this module talks to keyboards with a simplified
 137HIDBP protocol. It's smaller, but doesn't support any extra special keys.
 138Use usbhid instead if there isn't any special reason to use this.
 139
 1403.1.4 wacom
 141~~~~~~~~~~~
 142  This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom
 143PenPartner, that one is handled by the HID driver. Although the Intuos and
 144Graphire tablets claim that they are HID tablets as well, they are not and
 145thus need this specific driver.
 146
 1473.1.5 iforce
 148~~~~~~~~~~~~
 149  A driver for I-Force joysticks and wheels, both over USB and RS232. 
 150It includes ForceFeedback support now, even though Immersion
 151Corp. considers the protocol a trade secret and won't disclose a word
 152about it. 
 153
 1543.2 Event handlers
 155~~~~~~~~~~~~~~~~~~
 156  Event handlers distribute the events from the devices to userland and
 157kernel, as needed.
 158
 1593.2.1 keybdev
 160~~~~~~~~~~~~~
 161  keybdev is currently a rather ugly hack that translates the input
 162events into architecture-specific keyboard raw mode (Xlated AT Set2 on
 163x86), and passes them into the handle_scancode function of the
 164keyboard.c module. This works well enough on all architectures that
 165keybdev can generate rawmode on, other architectures can be added to
 166it.
 167
 168  The right way would be to pass the events to keyboard.c directly,
 169best if keyboard.c would itself be an event handler. This is done in
 170the input patch, available on the webpage mentioned below. 
 171
 1723.2.2 mousedev
 173~~~~~~~~~~~~~~
 174  mousedev is also a hack to make programs that use mouse input
 175work. It takes events from either mice or digitizers/tablets and makes
 176a PS/2-style (a la /dev/psaux) mouse device available to the
 177userland. Ideally, the programs could use a more reasonable interface,
 178for example evdev
 179
 180  Mousedev devices in /dev/input (as shown above) are:
 181
 182        crw-r--r--   1 root     root      13,  32 Mar 28 22:45 mouse0
 183        crw-r--r--   1 root     root      13,  33 Mar 29 00:41 mouse1
 184        crw-r--r--   1 root     root      13,  34 Mar 29 00:41 mouse2
 185        crw-r--r--   1 root     root      13,  35 Apr  1 10:50 mouse3
 186        ...
 187        ...
 188        crw-r--r--   1 root     root      13,  62 Apr  1 10:50 mouse30
 189        crw-r--r--   1 root     root      13,  63 Apr  1 10:50 mice
 190
 191Each 'mouse' device is assigned to a single mouse or digitizer, except
 192the last one - 'mice'. This single character device is shared by all
 193mice and digitizers, and even if none are connected, the device is
 194present.  This is useful for hotplugging USB mice, so that programs
 195can open the device even when no mice are present.
 196
 197  CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
 198the size of your screen (in pixels) in XFree86. This is needed if you
 199want to use your digitizer in X, because its movement is sent to X
 200via a virtual PS/2 mouse and thus needs to be scaled
 201accordingly. These values won't be used if you use a mouse only.
 202
 203  Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
 204ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
 205program reading the data wishes. You can set GPM and X to any of
 206these. You'll need ImPS/2 if you want to make use of a wheel on a USB
 207mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons. 
 208
 2093.2.3 joydev
 210~~~~~~~~~~~~
 211  Joydev implements v0.x and v1.x Linux joystick api, much like
 212drivers/char/joystick/joystick.c used to in earlier versions. See
 213joystick-api.txt in the Documentation subdirectory for details.  As
 214soon as any joystick is connected, it can be accessed in /dev/input
 215on: 
 216
 217        crw-r--r--   1 root     root      13,   0 Apr  1 10:50 js0
 218        crw-r--r--   1 root     root      13,   1 Apr  1 10:50 js1
 219        crw-r--r--   1 root     root      13,   2 Apr  1 10:50 js2
 220        crw-r--r--   1 root     root      13,   3 Apr  1 10:50 js3
 221        ...
 222
 223And so on up to js31.
 224
 2253.2.4 evdev
 226~~~~~~~~~~~
 227  evdev is the generic input event interface. It passes the events
 228generated in the kernel straight to the program, with timestamps. The
 229API is still evolving, but should be useable now. It's described in
 230section 5. 
 231
 232  This should be the way for GPM and X to get keyboard and mouse
 233events. It allows for multihead in X without any specific multihead
 234kernel support. The event codes are the same on all architectures and
 235are hardware independent.
 236
 237  The devices are in /dev/input:
 238
 239        crw-r--r--   1 root     root      13,  64 Apr  1 10:49 event0
 240        crw-r--r--   1 root     root      13,  65 Apr  1 10:50 event1
 241        crw-r--r--   1 root     root      13,  66 Apr  1 10:50 event2
 242        crw-r--r--   1 root     root      13,  67 Apr  1 10:50 event3
 243        ...
 244
 245And so on up to event31.
 246
 2474. Verifying if it works
 248~~~~~~~~~~~~~~~~~~~~~~~~
 249  Typing a couple keys on the keyboard should be enough to check that
 250a USB keyboard works and is correctly connected to the kernel keyboard
 251driver. 
 252
 253  Doing a "cat /dev/input/mouse0" (c, 13, 32) will verify that a mouse
 254is also emulated; characters should appear if you move it.
 255
 256  You can test the joystick emulation with the 'jstest' utility,
 257available in the joystick package (see Documentation/input/joystick.txt).
 258
 259  You can test the event devices with the 'evtest' utility available
 260in the LinuxConsole project CVS archive (see the URL below).
 261
 2625. Event interface
 263~~~~~~~~~~~~~~~~~~
 264  Should you want to add event device support into any application (X, gpm,
 265svgalib ...) I <vojtech@ucw.cz> will be happy to provide you any help I
 266can. Here goes a description of the current state of things, which is going
 267to be extended, but not changed incompatibly as time goes:
 268
 269  You can use blocking and nonblocking reads, also select() on the
 270/dev/input/eventX devices, and you'll always get a whole number of input
 271events on a read. Their layout is:
 272
 273struct input_event {
 274        struct timeval time;
 275        unsigned short type;
 276        unsigned short code;
 277        unsigned int value;
 278};
 279
 280  'time' is the timestamp, it returns the time at which the event happened.
 281Type is for example EV_REL for relative moment, EV_KEY for a keypress or
 282release. More types are defined in include/linux/input.h.
 283
 284  'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
 285list is in include/linux/input.h.
 286
 287  'value' is the value the event carries. Either a relative change for
 288EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
 289release, 1 for keypress and 2 for autorepeat.
 290
 291
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.