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