Documentation/input/input.rst

   1 .. include:: <isonum.txt>
   2
   3 ============
   4 Introduction
   5 ============
   6
   7 :Copyright: |copy| 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE
   8
   9 Architecture
  10 ============
  11
  12 Input subsystem  a collection of drivers that is designed to support
  13 all input devices under Linux. Most of the drivers reside in
  14 drivers/input, although quite a few live in drivers/hid and
  15 drivers/platform.
  16
  17 The core of the input subsystem is the input module, which must be
  18 loaded before any other of the input modules - it serves as a way of
  19 communication between two groups of modules:
  20
  21 Device drivers
  22 --------------
  23
  24 These modules talk to the hardware (for example via USB), and provide
  25 events (keystrokes, mouse movements) to the input module.
  26
  27 Event handlers
  28 --------------
  29
  30 These modules get events from input core and pass them where needed
  31 via various interfaces - keystrokes to the kernel, mouse movements via
  32 a simulated PS/2 interface to GPM and X, and so on.
  33
  34 Simple Usage
  35 ============
  36
  37 For the most usual configuration, with one USB mouse and one USB keyboard,
  38 you'll have to load the following modules (or have them built in to the
  39 kernel)::
  40
  41         input
  42         mousedev
  43         usbcore
  44         uhci_hcd or ohci_hcd or ehci_hcd
  45         usbhid
  46         hid_generic
  47
  48 After this, the USB keyboard will work straight away, and the USB mouse
  49 will be available as a character device on major 13, minor 63::
  50
  51         crw-r--r--   1 root     root      13,  63 Mar 28 22:45 mice
  52
  53 This device usually created automatically by the system. The commands
  54 to create it by hand are::
  55
  56         cd /dev
  57         mkdir input
  58         mknod input/mice c 13 63
  59
  60 After that you have to point GPM (the textmode mouse cut&paste tool) and
  61 XFree to this device to use it - GPM should be called like::
  62
  63         gpm -t ps2 -m /dev/input/mice
  64
  65 And in X::
  66
  67         Section "Pointer"
  68             Protocol    "ImPS/2"
  69             Device      "/dev/input/mice"
  70             ZAxisMapping 4 5
  71         EndSection
  72
  73 When you do all of the above, you can use your USB mouse and keyboard.
  74
  75 Detailed Description
  76 ====================
  77
  78 Event handlers
  79 --------------
  80
  81 Event handlers distribute the events from the devices to userspace and
  82 in-kernel consumers, as needed.
  83
  84 evdev
  85 ~~~~~
  86
  87 ``evdev`` is the generic input event interface. It passes the events
  88 generated in the kernel straight to the program, with timestamps. The
  89 event codes are the same on all architectures and are hardware
  90 independent.
  91
  92 This is the preferred interface for userspace to consume user
  93 input, and all clients are encouraged to use it.
  94
  95 See :ref:`event-interface` for notes on API.
  96
  97 The devices are in /dev/input::
  98
  99         crw-r--r--   1 root     root      13,  64 Apr  1 10:49 event0
 100         crw-r--r--   1 root     root      13,  65 Apr  1 10:50 event1
 101         crw-r--r--   1 root     root      13,  66 Apr  1 10:50 event2
 102         crw-r--r--   1 root     root      13,  67 Apr  1 10:50 event3
 103         ...
 104
 105 There are two ranges of minors: 64 through 95 is the static legacy
 106 range. If there are more than 32 input devices in a system, additional
 107 evdev nodes are created with minors starting with 256.
 108
 109 keyboard
 110 ~~~~~~~~
 111
 112 ``keyboard`` is in-kernel input handler and is a part of VT code. It
 113 consumes keyboard keystrokes and handles user input for VT consoles.
 114
 115 mousedev
 116 ~~~~~~~~
 117
 118 ``mousedev`` is a hack to make legacy programs that use mouse input
 119 work. It takes events from either mice or digitizers/tablets and makes
 120 a PS/2-style (a la /dev/psaux) mouse device available to the
 121 userland.
 122
 123 Mousedev devices in /dev/input (as shown above) are::
 124
 125         crw-r--r--   1 root     root      13,  32 Mar 28 22:45 mouse0
 126         crw-r--r--   1 root     root      13,  33 Mar 29 00:41 mouse1
 127         crw-r--r--   1 root     root      13,  34 Mar 29 00:41 mouse2
 128         crw-r--r--   1 root     root      13,  35 Apr  1 10:50 mouse3
 129         ...
 130         ...
 131         crw-r--r--   1 root     root      13,  62 Apr  1 10:50 mouse30
 132         crw-r--r--   1 root     root      13,  63 Apr  1 10:50 mice
 133
 134 Each ``mouse`` device is assigned to a single mouse or digitizer, except
 135 the last one - ``mice``. This single character device is shared by all
 136 mice and digitizers, and even if none are connected, the device is
 137 present.  This is useful for hotplugging USB mice, so that older programs
 138 that do not handle hotplug can open the device even when no mice are
 139 present.
 140
 141 CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
 142 the size of your screen (in pixels) in XFree86. This is needed if you
 143 want to use your digitizer in X, because its movement is sent to X
 144 via a virtual PS/2 mouse and thus needs to be scaled
 145 accordingly. These values won't be used if you use a mouse only.
 146
 147 Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
 148 ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
 149 program reading the data wishes. You can set GPM and X to any of
 150 these. You'll need ImPS/2 if you want to make use of a wheel on a USB
 151 mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.
 152
 153 joydev
 154 ~~~~~~
 155
 156 ``joydev`` implements v0.x and v1.x Linux joystick API. See
 157 :ref:`joystick-api` for details.
 158
 159 As soon as any joystick is connected, it can be accessed in /dev/input on::
 160
 161         crw-r--r--   1 root     root      13,   0 Apr  1 10:50 js0
 162         crw-r--r--   1 root     root      13,   1 Apr  1 10:50 js1
 163         crw-r--r--   1 root     root      13,   2 Apr  1 10:50 js2
 164         crw-r--r--   1 root     root      13,   3 Apr  1 10:50 js3
 165         ...
 166
 167 And so on up to js31 in legacy range, and additional nodes with minors
 168 above 256 if there are more joystick devices.
 169
 170 Device drivers
 171 --------------
 172
 173 Device drivers are the modules that generate events.
 174
 175 hid-generic
 176 ~~~~~~~~~~~
 177
 178 ``hid-generic`` is one of the largest and most complex driver of the
 179 whole suite. It handles all HID devices, and because there is a very
 180 wide variety of them, and because the USB HID specification isn't
 181 simple, it needs to be this big.
 182
 183 Currently, it handles USB mice, joysticks, gamepads, steering wheels
 184 keyboards, trackballs and digitizers.
 185
 186 However, USB uses HID also for monitor controls, speaker controls, UPSs,
 187 LCDs and many other purposes.
 188
 189 The monitor and speaker controls should be easy to add to the hid/input
 190 interface, but for the UPSs and LCDs it doesn't make much sense. For this,
 191 the hiddev interface was designed. See Documentation/hid/hiddev.rst
 192 for more information about it.
 193
 194 The usage of the usbhid module is very simple, it takes no parameters,
 195 detects everything automatically and when a HID device is inserted, it
 196 detects it appropriately.
 197
 198 However, because the devices vary wildly, you might happen to have a
 199 device that doesn't work well. In that case #define DEBUG at the beginning
 200 of hid-core.c and send me the syslog traces.
 201
 202 usbmouse
 203 ~~~~~~~~
 204
 205 For embedded systems, for mice with broken HID descriptors and just any
 206 other use when the big usbhid wouldn't be a good choice, there is the
 207 usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
 208 protocol. This also means the mice must support this simpler protocol. Not
 209 all do. If you don't have any strong reason to use this module, use usbhid
 210 instead.
 211
 212 usbkbd
 213 ~~~~~~
 214
 215 Much like usbmouse, this module talks to keyboards with a simplified
 216 HIDBP protocol. It's smaller, but doesn't support any extra special keys.
 217 Use usbhid instead if there isn't any special reason to use this.
 218
 219 psmouse
 220 ~~~~~~~
 221
 222 This is driver for all flavors of pointing devices using PS/2
 223 protocol, including Synaptics and ALPS touchpads, Intellimouse
 224 Explorer devices, Logitech PS/2 mice and so on.
 225
 226 atkbd
 227 ~~~~~
 228
 229 This is driver for PS/2 (AT) keyboards.
 230
 231 iforce
 232 ~~~~~~
 233
 234 A driver for I-Force joysticks and wheels, both over USB and RS232.
 235 It includes Force Feedback support now, even though Immersion
 236 Corp. considers the protocol a trade secret and won't disclose a word
 237 about it.
 238
 239 Verifying if it works
 240 =====================
 241
 242 Typing a couple keys on the keyboard should be enough to check that
 243 a keyboard works and is correctly connected to the kernel keyboard
 244 driver.
 245
 246 Doing a ``cat /dev/input/mouse0`` (c, 13, 32) will verify that a mouse
 247 is also emulated; characters should appear if you move it.
 248
 249 You can test the joystick emulation with the ``jstest`` utility,
 250 available in the joystick package (see :ref:`joystick-doc`).
 251
 252 You can test the event devices with the ``evtest`` utility.
 253
 254 .. _event-interface:
 255
 256 Event interface
 257 ===============
 258
 259 You can use blocking and nonblocking reads, and also select() on the
 260 /dev/input/eventX devices, and you'll always get a whole number of input
 261 events on a read. Their layout is::
 262
 263     struct input_event {
 264             struct timeval time;
 265             unsigned short type;
 266             unsigned short code;
 267             unsigned int value;
 268     };
 269
 270 ``time`` is the timestamp, it returns the time at which the event happened.
 271 Type is for example EV_REL for relative moment, EV_KEY for a keypress or
 272 release. More types are defined in include/uapi/linux/input-event-codes.h.
 273
 274 ``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete
 275 list is in include/uapi/linux/input-event-codes.h.
 276
 277 ``value`` is the value the event carries. Either a relative change for
 278 EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
 279 release, 1 for keypress and 2 for autorepeat.
 280
 281 See :ref:`input-event-codes` for more information about various even codes.