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