Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input
* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input:
Input: libps2 - better handle bad scheduler decisions
Input: usb1400_ts - fix access to "device data" in resume function
Input: multitouch - augment event semantics documentation
Input: multitouch - add tracking ID to the protocol
+83
-26
+79
-24
Documentation/input/multi-touch-protocol.txt
+79
-24
Documentation/input/multi-touch-protocol.txt
···
18
18
Anonymous finger details are sent sequentially as separate packets of ABS
19
19
events. Only the ABS_MT events are recognized as part of a finger
20
20
packet. The end of a packet is marked by calling the input_mt_sync()
21
-
function, which generates a SYN_MT_REPORT event. The end of multi-touch
22
-
transfer is marked by calling the usual input_sync() function.
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.
23
27
24
28
A set of ABS_MT events with the desired properties is defined. The events
25
29
are divided into categories, to allow for partial implementation. The
···
31
27
ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked. If the
32
28
device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size
33
29
of the approaching finger. Anisotropy and direction may be specified with
34
-
ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. Devices with
35
-
more granular information may specify general shapes as blobs, i.e., as a
36
-
sequence of rectangular shapes grouped together by an
37
-
ABS_MT_BLOB_ID. Finally, the ABS_MT_TOOL_TYPE may be used to specify
38
-
whether the touching tool is a finger or a pen or something else.
30
+
ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. The
31
+
ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
32
+
finger or a pen or something else. Devices with more granular information
33
+
may specify general shapes as blobs, i.e., as a sequence of rectangular
34
+
shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices
35
+
that currently support it, the ABS_MT_TRACKING_ID event may be used to
36
+
report finger tracking from hardware [5].
37
+
38
+
Here is what a minimal event sequence for a two-finger touch would look
39
+
like:
40
+
41
+
ABS_MT_TOUCH_MAJOR
42
+
ABS_MT_POSITION_X
43
+
ABS_MT_POSITION_Y
44
+
SYN_MT_REPORT
45
+
ABS_MT_TOUCH_MAJOR
46
+
ABS_MT_POSITION_X
47
+
ABS_MT_POSITION_Y
48
+
SYN_MT_REPORT
49
+
SYN_REPORT
39
50
40
51
41
52
Event Semantics
···
63
44
64
45
The length of the major axis of the contact. The length should be given in
65
46
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.
47
+
possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4].
67
48
68
49
ABS_MT_TOUCH_MINOR
69
50
70
51
The length, in surface units, of the minor axis of the contact. If the
71
-
contact is circular, this event can be omitted.
52
+
contact is circular, this event can be omitted [4].
72
53
73
54
ABS_MT_WIDTH_MAJOR
74
55
75
56
The length, in surface units, of the major axis of the approaching
76
57
tool. This should be understood as the size of the tool itself. The
77
58
orientation of the contact and the approaching tool are assumed to be the
78
-
same.
59
+
same [4].
79
60
80
61
ABS_MT_WIDTH_MINOR
81
62
82
63
The length, in surface units, of the minor axis of the approaching
83
-
tool. Omit if circular.
64
+
tool. Omit if circular [4].
84
65
85
66
The above four values can be used to derive additional information about
86
67
the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
···
89
70
90
71
ABS_MT_ORIENTATION
91
72
92
-
The orientation of the ellipse. The value should describe half a revolution
93
-
clockwise around the touch center. The scale of the value is arbitrary, but
94
-
zero should be returned for an ellipse aligned along the Y axis of the
95
-
surface. As an example, an index finger placed straight onto the axis could
96
-
return zero orientation, something negative when twisted to the left, and
97
-
something positive when twisted to the right. This value can be omitted if
98
-
the touching object is circular, or if the information is not available in
99
-
the kernel driver.
73
+
The orientation of the ellipse. The value should describe a signed quarter
74
+
of a revolution clockwise around the touch center. The signed value range
75
+
is arbitrary, but zero should be returned for a finger aligned along the Y
76
+
axis of the surface, a negative value when finger is turned to the left, and
77
+
a positive value when finger turned to the right. When completely aligned with
78
+
the X axis, the range max should be returned. Orientation can be omitted
79
+
if the touching object is circular, or if the information is not available
80
+
in the kernel driver. Partial orientation support is possible if the device
81
+
can distinguish between the two axis, but not (uniquely) any values in
82
+
between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1]
83
+
[4].
100
84
101
85
ABS_MT_POSITION_X
102
86
···
120
98
121
99
The BLOB_ID groups several packets together into one arbitrarily shaped
122
100
contact. This is a low-level anonymous grouping, and should not be confused
123
-
with the high-level contactID, explained below. Most kernel drivers will
124
-
not have this capability, and can safely omit the event.
101
+
with the high-level trackingID [5]. Most kernel drivers will not have blob
102
+
capability, and can safely omit the event.
103
+
104
+
ABS_MT_TRACKING_ID
105
+
106
+
The TRACKING_ID identifies an initiated contact throughout its life cycle
107
+
[5]. There are currently only a few devices that support it, so this event
108
+
should normally be omitted.
109
+
110
+
111
+
Event Computation
112
+
-----------------
113
+
114
+
The flora of different hardware unavoidably leads to some devices fitting
115
+
better to the MT protocol than others. To simplify and unify the mapping,
116
+
this section gives recipes for how to compute certain events.
117
+
118
+
For devices reporting contacts as rectangular shapes, signed orientation
119
+
cannot be obtained. Assuming X and Y are the lengths of the sides of the
120
+
touching rectangle, here is a simple formula that retains the most
121
+
information possible:
122
+
123
+
ABS_MT_TOUCH_MAJOR := max(X, Y)
124
+
ABS_MT_TOUCH_MINOR := min(X, Y)
125
+
ABS_MT_ORIENTATION := bool(X > Y)
126
+
127
+
The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that
128
+
the device can distinguish between a finger along the Y axis (0) and a
129
+
finger along the X axis (1).
125
130
126
131
127
132
Finger Tracking
···
158
109
anonymous contacts currently on the surface. The order in which the packets
159
110
appear in the event stream is not important.
160
111
161
-
The process of finger tracking, i.e., to assign a unique contactID to each
112
+
The process of finger tracking, i.e., to assign a unique trackingID to each
162
113
initiated contact on the surface, is left to user space; preferably the
163
-
multi-touch X driver [3]. In that driver, the contactID stays the same and
114
+
multi-touch X driver [3]. In that driver, the trackingID stays the same and
164
115
unique until the contact vanishes (when the finger leaves the surface). The
165
116
problem of assigning a set of anonymous fingers to a set of identified
166
117
fingers is a euclidian bipartite matching problem at each event update, and
167
118
relies on a sufficiently rapid update rate.
119
+
120
+
There are a few devices that support trackingID in hardware. User space can
121
+
make use of these native identifiers to reduce bandwidth and cpu usage.
122
+
168
123
169
124
Notes
170
125
-----
···
189
136
time of writing (April 2009), the MT protocol is not yet merged, and the
190
137
prototype implements finger matching, basic mouse support and two-finger
191
138
scrolling. The project aims at improving the quality of current multi-touch
192
-
functionality available in the synaptics X driver, and in addition
139
+
functionality available in the Synaptics X driver, and in addition
193
140
implement more advanced gestures.
141
+
[4] See the section on event computation.
142
+
[5] See the section on finger tracking.
+1
drivers/input/input.c
+1
drivers/input/input.c
+1
-1
drivers/input/serio/libps2.c
+1
-1
drivers/input/serio/libps2.c
···
210
210
timeout = wait_event_timeout(ps2dev->wait,
211
211
!(ps2dev->flags & PS2_FLAG_CMD1), timeout);
212
212
213
-
if (ps2dev->cmdcnt && timeout > 0) {
213
+
if (ps2dev->cmdcnt && !(ps2dev->flags & PS2_FLAG_CMD1)) {
214
214
215
215
timeout = ps2_adjust_timeout(ps2dev, command, timeout);
216
216
wait_event_timeout(ps2dev->wait,
+1
-1
drivers/input/touchscreen/ucb1400_ts.c
+1
-1
drivers/input/touchscreen/ucb1400_ts.c
+1
include/linux/input.h
+1
include/linux/input.h
···
656
656
#define ABS_MT_POSITION_Y 0x36 /* Center Y ellipse position */
657
657
#define ABS_MT_TOOL_TYPE 0x37 /* Type of touching device */
658
658
#define ABS_MT_BLOB_ID 0x38 /* Group a set of packets as a blob */
659
+
#define ABS_MT_TRACKING_ID 0x39 /* Unique ID of initiated contact */
659
660
660
661
#define ABS_MAX 0x3f
661
662
#define ABS_CNT (ABS_MAX+1)