Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 1 | .. include:: <isonum.txt> |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 2 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 3 | ============ |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 4 | Introduction |
| 5 | ============ |
| 6 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 7 | :Copyright: |copy| 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 8 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 9 | Architecture |
| 10 | ============ |
| 11 | |
Randy Dunlap | d1c34bb | 2021-03-02 14:35:16 -0800 | [diff] [blame] | 12 | Input subsystem is a collection of drivers that is designed to support |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 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 |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 18 | loaded before any other of the input modules - it serves as a way of |
| 19 | communication between two groups of modules: |
| 20 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 21 | Device drivers |
| 22 | -------------- |
| 23 | |
| 24 | These modules talk to the hardware (for example via USB), and provide |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 25 | events (keystrokes, mouse movements) to the input module. |
| 26 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 27 | Event handlers |
| 28 | -------------- |
| 29 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 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. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 33 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 34 | Simple Usage |
| 35 | ============ |
| 36 | |
| 37 | For the most usual configuration, with one USB mouse and one USB keyboard, |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 38 | you'll have to load the following modules (or have them built in to the |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 39 | kernel):: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 40 | |
| 41 | input |
| 42 | mousedev |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 43 | usbcore |
| 44 | uhci_hcd or ohci_hcd or ehci_hcd |
| 45 | usbhid |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 46 | hid_generic |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 47 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 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:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 50 | |
| 51 | crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice |
| 52 | |
Randy Dunlap | d1c34bb | 2021-03-02 14:35:16 -0800 | [diff] [blame] | 53 | This device is usually created automatically by the system. The commands |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 54 | to create it by hand are:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 55 | |
| 56 | cd /dev |
| 57 | mkdir input |
| 58 | mknod input/mice c 13 63 |
| 59 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 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:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 62 | |
| 63 | gpm -t ps2 -m /dev/input/mice |
| 64 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 65 | And in X:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 66 | |
| 67 | Section "Pointer" |
| 68 | Protocol "ImPS/2" |
| 69 | Device "/dev/input/mice" |
| 70 | ZAxisMapping 4 5 |
| 71 | EndSection |
| 72 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 73 | When you do all of the above, you can use your USB mouse and keyboard. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 74 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 75 | Detailed Description |
| 76 | ==================== |
| 77 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 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 | |
John de la Garza | 7dfedba | 2017-08-29 18:48:54 -0700 | [diff] [blame] | 112 | ``keyboard`` is in-kernel input handler and is a part of VT code. It |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 170 | Device drivers |
| 171 | -------------- |
| 172 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 173 | Device drivers are the modules that generate events. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 174 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 175 | hid-generic |
| 176 | ~~~~~~~~~~~ |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 177 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 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. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 182 | |
Randy Dunlap | d1c34bb | 2021-03-02 14:35:16 -0800 | [diff] [blame] | 183 | Currently, it handles USB mice, joysticks, gamepads, steering wheels, |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 184 | keyboards, trackballs and digitizers. |
| 185 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 186 | However, USB uses HID also for monitor controls, speaker controls, UPSs, |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 187 | LCDs and many other purposes. |
| 188 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 189 | The monitor and speaker controls should be easy to add to the hid/input |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 190 | interface, but for the UPSs and LCDs it doesn't make much sense. For this, |
Mauro Carvalho Chehab | cca4786 | 2019-06-28 09:19:59 -0300 | [diff] [blame] | 191 | the hiddev interface was designed. See Documentation/hid/hiddev.rst |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 192 | for more information about it. |
| 193 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 194 | The usage of the usbhid module is very simple, it takes no parameters, |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 195 | detects everything automatically and when a HID device is inserted, it |
| 196 | detects it appropriately. |
| 197 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 198 | However, because the devices vary wildly, you might happen to have a |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 202 | usbmouse |
| 203 | ~~~~~~~~ |
| 204 | |
| 205 | For embedded systems, for mice with broken HID descriptors and just any |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 212 | usbkbd |
| 213 | ~~~~~~ |
| 214 | |
| 215 | Much like usbmouse, this module talks to keyboards with a simplified |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 227 | ~~~~~ |
| 228 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 229 | This is driver for PS/2 (AT) keyboards. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 230 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 231 | iforce |
| 232 | ~~~~~~ |
| 233 | |
| 234 | A driver for I-Force joysticks and wheels, both over USB and RS232. |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 235 | It includes Force Feedback support now, even though Immersion |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 236 | Corp. considers the protocol a trade secret and won't disclose a word |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 237 | about it. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 238 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 239 | Verifying if it works |
| 240 | ===================== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 241 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 242 | Typing a couple keys on the keyboard should be enough to check that |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 243 | a keyboard works and is correctly connected to the kernel keyboard |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 244 | driver. |
| 245 | |
| 246 | Doing a ``cat /dev/input/mouse0`` (c, 13, 32) will verify that a mouse |
Randy Dunlap | 0960152 | 2012-03-30 13:37:13 -0700 | [diff] [blame] | 247 | is also emulated; characters should appear if you move it. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 248 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 249 | You can test the joystick emulation with the ``jstest`` utility, |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 250 | available in the joystick package (see :ref:`joystick-doc`). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 251 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 252 | You can test the event devices with the ``evtest`` utility. |
| 253 | |
| 254 | .. _event-interface: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 255 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 256 | Event interface |
| 257 | =============== |
| 258 | |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 259 | You can use blocking and nonblocking reads, and also select() on the |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 260 | /dev/input/eventX devices, and you'll always get a whole number of input |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 261 | events on a read. Their layout is:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 262 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 263 | struct input_event { |
| 264 | struct timeval time; |
| 265 | unsigned short type; |
| 266 | unsigned short code; |
| 267 | unsigned int value; |
| 268 | }; |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 269 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 270 | ``time`` is the timestamp, it returns the time at which the event happened. |
Randy Dunlap | d1c34bb | 2021-03-02 14:35:16 -0800 | [diff] [blame] | 271 | Type is for example EV_REL for relative movement, EV_KEY for a keypress or |
Martin Kepplinger | da23e4d | 2017-02-09 07:53:29 +0100 | [diff] [blame] | 272 | release. More types are defined in include/uapi/linux/input-event-codes.h. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 273 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 274 | ``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete |
Martin Kepplinger | da23e4d | 2017-02-09 07:53:29 +0100 | [diff] [blame] | 275 | list is in include/uapi/linux/input-event-codes.h. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 276 | |
Mauro Carvalho Chehab | b0f355f | 2017-04-04 17:29:06 -0700 | [diff] [blame] | 277 | ``value`` is the value the event carries. Either a relative change for |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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. |
Dmitry Torokhov | ad64938 | 2017-04-15 15:16:50 -0700 | [diff] [blame] | 280 | |
| 281 | See :ref:`input-event-codes` for more information about various even codes. |