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