[deliverable/linux.git] / Documentation / input / alps.txt

ALPS Touchpad Protocol
----------------------

Introduction
------------

Currently the ALPS touchpad driver supports four protocol versions in use by
ALPS touchpads, called versions 1, 2, 3, and 4. Information about the various
protocol versions is contained in the following sections.

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 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.

With 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.

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.

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.
Commit	Line	Data
d4b347b2 SF	1	ALPS Touchpad Protocol
	2	----------------------
	3
	4	Introduction
	5	------------
	6
7cf801cf SF	7	Currently the ALPS touchpad driver supports four protocol versions in use by
	8	ALPS touchpads, called versions 1, 2, 3, and 4. Information about the various
	9	protocol versions is contained in the following sections.
d4b347b2 SF	10
	11	Detection
	12	---------
	13
	14	All ALPS touchpads should respond to the "E6 report" command sequence:
	15	E8-E6-E6-E6-E9. An ALPS touchpad should respond with either 00-00-0A or
	16	00-00-64.
	17
	18	If the E6 report is successful, the touchpad model is identified using the "E7
	19	report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is
	20	matched against known models in the alps_model_data_array.
	21
7cf801cf SF	22	With protocol versions 3 and 4, the E7 report model signature is always
	23	73-02-64. To differentiate between these versions, the response from the
	24	"Enter Command Mode" sequence must be inspected as described below.
	25
	26	Command Mode
	27	------------
	28
	29	Protocol versions 3 and 4 have a command mode that is used to read and write
	30	one-byte device registers in a 16-bit address space. The command sequence
	31	EC-EC-EC-E9 places the device in command mode, and the device will respond
	32	with 88-07 followed by a third byte. This third byte can be used to determine
	33	whether the devices uses the version 3 or 4 protocol.
	34
	35	To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad.
	36
	37	While in command mode, register addresses can be set by first sending a
	38	specific command, either EC for v3 devices or F5 for v4 devices. Then the
	39	address is sent one nibble at a time, where each nibble is encoded as a
	40	command with optional data. This enoding differs slightly between the v3 and
	41	v4 protocols.
	42
	43	Once an address has been set, the addressed register can be read by sending
	44	PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the
	45	address of the register being read, and the third contains the value of the
	46	register. Registers are written by writing the value one nibble at a time
	47	using the same encoding used for addresses.
	48
d4b347b2 SF	49	Packet Format
	50	-------------
	51
7cf801cf	52	In the following tables, the following notation is used.
d4b347b2 SF	53
	54	CAPITALS = stick, miniscules = touchpad
	55
	56	?'s can have different meanings on different models, such as wheel rotation,
	57	extra buttons, stick buttons on a dualpoint, etc.
	58
	59	PS/2 packet format
	60	------------------
	61
	62	byte 0: 0 0 YSGN XSGN 1 M R L
	63	byte 1: X7 X6 X5 X4 X3 X2 X1 X0
	64	byte 2: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
	65
	66	Note that the device never signals overflow condition.
	67
7cf801cf SF	68	ALPS Absolute Mode - Protocol Verion 1
7cf801cf SF	69	--------------------------------------
d4b347b2 SF	70
	71	byte 0: 1 0 0 0 1 x9 x8 x7
	72	byte 1: 0 x6 x5 x4 x3 x2 x1 x0
	73	byte 2: 0 ? ? l r ? fin ges
	74	byte 3: 0 ? ? ? ? y9 y8 y7
	75	byte 4: 0 y6 y5 y4 y3 y2 y1 y0
	76	byte 5: 0 z6 z5 z4 z3 z2 z1 z0
	77
7cf801cf SF	78	ALPS Absolute Mode - Protocol Version 2
7cf801cf SF	79	---------------------------------------
d4b347b2 SF	80
	81	byte 0: 1 ? ? ? 1 ? ? ?
	82	byte 1: 0 x6 x5 x4 x3 x2 x1 x0
	83	byte 2: 0 x10 x9 x8 x7 ? fin ges
	84	byte 3: 0 y9 y8 y7 1 M R L
	85	byte 4: 0 y6 y5 y4 y3 y2 y1 y0
	86	byte 5: 0 z6 z5 z4 z3 z2 z1 z0
	87
	88	Dualpoint device -- interleaved packet format
	89	---------------------------------------------
	90
	91	byte 0: 1 1 0 0 1 1 1 1
	92	byte 1: 0 x6 x5 x4 x3 x2 x1 x0
	93	byte 2: 0 x10 x9 x8 x7 0 fin ges
	94	byte 3: 0 0 YSGN XSGN 1 1 1 1
	95	byte 4: X7 X6 X5 X4 X3 X2 X1 X0
	96	byte 5: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
	97	byte 6: 0 y9 y8 y7 1 m r l
	98	byte 7: 0 y6 y5 y4 y3 y2 y1 y0
	99	byte 8: 0 z6 z5 z4 z3 z2 z1 z0
7cf801cf SF	100
	101	ALPS Absolute Mode - Protocol Version 3
	102	---------------------------------------
	103
	104	ALPS protocol version 3 has three different packet formats. The first two are
	105	associated with touchpad events, and the third is associatd with trackstick
	106	events.
	107
	108	The first type is the touchpad position packet.
	109
	110	byte 0: 1 ? x1 x0 1 1 1 1
	111	byte 1: 0 x10 x9 x8 x7 x6 x5 x4
	112	byte 2: 0 y10 y9 y8 y7 y6 y5 y4
	113	byte 3: 0 M R L 1 m r l
	114	byte 4: 0 mt x3 x2 y3 y2 y1 y0
	115	byte 5: 0 z6 z5 z4 z3 z2 z1 z0
	116
	117	Note that for some devices the trackstick buttons are reported in this packet,
	118	and on others it is reported in the trackstick packets.
	119
	120	The second packet type contains bitmaps representing the x and y axes. In the
	121	bitmaps a given bit is set if there is a finger covering that position on the
	122	given axis. Thus the bitmap packet can be used for low-resolution multi-touch
	123	data, although finger tracking is not possible. This packet also encodes the
	124	number of contacts (f1 and f0 in the table below).
	125
	126	byte 0: 1 1 x1 x0 1 1 1 1
	127	byte 1: 0 x8 x7 x6 x5 x4 x3 x2
	128	byte 2: 0 y7 y6 y5 y4 y3 y2 y1
	129	byte 3: 0 y10 y9 y8 1 1 1 1
	130	byte 4: 0 x14 x13 x12 x11 x10 x9 y0
	131	byte 5: 0 1 ? ? ? ? f1 f0
	132
	133	This packet only appears after a position packet with the mt bit set, and
40e47125 MI	134	usually only appears when there are two or more contacts (although
40e47125 MI	135	occassionally it's seen with only a single contact).
7cf801cf SF	136
	137	The final v3 packet type is the trackstick packet.
	138
	139	byte 0: 1 1 x7 y7 1 1 1 1
	140	byte 1: 0 x6 x5 x4 x3 x2 x1 x0
	141	byte 2: 0 y6 y5 y4 y3 y2 y1 y0
	142	byte 3: 0 1 0 0 1 0 0 0
	143	byte 4: 0 z4 z3 z2 z1 z0 ? ?
	144	byte 5: 0 0 1 1 1 1 1 1
	145
	146	ALPS Absolute Mode - Protocol Version 4
	147	---------------------------------------
	148
	149	Protocol version 4 has an 8-byte packet format.
	150
	151	byte 0: 1 ? x1 x0 1 1 1 1
	152	byte 1: 0 x10 x9 x8 x7 x6 x5 x4
	153	byte 2: 0 y10 y9 y8 y7 y6 y5 y4
	154	byte 3: 0 1 x3 x2 y3 y2 y1 y0
	155	byte 4: 0 ? ? ? 1 ? r l
	156	byte 5: 0 z6 z5 z4 z3 z2 z1 z0
	157	byte 6: bitmap data (described below)
	158	byte 7: bitmap data (described below)
	159
	160	The last two bytes represent a partial bitmap packet, with 3 full packets
	161	required to construct a complete bitmap packet. Once assembled, the 6-byte
	162	bitmap packet has the following format:
	163
	164	byte 0: 0 1 x7 x6 x5 x4 x3 x2
	165	byte 1: 0 x1 x0 y4 y3 y2 y1 y0
	166	byte 2: 0 0 ? x14 x13 x12 x11 x10
	167	byte 3: 0 x9 x8 y9 y8 y7 y6 y5
	168	byte 4: 0 0 0 0 0 0 0 0
	169	byte 5: 0 0 0 0 0 0 0 y10
	170
	171	There are several things worth noting here.
	172
	173	1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
	174	identify the first fragment of a bitmap packet.
	175
	176	2) The bitmaps represent the same data as in the v3 bitmap packets, although
	177	the packet layout is different.
	178
	179	3) There doesn't seem to be a count of the contact points anywhere in the v4
	180	protocol packets. Deriving a count of contact points must be done by
	181	analyzing the bitmaps.
	182
	183	4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
	184	MT position can only be updated for every third ST position update, and
	185	the count of contact points can only be updated every third packet as
	186	well.
	187
	188	So far no v4 devices with tracksticks have been encountered.