1 Linux Input drivers v1.0
2 (c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz>
4 ----------------------------------------------------------------------------
8 This program is free software; you can redistribute it and/or modify it
9 under the terms of the GNU General Public License as published by the Free
10 Software Foundation; either version 2 of the License, or (at your option)
13 This program is distributed in the hope that it will be useful, but
14 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
18 You should have received a copy of the GNU General Public License along
19 with this program; if not, write to the Free Software Foundation, Inc., 59
20 Temple Place, Suite 330, Boston, MA 02111-1307 USA
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,
24 Simunkova 1594, Prague 8, 182 00 Czech Republic
26 For your convenience, the GNU General Public License version 2 is included
27 in the package: See the file COPYING.
31 This is a collection of drivers that is designed to support all input
32 devices under Linux. While it is currently used only on for USB input
33 devices, future use (say 2.5/2.6) is expected to expand to replace
34 most of the existing input system, which is why it lives in
35 drivers/input/ instead of drivers/usb/.
37 The centre of the input drivers is the input module, which must be
38 loaded before any other of the input modules - it serves as a way of
39 communication between two groups of modules:
43 These modules talk to the hardware (for example via USB), and provide
44 events (keystrokes, mouse movements) to the input module.
48 These modules get events from input and pass them where needed via
49 various interfaces - keystrokes to the kernel, mouse movements via a
50 simulated PS/2 interface to GPM and X and so on.
54 For the most usual configuration, with one USB mouse and one USB keyboard,
55 you'll have to load the following modules (or have them built in to the
62 uhci_hcd or ohci_hcd or ehci_hcd
65 After this, the USB keyboard will work straight away, and the USB mouse
66 will be available as a character device on major 13, minor 63:
68 crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice
70 This device has to be created.
71 The commands to create it by hand are:
75 mknod input/mice c 13 63
77 After that you have to point GPM (the textmode mouse cut&paste tool) and
78 XFree to this device to use it - GPM should be called like:
80 gpm -t ps2 -m /dev/input/mice
86 Device "/dev/input/mice"
90 When you do all of the above, you can use your USB mouse and keyboard.
92 3. Detailed Description
93 ~~~~~~~~~~~~~~~~~~~~~~~
96 Device drivers are the modules that generate events. The events are
97 however not useful without being handled, so you also will need to use some
98 of the modules from section 3.2.
102 usbhid is the largest and most complex driver of the whole suite. It
103 handles all HID devices, and because there is a very wide variety of them,
104 and because the USB HID specification isn't simple, it needs to be this big.
106 Currently, it handles USB mice, joysticks, gamepads, steering wheels
107 keyboards, trackballs and digitizers.
109 However, USB uses HID also for monitor controls, speaker controls, UPSs,
110 LCDs and many other purposes.
112 The monitor and speaker controls should be easy to add to the hid/input
113 interface, but for the UPSs and LCDs it doesn't make much sense. For this,
114 the hiddev interface was designed. See Documentation/usb/hiddev.txt
115 for more information about it.
117 The usage of the usbhid module is very simple, it takes no parameters,
118 detects everything automatically and when a HID device is inserted, it
119 detects it appropriately.
121 However, because the devices vary wildly, you might happen to have a
122 device that doesn't work well. In that case #define DEBUG at the beginning
123 of hid-core.c and send me the syslog traces.
127 For embedded systems, for mice with broken HID descriptors and just any
128 other use when the big usbhid wouldn't be a good choice, there is the
129 usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
130 protocol. This also means the mice must support this simpler protocol. Not
131 all do. If you don't have any strong reason to use this module, use usbhid
136 Much like usbmouse, this module talks to keyboards with a simplified
137 HIDBP protocol. It's smaller, but doesn't support any extra special keys.
138 Use usbhid instead if there isn't any special reason to use this.
142 This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom
143 PenPartner, that one is handled by the HID driver. Although the Intuos and
144 Graphire tablets claim that they are HID tablets as well, they are not and
145 thus need this specific driver.
149 A driver for I-Force joysticks and wheels, both over USB and RS232.
150 It includes ForceFeedback support now, even though Immersion
151 Corp. considers the protocol a trade secret and won't disclose a word
156 Event handlers distribute the events from the devices to userland and
161 keybdev is currently a rather ugly hack that translates the input
162 events into architecture-specific keyboard raw mode (Xlated AT Set2 on
163 x86), and passes them into the handle_scancode function of the
164 keyboard.c module. This works well enough on all architectures that
165 keybdev can generate rawmode on, other architectures can be added to
168 The right way would be to pass the events to keyboard.c directly,
169 best if keyboard.c would itself be an event handler. This is done in
170 the input patch, available on the webpage mentioned below.
174 mousedev is also a hack to make programs that use mouse input
175 work. It takes events from either mice or digitizers/tablets and makes
176 a PS/2-style (a la /dev/psaux) mouse device available to the
177 userland. Ideally, the programs could use a more reasonable interface,
180 Mousedev devices in /dev/input (as shown above) are:
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
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
191 Each 'mouse' device is assigned to a single mouse or digitizer, except
192 the last one - 'mice'. This single character device is shared by all
193 mice and digitizers, and even if none are connected, the device is
194 present. This is useful for hotplugging USB mice, so that programs
195 can open the device even when no mice are present.
197 CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
198 the size of your screen (in pixels) in XFree86. This is needed if you
199 want to use your digitizer in X, because its movement is sent to X
200 via a virtual PS/2 mouse and thus needs to be scaled
201 accordingly. These values won't be used if you use a mouse only.
203 Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
204 ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
205 program reading the data wishes. You can set GPM and X to any of
206 these. You'll need ImPS/2 if you want to make use of a wheel on a USB
207 mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.
211 Joydev implements v0.x and v1.x Linux joystick api, much like
212 drivers/char/joystick/joystick.c used to in earlier versions. See
213 joystick-api.txt in the Documentation subdirectory for details. As
214 soon as any joystick is connected, it can be accessed in /dev/input
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
223 And so on up to js31.
227 evdev is the generic input event interface. It passes the events
228 generated in the kernel straight to the program, with timestamps. The
229 API is still evolving, but should be useable now. It's described in
232 This should be the way for GPM and X to get keyboard and mouse
233 events. It allows for multihead in X without any specific multihead
234 kernel support. The event codes are the same on all architectures and
235 are hardware independent.
237 The devices are in /dev/input:
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
245 And so on up to event31.
247 4. Verifying if it works
248 ~~~~~~~~~~~~~~~~~~~~~~~~
249 Typing a couple keys on the keyboard should be enough to check that
250 a USB keyboard works and is correctly connected to the kernel keyboard
253 Doing a cat /dev/input/mouse0 (c, 13, 32) will verify that a mouse
254 is also emulated, characters should appear if you move it.
256 You can test the joystick emulation with the 'jstest' utility,
257 available in the joystick package (see Documentation/input/joystick.txt).
259 You can test the event devices with the 'evtest' utility available
260 in the LinuxConsole project CVS archive (see the URL below).
264 Should you want to add event device support into any application (X, gpm,
265 svgalib ...) I <vojtech@ucw.cz> will be happy to provide you any help I
266 can. Here goes a description of the current state of things, which is going
267 to be extended, but not changed incompatibly as time goes:
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
271 events on a read. Their layout is:
280 'time' is the timestamp, it returns the time at which the event happened.
281 Type is for example EV_REL for relative moment, EV_KEY for a keypress or
282 release. More types are defined in include/linux/input.h.
284 'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
285 list is in include/linux/input.h.
287 'value' is the value the event carries. Either a relative change for
288 EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
289 release, 1 for keypress and 2 for autorepeat.