feat(usb_host): Fix hw fifo sizing with bias for periodic OUT

[peter-marcisovsky]

Description

• Fixing RXFIFO extra lines for status quadlets when the bias is set to periodic OUT
• DWC Guide specifies +2 FIFO lines for status quadlets
• This was tested not to be enough and +3 lines are required instead
• A device with 512 byte IN EP never completes it's transfer otherwise

Related

• Fixes RX FIFO check accepts an undersized allocation for interrupt-IN (IDFGH-18354) esp-idf#19143

Testing

Testing esp-idf HID Host and Device examples, with a custom TinyUSB Device with following descriptor:

Device descriptor

peter@peter ➜  ~ lsusb -s 031 -v

Bus 003 Device 031: ID 303a:4004 TinyUSB TinyUSB Device
Couldn't open device, some information will be missing
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               2.00
  bDeviceClass            0 
  bDeviceSubClass         0 
  bDeviceProtocol         0 
  bMaxPacketSize0        64
  idVendor           0x303a 
  idProduct          0x4004 
  bcdDevice            1.00
  iManufacturer           1 TinyUSB
  iProduct                2 TinyUSB Device
  iSerial                 3 123456
  bNumConfigurations      1
  Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength       0x0029
    bNumInterfaces          1
    bConfigurationValue     1
    iConfiguration          0 
    bmAttributes         0xa0
      (Bus Powered)
      Remote Wakeup
    MaxPower              100mA
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        0
      bAlternateSetting       0
      bNumEndpoints           2
      bInterfaceClass         3 Human Interface Device
      bInterfaceSubClass      1 Boot Interface Subclass
      bInterfaceProtocol      1 Keyboard
      iInterface              4 
        HID Device Descriptor:
          bLength                 9
          bDescriptorType        33
          bcdHID               1.11
          bCountryCode            0 Not supported
          bNumDescriptors         1
          bDescriptorType        34 Report
          wDescriptorLength      36
         Report Descriptors: 
           ** UNAVAILABLE **
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x03  EP 3 OUT
        bmAttributes            3
          Transfer Type            Interrupt
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0400  1x 1024 bytes
        bInterval               1
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x82  EP 2 IN
        bmAttributes            3
          Transfer Type            Interrupt
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0200  1x 512 bytes
        bInterval               1

• HID Host was built with CONFIG_USB_HOST_HW_BUFFER_BIAS_PERIODIC_OUT bias
• When extra 2 lines (old code) for RXFIFO was present in code the device was accepted by the pipe_alloc_hcd_support_verification() but the IN transfer wold never complete.
• With extra 3 lines (the fix) for RXFIFO, the transfer was completed correctly

Buffer DMA formula

The DWC Programming guide specifies a formula for Buffer DMA only, in chapter 2.1.2.1 which is roughly the:
2 * ((Largest Packet size / 4) + 1 + 1) + n, where the n is number of non periodic channels used.

FYI: For SG DMA, there is the same formula but the + n parameter is missing.

For handling NAK/NYET in Buffer DMA mode, the application must determine the number of
Control/Bulk OUT endpoint data that must fit into the TX_FIFO at the same instant. Based on this, one
location each is required for Control/Bulk OUT endpoints.

For example, when the host addresses one Control OUT endpoint and three Bulk OUT endpoints, and all
these must fit into the non-periodic TxFIFO at the same time, then four extra locations are required in the
RxFIFO to store the rewind status information for each of these endpoints.

Applying this formula in SG DMA mode was proven not to be valid. More Non perodic channels in use did not require any extra RXFIFO lines. Which prove the formula is really Buffer DMA only.

---

Checklist

Before submitting a Pull Request, please ensure the following:

• 🚨 This PR does not introduce breaking changes.
• All CI checks (GH Actions) pass.
• Documentation is updated as needed.
• Tests are updated or added as necessary.
• Code is well-commented, especially in complex areas.
• Git history is clean — commits are squashed to the minimum necessary.

---

Note

Medium Risk
Changes DWC2 host FIFO layout for one menuconfig bias; wrong sizing can break IN traffic, but other bias modes and custom FIFO configs are unchanged.

Overview
Fixes interrupt-IN transfers that never complete when the host uses CONFIG_USB_HOST_HW_BUFFER_BIAS_PERIODIC_OUT, by reserving three RX FIFO lines for GRXSTSP status quadlets instead of two.

In _calculate_fifo_from_bias(), the periodic-OUT bias now sets rx_fifo_lines to D/8 + 3 (default 3, overridable via USB_DWC_HAL_RX_FIFO_STATUS_LINES), and shrinks the periodic TX FIFO by one line accordingly. Kconfig help for “Bias Periodic OUT” documents the +3 requirement and the 512-byte interrupt-IN failure seen with +2.

^{Reviewed by Cursor Bugbot for commit 2b4ca06. Bugbot is set up for automated code reviews on this repo. Configure here.}