Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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.8 2002/05/29 03:15:01 bradleym Exp $ |
| 5 | ---------------------------------------------------------------------------- |
| 6 | |
| 7 | 0. Disclaimer |
| 8 | ~~~~~~~~~~~~~ |
| 9 | This program is free software; you can redistribute it and/or modify it |
| 10 | under the terms of the GNU General Public License as published by the Free |
| 11 | Software Foundation; either version 2 of the License, or (at your option) |
| 12 | any later version. |
| 13 | |
| 14 | This program is distributed in the hope that it will be useful, but |
| 15 | WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY |
| 16 | or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for |
| 17 | more details. |
| 18 | |
| 19 | You should have received a copy of the GNU General Public License along |
| 20 | with this program; if not, write to the Free Software Foundation, Inc., 59 |
| 21 | Temple 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, |
| 25 | Simunkova 1594, Prague 8, 182 00 Czech Republic |
| 26 | |
| 27 | For your convenience, the GNU General Public License version 2 is included |
| 28 | in the package: See the file COPYING. |
| 29 | |
| 30 | 1. Introduction |
| 31 | ~~~~~~~~~~~~~~~ |
| 32 | This is a collection of drivers that is designed to support all input |
| 33 | devices under Linux. While it is currently used only on for USB input |
| 34 | devices, future use (say 2.5/2.6) is expected to expand to replace |
| 35 | most of the existing input system, which is why it lives in |
| 36 | drivers/input/ instead of drivers/usb/. |
| 37 | |
| 38 | The centre of the input drivers is the input module, which must be |
| 39 | loaded before any other of the input modules - it serves as a way of |
| 40 | communication between two groups of modules: |
| 41 | |
| 42 | 1.1 Device drivers |
| 43 | ~~~~~~~~~~~~~~~~~~ |
| 44 | These modules talk to the hardware (for example via USB), and provide |
| 45 | events (keystrokes, mouse movements) to the input module. |
| 46 | |
| 47 | 1.2 Event handlers |
| 48 | ~~~~~~~~~~~~~~~~~~ |
| 49 | These modules get events from input and pass them where needed via |
| 50 | various interfaces - keystrokes to the kernel, mouse movements via a |
| 51 | simulated PS/2 interface to GPM and X and so on. |
| 52 | |
| 53 | 2. Simple Usage |
| 54 | ~~~~~~~~~~~~~~~ |
| 55 | For the most usual configuration, with one USB mouse and one USB keyboard, |
| 56 | you'll have to load the following modules (or have them built in to the |
| 57 | kernel): |
| 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 |
| 67 | will 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 | |
Adrian Bunk | bf6ee0a | 2006-10-03 22:17:48 +0200 | [diff] [blame^] | 71 | This device has to be created. |
| 72 | The commands to create it by hand are: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 |
| 79 | XFree 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 | |
| 93 | 3. Detailed Description |
| 94 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 95 | 3.1 Device drivers |
| 96 | ~~~~~~~~~~~~~~~~~~ |
| 97 | Device drivers are the modules that generate events. The events are |
| 98 | however not useful without being handled, so you also will need to use some |
| 99 | of the modules from section 3.2. |
| 100 | |
| 101 | 3.1.1 usbhid |
| 102 | ~~~~~~~~~~~~ |
| 103 | usbhid is the largest and most complex driver of the whole suite. It |
| 104 | handles all HID devices, and because there is a very wide variety of them, |
| 105 | and 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 |
| 108 | keyboards, trackballs and digitizers. |
| 109 | |
| 110 | However, USB uses HID also for monitor controls, speaker controls, UPSs, |
| 111 | LCDs and many other purposes. |
| 112 | |
| 113 | The monitor and speaker controls should be easy to add to the hid/input |
| 114 | interface, but for the UPSs and LCDs it doesn't make much sense. For this, |
| 115 | the hiddev interface was designed. See Documentation/usb/hiddev.txt |
| 116 | for more information about it. |
| 117 | |
| 118 | The usage of the usbhid module is very simple, it takes no parameters, |
| 119 | detects everything automatically and when a HID device is inserted, it |
| 120 | detects it appropriately. |
| 121 | |
| 122 | However, because the devices vary wildly, you might happen to have a |
| 123 | device that doesn't work well. In that case #define DEBUG at the beginning |
| 124 | of hid-core.c and send me the syslog traces. |
| 125 | |
| 126 | 3.1.2 usbmouse |
| 127 | ~~~~~~~~~~~~~~ |
| 128 | For embedded systems, for mice with broken HID descriptors and just any |
| 129 | other use when the big usbhid wouldn't be a good choice, there is the |
| 130 | usbmouse driver. It handles USB mice only. It uses a simpler HIDBP |
| 131 | protocol. This also means the mice must support this simpler protocol. Not |
| 132 | all do. If you don't have any strong reason to use this module, use usbhid |
| 133 | instead. |
| 134 | |
| 135 | 3.1.3 usbkbd |
| 136 | ~~~~~~~~~~~~ |
| 137 | Much like usbmouse, this module talks to keyboards with a simplified |
| 138 | HIDBP protocol. It's smaller, but doesn't support any extra special keys. |
| 139 | Use usbhid instead if there isn't any special reason to use this. |
| 140 | |
| 141 | 3.1.4 wacom |
| 142 | ~~~~~~~~~~~ |
| 143 | This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom |
| 144 | PenPartner, that one is handled by the HID driver. Although the Intuos and |
| 145 | Graphire tablets claim that they are HID tablets as well, they are not and |
| 146 | thus need this specific driver. |
| 147 | |
| 148 | 3.1.5 iforce |
| 149 | ~~~~~~~~~~~~ |
| 150 | A driver for I-Force joysticks and wheels, both over USB and RS232. |
| 151 | It includes ForceFeedback support now, even though Immersion |
| 152 | Corp. considers the protocol a trade secret and won't disclose a word |
| 153 | about it. |
| 154 | |
| 155 | 3.2 Event handlers |
| 156 | ~~~~~~~~~~~~~~~~~~ |
| 157 | Event handlers distrubite the events from the devices to userland and |
| 158 | kernel, as needed. |
| 159 | |
| 160 | 3.2.1 keybdev |
| 161 | ~~~~~~~~~~~~~ |
| 162 | keybdev is currently a rather ugly hack that translates the input |
| 163 | events into architecture-specific keyboard raw mode (Xlated AT Set2 on |
| 164 | x86), and passes them into the handle_scancode function of the |
| 165 | keyboard.c module. This works well enough on all architectures that |
| 166 | keybdev can generate rawmode on, other architectures can be added to |
| 167 | it. |
| 168 | |
| 169 | The right way would be to pass the events to keyboard.c directly, |
| 170 | best if keyboard.c would itself be an event handler. This is done in |
| 171 | the input patch, available on the webpage mentioned below. |
| 172 | |
| 173 | 3.2.2 mousedev |
| 174 | ~~~~~~~~~~~~~~ |
| 175 | mousedev is also a hack to make programs that use mouse input |
| 176 | work. It takes events from either mice or digitizers/tablets and makes |
| 177 | a PS/2-style (a la /dev/psaux) mouse device available to the |
| 178 | userland. Ideally, the programs could use a more reasonable interface, |
| 179 | for 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 | |
| 192 | Each 'mouse' device is assigned to a single mouse or digitizer, except |
| 193 | the last one - 'mice'. This single character device is shared by all |
| 194 | mice and digitizers, and even if none are connected, the device is |
| 195 | present. This is useful for hotplugging USB mice, so that programs |
| 196 | can open the device even when no mice are present. |
| 197 | |
| 198 | CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are |
| 199 | the size of your screen (in pixels) in XFree86. This is needed if you |
| 200 | want to use your digitizer in X, because its movement is sent to X |
| 201 | via a virtual PS/2 mouse and thus needs to be scaled |
| 202 | accordingly. 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 |
| 205 | ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the |
| 206 | program reading the data wishes. You can set GPM and X to any of |
| 207 | these. You'll need ImPS/2 if you want to make use of a wheel on a USB |
| 208 | mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons. |
| 209 | |
| 210 | 3.2.3 joydev |
| 211 | ~~~~~~~~~~~~ |
| 212 | Joydev implements v0.x and v1.x Linux joystick api, much like |
| 213 | drivers/char/joystick/joystick.c used to in earlier versions. See |
| 214 | joystick-api.txt in the Documentation subdirectory for details. As |
| 215 | soon as any joystick is connected, it can be accessed in /dev/input |
| 216 | on: |
| 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 | |
| 224 | And so on up to js31. |
| 225 | |
| 226 | 3.2.4 evdev |
| 227 | ~~~~~~~~~~~ |
| 228 | evdev is the generic input event interface. It passes the events |
| 229 | generated in the kernel straight to the program, with timestamps. The |
| 230 | API is still evolving, but should be useable now. It's described in |
| 231 | section 5. |
| 232 | |
| 233 | This should be the way for GPM and X to get keyboard and mouse mouse |
| 234 | events. It allows for multihead in X without any specific multihead |
| 235 | kernel support. The event codes are the same on all architectures and |
| 236 | are 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 | |
| 246 | And so on up to event31. |
| 247 | |
| 248 | 4. Verifying if it works |
| 249 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 250 | Typing a couple keys on the keyboard should be enough to check that |
| 251 | a USB keyboard works and is correctly connected to the kernel keyboard |
| 252 | driver. |
| 253 | |
| 254 | Doing a cat /dev/input/mouse0 (c, 13, 32) will verify that a mouse |
| 255 | is also emulated, characters should appear if you move it. |
| 256 | |
| 257 | You can test the joystick emulation with the 'jstest' utility, |
| 258 | available in the joystick package (see Documentation/input/joystick.txt). |
| 259 | |
| 260 | You can test the event devices with the 'evtest' utility available |
| 261 | in the LinuxConsole project CVS archive (see the URL below). |
| 262 | |
| 263 | 5. Event interface |
| 264 | ~~~~~~~~~~~~~~~~~~ |
| 265 | Should you want to add event device support into any application (X, gpm, |
| 266 | svgalib ...) I <vojtech@ucw.cz> will be happy to provide you any help I |
| 267 | can. Here goes a description of the current state of things, which is going |
| 268 | to 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 |
| 272 | events on a read. Their layout is: |
| 273 | |
| 274 | struct 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. |
| 282 | Type is for example EV_REL for relative momement, REL_KEY for a keypress or |
| 283 | release. 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 |
| 286 | list is in include/linux/input.h. |
| 287 | |
| 288 | 'value' is the value the event carries. Either a relative change for |
| 289 | EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for |
| 290 | release, 1 for keypress and 2 for autorepeat. |
| 291 | |