feat(esp_tinyusb): Support ESP32-S31 as HS-only single-port device

[igi540]

Description

This PR enables esp_tinyusb on ESP32-S31, which has a single HS-only USB-OTG peripheral (UTMI PHY, no internal FSLS PHY).
Previously, HS handling in esp_tinyusb assumed that HS implies a multi-port chip (checked via SOC_USB_OTG_PERIPH_NUM > 1, with the HS port being TINYUSB_PORT_HIGH_SPEED_0). ESP32-S31 breaks that assumption: it has only one port, and that port is always HS. The refactor replaces those checks with two small helpers:

• TINYUSB_PORT_IS_HS(port) — used during descriptor selection in descriptors_control.c
• TINYUSB_PORT_DEFAULT_HS — used as the default port value in TINYUSB_CONFIG_HIGH_SPEED()
  so both multi-port HS chips (e.g. ESP32-P4) and single-port HS-only chips (e.g. ESP32-S31) are handled uniformly.
  Other notable changes:
• TinyUSB dependency is bumped to >=0.19.0~3-rc1, which is required for ESP32-S31 support.
• The DCache enable condition in tusb_config.h is tightened: having an L1 cache (CONFIG_CACHE_L1_CACHE_LINE_SIZE != 0) is no longer sufficient — internal SRAM must also be routed through it (CONFIG_SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE). Otherwise DCache clean/invalidate calls on TinyUSB DMA buffers (which live in internal SRAM) are unnecessary and incorrect on S31.
• Software VBUS monitoring (previously P4-only) is now also compiled in for ESP32-S31 and initialized unconditionally for self-powered devices on that target.

Related

IDF-14703

Testing

Manually verified on hardware:

• ESP32-S31 (new target)
  • msc device example — MSC device enumerates and works at high speed.
  • hid device example — HID device enumerates and works at high speed.
• ESP32-S2 (regression check)
  • msc device example — MSC device still enumerates and works at full speed, confirming the HS refactor does not break existing FS-only single-port targets.

---

Note

Medium Risk
Extends core USB init/descriptor and DMA-cache configuration logic to handle an HS-only target and bumps the TinyUSB dependency, which could affect enumeration and DMA behavior across supported chips if assumptions are wrong.

Overview
Adds ESP32-S31 as a supported target for esp_tinyusb, updating default config macros and descriptor selection to treat the single port as always high-speed (vs. the previous “HS implies multi-port” assumption).

Updates runtime init to use the UTMI PHY and HS speed on S31, enables software VBUS monitoring for S31 (and includes the GPIO dependency), and adjusts TinyUSB task port-speed selection accordingly.

Bumps the tinyusb component requirement to >=0.19.0~3-rc1, tightens the DMA DCache enable condition to require CONFIG_SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE, and updates Kconfig buffer-size defaults/ranges for HS-capable targets.

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

[tore-espressif]

@igi540 I tested with tinyusb 0.19.0~3-rc1 and all seems to work correctly.

I did not test VBUS yet

[Copilot]

Pull request overview

This PR updates esp_tinyusb to support ESP32-S31, a single-port HS-only USB-OTG target, by decoupling “HS support” from the prior “multi-port” assumption and aligning configuration/descriptor handling accordingly.

Changes:

• Add ESP32-S31 target support and bump TinyUSB dependency to a version that includes S31 support.
• Introduce HS-port selection helpers for default config and HS descriptor selection to support both multi-port HS chips (e.g., P4) and HS-only single-port chips (S31).
• Refine DMA DCache-maintenance enablement and extend software VBUS monitoring to ESP32-S31.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
device/esp_tinyusb/tinyusb_task.c	Sets task init speed for ESP32-S31 to HS unconditionally.
device/esp_tinyusb/tinyusb.c	Adjusts PHY configuration for S31 and extends software VBUS monitoring init/deinit logic.
device/esp_tinyusb/include/tusb_config.h	Enables HS max speed for S31 and tightens DCache-maintenance gating for DMA buffers.
device/esp_tinyusb/include/tinyusb_default_config.h	Adds a default HS port helper and uses it in TINYUSB_CONFIG_HIGH_SPEED().
device/esp_tinyusb/idf_component.yml	Adds esp32s31 target and bumps TinyUSB dependency version.
device/esp_tinyusb/descriptors_control.c	Adds TINYUSB_PORT_IS_HS() helper to select HS descriptors correctly on S31 and multi-port HS chips.
device/esp_tinyusb/Kconfig	Updates FIFO defaults/ranges to include ESP32-S31.
device/esp_tinyusb/CMakeLists.txt	Builds software VBUS monitoring module for ESP32-S31 in addition to ESP32-P4.

Comments suppressed due to low confidence (1)

device/esp_tinyusb/tinyusb.c:209

• On ESP32-S31, VBUS monitoring is initialized for any self_powered config, but there is no validation that config->phy.vbus_monitor_io is set to a valid GPIO (default is -1). If left at the default, tinyusb_vbus_monitor_init() will use BIT64(-1) and attempt to configure an invalid pin. Please add an explicit argument check (e.g. reject vbus_monitor_io < 0/GPIO_NUM_NC) before calling USB_PHY_SELF_POWERED_DEVICE() / tinyusb_vbus_monitor_init() when self_powered is true.

    // Initialize VBUS monitoring only for High-Speed ports and self-powered devices
#if (CONFIG_IDF_TARGET_ESP32P4)
    if (config->port == TINYUSB_PORT_HIGH_SPEED_0 && config->phy.self_powered) {
#else
    if (config->phy.self_powered) {
#endif
        const tinyusb_vbus_monitor_config_t vbus_cfg = {
            .gpio_num = config->phy.vbus_monitor_io,
            .port = (int)config->port,
        };

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[peter-marcisovsky]

BTW, no esp32s31 apps are built in this CI. Both builds, the device test apps and esp-idf exaples are disabled for esp32s31.

[tore-espressif]

BTW, no esp32s31 apps are built in this CI. Both builds, the device test apps and esp-idf exaples are disabled for esp32s31.

@igi540 @peter-marcisovsky So we merge #469 now and then rebase this?

[cursor]

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

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

^{Reviewed by Cursor Bugbot for commit 6a23893. Configure here.}

[tore-espressif]

@igi540 @peter-marcisovsky I could not reproduce the example build failure locally... If all other tests pass, IMO we can merge this to unblock CI for other PRs and double check everthing during esp_tinyusb v2.2.0 release

[peter-marcisovsky]

I have the same "error" locally, even thought it's just and warning during build, but warnings are treated as errors in CI build succeeded with warnings

(cmake) App examples/network/sta2eth, target esp32s2, sdkconfig (default), build in examples/network/sta2eth/build_esp32s2_default, build failed in 83.471661s: build succeeded with warnings

The app built fine. I suppose we can continue and catch this problem during esp_tinyusb release. I will take a look into it in meanwhile.