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, Version 1.0 only 6 * (the "License"). You may not use this file except in compliance 7 * with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or http://www.opensolaris.org/os/licensing. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22 /* 23 * Copyright 2005 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 #ifndef _SYS_USB_HIDPARSER_H 28 #define _SYS_USB_HIDPARSER_H 29 30 #pragma ident "%Z%%M% %I% %E% SMI" 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 #include <sys/usb/usbai.h> 37 #include <sys/usb/usba/usbai_private.h> 38 39 /* 40 * This file contains interfaces accessible by both the hid driver and 41 * a hid module. 42 */ 43 44 /* 45 * HID parser handle 46 * The handle is opaque to the hid driver as well as the hid streams 47 * modules. 48 */ 49 typedef struct hidparser_handle_impl *hidparser_handle_t; 50 51 #define HID_REPORT_ID_UNDEFINED 0 52 53 54 #define USAGE_MAX 20 /* Max no. of usages in a report */ 55 56 typedef struct hidparser_usage_info { 57 uint16_t usage_page; 58 uint16_t usage_id; 59 uint32_t usage_min; 60 uint32_t usage_max; 61 uint32_t collection_usage; 62 int32_t lmax; 63 int32_t lmin; 64 uint32_t rptcnt; 65 uint32_t rptsz; 66 } hidparser_usage_info_t; 67 68 /* 69 * structure for each report type, INPUT, OUTPUT or FEATURE 70 * Note report id 0 and only one collection is handled 71 */ 72 typedef struct hidparser_rpt { 73 uint_t report_id; 74 uint_t main_item_value; 75 uint_t no_of_usages; 76 hidparser_usage_info_t usage_descr[USAGE_MAX]; 77 } hidparser_rpt_t; 78 79 /* 80 * structure to return a list of report id used for a report 81 * type, INPUT, OUTPUT or FEATURE. 82 */ 83 #define REPORT_ID_MAX 10 /* Max no. of report ids supported per type */ 84 85 typedef struct hidparser_report_id_list { 86 uint_t main_item_value; 87 uint_t no_of_report_ids; 88 uint_t report_id[REPORT_ID_MAX]; 89 } hidparser_report_id_list_t; 90 91 typedef struct hidparser_packet_info { 92 uint_t max_packet_size; 93 uint_t report_id; 94 } hidparser_packet_info_t; 95 96 /* 97 * hidparser_get_country_code(): 98 * Obtain the country code value that was returned in the hid descriptor 99 * Fill in the country_code argument 100 * 101 * Arguments: 102 * parser_handle: 103 * hid parser handle 104 * country code 105 * filled in with the country code value, upon success 106 * 107 * Return values: 108 * HIDPARSER_SUCCESS - returned on success 109 * HIDPARSER_FAILURE - returned on an unspecified error 110 */ 111 int hidparser_get_country_code(hidparser_handle_t parser_handle, 112 uint16_t *country_code); 113 114 115 /* 116 * hidparser_get_packet_size(): 117 * Obtain the size(no. of bits) for a particular packet type. Note 118 * that a hid transfer may span more than one USB transaction. 119 * 120 * Arguments: 121 * parser_handle: 122 * hid parser handle 123 * report_id: 124 * report id 125 * main_item_type: 126 * type of report, either Input, Output, or Feature 127 * size: 128 * the size if filled in upon success 129 * Return values: 130 * HIDPARSER_SUCCESS - returned success 131 * HIDPARSER_FAILURE - returned failure 132 */ 133 int hidparser_get_packet_size(hidparser_handle_t parser_handle, 134 uint_t report_id, 135 uint_t main_item_type, 136 uint_t *size); 137 138 /* 139 * hidparser_get_usage_attribute() 140 * Find the specified local item associated with the given usage. For 141 * example, this function may be used to find the logical minimum for 142 * an X usage. Note that only short items are supported. 143 * 144 * 145 * Arguments: 146 * parser_handle: 147 * hid parser handle 148 * report id: 149 * report id of the particular report that the usage may be 150 * found in. 151 * main_item_type: 152 * type of report, either Input, Output, or Feature 153 * usage_page: 154 * usage page that the Usage may be found on. 155 * usage: 156 * the Usage for which the local item will be found 157 * usage_attribute: 158 * type of local item to be found. Possible local and global 159 * items are given below. 160 * 161 * usage_attribute_value: 162 * filled in with the value of the attribute upon return 163 * 164 * Return values: 165 * HIDPARSER_SUCCESS - returned success 166 * HIDPARSER_NOT_FOUND - usage specified by the parameters was not found 167 * HIDPARSER_FAILURE - unspecified failure 168 * 169 */ 170 int hidparser_get_usage_attribute(hidparser_handle_t parser_handle, 171 uint_t report_id, 172 uint_t main_item_type, 173 uint_t usage_page, 174 uint_t usage, 175 uint_t usage_attribute, 176 int *usage_attribute_value); 177 178 /* 179 * hidparser_get_main_item_data_descr() 180 * 181 * Description: 182 * Query the parser to find the data description of the main item. 183 * Section 6.2.2.5 of the HID 1.0 specification gives details 184 * about the data descriptions. For example, this function may be 185 * used to find out if an X value sent by the a USB mouse is an 186 * absolute or relative value. 187 * 188 * Parameters: 189 * parser_handle parser handle 190 * report_id report id of the particular report that the 191 * usage may be found in 192 * main_item_type type of report - either Input, Output, Feature, 193 * or Collection 194 * usage_page usage page that the usage may be found on 195 * usage type of local item to be found 196 * main_item_descr_value filled in with the data description 197 * 198 * Return values: 199 * HIDPARSER_SUCCESS attribute found successfully 200 * HIDPARSER_NOT_FOUND usage specified by the parameters was not found 201 * HIDPARSER_FAILURE unspecified failure 202 */ 203 int 204 hidparser_get_main_item_data_descr( 205 hidparser_handle_t parser_handle, 206 uint_t report_id, 207 uint_t main_item_type, 208 uint_t usage_page, 209 uint_t usage, 210 uint_t *main_item_descr_value); 211 212 213 /* 214 * hidparser_get_usage_list_in_order() 215 * Find all the usages corresponding to a main item, report id and 216 * a particular usage page. 217 * Note that only short items and 0 report id is supported. 218 * 219 * Arguments: 220 * parser_handle: 221 * hid parser handle 222 * report id: 223 * report id of the particular report where the usages belong to 224 * main_item_type: 225 * type of report, either Input, Output, or Feature 226 * usage_list: 227 * Filled in with the pointer to the first element of the 228 * usage list 229 * 230 * Return values: 231 * HIDPARSER_SUCCESS - returned success 232 * HIDPARSER_NOT_FOUND - usage specified by the parameters was not found 233 * HIDPARSER_FAILURE - unspecified failure 234 */ 235 int 236 hidparser_get_usage_list_in_order(hidparser_handle_t parse_handle, 237 uint_t report_id, 238 uint_t main_item_type, 239 hidparser_rpt_t *rpt); 240 241 242 /* 243 * hidparser_get_report_id_list() 244 * Return a list of all report ids used for descriptor items 245 * corresponding to a main item. 246 * 247 * Arguments: 248 * parser_handle: 249 * hid parser handle 250 * main_item_type: 251 * type of report, either Input, Output, or Feature 252 * report_id_list: 253 * Filled in with a list of report ids found in the descriptor 254 * 255 * Return values: 256 * HIDPARSER_SUCCESS - returned success 257 * HIDPARSER_FAILURE - unspecified failure 258 */ 259 int 260 hidparser_get_report_id_list(hidparser_handle_t parser_handle, 261 uint_t main_item_type, hidparser_report_id_list_t *report_id_list); 262 263 /* 264 * hidparser_find_max_packet_size_from_report_descriptor() 265 * Returns the packet size of the largest report in the complete 266 * report descriptor. 267 * 268 * Arguments 269 * parser_handle: 270 * hidparser_handle_t 271 * packet_info: 272 * hidparser_packet_info_t * 273 */ 274 void 275 hidparser_find_max_packet_size_from_report_descriptor( 276 hidparser_handle_t parser_handle, hidparser_packet_info_t *hpack); 277 278 279 280 /* 281 * Local Items 282 * See section 6.2.2.8 of the HID 1.0 specification for 283 * more details. 284 */ 285 #define HIDPARSER_ITEM_USAGE 0x08 286 #define HIDPARSER_ITEM_USAGE_MIN 0x18 287 #define HIDPARSER_ITEM_USAGE_MAX 0x28 288 #define HIDPARSER_ITEM_DESIGNATOR_INDEX 0x38 289 #define HIDPARSER_ITEM_DESIGNATOR_MIN 0x48 290 #define HIDPARSER_ITEM_DESIGNATOR_MAX 0x58 291 #define HIDPARSER_ITEM_STRING_INDEX 0x78 292 #define HIDPARSER_ITEM_STRING_MIN 0x88 293 #define HIDPARSER_ITEM_STRING_MAX 0x98 294 295 /* 296 * Global Items 297 * See section 6.2.2.7 of the HID 1.0 specifations for 298 * more details. 299 */ 300 #define HIDPARSER_ITEM_LOGICAL_MINIMUM 0x14 301 #define HIDPARSER_ITEM_LOGICAL_MAXIMUM 0x24 302 #define HIDPARSER_ITEM_PHYSICAL_MINIMUM 0x34 303 #define HIDPARSER_ITEM_PHYSICAL_MAXIMUM 0x44 304 #define HIDPARSER_ITEM_EXPONENT 0x54 305 #define HIDPARSER_ITEM_UNIT 0x64 306 #define HIDPARSER_ITEM_REPORT_SIZE 0x74 307 #define HIDPARSER_ITEM_REPORT_ID 0x84 308 #define HIDPARSER_ITEM_REPORT_COUNT 0x94 309 310 /* 311 * Main Items 312 * See section 6.2.2.5 of the HID 1.0 specification for 313 * more details. 314 */ 315 #define HIDPARSER_ITEM_INPUT 0x80 316 #define HIDPARSER_ITEM_OUTPUT 0x90 317 #define HIDPARSER_ITEM_FEATURE 0xB0 318 #define HIDPARSER_ITEM_COLLECTION 0xA0 319 320 321 /* 322 * Macros to extract the usage page and usage id from a 32 bit usage 323 * value. 324 */ 325 #define HID_USAGE_ID(usage) ((usage) & 0xffff) 326 #define HID_USAGE_PAGE(usage) ((usage)>>16 & 0xffff) 327 #define HID_BUILD_USAGE(page, id) (((page) & 0xffff) << 16 | \ 328 ((id) & 0xffff)) 329 330 /* 331 * Usage Pages 332 * See the "Universal Serial Bus HID Usages Table" 333 * specification for more information 334 */ 335 #define HID_GENERIC_DESKTOP 0x01 336 #define HID_KEYBOARD_KEYPAD_KEYS 0x07 337 #define HID_LEDS 0x08 338 #define HID_CONSUMER 0x0C 339 #define HID_BUTTON_PAGE 0x09 340 341 /* 342 * Any Usage Page 343 * See the "Universal Serial Bus HID Usages Table" 344 * specification for more information 345 */ 346 #define HID_USAGE_UNDEFINED 0x00 347 348 /* 349 * Generic Desktop Page (0x01) 350 * See the "Universal Serial Bus HID Usages Table" 351 * specification for more information 352 */ 353 #define HID_GD_POINTER 0x01 354 #define HID_GD_MOUSE 0x02 355 #define HID_GD_KEYBOARD 0x06 356 #define HID_GD_X 0x30 357 #define HID_GD_Y 0x31 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