blob: 1fec1135791d98c987105872c63b5e96589633d3 [file] [log] [blame]
Seth Forsheed4b347b2011-11-07 19:53:15 -08001ALPS Touchpad Protocol
2----------------------
3
4Introduction
5------------
Pali Roháref47fa52015-02-15 15:58:08 -08006Currently the ALPS touchpad driver supports seven protocol versions in use by
7ALPS touchpads, called versions 1, 2, 3, 4, 5, 6 and 7.
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
Masanari Iidaad4a6eb2015-02-25 20:30:22 +090061command with optional data. This encoding differs slightly between the v3 and
Seth Forshee7cf801c2011-11-07 19:54:35 -080062v4 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
Hans de Goede23105682015-04-15 10:48:32 -070097For protocol version 2 devices when the trackpoint is used, and no fingers
98are on the touchpad, the M R L bits signal the combined status of both the
99pointingstick and touchpad buttons.
100
Carlos Garciac98be0c2014-04-04 22:31:00 -0400101ALPS Absolute Mode - Protocol Version 1
Seth Forshee7cf801c2011-11-07 19:54:35 -0800102--------------------------------------
Seth Forsheed4b347b2011-11-07 19:53:15 -0800103
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
Seth Forshee7cf801c2011-11-07 19:54:35 -0800111ALPS Absolute Mode - Protocol Version 2
112---------------------------------------
Seth Forsheed4b347b2011-11-07 19:53:15 -0800113
Hans de Goede23105682015-04-15 10:48:32 -0700114 byte 0: 1 ? ? ? 1 PSM PSR PSL
Seth Forsheed4b347b2011-11-07 19:53:15 -0800115 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
Hans de Goede58d8a3b2015-04-03 17:30:31 -0700121Protocol Version 2 DualPoint devices send standard PS/2 mouse packets for
Hans de Goede073e5702015-08-03 14:06:24 -0700122the DualPoint Stick. The M, R and L bits signal the combined status of both
123the pointingstick and touchpad buttons, except for Dell dualpoint devices
124where the pointingstick buttons get reported separately in the PSM, PSR
125and PSL bits.
Hans de Goede58d8a3b2015-04-03 17:30:31 -0700126
Seth Forsheed4b347b2011-11-07 19:53:15 -0800127Dualpoint 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
Seth Forshee7cf801c2011-11-07 19:54:35 -0800139
Hans de Goede58d8a3b2015-04-03 17:30:31 -0700140Devices which use the interleaving format normally send standard PS/2 mouse
141packets for the DualPoint Stick + ALPS Absolute Mode packets for the
142touchpad, switching to the interleaved packet format when both the stick and
143the touchpad are used at the same time.
144
Seth Forshee7cf801c2011-11-07 19:54:35 -0800145ALPS Absolute Mode - Protocol Version 3
146---------------------------------------
147
148ALPS protocol version 3 has three different packet formats. The first two are
Masanari Iidaad4a6eb2015-02-25 20:30:22 +0900149associated with touchpad events, and the third is associated with trackstick
Seth Forshee7cf801c2011-11-07 19:54:35 -0800150events.
151
152The 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
161Note that for some devices the trackstick buttons are reported in this packet,
162and on others it is reported in the trackstick packets.
163
164The second packet type contains bitmaps representing the x and y axes. In the
165bitmaps a given bit is set if there is a finger covering that position on the
166given axis. Thus the bitmap packet can be used for low-resolution multi-touch
167data, although finger tracking is not possible. This packet also encodes the
168number 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
177This packet only appears after a position packet with the mt bit set, and
Masanari Iida40e47122012-03-04 23:16:11 +0900178usually only appears when there are two or more contacts (although
Masanari Iida4e79162a2012-11-08 21:57:35 +0900179occasionally it's seen with only a single contact).
Seth Forshee7cf801c2011-11-07 19:54:35 -0800180
181The 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
190ALPS Absolute Mode - Protocol Version 4
191---------------------------------------
192
193Protocol 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
204The last two bytes represent a partial bitmap packet, with 3 full packets
205required to construct a complete bitmap packet. Once assembled, the 6-byte
206bitmap 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
215There 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
232So far no v4 devices with tracksticks have been encountered.
dave turvene171fb58d2013-02-23 20:06:34 -0800233
234ALPS Absolute Mode - Protocol Version 5
235---------------------------------------
236This is basically Protocol Version 3 but with different logic for packet
237decode. It uses the same alps_process_touchpad_packet_v3 call with a
238specialized decode_fields function pointer to correctly interpret the
239packets. This appears to only be used by the Dolphin devices.
240
241For 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
250For 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
Pali Roháref47fa52015-02-15 15:58:08 -0800258
259ALPS Absolute Mode - Protocol Version 6
260---------------------------------------
261
262For 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
271For 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
282ALPS Absolute Mode - Protocol Version 7
283---------------------------------------
284
285For 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
294For 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 ...