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 2008 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 20 /* 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