]>
Commit | Line | Data |
---|---|---|
b0f355f3 MCC |
1 | .. include:: <isonum.txt> |
2 | ||
ad649380 DT |
3 | ============ |
4 | Introduction | |
5 | ============ | |
b0f355f3 MCC |
6 | |
7 | :Copyright: |copy| 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE | |
8 | ||
ad649380 | 9 | Architecture |
b0f355f3 MCC |
10 | ============ |
11 | ||
ad649380 DT |
12 | Input subsystem a collection of drivers that is designed to support |
13 | all input devices under Linux. Most of the drivers reside in | |
14 | drivers/input, although quite a few live in drivers/hid and | |
15 | drivers/platform. | |
1da177e4 | 16 | |
ad649380 | 17 | The core of the input subsystem is the input module, which must be |
1da177e4 LT |
18 | loaded before any other of the input modules - it serves as a way of |
19 | communication between two groups of modules: | |
20 | ||
b0f355f3 MCC |
21 | Device drivers |
22 | -------------- | |
23 | ||
24 | These modules talk to the hardware (for example via USB), and provide | |
1da177e4 LT |
25 | events (keystrokes, mouse movements) to the input module. |
26 | ||
b0f355f3 MCC |
27 | Event handlers |
28 | -------------- | |
29 | ||
ad649380 DT |
30 | These modules get events from input core and pass them where needed |
31 | via various interfaces - keystrokes to the kernel, mouse movements via | |
32 | a simulated PS/2 interface to GPM and X, and so on. | |
1da177e4 | 33 | |
b0f355f3 MCC |
34 | Simple Usage |
35 | ============ | |
36 | ||
37 | For the most usual configuration, with one USB mouse and one USB keyboard, | |
1da177e4 | 38 | you'll have to load the following modules (or have them built in to the |
b0f355f3 | 39 | kernel):: |
1da177e4 LT |
40 | |
41 | input | |
42 | mousedev | |
1da177e4 LT |
43 | usbcore |
44 | uhci_hcd or ohci_hcd or ehci_hcd | |
45 | usbhid | |
ad649380 | 46 | hid_generic |
1da177e4 | 47 | |
b0f355f3 MCC |
48 | After this, the USB keyboard will work straight away, and the USB mouse |
49 | will be available as a character device on major 13, minor 63:: | |
1da177e4 LT |
50 | |
51 | crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice | |
52 | ||
ad649380 DT |
53 | This device usually created automatically by the system. The commands |
54 | to create it by hand are:: | |
1da177e4 LT |
55 | |
56 | cd /dev | |
57 | mkdir input | |
58 | mknod input/mice c 13 63 | |
59 | ||
b0f355f3 MCC |
60 | After that you have to point GPM (the textmode mouse cut&paste tool) and |
61 | XFree to this device to use it - GPM should be called like:: | |
1da177e4 LT |
62 | |
63 | gpm -t ps2 -m /dev/input/mice | |
64 | ||
b0f355f3 | 65 | And in X:: |
1da177e4 LT |
66 | |
67 | Section "Pointer" | |
68 | Protocol "ImPS/2" | |
69 | Device "/dev/input/mice" | |
70 | ZAxisMapping 4 5 | |
71 | EndSection | |
72 | ||
b0f355f3 | 73 | When you do all of the above, you can use your USB mouse and keyboard. |
1da177e4 | 74 | |
b0f355f3 MCC |
75 | Detailed Description |
76 | ==================== | |
77 | ||
ad649380 | 78 | Event handlers |
b0f355f3 MCC |
79 | -------------- |
80 | ||
ad649380 DT |
81 | Event handlers distribute the events from the devices to userspace and |
82 | in-kernel consumers, as needed. | |
1da177e4 | 83 | |
ad649380 | 84 | evdev |
b0f355f3 MCC |
85 | ~~~~~ |
86 | ||
ad649380 DT |
87 | ``evdev`` is the generic input event interface. It passes the events |
88 | generated in the kernel straight to the program, with timestamps. The | |
89 | event codes are the same on all architectures and are hardware | |
90 | independent. | |
1da177e4 | 91 | |
ad649380 DT |
92 | This is the preferred interface for userspace to consume user |
93 | input, and all clients are encouraged to use it. | |
b0f355f3 | 94 | |
ad649380 | 95 | See :ref:`event-interface` for notes on API. |
b0f355f3 | 96 | |
ad649380 | 97 | The devices are in /dev/input:: |
1da177e4 | 98 | |
ad649380 DT |
99 | crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0 |
100 | crw-r--r-- 1 root root 13, 65 Apr 1 10:50 event1 | |
101 | crw-r--r-- 1 root root 13, 66 Apr 1 10:50 event2 | |
102 | crw-r--r-- 1 root root 13, 67 Apr 1 10:50 event3 | |
103 | ... | |
1da177e4 | 104 | |
ad649380 DT |
105 | There are two ranges of minors: 64 through 95 is the static legacy |
106 | range. If there are more than 32 input devices in a system, additional | |
107 | evdev nodes are created with minors starting with 256. | |
b0f355f3 | 108 | |
ad649380 DT |
109 | keyboard |
110 | ~~~~~~~~ | |
1da177e4 | 111 | |
7dfedbac | 112 | ``keyboard`` is in-kernel input handler and is a part of VT code. It |
ad649380 | 113 | consumes keyboard keystrokes and handles user input for VT consoles. |
1da177e4 | 114 | |
b0f355f3 MCC |
115 | mousedev |
116 | ~~~~~~~~ | |
117 | ||
ad649380 | 118 | ``mousedev`` is a hack to make legacy programs that use mouse input |
1da177e4 LT |
119 | work. It takes events from either mice or digitizers/tablets and makes |
120 | a PS/2-style (a la /dev/psaux) mouse device available to the | |
ad649380 | 121 | userland. |
1da177e4 | 122 | |
b0f355f3 | 123 | Mousedev devices in /dev/input (as shown above) are:: |
1da177e4 LT |
124 | |
125 | crw-r--r-- 1 root root 13, 32 Mar 28 22:45 mouse0 | |
126 | crw-r--r-- 1 root root 13, 33 Mar 29 00:41 mouse1 | |
127 | crw-r--r-- 1 root root 13, 34 Mar 29 00:41 mouse2 | |
128 | crw-r--r-- 1 root root 13, 35 Apr 1 10:50 mouse3 | |
129 | ... | |
130 | ... | |
131 | crw-r--r-- 1 root root 13, 62 Apr 1 10:50 mouse30 | |
132 | crw-r--r-- 1 root root 13, 63 Apr 1 10:50 mice | |
133 | ||
b0f355f3 MCC |
134 | Each ``mouse`` device is assigned to a single mouse or digitizer, except |
135 | the last one - ``mice``. This single character device is shared by all | |
1da177e4 | 136 | mice and digitizers, and even if none are connected, the device is |
ad649380 DT |
137 | present. This is useful for hotplugging USB mice, so that older programs |
138 | that do not handle hotplug can open the device even when no mice are | |
139 | present. | |
1da177e4 | 140 | |
b0f355f3 | 141 | CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are |
1da177e4 LT |
142 | the size of your screen (in pixels) in XFree86. This is needed if you |
143 | want to use your digitizer in X, because its movement is sent to X | |
144 | via a virtual PS/2 mouse and thus needs to be scaled | |
145 | accordingly. These values won't be used if you use a mouse only. | |
146 | ||
b0f355f3 | 147 | Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or |
1da177e4 LT |
148 | ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the |
149 | program reading the data wishes. You can set GPM and X to any of | |
150 | these. You'll need ImPS/2 if you want to make use of a wheel on a USB | |
b0f355f3 MCC |
151 | mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons. |
152 | ||
153 | joydev | |
154 | ~~~~~~ | |
1da177e4 | 155 | |
ad649380 DT |
156 | ``joydev`` implements v0.x and v1.x Linux joystick API. See |
157 | :ref:`joystick-api` for details. | |
158 | ||
159 | As soon as any joystick is connected, it can be accessed in /dev/input on:: | |
1da177e4 LT |
160 | |
161 | crw-r--r-- 1 root root 13, 0 Apr 1 10:50 js0 | |
162 | crw-r--r-- 1 root root 13, 1 Apr 1 10:50 js1 | |
163 | crw-r--r-- 1 root root 13, 2 Apr 1 10:50 js2 | |
164 | crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3 | |
165 | ... | |
166 | ||
ad649380 DT |
167 | And so on up to js31 in legacy range, and additional nodes with minors |
168 | above 256 if there are more joystick devices. | |
1da177e4 | 169 | |
ad649380 DT |
170 | Device drivers |
171 | -------------- | |
b0f355f3 | 172 | |
ad649380 | 173 | Device drivers are the modules that generate events. |
1da177e4 | 174 | |
ad649380 DT |
175 | hid-generic |
176 | ~~~~~~~~~~~ | |
1da177e4 | 177 | |
ad649380 DT |
178 | ``hid-generic`` is one of the largest and most complex driver of the |
179 | whole suite. It handles all HID devices, and because there is a very | |
180 | wide variety of them, and because the USB HID specification isn't | |
181 | simple, it needs to be this big. | |
1da177e4 | 182 | |
ad649380 DT |
183 | Currently, it handles USB mice, joysticks, gamepads, steering wheels |
184 | keyboards, trackballs and digitizers. | |
185 | ||
186 | However, USB uses HID also for monitor controls, speaker controls, UPSs, | |
187 | LCDs and many other purposes. | |
188 | ||
189 | The monitor and speaker controls should be easy to add to the hid/input | |
190 | interface, but for the UPSs and LCDs it doesn't make much sense. For this, | |
191 | the hiddev interface was designed. See Documentation/hid/hiddev.txt | |
192 | for more information about it. | |
193 | ||
194 | The usage of the usbhid module is very simple, it takes no parameters, | |
195 | detects everything automatically and when a HID device is inserted, it | |
196 | detects it appropriately. | |
1da177e4 | 197 | |
ad649380 DT |
198 | However, because the devices vary wildly, you might happen to have a |
199 | device that doesn't work well. In that case #define DEBUG at the beginning | |
200 | of hid-core.c and send me the syslog traces. | |
201 | ||
202 | usbmouse | |
203 | ~~~~~~~~ | |
204 | ||
205 | For embedded systems, for mice with broken HID descriptors and just any | |
206 | other use when the big usbhid wouldn't be a good choice, there is the | |
207 | usbmouse driver. It handles USB mice only. It uses a simpler HIDBP | |
208 | protocol. This also means the mice must support this simpler protocol. Not | |
209 | all do. If you don't have any strong reason to use this module, use usbhid | |
210 | instead. | |
211 | ||
212 | usbkbd | |
213 | ~~~~~~ | |
214 | ||
215 | Much like usbmouse, this module talks to keyboards with a simplified | |
216 | HIDBP protocol. It's smaller, but doesn't support any extra special keys. | |
217 | Use usbhid instead if there isn't any special reason to use this. | |
218 | ||
219 | psmouse | |
220 | ~~~~~~~ | |
221 | ||
222 | This is driver for all flavors of pointing devices using PS/2 | |
223 | protocol, including Synaptics and ALPS touchpads, Intellimouse | |
224 | Explorer devices, Logitech PS/2 mice and so on. | |
225 | ||
226 | atkbd | |
227 | ~~~~~ | |
228 | ||
229 | This is driver for PS/2 (AT) keyboards. | |
230 | ||
231 | iforce | |
232 | ~~~~~~ | |
233 | ||
234 | A driver for I-Force joysticks and wheels, both over USB and RS232. | |
235 | It includes Force Feedback support now, even though Immersion | |
236 | Corp. considers the protocol a trade secret and won't disclose a word | |
237 | about it. | |
1da177e4 | 238 | |
b0f355f3 MCC |
239 | Verifying if it works |
240 | ===================== | |
241 | ||
242 | Typing a couple keys on the keyboard should be enough to check that | |
ad649380 | 243 | a keyboard works and is correctly connected to the kernel keyboard |
b0f355f3 | 244 | driver. |
1da177e4 | 245 | |
b0f355f3 | 246 | Doing a ``cat /dev/input/mouse0`` (c, 13, 32) will verify that a mouse |
09601523 | 247 | is also emulated; characters should appear if you move it. |
1da177e4 | 248 | |
b0f355f3 | 249 | You can test the joystick emulation with the ``jstest`` utility, |
ad649380 | 250 | available in the joystick package (see :ref:`joystick-doc`). |
1da177e4 | 251 | |
ad649380 DT |
252 | You can test the event devices with the ``evtest`` utility. |
253 | ||
254 | .. _event-interface: | |
1da177e4 | 255 | |
b0f355f3 MCC |
256 | Event interface |
257 | =============== | |
258 | ||
ad649380 | 259 | You can use blocking and nonblocking reads, and also select() on the |
1da177e4 | 260 | /dev/input/eventX devices, and you'll always get a whole number of input |
b0f355f3 | 261 | events on a read. Their layout is:: |
1da177e4 | 262 | |
b0f355f3 MCC |
263 | struct input_event { |
264 | struct timeval time; | |
265 | unsigned short type; | |
266 | unsigned short code; | |
267 | unsigned int value; | |
268 | }; | |
1da177e4 | 269 | |
b0f355f3 | 270 | ``time`` is the timestamp, it returns the time at which the event happened. |
4a74491e | 271 | Type is for example EV_REL for relative moment, EV_KEY for a keypress or |
da23e4d1 | 272 | release. More types are defined in include/uapi/linux/input-event-codes.h. |
1da177e4 | 273 | |
b0f355f3 | 274 | ``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete |
da23e4d1 | 275 | list is in include/uapi/linux/input-event-codes.h. |
1da177e4 | 276 | |
b0f355f3 | 277 | ``value`` is the value the event carries. Either a relative change for |
1da177e4 LT |
278 | EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for |
279 | release, 1 for keypress and 2 for autorepeat. | |
ad649380 DT |
280 | |
281 | See :ref:`input-event-codes` for more information about various even codes. |