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