Merge branch 'docs/usb_maintainer_docs_p4' into 'master'

docs(usb/host): Update maintainer docs for ESP32-P4 See merge request espressif/esp-idf!32831
2024-09-19 14:26:01 -04:00 · 2024-08-22 22:21:31 +08:00 · 2024-08-22 22:21:31 +08:00 · 73e0948332
commit 73e0948332
parent d27cf6d00c 512df697f0
6 changed files with 91 additions and 48 deletions
--- a/components/soc/esp32p4/include/soc/usb_dwc_cfg.h
+++ b/components/soc/esp32p4/include/soc/usb_dwc_cfg.h
@ -17,7 +17,7 @@ Configuration Set ID: 11
 /* 3.1 Basic Config Parameters */
 #define OTG_MODE                0
 #define OTG_ARCHITECTURE        2
-#define OTG_SINGLE_POINT        0
+#define OTG_SINGLE_POINT        1
 #define OTG_ENABLE_LPM          0
 #define OTG_EN_DED_TX_FIFO      1
 #define OTG_EN_DESC_DMA         1
--- a/docs/docs_not_updated/esp32p4.txt
+++ b/docs/docs_not_updated/esp32p4.txt
@ -9,13 +9,6 @@ api-guides/wifi-security.rst
 api-reference/peripherals/adc_continuous.rst
 api-reference/peripherals/adc_oneshot.rst
 api-reference/peripherals/usb_host.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_dwc_otg.rst
-api-reference/peripherals/usb_host/usb_host_notes_design.rst
-api-reference/peripherals/usb_host/usb_host_notes_usbh.rst
-api-reference/peripherals/usb_host/usb_host_notes_enum.rst
-api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst
 api-reference/peripherals/usb_device.rst
 api-reference/peripherals/touch_element.rst
 api-reference/peripherals/touch_pad.rst
--- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_arch.rst
+++ b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_arch.rst
@ -39,7 +39,7 @@ The layers of the Host Stack are described in the following table. The layers ar
      - ``usb_host.h``, ``usb_host.c``
      - The USB Host Library layer is the lowest public API layer of the Host Stack and presents the concept of USB Host Clients. The abstraction of clients allows for multiple class drivers to coexist simultaneously (where each class roughly maps to a single client) and also acts as a mechanism for division of labor (where each client is responsible for its own processing and event handling).
    * - Host Class Drivers
-      - See the `ESP-IDF Extra Components repository <https://github.com/espressif/idf-extra-components>`_ or the USB Host examples in ESP-IDF (via :example:`peripherals/usb/host`).
+      - See the `ESP-USB repository <https://github.com/espressif/esp-usb>`_ or the USB Host examples in ESP-IDF (via :example:`peripherals/usb/host`).
      - The Host Class Drivers implement the host side of a particular device class (e.g., CDC, MSC, HID). The exposed API is specific to each class driver.

 Layer Dependencies
--- 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
@ -91,26 +91,51 @@ Hardware Configuration

 The DWC_OTG IP is configurable. The notable host related configurations of the {IDF_TARGET_NAME}'s DWC_OTG are listed below:

-.. list-table:: {IDF_TARGET_NAME}'s DWC_OTG Configuration
-    :widths: 70 30
-    :header-rows: 1
+.. only:: esp32p4

-    * - Description
-      - Configuration
-    * - Host and Device Mode support with OTG
-      - ``OTG_MODE = 0``
-    * - Full Speed (FS) and Low Speed (LS) support
-      - ``OTG_FSPHY_INTERFACE = 1``, ``OTG_HSPHY_INTERFACE = 0``
-    * - Internal DMA controller with Scatter/Gather DMA
-      - ``OTG_ARCHITECTURE = 2``, ``OTG_EN_DESC_DMA = 1``
-    * - FS Hubs are supported but HS Hub are not (i.e., split transfers not supported)
-      - ``OTG_SINGLE_POINT = 0``
-    * - 8 Host Mode channels
-      - ``OTG_NUM_HOST_CHAN = 8``
-    * - All transfer types supported, including ISOC and INTR OUT transfers
-      - ``OTG_EN_PERIO_HOST = 1``
-    * - Dynamically sized Data FIFO of 1024 bytes (256 lines)
-      - ``OTG_DFIFO_DYNAMIC = 1``, ``OTG_DFIFO_DEPTH = 256``
+    .. list-table:: {IDF_TARGET_NAME}'s DWC_OTG Configuration
+        :widths: 70 30
+        :header-rows: 1
+
+        * - Description
+          - Configuration
+        * - Host and Device Mode support with OTG
+          - ``OTG_MODE = 0``
+        * - High Speed (HS), Full Speed (FS) and Low Speed (LS) support
+          - ``OTG_FSPHY_INTERFACE = 2``, ``OTG_HSPHY_INTERFACE = 3``
+        * - Internal DMA controller with Scatter/Gather DMA
+          - ``OTG_ARCHITECTURE = 2``, ``OTG_EN_DESC_DMA = 1``
+        * - Split transfers not supported
+          - ``OTG_SINGLE_POINT = 1``
+        * - 16 Host Mode channels
+          - ``OTG_NUM_HOST_CHAN = 16``
+        * - All transfer types supported, including ISOC and INTR OUT transfers
+          - ``OTG_EN_PERIO_HOST = 1``
+        * - Dynamically sized Data FIFO of 4096 bytes (1024 lines)
+          - ``OTG_DFIFO_DYNAMIC = 1``, ``OTG_DFIFO_DEPTH = 1024``
+        * - 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
+
+    .. list-table:: {IDF_TARGET_NAME}'s DWC_OTG Configuration
+        :widths: 70 30
+        :header-rows: 1
+
+        * - Description
+          - Configuration
+        * - Host and Device Mode support with OTG
+          - ``OTG_MODE = 0``
+        * - Full Speed (FS) and Low Speed (LS) support
+          - ``OTG_FSPHY_INTERFACE = 1``, ``OTG_HSPHY_INTERFACE = 0``
+        * - Internal DMA controller with Scatter/Gather DMA
+          - ``OTG_ARCHITECTURE = 2``, ``OTG_EN_DESC_DMA = 1``
+        * - 8 Host Mode channels
+          - ``OTG_NUM_HOST_CHAN = 8``
+        * - All transfer types supported, including ISOC and INTR OUT transfers
+          - ``OTG_EN_PERIO_HOST = 1``
+        * - Dynamically sized Data FIFO of 1024 bytes (256 lines)
+          - ``OTG_DFIFO_DYNAMIC = 1``, ``OTG_DFIFO_DEPTH = 256``

 Scatter/Gather DMA Transfer
 ---------------------------
--- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_arch.rst
+++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_arch.rst
@ -39,7 +39,7 @@ USB 主机维护者注释（架构）
      - ``usb_host.h``， ``usb_host.c``
      - USB 主机库层是主机协议栈的最低公共 API 层，并呈现 USB 主机客户端的概念。客户端的抽象允许多个 class 驱动程序同时存在（其中每个类大致映射到一个单独的客户端），这也是一种分工机制（其中每个客户端负责各自的处理以及事件处理）。
    * - 主机 Class 驱动程序
-      - 请参阅 `ESP-IDF 额外组件存储库 <https://github.com/espressif/idf-extra-components>`_ 或是 ESP-IDF 中的 USB 主机示例 :example:`peripherals/usb/host`。
+      - 请参阅 `ESP-USB 存储库 <https://github.com/espressif/esp-usb>`_ 或是 ESP-IDF 中的 USB 主机示例 :example:`peripherals/usb/host`。
      - 主机 Class 驱动程序能实现特定设备类（例如，CDC、MSC、HID）的主机端。每个 class 驱动程序具有特定的公开 API 接口。

 层依赖关系
--- 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
@ -91,26 +91,51 @@ DMA 引擎负责在 FIFO 和主内存之间复制数据。启用主机模式分

 DWC_OTG IP 是可配置的。有关 {IDF_TARGET_NAME} 的 DWC_OTG 的重要主机配置，请参阅下表：

-.. list-table:: {IDF_TARGET_NAME} 的 DWC_OTG 配置
-    :widths: 70 30
-    :header-rows: 1
+.. only:: esp32p4

-    * - 描述
-      - 配置
-    * - 支持 OTG 的主机和设备模式
-      - ``OTG_MODE = 0``
-    * - 支持全速 (FS) 和低速 (LS)
-      - ``OTG_FSPHY_INTERFACE = 1``、``OTG_HSPHY_INTERFACE = 0``
-    * - 支持分散/聚集式 DMA 功能的内部 DMA 控制器
-      - ``OTG_ARCHITECTURE = 2``、 ``OTG_EN_DESC_DMA = 1``
-    * - 支持 FS 集线器但不支持 HS 集线器（即，不支持分割传输）
-      - ``OTG_SINGLE_POINT = 0``
-    * - 8 个主机模式通道
-      - ``OTG_NUM_HOST_CHAN = 8``
-    * - 支持包括 ISOC 和 INTR OUT 传输在内的所有传输类型
-      - ``OTG_EN_PERIO_HOST = 1``
-    * - 动态大小的 1024 字节（256 行）数据 FIFO
-      - ``OTG_DFIFO_DYNAMIC = 1``、``OTG_DFIFO_DEPTH = 256``
+    .. list-table:: {IDF_TARGET_NAME} 的 DWC_OTG 配置
+        :widths: 70 30
+        :header-rows: 1
+
+        * - 描述
+          - 配置
+        * - 支持 OTG 的主机和设备模式
+          - ``OTG_MODE = 0``
+        * - 支持高速 (HS)、全速 (FS) 和低速 (LS)
+          - ``OTG_FSPHY_INTERFACE = 2``、``OTG_HSPHY_INTERFACE = 3``
+        * - 支持分散/聚集式 DMA 功能的内部 DMA 控制器
+          - ``OTG_ARCHITECTURE = 2``、 ``OTG_EN_DESC_DMA = 1``
+        * - 不支持分割传输
+          - ``OTG_SINGLE_POINT = 1``
+        * - 16 个主机模式通道
+          - ``OTG_NUM_HOST_CHAN = 16``
+        * - 支持包括 ISOC 和 INTR OUT 传输在内的所有传输类型
+          - ``OTG_EN_PERIO_HOST = 1``
+        * - 动态大小的 4096 字节（1024 行）数据 FIFO
+          - ``OTG_DFIFO_DYNAMIC = 1``、``OTG_DFIFO_DEPTH = 1024``
+        * - 每个微帧仅支持 4 个周期性和 4 个非周期性事务
+          - ``OTG_NPERIO_TX_QUEUE_DEPTH = 4``、``OTG_PERIO_TX_QUEUE_DEPTH = 4``
+
+.. only:: esp32s2 or esp32s3
+
+    .. list-table:: {IDF_TARGET_NAME} 的 DWC_OTG 配置
+        :widths: 70 30
+        :header-rows: 1
+
+        * - 描述
+          - 配置
+        * - 支持 OTG 的主机和设备模式
+          - ``OTG_MODE = 0``
+        * - 支持全速 (FS) 和低速 (LS)
+          - ``OTG_FSPHY_INTERFACE = 1``、``OTG_HSPHY_INTERFACE = 0``
+        * - 支持分散/聚集式 DMA 功能的内部 DMA 控制器
+          - ``OTG_ARCHITECTURE = 2``、 ``OTG_EN_DESC_DMA = 1``
+        * - 8 个主机模式通道
+          - ``OTG_NUM_HOST_CHAN = 8``
+        * - 支持包括 ISOC 和 INTR OUT 传输在内的所有传输类型
+          - ``OTG_EN_PERIO_HOST = 1``
+        * - 动态大小的 1024 字节（256 行）数据 FIFO
+          - ``OTG_DFIFO_DYNAMIC = 1``, ``OTG_DFIFO_DEPTH = 256``

 分散/聚集式 DMA 传输
 ---------------------