media: videobuf2: fix buffer management issues
[linux-2.6.git] / Documentation / input / elantech.txt
1 Elantech 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
14 Contents
15 ~~~~~~~~
16
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
28
29
30
31 1. Introduction
32    ~~~~~~~~~~~~
33
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.
39
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.
43
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.
48
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.
53
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.
60
61
62 /////////////////////////////////////////////////////////////////////////////
63
64
65 2. Extra knobs
66    ~~~~~~~~~~~
67
68 Currently the Linux Elantech touchpad driver provides two extra knobs under
69 /sys/bus/serio/drivers/psmouse/serio? for the user.
70
71 * debug
72
73    Turn different levels of debugging ON or OFF.
74
75    By echoing "0" to this file all debugging will be turned OFF.
76
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".
80
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!
84
85 * paritycheck
86
87    Turns parity checking ON or OFF.
88
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.
92
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.
97
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.
101
102 /////////////////////////////////////////////////////////////////////////////
103
104 3. Differentiating hardware versions
105    =================================
106
107 To detect the hardware version, read the version number as param[0].param[1].param[2]
108
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.
114
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.
125
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.
129
130 /////////////////////////////////////////////////////////////////////////////
131
132 4. Hardware version 1
133    ==================
134
135 4.1 Registers
136     ~~~~~~~~~
137
138 By echoing a hexadecimal value to a register it contents can be altered.
139
140 For example:
141
142    echo -n 0x16 > reg_10
143
144 * reg_10
145
146    bit   7   6   5   4   3   2   1   0
147          B   C   T   D   L   A   S   E
148
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
157
158 * reg_11
159
160    bit   7   6   5   4   3   2   1   0
161          1   0   0   H   V   1   F   P
162
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
167
168 * reg_20
169
170          single finger width?
171
172 * reg_21
173
174          scroll area width (small: 0x40 ... wide: 0xff)
175
176 * reg_22
177
178          drag lock time out (short: 0x14 ... long: 0xfe;
179                              0xff = tap again to release)
180
181 * reg_23
182
183          tap make timeout?
184
185 * reg_24
186
187          tap release timeout?
188
189 * reg_25
190
191          smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast)
192
193 * reg_26
194
195          smart edge activation area width?
196
197
198 4.2 Native relative mode 4 byte packet format
199     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
200
201 byte 0:
202    bit   7   6   5   4   3   2   1   0
203          c   c  p2  p1   1   M   R   L
204
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
210
211 byte 1:
212    bit   7   6   5   4   3   2   1   0
213         dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0
214
215          dx7..dx0 = x movement;   positive = right, negative = left
216          byte 1 = 0xf0 when corner tap detected
217
218 byte 2:
219    bit   7   6   5   4   3   2   1   0
220         dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0
221
222          dy7..dy0 = y movement;   positive = up,    negative = down
223
224 byte 3:
225    parity checking enabled (reg_11, P = 1):
226
227       bit   7   6   5   4   3   2   1   0
228             w   h  n1  n0  ds3 ds2 ds1 ds0
229
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?
245
246    otherwise (reg_11, P = 0):
247
248       bit   7   6   5   4   3   2   1   0
249            ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0
250
251             ds7..ds0 = vertical scroll amount and direction
252                        negative = up
253                        positive = down
254
255
256 4.3 Native absolute mode 4 byte packet format
257     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
258
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.
262
263 byte 0:
264    firmware version 1.x:
265
266       bit   7   6   5   4   3   2   1   0
267             D   U  p1  p2   1  p3   R   L
268
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
272
273    firmware version 2.x:
274
275       bit   7   6   5   4   3   2   1   0
276            n1  n0  p2  p1   1  p3   R   L
277
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
281
282 byte 1:
283    firmware version 1.x:
284
285       bit   7   6   5   4   3   2   1   0
286             f   0  th  tw  x9  x8  y9  y8
287
288             tw = 1 when two finger touch
289             th = 1 when three finger touch
290             f  = 1 when finger touch
291
292    firmware version 2.x:
293
294       bit   7   6   5   4   3   2   1   0
295             .   .   .   .  x9  x8  y9  y8
296
297 byte 2:
298    bit   7   6   5   4   3   2   1   0
299         x7  x6  x5  x4  x3  x2  x1  x0
300
301          x9..x0 = absolute x value (horizontal)
302
303 byte 3:
304    bit   7   6   5   4   3   2   1   0
305         y7  y6  y5  y4  y3  y2  y1  y0
306
307          y9..y0 = absolute y value (vertical)
308
309
310 /////////////////////////////////////////////////////////////////////////////
311
312
313 5. Hardware version 2
314    ==================
315
316
317 5.1 Registers
318     ~~~~~~~~~
319
320 By echoing a hexadecimal value to a register it contents can be altered.
321
322 For example:
323
324    echo -n 0x56 > reg_10
325
326 * reg_10
327
328    bit   7   6   5   4   3   2   1   0
329          0   1   0   1   0   1   D   0
330
331          D: 1 = enable drag and drop
332
333 * reg_11
334
335    bit   7   6   5   4   3   2   1   0
336          1   0   0   0   S   0   1   0
337
338          S: 1 = enable vertical scroll
339
340 * reg_21
341
342          unknown (0x00)
343
344 * reg_22
345
346          drag and drop release time out (short: 0x70 ... long 0x7e;
347                                    0x7f = never i.e. tap again to release)
348
349
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.
354
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
369
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
374
375
376 In case an error is detected, all the packets are shifted by one (and packet[0] is discarded).
377
378 5.2.1 One/Three finger touch
379       ~~~~~~~~~~~~~~~~
380
381 byte 0:
382
383    bit   7   6   5   4   3   2   1   0
384          n1  n0  w3  w2   .   .   R   L
385
386          L, R = 1 when Left, Right mouse button pressed
387          n1..n0 = numbers of fingers on touchpad
388
389 byte 1:
390
391    bit   7   6   5   4   3   2   1   0
392          p7  p6  p5  p4  .  x10 x9  x8
393
394 byte 2:
395
396    bit   7   6   5   4   3   2   1   0
397          x7  x6  x5  x4  x3  x2  x1  x0
398
399          x10..x0 = absolute x value (horizontal)
400
401 byte 3:
402
403    bit   7   6   5   4   3   2   1   0
404          n4  vf  w1  w0   .   .   .  b2
405
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
419
420 byte 4:
421
422    bit   7   6   5   4   3   2   1   0
423         p3  p1  p2  p0   .   .  y9  y8
424
425          p7..p0 = pressure (not EF113)
426
427 byte 5:
428
429    bit   7   6   5   4   3   2   1   0
430         y7  y6  y5  y4  y3  y2  y1  y0
431
432          y9..y0 = absolute y value (vertical)
433
434
435 4.2.2 Two finger touch
436       ~~~~~~~~~~~~~~~~
437
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.
442
443 byte 0:
444
445    bit   7   6   5   4   3   2   1   0
446         n1  n0  ay8 ax8  .   .   R   L
447
448          L, R = 1 when Left, Right mouse button pressed
449          n1..n0 = numbers of fingers on touchpad
450
451 byte 1:
452
453    bit   7   6   5   4   3   2   1   0
454         ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0
455
456          ax8..ax0 = lower-left finger absolute x value
457
458 byte 2:
459
460    bit   7   6   5   4   3   2   1   0
461         ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0
462
463          ay8..ay0 = lower-left finger absolute y value
464
465 byte 3:
466
467    bit   7   6   5   4   3   2   1   0
468          .   .  by8 bx8  .   .   .   .
469
470 byte 4:
471
472    bit   7   6   5   4   3   2   1   0
473         bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0
474
475          bx8..bx0 = upper-right finger absolute x value
476
477 byte 5:
478
479    bit   7   6   5   4   3   2   1   0
480         by7 by8 by5 by4 by3 by2 by1 by0
481
482          by8..by0 = upper-right finger absolute y value