Orange Pi5 kernel

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