From e6a94e982c6c0565d877181f5ef3f297443e74c5 Mon Sep 17 00:00:00 2001 From: morris Date: Thu, 16 Jul 2020 19:24:52 +0800 Subject: [PATCH] docs: translate idf.py debug target --- docs/en/api-guides/jtag-debugging/esp32.inc | 6 +-- docs/en/api-guides/jtag-debugging/esp32s2.inc | 2 +- .../jtag-debugging/configure-ft2232h-jtag.rst | 12 ++--- .../zh_CN/api-guides/jtag-debugging/esp32.inc | 30 ++++++------- .../api-guides/jtag-debugging/esp32s2.inc | 16 +++---- .../zh_CN/api-guides/jtag-debugging/index.rst | 6 +-- .../jtag-debugging/using-debugger.rst | 44 +++++++++++++++++++ 7 files changed, 81 insertions(+), 35 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/esp32.inc b/docs/en/api-guides/jtag-debugging/esp32.inc index f558b05f2c..61976011df 100644 --- a/docs/en/api-guides/jtag-debugging/esp32.inc +++ b/docs/en/api-guides/jtag-debugging/esp32.inc @@ -88,11 +88,11 @@ * - 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 configuration file for 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 configuration file for 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. + - Board configuration file for 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`` diff --git a/docs/en/api-guides/jtag-debugging/esp32s2.inc b/docs/en/api-guides/jtag-debugging/esp32s2.inc index c161a919f9..aba480e688 100644 --- a/docs/en/api-guides/jtag-debugging/esp32s2.inc +++ b/docs/en/api-guides/jtag-debugging/esp32s2.inc @@ -80,7 +80,7 @@ .. openocd-cfg-files -.. list-table:: OpenOCD configuration files for ESP32 +.. list-table:: OpenOCD configuration files for ESP32-S2 :widths: 25 75 :header-rows: 1 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 69542ef790..396daae397 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 @@ -16,11 +16,11 @@ :start-after: devkit-hw-config :end-before: --- -2. 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。 +* 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。 -.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc - :start-after: jtag-pins - :end-before: --- + .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: jtag-pins + :end-before: --- 配置 USB 驱动 ^^^^^^^^^^^^^ @@ -118,7 +118,9 @@ MacOS 4. 运行 OpenOCD:: - openocd -f board/esp32-wrover-kit-3.3v.cfg + .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: run-openocd + :end-before: --- 5. 在另一个终端窗口，再一次加载 FTDI 串口驱动:: diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32.inc index e7c16c888a..63690ed853 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/esp32.inc +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32.inc @@ -14,7 +14,7 @@ openocd -f board/esp32-wrover-kit-3.3v.cfg -.. |run-openocd-device-name| replace:: ESP32-WROOM-32 模组的 ESP-WROVER-KIT 开发板 +.. |run-openocd-device-name| replace:: 板载 ESP32-WROOM-32 模组的 ESP-WROVER-KIT 开发板 --- @@ -81,39 +81,39 @@ .. openocd-cfg-files -.. list-table:: OpenOCD configuration files for ESP32 +.. list-table:: ESP32 相关的 OpenOCD 配置文件 :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. + - 板载 3.3V 模组（ESP32-WROOM-32，ESP32-WROVER-B，ESP32-WROVER-E）的 ESP-WROVER-KIT 开发板配置文件 * - ``board/esp32-wrover-kit-1.8v.cfg`` - - ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module. + - 板载 1.8V 模组（ESP32-WROVER）的 ESP-WROVER-KIT 开发板配置文件 * - ``board/esp32-ethernet-kit-3.3v.cfg`` - - ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module. + - 板载 3.3V 模组（ESP32-WROVER-B / ESP32-WROVER-E）的 ESP-Ethernet-KIT 开发板配置文件 * - ``target/esp32.cfg`` - - ESP32 target configuration file. Can be used together with one of the ``interface/`` configuration files. + - ESP32 的目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用 * - ``target/esp32-solo-1.cfg`` - - Target configuration file for ESP32-SOLO-1 module. Different from ``esp32.cfg`` in that it only configures one CPU. + - ESP32-SOLO-1 的目标配置文件，和 ``esp32.cfg`` 的差别在于它仅配置一个 CPU * - ``interface/ftdi/esp32_devkitj_v1.cfg`` - - JTAG adapter configuration file for ESP-WROVER-KIT and ESP-Prog boards. + - 适用于 ESP-WROVER-KIT 和 ESP-Prog 板子的 JTAG 适配器配置文件 --- .. openocd-target-specific-config-vars -.. list-table:: ESP32-specific OpenOCD variables +.. list-table:: ESP32 相关的 OpenOCD 变量 :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 模组集成的是 1.8 V 的 Flash，将该变量设置为 ``1.8``，详情请参考 :ref:`jtag-debugging-tip-code-flash-voltage` * - ``ESP32_ONLYCPU`` - - For multi-core targets, can be set to ``1`` to only enable single core debugging. + - 对于多核芯片，将该值设置为 ``1`` 可以仅启用单核调试功能 --- diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc index 49d3403713..8863c522e4 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc @@ -80,20 +80,20 @@ .. openocd-cfg-files -.. list-table:: OpenOCD configuration files for ESP32 +.. list-table:: ESP32-S2 相关的 OpenOCD 配置文件 :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. + - ESP32-S2-Kaluga-1 开发板配置文件，内部已包含 ESP32-S2 目标配置和 JTAG 适配器配置 * - ``target/esp32s2.cfg`` - - ESP32-S2 target configuration file. Can be used together with one of the ``interface/`` configuration files. + - ESP32-S2 目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用 * - ``interface/ftdi/esp32s2_kaluga_v1.cfg`` - - JTAG adapter configuration file for ESP32-S2-Kaluga-1 board. + - 适用于 ESP32-S2-Kaluga-1 开发板的 JTAG 适配器配置文件 * - ``interface/ftdi/esp32_devkitj_v1.cfg`` - - JTAG adapter configuration file for ESP-Prog boards. + - 适用于 ESP-Prog 板子的 JTAG 适配器配置文件 --- @@ -155,6 +155,6 @@ .. devkit-hw-config -* *开箱即用，ESP32-S2-Kaluga-1 不需要任何其他硬件配置即可进行 JTAG 调试。 但是，如果遇到问题，请检查 “JTAG” DIP 开关块的开关 2-5 是否在 “ON” 位置。 +* 开箱即用，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 5c2f287f5b..9211ab7c64 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -45,7 +45,7 @@ JTAG 调试 本文将指导如何在 Linux，Windows 和 MacOS 环境下为 {IDF_TARGET_NAME} 安装 OpenOCD，并使用 GDB 进行软件调试。除了个别操作系统的安装过程有所差别以外，软件用户界面和使用流程都是一样的。 .. note:: - 本文使用的图片素材来自于 Ubuntu 16.04 LTE 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows， MacOS 或者 Linux）和 Eclipse 软件版本在用户界面上可能会有细微的差别。 + 本文使用的图片素材来自于 Ubuntu 16.04 LTS 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows， MacOS 或者 Linux）和 Eclipse 软件版本在用户界面上可能会有细微的差别。 .. _jtag-debugging-how-it-works: @@ -148,13 +148,13 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 打开终端，按照快速入门中的指南 :ref:`设置好开发环境 ` ，然后运行如下命令，启动 OpenOCD（该命令在 Windows，Linux，和 macOS 中通用）: - .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc +.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc :start-after: run-openocd :end-before: --- .. note:: - 上述命令中 ``-f`` 选项后跟的配置文件专用于板载 |run-openocd-device-name|。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。 + 上述命令中 ``-f`` 选项后跟的配置文件专用于 |run-openocd-device-name|。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。 .. highlight:: none diff --git a/docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst b/docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst index ee0c751cc5..ce725fe9db 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst @@ -188,3 +188,47 @@ 注意上面日志的倒数第三行显示了调试器已经在 ``app_main()`` 函数的断点处停止，该断点在 ``gdbinit`` 文件中设定。由于处理器已经暂停运行，LED 也不会闪烁。如果这也是你看到的现象，你可以开始调试了。 如果你不太了解 GDB 的常用方法，请查阅 :ref:`jtag-debugging-examples-command-line` 文章中的调试示例章节 :ref:`jtag-debugging-examples`。 + + +.. _jtag-debugging-with-idf-py: + +使用 idf.py 进行调试 +^^^^^^^^^^^^^^^^^^^^ + +我们还可以使用 ``idf.py`` 更方便地执行上述提到的调试命令： + +1. ``idf.py openocd`` + + 在终端中运行 OpenOCD，其配置信息来源于环境变量或者命令行。默认会使用 ``OPENOCD_SCRIPTS`` 环境变量中指定的脚本路径，它是由 ESP-IDF 项目仓库中的导出脚本（``export.sh`` or ``export.bat``）添加到系统环境变量中的。 + 当然，我们可以在命令行中通过 ``--openocd-scripts`` 来覆盖这个变量的值。 + + .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :start-after: idf-py-openocd-default-cfg + :end-before: --- + + 你可以定义 ``OPENOCD_COMMANDS`` 环境变量来指定当前开发板的 JTAG 配置，或者通过 ``--openocd-commands`` 传递该参数。如果这两者都没有被定义，那么 OpenOCD 会使用 |idf-py-def-cfg| 参数来启动。 + + +2. ``idf.py gdb`` + + 根据当前项目的 elf 文件自动生成 gdb 启动脚本， 然后会按照 :ref:`jtag-debugging-using-debugger-command-line` 中所描述的步骤启动 GDB。 + + +3. ``idf.py gdbtui`` + + 和步骤 2 相同，但是会在启动 GDB 的时候传递 ``tui`` 参数，这样可以方便在调试过程中查看源代码。 + + +4. ``idf.py gdbgui`` + + 启动 `gdbgui `_，在浏览器中打开调试器的前端界面。 + + + 上述这些命令也可以合并到一起使用，``idf.py`` 会自动将后台进程（比如 openocd）最先运行，交互式进程（比图 gdb， monitor）最后运行。 + + 常用的组合命令如下所示:: + + idf.py openocd gdbgui monitor + + + 上述命令会将 OpenOCD 运行至后台，然后启动 `gdbgui `_ 打开一个浏览器窗口，显示调试器的前端界面，最后在活动终端打开串口监视器。