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