Add function to return the length of the HID Report

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
 -----

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__

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__

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__

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__

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 ) {

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
  *

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__

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 )