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