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