Documentation/input/input.txt

   1                           Linux Input drivers v1.0
   2                (c) 1999-2001 Vojtech Pavlik <vojtech@suse.cz>
   3                              Sponsored by SuSE
   4             $Id: input.txt,v 1.5 2001/06/06 11:05:33 vojtech 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@suse.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. However, in the current kernels, although it's
  34 possibilities are much bigger, it's limited to USB devices only. This is
  35 also why it resides in the drivers/usb subdirectory.
  36
  37   The center of the input drivers is the input.o module, which must be
  38 loaded before any other of the input modules - it serves as a way of
  39 communication between two groups of modules:
  40
  41 1.1 Device drivers
  42 ~~~~~~~~~~~~~~~~~~
  43   These modules talk to the hardware (for example via USB), and provide
  44 events (keystrokes, mouse movements) to the input.o module.
  45
  46 1.2 Event handlers
  47 ~~~~~~~~~~~~~~~~~~
  48   These modules get events from input.o and pass them where needed via
  49 various interfaces - keystrokes to the kernel, mouse movements via a
  50 simulated PS/2 interface to GPM and X and so on.
  51
  52 2. Simple Usage
  53 ~~~~~~~~~~~~~~~
  54   For the most usual configuration, with one USB mouse and one USB keyboard,
  55 you'll have to load the following modules (or have them built in to the
  56 kernel):
  57
  58         input.o
  59         mousedev.o
  60         keybdev.o
  61         usbcore.o
  62         usb-[uo]hci.o
  63         hid.o
  64
  65   After this, the USB keyboard will work straight away, and the USB mouse
  66 will 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, unless you use devfs, in which case it's
  71 created automatically. The commands to do that 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
  78 XFree 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
  92 3. Detailed Description
  93 ~~~~~~~~~~~~~~~~~~~~~~~
  94 3.1 Device drivers
  95 ~~~~~~~~~~~~~~~~~~
  96   Device drivers are the modules that generate events. The events are
  97 however not useful without being handled, so you also will need to use some
  98 of the modules from section 3.2.
  99
 100 3.1.1 hid.c
 101 ~~~~~~~~~~~
 102   Hid.c is the largest and most complex driver of the whole suite. It
 103 handles all HID devices, and because there is a very wide variety of them,
 104 and 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
 107 keyboards, trackballs and digitizers.
 108
 109  However, USB uses HID also for monitor controls, speaker controls, UPSs,
 110 LCDs and many other purposes.
 111
 112  The monitor and speaker controls should be easy to add to the hid/input
 113 interface, but for the UPSs and LCDs it doesn't make much sense. For this,
 114 the hiddev interface was designed. See Documentation/usb/hiddev.txt
 115 for more information about it.
 116
 117   The usage of the hid.o module is very simple, it takes no parameters,
 118 detects everything automatically and when a HID device is inserted, it
 119 detects it appropriately.
 120
 121   However, because the devices vary wildly, you might happen to have a
 122 device that doesn't work well. In that case #define DEBUG at the beginning
 123 of hid.c and send me the syslog traces.
 124
 125 3.1.2 usbmouse.c
 126 ~~~~~~~~~~~~~~~~
 127   For embedded systems, for mice with broken HID descriptors and just any
 128 other use when the big hid.c wouldn't be a good choice, there is the
 129 usbmouse.c driver. It handles USB mice only. It uses a simpler HIDBP
 130 protocol. This also means the mice must support this simpler protocol. Not
 131 all do. If you don't have any strong reason to use this module, use hid.c
 132 instead.
 133
 134 3.1.3 usbkbd.c
 135 ~~~~~~~~~~~~~~
 136   Much like usbmouse.c, this module talks to keyboards with a simpplified
 137 HIDBP protocol. It's smaller, but doesn't support any extra special keys.
 138 Use hid.c instead if there isn't any special reason to use this.
 139
 140 3.1.4 wacom.c
 141 ~~~~~~~~~~~~~
 142   This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom
 143 PenPartner, that one is handled by the HID driver. Although the Intuos and
 144 Graphire tablets claim that they are HID tablets as well, they are not and
 145 thus need this specific driver.
 146
 147 3.1.5 iforce.c
 148 ~~~~~~~~~~~~~~~
 149   A driver for I-Force joysticks and wheels, both over USB and RS232.
 150 It includes ForceFeedback support now, even though Immersion Corp. considers
 151 the protocol a trade secret and won't disclose a word about it.
 152
 153 3.2 Event handlers
 154 ~~~~~~~~~~~~~~~~~~
 155   Event handlers distrubite the events from the devices to userland and
 156 kernel, as needed.
 157
 158 3.2.1 keybdev.c
 159 ~~~~~~~~~~~~~~~
 160   Keybdev is currently a rather ugly hack that translates the input events
 161 into architecture-specific keyboard raw mode (Xlated AT Set2 on x86), and
 162 passes them into the handle_scancode function of the keyboard.c module. This
 163 works well enough on all architectures that keybdev can generate rawmode on,
 164 other architectures can be added to it.
 165
 166   The right way would be to pass the events to keyboard.c directly, best if
 167 keyboard.c would itself be an event handler. This is done in the input
 168 patch, available on the webpage mentioned below.
 169
 170 3.2.2 mousedev.c
 171 ~~~~~~~~~~~~~~~~
 172   Mousedev is also a hack to make programs that use mouse input work. It
 173 takes events from either mice or digitizers/tablets and makes a PS/2-style
 174 (a la /dev/psaux) mouse device available to the userland. Ideally, the
 175 programs could use a more reasonable interface, for example evdev.c
 176
 177   Mousedev devices in /dev/input (as shown above) are:
 178
 179         crw-r--r--   1 root     root      13,  32 Mar 28 22:45 mouse0
 180         crw-r--r--   1 root     root      13,  33 Mar 29 00:41 mouse1
 181         crw-r--r--   1 root     root      13,  34 Mar 29 00:41 mouse2
 182         crw-r--r--   1 root     root      13,  35 Apr  1 10:50 mouse3
 183         ...
 184         ...
 185         crw-r--r--   1 root     root      13,  62 Apr  1 10:50 mouse30
 186         crw-r--r--   1 root     root      13,  63 Apr  1 10:50 mice
 187
 188 Each 'mouse' device is assigned to a single mouse or digitizer, except the last
 189 one - 'mice'. This single character device is shared by all mice and
 190 digitizers, and even if none are connected, the device is present.  This is
 191 useful for hotplugging USB mice, so that programs can open the device even when
 192 no mice are present.
 193
 194   CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are the size
 195 of your screen (in pixels) in XFree86. This is needed if you want to use
 196 your digitizer in X, because it's movement is sent to X via a virtual PS/2
 197 mouse and thus needs to be scaled accordingly. These values won't be used if
 198 you use a mouse only.
 199
 200   Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
 201 ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the program
 202 reading the data wishes. You can set GPM and X to any of these. You'll need
 203 ImPS/2 if you want to make use of a wheel on a USB mouse and ExplorerPS/2 if you
 204 want to use extra (up to 5) buttons.
 205
 206 3.2.3 joydev.c
 207 ~~~~~~~~~~~~~~
 208   Joydev implements v0.x and v1.x Linux joystick api, much like
 209 drivers/char/joystick/joystick.c used to in earlier versions. See
 210 joystick-api.txt in the Documentation subdirectory for details.  As soon as
 211 any joystick is connected, it can be accessed in /dev/input on:
 212
 213         crw-r--r--   1 root     root      13,   0 Apr  1 10:50 js0
 214         crw-r--r--   1 root     root      13,   1 Apr  1 10:50 js1
 215         crw-r--r--   1 root     root      13,   2 Apr  1 10:50 js2
 216         crw-r--r--   1 root     root      13,   3 Apr  1 10:50 js3
 217         ...
 218
 219 And so on up to js31.
 220
 221 3.2.4 evdev.c
 222 ~~~~~~~~~~~~~
 223   Evdev is the generic input event interface. It passes the events generated
 224 in the kernel straight to the program, with timestamps. The API is still
 225 evolving, but should be useable now. It's described in section 5.
 226
 227   This should be the way for GPM and X to get keyboard and mouse mouse
 228 events. It allows for multihead in X without any specific multihead kernel
 229 support. The event codes are the same on all architectures and are hardware
 230 independent.
 231
 232   The devices are in /dev/input:
 233
 234         crw-r--r--   1 root     root      13,  64 Apr  1 10:49 event0
 235         crw-r--r--   1 root     root      13,  65 Apr  1 10:50 event1
 236         crw-r--r--   1 root     root      13,  66 Apr  1 10:50 event2
 237         crw-r--r--   1 root     root      13,  67 Apr  1 10:50 event3
 238         ...
 239
 240 3. Contacts
 241 ~~~~~~~~~~~
 242   This effort has it's home page at:
 243
 244         http://www.suse.cz/development/input/
 245
 246 You'll find both the latest HID driver and the complete Input driver there
 247 as well as information how to access the CVS repository for latest revisions
 248 of the drivers.
 249
 250   There is also a mailing list for this:
 251
 252         majordomo@atrey.karlin.mff.cuni.cz
 253
 254 Send "subscribe linux-input" to subscribe to it.
 255
 256 4. Verifying if it works
 257 ~~~~~~~~~~~~~~~~~~~~~~~~
 258   Typing a couple keys on the keyboard should be enough to check that a USB
 259 keyboard works and is correctly connected to the kernel keyboard driver.
 260
 261   Doing a cat /dev/input/mouse0 (c, 13, 32) will verify that a mouse is also
 262 emulated, characters should appear if you move it.
 263
 264   You can test the joystick emulation with the 'jstest' utility, available
 265 in the joystick package (see Documentation/joystick.txt).
 266
 267   You can test the event devics with the 'evtest' utitily available on the
 268 input driver homepage (see the URL above).
 269
 270 5. Event interface
 271 ~~~~~~~~~~~~~~~~~~
 272   Should you want to add event device support into any application (X, gpm,
 273 svgalib ...) I <vojtech@suse.cz> will be happy to provide you any help I
 274 can. Here goes a description of the current state of things, which is going
 275 to be extended, but not changed incompatibly as time goes:
 276
 277   You can use blocking and nonblocking reads, also select() on the
 278 /dev/input/eventX devices, and you'll always get a whole number of input
 279 events on a read. Their layout is:
 280
 281 struct input_event {
 282         struct timeval time;
 283         unsigned short type;
 284         unsigned short code;
 285         unsigned int value;
 286 };
 287
 288   'time' is the timestamp, it returns the time at which the event happened.
 289 Type is for example EV_REL for relative momement, REL_KEY for a keypress or
 290 release. More types are defined in include/linux/input.h.
 291
 292   'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
 293 list is in include/linux/input.h.
 294
 295   'value' is the value the event carries. Either a relative change for
 296 EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
 297 release, 1 for keypress and 2 for autorepeat.