docs: jtag-debugging: update Chinese version

Author: igrr

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 功能。
-
-2.  检查 ESP32 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+    :start-after: devkit-hw-config
+    :end-before: ---
 
-    +---+---------------+-----------+
-    |   | 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 并且为其安装驱动。如果驱动没有被自动安装，请前往 `官网 <https://www.ftdichip.com/Drivers/D2XX.htm>`_ 下载并手动安装。
+2.  等待 Windows 识别出 |devkit-name| 并且为其安装驱动。如果驱动没有被自动安装，请前往 `官网 <https://www.ftdichip.com/Drivers/D2XX.htm>`_ 下载并手动安装。
 
 3.  从 `Zadig 官网 <http://zadig.akeo.ie/>`_ 下载 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 官网 <https://www.ftdichip.com/Drivers/VCP.htm>`_ 安装驱动。
 
-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 脚本中。
 

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 的工作。
 

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" <all other options>
+
+---
+
+.. 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 功能。
+
+---