Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | ||
bf6ee0ae AB |
71 | This device has to be created. |
72 | The commands to create it by hand are: | |
1da177e4 LT |
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 | ~~~~~~~~~~~~~~~~~~ | |
fff9289b | 157 | Event handlers distribute the events from the devices to userland and |
1da177e4 LT |
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 |