docs(ext_hub): Added description for External Hub Driver

2024-09-19 14:26:01 -04:00 · 2024-05-23 13:13:13 +02:00 · 2024-05-23 13:13:13 +02:00 · 5527ee588e
commit 5527ee588e
parent 548b03c69f
7 changed files with 76 additions and 58 deletions
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@ -117,7 +117,8 @@ USB_DOCS = ['api-reference/peripherals/usb_device.rst',
            'api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst',
            'api-reference/peripherals/usb_host/usb_host_notes_index.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_enum.rst',
+            'api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst']

 I80_LCD_DOCS = ['api-reference/peripherals/lcd/i80_lcd.rst']
 RGB_LCD_DOCS = ['api-reference/peripherals/lcd/rgb_lcd.rst']
--- a/docs/docs_not_updated/esp32c5.txt
+++ b/docs/docs_not_updated/esp32c5.txt
@ -86,6 +86,7 @@ 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/sdspi_host.rst
 api-reference/peripherals/spi_slave.rst
--- a/docs/docs_not_updated/esp32p4.txt
+++ b/docs/docs_not_updated/esp32p4.txt
@ -18,6 +18,7 @@ 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/spi_flash/xip_from_psram.inc
--- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst
+++ b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst
@ -0,0 +1,65 @@
+USB Host External Hub Driver (Ext Hub)
+======================================
+
+Introduction
+------------
+
+The External Hub Driver (henceforth referred to as Ext Hub Driver)
+
+Requirements
+------------
+
+USB Specification Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Chapter 11 of the USB 2.0 specification outlines some aspects, when a USB Hub device is attached to a powered port.
+
+The design of the Ext Driver takes into consideration the following:
+
+- **Connectivity behavior**
+- **Power management**
+- **Device connect/disconnect detection**
+- **Bus fault detection and recovery**
+- **High-, full-, and low-speed device support**
+
+.. note::
+
+    For more detailed information, please refer to `USB 2.0 Specification <https://www.usb.org/document-library/usb-20-specification>`_ > Chapter 11.1 **Overview**.
+
+Host Stack Requirements
+^^^^^^^^^^^^^^^^^^^^^^^
+
+In addition to the USB 2.0 specification requirements, the Ext Hub Driver also takes into consideration the requirements set for the overall Host Stack (see :doc:`./usb_host_notes_design`):
+
+- Ext Hub Driver must not instantiate any tasks/threads
+- Ext Hub Driver must be event driven, providing event callbacks and an event processing function
+- Ext Hub Driver must use only API from underlying layer (USBH)
+
+Implementation & Usage
+----------------------
+
+Host Stack Interaction
+^^^^^^^^^^^^^^^^^^^^^^
+
+The Ext Hub Driver takes place between USB Host layer and USBH layer, next to the Hub Driver. The Hub Driver and the Ext Hub Driver were split into two Drivers to achieve the goal of logic distinguishing between root Hub and external Hub.
+
+Device handling
+^^^^^^^^^^^^^^^
+
+The Ext Hub Driver can be installed via ``ext_hub_install()`` call and uninstalled via ``ext_hub_uninstall()`` call. After installation the Ext Hub provides the following APIs for external Hub addition and removal:
+
+- ``ext_hub_new_dev()`` which will verify the device class (`HUB_CLASSCODE (09H)`) and, if the device has the Hub class, the Ext Hub Driver:
+
+    - allocates a new device object
+    - adds it to the external device pool
+    - starts the process of Hub configuration (retrieving Hub Descriptor, Device status and Hub status)
+
+- ``ext_hub_dev_gone()`` which will verify the device in the Ext Hub Driver list and start the process of external Hub device removing.
+
+Events & Processing
+^^^^^^^^^^^^^^^^^^^
+
+The Ext Hub Driver is completely event driven and all event handling is done via the ``ext_hub_process()`` function. The ``ext_hub_config_t.proc_req_cb`` callback provided on the Ext Hub Driver installation will be called when processing is required. Typically, ``ext_hub_process()`` will be called from the Hub Driver ``hub_process()`` processing function.
+
+The Ext Hub Driver does not expose any event callback.
+
--- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst
+++ b/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_dwc_otg
    usb_host_notes_usbh
    usb_host_notes_enum
+    usb_host_notes_ext_hub

 Todo:

@ -45,6 +46,10 @@ 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
@ -52,5 +57,4 @@ Features & Limitations

 **The Host Stack currently has the following notable limitations:**

- No HS (High Speed) support
 - No Hub support (currently only supports a single device)
--- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst
+++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst
@ -0,0 +1 @@
+.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst
--- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst
+++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst
@ -1,56 +1 @@
-USB 主机维护者注意事项（简介）
-==============================
-
-:link_to_translation:`en:[English]`
-
-本文档包含有关 USB 主机协议栈实现细节的信息，面向 USB 主机协议栈的维护者和第三方贡献者。USB 主机协议栈的用户请参考 :doc:`../usb_host`。
-
-.. warning::
-
-    USB 主机协议栈的实现细节属于私有 API，因此，除 USB 主机库外的所有层均不遵循 :ref:`ESP-IDF 版本简介 <versioning-scheme>`，即允许进行重大更改。
-
-.. figure:: ../../../../_static/usb_host/stack-overview.png
-    :align: center
-    :alt: 主机协议栈层次结构图
-
-本文档分为以下几个部分：
-
-.. toctree::
-    :maxdepth: 1
-
-    usb_host_notes_design
-    usb_host_notes_arch
-    usb_host_notes_dwc_otg
-    usb_host_notes_usbh
-    usb_host_notes_enum
-
-待写章节：
-
- USB 主机维护者注意事项（HAL 和 LL）
- USB 主机维护者注意事项（HCD）
- USB 主机维护者注意事项（Hub）
- USB 主机维护者注意事项（USB Host Library）
-
-.. -------------------------------------------------- Introduction -----------------------------------------------------
-
-简介
----
-
-ESP-IDF USB 主机协议栈允许 {IDF_TARGET_NAME} 作为 USB 主机运行，此时，{IDF_TARGET_NAME} 能够与各种 USB 设备通信。然而，大多数 USB 主机协议栈实现都不运行在嵌入式硬件上（即在电脑和手机端运行），因此，相对来说具有更多的资源（即，具有更高内存和 CPU 速度）。
-
-ESP-IDF USB 主机协议栈（以下简称为主机协议栈）的实现考虑到了 {IDF_TARGET_NAME} 的嵌入式特性，这体现在主机协议栈设计的各个方面。
-
-特性和局限性
-^^^^^^^^^^^^
-
-**主机协议栈目前支持以下显著特性：**
-
- 支持 FS（全速）和 LS（低速）设备
- 支持所有传输类型（控制传输、批量传输、同步传输和中断传输）
- 自动枚举已连接设备
- 允许多个类驱动程序（即 USB 主机库的客户端）同时运行并共享同一设备（即组合设备）
-
-**主机协议栈目前存在以下显著局限：**
-
- 不支持 HS（高速）设备
- 不支持集线器（当前仅支持单个设备）
+.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_index.rst
				`@ -0,0 +1 @@`
				`.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst`