doc: update tinyusb document to support esp32s3

1. Renamed SOC_USB_SUPPORTED to SOC_USB_OTG_SUPPORTED for the reason of another USB related peripheral: USB_JTAG_SERIAL 2. correct related document
2024-10-05 20:47:46 -04:00 · 2021-06-30 16:04:37 +08:00 · 2021-06-30 16:04:37 +08:00 · 2218204aa7
commit 2218204aa7
parent 42f3bca5a1
14 changed files with 26 additions and 19 deletions
--- a/components/soc/esp32s2/include/soc/soc_caps.h
+++ b/components/soc/esp32s2/include/soc/soc_caps.h
@ -44,7 +44,7 @@
 #define SOC_DEDICATED_GPIO_SUPPORTED    1
 #define SOC_SUPPORTS_SECURE_DL_MODE     1
 #define SOC_RISCV_COPROC_SUPPORTED      1
-#define SOC_USB_SUPPORTED               1
+#define SOC_USB_OTG_SUPPORTED           1
 #define SOC_PCNT_SUPPORTED              1
 #define SOC_ULP_SUPPORTED               1
 #define SOC_RTC_SLOW_MEM_SUPPORTED      1
--- a/components/soc/esp32s3/include/soc/soc_caps.h
+++ b/components/soc/esp32s3/include/soc/soc_caps.h
@ -15,6 +15,7 @@
 #define SOC_CPU_CORES_NUM               2
 #define SOC_CACHE_SUPPORT_WRAP          1
 #define SOC_ULP_SUPPORTED               1
+#define SOC_USB_OTG_SUPPORTED           1
 #define SOC_RTC_SLOW_MEM_SUPPORTED      1
 #define SOC_CCOMP_TIMER_SUPPORTED       1
 #define SOC_DIG_SIGN_SUPPORTED          0
--- a/docs/_static/usb-board-connection.png
+++ b/docs/_static/usb-board-connection.png
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@ -164,7 +164,7 @@ LEGACY_DOCS = ['api-guides/build-system-legacy.rst',
               'api-guides/unit-tests-legacy.rst',
               'get-started-legacy/**']

-USB_DOCS = ['api-reference/peripherals/usb.rst',
+USB_DOCS = ['api-reference/peripherals/usb_device.rst',
            'api-guides/usb-otg-console.rst',
            'api-guides/dfu.rst']

@ -212,7 +212,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
                            'SOC_SDMMC_HOST_SUPPORTED':SDMMC_DOCS,
                            'SOC_SDIO_SLAVE_SUPPORTED':SDIO_SLAVE_DOCS,
                            'SOC_MCPWM_SUPPORTED':MCPWM_DOCS,
-                            'SOC_USB_SUPPORTED':USB_DOCS,
+                            'SOC_USB_OTG_SUPPORTED':USB_DOCS,
                            'SOC_USB_SERIAL_JTAG_SUPPORTED':USB_SERIAL_JTAG_DOCS,
                            'SOC_DEDICATED_GPIO_SUPPORTED':DEDIC_GPIO_DOCS,
                            'SOC_SPIRAM_SUPPORTED':SPIRAM_DOCS,
--- a/docs/en/api-guides/index.rst
+++ b/docs/en/api-guides/index.rst
@ -12,7 +12,7 @@ API Guides
    Build System <build-system>
    :esp32: Build System (Legacy GNU Make) <build-system-legacy>
    Deep Sleep Wake Stubs <deep-sleep-stub>
-    :SOC_USB_SUPPORTED: Device Firmware Upgrade through USB <dfu>
+    :SOC_USB_OTG_SUPPORTED: Device Firmware Upgrade through USB <dfu>
    Error Handling <error-handling>
    :SOC_BT_SUPPORTED: ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
    ESP-WIFI-MESH <esp-wifi-mesh>
@ -41,6 +41,6 @@ API Guides
    Unit Testing (Target) <unit-tests>
    Unit Testing (Linux Host) <linux-host-testing>
    :esp32: Unit Testing (Legacy GNU Make) <unit-tests-legacy>
-    :SOC_USB_SUPPORTED: USB OTG Console <usb-otg-console>
+    :SOC_USB_OTG_SUPPORTED: USB OTG Console <usb-otg-console>
    :SOC_USB_SERIAL_JTAG_SUPPORTED: USB Serial/JTAG Controller Console <usb-serial-jtag-console>
    WiFi Driver <wifi>
--- a/docs/en/api-guides/performance/speed.rst
+++ b/docs/en/api-guides/performance/speed.rst
@ -91,8 +91,8 @@ Although standard output is buffered, it's possible for an application to be lim
 .. list::

    - Reduce the volume of log output by lowering the app :ref:`CONFIG_LOG_DEFAULT_LEVEL` (the equivalent bootloader setting is :ref:`CONFIG_BOOTLOADER_LOG_LEVEL`). This also reduces the binary size, and saves some CPU time spent on string formatting.
-    :not SOC_USB_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`
-    :SOC_USB_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`. (Unless using internal USB-CDC for serial console, in which case the serial throughput doesn't depend on the configured baud rate.)
+    :not SOC_USB_OTG_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`
+    :SOC_USB_OTG_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`. (Unless using internal USB-CDC for serial console, in which case the serial throughput doesn't depend on the configured baud rate.)

 Not Recommended
 ^^^^^^^^^^^^^^^
--- a/docs/en/api-reference/peripherals/index.rst
+++ b/docs/en/api-reference/peripherals/index.rst
@ -33,6 +33,6 @@ Peripherals API
    :esp32s2: Touch Element <touch_element>
    TWAI <twai>
    UART <uart>
-    :SOC_USB_SUPPORTED: USB <usb>
+    :SOC_USB_OTG_SUPPORTED: USB Device <usb_device>

 Code examples for this API section are provided in the :example:`peripherals` directory of ESP-IDF examples.
--- a/docs/en/api-reference/peripherals/usb_device.rst
+++ b/docs/en/api-reference/peripherals/usb_device.rst
@ -1,6 +1,9 @@

-USB Driver
-==========
+USB Device Driver
+=================
+
+{IDF_TARGET_USB_DP_GPIO_NUM:default="20"}
+{IDF_TARGET_USB_DM_GPIO_NUM:default="19"}

 Overview
 --------
@ -21,12 +24,14 @@ Hardware USB Connection

 - Any board with the {IDF_TARGET_NAME} chip with USB connectors or with exposed USB's D+ and D- (DATA+/DATA-) pins.

-If the board has no USB connector but has the pins, connect pins directly to the host (e.g. with do-it-yourself cable from any USB connection cable). For example, connect GPIO19/20 to D-/D+ respectively for an ESP32-S2 board:
+If the board has no USB connector but has the pins, connect pins directly to the host (e.g. with do-it-yourself cable from any USB connection cable).
+
+On {IDF_TARGET_NAME}, connect GPIO {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_USB_DM_GPIO_NUM} to D+/D- respectively:


 .. figure:: ../../../_static/usb-board-connection.png
    :align: center
-    :alt: Connection of a board to a host ESP32-S2
+    :alt: Connection of a board to a host ESP chip
    :figclass: align-center

 Driver Structure
--- a/docs/en/api-reference/system/freertos_additions.rst
+++ b/docs/en/api-reference/system/freertos_additions.rst
@ -25,8 +25,8 @@ Ring Buffers
 The ESP-IDF FreeRTOS ring buffer is a strictly FIFO buffer that supports arbitrarily sized items.
 Ring buffers are a more memory efficient alternative to FreeRTOS queues in situations where the
 size of items is variable. The capacity of a ring buffer is not measured by the number of items
-it can store, but rather by the amount of memory used for storing items. The ring buffer provides API 
-to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. 
+it can store, but rather by the amount of memory used for storing items. The ring buffer provides API
+to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user.
 For efficiency reasons,
 **items are always retrieved from the ring buffer by reference**. As a result, all retrieved
 items *must also be returned* to the ring buffer by using :cpp:func:`vRingbufferReturnItem` or :cpp:func:`vRingbufferReturnItemFromISR`, in order for them to be removed from the ring buffer completely.
@ -531,6 +531,6 @@ Hooks API Reference
 Component Specific Properties
 -----------------------------

-Besides standart component variables that could be gotten with basic cmake build properties FreeRTOS component also provides an arguments (only one so far) for simpler integration with other modules:
+Besides standard component variables that could be gotten with basic cmake build properties FreeRTOS component also provides an arguments (only one so far) for simpler integration with other modules:

 - `ORIG_INCLUDE_PATH` -  contains an absolute path to freertos root include folder. Thus instead of `#include "freertos/FreeRTOS.h"` you can refer to headers directly: `#include "FreeRTOS.h"`.
--- a/docs/page_redirects.txt
+++ b/docs/page_redirects.txt
@ -16,6 +16,7 @@ api-reference/ethernet/esp_eth                  api-reference/network/esp_eth
 api-reference/mesh/index                        api-reference/network/index
 api-reference/mesh/esp_mesh                     api-reference/network/esp_mesh
 api-reference/peripherals/can                   api-reference/peripherals/twai
+api-reference/peripherals/usb                   api-reference/peripherals/usb_device
 api-reference/wifi/index                        api-reference/network/index
 api-reference/wifi/esp_now                      api-reference/network/esp_now
 api-reference/wifi/esp_smartconfig              api-reference/network/esp_smartconfig
--- a/docs/zh_CN/api-guides/index.rst
+++ b/docs/zh_CN/api-guides/index.rst
@ -12,7 +12,7 @@ API 指南
   构建系统 <build-system>
   :esp32: 构建系统 (传统 GNU Make) <build-system-legacy>
   深度睡眠唤醒存根 <deep-sleep-stub>
-   :esp32s2: 通过 USB 升级设备固件 <dfu>
+   :SOC_USB_OTG_SUPPORTED: 通过 USB 升级设备固件 <dfu>
   错误处理 <error-handling>
   :SOC_BT_SUPPORTED: ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
   ESP-WIFI-MESH <esp-wifi-mesh>
@ -41,6 +41,6 @@ API 指南
   单元测试 (Target) <unit-tests>
   单元测试 (Linux Host) <linux-host-testing>
   :esp32: 单元测试 (传统 GNU Make) <unit-tests-legacy>
-   :SOC_USB_SUPPORTED: USB 控制台 <usb-otg-console>
+   :SOC_USB_OTG_SUPPORTED: USB 控制台 <usb-otg-console>
   :SOC_USB_SERIAL_JTAG_SUPPORTED: USB Serial/JTAG Controller Console <usb-serial-jtag-console>
   Wi-Fi 驱动 <wifi>
--- a/docs/zh_CN/api-reference/peripherals/index.rst
+++ b/docs/zh_CN/api-reference/peripherals/index.rst
@ -33,6 +33,6 @@
    :esp32s2: Touch Element <touch_element>
    TWAI <twai>
    UART <uart>
-    :SOC_USB_SUPPORTED: USB <usb>
+    :SOC_USB_OTG_SUPPORTED: USB Device <usb_device>

 本部分的 API 示例代码存放在 ESP-IDF 示例项目的 :example:`peripherals` 目录下。
--- a/docs/zh_CN/api-reference/peripherals/usb.rst
+++ b/docs/zh_CN/api-reference/peripherals/usb.rst
@ -1 +0,0 @@
-.. include:: ../../../en/api-reference/peripherals/usb.rst
--- a/docs/zh_CN/api-reference/peripherals/usb_device.rst
+++ b/docs/zh_CN/api-reference/peripherals/usb_device.rst
@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/peripherals/usb_device.rst
				`@ -1 +0,0 @@`
				`.. include:: ../../../en/api-reference/peripherals/usb.rst`
				`@ -0,0 +1 @@`
				`.. include:: ../../../en/api-reference/peripherals/usb_device.rst`