lkml.org 
[lkml]   [2010]   [Dec]   [16]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    SubjectRe: [PATCH 2/4] Documentation: Add evdev type and code definitions
    From
    On Wed, Dec 15, 2010 at 5:59 PM, Peter Hutterer
    <peter.hutterer@who-t.net> 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@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.

    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@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

    \
     
     \ /
      Last update: 2010-12-16 15:59    [W:0.044 / U:59.840 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site