Linux 3.16-rc2
[linux/fpc-iii.git] / Documentation / input / elantech.txt
blobe1ae127ed099d4934e1d7fb95f1a8ba819c1da9b
1 Elantech Touchpad Driver
2 ========================
4         Copyright (C) 2007-2008 Arjan Opmeer <arjan@opmeer.net>
6         Extra information for hardware version 1 found and
7         provided by Steve Havelka
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
14 Contents
15 ~~~~~~~~
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
44 1. Introduction
45    ~~~~~~~~~~~~
47 Currently the Linux Elantech touchpad driver is aware of two different
48 hardware versions unimaginatively called version 1 and version 2. Version 1
49 is found in "older" laptops and uses 4 bytes per packet. Version 2 seems to
50 be introduced with the EeePC and uses 6 bytes per packet, and provides
51 additional features such as position of two fingers, and width of the touch.
53 The driver tries to support both hardware versions and should be compatible
54 with the Xorg Synaptics touchpad driver and its graphical configuration
55 utilities.
57 Additionally the operation of the touchpad can be altered by adjusting the
58 contents of some of its internal registers. These registers are represented
59 by the driver as sysfs entries under /sys/bus/serio/drivers/psmouse/serio?
60 that can be read from and written to.
62 Currently only the registers for hardware version 1 are somewhat understood.
63 Hardware version 2 seems to use some of the same registers but it is not
64 known whether the bits in the registers represent the same thing or might
65 have changed their meaning.
67 On top of that, some register settings have effect only when the touchpad is
68 in relative mode and not in absolute mode. As the Linux Elantech touchpad
69 driver always puts the hardware into absolute mode not all information
70 mentioned below can be used immediately. But because there is no freely
71 available Elantech documentation the information is provided here anyway for
72 completeness sake.
75 /////////////////////////////////////////////////////////////////////////////
78 2. Extra knobs
79    ~~~~~~~~~~~
81 Currently the Linux Elantech touchpad driver provides two extra knobs under
82 /sys/bus/serio/drivers/psmouse/serio? for the user.
84 * debug
86    Turn different levels of debugging ON or OFF.
88    By echoing "0" to this file all debugging will be turned OFF.
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".
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!
98 * paritycheck
100    Turns parity checking ON or OFF.
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.
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.
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.
115 /////////////////////////////////////////////////////////////////////////////
117 3. Differentiating hardware versions
118    =================================
120 To detect the hardware version, read the version number as param[0].param[1].param[2]
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
125 In the wild, there appear to be more versions, such as 00.01.64, 01.00.21,
126 02.00.00, 02.00.04, 02.00.06.
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
135 In the wild, there appear to be more versions, such as 04.03.01, 04.04.11. There
136 appears to be almost no difference, except for EF113, which does not report
137 pressure/width and has different data consistency checks.
139 Probably all the versions with param[0] <= 01 can be considered as
140 4 bytes/firmware 1. The versions < 02.08.00, with the exception of 02.00.30, as
141 4 bytes/firmware 2. Everything >= 02.08.00 can be considered as 6 bytes.
143 /////////////////////////////////////////////////////////////////////////////
145 4. Hardware version 1
146    ==================
148 4.1 Registers
149     ~~~~~~~~~
151 By echoing a hexadecimal value to a register it contents can be altered.
153 For example:
155    echo -n 0x16 > reg_10
157 * reg_10
159    bit   7   6   5   4   3   2   1   0
160          B   C   T   D   L   A   S   E
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
171 * reg_11
173    bit   7   6   5   4   3   2   1   0
174          1   0   0   H   V   1   F   P
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
181 * reg_20
183          single finger width?
185 * reg_21
187          scroll area width (small: 0x40 ... wide: 0xff)
189 * reg_22
191          drag lock time out (short: 0x14 ... long: 0xfe;
192                              0xff = tap again to release)
194 * reg_23
196          tap make timeout?
198 * reg_24
200          tap release timeout?
202 * reg_25
204          smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast)
206 * reg_26
208          smart edge activation area width?
211 4.2 Native relative mode 4 byte packet format
212     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
214 byte 0:
215    bit   7   6   5   4   3   2   1   0
216          c   c  p2  p1   1   M   R   L
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
224 byte 1:
225    bit   7   6   5   4   3   2   1   0
226         dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0
228          dx7..dx0 = x movement;   positive = right, negative = left
229          byte 1 = 0xf0 when corner tap detected
231 byte 2:
232    bit   7   6   5   4   3   2   1   0
233         dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0
235          dy7..dy0 = y movement;   positive = up,    negative = down
237 byte 3:
238    parity checking enabled (reg_11, P = 1):
240       bit   7   6   5   4   3   2   1   0
241             w   h  n1  n0  ds3 ds2 ds1 ds0
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?
259    otherwise (reg_11, P = 0):
261       bit   7   6   5   4   3   2   1   0
262            ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0
264             ds7..ds0 = vertical scroll amount and direction
265                        negative = up
266                        positive = down
269 4.3 Native absolute mode 4 byte packet format
270     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
272 EF013 and EF019 have a special behaviour (due to a bug in the firmware?), and
273 when 1 finger is touching, the first 2 position reports must be discarded.
274 This counting is reset whenever a different number of fingers is reported.
276 byte 0:
277    firmware version 1.x:
279       bit   7   6   5   4   3   2   1   0
280             D   U  p1  p2   1  p3   R   L
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
286    firmware version 2.x:
288       bit   7   6   5   4   3   2   1   0
289            n1  n0  p2  p1   1  p3   R   L
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
295 byte 1:
296    firmware version 1.x:
298       bit   7   6   5   4   3   2   1   0
299             f   0  th  tw  x9  x8  y9  y8
301             tw = 1 when two finger touch
302             th = 1 when three finger touch
303             f  = 1 when finger touch
305    firmware version 2.x:
307       bit   7   6   5   4   3   2   1   0
308             .   .   .   .  x9  x8  y9  y8
310 byte 2:
311    bit   7   6   5   4   3   2   1   0
312         x7  x6  x5  x4  x3  x2  x1  x0
314          x9..x0 = absolute x value (horizontal)
316 byte 3:
317    bit   7   6   5   4   3   2   1   0
318         y7  y6  y5  y4  y3  y2  y1  y0
320          y9..y0 = absolute y value (vertical)
323 /////////////////////////////////////////////////////////////////////////////
326 5. Hardware version 2
327    ==================
330 5.1 Registers
331     ~~~~~~~~~
333 By echoing a hexadecimal value to a register it contents can be altered.
335 For example:
337    echo -n 0x56 > reg_10
339 * reg_10
341    bit   7   6   5   4   3   2   1   0
342          0   1   0   1   0   1   D   0
344          D: 1 = enable drag and drop
346 * reg_11
348    bit   7   6   5   4   3   2   1   0
349          1   0   0   0   S   0   1   0
351          S: 1 = enable vertical scroll
353 * reg_21
355          unknown (0x00)
357 * reg_22
359          drag and drop release time out (short: 0x70 ... long 0x7e;
360                                    0x7f = never i.e. tap again to release)
363 5.2 Native absolute mode 6 byte packet format
364     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
365 5.2.1 Parity checking and packet re-synchronization
366 There is no parity checking, however some consistency checks can be performed.
368 For 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
383 For 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
389 In case an error is detected, all the packets are shifted by one (and packet[0] is discarded).
391 5.2.2 One/Three finger touch
392       ~~~~~~~~~~~~~~~~
394 byte 0:
396    bit   7   6   5   4   3   2   1   0
397          n1  n0  w3  w2   .   .   R   L
399          L, R = 1 when Left, Right mouse button pressed
400          n1..n0 = number of fingers on touchpad
402 byte 1:
404    bit   7   6   5   4   3   2   1   0
405          p7  p6  p5  p4 x11 x10 x9  x8
407 byte 2:
409    bit   7   6   5   4   3   2   1   0
410          x7  x6  x5  x4  x3  x2  x1  x0
412          x11..x0 = absolute x value (horizontal)
414 byte 3:
416    bit   7   6   5   4   3   2   1   0
417          n4  vf  w1  w0   .   .   .  b2
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
433 byte 4:
435    bit   7   6   5   4   3   2   1   0
436         p3  p1  p2  p0  y11 y10 y9  y8
438          p7..p0 = pressure (not EF113)
440 byte 5:
442    bit   7   6   5   4   3   2   1   0
443         y7  y6  y5  y4  y3  y2  y1  y0
445          y11..y0 = absolute y value (vertical)
448 5.2.3 Two finger touch
449       ~~~~~~~~~~~~~~~~
451 Note that the two pairs of coordinates are not exactly the coordinates of the
452 two fingers, but only the pair of the lower-left and upper-right coordinates.
453 So the actual fingers might be situated on the other diagonal of the square
454 defined by these two points.
456 byte 0:
458    bit   7   6   5   4   3   2   1   0
459         n1  n0  ay8 ax8  .   .   R   L
461          L, R = 1 when Left, Right mouse button pressed
462          n1..n0 = number of fingers on touchpad
464 byte 1:
466    bit   7   6   5   4   3   2   1   0
467         ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0
469          ax8..ax0 = lower-left finger absolute x value
471 byte 2:
473    bit   7   6   5   4   3   2   1   0
474         ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0
476          ay8..ay0 = lower-left finger absolute y value
478 byte 3:
480    bit   7   6   5   4   3   2   1   0
481          .   .  by8 bx8  .   .   .   .
483 byte 4:
485    bit   7   6   5   4   3   2   1   0
486         bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0
488          bx8..bx0 = upper-right finger absolute x value
490 byte 5:
492    bit   7   6   5   4   3   2   1   0
493         by7 by8 by5 by4 by3 by2 by1 by0
495          by8..by0 = upper-right finger absolute y value
497 /////////////////////////////////////////////////////////////////////////////
499 6. Hardware version 3
500    ==================
502 6.1 Registers
503     ~~~~~~~~~
504 * reg_10
506    bit   7   6   5   4   3   2   1   0
507          0   0   0   0   R   F   T   A
509          A: 1 = enable absolute tracking
510          T: 1 = enable two finger mode auto correct
511          F: 1 = disable ABS Position Filter
512          R: 1 = enable real hardware resolution
514 6.2 Native absolute mode 6 byte packet format
515     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
516 1 and 3 finger touch shares the same 6-byte packet format, except that
517 3 finger touch only reports the position of the center of all three fingers.
519 Firmware would send 12 bytes of data for 2 finger touch.
521 Note on debounce:
522 In case the box has unstable power supply or other electricity issues, or
523 when number of finger changes, F/W would send "debounce packet" to inform
524 driver that the hardware is in debounce status.
525 The debouce packet has the following signature:
526     byte 0: 0xc4
527     byte 1: 0xff
528     byte 2: 0xff
529     byte 3: 0x02
530     byte 4: 0xff
531     byte 5: 0xff
532 When we encounter this kind of packet, we just ignore it.
534 6.2.1 One/Three finger touch
535       ~~~~~~~~~~~~~~~~~~~~~~
537 byte 0:
539    bit   7   6   5   4   3   2   1   0
540         n1  n0  w3  w2   0   1   R   L
542         L, R = 1 when Left, Right mouse button pressed
543         n1..n0 = number of fingers on touchpad
545 byte 1:
547    bit   7   6   5   4   3   2   1   0
548         p7  p6  p5  p4 x11 x10  x9  x8
550 byte 2:
552    bit   7   6   5   4   3   2   1   0
553         x7  x6  x5  x4  x3  x2  x1  x0
555         x11..x0 = absolute x value (horizontal)
557 byte 3:
559    bit   7   6   5   4   3   2   1   0
560          0   0  w1  w0   0   0   1   0
562          w3..w0 = width of the finger touch
564 byte 4:
566    bit   7   6   5   4   3   2   1   0
567         p3  p1  p2  p0  y11 y10 y9  y8
569         p7..p0 = pressure
571 byte 5:
573    bit   7   6   5   4   3   2   1   0
574         y7  y6  y5  y4  y3  y2  y1  y0
576         y11..y0 = absolute y value (vertical)
578 6.2.2 Two finger touch
579       ~~~~~~~~~~~~~~~~
581 The packet format is exactly the same for two finger touch, except the hardware
582 sends two 6 byte packets. The first packet contains data for the first finger,
583 the second packet has data for the second finger. So for two finger touch a
584 total of 12 bytes are sent.
586 /////////////////////////////////////////////////////////////////////////////
588 7. Hardware version 4
589    ==================
591 7.1 Registers
592     ~~~~~~~~~
593 * reg_07
595    bit   7   6   5   4   3   2   1   0
596          0   0   0   0   0   0   0   A
598          A: 1 = enable absolute tracking
600 7.2 Native absolute mode 6 byte packet format
601     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
602 v4 hardware is a true multitouch touchpad, capable of tracking up to 5 fingers.
603 Unfortunately, due to PS/2's limited bandwidth, its packet format is rather
604 complex.
606 Whenever the numbers or identities of the fingers changes, the hardware sends a
607 status packet to indicate how many and which fingers is on touchpad, followed by
608 head packets or motion packets. A head packet contains data of finger id, finger
609 position (absolute x, y values), width, and pressure. A motion packet contains
610 two fingers' position delta.
612 For example, when status packet tells there are 2 fingers on touchpad, then we
613 can expect two following head packets. If the finger status doesn't change,
614 the following packets would be motion packets, only sending delta of finger
615 position, until we receive a status packet.
617 One exception is one finger touch. when a status packet tells us there is only
618 one finger, the hardware would just send head packets afterwards.
620 7.2.1 Status packet
621       ~~~~~~~~~~~~~
623 byte 0:
625    bit   7   6   5   4   3   2   1   0
626          .   .   .   .   0   1   R   L
628          L, R = 1 when Left, Right mouse button pressed
630 byte 1:
632    bit   7   6   5   4   3   2   1   0
633          .   .   . ft4 ft3 ft2 ft1 ft0
635          ft4 ft3 ft2 ft1 ft0 ftn = 1 when finger n is on touchpad
637 byte 2: not used
639 byte 3:
641    bit   7   6   5   4   3   2   1   0
642          .   .   .   1   0   0   0   0
644          constant bits
646 byte 4:
648    bit   7   6   5   4   3   2   1   0
649          p   .   .   .   .   .   .   .
651          p = 1 for palm
653 byte 5: not used
655 7.2.2 Head packet
656       ~~~~~~~~~~~
658 byte 0:
660    bit   7   6   5   4   3   2   1   0
661         w3  w2  w1  w0   0   1   R   L
663         L, R = 1 when Left, Right mouse button pressed
664         w3..w0 = finger width (spans how many trace lines)
666 byte 1:
668    bit   7   6   5   4   3   2   1   0
669         p7  p6  p5  p4 x11 x10  x9  x8
671 byte 2:
673    bit   7   6   5   4   3   2   1   0
674         x7  x6  x5  x4  x3  x2  x1  x0
676         x11..x0 = absolute x value (horizontal)
678 byte 3:
680    bit   7   6   5   4   3   2   1   0
681        id2 id1 id0   1   0   0   0   1
683        id2..id0 = finger id
685 byte 4:
687    bit   7   6   5   4   3   2   1   0
688         p3  p1  p2  p0  y11 y10 y9  y8
690         p7..p0 = pressure
692 byte 5:
694    bit   7   6   5   4   3   2   1   0
695         y7  y6  y5  y4  y3  y2  y1  y0
697         y11..y0 = absolute y value (vertical)
699 7.2.3 Motion packet
700       ~~~~~~~~~~~~~
702 byte 0:
704    bit   7   6   5   4   3   2   1   0
705        id2 id1 id0   w   0   1   R   L
707        L, R = 1 when Left, Right mouse button pressed
708        id2..id0 = finger id
709        w = 1 when delta overflows (> 127 or < -128), in this case
710        firmware sends us (delta x / 5) and (delta y  / 5)
712 byte 1:
714    bit   7   6   5   4   3   2   1   0
715         x7  x6  x5  x4  x3  x2  x1  x0
717         x7..x0 = delta x (two's complement)
719 byte 2:
721    bit   7   6   5   4   3   2   1   0
722         y7  y6  y5  y4  y3  y2  y1  y0
724         y7..y0 = delta y (two's complement)
726 byte 3:
728    bit   7   6   5   4   3   2   1   0
729        id2 id1 id0   1   0   0   1   0
731        id2..id0 = finger id
733 byte 4:
735    bit   7   6   5   4   3   2   1   0
736         x7  x6  x5  x4  x3  x2  x1  x0
738         x7..x0 = delta x (two's complement)
740 byte 5:
742    bit   7   6   5   4   3   2   1   0
743         y7  y6  y5  y4  y3  y2  y1  y0
745         y7..y0 = delta y (two's complement)
747         byte 0 ~ 2 for one finger
748         byte 3 ~ 5 for another