Merge branch 'docs/usb_docs_p4_backport_v5.3' into 'release/v5.3'

usb_host: P4 Docs and DMA fix backport to v5.3

See merge request espressif/esp-idf!33075

docs/en/api-reference/peripherals/usb_device.rst

@@ -5,9 +5,9 @@ USB Device Stack
 
 {IDF_TARGET_USB_DP_GPIO_NUM:default="20"}
 {IDF_TARGET_USB_DM_GPIO_NUM:default="19"}
-{IDF_TARGET_USB_EP_NUM:default="6"}
-{IDF_TARGET_USB_EP_NUM_INOUT:default="5"}
-{IDF_TARGET_USB_EP_NUM_IN:default="1"}
+{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"}
 
 Overview
 --------
@@ -34,16 +34,24 @@ Features
 Hardware Connection
 -------------------
 
-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).
+.. only:: esp32s2 or esp32s3
+
+    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).
+
+.. only:: esp32p4
+
+    The {IDF_TARGET_NAME} routes the USB D+ and D- signals to their dedicated pins. For USB device functionality, these pins 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).
 
 .. figure:: ../../../_static/usb-board-connection.png
     :align: center
     :alt: Connection of an USB GPIOs directly to a USB standard-A plug
     :figclass: align-center
 
-.. note::
+.. only:: esp32s2 or esp32s3
 
-    If you are using an {IDF_TARGET_NAME} development board with two USB ports, the port labeled "USB" will already be connected to the D+ and D- GPIOs.
+    .. note::
+
+        If you are using an {IDF_TARGET_NAME} development board with two USB ports, the port labeled "USB" will already be connected to the D+ and D- GPIOs.
 
 .. note::
 
@@ -95,15 +103,17 @@ Full-speed devices should initialize the following field to provide their config
 
 - :cpp:member:`configuration_descriptor`
 
-High-speed devices should initialize the following fields to provide configuration descriptors at each speed:
+.. only:: esp32p4
 
-- :cpp:member:`fs_configuration_descriptor`
-- :cpp:member:`hs_configuration_descriptor`
-- :cpp:member:`qualifier_descriptor`
+    High-speed devices should initialize the following fields to provide configuration descriptors at each speed:
 
-.. note::
+    - :cpp:member:`fs_configuration_descriptor`
+    - :cpp:member:`hs_configuration_descriptor`
+    - :cpp:member:`qualifier_descriptor`
 
-    When Device Stack supports high-speed, both :cpp:member:`fs_configuration_descriptor` and :cpp:member:`hs_configuration_descriptor` should be present to comply with usb2.0 specification.
+    .. note::
+
+        Both :cpp:member:`fs_configuration_descriptor` and :cpp:member:`hs_configuration_descriptor` must be present to comply with USB 2.0 specification.
 
 The Device Stack will instantiate a USB device based on the descriptors provided in the fields described above when :cpp:func:`tinyusb_driver_install` is called.
 

docs/en/api-reference/peripherals/usb_host.rst

@@ -25,18 +25,26 @@ Features & Limitations
 
 The Host Library has the following features:
 
-- Supports Full Speed (FS) and Low Speed (LS) Devices.
-- Supports all four transfer types, i.e., Control, Bulk, Interrupt, and Isochronous.
-- Allows multiple class drivers to run simultaneously, i.e., multiple clients of the Host Library.
-- A single device can be used by multiple clients simultaneously, e.g., composite devices.
-- The Host Library itself and the underlying Host Stack does not internally instantiate any OS tasks. The number of tasks is entirely controlled by how the Host Library interface is used. However, a general rule of thumb regarding the number of tasks is ``(the number of host class drivers running + 1)``.
+.. list::
+
+    :esp32s2 or esp32s3: - 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.
+    - Allows multiple class drivers to run simultaneously, i.e., multiple clients of the Host Library.
+    - A single device can be used by multiple clients simultaneously, e.g., composite devices.
+    - The Host Library itself and the underlying Host Stack does not internally instantiate any OS tasks. The number of tasks is entirely controlled by how the Host Library interface is used. However, a general rule of thumb regarding the number of tasks is ``(the number of host class drivers running + 1)``.
 
 Currently, the Host Library and the underlying Host Stack has the following limitations:
 
-- Only supports a single device, but the Host Library's API is designed for multiple device support.
-- Only supports Asynchronous transfers.
-- Only supports using the first configuration found. Changing to other configurations is not supported yet.
-- Transfer timeouts are not supported yet.
+.. list::
+
+    - Only supports a single device, but the Host Library's API is designed for multiple device support.
+    - Only supports Asynchronous transfers.
+    - Only supports using one configuration. Changing to other configurations after enumeration is not supported yet.
+    - Transfer timeouts are not supported yet.
+    :esp32p4: - {IDF_TARGET_NAME} contains two USB-OTG peripherals USB 2.0 OTG High-Speed and USB 2.0 OTG Full-Speed. Only the High-Speed instance is supported now.
+    :esp32p4: - {IDF_TARGET_NAME} cannot enumerate Low-Speed devices yet.
 
 
 .. -------------------------------------------------- Architecture -----------------------------------------------------
@@ -89,7 +97,7 @@ Therefore, in addition to the client tasks, the Host Library also requires a tas
 Devices
 ^^^^^^^
 
-The Host Library shields clients from the details of device handling, encompassing details such as connection, memory allocation, and enumeration. The clients are provided only with a list of already connected and enumerated devices to choose from. During enumeration, each device is automatically configured to use the first configuration found, namely, the first configuration descriptor returned on a Get Configuration Descriptor request. For most standard devices, the first configuration will have a ``bConfigurationValue`` of ``1``.
+The Host Library shields clients from the details of device handling, encompassing details such as connection, memory allocation, and enumeration. The clients are provided only with a list of already connected and enumerated devices to choose from. By default during enumeration, each device is automatically configured to use the first configuration found, namely, the first configuration descriptor returned on a Get Configuration Descriptor request. For most standard devices, the first configuration will have a ``bConfigurationValue`` of ``1``. If option  :ref:`CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` is enabled, a different ``bConfigurationValue`` can be selected, see `Multiple configuration Support`_ for more details.
 
 It is possible for two or more clients to simultaneously communicate with the same device as long as they are not communicating to the same interface. However, multiple clients can simultaneously communicate with the same device's default endpoint (i.e., EP0), which will result in their control transfers being serialized.
 

docs/en/api-reference/peripherals/usb_host/usb_host_notes_arch.rst

@@ -37,7 +37,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

docs/en/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst

@@ -89,26 +89,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
 ---------------------------