| 1 | |
| 2 |
|
| 3 | =================
|
| 4 | Input event codes
|
| 5 | =================
|
| 6 |
|
| 7 |
|
| 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 |
|
| 27 | Event types
|
| 28 | ===========
|
| 29 |
|
| 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.
|
| 33 |
|
| 34 | * EV_SYN:
|
| 35 |
|
| 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:
|
| 40 |
|
| 41 | - Used to describe state changes of keyboards, buttons, or other key-like
|
| 42 | devices.
|
| 43 |
|
| 44 | * EV_REL:
|
| 45 |
|
| 46 | - Used to describe relative axis value changes, e.g. moving the mouse 5 units
|
| 47 | to the left.
|
| 48 |
|
| 49 | * EV_ABS:
|
| 50 |
|
| 51 | - Used to describe absolute axis value changes, e.g. describing the
|
| 52 | coordinates of a touch on a touchscreen.
|
| 53 |
|
| 54 | * EV_MSC:
|
| 55 |
|
| 56 | - Used to describe miscellaneous input data that do not fit into other types.
|
| 57 |
|
| 58 | * EV_SW:
|
| 59 |
|
| 60 | - Used to describe binary state input switches.
|
| 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 input device.
|
| 77 |
|
| 78 | * EV_PWR:
|
| 79 |
|
| 80 | - A special type for power button and switch input.
|
| 81 |
|
| 82 | * EV_FF_STATUS:
|
| 83 |
|
| 84 | - Used to receive force feedback device status.
|
| 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 is defined only by when they are
|
| 95 | sent in the evdev event stream.
|
| 96 |
|
| 97 | * SYN_REPORT:
|
| 98 |
|
| 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:
|
| 105 |
|
| 106 | - TBD
|
| 107 |
|
| 108 | * SYN_MT_REPORT:
|
| 109 |
|
| 110 | - Used to synchronize and separate touch events. See the
|
| 111 | multi-touch-protocol.txt document for more information.
|
| 112 |
|
| 113 | * SYN_DROPPED:
|
| 114 |
|
| 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 |
|
| 120 | EV_KEY
|
| 121 | ------
|
| 122 |
|
| 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>:
|
| 133 |
|
| 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>
|
| 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.
|
| 145 |
|
| 146 | * BTN_TOUCH:
|
| 147 |
|
| 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:
|
| 168 |
|
| 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 |
|
| 184 | EV_REL
|
| 185 | ------
|
| 186 |
|
| 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:
|
| 195 |
|
| 196 | - These codes are used for vertical and horizontal scroll wheels,
|
| 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.
|
| 217 |
|
| 218 | EV_ABS
|
| 219 | ------
|
| 220 |
|
| 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:
|
| 227 |
|
| 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.
|
| 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.
|
| 237 |
|
| 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 |
|
| 244 | * ABS_SND_PROFILE:
|
| 245 |
|
| 246 | - Used to describe the state of a multi-value sound profile switch.
|
| 247 | An event is emitted only when the selected profile changes,
|
| 248 | indicating the newly selected profile value.
|
| 249 |
|
| 250 | * ABS_MT_<name>:
|
| 251 |
|
| 252 | - Used to describe multitouch input events. Please see
|
| 253 | multi-touch-protocol.txt for details.
|
| 254 |
|
| 255 | * ABS_PRESSURE/ABS_MT_PRESSURE:
|
| 256 |
|
| 257 | - For touch devices, many devices converted contact size into pressure.
|
| 258 | A finger flattens with pressure, causing a larger contact area and thus
|
| 259 | pressure and contact size are directly related. This is not the case
|
| 260 | for other devices, for example digitizers and touchpads with a true
|
| 261 | pressure sensor ("pressure pads").
|
| 262 |
|
| 263 | A device should set the resolution of the axis to indicate whether the
|
| 264 | pressure is in measurable units. If the resolution is zero, the
|
| 265 | pressure data is in arbitrary units. If the resolution is non-zero, the
|
| 266 | pressure data is in units/gram. For example, a value of 10 with a
|
| 267 | resolution of 1 represents 10 gram, a value of 10 with a resolution of
|
| 268 | 1000 represents 10 microgram.
|
| 269 |
|
| 270 | EV_SW
|
| 271 | -----
|
| 272 |
|
| 273 | EV_SW events describe stateful binary switches. For example, the SW_LID code is
|
| 274 | used to denote when a laptop lid is closed.
|
| 275 |
|
| 276 | Upon binding to a device or resuming from suspend, a driver must report
|
| 277 | the current switch state. This ensures that the device, kernel, and userspace
|
| 278 | state is in sync.
|
| 279 |
|
| 280 | Upon resume, if the switch state is the same as before suspend, then the input
|
| 281 | subsystem will filter out the duplicate switch state reports. The driver does
|
| 282 | not need to keep the state of the switch at any time.
|
| 283 |
|
| 284 | EV_MSC
|
| 285 | ------
|
| 286 |
|
| 287 | EV_MSC events are used for input and output events that do not fall under other
|
| 288 | categories.
|
| 289 |
|
| 290 | A few EV_MSC codes have special meaning:
|
| 291 |
|
| 292 | * MSC_TIMESTAMP:
|
| 293 |
|
| 294 | - Used to report the number of microseconds since the last reset. This event
|
| 295 | should be coded as an uint32 value, which is allowed to wrap around with
|
| 296 | no special consequence. It is assumed that the time difference between two
|
| 297 | consecutive events is reliable on a reasonable time scale (hours).
|
| 298 | A reset to zero can happen, in which case the time since the last event is
|
| 299 | unknown. If the device does not provide this information, the driver must
|
| 300 | not provide it to user space.
|
| 301 |
|
| 302 | EV_LED
|
| 303 | ------
|
| 304 |
|
| 305 | EV_LED events are used for input and output to set and query the state of
|
| 306 | various LEDs on devices.
|
| 307 |
|
| 308 | EV_REP
|
| 309 | ------
|
| 310 |
|
| 311 | EV_REP events are used for specifying autorepeating events.
|
| 312 |
|
| 313 | EV_SND
|
| 314 | ------
|
| 315 |
|
| 316 | EV_SND events are used for sending sound commands to simple sound output
|
| 317 | devices.
|
| 318 |
|
| 319 | EV_FF
|
| 320 | -----
|
| 321 |
|
| 322 | EV_FF events are used to initialize a force feedback capable device and to cause
|
| 323 | such device to feedback.
|
| 324 |
|
| 325 | EV_PWR
|
| 326 | ------
|
| 327 |
|
| 328 | EV_PWR events are a special type of event used specifically for power
|
| 329 | management. Its usage is not well defined. To be addressed later.
|
| 330 |
|
| 331 | Device properties
|
| 332 | =================
|
| 333 |
|
| 334 | Normally, userspace sets up an input device based on the data it emits,
|
| 335 | i.e., the event types. In the case of two devices emitting the same event
|
| 336 | types, additional information can be provided in the form of device
|
| 337 | properties.
|
| 338 |
|
| 339 | INPUT_PROP_DIRECT + INPUT_PROP_POINTER
|
| 340 | --------------------------------------
|
| 341 |
|
| 342 | The INPUT_PROP_DIRECT property indicates that device coordinates should be
|
| 343 | directly mapped to screen coordinates (not taking into account trivial
|
| 344 | transformations, such as scaling, flipping and rotating). Non-direct input
|
| 345 | devices require non-trivial transformation, such as absolute to relative
|
| 346 | transformation for touchpads. Typical direct input devices: touchscreens,
|
| 347 | drawing tablets; non-direct devices: touchpads, mice.
|
| 348 |
|
| 349 | The INPUT_PROP_POINTER property indicates that the device is not transposed
|
| 350 | on the screen and thus requires use of an on-screen pointer to trace user's
|
| 351 | movements. Typical pointer devices: touchpads, tablets, mice; non-pointer
|
| 352 | device: touchscreen.
|
| 353 |
|
| 354 | If neither INPUT_PROP_DIRECT or INPUT_PROP_POINTER are set, the property is
|
| 355 | considered undefined and the device type should be deduced in the
|
| 356 | traditional way, using emitted event types.
|
| 357 |
|
| 358 | INPUT_PROP_BUTTONPAD
|
| 359 | --------------------
|
| 360 |
|
| 361 | For touchpads where the button is placed beneath the surface, such that
|
| 362 | pressing down on the pad causes a button click, this property should be
|
| 363 | set. Common in Clickpad notebooks and Macbooks from 2009 and onwards.
|
| 364 |
|
| 365 | Originally, the buttonpad property was coded into the bcm5974 driver
|
| 366 | version field under the name integrated button. For backwards
|
| 367 | compatibility, both methods need to be checked in userspace.
|
| 368 |
|
| 369 | INPUT_PROP_SEMI_MT
|
| 370 | ------------------
|
| 371 |
|
| 372 | Some touchpads, most common between 2008 and 2011, can detect the presence
|
| 373 | of multiple contacts without resolving the individual positions; only the
|
| 374 | number of contacts and a rectangular shape is known. For such
|
| 375 | touchpads, the SEMI_MT property should be set.
|
| 376 |
|
| 377 | Depending on the device, the rectangle may enclose all touches, like a
|
| 378 | bounding box, or just some of them, for instance the two most recent
|
| 379 | touches. The diversity makes the rectangle of limited use, but some
|
| 380 | gestures can normally be extracted from it.
|
| 381 |
|
| 382 | If INPUT_PROP_SEMI_MT is not set, the device is assumed to be a true MT
|
| 383 | device.
|
| 384 |
|
| 385 | INPUT_PROP_TOPBUTTONPAD
|
| 386 | -----------------------
|
| 387 |
|
| 388 | Some laptops, most notably the Lenovo 40 series provide a trackstick
|
| 389 | device but do not have physical buttons associated with the trackstick
|
| 390 | device. Instead, the top area of the touchpad is marked to show
|
| 391 | visual/haptic areas for left, middle, right buttons intended to be used
|
| 392 | with the trackstick.
|
| 393 |
|
| 394 | If INPUT_PROP_TOPBUTTONPAD is set, userspace should emulate buttons
|
| 395 | accordingly. This property does not affect kernel behavior.
|
| 396 | The kernel does not provide button emulation for such devices but treats
|
| 397 | them as any other INPUT_PROP_BUTTONPAD device.
|
| 398 |
|
| 399 | INPUT_PROP_ACCELEROMETER
|
| 400 | ------------------------
|
| 401 |
|
| 402 | Directional axes on this device (absolute and/or relative x, y, z) represent
|
| 403 | accelerometer data. Some devices also report gyroscope data, which devices
|
| 404 | can report through the rotational axes (absolute and/or relative rx, ry, rz).
|
| 405 |
|
| 406 | All other axes retain their meaning. A device must not mix
|
| 407 | regular directional axes and accelerometer axes on the same event node.
|
| 408 |
|
| 409 | INPUT_PROP_PRESSUREPAD
|
| 410 | ----------------------
|
| 411 |
|
| 412 | The INPUT_PROP_PRESSUREPAD property indicates that the device provides
|
| 413 | simulated haptic feedback (e.g. a vibrator motor situated below the surface)
|
| 414 | instead of physical haptic feedback (e.g. a hinge). This property is only set
|
| 415 | if the device:
|
| 416 |
|
| 417 | - can differentiate between at least 5 fingers
|
| 418 | - uses correct resolution for the X/Y (units and value)
|
| 419 | - follows the MT protocol type B
|
| 420 |
|
| 421 | If the simulated haptic feedback is controllable by userspace the device must:
|
| 422 |
|
| 423 | - support simple haptic auto and manual triggering, and
|
| 424 | - report correct force per touch, and correct units for them (newtons or grams), and
|
| 425 | - provide the EV_FF FF_HAPTIC force feedback effect.
|
| 426 |
|
| 427 | Summing up, such devices follow the MS spec for input devices in
|
| 428 | Win8 and Win8.1, and in addition may support the Simple haptic controller HID
|
| 429 | table, and report correct units for the pressure.
|
| 430 |
|
| 431 | Where applicable, this property is set in addition to INPUT_PROP_BUTTONPAD, it
|
| 432 | does not replace that property.
|
| 433 |
|
| 434 | Guidelines
|
| 435 | ==========
|
| 436 |
|
| 437 | The guidelines below ensure proper single-touch and multi-finger functionality.
|
| 438 | For multi-touch functionality, see the multi-touch-protocol.rst document for
|
| 439 | more information.
|
| 440 |
|
| 441 | Mice
|
| 442 | ----
|
| 443 |
|
| 444 | REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report
|
| 445 | the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report
|
| 446 | further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report
|
| 447 | scroll wheel events where available.
|
| 448 |
|
| 449 | Touchscreens
|
| 450 | ------------
|
| 451 |
|
| 452 | ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be
|
| 453 | used to report when a touch is active on the screen.
|
| 454 | BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch
|
| 455 | contact. BTN_TOOL_<name> events should be reported where possible.
|
| 456 |
|
| 457 | For new hardware, INPUT_PROP_DIRECT should be set.
|
| 458 |
|
| 459 | Trackpads
|
| 460 | ---------
|
| 461 |
|
| 462 | Legacy trackpads that only provide relative position information must report
|
| 463 | events like mice described above.
|
| 464 |
|
| 465 | Trackpads that provide absolute touch position must report ABS_{X,Y} for the
|
| 466 | location of the touch. BTN_TOUCH should be used to report when a touch is active
|
| 467 | on the trackpad. Where multi-finger support is available, BTN_TOOL_<name> should
|
| 468 | be used to report the number of touches active on the trackpad.
|
| 469 |
|
| 470 | For new hardware, INPUT_PROP_POINTER should be set.
|
| 471 |
|
| 472 | Tablets
|
| 473 | -------
|
| 474 |
|
| 475 | BTN_TOOL_<name> events must be reported when a stylus or other tool is active on
|
| 476 | the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH
|
| 477 | should be used to report when the tool is in contact with the tablet.
|
| 478 | BTN_{STYLUS,STYLUS2} should be used to report buttons on the tool itself. Any
|
| 479 | button may be used for buttons on the tablet except BTN_{MOUSE,LEFT}.
|
| 480 | BTN_{0,1,2,etc} are good generic codes for unlabeled buttons. Do not use
|
| 481 | meaningful buttons, like BTN_FORWARD, unless the button is labeled for that
|
| 482 | purpose on the device.
|
| 483 |
|
| 484 | For new hardware, both INPUT_PROP_DIRECT and INPUT_PROP_POINTER should be set.
|