From 3920ab0ae729e73bbcb5b3d0358c048ff9163629 Mon Sep 17 00:00:00 2001 From: Tai-hwa Liang Date: Wed, 13 Jan 2010 00:22:29 -0800 Subject: Input: update Sentelic protocol documentation iSigned-off-by: Tai-hwa Liang Signed-off-by: Dmitry Torokhov --- Documentation/input/sentelic.txt | 124 ++++++++++++++++++++++++++++++++++----- 1 file changed, 110 insertions(+), 14 deletions(-) (limited to 'Documentation/input') diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.txt index f7160a2fb6a2..b35affd5c649 100644 --- a/Documentation/input/sentelic.txt +++ b/Documentation/input/sentelic.txt @@ -1,5 +1,5 @@ -Copyright (C) 2002-2008 Sentelic Corporation. -Last update: Oct-31-2008 +Copyright (C) 2002-2010 Sentelic Corporation. +Last update: Jan-13-2010 ============================================================================== * Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons) @@ -44,7 +44,7 @@ B) MSID 6: Horizontal and Vertical scrolling. Packet 1 Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |Y|X|y|x|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 | | |B|F|l|r|u|d| + 1 |Y|X|y|x|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 | | |B|F|r|l|u|d| |---------------| |---------------| |---------------| |---------------| Byte 1: Bit7 => Y overflow @@ -59,15 +59,15 @@ Byte 2: X Movement(9-bit 2's complement integers) Byte 3: Y Movement(9-bit 2's complement integers) Byte 4: Bit0 => the Vertical scrolling movement downward. Bit1 => the Vertical scrolling movement upward. - Bit2 => the Vertical scrolling movement rightward. - Bit3 => the Vertical scrolling movement leftward. + Bit2 => the Horizontal scrolling movement leftward. + Bit3 => the Horizontal scrolling movement rightward. Bit4 => 1 = 4th mouse button is pressed, Forward one page. 0 = 4th mouse button is not pressed. Bit5 => 1 = 5th mouse button is pressed, Backward one page. 0 = 5th mouse button is not pressed. C) MSID 7: -# FSP uses 2 packets(8 Bytes) data to represent Absolute Position +# FSP uses 2 packets (8 Bytes) to represent Absolute Position. so we have PACKET NUMBER to identify packets. If PACKET NUMBER is 0, the packet is Packet 1. If PACKET NUMBER is 1, the packet is Packet 2. @@ -129,7 +129,7 @@ Byte 3: Message Type => 0x00 (Disabled) Byte 4: Bit7~Bit0 => Don't Care ============================================================================== -* Absolute position for STL3888-A0. +* Absolute position for STL3888-Ax. ============================================================================== Packet 1 (ABSOLUTE POSITION) Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 @@ -179,14 +179,14 @@ Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) Bit5~Bit4 => y2_g Bit7~Bit6 => x2_g -Notify Packet for STL3888-A0 +Notify Packet for STL3888-Ax Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| 1 |1|0|1|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|d|u|0|0|0|0| |---------------| |---------------| |---------------| |---------------| Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet + => 01, Absolute coordinates packet => 10, Notify packet Bit5 => 1 Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1): @@ -205,15 +205,106 @@ Byte 4: Bit7 => scroll right button Bit6 => scroll left button Bit5 => scroll down button Bit4 => scroll up button - * Note that if gesture and additional button (Bit4~Bit7) - happen at the same time, the button information will not - be sent. + * Note that if gesture and additional buttoni (Bit4~Bit7) + happen at the same time, the button information will not + be sent. + Bit3~Bit0 => Reserved + +Sample sequence of Multi-finger, Multi-coordinate mode: + + notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1, + abs pkt 2, ..., notify packet (valid bit == 0) + +============================================================================== +* Absolute position for STL3888-B0. +============================================================================== +Packet 1(ABSOLUTE POSITION) + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |0|1|V|F|1|0|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|u|d|X|X|Y|Y| + |---------------| |---------------| |---------------| |---------------| + +Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordinates packet + => 10, Notify packet + Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. + When both fingers are up, the last two reports have zero valid + bit. + Bit4 => finger up/down information. 1: finger down, 0: finger up. + Bit3 => 1 + Bit2 => finger index, 0 is the first finger, 1 is the second finger. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. +Byte 2: X coordinate (xpos[9:2]) +Byte 3: Y coordinate (ypos[9:2]) +Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) + Bit3~Bit2 => X coordinate (ypos[1:0]) + Bit4 => scroll down button + Bit5 => scroll up button + Bit6 => scroll left button + Bit7 => scroll right button + +Packet 2 (ABSOLUTE POSITION) + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |0|1|V|F|1|1|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|u|d|X|X|Y|Y| + |---------------| |---------------| |---------------| |---------------| + +Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordination packet + => 10, Notify packet + Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. + When both fingers are up, the last two reports have zero valid + bit. + Bit4 => finger up/down information. 1: finger down, 0: finger up. + Bit3 => 1 + Bit2 => finger index, 0 is the first finger, 1 is the second finger. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. +Byte 2: X coordinate (xpos[9:2]) +Byte 3: Y coordinate (ypos[9:2]) +Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) + Bit3~Bit2 => X coordinate (ypos[1:0]) + Bit4 => scroll down button + Bit5 => scroll up button + Bit6 => scroll left button + Bit7 => scroll right button + +Notify Packet for STL3888-B0 + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |1|0|1|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|u|d|0|0|0|0| + |---------------| |---------------| |---------------| |---------------| + +Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordination packet + => 10, Notify packet + Bit5 => 1 + Bit4 => when in absolute coordinate mode (valid when EN_PKT_GO is 1): + 0: left button is generated by the on-pad command + 1: left button is generated by the external button + Bit3 => 1 + Bit2 => Middle Button, 1 is pressed, 0 is not pressed. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. +Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode) +Byte 3: Bit7~Bit6 => Don't care + Bit5~Bit4 => Number of fingers + Bit3~Bit1 => Reserved + Bit0 => 1: enter gesture mode; 0: leaving gesture mode +Byte 4: Bit7 => scroll right button + Bit6 => scroll left button + Bit5 => scroll up button + Bit4 => scroll down button + * Note that if gesture and additional button(Bit4~Bit7) + happen at the same time, the button information will not + be sent. Bit3~Bit0 => Reserved Sample sequence of Multi-finger, Multi-coordinate mode: notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1, - abs pkt 2, ..., notify packet(valid bit == 0) + abs pkt 2, ..., notify packet (valid bit == 0) ============================================================================== * FSP Enable/Disable packet @@ -409,7 +500,8 @@ offset width default r/w name 0: read only, 1: read/write enable (Note that following registers does not require clock gating being enabled prior to write: 05 06 07 08 09 0c 0f 10 11 12 16 17 18 23 2e - 40 41 42 43.) + 40 41 42 43. In addition to that, this bit must be 1 when gesture + mode is enabled) 0x31 RW on-pad command detection bit7 0 RW on-pad command left button down tag @@ -463,6 +555,10 @@ offset width default r/w name absolute coordinates; otherwise, host only receives packets with relative coordinate.) + bit7 0 RW EN_PS2_F2: PS/2 gesture mode 2nd + finger packet enable + 0: disable, 1: enable + 0x43 RW on-pad control bit0 0 RW on-pad control enable 0: disable, 1: enable -- cgit v1.2.2 From f6bdc2303da6786cc22a7d24b6790e9f75b4cfdc Mon Sep 17 00:00:00 2001 From: Henrik Rydberg Date: Thu, 28 Jan 2010 22:28:28 -0800 Subject: Input: update multi-touch protocol documentation This patch documents a new ABS_MT parameter and adds further text to clarify some points around the MT protocol. Requested-by: Yoonyoung Shim Requested-by: Mika Kuoppala Requested-by: Peter Hutterer Signed-off-by: Henrik Rydberg Signed-off-by: Dmitry Torokhov --- Documentation/input/multi-touch-protocol.txt | 48 +++++++++++++++++++++++----- 1 file changed, 40 insertions(+), 8 deletions(-) (limited to 'Documentation/input') diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index a12ea3b586e6..8490480ce432 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -27,12 +27,30 @@ set of events/packets. A set of ABS_MT events with the desired properties is defined. The events are divided into categories, to allow for partial implementation. The -minimum set consists of ABS_MT_TOUCH_MAJOR, ABS_MT_POSITION_X and -ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked. If the -device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size -of the approaching finger. Anisotropy and direction may be specified with -ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. The -ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a +minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which +allows for multiple fingers to be tracked. If the device supports it, the +ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size +of the contact area and approaching finger, respectively. + +The TOUCH and WIDTH parameters have a geometrical interpretation; imagine +looking through a window at someone gently holding a finger against the +glass. You will see two regions, one inner region consisting of the part +of the finger actually touching the glass, and one outer region formed by +the perimeter of the finger. The diameter of the inner region is the +ABS_MT_TOUCH_MAJOR, the diameter of the outer region is +ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder +against the glass. The inner region will increase, and in general, the +ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than +unity, is related to the finger pressure. For pressure-based devices, +ABS_MT_PRESSURE may be used to provide the pressure on the contact area +instead. + +In addition to the MAJOR parameters, the oval shape of the finger can be +described by adding the MINOR parameters, such that MAJOR and MINOR are the +major and minor axis of an ellipse. Finally, the orientation of the oval +shape can be describe with the ORIENTATION parameter. + +The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a finger or a pen or something else. Devices with more granular information may specify general shapes as blobs, i.e., as a sequence of rectangular shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices @@ -42,11 +60,9 @@ report finger tracking from hardware [5]. Here is what a minimal event sequence for a two-finger touch would look like: - ABS_MT_TOUCH_MAJOR ABS_MT_POSITION_X ABS_MT_POSITION_Y SYN_MT_REPORT - ABS_MT_TOUCH_MAJOR ABS_MT_POSITION_X ABS_MT_POSITION_Y SYN_MT_REPORT @@ -87,6 +103,12 @@ the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates the notion of pressure. The fingers of the hand and the palm all have different characteristic widths [1]. +ABS_MT_PRESSURE + +The pressure, in arbitrary units, on the contact area. May be used instead +of TOUCH and WIDTH for pressure-based devices or any device with a spatial +signal intensity distribution. + ABS_MT_ORIENTATION The orientation of the ellipse. The value should describe a signed quarter @@ -170,6 +192,16 @@ There are a few devices that support trackingID in hardware. User space can make use of these native identifiers to reduce bandwidth and cpu usage. +Gestures +-------- + +In the specific application of creating gesture events, the TOUCH and WIDTH +parameters can be used to, e.g., approximate finger pressure or distinguish +between index finger and thumb. With the addition of the MINOR parameters, +one can also distinguish between a sweeping finger and a pointing finger, +and with ORIENTATION, one can detect twisting of fingers. + + Notes ----- -- cgit v1.2.2 From 3ad2f3fbb961429d2aa627465ae4829758bc7e07 Mon Sep 17 00:00:00 2001 From: Daniel Mack Date: Wed, 3 Feb 2010 08:01:28 +0800 Subject: tree-wide: Assorted spelling fixes In particular, several occurances of funny versions of 'success', 'unknown', 'therefore', 'acknowledge', 'argument', 'achieve', 'address', 'beginning', 'desirable', 'separate' and 'necessary' are fixed. Signed-off-by: Daniel Mack Cc: Joe Perches Cc: Junio C Hamano Signed-off-by: Jiri Kosina --- Documentation/input/rotary-encoder.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/input') diff --git a/Documentation/input/rotary-encoder.txt b/Documentation/input/rotary-encoder.txt index 3a6aec40c0b0..8b4129de1d2d 100644 --- a/Documentation/input/rotary-encoder.txt +++ b/Documentation/input/rotary-encoder.txt @@ -75,7 +75,7 @@ and the number of steps or will clamp at the maximum and zero depending on the configuration. Because GPIO to IRQ mapping is platform specific, this information must -be given in seperately to the driver. See the example below. +be given in separately to the driver. See the example below. ------------------ -- cgit v1.2.2 From 97065e033ec5fd824d0133ecd0c614fe1e5c20bd Mon Sep 17 00:00:00 2001 From: Henrik Rydberg Date: Sun, 21 Mar 2010 22:31:26 -0700 Subject: Input: clarify the no-finger event in multitouch protocol The current documentation does not explicitly specify how to report zero fingers, leaving a potential problem in the driver implementations and giving no parsing directive to userland. This patch defines two equally valid ways. Signed-off-by: Henrik Rydberg Signed-off-by: Dmitry Torokhov --- Documentation/input/multi-touch-protocol.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'Documentation/input') diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index 8490480ce432..eacb22606664 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -68,6 +68,22 @@ like: SYN_MT_REPORT SYN_REPORT +Here is the sequence after lifting one of the fingers: + + ABS_MT_POSITION_X + ABS_MT_POSITION_Y + SYN_MT_REPORT + SYN_REPORT + +And here is the sequence after lifting the remaining finger: + + SYN_MT_REPORT + SYN_REPORT + +If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the +ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the +last SYN_REPORT will be dropped by the input core, resulting in no +zero-finger event reaching userland. Event Semantics --------------- -- cgit v1.2.2 From 13bad37b04c779d98983307a27f97e9caa36f9b1 Mon Sep 17 00:00:00 2001 From: Henrik Rydberg Date: Sun, 21 Mar 2010 22:31:26 -0700 Subject: Input: update the status of the Multitouch X driver project The Multitouch X driver project has moved to alpha status. This patch updates the documentation accordingly. Signed-off-by: Henrik Rydberg Signed-off-by: Dmitry Torokhov --- Documentation/input/multi-touch-protocol.txt | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) (limited to 'Documentation/input') diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index eacb22606664..c0fc1c75fd88 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -233,11 +233,6 @@ where examples can be found. difference between the contact position and the approaching tool position could be used to derive tilt. [2] The list can of course be extended. -[3] The multi-touch X driver is currently in the prototyping stage. At the -time of writing (April 2009), the MT protocol is not yet merged, and the -prototype implements finger matching, basic mouse support and two-finger -scrolling. The project aims at improving the quality of current multi-touch -functionality available in the Synaptics X driver, and in addition -implement more advanced gestures. +[3] Multitouch X driver project: http://bitmath.org/code/multitouch/. [4] See the section on event computation. [5] See the section on finger tracking. -- cgit v1.2.2 From e938fbfd4a7ac829d48b767c4dc365535d5c4f97 Mon Sep 17 00:00:00 2001 From: Florian Ragwitz Date: Mon, 3 May 2010 23:29:37 -0700 Subject: Input: elantech - ignore high bits in the position coordinates In older versions of the elantech hardware/firmware those bits always were unset, so it didn't actually matter, but newer versions seem to use those high bits for something else, screwing up the coordinates we report to the input layer for those devices. Signed-off-by: Florian Ragwitz Signed-off-by: Dmitry Torokhov --- Documentation/input/elantech.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation/input') diff --git a/Documentation/input/elantech.txt b/Documentation/input/elantech.txt index a10c3b6ba7c4..56941ae1f5db 100644 --- a/Documentation/input/elantech.txt +++ b/Documentation/input/elantech.txt @@ -333,14 +333,14 @@ byte 0: byte 1: bit 7 6 5 4 3 2 1 0 - x15 x14 x13 x12 x11 x10 x9 x8 + . . . . . x10 x9 x8 byte 2: bit 7 6 5 4 3 2 1 0 x7 x6 x5 x4 x4 x2 x1 x0 - x15..x0 = absolute x value (horizontal) + x10..x0 = absolute x value (horizontal) byte 3: @@ -350,14 +350,14 @@ byte 3: byte 4: bit 7 6 5 4 3 2 1 0 - y15 y14 y13 y12 y11 y10 y8 y8 + . . . . . . y9 y8 byte 5: bit 7 6 5 4 3 2 1 0 y7 y6 y5 y4 y3 y2 y1 y0 - y15..y0 = absolute y value (vertical) + y9..y0 = absolute y value (vertical) 4.2.2 Two finger touch -- cgit v1.2.2