mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-20 00:36:01 -04:00
docs:update cn trans for jtag-debugging
This commit is contained in:
intern
BOT
parent
7efbca6701
commit
9a28504eea
@ -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
|
||||
==========
|
||||
|
||||
|
||||
@ -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`.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
下一步
|
||||
|
||||
@ -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` 章节。
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user