aboutsummaryrefslogtreecommitdiff
path: root/Documentation/input/elantech.txt
diff options
context:
space:
mode:
authorFathi Boudra <fathi.boudra@linaro.org>2013-04-28 09:33:08 +0300
committerFathi Boudra <fathi.boudra@linaro.org>2013-04-28 09:33:08 +0300
commit3b4bd47f8f4ed3aaf7c81c9b5d2d37ad79fadf4a (patch)
treeb9996006addfd7ae70a39672b76843b49aebc189 /Documentation/input/elantech.txt
Imported Upstream version 3.9.0HEADupstream/3.9.0upstreammaster
Diffstat (limited to 'Documentation/input/elantech.txt')
-rw-r--r--Documentation/input/elantech.txt745
1 files changed, 745 insertions, 0 deletions
diff --git a/Documentation/input/elantech.txt b/Documentation/input/elantech.txt
new file mode 100644
index 00000000..5602eb71
--- /dev/null
+++ b/Documentation/input/elantech.txt
@@ -0,0 +1,745 @@
+Elantech Touchpad Driver
+========================
+
+ Copyright (C) 2007-2008 Arjan Opmeer <arjan@opmeer.net>
+
+ Extra information for hardware version 1 found and
+ provided by Steve Havelka
+
+ Version 2 (EeePC) hardware support based on patches
+ received from Woody at Xandros and forwarded to me
+ by user StewieGriffin at the eeeuser.com forum
+
+
+Contents
+~~~~~~~~
+
+ 1. Introduction
+ 2. Extra knobs
+ 3. Differentiating hardware versions
+ 4. Hardware version 1
+ 4.1 Registers
+ 4.2 Native relative mode 4 byte packet format
+ 4.3 Native absolute mode 4 byte packet format
+ 5. Hardware version 2
+ 5.1 Registers
+ 5.2 Native absolute mode 6 byte packet format
+ 5.2.1 Parity checking and packet re-synchronization
+ 5.2.2 One/Three finger touch
+ 5.2.3 Two finger touch
+ 6. Hardware version 3
+ 6.1 Registers
+ 6.2 Native absolute mode 6 byte packet format
+ 6.2.1 One/Three finger touch
+ 6.2.2 Two finger touch
+ 7. Hardware version 4
+ 7.1 Registers
+ 7.2 Native absolute mode 6 byte packet format
+ 7.2.1 Status packet
+ 7.2.2 Head packet
+ 7.2.3 Motion packet
+
+
+
+1. Introduction
+ ~~~~~~~~~~~~
+
+Currently the Linux Elantech touchpad driver is aware of two different
+hardware versions unimaginatively called version 1 and version 2. Version 1
+is found in "older" laptops and uses 4 bytes per packet. Version 2 seems to
+be introduced with the EeePC and uses 6 bytes per packet, and provides
+additional features such as position of two fingers, and width of the touch.
+
+The driver tries to support both hardware versions and should be compatible
+with the Xorg Synaptics touchpad driver and its graphical configuration
+utilities.
+
+Additionally the operation of the touchpad can be altered by adjusting the
+contents of some of its internal registers. These registers are represented
+by the driver as sysfs entries under /sys/bus/serio/drivers/psmouse/serio?
+that can be read from and written to.
+
+Currently only the registers for hardware version 1 are somewhat understood.
+Hardware version 2 seems to use some of the same registers but it is not
+known whether the bits in the registers represent the same thing or might
+have changed their meaning.
+
+On top of that, some register settings have effect only when the touchpad is
+in relative mode and not in absolute mode. As the Linux Elantech touchpad
+driver always puts the hardware into absolute mode not all information
+mentioned below can be used immediately. But because there is no freely
+available Elantech documentation the information is provided here anyway for
+completeness sake.
+
+
+/////////////////////////////////////////////////////////////////////////////
+
+
+2. Extra knobs
+ ~~~~~~~~~~~
+
+Currently the Linux Elantech touchpad driver provides two extra knobs under
+/sys/bus/serio/drivers/psmouse/serio? for the user.
+
+* debug
+
+ Turn different levels of debugging ON or OFF.
+
+ By echoing "0" to this file all debugging will be turned OFF.
+
+ Currently a value of "1" will turn on some basic debugging and a value of
+ "2" will turn on packet debugging. For hardware version 1 the default is
+ OFF. For version 2 the default is "1".
+
+ Turning packet debugging on will make the driver dump every packet
+ received to the syslog before processing it. Be warned that this can
+ generate quite a lot of data!
+
+* paritycheck
+
+ Turns parity checking ON or OFF.
+
+ By echoing "0" to this file parity checking will be turned OFF. Any
+ non-zero value will turn it ON. For hardware version 1 the default is ON.
+ For version 2 the default it is OFF.
+
+ Hardware version 1 provides basic data integrity verification by
+ calculating a parity bit for the last 3 bytes of each packet. The driver
+ can check these bits and reject any packet that appears corrupted. Using
+ this knob you can bypass that check.
+
+ Hardware version 2 does not provide the same parity bits. Only some basic
+ data consistency checking can be done. For now checking is disabled by
+ default. Currently even turning it on will do nothing.
+
+/////////////////////////////////////////////////////////////////////////////
+
+3. Differentiating hardware versions
+ =================================
+
+To detect the hardware version, read the version number as param[0].param[1].param[2]
+
+ 4 bytes version: (after the arrow is the name given in the Dell-provided driver)
+ 02.00.22 => EF013
+ 02.06.00 => EF019
+In the wild, there appear to be more versions, such as 00.01.64, 01.00.21,
+02.00.00, 02.00.04, 02.00.06.
+
+ 6 bytes:
+ 02.00.30 => EF113
+ 02.08.00 => EF023
+ 02.08.XX => EF123
+ 02.0B.00 => EF215
+ 04.01.XX => Scroll_EF051
+ 04.02.XX => EF051
+In the wild, there appear to be more versions, such as 04.03.01, 04.04.11. There
+appears to be almost no difference, except for EF113, which does not report
+pressure/width and has different data consistency checks.
+
+Probably all the versions with param[0] <= 01 can be considered as
+4 bytes/firmware 1. The versions < 02.08.00, with the exception of 02.00.30, as
+4 bytes/firmware 2. Everything >= 02.08.00 can be considered as 6 bytes.
+
+/////////////////////////////////////////////////////////////////////////////
+
+4. Hardware version 1
+ ==================
+
+4.1 Registers
+ ~~~~~~~~~
+
+By echoing a hexadecimal value to a register it contents can be altered.
+
+For example:
+
+ echo -n 0x16 > reg_10
+
+* reg_10
+
+ bit 7 6 5 4 3 2 1 0
+ B C T D L A S E
+
+ E: 1 = enable smart edges unconditionally
+ S: 1 = enable smart edges only when dragging
+ A: 1 = absolute mode (needs 4 byte packets, see reg_11)
+ L: 1 = enable drag lock (see reg_22)
+ D: 1 = disable dynamic resolution
+ T: 1 = disable tapping
+ C: 1 = enable corner tap
+ B: 1 = swap left and right button
+
+* reg_11
+
+ bit 7 6 5 4 3 2 1 0
+ 1 0 0 H V 1 F P
+
+ P: 1 = enable parity checking for relative mode
+ F: 1 = enable native 4 byte packet mode
+ V: 1 = enable vertical scroll area
+ H: 1 = enable horizontal scroll area
+
+* reg_20
+
+ single finger width?
+
+* reg_21
+
+ scroll area width (small: 0x40 ... wide: 0xff)
+
+* reg_22
+
+ drag lock time out (short: 0x14 ... long: 0xfe;
+ 0xff = tap again to release)
+
+* reg_23
+
+ tap make timeout?
+
+* reg_24
+
+ tap release timeout?
+
+* reg_25
+
+ smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast)
+
+* reg_26
+
+ smart edge activation area width?
+
+
+4.2 Native relative mode 4 byte packet format
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+byte 0:
+ bit 7 6 5 4 3 2 1 0
+ c c p2 p1 1 M R L
+
+ L, R, M = 1 when Left, Right, Middle mouse button pressed
+ some models have M as byte 3 odd parity bit
+ when parity checking is enabled (reg_11, P = 1):
+ p1..p2 = byte 1 and 2 odd parity bit
+ c = 1 when corner tap detected
+
+byte 1:
+ bit 7 6 5 4 3 2 1 0
+ dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0
+
+ dx7..dx0 = x movement; positive = right, negative = left
+ byte 1 = 0xf0 when corner tap detected
+
+byte 2:
+ bit 7 6 5 4 3 2 1 0
+ dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0
+
+ dy7..dy0 = y movement; positive = up, negative = down
+
+byte 3:
+ parity checking enabled (reg_11, P = 1):
+
+ bit 7 6 5 4 3 2 1 0
+ w h n1 n0 ds3 ds2 ds1 ds0
+
+ normally:
+ ds3..ds0 = scroll wheel amount and direction
+ positive = down or left
+ negative = up or right
+ when corner tap detected:
+ ds0 = 1 when top right corner tapped
+ ds1 = 1 when bottom right corner tapped
+ ds2 = 1 when bottom left corner tapped
+ ds3 = 1 when top left corner tapped
+ n1..n0 = number of fingers on touchpad
+ only models with firmware 2.x report this, models with
+ firmware 1.x seem to map one, two and three finger taps
+ directly to L, M and R mouse buttons
+ h = 1 when horizontal scroll action
+ w = 1 when wide finger touch?
+
+ otherwise (reg_11, P = 0):
+
+ bit 7 6 5 4 3 2 1 0
+ ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0
+
+ ds7..ds0 = vertical scroll amount and direction
+ negative = up
+ positive = down
+
+
+4.3 Native absolute mode 4 byte packet format
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+EF013 and EF019 have a special behaviour (due to a bug in the firmware?), and
+when 1 finger is touching, the first 2 position reports must be discarded.
+This counting is reset whenever a different number of fingers is reported.
+
+byte 0:
+ firmware version 1.x:
+
+ bit 7 6 5 4 3 2 1 0
+ D U p1 p2 1 p3 R L
+
+ L, R = 1 when Left, Right mouse button pressed
+ p1..p3 = byte 1..3 odd parity bit
+ D, U = 1 when rocker switch pressed Up, Down
+
+ firmware version 2.x:
+
+ bit 7 6 5 4 3 2 1 0
+ n1 n0 p2 p1 1 p3 R L
+
+ L, R = 1 when Left, Right mouse button pressed
+ p1..p3 = byte 1..3 odd parity bit
+ n1..n0 = number of fingers on touchpad
+
+byte 1:
+ firmware version 1.x:
+
+ bit 7 6 5 4 3 2 1 0
+ f 0 th tw x9 x8 y9 y8
+
+ tw = 1 when two finger touch
+ th = 1 when three finger touch
+ f = 1 when finger touch
+
+ firmware version 2.x:
+
+ bit 7 6 5 4 3 2 1 0
+ . . . . x9 x8 y9 y8
+
+byte 2:
+ bit 7 6 5 4 3 2 1 0
+ x7 x6 x5 x4 x3 x2 x1 x0
+
+ x9..x0 = absolute x value (horizontal)
+
+byte 3:
+ bit 7 6 5 4 3 2 1 0
+ y7 y6 y5 y4 y3 y2 y1 y0
+
+ y9..y0 = absolute y value (vertical)
+
+
+/////////////////////////////////////////////////////////////////////////////
+
+
+5. Hardware version 2
+ ==================
+
+
+5.1 Registers
+ ~~~~~~~~~
+
+By echoing a hexadecimal value to a register it contents can be altered.
+
+For example:
+
+ echo -n 0x56 > reg_10
+
+* reg_10
+
+ bit 7 6 5 4 3 2 1 0
+ 0 1 0 1 0 1 D 0
+
+ D: 1 = enable drag and drop
+
+* reg_11
+
+ bit 7 6 5 4 3 2 1 0
+ 1 0 0 0 S 0 1 0
+
+ S: 1 = enable vertical scroll
+
+* reg_21
+
+ unknown (0x00)
+
+* reg_22
+
+ drag and drop release time out (short: 0x70 ... long 0x7e;
+ 0x7f = never i.e. tap again to release)
+
+
+5.2 Native absolute mode 6 byte packet format
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+5.2.1 Parity checking and packet re-synchronization
+There is no parity checking, however some consistency checks can be performed.
+
+For instance for EF113:
+ SA1= packet[0];
+ A1 = packet[1];
+ B1 = packet[2];
+ SB1= packet[3];
+ C1 = packet[4];
+ D1 = packet[5];
+ if( (((SA1 & 0x3C) != 0x3C) && ((SA1 & 0xC0) != 0x80)) || // check Byte 1
+ (((SA1 & 0x0C) != 0x0C) && ((SA1 & 0xC0) == 0x80)) || // check Byte 1 (one finger pressed)
+ (((SA1 & 0xC0) != 0x80) && (( A1 & 0xF0) != 0x00)) || // check Byte 2
+ (((SB1 & 0x3E) != 0x38) && ((SA1 & 0xC0) != 0x80)) || // check Byte 4
+ (((SB1 & 0x0E) != 0x08) && ((SA1 & 0xC0) == 0x80)) || // check Byte 4 (one finger pressed)
+ (((SA1 & 0xC0) != 0x80) && (( C1 & 0xF0) != 0x00)) ) // check Byte 5
+ // error detected
+
+For all the other ones, there are just a few constant bits:
+ if( ((packet[0] & 0x0C) != 0x04) ||
+ ((packet[3] & 0x0f) != 0x02) )
+ // error detected
+
+
+In case an error is detected, all the packets are shifted by one (and packet[0] is discarded).
+
+5.2.2 One/Three finger touch
+ ~~~~~~~~~~~~~~~~
+
+byte 0:
+
+ bit 7 6 5 4 3 2 1 0
+ n1 n0 w3 w2 . . R L
+
+ L, R = 1 when Left, Right mouse button pressed
+ n1..n0 = number of fingers on touchpad
+
+byte 1:
+
+ bit 7 6 5 4 3 2 1 0
+ p7 p6 p5 p4 x11 x10 x9 x8
+
+byte 2:
+
+ bit 7 6 5 4 3 2 1 0
+ x7 x6 x5 x4 x3 x2 x1 x0
+
+ x11..x0 = absolute x value (horizontal)
+
+byte 3:
+
+ bit 7 6 5 4 3 2 1 0
+ n4 vf w1 w0 . . . b2
+
+ n4 = set if more than 3 fingers (only in 3 fingers mode)
+ vf = a kind of flag ? (only on EF123, 0 when finger is over one
+ of the buttons, 1 otherwise)
+ w3..w0 = width of the finger touch (not EF113)
+ b2 (on EF113 only, 0 otherwise), b2.R.L indicates one button pressed:
+ 0 = none
+ 1 = Left
+ 2 = Right
+ 3 = Middle (Left and Right)
+ 4 = Forward
+ 5 = Back
+ 6 = Another one
+ 7 = Another one
+
+byte 4:
+
+ bit 7 6 5 4 3 2 1 0
+ p3 p1 p2 p0 y11 y10 y9 y8
+
+ p7..p0 = pressure (not EF113)
+
+byte 5:
+
+ bit 7 6 5 4 3 2 1 0
+ y7 y6 y5 y4 y3 y2 y1 y0
+
+ y11..y0 = absolute y value (vertical)
+
+
+5.2.3 Two finger touch
+ ~~~~~~~~~~~~~~~~
+
+Note that the two pairs of coordinates are not exactly the coordinates of the
+two fingers, but only the pair of the lower-left and upper-right coordinates.
+So the actual fingers might be situated on the other diagonal of the square
+defined by these two points.
+
+byte 0:
+
+ bit 7 6 5 4 3 2 1 0
+ n1 n0 ay8 ax8 . . R L
+
+ L, R = 1 when Left, Right mouse button pressed
+ n1..n0 = number of fingers on touchpad
+
+byte 1:
+
+ bit 7 6 5 4 3 2 1 0
+ ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0
+
+ ax8..ax0 = lower-left finger absolute x value
+
+byte 2:
+
+ bit 7 6 5 4 3 2 1 0
+ ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0
+
+ ay8..ay0 = lower-left finger absolute y value
+
+byte 3:
+
+ bit 7 6 5 4 3 2 1 0
+ . . by8 bx8 . . . .
+
+byte 4:
+
+ bit 7 6 5 4 3 2 1 0
+ bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0
+
+ bx8..bx0 = upper-right finger absolute x value
+
+byte 5:
+
+ bit 7 6 5 4 3 2 1 0
+ by7 by8 by5 by4 by3 by2 by1 by0
+
+ by8..by0 = upper-right finger absolute y value
+
+/////////////////////////////////////////////////////////////////////////////
+
+6. Hardware version 3
+ ==================
+
+6.1 Registers
+ ~~~~~~~~~
+* reg_10
+
+ bit 7 6 5 4 3 2 1 0
+ 0 0 0 0 0 0 0 A
+
+ A: 1 = enable absolute tracking
+
+6.2 Native absolute mode 6 byte packet format
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1 and 3 finger touch shares the same 6-byte packet format, except that
+3 finger touch only reports the position of the center of all three fingers.
+
+Firmware would send 12 bytes of data for 2 finger touch.
+
+Note on debounce:
+In case the box has unstable power supply or other electricity issues, or
+when number of finger changes, F/W would send "debounce packet" to inform
+driver that the hardware is in debounce status.
+The debouce packet has the following signature:
+ byte 0: 0xc4
+ byte 1: 0xff
+ byte 2: 0xff
+ byte 3: 0x02
+ byte 4: 0xff
+ byte 5: 0xff
+When we encounter this kind of packet, we just ignore it.
+
+6.2.1 One/Three finger touch
+ ~~~~~~~~~~~~~~~~~~~~~~
+
+byte 0:
+
+ bit 7 6 5 4 3 2 1 0
+ n1 n0 w3 w2 0 1 R L
+
+ L, R = 1 when Left, Right mouse button pressed
+ n1..n0 = number of fingers on touchpad
+
+byte 1:
+
+ bit 7 6 5 4 3 2 1 0
+ p7 p6 p5 p4 x11 x10 x9 x8
+
+byte 2:
+
+ bit 7 6 5 4 3 2 1 0
+ x7 x6 x5 x4 x3 x2 x1 x0
+
+ x11..x0 = absolute x value (horizontal)
+
+byte 3:
+
+ bit 7 6 5 4 3 2 1 0
+ 0 0 w1 w0 0 0 1 0
+
+ w3..w0 = width of the finger touch
+
+byte 4:
+
+ bit 7 6 5 4 3 2 1 0
+ p3 p1 p2 p0 y11 y10 y9 y8
+
+ p7..p0 = pressure
+
+byte 5:
+
+ bit 7 6 5 4 3 2 1 0
+ y7 y6 y5 y4 y3 y2 y1 y0
+
+ y11..y0 = absolute y value (vertical)
+
+6.2.2 Two finger touch
+ ~~~~~~~~~~~~~~~~
+
+The packet format is exactly the same for two finger touch, except the hardware
+sends two 6 byte packets. The first packet contains data for the first finger,
+the second packet has data for the second finger. So for two finger touch a
+total of 12 bytes are sent.
+
+/////////////////////////////////////////////////////////////////////////////
+
+7. Hardware version 4
+ ==================
+
+7.1 Registers
+ ~~~~~~~~~
+* reg_07
+
+ bit 7 6 5 4 3 2 1 0
+ 0 0 0 0 0 0 0 A
+
+ A: 1 = enable absolute tracking
+
+7.2 Native absolute mode 6 byte packet format
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+v4 hardware is a true multitouch touchpad, capable of tracking up to 5 fingers.
+Unfortunately, due to PS/2's limited bandwidth, its packet format is rather
+complex.
+
+Whenever the numbers or identities of the fingers changes, the hardware sends a
+status packet to indicate how many and which fingers is on touchpad, followed by
+head packets or motion packets. A head packet contains data of finger id, finger
+position (absolute x, y values), width, and pressure. A motion packet contains
+two fingers' position delta.
+
+For example, when status packet tells there are 2 fingers on touchpad, then we
+can expect two following head packets. If the finger status doesn't change,
+the following packets would be motion packets, only sending delta of finger
+position, until we receive a status packet.
+
+One exception is one finger touch. when a status packet tells us there is only
+one finger, the hardware would just send head packets afterwards.
+
+7.2.1 Status packet
+ ~~~~~~~~~~~~~
+
+byte 0:
+
+ bit 7 6 5 4 3 2 1 0
+ . . . . 0 1 R L
+
+ L, R = 1 when Left, Right mouse button pressed
+
+byte 1:
+
+ bit 7 6 5 4 3 2 1 0
+ . . . ft4 ft3 ft2 ft1 ft0
+
+ ft4 ft3 ft2 ft1 ft0 ftn = 1 when finger n is on touchpad
+
+byte 2: not used
+
+byte 3:
+
+ bit 7 6 5 4 3 2 1 0
+ . . . 1 0 0 0 0
+
+ constant bits
+
+byte 4:
+
+ bit 7 6 5 4 3 2 1 0
+ p . . . . . . .
+
+ p = 1 for palm
+
+byte 5: not used
+
+7.2.2 Head packet
+ ~~~~~~~~~~~
+
+byte 0:
+
+ bit 7 6 5 4 3 2 1 0
+ w3 w2 w1 w0 0 1 R L
+
+ L, R = 1 when Left, Right mouse button pressed
+ w3..w0 = finger width (spans how many trace lines)
+
+byte 1:
+
+ bit 7 6 5 4 3 2 1 0
+ p7 p6 p5 p4 x11 x10 x9 x8
+
+byte 2:
+
+ bit 7 6 5 4 3 2 1 0
+ x7 x6 x5 x4 x3 x2 x1 x0
+
+ x11..x0 = absolute x value (horizontal)
+
+byte 3:
+
+ bit 7 6 5 4 3 2 1 0
+ id2 id1 id0 1 0 0 0 1
+
+ id2..id0 = finger id
+
+byte 4:
+
+ bit 7 6 5 4 3 2 1 0
+ p3 p1 p2 p0 y11 y10 y9 y8
+
+ p7..p0 = pressure
+
+byte 5:
+
+ bit 7 6 5 4 3 2 1 0
+ y7 y6 y5 y4 y3 y2 y1 y0
+
+ y11..y0 = absolute y value (vertical)
+
+7.2.3 Motion packet
+ ~~~~~~~~~~~~~
+
+byte 0:
+
+ bit 7 6 5 4 3 2 1 0
+ id2 id1 id0 w 0 1 R L
+
+ L, R = 1 when Left, Right mouse button pressed
+ id2..id0 = finger id
+ w = 1 when delta overflows (> 127 or < -128), in this case
+ firmware sends us (delta x / 5) and (delta y / 5)
+
+byte 1:
+
+ bit 7 6 5 4 3 2 1 0
+ x7 x6 x5 x4 x3 x2 x1 x0
+
+ x7..x0 = delta x (two's complement)
+
+byte 2:
+
+ bit 7 6 5 4 3 2 1 0
+ y7 y6 y5 y4 y3 y2 y1 y0
+
+ y7..y0 = delta y (two's complement)
+
+byte 3:
+
+ bit 7 6 5 4 3 2 1 0
+ id2 id1 id0 1 0 0 1 0
+
+ id2..id0 = finger id
+
+byte 4:
+
+ bit 7 6 5 4 3 2 1 0
+ x7 x6 x5 x4 x3 x2 x1 x0
+
+ x7..x0 = delta x (two's complement)
+
+byte 5:
+
+ bit 7 6 5 4 3 2 1 0
+ y7 y6 y5 y4 y3 y2 y1 y0
+
+ y7..y0 = delta y (two's complement)
+
+ byte 0 ~ 2 for one finger
+ byte 3 ~ 5 for another