From 981e271b9466993a8b522c9039cd75bd8df08a95 Mon Sep 17 00:00:00 2001 From: "igor.masar" Date: Sun, 19 Oct 2025 19:10:38 +0200 Subject: [PATCH 1/2] docs(usb): add ESP32-H4 support notes and pin map - usb_device: add esp32h4 DP/DM defaults (GPIO22/21) and "only:: esp32h4"; add H4 PHY considerations; add H4 MSC write-speed table; generalize MSC SD note to {IDF_TARGET_NAME}; exclude tusb_ncm on H4 - usb_host: include esp32h4 in feature gates; add H4 PHY considerations - usb_host_notes_dwc_otg: enable H4 by extending "only::" selector - examples/usb: add ESP32-H4 row to DP/DM pin map - docs_not_updated: drop H4 entries for usb_device, usb_host, and related usb_host notes now covered - soc(esp32h4): set internal PHY mapping to DP=22, DM=21 (cherry picked from commit 7492f9b9cd74740ce23d1ba377856754c99efe88) --- components/soc/esp32h4/usb_dwc_periph.c | 4 +-- docs/docs_not_updated/esp32h4.txt | 10 ------ .../api-reference/peripherals/usb_device.rst | 33 +++++++++++++++---- .../en/api-reference/peripherals/usb_host.rst | 2 +- .../usb_host/usb_host_notes_dwc_otg.rst | 2 +- examples/peripherals/usb/README.md | 1 + 6 files changed, 32 insertions(+), 20 deletions(-) diff --git a/components/soc/esp32h4/usb_dwc_periph.c b/components/soc/esp32h4/usb_dwc_periph.c index 0b5c4e43dc7..fe2b5acdee1 100644 --- a/components/soc/esp32h4/usb_dwc_periph.c +++ b/components/soc/esp32h4/usb_dwc_periph.c @@ -28,8 +28,8 @@ static const usb_otg_signal_conn_t otg_signals = { }; static const usb_internal_phy_io_t internal_phy_io = { - .dp = 21, - .dm = 22, + .dp = 22, + .dm = 21, }; /* --------------------------------- Public --------------------------------- */ diff --git a/docs/docs_not_updated/esp32h4.txt b/docs/docs_not_updated/esp32h4.txt index d75bf21a37b..b16afa94618 100644 --- a/docs/docs_not_updated/esp32h4.txt +++ b/docs/docs_not_updated/esp32h4.txt @@ -125,10 +125,8 @@ api-reference/peripherals/gptimer.rst api-reference/peripherals/sdio_slave.rst api-reference/peripherals/bitscrambler.rst api-reference/peripherals/temp_sensor.rst -api-reference/peripherals/usb_device.rst api-reference/peripherals/jpeg.rst api-reference/peripherals/mcpwm.rst -api-reference/peripherals/usb_host.rst api-reference/peripherals/camera_driver.rst api-reference/peripherals/adc_oneshot.rst api-reference/peripherals/sdspi_share.rst @@ -139,14 +137,6 @@ api-reference/peripherals/sdspi_host.rst api-reference/peripherals/vad.rst api-reference/peripherals/i2s.rst api-reference/peripherals/isp.rst -api-reference/peripherals/usb_host/usb_host_notes_usbh.rst -api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst -api-reference/peripherals/usb_host/usb_host_notes_arch.rst -api-reference/peripherals/usb_host/usb_host_notes_index.rst -api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst -api-reference/peripherals/usb_host/usb_host_notes_design.rst -api-reference/peripherals/usb_host/usb_host_notes_enum.rst -api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst api-reference/peripherals/dedic_gpio.rst api-reference/peripherals/sd_pullup_requirements.rst api-reference/peripherals/parlio.rst diff --git a/docs/en/api-reference/peripherals/usb_device.rst b/docs/en/api-reference/peripherals/usb_device.rst index 8fcb8b2c8ac..df58ee34728 100644 --- a/docs/en/api-reference/peripherals/usb_device.rst +++ b/docs/en/api-reference/peripherals/usb_device.rst @@ -3,8 +3,8 @@ USB Device Stack :link_to_translation:`zh_CN:[中文]` -{IDF_TARGET_USB_DP_GPIO_NUM:default="20"} -{IDF_TARGET_USB_DM_GPIO_NUM:default="19"} +{IDF_TARGET_USB_DP_GPIO_NUM:default="20", esp32h4="22"} +{IDF_TARGET_USB_DM_GPIO_NUM:default="19", esp32h4="21"} {IDF_TARGET_USB_EP_NUM: default="6", esp32p4="15"} {IDF_TARGET_USB_EP_NUM_INOUT:default="5", esp32p4="8"} {IDF_TARGET_USB_EP_NUM_IN:default="1", esp32p4="7"} @@ -34,7 +34,7 @@ Features Hardware Connection ------------------- -.. only:: esp32s2 or esp32s3 +.. only:: esp32s2 or esp32s3 or esp32h4 The {IDF_TARGET_NAME} routes the USB D+ and D- signals to GPIOs {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_USB_DM_GPIO_NUM} respectively. For USB device functionality, these GPIOs should be connected to the bus in some way (e.g., via a Micro-B port, USB-C port, or directly to standard-A plug). @@ -47,7 +47,7 @@ Hardware Connection :alt: Connection of an USB GPIOs directly to a USB standard-A plug :figclass: align-center -.. only:: esp32s2 or esp32s3 +.. only:: esp32s2 or esp32s3 or esp32h4 .. note:: @@ -406,7 +406,7 @@ This approach ensures that USB transactions remain fast while avoiding potential .. note:: - SD card support is not available for ESP32-S2 in MSC device mode. + SD card support is not available for {IDF_TARGET_NAME} in MSC device mode. **SPI Flash Performance:** @@ -423,6 +423,27 @@ This approach ensures that USB transactions remain fast while avoiding potential * - 8192 B - 21.54 KB/s +.. only:: esp32h4 + + .. note:: + + SD card support is not available for {IDF_TARGET_NAME} in MSC device mode. + + **SPI Flash Performance:** + + .. list-table:: + :header-rows: 1 + :widths: 20 20 + + * - FIFO Size + - Write Speed + + * - 512 B + - 4.48 KB/s + + * - 8192 B + - 22.33 KB/s + Performance Limitations: - **Internal SPI Flash performance** is constrained by architectural limitations where program execution and storage access share the same flash chip. This results in program execution being **suspended during flash writes**, significantly impacting performance. @@ -444,6 +465,6 @@ The examples can be found in the directory :example:`peripherals/usb/device`. - :example:`peripherals/usb/device/tusb_msc` demonstrates how to use the USB capabilities to create a Mass Storage Device that can be recognized by USB-hosts, allowing access to its internal data storage, with support for SPI Flash and SD MMC Card storage media. - :example:`peripherals/usb/device/tusb_composite_msc_serialdevice` demonstrates how to set up {IDF_TARGET_NAME} to function simultaneously as both a USB Serial Device and an MSC device (SPI-Flash as the storage media) using the TinyUSB component. -.. only:: not esp32p4 +.. only:: not esp32p4 and not esp32h4 - :example:`peripherals/usb/device/tusb_ncm` demonstrates how to transmit Wi-Fi data to a Linux or Windows host via USB using the Network Control Model (NCM), a sub-class of Communication Device Class (CDC) USB Device for Ethernet-over-USB applications, with the help of a TinyUSB component. diff --git a/docs/en/api-reference/peripherals/usb_host.rst b/docs/en/api-reference/peripherals/usb_host.rst index c318c06eb6f..38184cfbe64 100644 --- a/docs/en/api-reference/peripherals/usb_host.rst +++ b/docs/en/api-reference/peripherals/usb_host.rst @@ -29,7 +29,7 @@ The Host Library has the following features: .. list:: - :esp32s2 or esp32s3: - Supports Full Speed (FS) and Low Speed (LS) Devices. + :esp32s2 or esp32s3 or esp32h4: - Supports Full Speed (FS) and Low Speed (LS) Devices. :esp32p4: - Supports High Speed (HS), Full Speed (FS) and Low Speed (LS) Devices. - Supports all four transfer types: Control, Bulk, Interrupt, and Isochronous. :esp32p4: - Supports High-Bandwidth Isochronous endpoints. diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst index e9cab825284..1885b7d0884 100644 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst +++ b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst @@ -116,7 +116,7 @@ The DWC_OTG IP is configurable. The notable host related configurations of the { * - Only 4 periodic and 4 non-periodic transactions per microframe - ``OTG_NPERIO_TX_QUEUE_DEPTH = 4``, ``OTG_PERIO_TX_QUEUE_DEPTH = 4`` -.. only:: esp32s2 or esp32s3 +.. only:: esp32s2 or esp32s3 or esp32h4 .. list-table:: {IDF_TARGET_NAME}'s DWC_OTG Configuration :widths: 70 30 diff --git a/examples/peripherals/usb/README.md b/examples/peripherals/usb/README.md index 30a6320fe71..b3000ffbb89 100644 --- a/examples/peripherals/usb/README.md +++ b/examples/peripherals/usb/README.md @@ -24,5 +24,6 @@ ESP BOARD USB CONNECTOR (type A) | ESP32-S2/S3 | GPIO20 | GPIO19 | | ESP32-P4 2.0 | pin 50 | pin 49 | | ESP32-P4 1.1 | GPIO27 | GPIO26 | +| ESP32-H4 | GPIO22 | GPIO21 | > Note: On the ESP32-P4, the USB 2.0 PHY pins are dedicated to USB-OTG functionality and cannot be used as general-purpose GPIOs. From c88d8ed378e3864dc5f4e9538f87a9280d4e3b25 Mon Sep 17 00:00:00 2001 From: renpeiying Date: Tue, 4 Nov 2025 15:07:36 +0800 Subject: [PATCH 2/2] docs: Update CN translation (cherry picked from commit bcef36325b41b93df9851c87940697b9653cd039) --- .../api-reference/peripherals/usb_device.rst | 33 +++++++++++++++---- .../api-reference/peripherals/usb_host.rst | 2 +- .../usb_host/usb_host_notes_dwc_otg.rst | 2 +- 3 files changed, 29 insertions(+), 8 deletions(-) diff --git a/docs/zh_CN/api-reference/peripherals/usb_device.rst b/docs/zh_CN/api-reference/peripherals/usb_device.rst index 205649f9d12..7486c26c0d7 100644 --- a/docs/zh_CN/api-reference/peripherals/usb_device.rst +++ b/docs/zh_CN/api-reference/peripherals/usb_device.rst @@ -3,8 +3,8 @@ USB 设备栈 :link_to_translation:`en:[English]` -{IDF_TARGET_USB_DP_GPIO_NUM:default="20"} -{IDF_TARGET_USB_DM_GPIO_NUM:default="19"} +{IDF_TARGET_USB_DP_GPIO_NUM:default="20", esp32h4="22"} +{IDF_TARGET_USB_DM_GPIO_NUM:default="19", esp32h4="21"} {IDF_TARGET_USB_EP_NUM: default="6", esp32p4="15"} {IDF_TARGET_USB_EP_NUM_INOUT:default="5", esp32p4="8"} {IDF_TARGET_USB_EP_NUM_IN:default="1", esp32p4="7"} @@ -34,7 +34,7 @@ USB 设备栈（以下简称设备栈）支持在 {IDF_TARGET_NAME} 上启用 US 硬件连接 -------- -.. only:: esp32s2 or esp32s3 +.. only:: esp32s2 or esp32s3 or esp32h4 {IDF_TARGET_NAME} 将 USB D+ 和 D- 信号分别路由到 GPIO {IDF_TARGET_USB_DP_GPIO_NUM} 和 {IDF_TARGET_USB_DM_GPIO_NUM}。为了实现 USB 设备功能，这些 GPIO 应通过某种方式连接到总线（例如，通过 Micro-B 端口、USB-C 端口或直接连接到标准-A 插头）。 @@ -47,7 +47,7 @@ USB 设备栈（以下简称设备栈）支持在 {IDF_TARGET_NAME} 上启用 US :alt: 将 USB GPIO 直接接连至 USB 标准-A 插头 :figclass: align-center -.. only:: esp32s2 or esp32s3 +.. only:: esp32s2 or esp32s3 or esp32h4 .. note:: @@ -406,7 +406,7 @@ single-buffer 方案通过使用专用 buffer 临时存储接收到的写入数 .. note:: - ESP32-S2 在 MSC 设备模式下不支持 SD 卡功能。 + {IDF_TARGET_NAME} 在 MSC 设备模式下不支持 SD 卡功能。 **SPI flash 性能：** @@ -423,6 +423,27 @@ single-buffer 方案通过使用专用 buffer 临时存储接收到的写入数 * - 8192 B - 21.54 KB/s +.. only:: esp32h4 + + .. note:: + + {IDF_TARGET_NAME} 不支持在 MSC 设备模式下使用 SD 卡。 + + **SPI Flash 性能：** + + .. list-table:: + :header-rows: 1 + :widths: 20 20 + + * - FIFO 大小 + - 写入速度 + + * - 512 B + - 4.48 KB/s + + * - 8192 B + - 22.33 KB/s + 性能限制： - **内部 SPI flash 性能** 受架构限制影响。程序执行和存储访问共享同一 flash 芯片，导致写入 flash 时必须暂停程序执行，会显著影响性能。 @@ -444,6 +465,6 @@ single-buffer 方案通过使用专用 buffer 临时存储接收到的写入数 - :example:`peripherals/usb/device/tusb_msc` 演示了如何使用 USB 功能创建一个可以被 USB 主机识别的大容量存储设备，允许访问其内部数据存储，支持 SPI Flash 和 SD MMC 卡存储介质。 - :example:`peripherals/usb/device/tusb_composite_msc_serialdevice` 演示了如何使用 TinyUSB 组件将 {IDF_TARGET_NAME} 同时配置为 USB 串行设备和 MSC 设备（存储介质为 SPI-Flash）运行。 -.. only:: not esp32p4 +.. only:: not esp32p4 and not esp32h4 - :example:`peripherals/usb/device/tusb_ncm` 演示了使用 TinyUSB 组件，借助网络控制模型 (NCM) 将 Wi-Fi 数据通过 USB 传输到 Linux 或 Windows 主机。NCM 是通信设备类 (CDC) USB 设备的一个子类，专用于 Ethernet-over-USB 应用。 diff --git a/docs/zh_CN/api-reference/peripherals/usb_host.rst b/docs/zh_CN/api-reference/peripherals/usb_host.rst index f83000d2c0e..40a192b4afc 100644 --- a/docs/zh_CN/api-reference/peripherals/usb_host.rst +++ b/docs/zh_CN/api-reference/peripherals/usb_host.rst @@ -29,7 +29,7 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供 .. list:: - :esp32s2 or esp32s3: - 支持全速 (FS) 和低速 (LS) 设备。 + :esp32s2 or esp32s3 or esp32h4: - 支持全速 (FS) 和低速 (LS) 设备。 :esp32p4: - 支持高速 (HS)、全速 (FS) 和低速 (LS) 设备。 - 支持四种传输类型，即控制传输、块传输、中断传输和同步传输。 :esp32p4: - 支持高带宽等时性端点。 diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst index a3f5d922786..63d2b3d272f 100644 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst +++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst @@ -116,7 +116,7 @@ DWC_OTG IP 是可配置的。有关 {IDF_TARGET_NAME} 的 DWC_OTG 的重要主 * - 每个微帧仅支持 4 个周期性和 4 个非周期性事务 - ``OTG_NPERIO_TX_QUEUE_DEPTH = 4``、``OTG_PERIO_TX_QUEUE_DEPTH = 4`` -.. only:: esp32s2 or esp32s3 +.. only:: esp32s2 or esp32s3 or esp32h4 .. list-table:: {IDF_TARGET_NAME} 的 DWC_OTG 配置 :widths: 70 30