aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/input
diff options
context:
space:
mode:
authorDmitry Torokhov <dmitry.torokhov@gmail.com>2009-05-08 21:29:27 -0400
committerDmitry Torokhov <dmitry.torokhov@gmail.com>2009-05-08 21:29:27 -0400
commitd585a021c0b10b0477d6b608c53e1feb8cde0507 (patch)
tree5ca059da1db7f15d4b29427644ad9c08270c885c /Documentation/input
parent84e5b0d00f8f84c4ae226be131d4bebbcee88bd3 (diff)
parent091bf7624d1c90cec9e578a18529f615213ff847 (diff)
Merge commit 'v2.6.30-rc5' into next
Diffstat (limited to 'Documentation/input')
-rw-r--r--Documentation/input/bcm5974.txt65
-rw-r--r--Documentation/input/multi-touch-protocol.txt140
2 files changed, 205 insertions, 0 deletions
diff --git a/Documentation/input/bcm5974.txt b/Documentation/input/bcm5974.txt
new file mode 100644
index 000000000000..5e22dcf6d48d
--- /dev/null
+++ b/Documentation/input/bcm5974.txt
@@ -0,0 +1,65 @@
1BCM5974 Driver (bcm5974)
2------------------------
3 Copyright (C) 2008-2009 Henrik Rydberg <rydberg@euromail.se>
4
5The USB initialization and package decoding was made by Scott Shawcroft as
6part of the touchd user-space driver project:
7 Copyright (C) 2008 Scott Shawcroft (scott.shawcroft@gmail.com)
8
9The BCM5974 driver is based on the appletouch driver:
10 Copyright (C) 2001-2004 Greg Kroah-Hartman (greg@kroah.com)
11 Copyright (C) 2005 Johannes Berg (johannes@sipsolutions.net)
12 Copyright (C) 2005 Stelian Pop (stelian@popies.net)
13 Copyright (C) 2005 Frank Arnold (frank@scirocco-5v-turbo.de)
14 Copyright (C) 2005 Peter Osterlund (petero2@telia.com)
15 Copyright (C) 2005 Michael Hanselmann (linux-kernel@hansmi.ch)
16 Copyright (C) 2006 Nicolas Boichat (nicolas@boichat.ch)
17
18This driver adds support for the multi-touch trackpad on the new Apple
19Macbook Air and Macbook Pro laptops. It replaces the appletouch driver on
20those computers, and integrates well with the synaptics driver of the Xorg
21system.
22
23Known to work on Macbook Air, Macbook Pro Penryn and the new unibody
24Macbook 5 and Macbook Pro 5.
25
26Usage
27-----
28
29The driver loads automatically for the supported usb device ids, and
30becomes available both as an event device (/dev/input/event*) and as a
31mouse via the mousedev driver (/dev/input/mice).
32
33USB Race
34--------
35
36The Apple multi-touch trackpads report both mouse and keyboard events via
37different interfaces of the same usb device. This creates a race condition
38with the HID driver, which, if not told otherwise, will find the standard
39HID mouse and keyboard, and claim the whole device. To remedy, the usb
40product id must be listed in the mouse_ignore list of the hid driver.
41
42Debug output
43------------
44
45To ease the development for new hardware version, verbose packet output can
46be switched on with the debug kernel module parameter. The range [1-9]
47yields different levels of verbosity. Example (as root):
48
49echo -n 9 > /sys/module/bcm5974/parameters/debug
50
51tail -f /var/log/debug
52
53echo -n 0 > /sys/module/bcm5974/parameters/debug
54
55Trivia
56------
57
58The driver was developed at the ubuntu forums in June 2008 [1], and now has
59a more permanent home at bitmath.org [2].
60
61Links
62-----
63
64[1] http://ubuntuforums.org/showthread.php?t=840040
65[2] http://http://bitmath.org/code/
diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt
new file mode 100644
index 000000000000..9f09557aea39
--- /dev/null
+++ b/Documentation/input/multi-touch-protocol.txt
@@ -0,0 +1,140 @@
1Multi-touch (MT) Protocol
2-------------------------
3 Copyright (C) 2009 Henrik Rydberg <rydberg@euromail.se>
4
5
6Introduction
7------------
8
9In order to utilize the full power of the new multi-touch devices, a way to
10report detailed finger data to user space is needed. This document
11describes the multi-touch (MT) protocol which allows kernel drivers to
12report details for an arbitrary number of fingers.
13
14
15Usage
16-----
17
18Anonymous finger details are sent sequentially as separate packets of ABS
19events. Only the ABS_MT events are recognized as part of a finger
20packet. The end of a packet is marked by calling the input_mt_sync()
21function, which generates a SYN_MT_REPORT event. The end of multi-touch
22transfer is marked by calling the usual input_sync() function.
23
24A set of ABS_MT events with the desired properties is defined. The events
25are divided into categories, to allow for partial implementation. The
26minimum set consists of ABS_MT_TOUCH_MAJOR, ABS_MT_POSITION_X and
27ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked. If the
28device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size
29of the approaching finger. Anisotropy and direction may be specified with
30ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. Devices with
31more granular information may specify general shapes as blobs, i.e., as a
32sequence of rectangular shapes grouped together by an
33ABS_MT_BLOB_ID. Finally, the ABS_MT_TOOL_TYPE may be used to specify
34whether the touching tool is a finger or a pen or something else.
35
36
37Event Semantics
38---------------
39
40The word "contact" is used to describe a tool which is in direct contact
41with the surface. A finger, a pen or a rubber all classify as contacts.
42
43ABS_MT_TOUCH_MAJOR
44
45The length of the major axis of the contact. The length should be given in
46surface units. If the surface has an X times Y resolution, the largest
47possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal.
48
49ABS_MT_TOUCH_MINOR
50
51The length, in surface units, of the minor axis of the contact. If the
52contact is circular, this event can be omitted.
53
54ABS_MT_WIDTH_MAJOR
55
56The length, in surface units, of the major axis of the approaching
57tool. This should be understood as the size of the tool itself. The
58orientation of the contact and the approaching tool are assumed to be the
59same.
60
61ABS_MT_WIDTH_MINOR
62
63The length, in surface units, of the minor axis of the approaching
64tool. Omit if circular.
65
66The above four values can be used to derive additional information about
67the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
68the notion of pressure. The fingers of the hand and the palm all have
69different characteristic widths [1].
70
71ABS_MT_ORIENTATION
72
73The orientation of the ellipse. The value should describe half a revolution
74clockwise around the touch center. The scale of the value is arbitrary, but
75zero should be returned for an ellipse aligned along the Y axis of the
76surface. As an example, an index finger placed straight onto the axis could
77return zero orientation, something negative when twisted to the left, and
78something positive when twisted to the right. This value can be omitted if
79the touching object is circular, or if the information is not available in
80the kernel driver.
81
82ABS_MT_POSITION_X
83
84The surface X coordinate of the center of the touching ellipse.
85
86ABS_MT_POSITION_Y
87
88The surface Y coordinate of the center of the touching ellipse.
89
90ABS_MT_TOOL_TYPE
91
92The type of approaching tool. A lot of kernel drivers cannot distinguish
93between different tool types, such as a finger or a pen. In such cases, the
94event should be omitted. The protocol currently supports MT_TOOL_FINGER and
95MT_TOOL_PEN [2].
96
97ABS_MT_BLOB_ID
98
99The BLOB_ID groups several packets together into one arbitrarily shaped
100contact. This is a low-level anonymous grouping, and should not be confused
101with the high-level contactID, explained below. Most kernel drivers will
102not have this capability, and can safely omit the event.
103
104
105Finger Tracking
106---------------
107
108The kernel driver should generate an arbitrary enumeration of the set of
109anonymous contacts currently on the surface. The order in which the packets
110appear in the event stream is not important.
111
112The process of finger tracking, i.e., to assign a unique contactID to each
113initiated contact on the surface, is left to user space; preferably the
114multi-touch X driver [3]. In that driver, the contactID stays the same and
115unique until the contact vanishes (when the finger leaves the surface). The
116problem of assigning a set of anonymous fingers to a set of identified
117fingers is a euclidian bipartite matching problem at each event update, and
118relies on a sufficiently rapid update rate.
119
120Notes
121-----
122
123In order to stay compatible with existing applications, the data
124reported in a finger packet must not be recognized as single-touch
125events. In addition, all finger data must bypass input filtering,
126since subsequent events of the same type refer to different fingers.
127
128The first kernel driver to utilize the MT protocol is the bcm5974 driver,
129where examples can be found.
130
131[1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the
132difference between the contact position and the approaching tool position
133could be used to derive tilt.
134[2] The list can of course be extended.
135[3] The multi-touch X driver is currently in the prototyping stage. At the
136time of writing (April 2009), the MT protocol is not yet merged, and the
137prototype implements finger matching, basic mouse support and two-finger
138scrolling. The project aims at improving the quality of current multi-touch
139functionality available in the synaptics X driver, and in addition
140implement more advanced gestures.