Merge branch 'upstream' of git://git.linux-mips.org/pub/scm/ralf/upstream-linus
[sfrench/cifs-2.6.git] / Documentation / input / alps.txt
1 ALPS Touchpad Protocol
2 ----------------------
3
4 Introduction
5 ------------
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.
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.
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
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.
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
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.
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
61 command with optional data. This encoding differs slightly between the v3 and
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
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
78 Packet Format
79 -------------
80
81 In the following tables, the following notation is used.
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
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
101 ALPS Absolute Mode - Protocol Version 1
102 --------------------------------------
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
111 ALPS Absolute Mode - Protocol Version 2
112 ---------------------------------------
113
114  byte 0:  1    ?    ?    ?    1  PSM  PSR  PSL
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
121 Protocol Version 2 DualPoint devices send standard PS/2 mouse packets for
122 the DualPoint Stick. For non interleaved dualpoint devices the pointingstick
123 buttons get reported separately in the PSM, PSR and PSL bits.
124
125 Dualpoint device -- interleaved packet format
126 ---------------------------------------------
127
128  byte 0:    1    1    0    0    1    1    1    1
129  byte 1:    0   x6   x5   x4   x3   x2   x1   x0
130  byte 2:    0  x10   x9   x8   x7    0  fin  ges
131  byte 3:    0    0 YSGN XSGN    1    1    1    1
132  byte 4:   X7   X6   X5   X4   X3   X2   X1   X0
133  byte 5:   Y7   Y6   Y5   Y4   Y3   Y2   Y1   Y0
134  byte 6:    0   y9   y8   y7    1    m    r    l
135  byte 7:    0   y6   y5   y4   y3   y2   y1   y0
136  byte 8:    0   z6   z5   z4   z3   z2   z1   z0
137
138 Devices which use the interleaving format normally send standard PS/2 mouse
139 packets for the DualPoint Stick + ALPS Absolute Mode packets for the
140 touchpad, switching to the interleaved packet format when both the stick and
141 the touchpad are used at the same time.
142
143 ALPS Absolute Mode - Protocol Version 3
144 ---------------------------------------
145
146 ALPS protocol version 3 has three different packet formats. The first two are
147 associated with touchpad events, and the third is associated with trackstick
148 events.
149
150 The first type is the touchpad position packet.
151
152  byte 0:    1    ?   x1   x0    1    1    1    1
153  byte 1:    0  x10   x9   x8   x7   x6   x5   x4
154  byte 2:    0  y10   y9   y8   y7   y6   y5   y4
155  byte 3:    0    M    R    L    1    m    r    l
156  byte 4:    0   mt   x3   x2   y3   y2   y1   y0
157  byte 5:    0   z6   z5   z4   z3   z2   z1   z0
158
159 Note that for some devices the trackstick buttons are reported in this packet,
160 and on others it is reported in the trackstick packets.
161
162 The second packet type contains bitmaps representing the x and y axes. In the
163 bitmaps a given bit is set if there is a finger covering that position on the
164 given axis. Thus the bitmap packet can be used for low-resolution multi-touch
165 data, although finger tracking is not possible.  This packet also encodes the
166 number of contacts (f1 and f0 in the table below).
167
168  byte 0:    1    1   x1   x0    1    1    1    1
169  byte 1:    0   x8   x7   x6   x5   x4   x3   x2
170  byte 2:    0   y7   y6   y5   y4   y3   y2   y1
171  byte 3:    0  y10   y9   y8    1    1    1    1
172  byte 4:    0  x14  x13  x12  x11  x10   x9   y0
173  byte 5:    0    1    ?    ?    ?    ?   f1   f0
174
175 This packet only appears after a position packet with the mt bit set, and
176 usually only appears when there are two or more contacts (although
177 occasionally it's seen with only a single contact).
178
179 The final v3 packet type is the trackstick packet.
180
181  byte 0:    1    1   x7   y7    1    1    1    1
182  byte 1:    0   x6   x5   x4   x3   x2   x1   x0
183  byte 2:    0   y6   y5   y4   y3   y2   y1   y0
184  byte 3:    0    1    0    0    1    0    0    0
185  byte 4:    0   z4   z3   z2   z1   z0    ?    ?
186  byte 5:    0    0    1    1    1    1    1    1
187
188 ALPS Absolute Mode - Protocol Version 4
189 ---------------------------------------
190
191 Protocol version 4 has an 8-byte packet format.
192
193  byte 0:    1    ?   x1   x0    1    1    1    1
194  byte 1:    0  x10   x9   x8   x7   x6   x5   x4
195  byte 2:    0  y10   y9   y8   y7   y6   y5   y4
196  byte 3:    0    1   x3   x2   y3   y2   y1   y0
197  byte 4:    0    ?    ?    ?    1    ?    r    l
198  byte 5:    0   z6   z5   z4   z3   z2   z1   z0
199  byte 6:    bitmap data (described below)
200  byte 7:    bitmap data (described below)
201
202 The last two bytes represent a partial bitmap packet, with 3 full packets
203 required to construct a complete bitmap packet.  Once assembled, the 6-byte
204 bitmap packet has the following format:
205
206  byte 0:    0    1   x7   x6   x5   x4   x3   x2
207  byte 1:    0   x1   x0   y4   y3   y2   y1   y0
208  byte 2:    0    0    ?  x14  x13  x12  x11  x10
209  byte 3:    0   x9   x8   y9   y8   y7   y6   y5
210  byte 4:    0    0    0    0    0    0    0    0
211  byte 5:    0    0    0    0    0    0    0  y10
212
213 There are several things worth noting here.
214
215  1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
216     identify the first fragment of a bitmap packet.
217
218  2) The bitmaps represent the same data as in the v3 bitmap packets, although
219     the packet layout is different.
220
221  3) There doesn't seem to be a count of the contact points anywhere in the v4
222     protocol packets. Deriving a count of contact points must be done by
223     analyzing the bitmaps.
224
225  4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
226     MT position can only be updated for every third ST position update, and
227     the count of contact points can only be updated every third packet as
228     well.
229
230 So far no v4 devices with tracksticks have been encountered.
231
232 ALPS Absolute Mode - Protocol Version 5
233 ---------------------------------------
234 This is basically Protocol Version 3 but with different logic for packet
235 decode.  It uses the same alps_process_touchpad_packet_v3 call with a
236 specialized decode_fields function pointer to correctly interpret the
237 packets.  This appears to only be used by the Dolphin devices.
238
239 For single-touch, the 6-byte packet format is:
240
241  byte 0:    1    1    0    0    1    0    0    0
242  byte 1:    0   x6   x5   x4   x3   x2   x1   x0
243  byte 2:    0   y6   y5   y4   y3   y2   y1   y0
244  byte 3:    0    M    R    L    1    m    r    l
245  byte 4:   y10  y9   y8   y7  x10   x9   x8   x7
246  byte 5:    0   z6   z5   z4   z3   z2   z1   z0
247
248 For mt, the format is:
249
250  byte 0:    1    1    1    n3   1   n2   n1   x24
251  byte 1:    1   y7   y6    y5  y4   y3   y2    y1
252  byte 2:    ?   x2   x1   y12 y11  y10   y9    y8
253  byte 3:    0  x23  x22   x21 x20  x19  x18   x17
254  byte 4:    0   x9   x8    x7  x6   x5   x4    x3
255  byte 5:    0  x16  x15   x14 x13  x12  x11   x10
256
257 ALPS Absolute Mode - Protocol Version 6
258 ---------------------------------------
259
260 For trackstick packet, the format is:
261
262  byte 0:    1    1    1    1    1    1    1    1
263  byte 1:    0   X6   X5   X4   X3   X2   X1   X0
264  byte 2:    0   Y6   Y5   Y4   Y3   Y2   Y1   Y0
265  byte 3:    ?   Y7   X7    ?    ?    M    R    L
266  byte 4:   Z7   Z6   Z5   Z4   Z3   Z2   Z1   Z0
267  byte 5:    0    1    1    1    1    1    1    1
268
269 For touchpad packet, the format is:
270
271  byte 0:    1    1    1    1    1    1    1    1
272  byte 1:    0    0    0    0   x3   x2   x1   x0
273  byte 2:    0    0    0    0   y3   y2   y1   y0
274  byte 3:    ?   x7   x6   x5   x4    ?    r    l
275  byte 4:    ?   y7   y6   y5   y4    ?    ?    ?
276  byte 5:   z7   z6   z5   z4   z3   z2   z1   z0
277
278 (v6 touchpad does not have middle button)
279
280 ALPS Absolute Mode - Protocol Version 7
281 ---------------------------------------
282
283 For trackstick packet, the format is:
284
285  byte 0:    0    1    0    0    1    0    0    0
286  byte 1:    1    1    *    *    1    M    R    L
287  byte 2:   X7    1   X5   X4   X3   X2   X1   X0
288  byte 3:   Z6    1   Y6   X6    1   Y2   Y1   Y0
289  byte 4:   Y7    0   Y5   Y4   Y3    1    1    0
290  byte 5:  T&P    0   Z5   Z4   Z3   Z2   Z1   Z0
291
292 For touchpad packet, the format is:
293
294          packet-fmt     b7     b6     b5     b4     b3     b2     b1     b0
295  byte 0: TWO & MULTI     L      1      R      M      1   Y0-2   Y0-1   Y0-0
296  byte 0: NEW             L      1   X1-5      1      1   Y0-2   Y0-1   Y0-0
297  byte 1:             Y0-10   Y0-9   Y0-8   Y0-7   Y0-6   Y0-5   Y0-4   Y0-3
298  byte 2:             X0-11      1  X0-10   X0-9   X0-8   X0-7   X0-6   X0-5
299  byte 3:             X1-11      1   X0-4   X0-3      1   X0-2   X0-1   X0-0
300  byte 4: TWO         X1-10    TWO   X1-9   X1-8   X1-7   X1-6   X1-5   X1-4
301  byte 4: MULTI       X1-10    TWO   X1-9   X1-8   X1-7   X1-6   Y1-5      1
302  byte 4: NEW         X1-10    TWO   X1-9   X1-8   X1-7   X1-6      0      0
303  byte 5: TWO & NEW   Y1-10      0   Y1-9   Y1-8   Y1-7   Y1-6   Y1-5   Y1-4
304  byte 5: MULTI       Y1-10      0   Y1-9   Y1-8   Y1-7   Y1-6    F-1    F-0
305
306  L:         Left button
307  R / M:     Non-clickpads: Right / Middle button
308             Clickpads: When > 2 fingers are down, and some fingers
309             are in the button area, then the 2 coordinates reported
310             are for fingers outside the button area and these report
311             extra fingers being present in the right / left button
312             area. Note these fingers are not added to the F field!
313             so if a TWO packet is received and R = 1 then there are
314             3 fingers down, etc.
315  TWO:       1: Two touches present, byte 0/4/5 are in TWO fmt
316             0: If byte 4 bit 0 is 1, then byte 0/4/5 are in MULTI fmt
317                otherwise byte 0 bit 4 must be set and byte 0/4/5 are
318                in NEW fmt
319  F:         Number of fingers - 3, 0 means 3 fingers, 1 means 4 ...