About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / input / alps.txt




Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:46 EST.

1	ALPS Touchpad Protocol
2	----------------------
3	
4	Introduction
5	------------
6	Currently the ALPS touchpad driver supports seven protocol versions in use by
7	ALPS touchpads, called versions 1, 2, 3, 4, 5, 6 and 7.
8	
9	Since roughly mid-2010 several new ALPS touchpads have been released and
10	integrated into a variety of laptops and netbooks.  These new touchpads
11	have enough behavior differences that the alps_model_data definition
12	table, describing the properties of the different versions, is no longer
13	adequate.  The design choices were to re-define the alps_model_data
14	table, with the risk of regression testing existing devices, or isolate
15	the new devices outside of the alps_model_data table.  The latter design
16	choice was made.  The new touchpad signatures are named: "Rushmore",
17	"Pinnacle", and "Dolphin", which you will see in the alps.c code.
18	For the purposes of this document, this group of ALPS touchpads will
19	generically be called "new ALPS touchpads".
20	
21	We experimented with probing the ACPI interface _HID (Hardware ID)/_CID
22	(Compatibility ID) definition as a way to uniquely identify the
23	different ALPS variants but there did not appear to be a 1:1 mapping.
24	In fact, it appeared to be an m:n mapping between the _HID and actual
25	hardware type.
26	
27	Detection
28	---------
29	
30	All ALPS touchpads should respond to the "E6 report" command sequence:
31	E8-E6-E6-E6-E9. An ALPS touchpad should respond with either 00-00-0A or
32	00-00-64 if no buttons are pressed. The bits 0-2 of the first byte will be 1s
33	if some buttons are pressed.
34	
35	If the E6 report is successful, the touchpad model is identified using the "E7
36	report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is
37	matched against known models in the alps_model_data_array.
38	
39	For older touchpads supporting protocol versions 3 and 4, the E7 report
40	model signature is always 73-02-64. To differentiate between these
41	versions, the response from the "Enter Command Mode" sequence must be
42	inspected as described below.
43	
44	The new ALPS touchpads have an E7 signature of 73-03-50 or 73-03-0A but
45	seem to be better differentiated by the EC Command Mode response.
46	
47	Command Mode
48	------------
49	
50	Protocol versions 3 and 4 have a command mode that is used to read and write
51	one-byte device registers in a 16-bit address space. The command sequence
52	EC-EC-EC-E9 places the device in command mode, and the device will respond
53	with 88-07 followed by a third byte. This third byte can be used to determine
54	whether the devices uses the version 3 or 4 protocol.
55	
56	To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad.
57	
58	While in command mode, register addresses can be set by first sending a
59	specific command, either EC for v3 devices or F5 for v4 devices. Then the
60	address is sent one nibble at a time, where each nibble is encoded as a
61	command with optional data. This encoding differs slightly between the v3 and
62	v4 protocols.
63	
64	Once an address has been set, the addressed register can be read by sending
65	PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the
66	address of the register being read, and the third contains the value of the
67	register. Registers are written by writing the value one nibble at a time
68	using the same encoding used for addresses.
69	
70	For the new ALPS touchpads, the EC command is used to enter command
71	mode. The response in the new ALPS touchpads is significantly different,
72	and more important in determining the behavior.  This code has been
73	separated from the original alps_model_data table and put in the
74	alps_identify function.  For example, there seem to be two hardware init
75	sequences for the "Dolphin" touchpads as determined by the second byte
76	of the EC response.
77	
78	Packet Format
79	-------------
80	
81	In the following tables, the following notation is used.
82	
83	 CAPITALS = stick, miniscules = touchpad
84	
85	?'s can have different meanings on different models, such as wheel rotation,
86	extra buttons, stick buttons on a dualpoint, etc.
87	
88	PS/2 packet format
89	------------------
90	
91	 byte 0:  0    0 YSGN XSGN    1    M    R    L
92	 byte 1: X7   X6   X5   X4   X3   X2   X1   X0
93	 byte 2: Y7   Y6   Y5   Y4   Y3   Y2   Y1   Y0
94	
95	Note that the device never signals overflow condition.
96	
97	For protocol version 2 devices when the trackpoint is used, and no fingers
98	are on the touchpad, the M R L bits signal the combined status of both the
99	pointingstick and touchpad buttons.
100	
101	ALPS Absolute Mode - Protocol Version 1
102	--------------------------------------
103	
104	 byte 0:  1    0    0    0    1   x9   x8   x7
105	 byte 1:  0   x6   x5   x4   x3   x2   x1   x0
106	 byte 2:  0    ?    ?    l    r    ?  fin  ges
107	 byte 3:  0    ?    ?    ?    ?   y9   y8   y7
108	 byte 4:  0   y6   y5   y4   y3   y2   y1   y0
109	 byte 5:  0   z6   z5   z4   z3   z2   z1   z0
110	
111	ALPS Absolute Mode - Protocol Version 2
112	---------------------------------------
113	
114	 byte 0:  1    ?    ?    ?    1  PSM  PSR  PSL
115	 byte 1:  0   x6   x5   x4   x3   x2   x1   x0
116	 byte 2:  0  x10   x9   x8   x7    ?  fin  ges
117	 byte 3:  0   y9   y8   y7    1    M    R    L
118	 byte 4:  0   y6   y5   y4   y3   y2   y1   y0
119	 byte 5:  0   z6   z5   z4   z3   z2   z1   z0
120	
121	Protocol Version 2 DualPoint devices send standard PS/2 mouse packets for
122	the DualPoint Stick. The M, R and L bits signal the combined status of both
123	the pointingstick and touchpad buttons, except for Dell dualpoint devices
124	where the pointingstick buttons get reported separately in the PSM, PSR
125	and PSL bits.
126	
127	Dualpoint device -- interleaved packet format
128	---------------------------------------------
129	
130	 byte 0:    1    1    0    0    1    1    1    1
131	 byte 1:    0   x6   x5   x4   x3   x2   x1   x0
132	 byte 2:    0  x10   x9   x8   x7    0  fin  ges
133	 byte 3:    0    0 YSGN XSGN    1    1    1    1
134	 byte 4:   X7   X6   X5   X4   X3   X2   X1   X0
135	 byte 5:   Y7   Y6   Y5   Y4   Y3   Y2   Y1   Y0
136	 byte 6:    0   y9   y8   y7    1    m    r    l
137	 byte 7:    0   y6   y5   y4   y3   y2   y1   y0
138	 byte 8:    0   z6   z5   z4   z3   z2   z1   z0
139	
140	Devices which use the interleaving format normally send standard PS/2 mouse
141	packets for the DualPoint Stick + ALPS Absolute Mode packets for the
142	touchpad, switching to the interleaved packet format when both the stick and
143	the touchpad are used at the same time.
144	
145	ALPS Absolute Mode - Protocol Version 3
146	---------------------------------------
147	
148	ALPS protocol version 3 has three different packet formats. The first two are
149	associated with touchpad events, and the third is associated with trackstick
150	events.
151	
152	The first type is the touchpad position packet.
153	
154	 byte 0:    1    ?   x1   x0    1    1    1    1
155	 byte 1:    0  x10   x9   x8   x7   x6   x5   x4
156	 byte 2:    0  y10   y9   y8   y7   y6   y5   y4
157	 byte 3:    0    M    R    L    1    m    r    l
158	 byte 4:    0   mt   x3   x2   y3   y2   y1   y0
159	 byte 5:    0   z6   z5   z4   z3   z2   z1   z0
160	
161	Note that for some devices the trackstick buttons are reported in this packet,
162	and on others it is reported in the trackstick packets.
163	
164	The second packet type contains bitmaps representing the x and y axes. In the
165	bitmaps a given bit is set if there is a finger covering that position on the
166	given axis. Thus the bitmap packet can be used for low-resolution multi-touch
167	data, although finger tracking is not possible.  This packet also encodes the
168	number of contacts (f1 and f0 in the table below).
169	
170	 byte 0:    1    1   x1   x0    1    1    1    1
171	 byte 1:    0   x8   x7   x6   x5   x4   x3   x2
172	 byte 2:    0   y7   y6   y5   y4   y3   y2   y1
173	 byte 3:    0  y10   y9   y8    1    1    1    1
174	 byte 4:    0  x14  x13  x12  x11  x10   x9   y0
175	 byte 5:    0    1    ?    ?    ?    ?   f1   f0
176	
177	This packet only appears after a position packet with the mt bit set, and
178	usually only appears when there are two or more contacts (although
179	occasionally it's seen with only a single contact).
180	
181	The final v3 packet type is the trackstick packet.
182	
183	 byte 0:    1    1   x7   y7    1    1    1    1
184	 byte 1:    0   x6   x5   x4   x3   x2   x1   x0
185	 byte 2:    0   y6   y5   y4   y3   y2   y1   y0
186	 byte 3:    0    1    0    0    1    0    0    0
187	 byte 4:    0   z4   z3   z2   z1   z0    ?    ?
188	 byte 5:    0    0    1    1    1    1    1    1
189	
190	ALPS Absolute Mode - Protocol Version 4
191	---------------------------------------
192	
193	Protocol version 4 has an 8-byte packet format.
194	
195	 byte 0:    1    ?   x1   x0    1    1    1    1
196	 byte 1:    0  x10   x9   x8   x7   x6   x5   x4
197	 byte 2:    0  y10   y9   y8   y7   y6   y5   y4
198	 byte 3:    0    1   x3   x2   y3   y2   y1   y0
199	 byte 4:    0    ?    ?    ?    1    ?    r    l
200	 byte 5:    0   z6   z5   z4   z3   z2   z1   z0
201	 byte 6:    bitmap data (described below)
202	 byte 7:    bitmap data (described below)
203	
204	The last two bytes represent a partial bitmap packet, with 3 full packets
205	required to construct a complete bitmap packet.  Once assembled, the 6-byte
206	bitmap packet has the following format:
207	
208	 byte 0:    0    1   x7   x6   x5   x4   x3   x2
209	 byte 1:    0   x1   x0   y4   y3   y2   y1   y0
210	 byte 2:    0    0    ?  x14  x13  x12  x11  x10
211	 byte 3:    0   x9   x8   y9   y8   y7   y6   y5
212	 byte 4:    0    0    0    0    0    0    0    0
213	 byte 5:    0    0    0    0    0    0    0  y10
214	
215	There are several things worth noting here.
216	
217	 1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
218	    identify the first fragment of a bitmap packet.
219	
220	 2) The bitmaps represent the same data as in the v3 bitmap packets, although
221	    the packet layout is different.
222	
223	 3) There doesn't seem to be a count of the contact points anywhere in the v4
224	    protocol packets. Deriving a count of contact points must be done by
225	    analyzing the bitmaps.
226	
227	 4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
228	    MT position can only be updated for every third ST position update, and
229	    the count of contact points can only be updated every third packet as
230	    well.
231	
232	So far no v4 devices with tracksticks have been encountered.
233	
234	ALPS Absolute Mode - Protocol Version 5
235	---------------------------------------
236	This is basically Protocol Version 3 but with different logic for packet
237	decode.  It uses the same alps_process_touchpad_packet_v3 call with a
238	specialized decode_fields function pointer to correctly interpret the
239	packets.  This appears to only be used by the Dolphin devices.
240	
241	For single-touch, the 6-byte packet format is:
242	
243	 byte 0:    1    1    0    0    1    0    0    0
244	 byte 1:    0   x6   x5   x4   x3   x2   x1   x0
245	 byte 2:    0   y6   y5   y4   y3   y2   y1   y0
246	 byte 3:    0    M    R    L    1    m    r    l
247	 byte 4:   y10  y9   y8   y7  x10   x9   x8   x7
248	 byte 5:    0   z6   z5   z4   z3   z2   z1   z0
249	
250	For mt, the format is:
251	
252	 byte 0:    1    1    1    n3   1   n2   n1   x24
253	 byte 1:    1   y7   y6    y5  y4   y3   y2    y1
254	 byte 2:    ?   x2   x1   y12 y11  y10   y9    y8
255	 byte 3:    0  x23  x22   x21 x20  x19  x18   x17
256	 byte 4:    0   x9   x8    x7  x6   x5   x4    x3
257	 byte 5:    0  x16  x15   x14 x13  x12  x11   x10
258	
259	ALPS Absolute Mode - Protocol Version 6
260	---------------------------------------
261	
262	For trackstick packet, the format is:
263	
264	 byte 0:    1    1    1    1    1    1    1    1
265	 byte 1:    0   X6   X5   X4   X3   X2   X1   X0
266	 byte 2:    0   Y6   Y5   Y4   Y3   Y2   Y1   Y0
267	 byte 3:    ?   Y7   X7    ?    ?    M    R    L
268	 byte 4:   Z7   Z6   Z5   Z4   Z3   Z2   Z1   Z0
269	 byte 5:    0    1    1    1    1    1    1    1
270	
271	For touchpad packet, the format is:
272	
273	 byte 0:    1    1    1    1    1    1    1    1
274	 byte 1:    0    0    0    0   x3   x2   x1   x0
275	 byte 2:    0    0    0    0   y3   y2   y1   y0
276	 byte 3:    ?   x7   x6   x5   x4    ?    r    l
277	 byte 4:    ?   y7   y6   y5   y4    ?    ?    ?
278	 byte 5:   z7   z6   z5   z4   z3   z2   z1   z0
279	
280	(v6 touchpad does not have middle button)
281	
282	ALPS Absolute Mode - Protocol Version 7
283	---------------------------------------
284	
285	For trackstick packet, the format is:
286	
287	 byte 0:    0    1    0    0    1    0    0    0
288	 byte 1:    1    1    *    *    1    M    R    L
289	 byte 2:   X7    1   X5   X4   X3   X2   X1   X0
290	 byte 3:   Z6    1   Y6   X6    1   Y2   Y1   Y0
291	 byte 4:   Y7    0   Y5   Y4   Y3    1    1    0
292	 byte 5:  T&P    0   Z5   Z4   Z3   Z2   Z1   Z0
293	
294	For touchpad packet, the format is:
295	
296	         packet-fmt     b7     b6     b5     b4     b3     b2     b1     b0
297	 byte 0: TWO & MULTI     L      1      R      M      1   Y0-2   Y0-1   Y0-0
298	 byte 0: NEW             L      1   X1-5      1      1   Y0-2   Y0-1   Y0-0
299	 byte 1:             Y0-10   Y0-9   Y0-8   Y0-7   Y0-6   Y0-5   Y0-4   Y0-3
300	 byte 2:             X0-11      1  X0-10   X0-9   X0-8   X0-7   X0-6   X0-5
301	 byte 3:             X1-11      1   X0-4   X0-3      1   X0-2   X0-1   X0-0
302	 byte 4: TWO         X1-10    TWO   X1-9   X1-8   X1-7   X1-6   X1-5   X1-4
303	 byte 4: MULTI       X1-10    TWO   X1-9   X1-8   X1-7   X1-6   Y1-5      1
304	 byte 4: NEW         X1-10    TWO   X1-9   X1-8   X1-7   X1-6      0      0
305	 byte 5: TWO & NEW   Y1-10      0   Y1-9   Y1-8   Y1-7   Y1-6   Y1-5   Y1-4
306	 byte 5: MULTI       Y1-10      0   Y1-9   Y1-8   Y1-7   Y1-6    F-1    F-0
307	
308	 L:         Left button
309	 R / M:     Non-clickpads: Right / Middle button
310	            Clickpads: When > 2 fingers are down, and some fingers
311	            are in the button area, then the 2 coordinates reported
312	            are for fingers outside the button area and these report
313	            extra fingers being present in the right / left button
314	            area. Note these fingers are not added to the F field!
315	            so if a TWO packet is received and R = 1 then there are
316	            3 fingers down, etc.
317	 TWO:       1: Two touches present, byte 0/4/5 are in TWO fmt
318	            0: If byte 4 bit 0 is 1, then byte 0/4/5 are in MULTI fmt
319	               otherwise byte 0 bit 4 must be set and byte 0/4/5 are
320	               in NEW fmt
321	 F:         Number of fingers - 3, 0 means 3 fingers, 1 means 4 ...
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.