diff --git a/CHANGELOG.rst b/CHANGELOG.rst index a0fed19f..a5db13c9 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,6 +1,11 @@ lib_xua Change Log ================== +1.3.0 +----- + + * CHANGED: Move HID descriptors to ease maintenance + 1.2.0 ----- @@ -12,6 +17,7 @@ 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/lib_xua/module_build_info b/lib_xua/module_build_info index 67df655e..39315c72 100644 --- a/lib_xua/module_build_info +++ b/lib_xua/module_build_info @@ -1,4 +1,4 @@ -VERSION = 1.2.0 +VERSION = 1.3.0 DEPENDENT_MODULES = lib_logging(>=3.0.0) \ lib_xassert(>=4.0.0) \ diff --git a/lib_xua/src/core/endpoint0/xua_ep0_descriptors.h b/lib_xua/src/core/endpoint0/xua_ep0_descriptors.h index 4e219a58..47991bf9 100644 --- a/lib_xua/src/core/endpoint0/xua_ep0_descriptors.h +++ b/lib_xua/src/core/endpoint0/xua_ep0_descriptors.h @@ -15,7 +15,7 @@ #include "usbaudio20.h" /* Defines from the USB Audio 2.0 Specifications */ #include "usbaudiocommon.h" #include "xud_device.h" -#include "usbaudio20.h" /* Defines from USB Audio 2.0 spec */ +#include "xua_hid_descriptor.h" #ifdef IAP_EA_NATIVE_TRANS #include "iap2.h" /* Defines iAP EA Native Transport protocol name */ @@ -581,7 +581,7 @@ unsigned char devQualDesc_Null[] = #endif #if( 0 < HID_CONTROLS ) -unsigned char hidReportDescriptor[] = /* Voice Command usage as per request #HUTRR45 */ +unsigned char hidReportDescriptor[] = { 0x05, 0x01, /* Usage Page (Generic Desktop) */ 0x09, 0x06, /* Usage (Keyboard) */ @@ -808,7 +808,7 @@ typedef struct #if( 0 < HID_CONTROLS ) USB_Descriptor_Interface_t HID_Interface; - unsigned char hidDesc[9]; //TODO ideally we would have a struct for this. + USB_HID_Descriptor_t HID_Descriptor; USB_Descriptor_Endpoint_t HID_In_Endpoint; #endif @@ -1939,7 +1939,7 @@ USB_Config_Descriptor_Audio2_t cfgDesc_Audio2= .wLockDelay = 0x0008, }, #endif /* (INPUT_FORMAT_COUNT > 2) */ -#endif /* #if(NUM_USB_CHAN_IN > 0) */ +#endif /* (NUM_USB_CHAN_IN > 0) */ #ifdef MIDI /* MIDI Descriptors */ @@ -2204,60 +2204,24 @@ USB_Config_Descriptor_Audio2_t cfgDesc_Audio2= #endif /* IAP */ #if( 0 < HID_CONTROLS ) - .HID_Interface = - { - 9, /* 0 bLength : Size of descriptor in Bytes */ - 4, /* 1 bDescriptorType (Interface: 0x04)*/ - INTERFACE_NUMBER_HID, /* 2 bInterfaceNumber : Number of interface */ - 0, /* 3 bAlternateSetting : Value used alternate interfaces using SetInterface Request */ - 1, /* 4: bNumEndpoints : Number of endpoitns for this interface (excluding 0) */ - 3, /* 5: bInterfaceClass */ - 0, /* 6: bInterfaceSubClass - no boot device */ - 0, /* 7: bInterfaceProtocol*/ - 0, /* 8 iInterface */ - }, - - { - 9, /* 0 bLength : Size of descriptor in Bytes */ - 0x21, /* 1 bDescriptorType (HID) */ - 0x10, /* 2 bcdHID */ - 0x01, /* 3 bcdHID */ - 0, /* 4 bCountryCode */ - 1, /* 5 bNumDescriptors */ - 0x22, /* 6 bDescriptorType[0] (Report) */ - sizeof(hidReportDescriptor) & 0xff,/* 7 wDescriptorLength[0] */ - sizeof(hidReportDescriptor) >> 8, /* 8 wDescriptorLength[0] */ - }, - - .HID_In_Endpoint = - { - /* Endpoint descriptor (IN) */ - 0x7, /* 0 bLength */ - 5, /* 1 bDescriptorType */ - ENDPOINT_ADDRESS_IN_HID, /* 2 bEndpointAddress */ - 3, /* 3 bmAttributes (INTERRUPT) */ - 64, /* 4 wMaxPacketSize */ - ENDPOINT_INT_INTERVAL_IN_HID, /* 6 bInterval */ - } + #include "xua_hid_descriptors.h" #endif }; #endif /* (AUDIO_CLASS == 2) */ #if( 0 < HID_CONTROLS ) +#if (AUDIO_CLASS ==1 ) unsigned char hidDescriptor[] = { - 0x09, /* 0 bLength : Size of descriptor in Bytes */ - 0x21, /* 1 bDescriptorType (HID) */ - 0x10, /* 2 bcdHID */ - 0x01, /* 3 bcdHID */ - 0x00, /* 4 bCountryCode */ - 0x01, /* 5 bNumDescriptors */ - 0x22, /* 6 bDescriptorType[0] (Report) */ - sizeof(hidReportDescriptor) & 0xff, /* 7 wDescriptorLength[0] */ - sizeof(hidReportDescriptor) >> 8, /* 8 wDescriptorLength[0] */ + #include "xua_hid_descriptor_contents.h" }; +#elif (AUDIO_CLASS == 2) +unsigned char* hidDescriptor = (unsigned char*) &cfgDesc_Audio2.HID_Descriptor; +#else + #error "Unknown Audio Class" #endif +#endif // 0 < HID_CONTROLS /* Configuration Descriptor for Null device */ @@ -2362,6 +2326,12 @@ const unsigned num_freqs_a1 = MAX(3, (0 #endif #if( 0 < HID_CONTROLS ) +/* + * The value of HID_INTERFACE_BYTES must match the length of the descriptors defined in + * - xua_hid_descriptor_contents.h + * - xua_hid_endpoint_descriptor_contents.h and + * - xua_hid_interface_descriptor_contents.h + */ #define HID_INTERFACE_BYTES ( 9 + 9 + 7 ) #define HID_INTERFACES_A1 1 #else @@ -2906,36 +2876,7 @@ unsigned char cfgDesc_Audio1[] = #endif #if( 0 < HID_CONTROLS ) - /* HID interface descriptor */ - 0x09, /* 0 bLength : Size of descriptor in Bytes */ - 0x04, /* 1 bDescriptorType (Interface: 0x04)*/ - INTERFACE_NUMBER_HID, /* 2 bInterfaceNumber : Number of interface */ - 0x00, /* 3 bAlternateSetting : Value used alternate interfaces using SetInterface Request */ - 0x01, /* 4: bNumEndpoints : Number of endpoitns for this interface (excluding 0) */ - 0x03, /* 5: bInterfaceClass */ - 0x00, /* 6: bInterfaceSubClass - no boot device */ - 0x00, /* 7: bInterfaceProtocol*/ - 0x00, /* 8 iInterface */ - - /* HID descriptor */ - 0x09, /* 0 bLength : Size of descriptor in Bytes */ - 0x21, /* 1 bDescriptorType (HID) */ - 0x10, /* 2 bcdHID */ - 0x01, /* 3 bcdHID */ - 0x00, /* 4 bCountryCode */ - 0x01, /* 5 bNumDescriptors */ - 0x22, /* 6 bDescriptorType[0] (Report) */ - sizeof(hidReportDescriptor) & 0xff, /* 7 wDescriptorLength[0] */ - sizeof(hidReportDescriptor) >> 8, /* 8 wDescriptorLength[0] */ - - /* HID Endpoint descriptor (IN) */ - 0x07, /* 0 bLength */ - 0x05, /* 1 bDescriptorType */ - ENDPOINT_ADDRESS_IN_HID, /* 2 bEndpointAddress */ - 0x03, /* 3 bmAttributes (INTERRUPT) */ - 0x40, /* 4 wMaxPacketSize */ - 0x00, /* 5 wMaxPacketSize */ - ENDPOINT_INT_INTERVAL_IN_HID, /* 6 bInterval */ + #include "xua_hid_descriptors.h" #endif }; diff --git a/lib_xua/src/hid/xua_hid_descriptor.h b/lib_xua/src/hid/xua_hid_descriptor.h new file mode 100644 index 00000000..4fed07a2 --- /dev/null +++ b/lib_xua/src/hid/xua_hid_descriptor.h @@ -0,0 +1,26 @@ +// Copyright 2021 XMOS LIMITED. +// This Software is subject to the terms of the XMOS Public Licence: Version 1. + +/** + * @brief Human Interface Device (HID) descriptor + * + * This file defines the structure of the HID descriptor. + * Document section numbers refer to the HID Device Class Definition, version 1.11. + */ + +#ifndef _HID_DESCRIPTOR_ +#define _HID_DESCRIPTOR_ + +/* USB HID Descriptor (section 6.2.1) */ +typedef struct +{ + unsigned char bLength; /* Size of the descriptor (bytes) */ + unsigned char bDescriptorType0; /* Descriptor type, a constant, 0x21 (section 7.1) */ + unsigned char bcdHID[2]; /* HID class specification release */ + unsigned char bCountryCode; /* Country code of localized hardware */ + unsigned char bNumDescriptors; /* Number of class descriptors */ + unsigned char bDescriptorType1; /* Type of 1st class descriptor (section 7.1) */ + unsigned char wDescriptorLength1[2]; /* Length in bytes of the 1st class descriptor */ +} __attribute__((packed)) USB_HID_Descriptor_t; + +#endif // _HID_DESCRIPTOR_ diff --git a/lib_xua/src/hid/xua_hid_descriptor_contents.h b/lib_xua/src/hid/xua_hid_descriptor_contents.h new file mode 100644 index 00000000..d91e7b15 --- /dev/null +++ b/lib_xua/src/hid/xua_hid_descriptor_contents.h @@ -0,0 +1,64 @@ +// Copyright 2021 XMOS LIMITED. +// This Software is subject to the terms of the XMOS Public Licence: Version 1. + +/** + * @brief Human Interface Device (HID) Endpoint descriptors + * + * This file lists the contents of the HID Endpoint descriptor returned during enumeration. + */ + +#ifndef _HID_DESCRIPTOR_CONTENTS_ +#define _HID_DESCRIPTOR_CONTENTS_ + +#include "xua_hid_descriptor.h" + +#define HID_DESCRIPTOR_LENGTH_0 0x09 /* Size of descriptor in Bytes */ +#define HID_DESCRIPTOR_TYPE_0 0x21 /* HID 0x21 */ +#define HID_BCD_VERSION_LO 0x10 /* HID class specification release */ +#define HID_BCD_VERSION_HI 0x01 +#define HID_COUNTRY_CODE 0x00 /* Country code of localized hardware */ +#define HID_NUM_DESCRIPTORS 0x01 /* Number of class descriptors */ +#define HID_DESCRIPTOR_TYPE_1 0x22 /* Type of 1st class descriptor, Report 0x22 */ +#define HID_DESCRIPTOR_LENGTH_1_LO sizeof(hidReportDescriptor) & 0xff +#define HID_DESCRIPTOR_LENGTH_1_HI sizeof(hidReportDescriptor) >> 8 + +#endif // _HID_DESCRIPTOR_CONTENTS_ + +#if (AUDIO_CLASS == 1) + + /* HID descriptor */ + HID_DESCRIPTOR_LENGTH_0, /* 0 bLength */ + HID_DESCRIPTOR_TYPE_0, /* 1 bDescriptorType (HID) */ + HID_BCD_VERSION_LO, /* 2 bcdHID */ + HID_BCD_VERSION_HI, /* 3 bcdHID */ + HID_COUNTRY_CODE, /* 4 bCountryCode */ + HID_NUM_DESCRIPTORS, /* 5 bNumDescriptors */ + HID_DESCRIPTOR_TYPE_1, /* 6 bDescriptorType[0] */ + HID_DESCRIPTOR_LENGTH_1_LO, /* 7 wDescriptorLength[0] */ + HID_DESCRIPTOR_LENGTH_1_HI, /* 8 wDescriptorLength[0] */ + +#elif (AUDIO_CLASS == 2) + + .HID_Descriptor = + { + /* HID descriptor */ + .bLength = sizeof(USB_HID_Descriptor_t), + .bDescriptorType0 = HID_DESCRIPTOR_TYPE_0, + .bcdHID = + { + HID_BCD_VERSION_LO, + HID_BCD_VERSION_HI, + }, + .bCountryCode = HID_COUNTRY_CODE, + .bNumDescriptors = HID_NUM_DESCRIPTORS, + .bDescriptorType1 = HID_DESCRIPTOR_TYPE_1, + .wDescriptorLength1 = + { + HID_DESCRIPTOR_LENGTH_1_LO, + HID_DESCRIPTOR_LENGTH_1_HI, + }, + }, + +#else + #error "Unknown Audio Class" +#endif diff --git a/lib_xua/src/hid/xua_hid_descriptors.h b/lib_xua/src/hid/xua_hid_descriptors.h new file mode 100644 index 00000000..e06ab90b --- /dev/null +++ b/lib_xua/src/hid/xua_hid_descriptors.h @@ -0,0 +1,20 @@ +// Copyright 2021 XMOS LIMITED. +// This Software is subject to the terms of the XMOS Public Licence: Version 1. + +/** + * @brief Human Interface Device (HID) descriptors + * + * This file lists the contents of the HID descriptors returned during enumeration. + * The full definition of the enumerated descriptors appears in xua_ep0_descriptors.h. + * That file should #include the contents of this one at an appropriate point in the + * definition of the cfgDesc_Audio1 and cfgDesc_Audio2 arrays. + */ + +#ifndef _HID_DESCRIPTORS_ +#define _HID_DESCRIPTORS_ + +#include "xua_hid_interface_descriptor_contents.h" +#include "xua_hid_descriptor_contents.h" +#include "xua_hid_endpoint_descriptor_contents.h" + +#endif // _HID_DESCRIPTORS_ diff --git a/lib_xua/src/hid/xua_hid_endpoint_descriptor_contents.h b/lib_xua/src/hid/xua_hid_endpoint_descriptor_contents.h new file mode 100644 index 00000000..bba85c72 --- /dev/null +++ b/lib_xua/src/hid/xua_hid_endpoint_descriptor_contents.h @@ -0,0 +1,49 @@ +// Copyright 2021 XMOS LIMITED. +// This Software is subject to the terms of the XMOS Public Licence: Version 1. + +/** + * @brief Human Interface Device (HID) Endpoint descriptors + * + * This file lists the contents of the HID Endpoint descriptor returned during enumeration. + */ + +#ifndef _HID_ENDPOINT_DESCRIPTOR_CONTENTS_ +#define _HID_ENDPOINT_DESCRIPTOR_CONTENTS_ + +#include "descriptor_defs.h" + +#define HID_ENDPOINT_DESCRIPTOR_LENGTH 0x07 /* Size of descriptor in Bytes */ +#define HID_ENDPOINT_DESCRIPTOR_TYPE 0x05 /* Endpoint 0x05 */ +#define HID_ENDPOINT_ATTRIBUTES 0x03 /* Interrupt */ +#define HID_ENDPOINT_DESCRIPTOR_PACKET_SIZE_LO 0x40 +#define HID_ENDPOINT_DESCRIPTOR_PACKET_SIZE_HI 0x00 + +#endif // _HID_ENDPOINT_DESCRIPTOR_CONTENTS_ + +#if (AUDIO_CLASS == 1) + + /* HID Endpoint descriptor (IN) */ + HID_ENDPOINT_DESCRIPTOR_LENGTH, /* 0 bLength */ + HID_ENDPOINT_DESCRIPTOR_TYPE, /* 1 bDescriptorType */ + ENDPOINT_ADDRESS_IN_HID, /* 2 bEndpointAddress */ + HID_ENDPOINT_ATTRIBUTES, /* 3 bmAttributes (INTERRUPT) */ + HID_ENDPOINT_DESCRIPTOR_PACKET_SIZE_LO, /* 4 wMaxPacketSize */ + HID_ENDPOINT_DESCRIPTOR_PACKET_SIZE_HI, /* 5 wMaxPacketSize */ + ENDPOINT_INT_INTERVAL_IN_HID, /* 6 bInterval */ + +#elif (AUDIO_CLASS == 2) + + .HID_In_Endpoint = + { + /* Endpoint descriptor (IN) */ + .bLength = sizeof(USB_Descriptor_Endpoint_t), + .bDescriptorType = HID_ENDPOINT_DESCRIPTOR_TYPE, + .bEndpointAddress = ENDPOINT_ADDRESS_IN_HID, + .bmAttributes = HID_ENDPOINT_ATTRIBUTES, + .wMaxPacketSize = HID_ENDPOINT_DESCRIPTOR_PACKET_SIZE_LO, + .bInterval = ENDPOINT_INT_INTERVAL_IN_HID, + }, + +#else + #error "Unknown Audio Class" +#endif diff --git a/lib_xua/src/hid/xua_hid_interface_descriptor_contents.h b/lib_xua/src/hid/xua_hid_interface_descriptor_contents.h new file mode 100644 index 00000000..20df1815 --- /dev/null +++ b/lib_xua/src/hid/xua_hid_interface_descriptor_contents.h @@ -0,0 +1,57 @@ +// Copyright 2021 XMOS LIMITED. +// This Software is subject to the terms of the XMOS Public Licence: Version 1. + +/** + * @brief Human Interface Device (HID) Interface descriptor + * + * This file lists the contents of the HID Interface descriptor returned during enumeration. + */ + +#ifndef _HID_INTERFACE_DESCRIPTOR_CONTENTS_ +#define _HID_INTERFACE_DESCRIPTOR_CONTENTS_ + +#include "descriptor_defs.h" + +#define HID_INTERFACE_DESCRIPTOR_LENGTH 0x09 /* Size of descriptor in Bytes */ +#define HID_INTERFACE_DESCRIPTOR_TYPE 0x04 /* Interface 0x04 */ +#define HID_INTERFACE_ALTERNATE_SETTING 0x00 /* Value used alternate interfaces using SetInterface Request */ +#define HID_INTERFACE_NUMBER_OF_ENDPOINTS 0x01 /* Number of endpoitns for this interface (excluding 0) */ +#define HID_INTERFACE_CLASS 0x03 +#define HID_INTERFACE_SUBCLASS 0x00 /* No boot device */ +#define HID_INTERFACE_PROTOCOL 0x00 +#define HID_INTERFACE_STRING_DESCRIPTOR_INDEX 0x00 + +#endif // _HID_INTERFACE_DESCRIPTOR_CONTENTS_ + +#if (AUDIO_CLASS == 1) + + /* HID interface descriptor */ + HID_INTERFACE_DESCRIPTOR_LENGTH, /* 0 bLength */ + HID_INTERFACE_DESCRIPTOR_TYPE, /* 1 bDescriptorType */ + INTERFACE_NUMBER_HID, /* 2 bInterfaceNumber : Number of interface */ + HID_INTERFACE_ALTERNATE_SETTING, /* 3 bAlternateSetting */ + HID_INTERFACE_NUMBER_OF_ENDPOINTS, /* 4: bNumEndpoints */ + HID_INTERFACE_CLASS, /* 5: bInterfaceClass */ + HID_INTERFACE_SUBCLASS, /* 6: bInterfaceSubClass */ + HID_INTERFACE_PROTOCOL, /* 7: bInterfaceProtocol*/ + HID_INTERFACE_STRING_DESCRIPTOR_INDEX, /* 8 iInterface */ + +#elif (AUDIO_CLASS == 2) + + .HID_Interface = + { + /* HID interface descriptor */ + .bLength = sizeof(USB_Descriptor_Interface_t), + .bDescriptorType = HID_INTERFACE_DESCRIPTOR_TYPE, + .bInterfaceNumber = INTERFACE_NUMBER_HID, + .bAlternateSetting = HID_INTERFACE_ALTERNATE_SETTING, + .bNumEndpoints = HID_INTERFACE_NUMBER_OF_ENDPOINTS, + .bInterfaceClass = HID_INTERFACE_CLASS, + .bInterfaceSubClass = HID_INTERFACE_SUBCLASS, + .bInterfaceProtocol = HID_INTERFACE_PROTOCOL, + .iInterface = HID_INTERFACE_STRING_DESCRIPTOR_INDEX, + }, + +#else + #error "Unknown Audio Class" +#endif