mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-10-30 08:02:30 +00:00
171fb58da0
Updated documentation for the new ALPS touchpad support submitted in two patchsets by Kevin Cernekee. My understanding is the most recent patchset '"Dolphin V2" touchpad support' may still need some work but Future work on the ALPS driver should not impact these documentation changes. See https://bugs.launchpad.net/ubuntu/+source/linux/+bug/606238 Signed-off-by: David Turvene <dturvene@dahetral.com> Acked-by: Kevin Cernekee <cernekee@gmail.com> Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
242 lines
9.9 KiB
Text
242 lines
9.9 KiB
Text
ALPS Touchpad Protocol
|
|
----------------------
|
|
|
|
Introduction
|
|
------------
|
|
Currently the ALPS touchpad driver supports five protocol versions in use by
|
|
ALPS touchpads, called versions 1, 2, 3, 4 and 5.
|
|
|
|
Since roughly mid-2010 several new ALPS touchpads have been released and
|
|
integrated into a variety of laptops and netbooks. These new touchpads
|
|
have enough behavior differences that the alps_model_data definition
|
|
table, describing the properties of the different versions, is no longer
|
|
adequate. The design choices were to re-define the alps_model_data
|
|
table, with the risk of regression testing existing devices, or isolate
|
|
the new devices outside of the alps_model_data table. The latter design
|
|
choice was made. The new touchpad signatures are named: "Rushmore",
|
|
"Pinnacle", and "Dolphin", which you will see in the alps.c code.
|
|
For the purposes of this document, this group of ALPS touchpads will
|
|
generically be called "new ALPS touchpads".
|
|
|
|
We experimented with probing the ACPI interface _HID (Hardware ID)/_CID
|
|
(Compatibility ID) definition as a way to uniquely identify the
|
|
different ALPS variants but there did not appear to be a 1:1 mapping.
|
|
In fact, it appeared to be an m:n mapping between the _HID and actual
|
|
hardware type.
|
|
|
|
Detection
|
|
---------
|
|
|
|
All ALPS touchpads should respond to the "E6 report" command sequence:
|
|
E8-E6-E6-E6-E9. An ALPS touchpad should respond with either 00-00-0A or
|
|
00-00-64 if no buttons are pressed. The bits 0-2 of the first byte will be 1s
|
|
if some buttons are pressed.
|
|
|
|
If the E6 report is successful, the touchpad model is identified using the "E7
|
|
report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is
|
|
matched against known models in the alps_model_data_array.
|
|
|
|
For older touchpads supporting protocol versions 3 and 4, the E7 report
|
|
model signature is always 73-02-64. To differentiate between these
|
|
versions, the response from the "Enter Command Mode" sequence must be
|
|
inspected as described below.
|
|
|
|
The new ALPS touchpads have an E7 signature of 73-03-50 or 73-03-0A but
|
|
seem to be better differentiated by the EC Command Mode response.
|
|
|
|
Command Mode
|
|
------------
|
|
|
|
Protocol versions 3 and 4 have a command mode that is used to read and write
|
|
one-byte device registers in a 16-bit address space. The command sequence
|
|
EC-EC-EC-E9 places the device in command mode, and the device will respond
|
|
with 88-07 followed by a third byte. This third byte can be used to determine
|
|
whether the devices uses the version 3 or 4 protocol.
|
|
|
|
To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad.
|
|
|
|
While in command mode, register addresses can be set by first sending a
|
|
specific command, either EC for v3 devices or F5 for v4 devices. Then the
|
|
address is sent one nibble at a time, where each nibble is encoded as a
|
|
command with optional data. This enoding differs slightly between the v3 and
|
|
v4 protocols.
|
|
|
|
Once an address has been set, the addressed register can be read by sending
|
|
PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the
|
|
address of the register being read, and the third contains the value of the
|
|
register. Registers are written by writing the value one nibble at a time
|
|
using the same encoding used for addresses.
|
|
|
|
For the new ALPS touchpads, the EC command is used to enter command
|
|
mode. The response in the new ALPS touchpads is significantly different,
|
|
and more important in determining the behavior. This code has been
|
|
separated from the original alps_model_data table and put in the
|
|
alps_identify function. For example, there seem to be two hardware init
|
|
sequences for the "Dolphin" touchpads as determined by the second byte
|
|
of the EC response.
|
|
|
|
Packet Format
|
|
-------------
|
|
|
|
In the following tables, the following notation is used.
|
|
|
|
CAPITALS = stick, miniscules = touchpad
|
|
|
|
?'s can have different meanings on different models, such as wheel rotation,
|
|
extra buttons, stick buttons on a dualpoint, etc.
|
|
|
|
PS/2 packet format
|
|
------------------
|
|
|
|
byte 0: 0 0 YSGN XSGN 1 M R L
|
|
byte 1: X7 X6 X5 X4 X3 X2 X1 X0
|
|
byte 2: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
|
|
|
|
Note that the device never signals overflow condition.
|
|
|
|
ALPS Absolute Mode - Protocol Verion 1
|
|
--------------------------------------
|
|
|
|
byte 0: 1 0 0 0 1 x9 x8 x7
|
|
byte 1: 0 x6 x5 x4 x3 x2 x1 x0
|
|
byte 2: 0 ? ? l r ? fin ges
|
|
byte 3: 0 ? ? ? ? y9 y8 y7
|
|
byte 4: 0 y6 y5 y4 y3 y2 y1 y0
|
|
byte 5: 0 z6 z5 z4 z3 z2 z1 z0
|
|
|
|
ALPS Absolute Mode - Protocol Version 2
|
|
---------------------------------------
|
|
|
|
byte 0: 1 ? ? ? 1 ? ? ?
|
|
byte 1: 0 x6 x5 x4 x3 x2 x1 x0
|
|
byte 2: 0 x10 x9 x8 x7 ? fin ges
|
|
byte 3: 0 y9 y8 y7 1 M R L
|
|
byte 4: 0 y6 y5 y4 y3 y2 y1 y0
|
|
byte 5: 0 z6 z5 z4 z3 z2 z1 z0
|
|
|
|
Dualpoint device -- interleaved packet format
|
|
---------------------------------------------
|
|
|
|
byte 0: 1 1 0 0 1 1 1 1
|
|
byte 1: 0 x6 x5 x4 x3 x2 x1 x0
|
|
byte 2: 0 x10 x9 x8 x7 0 fin ges
|
|
byte 3: 0 0 YSGN XSGN 1 1 1 1
|
|
byte 4: X7 X6 X5 X4 X3 X2 X1 X0
|
|
byte 5: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
|
|
byte 6: 0 y9 y8 y7 1 m r l
|
|
byte 7: 0 y6 y5 y4 y3 y2 y1 y0
|
|
byte 8: 0 z6 z5 z4 z3 z2 z1 z0
|
|
|
|
ALPS Absolute Mode - Protocol Version 3
|
|
---------------------------------------
|
|
|
|
ALPS protocol version 3 has three different packet formats. The first two are
|
|
associated with touchpad events, and the third is associatd with trackstick
|
|
events.
|
|
|
|
The first type is the touchpad position packet.
|
|
|
|
byte 0: 1 ? x1 x0 1 1 1 1
|
|
byte 1: 0 x10 x9 x8 x7 x6 x5 x4
|
|
byte 2: 0 y10 y9 y8 y7 y6 y5 y4
|
|
byte 3: 0 M R L 1 m r l
|
|
byte 4: 0 mt x3 x2 y3 y2 y1 y0
|
|
byte 5: 0 z6 z5 z4 z3 z2 z1 z0
|
|
|
|
Note that for some devices the trackstick buttons are reported in this packet,
|
|
and on others it is reported in the trackstick packets.
|
|
|
|
The second packet type contains bitmaps representing the x and y axes. In the
|
|
bitmaps a given bit is set if there is a finger covering that position on the
|
|
given axis. Thus the bitmap packet can be used for low-resolution multi-touch
|
|
data, although finger tracking is not possible. This packet also encodes the
|
|
number of contacts (f1 and f0 in the table below).
|
|
|
|
byte 0: 1 1 x1 x0 1 1 1 1
|
|
byte 1: 0 x8 x7 x6 x5 x4 x3 x2
|
|
byte 2: 0 y7 y6 y5 y4 y3 y2 y1
|
|
byte 3: 0 y10 y9 y8 1 1 1 1
|
|
byte 4: 0 x14 x13 x12 x11 x10 x9 y0
|
|
byte 5: 0 1 ? ? ? ? f1 f0
|
|
|
|
This packet only appears after a position packet with the mt bit set, and
|
|
usually only appears when there are two or more contacts (although
|
|
occassionally it's seen with only a single contact).
|
|
|
|
The final v3 packet type is the trackstick packet.
|
|
|
|
byte 0: 1 1 x7 y7 1 1 1 1
|
|
byte 1: 0 x6 x5 x4 x3 x2 x1 x0
|
|
byte 2: 0 y6 y5 y4 y3 y2 y1 y0
|
|
byte 3: 0 1 0 0 1 0 0 0
|
|
byte 4: 0 z4 z3 z2 z1 z0 ? ?
|
|
byte 5: 0 0 1 1 1 1 1 1
|
|
|
|
ALPS Absolute Mode - Protocol Version 4
|
|
---------------------------------------
|
|
|
|
Protocol version 4 has an 8-byte packet format.
|
|
|
|
byte 0: 1 ? x1 x0 1 1 1 1
|
|
byte 1: 0 x10 x9 x8 x7 x6 x5 x4
|
|
byte 2: 0 y10 y9 y8 y7 y6 y5 y4
|
|
byte 3: 0 1 x3 x2 y3 y2 y1 y0
|
|
byte 4: 0 ? ? ? 1 ? r l
|
|
byte 5: 0 z6 z5 z4 z3 z2 z1 z0
|
|
byte 6: bitmap data (described below)
|
|
byte 7: bitmap data (described below)
|
|
|
|
The last two bytes represent a partial bitmap packet, with 3 full packets
|
|
required to construct a complete bitmap packet. Once assembled, the 6-byte
|
|
bitmap packet has the following format:
|
|
|
|
byte 0: 0 1 x7 x6 x5 x4 x3 x2
|
|
byte 1: 0 x1 x0 y4 y3 y2 y1 y0
|
|
byte 2: 0 0 ? x14 x13 x12 x11 x10
|
|
byte 3: 0 x9 x8 y9 y8 y7 y6 y5
|
|
byte 4: 0 0 0 0 0 0 0 0
|
|
byte 5: 0 0 0 0 0 0 0 y10
|
|
|
|
There are several things worth noting here.
|
|
|
|
1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
|
|
identify the first fragment of a bitmap packet.
|
|
|
|
2) The bitmaps represent the same data as in the v3 bitmap packets, although
|
|
the packet layout is different.
|
|
|
|
3) There doesn't seem to be a count of the contact points anywhere in the v4
|
|
protocol packets. Deriving a count of contact points must be done by
|
|
analyzing the bitmaps.
|
|
|
|
4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
|
|
MT position can only be updated for every third ST position update, and
|
|
the count of contact points can only be updated every third packet as
|
|
well.
|
|
|
|
So far no v4 devices with tracksticks have been encountered.
|
|
|
|
ALPS Absolute Mode - Protocol Version 5
|
|
---------------------------------------
|
|
This is basically Protocol Version 3 but with different logic for packet
|
|
decode. It uses the same alps_process_touchpad_packet_v3 call with a
|
|
specialized decode_fields function pointer to correctly interpret the
|
|
packets. This appears to only be used by the Dolphin devices.
|
|
|
|
For single-touch, the 6-byte packet format is:
|
|
|
|
byte 0: 1 1 0 0 1 0 0 0
|
|
byte 1: 0 x6 x5 x4 x3 x2 x1 x0
|
|
byte 2: 0 y6 y5 y4 y3 y2 y1 y0
|
|
byte 3: 0 M R L 1 m r l
|
|
byte 4: y10 y9 y8 y7 x10 x9 x8 x7
|
|
byte 5: 0 z6 z5 z4 z3 z2 z1 z0
|
|
|
|
For mt, the format is:
|
|
|
|
byte 0: 1 1 1 n3 1 n2 n1 x24
|
|
byte 1: 1 y7 y6 y5 y4 y3 y2 y1
|
|
byte 2: ? x2 x1 y12 y11 y10 y9 y8
|
|
byte 3: 0 x23 x22 x21 x20 x19 x18 x17
|
|
byte 4: 0 x9 x8 x7 x6 x5 x4 x3
|
|
byte 5: 0 x16 x15 x14 x13 x12 x11 x10
|