docs: translate idf.py debug target

2025-07-31 03:07:21 +02:00 · 2020-07-16 19:24:52 +08:00
parent a3eb4d85d4
commit e6a94e982c
7 changed files with 81 additions and 35 deletions
--- 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``
--- 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

--- 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 串口驱动::

--- 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`` 可以仅启用单核调试功能

 ---

--- 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” 的位置。

 ---
--- 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:`设置好开发环境 <get-started-set-up-env>` ，然后运行如下命令，启动 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

--- 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 <https://www.gdbgui.com>`_，在浏览器中打开调试器的前端界面。
+
+
+    上述这些命令也可以合并到一起使用，``idf.py`` 会自动将后台进程（比如 openocd）最先运行，交互式进程（比图 gdb， monitor）最后运行。
+
+    常用的组合命令如下所示::
+
+        idf.py openocd gdbgui monitor
+
+
+    上述命令会将 OpenOCD 运行至后台，然后启动 `gdbgui <https://www.gdbgui.com>`_ 打开一个浏览器窗口，显示调试器的前端界面，最后在活动终端打开串口监视器。