hidparser.h revision 7492:2387323b838f
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 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 20 /* 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