Commit | Line | Data |
---|---|---|
ad649380 DT |
1 | .. _input-event-codes: |
2 | ||
acbdca8b MCC |
3 | ================= |
4 | Input event codes | |
5 | ================= | |
6 | ||
7 | ||
b1e064b8 CD |
8 | The input protocol uses a map of types and codes to express input device values |
9 | to userspace. This document describes the types and codes and how and when they | |
10 | may be used. | |
11 | ||
12 | A single hardware event generates multiple input events. Each input event | |
13 | contains the new value of a single data item. A special event type, EV_SYN, is | |
14 | used to separate input events into packets of input data changes occurring at | |
15 | the same moment in time. In the following, the term "event" refers to a single | |
16 | input event encompassing a type, code, and value. | |
17 | ||
18 | The input protocol is a stateful protocol. Events are emitted only when values | |
19 | of event codes have changed. However, the state is maintained within the Linux | |
20 | input subsystem; drivers do not need to maintain the state and may attempt to | |
21 | emit unchanged values without harm. Userspace may obtain the current state of | |
22 | event code values using the EVIOCG* ioctls defined in linux/input.h. The event | |
23 | reports supported by a device are also provided by sysfs in | |
24 | class/input/event*/device/capabilities/, and the properties of a device are | |
25 | provided in class/input/event*/device/properties. | |
26 | ||
acbdca8b | 27 | Event types |
d04df023 | 28 | =========== |
acbdca8b | 29 | |
d04df023 HR |
30 | Event types are groupings of codes under a logical input construct. Each |
31 | type has a set of applicable codes to be used in generating events. See the | |
32 | Codes section for details on valid codes for each type. | |
b1e064b8 CD |
33 | |
34 | * EV_SYN: | |
acbdca8b | 35 | |
b1e064b8 CD |
36 | - Used as markers to separate events. Events may be separated in time or in |
37 | space, such as with the multitouch protocol. | |
38 | ||
39 | * EV_KEY: | |
acbdca8b | 40 | |
b1e064b8 CD |
41 | - Used to describe state changes of keyboards, buttons, or other key-like |
42 | devices. | |
43 | ||
44 | * EV_REL: | |
acbdca8b | 45 | |
b1e064b8 CD |
46 | - Used to describe relative axis value changes, e.g. moving the mouse 5 units |
47 | to the left. | |
48 | ||
49 | * EV_ABS: | |
acbdca8b | 50 | |
b1e064b8 CD |
51 | - Used to describe absolute axis value changes, e.g. describing the |
52 | coordinates of a touch on a touchscreen. | |
53 | ||
54 | * EV_MSC: | |
acbdca8b | 55 | |
b1e064b8 CD |
56 | - Used to describe miscellaneous input data that do not fit into other types. |
57 | ||
58 | * EV_SW: | |
acbdca8b | 59 | |
b1e064b8 CD |
60 | - Used to describe binary state input switches. |
61 | ||
62 | * EV_LED: | |
acbdca8b | 63 | |
b1e064b8 CD |
64 | - Used to turn LEDs on devices on and off. |
65 | ||
66 | * EV_SND: | |
acbdca8b | 67 | |
b1e064b8 CD |
68 | - Used to output sound to devices. |
69 | ||
70 | * EV_REP: | |
acbdca8b | 71 | |
b1e064b8 CD |
72 | - Used for autorepeating devices. |
73 | ||
74 | * EV_FF: | |
acbdca8b | 75 | |
b1e064b8 CD |
76 | - Used to send force feedback commands to an input device. |
77 | ||
78 | * EV_PWR: | |
acbdca8b | 79 | |
b1e064b8 CD |
80 | - A special type for power button and switch input. |
81 | ||
82 | * EV_FF_STATUS: | |
acbdca8b | 83 | |
b1e064b8 CD |
84 | - Used to receive force feedback device status. |
85 | ||
acbdca8b | 86 | Event codes |
d04df023 | 87 | =========== |
acbdca8b | 88 | |
d04df023 | 89 | Event codes define the precise type of event. |
b1e064b8 | 90 | |
acbdca8b MCC |
91 | EV_SYN |
92 | ------ | |
93 | ||
b1e064b8 CD |
94 | EV_SYN event values are undefined. Their usage is defined only by when they are |
95 | sent in the evdev event stream. | |
96 | ||
97 | * SYN_REPORT: | |
acbdca8b | 98 | |
b1e064b8 CD |
99 | - Used to synchronize and separate events into packets of input data changes |
100 | occurring at the same moment in time. For example, motion of a mouse may set | |
101 | the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The next | |
102 | motion will emit more REL_X and REL_Y values and send another SYN_REPORT. | |
103 | ||
104 | * SYN_CONFIG: | |
acbdca8b | 105 | |
b1e064b8 CD |
106 | - TBD |
107 | ||
108 | * SYN_MT_REPORT: | |
acbdca8b | 109 | |
b1e064b8 CD |
110 | - Used to synchronize and separate touch events. See the |
111 | multi-touch-protocol.txt document for more information. | |
112 | ||
9fb0f14e | 113 | * SYN_DROPPED: |
acbdca8b | 114 | |
9fb0f14e JB |
115 | - Used to indicate buffer overrun in the evdev client's event queue. |
116 | Client should ignore all events up to and including next SYN_REPORT | |
117 | event and query the device (using EVIOCG* ioctls) to obtain its | |
118 | current state. | |
119 | ||
acbdca8b MCC |
120 | EV_KEY |
121 | ------ | |
122 | ||
b1e064b8 CD |
123 | EV_KEY events take the form KEY_<name> or BTN_<name>. For example, KEY_A is used |
124 | to represent the 'A' key on a keyboard. When a key is depressed, an event with | |
125 | the key's code is emitted with value 1. When the key is released, an event is | |
126 | emitted with value 0. Some hardware send events when a key is repeated. These | |
127 | events have a value of 2. In general, KEY_<name> is used for keyboard keys, and | |
128 | BTN_<name> is used for other types of momentary switch events. | |
129 | ||
130 | A few EV_KEY codes have special meanings: | |
131 | ||
132 | * BTN_TOOL_<name>: | |
acbdca8b | 133 | |
b1e064b8 CD |
134 | - These codes are used in conjunction with input trackpads, tablets, and |
135 | touchscreens. These devices may be used with fingers, pens, or other tools. | |
136 | When an event occurs and a tool is used, the corresponding BTN_TOOL_<name> | |
137 | code should be set to a value of 1. When the tool is no longer interacting | |
138 | with the input device, the BTN_TOOL_<name> code should be reset to 0. All | |
139 | trackpads, tablets, and touchscreens should use at least one BTN_TOOL_<name> | |
42764f97 BT |
140 | code when events are generated. Likewise all trackpads, tablets, and |
141 | touchscreens should export only one BTN_TOOL_<name> at a time. To not break | |
142 | existing userspace, it is recommended to not switch tool in one EV_SYN frame | |
143 | but first emitting the old BTN_TOOL_<name> at 0, then emit one SYN_REPORT | |
144 | and then set the new BTN_TOOL_<name> at 1. | |
b1e064b8 CD |
145 | |
146 | * BTN_TOUCH: | |
acbdca8b | 147 | |
b1e064b8 CD |
148 | BTN_TOUCH is used for touch contact. While an input tool is determined to be |
149 | within meaningful physical contact, the value of this property must be set | |
150 | to 1. Meaningful physical contact may mean any contact, or it may mean | |
151 | contact conditioned by an implementation defined property. For example, a | |
152 | touchpad may set the value to 1 only when the touch pressure rises above a | |
153 | certain value. BTN_TOUCH may be combined with BTN_TOOL_<name> codes. For | |
154 | example, a pen tablet may set BTN_TOOL_PEN to 1 and BTN_TOUCH to 0 while the | |
155 | pen is hovering over but not touching the tablet surface. | |
156 | ||
157 | Note: For appropriate function of the legacy mousedev emulation driver, | |
158 | BTN_TOUCH must be the first evdev code emitted in a synchronization frame. | |
159 | ||
160 | Note: Historically a touch device with BTN_TOOL_FINGER and BTN_TOUCH was | |
161 | interpreted as a touchpad by userspace, while a similar device without | |
162 | BTN_TOOL_FINGER was interpreted as a touchscreen. For backwards compatibility | |
163 | with current userspace it is recommended to follow this distinction. In the | |
164 | future, this distinction will be deprecated and the device properties ioctl | |
165 | EVIOCGPROP, defined in linux/input.h, will be used to convey the device type. | |
166 | ||
167 | * BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP: | |
acbdca8b | 168 | |
b1e064b8 CD |
169 | - These codes denote one, two, three, and four finger interaction on a |
170 | trackpad or touchscreen. For example, if the user uses two fingers and moves | |
171 | them on the touchpad in an effort to scroll content on screen, | |
172 | BTN_TOOL_DOUBLETAP should be set to value 1 for the duration of the motion. | |
173 | Note that all BTN_TOOL_<name> codes and the BTN_TOUCH code are orthogonal in | |
174 | purpose. A trackpad event generated by finger touches should generate events | |
175 | for one code from each group. At most only one of these BTN_TOOL_<name> | |
176 | codes should have a value of 1 during any synchronization frame. | |
177 | ||
178 | Note: Historically some drivers emitted multiple of the finger count codes with | |
179 | a value of 1 in the same synchronization frame. This usage is deprecated. | |
180 | ||
181 | Note: In multitouch drivers, the input_mt_report_finger_count() function should | |
182 | be used to emit these codes. Please see multi-touch-protocol.txt for details. | |
183 | ||
acbdca8b MCC |
184 | EV_REL |
185 | ------ | |
186 | ||
b1e064b8 CD |
187 | EV_REL events describe relative changes in a property. For example, a mouse may |
188 | move to the left by a certain number of units, but its absolute position in | |
189 | space is unknown. If the absolute position is known, EV_ABS codes should be used | |
190 | instead of EV_REL codes. | |
191 | ||
192 | A few EV_REL codes have special meanings: | |
193 | ||
194 | * REL_WHEEL, REL_HWHEEL: | |
acbdca8b | 195 | |
b1e064b8 | 196 | - These codes are used for vertical and horizontal scroll wheels, |
52ea8996 PH |
197 | respectively. The value is the number of detents moved on the wheel, the |
198 | physical size of which varies by device. For high-resolution wheels | |
199 | this may be an approximation based on the high-resolution scroll events, | |
200 | see REL_WHEEL_HI_RES. These event codes are legacy codes and | |
201 | REL_WHEEL_HI_RES and REL_HWHEEL_HI_RES should be preferred where | |
202 | available. | |
203 | ||
204 | * REL_WHEEL_HI_RES, REL_HWHEEL_HI_RES: | |
205 | ||
206 | - High-resolution scroll wheel data. The accumulated value 120 represents | |
207 | movement by one detent. For devices that do not provide high-resolution | |
208 | scrolling, the value is always a multiple of 120. For devices with | |
209 | high-resolution scrolling, the value may be a fraction of 120. | |
210 | ||
211 | If a vertical scroll wheel supports high-resolution scrolling, this code | |
212 | will be emitted in addition to REL_WHEEL or REL_HWHEEL. The REL_WHEEL | |
213 | and REL_HWHEEL may be an approximation based on the high-resolution | |
214 | scroll events. There is no guarantee that the high-resolution data | |
215 | is a multiple of 120 at the time of an emulated REL_WHEEL or REL_HWHEEL | |
216 | event. | |
b1e064b8 | 217 | |
acbdca8b MCC |
218 | EV_ABS |
219 | ------ | |
220 | ||
b1e064b8 CD |
221 | EV_ABS events describe absolute changes in a property. For example, a touchpad |
222 | may emit coordinates for a touch location. | |
223 | ||
224 | A few EV_ABS codes have special meanings: | |
225 | ||
226 | * ABS_DISTANCE: | |
acbdca8b | 227 | |
b1e064b8 CD |
228 | - Used to describe the distance of a tool from an interaction surface. This |
229 | event should only be emitted while the tool is hovering, meaning in close | |
230 | proximity of the device and while the value of the BTN_TOUCH code is 0. If | |
231 | the input device may be used freely in three dimensions, consider ABS_Z | |
232 | instead. | |
7eb5ca09 PH |
233 | - BTN_TOOL_<name> should be set to 1 when the tool comes into detectable |
234 | proximity and set to 0 when the tool leaves detectable proximity. | |
235 | BTN_TOOL_<name> signals the type of tool that is currently detected by the | |
236 | hardware and is otherwise independent of ABS_DISTANCE and/or BTN_TOUCH. | |
b1e064b8 | 237 | |
1260cd04 NY |
238 | * ABS_PROFILE: |
239 | ||
240 | - Used to describe the state of a multi-value profile switch. An event is | |
241 | emitted only when the selected profile changes, indicating the newly | |
242 | selected profile value. | |
243 | ||
b1e064b8 | 244 | * ABS_MT_<name>: |
acbdca8b | 245 | |
b1e064b8 CD |
246 | - Used to describe multitouch input events. Please see |
247 | multi-touch-protocol.txt for details. | |
248 | ||
20ccc8dd PH |
249 | * ABS_PRESSURE/ABS_MT_PRESSURE: |
250 | ||
251 | - For touch devices, many devices converted contact size into pressure. | |
252 | A finger flattens with pressure, causing a larger contact area and thus | |
253 | pressure and contact size are directly related. This is not the case | |
254 | for other devices, for example digitizers and touchpads with a true | |
255 | pressure sensor ("pressure pads"). | |
256 | ||
257 | A device should set the resolution of the axis to indicate whether the | |
258 | pressure is in measurable units. If the resolution is zero, the | |
61be51c1 | 259 | pressure data is in arbitrary units. If the resolution is non-zero, the |
20ccc8dd | 260 | pressure data is in units/gram. For example, a value of 10 with a |
61be51c1 | 261 | resolution of 1 represents 10 gram, a value of 10 with a resolution of |
20ccc8dd PH |
262 | 1000 represents 10 microgram. |
263 | ||
acbdca8b MCC |
264 | EV_SW |
265 | ----- | |
266 | ||
b1e064b8 CD |
267 | EV_SW events describe stateful binary switches. For example, the SW_LID code is |
268 | used to denote when a laptop lid is closed. | |
269 | ||
270 | Upon binding to a device or resuming from suspend, a driver must report | |
271 | the current switch state. This ensures that the device, kernel, and userspace | |
272 | state is in sync. | |
273 | ||
274 | Upon resume, if the switch state is the same as before suspend, then the input | |
275 | subsystem will filter out the duplicate switch state reports. The driver does | |
276 | not need to keep the state of the switch at any time. | |
277 | ||
acbdca8b MCC |
278 | EV_MSC |
279 | ------ | |
280 | ||
b1e064b8 CD |
281 | EV_MSC events are used for input and output events that do not fall under other |
282 | categories. | |
283 | ||
af8036dd BT |
284 | A few EV_MSC codes have special meaning: |
285 | ||
286 | * MSC_TIMESTAMP: | |
acbdca8b | 287 | |
af8036dd BT |
288 | - Used to report the number of microseconds since the last reset. This event |
289 | should be coded as an uint32 value, which is allowed to wrap around with | |
290 | no special consequence. It is assumed that the time difference between two | |
291 | consecutive events is reliable on a reasonable time scale (hours). | |
292 | A reset to zero can happen, in which case the time since the last event is | |
293 | unknown. If the device does not provide this information, the driver must | |
294 | not provide it to user space. | |
295 | ||
acbdca8b MCC |
296 | EV_LED |
297 | ------ | |
298 | ||
b1e064b8 CD |
299 | EV_LED events are used for input and output to set and query the state of |
300 | various LEDs on devices. | |
301 | ||
acbdca8b MCC |
302 | EV_REP |
303 | ------ | |
304 | ||
b1e064b8 CD |
305 | EV_REP events are used for specifying autorepeating events. |
306 | ||
acbdca8b MCC |
307 | EV_SND |
308 | ------ | |
309 | ||
b1e064b8 CD |
310 | EV_SND events are used for sending sound commands to simple sound output |
311 | devices. | |
312 | ||
acbdca8b MCC |
313 | EV_FF |
314 | ----- | |
315 | ||
b1e064b8 CD |
316 | EV_FF events are used to initialize a force feedback capable device and to cause |
317 | such device to feedback. | |
318 | ||
acbdca8b MCC |
319 | EV_PWR |
320 | ------ | |
321 | ||
b1e064b8 | 322 | EV_PWR events are a special type of event used specifically for power |
ad4a6ebe | 323 | management. Its usage is not well defined. To be addressed later. |
b1e064b8 | 324 | |
acbdca8b | 325 | Device properties |
d04df023 | 326 | ================= |
acbdca8b | 327 | |
d04df023 HR |
328 | Normally, userspace sets up an input device based on the data it emits, |
329 | i.e., the event types. In the case of two devices emitting the same event | |
330 | types, additional information can be provided in the form of device | |
331 | properties. | |
332 | ||
acbdca8b | 333 | INPUT_PROP_DIRECT + INPUT_PROP_POINTER |
d04df023 | 334 | -------------------------------------- |
acbdca8b | 335 | |
d04df023 HR |
336 | The INPUT_PROP_DIRECT property indicates that device coordinates should be |
337 | directly mapped to screen coordinates (not taking into account trivial | |
338 | transformations, such as scaling, flipping and rotating). Non-direct input | |
339 | devices require non-trivial transformation, such as absolute to relative | |
340 | transformation for touchpads. Typical direct input devices: touchscreens, | |
341 | drawing tablets; non-direct devices: touchpads, mice. | |
342 | ||
343 | The INPUT_PROP_POINTER property indicates that the device is not transposed | |
344 | on the screen and thus requires use of an on-screen pointer to trace user's | |
345 | movements. Typical pointer devices: touchpads, tablets, mice; non-pointer | |
346 | device: touchscreen. | |
347 | ||
348 | If neither INPUT_PROP_DIRECT or INPUT_PROP_POINTER are set, the property is | |
349 | considered undefined and the device type should be deduced in the | |
350 | traditional way, using emitted event types. | |
351 | ||
acbdca8b | 352 | INPUT_PROP_BUTTONPAD |
d04df023 | 353 | -------------------- |
acbdca8b | 354 | |
d04df023 HR |
355 | For touchpads where the button is placed beneath the surface, such that |
356 | pressing down on the pad causes a button click, this property should be | |
61be51c1 | 357 | set. Common in Clickpad notebooks and Macbooks from 2009 and onwards. |
d04df023 HR |
358 | |
359 | Originally, the buttonpad property was coded into the bcm5974 driver | |
360 | version field under the name integrated button. For backwards | |
361 | compatibility, both methods need to be checked in userspace. | |
362 | ||
acbdca8b | 363 | INPUT_PROP_SEMI_MT |
d04df023 | 364 | ------------------ |
acbdca8b | 365 | |
d04df023 HR |
366 | Some touchpads, most common between 2008 and 2011, can detect the presence |
367 | of multiple contacts without resolving the individual positions; only the | |
368 | number of contacts and a rectangular shape is known. For such | |
61be51c1 | 369 | touchpads, the SEMI_MT property should be set. |
d04df023 HR |
370 | |
371 | Depending on the device, the rectangle may enclose all touches, like a | |
372 | bounding box, or just some of them, for instance the two most recent | |
373 | touches. The diversity makes the rectangle of limited use, but some | |
374 | gestures can normally be extracted from it. | |
375 | ||
376 | If INPUT_PROP_SEMI_MT is not set, the device is assumed to be a true MT | |
377 | device. | |
378 | ||
acbdca8b | 379 | INPUT_PROP_TOPBUTTONPAD |
f62d14a8 | 380 | ----------------------- |
acbdca8b MCC |
381 | |
382 | Some laptops, most notably the Lenovo 40 series provide a trackstick | |
f62d14a8 PH |
383 | device but do not have physical buttons associated with the trackstick |
384 | device. Instead, the top area of the touchpad is marked to show | |
385 | visual/haptic areas for left, middle, right buttons intended to be used | |
386 | with the trackstick. | |
387 | ||
388 | If INPUT_PROP_TOPBUTTONPAD is set, userspace should emulate buttons | |
389 | accordingly. This property does not affect kernel behavior. | |
390 | The kernel does not provide button emulation for such devices but treats | |
391 | them as any other INPUT_PROP_BUTTONPAD device. | |
392 | ||
33096777 | 393 | INPUT_PROP_ACCELEROMETER |
acbdca8b MCC |
394 | ------------------------ |
395 | ||
33096777 | 396 | Directional axes on this device (absolute and/or relative x, y, z) represent |
227c011b RC |
397 | accelerometer data. Some devices also report gyroscope data, which devices |
398 | can report through the rotational axes (absolute and/or relative rx, ry, rz). | |
399 | ||
400 | All other axes retain their meaning. A device must not mix | |
33096777 PH |
401 | regular directional axes and accelerometer axes on the same event node. |
402 | ||
acbdca8b | 403 | Guidelines |
b1e064b8 | 404 | ========== |
acbdca8b | 405 | |
b1e064b8 | 406 | The guidelines below ensure proper single-touch and multi-finger functionality. |
61be51c1 | 407 | For multi-touch functionality, see the multi-touch-protocol.rst document for |
b1e064b8 CD |
408 | more information. |
409 | ||
acbdca8b MCC |
410 | Mice |
411 | ---- | |
412 | ||
b1e064b8 CD |
413 | REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report |
414 | the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report | |
415 | further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report | |
416 | scroll wheel events where available. | |
417 | ||
acbdca8b MCC |
418 | Touchscreens |
419 | ------------ | |
420 | ||
b1e064b8 CD |
421 | ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be |
422 | used to report when a touch is active on the screen. | |
423 | BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch | |
424 | contact. BTN_TOOL_<name> events should be reported where possible. | |
425 | ||
d04df023 HR |
426 | For new hardware, INPUT_PROP_DIRECT should be set. |
427 | ||
acbdca8b MCC |
428 | Trackpads |
429 | --------- | |
430 | ||
b1e064b8 CD |
431 | Legacy trackpads that only provide relative position information must report |
432 | events like mice described above. | |
433 | ||
434 | Trackpads that provide absolute touch position must report ABS_{X,Y} for the | |
435 | location of the touch. BTN_TOUCH should be used to report when a touch is active | |
436 | on the trackpad. Where multi-finger support is available, BTN_TOOL_<name> should | |
437 | be used to report the number of touches active on the trackpad. | |
438 | ||
d04df023 HR |
439 | For new hardware, INPUT_PROP_POINTER should be set. |
440 | ||
acbdca8b MCC |
441 | Tablets |
442 | ------- | |
443 | ||
b1e064b8 CD |
444 | BTN_TOOL_<name> events must be reported when a stylus or other tool is active on |
445 | the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH | |
446 | should be used to report when the tool is in contact with the tablet. | |
447 | BTN_{STYLUS,STYLUS2} should be used to report buttons on the tool itself. Any | |
448 | button may be used for buttons on the tablet except BTN_{MOUSE,LEFT}. | |
449 | BTN_{0,1,2,etc} are good generic codes for unlabeled buttons. Do not use | |
450 | meaningful buttons, like BTN_FORWARD, unless the button is labeled for that | |
451 | purpose on the device. | |
d04df023 HR |
452 | |
453 | For new hardware, both INPUT_PROP_DIRECT and INPUT_PROP_POINTER should be set. |