Remove unneeded version.h include from drivers/staging/mei/main.c
[zen-stable.git] / Documentation / input / elantech.txt
blobdb798af5ef98a434cbb8c8828857627953c932ec
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. Hardware version 1
20     3.1 Registers
21     3.2 Native relative mode 4 byte packet format
22     3.3 Native absolute mode 4 byte packet format
23  4. Hardware version 2
24     4.1 Registers
25     4.2 Native absolute mode 6 byte packet format
26         4.2.1 One finger touch
27         4.2.2 Two finger touch
31 1. Introduction
32    ~~~~~~~~~~~~
34 Currently the Linux Elantech touchpad driver is aware of two different
35 hardware versions unimaginatively called version 1 and version 2. Version 1
36 is found in "older" laptops and uses 4 bytes per packet. Version 2 seems to
37 be introduced with the EeePC and uses 6 bytes per packet, and provides
38 additional features such as position of two fingers, and width of the touch.
40 The driver tries to support both hardware versions and should be compatible
41 with the Xorg Synaptics touchpad driver and its graphical configuration
42 utilities.
44 Additionally the operation of the touchpad can be altered by adjusting the
45 contents of some of its internal registers. These registers are represented
46 by the driver as sysfs entries under /sys/bus/serio/drivers/psmouse/serio?
47 that can be read from and written to.
49 Currently only the registers for hardware version 1 are somewhat understood.
50 Hardware version 2 seems to use some of the same registers but it is not
51 known whether the bits in the registers represent the same thing or might
52 have changed their meaning.
54 On top of that, some register settings have effect only when the touchpad is
55 in relative mode and not in absolute mode. As the Linux Elantech touchpad
56 driver always puts the hardware into absolute mode not all information
57 mentioned below can be used immediately. But because there is no freely
58 available Elantech documentation the information is provided here anyway for
59 completeness sake.
62 /////////////////////////////////////////////////////////////////////////////
65 2. Extra knobs
66    ~~~~~~~~~~~
68 Currently the Linux Elantech touchpad driver provides two extra knobs under
69 /sys/bus/serio/drivers/psmouse/serio? for the user.
71 * debug
73    Turn different levels of debugging ON or OFF.
75    By echoing "0" to this file all debugging will be turned OFF.
77    Currently a value of "1" will turn on some basic debugging and a value of
78    "2" will turn on packet debugging. For hardware version 1 the default is
79    OFF. For version 2 the default is "1".
81    Turning packet debugging on will make the driver dump every packet
82    received to the syslog before processing it. Be warned that this can
83    generate quite a lot of data!
85 * paritycheck
87    Turns parity checking ON or OFF.
89    By echoing "0" to this file parity checking will be turned OFF. Any
90    non-zero value will turn it ON. For hardware version 1 the default is ON.
91    For version 2 the default it is OFF.
93    Hardware version 1 provides basic data integrity verification by
94    calculating a parity bit for the last 3 bytes of each packet. The driver
95    can check these bits and reject any packet that appears corrupted. Using
96    this knob you can bypass that check.
98    Hardware version 2 does not provide the same parity bits. Only some basic
99    data consistency checking can be done. For now checking is disabled by
100    default. Currently even turning it on will do nothing.
102 /////////////////////////////////////////////////////////////////////////////
104 3. Differentiating hardware versions
105    =================================
107 To detect the hardware version, read the version number as param[0].param[1].param[2]
109  4 bytes version: (after the arrow is the name given in the Dell-provided driver)
110  02.00.22 => EF013
111  02.06.00 => EF019
112 In the wild, there appear to be more versions, such as 00.01.64, 01.00.21,
113 02.00.00, 02.00.04, 02.00.06.
115  6 bytes:
116  02.00.30 => EF113
117  02.08.00 => EF023
118  02.08.XX => EF123
119  02.0B.00 => EF215
120  04.01.XX => Scroll_EF051
121  04.02.XX => EF051
122 In the wild, there appear to be more versions, such as 04.03.01, 04.04.11. There
123 appears to be almost no difference, except for EF113, which does not report
124 pressure/width and has different data consistency checks.
126 Probably all the versions with param[0] <= 01 can be considered as
127 4 bytes/firmware 1. The versions < 02.08.00, with the exception of 02.00.30, as
128 4 bytes/firmware 2. Everything >= 02.08.00 can be considered as 6 bytes.
130 /////////////////////////////////////////////////////////////////////////////
132 4. Hardware version 1
133    ==================
135 4.1 Registers
136     ~~~~~~~~~
138 By echoing a hexadecimal value to a register it contents can be altered.
140 For example:
142    echo -n 0x16 > reg_10
144 * reg_10
146    bit   7   6   5   4   3   2   1   0
147          B   C   T   D   L   A   S   E
149          E: 1 = enable smart edges unconditionally
150          S: 1 = enable smart edges only when dragging
151          A: 1 = absolute mode (needs 4 byte packets, see reg_11)
152          L: 1 = enable drag lock (see reg_22)
153          D: 1 = disable dynamic resolution
154          T: 1 = disable tapping
155          C: 1 = enable corner tap
156          B: 1 = swap left and right button
158 * reg_11
160    bit   7   6   5   4   3   2   1   0
161          1   0   0   H   V   1   F   P
163          P: 1 = enable parity checking for relative mode
164          F: 1 = enable native 4 byte packet mode
165          V: 1 = enable vertical scroll area
166          H: 1 = enable horizontal scroll area
168 * reg_20
170          single finger width?
172 * reg_21
174          scroll area width (small: 0x40 ... wide: 0xff)
176 * reg_22
178          drag lock time out (short: 0x14 ... long: 0xfe;
179                              0xff = tap again to release)
181 * reg_23
183          tap make timeout?
185 * reg_24
187          tap release timeout?
189 * reg_25
191          smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast)
193 * reg_26
195          smart edge activation area width?
198 4.2 Native relative mode 4 byte packet format
199     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201 byte 0:
202    bit   7   6   5   4   3   2   1   0
203          c   c  p2  p1   1   M   R   L
205          L, R, M = 1 when Left, Right, Middle mouse button pressed
206             some models have M as byte 3 odd parity bit
207          when parity checking is enabled (reg_11, P = 1):
208             p1..p2 = byte 1 and 2 odd parity bit
209          c = 1 when corner tap detected
211 byte 1:
212    bit   7   6   5   4   3   2   1   0
213         dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0
215          dx7..dx0 = x movement;   positive = right, negative = left
216          byte 1 = 0xf0 when corner tap detected
218 byte 2:
219    bit   7   6   5   4   3   2   1   0
220         dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0
222          dy7..dy0 = y movement;   positive = up,    negative = down
224 byte 3:
225    parity checking enabled (reg_11, P = 1):
227       bit   7   6   5   4   3   2   1   0
228             w   h  n1  n0  ds3 ds2 ds1 ds0
230             normally:
231                ds3..ds0 = scroll wheel amount and direction
232                           positive = down or left
233                           negative = up or right
234             when corner tap detected:
235                ds0 = 1 when top right corner tapped
236                ds1 = 1 when bottom right corner tapped
237                ds2 = 1 when bottom left corner tapped
238                ds3 = 1 when top left corner tapped
239             n1..n0 = number of fingers on touchpad
240                only models with firmware 2.x report this, models with
241                firmware 1.x seem to map one, two and three finger taps
242                directly to L, M and R mouse buttons
243             h = 1 when horizontal scroll action
244             w = 1 when wide finger touch?
246    otherwise (reg_11, P = 0):
248       bit   7   6   5   4   3   2   1   0
249            ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0
251             ds7..ds0 = vertical scroll amount and direction
252                        negative = up
253                        positive = down
256 4.3 Native absolute mode 4 byte packet format
257     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
259 EF013 and EF019 have a special behaviour (due to a bug in the firmware?), and
260 when 1 finger is touching, the first 2 position reports must be discarded.
261 This counting is reset whenever a different number of fingers is reported.
263 byte 0:
264    firmware version 1.x:
266       bit   7   6   5   4   3   2   1   0
267             D   U  p1  p2   1  p3   R   L
269             L, R = 1 when Left, Right mouse button pressed
270             p1..p3 = byte 1..3 odd parity bit
271             D, U = 1 when rocker switch pressed Up, Down
273    firmware version 2.x:
275       bit   7   6   5   4   3   2   1   0
276            n1  n0  p2  p1   1  p3   R   L
278             L, R = 1 when Left, Right mouse button pressed
279             p1..p3 = byte 1..3 odd parity bit
280             n1..n0 = number of fingers on touchpad
282 byte 1:
283    firmware version 1.x:
285       bit   7   6   5   4   3   2   1   0
286             f   0  th  tw  x9  x8  y9  y8
288             tw = 1 when two finger touch
289             th = 1 when three finger touch
290             f  = 1 when finger touch
292    firmware version 2.x:
294       bit   7   6   5   4   3   2   1   0
295             .   .   .   .  x9  x8  y9  y8
297 byte 2:
298    bit   7   6   5   4   3   2   1   0
299         x7  x6  x5  x4  x3  x2  x1  x0
301          x9..x0 = absolute x value (horizontal)
303 byte 3:
304    bit   7   6   5   4   3   2   1   0
305         y7  y6  y5  y4  y3  y2  y1  y0
307          y9..y0 = absolute y value (vertical)
310 /////////////////////////////////////////////////////////////////////////////
313 5. Hardware version 2
314    ==================
317 5.1 Registers
318     ~~~~~~~~~
320 By echoing a hexadecimal value to a register it contents can be altered.
322 For example:
324    echo -n 0x56 > reg_10
326 * reg_10
328    bit   7   6   5   4   3   2   1   0
329          0   1   0   1   0   1   D   0
331          D: 1 = enable drag and drop
333 * reg_11
335    bit   7   6   5   4   3   2   1   0
336          1   0   0   0   S   0   1   0
338          S: 1 = enable vertical scroll
340 * reg_21
342          unknown (0x00)
344 * reg_22
346          drag and drop release time out (short: 0x70 ... long 0x7e;
347                                    0x7f = never i.e. tap again to release)
350 5.2 Native absolute mode 6 byte packet format
351     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
352 5.2.1 Parity checking and packet re-synchronization
353 There is no parity checking, however some consistency checks can be performed.
355 For instance for EF113:
356         SA1= packet[0];
357         A1 = packet[1];
358         B1 = packet[2];
359         SB1= packet[3];
360         C1 = packet[4];
361         D1 = packet[5];
362         if( (((SA1 & 0x3C) != 0x3C) && ((SA1 & 0xC0) != 0x80)) || // check Byte 1
363             (((SA1 & 0x0C) != 0x0C) && ((SA1 & 0xC0) == 0x80)) || // check Byte 1 (one finger pressed)
364             (((SA1 & 0xC0) != 0x80) && (( A1 & 0xF0) != 0x00)) || // check Byte 2
365             (((SB1 & 0x3E) != 0x38) && ((SA1 & 0xC0) != 0x80)) || // check Byte 4
366             (((SB1 & 0x0E) != 0x08) && ((SA1 & 0xC0) == 0x80)) || // check Byte 4 (one finger pressed)
367             (((SA1 & 0xC0) != 0x80) && (( C1 & 0xF0) != 0x00))  ) // check Byte 5
368                 // error detected
370 For all the other ones, there are just a few constant bits:
371         if( ((packet[0] & 0x0C) != 0x04) ||
372             ((packet[3] & 0x0f) != 0x02) )
373                 // error detected
376 In case an error is detected, all the packets are shifted by one (and packet[0] is discarded).
378 5.2.1 One/Three finger touch
379       ~~~~~~~~~~~~~~~~
381 byte 0:
383    bit   7   6   5   4   3   2   1   0
384          n1  n0  w3  w2   .   .   R   L
386          L, R = 1 when Left, Right mouse button pressed
387          n1..n0 = numbers of fingers on touchpad
389 byte 1:
391    bit   7   6   5   4   3   2   1   0
392          p7  p6  p5  p4  .  x10 x9  x8
394 byte 2:
396    bit   7   6   5   4   3   2   1   0
397          x7  x6  x5  x4  x3  x2  x1  x0
399          x10..x0 = absolute x value (horizontal)
401 byte 3:
403    bit   7   6   5   4   3   2   1   0
404          n4  vf  w1  w0   .   .   .  b2
406          n4 = set if more than 3 fingers (only in 3 fingers mode)
407          vf = a kind of flag ? (only on EF123, 0 when finger is over one
408               of the buttons, 1 otherwise)
409          w3..w0 = width of the finger touch (not EF113)
410          b2 (on EF113 only, 0 otherwise), b2.R.L indicates one button pressed:
411                 0 = none
412                 1 = Left
413                 2 = Right
414                 3 = Middle (Left and Right)
415                 4 = Forward
416                 5 = Back
417                 6 = Another one
418                 7 = Another one
420 byte 4:
422    bit   7   6   5   4   3   2   1   0
423         p3  p1  p2  p0   .   .  y9  y8
425          p7..p0 = pressure (not EF113)
427 byte 5:
429    bit   7   6   5   4   3   2   1   0
430         y7  y6  y5  y4  y3  y2  y1  y0
432          y9..y0 = absolute y value (vertical)
435 4.2.2 Two finger touch
436       ~~~~~~~~~~~~~~~~
438 Note that the two pairs of coordinates are not exactly the coordinates of the
439 two fingers, but only the pair of the lower-left and upper-right coordinates.
440 So the actual fingers might be situated on the other diagonal of the square
441 defined by these two points.
443 byte 0:
445    bit   7   6   5   4   3   2   1   0
446         n1  n0  ay8 ax8  .   .   R   L
448          L, R = 1 when Left, Right mouse button pressed
449          n1..n0 = numbers of fingers on touchpad
451 byte 1:
453    bit   7   6   5   4   3   2   1   0
454         ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0
456          ax8..ax0 = lower-left finger absolute x value
458 byte 2:
460    bit   7   6   5   4   3   2   1   0
461         ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0
463          ay8..ay0 = lower-left finger absolute y value
465 byte 3:
467    bit   7   6   5   4   3   2   1   0
468          .   .  by8 bx8  .   .   .   .
470 byte 4:
472    bit   7   6   5   4   3   2   1   0
473         bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0
475          bx8..bx0 = upper-right finger absolute x value
477 byte 5:
479    bit   7   6   5   4   3   2   1   0
480         by7 by8 by5 by4 by3 by2 by1 by0
482          by8..by0 = upper-right finger absolute y value