docs(ext_port): Maintainers Notes for the External Port Driver

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

@@ -25,18 +25,32 @@ 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)``.
+    - Allows single Hub support (If option :ref:`CONFIG_USB_HOST_HUBS_SUPPORTED` is enabled).
+    - Allows multiple Hubs support (If option :ref:`CONFIG_USB_HOST_HUB_MULTI_LEVEL` is enabled).
 
 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 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.
+    - The External Hub Driver: Supports only devices with the same speed as upstream port speed (e.g., Low-speed device won't work through Full-speed external Hub).
+    - The External Hub Driver: Remote Wakeup feature is not supported (External Hubs are active, even if there are no devices inserted).
+    - The External Hub Driver: Doesn't handle error cases (overcurrent handling, errors during initialization etc. are not implemented yet).
+    - The External Hub Driver: No Interface selection. The Driver uses the first available Interface with Hub Class code (09h).
+    - The External Port Driver: No downstream port debounce mechanism (not implemented yet)
+    :esp32p4: - The External Hub Driver: No Transaction Translator layer (No FS/LS Devices support when a Hub is attached to HS Host).
 
 
 .. -------------------------------------------------- Architecture -----------------------------------------------------
@@ -89,7 +103,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.
 
@@ -158,8 +172,8 @@ Lifecycle
 
 The graph above illustrates the typical lifecycle of the Host Library with multiple clients and devices. Specifically, the example involves:
 
-- two registered clients (Client 1 and Client 2).
-- two connected devices (Device 1 and Device 2), where Client 1 communicates with Device 1 and Client 2 communicates with Device 2.
+- Two registered clients (Client 1 and Client 2).
+- Two connected devices (Device 1 and Device 2), where Client 1 communicates with Device 1 and Client 2 communicates with Device 2.
 
 With reference to the graph above, the typical lifecycle involves the following key stages.
 
@@ -431,6 +445,44 @@ Configurable parameters of the USB host stack can be configured with multiple op
 * For reset recovery interval, refer to :ref:`CONFIG_USB_HOST_RESET_RECOVERY_MS`.
 * For ``SetAddress()`` recovery interval, refer to :ref:`CONFIG_USB_HOST_SET_ADDR_RECOVERY_MS`.
 
+Downstream Port Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When external Hubs feature is supported, there are several parameters which could be configured for the external Hubs port.
+
+Each external Hub has a Hub Descriptor which describes the device characteristics.
+
+.. note::
+
+    For detailed information about Hub Descriptor, please refer to `USB 2.0 Specification <https://www.usb.org/document-library/usb-20-specification>`_ > Chapter 11.23.2.1 *Hub Descriptor*.
+
+Configurable parameters of the downstream port can be configured with multiple options via Menuconfig.
+
+* For custom value to stabilize the power after powering on the port (PwrOn2PwrGood value), refer to :ref:`CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_MS`.
+* For reset recovery interval, refer to :ref:`CONFIG_USB_HOST_EXT_PORT_RESET_RECOVERY_DELAY_MS`.
+
+.. note::
+
+    The specification claims, that for a hub with no power switches, PwrOn2PwrGood must be set to zero. Meanwhile, for some devices, this value could be increased to give extra time for device to power-up. To enable this feature, refer to :ref:`CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_ENABLE`.
+
+Host Channels
+"""""""""""""
+
+When external Hubs support feature is enabled (:ref:`CONFIG_USB_HOST_HUBS_SUPPORTED`), the amount of Host channels plays important role, as each downstream device requires vacant channel.
+
+To handle each attached device, different amount of channels are required. This amount does depend on the device class (EPs number).
+
+Supported amount of channels for {IDF_TARGET_NAME} is {OTG_NUM_HOST_CHAN}.
+
+.. note::
+
+    - One free channel is required to enumerate the device.
+
+    - From 1 to N (when N - number of EPs) free channels are required to claim the interface.
+
+    - When there are no more free Host channels available, the device could not be enumerated and its interface cannot be claimed.
+
+
 Multiple Configuration Support
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

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

@@ -0,0 +1,85 @@
+USB Host External Port Driver (Ext Port)
+========================================
+
+Introduction
+------------
+
+The External Port Driver (henceforth referred to as Ext Port Driver) isolates the handling process for downstream facing ports, which are provided by the Ext Hub Driver.
+
+.. note::
+
+    For more detailed information, please refer to `USB 2.0 Specification <https://www.usb.org/document-library/usb-20-specification>`_ > Chapter 11.5 **Downstream Facing Ports**.
+
+Requirements
+------------
+
+Host Stack Requirements
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The Ext Port Driver takes into consideration the requirements set for the overall Host Stack (see :doc:`./usb_host_notes_design`):
+
+- The Ext Port Driver must not instantiate any tasks/threads
+- The Ext Port Driver must be event driven, providing event callbacks and an event processing function
+- The Ext Port Driver must use only API from underlying layer (The Ext Hub Driver)
+
+Implementation & Usage
+----------------------
+
+Host Stack Interaction
+^^^^^^^^^^^^^^^^^^^^^^
+
+The Ext Port Driver is a part of The Ext Hub Driver, so the interaction and hierarchical place in USB Host Stack is the same as for the Ext Hub Driver. The Ext Hub and the Ext Port Drivers were split into two Drivers to achieve the goal of logic distinguishing between external Hubs and Downstream Facing Ports handling.
+
+Ports handling
+^^^^^^^^^^^^^^^
+
+The Ext Port Driver can be installed via ``ext_port_install()`` call and uninstalled via ``ext_port_uninstall()`` call.
+
+After installation, the Ext Port Driver API could be requested via ``ext_port_get_driver()`` call.
+
+The Ext Port Driver API
+-----------------------
+
+The Ext Port Driver provides an API, which could be split into three groups: object control, device control and general.
+
+The Ext Port Driver: Object Control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    - Create object
+    - Delete object
+
+The Ext Port Driver: Port Control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    - Reset
+    - Disable
+    - Recycle
+    - Activate
+    - Get Speed
+    - Get status
+    - Set status
+    - Gone
+
+The Ext Port Driver: General Purpose
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    - Request processing
+
+Events & Processing
+-------------------
+
+The Ext Port Driver is completely event driven and all event handling is done via the ``ext_port_process()`` function. The ``ext_port_driver_config_t.proc_req_cb`` callback provided on the Ext Port Driver installation will be called when processing is required. Typically, ``ext_port_process()`` will be called from the Hub Driver ``hub_process()`` processing function.
+
+The Ext Port Driver exposes the following events via ``ext_port_driver_config_t.event_cb``:
+
+- ``EXT_PORT_CONNECTED`` Downstream facing port has a device connection event
+- ``EXT_PORT_RESET_COMPLETED`` Downstream facing port has a device and completed the port reset
+- ``EXT_PORT_DISCONNECTED`` Downstream facing port has a device disconnection event
+
+The Ext Port Driver ports processing is based on the Hub class-specific request ``Get Port Status``.
+
+After successful completion of the class-specific request ``Get Port Status`` and setting the new port status, the Ext Port Driver continues the port handling while it is required by ports' state and status.
+
+.. note::
+
+    For more detailed information, please refer to `USB 2.0 Specification <https://www.usb.org/document-library/usb-20-specification>`_ > Chapter 11.24.2.7 **Get Port Status**

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

@@ -23,6 +23,7 @@ This document is split into the following sections:
     usb_host_notes_usbh
     usb_host_notes_enum
     usb_host_notes_ext_hub
+    usb_host_notes_ext_port
 
 Todo:
 
@@ -39,22 +40,3 @@ Introduction
 The ESP-IDF USB Host Stack allows the {IDF_TARGET_NAME} to operate as a USB Host. Operating as a USB Host allows the {IDF_TARGET_NAME} to communicate with a wide range of USB devices. However, most USB Host Stack implementations do not run on embedded hardware (i.e., runs on PCs and smartphones), thus have comparatively more resources (i.e., memory and CPU speed).
 
 The implementation of the ESP-IDF USB Host Stack (henceforth referred to as the Host Stack) takes into account the embedded nature of the {IDF_TARGET_NAME} which is reflected in various aspects of the Host Stack's design.
-
-Features & Limitations
-^^^^^^^^^^^^^^^^^^^^^^
-
-**The Host Stack currently supports the following notable features:**
-
-.. only:: esp32p4
-
-    - Supports HS (High Speed)
-
-- Supports FS (Full Speed) and LS (Low Speed) devices
-- Supports all transfer types (Control, Bulk, Isochronous, and Interrupt)
-- Automatically enumerates connected devices
-- Allows multiple class drivers (i.e., Clients of the USB Host Library) to run simultaneously and share the same device (i.e., composite devices).
-
-**The Host Stack currently has the following notable limitations:**
-
-- No Hub support (currently only supports a single device)
-