1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 #ifndef _SYS_USB_HIDPARSER_H
27 #define	_SYS_USB_HIDPARSER_H
28 
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 #include <sys/usb/usbai.h>
35 #include <sys/usb/usba/usbai_private.h>
36 
37 /*
38  * This file contains interfaces accessible by both the hid driver and
39  * a hid module.
40  */
41 
42 /*
43  * HID parser handle
44  *	The handle is opaque to the hid driver as well as the hid streams
45  *	modules.
46  */
47 typedef struct hidparser_handle_impl *hidparser_handle_t;
48 
49 #define	HID_REPORT_ID_UNDEFINED	0
50 
51 
52 #define	USAGE_MAX	100	/* Max no. of usages in a report */
53 
54 typedef struct hidparser_usage_info {
55 	uint16_t	usage_page;
56 	uint16_t	usage_id;
57 	uint32_t	usage_min;
58 	uint32_t	usage_max;
59 	uint32_t	collection_usage;
60 	int32_t		lmax;
61 	int32_t		lmin;
62 	uint32_t	rptcnt;
63 	uint32_t	rptsz;
64 } hidparser_usage_info_t;
65 
66 /*
67  * structure for each report type, INPUT, OUTPUT or FEATURE
68  * Note report id 0 and only one collection is handled
69  */
70 typedef struct hidparser_rpt {
71 	uint_t		report_id;
72 	uint_t		main_item_value;
73 	uint_t		no_of_usages;
74 	hidparser_usage_info_t	usage_descr[USAGE_MAX];
75 } hidparser_rpt_t;
76 
77 /*
78  * structure to return a list of report id used for a report
79  * type, INPUT, OUTPUT or FEATURE.
80  */
81 #define	REPORT_ID_MAX	10	/* Max no. of report ids supported per type */
82 
83 typedef struct hidparser_report_id_list {
84 	uint_t		main_item_value;
85 	uint_t		no_of_report_ids;
86 	uint_t		report_id[REPORT_ID_MAX];
87 } hidparser_report_id_list_t;
88 
89 typedef struct hidparser_packet_info {
90 	uint_t		max_packet_size;
91 	uint_t		report_id;
92 } hidparser_packet_info_t;
93 
94 /*
95  * hidparser_get_country_code():
96  *	Obtain the country code value that was returned in the hid descriptor
97  *	Fill in the country_code argument
98  *
99  * Arguments:
100  *	parser_handle:
101  *		hid parser handle
102  *	country code
103  *		filled in with the country code value, upon success
104  *
105  * Return values:
106  *	HIDPARSER_SUCCESS - returned on success
107  *	HIDPARSER_FAILURE - returned on an unspecified error
108  */
109 int hidparser_get_country_code(hidparser_handle_t parser_handle,
110 				uint16_t *country_code);
111 
112 
113 /*
114  * hidparser_get_packet_size():
115  *	Obtain the size(no. of bits) for a particular packet type. Note
116  *	that a hid transfer may span more than one USB transaction.
117  *
118  * Arguments:
119  *	parser_handle:
120  *		hid parser handle
121  *	report_id:
122  *		report id
123  *	main_item_type:
124  *		type of report, either Input, Output, or Feature
125  *	size:
126  *		the size if filled in upon success
127  * Return values:
128  *	HIDPARSER_SUCCESS - returned success
129  *	HIDPARSER_FAILURE - returned failure
130  */
131 int hidparser_get_packet_size(hidparser_handle_t parser_handle,
132 				uint_t report_id,
133 				uint_t main_item_type,
134 				uint_t *size);
135 
136 /*
137  * hidparser_get_usage_attribute()
138  *	Find the specified local item associated with the given usage. For
139  *	example, this function may be used to find the logical minimum for
140  *	an X usage.  Note that only short items are supported.
141  *
142  *
143  * Arguments:
144  *	parser_handle:
145  *		hid parser handle
146  *	report id:
147  *		report id of the particular report that the usage may be
148  *		found in.
149  *	main_item_type:
150  *		type of report, either Input, Output, or Feature
151  *	usage_page:
152  *		usage page that the Usage may be found on.
153  *	usage:
154  *		the Usage for which the local item will be found
155  *	usage_attribute:
156  *		type of local item to be found. Possible local and global
157  *		items are given below.
158  *
159  *	usage_attribute_value:
160  *		filled in with the value of the attribute upon return
161  *
162  * Return values:
163  *	HIDPARSER_SUCCESS - returned success
164  *	HIDPARSER_NOT_FOUND - usage specified by the parameters was not found
165  *	HIDPARSER_FAILURE - unspecified failure
166  *
167  */
168 int hidparser_get_usage_attribute(hidparser_handle_t parser_handle,
169 					uint_t report_id,
170 					uint_t main_item_type,
171 					uint_t usage_page,
172 					uint_t usage,
173 					uint_t usage_attribute,
174 					int *usage_attribute_value);
175 
176 /*
177  * hidparser_get_main_item_data_descr()
178  *
179  * Description:
180  *	Query the parser to find the data description of the main item.
181  *	Section 6.2.2.5 of the HID 1.0 specification gives details
182  *	about the data descriptions. For example, this function may be
183  *	used to find out if an X value sent by the a USB mouse is an
184  *	absolute or relative value.
185  *
186  * Parameters:
187  *	parser_handle		parser handle
188  *	report_id		report id of the particular report that the
189  *				usage may be found in
190  *	main_item_type		type of report - either Input, Output, Feature,
191  *				or Collection
192  *	usage_page		usage page that the usage may be found on
193  *	usage			type of local item to be found
194  *	main_item_descr_value	filled in with the data description
195  *
196  * Return values:
197  *	HIDPARSER_SUCCESS	attribute found successfully
198  *	HIDPARSER_NOT_FOUND	usage specified by the parameters was not found
199  *	HIDPARSER_FAILURE	unspecified failure
200  */
201 int
202 hidparser_get_main_item_data_descr(
203 			hidparser_handle_t	parser_handle,
204 			uint_t		report_id,
205 			uint_t		main_item_type,
206 			uint_t		usage_page,
207 			uint_t		usage,
208 			uint_t		*main_item_descr_value);
209 
210 
211 /*
212  * hidparser_get_usage_list_in_order()
213  *	Find all the usages corresponding to a main item, report id and
214  *	a particular usage page.
215  *	Note that only short items and 0 report id is supported.
216  *
217  * Arguments:
218  *	parser_handle:
219  *		hid parser handle
220  *	report id:
221  *		report id of the particular report where the usages belong to
222  *	main_item_type:
223  *		type of report, either Input, Output, or Feature
224  *	usage_list:
225  *		Filled in with the pointer to the first element of the
226  *		usage list
227  *
228  * Return values:
229  *	HIDPARSER_SUCCESS - returned success
230  *	HIDPARSER_NOT_FOUND - usage specified by the parameters was not found
231  *	HIDPARSER_FAILURE - unspecified failure
232  */
233 int
234 hidparser_get_usage_list_in_order(hidparser_handle_t parse_handle,
235 				uint_t report_id,
236 				uint_t main_item_type,
237 				hidparser_rpt_t *rpt);
238 
239 
240 /*
241  * hidparser_get_report_id_list()
242  *	Return a list of all report ids used for descriptor items
243  *	corresponding to a main item.
244  *
245  * Arguments:
246  *	parser_handle:
247  *		hid parser handle
248  *	main_item_type:
249  *		type of report, either Input, Output, or Feature
250  *	report_id_list:
251  *		Filled in with a list of report ids found in the descriptor
252  *
253  * Return values:
254  *	HIDPARSER_SUCCESS - returned success
255  *	HIDPARSER_FAILURE - unspecified failure
256  */
257 int
258 hidparser_get_report_id_list(hidparser_handle_t parser_handle,
259     uint_t main_item_type, hidparser_report_id_list_t *report_id_list);
260 
261 /*
262  * hidparser_find_max_packet_size_from_report_descriptor()
263  *	Returns the packet size of the largest report in the complete
264  *	report descriptor.
265  *
266  * Arguments
267  *	parser_handle:
268  *		hidparser_handle_t
269  *	packet_info:
270  *		hidparser_packet_info_t *
271  */
272 void
273 hidparser_find_max_packet_size_from_report_descriptor(
274     hidparser_handle_t parser_handle, hidparser_packet_info_t *hpack);
275 
276 
277 
278 /*
279  * Local Items
280  *	See section 6.2.2.8 of the HID 1.0 specification for
281  *	more details.
282  */
283 #define	HIDPARSER_ITEM_USAGE		0x08
284 #define	HIDPARSER_ITEM_USAGE_MIN	0x18
285 #define	HIDPARSER_ITEM_USAGE_MAX	0x28
286 #define	HIDPARSER_ITEM_DESIGNATOR_INDEX	0x38
287 #define	HIDPARSER_ITEM_DESIGNATOR_MIN	0x48
288 #define	HIDPARSER_ITEM_DESIGNATOR_MAX	0x58
289 #define	HIDPARSER_ITEM_STRING_INDEX	0x78
290 #define	HIDPARSER_ITEM_STRING_MIN	0x88
291 #define	HIDPARSER_ITEM_STRING_MAX	0x98
292 
293 /*
294  * Global Items
295  *	See section 6.2.2.7 of the HID 1.0 specifations for
296  *	more details.
297  */
298 #define	HIDPARSER_ITEM_LOGICAL_MINIMUM	0x14
299 #define	HIDPARSER_ITEM_LOGICAL_MAXIMUM	0x24
300 #define	HIDPARSER_ITEM_PHYSICAL_MINIMUM	0x34
301 #define	HIDPARSER_ITEM_PHYSICAL_MAXIMUM	0x44
302 #define	HIDPARSER_ITEM_EXPONENT		0x54
303 #define	HIDPARSER_ITEM_UNIT		0x64
304 #define	HIDPARSER_ITEM_REPORT_SIZE	0x74
305 #define	HIDPARSER_ITEM_REPORT_ID	0x84
306 #define	HIDPARSER_ITEM_REPORT_COUNT	0x94
307 
308 /*
309  * Main Items
310  *	See section 6.2.2.5 of the HID 1.0 specification for
311  *	more details.
312  */
313 #define	HIDPARSER_ITEM_INPUT		0x80
314 #define	HIDPARSER_ITEM_OUTPUT		0x90
315 #define	HIDPARSER_ITEM_FEATURE		0xB0
316 #define	HIDPARSER_ITEM_COLLECTION	0xA0
317 
318 
319 /*
320  * Macros to extract the usage page and usage id from a 32 bit usage
321  * value.
322  */
323 #define	HID_USAGE_ID(usage)		((usage) & 0xffff)
324 #define	HID_USAGE_PAGE(usage)		((usage)>>16 & 0xffff)
325 #define	HID_BUILD_USAGE(page, id)	(((page) & 0xffff) << 16 | \
326 					((id) & 0xffff))
327 
328 /*
329  * Usage Pages
330  *	See the "Universal Serial Bus HID Usages Table"
331  *	specification for more information
332  */
333 #define	HID_GENERIC_DESKTOP		0x01
334 #define	HID_KEYBOARD_KEYPAD_KEYS	0x07
335 #define	HID_LEDS			0x08
336 #define	HID_CONSUMER			0x0C
337 #define	HID_BUTTON_PAGE			0x09
338 
339 /*
340  * Any Usage Page
341  *	See the "Universal Serial Bus HID Usages Table"
342  *	specification for more information
343  */
344 #define	HID_USAGE_UNDEFINED	0x00
345 
346 /*
347  * Generic Desktop Page (0x01)
348  *	See the "Universal Serial Bus HID Usages Table"
349  *	specification for more information
350  */
351 #define	HID_GD_POINTER		0x01
352 #define	HID_GD_MOUSE		0x02
353 #define	HID_GD_KEYBOARD		0x06
354 #define	HID_GD_X		0x30
355 #define	HID_GD_Y		0x31
356 #define	HID_GD_Z		0x32
357 #define	HID_GD_WHEEL		0x38
358 
359 /*
360  * LED Page (0x08)
361  *	See the "Universal Serial Bus HID Usages Table"
362  *	specification for more information
363  */
364 #define	HID_LED_NUM_LOCK	0x01
365 #define	HID_LED_CAPS_LOCK	0x02
366 #define	HID_LED_SCROLL_LOCK	0x03
367 #define	HID_LED_COMPOSE		0x04
368 #define	HID_LED_KANA		0x05
369 
370 /*
371  * Consumer page (0x0C)
372  *	See the "Universal Serial Bus HID Usages Table"
373  *	specification for more information
374  */
375 #define	HID_CONSUMER_CONTROL	0x01
376 #define	HID_CONSUMER_MICROPHONE	0x04
377 #define	HID_CONSUMER_HEADPHONE	0x05
378 #define	HID_CONSUMER_GRAPHIC_EQ	0x06
379 #define	HID_CONSUMER_PLAY	0xB0
380 #define	HID_CONSUMER_RECORD	0xB2
381 #define	HID_CONSUMER_VOL	0xE0
382 #define	HID_CONSUMER_BALANCE	0xE1
383 #define	HID_CONSUMER_MUTE	0xE2
384 #define	HID_CONSUMER_BASS	0xE3
385 #define	HID_CONSUMER_TREBLE	0xE4
386 #define	HID_CONSUMER_VOL_INCR	0xE9
387 #define	HID_CONSUMER_VOL_DECR	0xEA
388 #define	HID_CONSUMER_BAL_RIGHT	0x150
389 #define	HID_CONSUMER_BAL_LEFT	0x151
390 #define	HID_CONSUMER_BASS_INCR	0x152
391 #define	HID_CONSUMER_BASS_DECR	0x153
392 #define	HID_CONSUMER_TREBLE_INCR 0x154
393 #define	HID_CONSUMER_TREBLE_DECR 0x155
394 
395 
396 /*
397  * Main Item Data Descriptor Information for
398  *	Input, Output, and Feature Main Items
399  *	See section 6.2.2.5 of the HID 1.0 specification for
400  *	more details.
401  */
402 
403 
404 #define	HID_MAIN_ITEM_DATA		0x0000
405 #define	HID_MAIN_ITEM_CONSTANT		0x0001
406 #define	HID_MAIN_ITEM_ARRAY		0x0000
407 #define	HID_MAIN_ITEM_VARIABLE		0x0002
408 #define	HID_MAIN_ITEM_ABSOLUTE		0x0000
409 #define	HID_MAIN_ITEM_RELATIVE		0x0004
410 #define	HID_MAIN_ITEM_NO_WRAP		0x0000
411 #define	HID_MAIN_ITEM_WRAP		0x0008
412 #define	HID_MAIN_ITEM_LINEAR		0x0000
413 #define	HID_MAIN_ITEM_NONLINEAR		0x0010
414 #define	HID_MAIN_ITEM_PREFERRED 	0x0000
415 #define	HID_MAIN_ITEM_NO_PREFERRED	0x0020
416 #define	HID_MAIN_ITEM_NO_NULL		0x0000
417 #define	HID_MAIN_ITEM_NULL		0x0040
418 #define	HID_MAIN_ITEM_NON_VOLATILE	0x0000
419 #define	HID_MAIN_ITEM_VOLATILE		0x0080
420 #define	HID_MAIN_ITEM_BIT_FIELD		0x0000
421 #define	HID_MAIN_ITEM_BUFFERED_BYTE	0x0100
422 
423 /*
424  * Main Item Data Descriptor Information for
425  *	Collection Main Items
426  *	See section 6.2.2.4 of the HID 1.0 specification for
427  *	more details.
428  */
429 #define	HID_MAIN_ITEM_PHYSICAL		0x0000
430 #define	HID_MAIN_ITEM_APPLICATION	0x0001
431 #define	HID_MAIN_ITEM_LOGICAL		0x0002
432 
433 
434 /*
435  * Other
436  */
437 #define	HIDPARSER_SUCCESS	0
438 #define	HIDPARSER_FAILURE	1
439 #define	HIDPARSER_NOT_FOUND	2
440 
441 #ifdef __cplusplus
442 }
443 #endif
444 
445 #endif	/* _SYS_USB_HIDPARSER_H */
446