summaryrefslogtreecommitdiffstats
path: root/Documentation/input/event-codes.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/input/event-codes.txt')
-rw-r--r--Documentation/input/event-codes.txt318
1 files changed, 0 insertions, 318 deletions
diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.txt
deleted file mode 100644
index 53305bd..0000000
--- a/Documentation/input/event-codes.txt
+++ /dev/null
@@ -1,318 +0,0 @@
-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.
-
-Event types:
-===========
-Event 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.
-
-Event codes:
-===========
-Event 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.
-
-Device properties:
-=================
-Normally, userspace sets up an input device based on the data it emits,
-i.e., the event types. In the case of two devices emitting the same event
-types, additional information can be provided in the form of device
-properties.
-
-INPUT_PROP_DIRECT + INPUT_PROP_POINTER:
---------------------------------------
-The INPUT_PROP_DIRECT property indicates that device coordinates should be
-directly mapped to screen coordinates (not taking into account trivial
-transformations, such as scaling, flipping and rotating). Non-direct input
-devices require non-trivial transformation, such as absolute to relative
-transformation for touchpads. Typical direct input devices: touchscreens,
-drawing tablets; non-direct devices: touchpads, mice.
-
-The INPUT_PROP_POINTER property indicates that the device is not transposed
-on the screen and thus requires use of an on-screen pointer to trace user's
-movements. Typical pointer devices: touchpads, tablets, mice; non-pointer
-device: touchscreen.
-
-If neither INPUT_PROP_DIRECT or INPUT_PROP_POINTER are set, the property is
-considered undefined and the device type should be deduced in the
-traditional way, using emitted event types.
-
-INPUT_PROP_BUTTONPAD:
---------------------
-For touchpads where the button is placed beneath the surface, such that
-pressing down on the pad causes a button click, this property should be
-set. Common in clickpad notebooks and macbooks from 2009 and onwards.
-
-Originally, the buttonpad property was coded into the bcm5974 driver
-version field under the name integrated button. For backwards
-compatibility, both methods need to be checked in userspace.
-
-INPUT_PROP_SEMI_MT:
-------------------
-Some touchpads, most common between 2008 and 2011, can detect the presence
-of multiple contacts without resolving the individual positions; only the
-number of contacts and a rectangular shape is known. For such
-touchpads, the semi-mt property should be set.
-
-Depending on the device, the rectangle may enclose all touches, like a
-bounding box, or just some of them, for instance the two most recent
-touches. The diversity makes the rectangle of limited use, but some
-gestures can normally be extracted from it.
-
-If INPUT_PROP_SEMI_MT is not set, the device is assumed to be a true MT
-device.
-
-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.
-
-For new hardware, INPUT_PROP_DIRECT should be set.
-
-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.
-
-For new hardware, INPUT_PROP_POINTER should be set.
-
-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.
-
-For new hardware, both INPUT_PROP_DIRECT and INPUT_PROP_POINTER should be set.