feat(usb): add FS/LS-only root port mode

[TDA-2030]

Description

This PR adds the root_port_fsls_only option to usb_host_config_t.

It allows the USB Host controller to operate root ports in FS/LS-only mode, avoiding the unsupported Transaction Translator (TT) path when using FS/LS
devices. At the same time, applications can retain the larger number of host channels provided by the HS-capable controller.

Benefits:

• Avoids the current TT limitation
• Retains the HS controller’s additional host channels
• Keeps the existing behavior unchanged by default

Related

Testing

---

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 root-port reset and host-controller configuration during enumeration; misconfiguration could affect device attach, but the feature is opt-in and defaults off.

Overview
Adds an opt-in root_port_fsls_only flag on usb_host_config_t so applications can restrict root-port enumeration to full/low speed while still using the high-speed-capable controller (and its extra host channels), avoiding the unsupported transaction-translator path for FS/LS devices.

The setting is threaded through hub install into each root HCD port (fsls_only on hcd_port_config_t / port_obj). When enabled, HCD_PORT_CMD_RESET applies usb_dwc_ll_hcfg_set_fsls_supp_only on the DWC before the normal reset sequence. Default remains false (existing behavior). Changelog and install unit tests initialize the new field.

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 9d9d1fe. Configure here.}

[peter-marcisovsky]

FYI, I did something similar for this issue espressif/esp-idf#17245

[TDA-2030]

FYI, I did something similar for this issue espressif/esp-idf#17245

Yes, it seems to be solving the same problem.

[peter-marcisovsky]

1. PTAL at my commit 6306c4f, I also changed the UTMI PHY clock and other timing stuff, once restricting only FS/LS connection on a HS port. Could you investigate whether we need it? It was quite a time ago and only a POC, so I don't remember.

2. Consider adding some HCD or USB Host target tests, where you set this bit when installing the USB Host and expect the connected device to enumerate as as a FS device. There is an esp32p4 runner with a flash disk connected. It should be straightforward.

[peter-marcisovsky]

Should we make this config available only for HS ports/targets ? There shall be no risk of setting this bit for FS ports only, per the DWC databook. But having it for esp32s2/s3 is bit misleading. Or at least put some comment with explanation.

[TDA-2030]

You're right. I didn't take that into account.

[peter-marcisovsky]

Per the DWC databook:

The application uses this bit to control the core’s enumeration speed. Using
this bit, the application can make the core enumerate as a FS host, even if
the connected device supports HS traffic. Do not make changes to this field
after initial programming.

The initial programming, is around the set_defaults() in HAL. WHich is called from both, the soft reset after enumeration and HAL init. In this context it should be fine. As we set the fslssupp before asserting reset.

There is another safety concern, the reset CMD can be issued also to exit suspended state, during which the PCLK is gated, thus some of the DWC registers are not accessible. Which means in a situation where you install the usb host with the fsls_bit set -> device enumerates as FS -> suspend the root port -> reset the root port -> risk of device being enumerated as HS again, as the usb_dwc_ll_hcfg_set_fsls_supp_only call could be ignored with the PCLK gated.

If this is true, I think, the safer place to call this might be from HAL, not from HCD.

You could investigate this riks. There is a HCD PORT target test which exits the suspended sate using port reset. Just install the HCD port wit the fsls bit set and expect the device to be enumerated as FS again.

[TDA-2030]

1. PTAL at my commit 6306c4f, I also changed the UTMI PHY clock and other timing stuff, once restricting only FS/LS connection on a HS port. Could you investigate whether we need it? It was quite a time ago and only a POC, so I don't remember.
2. Consider adding some HCD or USB Host target tests, where you set this bit when installing the USB Host and expect the connected device to enumerate as as a FS device. There is an esp32p4 runner with a flash disk connected. It should be straightforward.

1. I have tested the current code on the ESP32‑P4, and it can limit devices on the hub to connect at FS speed. Moreover, the devices still operate at FS speed after hot‑plugging. But I haven't tested whether there will be any issues with suspend/resume.

2. I will try to add such a test.