Merge branch 'docs/update_cn_trans_jtag_debugging' into 'master'

docs: update cn trans for jtag-debugging docs

Closes DOC-2810

See merge request espressif/esp-idf!17436

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
 ==========
 

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`.
-

docs/en/hw-reference/esp32/get-started-devkitc.rst

@@ -183,7 +183,6 @@ In case these issues occur, please remove the component. The figure below shows
 .. 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

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 源码
+    本文涉及的命令行操作均在装有 MINGW32 子系统的 MSYS2 shell 环境中进行了验证。
-=================
-
-支持 {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`` 目录中。
 
 
 安装依赖的软件包
 ================
 
-安装编译 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
+下载 OpenOCD 源码
-	pacman -S autoconf
+=================
-	pacman -S automake
-	pacman -S texinfo
-	pacman -S mingw-w64-i686-libusb-compat-git
-	pacman -S pkg-config
 
-.. 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
 
 
 下一步

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` 章节。
-