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
31extern "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 */
47typedef 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
54typedef 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 */
70typedef 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
83typedef 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
89typedef 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 */
109int 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 */
131int 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 */
168int 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 */
201int
202hidparser_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 */
233int
234hidparser_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 */
257int
258hidparser_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 */
272void
273hidparser_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