Seth Forshee | d4b347b | 2011-11-07 19:53:15 -0800 | [diff] [blame] | 1 | ALPS Touchpad Protocol |
| 2 | ---------------------- |
| 3 | |
| 4 | Introduction |
| 5 | ------------ |
dave turvene | 171fb58d | 2013-02-23 20:06:34 -0800 | [diff] [blame] | 6 | Currently the ALPS touchpad driver supports five protocol versions in use by |
| 7 | ALPS touchpads, called versions 1, 2, 3, 4 and 5. |
Seth Forshee | d4b347b | 2011-11-07 19:53:15 -0800 | [diff] [blame] | 8 | |
dave turvene | 171fb58d | 2013-02-23 20:06:34 -0800 | [diff] [blame] | 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. |
Seth Forshee | d4b347b | 2011-11-07 19:53:15 -0800 | [diff] [blame] | 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 |
Akio Idehara | 99c90ab | 2012-02-24 00:33:22 -0800 | [diff] [blame] | 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. |
Seth Forshee | d4b347b | 2011-11-07 19:53:15 -0800 | [diff] [blame] | 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 | |
dave turvene | 171fb58d | 2013-02-23 20:06:34 -0800 | [diff] [blame] | 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. |
Seth Forshee | 7cf801c | 2011-11-07 19:54:35 -0800 | [diff] [blame] | 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 | |
dave turvene | 171fb58d | 2013-02-23 20:06:34 -0800 | [diff] [blame] | 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 | |
Seth Forshee | d4b347b | 2011-11-07 19:53:15 -0800 | [diff] [blame] | 78 | Packet Format |
| 79 | ------------- |
| 80 | |
Seth Forshee | 7cf801c | 2011-11-07 19:54:35 -0800 | [diff] [blame] | 81 | In the following tables, the following notation is used. |
Seth Forshee | d4b347b | 2011-11-07 19:53:15 -0800 | [diff] [blame] | 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 | |
Seth Forshee | 7cf801c | 2011-11-07 19:54:35 -0800 | [diff] [blame] | 97 | ALPS Absolute Mode - Protocol Verion 1 |
| 98 | -------------------------------------- |
Seth Forshee | d4b347b | 2011-11-07 19:53:15 -0800 | [diff] [blame] | 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 | |
Seth Forshee | 7cf801c | 2011-11-07 19:54:35 -0800 | [diff] [blame] | 107 | ALPS Absolute Mode - Protocol Version 2 |
| 108 | --------------------------------------- |
Seth Forshee | d4b347b | 2011-11-07 19:53:15 -0800 | [diff] [blame] | 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 |
Seth Forshee | 7cf801c | 2011-11-07 19:54:35 -0800 | [diff] [blame] | 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 |
Masanari Iida | 40e4712 | 2012-03-04 23:16:11 +0900 | [diff] [blame] | 163 | usually only appears when there are two or more contacts (although |
Masanari Iida | 4e79162a | 2012-11-08 21:57:35 +0900 | [diff] [blame] | 164 | occasionally it's seen with only a single contact). |
Seth Forshee | 7cf801c | 2011-11-07 19:54:35 -0800 | [diff] [blame] | 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. |
dave turvene | 171fb58d | 2013-02-23 20:06:34 -0800 | [diff] [blame] | 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 |