263 lines
10 KiB
Plaintext
263 lines
10 KiB
Plaintext
The input protocol uses a map of types and codes to express input device values
|
|
to userspace. This document describes the types and codes and how and when they
|
|
may be used.
|
|
|
|
A single hardware event generates multiple input events. Each input event
|
|
contains the new value of a single data item. A special event type, EV_SYN, is
|
|
used to separate input events into packets of input data changes occurring at
|
|
the same moment in time. In the following, the term "event" refers to a single
|
|
input event encompassing a type, code, and value.
|
|
|
|
The input protocol is a stateful protocol. Events are emitted only when values
|
|
of event codes have changed. However, the state is maintained within the Linux
|
|
input subsystem; drivers do not need to maintain the state and may attempt to
|
|
emit unchanged values without harm. Userspace may obtain the current state of
|
|
event code values using the EVIOCG* ioctls defined in linux/input.h. The event
|
|
reports supported by a device are also provided by sysfs in
|
|
class/input/event*/device/capabilities/, and the properties of a device are
|
|
provided in class/input/event*/device/properties.
|
|
|
|
Types:
|
|
==========
|
|
Types are groupings of codes under a logical input construct. Each type has a
|
|
set of applicable codes to be used in generating events. See the Codes section
|
|
for details on valid codes for each type.
|
|
|
|
* EV_SYN:
|
|
- Used as markers to separate events. Events may be separated in time or in
|
|
space, such as with the multitouch protocol.
|
|
|
|
* EV_KEY:
|
|
- Used to describe state changes of keyboards, buttons, or other key-like
|
|
devices.
|
|
|
|
* EV_REL:
|
|
- Used to describe relative axis value changes, e.g. moving the mouse 5 units
|
|
to the left.
|
|
|
|
* EV_ABS:
|
|
- Used to describe absolute axis value changes, e.g. describing the
|
|
coordinates of a touch on a touchscreen.
|
|
|
|
* EV_MSC:
|
|
- Used to describe miscellaneous input data that do not fit into other types.
|
|
|
|
* EV_SW:
|
|
- Used to describe binary state input switches.
|
|
|
|
* EV_LED:
|
|
- Used to turn LEDs on devices on and off.
|
|
|
|
* EV_SND:
|
|
- Used to output sound to devices.
|
|
|
|
* EV_REP:
|
|
- Used for autorepeating devices.
|
|
|
|
* EV_FF:
|
|
- Used to send force feedback commands to an input device.
|
|
|
|
* EV_PWR:
|
|
- A special type for power button and switch input.
|
|
|
|
* EV_FF_STATUS:
|
|
- Used to receive force feedback device status.
|
|
|
|
Codes:
|
|
==========
|
|
Codes define the precise type of event.
|
|
|
|
EV_SYN:
|
|
----------
|
|
EV_SYN event values are undefined. Their usage is defined only by when they are
|
|
sent in the evdev event stream.
|
|
|
|
* SYN_REPORT:
|
|
- Used to synchronize and separate events into packets of input data changes
|
|
occurring at the same moment in time. For example, motion of a mouse may set
|
|
the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The next
|
|
motion will emit more REL_X and REL_Y values and send another SYN_REPORT.
|
|
|
|
* SYN_CONFIG:
|
|
- TBD
|
|
|
|
* SYN_MT_REPORT:
|
|
- Used to synchronize and separate touch events. See the
|
|
multi-touch-protocol.txt document for more information.
|
|
|
|
* SYN_DROPPED:
|
|
- Used to indicate buffer overrun in the evdev client's event queue.
|
|
Client should ignore all events up to and including next SYN_REPORT
|
|
event and query the device (using EVIOCG* ioctls) to obtain its
|
|
current state.
|
|
|
|
EV_KEY:
|
|
----------
|
|
EV_KEY events take the form KEY_<name> or BTN_<name>. For example, KEY_A is used
|
|
to represent the 'A' key on a keyboard. When a key is depressed, an event with
|
|
the key's code is emitted with value 1. When the key is released, an event is
|
|
emitted with value 0. Some hardware send events when a key is repeated. These
|
|
events have a value of 2. In general, KEY_<name> is used for keyboard keys, and
|
|
BTN_<name> is used for other types of momentary switch events.
|
|
|
|
A few EV_KEY codes have special meanings:
|
|
|
|
* BTN_TOOL_<name>:
|
|
- These codes are used in conjunction with input trackpads, tablets, and
|
|
touchscreens. These devices may be used with fingers, pens, or other tools.
|
|
When an event occurs and a tool is used, the corresponding BTN_TOOL_<name>
|
|
code should be set to a value of 1. When the tool is no longer interacting
|
|
with the input device, the BTN_TOOL_<name> code should be reset to 0. All
|
|
trackpads, tablets, and touchscreens should use at least one BTN_TOOL_<name>
|
|
code when events are generated.
|
|
|
|
* BTN_TOUCH:
|
|
BTN_TOUCH is used for touch contact. While an input tool is determined to be
|
|
within meaningful physical contact, the value of this property must be set
|
|
to 1. Meaningful physical contact may mean any contact, or it may mean
|
|
contact conditioned by an implementation defined property. For example, a
|
|
touchpad may set the value to 1 only when the touch pressure rises above a
|
|
certain value. BTN_TOUCH may be combined with BTN_TOOL_<name> codes. For
|
|
example, a pen tablet may set BTN_TOOL_PEN to 1 and BTN_TOUCH to 0 while the
|
|
pen is hovering over but not touching the tablet surface.
|
|
|
|
Note: For appropriate function of the legacy mousedev emulation driver,
|
|
BTN_TOUCH must be the first evdev code emitted in a synchronization frame.
|
|
|
|
Note: Historically a touch device with BTN_TOOL_FINGER and BTN_TOUCH was
|
|
interpreted as a touchpad by userspace, while a similar device without
|
|
BTN_TOOL_FINGER was interpreted as a touchscreen. For backwards compatibility
|
|
with current userspace it is recommended to follow this distinction. In the
|
|
future, this distinction will be deprecated and the device properties ioctl
|
|
EVIOCGPROP, defined in linux/input.h, will be used to convey the device type.
|
|
|
|
* BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP:
|
|
- These codes denote one, two, three, and four finger interaction on a
|
|
trackpad or touchscreen. For example, if the user uses two fingers and moves
|
|
them on the touchpad in an effort to scroll content on screen,
|
|
BTN_TOOL_DOUBLETAP should be set to value 1 for the duration of the motion.
|
|
Note that all BTN_TOOL_<name> codes and the BTN_TOUCH code are orthogonal in
|
|
purpose. A trackpad event generated by finger touches should generate events
|
|
for one code from each group. At most only one of these BTN_TOOL_<name>
|
|
codes should have a value of 1 during any synchronization frame.
|
|
|
|
Note: Historically some drivers emitted multiple of the finger count codes with
|
|
a value of 1 in the same synchronization frame. This usage is deprecated.
|
|
|
|
Note: In multitouch drivers, the input_mt_report_finger_count() function should
|
|
be used to emit these codes. Please see multi-touch-protocol.txt for details.
|
|
|
|
EV_REL:
|
|
----------
|
|
EV_REL events describe relative changes in a property. For example, a mouse may
|
|
move to the left by a certain number of units, but its absolute position in
|
|
space is unknown. If the absolute position is known, EV_ABS codes should be used
|
|
instead of EV_REL codes.
|
|
|
|
A few EV_REL codes have special meanings:
|
|
|
|
* REL_WHEEL, REL_HWHEEL:
|
|
- These codes are used for vertical and horizontal scroll wheels,
|
|
respectively.
|
|
|
|
EV_ABS:
|
|
----------
|
|
EV_ABS events describe absolute changes in a property. For example, a touchpad
|
|
may emit coordinates for a touch location.
|
|
|
|
A few EV_ABS codes have special meanings:
|
|
|
|
* ABS_DISTANCE:
|
|
- Used to describe the distance of a tool from an interaction surface. This
|
|
event should only be emitted while the tool is hovering, meaning in close
|
|
proximity of the device and while the value of the BTN_TOUCH code is 0. If
|
|
the input device may be used freely in three dimensions, consider ABS_Z
|
|
instead.
|
|
|
|
* ABS_MT_<name>:
|
|
- Used to describe multitouch input events. Please see
|
|
multi-touch-protocol.txt for details.
|
|
|
|
EV_SW:
|
|
----------
|
|
EV_SW events describe stateful binary switches. For example, the SW_LID code is
|
|
used to denote when a laptop lid is closed.
|
|
|
|
Upon binding to a device or resuming from suspend, a driver must report
|
|
the current switch state. This ensures that the device, kernel, and userspace
|
|
state is in sync.
|
|
|
|
Upon resume, if the switch state is the same as before suspend, then the input
|
|
subsystem will filter out the duplicate switch state reports. The driver does
|
|
not need to keep the state of the switch at any time.
|
|
|
|
EV_MSC:
|
|
----------
|
|
EV_MSC events are used for input and output events that do not fall under other
|
|
categories.
|
|
|
|
EV_LED:
|
|
----------
|
|
EV_LED events are used for input and output to set and query the state of
|
|
various LEDs on devices.
|
|
|
|
EV_REP:
|
|
----------
|
|
EV_REP events are used for specifying autorepeating events.
|
|
|
|
EV_SND:
|
|
----------
|
|
EV_SND events are used for sending sound commands to simple sound output
|
|
devices.
|
|
|
|
EV_FF:
|
|
----------
|
|
EV_FF events are used to initialize a force feedback capable device and to cause
|
|
such device to feedback.
|
|
|
|
EV_PWR:
|
|
----------
|
|
EV_PWR events are a special type of event used specifically for power
|
|
mangement. Its usage is not well defined. To be addressed later.
|
|
|
|
Guidelines:
|
|
==========
|
|
The guidelines below ensure proper single-touch and multi-finger functionality.
|
|
For multi-touch functionality, see the multi-touch-protocol.txt document for
|
|
more information.
|
|
|
|
Mice:
|
|
----------
|
|
REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report
|
|
the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report
|
|
further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report
|
|
scroll wheel events where available.
|
|
|
|
Touchscreens:
|
|
----------
|
|
ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be
|
|
used to report when a touch is active on the screen.
|
|
BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch
|
|
contact. BTN_TOOL_<name> events should be reported where possible.
|
|
|
|
Trackpads:
|
|
----------
|
|
Legacy trackpads that only provide relative position information must report
|
|
events like mice described above.
|
|
|
|
Trackpads that provide absolute touch position must report ABS_{X,Y} for the
|
|
location of the touch. BTN_TOUCH should be used to report when a touch is active
|
|
on the trackpad. Where multi-finger support is available, BTN_TOOL_<name> should
|
|
be used to report the number of touches active on the trackpad.
|
|
|
|
Tablets:
|
|
----------
|
|
BTN_TOOL_<name> events must be reported when a stylus or other tool is active on
|
|
the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH
|
|
should be used to report when the tool is in contact with the tablet.
|
|
BTN_{STYLUS,STYLUS2} should be used to report buttons on the tool itself. Any
|
|
button may be used for buttons on the tablet except BTN_{MOUSE,LEFT}.
|
|
BTN_{0,1,2,etc} are good generic codes for unlabeled buttons. Do not use
|
|
meaningful buttons, like BTN_FORWARD, unless the button is labeled for that
|
|
purpose on the device.
|