[PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Chase Douglas]

Hello all,

I was left somewhat dissatisfied by the MT_TOOL_ENVELOPE addition, so I decided
to try to propose a different solution for the problem. As a recap, the problem
can best be defined by Synaptics hardware that provide two touch coordinates
(X1, Y1) and (X2, Y2). Unfortunately, the real touches may be at (X1, Y2) and
(X2, Y1). Further, three touches may be recognized, but only two coordinates are
reported.

Following this are four patches. The first merely reverts the MT_TOOL_ENVELOPE
addition. The second adds documentation for evdev codes to the Documentation
directory. It was hastily created, so it has some ommissions and may have some
mistakes. My hope is that we keep this or a similar document up to date whenever
non-obvious codes are added to evdev. The third patch adds the following EV_ABS
codes:

ABS_RECT_MIN_X
ABS_RECT_MIN_Y
ABS_RECT_MAX_X
ABS_RECT_MAX_Y

The purpose of these codes is to provide for devices that at best report a
rectangular bounding box of touches. Instead of using the MT evdev protocol,
this approach uses ST protocol semantics.

Finally, the last patch adds support for the above codes to the synaptics
driver.

It is my belief that this is a better interface than MT_TOOL_ENVELOPE for the
following reasons:

* The code meanings are more readily graspable from the names
* The codes behave with ST semantics, which is useful because we likely cannot
  split properties like pressure and orientation among the touches
* ST semantics are easier to comprehend than MT semantics, and MT isn't required
  to solve this problem
* The codes provide only the max and min values, none in between. This is in
  contrast with MT_TOOL_ENVELOPE, which provides all touches as presented by the
  hardware. However, we don't trust all the coordinate pairings, so providing
  faulty pairings may induce incorrect userspace usage of the events.
* A clear distinction is made here that full multitouch devices should use the
  MT protocol, while lesser devices should use the ST protocol.

Thanks!

-- Chase

[PATCH 1/4] Revert "input: mt: Interface and MT_TOOL documentation updates"

[Chase Douglas]

The new MT_TOOL_ENVELOPE code has ambiguities that may be remedied by
changing to a different interface construct.

This reverts commit e665f5646d4b7d0b470be6afd817edfb43556921.

Signed-off-by: Chase Douglas <chase.douglas@canonical.com>
---
 Documentation/input/multi-touch-protocol.txt |   39 ++++++++------------------
 include/linux/input.h                        |    6 ++--
 2 files changed, 15 insertions(+), 30 deletions(-)

diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt
index 5ab352e..351fab8 100644
--- a/Documentation/input/multi-touch-protocol.txt
+++ b/Documentation/input/multi-touch-protocol.txt
@@ -169,14 +169,12 @@ described by adding the MINOR parameters, such that MAJOR and MINOR are the
 major and minor axis of an ellipse. Finally, the orientation of the oval
 shape can be describe with the ORIENTATION parameter.
 
-For type A devices, further specification of the touch shape is possible
-via ABS_MT_BLOB_ID.
-
 The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
-contact or a pen or something else. Finally, the ABS_MT_TRACKING_ID event
-may be used to track identified contacts over time [5]. In the type B
-protocol, the use of ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID is implicit
-via the input_mt_report_slot_state() function.
+contact or a pen or something else.  Devices with more granular information
+may specify general shapes as blobs, i.e., as a sequence of rectangular
+shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices
+that currently support it, the ABS_MT_TRACKING_ID event may be used to
+report contact tracking from hardware [5].
 
 
 Event Semantics
@@ -248,35 +246,22 @@ ABS_MT_TOOL_TYPE
 
 The type of approaching tool. A lot of kernel drivers cannot distinguish
 between different tool types, such as a finger or a pen. In such cases, the
-event should be omitted. The protocol currently supports MT_TOOL_FINGER,
-MT_TOOL_PEN and MT_TOOL_ENVELOPE [2]. For type B devices, this event is
-handled by input core, via the input_mt interface.
-
-- The MT_TOOL_FINGER type is the default, and represents a finger touch.
-
-- The MT_TOOL_PEN type represents a pen, and the list of related tools is
-expected to grow with time.
-
-- The MT_TOOL_ENVELOPE type is used to indicate that the contact position
-is not well-defined, and is only used for legacy hardware. The real contact
-positions are to be found within the bounding rectangle formed by the
-envelope contact positions.
+event should be omitted. The protocol currently supports MT_TOOL_FINGER and
+MT_TOOL_PEN and MT_TOOL_ENVELOPE [2].
 
 ABS_MT_BLOB_ID
 
 The BLOB_ID groups several packets together into one arbitrarily shaped
-contact. The sequence of points forms a polygon which defines the shape of
-the contact. This is a low-level anonymous grouping for type A devices, and
+contact. This is a low-level anonymous grouping for type A devices, and
 should not be confused with the high-level trackingID [5]. Most type A
 devices do not have blob capability, so drivers can safely omit this event.
 
 ABS_MT_TRACKING_ID
 
 The TRACKING_ID identifies an initiated contact throughout its life cycle
-[5]. The value range of the TRACKING_ID should be large enough to ensure
-unique identification of a contact maintained over an extended period of
-time. For type B devices, this event is handled by input core, via the
-input_mt interface.
+[5]. This event is mandatory for type B devices. The value range of the
+TRACKING_ID should be large enough to ensure unique identification of a
+contact maintained over an extended period of time.
 
 
 Event Computation
@@ -336,6 +321,6 @@ difference between the contact position and the approaching tool position
 could be used to derive tilt.
 [2] ABS_MT_ENVELOPE contacts represent an envelope of the contacts rather
 than the actual contacts. Used with older, not fully MT capable, devices.
-[3] The mtdev project: http://bitmath.org/code/mtdev/.
+[3] Multitouch X driver project: http://bitmath.org/code/multitouch/.
 [4] See the section on event computation.
 [5] See the section on finger tracking.
diff --git a/include/linux/input.h b/include/linux/input.h
index 787aa7e..cd0618c 100644
--- a/include/linux/input.h
+++ b/include/linux/input.h
@@ -847,9 +847,9 @@ struct input_keymap_entry {
 /*
  * MT_TOOL types
  */
-#define MT_TOOL_FINGER		0	/* normal finger */
-#define MT_TOOL_PEN		1	/* pen tool */
-#define MT_TOOL_ENVELOPE	2	/* rectangle corner - older hw only */
+#define MT_TOOL_FINGER		0
+#define MT_TOOL_PEN		1
+#define MT_TOOL_ENVELOPE	2
 #define MT_TOOL_MAX		2
 
 /*
-- 
1.7.1

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

[Chase Douglas]

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

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

[Peter Hutterer]

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

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@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
>

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

[Dmitry Torokhov]

On Thu, Dec 16, 2010 at 08:56:58AM -0600, Chris Bagwell wrote:
> 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.

mousedev. Synaptics devices used to be (still are?) very sensitive and
if you start sending BTN_TOUCH whenever you detect contact the touchpad
is not useable without synaptics X driver.

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

Alps does this as well. Any device that starts sending contacts while
hovering should consider legacy drivers when choosing when to emit
BTN_TOUCH.

-- 
Dmitry
--
To unsubscribe from this list: send the line "unsubscribe linux-input" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Chase Douglas]

On 12/16/2010 09:56 AM, Chris Bagwell wrote:
> 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:
>>> +* 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.

I have attempted to capture this in the document.

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

I tried to convey both points in the documentation for these codes, and
hopefully examples added to the document will help as well.

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

All of the evdev codes are optional, unless stated somewhere in here
otherwise like BTN_TOUCH (in my next revision). I feel this falls into
how userspace should use the codes, not the definition of the codes.

Thanks!

-- Chase

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

[Chase Douglas]

On 12/15/2010 06:59 PM, Peter Hutterer wrote:
> On Tue, Dec 14, 2010 at 01:21:10PM -0800, Chase Douglas wrote:
>> +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.

Done.

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

I've added wording for this.

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

In my mind I thought people may confuse this with a generic knob input
device. I've seen these in the local Apple store, and I believe they are
used primarily for professional a/v editing to go forward and backward
in time. I don't believe such devices should be using either of these
codes, so I defined the codes to be for scroll wheels.

Any objections?

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

I think I had something in mind for this like the above REL_WHEEL, but I
can't think of it now. After re-reading this description, I don't think
it yields any new information that can't be gleaned from the code name
itself, so I've yanked it from the document.

> 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).

I would like to see this as well, but I think I'll leave the initial
commit to just the protocol documentation. We should add these in a
subsequent commit (and I'm running out of time at the moment :).

Thanks!

-- Chase

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

[Henrik Rydberg]

Hi Chase,

this is very nice, thanks for doing this! Comments inline.

On 12/14/2010 10:21 PM, 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.


On a general note, the transfer is stateful. It is assumed that the receiver
knows that prior state of an axes when the new value comes in. Only changed
values are emitted.

Most of the input state can be retrieved via ioctl/sysfs calls.

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


We have not using the name @frame@ much so far, but i think it is a good name
for it.

> +* 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.
> +
> +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 always required, and on top of that, one or several other BTN_TOOL
can be used. There is also a quirk in that BTN_TOUCH should come first in the
event stream, for the benefit of the mousedev emulation driver.

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


In the input-mt interface, there is a function to report these,
input_mt_report_finger_count().

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


The word "hovering" is commonly used to describe this usage. Many pen tablets
use it, and touch versions are emerging.

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


Thanks,
Henrik

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

[Chase Douglas]

On 12/16/2010 09:12 AM, Henrik Rydberg wrote:
> On 12/14/2010 10:21 PM, Chase Douglas wrote:
>> +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.
> 
> 
> On a general note, the transfer is stateful. It is assumed that the receiver
> knows that prior state of an axes when the new value comes in. Only changed
> values are emitted.
> 
> Most of the input state can be retrieved via ioctl/sysfs calls.

I've noted both of these for the next revision.

>> +* 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.
> 
> 
> We have not using the name @frame@ much so far, but i think it is a good name
> for it.

Good idea. I began using 'frame' name for the next revision.

>> +* 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 always required, and on top of that, one or several other BTN_TOOL
> can be used. There is also a quirk in that BTN_TOUCH should come first in the
> event stream, for the benefit of the mousedev emulation driver.

I've tried to address both issues in the next revision.

>> +* 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.
> 
> 
> In the input-mt interface, there is a function to report these,
> input_mt_report_finger_count().

I've added a note about this.

>> +* 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.
> 
> 
> The word "hovering" is commonly used to describe this usage. Many pen tablets
> use it, and touch versions are emerging.

I added use of the word 'hovering' to be clear.

Thanks!

-- Chase

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

[Nikolai Kondrashov]

Hi Chase,

Thank you for this work :)

On 12/15/2010 12:21 AM, Chase Douglas wrote:
> +* 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.
One minor note: some cheap tablets don't send any BTN_TOOL_*, but only a
BTN_TOUCH. These include UC-Logic tablets (drivers/hid/hid-uclogic.c).

Sincerely,
Nick

[PATCH 3/4] Input: Add ABS_RECT_* legacy multitouch evdev codes

[Chase Douglas]

The ABS_RECT_* codes allow for partial multitouch support for devices
that do not provide accurate touch coordinate pairings. For example, a
device may emit two touches at points (X1, Y1) and (X2, Y2); however,
the real touch coordinates may be (X1, Y2) and (X2, Y1). Providing a
bounding rectangle allows for panning and pinching multitouch support.

Signed-off-by: Chase Douglas <chase.douglas@canonical.com>
---
 Documentation/input/evdev-codes.txt |   10 ++++++++++
 include/linux/input.h               |    5 +++++
 2 files changed, 15 insertions(+), 0 deletions(-)

diff --git a/Documentation/input/evdev-codes.txt b/Documentation/input/evdev-codes.txt
index 69c810f..65db20e 100644
--- a/Documentation/input/evdev-codes.txt
+++ b/Documentation/input/evdev-codes.txt
@@ -116,6 +116,16 @@ A few EV_ABS codes have special meanings:
     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_RECT_MIN_X, ABS_RECT_MIN_Y, ABS_RECT_MAX_X, ABS_RECT_MAX_Y:
+  - Used to convey partial multitouch support. Some legacy device multitouch
+    coordinates are not accurate enough to be relied on directly. For example,
+    the device may give coordinates (X1, Y1) and (X2, Y2) for two touch points,
+    but in reality the touches are at (X1, Y2) and (X2, Y1). The maximum and
+    minimum axis values are accurate, so they may be used to provide a rectangle
+    bounding box for the touches.
+    The values for these codes are undefined unless two or more touches are
+    active, designated by BTN_TOOL_DOUBLETAP or higher order code being set to
+    1.
 * ABS_MT_<name>:
   - Used to describe multitouch input events. Please see
     multi-touch-protocol.txt for details.
diff --git a/include/linux/input.h b/include/linux/input.h
index cd0618c..5acdc60 100644
--- a/include/linux/input.h
+++ b/include/linux/input.h
@@ -719,6 +719,11 @@ struct input_keymap_entry {
 
 #define ABS_VOLUME		0x20
 
+#define ABS_RECT_MIN_X		0x21
+#define ABS_RECT_MIN_Y		0x22
+#define ABS_RECT_MAX_X		0x23
+#define ABS_RECT_MAX_Y		0x24
+
 #define ABS_MISC		0x28
 
 #define ABS_MT_SLOT		0x2f	/* MT slot being modified */
-- 
1.7.1

[PATCH 4/4] Input: synaptics - Add support for ABS_RECT_*

[Chase Douglas]

Add support for partial multitouch support through the ABS_RECT_* evdev
codes.

Signed-off-by: Chase Douglas <chase.douglas@canonical.com>
---
 drivers/input/mouse/synaptics.c |   18 ++++++++++++++++++
 1 files changed, 18 insertions(+), 0 deletions(-)

diff --git a/drivers/input/mouse/synaptics.c b/drivers/input/mouse/synaptics.c
index 2e300a4..7cebdce 100644
--- a/drivers/input/mouse/synaptics.c
+++ b/drivers/input/mouse/synaptics.c
@@ -525,6 +525,13 @@ static void synaptics_process_packet(struct psmouse *psmouse)
 	}
 	input_report_abs(dev, ABS_PRESSURE, hw.z);
 
+	if (priv->multitouch && num_fingers >= 2) {
+		input_report_abs(dev, ABS_RECT_MIN_X, min(hw.x, priv->mt.x));
+		input_report_abs(dev, ABS_RECT_MAX_X, max(hw.x, priv->mt.x));
+		input_report_abs(dev, ABS_RECT_MIN_Y, min(hw.y, priv->mt.y));
+		input_report_abs(dev, ABS_RECT_MAX_Y, max(hw.y, priv->mt.y));
+	}
+
 	if (SYN_CAP_PALMDETECT(priv->capabilities))
 		input_report_abs(dev, ABS_TOOL_WIDTH, finger_width);
 
@@ -667,6 +674,17 @@ static void set_input_params(struct input_dev *dev, struct synaptics_data *priv)
 		__clear_bit(BTN_RIGHT, dev->keybit);
 		__clear_bit(BTN_MIDDLE, dev->keybit);
 	}
+
+	if (priv->multitouch) {
+		input_set_abs_params(dev, ABS_RECT_MIN_X, XMIN_NOMINAL,
+				     priv->x_max ?: XMAX_NOMINAL, 0, 0);
+		input_set_abs_params(dev, ABS_RECT_MAX_X, XMIN_NOMINAL,
+				     priv->x_max ?: XMAX_NOMINAL, 0, 0);
+		input_set_abs_params(dev, ABS_RECT_MIN_Y, YMIN_NOMINAL,
+				     priv->y_max ?: YMAX_NOMINAL, 0, 0);
+		input_set_abs_params(dev, ABS_RECT_MAX_Y, YMIN_NOMINAL,
+				     priv->y_max ?: YMAX_NOMINAL, 0, 0);
+	}
 }
 
 static void synaptics_disconnect(struct psmouse *psmouse)
-- 
1.7.1

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Chase Douglas]

On 12/14/2010 01:21 PM, Chase Douglas wrote:
> Hello all,
> 
> I was left somewhat dissatisfied by the MT_TOOL_ENVELOPE addition, so I decided
> to try to propose a different solution for the problem. As a recap, the problem
> can best be defined by Synaptics hardware that provide two touch coordinates
> (X1, Y1) and (X2, Y2). Unfortunately, the real touches may be at (X1, Y2) and
> (X2, Y1). Further, three touches may be recognized, but only two coordinates are
> reported.
> 
> Following this are four patches.

[...]

I forgot to mention that these apply on top of Dmitry's next tree plus
the first synaptics multitouch patch. My bad :(.

-- Chase

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Dmitry Torokhov]

Hi Chase,

On Tue, Dec 14, 2010 at 01:21:08PM -0800, Chase Douglas wrote:
> Hello all,
> 
> I was left somewhat dissatisfied by the MT_TOOL_ENVELOPE addition, so I decided
> to try to propose a different solution for the problem. As a recap, the problem
> can best be defined by Synaptics hardware that provide two touch coordinates
> (X1, Y1) and (X2, Y2). Unfortunately, the real touches may be at (X1, Y2) and
> (X2, Y1). Further, three touches may be recognized, but only two coordinates are
> reported.
> 
> Following this are four patches. The first merely reverts the MT_TOOL_ENVELOPE
> addition. The second adds documentation for evdev codes to the Documentation
> directory. It was hastily created, so it has some ommissions and may have some
> mistakes. My hope is that we keep this or a similar document up to date whenever
> non-obvious codes are added to evdev.

This is great, thank you.

> The third patch adds the following EV_ABS
> codes:
> 
> ABS_RECT_MIN_X
> ABS_RECT_MIN_Y
> ABS_RECT_MAX_X
> ABS_RECT_MAX_Y
> 
> The purpose of these codes is to provide for devices that at best report a
> rectangular bounding box of touches. Instead of using the MT evdev protocol,
> this approach uses ST protocol semantics.
> 
> Finally, the last patch adds support for the above codes to the synaptics
> driver.
> 
> It is my belief that this is a better interface than MT_TOOL_ENVELOPE for the
> following reasons:
> 
> * The code meanings are more readily graspable from the names
> * The codes behave with ST semantics, which is useful because we likely cannot
>   split properties like pressure and orientation among the touches
> * ST semantics are easier to comprehend than MT semantics, and MT isn't required
>   to solve this problem
> * The codes provide only the max and min values, none in between. This is in
>   contrast with MT_TOOL_ENVELOPE, which provides all touches as presented by the
>   hardware. However, we don't trust all the coordinate pairings, so providing
>   faulty pairings may induce incorrect userspace usage of the events.
> * A clear distinction is made here that full multitouch devices should use the
>   MT protocol, while lesser devices should use the ST protocol.
> 

No, I do not agree with this proposal. This would introduce new _axes_
(with potentially different min, max, resolution, etc) for the working
surface of the devices instead of merely saying that the device may
report more than simple singular contact within the standard axes.

I believe that MT protocol _is_ the correct vehicle to transmit semi-MT
device state to userspace.

As to reporting more than 2 contacts with MT_TOOL_ENVELOPE - I think we
should not do that. Instead we should only report 2 outermost points of
the bounding rectangle as MT_TOOL_ENVELOPE and convey number of contacts
with BTN_TOOL_xxxTAP (so up to 4 contacts, at least for now).

Thanks.

-- 
Dmitry

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Chase Douglas]

On 12/14/2010 02:12 PM, Dmitry Torokhov wrote:
> Hi Chase,
> 
> On Tue, Dec 14, 2010 at 01:21:08PM -0800, Chase Douglas wrote:
>> Hello all,
>>
>> I was left somewhat dissatisfied by the MT_TOOL_ENVELOPE addition, so I decided
>> to try to propose a different solution for the problem. As a recap, the problem
>> can best be defined by Synaptics hardware that provide two touch coordinates
>> (X1, Y1) and (X2, Y2). Unfortunately, the real touches may be at (X1, Y2) and
>> (X2, Y1). Further, three touches may be recognized, but only two coordinates are
>> reported.
>>
>> Following this are four patches. The first merely reverts the MT_TOOL_ENVELOPE
>> addition. The second adds documentation for evdev codes to the Documentation
>> directory. It was hastily created, so it has some ommissions and may have some
>> mistakes. My hope is that we keep this or a similar document up to date whenever
>> non-obvious codes are added to evdev.
> 
> This is great, thank you.

I've found a few formatting issues, so don't apply it quite yet.

>> The third patch adds the following EV_ABS
>> codes:
>>
>> ABS_RECT_MIN_X
>> ABS_RECT_MIN_Y
>> ABS_RECT_MAX_X
>> ABS_RECT_MAX_Y
>>
>> The purpose of these codes is to provide for devices that at best report a
>> rectangular bounding box of touches. Instead of using the MT evdev protocol,
>> this approach uses ST protocol semantics.
>>
>> Finally, the last patch adds support for the above codes to the synaptics
>> driver.
>>
>> It is my belief that this is a better interface than MT_TOOL_ENVELOPE for the
>> following reasons:
>>
>> * The code meanings are more readily graspable from the names
>> * The codes behave with ST semantics, which is useful because we likely cannot
>>   split properties like pressure and orientation among the touches
>> * ST semantics are easier to comprehend than MT semantics, and MT isn't required
>>   to solve this problem
>> * The codes provide only the max and min values, none in between. This is in
>>   contrast with MT_TOOL_ENVELOPE, which provides all touches as presented by the
>>   hardware. However, we don't trust all the coordinate pairings, so providing
>>   faulty pairings may induce incorrect userspace usage of the events.
>> * A clear distinction is made here that full multitouch devices should use the
>>   MT protocol, while lesser devices should use the ST protocol.
>>
> 
> No, I do not agree with this proposal. This would introduce new _axes_
> (with potentially different min, max, resolution, etc) for the working
> surface of the devices instead of merely saying that the device may
> report more than simple singular contact within the standard axes.
> 
> I believe that MT protocol _is_ the correct vehicle to transmit semi-MT
> device state to userspace.
> 
> As to reporting more than 2 contacts with MT_TOOL_ENVELOPE - I think we
> should not do that. Instead we should only report 2 outermost points of
> the bounding rectangle as MT_TOOL_ENVELOPE and convey number of contacts
> with BTN_TOOL_xxxTAP (so up to 4 contacts, at least for now).

I gave this some more thought, and I was close to accepting it with
documentation of the above restrictions. Then I thought of how the
following two devices would be presented to userspace:

1. A real MT device supporting up to 2 touches (e.g. a bamboo touch)
  - ABS_{X,Y}, BTN_TOUCH, BTN_TOOL_FINGER, and BTN_TOOL_DOUBLETAP for ST
  - ABS_MT_SLOT, ABS_MT_TRACKING_ID, ABS_MT_POSITION_{X,Y}, ABS_MT_TOOL_TYPE

2. A partial MT device using MT_TOOL_ENVELOPE (e.g. synaptics MT)
  - ABS_{X,Y}, BTN_TOUCH, BTN_TOOL_FINGER, and BTN_TOOL_DOUBLETAP for ST
  - ABS_MT_SLOT, ABS_MT_TRACKING_ID, ABS_MT_POSITION_{X,Y}, ABS_MT_TOOL_TYPE

Note that they are identical! The range of values for each axis would be
identical too. The only way to tell the two apart would be to watch for
the ABS_MT_TOOL_TYPE axis. If the tool type stays MT_TOOL_FINGER when
both slots are active, it's a real MT device. If the tool type switches
to MT_TOOL_ENVELOPE, it's a partial MT device.

This means in userspace we cannot determine the full capabilities of the
device until at least two fingers touch it. This presents a challenge to
user space software like X and a gesture recognizer. In the former case,
the device properties would need to be changed, and X clients may need
to watch the device properties to ensure they are handling devices
correctly. No one does this yet because no input devices have ever
needed to be mutable. In the recognizer case, a partial MT device cannot
perform some rotation gestures. Gesture clients will need to know
whether a rotation gesture is possible on a given device.

Further, another issue I see is that this conflates boundary boxes of
input touches with tool type. How do we denote the tool type of a
partial MT device when MT_TOOL_ENVELOPE is taking up the
ABS_MT_TOOL_TYPE property? Or do we want to codify MT_TOOL_ENVELOPE to
mean a bounding box of *only* finger touches? If the latter, that's just
piling even more constraints on an evdev code name that doesn't give a
hint of any of these complexities. We can document this all, but I have
a hard time thinking this is the best way forward.

I understand that more new ABS_* axes may be undesirable, but it feels
the best approach to me. However, I would be ok with MT slots approaches
as long as they are well defined and do not introduce problems
highlighted above.

Thanks,

-- Chase

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Henrik Rydberg]

Hi Chase,

>

> I gave this some more thought, and I was close to accepting it with
> documentation of the above restrictions. Then I thought of how the
> following two devices would be presented to userspace:
> 
> 1. A real MT device supporting up to 2 touches (e.g. a bamboo touch)
>   - ABS_{X,Y}, BTN_TOUCH, BTN_TOOL_FINGER, and BTN_TOOL_DOUBLETAP for ST
>   - ABS_MT_SLOT, ABS_MT_TRACKING_ID, ABS_MT_POSITION_{X,Y}, ABS_MT_TOOL_TYPE
> 
> 2. A partial MT device using MT_TOOL_ENVELOPE (e.g. synaptics MT)
>   - ABS_{X,Y}, BTN_TOUCH, BTN_TOOL_FINGER, and BTN_TOOL_DOUBLETAP for ST
>   - ABS_MT_SLOT, ABS_MT_TRACKING_ID, ABS_MT_POSITION_{X,Y}, ABS_MT_TOOL_TYPE
> 
> Note that they are identical! The range of values for each axis would be
> identical too. The only way to tell the two apart would be to watch for
> the ABS_MT_TOOL_TYPE axis.


Ping has touched upon this subject as well, from the pen & touch perspective.
Generally, some ABS axes are actually enumerations, for which we have no direct
abstraction. If we had a way to declare the used values for such enumerations,
it would resolve these and possibly other issues.

Thanks,
Henrik

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Dmitry Torokhov]

On Wed, Dec 15, 2010 at 02:37:54AM +0100, Henrik Rydberg wrote:
> Hi Chase,
> 
> >
> 
> > I gave this some more thought, and I was close to accepting it with
> > documentation of the above restrictions. Then I thought of how the
> > following two devices would be presented to userspace:
> > 
> > 1. A real MT device supporting up to 2 touches (e.g. a bamboo touch)
> >   - ABS_{X,Y}, BTN_TOUCH, BTN_TOOL_FINGER, and BTN_TOOL_DOUBLETAP for ST
> >   - ABS_MT_SLOT, ABS_MT_TRACKING_ID, ABS_MT_POSITION_{X,Y}, ABS_MT_TOOL_TYPE
> > 
> > 2. A partial MT device using MT_TOOL_ENVELOPE (e.g. synaptics MT)
> >   - ABS_{X,Y}, BTN_TOUCH, BTN_TOOL_FINGER, and BTN_TOOL_DOUBLETAP for ST
> >   - ABS_MT_SLOT, ABS_MT_TRACKING_ID, ABS_MT_POSITION_{X,Y}, ABS_MT_TOOL_TYPE
> > 
> > Note that they are identical! The range of values for each axis would be
> > identical too. The only way to tell the two apart would be to watch for
> > the ABS_MT_TOOL_TYPE axis.

Question: does the driver really need to know this data beforehand?  I'd
expect MT-aware driver simply having handlers for both styles and then
doing the best it can with the data stream it gets... There should not
be ambiguity as to what event is - I believe we should be sending
BTN_TOOL_ENVELOPE even for the single/first contact for devices that do
not do full MT tracking.

> 
> 
> Ping has touched upon this subject as well, from the pen & touch perspective.
> Generally, some ABS axes are actually enumerations, for which we have no direct
> abstraction. If we had a way to declare the used values for such enumerations,
> it would resolve these and possibly other issues.

I think that presence of pen/touch can be detected by having
BTN_TOOL_PEN and BTN_TOOL_FINGER. However in this case the tool is
finger, so I do not think we should introduce BTN_TOOL_ENVELOPE. Maybe
this is another case where we should employ the proposed device flags?

Anyway, it looks like we have a few concerns with current
MT_TOOL_ENVELOPE so I want to rewind my 'next' branch.

-- 
Dmitry

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Chase Douglas]

On 12/15/2010 02:25 AM, Dmitry Torokhov wrote:
> On Wed, Dec 15, 2010 at 02:37:54AM +0100, Henrik Rydberg wrote:
>> Hi Chase,
>>
>>>
>>
>>> I gave this some more thought, and I was close to accepting it with
>>> documentation of the above restrictions. Then I thought of how the
>>> following two devices would be presented to userspace:
>>>
>>> 1. A real MT device supporting up to 2 touches (e.g. a bamboo touch)
>>>   - ABS_{X,Y}, BTN_TOUCH, BTN_TOOL_FINGER, and BTN_TOOL_DOUBLETAP for ST
>>>   - ABS_MT_SLOT, ABS_MT_TRACKING_ID, ABS_MT_POSITION_{X,Y}, ABS_MT_TOOL_TYPE
>>>
>>> 2. A partial MT device using MT_TOOL_ENVELOPE (e.g. synaptics MT)
>>>   - ABS_{X,Y}, BTN_TOUCH, BTN_TOOL_FINGER, and BTN_TOOL_DOUBLETAP for ST
>>>   - ABS_MT_SLOT, ABS_MT_TRACKING_ID, ABS_MT_POSITION_{X,Y}, ABS_MT_TOOL_TYPE
>>>
>>> Note that they are identical! The range of values for each axis would be
>>> identical too. The only way to tell the two apart would be to watch for
>>> the ABS_MT_TOOL_TYPE axis.
> 
> Question: does the driver really need to know this data beforehand?  I'd
> expect MT-aware driver simply having handlers for both styles and then
> doing the best it can with the data stream it gets... There should not
> be ambiguity as to what event is - I believe we should be sending
> BTN_TOOL_ENVELOPE even for the single/first contact for devices that do
> not do full MT tracking.

In XI 2.1 with MT, I would envision a partial MT device having different
axis labels. We don't want to push an implementation specific
abstraction, as MT_TOOL_ENVELOPE is, through the X protocol and require
clients to watch the tool type. It should be readily apparent by the
axis labels of the position valuators whether they represent true MT
coordinates or a bounding rectangle of touches.

As for whether clients will want to know if the device is real or
partial MT, I think we should design a protocol that allows for a client
to know. Maybe the application gives visual feedback on how to perform
gestures depending on the device type?

Thanks,

-- Chase

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Chris Bagwell]

On Wed, Dec 15, 2010 at 11:31 AM, Chase Douglas
<chase.douglas@canonical.com> wrote:
> On 12/15/2010 02:25 AM, Dmitry Torokhov wrote:
>> On Wed, Dec 15, 2010 at 02:37:54AM +0100, Henrik Rydberg wrote:
>>> Hi Chase,
>>>
>>>>
>>>
>>>> I gave this some more thought, and I was close to accepting it with
>>>> documentation of the above restrictions. Then I thought of how the
>>>> following two devices would be presented to userspace:
>>>>
>>>> 1. A real MT device supporting up to 2 touches (e.g. a bamboo touch)
>>>>   - ABS_{X,Y}, BTN_TOUCH, BTN_TOOL_FINGER, and BTN_TOOL_DOUBLETAP for ST
>>>>   - ABS_MT_SLOT, ABS_MT_TRACKING_ID, ABS_MT_POSITION_{X,Y}, ABS_MT_TOOL_TYPE
>>>>
>>>> 2. A partial MT device using MT_TOOL_ENVELOPE (e.g. synaptics MT)
>>>>   - ABS_{X,Y}, BTN_TOUCH, BTN_TOOL_FINGER, and BTN_TOOL_DOUBLETAP for ST
>>>>   - ABS_MT_SLOT, ABS_MT_TRACKING_ID, ABS_MT_POSITION_{X,Y}, ABS_MT_TOOL_TYPE
>>>>
>>>> Note that they are identical! The range of values for each axis would be
>>>> identical too. The only way to tell the two apart would be to watch for
>>>> the ABS_MT_TOOL_TYPE axis.
>>
>> Question: does the driver really need to know this data beforehand?  I'd
>> expect MT-aware driver simply having handlers for both styles and then
>> doing the best it can with the data stream it gets... There should not
>> be ambiguity as to what event is - I believe we should be sending
>> BTN_TOOL_ENVELOPE even for the single/first contact for devices that do
>> not do full MT tracking.
>
> In XI 2.1 with MT, I would envision a partial MT device having different
> axis labels. We don't want to push an implementation specific
> abstraction, as MT_TOOL_ENVELOPE is, through the X protocol and require
> clients to watch the tool type. It should be readily apparent by the
> axis labels of the position valuators whether they represent true MT
> coordinates or a bounding rectangle of touches.
>
> As for whether clients will want to know if the device is real or
> partial MT, I think we should design a protocol that allows for a client
> to know. Maybe the application gives visual feedback on how to perform
> gestures depending on the device type?
>

Agree with these points.  From a configuration GUI perspective, I'd
want to show a subset of gestures can be performed on these partial
MT... or at least show a different video on how gesture must be
performed to be recognized.

So I think we do need to expose up front.

Chris
--
To unsubscribe from this list: send the line "unsubscribe linux-input" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Henrik Rydberg]

>> Ping has touched upon this subject as well, from the pen & touch perspective.
>> Generally, some ABS axes are actually enumerations, for which we have no
>> direct abstraction. If we had a way to declare the used values for such
>> enumerations, it would resolve these and possibly other issues.

> I think that presence of pen/touch can be detected by having
> BTN_TOOL_PEN and BTN_TOOL_FINGER. However in this case the tool is
> finger, so I do not think we should introduce BTN_TOOL_ENVELOPE. Maybe
> this is another case where we should employ the proposed device flags?

Yes. Having something like INPUT_QUIRK_SEMI_MT might be enough, and we could
drop the whole MT_TOOL_ENVELOPE circus. Chase, Peter, Chris, would you be
comfortable with such a solution?

> Anyway, it looks like we have a few concerns with current
> MT_TOOL_ENVELOPE so I want to rewind my 'next' branch.

Yep. Should I also take the opportunity to sync from -rc1 instead, and fold the
cleanup patches into the appropriate places?

Thanks,
Henrik

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Chase Douglas]

On 12/15/2010 05:26 AM, Henrik Rydberg wrote:
>>> Ping has touched upon this subject as well, from the pen & touch perspective.
>>> Generally, some ABS axes are actually enumerations, for which we have no
>>> direct abstraction. If we had a way to declare the used values for such
>>> enumerations, it would resolve these and possibly other issues.
> 
>> I think that presence of pen/touch can be detected by having
>> BTN_TOOL_PEN and BTN_TOOL_FINGER. However in this case the tool is
>> finger, so I do not think we should introduce BTN_TOOL_ENVELOPE. Maybe
>> this is another case where we should employ the proposed device flags?
> 
> Yes. Having something like INPUT_QUIRK_SEMI_MT might be enough, and we could
> drop the whole MT_TOOL_ENVELOPE circus. Chase, Peter, Chris, would you be
> comfortable with such a solution?

That sounds like a good solution to me. I believe it would resolve all
the issues I had.

As I attempted to write up more documentation, I thought of the
following. What do you think?

With regards to partial MT devices, if the device provides a single
valued property, such as pressure and tool type for synaptics, it may
only be provided through the traditional property semantics, i.e.
ABS_PRESSURE and BTN_TOOL_*. If the device provides multiple values for
a property, then ABS_MT_* types may be used as well to provide up to two
values, though the client should understand there's no direct
correlation between the slot's coordinates and the property. I could see
this being used to provide info on multiple tool types or a high and low
pressure.

Enforcing the above behaviour provides even more information about the
capabilities of the device based solely on the evdev codes published.

Thanks,

-- Chase

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Henrik Rydberg]

>>> I think that presence of pen/touch can be detected by having

>>> BTN_TOOL_PEN and BTN_TOOL_FINGER. However in this case the tool is
>>> finger, so I do not think we should introduce BTN_TOOL_ENVELOPE. Maybe
>>> this is another case where we should employ the proposed device flags?
>>
>> Yes. Having something like INPUT_QUIRK_SEMI_MT might be enough, and we could
>> drop the whole MT_TOOL_ENVELOPE circus. Chase, Peter, Chris, would you be
>> comfortable with such a solution?
> 
> That sounds like a good solution to me. I believe it would resolve all
> the issues I had.


Sounds good.


> As I attempted to write up more documentation, I thought of the
> following. What do you think?
> 
> With regards to partial MT devices, if the device provides a single
> valued property, such as pressure and tool type for synaptics, it may
> only be provided through the traditional property semantics, i.e.
> ABS_PRESSURE and BTN_TOOL_*. If the device provides multiple values for
> a property, then ABS_MT_* types may be used as well to provide up to two
> values, though the client should understand there's no direct
> correlation between the slot's coordinates and the property. I could see
> this being used to provide info on multiple tool types or a high and low
> pressure.
> 
> Enforcing the above behaviour provides even more information about the
> capabilities of the device based solely on the evdev codes published.


Looks good, but I do not think we need to formalize all possibilities here, only
the usage of MT data for bounding rectangle and ST data for finger count.
Referring to the patch just sent: whenever INPUT_PROP_SEMI_MT is true, this
behavior is expected. In the event of new odd hardware, the combination of a new
property quirk and a documented recipe should do the trick.

Thanks,
Henrik

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Chase Douglas]

On 12/15/2010 02:36 PM, Henrik Rydberg wrote:
>>>> I think that presence of pen/touch can be detected by having
> 
>>>> BTN_TOOL_PEN and BTN_TOOL_FINGER. However in this case the tool is
>>>> finger, so I do not think we should introduce BTN_TOOL_ENVELOPE. Maybe
>>>> this is another case where we should employ the proposed device flags?
>>>
>>> Yes. Having something like INPUT_QUIRK_SEMI_MT might be enough, and we could
>>> drop the whole MT_TOOL_ENVELOPE circus. Chase, Peter, Chris, would you be
>>> comfortable with such a solution?
>>
>> That sounds like a good solution to me. I believe it would resolve all
>> the issues I had.
> 
> 
> Sounds good.
> 
> 
>> As I attempted to write up more documentation, I thought of the
>> following. What do you think?
>>
>> With regards to partial MT devices, if the device provides a single
>> valued property, such as pressure and tool type for synaptics, it may
>> only be provided through the traditional property semantics, i.e.
>> ABS_PRESSURE and BTN_TOOL_*. If the device provides multiple values for
>> a property, then ABS_MT_* types may be used as well to provide up to two
>> values, though the client should understand there's no direct
>> correlation between the slot's coordinates and the property. I could see
>> this being used to provide info on multiple tool types or a high and low
>> pressure.
>>
>> Enforcing the above behaviour provides even more information about the
>> capabilities of the device based solely on the evdev codes published.
> 
> 
> Looks good, but I do not think we need to formalize all possibilities here, only
> the usage of MT data for bounding rectangle and ST data for finger count.
> Referring to the patch just sent: whenever INPUT_PROP_SEMI_MT is true, this
> behavior is expected. In the event of new odd hardware, the combination of a new
> property quirk and a documented recipe should do the trick.

Would you feel comfortable stating the above in less concrete terms, as
sort of a best practices guide? I'd like to know for this specific case
if you agree beyond ST finger count data, or if you feel we should do
something else like always provide as much data as possible in MT
properties? It's a real corner case, and I don't care too much one way
or another. I just don't want synaptics implemented one way, elantech
another, etc.

Thanks,

-- Chase

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Henrik Rydberg]

>>>

>>> With regards to partial MT devices, if the device provides a single
>>> valued property, such as pressure and tool type for synaptics, it may
>>> only be provided through the traditional property semantics, i.e.
>>> ABS_PRESSURE and BTN_TOOL_*. If the device provides multiple values for
>>> a property, then ABS_MT_* types may be used as well to provide up to two
>>> values, though the client should understand there's no direct
>>> correlation between the slot's coordinates and the property. I could see
>>> this being used to provide info on multiple tool types or a high and low
>>> pressure.
>>>
>>> Enforcing the above behaviour provides even more information about the
>>> capabilities of the device based solely on the evdev codes published.
>>
>>
>> Looks good, but I do not think we need to formalize all possibilities here, only
>> the usage of MT data for bounding rectangle and ST data for finger count.
>> Referring to the patch just sent: whenever INPUT_PROP_SEMI_MT is true, this
>> behavior is expected. In the event of new odd hardware, the combination of a new
>> property quirk and a documented recipe should do the trick.
> 
> Would you feel comfortable stating the above in less concrete terms, as
> sort of a best practices guide? I'd like to know for this specific case
> if you agree beyond ST finger count data, or if you feel we should do
> something else like always provide as much data as possible in MT
> properties? It's a real corner case, and I don't care too much one way
> or another. I just don't want synaptics implemented one way, elantech
> another, etc.


A driver can still choose to report ABS_MT_PRESSURE for instance, in which case
it is assumed to make sense for individual fingers/corners. For semi-mt devices,
it seems reasonable to go to the ST variants to collect information not provided
via the MT protocol. I see no immediate reason to specify beyond that point.

Thanks,
Henrik

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Chris Bagwell]

On Wed, Dec 15, 2010 at 11:40 AM, Chase Douglas
<chase.douglas@canonical.com> wrote:
> On 12/15/2010 05:26 AM, Henrik Rydberg wrote:
>>>> Ping has touched upon this subject as well, from the pen & touch perspective.
>>>> Generally, some ABS axes are actually enumerations, for which we have no
>>>> direct abstraction. If we had a way to declare the used values for such
>>>> enumerations, it would resolve these and possibly other issues.
>>
>>> I think that presence of pen/touch can be detected by having
>>> BTN_TOOL_PEN and BTN_TOOL_FINGER. However in this case the tool is
>>> finger, so I do not think we should introduce BTN_TOOL_ENVELOPE. Maybe
>>> this is another case where we should employ the proposed device flags?
>>
>> Yes. Having something like INPUT_QUIRK_SEMI_MT might be enough, and we could
>> drop the whole MT_TOOL_ENVELOPE circus. Chase, Peter, Chris, would you be
>> comfortable with such a solution?
>
> That sounds like a good solution to me. I believe it would resolve all
> the issues I had.

Works for me as well.

>
> As I attempted to write up more documentation, I thought of the
> following. What do you think?
>
> With regards to partial MT devices, if the device provides a single
> valued property, such as pressure and tool type for synaptics, it may
> only be provided through the traditional property semantics, i.e.
> ABS_PRESSURE and BTN_TOOL_*. If the device provides multiple values for
> a property, then ABS_MT_* types may be used as well to provide up to two
> values, though the client should understand there's no direct
> correlation between the slot's coordinates and the property. I could see
> this being used to provide info on multiple tool types or a high and low
> pressure.
>
> Enforcing the above behaviour provides even more information about the
> capabilities of the device based solely on the evdev codes published.
>

I meant to mention: once your initial draft gets committed I would
love to help update it some.  I specifically want to show two example
usage.  1) touchpad as 1 to 3 touchs occur and show special
considerations to ABS_* that apps should handle.  2) a touchscreen
that supports a pen as well and show how tool change (finger to pen)
should work.  For both those examples, it would be interesting to
discuss how MT can be used concurrently (does pen in slot 0 and touch
in slot 1 make sense for example).

I think it will be invaluable to document this stuff for driver
writers and apps but I'm not sure yet what level needs to be enforced.

Chris

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Chase Douglas]

On 12/15/2010 03:41 PM, Chris Bagwell wrote:
> I meant to mention: once your initial draft gets committed I would
> love to help update it some.  I specifically want to show two example
> usage.  1) touchpad as 1 to 3 touchs occur and show special
> considerations to ABS_* that apps should handle.  2) a touchscreen
> that supports a pen as well and show how tool change (finger to pen)
> should work.  For both those examples, it would be interesting to
> discuss how MT can be used concurrently (does pen in slot 0 and touch
> in slot 1 make sense for example).

This is the other main reason I wanted to make the document. Having a
place where best practices are detailed will help future driver writers
and hopefully reduce errors in evdev code usage. I'd love to see this
added to the document.

I do think that MT is complex enough that related documentation should
be in multi-touch-protocol.txt, though. Anywhere I discussed MT in
evdev-codes.txt I referred the reader to the other file. Henrik, does
that sound good to you?

> I think it will be invaluable to document this stuff for driver
> writers and apps but I'm not sure yet what level needs to be enforced.

That's the biggest issue I see right now. Do we want black and white
specificity? For example, using terms like "must" and "may not" etc. Or
do we want the document to merely hold best practices while not
proscribing exact details? I think even with exact details we can loosen
them if needed, but that has its own can of worms.

Dmitry, what are your thoughts on this?

Thanks,

-- Chase

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Henrik Rydberg]

>

> I do think that MT is complex enough that related documentation should
> be in multi-touch-protocol.txt, though. Anywhere I discussed MT in
> evdev-codes.txt I referred the reader to the other file. Henrik, does
> that sound good to you?


Yep, thanks.

>> I think it will be invaluable to document this stuff for driver
>> writers and apps but I'm not sure yet what level needs to be enforced.
> 
> That's the biggest issue I see right now. Do we want black and white
> specificity? For example, using terms like "must" and "may not" etc. Or
> do we want the document to merely hold best practices while not
> proscribing exact details? I think even with exact details we can loosen
> them if needed, but that has its own can of worms.


It will most likely need to be judged on a case-by-case basis.

Thanks,
Henrik

Re: [PATCH 0/4] Alternative approach to MT_TOOL_ENVELOPE

[Peter Hutterer]

On Wed, Dec 15, 2010 at 11:26:59AM +0100, Henrik Rydberg wrote:
> >> Ping has touched upon this subject as well, from the pen & touch perspective.
> >> Generally, some ABS axes are actually enumerations, for which we have no
> >> direct abstraction. If we had a way to declare the used values for such
> >> enumerations, it would resolve these and possibly other issues.
> 
> > I think that presence of pen/touch can be detected by having
> > BTN_TOOL_PEN and BTN_TOOL_FINGER. However in this case the tool is
> > finger, so I do not think we should introduce BTN_TOOL_ENVELOPE. Maybe
> > this is another case where we should employ the proposed device flags?
> 
> Yes. Having something like INPUT_QUIRK_SEMI_MT might be enough, and we could
> drop the whole MT_TOOL_ENVELOPE circus. Chase, Peter, Chris, would you be
> comfortable with such a solution?

sounds good to me, thanks.

Cheers,
  Peter

> > Anyway, it looks like we have a few concerns with current
> > MT_TOOL_ENVELOPE so I want to rewind my 'next' branch.
> 
> Yep. Should I also take the opportunity to sync from -rc1 instead, and fold the
> cleanup patches into the appropriate places?
> 
> Thanks,
> Henrik
>