Enable ESP32-S31 in the USB device example build rules, supported
target tables, USB PHY pin mapping, and pytest target parametrization.
The target supports USB-OTG through its USB 2.0 PHY. Keep ESP32-S31
USB device tests marked as temporary CI skips until runners with the
usb_device tag are available.
Remove the temporary esp32s31 disable from usb/host build-test rules.
Add esp32s31 and esp32h4 to the usb_host_msc and usb_host_lib pytest
matrices. Keep the tests temp-skipped in CI until usb_host_flash_disk
runners exist.
Add ESP32-S31 USB DWC/UTMI LL headers, SoC register structures, peripheral
descriptors, capabilities, and linker mappings so the HS OTG controller and
UTMI PHY can be built in esp_hal_usb.
Introduce SOC_USB_FSLS_PHY_NUM on USB-OTG targets to separate FSLS USB_WRAP
support from OTG/UTMI support. Use it to gate usb_wrap, the USB PHY driver,
docs, and example build rules on targets without an FSLS PHY.
Also add UTMI data pulldown control to the HAL, clear the boot-time DWC
suspend state on ESP32-S31, alias the legacy internal PHY target to UTMI for
backward compatibility, and extend usb_phy tests for UTMI-only targets.
Replace the peripherals index USB entries with direct links to
ESP-USB so the generated pages are no longer redirect-only stubs.
Keep legacy USB URLs working via redirects, including the
individual USB host maintainer notes pages.
Remove the obsolete placeholder documents and stale CODEOWNERS
pattern.
Mark the moved USB examples as KNOWN_MISSING in the example
documentation checker until it can also read the ESP-USB guide.
Remove USB Host/Device content from ESP-IDF pages and keep only links to
ESP-USB documentation.
Add redirects for legacy USB pages to ESP-USB with target-aware URL
substitution in docs config.
Drop obsolete USB host notes references from docs_not_updated lists.
Add top-level section for configuring and initializing external USB PHY
on ESP32-S3. Includes GPIO mapping, code example, and guidance on
suspend and speed selection pins.
Link to ESP USB PHY guide for SP5301 setup to avoid duplicating content.
Add dedicated schematic reference for STUSB03E with analog switch.
Moved USB PHY source and headers from `usb/` to `esp_hw_support/`
to better reflect their hardware-specific nature.
Replaced use of public GPIO driver APIs with internal LL (Low-Level) APIs
for more precise hardware control and alignment with ESP-IDF HAL best practices.
Deleted deprecated PHY helper functions.
Consolidated all SoC-specific declarations under `usb_periph.h`.
BREAKING CHANGE: deprecated USB PHY APIs have been removed; update
callers to use the new interfaces in esp_hw_support/usb_phy.h
The ESP_LOGD message that prints FIFO line sizes used %u for uint32_t,
which may cause incorrect output on some architectures (e.g., ESP32-P4
where uint32_t maps to unsigned long). To ensure portable and correct
logging across all supported platforms, this patch replaces %u with
%" PRIu32 ", defined in <inttypes.h>.
No functional behavior is affected — this is a formatting correction
for debug output only.
Introduce a new HAL API `usb_dwc_hal_set_fifo_config()` that allows advanced users
to manually configure RX, Non-Periodic TX, and Periodic TX FIFO sizes. This offers
fine-grained control beyond the previous bias-based sizing approach.
The HAL function no longer returns `esp_err_t`, and internal validations are enforced
via `HAL_ASSERT()`. Responsibility for input validation has been moved to the HCD layer.
FIFO configuration must be applied before any USB pipes are created or activated.
This feature is intended for use during `usb_host_install()`.
If no custom FIFO configuration is provided (i.e., all values are zero),
the driver falls back to a bias-based default layout based on Kconfig settings
(`CONFIG_USB_HOST_HW_BUFFER_BIAS_*`). Bias resolution is done inside `hcd_port_init()`.
The `port_obj_t` structure has been extended with a `fifo_config` field, which stores
the configuration to allow re-application after a USB port reset.
Obsolete FIFO bias enums (`usb_hal_fifo_bias_t`, `hcd_port_fifo_bias_t`) and related
APIs (`hcd_port_set_fifo_bias()`) have been removed in favor of the new structure-based mechanism.
The HCD initialization and port reset flow has been updated to use the explicit
FIFO configuration.
USB Host maintainer documentation (`maintainers.md`) has been updated accordingly.
Test cases were updated to remove the usage of removed bias API and now rely on default
or custom FIFO configuration.
Added performance optimization details for USB MSC on ESP32-S3, ESP32-P4, and ESP32-S2.
Includes benchmarking results for SD card and SPI flash, explanation of performance
limitations.
Related to https://github.com/espressif/esp-idf/issues/11110
Changed error code from ESP_ERR_INVALID_STATE to ESP_ERR_NOT_FOUND
when the client never opened the device.
Updated function documentation to correctly reflect return values.
Enhanced the USB MSC host example to support multiple simultaneously
connected Mass Storage Class (MSC) devices.
- Implemented dynamic allocation and mounting of multiple MSC devices.
- Improved example logic for handling USB device connections and disconnections.
- Updated documentation to clarify USB host limitations and endpoint allocation.
The hardware field `ghwcfg2.numhstchnl` is zero-based, meaning the actual
number of available host channels is `numhstchnl + 1`. This off-by-one
error caused the USB Host controller to report N-1 channels instead of N,
leading to premature "No more HCD channels available" errors when
connecting multiple devices.
This issue affects ESP32-S2, ESP32-S3, and ESP32-P4.
igor.masar