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

[Randy Dunlap <rdunlap@xenotime.net>]

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