Re: [PATCH 2/4] Documentation: Add evdev type and code definitions

[Peter Hutterer <peter.hutterer@who-t.net>]

On Tue, Dec 14, 2010 at 01:21:10PM -0800, Chase Douglas wrote:
> This commit adds the file Documentation/input/evdev-codes.txt.
> 
> Signed-off-by: Chase Douglas <chase.douglas@canonical.com>
> ---
>  Documentation/input/evdev-codes.txt |  160 +++++++++++++++++++++++++++++++++++
>  1 files changed, 160 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/input/evdev-codes.txt
> 
> diff --git a/Documentation/input/evdev-codes.txt b/Documentation/input/evdev-codes.txt
> new file mode 100644
> index 0000000..69c810f
> --- /dev/null
> +++ b/Documentation/input/evdev-codes.txt
> @@ -0,0 +1,160 @@
> +The evdev 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.
> +
> +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 keyboard and other key-like input events.
> +* EV_REL:
> +  - Used to describe relative input events, e.g. moving the mouse 5 units to the
> +    left.
> +* EV_ABS:
> +  - Used to describe absolute input events, e.g. describing the coordinates of a
> +    touch on a touchscreen.
> +* EV_MSC:
> +  - Used to describe miscellaneous input events 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 Codes:
> +----------
> +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 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.
> +
> +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 depressed, an event is
> +emitted with value 0. In general, KEY_<name> is used for keyboard keys, and
> +BTN_<name> is used for other types of momentary switch events.

repeat keys have value 2, might want to add this here.

> +
> +A few EV_KEY codes have special meanings:
> +
> +* BTN_TOOL_<name>, BTN_TOUCH:
> +  - 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. For non-tablet devices, the tool is usually
> +    BTN_TOUCH.

BTN_TOUCH is used as proximity delimiter. e.g. wacom sends BTN_TOOL_PEN when
the pen comes into proximity and (in addition) BTN_TOUCH when the pen
actually touches the tablet. synaptics does the same IIRC except that it
doesn't support hovering, so BTN_TOOL_FINGER and BTN_TOUCH are always
set/unset in the same EV_SYN frame.


> +
> +* 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 these codes and the BTN_TOOL_<name> and BTN_TOUCH codes are
> +    orthogonal in purpose. A trackpad event generated by finger touches should
> +    generate events for one code from each group.
> +
> +* KEY_SUSPEND, KEY_POWER:
> +  - These codes are reserved for the EV_PWR type.
> +
> +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.

I'm not sure they're special, other than in X where we still treat them as
buttons by convention. It's good to describe them here, just in case, but I
wouldn't call that a "special meaning".

> +
> +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_PRESSURE:
> +  - Used to describe the pressure of a touch interaction on an input device.

again, that's not really special IMO. it pretty much does what it says on
the box :)

fwiw, I know that even though the documentation should be enough as-is,
having a few simple examples are always really useful to form the picture in
one's head. especially for newcomers who don't understand the basic concepts
yet.

just something like:
"for example, an absolute device moving to a new position and pressing and
releasing a button may send events like this:
code            value
-----------------------
ABS_X           10
ABS_Y           100
BTN_LEFT        1
EV_SYN          SYN_REPORT
BTN_LEFT        0
EV_SYN          SYN_REPORT

This immediately makes it obvious that buttons and axes can be mixed in the
same frame. you may want to also point to a few tools that show the event
stream (evtest comes to mind as the most widely distributed).

Cheers,
  Peter

> +* ABS_DISTANCE:
> +  - Used to describe the distance of a tool from an interaction surface. This
> +    should only be used while the tool is in close proximity of the device. 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.
> +
> +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 key event used specifically for monitoring
> +power buttons and switches. The two codes in use are:
> +
> +* KEY_POWER:
> +  - Used to denote a power button event.
> +* KEY_SUSPEND:
> +  - Used to denote a suspend button event.
> -- 
> 1.7.1