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