Merge branch 'docs/update_cn_trans_jtag_debugging_docs_4.4' into 'release/v4.4'

docs: update jtag_debugging docs and get-started-devkitc.rst (backport v4.4) See merge request espressif/esp-idf!17493
2024-10-05 20:47:46 -04:00 · 2022-04-20 16:21:04 +08:00 · 2022-04-20 16:21:04 +08:00 · 4b2098bc58
commit 4b2098bc58
parent 3d6f7f7fe0 cc054605a0
8 changed files with 214 additions and 122 deletions
--- a/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst
+++ b/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst
@ -3,19 +3,21 @@ Building OpenOCD from Sources for Windows
 *****************************************
 :link_to_translation:`zh_CN:[中文]`

-The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :ref:`jtag-debugging-setup-openocd`.
+.. note::

-.. highlight:: bash
+    This document outlines how to build a binary of OpenOCD from its source files instead of downloading the pre-built binary. For a quick setup, users can download a pre-built binary of OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_ instead of compiling it themselves (see :ref:`jtag-debugging-setup-openocd` for more details).

 .. note::

-    Following instructions are assumed to be runned in MSYS2 environment with MINGW32 subsystem!
+    All code snippets in this document are assumed to be running in an MSYS2 shell with the MINGW32 subsystem.


 Install Dependencies
 ====================

-Install packages that are required to compile OpenOCD::
+Install packages that are required to compile OpenOCD:
+
+.. code-block:: bash

    pacman -S --noconfirm --needed autoconf automake git make \
    mingw-w64-i686-gcc \
@ -29,31 +31,40 @@ Install packages that are required to compile OpenOCD::
 Download Sources of OpenOCD
 ===========================

-The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
+The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif's GitHub under https://github.com/espressif/openocd-esp32. These source files can be pulled via Git using the following commands:
+
+.. code-block:: bash

    cd ~/esp
    git clone --recursive https://github.com/espressif/openocd-esp32.git

-
 The clone of sources should be now saved in ``~/esp/openocd-esp32`` directory.


 Downloading libusb
 ==================

-Build and export variables for a following OpenOCD compilation::
+The libusb library is also required when building OpenOCD. The following commands will download a particular release of libusb and uncompress it to the current directory.
+
+.. code-block:: bash

    wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z
    7z x -olibusb ./libusb-1.0.22.7z
+
+We now need to export the following variables such that the libusb library gets linked into the OpenOCD build.
+
+.. code-block:: bash
+
    export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"
    export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"


-
 Build OpenOCD
 =============

-Proceed with configuring and building OpenOCD::
+The following commands will configure OpenOCD then build it.
+
+.. code-block:: bash

    cd ~/esp/openocd-esp32
    export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error"
@ -64,7 +75,12 @@ Proceed with configuring and building OpenOCD::
    cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src


-Optionally you can add ``make install`` step at the end. Skip it, if you have an existing OpenOCD (from e.g. another development platform), as it may get overwritten. Also you could use ``export DESTDIR="/custom/install/dir"; make install``.
+Once the build is completed, the OpenOCD binary will be placed in ``~/esp/openocd-esp32/src/``.
+
+You can then optionally call ``make install``. This will copy the OpenOCD binary to a user specified location.
+
+- This location can be specified when OpenOCD is configured, or by setting ``export DESTDIR="/custom/install/dir"`` before calling ``make install``.
+- If you have an existing OpenOCD (from e.g. another development platform), you may want to skip this call as your existing OpenOCD may get overwritten.

 .. note::

@ -81,7 +97,9 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will
 Full Listing
 ============

-A complete described previously process is provided below for the faster execution, e.g. as a shell script::
+For greater convenience, all of commands called throughout the OpenOCD build process have been listed in the code snippet below. Users can copy this code snippet into a shell script then execute it:
+
+.. code-block:: bash

    pacman -S --noconfirm --needed autoconf automake git make mingw-w64-i686-gcc mingw-w64-i686-toolchain mingw-w64-i686-libtool mingw-w64-i686-pkg-config mingw-w64-cross-winpthreads-git p7zip
    cd ~/esp
@ -106,7 +124,6 @@ A complete described previously process is provided below for the faster executi
    # cp ./src/libwinpthread-1.dll $DESTDIR/mingw32/bin


-
 Next Steps
 ==========

--- a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst
+++ b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst
@ -2,7 +2,7 @@ Configure Other JTAG Interface
 ==============================
 :link_to_translation:`zh_CN:[中文]`

-Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and {IDF_TARGET_NAME}. Then follow three configuration steps below to get it working.
+For guidance about which JTAG interface to select to enable operation with OpenOCD and {IDF_TARGET_NAME}, refer to section :ref:`jtag-debugging-selecting-jtag-adapter`. Then follow the three configuration steps below to get it working.


 .. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
@ -14,34 +14,35 @@ Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what

   Burning eFuses is an irreversible operation, so consider both options below before starting the process.

-   - Burning ``DIS_USB_JTAG`` eFuse will permanently disable the connection between USB_SERIAL_JTAG and the JTAG port of the CPU. JTAG interface can then be connected to |jtag-gpio-list|. Note that USB CDC functionality of USB_SERIAL_JTAG will still be useable, i.e. flashing and monitoring over USB CDC will still work.
+   - Burning ``DIS_USB_JTAG`` eFuse will permanently disable the connection between USB_SERIAL_JTAG and the JTAG port of the CPU. JTAG interface can then be connected to |jtag-gpio-list|. Note that USB CDC functionality of USB_SERIAL_JTAG will still be usable, i.e. flashing and monitoring over USB CDC will still work.

   - Burning ``JTAG_SEL_ENABLE`` eFuse will enable selection of JTAG interface by a strapping pin, |jtag-sel-gpio|. If the strapping pin is low when {IDF_TARGET_NAME} is reset, JTAG interface will use |jtag-gpio-list|. If the strapping pin is high, USB_SERIAL_JTAG will be used as the JTAG interface.

+
 Configure Hardware
 ^^^^^^^^^^^^^^^^^^

-1.  Identify all pins / signals on JTAG interface and {IDF_TARGET_NAME} board, that should be connected to establish communication.
+1.  Identify all pins/signals on JTAG interface and {IDF_TARGET_NAME} board that should be connected to establish communication.

    .. include:: {IDF_TARGET_PATH_NAME}.inc
        :start-after: jtag-pins
        :end-before: ---

-2.  Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation.
+2.  Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other hardware that may disturb JTAG operation.

-3.  Connect identified pin / signals of {IDF_TARGET_NAME} and JTAG interface.
+3.  Connect identified pin/signals of {IDF_TARGET_NAME} and JTAG interface.


 Configure Drivers
 ^^^^^^^^^^^^^^^^^
-You may need to install driver s/w to make JTAG work with computer. Refer to documentation of JTAG adapter, that should provide related details.
+
+You may need to install driver software to make JTAG work with computer. Refer to documentation of your JTAG adapter for related details.


 Connect
 ^^^^^^^

-Connect JTAG interface to the computer. Power on {IDF_TARGET_NAME} and JTAG interface boards. Check if JTAG interface is visible by computer.
+Connect JTAG interface to the computer. Power on {IDF_TARGET_NAME} and JTAG interface boards. Check if the JTAG interface is visible on the computer.


 To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
-
--- a/docs/en/hw-reference/esp32/get-started-devkitc.rst
+++ b/docs/en/hw-reference/esp32/get-started-devkitc.rst
@ -9,7 +9,7 @@ This guide shows how to start using the ESP32-DevKitC V4 development board.
 What You Need
 -------------

-* ESP32-DevKitC V4 board
+* :ref:`ESP32-DevKitC V4 board <get-started-esp32-devkitc-board-front>`
 * USB A / micro USB B cable
 * Computer running Windows, Linux, or macOS

@ -177,13 +177,12 @@ The component C15 may cause the following issues on earlier ESP32-DevKitC V4 boa
 * The board may boot into Download mode
 * If you output clock on GPIO0, C15 may impact the signal

-In case these issues occur, please remove the component. The figure below shows C15 highlighted in yellow.
+In case these issues occur, please remove the component. The figure below shows the location of C15 highlighted in yellow.


 .. figure:: ../../../_static/esp32-devkitc-c15-location.png
    :align: center
    :alt: Location of C15 (colored yellow) on ESP32-DevKitC V4 board
-    :figclass: align-center
    :width: 30%

    Location of C15 (yellow) on ESP32-DevKitC V4 board
@ -211,26 +210,17 @@ Board Dimensions
 Related Documents
 -----------------

-* `ESP32-DevKitC V4 schematics`_ (PDF)
-* `ESP32 Datasheet`_ (PDF)
-* `ESP32-WROOM-DA Datasheet`_ (PDF)
-* `ESP32-WROOM-32 Datasheet`_ (PDF)
-* `ESP32-WROOM-32D and ESP32-WROOM-32U Datasheet`_ (PDF)
-* `ESP32-WROVER Datasheet`_ (PDF)
-* `ESP32-WROVER-B Datasheet`_ (PDF)
-* `ESP Product Selector`_ 
+* `ESP32-DevKitC V4 schematics <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch.pdf>`_ (PDF)
+* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
+* `ESP32-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf>`_ (PDF)
+* `ESP32-WROOM-32D and ESP32-WROOM-32U Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32d_esp32-wroom-32u_datasheet_en.pdf>`_ (PDF)
+* `ESP32-WROOM-DA Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf>`_ (PDF)
+* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
+* `ESP32-WROVER-B Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-b_datasheet_en.pdf>`_ (PDF)
+* `ESP Product Selector <https://products.espressif.com/#/product-selector?names=>`_ 

 For further design documentation for the board, please contact us at `sales@espressif.com <sales@espressif.com>`_.

-.. _ESP32-DevKitC V4 schematics: https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch.pdf
-.. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
-.. _ESP32-WROOM-32 Datasheet: https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf
-.. _ESP32-WROOM-32D and ESP32-WROOM-32U Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32d_esp32-wroom-32u_datasheet_en.pdf
-.. _ESP32-WROVER Datasheet: https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf
-.. _ESP32-WROVER-B Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-wrover-b_datasheet_en.pdf
-.. _ESP32-WROOM-DA Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-wroom-da_datasheet_en.pdf
-.. _ESP Product Selector: https://products.espressif.com/#/product-selector?names=
-

 .. toctree::
    :hidden:
--- a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-windows.rst
+++ b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-windows.rst
@ -3,56 +3,84 @@ Windows 环境下从源码编译 OpenOCD
 ********************************
 :link_to_translation:`en:[English]`

-除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :ref:`jtag-debugging-setup-openocd` 章节查阅。
+.. note::

+    本文介绍了如何从 OpenOCD 源文件构建二进制文件。如果您想要更快速地构建，也可以从 `乐鑫 GitHub <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 的预构建二进制文件，而无需自己编译（详细信息，请参阅 :ref:`jtag-debugging-setup-openocd`）。

-.. highlight:: bash
+.. note::

-下载 OpenOCD 源码
-=================
-
-支持 {IDF_TARGET_NAME} 的 OpenOCD 源代码可以从乐鑫官方的 GitHub 获得，网址为 https://github.com/espressif/openocd-esp32。请使用以下命令来下载源代码::
-
-    cd ~/esp
-    git clone --recursive https://github.com/espressif/openocd-esp32.git
-
-克隆后的源代码被保存在 ``~/esp/openocd-esp32`` 目录中。
+    本文涉及的命令行操作均在装有 MINGW32 子系统的 MSYS2 shell 环境中进行了验证。


 安装依赖的软件包
 ================

-安装编译 OpenOCD 所需的软件包。
+安装编译 OpenOCD 所需的软件包：

-.. note::
+.. code-block:: bash

-    依次安装以下软件包，检查安装是否成功，然后继续下一个软件包的安装。在进行下一步操作之前，要先解决当前报告的问题。
+    pacman -S --noconfirm --needed autoconf automake git make \
+    mingw-w64-i686-gcc \
+    mingw-w64-i686-toolchain \
+    mingw-w64-i686-libtool \
+    mingw-w64-i686-pkg-config \
+    mingw-w64-cross-winpthreads-git \
+    p7zip

-::

-	pacman -S libtool
-	pacman -S autoconf
-	pacman -S automake
-	pacman -S texinfo
-	pacman -S mingw-w64-i686-libusb-compat-git
-	pacman -S pkg-config
+下载 OpenOCD 源码
+=================

-.. note::
+支持 {IDF_TARGET_NAME} 的 OpenOCD 源码可以从乐鑫官方 GitHub 获取，网址为 https://github.com/espressif/openocd-esp32。您可以在 Git 中使用以下命令来拉取源代码：

-	安装 ``pkg-config`` 会破坏 esp-idf 的工具链，因而在 OpenOCD 构建完成后，应将其卸载。详见文末进一步说明。如果想要再次构建 OpenOCD，你需要再次运行 ``pacman -S pkg-config``。此步骤安装的其他软件包（在 ``pkg-config`` 之前）并不会出现这一问题。
+.. code-block:: bash
+
+    cd ~/esp
+    git clone --recursive https://github.com/espressif/openocd-esp32.git
+
+克隆后的源代码保存在 ``~/esp/openocd-esp32`` 目录下。
+
+
+下载 libusb
+================
+
+构建 OpenOCD 需使用 libusb 库。请执行以下命令来下载特定版本的 libusb，并将其解压至当前目录。
+
+.. code-block:: bash
+
+    wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z
+    7z x -olibusb ./libusb-1.0.22.7z
+
+现在需要导出以下变量，以便将 libusb 库与 OpenOCD 构建相关联。
+
+.. code-block:: bash
+
+    export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"
+    export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"


 构建 OpenOCD
 ============

-配置和构建 OpenOCD 的流程如下::
+配置和构建 OpenOCD，请参考以下命令：
+
+.. code-block:: bash

    cd ~/esp/openocd-esp32
+    export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error"
    ./bootstrap
-    ./configure
+    ./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink --build=i686-w64-mingw32 --host=i686-w64-mingw32
    make
+    cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src
+    cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src

-你可以选择最后再执行 ``sudo make install`` ，如果你已经安装过别的开发平台的 OpenOCD，请跳过这个步骤，因为它可能会覆盖掉原来的 OpenOCD。
+
+构建完成后，OpenOCD 的二进制文件将被保存于 ``~/esp/openocd-esp32/src/`` 目录下。
+
+您也可以调用 ``make install``，将其复制到指定位置。
+
+- 您可以在配置 OpenOCD 时指定这一位置，也可以在调用 ``make install`` 前设置 ``export DESTDIR="/custom/install/dir"``。
+- 如果您已经安装过其他开发平台的 OpenOCD，请跳过此步骤，否则原来的 OpenOCD 可能会被覆盖。

 .. note::

@ -61,12 +89,39 @@ Windows 环境下从源码编译 OpenOCD
    * 如果 ``./configure`` 成功运行，JTAG 被使能的信息会被打印在 ``OpenOCD configuration summary`` 下面。
    * 如果您的设备信息未显示在日志中，请根据 ``../openocd-esp32/doc/INSTALL.txt`` 文中的描述使用 ``./configure`` 启用它。
    * 有关编译 OpenOCD 的详细信息，请参阅 ``openocd-esp32/README.Windows``。
+    * 请记得将 `libusb-1.0.dll` 和 `libwinpthread-1.dll` 从 ``~/esp/openocd-esp32/src`` 复制到 `OOCD_INSTALLDIR/bin`。

-一旦 ``make`` 过程成功完成，OpenOCD 的可执行文件会被保存到 ``~/esp/openocd-esp32/src/openocd`` 目录中。
+一旦 ``make`` 过程完成，OpenOCD 的可执行文件会被保存到 ``~/esp/openocd-esp32/src/openocd`` 目录下。

-如安装依赖步骤所述，最后还需要移除 ``pkg-config`` 软件包::

-	pacman -Rs pkg-config
+完整编译过程
+==============
+
+OpenOCD 编译过程中所调用的所有命令都已包含在以下代码片段中，您可以将其复制到 shell 脚本中，以便快速执行:
+
+.. code-block:: bash
+
+    pacman -S --noconfirm --needed autoconf automake git make mingw-w64-i686-gcc mingw-w64-i686-toolchain mingw-w64-i686-libtool mingw-w64-i686-pkg-config mingw-w64-cross-winpthreads-git p7zip
+    cd ~/esp
+    git clone --recursive https://github.com/espressif/openocd-esp32.git
+
+    wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z
+    7z x -olibusb ./libusb-1.0.22.7z
+    export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"; export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"
+
+    export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error"
+    cd ~/esp/openocd-esp32
+    ./bootstrap
+    ./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink --build=i686-w64-mingw32 --host=i686-w64-mingw32
+    make
+    cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src
+    cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src
+
+    # # optional
+    # export DESTDIR="$PWD"
+    # make install
+    # cp ./src/libusb-1.0.dll $DESTDIR/mingw32/bin
+    # cp ./src/libwinpthread-1.dll $DESTDIR/mingw32/bin


 下一步
--- a/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst
+++ b/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst
@ -5,23 +5,38 @@
 关于适配 OpenOCD 和 {IDF_TARGET_NAME} 的 JTAG 接口选择问题，请参考 :ref:`jtag-debugging-selecting-jtag-adapter` 章节，确保 JTAG 适配器能够与 OpenOCD 和 {IDF_TARGET_NAME} 一同工作。然后按照以下三个步骤进行设置，使其正常工作。


+.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
+
+   配置 eFuses
+   ^^^^^^^^^^^^^^^^
+
+   {IDF_TARGET_NAME} JTAG 接口默认连接至 :doc:`内置 USB_SERIAL_JTAG 外设 <configure-builtin-jtag>`。要使用外部 JTAG 适配器，需将 JTAG 接口切换至 GPIO 管脚。您可以使用 `espefuse.py` 工具来烧录 eFuse，以完成接口转换。
+
+   烧录 eFuse 是一项不可逆的操作，所以在开始之前，请考虑以下两点：
+
+   - 烧录 `DIS_USB_JTAG` eFuse 后，USB_SERIAL_JTAG 和 CPU 的 JTAG 接口之间的连接将被永久禁用，此后您可以将 JTAG 接口连接到 |jtag-gpio-list|。注意，烧录后，USB_SERIAL_JTAG 的 USB CDC 功能仍然可用，即仍然可以通过 USB CDC 进行烧录和 log 查看。
+ 
+   - 烧录 ``JTAG_SEL_ENABLE`` eFuse 后，JTAG 接口的选择将由 strapping 管脚 |jtag-sel-gpio| 来决定。{IDF_TARGET_NAME} 复位时，如果该 strapping 管脚为低电平，JTAG 接口将使用 |jtag-gpio-list|，如果为高电平，USB_SERIAL_JTAG 将被用作 JTAG 接口。
+
+
 配置硬件
 ^^^^^^^^

-1.  找到 JTAG 接口和 {IDF_TARGET_NAME} 板上需要相互连接并建立通信的引脚/信号。
+1.  找到 JTAG 接口和 {IDF_TARGET_NAME} 板上需要相互连接并建立通信的所有管脚或信号。

    .. include:: {IDF_TARGET_PATH_NAME}.inc
        :start-after: jtag-pins
        :end-before: ---

-2.  检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的的引脚是否被连接到了其它硬件上，这可能会影响 JTAG 的工作。
+2.  检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的管脚是否被连接到了其它硬件上，这可能会影响 JTAG 的工作。

-3.  连接 {IDF_TARGET_NAME} 和 JTAG 接口上的引脚/信号。
+3.  连接 {IDF_TARGET_NAME} 和 JTAG 接口上的管脚或信号。


 配置驱动
 ^^^^^^^^
-你可能还需要安装软件驱动，才能使 JTAG 在计算机上正常工作，请参阅你所使用的 JTAG 适配器的有关文档，获取相关详细信息。
+
+您可能还需要安装软件驱动，才能使 JTAG 在计算机上正常工作，请参阅您所使用的 JTAG 适配器的有关文档，获取相关详细信息。


 连接
@ -31,4 +46,3 @@


 要继续设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。
-
--- a/docs/zh_CN/api-guides/jtag-debugging/esp32c3.inc
+++ b/docs/zh_CN/api-guides/jtag-debugging/esp32c3.inc
@ -7,7 +7,6 @@
 .. These code blocks can be moved back to the main .rst files, with target-specific
 .. file names being replaced by substitutions.

-
 .. run-openocd

 ::
@ -22,21 +21,25 @@

 ::

-    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s2-kaluga-1.cfg
-    Open On-Chip Debugger  v0.10.0-esp32-20200420 (2020-04-20-16:15)
+    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32c3-builtin.cfg
+    Open On-Chip Debugger v0.10.0-esp32-20201202-26-g05a036c2 (2021-03-15-17:18)
    Licensed under GNU GPL v2
    For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
-    none separate
-    adapter speed: 20000 kHz
+    Info : only one transport option; autoselect 'jtag'
+    Warn : Transport "jtag" was already selected
    force hard breakpoints
-    Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
-    Info : clock speed 20000 kHz
-    Info : JTAG tap: esp32s2.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
-    Info : esp32s2: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
-    Info : esp32s2: Core was reset (pwrstat=0x5F, after clear 0x0F).
+    Info : Listening on port 6666 for tcl connections
+    Info : Listening on port 4444 for telnet connections
+    Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255
+    Info : clock speed 40000 kHz
+    Info : JTAG tap: esp32c3.cpu tap/device found: 0x00005c25 (mfg: 0x612 (Espressif Systems), part: 0x0005, ver: 0x0)
+    Info : datacount=2 progbufsize=16
+    Info : Examined RISC-V core; found 1 harts
+    Info :  hart 0: XLEN=32, misa=0x40101104
+    Info : Listening on port 3333 for gdb connections

-.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s2-kaluga-1.cfg``
+.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32c3-builtin.cfg``

 ---

@ -44,7 +47,7 @@

 ::

-    openocd -f board/esp32s2-kaluga-1.cfg -c "program_esp filename.bin 0x10000 verify exit"
+    openocd -f board/esp32c3-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit"

 ---

@ -52,7 +55,7 @@

 .. code-block:: bash

-    src/openocd -f board/esp32s2-kaluga-1.cfg
+    src/openocd -f board/esp32c3-builtin.cfg

 ---

@ -60,13 +63,13 @@

 .. code-block:: batch

-    src\openocd -f board/esp32s2-kaluga-1.cfg
+    src\openocd -f board/esp32c3-builtin.cfg

 ---

 .. idf-py-openocd-default-cfg

-.. |idf-py-def-cfg| replace:: ``-f board/esp32s2-kaluga-1.cfg``
+.. |idf-py-def-cfg| replace:: ``-f board/esp32c3-builtin.cfg``

 ---

@ -74,26 +77,28 @@

 ::

-    openocd -f board/esp32s2-kaluga-1.cfg -c "init; halt; esp appimage_offset 0x210000"
+    openocd -f board/esp32c3-builtin.cfg -c "init; halt; esp appimage_offset 0x210000"

 ---

 .. openocd-cfg-files

-.. list-table:: ESP32-S2 相关的 OpenOCD 配置文件
+.. list-table:: ESP32-C3 相关的 OpenOCD 配置文件
    :widths: 25 75
    :header-rows: 1

-    * - 名字
+    * - 名称
      - 描述
-    * - ``board/esp32s2-kaluga-1.cfg``
-      - ESP32-S2-Kaluga-1 开发板配置文件，内部已包含 ESP32-S2 目标配置和 JTAG 适配器配置
-    * - ``target/esp32s2.cfg``
-      - ESP32-S2 目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用
-    * - ``interface/ftdi/esp32s2_kaluga_v1.cfg``
-      - 适用于 ESP32-S2-Kaluga-1 开发板的 JTAG 适配器配置文件
+    * - ``board/esp32c3-builtin.cfg``
+      - 通过内置 USB 连接的 ESP32-C3 系列开发板配置文件，包含 ESP32-C3 目标配置和 JTAG 适配器配置。
+    * - ``board/esp32c3-ftdi.cfg``
+      - 通过与 ESP-Prog 兼容的 FTDI 对 ESP32-C3 调试的配置文件，包括 ESP32-C3 目标配置和 JTAG 适配器配置。
+    * - ``target/esp32c3.cfg``
+      - ESP32-C3 目标配置文件。可以和某个 ``interface/`` 下的配置文件一同使用。
+    * - ``interface/esp_usb_jtag.cfg``
+      - 适用于 ESP32-C3 的 JTAG 适配器配置文件。
    * - ``interface/ftdi/esp32_devkitj_v1.cfg``
-      - 适用于 ESP-Prog 板子的 JTAG 适配器配置文件
+      - 适用于 ESP-Prog 的 JTAG 适配器配置文件。

 ---

@ -105,28 +110,31 @@

 .. jtag-pins

-.. list-table:: ESP32-S2 引脚和 JTAG 接口信号
+.. list-table:: ESP32-C3 管脚和 JTAG 接口信号
    :widths: 25 75
    :header-rows: 1

-    * - ESP32-S2 引脚
+    * - ESP32-C3 管脚
      - JTAG 信号
-    * - MTDO / GPIO40
+    * - MTDO / GPIO7
      - TDO
-    * - MTDI / GPIO41
+    * - MTDI / GPIO5
      - TDI
-    * - MTCK / GPIO39
+    * - MTCK / GPIO6
      - TCK
-    * - MTMS / GPIO42
+    * - MTMS / GPIO4
      - TMS

+.. |jtag-sel-gpio| replace:: GPIO10
+.. |jtag-gpio-list| replace:: GPIO4-GPIO7
+
 ---

 .. run-openocd-d3

 ::

-    openocd -l openocd_log.txt -d3 -f board/esp32s2-kaluga-1.cfg
+    openocd -l openocd_log.txt -d3 -f board/esp32c3-builtin.cfg

 ---

@ -134,7 +142,7 @@

 ::

-    openocd -d3 -f board/esp32s2-kaluga-1.cfg 2>&1 | tee openocd.log
+    openocd -d3 -f board/esp32c3-builtin.cfg 2>&1 | tee openocd.log

 ---

@ -142,19 +150,19 @@

 ::

-    xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
+    riscv32-esp-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>

 ---

 .. devkit-defs

-.. |devkit-name| replace:: ESP-S2-Kaluga-1
-.. |devkit-name-with-link| replace:: :doc:`ESP-S2-Kaluga-1 <../../hw-reference/index>`
+.. |devkit-name| replace:: ESP32-C3
+.. |devkit-name-with-link| replace:: :doc:`ESP32-C3 <../../hw-reference/index>`

 ---

 .. devkit-hw-config

-* 开箱即用，ESP32-S2-Kaluga-1 不需要任何其他硬件配置即可进行 JTAG 调试。 但是，如果遇到问题，请检查 “JTAG” DIP 开关的 2～5 号是否在 “ON” 的位置。
+* 开箱即用，ESP32-C3 不需要任何其他硬件配置即可进行 JTAG 调试。

 ---
--- a/docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc
+++ b/docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc
@ -129,6 +129,9 @@
    * - MTMS
      - TMS

+.. |jtag-sel-gpio| replace:: GPIO3
+.. |jtag-gpio-list| replace:: GPIO39-GPIO42
+
 ---

 .. run-openocd-d3
--- a/docs/zh_CN/hw-reference/esp32/get-started-devkitc.rst
+++ b/docs/zh_CN/hw-reference/esp32/get-started-devkitc.rst
@ -5,6 +5,7 @@ ESP32-DevKitC V4 入门指南

 本指南介绍了如何开始使用 ESP32-DevKitC V4 开发板。

+
 准备工作
 -----------

@ -35,7 +36,6 @@ ESP32-DevKitC V4 是 `乐鑫 <https://espressif.com>`_ 一款基于 ESP32 的小
   - `ESP32-WROVER-IE <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_cn.pdf>`_
   - `ESP32-WROOM-DA <https://www.espressif.com/sites/default/files/documentation/esp32-wroom-da_datasheet_cn.pdf>`_

-
 - 可选排针或排母

 详情请见 `乐鑫产品选型工具 <https://products.espressif.com/#/product-selector?names=>`__。
@ -82,7 +82,7 @@ ESP32-DevKitC V4 开发板的主要组件、接口及控制方式见下。

 .. note::

-	管脚 GPIO16 和 GPIO17 仅适用于板载 ESP32-WROOM 系列和 ESP32-SOLO-1 的开发板，保留内部使用。
+	管脚 GPIO16 和 GPIO17 仅适用于板载 ESP32-WROOM 系列和 ESP32-SOLO-1 的开发板，板载 ESP32-WROVER 系列开发板的管脚 GPIO16 和 GPIO17 保留内部使用。


 电源选项
@ -195,6 +195,7 @@ ESP32-DevKitC V4 上电前，请首先确认开发板完好无损。

 现在，请前往 :doc:`../../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。

+
 开发板尺寸
 -------------

@ -213,10 +214,13 @@ ESP32-DevKitC V4 上电前，请首先确认开发板完好无损。
 * `《ESP32 技术规格书》 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>`_ (PDF)
 * `《ESP32-WROOM-32 技术规格书》 <https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_cn.pdf>`_ (PDF)
 * `《ESP32-WROOM-32D & ESP32-WROOM-32U 技术规格书》 <https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32d_esp32-wroom-32u_datasheet_cn.pdf>`_ (PDF)
+* `《ESP32-WROOM-DA 技术规格书》 <https://www.espressif.com/sites/default/files/documentation/esp32-wroom-da_datasheet_cn.pdf>`_ (PDF)
 * `《ESP32-WROVER 技术规格书》 <https://espressif.com/sites/default/files/documentation/esp32_wrover_datasheet_cn.pdf>`_ (PDF)
 * `《ESP32-WROVER-B 技术规格书》 <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-b_datasheet_cn.pdf>`_ (PDF)
-* `《ESP32-WROOM-DA 技术规格书》 <https://www.espressif.com/sites/default/files/documentation/esp32-wroom-da_datasheet_cn.pdf>`_ (PDF)
-* `乐鑫产品选型工具 <https://products.espressif.com/#/product-selector?names=>`__
+* `乐鑫产品选型工具 <https://products.espressif.com/#/product-selector?names=>`_
+
+有关本开发板的更多设计文档，请联系我们的商务部门 `sales@espressif.com <sales@espressif.com>`_。
+

 .. toctree::
 	:hidden: