USB HID Report Descriptor length greater than 255 bytes not supported

[fronders]

USB HID Descriptor uses only lowest byte of 16-bit USB HID Report Descriptor length (defined by standard), while higher byte is always set to 0. This results in maximum length of HID Report Descriptor to only 255 bytes instead of 65535. This issue is related to USB_Device middleware and is present across all STM32 families. Same issue appears when using HID or Custom HID classes in USB Device middleware.

Describe the set-up

• CubeMX v6.4.0 with CubeL4 v1.17.0 under Windows 10 Pro x64 21H1 (build 19043.1237)

Describe the bug The following code gets generated for Device Configuration descriptor in usbd_customhid.c when using USB Custom HID Class:

  /******************** Descriptor of CUSTOM_HID *************************/
  /* 18 */
  0x09,                                               /* bLength: CUSTOM_HID Descriptor size */
  CUSTOM_HID_DESCRIPTOR_TYPE,                         /* bDescriptorType: CUSTOM_HID */
  0x11,                                               /* bCUSTOM_HIDUSTOM_HID: CUSTOM_HID Class Spec release number */
  0x01,
  0x00,                                               /* bCountryCode: Hardware target country */
  0x01,                                               /* bNumDescriptors: Number of CUSTOM_HID class descriptors to follow */
  0x22,                                               /* bDescriptorType */
  USBD_CUSTOM_HID_REPORT_DESC_SIZE,                   /* wItemLength: Total length of Report descriptor */
  0x00,

Here the field wItemLength is at offset 7 and has length of 1 byte, second byte is explicitly set to 0x00, while the HID Class Definition states wDescriptorLength is at offset 7 and length of 2 bytes (see screenshot below). This prevents the HID Descriptor being larger than 255 bytes.

In order to fix the issue I suggest changing the uppermentioned descriptor to following:

  /******************** Descriptor of CUSTOM_HID *************************/
  /* 18 */
  0x09,                                               /* bLength: CUSTOM_HID Descriptor size */
  CUSTOM_HID_DESCRIPTOR_TYPE,                         /* bDescriptorType: CUSTOM_HID */
  0x11,                                               /* bCUSTOM_HIDUSTOM_HID: CUSTOM_HID Class Spec release number */
  0x01,
  0x00,                                               /* bCountryCode: Hardware target country */
  0x01,                                               /* bNumDescriptors: Number of CUSTOM_HID class descriptors to follow */
  0x22,                                               /* bDescriptorType */
  LOBYTE(USBD_CUSTOM_HID_REPORT_DESC_SIZE),           /* wItemLength: Total length of Report descriptor (lower byte) */
  HIBYTE(USBD_CUSTOM_HID_REPORT_DESC_SIZE),           /* wItemLength: Total length of Report descriptor (higher byte) */

I have verified the fix to work correctly in multiple projects with HID Report Descriptor being 300+ bytes length. This needs to be patched in multiple locations throughout usbd_customhid.c as it is present in multiple config descriptor arrays:

• USBD_CUSTOM_HID_CfgFSDesc[]
• USBD_CUSTOM_HID_CfgHSDesc[]
• USBD_CUSTOM_HID_OtherSpeedCfgDesc[]

[ALABSTM]

Hi @fronders,

Thank you for having reported. Actually, @berkakinci proposed the same fix in #3. The point will be forwarded to our development teams. Thank you again.

With regards,

[berkakinci]

@ALABSTM Please note that this fix also needs corresponding changes to STM32CubeMX. I'm not working on this project, so I can't check if it's been done on STM32CubeMX. My original note says:

A corresponding fix is necessary for STM32CubeMX. There is an artificial "255" limit on Class parameter: USBD_CUSTOM_HID_REPORT_DESC_SIZE. With this fix, it can be larger. I'm using 587 bytes currently. There may be more limits to relax, but this was the only one in my way.

I only mentioned one limit, but I now see I added several 16-bit value fixes in the pull request. Each may need a corresponding STM32CubeMX change.