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