Documentation/input/alps.txt

   1 ALPS Touchpad Protocol
   2 ----------------------
   3
   4 Introduction
   5 ------------
   6 Currently the ALPS touchpad driver supports five protocol versions in use by
   7 ALPS touchpads, called versions 1, 2, 3, 4 and 5.
   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 Verion 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 Dualpoint device -- interleaved packet format
 118 ---------------------------------------------
 119
 120  byte 0:    1    1    0    0    1    1    1    1
 121  byte 1:    0   x6   x5   x4   x3   x2   x1   x0
 122  byte 2:    0  x10   x9   x8   x7    0  fin  ges
 123  byte 3:    0    0 YSGN XSGN    1    1    1    1
 124  byte 4:   X7   X6   X5   X4   X3   X2   X1   X0
 125  byte 5:   Y7   Y6   Y5   Y4   Y3   Y2   Y1   Y0
 126  byte 6:    0   y9   y8   y7    1    m    r    l
 127  byte 7:    0   y6   y5   y4   y3   y2   y1   y0
 128  byte 8:    0   z6   z5   z4   z3   z2   z1   z0
 129
 130 ALPS Absolute Mode - Protocol Version 3
 131 ---------------------------------------
 132
 133 ALPS protocol version 3 has three different packet formats. The first two are
 134 associated with touchpad events, and the third is associatd with trackstick
 135 events.
 136
 137 The first type is the touchpad position packet.
 138
 139  byte 0:    1    ?   x1   x0    1    1    1    1
 140  byte 1:    0  x10   x9   x8   x7   x6   x5   x4
 141  byte 2:    0  y10   y9   y8   y7   y6   y5   y4
 142  byte 3:    0    M    R    L    1    m    r    l
 143  byte 4:    0   mt   x3   x2   y3   y2   y1   y0
 144  byte 5:    0   z6   z5   z4   z3   z2   z1   z0
 145
 146 Note that for some devices the trackstick buttons are reported in this packet,
 147 and on others it is reported in the trackstick packets.
 148
 149 The second packet type contains bitmaps representing the x and y axes. In the
 150 bitmaps a given bit is set if there is a finger covering that position on the
 151 given axis. Thus the bitmap packet can be used for low-resolution multi-touch
 152 data, although finger tracking is not possible.  This packet also encodes the
 153 number of contacts (f1 and f0 in the table below).
 154
 155  byte 0:    1    1   x1   x0    1    1    1    1
 156  byte 1:    0   x8   x7   x6   x5   x4   x3   x2
 157  byte 2:    0   y7   y6   y5   y4   y3   y2   y1
 158  byte 3:    0  y10   y9   y8    1    1    1    1
 159  byte 4:    0  x14  x13  x12  x11  x10   x9   y0
 160  byte 5:    0    1    ?    ?    ?    ?   f1   f0
 161
 162 This packet only appears after a position packet with the mt bit set, and
 163 usually only appears when there are two or more contacts (although
 164 occasionally it's seen with only a single contact).
 165
 166 The final v3 packet type is the trackstick packet.
 167
 168  byte 0:    1    1   x7   y7    1    1    1    1
 169  byte 1:    0   x6   x5   x4   x3   x2   x1   x0
 170  byte 2:    0   y6   y5   y4   y3   y2   y1   y0
 171  byte 3:    0    1    0    0    1    0    0    0
 172  byte 4:    0   z4   z3   z2   z1   z0    ?    ?
 173  byte 5:    0    0    1    1    1    1    1    1
 174
 175 ALPS Absolute Mode - Protocol Version 4
 176 ---------------------------------------
 177
 178 Protocol version 4 has an 8-byte packet format.
 179
 180  byte 0:    1    ?   x1   x0    1    1    1    1
 181  byte 1:    0  x10   x9   x8   x7   x6   x5   x4
 182  byte 2:    0  y10   y9   y8   y7   y6   y5   y4
 183  byte 3:    0    1   x3   x2   y3   y2   y1   y0
 184  byte 4:    0    ?    ?    ?    1    ?    r    l
 185  byte 5:    0   z6   z5   z4   z3   z2   z1   z0
 186  byte 6:    bitmap data (described below)
 187  byte 7:    bitmap data (described below)
 188
 189 The last two bytes represent a partial bitmap packet, with 3 full packets
 190 required to construct a complete bitmap packet.  Once assembled, the 6-byte
 191 bitmap packet has the following format:
 192
 193  byte 0:    0    1   x7   x6   x5   x4   x3   x2
 194  byte 1:    0   x1   x0   y4   y3   y2   y1   y0
 195  byte 2:    0    0    ?  x14  x13  x12  x11  x10
 196  byte 3:    0   x9   x8   y9   y8   y7   y6   y5
 197  byte 4:    0    0    0    0    0    0    0    0
 198  byte 5:    0    0    0    0    0    0    0  y10
 199
 200 There are several things worth noting here.
 201
 202  1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
 203     identify the first fragment of a bitmap packet.
 204
 205  2) The bitmaps represent the same data as in the v3 bitmap packets, although
 206     the packet layout is different.
 207
 208  3) There doesn't seem to be a count of the contact points anywhere in the v4
 209     protocol packets. Deriving a count of contact points must be done by
 210     analyzing the bitmaps.
 211
 212  4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
 213     MT position can only be updated for every third ST position update, and
 214     the count of contact points can only be updated every third packet as
 215     well.
 216
 217 So far no v4 devices with tracksticks have been encountered.
 218
 219 ALPS Absolute Mode - Protocol Version 5
 220 ---------------------------------------
 221 This is basically Protocol Version 3 but with different logic for packet
 222 decode.  It uses the same alps_process_touchpad_packet_v3 call with a
 223 specialized decode_fields function pointer to correctly interpret the
 224 packets.  This appears to only be used by the Dolphin devices.
 225
 226 For single-touch, the 6-byte packet format is:
 227
 228  byte 0:    1    1    0    0    1    0    0    0
 229  byte 1:    0   x6   x5   x4   x3   x2   x1   x0
 230  byte 2:    0   y6   y5   y4   y3   y2   y1   y0
 231  byte 3:    0    M    R    L    1    m    r    l
 232  byte 4:   y10  y9   y8   y7  x10   x9   x8   x7
 233  byte 5:    0   z6   z5   z4   z3   z2   z1   z0
 234
 235 For mt, the format is:
 236
 237  byte 0:    1    1    1    n3   1   n2   n1   x24
 238  byte 1:    1   y7   y6    y5  y4   y3   y2    y1
 239  byte 2:    ?   x2   x1   y12 y11  y10   y9    y8
 240  byte 3:    0  x23  x22   x21 x20  x19  x18   x17
 241  byte 4:    0   x9   x8    x7  x6   x5   x4    x3
 242  byte 5:    0  x16  x15   x14 x13  x12  x11   x10