aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/input
diff options
context:
space:
mode:
authorLen Brown <len.brown@intel.com>2010-08-15 01:06:31 -0400
committerLen Brown <len.brown@intel.com>2010-08-15 01:06:31 -0400
commit95ee46aa8698f2000647dfb362400fadbb5807cf (patch)
treee5a05c7297f997e191c73091934e42e3195c0e40 /Documentation/input
parentcfa806f059801dbe7e435745eb2e187c8bfe1e7f (diff)
parent92fa5bd9a946b6e7aab6764e7312e4e3d9bed295 (diff)
Merge branch 'linus' into release
Conflicts: drivers/acpi/debug.c Signed-off-by: Len Brown <len.brown@intel.com>
Diffstat (limited to 'Documentation/input')
-rw-r--r--Documentation/input/appletouch.txt2
-rw-r--r--Documentation/input/bcm5974.txt2
-rw-r--r--Documentation/input/iforce-protocol.txt2
-rw-r--r--Documentation/input/multi-touch-protocol.txt218
-rw-r--r--Documentation/input/sentelic.txt2
-rw-r--r--Documentation/input/xpad.txt2
6 files changed, 154 insertions, 74 deletions
diff --git a/Documentation/input/appletouch.txt b/Documentation/input/appletouch.txt
index 4f7c633a76d2..b13de3f89108 100644
--- a/Documentation/input/appletouch.txt
+++ b/Documentation/input/appletouch.txt
@@ -82,4 +82,4 @@ Links:
82------ 82------
83 83
84[1]: http://johannes.sipsolutions.net/PowerBook/touchpad/ 84[1]: http://johannes.sipsolutions.net/PowerBook/touchpad/
85[2]: http://web.telia.com/~u89404340/touchpad/index.html 85[2]: http://web.archive.org/web/*/http://web.telia.com/~u89404340/touchpad/index.html
diff --git a/Documentation/input/bcm5974.txt b/Documentation/input/bcm5974.txt
index 5e22dcf6d48d..74d3876d6f34 100644
--- a/Documentation/input/bcm5974.txt
+++ b/Documentation/input/bcm5974.txt
@@ -62,4 +62,4 @@ Links
62----- 62-----
63 63
64[1] http://ubuntuforums.org/showthread.php?t=840040 64[1] http://ubuntuforums.org/showthread.php?t=840040
65[2] http://http://bitmath.org/code/ 65[2] http://bitmath.org/code/
diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.txt
index 3ac92413c874..2d5fbfd6023e 100644
--- a/Documentation/input/iforce-protocol.txt
+++ b/Documentation/input/iforce-protocol.txt
@@ -251,7 +251,7 @@ Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.
251 251
252** Author of this document ** 252** Author of this document **
253Johann Deneux <johann.deneux@gmail.com> 253Johann Deneux <johann.deneux@gmail.com>
254Home page at http://www.esil.univ-mrs.fr/~jdeneux/projects/ff/ 254Home page at http://web.archive.org/web/*/http://www.esil.univ-mrs.fr
255 255
256Additions by Vojtech Pavlik. 256Additions by Vojtech Pavlik.
257 257
diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt
index c0fc1c75fd88..bdcba154b83e 100644
--- a/Documentation/input/multi-touch-protocol.txt
+++ b/Documentation/input/multi-touch-protocol.txt
@@ -6,31 +6,149 @@ Multi-touch (MT) Protocol
6Introduction 6Introduction
7------------ 7------------
8 8
9In order to utilize the full power of the new multi-touch devices, a way to 9In order to utilize the full power of the new multi-touch and multi-user
10report detailed finger data to user space is needed. This document 10devices, a way to report detailed data from multiple contacts, i.e.,
11describes the multi-touch (MT) protocol which allows kernel drivers to 11objects in direct contact with the device surface, is needed. This
12report details for an arbitrary number of fingers. 12document describes the multi-touch (MT) protocol which allows kernel
13drivers to report details for an arbitrary number of contacts.
14
15The protocol is divided into two types, depending on the capabilities of the
16hardware. For devices handling anonymous contacts (type A), the protocol
17describes how to send the raw data for all contacts to the receiver. For
18devices capable of tracking identifiable contacts (type B), the protocol
19describes how to send updates for individual contacts via event slots.
20
21
22Protocol Usage
23--------------
24
25Contact details are sent sequentially as separate packets of ABS_MT
26events. Only the ABS_MT events are recognized as part of a contact
27packet. Since these events are ignored by current single-touch (ST)
28applications, the MT protocol can be implemented on top of the ST protocol
29in an existing driver.
30
31Drivers for type A devices separate contact packets by calling
32input_mt_sync() at the end of each packet. This generates a SYN_MT_REPORT
33event, which instructs the receiver to accept the data for the current
34contact and prepare to receive another.
35
36Drivers for type B devices separate contact packets by calling
37input_mt_slot(), with a slot as argument, at the beginning of each packet.
38This generates an ABS_MT_SLOT event, which instructs the receiver to
39prepare for updates of the given slot.
40
41All drivers mark the end of a multi-touch transfer by calling the usual
42input_sync() function. This instructs the receiver to act upon events
43accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new set
44of events/packets.
45
46The main difference between the stateless type A protocol and the stateful
47type B slot protocol lies in the usage of identifiable contacts to reduce
48the amount of data sent to userspace. The slot protocol requires the use of
49the ABS_MT_TRACKING_ID, either provided by the hardware or computed from
50the raw data [5].
51
52For type A devices, the kernel driver should generate an arbitrary
53enumeration of the full set of anonymous contacts currently on the
54surface. The order in which the packets appear in the event stream is not
55important. Event filtering and finger tracking is left to user space [3].
56
57For type B devices, the kernel driver should associate a slot with each
58identified contact, and use that slot to propagate changes for the contact.
59Creation, replacement and destruction of contacts is achieved by modifying
60the ABS_MT_TRACKING_ID of the associated slot. A non-negative tracking id
61is interpreted as a contact, and the value -1 denotes an unused slot. A
62tracking id not previously present is considered new, and a tracking id no
63longer present is considered removed. Since only changes are propagated,
64the full state of each initiated contact has to reside in the receiving
65end. Upon receiving an MT event, one simply updates the appropriate
66attribute of the current slot.
67
68
69Protocol Example A
70------------------
71
72Here is what a minimal event sequence for a two-contact touch would look
73like for a type A device:
74
75 ABS_MT_POSITION_X x[0]
76 ABS_MT_POSITION_Y y[0]
77 SYN_MT_REPORT
78 ABS_MT_POSITION_X x[1]
79 ABS_MT_POSITION_Y y[1]
80 SYN_MT_REPORT
81 SYN_REPORT
13 82
83The sequence after moving one of the contacts looks exactly the same; the
84raw data for all present contacts are sent between every synchronization
85with SYN_REPORT.
14 86
15Usage 87Here is the sequence after lifting the first contact:
16----- 88
89 ABS_MT_POSITION_X x[1]
90 ABS_MT_POSITION_Y y[1]
91 SYN_MT_REPORT
92 SYN_REPORT
93
94And here is the sequence after lifting the second contact:
95
96 SYN_MT_REPORT
97 SYN_REPORT
98
99If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the
100ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the
101last SYN_REPORT will be dropped by the input core, resulting in no
102zero-contact event reaching userland.
17 103
18Anonymous finger details are sent sequentially as separate packets of ABS 104
19events. Only the ABS_MT events are recognized as part of a finger 105Protocol Example B
20packet. The end of a packet is marked by calling the input_mt_sync() 106------------------
21function, which generates a SYN_MT_REPORT event. This instructs the 107
22receiver to accept the data for the current finger and prepare to receive 108Here is what a minimal event sequence for a two-contact touch would look
23another. The end of a multi-touch transfer is marked by calling the usual 109like for a type B device:
24input_sync() function. This instructs the receiver to act upon events 110
25accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new 111 ABS_MT_SLOT 0
26set of events/packets. 112 ABS_MT_TRACKING_ID 45
113 ABS_MT_POSITION_X x[0]
114 ABS_MT_POSITION_Y y[0]
115 ABS_MT_SLOT 1
116 ABS_MT_TRACKING_ID 46
117 ABS_MT_POSITION_X x[1]
118 ABS_MT_POSITION_Y y[1]
119 SYN_REPORT
120
121Here is the sequence after moving contact 45 in the x direction:
122
123 ABS_MT_SLOT 0
124 ABS_MT_POSITION_X x[0]
125 SYN_REPORT
126
127Here is the sequence after lifting the contact in slot 0:
128
129 ABS_MT_TRACKING_ID -1
130 SYN_REPORT
131
132The slot being modified is already 0, so the ABS_MT_SLOT is omitted. The
133message removes the association of slot 0 with contact 45, thereby
134destroying contact 45 and freeing slot 0 to be reused for another contact.
135
136Finally, here is the sequence after lifting the second contact:
137
138 ABS_MT_SLOT 1
139 ABS_MT_TRACKING_ID -1
140 SYN_REPORT
141
142
143Event Usage
144-----------
27 145
28A set of ABS_MT events with the desired properties is defined. The events 146A set of ABS_MT events with the desired properties is defined. The events
29are divided into categories, to allow for partial implementation. The 147are divided into categories, to allow for partial implementation. The
30minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which 148minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which
31allows for multiple fingers to be tracked. If the device supports it, the 149allows for multiple contacts to be tracked. If the device supports it, the
32ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size 150ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size
33of the contact area and approaching finger, respectively. 151of the contact area and approaching contact, respectively.
34 152
35The TOUCH and WIDTH parameters have a geometrical interpretation; imagine 153The TOUCH and WIDTH parameters have a geometrical interpretation; imagine
36looking through a window at someone gently holding a finger against the 154looking through a window at someone gently holding a finger against the
@@ -41,56 +159,26 @@ ABS_MT_TOUCH_MAJOR, the diameter of the outer region is
41ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder 159ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder
42against the glass. The inner region will increase, and in general, the 160against the glass. The inner region will increase, and in general, the
43ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than 161ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than
44unity, is related to the finger pressure. For pressure-based devices, 162unity, is related to the contact pressure. For pressure-based devices,
45ABS_MT_PRESSURE may be used to provide the pressure on the contact area 163ABS_MT_PRESSURE may be used to provide the pressure on the contact area
46instead. 164instead.
47 165
48In addition to the MAJOR parameters, the oval shape of the finger can be 166In addition to the MAJOR parameters, the oval shape of the contact can be
49described by adding the MINOR parameters, such that MAJOR and MINOR are the 167described by adding the MINOR parameters, such that MAJOR and MINOR are the
50major and minor axis of an ellipse. Finally, the orientation of the oval 168major and minor axis of an ellipse. Finally, the orientation of the oval
51shape can be describe with the ORIENTATION parameter. 169shape can be describe with the ORIENTATION parameter.
52 170
53The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a 171The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
54finger or a pen or something else. Devices with more granular information 172contact or a pen or something else. Devices with more granular information
55may specify general shapes as blobs, i.e., as a sequence of rectangular 173may specify general shapes as blobs, i.e., as a sequence of rectangular
56shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices 174shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices
57that currently support it, the ABS_MT_TRACKING_ID event may be used to 175that currently support it, the ABS_MT_TRACKING_ID event may be used to
58report finger tracking from hardware [5]. 176report contact tracking from hardware [5].
59 177
60Here is what a minimal event sequence for a two-finger touch would look
61like:
62
63 ABS_MT_POSITION_X
64 ABS_MT_POSITION_Y
65 SYN_MT_REPORT
66 ABS_MT_POSITION_X
67 ABS_MT_POSITION_Y
68 SYN_MT_REPORT
69 SYN_REPORT
70
71Here is the sequence after lifting one of the fingers:
72
73 ABS_MT_POSITION_X
74 ABS_MT_POSITION_Y
75 SYN_MT_REPORT
76 SYN_REPORT
77
78And here is the sequence after lifting the remaining finger:
79
80 SYN_MT_REPORT
81 SYN_REPORT
82
83If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the
84ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the
85last SYN_REPORT will be dropped by the input core, resulting in no
86zero-finger event reaching userland.
87 178
88Event Semantics 179Event Semantics
89--------------- 180---------------
90 181
91The word "contact" is used to describe a tool which is in direct contact
92with the surface. A finger, a pen or a rubber all classify as contacts.
93
94ABS_MT_TOUCH_MAJOR 182ABS_MT_TOUCH_MAJOR
95 183
96The length of the major axis of the contact. The length should be given in 184The length of the major axis of the contact. The length should be given in
@@ -157,15 +245,16 @@ MT_TOOL_PEN [2].
157ABS_MT_BLOB_ID 245ABS_MT_BLOB_ID
158 246
159The BLOB_ID groups several packets together into one arbitrarily shaped 247The BLOB_ID groups several packets together into one arbitrarily shaped
160contact. This is a low-level anonymous grouping, and should not be confused 248contact. This is a low-level anonymous grouping for type A devices, and
161with the high-level trackingID [5]. Most kernel drivers will not have blob 249should not be confused with the high-level trackingID [5]. Most type A
162capability, and can safely omit the event. 250devices do not have blob capability, so drivers can safely omit this event.
163 251
164ABS_MT_TRACKING_ID 252ABS_MT_TRACKING_ID
165 253
166The TRACKING_ID identifies an initiated contact throughout its life cycle 254The TRACKING_ID identifies an initiated contact throughout its life cycle
167[5]. There are currently only a few devices that support it, so this event 255[5]. This event is mandatory for type B devices. The value range of the
168should normally be omitted. 256TRACKING_ID should be large enough to ensure unique identification of a
257contact maintained over an extended period of time.
169 258
170 259
171Event Computation 260Event Computation
@@ -192,20 +281,11 @@ finger along the X axis (1).
192Finger Tracking 281Finger Tracking
193--------------- 282---------------
194 283
195The kernel driver should generate an arbitrary enumeration of the set of
196anonymous contacts currently on the surface. The order in which the packets
197appear in the event stream is not important.
198
199The process of finger tracking, i.e., to assign a unique trackingID to each 284The process of finger tracking, i.e., to assign a unique trackingID to each
200initiated contact on the surface, is left to user space; preferably the 285initiated contact on the surface, is a Euclidian Bipartite Matching
201multi-touch X driver [3]. In that driver, the trackingID stays the same and 286problem. At each event synchronization, the set of actual contacts is
202unique until the contact vanishes (when the finger leaves the surface). The 287matched to the set of contacts from the previous synchronization. A full
203problem of assigning a set of anonymous fingers to a set of identified 288implementation can be found in [3].
204fingers is a euclidian bipartite matching problem at each event update, and
205relies on a sufficiently rapid update rate.
206
207There are a few devices that support trackingID in hardware. User space can
208make use of these native identifiers to reduce bandwidth and cpu usage.
209 289
210 290
211Gestures 291Gestures
diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.txt
index b35affd5c649..b2ef125b71f8 100644
--- a/Documentation/input/sentelic.txt
+++ b/Documentation/input/sentelic.txt
@@ -341,7 +341,7 @@ Byte 5~8: Don't care (Absolute packet)
341FSP supports basic PS/2 commanding set and modes, refer to following URL for 341FSP supports basic PS/2 commanding set and modes, refer to following URL for
342details about PS/2 commands: 342details about PS/2 commands:
343 343
344http://www.computer-engineering.org/index.php?title=PS/2_Mouse_Interface 344http://www.computer-engineering.org/ps2mouse/
345 345
346============================================================================== 346==============================================================================
347* Programming Sequence for Determining Packet Parsing Flow 347* Programming Sequence for Determining Packet Parsing Flow
diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt
index aae0d404c566..7cc9a436e6a1 100644
--- a/Documentation/input/xpad.txt
+++ b/Documentation/input/xpad.txt
@@ -150,7 +150,7 @@ the basic functionality.
150 150
1511. http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki) 1511. http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
1522. http://xpad.xbox-scene.com/ 1522. http://xpad.xbox-scene.com/
1533. http://www.xboxhackz.com/Hackz-Reference.htm 1533. http://www.markosweb.com/www/xboxhackz.com/
154 154
1554. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany): 1554. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany):
156 156