Documentation/input/alps.txt

   1 ALPS Touchpad Protocol
   2 ----------------------
   3
   4 Introduction
   5 ------------
   6
   7 Currently the ALPS touchpad driver supports four protocol versions in use by
   8 ALPS touchpads, called versions 1, 2, 3, and 4. Information about the various
   9 protocol versions is contained in the following sections.
  10
  11 Detection
  12 ---------
  13
  14 All ALPS touchpads should respond to the "E6 report" command sequence:
  15 E8-E6-E6-E6-E9. An ALPS touchpad should respond with either 00-00-0A or
  16 00-00-64.
  17
  18 If the E6 report is successful, the touchpad model is identified using the "E7
  19 report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is
  20 matched against known models in the alps_model_data_array.
  21
  22 With protocol versions 3 and 4, the E7 report model signature is always
  23 73-02-64. To differentiate between these versions, the response from the
  24 "Enter Command Mode" sequence must be inspected as described below.
  25
  26 Command Mode
  27 ------------
  28
  29 Protocol versions 3 and 4 have a command mode that is used to read and write
  30 one-byte device registers in a 16-bit address space. The command sequence
  31 EC-EC-EC-E9 places the device in command mode, and the device will respond
  32 with 88-07 followed by a third byte. This third byte can be used to determine
  33 whether the devices uses the version 3 or 4 protocol.
  34
  35 To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad.
  36
  37 While in command mode, register addresses can be set by first sending a
  38 specific command, either EC for v3 devices or F5 for v4 devices. Then the
  39 address is sent one nibble at a time, where each nibble is encoded as a
  40 command with optional data. This enoding differs slightly between the v3 and
  41 v4 protocols.
  42
  43 Once an address has been set, the addressed register can be read by sending
  44 PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the
  45 address of the register being read, and the third contains the value of the
  46 register. Registers are written by writing the value one nibble at a time
  47 using the same encoding used for addresses.
  48
  49 Packet Format
  50 -------------
  51
  52 In the following tables, the following notation is used.
  53
  54  CAPITALS = stick, miniscules = touchpad
  55
  56 ?'s can have different meanings on different models, such as wheel rotation,
  57 extra buttons, stick buttons on a dualpoint, etc.
  58
  59 PS/2 packet format
  60 ------------------
  61
  62  byte 0:  0    0 YSGN XSGN    1    M    R    L
  63  byte 1: X7   X6   X5   X4   X3   X2   X1   X0
  64  byte 2: Y7   Y6   Y5   Y4   Y3   Y2   Y1   Y0
  65
  66 Note that the device never signals overflow condition.
  67
  68 ALPS Absolute Mode - Protocol Verion 1
  69 --------------------------------------
  70
  71  byte 0:  1    0    0    0    1   x9   x8   x7
  72  byte 1:  0   x6   x5   x4   x3   x2   x1   x0
  73  byte 2:  0    ?    ?    l    r    ?  fin  ges
  74  byte 3:  0    ?    ?    ?    ?   y9   y8   y7
  75  byte 4:  0   y6   y5   y4   y3   y2   y1   y0
  76  byte 5:  0   z6   z5   z4   z3   z2   z1   z0
  77
  78 ALPS Absolute Mode - Protocol Version 2
  79 ---------------------------------------
  80
  81  byte 0:  1    ?    ?    ?    1    ?    ?    ?
  82  byte 1:  0   x6   x5   x4   x3   x2   x1   x0
  83  byte 2:  0  x10   x9   x8   x7    ?  fin  ges
  84  byte 3:  0   y9   y8   y7    1    M    R    L
  85  byte 4:  0   y6   y5   y4   y3   y2   y1   y0
  86  byte 5:  0   z6   z5   z4   z3   z2   z1   z0
  87
  88 Dualpoint device -- interleaved packet format
  89 ---------------------------------------------
  90
  91  byte 0:    1    1    0    0    1    1    1    1
  92  byte 1:    0   x6   x5   x4   x3   x2   x1   x0
  93  byte 2:    0  x10   x9   x8   x7    0  fin  ges
  94  byte 3:    0    0 YSGN XSGN    1    1    1    1
  95  byte 4:   X7   X6   X5   X4   X3   X2   X1   X0
  96  byte 5:   Y7   Y6   Y5   Y4   Y3   Y2   Y1   Y0
  97  byte 6:    0   y9   y8   y7    1    m    r    l
  98  byte 7:    0   y6   y5   y4   y3   y2   y1   y0
  99  byte 8:    0   z6   z5   z4   z3   z2   z1   z0
 100
 101 ALPS Absolute Mode - Protocol Version 3
 102 ---------------------------------------
 103
 104 ALPS protocol version 3 has three different packet formats. The first two are
 105 associated with touchpad events, and the third is associatd with trackstick
 106 events.
 107
 108 The first type is the touchpad position packet.
 109
 110  byte 0:    1    ?   x1   x0    1    1    1    1
 111  byte 1:    0  x10   x9   x8   x7   x6   x5   x4
 112  byte 2:    0  y10   y9   y8   y7   y6   y5   y4
 113  byte 3:    0    M    R    L    1    m    r    l
 114  byte 4:    0   mt   x3   x2   y3   y2   y1   y0
 115  byte 5:    0   z6   z5   z4   z3   z2   z1   z0
 116
 117 Note that for some devices the trackstick buttons are reported in this packet,
 118 and on others it is reported in the trackstick packets.
 119
 120 The second packet type contains bitmaps representing the x and y axes. In the
 121 bitmaps a given bit is set if there is a finger covering that position on the
 122 given axis. Thus the bitmap packet can be used for low-resolution multi-touch
 123 data, although finger tracking is not possible.  This packet also encodes the
 124 number of contacts (f1 and f0 in the table below).
 125
 126  byte 0:    1    1   x1   x0    1    1    1    1
 127  byte 1:    0   x8   x7   x6   x5   x4   x3   x2
 128  byte 2:    0   y7   y6   y5   y4   y3   y2   y1
 129  byte 3:    0  y10   y9   y8    1    1    1    1
 130  byte 4:    0  x14  x13  x12  x11  x10   x9   y0
 131  byte 5:    0    1    ?    ?    ?    ?   f1   f0
 132
 133 This packet only appears after a position packet with the mt bit set, and
 134 ususally only appears when there are two or more contacts (although
 135 ocassionally it's seen with only a single contact).
 136
 137 The final v3 packet type is the trackstick packet.
 138
 139  byte 0:    1    1   x7   y7    1    1    1    1
 140  byte 1:    0   x6   x5   x4   x3   x2   x1   x0
 141  byte 2:    0   y6   y5   y4   y3   y2   y1   y0
 142  byte 3:    0    1    0    0    1    0    0    0
 143  byte 4:    0   z4   z3   z2   z1   z0    ?    ?
 144  byte 5:    0    0    1    1    1    1    1    1
 145
 146 ALPS Absolute Mode - Protocol Version 4
 147 ---------------------------------------
 148
 149 Protocol version 4 has an 8-byte packet format.
 150
 151  byte 0:    1    ?   x1   x0    1    1    1    1
 152  byte 1:    0  x10   x9   x8   x7   x6   x5   x4
 153  byte 2:    0  y10   y9   y8   y7   y6   y5   y4
 154  byte 3:    0    1   x3   x2   y3   y2   y1   y0
 155  byte 4:    0    ?    ?    ?    1    ?    r    l
 156  byte 5:    0   z6   z5   z4   z3   z2   z1   z0
 157  byte 6:    bitmap data (described below)
 158  byte 7:    bitmap data (described below)
 159
 160 The last two bytes represent a partial bitmap packet, with 3 full packets
 161 required to construct a complete bitmap packet.  Once assembled, the 6-byte
 162 bitmap packet has the following format:
 163
 164  byte 0:    0    1   x7   x6   x5   x4   x3   x2
 165  byte 1:    0   x1   x0   y4   y3   y2   y1   y0
 166  byte 2:    0    0    ?  x14  x13  x12  x11  x10
 167  byte 3:    0   x9   x8   y9   y8   y7   y6   y5
 168  byte 4:    0    0    0    0    0    0    0    0
 169  byte 5:    0    0    0    0    0    0    0  y10
 170
 171 There are several things worth noting here.
 172
 173  1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
 174     identify the first fragment of a bitmap packet.
 175
 176  2) The bitmaps represent the same data as in the v3 bitmap packets, although
 177     the packet layout is different.
 178
 179  3) There doesn't seem to be a count of the contact points anywhere in the v4
 180     protocol packets. Deriving a count of contact points must be done by
 181     analyzing the bitmaps.
 182
 183  4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
 184     MT position can only be updated for every third ST position update, and
 185     the count of contact points can only be updated every third packet as
 186     well.
 187
 188 So far no v4 devices with tracksticks have been encountered.