ARM: Merge next-samsung-s3c2443-clock
[linux-2.6.git] / Documentation / input / multi-touch-protocol.txt
1 Multi-touch (MT) Protocol
2 -------------------------
3         Copyright (C) 2009      Henrik Rydberg <rydberg@euromail.se>
4
5
6 Introduction
7 ------------
8
9 In order to utilize the full power of the new multi-touch devices, a way to
10 report detailed finger data to user space is needed. This document
11 describes the multi-touch (MT) protocol which allows kernel drivers to
12 report details for an arbitrary number of fingers.
13
14
15 Usage
16 -----
17
18 Anonymous finger details are sent sequentially as separate packets of ABS
19 events. Only the ABS_MT events are recognized as part of a finger
20 packet. The end of a packet is marked by calling the input_mt_sync()
21 function, which generates a SYN_MT_REPORT event. This instructs the
22 receiver to accept the data for the current finger and prepare to receive
23 another. The end of a multi-touch transfer is marked by calling the usual
24 input_sync() function. This instructs the receiver to act upon events
25 accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new
26 set of events/packets.
27
28 A set of ABS_MT events with the desired properties is defined. The events
29 are divided into categories, to allow for partial implementation.  The
30 minimum set consists of ABS_MT_TOUCH_MAJOR, ABS_MT_POSITION_X and
31 ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked.  If the
32 device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size
33 of the approaching finger. Anisotropy and direction may be specified with
34 ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION.  The
35 ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
36 finger or a pen or something else.  Devices with more granular information
37 may specify general shapes as blobs, i.e., as a sequence of rectangular
38 shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices
39 that currently support it, the ABS_MT_TRACKING_ID event may be used to
40 report finger tracking from hardware [5].
41
42 Here is what a minimal event sequence for a two-finger touch would look
43 like:
44
45    ABS_MT_TOUCH_MAJOR
46    ABS_MT_POSITION_X
47    ABS_MT_POSITION_Y
48    SYN_MT_REPORT
49    ABS_MT_TOUCH_MAJOR
50    ABS_MT_POSITION_X
51    ABS_MT_POSITION_Y
52    SYN_MT_REPORT
53    SYN_REPORT
54
55
56 Event Semantics
57 ---------------
58
59 The word "contact" is used to describe a tool which is in direct contact
60 with the surface. A finger, a pen or a rubber all classify as contacts.
61
62 ABS_MT_TOUCH_MAJOR
63
64 The length of the major axis of the contact. The length should be given in
65 surface units. If the surface has an X times Y resolution, the largest
66 possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4].
67
68 ABS_MT_TOUCH_MINOR
69
70 The length, in surface units, of the minor axis of the contact. If the
71 contact is circular, this event can be omitted [4].
72
73 ABS_MT_WIDTH_MAJOR
74
75 The length, in surface units, of the major axis of the approaching
76 tool. This should be understood as the size of the tool itself. The
77 orientation of the contact and the approaching tool are assumed to be the
78 same [4].
79
80 ABS_MT_WIDTH_MINOR
81
82 The length, in surface units, of the minor axis of the approaching
83 tool. Omit if circular [4].
84
85 The above four values can be used to derive additional information about
86 the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
87 the notion of pressure. The fingers of the hand and the palm all have
88 different characteristic widths [1].
89
90 ABS_MT_ORIENTATION
91
92 The orientation of the ellipse. The value should describe a signed quarter
93 of a revolution clockwise around the touch center. The signed value range
94 is arbitrary, but zero should be returned for a finger aligned along the Y
95 axis of the surface, a negative value when finger is turned to the left, and
96 a positive value when finger turned to the right. When completely aligned with
97 the X axis, the range max should be returned.  Orientation can be omitted
98 if the touching object is circular, or if the information is not available
99 in the kernel driver. Partial orientation support is possible if the device
100 can distinguish between the two axis, but not (uniquely) any values in
101 between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1]
102 [4].
103
104 ABS_MT_POSITION_X
105
106 The surface X coordinate of the center of the touching ellipse.
107
108 ABS_MT_POSITION_Y
109
110 The surface Y coordinate of the center of the touching ellipse.
111
112 ABS_MT_TOOL_TYPE
113
114 The type of approaching tool. A lot of kernel drivers cannot distinguish
115 between different tool types, such as a finger or a pen. In such cases, the
116 event should be omitted. The protocol currently supports MT_TOOL_FINGER and
117 MT_TOOL_PEN [2].
118
119 ABS_MT_BLOB_ID
120
121 The BLOB_ID groups several packets together into one arbitrarily shaped
122 contact. This is a low-level anonymous grouping, and should not be confused
123 with the high-level trackingID [5]. Most kernel drivers will not have blob
124 capability, and can safely omit the event.
125
126 ABS_MT_TRACKING_ID
127
128 The TRACKING_ID identifies an initiated contact throughout its life cycle
129 [5]. There are currently only a few devices that support it, so this event
130 should normally be omitted.
131
132
133 Event Computation
134 -----------------
135
136 The flora of different hardware unavoidably leads to some devices fitting
137 better to the MT protocol than others. To simplify and unify the mapping,
138 this section gives recipes for how to compute certain events.
139
140 For devices reporting contacts as rectangular shapes, signed orientation
141 cannot be obtained. Assuming X and Y are the lengths of the sides of the
142 touching rectangle, here is a simple formula that retains the most
143 information possible:
144
145    ABS_MT_TOUCH_MAJOR := max(X, Y)
146    ABS_MT_TOUCH_MINOR := min(X, Y)
147    ABS_MT_ORIENTATION := bool(X > Y)
148
149 The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that
150 the device can distinguish between a finger along the Y axis (0) and a
151 finger along the X axis (1).
152
153
154 Finger Tracking
155 ---------------
156
157 The kernel driver should generate an arbitrary enumeration of the set of
158 anonymous contacts currently on the surface. The order in which the packets
159 appear in the event stream is not important.
160
161 The process of finger tracking, i.e., to assign a unique trackingID to each
162 initiated contact on the surface, is left to user space; preferably the
163 multi-touch X driver [3]. In that driver, the trackingID stays the same and
164 unique until the contact vanishes (when the finger leaves the surface). The
165 problem of assigning a set of anonymous fingers to a set of identified
166 fingers is a euclidian bipartite matching problem at each event update, and
167 relies on a sufficiently rapid update rate.
168
169 There are a few devices that support trackingID in hardware. User space can
170 make use of these native identifiers to reduce bandwidth and cpu usage.
171
172
173 Notes
174 -----
175
176 In order to stay compatible with existing applications, the data
177 reported in a finger packet must not be recognized as single-touch
178 events. In addition, all finger data must bypass input filtering,
179 since subsequent events of the same type refer to different fingers.
180
181 The first kernel driver to utilize the MT protocol is the bcm5974 driver,
182 where examples can be found.
183
184 [1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the
185 difference between the contact position and the approaching tool position
186 could be used to derive tilt.
187 [2] The list can of course be extended.
188 [3] The multi-touch X driver is currently in the prototyping stage. At the
189 time of writing (April 2009), the MT protocol is not yet merged, and the
190 prototype implements finger matching, basic mouse support and two-finger
191 scrolling. The project aims at improving the quality of current multi-touch
192 functionality available in the Synaptics X driver, and in addition
193 implement more advanced gestures.
194 [4] See the section on event computation.
195 [5] See the section on finger tracking.