From 9a28504eea47176e7e7696f1292ac94e13c91b06 Mon Sep 17 00:00:00 2001 From: intern Date: Thu, 10 Mar 2022 11:56:49 +0800 Subject: [PATCH] docs:update cn trans for jtag-debugging --- .../building-openocd-windows.rst | 41 +++++-- .../jtag-debugging/configure-other-jtag.rst | 17 +-- .../esp32/get-started-devkitc.rst | 1 - .../building-openocd-windows.rst | 113 +++++++++++++----- .../jtag-debugging/configure-other-jtag.rst | 24 +++- 5 files changed, 141 insertions(+), 55 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst b/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst index 423a177dc1..8d27f5311b 100644 --- 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 `_. 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 `_ 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 ========== diff --git a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst index 0d28f2b4fb..1f0da8312c 100644 --- 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`. - diff --git a/docs/en/hw-reference/esp32/get-started-devkitc.rst b/docs/en/hw-reference/esp32/get-started-devkitc.rst index 374921c536..d48142702f 100644 --- a/docs/en/hw-reference/esp32/get-started-devkitc.rst +++ b/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 diff --git a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-windows.rst b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-windows.rst index 25f8d684ca..58dca13ba8 100644 --- 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 官方 `_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :ref:`jtag-debugging-setup-openocd` 章节查阅。 +.. note:: + 本文介绍了如何从 OpenOCD 源文件构建二进制文件。如果您想要更快速地构建，也可以从 `乐鑫 GitHub `_ 直接下载 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 下一步 diff --git a/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst b/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst index ad453cc3d3..ab011392ea 100644 --- 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 外设 `。要使用外部 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` 章节。 -