blob: e544c7ff8cfa5c6c60697aae738eb4b029e86d23 [file] [log] [blame]
Seth Forsheed4b347b2011-11-07 19:53:15 -08001ALPS Touchpad Protocol
2----------------------
3
4Introduction
5------------
dave turvene171fb58d2013-02-23 20:06:34 -08006Currently the ALPS touchpad driver supports five protocol versions in use by
7ALPS touchpads, called versions 1, 2, 3, 4 and 5.
Seth Forsheed4b347b2011-11-07 19:53:15 -08008
dave turvene171fb58d2013-02-23 20:06:34 -08009Since roughly mid-2010 several new ALPS touchpads have been released and
10integrated into a variety of laptops and netbooks. These new touchpads
11have enough behavior differences that the alps_model_data definition
12table, describing the properties of the different versions, is no longer
13adequate. The design choices were to re-define the alps_model_data
14table, with the risk of regression testing existing devices, or isolate
15the new devices outside of the alps_model_data table. The latter design
16choice was made. The new touchpad signatures are named: "Rushmore",
17"Pinnacle", and "Dolphin", which you will see in the alps.c code.
18For the purposes of this document, this group of ALPS touchpads will
19generically be called "new ALPS touchpads".
20
21We experimented with probing the ACPI interface _HID (Hardware ID)/_CID
22(Compatibility ID) definition as a way to uniquely identify the
23different ALPS variants but there did not appear to be a 1:1 mapping.
24In fact, it appeared to be an m:n mapping between the _HID and actual
25hardware type.
Seth Forsheed4b347b2011-11-07 19:53:15 -080026
27Detection
28---------
29
30All ALPS touchpads should respond to the "E6 report" command sequence:
31E8-E6-E6-E6-E9. An ALPS touchpad should respond with either 00-00-0A or
Akio Idehara99c90ab2012-02-24 00:33:22 -08003200-00-64 if no buttons are pressed. The bits 0-2 of the first byte will be 1s
33if some buttons are pressed.
Seth Forsheed4b347b2011-11-07 19:53:15 -080034
35If the E6 report is successful, the touchpad model is identified using the "E7
36report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is
37matched against known models in the alps_model_data_array.
38
dave turvene171fb58d2013-02-23 20:06:34 -080039For older touchpads supporting protocol versions 3 and 4, the E7 report
40model signature is always 73-02-64. To differentiate between these
41versions, the response from the "Enter Command Mode" sequence must be
42inspected as described below.
43
44The new ALPS touchpads have an E7 signature of 73-03-50 or 73-03-0A but
45seem to be better differentiated by the EC Command Mode response.
Seth Forshee7cf801c2011-11-07 19:54:35 -080046
47Command Mode
48------------
49
50Protocol versions 3 and 4 have a command mode that is used to read and write
51one-byte device registers in a 16-bit address space. The command sequence
52EC-EC-EC-E9 places the device in command mode, and the device will respond
53with 88-07 followed by a third byte. This third byte can be used to determine
54whether the devices uses the version 3 or 4 protocol.
55
56To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad.
57
58While in command mode, register addresses can be set by first sending a
59specific command, either EC for v3 devices or F5 for v4 devices. Then the
60address is sent one nibble at a time, where each nibble is encoded as a
61command with optional data. This enoding differs slightly between the v3 and
62v4 protocols.
63
64Once an address has been set, the addressed register can be read by sending
65PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the
66address of the register being read, and the third contains the value of the
67register. Registers are written by writing the value one nibble at a time
68using the same encoding used for addresses.
69
dave turvene171fb58d2013-02-23 20:06:34 -080070For the new ALPS touchpads, the EC command is used to enter command
71mode. The response in the new ALPS touchpads is significantly different,
72and more important in determining the behavior. This code has been
73separated from the original alps_model_data table and put in the
74alps_identify function. For example, there seem to be two hardware init
75sequences for the "Dolphin" touchpads as determined by the second byte
76of the EC response.
77
Seth Forsheed4b347b2011-11-07 19:53:15 -080078Packet Format
79-------------
80
Seth Forshee7cf801c2011-11-07 19:54:35 -080081In the following tables, the following notation is used.
Seth Forsheed4b347b2011-11-07 19:53:15 -080082
83 CAPITALS = stick, miniscules = touchpad
84
85?'s can have different meanings on different models, such as wheel rotation,
86extra buttons, stick buttons on a dualpoint, etc.
87
88PS/2 packet format
89------------------
90
91 byte 0: 0 0 YSGN XSGN 1 M R L
92 byte 1: X7 X6 X5 X4 X3 X2 X1 X0
93 byte 2: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
94
95Note that the device never signals overflow condition.
96
Seth Forshee7cf801c2011-11-07 19:54:35 -080097ALPS Absolute Mode - Protocol Verion 1
98--------------------------------------
Seth Forsheed4b347b2011-11-07 19:53:15 -080099
100 byte 0: 1 0 0 0 1 x9 x8 x7
101 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
102 byte 2: 0 ? ? l r ? fin ges
103 byte 3: 0 ? ? ? ? y9 y8 y7
104 byte 4: 0 y6 y5 y4 y3 y2 y1 y0
105 byte 5: 0 z6 z5 z4 z3 z2 z1 z0
106
Seth Forshee7cf801c2011-11-07 19:54:35 -0800107ALPS Absolute Mode - Protocol Version 2
108---------------------------------------
Seth Forsheed4b347b2011-11-07 19:53:15 -0800109
110 byte 0: 1 ? ? ? 1 ? ? ?
111 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
112 byte 2: 0 x10 x9 x8 x7 ? fin ges
113 byte 3: 0 y9 y8 y7 1 M R L
114 byte 4: 0 y6 y5 y4 y3 y2 y1 y0
115 byte 5: 0 z6 z5 z4 z3 z2 z1 z0
116
117Dualpoint device -- interleaved packet format
118---------------------------------------------
119
120 byte 0: 1 1 0 0 1 1 1 1
121 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
122 byte 2: 0 x10 x9 x8 x7 0 fin ges
123 byte 3: 0 0 YSGN XSGN 1 1 1 1
124 byte 4: X7 X6 X5 X4 X3 X2 X1 X0
125 byte 5: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
126 byte 6: 0 y9 y8 y7 1 m r l
127 byte 7: 0 y6 y5 y4 y3 y2 y1 y0
128 byte 8: 0 z6 z5 z4 z3 z2 z1 z0
Seth Forshee7cf801c2011-11-07 19:54:35 -0800129
130ALPS Absolute Mode - Protocol Version 3
131---------------------------------------
132
133ALPS protocol version 3 has three different packet formats. The first two are
134associated with touchpad events, and the third is associatd with trackstick
135events.
136
137The first type is the touchpad position packet.
138
139 byte 0: 1 ? x1 x0 1 1 1 1
140 byte 1: 0 x10 x9 x8 x7 x6 x5 x4
141 byte 2: 0 y10 y9 y8 y7 y6 y5 y4
142 byte 3: 0 M R L 1 m r l
143 byte 4: 0 mt x3 x2 y3 y2 y1 y0
144 byte 5: 0 z6 z5 z4 z3 z2 z1 z0
145
146Note that for some devices the trackstick buttons are reported in this packet,
147and on others it is reported in the trackstick packets.
148
149The second packet type contains bitmaps representing the x and y axes. In the
150bitmaps a given bit is set if there is a finger covering that position on the
151given axis. Thus the bitmap packet can be used for low-resolution multi-touch
152data, although finger tracking is not possible. This packet also encodes the
153number of contacts (f1 and f0 in the table below).
154
155 byte 0: 1 1 x1 x0 1 1 1 1
156 byte 1: 0 x8 x7 x6 x5 x4 x3 x2
157 byte 2: 0 y7 y6 y5 y4 y3 y2 y1
158 byte 3: 0 y10 y9 y8 1 1 1 1
159 byte 4: 0 x14 x13 x12 x11 x10 x9 y0
160 byte 5: 0 1 ? ? ? ? f1 f0
161
162This packet only appears after a position packet with the mt bit set, and
Masanari Iida40e47122012-03-04 23:16:11 +0900163usually only appears when there are two or more contacts (although
Masanari Iida4e79162a2012-11-08 21:57:35 +0900164occasionally it's seen with only a single contact).
Seth Forshee7cf801c2011-11-07 19:54:35 -0800165
166The final v3 packet type is the trackstick packet.
167
168 byte 0: 1 1 x7 y7 1 1 1 1
169 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
170 byte 2: 0 y6 y5 y4 y3 y2 y1 y0
171 byte 3: 0 1 0 0 1 0 0 0
172 byte 4: 0 z4 z3 z2 z1 z0 ? ?
173 byte 5: 0 0 1 1 1 1 1 1
174
175ALPS Absolute Mode - Protocol Version 4
176---------------------------------------
177
178Protocol version 4 has an 8-byte packet format.
179
180 byte 0: 1 ? x1 x0 1 1 1 1
181 byte 1: 0 x10 x9 x8 x7 x6 x5 x4
182 byte 2: 0 y10 y9 y8 y7 y6 y5 y4
183 byte 3: 0 1 x3 x2 y3 y2 y1 y0
184 byte 4: 0 ? ? ? 1 ? r l
185 byte 5: 0 z6 z5 z4 z3 z2 z1 z0
186 byte 6: bitmap data (described below)
187 byte 7: bitmap data (described below)
188
189The last two bytes represent a partial bitmap packet, with 3 full packets
190required to construct a complete bitmap packet. Once assembled, the 6-byte
191bitmap packet has the following format:
192
193 byte 0: 0 1 x7 x6 x5 x4 x3 x2
194 byte 1: 0 x1 x0 y4 y3 y2 y1 y0
195 byte 2: 0 0 ? x14 x13 x12 x11 x10
196 byte 3: 0 x9 x8 y9 y8 y7 y6 y5
197 byte 4: 0 0 0 0 0 0 0 0
198 byte 5: 0 0 0 0 0 0 0 y10
199
200There are several things worth noting here.
201
202 1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
203 identify the first fragment of a bitmap packet.
204
205 2) The bitmaps represent the same data as in the v3 bitmap packets, although
206 the packet layout is different.
207
208 3) There doesn't seem to be a count of the contact points anywhere in the v4
209 protocol packets. Deriving a count of contact points must be done by
210 analyzing the bitmaps.
211
212 4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
213 MT position can only be updated for every third ST position update, and
214 the count of contact points can only be updated every third packet as
215 well.
216
217So far no v4 devices with tracksticks have been encountered.
dave turvene171fb58d2013-02-23 20:06:34 -0800218
219ALPS Absolute Mode - Protocol Version 5
220---------------------------------------
221This is basically Protocol Version 3 but with different logic for packet
222decode. It uses the same alps_process_touchpad_packet_v3 call with a
223specialized decode_fields function pointer to correctly interpret the
224packets. This appears to only be used by the Dolphin devices.
225
226For single-touch, the 6-byte packet format is:
227
228 byte 0: 1 1 0 0 1 0 0 0
229 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
230 byte 2: 0 y6 y5 y4 y3 y2 y1 y0
231 byte 3: 0 M R L 1 m r l
232 byte 4: y10 y9 y8 y7 x10 x9 x8 x7
233 byte 5: 0 z6 z5 z4 z3 z2 z1 z0
234
235For mt, the format is:
236
237 byte 0: 1 1 1 n3 1 n2 n1 x24
238 byte 1: 1 y7 y6 y5 y4 y3 y2 y1
239 byte 2: ? x2 x1 y12 y11 y10 y9 y8
240 byte 3: 0 x23 x22 x21 x20 x19 x18 x17
241 byte 4: 0 x9 x8 x7 x6 x5 x4 x3
242 byte 5: 0 x16 x15 x14 x13 x12 x11 x10