Skip to content

Commit e6a94e9

Browse files
suda-morrisigrr
suda-morris
authored and
igrr
committed
docs: translate idf.py debug target
1 parent a3eb4d8 commit e6a94e9

File tree

7 files changed

+81
-35
lines changed

7 files changed

+81
-35
lines changed

‎docs/en/api-guides/jtag-debugging/esp32.inc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -88,11 +88,11 @@
8888
* - Name
8989
- Description
9090
* - ``board/esp32-wrover-kit-3.3v.cfg``
91-
- ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32 module or ESP32-WROVER-B / ESP32-WROVER-E module.
91+
- Board configuration file for ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32 module or ESP32-WROVER-B / ESP32-WROVER-E module.
9292
* - ``board/esp32-wrover-kit-1.8v.cfg``
93-
- ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module.
93+
- Board configuration file for ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module.
9494
* - ``board/esp32-ethernet-kit-3.3v.cfg``
95-
- ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module.
95+
- Board configuration file for ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module.
9696
* - ``target/esp32.cfg``
9797
- ESP32 target configuration file. Can be used together with one of the ``interface/`` configuration files.
9898
* - ``target/esp32-solo-1.cfg``

‎docs/en/api-guides/jtag-debugging/esp32s2.inc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@
8080

8181
.. openocd-cfg-files
8282

83-
.. list-table:: OpenOCD configuration files for ESP32
83+
.. list-table:: OpenOCD configuration files for ESP32-S2
8484
:widths: 25 75
8585
:header-rows: 1
8686

‎docs/zh_CN/api-guides/jtag-debugging/configure-ft2232h-jtag.rst

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,11 @@
1616
:start-after: devkit-hw-config
1717
:end-before: ---
1818

19-
2. 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。
19+
* 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。
2020

21-
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
22-
:start-after: jtag-pins
23-
:end-before: ---
21+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
22+
:start-after: jtag-pins
23+
:end-before: ---
2424

2525
配置 USB 驱动
2626
^^^^^^^^^^^^^
@@ -118,7 +118,9 @@ MacOS
118118

119119
4. 运行 OpenOCD::
120120

121-
openocd -f board/esp32-wrover-kit-3.3v.cfg
121+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
122+
:start-after: run-openocd
123+
:end-before: ---
122124

123125
5. 在另一个终端窗口，再一次加载 FTDI 串口驱动::
124126

‎docs/zh_CN/api-guides/jtag-debugging/esp32.inc

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
1515
openocd -f board/esp32-wrover-kit-3.3v.cfg
1616
17-
.. |run-openocd-device-name| replace:: ESP32-WROOM-32 模组的 ESP-WROVER-KIT 开发板
17+
.. |run-openocd-device-name| replace:: 板载 ESP32-WROOM-32 模组的 ESP-WROVER-KIT 开发板
1818
1919
---
2020
@@ -81,39 +81,39 @@
8181

8282
.. openocd-cfg-files
8383

84-
.. list-table:: OpenOCD configuration files for ESP32
84+
.. list-table:: ESP32 相关的 OpenOCD 配置文件
8585
:widths: 25 75
8686
:header-rows: 1
8787

88-
* - Name
89-
- Description
88+
* - 名字
89+
- 描述
9090
* - ``board/esp32-wrover-kit-3.3v.cfg``
91-
- ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32 module or ESP32-WROVER-B / ESP32-WROVER-E module.
91+
- 板载 3.3V 模组（ESP32-WROOM-32，ESP32-WROVER-B，ESP32-WROVER-E）的 ESP-WROVER-KIT 开发板配置文件
9292
* - ``board/esp32-wrover-kit-1.8v.cfg``
93-
- ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module.
93+
- 板载 1.8V 模组（ESP32-WROVER）的 ESP-WROVER-KIT 开发板配置文件
9494
* - ``board/esp32-ethernet-kit-3.3v.cfg``
95-
- ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module.
95+
- 板载 3.3V 模组（ESP32-WROVER-B / ESP32-WROVER-E）的 ESP-Ethernet-KIT 开发板配置文件
9696
* - ``target/esp32.cfg``
97-
- ESP32 target configuration file. Can be used together with one of the ``interface/`` configuration files.
97+
- ESP32 的目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用
9898
* - ``target/esp32-solo-1.cfg``
99-
- Target configuration file for ESP32-SOLO-1 module. Different from ``esp32.cfg`` in that it only configures one CPU.
99+
- ESP32-SOLO-1 的目标配置文件，和 ``esp32.cfg`` 的差别在于它仅配置一个 CPU
100100
* - ``interface/ftdi/esp32_devkitj_v1.cfg``
101-
- JTAG adapter configuration file for ESP-WROVER-KIT and ESP-Prog boards.
101+
- 适用于 ESP-WROVER-KIT 和 ESP-Prog 板子的 JTAG 适配器配置文件
102102

103103
---
104104

105105
.. openocd-target-specific-config-vars
106106

107-
.. list-table:: ESP32-specific OpenOCD variables
107+
.. list-table:: ESP32 相关的 OpenOCD 变量
108108
:widths: 25 75
109109
:header-rows: 1
110110

111-
* - Name
112-
- Description
111+
* - 名字
112+
- 描述
113113
* - ``ESP32_FLASH_VOLTAGE``
114-
- When using 1.8 V flash ESP32 based modules, set this variable to ``1.8``. Refer to :ref:`jtag-debugging-tip-code-flash-voltage`.
114+
- 如果 ESP32 模组集成的是 1.8 V 的 Flash，将该变量设置为 ``1.8``，详情请参考 :ref:`jtag-debugging-tip-code-flash-voltage`
115115
* - ``ESP32_ONLYCPU``
116-
- For multi-core targets, can be set to ``1`` to only enable single core debugging.
116+
- 对于多核芯片，将该值设置为 ``1`` 可以仅启用单核调试功能
117117

118118
---
119119

‎docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -80,20 +80,20 @@
8080

8181
.. openocd-cfg-files
8282

83-
.. list-table:: OpenOCD configuration files for ESP32
83+
.. list-table:: ESP32-S2 相关的 OpenOCD 配置文件
8484
:widths: 25 75
8585
:header-rows: 1
8686

87-
* - Name
88-
- Description
87+
* - 名字
88+
- 描述
8989
* - ``board/esp32s2-kaluga-1.cfg``
90-
- Board configuration file for ESP32-S2-Kaluga-1, includes target and adapter configuration.
90+
- ESP32-S2-Kaluga-1 开发板配置文件，内部已包含 ESP32-S2 目标配置和 JTAG 适配器配置
9191
* - ``target/esp32s2.cfg``
92-
- ESP32-S2 target configuration file. Can be used together with one of the ``interface/`` configuration files.
92+
- ESP32-S2 目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用
9393
* - ``interface/ftdi/esp32s2_kaluga_v1.cfg``
94-
- JTAG adapter configuration file for ESP32-S2-Kaluga-1 board.
94+
- 适用于 ESP32-S2-Kaluga-1 开发板的 JTAG 适配器配置文件
9595
* - ``interface/ftdi/esp32_devkitj_v1.cfg``
96-
- JTAG adapter configuration file for ESP-Prog boards.
96+
- 适用于 ESP-Prog 板子的 JTAG 适配器配置文件
9797

9898
---
9999

@@ -155,6 +155,6 @@
155155

156156
.. devkit-hw-config
157157

158-
* *开箱即用，ESP32-S2-Kaluga-1 不需要任何其他硬件配置即可进行 JTAG 调试。 但是，如果遇到问题，请检查 “JTAG” DIP 开关块的开关 2-5 是否在 “ON” 位置。
158+
* 开箱即用，ESP32-S2-Kaluga-1 不需要任何其他硬件配置即可进行 JTAG 调试。 但是，如果遇到问题，请检查 “JTAG” DIP 开关的 2～5 号是否在 “ON” 的位置。
159159

160160
---

‎docs/zh_CN/api-guides/jtag-debugging/index.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ JTAG 调试
4545
本文将指导如何在 Linux，Windows 和 MacOS 环境下为 {IDF_TARGET_NAME} 安装 OpenOCD，并使用 GDB 进行软件调试。除了个别操作系统的安装过程有所差别以外，软件用户界面和使用流程都是一样的。
4646

4747
.. note::
48-
本文使用的图片素材来自于 Ubuntu 16.04 LTE 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows， MacOS 或者 Linux）和 Eclipse 软件版本在用户界面上可能会有细微的差别。
48+
本文使用的图片素材来自于 Ubuntu 16.04 LTS 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows， MacOS 或者 Linux）和 Eclipse 软件版本在用户界面上可能会有细微的差别。
4949

5050
.. _jtag-debugging-how-it-works:
5151

@@ -148,13 +148,13 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
148148

149149
打开终端，按照快速入门中的指南 :ref:`设置好开发环境 <get-started-set-up-env>` ，然后运行如下命令，启动 OpenOCD（该命令在 Windows，Linux，和 macOS 中通用）:
150150

151-
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
151+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
152152
:start-after: run-openocd
153153
:end-before: ---
154154

155155
.. note::
156156

157-
上述命令中 ``-f`` 选项后跟的配置文件专用于板载 |run-openocd-device-name|。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。
157+
上述命令中 ``-f`` 选项后跟的配置文件专用于 |run-openocd-device-name|。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。
158158

159159
.. highlight:: none
160160

‎docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,3 +188,47 @@
188188
注意上面日志的倒数第三行显示了调试器已经在 ``app_main()`` 函数的断点处停止，该断点在 ``gdbinit`` 文件中设定。由于处理器已经暂停运行，LED 也不会闪烁。如果这也是你看到的现象，你可以开始调试了。
189189

190190
如果你不太了解 GDB 的常用方法，请查阅 :ref:`jtag-debugging-examples-command-line` 文章中的调试示例章节 :ref:`jtag-debugging-examples`。
191+
192+
193+
.. _jtag-debugging-with-idf-py:
194+
195+
使用 idf.py 进行调试
196+
^^^^^^^^^^^^^^^^^^^^
197+
198+
我们还可以使用 ``idf.py`` 更方便地执行上述提到的调试命令：
199+
200+
1. ``idf.py openocd``
201+
202+
在终端中运行 OpenOCD，其配置信息来源于环境变量或者命令行。默认会使用 ``OPENOCD_SCRIPTS`` 环境变量中指定的脚本路径，它是由 ESP-IDF 项目仓库中的导出脚本（``export.sh`` or ``export.bat``）添加到系统环境变量中的。
203+
当然，我们可以在命令行中通过 ``--openocd-scripts`` 来覆盖这个变量的值。
204+
205+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
206+
:start-after: idf-py-openocd-default-cfg
207+
:end-before: ---
208+
209+
你可以定义 ``OPENOCD_COMMANDS`` 环境变量来指定当前开发板的 JTAG 配置，或者通过 ``--openocd-commands`` 传递该参数。如果这两者都没有被定义，那么 OpenOCD 会使用 |idf-py-def-cfg| 参数来启动。
210+
211+
212+
2. ``idf.py gdb``
213+
214+
根据当前项目的 elf 文件自动生成 gdb 启动脚本， 然后会按照 :ref:`jtag-debugging-using-debugger-command-line` 中所描述的步骤启动 GDB。
215+
216+
217+
3. ``idf.py gdbtui``
218+
219+
和步骤 2 相同，但是会在启动 GDB 的时候传递 ``tui`` 参数，这样可以方便在调试过程中查看源代码。
220+
221+
222+
4. ``idf.py gdbgui``
223+
224+
启动 `gdbgui <https://www.gdbgui.com>`_，在浏览器中打开调试器的前端界面。
225+
226+
227+
上述这些命令也可以合并到一起使用，``idf.py`` 会自动将后台进程（比如 openocd）最先运行，交互式进程（比图 gdb， monitor）最后运行。
228+
229+
常用的组合命令如下所示::
230+
231+
idf.py openocd gdbgui monitor
232+
233+
234+
上述命令会将 OpenOCD 运行至后台，然后启动 `gdbgui <https://www.gdbgui.com>`_ 打开一个浏览器窗口，显示调试器的前端界面，最后在活动终端打开串口监视器。

0 commit comments

Comments
 (0)