diff --git a/examples/AN00246_xua_example/src/hid_report_descriptor.h b/examples/AN00246_xua_example/src/hid_report_descriptor.h index ec2c13e5..022e6af0 100644 --- a/examples/AN00246_xua_example/src/hid_report_descriptor.h +++ b/examples/AN00246_xua_example/src/hid_report_descriptor.h @@ -32,33 +32,58 @@ unsigned char hidReportDescriptor[] = /* * Define non-configurable items in the HID Report descriptor. */ -static const USB_HID_Short_Item_t hidCollectionApplication = { .header = 0xA1, .data = { 0x01, 0x00 }, .location = 0x00 }; -static const USB_HID_Short_Item_t hidCollectionEnd = { .header = 0xC0, .data = { 0x00, 0x00 }, .location = 0x00 }; +static const USB_HID_Short_Item_t hidCollectionApplication = { .header = 0xA1, .data = { 0x01, 0x00 } }; +static const USB_HID_Short_Item_t hidCollectionEnd = { .header = 0xC0, .data = { 0x00, 0x00 } }; -static const USB_HID_Short_Item_t hidInputConstArray = { .header = 0x81, .data = { 0x01, 0x00 }, .location = 0x00 }; -static const USB_HID_Short_Item_t hidInputDataVar = { .header = 0x81, .data = { 0x02, 0x00 }, .location = 0x00 }; +static const USB_HID_Short_Item_t hidInputConstArray = { .header = 0x81, .data = { 0x01, 0x00 } }; +static const USB_HID_Short_Item_t hidInputDataVar = { .header = 0x81, .data = { 0x02, 0x00 } }; -static const USB_HID_Short_Item_t hidLogicalMaximum0 = { .header = 0x25, .data = { 0x00, 0x00 }, .location = 0x00 }; -static const USB_HID_Short_Item_t hidLogicalMaximum1 = { .header = 0x25, .data = { 0x01, 0x00 }, .location = 0x00 }; -static const USB_HID_Short_Item_t hidLogicalMinimum0 = { .header = 0x15, .data = { 0x00, 0x00 }, .location = 0x00 }; +static const USB_HID_Short_Item_t hidLogicalMaximum0 = { .header = 0x25, .data = { 0x00, 0x00 } }; +static const USB_HID_Short_Item_t hidLogicalMaximum1 = { .header = 0x25, .data = { 0x01, 0x00 } }; +static const USB_HID_Short_Item_t hidLogicalMinimum0 = { .header = 0x15, .data = { 0x00, 0x00 } }; -static const USB_HID_Short_Item_t hidReportCount2 = { .header = 0x95, .data = { 0x02, 0x00 }, .location = 0x00 }; -static const USB_HID_Short_Item_t hidReportCount6 = { .header = 0x95, .data = { 0x06, 0x00 }, .location = 0x00 }; -static const USB_HID_Short_Item_t hidReportSize1 = { .header = 0x75, .data = { 0x01, 0x00 }, .location = 0x00 }; +static const USB_HID_Short_Item_t hidReportCount2 = { .header = 0x95, .data = { 0x02, 0x00 } }; +static const USB_HID_Short_Item_t hidReportCount6 = { .header = 0x95, .data = { 0x06, 0x00 } }; +static const USB_HID_Short_Item_t hidReportSize1 = { .header = 0x75, .data = { 0x01, 0x00 } }; -static const USB_HID_Short_Item_t hidUsageConsumerControl = { .header = 0x09, .data = { 0x01, 0x00 }, .location = 0x00 }; +static const USB_HID_Short_Item_t hidUsageConsumerControl = { .header = 0x09, .data = { 0x01, 0x00 } }; -static const USB_HID_Short_Item_t hidUsagePageConsumer = { .header = 0x05, .data = { 0x0C, 0x00 }, .location = 0x00 }; +/* + * Define the HID Report Descriptor Item, Usage Page, Report ID and length for each HID Report + * For internal purposes, a report element with ID of 0 must be included if report IDs are not being used. + */ +static const USB_HID_Report_Element_t hidReportPageConsumer = { + .item = { .header = 0x05, .data = { USB_HID_USAGE_PAGE_ID_CONSUMER, 0x00 }}, + .location = HID_REPORT_SET_LOC( 0, 2, 0, 0 ) +}; /* * Define configurable items in the HID Report descriptor. */ -static USB_HID_Short_Item_t hidUsageByte0Bit5 = { .header = 0x09, .data = { 0xE2, 0x00 }, .location = 0x50 }; // Mute -static USB_HID_Short_Item_t hidUsageByte0Bit4 = { .header = 0x09, .data = { 0xEA, 0x00 }, .location = 0x40 }; // Vol- -static USB_HID_Short_Item_t hidUsageByte0Bit3 = { .header = 0x09, .data = { 0xE9, 0x00 }, .location = 0x30 }; // Vol+ -static USB_HID_Short_Item_t hidUsageByte0Bit2 = { .header = 0x09, .data = { 0xB6, 0x00 }, .location = 0x20 }; // Scan Prev -static USB_HID_Short_Item_t hidUsageByte0Bit1 = { .header = 0x09, .data = { 0xB5, 0x00 }, .location = 0x10 }; // Scan Next -static USB_HID_Short_Item_t hidUsageByte0Bit0 = { .header = 0x09, .data = { 0xB0, 0x00 }, .location = 0x00 }; // Play +static USB_HID_Report_Element_t hidUsageByte0Bit5 = { + .item = { .header = 0x09, .data = { 0xE2, 0x00 }}, + .location = HID_REPORT_SET_LOC(0, 0, 0, 5) +}; // Mute +static USB_HID_Report_Element_t hidUsageByte0Bit4 = { + .item = { .header = 0x09, .data = { 0xEA, 0x00 }}, + .location = HID_REPORT_SET_LOC(0, 0, 0, 4) +}; // Vol- +static USB_HID_Report_Element_t hidUsageByte0Bit3 = { + .item = { .header = 0x09, .data = { 0xE9, 0x00 }}, + .location = HID_REPORT_SET_LOC(0, 0, 0, 3) +}; // Vol+ +static USB_HID_Report_Element_t hidUsageByte0Bit2 = { + .item = { .header = 0x09, .data = { 0xB6, 0x00 }}, + .location = HID_REPORT_SET_LOC(0, 0, 0, 2) +}; // Scan Prev +static USB_HID_Report_Element_t hidUsageByte0Bit1 = { + .item = { .header = 0x09, .data = { 0xB5, 0x00 }}, + .location = HID_REPORT_SET_LOC(0, 0, 0, 1) +}; // Scan Next +static USB_HID_Report_Element_t hidUsageByte0Bit0 = { + .item = { .header = 0x09, .data = { 0xB0, 0x00 }}, + .location = HID_REPORT_SET_LOC(0, 0, 0, 0) +}; // Play /* * List the configurable items in the HID Report descriptor. diff --git a/legacy_tests/app_test_i2s_loopback/hid_report_descriptor.h b/legacy_tests/app_test_i2s_loopback/hid_report_descriptor.h index a24c714d..b473b0a4 100644 --- a/legacy_tests/app_test_i2s_loopback/hid_report_descriptor.h +++ b/legacy_tests/app_test_i2s_loopback/hid_report_descriptor.h @@ -30,7 +30,6 @@ unsigned char hidReportDescriptor[] = #endif #define USB_HID_REPORT_ID_CONSUMER ( 0x02 ) -#define USB_HID_USAGE_PAGE_ID_CONSUMER ( 0x02 ) /* * Define non-configurable items in the HID Report descriptor. diff --git a/lib_xua/src/hid/xua_hid_report.h b/lib_xua/src/hid/xua_hid_report.h index 65d51c2c..7fa1d846 100644 --- a/lib_xua/src/hid/xua_hid_report.h +++ b/lib_xua/src/hid/xua_hid_report.h @@ -13,11 +13,13 @@ * Document section numbers refer to the HID Device Class Definition, version 1.11. */ -#ifndef _HID_REPORT_DESCRIPTOR_ -#define _HID_REPORT_DESCRIPTOR_ +#ifndef _XUA_HID_REPORT_ +#define _XUA_HID_REPORT_ #include +#include "xua_hid_report_descriptor_constants.h" + #define HID_REPORT_ITEM_HDR_SIZE_MASK ( 0x03 ) #define HID_REPORT_ITEM_HDR_SIZE_SHIFT ( 0U ) @@ -44,12 +46,39 @@ #define HID_REPORT_ITEM_USAGE_TAG ( 0U ) #define HID_REPORT_ITEM_USAGE_TYPE ( 2U ) +// Constants from the USB Device Class Definition for HID +#define HID_REPORT_ITEM_TYPE_MAIN ( 0x00 ) +#define HID_REPORT_ITEM_TYPE_GLOBAL ( 0x01 ) +#define HID_REPORT_ITEM_TYPE_LOCAL ( 0x02 ) +#define HID_REPORT_ITEM_TYPE_RESERVED ( 0x03 ) + +/** + * @brief Helper macro to configure the location field of USB_HID_Report_Element_t. + * + * @param id The report ID that this element is within. + * @param len (only relevant for the usage_page elements in hidReports) The length + * of the report under this report ID. + * @param byte The byte location of this element in the report. + * @param bit The bit location (within the byte) of this element in the report. + */ #define HID_REPORT_SET_LOC(id, len, byte, bit) (\ (( id << HID_REPORT_ELEMENT_LOC_ID_SHIFT ) & HID_REPORT_ELEMENT_LOC_ID_MASK ) | \ (( len << HID_REPORT_ELEMENT_LOC_LEN_SHIFT ) & HID_REPORT_ELEMENT_LOC_LEN_MASK ) | \ (( byte << HID_REPORT_ELEMENT_LOC_BYTE_SHIFT ) & HID_REPORT_ELEMENT_LOC_BYTE_MASK ) | \ (( bit << HID_REPORT_ELEMENT_LOC_BIT_SHIFT ) & HID_REPORT_ELEMENT_LOC_BIT_MASK )) +/** + * @brief Helper macro to configure the header field of USB_HID_Short_Item_t + * + * @param size The size of the report descriptor item (valid values: 0, 1, 2) + * @param type The type of the report descriptor item + * @param tag The tag + */ +#define HID_REPORT_SET_HEADER(size, type, tag) (\ + (( size << HID_REPORT_ITEM_HDR_SIZE_SHIFT) & HID_REPORT_ITEM_HDR_SIZE_MASK ) |\ + (( type << HID_REPORT_ITEM_HDR_TYPE_SHIFT) & HID_REPORT_ITEM_HDR_TYPE_MASK ) |\ + (( tag << HID_REPORT_ITEM_HDR_TAG_SHIFT ) & HID_REPORT_ITEM_HDR_TAG_SHIFT ) ) + #define HID_STATUS_GOOD ( 0U ) #define HID_STATUS_BAD_HEADER ( 1U ) #define HID_STATUS_BAD_ID ( 2U ) @@ -473,4 +502,4 @@ unsigned hidSetReportItem( */ void hidSetReportPeriod( const unsigned id, const unsigned period ); -#endif // _HID_REPORT_DESCRIPTOR_ +#endif // _XUA_HID_REPORT_ diff --git a/lib_xua/src/hid/xua_hid_report_descriptor_constants.h b/lib_xua/src/hid/xua_hid_report_descriptor_constants.h new file mode 100644 index 00000000..893c2101 --- /dev/null +++ b/lib_xua/src/hid/xua_hid_report_descriptor_constants.h @@ -0,0 +1,65 @@ +// Copyright 2021 XMOS LIMITED. +// This Software is subject to the terms of the XMOS Public Licence: Version 1. + +/** + * @brief Human Interface Device (HID) Report descriptor constants + * + * This file defines a collection of constants from the USB HID documents. + * This includes constants from: + * - Device Class Definition for Human Interface Devices, version 1.11 + * - HID Usage Tables for Universal Serial Bus, version 1.22 + * + * This file is incomplete, but can be expanded with new constants as necessary. + */ + +#ifndef _XUA_HID_REPORT_DESCRIPTOR_CONSTANTS_ +#define _XUA_HID_REPORT_DESCRIPTOR_CONSTANTS_ + + +// Constants from the USB Device Class Definition for HID for type +#define HID_REPORT_ITEM_TYPE_MAIN ( 0x00 ) +#define HID_REPORT_ITEM_TYPE_GLOBAL ( 0x01 ) +#define HID_REPORT_ITEM_TYPE_LOCAL ( 0x02 ) +#define HID_REPORT_ITEM_TYPE_RESERVED ( 0x03 ) + +// Constants from the USB Device Class Definition for HID for tag +// Main items +#define HID_REPORT_ITEM_TAG_INPUT ( 0x08 ) +#define HID_REPORT_ITEM_TAG_OUTPUT ( 0x09 ) +#define HID_REPORT_ITEM_TAG_FEATURE ( 0x0B ) +#define HID_REPORT_ITEM_TAG_COLLECTION ( 0x0A ) +#define HID_REPORT_ITEM_TAG_END_COLLECTION ( 0x0C ) + +// Global items +#define HID_REPORT_ITEM_TAG_USAGE_PAGE ( 0x00 ) +#define HID_REPORT_ITEM_TAG_LOGICAL_MINIMUM ( 0x01 ) +#define HID_REPORT_ITEM_TAG_LOGICAL_MAXIMUM ( 0x02 ) +#define HID_REPORT_ITEM_TAG_PHYSICAL_MINIMUM ( 0x03 ) +#define HID_REPORT_ITEM_TAG_PHYSICAL_MAXIMUM ( 0x04 ) +#define HID_REPORT_ITEM_TAG_UNIT_EXPONENT ( 0x05 ) +#define HID_REPORT_ITEM_TAG_UNIT ( 0x06 ) +#define HID_REPORT_ITEM_TAG_REPORT_SIZE ( 0x07 ) +#define HID_REPORT_ITEM_TAG_REPORT_ID ( 0x08 ) +#define HID_REPORT_ITEM_TAG_REPORT_COUNT ( 0x09 ) +#define HID_REPORT_ITEM_TAG_PUSH ( 0x0A ) +#define HID_REPORT_ITEM_TAG_POP ( 0x0B ) + +// Local items +#define HID_REPORT_ITEM_TAG_USAGE ( 0x00 ) +#define HID_REPORT_ITEM_TAG_USAGE_MINIMUM ( 0x01 ) +#define HID_REPORT_ITEM_TAG_USAGE_MAXIMUM ( 0x02 ) +#define HID_REPORT_ITEM_TAG_DESIGNATOR_INDEX ( 0x03 ) +#define HID_REPORT_ITEM_TAG_DESIGNATOR_MINIMUM ( 0x04 ) +#define HID_REPORT_ITEM_TAG_DESIGNATOR_MAXIMUM ( 0x05 ) +#define HID_REPORT_ITEM_TAG_STRING_INDEX ( 0x07 ) +#define HID_REPORT_ITEM_TAG_STRING_MINIMUM ( 0x08 ) +#define HID_REPORT_ITEM_TAG_STRING_MAXIMUM ( 0x09 ) +#define HID_REPORT_ITEM_TAG_DELIMITER ( 0x0A ) + +// Constants from HID Usage Tables +// Usage page IDs +#define USB_HID_USAGE_PAGE_ID_KEYBOARD ( 0x07 ) +#define USB_HID_USAGE_PAGE_ID_TELEPHONY_DEVICE ( 0x0B ) +#define USB_HID_USAGE_PAGE_ID_CONSUMER ( 0x0C ) + +#endif // _XUA_HID_REPORT_DESCRIPTOR_CONSTANTS_ diff --git a/tests/xua_unit_tests/src/test_multi_report/hid_report_descriptor.h b/tests/xua_unit_tests/src/test_multi_report/hid_report_descriptor.h index e0549641..9fe77d05 100644 --- a/tests/xua_unit_tests/src/test_multi_report/hid_report_descriptor.h +++ b/tests/xua_unit_tests/src/test_multi_report/hid_report_descriptor.h @@ -10,10 +10,6 @@ #define USB_HID_REPORT_ID_CONSUMER ( 0x02 ) #define USB_HID_REPORT_ID_TELEPHONY ( 0x03 ) -#define USB_HID_USAGE_PAGE_ID_CONSUMER ( 0x0C ) -#define USB_HID_USAGE_PAGE_ID_KEYBOARD ( 0x07 ) -#define USB_HID_USAGE_PAGE_ID_TELEPHONY ( 0x0B ) - /* * Define non-configurable items in the HID Report descriptor. * (These are short items as the location field isn't relevant for them) @@ -55,7 +51,7 @@ static const USB_HID_Report_Element_t hidReportConsumer = { }; static const USB_HID_Report_Element_t hidReportTelephony = { - .item = { .header = 0x05, .data = { USB_HID_USAGE_PAGE_ID_TELEPHONY, 0x00 }}, + .item = { .header = 0x05, .data = { USB_HID_USAGE_PAGE_ID_TELEPHONY_DEVICE, 0x00 }}, .location = HID_REPORT_SET_LOC( USB_HID_REPORT_ID_TELEPHONY, 1, 0, 0 ) }; diff --git a/tests/xua_unit_tests/src/test_simple/hid_report_descriptor.h b/tests/xua_unit_tests/src/test_simple/hid_report_descriptor.h index a466879b..daf6194e 100644 --- a/tests/xua_unit_tests/src/test_simple/hid_report_descriptor.h +++ b/tests/xua_unit_tests/src/test_simple/hid_report_descriptor.h @@ -6,8 +6,6 @@ #include "xua_hid_report.h" -#define USB_HID_USAGE_PAGE_ID_CONSUMER ( 0x0C ) - /* * Define non-configurable items in the HID Report descriptor. * (These are short items as the location field isn't relevant for them) diff --git a/tests/xua_unit_tests/src/test_simple/test_hid.c b/tests/xua_unit_tests/src/test_simple/test_hid.c index d7e3015c..5857895f 100644 --- a/tests/xua_unit_tests/src/test_simple/test_hid.c +++ b/tests/xua_unit_tests/src/test_simple/test_hid.c @@ -22,12 +22,6 @@ #define LOUDNESS_CONTROL ( 0xE7 ) #define AL_CONTROL_PANEL ( 0x019F ) -// Constants from the USB Device Class Definition for HID -#define HID_REPORT_ITEM_TYPE_MAIN ( 0x00 ) -#define HID_REPORT_ITEM_TYPE_GLOBAL ( 0x01 ) -#define HID_REPORT_ITEM_TYPE_LOCAL ( 0x02 ) -#define HID_REPORT_ITEM_TYPE_RESERVED ( 0x03 ) - static unsigned construct_usage_header( unsigned size ) { unsigned header = 0x00;