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

[Chris Bagwell]

On Wed, Dec 15, 2010 at 5:59 PM, Peter Hutterer
<peter.hutterer@xxxxxxxxx> wrote:
> 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@xxxxxxxxxxxxx>
>> ---
>>  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.

This area is where most special cases are so somehow I think it
deserves extra attention.  Either in paragraphs or in sample events.

There is the special historical case of touchscreen were
BTN_TOOL_FINGER is not sent; which mostly works because most
touchscreens do not support proximity/hover concepts.  It can
recommend not to use this approach and to use new ioctl() to convey
touchscreen vs. touchpad information.

Just an FYI: Synaptics is only sending BTN_TOUCH when pressure is >30
for what ever historical reason (and duplicating logic in
xf86-input-synaptics) so it usually won't be in same sync window as
BTN_TOOL_FINGER.  I think its only touchpad left doing this so I think
we may want to recommend best practice is to have BTN_TOOL_FINGER/*TAP
and BTN_TOUCH track each other when hover is not supported.

>
>
>> +
>> +* 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.

We should probably recommend a best practice here.  Almost all drivers
today send only 1 of BTN_TOOL_FINGER/*TAP today.  For example, if 1
touch then BTN_TOOL_FINGER=1 and BTN_TOOL_DOUBLETAP=0 and during 2
touch then BTN_TOOL_FINGER=0 and BTN_TOOL_DOUBLETAP=1.

I think at least 1 driver sends them concurrently today and you must
look for highest finger count tool.  I'm pretty sure historically a
lot of the drivers sent them concurrently as well.

>> +
>> +* 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 :)

:-)

It may be worth noting though that this is optional event.  When it
doesn't exist then BTN_TOUCH indicates touch.  When it does exist then
this is preferred indication of touch and should be used to debounced
touches because of fact that majority of touchpad/touchscreen will
start detecting contact while hovering.  But then that leads to
optional ABS_DISTANCE...

Chris

>
> 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
>
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/