Documentation/input/elantech.txt

   1 Elantech Touchpad Driver
   2 ========================
   3
   4         Copyright (C) 2007-2008 Arjan Opmeer <arjan@opmeer.net>
   5
   6         Extra information for hardware version 1 found and
   7         provided by Steve Havelka
   8
   9         Version 2 (EeePC) hardware support based on patches
  10         received from Woody at Xandros and forwarded to me
  11         by user StewieGriffin at the eeeuser.com forum
  12
  13
  14 Contents
  15 ~~~~~~~~
  16
  17  1. Introduction
  18  2. Extra knobs
  19  3. Hardware version 1
  20     3.1 Registers
  21     3.2 Native relative mode 4 byte packet format
  22     3.3 Native absolute mode 4 byte packet format
  23  4. Hardware version 2
  24     4.1 Registers
  25     4.2 Native absolute mode 6 byte packet format
  26         4.2.1 One finger touch
  27         4.2.2 Two finger touch
  28
  29
  30
  31 1. Introduction
  32    ~~~~~~~~~~~~
  33
  34 Currently the Linux Elantech touchpad driver is aware of two different
  35 hardware versions unimaginatively called version 1 and version 2. Version 1
  36 is found in "older" laptops and uses 4 bytes per packet. Version 2 seems to
  37 be introduced with the EeePC and uses 6 bytes per packet, and provides
  38 additional features such as position of two fingers, and width of the touch.
  39
  40 The driver tries to support both hardware versions and should be compatible
  41 with the Xorg Synaptics touchpad driver and its graphical configuration
  42 utilities.
  43
  44 Additionally the operation of the touchpad can be altered by adjusting the
  45 contents of some of its internal registers. These registers are represented
  46 by the driver as sysfs entries under /sys/bus/serio/drivers/psmouse/serio?
  47 that can be read from and written to.
  48
  49 Currently only the registers for hardware version 1 are somewhat understood.
  50 Hardware version 2 seems to use some of the same registers but it is not
  51 known whether the bits in the registers represent the same thing or might
  52 have changed their meaning.
  53
  54 On top of that, some register settings have effect only when the touchpad is
  55 in relative mode and not in absolute mode. As the Linux Elantech touchpad
  56 driver always puts the hardware into absolute mode not all information
  57 mentioned below can be used immediately. But because there is no freely
  58 available Elantech documentation the information is provided here anyway for
  59 completeness sake.
  60
  61
  62 /////////////////////////////////////////////////////////////////////////////
  63
  64
  65 2. Extra knobs
  66    ~~~~~~~~~~~
  67
  68 Currently the Linux Elantech touchpad driver provides two extra knobs under
  69 /sys/bus/serio/drivers/psmouse/serio? for the user.
  70
  71 * debug
  72
  73    Turn different levels of debugging ON or OFF.
  74
  75    By echoing "0" to this file all debugging will be turned OFF.
  76
  77    Currently a value of "1" will turn on some basic debugging and a value of
  78    "2" will turn on packet debugging. For hardware version 1 the default is
  79    OFF. For version 2 the default is "1".
  80
  81    Turning packet debugging on will make the driver dump every packet
  82    received to the syslog before processing it. Be warned that this can
  83    generate quite a lot of data!
  84
  85 * paritycheck
  86
  87    Turns parity checking ON or OFF.
  88
  89    By echoing "0" to this file parity checking will be turned OFF. Any
  90    non-zero value will turn it ON. For hardware version 1 the default is ON.
  91    For version 2 the default it is OFF.
  92
  93    Hardware version 1 provides basic data integrity verification by
  94    calculating a parity bit for the last 3 bytes of each packet. The driver
  95    can check these bits and reject any packet that appears corrupted. Using
  96    this knob you can bypass that check.
  97
  98    Hardware version 2 does not provide the same parity bits. Only some basic
  99    data consistency checking can be done. For now checking is disabled by
 100    default. Currently even turning it on will do nothing.
 101
 102 /////////////////////////////////////////////////////////////////////////////
 103
 104 3. Differentiating hardware versions
 105    =================================
 106
 107 To detect the hardware version, read the version number as param[0].param[1].param[2]
 108
 109  4 bytes version: (after the arrow is the name given in the Dell-provided driver)
 110  02.00.22 => EF013
 111  02.06.00 => EF019
 112 In the wild, there appear to be more versions, such as 00.01.64, 01.00.21,
 113 02.00.00, 02.00.04, 02.00.06.
 114
 115  6 bytes:
 116  02.00.30 => EF113
 117  02.08.00 => EF023
 118  02.08.XX => EF123
 119  02.0B.00 => EF215
 120  04.01.XX => Scroll_EF051
 121  04.02.XX => EF051
 122 In the wild, there appear to be more versions, such as 04.03.01, 04.04.11. There
 123 appears to be almost no difference, except for EF113, which does not report
 124 pressure/width and has different data consistency checks.
 125
 126 Probably all the versions with param[0] <= 01 can be considered as
 127 4 bytes/firmware 1. The versions < 02.08.00, with the exception of 02.00.30, as
 128 4 bytes/firmware 2. Everything >= 02.08.00 can be considered as 6 bytes.
 129
 130 /////////////////////////////////////////////////////////////////////////////
 131
 132 4. Hardware version 1
 133    ==================
 134
 135 4.1 Registers
 136     ~~~~~~~~~
 137
 138 By echoing a hexadecimal value to a register it contents can be altered.
 139
 140 For example:
 141
 142    echo -n 0x16 > reg_10
 143
 144 * reg_10
 145
 146    bit   7   6   5   4   3   2   1   0
 147          B   C   T   D   L   A   S   E
 148
 149          E: 1 = enable smart edges unconditionally
 150          S: 1 = enable smart edges only when dragging
 151          A: 1 = absolute mode (needs 4 byte packets, see reg_11)
 152          L: 1 = enable drag lock (see reg_22)
 153          D: 1 = disable dynamic resolution
 154          T: 1 = disable tapping
 155          C: 1 = enable corner tap
 156          B: 1 = swap left and right button
 157
 158 * reg_11
 159
 160    bit   7   6   5   4   3   2   1   0
 161          1   0   0   H   V   1   F   P
 162
 163          P: 1 = enable parity checking for relative mode
 164          F: 1 = enable native 4 byte packet mode
 165          V: 1 = enable vertical scroll area
 166          H: 1 = enable horizontal scroll area
 167
 168 * reg_20
 169
 170          single finger width?
 171
 172 * reg_21
 173
 174          scroll area width (small: 0x40 ... wide: 0xff)
 175
 176 * reg_22
 177
 178          drag lock time out (short: 0x14 ... long: 0xfe;
 179                              0xff = tap again to release)
 180
 181 * reg_23
 182
 183          tap make timeout?
 184
 185 * reg_24
 186
 187          tap release timeout?
 188
 189 * reg_25
 190
 191          smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast)
 192
 193 * reg_26
 194
 195          smart edge activation area width?
 196
 197
 198 4.2 Native relative mode 4 byte packet format
 199     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 200
 201 byte 0:
 202    bit   7   6   5   4   3   2   1   0
 203          c   c  p2  p1   1   M   R   L
 204
 205          L, R, M = 1 when Left, Right, Middle mouse button pressed
 206             some models have M as byte 3 odd parity bit
 207          when parity checking is enabled (reg_11, P = 1):
 208             p1..p2 = byte 1 and 2 odd parity bit
 209          c = 1 when corner tap detected
 210
 211 byte 1:
 212    bit   7   6   5   4   3   2   1   0
 213         dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0
 214
 215          dx7..dx0 = x movement;   positive = right, negative = left
 216          byte 1 = 0xf0 when corner tap detected
 217
 218 byte 2:
 219    bit   7   6   5   4   3   2   1   0
 220         dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0
 221
 222          dy7..dy0 = y movement;   positive = up,    negative = down
 223
 224 byte 3:
 225    parity checking enabled (reg_11, P = 1):
 226
 227       bit   7   6   5   4   3   2   1   0
 228             w   h  n1  n0  ds3 ds2 ds1 ds0
 229
 230             normally:
 231                ds3..ds0 = scroll wheel amount and direction
 232                           positive = down or left
 233                           negative = up or right
 234             when corner tap detected:
 235                ds0 = 1 when top right corner tapped
 236                ds1 = 1 when bottom right corner tapped
 237                ds2 = 1 when bottom left corner tapped
 238                ds3 = 1 when top left corner tapped
 239             n1..n0 = number of fingers on touchpad
 240                only models with firmware 2.x report this, models with
 241                firmware 1.x seem to map one, two and three finger taps
 242                directly to L, M and R mouse buttons
 243             h = 1 when horizontal scroll action
 244             w = 1 when wide finger touch?
 245
 246    otherwise (reg_11, P = 0):
 247
 248       bit   7   6   5   4   3   2   1   0
 249            ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0
 250
 251             ds7..ds0 = vertical scroll amount and direction
 252                        negative = up
 253                        positive = down
 254
 255
 256 4.3 Native absolute mode 4 byte packet format
 257     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 258
 259 EF013 and EF019 have a special behaviour (due to a bug in the firmware?), and
 260 when 1 finger is touching, the first 2 position reports must be discarded.
 261 This counting is reset whenever a different number of fingers is reported.
 262
 263 byte 0:
 264    firmware version 1.x:
 265
 266       bit   7   6   5   4   3   2   1   0
 267             D   U  p1  p2   1  p3   R   L
 268
 269             L, R = 1 when Left, Right mouse button pressed
 270             p1..p3 = byte 1..3 odd parity bit
 271             D, U = 1 when rocker switch pressed Up, Down
 272
 273    firmware version 2.x:
 274
 275       bit   7   6   5   4   3   2   1   0
 276            n1  n0  p2  p1   1  p3   R   L
 277
 278             L, R = 1 when Left, Right mouse button pressed
 279             p1..p3 = byte 1..3 odd parity bit
 280             n1..n0 = number of fingers on touchpad
 281
 282 byte 1:
 283    firmware version 1.x:
 284
 285       bit   7   6   5   4   3   2   1   0
 286             f   0  th  tw  x9  x8  y9  y8
 287
 288             tw = 1 when two finger touch
 289             th = 1 when three finger touch
 290             f  = 1 when finger touch
 291
 292    firmware version 2.x:
 293
 294       bit   7   6   5   4   3   2   1   0
 295             .   .   .   .  x9  x8  y9  y8
 296
 297 byte 2:
 298    bit   7   6   5   4   3   2   1   0
 299         x7  x6  x5  x4  x3  x2  x1  x0
 300
 301          x9..x0 = absolute x value (horizontal)
 302
 303 byte 3:
 304    bit   7   6   5   4   3   2   1   0
 305         y7  y6  y5  y4  y3  y2  y1  y0
 306
 307          y9..y0 = absolute y value (vertical)
 308
 309
 310 /////////////////////////////////////////////////////////////////////////////
 311
 312
 313 5. Hardware version 2
 314    ==================
 315
 316
 317 5.1 Registers
 318     ~~~~~~~~~
 319
 320 By echoing a hexadecimal value to a register it contents can be altered.
 321
 322 For example:
 323
 324    echo -n 0x56 > reg_10
 325
 326 * reg_10
 327
 328    bit   7   6   5   4   3   2   1   0
 329          0   1   0   1   0   1   D   0
 330
 331          D: 1 = enable drag and drop
 332
 333 * reg_11
 334
 335    bit   7   6   5   4   3   2   1   0
 336          1   0   0   0   S   0   1   0
 337
 338          S: 1 = enable vertical scroll
 339
 340 * reg_21
 341
 342          unknown (0x00)
 343
 344 * reg_22
 345
 346          drag and drop release time out (short: 0x70 ... long 0x7e;
 347                                    0x7f = never i.e. tap again to release)
 348
 349
 350 5.2 Native absolute mode 6 byte packet format
 351     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 352 5.2.1 Parity checking and packet re-synchronization
 353 There is no parity checking, however some consistency checks can be performed.
 354
 355 For instance for EF113:
 356         SA1= packet[0];
 357         A1 = packet[1];
 358         B1 = packet[2];
 359         SB1= packet[3];
 360         C1 = packet[4];
 361         D1 = packet[5];
 362         if( (((SA1 & 0x3C) != 0x3C) && ((SA1 & 0xC0) != 0x80)) || // check Byte 1
 363             (((SA1 & 0x0C) != 0x0C) && ((SA1 & 0xC0) == 0x80)) || // check Byte 1 (one finger pressed)
 364             (((SA1 & 0xC0) != 0x80) && (( A1 & 0xF0) != 0x00)) || // check Byte 2
 365             (((SB1 & 0x3E) != 0x38) && ((SA1 & 0xC0) != 0x80)) || // check Byte 4
 366             (((SB1 & 0x0E) != 0x08) && ((SA1 & 0xC0) == 0x80)) || // check Byte 4 (one finger pressed)
 367             (((SA1 & 0xC0) != 0x80) && (( C1 & 0xF0) != 0x00))  ) // check Byte 5
 368                 // error detected
 369
 370 For all the other ones, there are just a few constant bits:
 371         if( ((packet[0] & 0x0C) != 0x04) ||
 372             ((packet[3] & 0x0f) != 0x02) )
 373                 // error detected
 374
 375
 376 In case an error is detected, all the packets are shifted by one (and packet[0] is discarded).
 377
 378 5.2.1 One/Three finger touch
 379       ~~~~~~~~~~~~~~~~
 380
 381 byte 0:
 382
 383    bit   7   6   5   4   3   2   1   0
 384          n1  n0  w3  w2   .   .   R   L
 385
 386          L, R = 1 when Left, Right mouse button pressed
 387          n1..n0 = numbers of fingers on touchpad
 388
 389 byte 1:
 390
 391    bit   7   6   5   4   3   2   1   0
 392          p7  p6  p5  p4  .  x10 x9  x8
 393
 394 byte 2:
 395
 396    bit   7   6   5   4   3   2   1   0
 397          x7  x6  x5  x4  x3  x2  x1  x0
 398
 399          x10..x0 = absolute x value (horizontal)
 400
 401 byte 3:
 402
 403    bit   7   6   5   4   3   2   1   0
 404          n4  vf  w1  w0   .   .   .  b2
 405
 406          n4 = set if more than 3 fingers (only in 3 fingers mode)
 407          vf = a kind of flag ? (only on EF123, 0 when finger is over one
 408               of the buttons, 1 otherwise)
 409          w3..w0 = width of the finger touch (not EF113)
 410          b2 (on EF113 only, 0 otherwise), b2.R.L indicates one button pressed:
 411                 0 = none
 412                 1 = Left
 413                 2 = Right
 414                 3 = Middle (Left and Right)
 415                 4 = Forward
 416                 5 = Back
 417                 6 = Another one
 418                 7 = Another one
 419
 420 byte 4:
 421
 422    bit   7   6   5   4   3   2   1   0
 423         p3  p1  p2  p0   .   .  y9  y8
 424
 425          p7..p0 = pressure (not EF113)
 426
 427 byte 5:
 428
 429    bit   7   6   5   4   3   2   1   0
 430         y7  y6  y5  y4  y3  y2  y1  y0
 431
 432          y9..y0 = absolute y value (vertical)
 433
 434
 435 4.2.2 Two finger touch
 436       ~~~~~~~~~~~~~~~~
 437
 438 Note that the two pairs of coordinates are not exactly the coordinates of the
 439 two fingers, but only the pair of the lower-left and upper-right coordinates.
 440 So the actual fingers might be situated on the other diagonal of the square
 441 defined by these two points.
 442
 443 byte 0:
 444
 445    bit   7   6   5   4   3   2   1   0
 446         n1  n0  ay8 ax8  .   .   R   L
 447
 448          L, R = 1 when Left, Right mouse button pressed
 449          n1..n0 = numbers of fingers on touchpad
 450
 451 byte 1:
 452
 453    bit   7   6   5   4   3   2   1   0
 454         ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0
 455
 456          ax8..ax0 = lower-left finger absolute x value
 457
 458 byte 2:
 459
 460    bit   7   6   5   4   3   2   1   0
 461         ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0
 462
 463          ay8..ay0 = lower-left finger absolute y value
 464
 465 byte 3:
 466
 467    bit   7   6   5   4   3   2   1   0
 468          .   .  by8 bx8  .   .   .   .
 469
 470 byte 4:
 471
 472    bit   7   6   5   4   3   2   1   0
 473         bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0
 474
 475          bx8..bx0 = upper-right finger absolute x value
 476
 477 byte 5:
 478
 479    bit   7   6   5   4   3   2   1   0
 480         by7 by8 by5 by4 by3 by2 by1 by0
 481
 482          by8..by0 = upper-right finger absolute y value