From a3eb4d85d462b730a3eaae5e5b34a0392c682c3a Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Wed, 15 Jul 2020 15:39:19 +0200 Subject: [PATCH] docs: jtag-debugging: update Chinese version --- .../jtag-debugging/configure-ft2232h-jtag.rst | 61 +++--- .../jtag-debugging/configure-other-jtag.rst | 38 +--- .../zh_CN/api-guides/jtag-debugging/esp32.inc | 177 +++++++++++++++++- .../api-guides/jtag-debugging/esp32s2.inc | 161 +++++++++++++++- .../zh_CN/api-guides/jtag-debugging/index.rst | 65 ++++--- .../jtag-debugging/tips-and-quirks.rst | 170 +++++++---------- 6 files changed, 467 insertions(+), 205 deletions(-) diff --git a/docs/zh_CN/api-guides/jtag-debugging/configure-ft2232h-jtag.rst b/docs/zh_CN/api-guides/jtag-debugging/configure-ft2232h-jtag.rst index 842561c484..69542ef790 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/configure-ft2232h-jtag.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/configure-ft2232h-jtag.rst @@ -1,52 +1,47 @@ -配置 WROVER 上的 JTAG 接口 -========================== +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: devkit-defs + :end-before: --- + +配置 |devkit-name| 上的 JTAG 接口 +===================================== :link_to_translation:`en:[English]` -所有版本的 ESP-WROVER-KIT 板子都内置了 JTAG 调试功能，要使其正常工作，还需要设置相关跳帽来启用 JTAG 功能，设置 SPI 闪存电压和配置 USB 驱动程序。具体步骤请参考以下说明。 +所有版本的 |devkit-name| 板子都内置了 JTAG 调试功能，要使其正常工作，还需要设置相关跳帽来启用 JTAG 功能，设置 SPI 闪存电压和配置 USB 驱动程序。具体步骤请参考以下说明。 配置硬件 ^^^^^^^^ -1. 根据 :doc:`../../hw-reference/esp32/get-started-wrover-kit` 文档中 :ref:`get-started-esp-wrover-kit-v4.1-setup-options` 章节所描述的信息，设置 JP8 便可以启用 JTAG 功能。 +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: devkit-hw-config + :end-before: --- -2. 检查 ESP32 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。 - - +---+---------------+-----------+ - | | ESP32 引脚 | JTAG 信号 | - +===+===============+===========+ - | 1 | CHIP_PU | TRST_N | - +---+---------------+-----------+ - | 2 | MTDO / GPIO15 | TDO | - +---+---------------+-----------+ - | 3 | MTDI / GPIO12 | TDI | - +---+---------------+-----------+ - | 4 | MTCK / GPIO13 | TCK | - +---+---------------+-----------+ - | 5 | MTMS / GPIO14 | TMS | - +---+---------------+-----------+ +2. 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。 +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: jtag-pins + :end-before: --- 配置 USB 驱动 ^^^^^^^^^^^^^ -安装和配置 USB 驱动，这样 OpenOCD 才能够与 ESP-WROVER-KIT 板上的 JTAG 接口通信，并且使用 UART 接口上传待烧写的镜像文件。请根据你的操作系统按照以下步骤进行安装配置。 +安装和配置 USB 驱动，这样 OpenOCD 才能够与 |devkit-name| 板上的 JTAG 接口通信，并且使用 UART 接口上传待烧写的镜像文件。请根据你的操作系统按照以下步骤进行安装配置。 -.. note:: ESP-WROVER-KIT 使用了 FT2232 芯片实现了 JTAG 适配器，所以以下说明同样适用于其他基于 FT2232 的 JTAG 适配器。 +.. note:: |devkit-name| 使用了 FT2232 芯片实现了 JTAG 适配器，所以以下说明同样适用于其他基于 FT2232 的 JTAG 适配器。 Windows """"""" -1. 使用标准 USB A / micro USB B 线将 ESP-WROVER-KIT 与计算机相连接，并打开板子的电源。 +1. 使用标准 USB A / micro USB B 线将 |devkit-name| 与计算机相连接，并打开板子的电源。 -2. 等待 Windows 识别出 ESP-WROVER-KIT 并且为其安装驱动。如果驱动没有被自动安装，请前往 `官网 `_ 下载并手动安装。 +2. 等待 Windows 识别出 |devkit-name| 并且为其安装驱动。如果驱动没有被自动安装，请前往 `官网 `_ 下载并手动安装。 3. 从 `Zadig 官网 `_ 下载 Zadig 工具（Zadig_X.X.exe）并运行。 4. 在 Zadig 工具中，进入 “Options” 菜单中选中 “List All Devices”。 -5. 检查设备列表，其中应该包含两条与 ESP-WROVER-KIT 相关的条目：“Dual RS232-HS (Interface 0)” 和 “Dual RS232-HS (Interface 1)”。驱动的名字应该是 “FTDIBUS (vxxxx)” 并且 USB ID 为：0403 6010。 +5. 检查设备列表，其中应该包含两条与 |devkit-name| 相关的条目：“Dual RS232-HS (Interface 0)” 和 “Dual RS232-HS (Interface 1)”。驱动的名字应该是 “FTDIBUS (vxxxx)” 并且 USB ID 为：0403 6010。 .. figure:: ../../../_static/jtag-usb-configuration-zadig.jpg :align: center @@ -55,19 +50,19 @@ Windows 在 Zadig 工具中配置 JTAG USB 驱动 -6. 第一个设备 “Dual RS232-HS（Interface 0）” 连接到了 ESP32 的 JTAG 端口，此设备原来的 “FTDIBUS (vxxxx)” 驱动需要替换成 "WinUSB (v6xxxxx)"。为此，请选择 “Dual RS232-HS (Interface 0)” 并将驱动重新安装为 “WinUSB (v6xxxxx)”，具体可以参考上图。 +6. 第一个设备 “Dual RS232-HS（Interface 0）” 连接到了 {IDF_TARGET_NAME} 的 JTAG 端口，此设备原来的 “FTDIBUS (vxxxx)” 驱动需要替换成 "WinUSB (v6xxxxx)"。为此，请选择 “Dual RS232-HS (Interface 0)” 并将驱动重新安装为 “WinUSB (v6xxxxx)”，具体可以参考上图。 .. note:: - 请勿更改第二个设备 “Dual RS232-HS（Interface 1）” 的驱动，它被连接到 ESP32 的串口（UART），用于上传应用程序映像给 ESP32 进行烧写。 + 请勿更改第二个设备 “Dual RS232-HS（Interface 1）” 的驱动，它被连接到 {IDF_TARGET_NAME} 的串口（UART），用于上传应用程序映像给 {IDF_TARGET_NAME} 进行烧写。 -现在，ESP-WROVER-KIT 的 JTAG 接口应该可以被 OpenOCD 使用了，想要进一步设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。 +现在，|devkit-name| 的 JTAG 接口应该可以被 OpenOCD 使用了，想要进一步设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。 Linux """"" -1. 使用标准 USB A / micro USB B 线将 ESP-WROVER-KIT 与计算机相连接，并打开板子的电源。 +1. 使用标准 USB A / micro USB B 线将 |devkit-name| 与计算机相连接，并打开板子的电源。 .. highlight:: none @@ -92,9 +87,9 @@ Linux 如果看到类似的输出结果，并且你也是 ``plugdev`` 组的成员， 那么设置工作就完成了。 - 具有较低编号的 ``/dev/ttyUSBn`` 接口用于 JTAG 通信，另一路接口被连接到 ESP32 的串口（UART），用于上传应用程序映像给 ESP32 进行烧写。 + 具有较低编号的 ``/dev/ttyUSBn`` 接口用于 JTAG 通信，另一路接口被连接到 {IDF_TARGET_NAME} 的串口（UART），用于上传应用程序映像给 {IDF_TARGET_NAME} 进行烧写。 -现在，ESP-WROVER-KIT 的 JTAG 接口应该可以被 OpenOCD 使用了，想要进一步设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。 +现在，|devkit-name| 的 JTAG 接口应该可以被 OpenOCD 使用了，想要进一步设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。 MacOS @@ -104,14 +99,14 @@ MacOS 1. 在启动 OpenOCD 之前手动卸载 FTDI 串口驱动程序，然后启动 OpenOCD，再加载串口驱动程序。 -2. 修改 FTDI 驱动程序的配置，使其不会为 FT2232 芯片的通道 B 进行自我加载，该通道用于 ESP-WROVER-KIT 板上的 JTAG 通道。 +2. 修改 FTDI 驱动程序的配置，使其不会为 FT2232 芯片的通道 B 进行自我加载，该通道用于 |devkit-name| 板上的 JTAG 通道。 手动卸载驱动程序 ................ 1. 从 `FTDI 官网 `_ 安装驱动。 -2. 使用 USB 线连接 ESP-WROVER-KIT。 +2. 使用 USB 线连接 |devkit-name|。 3. 卸载串口驱动 :: @@ -131,7 +126,7 @@ MacOS .. note:: - 如果你需要重启 OpenOCD，则无需再次卸载 FTDI 驱动程序，只需停止 OpenOCD 并再次启动它。只有在重新连接 ESP-WROVER-KIT 或者切换了电源的情况下才需要再次卸载驱动。 + 如果你需要重启 OpenOCD，则无需再次卸载 FTDI 驱动程序，只需停止 OpenOCD 并再次启动它。只有在重新连接 |devkit-name| 或者切换了电源的情况下才需要再次卸载驱动。 你也可以根据自身需求，将此过程包装进 shell 脚本中。 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 d29f91b08f..46c87a9971 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 @@ -10,41 +10,9 @@ 1. 找到 JTAG 接口和 {IDF_TARGET_NAME} 板上需要相互连接并建立通信的引脚/信号。 -.. only:: esp32 - - +---+---------------+-----------+ - | | ESP32 引脚 | JTAG 信号 | - +===+===============+===========+ - | 1 | CHIP_PU | TRST_N | - +---+---------------+-----------+ - | 2 | MTDO / GPIO15 | TDO | - +---+---------------+-----------+ - | 3 | MTDI / GPIO12 | TDI | - +---+---------------+-----------+ - | 4 | MTCK / GPIO13 | TCK | - +---+---------------+-----------+ - | 5 | MTMS / GPIO14 | TMS | - +---+---------------+-----------+ - | 6 | GND | GND | - +---+---------------+-----------+ - -.. only:: esp32s2 - - +---+-----------------------+-------------+ - | | ESP32-S2 Pin | JTAG Signal | - +===+=======================+=============+ - | 1 | CHIP_PU | TRST_N | - +---+-----------------------+-------------+ - | 2 | MTDO / GPIO40 | TDO | - +---+-----------------------+-------------+ - | 3 | MTDI / GPIO41 | TDI | - +---+-----------------------+-------------+ - | 4 | MTCK / GPIO39 | TCK | - +---+-----------------------+-------------+ - | 5 | MTMS / GPIO42 | TMS | - +---+-----------------------+-------------+ - | 6 | GND | GND | - +---+-----------------------+-------------+ + .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: jtag-pins + :end-before: --- 2. 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的的引脚是否被连接到了其它硬件上，这可能会影响 JTAG 的工作。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32.inc index 07a0f663c4..e7c16c888a 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/esp32.inc +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32.inc @@ -1 +1,176 @@ -.. Placeholder, unused in zh_CN version yet. +.. This file gets included from other .rst files in this folder. +.. It contains target-specific snippets. +.. Comments and '---' lines act as delimiters. +.. +.. This is necessary mainly because RST doesn't support substitutions +.. (defined in RST, not in Python) inside code blocks. If that is ever implemented, +.. These code blocks can be moved back to the main .rst files, with target-specific +.. file names being replaced by substitutions. + + +.. run-openocd + +:: + + openocd -f board/esp32-wrover-kit-3.3v.cfg + +.. |run-openocd-device-name| replace:: ESP32-WROOM-32 模组的 ESP-WROVER-KIT 开发板 + +--- + +.. run-openocd-output + +:: + + user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32-wrover-kit-3.3v.cfg + Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04) + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + none separate + adapter speed: 20000 kHz + 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: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + Info : esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). + Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F). + +.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32-wrover-kit-3.3v.cfg`` + +--- + +.. run-openocd-upload + +:: + + openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000 verify exit" + +--- + +.. run-openocd-src-linux + +.. code-block:: bash + + src/openocd -f board/esp32-wrover-kit-3.3v.cfg + +--- + +.. run-openocd-src-win + +.. code-block:: batch + + src\openocd -f board\esp32-wrover-kit-3.3v.cfg + +--- + +.. idf-py-openocd-default-cfg + +.. |idf-py-def-cfg| replace:: ``-f board/esp32-wrover-kit-3.3v.cfg`` + +--- + +.. run-openocd-appimage-offset + +:: + + openocd -f board/esp32-wrover-kit-3.3v.cfg -c "init; halt; esp appimage_offset 0x210000" + +--- + +.. openocd-cfg-files + +.. list-table:: OpenOCD configuration files for ESP32 + :widths: 25 75 + :header-rows: 1 + + * - Name + - Description + * - ``board/esp32-wrover-kit-3.3v.cfg`` + - ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32 module or ESP32-WROVER-B / ESP32-WROVER-E module. + * - ``board/esp32-wrover-kit-1.8v.cfg`` + - ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module. + * - ``board/esp32-ethernet-kit-3.3v.cfg`` + - ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module. + * - ``target/esp32.cfg`` + - ESP32 target configuration file. Can be used together with one of the ``interface/`` configuration files. + * - ``target/esp32-solo-1.cfg`` + - Target configuration file for ESP32-SOLO-1 module. Different from ``esp32.cfg`` in that it only configures one CPU. + * - ``interface/ftdi/esp32_devkitj_v1.cfg`` + - JTAG adapter configuration file for ESP-WROVER-KIT and ESP-Prog boards. + +--- + +.. openocd-target-specific-config-vars + +.. list-table:: ESP32-specific OpenOCD variables + :widths: 25 75 + :header-rows: 1 + + * - Name + - Description + * - ``ESP32_FLASH_VOLTAGE`` + - When using 1.8 V flash ESP32 based modules, set this variable to ``1.8``. Refer to :ref:`jtag-debugging-tip-code-flash-voltage`. + * - ``ESP32_ONLYCPU`` + - For multi-core targets, can be set to ``1`` to only enable single core debugging. + +--- + +.. jtag-pins + +.. list-table:: ESP32 引脚和 JTAG 接口信号 + :widths: 25 75 + :header-rows: 1 + + * - ESP32 引脚 + - JTAG 信号 + * - MTDO / GPIO15 + - TDO + * - MTDI / GPIO12 + - TDI + * - MTCK / GPIO13 + - TCK + * - MTMS / GPIO14 + - TMS + * - GND + - GND + +--- + +.. run-openocd-d3 + +:: + + openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg + +--- + +.. run-openocd-d3-tee + +:: + + openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log + +--- + +.. run-gdb-remotelog + +:: + + xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" + +--- + +.. devkit-defs + +.. |devkit-name| replace:: ESP-WROVER-KIT +.. |devkit-name-with-link| replace:: :doc:`ESP-WROVER-KIT 开发板 <../../hw-reference/modules-and-boards>` + +--- + +.. devkit-hw-config + +* 根据 :doc:`../../hw-reference/esp32/get-started-wrover-kit` 文档中 :ref:`get-started-esp-wrover-kit-v4.1-setup-options` 章节所描述的信息，设置 JP8 便可以启用 JTAG 功能。 + +--- diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc index 07a0f663c4..49d3403713 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc @@ -1 +1,160 @@ -.. Placeholder, unused in zh_CN version yet. +.. This file gets included from other .rst files in this folder. +.. It contains target-specific snippets. +.. Comments and '---' lines act as delimiters. +.. +.. This is necessary mainly because RST doesn't support substitutions +.. (defined in RST, not in Python) inside code blocks. If that is ever implemented, +.. These code blocks can be moved back to the main .rst files, with target-specific +.. file names being replaced by substitutions. + + +.. run-openocd + +:: + + openocd -f board/esp32s2-kaluga-1.cfg + +.. |run-openocd-device-name| replace:: ESP32-S2-Kaluga-1 开发板 + +--- + +.. run-openocd-output + +:: + + 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) + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + none separate + adapter speed: 20000 kHz + 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). + +.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s2-kaluga-1.cfg`` + +--- + +.. run-openocd-upload + +:: + + openocd -f board/esp32s2-kaluga-1.cfg -c "program_esp filename.bin 0x10000 verify exit" + +--- + +.. run-openocd-src-linux + +.. code-block:: bash + + src/openocd -f board/esp32s2-kaluga-1.cfg + +--- + +.. run-openocd-src-win + +.. code-block:: batch + + src\openocd -f board/esp32s2-kaluga-1.cfg + +--- + +.. idf-py-openocd-default-cfg + +.. |idf-py-def-cfg| replace:: ``-f board/esp32s2-kaluga-1.cfg`` + +--- + +.. run-openocd-appimage-offset + +:: + + openocd -f board/esp32s2-kaluga-1.cfg -c "init; halt; esp appimage_offset 0x210000" + +--- + +.. openocd-cfg-files + +.. list-table:: OpenOCD configuration files for ESP32 + :widths: 25 75 + :header-rows: 1 + + * - Name + - Description + * - ``board/esp32s2-kaluga-1.cfg`` + - Board configuration file for ESP32-S2-Kaluga-1, includes target and adapter configuration. + * - ``target/esp32s2.cfg`` + - ESP32-S2 target configuration file. Can be used together with one of the ``interface/`` configuration files. + * - ``interface/ftdi/esp32s2_kaluga_v1.cfg`` + - JTAG adapter configuration file for ESP32-S2-Kaluga-1 board. + * - ``interface/ftdi/esp32_devkitj_v1.cfg`` + - JTAG adapter configuration file for ESP-Prog boards. + +--- + +.. openocd-target-specific-config-vars + +--- + +--- + +.. jtag-pins + +.. list-table:: ESP32-S2 引脚和 JTAG 接口信号 + :widths: 25 75 + :header-rows: 1 + + * - ESP32-S2 引脚 + - JTAG 信号 + * - MTDO / GPIO40 + - TDO + * - MTDI / GPIO41 + - TDI + * - MTCK / GPIO39 + - TCK + * - MTMS / GPIO42 + - TMS + +--- + +.. run-openocd-d3 + +:: + + openocd -l openocd_log.txt -d3 -f board/esp32s2-kaluga-1.cfg + +--- + +.. run-openocd-d3-tee + +:: + + openocd -d3 -f board/esp32s2-kaluga-1.cfg 2>&1 | tee openocd.log + +--- + +.. run-gdb-remotelog + +:: + + xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" + +--- + +.. devkit-defs + +.. |devkit-name| replace:: ESP-S2-Kaluga-1 +.. |devkit-name-with-link| replace:: :doc:`ESP-S2-Kaluga-1 <../../hw-reference/modules-and-boards>` + +--- + +.. devkit-hw-config + +* *开箱即用，ESP32-S2-Kaluga-1 不需要任何其他硬件配置即可进行 JTAG 调试。 但是，如果遇到问题，请检查 “JTAG” DIP 开关块的开关 2-5 是否在 “ON” 位置。 + +--- diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index e307978b61..5c2f287f5b 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -23,6 +23,12 @@ JTAG 调试 :ref:`jtag-debugging-tips-and-quirks` 介绍使用 OpenOCD 和 GDB 通过 JTAG 接口调试 {IDF_TARGET_NAME} 时的注意事项和补充内容。 + +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: devkit-defs + :end-before: --- + + .. _jtag-debugging-introduction: 引言 @@ -60,7 +66,7 @@ JTAG 调试 `Eclipse `__ 环境集成了 JTAG 调试和应用程序加载、监视的功能，它使得软件从编写、编译、加载到调试的迭代过程变得更加快速而简单。所有的软件均适用于 Windows，Linux 和 MacOS 平台。 -如果你使用的是 :doc:`ESP-WROVER-KIT 开发板 <../../hw-reference/modules-and-boards>`，得益于板载的 FT232H 芯片，PC 和 {IDF_TARGET_NAME} 的连接仅仅需要一根 USB 线即可完成。FT232H 提供了两路 USB 通道，一路连接到 JTAG，另一路连接到 UART。 +如果你使用的是 |devkit-name-with-link|，得益于板载的 FT232H 芯片，PC 和 {IDF_TARGET_NAME} 的连接仅仅需要一根 USB 线即可完成。FT232H 提供了两路 USB 通道，一路连接到 JTAG，另一路连接到 UART。 根据用户的喜好，除了使用 Eclipse 集成开发环境，还可以直接在命令行终端运行 `debugger` 和 `idf.py build`。 @@ -69,7 +75,7 @@ JTAG 调试 选择 JTAG 适配器 ---------------- -上手 JTAG 最快速便捷的方式是使用 :doc:`ESP-WROVER-KIT 开发板 <../../hw-reference/modules-and-boards>`，因为它板载了 JTAG 调试接口，无需使用外部的 JTAG 硬件适配器和额外的线缆来连接 JTAG 与 {IDF_TARGET_NAME}。ESP-WROVER-KIT 采用 FT2232H 提供的 JTAG 接口，可以稳定运行在 20 MHz 的时钟频率，外接的适配器很难达到这个速度。 +上手 JTAG 最快速便捷的方式是使用 |devkit-name-with-link|，因为它板载了 JTAG 调试接口，无需使用外部的 JTAG 硬件适配器和额外的线缆来连接 JTAG 与 {IDF_TARGET_NAME}。|devkit-name| 采用 FT2232H 提供的 JTAG 接口，可以稳定运行在 20 MHz 的时钟频率，外接的适配器很难达到这个速度。 如果你想使用单独的 JTAG 适配器，请确保其与 {IDF_TARGET_NAME} 的电平电压和 OpenOCD 软件都兼容。{IDF_TARGET_NAME} 使用的是业界标准的 JTAG 接口，它省略了（实际上也并不需要）TRST 信号脚。JTAG 使用的 IO 引脚由 VDD_3P3_RTC 电源引脚供电（通常连接到外部 3.3 V 的电源轨），因此 JTAG 硬件适配器的引脚需要能够在该电压范围内正常工作。 @@ -140,35 +146,26 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G .. highlight:: bash -打开终端，按照快速入门中的指南 :ref:`设置好开发环境 ` ，然后运行如下命令，启动 OpenOCD（该命令在 Windows，Linux，和 macOS 中通用）:: +打开终端，按照快速入门中的指南 :ref:`设置好开发环境 ` ，然后运行如下命令，启动 OpenOCD（该命令在 Windows，Linux，和 macOS 中通用）: - openocd -f board/esp32-wrover-kit-3.3v.cfg + .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: run-openocd + :end-before: --- .. note:: - 上述命令中 ``-f`` 选项后跟的配置文件专用于板载 esp32-wroom-32 模组的 ESP-WROVER-KIT 开发板。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。 + 上述命令中 ``-f`` 选项后跟的配置文件专用于板载 |run-openocd-device-name|。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。 .. highlight:: none -现在应该可以看到如下输入（此日志来自 ESP-WROVER-KIT）:: +现在应该可以看到如下输入（此日志来自 |run-openocd-device-name|）: - user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32-wrover-kit-3.3v.cfg - Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04) - Licensed under GNU GPL v2 - For bug reports, read - http://openocd.org/doc/doxygen/bugs.html - none separate - adapter speed: 20000 kHz - 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: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - Info : esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). - Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F). +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: run-openocd-output + :end-before: --- - 如果出现指示权限问题的错误，请参阅 ``~/esp/openocd-esp32`` 目录下 OpenOCD README 文件中关于 “Permissions delegation” 的说明。 -- 如果发现配置文件有错误，例如 ``Can't find board/esp32-wrover-kit-3.3v.cfg``，请检查 ``-s`` 后面的路径，OpenOCD 会根据此路径来查找 ``-f`` 指定的文件。此外，还需要检查配置文件是否确实位于该路径下。 +- 如果发现配置文件有错误，例如 |run-openocd-cfg-file-err|，请检查 ``-s`` 后面的路径，OpenOCD 会根据此路径来查找 ``-f`` 指定的文件。此外，还需要检查配置文件是否确实位于该路径下。 - 如果看到 JTAG 错误（输出全是 1 或者全是 0），请检查硬件连接，除了 {IDF_TARGET_NAME} 的引脚之外是否还有其他信号连接到了 JTAG，并查看是否所有器件都已经上电。 @@ -179,9 +176,11 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 您可以像往常一样构建并上传 {IDF_TARGET_NAME} 应用程序，具体请参阅 :ref:`get-started-build` 章节。 -除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下:: +除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下: - openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000 verify exit" +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: run-openocd-upload + :end-before: --- 其中 OpenOCD 的烧写命令 ``program_esp`` 具有以下格式： @@ -250,23 +249,31 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G .. highlight:: bash -如果要使用本地从源代码编译的 OpenOCD 程序，需要将相应可执行文件的路径修改为 ``src/openocd``，并设置 ``OPENOCD_SCRIPTS`` 环境变量，这样 OpenOCD 才能找到配置文件。Linux 和 macOS 用户可以执行:: +如果要使用本地从源代码编译的 OpenOCD 程序，需要将相应可执行文件的路径修改为 ``src/openocd``，并设置 ``OPENOCD_SCRIPTS`` 环境变量，这样 OpenOCD 才能找到配置文件。Linux 和 macOS 用户可以执行: + +.. code-block:: bash cd ~/esp/openocd-esp32 export OPENOCD_SCRIPTS=$PWD/tcl -Windows 用户可以执行:: +Windows 用户可以执行: + +.. code-block:: batch cd %USERPROFILE%\esp\openocd-esp32 set "OPENOCD_SCRIPTS=%CD%\tcl" -运行本地编译的 OpenOCD 的示例如下（Linux 和 macOS 用户）:: +运行本地编译的 OpenOCD 的示例如下（Linux 和 macOS 用户）: - src/openocd -f board/esp32-wrover-kit-3.3v.cfg +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: run-openocd-src-linux + :end-before: --- -Windows 用户:: +Windows 用户: - src\openocd -f board\esp32-wrover-kit-3.3v.cfg +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: run-openocd-src-win + :end-before: --- .. _jtag-debugging-tips-and-quirks: diff --git a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst index 2f63ba2cdb..1f61c14408 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst @@ -27,7 +27,7 @@ 为了在闪存中设置或者清除软件断点，OpenOCD 需要知道它们在闪存中的地址。为了完成从 {IDF_TARGET_NAME} 的地址空间到闪存地址的转换，OpenOCD 使用闪存中程序代码区域的映射。这些映射被保存在程序映像的头部，位于二进制数据（代码段和数据段）之前，并且特定于写入闪存的每一个应用程序的映像。因此，为了支持软件闪存断点，OpenOCD 需要知道待调试的应用程序映像在闪存中的位置。默认情况下，OpenOCD 会在 0x8000 处读取分区表并使用第一个找到的应用程序映像的映射，但是也可能会存在无法工作的情况，比如分区表不在标准的闪存位置，甚至可能有多个映像：一个出厂映像和两个 OTA 映像，你可能想要调试其中的任意一个。为了涵盖所有可能的调试情况，OpenOCD 支持特殊的命令，用于指定待调试的应用程序映像在闪存中的具体位置。该命令具有以下格式： -``esp32 appimage_offset `` +``esp appimage_offset `` 偏移量应为十六进制格式，如果要恢复默认行为，可以将偏移地址设置为 ``-1`` 。 @@ -35,7 +35,9 @@ 由于 GDB 在连接 OpenOCD 时仅仅请求一次内存映射，所以可以在 TCL 配置文件中指定该命令，或者通过命令行传递给 OpenOCD。对于后者，命令行示例如下： - ``openocd -f board/esp32-wrover-kit-3.3v.cfg -c "init; halt; esp32 appimage_offset 0x210000"`` + .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: run-openocd-appimage-offset + :end-before: --- 另外还可以通过 OpenOCD 的 telnet 会话执行该命令，然后再连接 GDB， 不过这种方式似乎没有那么便捷。 @@ -76,9 +78,9 @@ OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRT ESP32 的 MTDI 引脚是用于 JTAG 通信的四个引脚之一，同时也是 ESP32 的 bootstrapping 引脚。上电时，ESP32 会在 MTDI 引脚上采样二进制电平，据此来设置内部的稳压器，用于给外部的 SPI 闪存芯片供电。如果上电时 MTDI 引脚上的二进制电平为低电平，则稳压器会被设置为 3.3 V；如果 MTDI 引脚为高电平，则稳压器会被设置为 1.8 V。MTDI 引脚通常需要一个上拉电阻或者直接使能内部的弱下拉电阻（详见 `ESP32 系列芯片技术规格书 `_ ），具体取决于所使用的 SPI 芯片的类型。但是一旦连接上 JTAG 后，原来用于实现 bootstrapping 功能的上拉或者下拉电阻都会被覆盖掉。 - 为了解决这个问题，OpenOCD 的板级配置文件（例如 ESP32-WROOM-32 模组的 ``boards\esp-wroom-32.cfg``）提供了 ``ESP32_FLASH_VOLTAGE`` 参数来设置 ``TDO`` 信号线在空闲状态下的二进制电平，这样就可以减少由于闪存电压不正确而导致的应用程序启动不良的几率。 + 为了解决这个问题，OpenOCD 的板级配置文件（例如 ESP-WROVER-KIT 开发板的 ``board\esp32-wrover-kit-3.3v.cfg``）提供了 ``ESP32_FLASH_VOLTAGE`` 参数来设置 ``TDO`` 信号线在空闲状态下的二进制电平，这样就可以减少由于闪存电压不正确而导致的应用程序启动不良的几率。 - 查看 JTAG 连接的 ESP32 模组的规格书，检查其 SPI 闪存芯片的供电电压值，然后再相应的设置 ``ESP32_FLASH_VOLTAGE``。大多数的 WROOM 模组使用 3.3 V 的闪存芯片，但是 WROVER 模组使用 1.8 V 的闪存芯片。 + 查看 JTAG 连接的 ESP32 模组的规格书，检查其 SPI 闪存芯片的供电电压值，然后再相应的设置 ``ESP32_FLASH_VOLTAGE``。大多数WROOM模块使用 3.3 V 的闪存芯片。 早于 ESP32-WROVER-B 的 WROVER 模块使用 1.8 V 闪存芯片，而ESP32-WROVER-B和-E模块使用 3.3 V 闪存芯片。 .. _jtag-debugging-tip-optimize-jtag-speed: @@ -113,93 +115,68 @@ OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRT .. _jtag-debugging-tip-openocd-configure-target: -针对特定目标的 OpenOCD 配置 -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configuration of OpenOCD for specific target +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -OpenOCD 需要知道当前使用的 JTAG 适配器的类型，以及其连接的目标板和处理器的类型。为此，请使用位于 OpenOCD 安装目录下 ``share/openocd/scripts/interface`` 和 ``share/openocd/scripts/board`` 文件夹中现有的配置文件。 +There are several kinds of OpenOCD configuration files (``*.cfg``). All configuration files are located in subdirectories of ``share/openocd/scripts`` directory of OpenOCD distribution (or ``tcl/scripts`` directory of the source repository). For the purposes of this guide, the most important ones are ``board``, ``interface`` and ``target``. -例如，如果使用板载 ESP-WROOM-32 模组的 ESP-WROVER-KIT 开发板，请使用以下配置文件： +* ``interface`` configuration files describe the JTAG adapter. Examples of JTAG adapters are ESP-Prog and J-Link. +* ``target`` configuration files describe specific chips, or in some cases, modules. +* ``board`` configuration files are provided for development boards with a built-in JTAG adapter. Such files include an ``interface`` configuration file to choose the adapter, and ``target`` configuration file to choose the chip/module. -* ``board/esp32-wrover-kit-3.3v.cfg`` +The following configuration files are available for {IDF_TARGET_NAME}: -当然也可以使用自定义的配置文件，建议在已有配置文件的基础上进行修改，以匹配你的硬件。下面列举一些常用的板级配置参数。 +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: openocd-cfg-files + :end-before: --- -.. highlight:: none +If you are using one of the boards which have a pre-defined configuration file, you only need to pass one ``-f`` argument to OpenOCD, specifying that file. -适配器的时钟速度 -"""""""""""""""" +If you are using a board not listed here, you need to specify both the interface configuration file and target configuration file. -:: +Custom configuration files +"""""""""""""""""""""""""" - adapter_khz 20000 +OpenOCD configuration files are written in TCL, and include a variety of choices for customization and scripting. This can be useful for non-standard debugging situations. Please refer to `OpenOCD Manual`_ for the TCL scripting reference. -请参阅 :ref:`jtag-debugging-tip-optimize-jtag-speed` 以获取有关如何设置此值的指导。 +.. _jtag-debugging-tip-openocd-config-vars: +OpenOCD configuration variables +""""""""""""""""""""""""""""""" -.. only:: esp32 +The following variables can be optionally set before including the ESP-specific target configuration file. This can be done either in a custom configuration file, or from the command line. - 单核调试 - """""""" +The syntax for setting a variable in TCL is: - :: +.. code-block:: tcl - set ESP32_ONLYCPU 1 + set VARIABLE_NAME value - 如果是双核调试，请注释掉这一行。 +To set a variable from the command line (replace the name of .cfg file with the correct file for your board): +.. code-block:: bash -禁用 RTOS 支持 -"""""""""""""" + openocd -c 'set VARIABLE_NAME value' -f board/esp-xxxxx-kit.cfg -:: +It is important to set the variable before including the ESP-specific configuration file, otherwise the variable will not have effect. You can set multiple variables by repeating the ``-c`` option. - set ESP32_RTOS none +.. list-table:: Common ESP-related OpenOCD variables + :widths: 25 75 + :header-rows: 1 -如果要支持 RTOS， 请注释掉这一行。 + * - Variable + - Description + * - ``ESP_RTOS`` + - Set to ``none`` to disable RTOS support. In this case, thread list will not be available in GDB. Can be useful when debugging FreeRTOS itself, and stepping through the scheduler code. + * - ``ESP_FLASH_SIZE`` + - Set to ``0`` to disable Flash breakpoints support. + * - ``ESP_SEMIHOST_BASEDIR`` + - Set to the path (on the host) which will be the default directory for semihosting functions. -.. only:: esp32 - - ESP32 的 SPI 闪存芯片的电源电压 - """""""""""""""""""""""""""""""""" - - :: - - set ESP32_FLASH_VOLTAGE 1.8 - - 如果 SPI 闪存芯片的电源电压为 3.3 V， 请注释掉这一行，更多信息请参阅： :ref:`jtag-debugging-tip-code-flash-voltage`。 - - - - - ESP32 的目标配置文件 - """""""""""""""""""" - - :: - - source [find target/esp32.cfg] - - .. note:: - - 除非你熟悉 OpenOCD 内部的工作原理，否则请不要更改 ``source [find target/esp32.cfg]`` 这一行。 - - 目前 ``target/esp32.cfg`` 仍然是 ESP32 目标（esp108 和 esp32）的唯一配置文件。支持的配置矩阵如下所示： - - +---------------+---------------+---------------+ - | Dual/single | RTOS | Target used | - +===============+===============+===============+ - | dual | FreeRTOS | esp32 | - +---------------+---------------+---------------+ - | single | FreeRTOS | esp108 (*) | - +---------------+---------------+---------------+ - | dual | none | esp108 | - +---------------+---------------+---------------+ - | single | none | esp108 | - +---------------+---------------+---------------+ - - (*) — 我们计划修复此问题，并在后续提交中添加对 esp32 目标的单核调试的支持。 - - 更多信息，请查看 ``board/esp-wroom-32.cfg`` 配置文件的注释部分。 +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: openocd-target-specific-config-vars + :end-before: --- .. _jtag-debugging-tip-reset-by-debugger: @@ -217,36 +194,14 @@ OpenOCD 需要知道当前使用的 JTAG 适配器的类型，以及其连接的 如果除了 {IDF_TARGET_NAME} 模组和 JTAG 适配器之外的其他硬件也连接到了 JTAG 引脚，那么 JTAG 的操作可能会受到干扰。{IDF_TARGET_NAME} JTAG 使用以下引脚： -.. only:: esp32 - +---+----------------+-------------+ - | | ESP32 JTAG Pin | JTAG Signal | - +===+================+=============+ - | 1 | MTDO / GPIO15 | TDO | - +---+----------------+-------------+ - | 2 | MTDI / GPIO12 | TDI | - +---+----------------+-------------+ - | 3 | MTCK / GPIO13 | TCK | - +---+----------------+-------------+ - | 4 | MTMS / GPIO14 | TMS | - +---+----------------+-------------+ - -.. only:: esp32s2 - - +---+-----------------------+-------------+ - | | ESP32-S2 Pin | JTAG Signal | - +===+=======================+=============+ - | 1 | MTDO / GPIO40 | TDO | - +---+-----------------------+-------------+ - | 2 | MTDI / GPIO41 | TDI | - +---+-----------------------+-------------+ - | 3 | MTCK / GPIO39 | TCK | - +---+-----------------------+-------------+ - | 4 | MTMS / GPIO42 | TMS | - +---+-----------------------+-------------+ 如果用户应用程序更改了 JTAG 引脚的配置，JTAG 通信可能会失败。如果 OpenOCD 正确初始化（检测到两个 Tensilica 内核），但在程序运行期间失去了同步并报出大量 DTR/DIR 错误，则应用程序可能将 JTAG 引脚重新配置为其他功能或者用户忘记将 Vtar 连接到 JTAG 适配器。 +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: jtag-pins + :end-before: --- + .. highlight:: none 下面是 GDB 在应用程序进入重新配置 MTDO/GPIO15 作为输入代码后报告的一系列错误摘录:: @@ -302,23 +257,26 @@ To disable software breakpoints while using JTAG, add an extra argument ``-c 'se OpenOCD 端： - :: + .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: run-openocd-d3 + :end-before: --- - openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg + 这种方式会将日志输出到文件，但是它会阻止调试信息打印在终端上。当有大量信息需要输出的时候（比如调试等级提高到 ``-d3``）这是个不错的选择。如果你仍然希望在屏幕上看到调试日志，请改用以下命令： - 这种方式会将日志输出到文件，但是它会阻止调试信息打印在终端上。当有大量信息需要输出的时候（比如调试等级提高到 ``-d3``）这是个不错的选择。如果你仍然希望在屏幕上看到调试日志，请改用以下命令： - - :: - - openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log + .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: run-openocd-d3-tee + :end-before: --- Debugger 端： - :: + .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: run-gdb-remotelog + :end-before: --- - xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -ex "set remotelogfile gdb_log.txt" - - 也可以将命令 ``remotelogfile gdb_log.txt`` 添加到 ``gdbinit`` 文件中。 + 也可以将命令 ``remotelogfile gdb_log.txt`` 添加到 ``gdbinit`` 文件中。 4. 请将 ``openocd_log.txt`` 和 ``gdb_log.txt`` 文件附在你的问题报告中。 + + +.. _OpenOCD Manual: http://openocd.org/doc/html/index.html