view Documentation/input/input.txt @ 452:c7ed6fe5dca0

kexec: dont initialise regions in reserve_memory()

There is no need to initialise efi_memmap_res and boot_param_res in
reserve_memory() for the initial xen domain as it is done in
machine_kexec_setup_resources() using values from the kexec hypercall.

Signed-off-by: Simon Horman <horms@verge.net.au>
author Keir Fraser <keir.fraser@citrix.com>
date Thu Feb 28 10:55:18 2008 +0000 (2008-02-28)
parents 831230e53067
line source
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 ----------------------------------------------------------------------------
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.
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.
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
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
27 For your convenience, the GNU General Public License version 2 is included
28 in the package: See the file COPYING.
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/.
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:
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.
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.
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):
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
67 will 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
72 created 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
79 XFree 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.
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.
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.
107 Currently, it handles USB mice, joysticks, gamepads, steering wheels
108 keyboards, trackballs and digitizers.
110 However, USB uses HID also for monitor controls, speaker controls, UPSs,
111 LCDs and many other purposes.
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.
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.
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.
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.
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.
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.
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.
155 3.2 Event handlers
156 ~~~~~~~~~~~~~~~~~~
157 Event handlers distrubite the events from the devices to userland and
158 kernel, as needed.
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.
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.
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
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
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.
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.
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.
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:
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 ...
224 And so on up to js31.
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.
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.
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 ...
246 And so on up to event31.
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.
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.
257 You can test the joystick emulation with the 'jstest' utility,
258 available in the joystick package (see Documentation/input/joystick.txt).
260 You can test the event devices with the 'evtest' utility available
261 in the LinuxConsole project CVS archive (see the URL below).
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:
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:
274 struct input_event {
275 struct timeval time;
276 unsigned short type;
277 unsigned short code;
278 unsigned int value;
279 };
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.
285 'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
286 list is in include/linux/input.h.
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.
292 6. Contacts
293 ~~~~~~~~~~~
294 This effort has its home page at:
296 http://www.suse.cz/development/input/
298 You'll find both the latest HID driver and the complete Input driver
299 there as well as information how to access the CVS repository for
300 latest revisions of the drivers.
302 There is also a mailing list for this:
304 majordomo@atrey.karlin.mff.cuni.cz
306 Send "subscribe linux-input" to subscribe to it.
308 The input changes are also being worked on as part of the LinuxConsole
309 project, see:
311 http://sourceforge.net/projects/linuxconsole/