From a02b87da569e3e14e32d57226b321a52d986adf6 Mon Sep 17 00:00:00 2001 From: Samuel Obuch Date: Tue, 28 Apr 2026 12:19:23 +0200 Subject: [PATCH] docs(jtag-debugging): update esp32s31 documentation --- .../jtag-debugging/configure-other-jtag.rst | 2 +- docs/en/api-guides/jtag-debugging/esp32s3.inc | 2 +- .../en/api-guides/jtag-debugging/esp32s31.inc | 54 +++++++++++-------- docs/en/api-guides/jtag-debugging/index.rst | 2 +- .../jtag-debugging/configure-other-jtag.rst | 2 +- .../api-guides/jtag-debugging/esp32h21.inc | 2 +- .../api-guides/jtag-debugging/esp32s3.inc | 2 +- .../api-guides/jtag-debugging/esp32s31.inc | 54 +++++++++++-------- .../zh_CN/api-guides/jtag-debugging/index.rst | 2 +- 9 files changed, 69 insertions(+), 53 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst index 5200a1d7689..3c04a0b6f51 100644 --- a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst +++ b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst @@ -3,7 +3,7 @@ Configure Other JTAG Interfaces :link_to_translation:`zh_CN:[中文]` -{IDF_TARGET_JTAG_SEL_EFUSE:default="Not Updated!", esp32s3="STRAP_JTAG_SEL", esp32c6="JTAG_SEL_ENABLE", esp32h2="JTAG_SEL_ENABLE", esp32p4="JTAG_SEL_ENABLE", esp32c5="JTAG_SEL_ENABLE", esp32c61="JTAG_SEL_ENABLE", esp32h4="JTAG_SEL_ENABLE", esp32h21="JTAG_SEL_ENABLE"} +{IDF_TARGET_JTAG_SEL_EFUSE:default="Not Updated!", esp32s3="STRAP_JTAG_SEL", esp32c6="JTAG_SEL_ENABLE", esp32h2="JTAG_SEL_ENABLE", esp32p4="JTAG_SEL_ENABLE", esp32c5="JTAG_SEL_ENABLE", esp32c61="JTAG_SEL_ENABLE", esp32h4="JTAG_SEL_ENABLE", esp32h21="JTAG_SEL_ENABLE", esp32s31="JTAG_SEL_ENABLE"} For guidance about which JTAG interface to select when using OpenOCD with {IDF_TARGET_NAME}, refer to the section :ref:`jtag-debugging-selecting-jtag-adapter`. Then follow the configuration steps below to get it working. diff --git a/docs/en/api-guides/jtag-debugging/esp32s3.inc b/docs/en/api-guides/jtag-debugging/esp32s3.inc index 49e3cdc6653..dfaee3faf9c 100644 --- a/docs/en/api-guides/jtag-debugging/esp32s3.inc +++ b/docs/en/api-guides/jtag-debugging/esp32s3.inc @@ -99,7 +99,7 @@ - Board configuration file for ESP32-S3 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration. * - ``target/esp32s3.cfg`` - ESP32-S3 target configuration file. Can be used together with one of the ``interface/`` configuration files. - * - ``interface/ftdi/esp_usb_jtag.cfg`` + * - ``interface/esp_usb_jtag.cfg`` - JTAG adapter configuration file for ESP32-S3 builtin USB JTAG. * - ``interface/ftdi/esp_ftdi.cfg`` - JTAG adapter configuration file for ESP-Prog debug adapter board. diff --git a/docs/en/api-guides/jtag-debugging/esp32s31.inc b/docs/en/api-guides/jtag-debugging/esp32s31.inc index bc8005c6388..b724526d33c 100644 --- a/docs/en/api-guides/jtag-debugging/esp32s31.inc +++ b/docs/en/api-guides/jtag-debugging/esp32s31.inc @@ -23,24 +23,32 @@ :: user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s31-builtin.cfg - Open On-Chip Debugger v0.10.0-esp32-20210902 (2021-10-05-23:44) + Open On-Chip Debugger v0.12.0-esp32-20260424 (2026-04-24-15:13) Licensed under GNU GPL v2 For bug reports, read - https://openocd.org/doc/doxygen/bugs.html - debug_level: 2 - - Info : only one transport option; autoselect 'jtag' - Warn : Transport "jtag" was already selected + http://openocd.org/doc/doxygen/bugs.html + Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001 + Info : esp_usb_jtag: capabilities descriptor set to 0x2000 Info : Listening on port 6666 for tcl connections Info : Listening on port 4444 for telnet connections - Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255 - Info : clock speed 40000 kHz - Info : JTAG tap: esp32s31.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - Info : JTAG tap: esp32s31.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - Info : esp32s31.cpu0: Debug controller was reset. - Info : esp32s31.cpu0: Core was reset. - Info : esp32s31.cpu1: Debug controller was reset. - Info : esp32s31.cpu1: Core was reset. + Info : esp_usb_jtag: serial (30:ED:A0:ED:77:E4) + Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255 + Info : clock speed 24000 kHz + Info : JTAG tap: esp32s31.tap0 tap/device found: 0x00003c25 (mfg: 0x612 (Espressif Systems), part: 0x0003, ver: 0x0) + Info : JTAG tap: esp32s31.tap1 tap/device found: 0x00020c25 (mfg: 0x612 (Espressif Systems), part: 0x0020, ver: 0x0) + Info : [esp32s31.hp.cpu0] datacount=1 progbufsize=2 + Info : [esp32s31.hp.cpu0] Core 0 made part of halt group 1. + Info : [esp32s31.hp.cpu0] Examined RISC-V core + Info : [esp32s31.hp.cpu0] XLEN=32, misa=0x40943127 + Info : [esp32s31.hp.cpu0] Chip revision v0.0 + Info : [esp32s31.hp.cpu0] Examination succeed + Info : [esp32s31.hp.cpu1] datacount=1 progbufsize=2 + Info : [esp32s31.hp.cpu1] Core 1 made part of halt group 1. + Info : [esp32s31.hp.cpu1] Examined RISC-V core + Info : [esp32s31.hp.cpu1] XLEN=32, misa=0x40943127 + Info : [esp32s31.hp.cpu1] Chip revision v0.0 + Info : [esp32s31.hp.cpu1] Examination succeed + Info : [esp32s31.hp.cpu0] starting gdb server on 3333 Info : Listening on port 3333 for gdb connections .. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s31-builtin.cfg`` @@ -99,7 +107,7 @@ - Board configuration file for ESP32-S31 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration. * - ``target/esp32s31.cfg`` - ESP32-S31 target configuration file. Can be used together with one of the ``interface/`` configuration files. - * - ``interface/ftdi/esp_usb_jtag.cfg`` + * - ``interface/esp_usb_jtag.cfg`` - JTAG adapter configuration file for ESP32-S31 builtin USB JTAG. * - ``interface/ftdi/esp_ftdi.cfg`` - JTAG adapter configuration file for ESP-Prog debug adapter board. @@ -120,17 +128,17 @@ * - ESP32-S31 Pin - JTAG Signal - * - MTDO / GPIO40 + * - MTDO / GPIO54 - TDO - * - MTDI / GPIO41 + * - MTDI / GPIO56 - TDI - * - MTCK / GPIO39 + * - MTCK / GPIO55 - TCK - * - MTMS / GPIO42 + * - MTMS / GPIO57 - TMS -.. |jtag-sel-gpio| replace:: GPIO3 -.. |jtag-gpio-list| replace:: GPIO39-GPIO42 +.. |jtag-sel-gpio| replace:: GPIO37 +.. |jtag-gpio-list| replace:: GPIO54-GPIO57 --- @@ -154,7 +162,7 @@ :: - xtensa-esp32s31-elf-gdb -ex "set remotelogfile gdb_log.txt" + riscv32-esp-elf-gdb -ex "set remotelogfile gdb_log.txt" --- @@ -167,6 +175,6 @@ .. devkit-hw-config -* Out of the box, ESP32-S31 doesn't need any additional hardware configuration for JTAG debugging. However if you are experiencing issues, check that switches 2-5 of the "JTAG" DIP switch block are in "ON" position. +* Out of the box, ESP32-S31 doesn't need any additional hardware configuration for JTAG debugging. --- diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst index 206c1b66945..d14ea70062f 100644 --- a/docs/en/api-guides/jtag-debugging/index.rst +++ b/docs/en/api-guides/jtag-debugging/index.rst @@ -184,7 +184,7 @@ Open a terminal and set it up for using the ESP-IDF as described in the :ref:`se :start-after: run-openocd :end-before: --- -{IDF_TARGET_FTDI_CONFIG:default="Not Updated!", esp32s3="board/esp32s3-ftdi.cfg", esp32c3="board/esp32c3-ftdi.cfg", esp32c6="board/esp32c6-ftdi.cfg", esp32h2="board/esp32h2-ftdi.cfg", esp32h21="board/esp32h21-ftdi.cfg", esp32h4="board/esp32h4-ftdi.cfg", esp32p4="board/esp32p4-ftdi.cfg", esp32c5="board/esp32c5-ftdi.cfg", esp32c61="board/esp32c61-ftdi.cfg"} +{IDF_TARGET_FTDI_CONFIG:default="Not Updated!", esp32s3="board/esp32s3-ftdi.cfg", esp32c3="board/esp32c3-ftdi.cfg", esp32c6="board/esp32c6-ftdi.cfg", esp32h2="board/esp32h2-ftdi.cfg", esp32h21="board/esp32h21-ftdi.cfg", esp32h4="board/esp32h4-ftdi.cfg", esp32p4="board/esp32p4-ftdi.cfg", esp32c5="board/esp32c5-ftdi.cfg", esp32c61="board/esp32c61-ftdi.cfg", esp32s31="board/esp32s31-ftdi.cfg} .. note:: diff --git a/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst b/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst index 3b1a30d6a66..c8a3903fe0d 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst @@ -3,7 +3,7 @@ :link_to_translation:`en:[English]` -{IDF_TARGET_JTAG_SEL_EFUSE:default="Not Updated!", esp32s3="STRAP_JTAG_SEL", esp32c6="JTAG_SEL_ENABLE", esp32h2="JTAG_SEL_ENABLE", esp32p4="JTAG_SEL_ENABLE", esp32c5="JTAG_SEL_ENABLE", esp32c61="JTAG_SEL_ENABLE", esp32h4="JTAG_SEL_ENABLE", esp32h21="JTAG_SEL_ENABLE"} +{IDF_TARGET_JTAG_SEL_EFUSE:default="Not Updated!", esp32s3="STRAP_JTAG_SEL", esp32c6="JTAG_SEL_ENABLE", esp32h2="JTAG_SEL_ENABLE", esp32p4="JTAG_SEL_ENABLE", esp32c5="JTAG_SEL_ENABLE", esp32c61="JTAG_SEL_ENABLE", esp32h4="JTAG_SEL_ENABLE", esp32h21="JTAG_SEL_ENABLE", esp32s31="JTAG_SEL_ENABLE"} 关于适配 OpenOCD 和 {IDF_TARGET_NAME} 的 JTAG 接口选择问题，请参考 :ref:`jtag-debugging-selecting-jtag-adapter` 章节。然后按照以下步骤进行设置，使其正常工作。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32h21.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32h21.inc index d24aeeb839b..84d2bc94575 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/esp32h21.inc +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32h21.inc @@ -158,7 +158,7 @@ .. devkit-defs -.. |devkit-name| replace:: ESP32-H1 +.. |devkit-name| replace:: ESP32-H21 .. |devkit-name-with-link| replace:: :doc:`ESP32-H21 <../../hw-reference/index>` --- diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc index 79d3f2dac88..d0b18c4c7b1 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc @@ -99,7 +99,7 @@ - ESP32-S3 系列开发板的配置文件，用于通过外部连接的基于 FTDI 的探头，如 ESP-Prog，包括 ESP32-S3 目标配置和适配器配置。 * - ``target/esp32s3.cfg`` - ESP32-S3 目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用 - * - ``interface/ftdi/esp_usb_jtag.cfg`` + * - ``interface/esp_usb_jtag.cfg`` - 适用于 ESP32-S3 的 JTAG 适配器配置文件。 * - ``interface/ftdi/esp_ftdi.cfg`` - 适用于 ESP-Prog 的 JTAG 适配器配置文件。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32s31.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32s31.inc index bc8005c6388..b724526d33c 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/esp32s31.inc +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32s31.inc @@ -23,24 +23,32 @@ :: user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s31-builtin.cfg - Open On-Chip Debugger v0.10.0-esp32-20210902 (2021-10-05-23:44) + Open On-Chip Debugger v0.12.0-esp32-20260424 (2026-04-24-15:13) Licensed under GNU GPL v2 For bug reports, read - https://openocd.org/doc/doxygen/bugs.html - debug_level: 2 - - Info : only one transport option; autoselect 'jtag' - Warn : Transport "jtag" was already selected + http://openocd.org/doc/doxygen/bugs.html + Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001 + Info : esp_usb_jtag: capabilities descriptor set to 0x2000 Info : Listening on port 6666 for tcl connections Info : Listening on port 4444 for telnet connections - Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255 - Info : clock speed 40000 kHz - Info : JTAG tap: esp32s31.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - Info : JTAG tap: esp32s31.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - Info : esp32s31.cpu0: Debug controller was reset. - Info : esp32s31.cpu0: Core was reset. - Info : esp32s31.cpu1: Debug controller was reset. - Info : esp32s31.cpu1: Core was reset. + Info : esp_usb_jtag: serial (30:ED:A0:ED:77:E4) + Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255 + Info : clock speed 24000 kHz + Info : JTAG tap: esp32s31.tap0 tap/device found: 0x00003c25 (mfg: 0x612 (Espressif Systems), part: 0x0003, ver: 0x0) + Info : JTAG tap: esp32s31.tap1 tap/device found: 0x00020c25 (mfg: 0x612 (Espressif Systems), part: 0x0020, ver: 0x0) + Info : [esp32s31.hp.cpu0] datacount=1 progbufsize=2 + Info : [esp32s31.hp.cpu0] Core 0 made part of halt group 1. + Info : [esp32s31.hp.cpu0] Examined RISC-V core + Info : [esp32s31.hp.cpu0] XLEN=32, misa=0x40943127 + Info : [esp32s31.hp.cpu0] Chip revision v0.0 + Info : [esp32s31.hp.cpu0] Examination succeed + Info : [esp32s31.hp.cpu1] datacount=1 progbufsize=2 + Info : [esp32s31.hp.cpu1] Core 1 made part of halt group 1. + Info : [esp32s31.hp.cpu1] Examined RISC-V core + Info : [esp32s31.hp.cpu1] XLEN=32, misa=0x40943127 + Info : [esp32s31.hp.cpu1] Chip revision v0.0 + Info : [esp32s31.hp.cpu1] Examination succeed + Info : [esp32s31.hp.cpu0] starting gdb server on 3333 Info : Listening on port 3333 for gdb connections .. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s31-builtin.cfg`` @@ -99,7 +107,7 @@ - Board configuration file for ESP32-S31 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration. * - ``target/esp32s31.cfg`` - ESP32-S31 target configuration file. Can be used together with one of the ``interface/`` configuration files. - * - ``interface/ftdi/esp_usb_jtag.cfg`` + * - ``interface/esp_usb_jtag.cfg`` - JTAG adapter configuration file for ESP32-S31 builtin USB JTAG. * - ``interface/ftdi/esp_ftdi.cfg`` - JTAG adapter configuration file for ESP-Prog debug adapter board. @@ -120,17 +128,17 @@ * - ESP32-S31 Pin - JTAG Signal - * - MTDO / GPIO40 + * - MTDO / GPIO54 - TDO - * - MTDI / GPIO41 + * - MTDI / GPIO56 - TDI - * - MTCK / GPIO39 + * - MTCK / GPIO55 - TCK - * - MTMS / GPIO42 + * - MTMS / GPIO57 - TMS -.. |jtag-sel-gpio| replace:: GPIO3 -.. |jtag-gpio-list| replace:: GPIO39-GPIO42 +.. |jtag-sel-gpio| replace:: GPIO37 +.. |jtag-gpio-list| replace:: GPIO54-GPIO57 --- @@ -154,7 +162,7 @@ :: - xtensa-esp32s31-elf-gdb -ex "set remotelogfile gdb_log.txt" + riscv32-esp-elf-gdb -ex "set remotelogfile gdb_log.txt" --- @@ -167,6 +175,6 @@ .. devkit-hw-config -* Out of the box, ESP32-S31 doesn't need any additional hardware configuration for JTAG debugging. However if you are experiencing issues, check that switches 2-5 of the "JTAG" DIP switch block are in "ON" position. +* Out of the box, ESP32-S31 doesn't need any additional hardware configuration for JTAG debugging. --- diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index f8225ebaee5..31634f804e1 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -184,7 +184,7 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG :start-after: run-openocd :end-before: --- -{IDF_TARGET_FTDI_CONFIG:default="Not Updated!", esp32s3="board/esp32s3-ftdi.cfg", esp32c3="board/esp32c3-ftdi.cfg", esp32c6="board/esp32c6-ftdi.cfg", esp32h2="board/esp32h2-ftdi.cfg", esp32h21="board/esp32h21-ftdi.cfg", esp32h4="board/esp32h4-ftdi.cfg", esp32p4="board/esp32p4-ftdi.cfg", esp32c5="board/esp32c5-ftdi.cfg", esp32c61="board/esp32c61-ftdi.cfg"} +{IDF_TARGET_FTDI_CONFIG:default="Not Updated!", esp32s3="board/esp32s3-ftdi.cfg", esp32c3="board/esp32c3-ftdi.cfg", esp32c6="board/esp32c6-ftdi.cfg", esp32h2="board/esp32h2-ftdi.cfg", esp32h21="board/esp32h21-ftdi.cfg", esp32h4="board/esp32h4-ftdi.cfg", esp32p4="board/esp32p4-ftdi.cfg", esp32c5="board/esp32c5-ftdi.cfg", esp32c61="board/esp32c61-ftdi.cfg, esp32s31="board/esp32s31-ftdi.cfg"} .. note::