Documentation/input/input.txt

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