[PATCH 1/2] input: mt: Introduce MT event slots (rev 5)

[PATCH 1/2] input: mt: Introduce MT event slots (rev 5)

[Henrik Rydberg]

With the rapidly increasing number of intelligent multi-contact and
multi-user devices, the need to send digested, filtered information
from a set of different sources within the same device is imminent.
This patch adds the concept of slots to the MT protocol. The slots
enumerate a set of identified sources, such that all MT events
can be passed independently and selectively per identified source.

The protocol works like this: Instead of sending a SYN_MT_REPORT
event immediately after the contact data, one sends an ABS_MT_SLOT
event immediately before the contact data. The input core will only
emit events for slots with modified MT events. It is assumed that
the same slot is used for the duration of an initiated contact.

Signed-off-by: Henrik Rydberg <rydberg@euromail.se>
---
Revision 5 incorporates the following changes:
	 - Rename the slot event to ABS_MT_SLOT to keep all MT-related events
	   in the same namespace.
	 - Move the MT slot event list to input.h so that it can be read
	   by userspace.

 drivers/input/input.c |  105 +++++++++++++++++++++++++++++++++++++------------
 include/linux/input.h |   44 ++++++++++++++++++++
 2 files changed, 123 insertions(+), 26 deletions(-)

diff --git a/drivers/input/input.c b/drivers/input/input.c
index 9c79bd5..9b6d474 100644
--- a/drivers/input/input.c
+++ b/drivers/input/input.c
@@ -33,24 +33,9 @@ MODULE_LICENSE("GPL");
 
 #define INPUT_DEVICES	256
 
-/*
- * EV_ABS events which should not be cached are listed here.
- */
-static unsigned int input_abs_bypass_init_data[] __initdata = {
-	ABS_MT_TOUCH_MAJOR,
-	ABS_MT_TOUCH_MINOR,
-	ABS_MT_WIDTH_MAJOR,
-	ABS_MT_WIDTH_MINOR,
-	ABS_MT_ORIENTATION,
-	ABS_MT_POSITION_X,
-	ABS_MT_POSITION_Y,
-	ABS_MT_TOOL_TYPE,
-	ABS_MT_BLOB_ID,
-	ABS_MT_TRACKING_ID,
-	ABS_MT_PRESSURE,
-	0
-};
-static unsigned long input_abs_bypass[BITS_TO_LONGS(ABS_CNT)];
+static unsigned int input_mt_abs_map_init_data[] __initdata =
+	MT_SLOT_ABS_EVENTS;
+static unsigned char input_mt_abs_map[ABS_CNT];
 
 static LIST_HEAD(input_dev_list);
 static LIST_HEAD(input_handler_list);
@@ -181,6 +166,26 @@ static void input_stop_autorepeat(struct input_dev *dev)
 #define INPUT_PASS_TO_DEVICE	2
 #define INPUT_PASS_TO_ALL	(INPUT_PASS_TO_HANDLERS | INPUT_PASS_TO_DEVICE)
 
+static void input_mt_handle_abs_event(struct input_dev *dev,
+				      unsigned int code, int value)
+{
+	if (dev->mt) {
+		struct input_mt_slot *mtslot = &dev->mt[dev->slot];
+		unsigned int mtcode = input_mt_abs_map[code] - 1;
+		int old = mtslot->abs[mtcode];
+		value = input_defuzz_abs_event(value, old, dev->absfuzz[code]);
+		if (value == old)
+			return;
+		mtslot->abs[mtcode] = value;
+	}
+	dev->sync = 0;
+	if (dev->slot != dev->abs[ABS_MT_SLOT]) {
+		dev->abs[ABS_MT_SLOT] = dev->slot;
+		input_pass_event(dev, EV_ABS, ABS_MT_SLOT, dev->slot);
+	}
+	input_pass_event(dev, EV_ABS, code, value);
+}
+
 static void input_handle_event(struct input_dev *dev,
 			       unsigned int type, unsigned int code, int value)
 {
@@ -235,11 +240,17 @@ static void input_handle_event(struct input_dev *dev,
 	case EV_ABS:
 		if (is_event_supported(code, dev->absbit, ABS_MAX)) {
 
-			if (test_bit(code, input_abs_bypass)) {
-				disposition = INPUT_PASS_TO_HANDLERS;
+			if (code == ABS_MT_SLOT) {
+				if (value >= 0 && value < dev->mtsize)
+					dev->slot = value;
 				break;
 			}
 
+			if (input_mt_abs_map[code]) {
+				input_mt_handle_abs_event(dev, code, value);
+				return;
+			}
+
 			value = input_defuzz_abs_event(value,
 					dev->abs[code], dev->absfuzz[code]);
 
@@ -1278,6 +1289,7 @@ static void input_dev_release(struct device *device)
 	struct input_dev *dev = to_input_dev(device);
 
 	input_ff_destroy(dev);
+	input_mt_destroy_slots(dev);
 	kfree(dev);
 
 	module_put(THIS_MODULE);
@@ -1518,6 +1530,46 @@ void input_free_device(struct input_dev *dev)
 EXPORT_SYMBOL(input_free_device);
 
 /**
+ * input_mt_create_slots() - create MT input slots
+ * @dev: input device supporting MT events and finger tracking
+ * @max_slots: maximum number of slots supported by the device
+ *
+ * This function allocates all necessary memory for MT slot handling
+ * in the input device, and adds ABS_MT_SLOT to the device capabilities.
+ */
+int input_mt_create_slots(struct input_dev *dev, int max_slots)
+{
+	struct input_mt_slot *mt;
+
+	if (max_slots <= 0)
+		return 0;
+	mt = kzalloc(max_slots * sizeof(struct input_mt_slot), GFP_KERNEL);
+	if (!mt)
+		return -ENOMEM;
+
+	dev->mt = mt;
+	dev->mtsize = max_slots;
+	input_set_abs_params(dev, ABS_MT_SLOT, 0, max_slots - 1, 0, 0);
+	return 0;
+}
+EXPORT_SYMBOL(input_mt_create_slots);
+
+/**
+ * input_mt_destroy_slots() - frees the MT slots of the input device
+ * @dev: input device with allocated MT slots
+ *
+ * This function is only needed in error path as the input core will
+ * automatically free the MT slots when the device is destroyed.
+ */
+void input_mt_destroy_slots(struct input_dev *dev)
+{
+	kfree(dev->mt);
+	dev->mt = NULL;
+	dev->mtsize = 0;
+}
+EXPORT_SYMBOL(input_mt_destroy_slots);
+
+/**
  * input_set_capability - mark device as capable of a certain event
  * @dev: device that is capable of emitting or accepting event
  * @type: type of the event (EV_KEY, EV_REL, etc...)
@@ -1926,19 +1978,20 @@ static const struct file_operations input_fops = {
 	.open = input_open_file,
 };
 
-static void __init input_init_abs_bypass(void)
+static void __init input_mt_init_maps(void)
 {
-	const unsigned int *p;
-
-	for (p = input_abs_bypass_init_data; *p; p++)
-		input_abs_bypass[BIT_WORD(*p)] |= BIT_MASK(*p);
+	int i;
+	BUILD_BUG_ON(MT_ABS_SIZE != (typeof(input_mt_abs_map[0]))MT_ABS_SIZE);
+	BUILD_BUG_ON(ARRAY_SIZE(input_mt_abs_map_init_data) > MT_ABS_SIZE);
+	for (i = 0; i < ARRAY_SIZE(input_mt_abs_map_init_data); i++)
+		input_mt_abs_map[input_mt_abs_map_init_data[i]] = i + 1;
 }
 
 static int __init input_init(void)
 {
 	int err;
 
-	input_init_abs_bypass();
+	input_mt_init_maps();
 
 	err = class_register(&input_class);
 	if (err) {
diff --git a/include/linux/input.h b/include/linux/input.h
index 7ed2251..bea6958 100644
--- a/include/linux/input.h
+++ b/include/linux/input.h
@@ -694,6 +694,7 @@ struct input_absinfo {
 #define ABS_VOLUME		0x20
 #define ABS_MISC		0x28
 
+#define ABS_MT_SLOT		0x2f	/* MT slot being modified */
 #define ABS_MT_TOUCH_MAJOR	0x30	/* Major axis of touching ellipse */
 #define ABS_MT_TOUCH_MINOR	0x31	/* Minor axis (omit if circular) */
 #define ABS_MT_WIDTH_MAJOR	0x32	/* Major axis of approaching ellipse */
@@ -814,6 +815,24 @@ struct input_absinfo {
 #define MT_TOOL_PEN		1
 
 /*
+ * MT slot event lists
+ */
+
+#define MT_SLOT_ABS_EVENTS {	\
+	ABS_MT_TOUCH_MAJOR,	\
+	ABS_MT_TOUCH_MINOR,	\
+	ABS_MT_WIDTH_MAJOR,	\
+	ABS_MT_WIDTH_MINOR,	\
+	ABS_MT_ORIENTATION,	\
+	ABS_MT_POSITION_X,	\
+	ABS_MT_POSITION_Y,	\
+	ABS_MT_TOOL_TYPE,	\
+	ABS_MT_BLOB_ID,		\
+	ABS_MT_TRACKING_ID,	\
+	ABS_MT_PRESSURE,	\
+}
+
+/*
  * Values describing the status of a force-feedback effect
  */
 #define FF_STATUS_STOPPED	0x00
@@ -1080,6 +1099,9 @@ struct ff_effect {
  * @sync: set to 1 when there were no new events since last EV_SYNC
  * @abs: current values for reports from absolute axes
  * @rep: current values for autorepeat parameters (delay, rate)
+ * @mt: array of MT slots
+ * @mtsize: number of allocated MT slots
+ * @slot: current MT slot
  * @key: reflects current state of device's keys/buttons
  * @led: reflects current state of device's LEDs
  * @snd: reflects current state of sound effects
@@ -1157,6 +1179,10 @@ struct input_dev {
 	int abs[ABS_MAX + 1];
 	int rep[REP_MAX + 1];
 
+	struct input_mt_slot *mt;
+	int mtsize;
+	int slot;
+
 	unsigned long key[BITS_TO_LONGS(KEY_CNT)];
 	unsigned long led[BITS_TO_LONGS(LED_CNT)];
 	unsigned long snd[BITS_TO_LONGS(SND_CNT)];
@@ -1405,6 +1431,11 @@ static inline void input_mt_sync(struct input_dev *dev)
 	input_event(dev, EV_SYN, SYN_MT_REPORT, 0);
 }
 
+static inline void input_mt_slot(struct input_dev *dev, int slot)
+{
+	input_event(dev, EV_ABS, ABS_MT_SLOT, slot);
+}
+
 void input_set_capability(struct input_dev *dev, unsigned int type, unsigned int code);
 
 static inline void input_set_abs_params(struct input_dev *dev, int axis, int min, int max, int fuzz, int flat)
@@ -1484,5 +1515,18 @@ int input_ff_erase(struct input_dev *dev, int effect_id, struct file *file);
 int input_ff_create_memless(struct input_dev *dev, void *data,
 		int (*play_effect)(struct input_dev *, void *, struct ff_effect *));
 
+#define MT_ABS_SIZE 11
+
+/**
+ * struct input_mt_slot - represents the state of an input MT slot
+ * @abs: current values of ABS_MT axes for this slot
+ */
+struct input_mt_slot {
+	int abs[MT_ABS_SIZE];
+};
+
+int input_mt_create_slots(struct input_dev *dev, int max_slots);
+void input_mt_destroy_slots(struct input_dev *dev);
+
 #endif
 #endif
-- 
1.6.3.3

[PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Henrik Rydberg]

This patch adds documentation for the ABS_MT_SLOT event and gives
examples of how to use the event slot protocol.

Reviewed-by: Ping Cheng <pingc@wacom.com>
Signed-off-by: Henrik Rydberg <rydberg@euromail.se>
---
Revision 4 incorporates the following changes:
	 - Rename the slot event to ABS_MT_SLOT to keep all MT-related events
	   in the same namespace.
	 - Fix typo, thanks to Ping Cheng.
	   
 Documentation/input/multi-touch-protocol.txt |  204 ++++++++++++++++++--------
 1 files changed, 140 insertions(+), 64 deletions(-)

diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt
index c0fc1c7..92be65e 100644
--- a/Documentation/input/multi-touch-protocol.txt
+++ b/Documentation/input/multi-touch-protocol.txt
@@ -6,31 +6,146 @@ Multi-touch (MT) Protocol
 Introduction
 ------------
 
-In order to utilize the full power of the new multi-touch devices, a way to
-report detailed finger data to user space is needed. This document
-describes the multi-touch (MT) protocol which allows kernel drivers to
-report details for an arbitrary number of fingers.
+In order to utilize the full power of the new multi-touch and multi-user
+devices, a way to report detailed data from multiple contacts, i.e.,
+objects in direct contact with the device surface, is needed.  This
+document describes the multi-touch (MT) protocol which allows kernel
+drivers to report details for an arbitrary number of contacts.
+
+The protocol is divided into two types, depending on the capabilities of the
+hardware. For devices handling anonymous contacts (type A), the protocol
+describes how to send the raw data for all contacts to the receiver. For
+devices capable of tracking identifiable contacts (type B), the protocol
+describes how to send updates for individual contacts via event slots.
+
+
+Protocol Usage
+--------------
+
+Contact details are sent sequentially as separate packets of ABS_MT
+events. Only the ABS_MT events are recognized as part of a contact
+packet. Since these events are ignored by current single-touch (ST)
+applications, the MT protocol can be implemented on top of the ST protocol
+in an existing driver.
+
+Drivers for type A devices mark the end of a packet by calling the
+input_mt_sync() function, which generates a SYN_MT_REPORT event. This
+instructs the receiver to accept the data for the current contact and
+prepare to receive another. Drivers for type B devices mark the beginning
+of a packet by calling the input_mt_slot() function with a slot as
+argument, which generates an ABS_MT_SLOT event. This instructs the receiver
+to prepare for updates of the given slot.
+
+The end of a multi-touch transfer is marked by calling the usual
+input_sync() function. This instructs the receiver to act upon events
+accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new set
+of events/packets.
+
+The main difference between the raw type A protocol and the higher level
+type B slot protocol lies in the usage of identifiable contacts. The slot
+protocol requires the use of the ABS_MT_TRACKING_ID, either provided by the
+hardware or computed from the raw data [5].
+
+For type A devices, the kernel driver should generate an arbitrary
+enumeration of the set of anonymous contacts currently on the surface. The
+order in which the packets appear in the event stream is not important.
+Event filtering and finger tracking is left to user space [3].
+
+For type B devices, the kernel driver should associate a slot with each
+identified contact, and use that slot to propagate changes for the contact.
+Creation, replacement and destruction of contacts is achieved by modifying
+the ABS_MT_TRACKING_ID of the associated slot.  A tracking id within the
+specified value range is interpreted as a contact, all other values are
+interpreted as an unused slot.  A tracking id not previously present is
+considered new, and a tracking id no longer present is considered removed.
+Since only changes are propagated, the full state of each initiated contact
+has to reside in the receiving end.  Upon receiving an MT event, one simply
+updates the appropriate attribute of the current slot.
+
+
+Protocol Example A
+------------------
+
+Here is what a minimal event sequence for a two-contact touch would look
+like for a type A device:
+
+   ABS_MT_POSITION_X x[0]
+   ABS_MT_POSITION_Y y[0]
+   SYN_MT_REPORT
+   ABS_MT_POSITION_X x[1]
+   ABS_MT_POSITION_Y y[1]
+   SYN_MT_REPORT
+   SYN_REPORT
 
+The sequence after moving one of the contacts looks exactly the same; the
+raw data for all present contacts are sent between every synchronization
+with SYN_REPORT.
 
-Usage
------
+Here is the sequence after lifting the first contact:
+
+   ABS_MT_POSITION_X x[1]
+   ABS_MT_POSITION_Y y[1]
+   SYN_MT_REPORT
+   SYN_REPORT
+
+And here is the sequence after lifting the second contact:
+
+   SYN_MT_REPORT
+   SYN_REPORT
+
+If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the
+ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the
+last SYN_REPORT will be dropped by the input core, resulting in no
+zero-contact event reaching userland.
 
-Anonymous finger details are sent sequentially as separate packets of ABS
-events. Only the ABS_MT events are recognized as part of a finger
-packet. The end of a packet is marked by calling the input_mt_sync()
-function, which generates a SYN_MT_REPORT event. This instructs the
-receiver to accept the data for the current finger and prepare to receive
-another. The end of a multi-touch transfer is marked by calling the usual
-input_sync() function. This instructs the receiver to act upon events
-accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new
-set of events/packets.
+
+Protocol Example B
+------------------
+
+Here is what a minimal event sequence for a two-contact touch would look
+like for a type B device:
+
+   ABS_MT_SLOT 0
+   ABS_MT_TRACKING_ID 45
+   ABS_MT_POSITION_X x[0]
+   ABS_MT_POSITION_Y y[0]
+   ABS_MT_SLOT 1
+   ABS_MT_TRACKING_ID 46
+   ABS_MT_POSITION_X x[1]
+   ABS_MT_POSITION_Y y[1]
+   SYN_REPORT
+
+Here is the sequence after moving contact 45 in the x direction:
+
+   ABS_MT_SLOT 0
+   ABS_MT_POSITION_X x[0]
+   SYN_REPORT
+
+Here is the sequence after lifting the contact in slot 0:
+
+   ABS_MT_TRACKING_ID 0
+   SYN_REPORT
+
+The slot being modified is already 0, so the ABS_MT_SLOT is omitted.  The
+message removes the association of slot 0 with contact 45, thereby
+destroying contact 45 and freeing slot 0 to be reused for another contact.
+
+Finally, here is the sequence after lifting the second contact:
+
+   ABS_MT_SLOT 1
+   ABS_MT_TRACKING_ID 0
+   SYN_REPORT
+
+
+Event Usage
+-----------
 
 A set of ABS_MT events with the desired properties is defined. The events
 are divided into categories, to allow for partial implementation.  The
 minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which
-allows for multiple fingers to be tracked.  If the device supports it, the
+allows for multiple contacts to be tracked.  If the device supports it, the
 ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size
-of the contact area and approaching finger, respectively.
+of the contact area and approaching contact, respectively.
 
 The TOUCH and WIDTH parameters have a geometrical interpretation; imagine
 looking through a window at someone gently holding a finger against the
@@ -41,56 +156,26 @@ ABS_MT_TOUCH_MAJOR, the diameter of the outer region is
 ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder
 against the glass. The inner region will increase, and in general, the
 ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than
-unity, is related to the finger pressure. For pressure-based devices,
+unity, is related to the contact pressure. For pressure-based devices,
 ABS_MT_PRESSURE may be used to provide the pressure on the contact area
 instead.
 
-In addition to the MAJOR parameters, the oval shape of the finger can be
+In addition to the MAJOR parameters, the oval shape of the contact can be
 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.
 
 The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
-finger or a pen or something else.  Devices with more granular information
+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 finger tracking from hardware [5].
+report contact tracking from hardware [5].
 
-Here is what a minimal event sequence for a two-finger touch would look
-like:
-
-   ABS_MT_POSITION_X
-   ABS_MT_POSITION_Y
-   SYN_MT_REPORT
-   ABS_MT_POSITION_X
-   ABS_MT_POSITION_Y
-   SYN_MT_REPORT
-   SYN_REPORT
-
-Here is the sequence after lifting one of the fingers:
-
-   ABS_MT_POSITION_X
-   ABS_MT_POSITION_Y
-   SYN_MT_REPORT
-   SYN_REPORT
-
-And here is the sequence after lifting the remaining finger:
-
-   SYN_MT_REPORT
-   SYN_REPORT
-
-If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the
-ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the
-last SYN_REPORT will be dropped by the input core, resulting in no
-zero-finger event reaching userland.
 
 Event Semantics
 ---------------
 
-The word "contact" is used to describe a tool which is in direct contact
-with the surface. A finger, a pen or a rubber all classify as contacts.
-
 ABS_MT_TOUCH_MAJOR
 
 The length of the major axis of the contact. The length should be given in
@@ -192,20 +277,11 @@ finger along the X axis (1).
 Finger Tracking
 ---------------
 
-The kernel driver should generate an arbitrary enumeration of the set of
-anonymous contacts currently on the surface. The order in which the packets
-appear in the event stream is not important.
-
 The process of finger tracking, i.e., to assign a unique trackingID to each
-initiated contact on the surface, is left to user space; preferably the
-multi-touch X driver [3]. In that driver, the trackingID stays the same and
-unique until the contact vanishes (when the finger leaves the surface). The
-problem of assigning a set of anonymous fingers to a set of identified
-fingers is a euclidian bipartite matching problem at each event update, and
-relies on a sufficiently rapid update rate.
-
-There are a few devices that support trackingID in hardware. User space can
-make use of these native identifiers to reduce bandwidth and cpu usage.
+initiated contact on the surface, is a Euclidian Bipartite Matching
+problem.  At each event synchronization, the set of actual contacts are
+matched to the set of contacts from the previous synchronization. A full
+implementation can be found in [3].
 
 
 Gestures
-- 
1.6.3.3

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Ping Cheng]

The fool is smiling like a fool now :).

Ping

BTW, I didn't receive the updated "[PATCH 1/2] input: mt: Introduce MT
event slots (rev 5)".  Maybe gmail filtered the file for me?

On Sat, May 22, 2010 at 3:30 PM, Henrik Rydberg <rydberg@euromail.se> wrote:
> This patch adds documentation for the ABS_MT_SLOT event and gives
> examples of how to use the event slot protocol.
>
> Reviewed-by: Ping Cheng <pingc@wacom.com>
> Signed-off-by: Henrik Rydberg <rydberg@euromail.se>
> ---
> Revision 4 incorporates the following changes:
>         - Rename the slot event to ABS_MT_SLOT to keep all MT-related events
>           in the same namespace.
>         - Fix typo, thanks to Ping Cheng.
--
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/2] input: mt: Document the MT event slot protocol (rev4)

[Henrik Rydberg]

Ping Cheng wrote:
> The fool is smiling like a fool now :).

“The trouble ain't that there is too many fools, but that the lightning ain't
distributed right.”

> BTW, I didn't receive the updated "[PATCH 1/2] input: mt: Introduce MT
> event slots (rev 5)".  Maybe gmail filtered the file for me?

Heh, the correspondence on these patches has taken somewhat spam-like
proportions, but it should calm down considerably now. Hopefully it was all for
the best.

Cheers!
Henrik

--
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/2] input: mt: Document the MT event slot protocol (rev4)

[Randy Dunlap]

On Sun, 23 May 2010 00:30:37 +0200 Henrik Rydberg wrote:

> This patch adds documentation for the ABS_MT_SLOT event and gives
> examples of how to use the event slot protocol.
> 
> Reviewed-by: Ping Cheng <pingc@wacom.com>
> Signed-off-by: Henrik Rydberg <rydberg@euromail.se>
> ---
> Revision 4 incorporates the following changes:
> 	 - Rename the slot event to ABS_MT_SLOT to keep all MT-related events
> 	   in the same namespace.
> 	 - Fix typo, thanks to Ping Cheng.
> 	   
>  Documentation/input/multi-touch-protocol.txt |  204 ++++++++++++++++++--------
>  1 files changed, 140 insertions(+), 64 deletions(-)
> 
> diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt
> index c0fc1c7..92be65e 100644
> --- a/Documentation/input/multi-touch-protocol.txt
> +++ b/Documentation/input/multi-touch-protocol.txt
> @@ -6,31 +6,146 @@ Multi-touch (MT) Protocol
...
> +Protocol Usage
> +--------------
> +
> +Contact details are sent sequentially as separate packets of ABS_MT
> +events. Only the ABS_MT events are recognized as part of a contact
> +packet. Since these events are ignored by current single-touch (ST)
> +applications, the MT protocol can be implemented on top of the ST protocol
> +in an existing driver.
> +
> +Drivers for type A devices mark the end of a packet by calling the

end?

> +input_mt_sync() function, which generates a SYN_MT_REPORT event. This
> +instructs the receiver to accept the data for the current contact and
> +prepare to receive another. Drivers for type B devices mark the beginning

vs. beginning?  Seems incongruous.  And not just to the doc, but to
producers and consumers as well.


> +of a packet by calling the input_mt_slot() function with a slot as
> +argument, which generates an ABS_MT_SLOT event. This instructs the receiver
> +to prepare for updates of the given slot.
> +
> +The end of a multi-touch transfer is marked by calling the usual

The end method is done for Types A and B, right?


> +input_sync() function. This instructs the receiver to act upon events
> +accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new set
> +of events/packets.
> +
...

> @@ -192,20 +277,11 @@ finger along the X axis (1).
>  Finger Tracking
>  ---------------
>  
> -The kernel driver should generate an arbitrary enumeration of the set of
> -anonymous contacts currently on the surface. The order in which the packets
> -appear in the event stream is not important.
> -
>  The process of finger tracking, i.e., to assign a unique trackingID to each
> -initiated contact on the surface, is left to user space; preferably the
> -multi-touch X driver [3]. In that driver, the trackingID stays the same and
> -unique until the contact vanishes (when the finger leaves the surface). The
> -problem of assigning a set of anonymous fingers to a set of identified
> -fingers is a euclidian bipartite matching problem at each event update, and
> -relies on a sufficiently rapid update rate.
> -
> -There are a few devices that support trackingID in hardware. User space can
> -make use of these native identifiers to reduce bandwidth and cpu usage.
> +initiated contact on the surface, is a Euclidian Bipartite Matching
> +problem.  At each event synchronization, the set of actual contacts are

                                                                       is

> +matched to the set of contacts from the previous synchronization. A full
> +implementation can be found in [3].


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Henrik Rydberg]

Randy Dunlap wrote:
[...]
>> +Protocol Usage
>> +--------------
>> +
>> +Contact details are sent sequentially as separate packets of ABS_MT
>> +events. Only the ABS_MT events are recognized as part of a contact
>> +packet. Since these events are ignored by current single-touch (ST)
>> +applications, the MT protocol can be implemented on top of the ST protocol
>> +in an existing driver.
>> +
>> +Drivers for type A devices mark the end of a packet by calling the
> 
> end?
> 
>> +input_mt_sync() function, which generates a SYN_MT_REPORT event. This
>> +instructs the receiver to accept the data for the current contact and
>> +prepare to receive another. Drivers for type B devices mark the beginning
> 
> vs. beginning?  Seems incongruous.  And not just to the doc, but to
> producers and consumers as well.

Perhaps this modification makes it clearer?

Drivers for type A devices separate contact packets by calling
input_mt_sync() at the end of each packet. This generates a SYN_MT_REPORT
event, which instructs the receiver to accept the data for the current
contact and prepare to receive another.

Drivers for type B devices separate contact packets by calling
input_mt_slot(), with a slot as argument, at the beginning of each packet.
This generates an ABS_MT_SLOT event, which instructs the receiver to
prepare for updates of the given slot.

>> +of a packet by calling the input_mt_slot() function with a slot as
>> +argument, which generates an ABS_MT_SLOT event. This instructs the receiver
>> +to prepare for updates of the given slot.
>> +
>> +The end of a multi-touch transfer is marked by calling the usual
> 
> The end method is done for Types A and B, right?

How about this line instead?

All drivers mark the end of a multi-touch transfer by calling the usual

>                                                                        is

Changed, thanks.

Henrik

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Randy Dunlap]

On Mon, 24 May 2010 00:27:19 +0200 Henrik Rydberg wrote:

> Randy Dunlap wrote:
> [...]
> >> +Protocol Usage
> >> +--------------
> >> +
> >> +Contact details are sent sequentially as separate packets of ABS_MT
> >> +events. Only the ABS_MT events are recognized as part of a contact
> >> +packet. Since these events are ignored by current single-touch (ST)
> >> +applications, the MT protocol can be implemented on top of the ST protocol
> >> +in an existing driver.
> >> +
> >> +Drivers for type A devices mark the end of a packet by calling the
> > 
> > end?
> > 
> >> +input_mt_sync() function, which generates a SYN_MT_REPORT event. This
> >> +instructs the receiver to accept the data for the current contact and
> >> +prepare to receive another. Drivers for type B devices mark the beginning
> > 
> > vs. beginning?  Seems incongruous.  And not just to the doc, but to
> > producers and consumers as well.
> 
> Perhaps this modification makes it clearer?
> 
> Drivers for type A devices separate contact packets by calling
> input_mt_sync() at the end of each packet. This generates a SYN_MT_REPORT
> event, which instructs the receiver to accept the data for the current
> contact and prepare to receive another.
> 
> Drivers for type B devices separate contact packets by calling
> input_mt_slot(), with a slot as argument, at the beginning of each packet.
> This generates an ABS_MT_SLOT event, which instructs the receiver to
> prepare for updates of the given slot.

Yes, that sounds good to me.

> >> +of a packet by calling the input_mt_slot() function with a slot as
> >> +argument, which generates an ABS_MT_SLOT event. This instructs the receiver
> >> +to prepare for updates of the given slot.
> >> +
> >> +The end of a multi-touch transfer is marked by calling the usual
> > 
> > The end method is done for Types A and B, right?
> 
> How about this line instead?
> 
> All drivers mark the end of a multi-touch transfer by calling the usual

Yes, good.


thanks.
---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Ping Cheng]

On Sun, May 23, 2010 at 3:27 PM, Henrik Rydberg <rydberg@euromail.se> wrote:
> Randy Dunlap wrote:
> [...]
>>> +Protocol Usage
>>> +--------------
>>> +
>>> +Contact details are sent sequentially as separate packets of ABS_MT
>>> +events. Only the ABS_MT events are recognized as part of a contact
>>> +packet. Since these events are ignored by current single-touch (ST)
>>> +applications, the MT protocol can be implemented on top of the ST protocol
>>> +in an existing driver.
>>> +
>>> +Drivers for type A devices mark the end of a packet by calling the
>>
>> end?

Since Randy brought this question up, I feel the urge to say
something.  I know there are X drivers and clients using the type A
format so I am not suggesting that we need to change this format.

What I am thinking is that we only need one SYN_ call for both _MT_
and regular data combined, which is a call to input_sync() at the end
of the whole packet. The SYN_MT_ can be replaced by the following
example, which I think is more "client-friendly". This solution is
based on the fact that the major difference between type A and type B
is whether we need to filter the data or not:

ABS_MT_RANDOM 0
ABS_MT_POSITION_X x[0]
ABS_MT_POSITION_Y y[0]
ABS_MT_ RANDOM 1
ABS_MT_POSITION_X x[1]
ABS_MT_POSITION_Y y[1]
SYN_REPORT

input_set_abs_params(input_dev, ABS_MT_RANDOM, 0, 2, 0, 0);

would tell the clients that they can expect two random touches.


>>> +The end of a multi-touch transfer is marked by calling the usual
>>
>> The end method is done for Types A and B, right?
>
> How about this line instead?
>
> All drivers mark the end of a multi-touch transfer by calling the usual

If we use ABS_MT_RANDOM, there would be only one SYN_ event for the
whole packet at the end, regardless of what kind of data is included
before the SYN_ event.

Basically, ABS_MT_RANDOM indicates a non-filtered and non-tracked MT_
event; ABS_MT_SLOT indicates a filtered and tracked MT_ event/slot.

With all this said, I don't have a preference for type A since I do
not need it for my driver. Just to be active in the group if you
wonder if there is any positive rationale :).

Ping

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Henrik Rydberg]

Ping Cheng wrote:
> On Sun, May 23, 2010 at 3:27 PM, Henrik Rydberg <rydberg@euromail.se> wrote:
>> Randy Dunlap wrote:
>> [...]
>>>> +Protocol Usage
>>>> +--------------
>>>> +
>>>> +Contact details are sent sequentially as separate packets of ABS_MT
>>>> +events. Only the ABS_MT events are recognized as part of a contact
>>>> +packet. Since these events are ignored by current single-touch (ST)
>>>> +applications, the MT protocol can be implemented on top of the ST protocol
>>>> +in an existing driver.
>>>> +
>>>> +Drivers for type A devices mark the end of a packet by calling the
>>> end?
> 
> Since Randy brought this question up, I feel the urge to say
> something.  I know there are X drivers and clients using the type A
> format so I am not suggesting that we need to change this format.

It is tempting to try to make type B backwards compatible, but unfortunately,
that is not possible. A type A receiver will always expect all data, and a type
B device will never send all data.

> 
> What I am thinking is that we only need one SYN_ call for both _MT_
> and regular data combined, which is a call to input_sync() at the end
> of the whole packet. The SYN_MT_ can be replaced by the following
> example, which I think is more "client-friendly". This solution is
> based on the fact that the major difference between type A and type B
> is whether we need to filter the data or not:
> 
> ABS_MT_RANDOM 0
> ABS_MT_POSITION_X x[0]
> ABS_MT_POSITION_Y y[0]
> ABS_MT_ RANDOM 1
> ABS_MT_POSITION_X x[1]
> ABS_MT_POSITION_Y y[1]
> SYN_REPORT
> 
> input_set_abs_params(input_dev, ABS_MT_RANDOM, 0, 2, 0, 0);
> 
> would tell the clients that they can expect two random touches.

And if you do s/RANDOM/SLOT/, you end up with what? ;-)

Henrik

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Ping Cheng]

On Mon, May 24, 2010 at 12:13 AM, Henrik Rydberg <rydberg@euromail.se> wrote:
> Ping Cheng wrote:
>> What I am thinking is that we only need one SYN_ call for both _MT_
>> and regular data combined, which is a call to input_sync() at the end
>> of the whole packet. The SYN_MT_ can be replaced by the following
>> example, which I think is more "client-friendly". This solution is
>> based on the fact that the major difference between type A and type B
>> is whether we need to filter the data or not:
>>
>> ABS_MT_RANDOM 0
>> ABS_MT_POSITION_X x[0]
>> ABS_MT_POSITION_Y y[0]
>> ABS_MT_ RANDOM 1
>> ABS_MT_POSITION_X x[1]
>> ABS_MT_POSITION_Y y[1]
>> SYN_REPORT
>>
>> input_set_abs_params(input_dev, ABS_MT_RANDOM, 0, 2, 0, 0);
>>
>> would tell the clients that they can expect two random touches.
>
> And if you do s/RANDOM/SLOT/, you end up with what? ;-)

Haha, I know what you are thinking :).

Maybe I didn't make my point clear.  I didn't mean to make SLOT
backward compatible.  I meant to replace SYN_MT_REPORT event with the
ABS_MT_ RANDOM label so we only sync the whole packet once at the end.
This way both types of MT_ data follow the same input event reporting
flow....

SLOT and RANDOM are both needed since they deal with two different
types of MT data, filtered (type B) and unfiltered (type A). There is
no midunderstanding there.

Ping

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Henrik Rydberg]

Ping Cheng wrote:
> On Mon, May 24, 2010 at 12:13 AM, Henrik Rydberg <rydberg@euromail.se> wrote:
>> Ping Cheng wrote:
>>> What I am thinking is that we only need one SYN_ call for both _MT_
>>> and regular data combined, which is a call to input_sync() at the end
>>> of the whole packet. The SYN_MT_ can be replaced by the following
>>> example, which I think is more "client-friendly". This solution is
>>> based on the fact that the major difference between type A and type B
>>> is whether we need to filter the data or not:
>>>
>>> ABS_MT_RANDOM 0
>>> ABS_MT_POSITION_X x[0]
>>> ABS_MT_POSITION_Y y[0]
>>> ABS_MT_ RANDOM 1
>>> ABS_MT_POSITION_X x[1]
>>> ABS_MT_POSITION_Y y[1]
>>> SYN_REPORT
>>>
>>> input_set_abs_params(input_dev, ABS_MT_RANDOM, 0, 2, 0, 0);
>>>
>>> would tell the clients that they can expect two random touches.
>> And if you do s/RANDOM/SLOT/, you end up with what? ;-)
> 
> Haha, I know what you are thinking :).
> 
> Maybe I didn't make my point clear.  I didn't mean to make SLOT
> backward compatible.  I meant to replace SYN_MT_REPORT event with the
> ABS_MT_ RANDOM label so we only sync the whole packet once at the end.
> This way both types of MT_ data follow the same input event reporting
> flow....

You mean changing the type A protocol, breaking the current code base? That is a
big no-no.

> SLOT and RANDOM are both needed since they deal with two different
> types of MT data, filtered (type B) and unfiltered (type A). There is
> no midunderstanding there.
> 
> Ping

Henrik

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Dmitry Torokhov]

On Mon, May 24, 2010 at 08:02:40PM +0200, Henrik Rydberg wrote:
> Ping Cheng wrote:
> > On Mon, May 24, 2010 at 12:13 AM, Henrik Rydberg <rydberg@euromail.se> wrote:
> >> Ping Cheng wrote:
> >>> What I am thinking is that we only need one SYN_ call for both _MT_
> >>> and regular data combined, which is a call to input_sync() at the end
> >>> of the whole packet. The SYN_MT_ can be replaced by the following
> >>> example, which I think is more "client-friendly". This solution is
> >>> based on the fact that the major difference between type A and type B
> >>> is whether we need to filter the data or not:
> >>>
> >>> ABS_MT_RANDOM 0
> >>> ABS_MT_POSITION_X x[0]
> >>> ABS_MT_POSITION_Y y[0]
> >>> ABS_MT_ RANDOM 1
> >>> ABS_MT_POSITION_X x[1]
> >>> ABS_MT_POSITION_Y y[1]
> >>> SYN_REPORT
> >>>
> >>> input_set_abs_params(input_dev, ABS_MT_RANDOM, 0, 2, 0, 0);
> >>>
> >>> would tell the clients that they can expect two random touches.
> >> And if you do s/RANDOM/SLOT/, you end up with what? ;-)
> > 
> > Haha, I know what you are thinking :).
> > 
> > Maybe I didn't make my point clear.  I didn't mean to make SLOT
> > backward compatible.  I meant to replace SYN_MT_REPORT event with the
> > ABS_MT_ RANDOM label so we only sync the whole packet once at the end.
> > This way both types of MT_ data follow the same input event reporting
> > flow....
> 
> You mean changing the type A protocol, breaking the current code base? That is a
> big no-no.
> 

We, however, could say that SYN_MT_REPORT may be omitted by the drivers
using slotting mechanism.

-- 
Dmitry

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Henrik Rydberg]

Dmitry Torokhov wrote:
> On Mon, May 24, 2010 at 08:02:40PM +0200, Henrik Rydberg wrote:
>> Ping Cheng wrote:
>>> On Mon, May 24, 2010 at 12:13 AM, Henrik Rydberg <rydberg@euromail.se> wrote:
>>>> Ping Cheng wrote:
>>>>> What I am thinking is that we only need one SYN_ call for both _MT_
>>>>> and regular data combined, which is a call to input_sync() at the end
>>>>> of the whole packet. The SYN_MT_ can be replaced by the following
>>>>> example, which I think is more "client-friendly". This solution is
>>>>> based on the fact that the major difference between type A and type B
>>>>> is whether we need to filter the data or not:
>>>>>
>>>>> ABS_MT_RANDOM 0
>>>>> ABS_MT_POSITION_X x[0]
>>>>> ABS_MT_POSITION_Y y[0]
>>>>> ABS_MT_ RANDOM 1
>>>>> ABS_MT_POSITION_X x[1]
>>>>> ABS_MT_POSITION_Y y[1]
>>>>> SYN_REPORT
>>>>>
>>>>> input_set_abs_params(input_dev, ABS_MT_RANDOM, 0, 2, 0, 0);
>>>>>
>>>>> would tell the clients that they can expect two random touches.
>>>> And if you do s/RANDOM/SLOT/, you end up with what? ;-)
>>> Haha, I know what you are thinking :).
>>>
>>> Maybe I didn't make my point clear.  I didn't mean to make SLOT
>>> backward compatible.  I meant to replace SYN_MT_REPORT event with the
>>> ABS_MT_ RANDOM label so we only sync the whole packet once at the end.
>>> This way both types of MT_ data follow the same input event reporting
>>> flow....
>> You mean changing the type A protocol, breaking the current code base? That is a
>> big no-no.
>>
> 
> We, however, could say that SYN_MT_REPORT may be omitted by the drivers
> using slotting mechanism.
> 

Yes. If that is still unclear from the documentation, I will happily modify it.

Henrik

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Ping Cheng]

On Mon, May 24, 2010 at 11:02 AM, Henrik Rydberg <rydberg@euromail.se> wrote:
> Ping Cheng wrote:
>> On Mon, May 24, 2010 at 12:13 AM, Henrik Rydberg <rydberg@euromail.se> wrote:
>>> Ping Cheng wrote:
>>>> What I am thinking is that we only need one SYN_ call for both _MT_
>>>> and regular data combined, which is a call to input_sync() at the end
>>>> of the whole packet. The SYN_MT_ can be replaced by the following
>>>> example, which I think is more "client-friendly". This solution is
>>>> based on the fact that the major difference between type A and type B
>>>> is whether we need to filter the data or not:
>>>>
>>>> ABS_MT_RANDOM 0
>>>> ABS_MT_POSITION_X x[0]
>>>> ABS_MT_POSITION_Y y[0]
>>>> ABS_MT_ RANDOM 1
>>>> ABS_MT_POSITION_X x[1]
>>>> ABS_MT_POSITION_Y y[1]
>>>> SYN_REPORT
>>>>
>>>> input_set_abs_params(input_dev, ABS_MT_RANDOM, 0, 2, 0, 0);
>>>>
>>>> would tell the clients that they can expect two random touches.
>>> And if you do s/RANDOM/SLOT/, you end up with what? ;-)
>>
>> Haha, I know what you are thinking :).
>>
>> Maybe I didn't make my point clear.  I didn't mean to make SLOT
>> backward compatible.  I meant to replace SYN_MT_REPORT event with the
>> ABS_MT_ RANDOM label so we only sync the whole packet once at the end.
>> This way both types of MT_ data follow the same input event reporting
>> flow....
>
> You mean changing the type A protocol, breaking the current code base? That is a
> big no-no.

Hi Henrik,

I saw your new patchset, very much appreciated.  There are reasons
that I am not "attacking" your new patches:

1.  I don't want to ruin your hard work;
2.  It would be easier for others to understand what I am talking
about along this thread.

I came up with another "crazy" idea which doesn't break the existing
type A protocol/code. We leave the existing code as is. However, we
make the new SLOT format support both type A and type B. This unified
approach offers a benefit for future X driver and client developers to
treat both types the same way.

As we've discussed before, the major difference between type A and
type B is the filtering and tracking mechanism. Filtering is tied to
the tracking ID since we do not apply filter to the untracked touch
poinsts. From this point of view, ABS_MT_SLOT doesn't lead to the
filter. The existence of an unique tracking ID triggers the filter.

Pure type A format (no filter applied):

ABS_MT_SLOT 0
ABS_MT_POSITION_X x[0]
ABS_MT_POSITION_Y y[0]
ABS_MT_ SLOT 1
ABS_MT_POSITION_X x[1]
ABS_MT_POSITION_Y y[1]
SYN_REPORT

Pure type B format (filter applied upon the detection of a tracking ID)

ABS_MT_SLOT 0
ABS_MT_TRACKING_ID 45
ABS_MT_POSITION_X x[0]
ABS_MT_POSITION_Y y[0]
ABS_MT_SLOT 1
ABS_MT_TRACKING_ID 46
ABS_MT_POSITION_X x[1]
ABS_MT_POSITION_Y y[1]
SYN_REPORT

Hybrid format (filter applied only when a tracking ID is detected):

ABS_MT_SLOT 0
ABS_MT_POSITION_X x[0]
ABS_MT_POSITION_Y y[0]
ABS_MT_SLOT 1
ABS_MT_TRACKING_ID 46
ABS_MT_POSITION_X x[1]
ABS_MT_POSITION_Y y[1]
ABS_MT_SLOT 2
ABS_MT_TRACKING_ID 20
ABS_MT_POSITION_X x[2]
ABS_MT_POSITION_Y y[2]
SYN_REPORT

So, one protocol covers both cases for the future.

Ping
--
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/2] input: mt: Document the MT event slot protocol (rev4)

[Pavel Machek]

Hi!

> +Protocol Example A
> +------------------
> +
> +Here is what a minimal event sequence for a two-contact touch would look
> +like for a type A device:
> +
> +   ABS_MT_POSITION_X x[0]
> +   ABS_MT_POSITION_Y y[0]
> +   SYN_MT_REPORT
> +   ABS_MT_POSITION_X x[1]
> +   ABS_MT_POSITION_Y y[1]
> +   SYN_MT_REPORT
> +   SYN_REPORT
...
> -Usage
> ------
> +Here is the sequence after lifting the first contact:
> +
> +   ABS_MT_POSITION_X x[1]
> +   ABS_MT_POSITION_Y y[1]
> +   SYN_MT_REPORT
> +   SYN_REPORT

...

> +Protocol Example B
> +------------------
> +
> +Here is what a minimal event sequence for a two-contact touch would look
> +like for a type B device:
> +
> +   ABS_MT_SLOT 0
> +   ABS_MT_TRACKING_ID 45
> +   ABS_MT_POSITION_X x[0]
> +   ABS_MT_POSITION_Y y[0]
> +   ABS_MT_SLOT 1
> +   ABS_MT_TRACKING_ID 46
> +   ABS_MT_POSITION_X x[1]
> +   ABS_MT_POSITION_Y y[1]
> +   SYN_REPORT
> +
> +Here is the sequence after moving contact 45 in the x direction:
> +
> +   ABS_MT_SLOT 0
> +   ABS_MT_POSITION_X x[0]
> +   SYN_REPORT

With this proposed system, protocol A is *very* different from
protocol B. Is there way to make them more similar?
-- 
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html

Re: [PATCH 2/2] input: mt: Document the MT event slot protocol (rev4)

[Henrik Rydberg]

Pavel Machek wrote:
> Hi!
> 
>> +Protocol Example A
>> +------------------
>> +
>> +Here is what a minimal event sequence for a two-contact touch would look
>> +like for a type A device:
>> +
>> +   ABS_MT_POSITION_X x[0]
>> +   ABS_MT_POSITION_Y y[0]
>> +   SYN_MT_REPORT
>> +   ABS_MT_POSITION_X x[1]
>> +   ABS_MT_POSITION_Y y[1]
>> +   SYN_MT_REPORT
>> +   SYN_REPORT
> ...
>> -Usage
>> ------
>> +Here is the sequence after lifting the first contact:
>> +
>> +   ABS_MT_POSITION_X x[1]
>> +   ABS_MT_POSITION_Y y[1]
>> +   SYN_MT_REPORT
>> +   SYN_REPORT
> 
> ...
> 
>> +Protocol Example B
>> +------------------
>> +
>> +Here is what a minimal event sequence for a two-contact touch would look
>> +like for a type B device:
>> +
>> +   ABS_MT_SLOT 0
>> +   ABS_MT_TRACKING_ID 45
>> +   ABS_MT_POSITION_X x[0]
>> +   ABS_MT_POSITION_Y y[0]
>> +   ABS_MT_SLOT 1
>> +   ABS_MT_TRACKING_ID 46
>> +   ABS_MT_POSITION_X x[1]
>> +   ABS_MT_POSITION_Y y[1]
>> +   SYN_REPORT
>> +
>> +Here is the sequence after moving contact 45 in the x direction:
>> +
>> +   ABS_MT_SLOT 0
>> +   ABS_MT_POSITION_X x[0]
>> +   SYN_REPORT
> 
> With this proposed system, protocol A is *very* different from
> protocol B. Is there way to make them more similar?

Hello,

unfortunately, the two protocols are different for a reason. Given the point of
the type B protocol, to reduce bandwidth and accommodate filtering in the input
core, the major difference is that type A receivers always expect all data
between synchronizations, whereas type B devices never send all data. This alone
means a receiver wishing to support both type of streams will need to know what
type of stream to expect. This is accomplished by the presence of ABS_MT_SLOT.
Secondly, in order to not break the established semantics of events, ABS_MT_SLOT
is used instead SYN_MT_REPORT. This also makes type B devices in type A
applications stop working in a somewhat graceful fashion.

The usage of SYN_MT_REPORT versus ABS_MT_SLOT is the only syntactic difference
between the protocols, and it stems from the different interpretation of what
comes through the wire. IMHO, it means the way the type B protocol is formulated
is the smallest possible change that accommodates the required effect.

Thanks,
Henrik

Re: [PATCH 1/2] input: mt: Introduce MT event slots (rev 5)

[Chase Douglas]

On Sun, 2010-05-23 at 00:30 +0200, Henrik Rydberg wrote:
> With the rapidly increasing number of intelligent multi-contact and
> multi-user devices, the need to send digested, filtered information
> from a set of different sources within the same device is imminent.
> This patch adds the concept of slots to the MT protocol. The slots
> enumerate a set of identified sources, such that all MT events
> can be passed independently and selectively per identified source.
> 
> The protocol works like this: Instead of sending a SYN_MT_REPORT
> event immediately after the contact data, one sends an ABS_MT_SLOT
> event immediately before the contact data. The input core will only
> emit events for slots with modified MT events. It is assumed that
> the same slot is used for the duration of an initiated contact.
> 
> Signed-off-by: Henrik Rydberg <rydberg@euromail.se>
> ---
> Revision 5 incorporates the following changes:
> 	 - Rename the slot event to ABS_MT_SLOT to keep all MT-related events
> 	   in the same namespace.
> 	 - Move the MT slot event list to input.h so that it can be read
> 	   by userspace.
> 
>  drivers/input/input.c |  105 +++++++++++++++++++++++++++++++++++++------------
>  include/linux/input.h |   44 ++++++++++++++++++++
>  2 files changed, 123 insertions(+), 26 deletions(-)

I was wondering what the status of this patch was. I reviewed it and I
think it's a good improvement of the protocol. I think it will help
simplify things in userspace event handling, and should reduce the noise
in evdev. I also like the incremental approach in that it doesn't force
drivers into the new protocol, but makes it available for them when they
can use it.

Acked-by: Chase Douglas <chase.douglas@canonical.com>

Long term, I think it makes the most sense to have a layer inside the
kernel to do software touch tracking and expose all MT data through the
slots protocol instead of it being determined by the capabilities of the
device/driver.

-- Chase

Re: [PATCH 1/2] input: mt: Introduce MT event slots (rev 5)

[Rafi Rubin]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 05/22/10 18:30, Henrik Rydberg wrote:
> With the rapidly increasing number of intelligent multi-contact and
> multi-user devices, the need to send digested, filtered information
> from a set of different sources within the same device is imminent.
> This patch adds the concept of slots to the MT protocol. The slots
> enumerate a set of identified sources, such that all MT events
> can be passed independently and selectively per identified source.
> 
> The protocol works like this: Instead of sending a SYN_MT_REPORT
> event immediately after the contact data, one sends an ABS_MT_SLOT
> event immediately before the contact data. The input core will only
> emit events for slots with modified MT events. It is assumed that
> the same slot is used for the duration of an initiated contact.
> 
Sorry, about taking so long to look at this patch.  This looks like a good step
forward and it looks good to me.

Acked-by: Rafi Rubin <rafi@seas.upenn.edu>
> Signed-off-by: Henrik Rydberg <rydberg@euromail.se>
> ---
> Revision 5 incorporates the following changes:
> 	 - Rename the slot event to ABS_MT_SLOT to keep all MT-related events
> 	   in the same namespace.
> 	 - Move the MT slot event list to input.h so that it can be read
> 	   by userspace.
> 
>  drivers/input/input.c |  105 +++++++++++++++++++++++++++++++++++++------------
>  include/linux/input.h |   44 ++++++++++++++++++++
>  2 files changed, 123 insertions(+), 26 deletions(-)
> 
> diff --git a/drivers/input/input.c b/drivers/input/input.c
> index 9c79bd5..9b6d474 100644
> --- a/drivers/input/input.c
> +++ b/drivers/input/input.c
> @@ -33,24 +33,9 @@ MODULE_LICENSE("GPL");
>  
>  #define INPUT_DEVICES	256
>  
> -/*
> - * EV_ABS events which should not be cached are listed here.
> - */
> -static unsigned int input_abs_bypass_init_data[] __initdata = {
> -	ABS_MT_TOUCH_MAJOR,
> -	ABS_MT_TOUCH_MINOR,
> -	ABS_MT_WIDTH_MAJOR,
> -	ABS_MT_WIDTH_MINOR,
> -	ABS_MT_ORIENTATION,
> -	ABS_MT_POSITION_X,
> -	ABS_MT_POSITION_Y,
> -	ABS_MT_TOOL_TYPE,
> -	ABS_MT_BLOB_ID,
> -	ABS_MT_TRACKING_ID,
> -	ABS_MT_PRESSURE,
> -	0
> -};
> -static unsigned long input_abs_bypass[BITS_TO_LONGS(ABS_CNT)];
> +static unsigned int input_mt_abs_map_init_data[] __initdata =
> +	MT_SLOT_ABS_EVENTS;
> +static unsigned char input_mt_abs_map[ABS_CNT];
>  
>  static LIST_HEAD(input_dev_list);
>  static LIST_HEAD(input_handler_list);
> @@ -181,6 +166,26 @@ static void input_stop_autorepeat(struct input_dev *dev)
>  #define INPUT_PASS_TO_DEVICE	2
>  #define INPUT_PASS_TO_ALL	(INPUT_PASS_TO_HANDLERS | INPUT_PASS_TO_DEVICE)
>  
> +static void input_mt_handle_abs_event(struct input_dev *dev,
> +				      unsigned int code, int value)
> +{
> +	if (dev->mt) {
> +		struct input_mt_slot *mtslot = &dev->mt[dev->slot];
> +		unsigned int mtcode = input_mt_abs_map[code] - 1;
> +		int old = mtslot->abs[mtcode];
> +		value = input_defuzz_abs_event(value, old, dev->absfuzz[code]);
> +		if (value == old)
> +			return;
> +		mtslot->abs[mtcode] = value;
> +	}
> +	dev->sync = 0;
> +	if (dev->slot != dev->abs[ABS_MT_SLOT]) {
> +		dev->abs[ABS_MT_SLOT] = dev->slot;
> +		input_pass_event(dev, EV_ABS, ABS_MT_SLOT, dev->slot);
> +	}
> +	input_pass_event(dev, EV_ABS, code, value);
> +}
> +
>  static void input_handle_event(struct input_dev *dev,
>  			       unsigned int type, unsigned int code, int value)
>  {
> @@ -235,11 +240,17 @@ static void input_handle_event(struct input_dev *dev,
>  	case EV_ABS:
>  		if (is_event_supported(code, dev->absbit, ABS_MAX)) {
>  
> -			if (test_bit(code, input_abs_bypass)) {
> -				disposition = INPUT_PASS_TO_HANDLERS;
> +			if (code == ABS_MT_SLOT) {
> +				if (value >= 0 && value < dev->mtsize)
> +					dev->slot = value;
>  				break;
>  			}
>  
> +			if (input_mt_abs_map[code]) {
> +				input_mt_handle_abs_event(dev, code, value);
> +				return;
> +			}
> +
>  			value = input_defuzz_abs_event(value,
>  					dev->abs[code], dev->absfuzz[code]);
>  
> @@ -1278,6 +1289,7 @@ static void input_dev_release(struct device *device)
>  	struct input_dev *dev = to_input_dev(device);
>  
>  	input_ff_destroy(dev);
> +	input_mt_destroy_slots(dev);
>  	kfree(dev);
>  
>  	module_put(THIS_MODULE);
> @@ -1518,6 +1530,46 @@ void input_free_device(struct input_dev *dev)
>  EXPORT_SYMBOL(input_free_device);
>  
>  /**
> + * input_mt_create_slots() - create MT input slots
> + * @dev: input device supporting MT events and finger tracking
> + * @max_slots: maximum number of slots supported by the device
> + *
> + * This function allocates all necessary memory for MT slot handling
> + * in the input device, and adds ABS_MT_SLOT to the device capabilities.
> + */
> +int input_mt_create_slots(struct input_dev *dev, int max_slots)
> +{
> +	struct input_mt_slot *mt;
> +
> +	if (max_slots <= 0)
> +		return 0;
> +	mt = kzalloc(max_slots * sizeof(struct input_mt_slot), GFP_KERNEL);
> +	if (!mt)
> +		return -ENOMEM;
> +
> +	dev->mt = mt;
> +	dev->mtsize = max_slots;
> +	input_set_abs_params(dev, ABS_MT_SLOT, 0, max_slots - 1, 0, 0);
> +	return 0;
> +}
> +EXPORT_SYMBOL(input_mt_create_slots);
> +
> +/**
> + * input_mt_destroy_slots() - frees the MT slots of the input device
> + * @dev: input device with allocated MT slots
> + *
> + * This function is only needed in error path as the input core will
> + * automatically free the MT slots when the device is destroyed.
> + */
> +void input_mt_destroy_slots(struct input_dev *dev)
> +{
> +	kfree(dev->mt);
> +	dev->mt = NULL;
> +	dev->mtsize = 0;
> +}
> +EXPORT_SYMBOL(input_mt_destroy_slots);
> +
> +/**
>   * input_set_capability - mark device as capable of a certain event
>   * @dev: device that is capable of emitting or accepting event
>   * @type: type of the event (EV_KEY, EV_REL, etc...)
> @@ -1926,19 +1978,20 @@ static const struct file_operations input_fops = {
>  	.open = input_open_file,
>  };
>  
> -static void __init input_init_abs_bypass(void)
> +static void __init input_mt_init_maps(void)
>  {
> -	const unsigned int *p;
> -
> -	for (p = input_abs_bypass_init_data; *p; p++)
> -		input_abs_bypass[BIT_WORD(*p)] |= BIT_MASK(*p);
> +	int i;
> +	BUILD_BUG_ON(MT_ABS_SIZE != (typeof(input_mt_abs_map[0]))MT_ABS_SIZE);
> +	BUILD_BUG_ON(ARRAY_SIZE(input_mt_abs_map_init_data) > MT_ABS_SIZE);
> +	for (i = 0; i < ARRAY_SIZE(input_mt_abs_map_init_data); i++)
> +		input_mt_abs_map[input_mt_abs_map_init_data[i]] = i + 1;
>  }
>  
>  static int __init input_init(void)
>  {
>  	int err;
>  
> -	input_init_abs_bypass();
> +	input_mt_init_maps();
>  
>  	err = class_register(&input_class);
>  	if (err) {
> diff --git a/include/linux/input.h b/include/linux/input.h
> index 7ed2251..bea6958 100644
> --- a/include/linux/input.h
> +++ b/include/linux/input.h
> @@ -694,6 +694,7 @@ struct input_absinfo {
>  #define ABS_VOLUME		0x20
>  #define ABS_MISC		0x28
>  
> +#define ABS_MT_SLOT		0x2f	/* MT slot being modified */
>  #define ABS_MT_TOUCH_MAJOR	0x30	/* Major axis of touching ellipse */
>  #define ABS_MT_TOUCH_MINOR	0x31	/* Minor axis (omit if circular) */
>  #define ABS_MT_WIDTH_MAJOR	0x32	/* Major axis of approaching ellipse */
> @@ -814,6 +815,24 @@ struct input_absinfo {
>  #define MT_TOOL_PEN		1
>  
>  /*
> + * MT slot event lists
> + */
> +
> +#define MT_SLOT_ABS_EVENTS {	\
> +	ABS_MT_TOUCH_MAJOR,	\
> +	ABS_MT_TOUCH_MINOR,	\
> +	ABS_MT_WIDTH_MAJOR,	\
> +	ABS_MT_WIDTH_MINOR,	\
> +	ABS_MT_ORIENTATION,	\
> +	ABS_MT_POSITION_X,	\
> +	ABS_MT_POSITION_Y,	\
> +	ABS_MT_TOOL_TYPE,	\
> +	ABS_MT_BLOB_ID,		\
> +	ABS_MT_TRACKING_ID,	\
> +	ABS_MT_PRESSURE,	\
> +}
> +
> +/*
>   * Values describing the status of a force-feedback effect
>   */
>  #define FF_STATUS_STOPPED	0x00
> @@ -1080,6 +1099,9 @@ struct ff_effect {
>   * @sync: set to 1 when there were no new events since last EV_SYNC
>   * @abs: current values for reports from absolute axes
>   * @rep: current values for autorepeat parameters (delay, rate)
> + * @mt: array of MT slots
> + * @mtsize: number of allocated MT slots
> + * @slot: current MT slot
>   * @key: reflects current state of device's keys/buttons
>   * @led: reflects current state of device's LEDs
>   * @snd: reflects current state of sound effects
> @@ -1157,6 +1179,10 @@ struct input_dev {
>  	int abs[ABS_MAX + 1];
>  	int rep[REP_MAX + 1];
>  
> +	struct input_mt_slot *mt;
> +	int mtsize;
> +	int slot;
> +
>  	unsigned long key[BITS_TO_LONGS(KEY_CNT)];
>  	unsigned long led[BITS_TO_LONGS(LED_CNT)];
>  	unsigned long snd[BITS_TO_LONGS(SND_CNT)];
> @@ -1405,6 +1431,11 @@ static inline void input_mt_sync(struct input_dev *dev)
>  	input_event(dev, EV_SYN, SYN_MT_REPORT, 0);
>  }
>  
> +static inline void input_mt_slot(struct input_dev *dev, int slot)
> +{
> +	input_event(dev, EV_ABS, ABS_MT_SLOT, slot);
> +}
> +
>  void input_set_capability(struct input_dev *dev, unsigned int type, unsigned int code);
>  
>  static inline void input_set_abs_params(struct input_dev *dev, int axis, int min, int max, int fuzz, int flat)
> @@ -1484,5 +1515,18 @@ int input_ff_erase(struct input_dev *dev, int effect_id, struct file *file);
>  int input_ff_create_memless(struct input_dev *dev, void *data,
>  		int (*play_effect)(struct input_dev *, void *, struct ff_effect *));
>  
> +#define MT_ABS_SIZE 11
> +
> +/**
> + * struct input_mt_slot - represents the state of an input MT slot
> + * @abs: current values of ABS_MT axes for this slot
> + */
> +struct input_mt_slot {
> +	int abs[MT_ABS_SIZE];
> +};
> +
> +int input_mt_create_slots(struct input_dev *dev, int max_slots);
> +void input_mt_destroy_slots(struct input_dev *dev);
> +
>  #endif
>  #endif

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkwXCKwACgkQwuRiAT9o608AfwCfT15rbveKL/kCROKk5E7xg81L
zrYAoK8edxq+1HeBDBcHiuP2rDoy4Oi/
=J6e0
-----END PGP SIGNATURE-----