Documentation/input/devices/alps.rst

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