Commit | Line | Data |
---|---|---|
d4b347b2 SF |
1 | ALPS Touchpad Protocol |
2 | ---------------------- | |
3 | ||
4 | Introduction | |
5 | ------------ | |
ef47fa52 PR |
6 | Currently the ALPS touchpad driver supports seven protocol versions in use by |
7 | ALPS touchpads, called versions 1, 2, 3, 4, 5, 6 and 7. | |
171fb58d | 8 | |
9 | Since roughly mid-2010 several new ALPS touchpads have been released and | |
10 | integrated into a variety of laptops and netbooks. These new touchpads | |
11 | have enough behavior differences that the alps_model_data definition | |
12 | table, describing the properties of the different versions, is no longer | |
13 | adequate. The design choices were to re-define the alps_model_data | |
14 | table, with the risk of regression testing existing devices, or isolate | |
15 | the new devices outside of the alps_model_data table. The latter design | |
16 | choice was made. The new touchpad signatures are named: "Rushmore", | |
17 | "Pinnacle", and "Dolphin", which you will see in the alps.c code. | |
18 | For the purposes of this document, this group of ALPS touchpads will | |
19 | generically be called "new ALPS touchpads". | |
20 | ||
21 | We experimented with probing the ACPI interface _HID (Hardware ID)/_CID | |
22 | (Compatibility ID) definition as a way to uniquely identify the | |
23 | different ALPS variants but there did not appear to be a 1:1 mapping. | |
24 | In fact, it appeared to be an m:n mapping between the _HID and actual | |
25 | hardware type. | |
d4b347b2 SF |
26 | |
27 | Detection | |
28 | --------- | |
29 | ||
30 | All ALPS touchpads should respond to the "E6 report" command sequence: | |
31 | E8-E6-E6-E6-E9. An ALPS touchpad should respond with either 00-00-0A or | |
99c90ab3 AI |
32 | 00-00-64 if no buttons are pressed. The bits 0-2 of the first byte will be 1s |
33 | if some buttons are pressed. | |
d4b347b2 SF |
34 | |
35 | If the E6 report is successful, the touchpad model is identified using the "E7 | |
36 | report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is | |
37 | matched against known models in the alps_model_data_array. | |
38 | ||
171fb58d | 39 | For older touchpads supporting protocol versions 3 and 4, the E7 report |
40 | model signature is always 73-02-64. To differentiate between these | |
41 | versions, the response from the "Enter Command Mode" sequence must be | |
42 | inspected as described below. | |
43 | ||
44 | The new ALPS touchpads have an E7 signature of 73-03-50 or 73-03-0A but | |
45 | seem to be better differentiated by the EC Command Mode response. | |
7cf801cf SF |
46 | |
47 | Command Mode | |
48 | ------------ | |
49 | ||
50 | Protocol versions 3 and 4 have a command mode that is used to read and write | |
51 | one-byte device registers in a 16-bit address space. The command sequence | |
52 | EC-EC-EC-E9 places the device in command mode, and the device will respond | |
53 | with 88-07 followed by a third byte. This third byte can be used to determine | |
54 | whether the devices uses the version 3 or 4 protocol. | |
55 | ||
56 | To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad. | |
57 | ||
58 | While in command mode, register addresses can be set by first sending a | |
59 | specific command, either EC for v3 devices or F5 for v4 devices. Then the | |
60 | address is sent one nibble at a time, where each nibble is encoded as a | |
ad4a6ebe | 61 | command with optional data. This encoding differs slightly between the v3 and |
7cf801cf SF |
62 | v4 protocols. |
63 | ||
64 | Once an address has been set, the addressed register can be read by sending | |
65 | PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the | |
66 | address of the register being read, and the third contains the value of the | |
67 | register. Registers are written by writing the value one nibble at a time | |
68 | using the same encoding used for addresses. | |
69 | ||
171fb58d | 70 | For the new ALPS touchpads, the EC command is used to enter command |
71 | mode. The response in the new ALPS touchpads is significantly different, | |
72 | and more important in determining the behavior. This code has been | |
73 | separated from the original alps_model_data table and put in the | |
74 | alps_identify function. For example, there seem to be two hardware init | |
75 | sequences for the "Dolphin" touchpads as determined by the second byte | |
76 | of the EC response. | |
77 | ||
d4b347b2 SF |
78 | Packet Format |
79 | ------------- | |
80 | ||
7cf801cf | 81 | In the following tables, the following notation is used. |
d4b347b2 SF |
82 | |
83 | CAPITALS = stick, miniscules = touchpad | |
84 | ||
85 | ?'s can have different meanings on different models, such as wheel rotation, | |
86 | extra buttons, stick buttons on a dualpoint, etc. | |
87 | ||
88 | PS/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 | ||
95 | Note that the device never signals overflow condition. | |
96 | ||
2310568f HG |
97 | For protocol version 2 devices when the trackpoint is used, and no fingers |
98 | are on the touchpad, the M R L bits signal the combined status of both the | |
99 | pointingstick and touchpad buttons. | |
100 | ||
c98be0c9 | 101 | ALPS Absolute Mode - Protocol Version 1 |
7cf801cf | 102 | -------------------------------------- |
d4b347b2 SF |
103 | |
104 | byte 0: 1 0 0 0 1 x9 x8 x7 | |
105 | byte 1: 0 x6 x5 x4 x3 x2 x1 x0 | |
106 | byte 2: 0 ? ? l r ? fin ges | |
107 | byte 3: 0 ? ? ? ? y9 y8 y7 | |
108 | byte 4: 0 y6 y5 y4 y3 y2 y1 y0 | |
109 | byte 5: 0 z6 z5 z4 z3 z2 z1 z0 | |
110 | ||
7cf801cf SF |
111 | ALPS Absolute Mode - Protocol Version 2 |
112 | --------------------------------------- | |
d4b347b2 | 113 | |
2310568f | 114 | byte 0: 1 ? ? ? 1 PSM PSR PSL |
d4b347b2 SF |
115 | byte 1: 0 x6 x5 x4 x3 x2 x1 x0 |
116 | byte 2: 0 x10 x9 x8 x7 ? fin ges | |
117 | byte 3: 0 y9 y8 y7 1 M R L | |
118 | byte 4: 0 y6 y5 y4 y3 y2 y1 y0 | |
119 | byte 5: 0 z6 z5 z4 z3 z2 z1 z0 | |
120 | ||
58d8a3be | 121 | Protocol Version 2 DualPoint devices send standard PS/2 mouse packets for |
073e570d HG |
122 | the DualPoint Stick. The M, R and L bits signal the combined status of both |
123 | the pointingstick and touchpad buttons, except for Dell dualpoint devices | |
124 | where the pointingstick buttons get reported separately in the PSM, PSR | |
125 | and PSL bits. | |
58d8a3be | 126 | |
d4b347b2 SF |
127 | Dualpoint device -- interleaved packet format |
128 | --------------------------------------------- | |
129 | ||
130 | byte 0: 1 1 0 0 1 1 1 1 | |
131 | byte 1: 0 x6 x5 x4 x3 x2 x1 x0 | |
132 | byte 2: 0 x10 x9 x8 x7 0 fin ges | |
133 | byte 3: 0 0 YSGN XSGN 1 1 1 1 | |
134 | byte 4: X7 X6 X5 X4 X3 X2 X1 X0 | |
135 | byte 5: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 | |
136 | byte 6: 0 y9 y8 y7 1 m r l | |
137 | byte 7: 0 y6 y5 y4 y3 y2 y1 y0 | |
138 | byte 8: 0 z6 z5 z4 z3 z2 z1 z0 | |
7cf801cf | 139 | |
58d8a3be HG |
140 | Devices which use the interleaving format normally send standard PS/2 mouse |
141 | packets for the DualPoint Stick + ALPS Absolute Mode packets for the | |
142 | touchpad, switching to the interleaved packet format when both the stick and | |
143 | the touchpad are used at the same time. | |
144 | ||
7cf801cf SF |
145 | ALPS Absolute Mode - Protocol Version 3 |
146 | --------------------------------------- | |
147 | ||
148 | ALPS protocol version 3 has three different packet formats. The first two are | |
ad4a6ebe | 149 | associated with touchpad events, and the third is associated with trackstick |
7cf801cf SF |
150 | events. |
151 | ||
152 | The first type is the touchpad position packet. | |
153 | ||
154 | byte 0: 1 ? x1 x0 1 1 1 1 | |
155 | byte 1: 0 x10 x9 x8 x7 x6 x5 x4 | |
156 | byte 2: 0 y10 y9 y8 y7 y6 y5 y4 | |
157 | byte 3: 0 M R L 1 m r l | |
158 | byte 4: 0 mt x3 x2 y3 y2 y1 y0 | |
159 | byte 5: 0 z6 z5 z4 z3 z2 z1 z0 | |
160 | ||
161 | Note that for some devices the trackstick buttons are reported in this packet, | |
162 | and on others it is reported in the trackstick packets. | |
163 | ||
164 | The second packet type contains bitmaps representing the x and y axes. In the | |
165 | bitmaps a given bit is set if there is a finger covering that position on the | |
166 | given axis. Thus the bitmap packet can be used for low-resolution multi-touch | |
167 | data, although finger tracking is not possible. This packet also encodes the | |
168 | number of contacts (f1 and f0 in the table below). | |
169 | ||
170 | byte 0: 1 1 x1 x0 1 1 1 1 | |
171 | byte 1: 0 x8 x7 x6 x5 x4 x3 x2 | |
172 | byte 2: 0 y7 y6 y5 y4 y3 y2 y1 | |
173 | byte 3: 0 y10 y9 y8 1 1 1 1 | |
174 | byte 4: 0 x14 x13 x12 x11 x10 x9 y0 | |
175 | byte 5: 0 1 ? ? ? ? f1 f0 | |
176 | ||
177 | This packet only appears after a position packet with the mt bit set, and | |
40e47125 | 178 | usually only appears when there are two or more contacts (although |
4e79162a | 179 | occasionally it's seen with only a single contact). |
7cf801cf SF |
180 | |
181 | The final v3 packet type is the trackstick packet. | |
182 | ||
183 | byte 0: 1 1 x7 y7 1 1 1 1 | |
184 | byte 1: 0 x6 x5 x4 x3 x2 x1 x0 | |
185 | byte 2: 0 y6 y5 y4 y3 y2 y1 y0 | |
186 | byte 3: 0 1 0 0 1 0 0 0 | |
187 | byte 4: 0 z4 z3 z2 z1 z0 ? ? | |
188 | byte 5: 0 0 1 1 1 1 1 1 | |
189 | ||
190 | ALPS Absolute Mode - Protocol Version 4 | |
191 | --------------------------------------- | |
192 | ||
193 | Protocol version 4 has an 8-byte packet format. | |
194 | ||
195 | byte 0: 1 ? x1 x0 1 1 1 1 | |
196 | byte 1: 0 x10 x9 x8 x7 x6 x5 x4 | |
197 | byte 2: 0 y10 y9 y8 y7 y6 y5 y4 | |
198 | byte 3: 0 1 x3 x2 y3 y2 y1 y0 | |
199 | byte 4: 0 ? ? ? 1 ? r l | |
200 | byte 5: 0 z6 z5 z4 z3 z2 z1 z0 | |
201 | byte 6: bitmap data (described below) | |
202 | byte 7: bitmap data (described below) | |
203 | ||
204 | The last two bytes represent a partial bitmap packet, with 3 full packets | |
205 | required to construct a complete bitmap packet. Once assembled, the 6-byte | |
206 | bitmap packet has the following format: | |
207 | ||
208 | byte 0: 0 1 x7 x6 x5 x4 x3 x2 | |
209 | byte 1: 0 x1 x0 y4 y3 y2 y1 y0 | |
210 | byte 2: 0 0 ? x14 x13 x12 x11 x10 | |
211 | byte 3: 0 x9 x8 y9 y8 y7 y6 y5 | |
212 | byte 4: 0 0 0 0 0 0 0 0 | |
213 | byte 5: 0 0 0 0 0 0 0 y10 | |
214 | ||
215 | There are several things worth noting here. | |
216 | ||
217 | 1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to | |
218 | identify the first fragment of a bitmap packet. | |
219 | ||
220 | 2) The bitmaps represent the same data as in the v3 bitmap packets, although | |
221 | the packet layout is different. | |
222 | ||
223 | 3) There doesn't seem to be a count of the contact points anywhere in the v4 | |
224 | protocol packets. Deriving a count of contact points must be done by | |
225 | analyzing the bitmaps. | |
226 | ||
227 | 4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore | |
228 | MT position can only be updated for every third ST position update, and | |
229 | the count of contact points can only be updated every third packet as | |
230 | well. | |
231 | ||
232 | So far no v4 devices with tracksticks have been encountered. | |
171fb58d | 233 | |
234 | ALPS Absolute Mode - Protocol Version 5 | |
235 | --------------------------------------- | |
236 | This is basically Protocol Version 3 but with different logic for packet | |
237 | decode. It uses the same alps_process_touchpad_packet_v3 call with a | |
238 | specialized decode_fields function pointer to correctly interpret the | |
239 | packets. This appears to only be used by the Dolphin devices. | |
240 | ||
241 | For single-touch, the 6-byte packet format is: | |
242 | ||
243 | byte 0: 1 1 0 0 1 0 0 0 | |
244 | byte 1: 0 x6 x5 x4 x3 x2 x1 x0 | |
245 | byte 2: 0 y6 y5 y4 y3 y2 y1 y0 | |
246 | byte 3: 0 M R L 1 m r l | |
247 | byte 4: y10 y9 y8 y7 x10 x9 x8 x7 | |
248 | byte 5: 0 z6 z5 z4 z3 z2 z1 z0 | |
249 | ||
250 | For mt, the format is: | |
251 | ||
252 | byte 0: 1 1 1 n3 1 n2 n1 x24 | |
253 | byte 1: 1 y7 y6 y5 y4 y3 y2 y1 | |
254 | byte 2: ? x2 x1 y12 y11 y10 y9 y8 | |
255 | byte 3: 0 x23 x22 x21 x20 x19 x18 x17 | |
256 | byte 4: 0 x9 x8 x7 x6 x5 x4 x3 | |
257 | byte 5: 0 x16 x15 x14 x13 x12 x11 x10 | |
ef47fa52 PR |
258 | |
259 | ALPS Absolute Mode - Protocol Version 6 | |
260 | --------------------------------------- | |
261 | ||
262 | For trackstick packet, the format is: | |
263 | ||
264 | byte 0: 1 1 1 1 1 1 1 1 | |
265 | byte 1: 0 X6 X5 X4 X3 X2 X1 X0 | |
266 | byte 2: 0 Y6 Y5 Y4 Y3 Y2 Y1 Y0 | |
267 | byte 3: ? Y7 X7 ? ? M R L | |
268 | byte 4: Z7 Z6 Z5 Z4 Z3 Z2 Z1 Z0 | |
269 | byte 5: 0 1 1 1 1 1 1 1 | |
270 | ||
271 | For touchpad packet, the format is: | |
272 | ||
273 | byte 0: 1 1 1 1 1 1 1 1 | |
274 | byte 1: 0 0 0 0 x3 x2 x1 x0 | |
275 | byte 2: 0 0 0 0 y3 y2 y1 y0 | |
276 | byte 3: ? x7 x6 x5 x4 ? r l | |
277 | byte 4: ? y7 y6 y5 y4 ? ? ? | |
278 | byte 5: z7 z6 z5 z4 z3 z2 z1 z0 | |
279 | ||
280 | (v6 touchpad does not have middle button) | |
281 | ||
282 | ALPS Absolute Mode - Protocol Version 7 | |
283 | --------------------------------------- | |
284 | ||
285 | For trackstick packet, the format is: | |
286 | ||
287 | byte 0: 0 1 0 0 1 0 0 0 | |
288 | byte 1: 1 1 * * 1 M R L | |
289 | byte 2: X7 1 X5 X4 X3 X2 X1 X0 | |
290 | byte 3: Z6 1 Y6 X6 1 Y2 Y1 Y0 | |
291 | byte 4: Y7 0 Y5 Y4 Y3 1 1 0 | |
292 | byte 5: T&P 0 Z5 Z4 Z3 Z2 Z1 Z0 | |
293 | ||
294 | For touchpad packet, the format is: | |
295 | ||
296 | packet-fmt b7 b6 b5 b4 b3 b2 b1 b0 | |
297 | byte 0: TWO & MULTI L 1 R M 1 Y0-2 Y0-1 Y0-0 | |
298 | byte 0: NEW L 1 X1-5 1 1 Y0-2 Y0-1 Y0-0 | |
299 | byte 1: Y0-10 Y0-9 Y0-8 Y0-7 Y0-6 Y0-5 Y0-4 Y0-3 | |
300 | byte 2: X0-11 1 X0-10 X0-9 X0-8 X0-7 X0-6 X0-5 | |
301 | byte 3: X1-11 1 X0-4 X0-3 1 X0-2 X0-1 X0-0 | |
302 | byte 4: TWO X1-10 TWO X1-9 X1-8 X1-7 X1-6 X1-5 X1-4 | |
303 | byte 4: MULTI X1-10 TWO X1-9 X1-8 X1-7 X1-6 Y1-5 1 | |
304 | byte 4: NEW X1-10 TWO X1-9 X1-8 X1-7 X1-6 0 0 | |
305 | byte 5: TWO & NEW Y1-10 0 Y1-9 Y1-8 Y1-7 Y1-6 Y1-5 Y1-4 | |
306 | byte 5: MULTI Y1-10 0 Y1-9 Y1-8 Y1-7 Y1-6 F-1 F-0 | |
307 | ||
308 | L: Left button | |
309 | R / M: Non-clickpads: Right / Middle button | |
310 | Clickpads: When > 2 fingers are down, and some fingers | |
311 | are in the button area, then the 2 coordinates reported | |
312 | are for fingers outside the button area and these report | |
313 | extra fingers being present in the right / left button | |
314 | area. Note these fingers are not added to the F field! | |
315 | so if a TWO packet is received and R = 1 then there are | |
316 | 3 fingers down, etc. | |
317 | TWO: 1: Two touches present, byte 0/4/5 are in TWO fmt | |
318 | 0: If byte 4 bit 0 is 1, then byte 0/4/5 are in MULTI fmt | |
319 | otherwise byte 0 bit 4 must be set and byte 0/4/5 are | |
320 | in NEW fmt | |
321 | F: Number of fingers - 3, 0 means 3 fingers, 1 means 4 ... |