Based on kernel version 4.10.8. Page generated on 2017-04-01 14:43 EST.
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. 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. 126 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 139 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 145 ALPS Absolute Mode - Protocol Version 3 146 --------------------------------------- 147 148 ALPS protocol version 3 has three different packet formats. The first two are 149 associated with touchpad events, and the third is associated with trackstick 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 178 usually only appears when there are two or more contacts (although 179 occasionally it's seen with only a single contact). 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. 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 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 ... 322 323 324 ALPS Absolute Mode - Protocol Version 8 325 --------------------------------------- 326 327 Spoken by SS4 (73 03 14) and SS5 (73 03 28) hardware. 328 329 The packet type is given by the APD field, bits 4-5 of byte 3. 330 331 Touchpad packet (APD = 0x2): 332 333 b7 b6 b5 b4 b3 b2 b1 b0 334 byte 0: SWM SWR SWL 1 1 0 0 X7 335 byte 1: 0 X6 X5 X4 X3 X2 X1 X0 336 byte 2: 0 Y6 Y5 Y4 Y3 Y2 Y1 Y0 337 byte 3: 0 T&P 1 0 1 0 0 Y7 338 byte 4: 0 Z6 Z5 Z4 Z3 Z2 Z1 Z0 339 byte 5: 0 0 0 0 0 0 0 0 340 341 SWM, SWR, SWL: Middle, Right, and Left button states 342 343 Touchpad 1 Finger packet (APD = 0x0): 344 345 b7 b6 b5 b4 b3 b2 b1 b0 346 byte 0: SWM SWR SWL 1 1 X2 X1 X0 347 byte 1: X9 X8 X7 1 X6 X5 X4 X3 348 byte 2: 0 X11 X10 LFB Y3 Y2 Y1 Y0 349 byte 3: Y5 Y4 0 0 1 TAPF2 TAPF1 TAPF0 350 byte 4: Zv7 Y11 Y10 1 Y9 Y8 Y7 Y6 351 byte 5: Zv6 Zv5 Zv4 0 Zv3 Zv2 Zv1 Zv0 352 353 TAPF: ??? 354 LFB: ??? 355 356 Touchpad 2 Finger packet (APD = 0x1): 357 358 b7 b6 b5 b4 b3 b2 b1 b0 359 byte 0: SWM SWR SWL 1 1 AX6 AX5 AX4 360 byte 1: AX11 AX10 AX9 AX8 AX7 AZ1 AY4 AZ0 361 byte 2: AY11 AY10 AY9 CONT AY8 AY7 AY6 AY5 362 byte 3: 0 0 0 1 1 BX6 BX5 BX4 363 byte 4: BX11 BX10 BX9 BX8 BX7 BZ1 BY4 BZ0 364 byte 5: BY11 BY10 BY9 0 BY8 BY7 BY5 BY5 365 366 CONT: A 3-or-4 Finger packet is to follow 367 368 Touchpad 3-or-4 Finger packet (APD = 0x3): 369 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 OVF AY8 AY7 AY6 AY5 374 byte 3: 0 0 1 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 377 378 OVF: 5th finger detected