1Elantech 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 14Contents 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 7. Hardware version 4 36 7.1 Registers 37 7.2 Native absolute mode 6 byte packet format 38 7.2.1 Status packet 39 7.2.2 Head packet 40 7.2.3 Motion packet 41 42 43 441. Introduction 45 ~~~~~~~~~~~~ 46 47Currently the Linux Elantech touchpad driver is aware of two different 48hardware versions unimaginatively called version 1 and version 2. Version 1 49is found in "older" laptops and uses 4 bytes per packet. Version 2 seems to 50be introduced with the EeePC and uses 6 bytes per packet, and provides 51additional features such as position of two fingers, and width of the touch. 52 53The driver tries to support both hardware versions and should be compatible 54with the Xorg Synaptics touchpad driver and its graphical configuration 55utilities. 56 57Additionally the operation of the touchpad can be altered by adjusting the 58contents of some of its internal registers. These registers are represented 59by the driver as sysfs entries under /sys/bus/serio/drivers/psmouse/serio? 60that can be read from and written to. 61 62Currently only the registers for hardware version 1 are somewhat understood. 63Hardware version 2 seems to use some of the same registers but it is not 64known whether the bits in the registers represent the same thing or might 65have changed their meaning. 66 67On top of that, some register settings have effect only when the touchpad is 68in relative mode and not in absolute mode. As the Linux Elantech touchpad 69driver always puts the hardware into absolute mode not all information 70mentioned below can be used immediately. But because there is no freely 71available Elantech documentation the information is provided here anyway for 72completeness sake. 73 74 75///////////////////////////////////////////////////////////////////////////// 76 77 782. Extra knobs 79 ~~~~~~~~~~~ 80 81Currently the Linux Elantech touchpad driver provides two extra knobs under 82/sys/bus/serio/drivers/psmouse/serio? for the user. 83 84* debug 85 86 Turn different levels of debugging ON or OFF. 87 88 By echoing "0" to this file all debugging will be turned OFF. 89 90 Currently a value of "1" will turn on some basic debugging and a value of 91 "2" will turn on packet debugging. For hardware version 1 the default is 92 OFF. For version 2 the default is "1". 93 94 Turning packet debugging on will make the driver dump every packet 95 received to the syslog before processing it. Be warned that this can 96 generate quite a lot of data! 97 98* paritycheck 99 100 Turns parity checking ON or OFF. 101 102 By echoing "0" to this file parity checking will be turned OFF. Any 103 non-zero value will turn it ON. For hardware version 1 the default is ON. 104 For version 2 the default it is OFF. 105 106 Hardware version 1 provides basic data integrity verification by 107 calculating a parity bit for the last 3 bytes of each packet. The driver 108 can check these bits and reject any packet that appears corrupted. Using 109 this knob you can bypass that check. 110 111 Hardware version 2 does not provide the same parity bits. Only some basic 112 data consistency checking can be done. For now checking is disabled by 113 default. Currently even turning it on will do nothing. 114 115///////////////////////////////////////////////////////////////////////////// 116 1173. Differentiating hardware versions 118 ================================= 119 120To detect the hardware version, read the version number as param[0].param[1].param[2] 121 122 4 bytes version: (after the arrow is the name given in the Dell-provided driver) 123 02.00.22 => EF013 124 02.06.00 => EF019 125In the wild, there appear to be more versions, such as 00.01.64, 01.00.21, 12602.00.00, 02.00.04, 02.00.06. 127 128 6 bytes: 129 02.00.30 => EF113 130 02.08.00 => EF023 131 02.08.XX => EF123 132 02.0B.00 => EF215 133 04.01.XX => Scroll_EF051 134 04.02.XX => EF051 135In the wild, there appear to be more versions, such as 04.03.01, 04.04.11. There 136appears to be almost no difference, except for EF113, which does not report 137pressure/width and has different data consistency checks. 138 139Probably all the versions with param[0] <= 01 can be considered as 1404 bytes/firmware 1. The versions < 02.08.00, with the exception of 02.00.30, as 1414 bytes/firmware 2. Everything >= 02.08.00 can be considered as 6 bytes. 142 143///////////////////////////////////////////////////////////////////////////// 144 1454. Hardware version 1 146 ================== 147 1484.1 Registers 149 ~~~~~~~~~ 150 151By echoing a hexadecimal value to a register it contents can be altered. 152 153For example: 154 155 echo -n 0x16 > reg_10 156 157* reg_10 158 159 bit 7 6 5 4 3 2 1 0 160 B C T D L A S E 161 162 E: 1 = enable smart edges unconditionally 163 S: 1 = enable smart edges only when dragging 164 A: 1 = absolute mode (needs 4 byte packets, see reg_11) 165 L: 1 = enable drag lock (see reg_22) 166 D: 1 = disable dynamic resolution 167 T: 1 = disable tapping 168 C: 1 = enable corner tap 169 B: 1 = swap left and right button 170 171* reg_11 172 173 bit 7 6 5 4 3 2 1 0 174 1 0 0 H V 1 F P 175 176 P: 1 = enable parity checking for relative mode 177 F: 1 = enable native 4 byte packet mode 178 V: 1 = enable vertical scroll area 179 H: 1 = enable horizontal scroll area 180 181* reg_20 182 183 single finger width? 184 185* reg_21 186 187 scroll area width (small: 0x40 ... wide: 0xff) 188 189* reg_22 190 191 drag lock time out (short: 0x14 ... long: 0xfe; 192 0xff = tap again to release) 193 194* reg_23 195 196 tap make timeout? 197 198* reg_24 199 200 tap release timeout? 201 202* reg_25 203 204 smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast) 205 206* reg_26 207 208 smart edge activation area width? 209 210 2114.2 Native relative mode 4 byte packet format 212 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 213 214byte 0: 215 bit 7 6 5 4 3 2 1 0 216 c c p2 p1 1 M R L 217 218 L, R, M = 1 when Left, Right, Middle mouse button pressed 219 some models have M as byte 3 odd parity bit 220 when parity checking is enabled (reg_11, P = 1): 221 p1..p2 = byte 1 and 2 odd parity bit 222 c = 1 when corner tap detected 223 224byte 1: 225 bit 7 6 5 4 3 2 1 0 226 dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0 227 228 dx7..dx0 = x movement; positive = right, negative = left 229 byte 1 = 0xf0 when corner tap detected 230 231byte 2: 232 bit 7 6 5 4 3 2 1 0 233 dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0 234 235 dy7..dy0 = y movement; positive = up, negative = down 236 237byte 3: 238 parity checking enabled (reg_11, P = 1): 239 240 bit 7 6 5 4 3 2 1 0 241 w h n1 n0 ds3 ds2 ds1 ds0 242 243 normally: 244 ds3..ds0 = scroll wheel amount and direction 245 positive = down or left 246 negative = up or right 247 when corner tap detected: 248 ds0 = 1 when top right corner tapped 249 ds1 = 1 when bottom right corner tapped 250 ds2 = 1 when bottom left corner tapped 251 ds3 = 1 when top left corner tapped 252 n1..n0 = number of fingers on touchpad 253 only models with firmware 2.x report this, models with 254 firmware 1.x seem to map one, two and three finger taps 255 directly to L, M and R mouse buttons 256 h = 1 when horizontal scroll action 257 w = 1 when wide finger touch? 258 259 otherwise (reg_11, P = 0): 260 261 bit 7 6 5 4 3 2 1 0 262 ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0 263 264 ds7..ds0 = vertical scroll amount and direction 265 negative = up 266 positive = down 267 268 2694.3 Native absolute mode 4 byte packet format 270 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 271 272EF013 and EF019 have a special behaviour (due to a bug in the firmware?), and 273when 1 finger is touching, the first 2 position reports must be discarded. 274This counting is reset whenever a different number of fingers is reported. 275 276byte 0: 277 firmware version 1.x: 278 279 bit 7 6 5 4 3 2 1 0 280 D U p1 p2 1 p3 R L 281 282 L, R = 1 when Left, Right mouse button pressed 283 p1..p3 = byte 1..3 odd parity bit 284 D, U = 1 when rocker switch pressed Up, Down 285 286 firmware version 2.x: 287 288 bit 7 6 5 4 3 2 1 0 289 n1 n0 p2 p1 1 p3 R L 290 291 L, R = 1 when Left, Right mouse button pressed 292 p1..p3 = byte 1..3 odd parity bit 293 n1..n0 = number of fingers on touchpad 294 295byte 1: 296 firmware version 1.x: 297 298 bit 7 6 5 4 3 2 1 0 299 f 0 th tw x9 x8 y9 y8 300 301 tw = 1 when two finger touch 302 th = 1 when three finger touch 303 f = 1 when finger touch 304 305 firmware version 2.x: 306 307 bit 7 6 5 4 3 2 1 0 308 . . . . x9 x8 y9 y8 309 310byte 2: 311 bit 7 6 5 4 3 2 1 0 312 x7 x6 x5 x4 x3 x2 x1 x0 313 314 x9..x0 = absolute x value (horizontal) 315 316byte 3: 317 bit 7 6 5 4 3 2 1 0 318 y7 y6 y5 y4 y3 y2 y1 y0 319 320 y9..y0 = absolute y value (vertical) 321 322 323///////////////////////////////////////////////////////////////////////////// 324 325 3265. Hardware version 2 327 ================== 328 329 3305.1 Registers 331 ~~~~~~~~~ 332 333By echoing a hexadecimal value to a register it contents can be altered. 334 335For example: 336 337 echo -n 0x56 > reg_10 338 339* reg_10 340 341 bit 7 6 5 4 3 2 1 0 342 0 1 0 1 0 1 D 0 343 344 D: 1 = enable drag and drop 345 346* reg_11 347 348 bit 7 6 5 4 3 2 1 0 349 1 0 0 0 S 0 1 0 350 351 S: 1 = enable vertical scroll 352 353* reg_21 354 355 unknown (0x00) 356 357* reg_22 358 359 drag and drop release time out (short: 0x70 ... long 0x7e; 360 0x7f = never i.e. tap again to release) 361 362 3635.2 Native absolute mode 6 byte packet format 364 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3655.2.1 Parity checking and packet re-synchronization 366There is no parity checking, however some consistency checks can be performed. 367 368For instance for EF113: 369 SA1= packet[0]; 370 A1 = packet[1]; 371 B1 = packet[2]; 372 SB1= packet[3]; 373 C1 = packet[4]; 374 D1 = packet[5]; 375 if( (((SA1 & 0x3C) != 0x3C) && ((SA1 & 0xC0) != 0x80)) || // check Byte 1 376 (((SA1 & 0x0C) != 0x0C) && ((SA1 & 0xC0) == 0x80)) || // check Byte 1 (one finger pressed) 377 (((SA1 & 0xC0) != 0x80) && (( A1 & 0xF0) != 0x00)) || // check Byte 2 378 (((SB1 & 0x3E) != 0x38) && ((SA1 & 0xC0) != 0x80)) || // check Byte 4 379 (((SB1 & 0x0E) != 0x08) && ((SA1 & 0xC0) == 0x80)) || // check Byte 4 (one finger pressed) 380 (((SA1 & 0xC0) != 0x80) && (( C1 & 0xF0) != 0x00)) ) // check Byte 5 381 // error detected 382 383For all the other ones, there are just a few constant bits: 384 if( ((packet[0] & 0x0C) != 0x04) || 385 ((packet[3] & 0x0f) != 0x02) ) 386 // error detected 387 388 389In case an error is detected, all the packets are shifted by one (and packet[0] is discarded). 390 3915.2.2 One/Three finger touch 392 ~~~~~~~~~~~~~~~~ 393 394byte 0: 395 396 bit 7 6 5 4 3 2 1 0 397 n1 n0 w3 w2 . . R L 398 399 L, R = 1 when Left, Right mouse button pressed 400 n1..n0 = number of fingers on touchpad 401 402byte 1: 403 404 bit 7 6 5 4 3 2 1 0 405 p7 p6 p5 p4 x11 x10 x9 x8 406 407byte 2: 408 409 bit 7 6 5 4 3 2 1 0 410 x7 x6 x5 x4 x3 x2 x1 x0 411 412 x11..x0 = absolute x value (horizontal) 413 414byte 3: 415 416 bit 7 6 5 4 3 2 1 0 417 n4 vf w1 w0 . . . b2 418 419 n4 = set if more than 3 fingers (only in 3 fingers mode) 420 vf = a kind of flag ? (only on EF123, 0 when finger is over one 421 of the buttons, 1 otherwise) 422 w3..w0 = width of the finger touch (not EF113) 423 b2 (on EF113 only, 0 otherwise), b2.R.L indicates one button pressed: 424 0 = none 425 1 = Left 426 2 = Right 427 3 = Middle (Left and Right) 428 4 = Forward 429 5 = Back 430 6 = Another one 431 7 = Another one 432 433byte 4: 434 435 bit 7 6 5 4 3 2 1 0 436 p3 p1 p2 p0 y11 y10 y9 y8 437 438 p7..p0 = pressure (not EF113) 439 440byte 5: 441 442 bit 7 6 5 4 3 2 1 0 443 y7 y6 y5 y4 y3 y2 y1 y0 444 445 y11..y0 = absolute y value (vertical) 446 447 4485.2.3 Two finger touch 449 ~~~~~~~~~~~~~~~~ 450 451Note that the two pairs of coordinates are not exactly the coordinates of the 452two fingers, but only the pair of the lower-left and upper-right coordinates. 453So the actual fingers might be situated on the other diagonal of the square 454defined by these two points. 455 456byte 0: 457 458 bit 7 6 5 4 3 2 1 0 459 n1 n0 ay8 ax8 . . R L 460 461 L, R = 1 when Left, Right mouse button pressed 462 n1..n0 = number of fingers on touchpad 463 464byte 1: 465 466 bit 7 6 5 4 3 2 1 0 467 ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0 468 469 ax8..ax0 = lower-left finger absolute x value 470 471byte 2: 472 473 bit 7 6 5 4 3 2 1 0 474 ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0 475 476 ay8..ay0 = lower-left finger absolute y value 477 478byte 3: 479 480 bit 7 6 5 4 3 2 1 0 481 . . by8 bx8 . . . . 482 483byte 4: 484 485 bit 7 6 5 4 3 2 1 0 486 bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0 487 488 bx8..bx0 = upper-right finger absolute x value 489 490byte 5: 491 492 bit 7 6 5 4 3 2 1 0 493 by7 by8 by5 by4 by3 by2 by1 by0 494 495 by8..by0 = upper-right finger absolute y value 496 497///////////////////////////////////////////////////////////////////////////// 498 4996. Hardware version 3 500 ================== 501 5026.1 Registers 503 ~~~~~~~~~ 504* reg_10 505 506 bit 7 6 5 4 3 2 1 0 507 0 0 0 0 0 0 0 A 508 509 A: 1 = enable absolute tracking 510 5116.2 Native absolute mode 6 byte packet format 512 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5131 and 3 finger touch shares the same 6-byte packet format, except that 5143 finger touch only reports the position of the center of all three fingers. 515 516Firmware would send 12 bytes of data for 2 finger touch. 517 518Note on debounce: 519In case the box has unstable power supply or other electricity issues, or 520when number of finger changes, F/W would send "debounce packet" to inform 521driver that the hardware is in debounce status. 522The debouce packet has the following signature: 523 byte 0: 0xc4 524 byte 1: 0xff 525 byte 2: 0xff 526 byte 3: 0x02 527 byte 4: 0xff 528 byte 5: 0xff 529When we encounter this kind of packet, we just ignore it. 530 5316.2.1 One/Three finger touch 532 ~~~~~~~~~~~~~~~~~~~~~~ 533 534byte 0: 535 536 bit 7 6 5 4 3 2 1 0 537 n1 n0 w3 w2 0 1 R L 538 539 L, R = 1 when Left, Right mouse button pressed 540 n1..n0 = number of fingers on touchpad 541 542byte 1: 543 544 bit 7 6 5 4 3 2 1 0 545 p7 p6 p5 p4 x11 x10 x9 x8 546 547byte 2: 548 549 bit 7 6 5 4 3 2 1 0 550 x7 x6 x5 x4 x3 x2 x1 x0 551 552 x11..x0 = absolute x value (horizontal) 553 554byte 3: 555 556 bit 7 6 5 4 3 2 1 0 557 0 0 w1 w0 0 0 1 0 558 559 w3..w0 = width of the finger touch 560 561byte 4: 562 563 bit 7 6 5 4 3 2 1 0 564 p3 p1 p2 p0 y11 y10 y9 y8 565 566 p7..p0 = pressure 567 568byte 5: 569 570 bit 7 6 5 4 3 2 1 0 571 y7 y6 y5 y4 y3 y2 y1 y0 572 573 y11..y0 = absolute y value (vertical) 574 5756.2.2 Two finger touch 576 ~~~~~~~~~~~~~~~~ 577 578The packet format is exactly the same for two finger touch, except the hardware 579sends two 6 byte packets. The first packet contains data for the first finger, 580the second packet has data for the second finger. So for two finger touch a 581total of 12 bytes are sent. 582 583///////////////////////////////////////////////////////////////////////////// 584 5857. Hardware version 4 586 ================== 587 5887.1 Registers 589 ~~~~~~~~~ 590* reg_07 591 592 bit 7 6 5 4 3 2 1 0 593 0 0 0 0 0 0 0 A 594 595 A: 1 = enable absolute tracking 596 5977.2 Native absolute mode 6 byte packet format 598 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 599v4 hardware is a true multitouch touchpad, capable of tracking up to 5 fingers. 600Unfortunately, due to PS/2's limited bandwidth, its packet format is rather 601complex. 602 603Whenever the numbers or identities of the fingers changes, the hardware sends a 604status packet to indicate how many and which fingers is on touchpad, followed by 605head packets or motion packets. A head packet contains data of finger id, finger 606position (absolute x, y values), width, and pressure. A motion packet contains 607two fingers' position delta. 608 609For example, when status packet tells there are 2 fingers on touchpad, then we 610can expect two following head packets. If the finger status doesn't change, 611the following packets would be motion packets, only sending delta of finger 612position, until we receive a status packet. 613 614One exception is one finger touch. when a status packet tells us there is only 615one finger, the hardware would just send head packets afterwards. 616 6177.2.1 Status packet 618 ~~~~~~~~~~~~~ 619 620byte 0: 621 622 bit 7 6 5 4 3 2 1 0 623 . . . . 0 1 R L 624 625 L, R = 1 when Left, Right mouse button pressed 626 627byte 1: 628 629 bit 7 6 5 4 3 2 1 0 630 . . . ft4 ft3 ft2 ft1 ft0 631 632 ft4 ft3 ft2 ft1 ft0 ftn = 1 when finger n is on touchpad 633 634byte 2: not used 635 636byte 3: 637 638 bit 7 6 5 4 3 2 1 0 639 . . . 1 0 0 0 0 640 641 constant bits 642 643byte 4: 644 645 bit 7 6 5 4 3 2 1 0 646 p . . . . . . . 647 648 p = 1 for palm 649 650byte 5: not used 651 6527.2.2 Head packet 653 ~~~~~~~~~~~ 654 655byte 0: 656 657 bit 7 6 5 4 3 2 1 0 658 w3 w2 w1 w0 0 1 R L 659 660 L, R = 1 when Left, Right mouse button pressed 661 w3..w0 = finger width (spans how many trace lines) 662 663byte 1: 664 665 bit 7 6 5 4 3 2 1 0 666 p7 p6 p5 p4 x11 x10 x9 x8 667 668byte 2: 669 670 bit 7 6 5 4 3 2 1 0 671 x7 x6 x5 x4 x3 x2 x1 x0 672 673 x11..x0 = absolute x value (horizontal) 674 675byte 3: 676 677 bit 7 6 5 4 3 2 1 0 678 id2 id1 id0 1 0 0 0 1 679 680 id2..id0 = finger id 681 682byte 4: 683 684 bit 7 6 5 4 3 2 1 0 685 p3 p1 p2 p0 y11 y10 y9 y8 686 687 p7..p0 = pressure 688 689byte 5: 690 691 bit 7 6 5 4 3 2 1 0 692 y7 y6 y5 y4 y3 y2 y1 y0 693 694 y11..y0 = absolute y value (vertical) 695 6967.2.3 Motion packet 697 ~~~~~~~~~~~~~ 698 699byte 0: 700 701 bit 7 6 5 4 3 2 1 0 702 id2 id1 id0 w 0 1 R L 703 704 L, R = 1 when Left, Right mouse button pressed 705 id2..id0 = finger id 706 w = 1 when delta overflows (> 127 or < -128), in this case 707 firmware sends us (delta x / 5) and (delta y / 5) 708 709byte 1: 710 711 bit 7 6 5 4 3 2 1 0 712 x7 x6 x5 x4 x3 x2 x1 x0 713 714 x7..x0 = delta x (two's complement) 715 716byte 2: 717 718 bit 7 6 5 4 3 2 1 0 719 y7 y6 y5 y4 y3 y2 y1 y0 720 721 y7..y0 = delta y (two's complement) 722 723byte 3: 724 725 bit 7 6 5 4 3 2 1 0 726 id2 id1 id0 1 0 0 1 0 727 728 id2..id0 = finger id 729 730byte 4: 731 732 bit 7 6 5 4 3 2 1 0 733 x7 x6 x5 x4 x3 x2 x1 x0 734 735 x7..x0 = delta x (two's complement) 736 737byte 5: 738 739 bit 7 6 5 4 3 2 1 0 740 y7 y6 y5 y4 y3 y2 y1 y0 741 742 y7..y0 = delta y (two's complement) 743 744 byte 0 ~ 2 for one finger 745 byte 3 ~ 5 for another 746