Merge branch 'doc/esp32c2_jtag' into 'master'

docs: update JTAG related information for ESP32-C2 Closes IDF-4327 See merge request espressif/esp-idf!18496
Asc91 · Jul 19, 2022 · de3990f · de3990f
2 parents 394a195 + 2ce10d4
commit de3990f
Show file tree

Hide file tree

Showing 5 changed files with 42 additions and 58 deletions.
diff --git a/docs/docs_not_updated/esp32c2.txt b/docs/docs_not_updated/esp32c2.txt
@@ -1,13 +1,3 @@
-api-guides/jtag-debugging/debugging-examples
-api-guides/jtag-debugging/configure-ft2232h-jtag
-api-guides/jtag-debugging/tips-and-quirks
-api-guides/jtag-debugging/using-debugger
-api-guides/jtag-debugging/building-openocd-macos
-api-guides/jtag-debugging/building-openocd-linux
-api-guides/jtag-debugging/configure-other-jtag
-api-guides/jtag-debugging/building-openocd-windows
-api-guides/jtag-debugging/index
-api-guides/jtag-debugging/configure-builtin-jtag
 api-guides/blufi
 api-guides/lwip
 api-guides/esp-ble-mesh/ble-mesh-index

diff --git a/docs/en/api-guides/jtag-debugging/esp32c2.inc b/docs/en/api-guides/jtag-debugging/esp32c2.inc
@@ -11,9 +11,9 @@
 
 ::
 
-    openocd -f board/esp32c2-BOARD_NAME.cfg
+    openocd -f board/esp32c2-ftdi.cfg
 
-.. |run-openocd-device-name| replace:: ESP32C2
+.. |run-openocd-device-name| replace:: ESP32-C2 development board with ESP-Prog
 
 ---
 
@@ -23,51 +23,51 @@
 
     CHIP SPECIFIC LOG OUTPUT
 
-.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32c2-BOARD_NAME.cfg``
+.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32c2-ftdi.cfg``
 
 ---
 
 .. run-openocd-upload
 
 ::
 
-    openocd -f board/esp32c2-BOARD_NAME.cfg -c "program_esp filename.bin 0x10000 verify exit"
+    openocd -f board/esp32c2-ftdi.cfg -c "program_esp filename.bin 0x10000 verify exit"
 
 ---
 
 .. run-openocd-src-linux
 
 .. code-block:: bash
 
-    src/openocd -f board/esp32c2-BOARD_NAME.cfg
+    src/openocd -f board/esp32c2-ftdi.cfg
 
 ---
 
 .. run-openocd-src-win
 
 .. code-block:: batch
 
-    src\openocd -f board/esp32c2-BOARD_NAME.cfg
+    src\openocd -f board/esp32c2-ftdi.cfg
 
 ---
 
 .. idf-py-openocd-default-cfg
 
-.. |idf-py-def-cfg| replace:: ``-f board/esp32c2-BOARD_NAME.cfg``
+.. |idf-py-def-cfg| replace:: ``-f board/esp32c2-ftdi.cfg``
 
 ---
 
 .. run-openocd-appimage-offset
 
 ::
 
-    openocd -f board/esp32c2-BOARD_NAME.cfg -c "init; halt; esp appimage_offset 0x210000"
+    openocd -f board/esp32c2-ftdi.cfg -c "init; halt; esp appimage_offset 0x210000"
 
 ---
 
 .. openocd-cfg-files
 
-.. list-table:: OpenOCD configuration files for ESP32C2
+.. list-table:: OpenOCD configuration files for ESP32-C2
     :widths: 25 75
     :header-rows: 1
 
@@ -86,39 +86,36 @@
 
 .. jtag-pins
 
-.. list-table:: ESP32C2 pins and JTAG signals
+.. list-table:: ESP32-C2 pins and JTAG signals
     :widths: 25 75
     :header-rows: 1
 
-    * - ESP32C2 Pin
+    * - ESP32-C2 Pin
       - JTAG Signal
-    * - MTDO / GPIOX
+    * - MTDO / GPIO7
       - TDO
-    * - MTDI / GPIOX
+    * - MTDI / GPIO5
       - TDI
-    * - MTCK / GPIOX
+    * - MTCK / GPIO6
       - TCK
-    * - MTMS / GPIOX
+    * - MTMS / GPIO4
       - TMS
 
-.. |jtag-sel-gpio| replace:: GPIOX
-.. |jtag-gpio-list| replace:: GPIOX
-
 ---
 
 .. run-openocd-d3
 
 ::
 
-    openocd -l openocd_log.txt -d3 -f board/esp32c2-BOARD_NAME.cfg
+    openocd -l openocd_log.txt -d3 -f board/esp32c2-ftdi.cfg
 
 ---
 
 .. run-openocd-d3-tee
 
 ::
 
-    openocd -d3 -f board/esp32c2-BOARD_NAME.cfg 2>&1 | tee openocd.log
+    openocd -d3 -f board/esp32c2-ftdi.cfg 2>&1 | tee openocd.log
 
 ---
 
@@ -132,8 +129,8 @@
 
 .. devkit-defs
 
-.. |devkit-name| replace:: ESP32C2
-.. |devkit-name-with-link| replace:: LINK TO DEVKIT
+.. |devkit-name| replace:: There is no ESP32-C2 devkit with FT2232H
+.. |devkit-name-with-link| replace:: add a link here if such a devkit is added.
 
 ---
 

diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst
@@ -66,7 +66,7 @@ Likewise, the "Application Loading and Monitoring" label indicates the key softw
 
 "Debugging With JTAG" and "Application Loading and Monitoring" is integrated under the `Eclipse <https://www.eclipse.org/>`_ IDE in order to provide a quick and easy transition between writing/compiling/loading/debugging code. The Eclipse IDE (and the integrated debugging software) is available for Windows, Linux and macOS platforms. Depending on user preferences, both the debugger and ``idf.py build`` can also be used directly from terminal/command line, instead of Eclipse.
 
-.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED
+.. only:: esp32 or esp32s2
 
     If the |devkit-name-with-link| is used, then connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the other for UART connection.
 
@@ -85,7 +85,7 @@ Likewise, the "Application Loading and Monitoring" label indicates the key softw
 Selecting JTAG Adapter
 ----------------------
 
-.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED
+.. only:: esp32 or esp32s2
 
     The quickest and most convenient way to start with JTAG debugging is by using |devkit-name-with-link|. Each version of this development board has JTAG interface already built in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. |devkit-name| is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
 

diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32c2.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32c2.inc
@@ -11,9 +11,9 @@
 
 ::
 
-    openocd -f board/esp32c2-BOARD_NAME.cfg
+    openocd -f board/esp32c2-ftdi.cfg
 
-.. |run-openocd-device-name| replace:: ESP32C2
+.. |run-openocd-device-name| replace:: ESP32-C2 development board with ESP-Prog
 
 ---
 
@@ -23,51 +23,51 @@
 
     CHIP SPECIFIC LOG OUTPUT
 
-.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32c2-BOARD_NAME.cfg``
+.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32c2-ftdi.cfg``
 
 ---
 
 .. run-openocd-upload
 
 ::
 
-    openocd -f board/esp32c2-BOARD_NAME.cfg -c "program_esp filename.bin 0x10000 verify exit"
+    openocd -f board/esp32c2-ftdi.cfg -c "program_esp filename.bin 0x10000 verify exit"
 
 ---
 
 .. run-openocd-src-linux
 
 .. code-block:: bash
 
-    src/openocd -f board/esp32c2-BOARD_NAME.cfg
+    src/openocd -f board/esp32c2-ftdi.cfg
 
 ---
 
 .. run-openocd-src-win
 
 .. code-block:: batch
 
-    src\openocd -f board/esp32c2-BOARD_NAME.cfg
+    src\openocd -f board/esp32c2-ftdi.cfg
 
 ---
 
 .. idf-py-openocd-default-cfg
 
-.. |idf-py-def-cfg| replace:: ``-f board/esp32c2-BOARD_NAME.cfg``
+.. |idf-py-def-cfg| replace:: ``-f board/esp32c2-ftdi.cfg``
 
 ---
 
 .. run-openocd-appimage-offset
 
 ::
 
-    openocd -f board/esp32c2-BOARD_NAME.cfg -c "init; halt; esp appimage_offset 0x210000"
+    openocd -f board/esp32c2-ftdi.cfg -c "init; halt; esp appimage_offset 0x210000"
 
 ---
 
 .. openocd-cfg-files
 
-.. list-table:: OpenOCD configuration files for ESP32C2
+.. list-table:: OpenOCD configuration files for ESP32-C2
     :widths: 25 75
     :header-rows: 1
 
@@ -86,39 +86,36 @@
 
 .. jtag-pins
 
-.. list-table:: ESP32C2 pins and JTAG signals
+.. list-table:: ESP32-C2 pins and JTAG signals
     :widths: 25 75
     :header-rows: 1
 
-    * - ESP32C2 Pin
+    * - ESP32-C2 Pin
       - JTAG Signal
-    * - MTDO / GPIOX
+    * - MTDO / GPIO7
       - TDO
-    * - MTDI / GPIOX
+    * - MTDI / GPIO5
       - TDI
-    * - MTCK / GPIOX
+    * - MTCK / GPIO6
       - TCK
-    * - MTMS / GPIOX
+    * - MTMS / GPIO4
       - TMS
 
-.. |jtag-sel-gpio| replace:: GPIOX
-.. |jtag-gpio-list| replace:: GPIOX
-
 ---
 
 .. run-openocd-d3
 
 ::
 
-    openocd -l openocd_log.txt -d3 -f board/esp32c2-BOARD_NAME.cfg
+    openocd -l openocd_log.txt -d3 -f board/esp32c2-ftdi.cfg
 
 ---
 
 .. run-openocd-d3-tee
 
 ::
 
-    openocd -d3 -f board/esp32c2-BOARD_NAME.cfg 2>&1 | tee openocd.log
+    openocd -d3 -f board/esp32c2-ftdi.cfg 2>&1 | tee openocd.log
 
 ---
 
@@ -132,8 +129,8 @@
 
 .. devkit-defs
 
-.. |devkit-name| replace:: ESP32C2
-.. |devkit-name-with-link| replace:: LINK TO DEVKIT
+.. |devkit-name| replace:: There is no ESP32-C2 devkit with FT2232H
+.. |devkit-name-with-link| replace:: add a link here if such a devkit is added.
 
 ---
 

diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst
@@ -66,7 +66,7 @@ JTAG 调试
 
 `Eclipse <https://www.eclipse.org/>`__ 环境集成了 JTAG 调试和应用程序加载、监视的功能，使得软件从编写、编译、加载到调试的迭代过程变得更加快速简单。Eclipse IDE 及其集成的调试软件均适用于 Windows、Linux 和 macOS 平台。根据用户喜好，除了使用 Eclipse 集成开发环境，还可以直接在命令行终端运行 `debugger` 和 `idf.py build`。
 
-.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED
+.. only:: esp32 or esp32s2
 
     若使用 |devkit-name-with-link|，由于其板载 FT232H 芯片，仅需一根 USB 线即可连接 PC 与 {IDF_TARGET_NAME}。FT232H 提供了两路 USB 通道，一路连接到 JTAG，另一路连接到 UART。
 
@@ -85,7 +85,7 @@ JTAG 调试
 选择 JTAG 适配器
 ----------------
 
-.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED
+.. only:: esp32 or esp32s2
 
     上手 JTAG 最快速便捷的方式是使用 |devkit-name-with-link|，因为它板载了 JTAG 调试接口，无需使用外部 JTAG 硬件适配器和额外线缆来连接 JTAG 与 {IDF_TARGET_NAME}。|devkit-name| 采用 FT2232H 提供的 JTAG 接口，可以稳定运行在 20 MHz 的时钟频率，外接的适配器很难达到这个速度。