PageRenderTime 21ms CodeModel.GetById 17ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 0ms

Plain Text | 312 lines | 245 code | 67 blank | 0 comment | 0 complexity | 7a1799cfa65bece4edcde2074374fc23 MD5 | raw file
  1			  Linux Input drivers v1.0
  2	       (c) 1999-2001 Vojtech Pavlik <>
  3			     Sponsored by SuSE
  4	    $Id: input.txt,v 1.8 2002/05/29 03:15:01 bradleym Exp $
  70. Disclaimer
  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.
 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.
 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
 23  Should you need to contact me, the author, you can do so either by e-mail
 24- mail your message to <>, or by paper mail: Vojtech Pavlik,
 25Simunkova 1594, Prague 8, 182 00 Czech Republic
 27  For your convenience, the GNU General Public License version 2 is included
 28in the package: See the file COPYING.
 301. Introduction
 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/.
 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:
 421.1 Device drivers
 44  These modules talk to the hardware (for example via USB), and provide
 45events (keystrokes, mouse movements) to the input module.
 471.2 Event handlers
 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.
 532. Simple Usage
 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
 59	input
 60	mousedev
 61	keybdev
 62	usbcore
 63	uhci_hcd or ohci_hcd or ehci_hcd
 64	usbhid
 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:
 69	crw-r--r--   1 root     root      13,  63 Mar 28 22:45 mice
 71  This device has to be created, unless you use devfs, in which case it's
 72created automatically. The commands to do create it by hand are:
 74	cd /dev
 75	mkdir input
 76	mknod input/mice c 13 63
 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:
 81	gpm -t ps2 -m /dev/input/mice
 83  And in X:
 85	Section "Pointer"
 86	    Protocol    "ImPS/2"
 87	    Device      "/dev/input/mice"
 88	    ZAxisMapping 4 5
 89	EndSection
 91  When you do all of the above, you can use your USB mouse and keyboard.
 933. Detailed Description
 953.1 Device drivers
 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.
1013.1.1 usbhid
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.
107  Currently, it handles USB mice, joysticks, gamepads, steering wheels
108keyboards, trackballs and digitizers.
110 However, USB uses HID also for monitor controls, speaker controls, UPSs,
111LCDs and many other purposes.
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.
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.
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.
1263.1.2 usbmouse
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
1353.1.3 usbkbd
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.
1413.1.4 wacom
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.
1483.1.5 iforce
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. 
1553.2 Event handlers
157  Event handlers distrubite the events from the devices to userland and
158kernel, as needed.
1603.2.1 keybdev
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
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. 
1733.2.2 mousedev
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
181  Mousedev devices in /dev/input (as shown above) are:
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
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.
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.
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. 
2103.2.3 joydev
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
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	...
224And so on up to js31.
2263.2.4 evdev
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. 
233  This should be the way for GPM and X to get keyboard and mouse 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.
238  The devices are in /dev/input:
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	...
246And so on up to event31.
2484. Verifying if it works
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
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.
257  You can test the joystick emulation with the 'jstest' utility,
258available in the joystick package (see Documentation/input/joystick.txt).
260  You can test the event devices with the 'evtest' utility available
261in the LinuxConsole project CVS archive (see the URL below).
2635. Event interface
265  Should you want to add event device support into any application (X, gpm,
266svgalib ...) I <> 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:
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:
274struct input_event {
275	struct timeval time;
276	unsigned short type;
277	unsigned short code;
278	unsigned int value;
281  'time' is the timestamp, it returns the time at which the event happened.
282Type is for example EV_REL for relative momement, REL_KEY for a keypress or
283release. More types are defined in include/linux/input.h.
285  'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
286list is in include/linux/input.h.
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.
2926. Contacts
294  This effort has its home page at:
298You'll find both the latest HID driver and the complete Input driver
299there as well as information how to access the CVS repository for
300latest revisions of the drivers.
302  There is also a mailing list for this:
306Send "subscribe linux-input" to subscribe to it.
308The input changes are also being worked on as part of the LinuxConsole
309project, see: