espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-10-02 18:10:57 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'docs/update_esp32h4_jtag_debugging' into 'master'

Browse Source 
docs: update esp32h4 debugging docs (jtag + coredump)

Closes IDF-12954 and IDF-12958

See merge request espressif/esp-idf!41696
This commit is contained in:
Alexey Gerenkov
2025-09-11 18:22:18 +08:00
parent b72bbfdec9 fa472d0e41
commit ffad794b02
7 changed files with 81 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/docs_not_updated/esp32h4.txt
View File

@@ -1,11 +1,9 @@
index.rst index.rst
api-guides/openthread.rst api-guides/openthread.rst
api-guides/core_dump_internals.rst
api-guides/wifi-expansion.rst api-guides/wifi-expansion.rst
api-guides/deep-sleep-stub.rst api-guides/deep-sleep-stub.rst
api-guides/app_trace.rst api-guides/app_trace.rst
api-guides/esp-wifi-mesh.rst api-guides/esp-wifi-mesh.rst
api-guides/core_dump.rst
api-guides/lwip.rst api-guides/lwip.rst
api-guides/esp-ble-mesh/ble-mesh-faq.rst api-guides/esp-ble-mesh/ble-mesh-faq.rst
api-guides/esp-ble-mesh/ble-mesh-feature-list.rst api-guides/esp-ble-mesh/ble-mesh-feature-list.rst
@@ -32,16 +30,6 @@ api-guides/ble/ble-qualification.rst
api-guides/ble/blufi.rst api-guides/ble/blufi.rst
api-guides/ble/ble-feature-support-status.rst api-guides/ble/ble-feature-support-status.rst
api-guides/file-system-considerations.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/wifi-security.rst
api-guides/RF_calibration.rst api-guides/RF_calibration.rst
api-guides/usb-otg-console.rst api-guides/usb-otg-console.rst

2
docs/en/api-guides/jtag-debugging/configure-other-jtag.rst
View File

@@ -3,7 +3,7 @@ Configure Other JTAG Interfaces
:link_to_translation:`zh_CN:[中文]` :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. 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.

83
docs/en/api-guides/jtag-debugging/esp32h4.inc
View File

@@ -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 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 Licensed under GNU GPL v2
For bug reports, read For bug reports, read
http://openocd.org/doc/doxygen/bugs.html http://openocd.org/doc/doxygen/bugs.html
Info : only one transport option; autoselecting 'jtag' Info : only one transport option; autoselecting 'jtag'
Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001 Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
Info : esp_usb_jtag: capabilities descriptor set to 0x2000 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 6666 for tcl connections
Info : Listening on port 4444 for telnet 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 : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
Info : clock speed 24000 kHz Info : clock speed 24000 kHz
Info : JTAG tap: esp32h2.cpu tap/device found: 0x00010c25 (mfg: 0x612 (Espressif Systems), part: 0x0010, ver: 0x0) Info : JTAG tap: esp32h4.tap0 tap/device found: 0x0001cc25 (mfg: 0x612 (Espressif Systems), part: 0x001c, ver: 0x0)
Info : datacount=2 progbufsize=16 Info : [esp32h4.hp.cpu0] datacount=1 progbufsize=2
Info : Examined RISC-V core; found 1 harts Info : [esp32h4.hp.cpu0] Core 0 made part of halt group 1.
Info : hart 0: XLEN=32, misa=0x40903105 Info : [esp32h4.hp.cpu0] Examined RISC-V core; found 2 harts
Info : starting gdb server for esp32h2 on 3333 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 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 .. code-block:: bash
src/openocd -f board/esp32h2-builtin.cfg src/openocd -f board/esp32h4-builtin.cfg
--- ---
@@ -66,13 +73,13 @@
.. code-block:: batch .. code-block:: batch
src\openocd -f board/esp32h2-builtin.cfg src\openocd -f board/esp32h4-builtin.cfg
--- ---
.. idf-py-openocd-default-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 .. openocd-cfg-files
.. list-table:: OpenOCD configuration files for ESP32-H2 .. list-table:: OpenOCD configuration files for ESP32-H4
:widths: 25 75 :widths: 25 75
:header-rows: 1 :header-rows: 1
* - Name * - Name
- Description - Description
* - ``board/esp32h2-builtin.cfg`` * - ``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/esp32h2-ftdi.cfg`` * - ``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/esp32h2.cfg`` * - ``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`` * - ``interface/esp_usb_jtag.cfg``
- JTAG adapter configuration file for ESP32-H2. - JTAG adapter configuration file for ESP32-H4.
* - ``interface/ftdi/esp_ftdi.cfg`` * - ``interface/ftdi/esp_ftdi.cfg``
- JTAG adapter configuration file for ESP-Prog boards. - JTAG adapter configuration file for ESP-Prog boards.
@@ -113,23 +120,23 @@
.. jtag-pins .. jtag-pins
.. list-table:: ESP32-H2 pins and JTAG signals .. list-table:: ESP32-H4 pins and JTAG signals
:widths: 25 75 :widths: 25 75
:header-rows: 1 :header-rows: 1
* - ESP32-H2 Pin * - ESP32-H4 Pin
- JTAG Signal - JTAG Signal
* - MTDO / GPIO3 * - MTDO / GPIO31
- TDO - TDO
* - MTDI / GPIO5 * - MTDI / GPIO29
- TDI - TDI
* - MTCK / GPIO4 * - MTCK / GPIO30
- TCK - TCK
* - MTMS / GPIO2 * - MTMS / GPIO28
- TMS - TMS
.. |jtag-sel-gpio| replace:: GPIO25 .. |jtag-sel-gpio| replace:: GPIO36
.. |jtag-gpio-list| replace:: GPIO2-GPIO5 .. |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-defs
.. |devkit-name| replace:: ESP32-H2 .. |devkit-name| replace:: ESP32-H4
.. |devkit-name-with-link| replace:: :doc:`ESP32-H2 <../../hw-reference/index>` .. |devkit-name-with-link| replace:: :doc:`ESP32-H4 <../../hw-reference/index>`
--- ---
.. devkit-hw-config .. 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.
--- ---

2
docs/en/api-guides/jtag-debugging/index.rst
View File

@@ -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 :start-after: run-openocd
:end-before: --- :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:: .. note::

2
docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst
View File

@@ -3,7 +3,7 @@
:link_to_translation:`en:[English]` :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` 章节。然后按照以下步骤进行设置，使其正常工作。 关于适配 OpenOCD 和 {IDF_TARGET_NAME} 的 JTAG 接口选择问题，请参考 :ref:`jtag-debugging-selecting-jtag-adapter` 章节。然后按照以下步骤进行设置，使其正常工作。

57
docs/zh_CN/api-guides/jtag-debugging/esp32h4.inc
View File

@@ -13,7 +13,7 @@
openocd -f board/esp32h4-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
--- ---
@@ -22,24 +22,31 @@
:: ::
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32h4-builtin.cfg 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 Licensed under GNU GPL v2
For bug reports, read For bug reports, read
http://openocd.org/doc/doxygen/bugs.html http://openocd.org/doc/doxygen/bugs.html
Info : only one transport option; autoselecting 'jtag' Info : only one transport option; autoselecting 'jtag'
Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001 Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
Info : esp_usb_jtag: capabilities descriptor set to 0x2000 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 6666 for tcl connections
Info : Listening on port 4444 for telnet 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 : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
Info : clock speed 24000 kHz Info : clock speed 24000 kHz
Info : JTAG tap: esp32h4.cpu tap/device found: 0x00010c25 (mfg: 0x612 (Espressif Systems), part: 0x0010, ver: 0x0) Info : JTAG tap: esp32h4.tap0 tap/device found: 0x0001cc25 (mfg: 0x612 (Espressif Systems), part: 0x001c, ver: 0x0)
Info : datacount=2 progbufsize=16 Info : [esp32h4.hp.cpu0] datacount=1 progbufsize=2
Info : Examined RISC-V core; found 1 harts Info : [esp32h4.hp.cpu0] Core 0 made part of halt group 1.
Info : hart 0: XLEN=32, misa=0x40903105 Info : [esp32h4.hp.cpu0] Examined RISC-V core; found 2 harts
Info : starting gdb server for esp32h4 on 3333 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 Info : Listening on port 3333 for gdb connections
.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32h4-builtin.cfg`` .. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32h4-builtin.cfg``
@@ -86,20 +93,20 @@
.. openocd-cfg-files .. openocd-cfg-files
.. list-table:: OpenOCD configuration files for ESP32-H2 .. list-table:: OpenOCD configuration files for ESP32-H4
:widths: 25 75 :widths: 25 75
:header-rows: 1 :header-rows: 1
* - Name * - Name
- Description - Description
* - ``board/esp32h4-builtin.cfg`` * - ``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/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`` * - ``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`` * - ``interface/esp_usb_jtag.cfg``
- JTAG adapter configuration file for ESP32-H2. - JTAG adapter configuration file for ESP32-H4.
* - ``interface/ftdi/esp_ftdi.cfg`` * - ``interface/ftdi/esp_ftdi.cfg``
- JTAG adapter configuration file for ESP-Prog boards. - JTAG adapter configuration file for ESP-Prog boards.
@@ -113,23 +120,23 @@
.. jtag-pins .. jtag-pins
.. list-table:: ESP32-H2 pins and JTAG signals .. list-table:: ESP32-H4 pins and JTAG ESP32-H4
:widths: 25 75 :widths: 25 75
:header-rows: 1 :header-rows: 1
* - ESP32-H2 Pin * - ESP32-H4 Pin
- JTAG Signal - JTAG Signal
* - MTDO / GPIO3 * - MTDO / GPIO31
- TDO - TDO
* - MTDI / GPIO5 * - MTDI / GPIO29
- TDI - TDI
* - MTCK / GPIO4 * - MTCK / GPIO30
- TCK - TCK
* - MTMS / GPIO2 * - MTMS / GPIO28
- TMS - TMS
.. |jtag-sel-gpio| replace:: GPIO25 .. |jtag-sel-gpio| replace:: GPIO36
.. |jtag-gpio-list| replace:: GPIO2-GPIO5 .. |jtag-gpio-list| replace:: GPIO28-GPIO31
--- ---
@@ -159,13 +166,13 @@
.. devkit-defs .. devkit-defs
.. |devkit-name| replace:: ESP32-H2 .. |devkit-name| replace:: ESP32-H4
.. |devkit-name-with-link| replace:: :doc:`ESP32-H2 <../../hw-reference/index>` .. |devkit-name-with-link| replace:: :doc:`ESP32-H4 <../../hw-reference/index>`
--- ---
.. devkit-hw-config .. 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.
--- ---

2
docs/zh_CN/api-guides/jtag-debugging/index.rst
View File

@@ -184,7 +184,7 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG
:start-after: run-openocd :start-after: run-openocd
:end-before: --- :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:: .. note::