Add function to return the length of the HID Report

2021-06-03 15:53:50 +01:00
parent dab84e56df
commit fd45908ff6
9 changed files with 118 additions and 1 deletions
--- 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
 -----
--- 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__
--- 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__
--- 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__
--- 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__
--- 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 ) {
--- 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
 *
--- 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__
--- 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 )