From 0de6267eebffc5645fcf886d9a42e381bb1d9bab Mon Sep 17 00:00:00 2001 From: Roman Leonov Date: Thu, 23 May 2024 13:13:13 +0200 Subject: [PATCH] docs(enum): Added description for Enumeration process (Enum Driver) --- docs/_static/usb_host/stack-overview.png | Bin 23571 -> 19318 bytes docs/conf_common.py | 3 +- docs/docs_not_updated/esp32c5.txt | 1 + docs/docs_not_updated/esp32p4.txt | 1 + .../usb_host/usb_host_notes_enum.rst | 119 ++++++++++++++++++ .../usb_host/usb_host_notes_index.rst | 1 + .../usb_host/usb_host_notes_enum.rst | 1 + .../usb_host/usb_host_notes_index.rst | 1 + 8 files changed, 126 insertions(+), 1 deletion(-) create mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_enum.rst create mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst diff --git a/docs/_static/usb_host/stack-overview.png b/docs/_static/usb_host/stack-overview.png index 0558d8388b1604e91a1098996c4a688eaa56560c..40996041de17cf705c4bad02cf2c4e837235a290 100644 GIT binary patch literal 19318 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 literal 23571 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 w7)>S=H@3%9@Z!Y)Ls!=geM+MW&7&WikB41`_ > Chapter 9.1.2 **Bus Enumeration**. + +Host Stack Requirements +^^^^^^^^^^^^^^^^^^^^^^^ + +In addition to the USB 2.0 specification requirements, the Enum Driver also takes into consideration the requirements set for the overall Host Stack (see :doc:`./usb_host_notes_design`): + +- Enum Driver must not instantiate any tasks/threads +- Enum Driver must be event driven, providing event callbacks and an event processing function +- Enum Driver must use only API from underlying layer (USBH) + +Implementation & Usage +---------------------- + +Host Stack Interaction +^^^^^^^^^^^^^^^^^^^^^^ + +The Enum Driver takes place between USB Host layer and USBH layer with a possibility to select configuration with ``enum_config_t.enum_event_cb`` callback provided on Enum Driver installation. + +Events & Processing +^^^^^^^^^^^^^^^^^^^ + +The Enum Driver is completely event driven and all event handling is done via the ``enum_process()`` function. The ``enum_config_t.proc_req_cb`` callback provided on Enum Driver installation will be called when processing is required. Typically, ``enum_process()`` will be called from a shared USB Host stack thread/task. + +The Enum Driver exposes the following event callbacks: + +- ``enum_event_cb_t`` used to indicate various events regarding an enumeration process. This callback is called from the context of ``enum_process()`` + +The Enum Driver exposes the following events: + +- ``ENUM_EVENT_STARTED`` Enumeration process has been started +- ``ENUM_EVENT_RESET_REQUIRED`` Enumeration process requires device reset +- ``ENUM_EVENT_COMPLETED`` Enumeration process has been completed +- ``ENUM_EVENT_CANCELED`` Enumeration process has been canceled (due to internal error or via ``enum_cancel()`` function call) + +Device Enumeration +^^^^^^^^^^^^^^^^^^ + +The USB device enumeration process implemented in the Enum Driver is mostly based same process in the `Windows USB stack `__. The Enum Driver's enumeration process involves the following steps: + +#. First device descriptor request (to obtain the MPS of EP0) +#. Second device reset (to workaround some non-compliant devices) +#. Set device address +#. Second device descriptor request (to obtain and store the full device descriptor) +#. Configuration descriptor request (to obtain the full configuration descriptor of selected configuration) +#. Language ID Table request (checks to see if en-US is supported) +#. Manufacturer string descriptor request +#. Product string descriptor request +#. Serial number string descriptor request +#. Set configuration request (sets the device to target configuration number) + +.. note:: + + String descriptors are optional. If a device does not support string descriptors, these stages could be omitted. + +Enumeration Stages +^^^^^^^^^^^^^^^^^^ + +The Enum Driver splits the enumeration process into multiple stages which are executed linearly. Depending on the connected device, some stages (such as fetching the string descriptors) can be skipped. When a stage completes, a call to the ``enum_config_t.proc_req_cb`` callback must be made to trigger a subsequent call of ``enum_process()``.The subsequent call of ``enum_process()`` will then select and execute the next stage of enumeration. Stage completion can trigger the ``enum_config_t.proc_req_cb`` callback in one of the following ways: + +- Inside the control transfer completion callback (for stages that send a control transfer) +- Direct call to ``enum_config_t.proc_req_cb`` (for stages that don't need to wait for any event) +- Inside ``enum_proceed()`` (for stages that require some action to be carried out outside the Enum Driver) + +Any control transfer made during enumeration is split into two stages, where the first stage executes the transfer and the second stage (suffixed with ``_CHECK``) will check the results of the transfers. + +When requesting a variable length descriptors (e.g., configuration or string descriptors), the request is split into two control transfers. The first control transfer is fixed in length which only reads the header of the descriptor. The ``bLength`` field of the descriptor's header indicates the full length of the entire descriptor and is used to set the size of the second transfer which fetches the entire descriptor. As a result, any request for a variable length descriptor is split into four stages: + +- Get short **ANY** descriptor (prefixed with ``GET_SHORT_...``) +- Check short **ANY** descriptor (prefixed with ``CHECK_SHORT_...``) +- Get full **ANY** descriptor (prefixed with ``GET_FULL_...``) +- Check full **ANY** descriptor (prefixed with ``CHECK_FULL_...``) + +.. note:: + + Retrieving the Device Descriptor is an exception here because the second reset is taken place after retrieving short Device Descriptor. + +Cancel Enumeration +^^^^^^^^^^^^^^^^^^ + +In some cases (such as a device disconnection), an ongoing enumeration process may need to be cancelled. An ongoing enumeration can be cancelled (regardless of its current stage) by calling ``enum_cancel()`` which will change the enumeration process's current stage to ``ENUM_STAGE_CANCEL``. + +On the next call to ``enum_process``, the Enum Driver will execute the ``ENUM_STAGE_CANCEL`` which does the following: + +- releases the device's enumeration lock. +- frees all resources related to the current device. +- propagates the ``ENUM_EVENT_CANCELED`` event. diff --git 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 index 2d23befb42..6b1c6fa9ac 100644 --- 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 @@ -22,6 +22,7 @@ This document is split into the following sections: usb_host_notes_arch usb_host_notes_dwc_otg usb_host_notes_usbh + usb_host_notes_enum Todo: diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst new file mode 100644 index 0000000000..3e4a5dd75b --- /dev/null +++ b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst @@ -0,0 +1 @@ +.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_enum.rst diff --git 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 index 1ab83954de..c6318a690a 100644 --- 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 @@ -22,6 +22,7 @@ USB 主机维护者注意事项(简介) usb_host_notes_arch usb_host_notes_dwc_otg usb_host_notes_usbh + usb_host_notes_enum 待写章节: