Documentation/input/input.rst

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