842 lines · plain
1Elantech Touchpad Driver2========================3 4 Copyright (C) 2007-2008 Arjan Opmeer <arjan@opmeer.net>5 6 Extra information for hardware version 1 found and7 provided by Steve Havelka8 9 Version 2 (EeePC) hardware support based on patches10 received from Woody at Xandros and forwarded to me11 by user StewieGriffin at the eeeuser.com forum12 13.. Contents14 15 1. Introduction16 2. Extra knobs17 3. Differentiating hardware versions18 4. Hardware version 119 4.1 Registers20 4.2 Native relative mode 4 byte packet format21 4.3 Native absolute mode 4 byte packet format22 5. Hardware version 223 5.1 Registers24 5.2 Native absolute mode 6 byte packet format25 5.2.1 Parity checking and packet re-synchronization26 5.2.2 One/Three finger touch27 5.2.3 Two finger touch28 6. Hardware version 329 6.1 Registers30 6.2 Native absolute mode 6 byte packet format31 6.2.1 One/Three finger touch32 6.2.2 Two finger touch33 7. Hardware version 434 7.1 Registers35 7.2 Native absolute mode 6 byte packet format36 7.2.1 Status packet37 7.2.2 Head packet38 7.2.3 Motion packet39 8. Trackpoint (for Hardware version 3 and 4)40 8.1 Registers41 8.2 Native relative mode 6 byte packet format42 8.2.1 Status Packet43 44 45 46Introduction47~~~~~~~~~~~~48 49Currently the Linux Elantech touchpad driver is aware of four different50hardware versions unimaginatively called version 1,version 2, version 351and version 4. Version 1 is found in "older" laptops and uses 4 bytes per52packet. Version 2 seems to be introduced with the EeePC and uses 6 bytes53per packet, and provides additional features such as position of two fingers,54and width of the touch. Hardware version 3 uses 6 bytes per packet (and55for 2 fingers the concatenation of two 6 bytes packets) and allows tracking56of up to 3 fingers. Hardware version 4 uses 6 bytes per packet, and can57combine a status packet with multiple head or motion packets. Hardware version584 allows tracking up to 5 fingers.59 60Some Hardware version 3 and version 4 also have a trackpoint which uses a61separate packet format. It is also 6 bytes per packet.62 63The driver tries to support both hardware versions and should be compatible64with the Xorg Synaptics touchpad driver and its graphical configuration65utilities.66 67Note that a mouse button is also associated with either the touchpad or the68trackpoint when a trackpoint is available. Disabling the Touchpad in xorg69(TouchPadOff=0) will also disable the buttons associated with the touchpad.70 71Additionally the operation of the touchpad can be altered by adjusting the72contents of some of its internal registers. These registers are represented73by the driver as sysfs entries under /sys/bus/serio/drivers/psmouse/serio?74that can be read from and written to.75 76Currently only the registers for hardware version 1 are somewhat understood.77Hardware version 2 seems to use some of the same registers but it is not78known whether the bits in the registers represent the same thing or might79have changed their meaning.80 81On top of that, some register settings have effect only when the touchpad is82in relative mode and not in absolute mode. As the Linux Elantech touchpad83driver always puts the hardware into absolute mode not all information84mentioned below can be used immediately. But because there is no freely85available Elantech documentation the information is provided here anyway for86completeness sake.87 88 89Extra knobs90~~~~~~~~~~~91 92Currently the Linux Elantech touchpad driver provides three extra knobs under93/sys/bus/serio/drivers/psmouse/serio? for the user.94 95* debug96 97 Turn different levels of debugging ON or OFF.98 99 By echoing "0" to this file all debugging will be turned OFF.100 101 Currently a value of "1" will turn on some basic debugging and a value of102 "2" will turn on packet debugging. For hardware version 1 the default is103 OFF. For version 2 the default is "1".104 105 Turning packet debugging on will make the driver dump every packet106 received to the syslog before processing it. Be warned that this can107 generate quite a lot of data!108 109* paritycheck110 111 Turns parity checking ON or OFF.112 113 By echoing "0" to this file parity checking will be turned OFF. Any114 non-zero value will turn it ON. For hardware version 1 the default is ON.115 For version 2 the default it is OFF.116 117 Hardware version 1 provides basic data integrity verification by118 calculating a parity bit for the last 3 bytes of each packet. The driver119 can check these bits and reject any packet that appears corrupted. Using120 this knob you can bypass that check.121 122 Hardware version 2 does not provide the same parity bits. Only some basic123 data consistency checking can be done. For now checking is disabled by124 default. Currently even turning it on will do nothing.125 126* crc_enabled127 128 Sets crc_enabled to 0/1. The name "crc_enabled" is the official name of129 this integrity check, even though it is not an actual cyclic redundancy130 check.131 132 Depending on the state of crc_enabled, certain basic data integrity133 verification is done by the driver on hardware version 3 and 4. The134 driver will reject any packet that appears corrupted. Using this knob,135 The state of crc_enabled can be altered with this knob.136 137 Reading the crc_enabled value will show the active value. Echoing138 "0" or "1" to this file will set the state to "0" or "1".139 140Differentiating hardware versions141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~142 143To detect the hardware version, read the version number as param[0].param[1].param[2]::144 145 4 bytes version: (after the arrow is the name given in the Dell-provided driver)146 02.00.22 => EF013147 02.06.00 => EF019148 149In the wild, there appear to be more versions, such as 00.01.64, 01.00.21,15002.00.00, 02.00.04, 02.00.06::151 152 6 bytes:153 02.00.30 => EF113154 02.08.00 => EF023155 02.08.XX => EF123156 02.0B.00 => EF215157 04.01.XX => Scroll_EF051158 04.02.XX => EF051159 160In the wild, there appear to be more versions, such as 04.03.01, 04.04.11. There161appears to be almost no difference, except for EF113, which does not report162pressure/width and has different data consistency checks.163 164Probably all the versions with param[0] <= 01 can be considered as1654 bytes/firmware 1. The versions < 02.08.00, with the exception of 02.00.30, as1664 bytes/firmware 2. Everything >= 02.08.00 can be considered as 6 bytes.167 168 169Hardware version 1170~~~~~~~~~~~~~~~~~~171 172Registers173---------174 175By echoing a hexadecimal value to a register it contents can be altered.176 177For example::178 179 echo -n 0x16 > reg_10180 181* reg_10::182 183 bit 7 6 5 4 3 2 1 0184 B C T D L A S E185 186 E: 1 = enable smart edges unconditionally187 S: 1 = enable smart edges only when dragging188 A: 1 = absolute mode (needs 4 byte packets, see reg_11)189 L: 1 = enable drag lock (see reg_22)190 D: 1 = disable dynamic resolution191 T: 1 = disable tapping192 C: 1 = enable corner tap193 B: 1 = swap left and right button194 195* reg_11::196 197 bit 7 6 5 4 3 2 1 0198 1 0 0 H V 1 F P199 200 P: 1 = enable parity checking for relative mode201 F: 1 = enable native 4 byte packet mode202 V: 1 = enable vertical scroll area203 H: 1 = enable horizontal scroll area204 205* reg_20::206 207 single finger width?208 209* reg_21::210 211 scroll area width (small: 0x40 ... wide: 0xff)212 213* reg_22::214 215 drag lock time out (short: 0x14 ... long: 0xfe;216 0xff = tap again to release)217 218* reg_23::219 220 tap make timeout?221 222* reg_24::223 224 tap release timeout?225 226* reg_25::227 228 smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast)229 230* reg_26::231 232 smart edge activation area width?233 234 235Native relative mode 4 byte packet format236-----------------------------------------237 238byte 0::239 240 bit 7 6 5 4 3 2 1 0241 c c p2 p1 1 M R L242 243 L, R, M = 1 when Left, Right, Middle mouse button pressed244 some models have M as byte 3 odd parity bit245 when parity checking is enabled (reg_11, P = 1):246 p1..p2 = byte 1 and 2 odd parity bit247 c = 1 when corner tap detected248 249byte 1::250 251 bit 7 6 5 4 3 2 1 0252 dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0253 254 dx7..dx0 = x movement; positive = right, negative = left255 byte 1 = 0xf0 when corner tap detected256 257byte 2::258 259 bit 7 6 5 4 3 2 1 0260 dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0261 262 dy7..dy0 = y movement; positive = up, negative = down263 264byte 3::265 266 parity checking enabled (reg_11, P = 1):267 268 bit 7 6 5 4 3 2 1 0269 w h n1 n0 ds3 ds2 ds1 ds0270 271 normally:272 ds3..ds0 = scroll wheel amount and direction273 positive = down or left274 negative = up or right275 when corner tap detected:276 ds0 = 1 when top right corner tapped277 ds1 = 1 when bottom right corner tapped278 ds2 = 1 when bottom left corner tapped279 ds3 = 1 when top left corner tapped280 n1..n0 = number of fingers on touchpad281 only models with firmware 2.x report this, models with282 firmware 1.x seem to map one, two and three finger taps283 directly to L, M and R mouse buttons284 h = 1 when horizontal scroll action285 w = 1 when wide finger touch?286 287 otherwise (reg_11, P = 0):288 289 bit 7 6 5 4 3 2 1 0290 ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0291 292 ds7..ds0 = vertical scroll amount and direction293 negative = up294 positive = down295 296 297Native absolute mode 4 byte packet format298-----------------------------------------299 300EF013 and EF019 have a special behaviour (due to a bug in the firmware?), and301when 1 finger is touching, the first 2 position reports must be discarded.302This counting is reset whenever a different number of fingers is reported.303 304byte 0::305 306 firmware version 1.x:307 308 bit 7 6 5 4 3 2 1 0309 D U p1 p2 1 p3 R L310 311 L, R = 1 when Left, Right mouse button pressed312 p1..p3 = byte 1..3 odd parity bit313 D, U = 1 when rocker switch pressed Up, Down314 315 firmware version 2.x:316 317 bit 7 6 5 4 3 2 1 0318 n1 n0 p2 p1 1 p3 R L319 320 L, R = 1 when Left, Right mouse button pressed321 p1..p3 = byte 1..3 odd parity bit322 n1..n0 = number of fingers on touchpad323 324byte 1::325 326 firmware version 1.x:327 328 bit 7 6 5 4 3 2 1 0329 f 0 th tw x9 x8 y9 y8330 331 tw = 1 when two finger touch332 th = 1 when three finger touch333 f = 1 when finger touch334 335 firmware version 2.x:336 337 bit 7 6 5 4 3 2 1 0338 . . . . x9 x8 y9 y8339 340byte 2::341 342 bit 7 6 5 4 3 2 1 0343 x7 x6 x5 x4 x3 x2 x1 x0344 345 x9..x0 = absolute x value (horizontal)346 347byte 3::348 349 bit 7 6 5 4 3 2 1 0350 y7 y6 y5 y4 y3 y2 y1 y0351 352 y9..y0 = absolute y value (vertical)353 354 355Hardware version 2356~~~~~~~~~~~~~~~~~~357 358 359Registers360---------361 362By echoing a hexadecimal value to a register it contents can be altered.363 364For example::365 366 echo -n 0x56 > reg_10367 368* reg_10::369 370 bit 7 6 5 4 3 2 1 0371 0 1 0 1 0 1 D 0372 373 D: 1 = enable drag and drop374 375* reg_11::376 377 bit 7 6 5 4 3 2 1 0378 1 0 0 0 S 0 1 0379 380 S: 1 = enable vertical scroll381 382* reg_21::383 384 unknown (0x00)385 386* reg_22::387 388 drag and drop release time out (short: 0x70 ... long 0x7e;389 0x7f = never i.e. tap again to release)390 391 392Native absolute mode 6 byte packet format393-----------------------------------------394 395Parity checking and packet re-synchronization396^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^397 398There is no parity checking, however some consistency checks can be performed.399 400For instance for EF113::401 402 SA1= packet[0];403 A1 = packet[1];404 B1 = packet[2];405 SB1= packet[3];406 C1 = packet[4];407 D1 = packet[5];408 if( (((SA1 & 0x3C) != 0x3C) && ((SA1 & 0xC0) != 0x80)) || // check Byte 1409 (((SA1 & 0x0C) != 0x0C) && ((SA1 & 0xC0) == 0x80)) || // check Byte 1 (one finger pressed)410 (((SA1 & 0xC0) != 0x80) && (( A1 & 0xF0) != 0x00)) || // check Byte 2411 (((SB1 & 0x3E) != 0x38) && ((SA1 & 0xC0) != 0x80)) || // check Byte 4412 (((SB1 & 0x0E) != 0x08) && ((SA1 & 0xC0) == 0x80)) || // check Byte 4 (one finger pressed)413 (((SA1 & 0xC0) != 0x80) && (( C1 & 0xF0) != 0x00)) ) // check Byte 5414 // error detected415 416For all the other ones, there are just a few constant bits::417 418 if( ((packet[0] & 0x0C) != 0x04) ||419 ((packet[3] & 0x0f) != 0x02) )420 // error detected421 422 423In case an error is detected, all the packets are shifted by one (and packet[0] is discarded).424 425One/Three finger touch426^^^^^^^^^^^^^^^^^^^^^^427 428byte 0::429 430 bit 7 6 5 4 3 2 1 0431 n1 n0 w3 w2 . . R L432 433 L, R = 1 when Left, Right mouse button pressed434 n1..n0 = number of fingers on touchpad435 436byte 1::437 438 bit 7 6 5 4 3 2 1 0439 p7 p6 p5 p4 x11 x10 x9 x8440 441byte 2::442 443 bit 7 6 5 4 3 2 1 0444 x7 x6 x5 x4 x3 x2 x1 x0445 446 x11..x0 = absolute x value (horizontal)447 448byte 3::449 450 bit 7 6 5 4 3 2 1 0451 n4 vf w1 w0 . . . b2452 453 n4 = set if more than 3 fingers (only in 3 fingers mode)454 vf = a kind of flag ? (only on EF123, 0 when finger is over one455 of the buttons, 1 otherwise)456 w3..w0 = width of the finger touch (not EF113)457 b2 (on EF113 only, 0 otherwise), b2.R.L indicates one button pressed:458 0 = none459 1 = Left460 2 = Right461 3 = Middle (Left and Right)462 4 = Forward463 5 = Back464 6 = Another one465 7 = Another one466 467byte 4::468 469 bit 7 6 5 4 3 2 1 0470 p3 p1 p2 p0 y11 y10 y9 y8471 472 p7..p0 = pressure (not EF113)473 474byte 5::475 476 bit 7 6 5 4 3 2 1 0477 y7 y6 y5 y4 y3 y2 y1 y0478 479 y11..y0 = absolute y value (vertical)480 481 482Two finger touch483^^^^^^^^^^^^^^^^484 485Note that the two pairs of coordinates are not exactly the coordinates of the486two fingers, but only the pair of the lower-left and upper-right coordinates.487So the actual fingers might be situated on the other diagonal of the square488defined by these two points.489 490byte 0::491 492 bit 7 6 5 4 3 2 1 0493 n1 n0 ay8 ax8 . . R L494 495 L, R = 1 when Left, Right mouse button pressed496 n1..n0 = number of fingers on touchpad497 498byte 1::499 500 bit 7 6 5 4 3 2 1 0501 ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0502 503 ax8..ax0 = lower-left finger absolute x value504 505byte 2::506 507 bit 7 6 5 4 3 2 1 0508 ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0509 510 ay8..ay0 = lower-left finger absolute y value511 512byte 3::513 514 bit 7 6 5 4 3 2 1 0515 . . by8 bx8 . . . .516 517byte 4::518 519 bit 7 6 5 4 3 2 1 0520 bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0521 522 bx8..bx0 = upper-right finger absolute x value523 524byte 5::525 526 bit 7 6 5 4 3 2 1 0527 by7 by8 by5 by4 by3 by2 by1 by0528 529 by8..by0 = upper-right finger absolute y value530 531Hardware version 3532~~~~~~~~~~~~~~~~~~533 534Registers535---------536 537* reg_10::538 539 bit 7 6 5 4 3 2 1 0540 0 0 0 0 R F T A541 542 A: 1 = enable absolute tracking543 T: 1 = enable two finger mode auto correct544 F: 1 = disable ABS Position Filter545 R: 1 = enable real hardware resolution546 547Native absolute mode 6 byte packet format548-----------------------------------------549 5501 and 3 finger touch shares the same 6-byte packet format, except that5513 finger touch only reports the position of the center of all three fingers.552 553Firmware would send 12 bytes of data for 2 finger touch.554 555Note on debounce:556In case the box has unstable power supply or other electricity issues, or557when number of finger changes, F/W would send "debounce packet" to inform558driver that the hardware is in debounce status.559The debouce packet has the following signature::560 561 byte 0: 0xc4562 byte 1: 0xff563 byte 2: 0xff564 byte 3: 0x02565 byte 4: 0xff566 byte 5: 0xff567 568When we encounter this kind of packet, we just ignore it.569 570One/Three finger touch571^^^^^^^^^^^^^^^^^^^^^^572 573byte 0::574 575 bit 7 6 5 4 3 2 1 0576 n1 n0 w3 w2 0 1 R L577 578 L, R = 1 when Left, Right mouse button pressed579 n1..n0 = number of fingers on touchpad580 581byte 1::582 583 bit 7 6 5 4 3 2 1 0584 p7 p6 p5 p4 x11 x10 x9 x8585 586byte 2::587 588 bit 7 6 5 4 3 2 1 0589 x7 x6 x5 x4 x3 x2 x1 x0590 591 x11..x0 = absolute x value (horizontal)592 593byte 3::594 595 bit 7 6 5 4 3 2 1 0596 0 0 w1 w0 0 0 1 0597 598 w3..w0 = width of the finger touch599 600byte 4::601 602 bit 7 6 5 4 3 2 1 0603 p3 p1 p2 p0 y11 y10 y9 y8604 605 p7..p0 = pressure606 607byte 5::608 609 bit 7 6 5 4 3 2 1 0610 y7 y6 y5 y4 y3 y2 y1 y0611 612 y11..y0 = absolute y value (vertical)613 614Two finger touch615^^^^^^^^^^^^^^^^616 617The packet format is exactly the same for two finger touch, except the hardware618sends two 6 byte packets. The first packet contains data for the first finger,619the second packet has data for the second finger. So for two finger touch a620total of 12 bytes are sent.621 622Hardware version 4623~~~~~~~~~~~~~~~~~~624 625Registers626---------627 628* reg_07::629 630 bit 7 6 5 4 3 2 1 0631 0 0 0 0 0 0 0 A632 633 A: 1 = enable absolute tracking634 635Native absolute mode 6 byte packet format636-----------------------------------------637 638v4 hardware is a true multitouch touchpad, capable of tracking up to 5 fingers.639Unfortunately, due to PS/2's limited bandwidth, its packet format is rather640complex.641 642Whenever the numbers or identities of the fingers changes, the hardware sends a643status packet to indicate how many and which fingers is on touchpad, followed by644head packets or motion packets. A head packet contains data of finger id, finger645position (absolute x, y values), width, and pressure. A motion packet contains646two fingers' position delta.647 648For example, when status packet tells there are 2 fingers on touchpad, then we649can expect two following head packets. If the finger status doesn't change,650the following packets would be motion packets, only sending delta of finger651position, until we receive a status packet.652 653One exception is one finger touch. when a status packet tells us there is only654one finger, the hardware would just send head packets afterwards.655 656Status packet657^^^^^^^^^^^^^658 659byte 0::660 661 bit 7 6 5 4 3 2 1 0662 . . . . 0 1 R L663 664 L, R = 1 when Left, Right mouse button pressed665 666byte 1::667 668 bit 7 6 5 4 3 2 1 0669 . . . ft4 ft3 ft2 ft1 ft0670 671 ft4 ft3 ft2 ft1 ft0 ftn = 1 when finger n is on touchpad672 673byte 2::674 675 not used676 677byte 3::678 679 bit 7 6 5 4 3 2 1 0680 . . . 1 0 0 0 0681 682 constant bits683 684byte 4::685 686 bit 7 6 5 4 3 2 1 0687 p . . . . . . .688 689 p = 1 for palm690 691byte 5::692 693 not used694 695Head packet696^^^^^^^^^^^697 698byte 0::699 700 bit 7 6 5 4 3 2 1 0701 w3 w2 w1 w0 0 1 R L702 703 L, R = 1 when Left, Right mouse button pressed704 w3..w0 = finger width (spans how many trace lines)705 706byte 1::707 708 bit 7 6 5 4 3 2 1 0709 p7 p6 p5 p4 x11 x10 x9 x8710 711byte 2::712 713 bit 7 6 5 4 3 2 1 0714 x7 x6 x5 x4 x3 x2 x1 x0715 716 x11..x0 = absolute x value (horizontal)717 718byte 3::719 720 bit 7 6 5 4 3 2 1 0721 id2 id1 id0 1 0 0 0 1722 723 id2..id0 = finger id724 725byte 4::726 727 bit 7 6 5 4 3 2 1 0728 p3 p1 p2 p0 y11 y10 y9 y8729 730 p7..p0 = pressure731 732byte 5::733 734 bit 7 6 5 4 3 2 1 0735 y7 y6 y5 y4 y3 y2 y1 y0736 737 y11..y0 = absolute y value (vertical)738 739Motion packet740^^^^^^^^^^^^^741 742byte 0::743 744 bit 7 6 5 4 3 2 1 0745 id2 id1 id0 w 0 1 R L746 747 L, R = 1 when Left, Right mouse button pressed748 id2..id0 = finger id749 w = 1 when delta overflows (> 127 or < -128), in this case750 firmware sends us (delta x / 5) and (delta y / 5)751 752byte 1::753 754 bit 7 6 5 4 3 2 1 0755 x7 x6 x5 x4 x3 x2 x1 x0756 757 x7..x0 = delta x (two's complement)758 759byte 2::760 761 bit 7 6 5 4 3 2 1 0762 y7 y6 y5 y4 y3 y2 y1 y0763 764 y7..y0 = delta y (two's complement)765 766byte 3::767 768 bit 7 6 5 4 3 2 1 0769 id2 id1 id0 1 0 0 1 0770 771 id2..id0 = finger id772 773byte 4::774 775 bit 7 6 5 4 3 2 1 0776 x7 x6 x5 x4 x3 x2 x1 x0777 778 x7..x0 = delta x (two's complement)779 780byte 5::781 782 bit 7 6 5 4 3 2 1 0783 y7 y6 y5 y4 y3 y2 y1 y0784 785 y7..y0 = delta y (two's complement)786 787 byte 0 ~ 2 for one finger788 byte 3 ~ 5 for another789 790 791Trackpoint (for Hardware version 3 and 4)792~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~793 794Registers795---------796 797No special registers have been identified.798 799Native relative mode 6 byte packet format800-----------------------------------------801 802Status Packet803^^^^^^^^^^^^^804 805byte 0::806 807 bit 7 6 5 4 3 2 1 0808 0 0 sx sy 0 M R L809 810byte 1::811 812 bit 7 6 5 4 3 2 1 0813 ~sx 0 0 0 0 0 0 0814 815byte 2::816 817 bit 7 6 5 4 3 2 1 0818 ~sy 0 0 0 0 0 0 0819 820byte 3::821 822 bit 7 6 5 4 3 2 1 0823 0 0 ~sy ~sx 0 1 1 0824 825byte 4::826 827 bit 7 6 5 4 3 2 1 0828 x7 x6 x5 x4 x3 x2 x1 x0829 830byte 5::831 832 bit 7 6 5 4 3 2 1 0833 y7 y6 y5 y4 y3 y2 y1 y0834 835 836 x and y are written in two's complement spread837 over 9 bits with sx/sy the relative top bit and838 x7..x0 and y7..y0 the lower bits.839 ~sx is the inverse of sx, ~sy is the inverse of sy.840 The sign of y is opposite to what the input driver841 expects for a relative movement842