1 // Copyright 2017 The Fuchsia Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #pragma once 6 7 // This header contains elements that may be used to construct Human Interface 8 // Device (HID) descriptors, as defined by the USB Implementers Forum. 9 // 10 // The macros defined here expand to comma-separated byte values, and are 11 // suitable for use in array definitions. E.g. 12 // 13 // // This is a HID Descriptor that defines a Mouse with no buttons and two 14 // // relative positional axes. 15 // uint8_t hid_descriptor[] = { 16 // HID_USAGE_PAGE(1), // Generic Desktop 17 // HID_USAGE(2), // Mouse 18 // HID_COLLECTION_APPLICATION, 19 // HID_USAGE(1), // Pointer 20 // HID_COLLECTION_PHYSICAL, 21 // HID_LOGICAL_MIN(-127), 22 // HID_LOGICAL_MAX(-127), 23 // HID_REPORT_SIZE(8), 24 // HID_REPORT_COUNT(1), 25 // HID_USAGE(0x30), // X 26 // HID_INPUT(0x6), // Data Variable Relative 27 // HID_USAGE(0x31), // Y 28 // HID_INPUT(0x6), // Data Variable Relative 29 // HID_END_COLLECTION, 30 // HID_END_COLLECTION, 31 // }; 32 // 33 // Future Work: 34 // - Define nice shorthands for the argument to Input/Output/Feature 35 // - Define commonly used usage pages and usages 36 // - Define units element and commonly used units 37 // - Support Long Items 38 39 // clang-format off 40 #define _HID_LOW8(v) (unsigned char)(v) 41 #define _HID_SECOND8(v) (unsigned char)((v) >> 8) 42 #define _HID_THIRD8(v) (unsigned char)((v) >> 16) 43 #define _HID_HIGH8(v) (unsigned char)((v) >> 24) 44 #define _HID_MAIN_VAL(bTag, v) (((bTag) << 4) | 0x1), _HID_LOW8(v) 45 #define _HID_MAIN_VAL16(bTag, v) (((bTag) << 4) | 0x2), _HID_LOW8(v), _HID_SECOND8(v) 46 47 #define _HID_GLOBAL_VAL(bTag, v) (((bTag) << 4) | 0x5), _HID_LOW8(v) 48 #define _HID_GLOBAL_VAL16(bTag, v) (((bTag) << 4) | 0x6), _HID_LOW8(v), _HID_SECOND8(v) 49 #define _HID_GLOBAL_VAL32(bTag, v) (((bTag) << 4) | 0x7), _HID_LOW8(v), _HID_SECOND8(v), \ 50 _HID_THIRD8(v), _HID_HIGH8(v) 51 52 #define _HID_LOCAL_VAL(bTag, v) (((bTag) << 4) | 0x9), _HID_LOW8(v) 53 #define _HID_LOCAL_VAL16(bTag, v) (((bTag) << 4) | 0xa), _HID_LOW8(v), _HID_SECOND8(v) 54 55 // Main HID items 56 #define HID_INPUT(v) _HID_MAIN_VAL(0x8, v) 57 #define HID_INPUT16(v) _HID_MAIN_VAL16(0x8, v) 58 #define HID_OUTPUT(v) _HID_MAIN_VAL(0x9, v) 59 #define HID_OUTPUT16(v) _HID_MAIN_VAL16(0x9, v) 60 #define HID_FEATURE(v) _HID_MAIN_VAL(0xb, v) 61 #define HID_FEATURE16(v) _HID_MAIN_VAL16(0xb, v) 62 #define HID_COLLECTION(v) _HID_MAIN_VAL(0xa, v) 63 #define HID_END_COLLECTION 0xc0 64 65 #define HID_COLLECTION_PHYSICAL HID_COLLECTION(0) 66 #define HID_COLLECTION_APPLICATION HID_COLLECTION(1) 67 #define HID_COLLECTION_LOGICAL HID_COLLECTION(2) 68 #define HID_COLLECTION_REPORT HID_COLLECTION(3) 69 #define HID_COLLECTION_NAMED_ARRAY HID_COLLECTION(4) 70 #define HID_COLLECTION_USAGE_SWITCH HID_COLLECTION(5) 71 #define HID_COLLECTION_USAGE_MODIFIER HID_COLLECTION(6) 72 73 // Global HID items 74 #define HID_USAGE_PAGE(v) _HID_GLOBAL_VAL(0x0, v) 75 #define HID_USAGE_PAGE16(v) _HID_GLOBAL_VAL16(0x0, v) 76 #define HID_LOGICAL_MIN(v) _HID_GLOBAL_VAL(0x1, v) 77 #define HID_LOGICAL_MIN16(v) _HID_GLOBAL_VAL16(0x1, v) 78 #define HID_LOGICAL_MIN32(v) _HID_GLOBAL_VAL32(0x1, v) 79 #define HID_LOGICAL_MAX(v) _HID_GLOBAL_VAL(0x2, v) 80 #define HID_LOGICAL_MAX16(v) _HID_GLOBAL_VAL16(0x2, v) 81 #define HID_LOGICAL_MAX32(v) _HID_GLOBAL_VAL32(0x2, v) 82 #define HID_PHYSICAL_MIN(v) _HID_GLOBAL_VAL(0x3, v) 83 #define HID_PHYSICAL_MIN16(v) _HID_GLOBAL_VAL16(0x3, v) 84 #define HID_PHYSICAL_MIN32(v) _HID_GLOBAL_VAL32(0x3, v) 85 #define HID_PHYSICAL_MAX(v) _HID_GLOBAL_VAL(0x4, v) 86 #define HID_PHYSICAL_MAX16(v) _HID_GLOBAL_VAL16(0x4, v) 87 #define HID_PHYSICAL_MAX32(v) _HID_GLOBAL_VAL32(0x4, v) 88 #define HID_UNIT_EXPONENT(v) _HID_GLOBAL_VAL(0x5, (v) & 0xf) 89 #define HID_REPORT_SIZE(v) _HID_GLOBAL_VAL(0x7, v) 90 #define HID_REPORT_ID(v) _HID_GLOBAL_VAL(0x8, v) 91 #define HID_REPORT_COUNT(v) _HID_GLOBAL_VAL(0x9, v) 92 #define HID_PUSH 0xa4 93 #define HID_POP 0xb4 94 95 // Local HID items 96 #define HID_USAGE(v) _HID_LOCAL_VAL(0x0, v) 97 #define HID_USAGE16(v) _HID_LOCAL_VAL16(0x0, v) 98 #define HID_USAGE_MIN(v) _HID_LOCAL_VAL(0x1, v) 99 #define HID_USAGE_MAX(v) _HID_LOCAL_VAL(0x2, v) 100 101 // Input/Output/Feature Items 102 #define HID_Data_Arr_Abs 0x00 103 #define HID_Const_Arr_Abs 0x01 104 #define HID_Data_Var_Abs 0x02 105 #define HID_Const_Var_Abs 0x03 106 #define HID_Data_Var_Rel 0x06 107 108 // Sensor Data 109 #define HID_USAGE_SENSOR_DATA(a,b) a|b 110 111 #define HID_USAGE_SENSOR_DATA_MOD_NONE 0x00 112 #define HID_USAGE_SENSOR_DATA_MOD_CHANGE_SENSITIVITY_ABS 0x10 113 #define HID_USAGE_SENSOR_DATA_MOD_MAX 0x20 114 #define HID_USAGE_SENSOR_DATA_MOD_MIN 0x30 115 #define HID_USAGE_SENSOR_DATA_MOD_ACCURACY 0x40 116 #define HID_USAGE_SENSOR_DATA_MOD_RESOLUTION 0x50 117 #define HID_USAGE_SENSOR_DATA_MOD_THRESHOLD_HIGH 0x60 118 #define HID_USAGE_SENSOR_DATA_MOD_THRESHOLD_LOW 0x70 119 #define HID_USAGE_SENSOR_DATA_MOD_CALIBRATION_OFFSET 0x80 120 #define HID_USAGE_SENSOR_DATA_MOD_CALIBRATION_MULTIPLIER 0x90 121 #define HID_USAGE_SENSOR_DATA_MOD_REPORT_INTERVAL 0xA0 122 #define HID_USAGE_SENSOR_DATA_MOD_FREQUENCY_MAX 0xB0 123 #define HID_USAGE_SENSOR_DATA_MOD_PERIOD_MAX 0xC0 124 #define HID_USAGE_SENSOR_DATA_MOD_CHANGE_SENSITIVITY_RANGE_PCT 0xD0 125 #define HID_USAGE_SENSOR_DATA_MOD_CHANGE_SENSITIVITY_REL_PCT 0xE0 126 127 // Sensor Units 128 #define HID_SENSOR_UNITS(v) _HID_GLOBAL_VAL(0x6, v) 129 #define HID_SENSOR_UNITS16(v) _HID_GLOBAL_VAL16(0x6, v) 130 #define HID_SENSOR_UNITS32(v) _HID_GLOBAL_VAL32(0x6, v) 131 #define HID_USAGE_SENSOR_GENERIC_UNITS_NOT_SPECIFIED HID_SENSOR_UNITS(0) 132 #define HID_USAGE_SENSOR_GENERIC_UNITS_LUX HID_SENSOR_UNITS32(0x010000E1) 133 #define HID_USAGE_SENSOR_GENERIC_UNITS_KELVIN HID_SENSOR_UNITS32(0x00010001) 134 #define HID_USAGE_SENSOR_GENERIC_UNITS_FAHRENHEIT HID_SENSOR_UNITS32(0x00010003) 135 #define HID_USAGE_SENSOR_GENERIC_UNITS_PASCAL HID_SENSOR_UNITS16(0xE1F1) 136 #define HID_USAGE_SENSOR_GENERIC_UNITS_NEWTON HID_SENSOR_UNITS16(0xE111) 137 #define HID_USAGE_SENSOR_GENERIC_UNITS_METERS_PER_SECOND HID_SENSOR_UNITS16(0xF011) 138 #define HID_USAGE_SENSOR_GENERIC_UNITS_METERS_PER_SEC_SQRD HID_SENSOR_UNITS16(0xE011) 139 #define HID_USAGE_SENSOR_GENERIC_UNITS_FARAD HID_SENSOR_UNITS32(0x00204FE1) 140 #define HID_USAGE_SENSOR_GENERIC_UNITS_AMPERE HID_SENSOR_UNITS32(0x00100001) 141 #define HID_USAGE_SENSOR_GENERIC_UNITS_WATT HID_SENSOR_UNITS16(0xD121) 142 #define HID_USAGE_SENSOR_GENERIC_UNITS_HENRY HID_SENSOR_UNITS32(0x00E0E121) 143 #define HID_USAGE_SENSOR_GENERIC_UNITS_OHM HID_SENSOR_UNITS32(0x00E0D121) 144 #define HID_USAGE_SENSOR_GENERIC_UNITS_VOLT HID_SENSOR_UNITS32(0x00F0D121) 145 #define HID_USAGE_SENSOR_GENERIC_UNITS_HERTZ HID_SENSOR_UNITS16(0xF001) 146 #define HID_USAGE_SENSOR_GENERIC_UNITS_DEGREES HID_SENSOR_UNITS(0x14) 147 #define HID_USAGE_SENSOR_GENERIC_UNITS_DEGREES_PER_SECOND HID_SENSOR_UNITS16(0xF014) 148 #define HID_USAGE_SENSOR_GENERIC_UNITS_DEGREES_PER_SEC_SQRD HID_SENSOR_UNITS16(0xE014) 149 #define HID_USAGE_SENSOR_GENERIC_UNITS_RADIANS HID_SENSOR_UNITS(0x12) 150 #define HID_USAGE_SENSOR_GENERIC_UNITS_RADIANS_PER_SECOND HID_SENSOR_UNITS16(0xF012) 151 #define HID_USAGE_SENSOR_GENERIC_UNITS_RADIANS_PER_SEC_SQRD HID_SENSOR_UNITS16(0xE012) 152 #define HID_USAGE_SENSOR_GENERIC_UNITS_SECOND HID_SENSOR_UNITS16(0x1001) 153 #define HID_USAGE_SENSOR_GENERIC_UNITS_GAUSS HID_SENSOR_UNITS32(0x00F0E101) 154 #define HID_USAGE_SENSOR_GENERIC_UNITS_GRAM HID_SENSOR_UNITS16(0x0101) 155 #define HID_USAGE_SENSOR_GENERIC_UNITS_CENTIMETER HID_SENSOR_UNITS(0x11) 156 157 // Sensor State 158 #define HID_USAGE_SENSOR_STATE HID_USAGE16(0x0201) 159 #define HID_USAGE_SENSOR_STATE_UNKNOWN HID_USAGE16(0x0800) 160 #define HID_USAGE_SENSOR_STATE_READY HID_USAGE16(0x0801) 161 #define HID_USAGE_SENSOR_STATE_NOT_AVAILABLE HID_USAGE16(0x0802) 162 #define HID_USAGE_SENSOR_STATE_NO_DATA HID_USAGE16(0x0803) 163 #define HID_USAGE_SENSOR_STATE_INITIALIZING HID_USAGE16(0x0804) 164 #define HID_USAGE_SENSOR_STATE_ACCESS_DENIED HID_USAGE16(0x0805) 165 #define HID_USAGE_SENSOR_STATE_ERROR HID_USAGE16(0x0806) 166 167 #define HID_USAGE_SENSOR_STATE_UNKNOWN_VAL 0x00 168 #define HID_USAGE_SENSOR_STATE_READY_VAL 0x01 169 #define HID_USAGE_SENSOR_STATE_NOT_AVAILABLE_VAL 0x02 170 #define HID_USAGE_SENSOR_STATE_NO_DATA_VAL 0x03 171 #define HID_USAGE_SENSOR_STATE_INITIALIZING_VAL 0x04 172 #define HID_USAGE_SENSOR_STATE_ACCESS_DENIED_VAL 0x05 173 #define HID_USAGE_SENSOR_STATE_ERROR_VAL 0x06 174 175 // Event Usages 176 #define HID_USAGE_SENSOR_EVENT HID_USAGE16(0x0202) 177 178 #define HID_USAGE_SENSOR_EVENT_UNKNOWN HID_USAGE16(0x0810) 179 #define HID_USAGE_SENSOR_EVENT_STATE_CHANGED HID_USAGE16(0x0811) 180 #define HID_USAGE_SENSOR_EVENT_PROPERTY_CHANGED HID_USAGE16(0x0812) 181 #define HID_USAGE_SENSOR_EVENT_DATA_UPDATED HID_USAGE16(0x0813) 182 #define HID_USAGE_SENSOR_EVENT_POLL_RESPONSE HID_USAGE16(0x0814) 183 #define HID_USAGE_SENSOR_EVENT_CHANGE_SENSITIVITY HID_USAGE16(0x0815) 184 #define HID_USAGE_SENSOR_EVENT_MAX_REACHED HID_USAGE16(0x0816) 185 #define HID_USAGE_SENSOR_EVENT_MIN_REACHED HID_USAGE16(0x0817) 186 #define HID_USAGE_SENSOR_EVENT_HIGH_THRESHOLD_CROSS_UPWARD HID_USAGE16(0x0818) 187 #define HID_USAGE_SENSOR_EVENT_HIGH_THRESHOLD_CROSS_DOWNWARD HID_USAGE16(0x0819) 188 #define HID_USAGE_SENSOR_EVENT_LOW_THRESHOLD_CROSS_UPWARD HID_USAGE16(0x081A) 189 #define HID_USAGE_SENSOR_EVENT_LOW_THRESHOLD_CROSS_DOWNWARD HID_USAGE16(0x081B) 190 #define HID_USAGE_SENSOR_EVENT_ZERO_THRESHOLD_CROSS_UPWARD HID_USAGE16(0x081C) 191 #define HID_USAGE_SENSOR_EVENT_ZERO_THRESHOLD_CROSS_DOWNWARD HID_USAGE16(0x081D) 192 #define HID_USAGE_SENSOR_EVENT_PERIOD_EXCEEDED HID_USAGE16(0x081E) 193 #define HID_USAGE_SENSOR_EVENT_FREQUENCY_EXCEEDED HID_USAGE16(0x081F) 194 #define HID_USAGE_SENSOR_EVENT_COMPLEX_TRIGGER HID_USAGE16(0x0820) 195 196 #define HID_USAGE_SENSOR_EVENT_UNKNOWN_VAL 0x00 197 #define HID_USAGE_SENSOR_EVENT_STATE_CHANGED_VAL 0x01 198 #define HID_USAGE_SENSOR_EVENT_PROPERTY_CHANGED_VAL 0x02 199 #define HID_USAGE_SENSOR_EVENT_DATA_UPDATED_VAL 0x03 200 #define HID_USAGE_SENSOR_EVENT_POLL_RESPONSE_VAL 0x04 201 #define HID_USAGE_SENSOR_EVENT_CHANGE_SENSITIVITY_VAL 0x05 202 #define HID_USAGE_SENSOR_EVENT_MAX_REACHED_VAL 0x06 203 #define HID_USAGE_SENSOR_EVENT_MIN_REACHED_VAL 0x07 204 #define HID_USAGE_SENSOR_EVENT_HIGH_THRESHOLD_CROSS_UPWARD_VAL 0x08 205 #define HID_USAGE_SENSOR_EVENT_HIGH_THRESHOLD_CROSS_DOWNWARD_VAL 0x09 206 #define HID_USAGE_SENSOR_EVENT_LOW_THRESHOLD_CROSS_UPWARD_VAL 0x0A 207 #define HID_USAGE_SENSOR_EVENT_LOW_THRESHOLD_CROSS_DOWNWARD_VAL 0x0B 208 #define HID_USAGE_SENSOR_EVENT_ZERO_THRESHOLD_CROSS_UPWARD_VAL 0x0C 209 #define HID_USAGE_SENSOR_EVENT_ZERO_THRESHOLD_CROSS_DOWNWARD_VAL 0x0D 210 #define HID_USAGE_SENSOR_EVENT_PERIOD_EXCEEDED_VAL 0x0E 211 #define HID_USAGE_SENSOR_EVENT_FREQUENCY_EXCEEDED_VAL 0x0F 212 #define HID_USAGE_SENSOR_EVENT_COMPLEX_TRIGGER_VAL 0x10 213 214 // Property usages 215 #define HID_USAGE_SENSOR_PROPERTY HID_USAGE16(0x0300) 216 #define HID_USAGE_SENSOR_PROPERTY_FRIENDLY_NAME HID_USAGE16(0x0301) 217 #define HID_USAGE_SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID HID_USAGE16(0x0302) 218 #define HID_USAGE_SENSOR_PROPERTY_SENSOR_STATUS HID_USAGE16(0x0303) 219 #define HID_USAGE_SENSOR_PROPERTY_MINIMUM_REPORT_INTERVAL HID_USAGE16(0x0304) 220 #define HID_USAGE_SENSOR_PROPERTY_SENSOR_MANUFACTURER HID_USAGE16(0x0305) 221 #define HID_USAGE_SENSOR_PROPERTY_SENSOR_MODEL HID_USAGE16(0x0306) 222 #define HID_USAGE_SENSOR_PROPERTY_SENSOR_SERIAL_NUMBER HID_USAGE16(0x0307) 223 #define HID_USAGE_SENSOR_PROPERTY_SENSOR_DESCRIPTION HID_USAGE16(0x0308) 224 #define HID_USAGE_SENSOR_PROPERTY_SENSOR_CONNECTION_TYPE HID_USAGE16(0x0309) 225 226 #define HID_USAGE_SENSOR_PROPERTY_SENSOR_DEVICE_PATH HID_USAGE16(0x030A) 227 #define HID_USAGE_SENSOR_PROPERTY_HARDWARE_REVISION HID_USAGE16(0x030B) 228 #define HID_USAGE_SENSOR_PROPERTY_FIRMWARE_VERSION HID_USAGE16(0x030C) 229 #define HID_USAGE_SENSOR_PROPERTY_RELEASE_DATE HID_USAGE16(0x030D) 230 #define HID_USAGE_SENSOR_PROPERTY_REPORT_INTERVAL HID_USAGE16(0x030E) 231 #define HID_USAGE_SENSOR_PROPERTY_CHANGE_SENSITIVITY_ABS HID_USAGE16(0x030F) 232 #define HID_USAGE_SENSOR_PROPERTY_CHANGE_SENSITIVITY_RANGE_PCT HID_USAGE16(0x0310) 233 #define HID_USAGE_SENSOR_PROPERTY_CHANGE_SENSITIVITY_REL_PCT HID_USAGE16(0x0311) 234 #define HID_USAGE_SENSOR_PROPERTY_ACCURACY HID_USAGE16(0x0312) 235 #define HID_USAGE_SENSOR_PROPERTY_RESOLUTION HID_USAGE16(0x0313) 236 #define HID_USAGE_SENSOR_PROPERTY_RANGE_MAXIMUM HID_USAGE16(0x0314) 237 #define HID_USAGE_SENSOR_PROPERTY_RANGE_MINIMUM HID_USAGE16(0x0315) 238 #define HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE HID_USAGE16(0x0316) 239 240 #define HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_NO_EVENTS HID_USAGE16(0x0840) 241 #define HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_ALL_EVENTS HID_USAGE16(0x0841) 242 #define HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_THRESHOLD_EVENTS HID_USAGE16(0x0842) 243 #define HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_NO_EVENTS_WAKE HID_USAGE16(0x0843) 244 #define HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_ALL_EVENTS_WAKE HID_USAGE16(0x0844) 245 #define HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_THRESHOLD_EVENTS_WAKE HID_USAGE16(0x0845) 246 // clang-format on 247