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