From 2661c994db8addb0c5a80cb76dd72603122e60e2 Mon Sep 17 00:00:00 2001 From: Erhan Kurubas Date: Tue, 2 Sep 2025 14:05:19 +0300 Subject: [PATCH 1/2] docs(jtag): update esp32h4 jtag debugging guide --- docs/docs_not_updated/esp32h4.txt | 10 --- .../jtag-debugging/configure-other-jtag.rst | 2 +- docs/en/api-guides/jtag-debugging/esp32h4.inc | 83 ++++++++++--------- docs/en/api-guides/jtag-debugging/index.rst | 2 +- .../jtag-debugging/configure-other-jtag.rst | 2 +- .../api-guides/jtag-debugging/esp32h4.inc | 57 +++++++------ .../zh_CN/api-guides/jtag-debugging/index.rst | 2 +- 7 files changed, 81 insertions(+), 77 deletions(-) diff --git a/docs/docs_not_updated/esp32h4.txt b/docs/docs_not_updated/esp32h4.txt index c863cf2096..87fda38e8d 100644 --- a/docs/docs_not_updated/esp32h4.txt +++ b/docs/docs_not_updated/esp32h4.txt @@ -32,16 +32,6 @@ api-guides/ble/ble-qualification.rst api-guides/ble/blufi.rst api-guides/ble/ble-feature-support-status.rst api-guides/file-system-considerations.rst -api-guides/jtag-debugging/index.rst -api-guides/jtag-debugging/building-openocd-macos.rst -api-guides/jtag-debugging/debugging-examples.rst -api-guides/jtag-debugging/building-openocd-windows.rst -api-guides/jtag-debugging/configure-ft2232h-jtag.rst -api-guides/jtag-debugging/configure-other-jtag.rst -api-guides/jtag-debugging/using-debugger.rst -api-guides/jtag-debugging/building-openocd-linux.rst -api-guides/jtag-debugging/tips-and-quirks.rst -api-guides/jtag-debugging/configure-builtin-jtag.rst api-guides/wifi-security.rst api-guides/RF_calibration.rst api-guides/usb-otg-console.rst 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 a92ed3b93b..f8f2013b03 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"} +{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"} 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/esp32h4.inc b/docs/en/api-guides/jtag-debugging/esp32h4.inc index ccf972497e..dc052e06f0 100644 --- a/docs/en/api-guides/jtag-debugging/esp32h4.inc +++ b/docs/en/api-guides/jtag-debugging/esp32h4.inc @@ -11,9 +11,9 @@ :: - openocd -f board/esp32h2-builtin.cfg + openocd -f board/esp32h4-builtin.cfg -.. |run-openocd-device-name| replace:: ESP32-H2 through built-in USB connection +.. |run-openocd-device-name| replace:: ESP32-H4 through built-in USB connection --- @@ -21,28 +21,35 @@ :: - user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32h2-builtin.cfg - Open On-Chip Debugger v0.12.0-esp32-20221026-175-g0f5217b3-dirty (2023-02-02-11:32) + user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32h4-builtin.cfg + Open On-Chip Debugger v0.12.0-esp32-20250707-152-g5b64e9cc-dirty (2025-09-02-09:30) Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.html Info : only one transport option; autoselecting 'jtag' Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001 Info : esp_usb_jtag: capabilities descriptor set to 0x2000 - Warn : Transport "jtag" was already selected Info : Listening on port 6666 for tcl connections Info : Listening on port 4444 for telnet connections - Info : esp_usb_jtag: serial (60:55:F9:F7:2C:3F) + Info : esp_usb_jtag: serial (00:00:00:00:00:00) Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255 Info : clock speed 24000 kHz - Info : JTAG tap: esp32h2.cpu tap/device found: 0x00010c25 (mfg: 0x612 (Espressif Systems), part: 0x0010, ver: 0x0) - Info : datacount=2 progbufsize=16 - Info : Examined RISC-V core; found 1 harts - Info : hart 0: XLEN=32, misa=0x40903105 - Info : starting gdb server for esp32h2 on 3333 + Info : JTAG tap: esp32h4.tap0 tap/device found: 0x0001cc25 (mfg: 0x612 (Espressif Systems), part: 0x001c, ver: 0x0) + Info : [esp32h4.hp.cpu0] datacount=1 progbufsize=2 + Info : [esp32h4.hp.cpu0] Core 0 made part of halt group 1. + Info : [esp32h4.hp.cpu0] Examined RISC-V core; found 2 harts + Info : [esp32h4.hp.cpu0] XLEN=32, misa=0x40903127 + Info : [esp32h4.hp.cpu0] Examination succeed + Info : [esp32h4.hp.cpu1] datacount=1 progbufsize=2 + Info : [esp32h4.hp.cpu1] Hart unexpectedly reset! + Info : [esp32h4.hp.cpu1] Core 1 made part of halt group 1. + Info : [esp32h4.hp.cpu1] Examined RISC-V core; found 2 harts + Info : [esp32h4.hp.cpu1] XLEN=32, misa=0x40903127 + Info : [esp32h4.hp.cpu1] Examination succeed + Info : [esp32h4.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/esp32h2-builtin.cfg`` +.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32h4-builtin.cfg`` --- @@ -50,7 +57,7 @@ :: - openocd -f board/esp32h2-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit" + openocd -f board/esp32h4-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit" --- @@ -58,7 +65,7 @@ .. code-block:: bash - src/openocd -f board/esp32h2-builtin.cfg + src/openocd -f board/esp32h4-builtin.cfg --- @@ -66,13 +73,13 @@ .. code-block:: batch - src\openocd -f board/esp32h2-builtin.cfg + src\openocd -f board/esp32h4-builtin.cfg --- .. idf-py-openocd-default-cfg -.. |idf-py-def-cfg| replace:: ``-f board/esp32h2-builtin.cfg`` +.. |idf-py-def-cfg| replace:: ``-f board/esp32h4-builtin.cfg`` --- @@ -80,26 +87,26 @@ :: - openocd -f board/esp32h2-builtin.cfg -c "init; halt; esp appimage_offset 0x210000" + openocd -f board/esp32h4-builtin.cfg -c "init; halt; esp appimage_offset 0x210000" --- .. openocd-cfg-files -.. list-table:: OpenOCD configuration files for ESP32-H2 +.. list-table:: OpenOCD configuration files for ESP32-H4 :widths: 25 75 :header-rows: 1 * - Name - Description - * - ``board/esp32h2-builtin.cfg`` - - Board configuration file for ESP32-H2 through built-in USB, includes target and adapter configuration. - * - ``board/esp32h2-ftdi.cfg`` - - Board configuration file for ESP32-H2 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration. - * - ``target/esp32h2.cfg`` - - ESP32-H2 target configuration file. Can be used together with one of the ``interface/`` configuration files. + * - ``board/esp32h4-builtin.cfg`` + - Board configuration file for ESP32-H4 through built-in USB, includes target and adapter configuration. + * - ``board/esp32h4-ftdi.cfg`` + - Board configuration file for ESP32-H4 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration. + * - ``target/esp32h4.cfg`` + - ESP32-H4 target configuration file. Can be used together with one of the ``interface/`` configuration files. * - ``interface/esp_usb_jtag.cfg`` - - JTAG adapter configuration file for ESP32-H2. + - JTAG adapter configuration file for ESP32-H4. * - ``interface/ftdi/esp_ftdi.cfg`` - JTAG adapter configuration file for ESP-Prog boards. @@ -113,23 +120,23 @@ .. jtag-pins -.. list-table:: ESP32-H2 pins and JTAG signals +.. list-table:: ESP32-H4 pins and JTAG signals :widths: 25 75 :header-rows: 1 - * - ESP32-H2 Pin + * - ESP32-H4 Pin - JTAG Signal - * - MTDO / GPIO3 + * - MTDO / GPIO31 - TDO - * - MTDI / GPIO5 + * - MTDI / GPIO29 - TDI - * - MTCK / GPIO4 + * - MTCK / GPIO30 - TCK - * - MTMS / GPIO2 + * - MTMS / GPIO28 - TMS -.. |jtag-sel-gpio| replace:: GPIO25 -.. |jtag-gpio-list| replace:: GPIO2-GPIO5 +.. |jtag-sel-gpio| replace:: GPIO36 +.. |jtag-gpio-list| replace:: GPIO28-GPIO31 --- @@ -137,7 +144,7 @@ :: - openocd -l openocd_log.txt -d3 -f board/esp32h2-builtin.cfg + openocd -l openocd_log.txt -d3 -f board/esp32h4-builtin.cfg --- @@ -145,7 +152,7 @@ :: - openocd -d3 -f board/esp32h2-builtin.cfg 2>&1 | tee openocd.log + openocd -d3 -f board/esp32h4-builtin.cfg 2>&1 | tee openocd.log --- @@ -159,13 +166,13 @@ .. devkit-defs -.. |devkit-name| replace:: ESP32-H2 -.. |devkit-name-with-link| replace:: :doc:`ESP32-H2 <../../hw-reference/index>` +.. |devkit-name| replace:: ESP32-H4 +.. |devkit-name-with-link| replace:: :doc:`ESP32-H4 <../../hw-reference/index>` --- .. devkit-hw-config -* Out of the box, ESP32-H2 doesn't need any additional hardware configuration for JTAG debugging. +* Out of the box, ESP32-H4 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 a4b442917c..847e410e4a 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", 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", esp32h4="board/esp32h4-ftdi.cfg", esp32p4="board/esp32p4-ftdi.cfg", esp32c5="board/esp32c5-ftdi.cfg", esp32c61="board/esp32c61-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 2ca4d797ce..44c231d88a 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"} +{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"} 关于适配 OpenOCD 和 {IDF_TARGET_NAME} 的 JTAG 接口选择问题，请参考 :ref:`jtag-debugging-selecting-jtag-adapter` 章节。然后按照以下步骤进行设置，使其正常工作。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32h4.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32h4.inc index c66c38ec88..f08cfe308a 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/esp32h4.inc +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32h4.inc @@ -13,7 +13,7 @@ openocd -f board/esp32h4-builtin.cfg -.. |run-openocd-device-name| replace:: ESP32-H2 through built-in USB connection +.. |run-openocd-device-name| replace:: ESP32-H4 through built-in USB connection --- @@ -22,24 +22,31 @@ :: user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32h4-builtin.cfg - Open On-Chip Debugger v0.12.0-esp32-20221026-175-g0f5217b3-dirty (2023-02-02-11:32) + Open On-Chip Debugger v0.12.0-esp32-20250707-152-g5b64e9cc-dirty (2025-09-02-09:30) Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.html Info : only one transport option; autoselecting 'jtag' Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001 Info : esp_usb_jtag: capabilities descriptor set to 0x2000 - Warn : Transport "jtag" was already selected Info : Listening on port 6666 for tcl connections Info : Listening on port 4444 for telnet connections - Info : esp_usb_jtag: serial (60:55:F9:F7:2C:3F) + Info : esp_usb_jtag: serial (00:00:00:00:00:00) Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255 Info : clock speed 24000 kHz - Info : JTAG tap: esp32h4.cpu tap/device found: 0x00010c25 (mfg: 0x612 (Espressif Systems), part: 0x0010, ver: 0x0) - Info : datacount=2 progbufsize=16 - Info : Examined RISC-V core; found 1 harts - Info : hart 0: XLEN=32, misa=0x40903105 - Info : starting gdb server for esp32h4 on 3333 + Info : JTAG tap: esp32h4.tap0 tap/device found: 0x0001cc25 (mfg: 0x612 (Espressif Systems), part: 0x001c, ver: 0x0) + Info : [esp32h4.hp.cpu0] datacount=1 progbufsize=2 + Info : [esp32h4.hp.cpu0] Core 0 made part of halt group 1. + Info : [esp32h4.hp.cpu0] Examined RISC-V core; found 2 harts + Info : [esp32h4.hp.cpu0] XLEN=32, misa=0x40903127 + Info : [esp32h4.hp.cpu0] Examination succeed + Info : [esp32h4.hp.cpu1] datacount=1 progbufsize=2 + Info : [esp32h4.hp.cpu1] Hart unexpectedly reset! + Info : [esp32h4.hp.cpu1] Core 1 made part of halt group 1. + Info : [esp32h4.hp.cpu1] Examined RISC-V core; found 2 harts + Info : [esp32h4.hp.cpu1] XLEN=32, misa=0x40903127 + Info : [esp32h4.hp.cpu1] Examination succeed + Info : [esp32h4.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/esp32h4-builtin.cfg`` @@ -86,20 +93,20 @@ .. openocd-cfg-files -.. list-table:: OpenOCD configuration files for ESP32-H2 +.. list-table:: OpenOCD configuration files for ESP32-H4 :widths: 25 75 :header-rows: 1 * - Name - Description * - ``board/esp32h4-builtin.cfg`` - - Board configuration file for ESP32-H2 through built-in USB, includes target and adapter configuration. + - Board configuration file for ESP32-H4 through built-in USB, includes target and adapter configuration. * - ``board/esp32h4-ftdi.cfg`` - - Board configuration file for ESP32-H2 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration. + - Board configuration file for ESP32-H4 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration. * - ``target/esp32h4.cfg`` - - ESP32-H2 target configuration file. Can be used together with one of the ``interface/`` configuration files. + - ESP32-H4 target configuration file. Can be used together with one of the ``interface/`` configuration files. * - ``interface/esp_usb_jtag.cfg`` - - JTAG adapter configuration file for ESP32-H2. + - JTAG adapter configuration file for ESP32-H4. * - ``interface/ftdi/esp_ftdi.cfg`` - JTAG adapter configuration file for ESP-Prog boards. @@ -113,23 +120,23 @@ .. jtag-pins -.. list-table:: ESP32-H2 pins and JTAG signals +.. list-table:: ESP32-H4 pins and JTAG ESP32-H4 :widths: 25 75 :header-rows: 1 - * - ESP32-H2 Pin + * - ESP32-H4 Pin - JTAG Signal - * - MTDO / GPIO3 + * - MTDO / GPIO31 - TDO - * - MTDI / GPIO5 + * - MTDI / GPIO29 - TDI - * - MTCK / GPIO4 + * - MTCK / GPIO30 - TCK - * - MTMS / GPIO2 + * - MTMS / GPIO28 - TMS -.. |jtag-sel-gpio| replace:: GPIO25 -.. |jtag-gpio-list| replace:: GPIO2-GPIO5 +.. |jtag-sel-gpio| replace:: GPIO36 +.. |jtag-gpio-list| replace:: GPIO28-GPIO31 --- @@ -159,13 +166,13 @@ .. devkit-defs -.. |devkit-name| replace:: ESP32-H2 -.. |devkit-name-with-link| replace:: :doc:`ESP32-H2 <../../hw-reference/index>` +.. |devkit-name| replace:: ESP32-H4 +.. |devkit-name-with-link| replace:: :doc:`ESP32-H4 <../../hw-reference/index>` --- .. devkit-hw-config -* Out of the box, ESP32-H2 doesn't need any additional hardware configuration for JTAG debugging. +* Out of the box, ESP32-H4 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 796cf4fbcf..a9343d7c1a 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", 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", esp32h4="board/esp32h4-ftdi.cfg", esp32p4="board/esp32p4-ftdi.cfg", esp32c5="board/esp32c5-ftdi.cfg", esp32c61="board/esp32c61-ftdi.cfg"} .. note:: From fa472d0e41dd0cc77cff9a505d1f03efb8ad61d4 Mon Sep 17 00:00:00 2001 From: Erhan Kurubas Date: Tue, 2 Sep 2025 15:01:26 +0300 Subject: [PATCH 2/2] docs(coredump): update docs_not_updated for esp32h4 --- docs/docs_not_updated/esp32h4.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/docs_not_updated/esp32h4.txt b/docs/docs_not_updated/esp32h4.txt index 87fda38e8d..f881860689 100644 --- a/docs/docs_not_updated/esp32h4.txt +++ b/docs/docs_not_updated/esp32h4.txt @@ -1,11 +1,9 @@ index.rst api-guides/openthread.rst -api-guides/core_dump_internals.rst api-guides/wifi-expansion.rst api-guides/deep-sleep-stub.rst api-guides/app_trace.rst api-guides/esp-wifi-mesh.rst -api-guides/core_dump.rst api-guides/lwip.rst api-guides/esp-ble-mesh/ble-mesh-faq.rst api-guides/esp-ble-mesh/ble-mesh-feature-list.rst