1/** 2 * \brief this file contains definitions for the the USB HID class 3 */ 4 5/* 6 * Copyright (c) 2007-2013 ETH Zurich. 7 * All rights reserved. 8 * 9 * This file is distributed under the terms in the attached LICENSE file. 10 * If you do not find this file, copies can be found by writing to: 11 * ETH Zurich D-INFK, Universitaetstrasse 6, CH-8092 Zurich. Attn: Systems Group. 12 */ 13 14#ifndef LIBUSB_CLASS_HID_H_ 15#define LIBUSB_CLASS_HID_H_ 16 17#include <usb/usb_descriptor.h> 18 19#define USB_HID_CLASS_CODE 0x3 20#define USB_HID_SUBCLASS_CODE_BOOT 0x1 21#define USB_HID_PROTOCOL_NONE 0x0 22#define USB_HID_PROTOCOL_KEYBOARD 0x1 23#define USB_HID_PROTOCOL_MOUSE 0x2 24 25/* 26 * USB HID class descriptor types 27 */ 28 29/// Descriptor type for the HID 30#define USB_DESCRIPTOR_TYPE_HID 0x21 31 32/// Descriptor type for HID report 33#define USB_DESCRIPTOR_TYPE_REPORT 0x22 34 35/// descriptor type for HID physical 36#define USB_DESCRIPTOR_TYPE_PHYSICAL 0x23 37 38/* 39 * HID class specific request types 40 */ 41 42#define USB_HID_REQUEST_GET_REPORT 0x01 43#define USB_HID_REQUEST_SET_REPORT 0x09 44 45#define USB_HID_REQUEST_GET_IDLE 0x02 46#define USB_HID_REQUEST_SET_IDLE 0x0A 47 48#define USB_HID_REQUEST_GET_PROTOCOL 0x03 49#define USB_HID_REQUEST_SET_PROTOCOL 0x0B 50 51#define USB_HID_REQUEST_GET_DESCRIPTOR 0x06 52#define USB_HID_REQUEST_SET_DESCRIPTOR 0x07 53 54/** 55 * struct definition for a HID descriptor type 56 * XXX: the length cannot be an uint16, because of alignment issues 57 */ 58struct usb_hid_dtype { 59 uint8_t bDescriptorType; ///< the type of the optional descriptor 60 uint8_t wDescriptorLength[2]; ///< the size of the optional descriptor 61}__attribute__((packed)); 62 63/// type definition of the HID descriptor type 64typedef struct usb_hid_dtype usb_hid_dtype_t; 65 66/// makro definition for getting the length of a descriptor type 67#define USB_HID_DTYPE_GET_LEN(_d) \ 68 ((_d)->wDescriptorLength[0] | ((uint16_t)((_d)->wDescriptorLength[1] << 8))) 69 70/** 71 * USB HID Descriptor Type 72 * Device Class Definition for HID Devices, Section 6.2.1 73 * 74 * Note: This descriptor is of variable size, the last field descriptors 75 * contains the information of at least one descriptor (i.e. the report 76 * descriptor) 77 */ 78struct usb_hid_descriptor { 79 uint8_t bLength; ///< the total size in bytes of this descr 80 uint8_t bDescriptorType; ///< constant, specifying the HID descr type 81 uint16_t bcdHID; ///< HID class specific release version 82 uint8_t bCountryCode; ///< country code for localized hardware 83 uint8_t bNumDescriptors; ///< the number of class descriptors > 1 84 usb_hid_dtype_t descriptors[1]; ///< subordinate descriptors 85}__attribute__((packed)); 86 87/// USB HID descriptor type 88typedef struct usb_hid_descriptor usb_hid_descriptor_t; 89 90/// calcualtes the size of the HID descriptor 91#define USB_HID_DESCRIPTOR_SIZE(n) (9+((n)*3)) 92 93/* 94 * ------------------------------------------------------------------------- 95 * USB HID class report items 96 * ------------------------------------------------------------------------- 97 */ 98 99#define USB_HID_REPORT_INPUT 0x01 100#define USB_HID_REPORT_OUTPUT 0x02 101#define USB_HID_REPORT_FEATURE 0x03 102 103/* 104 * some flags 105 */ 106#define USB_HID_IO_CONST 0x001 107#define USB_HID_IO_VARIABLE 0x002 108#define USB_HID_IO_RELATIVE 0x004 109#define USB_HID_IO_WRAP 0x008 110#define USB_HID_IO_NONLINEAR 0x010 111#define USB_HID_IO_NOPREF 0x020 112#define USB_HID_IO_NULLSTATE 0x040 113#define USB_HID_IO_VOLATILE 0x080 114#define USB_HID_IO_BUFBYTES 0x100 115 116/// enumeration representing the type of the report item 117enum usb_hid_kind { 118 USB_HID_KIND_INPUT = 0, ///< input report 119 USB_HID_KIND_OUTPUT = 1, ///< output report 120 USB_HID_KIND_FEATURE = 2, ///< feature report 121 USB_HID_KIND_COLLECTION = 3, ///< collection start 122 USB_HID_KIND_ENDCOLLECTION = 4, ///< collection end 123}; 124 125/// struct definition for report id - position association 126struct usb_hid_pos_data { 127 int32_t rid; ///< report id 128 uint32_t position; ///< position 129}; 130 131/// struct definition for storing information about the HID item in an report 132struct usb_hid_location { 133 uint32_t size; ///< the size of one item element 134 uint32_t count; ///< the number of elements in this location 135 uint32_t position; ///< the position within the report 136}; 137 138/// This struct represents an item in a USB report 139struct usb_hid_item { 140 /* Global */ 141 int32_t _usage_page; ///< 142 int32_t logical_minimum; ///< 143 int32_t logical_maximum; ///< 144 int32_t physical_minimum; ///< 145 int32_t physical_maximum; ///< 146 int32_t unit_exponent; ///< 147 int32_t unit; ///< 148 int32_t report_ID; ///< 149 /* Local */ 150 int32_t usage; ///< 151 int32_t usage_minimum; ///< 152 int32_t usage_maximum; ///< 153 int32_t designator_index; ///< 154 int32_t designator_minimum; ///< 155 int32_t designator_maximum; ///< 156 int32_t string_index; ///< 157 int32_t string_minimum; ///< 158 int32_t string_maximum; ///< 159 int32_t set_delimiter; ///< 160 /* Misc */ 161 int32_t collection; ///< 162 int32_t collevel; ///< 163 enum usb_hid_kind kind; ///< 164 uint32_t flags; ///< 165 /* Location */ 166 struct usb_hid_location loc; ///< 167}; 168 169/* 170 * definitions for parsing the report descriptors 171 */ 172 173#define USB_HID_MAXUSAGE 64 174#define USB_HID_MAXPUSH 4 175#define USB_HID_MAXID 16 176 177/** 178 * this structure is used for storing the necessary data when parsing 179 * USB HID reports 180 */ 181struct usb_hid_data { 182 const uint8_t *start; 183 const uint8_t *end; 184 const uint8_t *p; 185 struct usb_hid_item cur[USB_HID_MAXPUSH]; 186 struct usb_hid_pos_data last_pos[USB_HID_MAXID]; 187 int32_t usages_min[USB_HID_MAXUSAGE]; 188 int32_t usages_max[USB_HID_MAXUSAGE]; 189 int32_t usage_last; /* last seen usage */ 190 uint32_t loc_size; /* last seen size */ 191 uint32_t loc_count; /* last seen count */ 192 uint8_t kindset; /* we have 5 kinds so 8 bits are enough */ 193 uint8_t pushlevel; /* current pushlevel */ 194 uint8_t ncount; /* end usage item count */ 195 uint8_t icount; /* current usage item count */ 196 uint8_t nusage; /* end "usages_min/max" index */ 197 uint8_t iusage; /* current "usages_min/max" index */ 198 uint8_t ousage; /* current "usages_min/max" offset */ 199 uint8_t susage; /* usage set flags */ 200}; 201 202#define USB_HID_REQUEST_TYPE_WRITE 0xA1 203#define USB_HID_REQUEST_TYPE_READ 0x21 204 205#define USB_HID_REQUEST_VALUE_IN 0x01 206#define USB_HID_REQUEST_VALUE_OUT 0x02 207#define USB_HID_REQUEST_VALUE_FEATURE 0x03 208 209/* 210 * ------------------------------------------------------------------------- 211 * Country Codes 212 * ------------------------------------------------------------------------- 213 */ 214 215#define USB_HID_COUNTRY_DEFAULT 0 216#define USB_HID_COUNTRY_ARABIC 1 217#define USB_HID_COUNTRY_BELGIAN 2 218#define USB_HID_COUNTRY_CANADIAN 3 219#define USB_HID_COUNTRY_CANADIAN_FRENCH 4 220#define USB_HID_COUNTRY_CZECH 5 221#define USB_HID_COUNTRY_DANISH 6 222#define USB_HID_COUNTRY_FINNISH 7 223#define USB_HID_COUNTRY_FRENCH 8 224#define USB_HID_COUNTRY_GERMAN 9 225#define USB_HID_COUNTRY_GREEK 10 226#define USB_HID_COUNTRY_HEBREW 11 227#define USB_HID_COUNTRY_HUNGARY 12 228#define USB_HID_COUNTRY_INTERNATIONAL 13 229#define USB_HID_COUNTRY_ITALIAN 14 230#define USB_HID_COUNTRY_JAPAN 15 231#define USB_HID_COUNTRY_KOREAN 16 232#define USB_HID_COUNTRY_LATIN 17 233#define USB_HID_COUNTRY_DUTCH 18 234#define USB_HID_COUNTRY_NORWEGIAN 19 235#define USB_HID_COUNTRY_PERSIAN 20 236#define USB_HID_COUNTRY_POLAND 21 237#define USB_HID_COUNTRY_PORTUGUESE 22 238#define USB_HID_COUNTRY_RUSSIA 23 239#define USB_HID_COUNTRY_SLOVAKIA 24 240#define USB_HID_COUNTRY_SPANISH 25 241#define USB_HID_COUNTRY_SWEDISH 26 242#define USB_HID_COUNTRY_SWISS_FRENCH 27 243#define USB_HID_COUNTRY_SWISS_GERMAN 28 244#define USB_HID_COUNTRY_SWITZERLAND 29 245#define USB_HID_COUNTRY_TAIWAN 30 246#define USB_HID_COUNTRY_TURKISH_Q 31 247#define USB_HID_COUNTRY_UK 32 248#define USB_HID_COUNTRY_US 33 249#define USB_HID_COUNTRY_YUGOSLAVIA 34 250#define USB_HID_COUNTRY_TURKISH_F 35 251// other 36-255 reserved 252 253/* 254 * ------------------------------------------------------------------------- 255 * USB HID Physical Designator Values 256 * 257 * This defines specify which part of the human body 258 * triggered the input. 259 * 260 * e.g. the hand or finger 261 * ------------------------------------------------------------------------- 262 */ 263#define USB_HID_DESIGNATOR_NONE 0x00 264#define USB_HID_DESIGNATOR_HAND 0x01 265#define USB_HID_DESIGNATOR_EYEBALL 0x02 266#define USB_HID_DESIGNATOR_EYEBROW 0x03 267#define USB_HID_DESIGNATOR_EYELID 0x04 268#define USB_HID_DESIGNATOR_EAR 0x05 269#define USB_HID_DESIGNATOR_NOSE 0x06 270#define USB_HID_DESIGNATOR_MOUTH 0x07 271#define USB_HID_DESIGNATOR_UPPER_LIP 0x08 272#define USB_HID_DESIGNATOR_LOWER_LIP 0x09 273#define USB_HID_DESIGNATOR_JAW 0x0A 274#define USB_HID_DESIGNATOR_NECK 0x0B 275#define USB_HID_DESIGNATOR_UPPER_ARM 0x0C 276#define USB_HID_DESIGNATOR_ELBOW 0x0D 277#define USB_HID_DESIGNATOR_FOREARM 0x0E 278#define USB_HID_DESIGNATOR_WRIST 0x0F 279#define USB_HID_DESIGNATOR_PALM 0x10 280#define USB_HID_DESIGNATOR_THUMB 0x11 281#define USB_HID_DESIGNATOR_I_FINGER 0x12 282#define USB_HID_DESIGNATOR_M_FINGER 0x13 283#define USB_HID_DESIGNATOR_R_FINGER 0x14 284#define USB_HID_DESIGNATOR_L_FINGER 0x15 285#define USB_HID_DESIGNATOR_HEAD 0x16 286#define USB_HID_DESIGNATOR_SHOULDER 0x17 287#define USB_HID_DESIGNATOR_HIP 0x18 288#define USB_HID_DESIGNATOR_WAIST 0x19 289#define USB_HID_DESIGNATOR_THIGH 0x1A 290#define USB_HID_DESIGNATOR_KNEE 0x1B 291#define USB_HID_DESIGNATOR_CALF 0x1C 292#define USB_HID_DESIGNATOR_ANKLE 0x1D 293#define USB_HID_DESIGNATOR_FOOT 0x1E 294#define USB_HID_DESIGNATOR_HEEL 0x1F 295#define USB_HID_DESIGNATOR_BALL_FOOT 0x20 296#define USB_HID_DESIGNATOR_BIG_TOE 0x21 297#define USB_HID_DESIGNATOR_TOE_2 0x22 298#define USB_HID_DESIGNATOR_TOE_3 0x23 299#define USB_HID_DESIGNATOR_TOE_4 0x24 300#define USB_HID_DESIGNATOR_TOE_5 0x25 301#define USB_HID_DESIGNATOR_BROW 0x26 302#define USB_HID_DESIGNATOR_CHEEK 0x27 303/* 28-FF reserved */ 304 305/* 306 * ------------------------------------------------------------------------- 307 * USB HID Physical Qualifier Fields 308 * 309 * This values represent which of the possible multiple input 310 * designators triggered the input. 311 * 312 * e.g. right or left hand 313 * ------------------------------------------------------------------------- 314 */ 315#define USB_HID_PHYSICAL_QUALIFIER_NONE 0x0 316#define USB_HID_PHYSICAL_QUALIFIER_RIGHT 0x1 317#define USB_HID_PHYSICAL_QUALIFIER_LEFT 0x2 318#define USB_HID_PHYSICAL_QUALIFIER_BOTH 0x3 319#define USB_HID_PHYSICAL_QUALIFIER_EITHER 0x4 320#define USB_HID_PHYSICAL_QUALIFIER_CENTER 0x5 321#define USB_HID_PHYSICAL_QUALIFIER_RESERVED 0x6 322#define USB_HID_PHYSICAL_QUALIFIER_RESERVED_ 0x7 323 324/* 325 * ------------------------------------------------------------------------- 326 * USB HID Usages 327 * ------------------------------------------------------------------------- 328 */ 329#define USB_HID_USAGE_UNDEFINED 0x0000 330#define USB_HID_USAGE_GENERIC_DESKTOP 0x0001 331#define USB_HID_USAGE_SIMULATION 0x0002 332#define USB_HID_USAGE_VR_CONTROLS 0x0003 333#define USB_HID_USAGE_SPORTS_CONTROLS 0x0004 334#define USB_HID_USAGE_GAMING_CONTROLS 0x0005 335#define USB_HID_USAGE_KEYBOARD 0x0007 336#define USB_HID_USAGE_LEDS 0x0008 337#define USB_HID_USAGE_BUTTON 0x0009 338#define USB_HID_USAGE_ORDINALS 0x000a 339#define USB_HID_USAGE_TELEPHONY 0x000b 340#define USB_HID_USAGE_CONSUMER 0x000c 341#define USB_HID_USAGE_DIGITIZERS 0x000d 342#define USB_HID_USAGE_PHYSICAL_IFACE 0x000e 343#define USB_HID_USAGE_UNICODE 0x0010 344#define USB_HID_USAGE_ALPHANUM_DISPLAY 0x0014 345#define USB_HID_USAGE_MONITOR 0x0080 346#define USB_HID_USAGE_MONITOR_ENUM_VAL 0x0081 347#define USB_HID_USAGE_VESA_VC 0x0082 348#define USB_HID_USAGE_VESA_CMD 0x0083 349#define USB_HID_USAGE_POWER 0x0084 350#define USB_HID_USAGE_BATTERY_SYSTEM 0x0085 351#define USB_HID_USAGE_BARCODE_SCANNER 0x008b 352#define USB_HID_USAGE_SCALE 0x008c 353#define USB_HID_USAGE_CAMERA_CONTROL 0x0090 354#define USB_HID_USAGE_ARCADE 0x0091 355#define USB_HID_USAGE_MICROSOFT 0xff00 356 357/* Usages, generic desktop */ 358#define USB_HID_USAGE_POINTER 0x0001 359#define USB_HID_USAGE_MOUSE 0x0002 360#define USB_HID_USAGE_JOYSTICK 0x0004 361#define USB_HID_USAGE_GAME_PAD 0x0005 362#define USB_HID_USAGE_DKEYBOARD 0x0006 363#define USB_HID_USAGE_KEYPAD 0x0007 364#define USB_HID_USAGE_X 0x0030 365#define USB_HID_USAGE_Y 0x0031 366#define USB_HID_USAGE_Z 0x0032 367#define USB_HID_USAGE_RX 0x0033 368#define USB_HID_USAGE_RY 0x0034 369#define USB_HID_USAGE_RZ 0x0035 370#define USB_HID_USAGE_SLIDER 0x0036 371#define USB_HID_USAGE_DIAL 0x0037 372#define USB_HID_USAGE_WHEEL 0x0038 373#define USB_HID_USAGE_HAT_SWITCH 0x0039 374#define USB_HID_USAGE_COUNTED_BUFFER 0x003a 375#define USB_HID_USAGE_BYTE_COUNT 0x003b 376#define USB_HID_USAGE_MOTION_WAKEUP 0x003c 377#define USB_HID_USAGE_VX 0x0040 378#define USB_HID_USAGE_VY 0x0041 379#define USB_HID_USAGE_VZ 0x0042 380#define USB_HID_USAGE_VBRX 0x0043 381#define USB_HID_USAGE_VBRY 0x0044 382#define USB_HID_USAGE_VBRZ 0x0045 383#define USB_HID_USAGE_VNO 0x0046 384#define USB_HID_USAGE_TWHEEL 0x0048 385#define USB_HID_USAGE_SYSTEM_CONTROL 0x0080 386#define USB_HID_USAGE_SYSTEM_POWER_DOWN 0x0081 387#define USB_HID_USAGE_SYSTEM_SLEEP 0x0082 388#define USB_HID_USAGE_SYSTEM_WAKEUP 0x0083 389#define USB_HID_USAGE_SYSTEM_CONTEXT_MENU 0x0084 390#define USB_HID_USAGE_SYSTEM_MAIN_MENU 0x0085 391#define USB_HID_USAGE_SYSTEM_APP_MENU 0x0086 392#define USB_HID_USAGE_SYSTEM_MENU_HELP 0x0087 393#define USB_HID_USAGE_SYSTEM_MENU_EXIT 0x0088 394#define USB_HID_USAGE_SYSTEM_MENU_SELECT 0x0089 395#define USB_HID_USAGE_SYSTEM_MENU_RIGHT 0x008a 396#define USB_HID_USAGE_SYSTEM_MENU_LEFT 0x008b 397#define USB_HID_USAGE_SYSTEM_MENU_UP 0x008c 398#define USB_HID_USAGE_SYSTEM_MENU_DOWN 0x008d 399#define USB_HID_USAGE_APPLE_EJECT 0x00b8 400 401/* Usages Digitizers */ 402#define USB_HID_USAGE_UNDEFINED 0x0000 403#define USB_HID_USAGE_TIP_PRESSURE 0x0030 404#define USB_HID_USAGE_BARREL_PRESSURE 0x0031 405#define USB_HID_USAGE_IN_RANGE 0x0032 406#define USB_HID_USAGE_TOUCH 0x0033 407#define USB_HID_USAGE_UNTOUCH 0x0034 408#define USB_HID_USAGE_TAP 0x0035 409#define USB_HID_USAGE_QUALITY 0x0036 410#define USB_HID_USAGE_DATA_VALID 0x0037 411#define USB_HID_USAGE_TRANSDUCER_INDEX 0x0038 412#define USB_HID_USAGE_TABLET_FKEYS 0x0039 413#define USB_HID_USAGE_PROGRAM_CHANGE_KEYS 0x003a 414#define USB_HID_USAGE_BATTERY_STRENGTH 0x003b 415#define USB_HID_USAGE_INVERT 0x003c 416#define USB_HID_USAGE_X_TILT 0x003d 417#define USB_HID_USAGE_Y_TILT 0x003e 418#define USB_HID_USAGE_AZIMUTH 0x003f 419#define USB_HID_USAGE_ALTITUDE 0x0040 420#define USB_HID_USAGE_TWIST 0x0041 421#define USB_HID_USAGE_TIP_SWITCH 0x0042 422#define USB_HID_USAGE_SEC_TIP_SWITCH 0x0043 423#define USB_HID_USAGE_BARREL_SWITCH 0x0044 424#define USB_HID_USAGE_ERASER 0x0045 425#define USB_HID_USAGE_TABLET_PICK 0x0046 426 427/* Usages, Consumer */ 428#define USB_HID_USAGE_AC_PAN 0x0238 429 430/// Macro for combining two usages 431#define USB_HID_USAGE_COMBINE(x,y) (((x) << 16) | (y)) 432 433struct usb_hid_data *usb_hid_start_parse(const void *d, uint32_t len, 434 int32_t kindset); 435 436void usb_hid_end_parse(struct usb_hid_data *s); 437 438int32_t usb_hid_get_item(struct usb_hid_data *s, struct usb_hid_item *h); 439 440int32_t usb_hid_report_size(const void *buf, uint32_t len, enum usb_hid_kind k, 441 uint8_t *id); 442 443int32_t usb_hid_locate(const void *desc, uint32_t size, uint32_t usage, 444 enum usb_hid_kind kind, uint8_t index, struct usb_hid_location *loc, 445 uint32_t *flags, uint8_t *id); 446 447int32_t usb_hid_get_data(const uint8_t *buf, uint32_t len, 448 struct usb_hid_location *loc); 449 450uint32_t usb_hid_get_data_unsigned(const uint8_t *buf, uint32_t len, 451 struct usb_hid_location *loc); 452 453void usb_hid_put_data_unsigned(uint8_t *buf, uint32_t len, 454 struct usb_hid_location *loc, uint32_t value); 455 456int32_t usb_hid_is_collection(const void *desc, uint32_t size, uint32_t usage); 457 458struct usb_hid_descriptor *usb_hid_get_descriptor_from_usb( 459 struct usb_config_descriptor *cd, struct usb_interface_descriptor *id); 460 461usb_error_t usb_hid_get_hid_descriptor(struct usb_hid_descriptor **ret_desc, 462 uint16_t *ret_size, uint8_t iface_index); 463 464usb_error_t usb_hid_get_report_descriptor(struct usb_hid_descriptor **d, 465 uint16_t size, uint8_t iface); 466 467usb_error_t usb_hid_set_idle(uint8_t iface, uint8_t duration, uint8_t id); 468 469#endif /* LIBUSB_CLASS_HID_H_ */ 470 471