| blob | b556d6bde5e11744315fa8a67cb72c6b624ab3a2 |
1 ----------------------
2 ALPS Touchpad Protocol
3 ----------------------
5 Introduction
6 ------------
7 Currently the ALPS touchpad driver supports seven protocol versions in use by
8 ALPS touchpads, called versions 1, 2, 3, 4, 5, 6, 7 and 8.
10 Since roughly mid-2010 several new ALPS touchpads have been released and
11 integrated into a variety of laptops and netbooks. These new touchpads
12 have enough behavior differences that the alps_model_data definition
13 table, describing the properties of the different versions, is no longer
14 adequate. The design choices were to re-define the alps_model_data
15 table, with the risk of regression testing existing devices, or isolate
16 the new devices outside of the alps_model_data table. The latter design
17 choice was made. The new touchpad signatures are named: "Rushmore",
18 "Pinnacle", and "Dolphin", which you will see in the alps.c code.
19 For the purposes of this document, this group of ALPS touchpads will
20 generically be called "new ALPS touchpads".
22 We experimented with probing the ACPI interface _HID (Hardware ID)/_CID
23 (Compatibility ID) definition as a way to uniquely identify the
24 different ALPS variants but there did not appear to be a 1:1 mapping.
25 In fact, it appeared to be an m:n mapping between the _HID and actual
26 hardware type.
28 Detection
29 ---------
31 All ALPS touchpads should respond to the "E6 report" command sequence:
32 E8-E6-E6-E6-E9. An ALPS touchpad should respond with either 00-00-0A or
33 00-00-64 if no buttons are pressed. The bits 0-2 of the first byte will be 1s
34 if some buttons are pressed.
36 If the E6 report is successful, the touchpad model is identified using the "E7
37 report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is
38 matched against known models in the alps_model_data_array.
40 For older touchpads supporting protocol versions 3 and 4, the E7 report
41 model signature is always 73-02-64. To differentiate between these
42 versions, the response from the "Enter Command Mode" sequence must be
43 inspected as described below.
45 The new ALPS touchpads have an E7 signature of 73-03-50 or 73-03-0A but
46 seem to be better differentiated by the EC Command Mode response.
48 Command Mode
49 ------------
51 Protocol versions 3 and 4 have a command mode that is used to read and write
52 one-byte device registers in a 16-bit address space. The command sequence
53 EC-EC-EC-E9 places the device in command mode, and the device will respond
54 with 88-07 followed by a third byte. This third byte can be used to determine
55 whether the devices uses the version 3 or 4 protocol.
57 To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad.
59 While in command mode, register addresses can be set by first sending a
60 specific command, either EC for v3 devices or F5 for v4 devices. Then the
61 address is sent one nibble at a time, where each nibble is encoded as a
62 command with optional data. This encoding differs slightly between the v3 and
63 v4 protocols.
65 Once an address has been set, the addressed register can be read by sending
66 PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the
67 address of the register being read, and the third contains the value of the
68 register. Registers are written by writing the value one nibble at a time
69 using the same encoding used for addresses.
71 For the new ALPS touchpads, the EC command is used to enter command
72 mode. The response in the new ALPS touchpads is significantly different,
73 and more important in determining the behavior. This code has been
74 separated from the original alps_model_data table and put in the
75 alps_identify function. For example, there seem to be two hardware init
76 sequences for the "Dolphin" touchpads as determined by the second byte
77 of the EC response.
79 Packet Format
80 -------------
82 In the following tables, the following notation is used::
84 CAPITALS = stick, miniscules = touchpad
86 ?'s can have different meanings on different models, such as wheel rotation,
87 extra buttons, stick buttons on a dualpoint, etc.
89 PS/2 packet format
90 ------------------
92 ::
94 byte 0: 0 0 YSGN XSGN 1 M R L
95 byte 1: X7 X6 X5 X4 X3 X2 X1 X0
96 byte 2: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
98 Note that the device never signals overflow condition.
100 For protocol version 2 devices when the trackpoint is used, and no fingers
101 are on the touchpad, the M R L bits signal the combined status of both the
102 pointingstick and touchpad buttons.
104 ALPS Absolute Mode - Protocol Version 1
105 ---------------------------------------
107 ::
109 byte 0: 1 0 0 0 1 x9 x8 x7
110 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
111 byte 2: 0 ? ? l r ? fin ges
112 byte 3: 0 ? ? ? ? y9 y8 y7
113 byte 4: 0 y6 y5 y4 y3 y2 y1 y0
114 byte 5: 0 z6 z5 z4 z3 z2 z1 z0
116 ALPS Absolute Mode - Protocol Version 2
117 ---------------------------------------
119 ::
121 byte 0: 1 ? ? ? 1 PSM PSR PSL
122 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
123 byte 2: 0 x10 x9 x8 x7 ? fin ges
124 byte 3: 0 y9 y8 y7 1 M R L
125 byte 4: 0 y6 y5 y4 y3 y2 y1 y0
126 byte 5: 0 z6 z5 z4 z3 z2 z1 z0
128 Protocol Version 2 DualPoint devices send standard PS/2 mouse packets for
129 the DualPoint Stick. The M, R and L bits signal the combined status of both
130 the pointingstick and touchpad buttons, except for Dell dualpoint devices
131 where the pointingstick buttons get reported separately in the PSM, PSR
132 and PSL bits.
134 Dualpoint device -- interleaved packet format
135 ---------------------------------------------
137 ::
139 byte 0: 1 1 0 0 1 1 1 1
140 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
141 byte 2: 0 x10 x9 x8 x7 0 fin ges
142 byte 3: 0 0 YSGN XSGN 1 1 1 1
143 byte 4: X7 X6 X5 X4 X3 X2 X1 X0
144 byte 5: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
145 byte 6: 0 y9 y8 y7 1 m r l
146 byte 7: 0 y6 y5 y4 y3 y2 y1 y0
147 byte 8: 0 z6 z5 z4 z3 z2 z1 z0
149 Devices which use the interleaving format normally send standard PS/2 mouse
150 packets for the DualPoint Stick + ALPS Absolute Mode packets for the
151 touchpad, switching to the interleaved packet format when both the stick and
152 the touchpad are used at the same time.
154 ALPS Absolute Mode - Protocol Version 3
155 ---------------------------------------
157 ALPS protocol version 3 has three different packet formats. The first two are
158 associated with touchpad events, and the third is associated with trackstick
159 events.
161 The first type is the touchpad position packet::
163 byte 0: 1 ? x1 x0 1 1 1 1
164 byte 1: 0 x10 x9 x8 x7 x6 x5 x4
165 byte 2: 0 y10 y9 y8 y7 y6 y5 y4
166 byte 3: 0 M R L 1 m r l
167 byte 4: 0 mt x3 x2 y3 y2 y1 y0
168 byte 5: 0 z6 z5 z4 z3 z2 z1 z0
170 Note that for some devices the trackstick buttons are reported in this packet,
171 and on others it is reported in the trackstick packets.
173 The second packet type contains bitmaps representing the x and y axes. In the
174 bitmaps a given bit is set if there is a finger covering that position on the
175 given axis. Thus the bitmap packet can be used for low-resolution multi-touch
176 data, although finger tracking is not possible. This packet also encodes the
177 number of contacts (f1 and f0 in the table below)::
179 byte 0: 1 1 x1 x0 1 1 1 1
180 byte 1: 0 x8 x7 x6 x5 x4 x3 x2
181 byte 2: 0 y7 y6 y5 y4 y3 y2 y1
182 byte 3: 0 y10 y9 y8 1 1 1 1
183 byte 4: 0 x14 x13 x12 x11 x10 x9 y0
184 byte 5: 0 1 ? ? ? ? f1 f0
186 This packet only appears after a position packet with the mt bit set, and
187 usually only appears when there are two or more contacts (although
188 occasionally it's seen with only a single contact).
190 The final v3 packet type is the trackstick packet::
192 byte 0: 1 1 x7 y7 1 1 1 1
193 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
194 byte 2: 0 y6 y5 y4 y3 y2 y1 y0
195 byte 3: 0 1 TP SW 1 M R L
196 byte 4: 0 z6 z5 z4 z3 z2 z1 z0
197 byte 5: 0 0 1 1 1 1 1 1
199 TP means Tap SW status when tap processing is enabled or Press status when press
200 processing is enabled. SW means scroll up when 4 buttons are available.
202 ALPS Absolute Mode - Protocol Version 4
203 ---------------------------------------
205 Protocol version 4 has an 8-byte packet format::
207 byte 0: 1 ? x1 x0 1 1 1 1
208 byte 1: 0 x10 x9 x8 x7 x6 x5 x4
209 byte 2: 0 y10 y9 y8 y7 y6 y5 y4
210 byte 3: 0 1 x3 x2 y3 y2 y1 y0
211 byte 4: 0 ? ? ? 1 ? r l
212 byte 5: 0 z6 z5 z4 z3 z2 z1 z0
213 byte 6: bitmap data (described below)
214 byte 7: bitmap data (described below)
216 The last two bytes represent a partial bitmap packet, with 3 full packets
217 required to construct a complete bitmap packet. Once assembled, the 6-byte
218 bitmap packet has the following format::
220 byte 0: 0 1 x7 x6 x5 x4 x3 x2
221 byte 1: 0 x1 x0 y4 y3 y2 y1 y0
222 byte 2: 0 0 ? x14 x13 x12 x11 x10
223 byte 3: 0 x9 x8 y9 y8 y7 y6 y5
224 byte 4: 0 0 0 0 0 0 0 0
225 byte 5: 0 0 0 0 0 0 0 y10
227 There are several things worth noting here.
229 1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
230 identify the first fragment of a bitmap packet.
232 2) The bitmaps represent the same data as in the v3 bitmap packets, although
233 the packet layout is different.
235 3) There doesn't seem to be a count of the contact points anywhere in the v4
236 protocol packets. Deriving a count of contact points must be done by
237 analyzing the bitmaps.
239 4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
240 MT position can only be updated for every third ST position update, and
241 the count of contact points can only be updated every third packet as
242 well.
244 So far no v4 devices with tracksticks have been encountered.
246 ALPS Absolute Mode - Protocol Version 5
247 ---------------------------------------
248 This is basically Protocol Version 3 but with different logic for packet
249 decode. It uses the same alps_process_touchpad_packet_v3 call with a
250 specialized decode_fields function pointer to correctly interpret the
251 packets. This appears to only be used by the Dolphin devices.
253 For single-touch, the 6-byte packet format is::
255 byte 0: 1 1 0 0 1 0 0 0
256 byte 1: 0 x6 x5 x4 x3 x2 x1 x0
257 byte 2: 0 y6 y5 y4 y3 y2 y1 y0
258 byte 3: 0 M R L 1 m r l
259 byte 4: y10 y9 y8 y7 x10 x9 x8 x7
260 byte 5: 0 z6 z5 z4 z3 z2 z1 z0
262 For mt, the format is::
264 byte 0: 1 1 1 n3 1 n2 n1 x24
265 byte 1: 1 y7 y6 y5 y4 y3 y2 y1
266 byte 2: ? x2 x1 y12 y11 y10 y9 y8
267 byte 3: 0 x23 x22 x21 x20 x19 x18 x17
268 byte 4: 0 x9 x8 x7 x6 x5 x4 x3
269 byte 5: 0 x16 x15 x14 x13 x12 x11 x10
271 ALPS Absolute Mode - Protocol Version 6
272 ---------------------------------------
274 For trackstick packet, the format is::
276 byte 0: 1 1 1 1 1 1 1 1
277 byte 1: 0 X6 X5 X4 X3 X2 X1 X0
278 byte 2: 0 Y6 Y5 Y4 Y3 Y2 Y1 Y0
279 byte 3: ? Y7 X7 ? ? M R L
280 byte 4: Z7 Z6 Z5 Z4 Z3 Z2 Z1 Z0
281 byte 5: 0 1 1 1 1 1 1 1
283 For touchpad packet, the format is::
285 byte 0: 1 1 1 1 1 1 1 1
286 byte 1: 0 0 0 0 x3 x2 x1 x0
287 byte 2: 0 0 0 0 y3 y2 y1 y0
288 byte 3: ? x7 x6 x5 x4 ? r l
289 byte 4: ? y7 y6 y5 y4 ? ? ?
290 byte 5: z7 z6 z5 z4 z3 z2 z1 z0
292 (v6 touchpad does not have middle button)
294 ALPS Absolute Mode - Protocol Version 7
295 ---------------------------------------
297 For trackstick packet, the format is::
299 byte 0: 0 1 0 0 1 0 0 0
300 byte 1: 1 1 * * 1 M R L
301 byte 2: X7 1 X5 X4 X3 X2 X1 X0
302 byte 3: Z6 1 Y6 X6 1 Y2 Y1 Y0
303 byte 4: Y7 0 Y5 Y4 Y3 1 1 0
304 byte 5: T&P 0 Z5 Z4 Z3 Z2 Z1 Z0
306 For touchpad packet, the format is::
308 packet-fmt b7 b6 b5 b4 b3 b2 b1 b0
309 byte 0: TWO & MULTI L 1 R M 1 Y0-2 Y0-1 Y0-0
310 byte 0: NEW L 1 X1-5 1 1 Y0-2 Y0-1 Y0-0
311 byte 1: Y0-10 Y0-9 Y0-8 Y0-7 Y0-6 Y0-5 Y0-4 Y0-3
312 byte 2: X0-11 1 X0-10 X0-9 X0-8 X0-7 X0-6 X0-5
313 byte 3: X1-11 1 X0-4 X0-3 1 X0-2 X0-1 X0-0
314 byte 4: TWO X1-10 TWO X1-9 X1-8 X1-7 X1-6 X1-5 X1-4
315 byte 4: MULTI X1-10 TWO X1-9 X1-8 X1-7 X1-6 Y1-5 1
316 byte 4: NEW X1-10 TWO X1-9 X1-8 X1-7 X1-6 0 0
317 byte 5: TWO & NEW Y1-10 0 Y1-9 Y1-8 Y1-7 Y1-6 Y1-5 Y1-4
318 byte 5: MULTI Y1-10 0 Y1-9 Y1-8 Y1-7 Y1-6 F-1 F-0
320 L: Left button
321 R / M: Non-clickpads: Right / Middle button
322 Clickpads: When > 2 fingers are down, and some fingers
323 are in the button area, then the 2 coordinates reported
324 are for fingers outside the button area and these report
325 extra fingers being present in the right / left button
326 area. Note these fingers are not added to the F field!
327 so if a TWO packet is received and R = 1 then there are
328 3 fingers down, etc.
329 TWO: 1: Two touches present, byte 0/4/5 are in TWO fmt
330 0: If byte 4 bit 0 is 1, then byte 0/4/5 are in MULTI fmt
331 otherwise byte 0 bit 4 must be set and byte 0/4/5 are
332 in NEW fmt
333 F: Number of fingers - 3, 0 means 3 fingers, 1 means 4 ...
336 ALPS Absolute Mode - Protocol Version 8
337 ---------------------------------------
339 Spoken by SS4 (73 03 14) and SS5 (73 03 28) hardware.
341 The packet type is given by the APD field, bits 4-5 of byte 3.
343 Touchpad packet (APD = 0x2)::
345 b7 b6 b5 b4 b3 b2 b1 b0
346 byte 0: SWM SWR SWL 1 1 0 0 X7
347 byte 1: 0 X6 X5 X4 X3 X2 X1 X0
348 byte 2: 0 Y6 Y5 Y4 Y3 Y2 Y1 Y0
349 byte 3: 0 T&P 1 0 1 0 0 Y7
350 byte 4: 0 Z6 Z5 Z4 Z3 Z2 Z1 Z0
351 byte 5: 0 0 0 0 0 0 0 0
353 SWM, SWR, SWL: Middle, Right, and Left button states
355 Touchpad 1 Finger packet (APD = 0x0)::
357 b7 b6 b5 b4 b3 b2 b1 b0
358 byte 0: SWM SWR SWL 1 1 X2 X1 X0
359 byte 1: X9 X8 X7 1 X6 X5 X4 X3
360 byte 2: 0 X11 X10 LFB Y3 Y2 Y1 Y0
361 byte 3: Y5 Y4 0 0 1 TAPF2 TAPF1 TAPF0
362 byte 4: Zv7 Y11 Y10 1 Y9 Y8 Y7 Y6
363 byte 5: Zv6 Zv5 Zv4 0 Zv3 Zv2 Zv1 Zv0
365 TAPF: ???
366 LFB: ???
368 Touchpad 2 Finger packet (APD = 0x1)::
370 b7 b6 b5 b4 b3 b2 b1 b0
371 byte 0: SWM SWR SWL 1 1 AX6 AX5 AX4
372 byte 1: AX11 AX10 AX9 AX8 AX7 AZ1 AY4 AZ0
373 byte 2: AY11 AY10 AY9 CONT AY8 AY7 AY6 AY5
374 byte 3: 0 0 0 1 1 BX6 BX5 BX4
375 byte 4: BX11 BX10 BX9 BX8 BX7 BZ1 BY4 BZ0
376 byte 5: BY11 BY10 BY9 0 BY8 BY7 BY5 BY5
378 CONT: A 3-or-4 Finger packet is to follow
380 Touchpad 3-or-4 Finger packet (APD = 0x3)::
382 b7 b6 b5 b4 b3 b2 b1 b0
383 byte 0: SWM SWR SWL 1 1 AX6 AX5 AX4
384 byte 1: AX11 AX10 AX9 AX8 AX7 AZ1 AY4 AZ0
385 byte 2: AY11 AY10 AY9 OVF AY8 AY7 AY6 AY5
386 byte 3: 0 0 1 1 1 BX6 BX5 BX4
387 byte 4: BX11 BX10 BX9 BX8 BX7 BZ1 BY4 BZ0
388 byte 5: BY11 BY10 BY9 0 BY8 BY7 BY5 BY5
390 OVF: 5th finger detected