diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 23ac34cf..dd6f39cc 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -7,6 +7,8 @@ lib_xua Change Log * CHANGED: Move HID descriptors to ease maintenance * CHANGED: Move legacy tests to separate directory * CHANGED: Replace unused GPI-specific HID event names with generic ones + * ADDED: Build default HID Report descriptor at boot-time + * ADDED: Function to return length of HID Report 1.2.0 ----- @@ -19,7 +21,6 @@ lib_xua Change Log * FIXED: Runtime error when using mic array interface * CHANGED: Use XMOS Public Licence Version 1 * FIXED: Automate HID Report Descriptor length in AC1 HID Descriptor - * CHANGED: Move HID descriptors to ease maintenance 1.1.1 ----- diff --git a/examples/AN00246_xua_example/src/hid_report_descriptor.h b/examples/AN00246_xua_example/src/hid_report_descriptor.h index 7bedc6a2..b183beda 100644 --- a/examples/AN00246_xua_example/src/hid_report_descriptor.h +++ b/examples/AN00246_xua_example/src/hid_report_descriptor.h @@ -29,6 +29,9 @@ unsigned char hidReportDescriptor[] = }; #endif +/* + * 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 }; @@ -47,6 +50,9 @@ static const USB_HID_Short_Item_t hidUsageConsumerControl = { .header = 0x09, static const USB_HID_Short_Item_t hidUsagePageConsumer = { .header = 0x05, .data = { 0x0C, 0x00 }, .location = 0x00 }; +/* + * 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+ @@ -54,6 +60,9 @@ static USB_HID_Short_Item_t hidUsageByte0Bit2 = { .header = 0x09, .data = { 0x 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 +/* + * List the configurable items in the HID Report descriptor. + */ static USB_HID_Short_Item_t* const hidConfigurableItems[] = { &hidUsageByte0Bit0, &hidUsageByte0Bit1, @@ -63,6 +72,9 @@ static USB_HID_Short_Item_t* const hidConfigurableItems[] = { &hidUsageByte0Bit5 }; +/* + * List all items in the HID Report descriptor. + */ static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = { &hidUsagePageConsumer, &hidUsageConsumerControl, @@ -84,4 +96,10 @@ static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = { &hidCollectionEnd }; +/* + * Define the length of the HID Report. + * This value must match the number of Report bytes defined by hidReportDescriptorItems. + */ +#define HID_REPORT_LENGTH ( 1 ) + #endif // __hid_report_descriptor_h__ diff --git a/examples/AN00247_xua_example_spdif_tx/src/hid_report_descriptor.h b/examples/AN00247_xua_example_spdif_tx/src/hid_report_descriptor.h index 7bedc6a2..b183beda 100644 --- a/examples/AN00247_xua_example_spdif_tx/src/hid_report_descriptor.h +++ b/examples/AN00247_xua_example_spdif_tx/src/hid_report_descriptor.h @@ -29,6 +29,9 @@ unsigned char hidReportDescriptor[] = }; #endif +/* + * 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 }; @@ -47,6 +50,9 @@ static const USB_HID_Short_Item_t hidUsageConsumerControl = { .header = 0x09, static const USB_HID_Short_Item_t hidUsagePageConsumer = { .header = 0x05, .data = { 0x0C, 0x00 }, .location = 0x00 }; +/* + * 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+ @@ -54,6 +60,9 @@ static USB_HID_Short_Item_t hidUsageByte0Bit2 = { .header = 0x09, .data = { 0x 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 +/* + * List the configurable items in the HID Report descriptor. + */ static USB_HID_Short_Item_t* const hidConfigurableItems[] = { &hidUsageByte0Bit0, &hidUsageByte0Bit1, @@ -63,6 +72,9 @@ static USB_HID_Short_Item_t* const hidConfigurableItems[] = { &hidUsageByte0Bit5 }; +/* + * List all items in the HID Report descriptor. + */ static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = { &hidUsagePageConsumer, &hidUsageConsumerControl, @@ -84,4 +96,10 @@ static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = { &hidCollectionEnd }; +/* + * Define the length of the HID Report. + * This value must match the number of Report bytes defined by hidReportDescriptorItems. + */ +#define HID_REPORT_LENGTH ( 1 ) + #endif // __hid_report_descriptor_h__ diff --git a/examples/AN00248_xua_example_pdm_mics/src/hid_report_descriptor.h b/examples/AN00248_xua_example_pdm_mics/src/hid_report_descriptor.h index 7bedc6a2..b183beda 100644 --- a/examples/AN00248_xua_example_pdm_mics/src/hid_report_descriptor.h +++ b/examples/AN00248_xua_example_pdm_mics/src/hid_report_descriptor.h @@ -29,6 +29,9 @@ unsigned char hidReportDescriptor[] = }; #endif +/* + * 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 }; @@ -47,6 +50,9 @@ static const USB_HID_Short_Item_t hidUsageConsumerControl = { .header = 0x09, static const USB_HID_Short_Item_t hidUsagePageConsumer = { .header = 0x05, .data = { 0x0C, 0x00 }, .location = 0x00 }; +/* + * 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+ @@ -54,6 +60,9 @@ static USB_HID_Short_Item_t hidUsageByte0Bit2 = { .header = 0x09, .data = { 0x 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 +/* + * List the configurable items in the HID Report descriptor. + */ static USB_HID_Short_Item_t* const hidConfigurableItems[] = { &hidUsageByte0Bit0, &hidUsageByte0Bit1, @@ -63,6 +72,9 @@ static USB_HID_Short_Item_t* const hidConfigurableItems[] = { &hidUsageByte0Bit5 }; +/* + * List all items in the HID Report descriptor. + */ static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = { &hidUsagePageConsumer, &hidUsageConsumerControl, @@ -84,4 +96,10 @@ static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = { &hidCollectionEnd }; +/* + * Define the length of the HID Report. + * This value must match the number of Report bytes defined by hidReportDescriptorItems. + */ +#define HID_REPORT_LENGTH ( 1 ) + #endif // __hid_report_descriptor_h__ 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 7bedc6a2..b183beda 100644 --- a/legacy_tests/app_test_i2s_loopback/hid_report_descriptor.h +++ b/legacy_tests/app_test_i2s_loopback/hid_report_descriptor.h @@ -29,6 +29,9 @@ unsigned char hidReportDescriptor[] = }; #endif +/* + * 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 }; @@ -47,6 +50,9 @@ static const USB_HID_Short_Item_t hidUsageConsumerControl = { .header = 0x09, static const USB_HID_Short_Item_t hidUsagePageConsumer = { .header = 0x05, .data = { 0x0C, 0x00 }, .location = 0x00 }; +/* + * 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+ @@ -54,6 +60,9 @@ static USB_HID_Short_Item_t hidUsageByte0Bit2 = { .header = 0x09, .data = { 0x 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 +/* + * List the configurable items in the HID Report descriptor. + */ static USB_HID_Short_Item_t* const hidConfigurableItems[] = { &hidUsageByte0Bit0, &hidUsageByte0Bit1, @@ -63,6 +72,9 @@ static USB_HID_Short_Item_t* const hidConfigurableItems[] = { &hidUsageByte0Bit5 }; +/* + * List all items in the HID Report descriptor. + */ static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = { &hidUsagePageConsumer, &hidUsageConsumerControl, @@ -84,4 +96,10 @@ static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = { &hidCollectionEnd }; +/* + * Define the length of the HID Report. + * This value must match the number of Report bytes defined by hidReportDescriptorItems. + */ +#define HID_REPORT_LENGTH ( 1 ) + #endif // __hid_report_descriptor_h__ diff --git a/lib_xua/src/hid/hid_report_descriptor.c b/lib_xua/src/hid/hid_report_descriptor.c index 14cfd0a4..42565265 100644 --- a/lib_xua/src/hid/hid_report_descriptor.c +++ b/lib_xua/src/hid/hid_report_descriptor.c @@ -130,6 +130,11 @@ size_t hidGetReportDescriptorLength( void ) return ( hidReportDescriptorPrepared ) ? hidReportDescriptorLength : 0; } +size_t hidGetReportLength( void ) +{ + return ( hidReportDescriptorPrepared ) ? HID_REPORT_LENGTH : 0; +} + void hidPrepareReportDescriptor( void ) { if( !hidReportDescriptorPrepared ) { diff --git a/lib_xua/src/hid/xua_hid_report_descriptor.h b/lib_xua/src/hid/xua_hid_report_descriptor.h index 91d01e41..e917a483 100644 --- a/lib_xua/src/hid/xua_hid_report_descriptor.h +++ b/lib_xua/src/hid/xua_hid_report_descriptor.h @@ -6,6 +6,10 @@ * * This file defines the structure of the HID Report descriptor and decalres * functions for manipulating it. + * Because the Report descriptor defines the length of the HID Report, this file + * declares a function for obtaining the Report length as well. + * The using application has the responsibility to define the report descriptor + * structure and default contents in their hid_report_descriptor.h file. * Document section numbers refer to the HID Device Class Definition, version 1.11. */ @@ -82,6 +86,17 @@ unsigned char* hidGetReportDescriptor( void ); */ size_t hidGetReportDescriptorLength( void ); +/** + * @brief Get the length of the HID Report + * + * This function returns the length of the USB HID Report. + * It returns zero if the Report descriptor has not been prepared, + * i.e., no one has called \c hidPrepareReportDescriptor(). + * + * @return The length of the Report in bytes + */ +size_t hidGetReportLength( void ); + /** * @brief Prepare the USB HID Report descriptor * diff --git a/tests/xua_unit_tests/src/hid_report_descriptor.h b/tests/xua_unit_tests/src/hid_report_descriptor.h index 7830ca8d..faf3e7f7 100644 --- a/tests/xua_unit_tests/src/hid_report_descriptor.h +++ b/tests/xua_unit_tests/src/hid_report_descriptor.h @@ -12,6 +12,9 @@ #define MIN_VALID_BIT ( 0 ) #define MIN_VALID_BYTE ( 0 ) +/* + * 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 hidCollectionLogical = { .header = 0xA1, .data = { 0x02, 0x00 }, .location = 0x00 }; @@ -32,17 +35,26 @@ static const USB_HID_Short_Item_t hidUsageConsumerControl = { .header = 0x09, static const USB_HID_Short_Item_t hidUsagePageConsumer = { .header = 0x05, .data = { 0x0C, 0x00 }, .location = 0x00 }; +/* + * Define configurable items in the HID Report descriptor. + */ static USB_HID_Short_Item_t hidUsageByte0Bit0 = { .header = 0x09, .data = { 0xE2, 0x00 }, .location = 0x00 }; // Mute static USB_HID_Short_Item_t hidUsageByte1Bit7 = { .header = 0x09, .data = { 0xEA, 0x00 }, .location = 0x71 }; // Vol- static USB_HID_Short_Item_t hidUsageByte1Bit0 = { .header = 0x09, .data = { 0xE9, 0x00 }, .location = 0x01 }; // Vol+ +/* + * List the configurable items in the HID Report descriptor. + */ static USB_HID_Short_Item_t* const hidConfigurableItems[] = { &hidUsageByte0Bit0, &hidUsageByte1Bit0, &hidUsageByte1Bit7 }; +/* + * List all items in the HID Report descriptor. + */ static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = { &hidUsagePageConsumer, &hidUsageConsumerControl, @@ -73,4 +85,10 @@ static const USB_HID_Short_Item_t* const hidReportDescriptorItems[] = { &hidCollectionEnd }; +/* + * Define the length of the HID Report. + * This value must match the number of Report bytes defined by hidReportDescriptorItems. + */ +#define HID_REPORT_LENGTH ( 2 ) + #endif // __hid_report_descriptor_h__ diff --git a/tests/xua_unit_tests/src/test_hid.c b/tests/xua_unit_tests/src/test_hid.c index d528462f..7c014a2c 100644 --- a/tests/xua_unit_tests/src/test_hid.c +++ b/tests/xua_unit_tests/src/test_hid.c @@ -36,6 +36,9 @@ void test_unprepared_hidGetReportDescriptor( void ) { unsigned char* reportDescPtr = hidGetReportDescriptor(); TEST_ASSERT_NULL( reportDescPtr ); + + unsigned reportLength = hidGetReportLength(); + TEST_ASSERT_EQUAL_UINT( 0, reportLength ); } void test_prepared_hidGetReportDescriptor( void ) @@ -43,6 +46,9 @@ void test_prepared_hidGetReportDescriptor( void ) hidPrepareReportDescriptor(); unsigned char* reportDescPtr = hidGetReportDescriptor(); TEST_ASSERT_NOT_NULL( reportDescPtr ); + + unsigned reportLength = hidGetReportLength(); + TEST_ASSERT_EQUAL_UINT( HID_REPORT_LENGTH, reportLength ); } void test_reset_unprepared_hidGetReportDescriptor( void )