tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Input: ALPS - add documentation for protocol versions 3 and 4
Also converts from using "old" and "new" to describe the already-known
protocols to using "version 1" and "version 2" to match the code.
Signed-off-by: Seth Forshee <seth.forshee@canonical.com>
Acked-by: Chase Douglas <chase.douglas@canonical.com>
Signed-off-by: Dmitry Torokhov <dtor@mail.ru>
authored by
Seth Forshee
and committed by
Dmitry Torokhov
7cf801cf
01ce661f
+124
-11
+124
-11
Documentation/input/alps.txt
+124
-11
Documentation/input/alps.txt
···
4
4
Introduction
5
5
------------
6
6
7
-
Currently the ALPS touchpad driver supports two protocol versions in use by
8
-
ALPS touchpads, the "old" and "new" protocol versions. Fundamentally these
9
-
differ only in the format of their event packets (in reality many features may
10
-
be found on new protocol devices that aren't found on the old protocol
11
-
devices, but these are handled transparently as feature differences rather
12
-
than protocol differences).
7
+
Currently the ALPS touchpad driver supports four protocol versions in use by
8
+
ALPS touchpads, called versions 1, 2, 3, and 4. Information about the various
9
+
protocol versions is contained in the following sections.
13
10
14
11
Detection
15
12
---------
···
19
22
report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is
20
23
matched against known models in the alps_model_data_array.
21
24
25
+
With protocol versions 3 and 4, the E7 report model signature is always
26
+
73-02-64. To differentiate between these versions, the response from the
27
+
"Enter Command Mode" sequence must be inspected as described below.
28
+
29
+
Command Mode
30
+
------------
31
+
32
+
Protocol versions 3 and 4 have a command mode that is used to read and write
33
+
one-byte device registers in a 16-bit address space. The command sequence
34
+
EC-EC-EC-E9 places the device in command mode, and the device will respond
35
+
with 88-07 followed by a third byte. This third byte can be used to determine
36
+
whether the devices uses the version 3 or 4 protocol.
37
+
38
+
To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad.
39
+
40
+
While in command mode, register addresses can be set by first sending a
41
+
specific command, either EC for v3 devices or F5 for v4 devices. Then the
42
+
address is sent one nibble at a time, where each nibble is encoded as a
43
+
command with optional data. This enoding differs slightly between the v3 and
44
+
v4 protocols.
45
+
46
+
Once an address has been set, the addressed register can be read by sending
47
+
PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the
48
+
address of the register being read, and the third contains the value of the
49
+
register. Registers are written by writing the value one nibble at a time
50
+
using the same encoding used for addresses.
51
+
22
52
Packet Format
23
53
-------------
24
54
25
-
In the following tables, the following notation us used.
55
+
In the following tables, the following notation is used.
26
56
27
57
CAPITALS = stick, miniscules = touchpad
28
58
···
65
41
66
42
Note that the device never signals overflow condition.
67
43
68
-
ALPS Absolute Mode - Old Format
69
-
-------------------------------
44
+
ALPS Absolute Mode - Protocol Verion 1
45
+
--------------------------------------
70
46
71
47
byte 0: 1 0 0 0 1 x9 x8 x7
72
48
byte 1: 0 x6 x5 x4 x3 x2 x1 x0
···
75
51
byte 4: 0 y6 y5 y4 y3 y2 y1 y0
76
52
byte 5: 0 z6 z5 z4 z3 z2 z1 z0
77
53
78
-
ALPS Absolute Mode - New Format
79
-
-------------------------------
54
+
ALPS Absolute Mode - Protocol Version 2
55
+
---------------------------------------
80
56
81
57
byte 0: 1 ? ? ? 1 ? ? ?
82
58
byte 1: 0 x6 x5 x4 x3 x2 x1 x0
···
97
73
byte 6: 0 y9 y8 y7 1 m r l
98
74
byte 7: 0 y6 y5 y4 y3 y2 y1 y0
99
75
byte 8: 0 z6 z5 z4 z3 z2 z1 z0
76
+
77
+
ALPS Absolute Mode - Protocol Version 3
78
+
---------------------------------------
79
+
80
+
ALPS protocol version 3 has three different packet formats. The first two are
81
+
associated with touchpad events, and the third is associatd with trackstick
82
+
events.
83
+
84
+
The first type is the touchpad position packet.
85
+
86
+
byte 0: 1 ? x1 x0 1 1 1 1
87
+
byte 1: 0 x10 x9 x8 x7 x6 x5 x4
88
+
byte 2: 0 y10 y9 y8 y7 y6 y5 y4
89
+
byte 3: 0 M R L 1 m r l
90
+
byte 4: 0 mt x3 x2 y3 y2 y1 y0
91
+
byte 5: 0 z6 z5 z4 z3 z2 z1 z0
92
+
93
+
Note that for some devices the trackstick buttons are reported in this packet,
94
+
and on others it is reported in the trackstick packets.
95
+
96
+
The second packet type contains bitmaps representing the x and y axes. In the
97
+
bitmaps a given bit is set if there is a finger covering that position on the
98
+
given axis. Thus the bitmap packet can be used for low-resolution multi-touch
99
+
data, although finger tracking is not possible. This packet also encodes the
100
+
number of contacts (f1 and f0 in the table below).
101
+
102
+
byte 0: 1 1 x1 x0 1 1 1 1
103
+
byte 1: 0 x8 x7 x6 x5 x4 x3 x2
104
+
byte 2: 0 y7 y6 y5 y4 y3 y2 y1
105
+
byte 3: 0 y10 y9 y8 1 1 1 1
106
+
byte 4: 0 x14 x13 x12 x11 x10 x9 y0
107
+
byte 5: 0 1 ? ? ? ? f1 f0
108
+
109
+
This packet only appears after a position packet with the mt bit set, and
110
+
ususally only appears when there are two or more contacts (although
111
+
ocassionally it's seen with only a single contact).
112
+
113
+
The final v3 packet type is the trackstick packet.
114
+
115
+
byte 0: 1 1 x7 y7 1 1 1 1
116
+
byte 1: 0 x6 x5 x4 x3 x2 x1 x0
117
+
byte 2: 0 y6 y5 y4 y3 y2 y1 y0
118
+
byte 3: 0 1 0 0 1 0 0 0
119
+
byte 4: 0 z4 z3 z2 z1 z0 ? ?
120
+
byte 5: 0 0 1 1 1 1 1 1
121
+
122
+
ALPS Absolute Mode - Protocol Version 4
123
+
---------------------------------------
124
+
125
+
Protocol version 4 has an 8-byte packet format.
126
+
127
+
byte 0: 1 ? x1 x0 1 1 1 1
128
+
byte 1: 0 x10 x9 x8 x7 x6 x5 x4
129
+
byte 2: 0 y10 y9 y8 y7 y6 y5 y4
130
+
byte 3: 0 1 x3 x2 y3 y2 y1 y0
131
+
byte 4: 0 ? ? ? 1 ? r l
132
+
byte 5: 0 z6 z5 z4 z3 z2 z1 z0
133
+
byte 6: bitmap data (described below)
134
+
byte 7: bitmap data (described below)
135
+
136
+
The last two bytes represent a partial bitmap packet, with 3 full packets
137
+
required to construct a complete bitmap packet. Once assembled, the 6-byte
138
+
bitmap packet has the following format:
139
+
140
+
byte 0: 0 1 x7 x6 x5 x4 x3 x2
141
+
byte 1: 0 x1 x0 y4 y3 y2 y1 y0
142
+
byte 2: 0 0 ? x14 x13 x12 x11 x10
143
+
byte 3: 0 x9 x8 y9 y8 y7 y6 y5
144
+
byte 4: 0 0 0 0 0 0 0 0
145
+
byte 5: 0 0 0 0 0 0 0 y10
146
+
147
+
There are several things worth noting here.
148
+
149
+
1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
150
+
identify the first fragment of a bitmap packet.
151
+
152
+
2) The bitmaps represent the same data as in the v3 bitmap packets, although
153
+
the packet layout is different.
154
+
155
+
3) There doesn't seem to be a count of the contact points anywhere in the v4
156
+
protocol packets. Deriving a count of contact points must be done by
157
+
analyzing the bitmaps.
158
+
159
+
4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
160
+
MT position can only be updated for every third ST position update, and
161
+
the count of contact points can only be updated every third packet as
162
+
well.
163
+
164
+
So far no v4 devices with tracksticks have been encountered.