1 .. _input-event-codes:
2
3 =================
4 Input event codes
5 =================
6
7
8 The input protocol uses a map of types and cod
9 to userspace. This document describes the type
10 may be used.
11
12 A single hardware event generates multiple inp
13 contains the new value of a single data item.
14 used to separate input events into packets of
15 the same moment in time. In the following, the
16 input event encompassing a type, code, and val
17
18 The input protocol is a stateful protocol. Eve
19 of event codes have changed. However, the stat
20 input subsystem; drivers do not need to mainta
21 emit unchanged values without harm. Userspace
22 event code values using the EVIOCG* ioctls def
23 reports supported by a device are also provide
24 class/input/event*/device/capabilities/, and t
25 provided in class/input/event*/device/properti
26
27 Event types
28 ===========
29
30 Event types are groupings of codes under a log
31 type has a set of applicable codes to be used
32 Codes section for details on valid codes for e
33
34 * EV_SYN:
35
36 - Used as markers to separate events. Events
37 space, such as with the multitouch protoco
38
39 * EV_KEY:
40
41 - Used to describe state changes of keyboard
42 devices.
43
44 * EV_REL:
45
46 - Used to describe relative axis value chang
47 to the left.
48
49 * EV_ABS:
50
51 - Used to describe absolute axis value chang
52 coordinates of a touch on a touchscreen.
53
54 * EV_MSC:
55
56 - Used to describe miscellaneous input data
57
58 * EV_SW:
59
60 - Used to describe binary state input switch
61
62 * EV_LED:
63
64 - Used to turn LEDs on devices on and off.
65
66 * EV_SND:
67
68 - Used to output sound to devices.
69
70 * EV_REP:
71
72 - Used for autorepeating devices.
73
74 * EV_FF:
75
76 - Used to send force feedback commands to an
77
78 * EV_PWR:
79
80 - A special type for power button and switch
81
82 * EV_FF_STATUS:
83
84 - Used to receive force feedback device stat
85
86 Event codes
87 ===========
88
89 Event codes define the precise type of event.
90
91 EV_SYN
92 ------
93
94 EV_SYN event values are undefined. Their usage
95 sent in the evdev event stream.
96
97 * SYN_REPORT:
98
99 - Used to synchronize and separate events in
100 occurring at the same moment in time. For
101 the REL_X and REL_Y values for one motion,
102 motion will emit more REL_X and REL_Y valu
103
104 * SYN_CONFIG:
105
106 - TBD
107
108 * SYN_MT_REPORT:
109
110 - Used to synchronize and separate touch eve
111 multi-touch-protocol.txt document for more
112
113 * SYN_DROPPED:
114
115 - Used to indicate buffer overrun in the evd
116 Client should ignore all events up to and
117 event and query the device (using EVIOCG*
118 current state.
119
120 EV_KEY
121 ------
122
123 EV_KEY events take the form KEY_<name> or BTN_
124 to represent the 'A' key on a keyboard. When a
125 the key's code is emitted with value 1. When t
126 emitted with value 0. Some hardware send event
127 events have a value of 2. In general, KEY_<nam
128 BTN_<name> is used for other types of momentar
129
130 A few EV_KEY codes have special meanings:
131
132 * BTN_TOOL_<name>:
133
134 - These codes are used in conjunction with i
135 touchscreens. These devices may be used wi
136 When an event occurs and a tool is used, t
137 code should be set to a value of 1. When t
138 with the input device, the BTN_TOOL_<name>
139 trackpads, tablets, and touchscreens shoul
140 code when events are generated. Likewise a
141 touchscreens should export only one BTN_TO
142 existing userspace, it is recommended to n
143 but first emitting the old BTN_TOOL_<name>
144 and then set the new BTN_TOOL_<name> at 1.
145
146 * BTN_TOUCH:
147
148 BTN_TOUCH is used for touch contact. While
149 within meaningful physical contact, the va
150 to 1. Meaningful physical contact may mean
151 contact conditioned by an implementation d
152 touchpad may set the value to 1 only when
153 certain value. BTN_TOUCH may be combined w
154 example, a pen tablet may set BTN_TOOL_PEN
155 pen is hovering over but not touching the
156
157 Note: For appropriate function of the legacy m
158 BTN_TOUCH must be the first evdev code emitted
159
160 Note: Historically a touch device with BTN_TOO
161 interpreted as a touchpad by userspace, while
162 BTN_TOOL_FINGER was interpreted as a touchscre
163 with current userspace it is recommended to fo
164 future, this distinction will be deprecated an
165 EVIOCGPROP, defined in linux/input.h, will be
166
167 * BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOO
168
169 - These codes denote one, two, three, and fo
170 trackpad or touchscreen. For example, if t
171 them on the touchpad in an effort to scrol
172 BTN_TOOL_DOUBLETAP should be set to value
173 Note that all BTN_TOOL_<name> codes and th
174 purpose. A trackpad event generated by fin
175 for one code from each group. At most only
176 codes should have a value of 1 during any
177
178 Note: Historically some drivers emitted multip
179 a value of 1 in the same synchronization frame
180
181 Note: In multitouch drivers, the input_mt_repo
182 be used to emit these codes. Please see multi-
183
184 EV_REL
185 ------
186
187 EV_REL events describe relative changes in a p
188 move to the left by a certain number of units,
189 space is unknown. If the absolute position is
190 instead of EV_REL codes.
191
192 A few EV_REL codes have special meanings:
193
194 * REL_WHEEL, REL_HWHEEL:
195
196 - These codes are used for vertical and hori
197 respectively. The value is the number of d
198 physical size of which varies by device. F
199 this may be an approximation based on the
200 see REL_WHEEL_HI_RES. These event codes ar
201 REL_WHEEL_HI_RES and REL_HWHEEL_HI_RES sho
202 available.
203
204 * REL_WHEEL_HI_RES, REL_HWHEEL_HI_RES:
205
206 - High-resolution scroll wheel data. The acc
207 movement by one detent. For devices that d
208 scrolling, the value is always a multiple
209 high-resolution scrolling, the value may b
210
211 If a vertical scroll wheel supports high-r
212 will be emitted in addition to REL_WHEEL o
213 and REL_HWHEEL may be an approximation bas
214 scroll events. There is no guarantee that
215 is a multiple of 120 at the time of an emu
216 event.
217
218 EV_ABS
219 ------
220
221 EV_ABS events describe absolute changes in a p
222 may emit coordinates for a touch location.
223
224 A few EV_ABS codes have special meanings:
225
226 * ABS_DISTANCE:
227
228 - Used to describe the distance of a tool fr
229 event should only be emitted while the too
230 proximity of the device and while the valu
231 the input device may be used freely in thr
232 instead.
233 - BTN_TOOL_<name> should be set to 1 when th
234 proximity and set to 0 when the tool leave
235 BTN_TOOL_<name> signals the type of tool t
236 hardware and is otherwise independent of A
237
238 * ABS_PROFILE:
239
240 - Used to describe the state of a multi-valu
241 emitted only when the selected profile cha
242 selected profile value.
243
244 * ABS_MT_<name>:
245
246 - Used to describe multitouch input events.
247 multi-touch-protocol.txt for details.
248
249 * ABS_PRESSURE/ABS_MT_PRESSURE:
250
251 - For touch devices, many devices converted
252 A finger flattens with pressure, causing
253 pressure and contact size are directly re
254 for other devices, for example digitizers
255 pressure sensor ("pressure pads").
256
257 A device should set the resolution of the
258 pressure is in measurable units. If the r
259 pressure data is in arbitrary units. If t
260 pressure data is in units/gram. For examp
261 resolution of 1 represents 10 gram, a val
262 1000 represents 10 microgram.
263
264 EV_SW
265 -----
266
267 EV_SW events describe stateful binary switches
268 used to denote when a laptop lid is closed.
269
270 Upon binding to a device or resuming from susp
271 the current switch state. This ensures that th
272 state is in sync.
273
274 Upon resume, if the switch state is the same a
275 subsystem will filter out the duplicate switch
276 not need to keep the state of the switch at an
277
278 EV_MSC
279 ------
280
281 EV_MSC events are used for input and output ev
282 categories.
283
284 A few EV_MSC codes have special meaning:
285
286 * MSC_TIMESTAMP:
287
288 - Used to report the number of microseconds
289 should be coded as an uint32 value, which
290 no special consequence. It is assumed that
291 consecutive events is reliable on a reason
292 A reset to zero can happen, in which case
293 unknown. If the device does not provide t
294 not provide it to user space.
295
296 EV_LED
297 ------
298
299 EV_LED events are used for input and output to
300 various LEDs on devices.
301
302 EV_REP
303 ------
304
305 EV_REP events are used for specifying autorepe
306
307 EV_SND
308 ------
309
310 EV_SND events are used for sending sound comma
311 devices.
312
313 EV_FF
314 -----
315
316 EV_FF events are used to initialize a force fe
317 such device to feedback.
318
319 EV_PWR
320 ------
321
322 EV_PWR events are a special type of event used
323 management. Its usage is not well defined. To
324
325 Device properties
326 =================
327
328 Normally, userspace sets up an input device ba
329 i.e., the event types. In the case of two devi
330 types, additional information can be provided
331 properties.
332
333 INPUT_PROP_DIRECT + INPUT_PROP_POINTER
334 --------------------------------------
335
336 The INPUT_PROP_DIRECT property indicates that
337 directly mapped to screen coordinates (not tak
338 transformations, such as scaling, flipping and
339 devices require non-trivial transformation, su
340 transformation for touchpads. Typical direct i
341 drawing tablets; non-direct devices: touchpads
342
343 The INPUT_PROP_POINTER property indicates that
344 on the screen and thus requires use of an on-s
345 movements. Typical pointer devices: touchpads
346 device: touchscreen.
347
348 If neither INPUT_PROP_DIRECT or INPUT_PROP_POI
349 considered undefined and the device type shoul
350 traditional way, using emitted event types.
351
352 INPUT_PROP_BUTTONPAD
353 --------------------
354
355 For touchpads where the button is placed benea
356 pressing down on the pad causes a button click
357 set. Common in Clickpad notebooks and Macbooks
358
359 Originally, the buttonpad property was coded i
360 version field under the name integrated button
361 compatibility, both methods need to be checked
362
363 INPUT_PROP_SEMI_MT
364 ------------------
365
366 Some touchpads, most common between 2008 and 2
367 of multiple contacts without resolving the ind
368 number of contacts and a rectangular shape is
369 touchpads, the SEMI_MT property should be set.
370
371 Depending on the device, the rectangle may enc
372 bounding box, or just some of them, for instan
373 touches. The diversity makes the rectangle of
374 gestures can normally be extracted from it.
375
376 If INPUT_PROP_SEMI_MT is not set, the device i
377 device.
378
379 INPUT_PROP_TOPBUTTONPAD
380 -----------------------
381
382 Some laptops, most notably the Lenovo 40 serie
383 device but do not have physical buttons associ
384 device. Instead, the top area of the touchpad
385 visual/haptic areas for left, middle, right bu
386 with the trackstick.
387
388 If INPUT_PROP_TOPBUTTONPAD is set, userspace s
389 accordingly. This property does not affect ker
390 The kernel does not provide button emulation f
391 them as any other INPUT_PROP_BUTTONPAD device.
392
393 INPUT_PROP_ACCELEROMETER
394 ------------------------
395
396 Directional axes on this device (absolute and/
397 accelerometer data. Some devices also report g
398 can report through the rotational axes (absolu
399
400 All other axes retain their meaning. A device
401 regular directional axes and accelerometer axe
402
403 Guidelines
404 ==========
405
406 The guidelines below ensure proper single-touc
407 For multi-touch functionality, see the multi-t
408 more information.
409
410 Mice
411 ----
412
413 REL_{X,Y} must be reported when the mouse move
414 the primary button press. BTN_{MIDDLE,RIGHT,4,
415 further buttons of the device. REL_WHEEL and R
416 scroll wheel events where available.
417
418 Touchscreens
419 ------------
420
421 ABS_{X,Y} must be reported with the location o
422 used to report when a touch is active on the s
423 BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be repo
424 contact. BTN_TOOL_<name> events should be repo
425
426 For new hardware, INPUT_PROP_DIRECT should be
427
428 Trackpads
429 ---------
430
431 Legacy trackpads that only provide relative po
432 events like mice described above.
433
434 Trackpads that provide absolute touch position
435 location of the touch. BTN_TOUCH should be use
436 on the trackpad. Where multi-finger support is
437 be used to report the number of touches active
438
439 For new hardware, INPUT_PROP_POINTER should be
440
441 Tablets
442 -------
443
444 BTN_TOOL_<name> events must be reported when a
445 the tablet. ABS_{X,Y} must be reported with th
446 should be used to report when the tool is in c
447 BTN_{STYLUS,STYLUS2} should be used to report
448 button may be used for buttons on the tablet e
449 BTN_{0,1,2,etc} are good generic codes for unl
450 meaningful buttons, like BTN_FORWARD, unless t
451 purpose on the device.
452
453 For new hardware, both INPUT_PROP_DIRECT and I
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.