Skip to content

Commit ffad794

Browse files
gerekongerekon
committed
Merge branch 'docs/update_esp32h4_jtag_debugging' into 'master'
docs: update esp32h4 debugging docs (jtag + coredump) Closes IDF-12954 and IDF-12958 See merge request espressif/esp-idf!41696
2 parents b72bbfd + fa472d0 commit ffad794

File tree

7 files changed

+81
-79
lines changed

7 files changed

+81
-79
lines changed

‎docs/docs_not_updated/esp32h4.txt‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,9 @@
11
index.rst
22
api-guides/openthread.rst
3-
api-guides/core_dump_internals.rst
43
api-guides/wifi-expansion.rst
54
api-guides/deep-sleep-stub.rst
65
api-guides/app_trace.rst
76
api-guides/esp-wifi-mesh.rst
8-
api-guides/core_dump.rst
97
api-guides/lwip.rst
108
api-guides/esp-ble-mesh/ble-mesh-faq.rst
119
api-guides/esp-ble-mesh/ble-mesh-feature-list.rst
@@ -32,16 +30,6 @@ api-guides/ble/ble-qualification.rst
3230
api-guides/ble/blufi.rst
3331
api-guides/ble/ble-feature-support-status.rst
3432
api-guides/file-system-considerations.rst
35-
api-guides/jtag-debugging/index.rst
36-
api-guides/jtag-debugging/building-openocd-macos.rst
37-
api-guides/jtag-debugging/debugging-examples.rst
38-
api-guides/jtag-debugging/building-openocd-windows.rst
39-
api-guides/jtag-debugging/configure-ft2232h-jtag.rst
40-
api-guides/jtag-debugging/configure-other-jtag.rst
41-
api-guides/jtag-debugging/using-debugger.rst
42-
api-guides/jtag-debugging/building-openocd-linux.rst
43-
api-guides/jtag-debugging/tips-and-quirks.rst
44-
api-guides/jtag-debugging/configure-builtin-jtag.rst
4533
api-guides/wifi-security.rst
4634
api-guides/RF_calibration.rst
4735
api-guides/usb-otg-console.rst

‎docs/en/api-guides/jtag-debugging/configure-other-jtag.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ Configure Other JTAG Interfaces
33

44
:link_to_translation:`zh_CN:[中文]`
55

6-
{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"}
6+
{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"}
77

88
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.
99

‎docs/en/api-guides/jtag-debugging/esp32h4.inc‎

Lines changed: 45 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -11,95 +11,102 @@
1111
1212
::
1313
14-
openocd -f board/esp32h2-builtin.cfg
14+
openocd -f board/esp32h4-builtin.cfg
1515
16-
.. |run-openocd-device-name| replace:: ESP32-H2 through built-in USB connection
16+
.. |run-openocd-device-name| replace:: ESP32-H4 through built-in USB connection
1717
1818
---
1919
2020
.. run-openocd-output
2121
2222
::
2323
24-
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32h2-builtin.cfg
25-
Open On-Chip Debugger v0.12.0-esp32-20221026-175-g0f5217b3-dirty (2023-02-02-11:32)
24+
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32h4-builtin.cfg
25+
Open On-Chip Debugger v0.12.0-esp32-20250707-152-g5b64e9cc-dirty (2025-09-02-09:30)
2626
Licensed under GNU GPL v2
2727
For bug reports, read
2828
http://openocd.org/doc/doxygen/bugs.html
2929
Info : only one transport option; autoselecting 'jtag'
3030
Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
3131
Info : esp_usb_jtag: capabilities descriptor set to 0x2000
32-
Warn : Transport "jtag" was already selected
3332
Info : Listening on port 6666 for tcl connections
3433
Info : Listening on port 4444 for telnet connections
35-
Info : esp_usb_jtag: serial (60:55:F9:F7:2C:3F)
34+
Info : esp_usb_jtag: serial (00:00:00:00:00:00)
3635
Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
3736
Info : clock speed 24000 kHz
38-
Info : JTAG tap: esp32h2.cpu tap/device found: 0x00010c25 (mfg: 0x612 (Espressif Systems), part: 0x0010, ver: 0x0)
39-
Info : datacount=2 progbufsize=16
40-
Info : Examined RISC-V core; found 1 harts
41-
Info : hart 0: XLEN=32, misa=0x40903105
42-
Info : starting gdb server for esp32h2 on 3333
37+
Info : JTAG tap: esp32h4.tap0 tap/device found: 0x0001cc25 (mfg: 0x612 (Espressif Systems), part: 0x001c, ver: 0x0)
38+
Info : [esp32h4.hp.cpu0] datacount=1 progbufsize=2
39+
Info : [esp32h4.hp.cpu0] Core 0 made part of halt group 1.
40+
Info : [esp32h4.hp.cpu0] Examined RISC-V core; found 2 harts
41+
Info : [esp32h4.hp.cpu0] XLEN=32, misa=0x40903127
42+
Info : [esp32h4.hp.cpu0] Examination succeed
43+
Info : [esp32h4.hp.cpu1] datacount=1 progbufsize=2
44+
Info : [esp32h4.hp.cpu1] Hart unexpectedly reset!
45+
Info : [esp32h4.hp.cpu1] Core 1 made part of halt group 1.
46+
Info : [esp32h4.hp.cpu1] Examined RISC-V core; found 2 harts
47+
Info : [esp32h4.hp.cpu1] XLEN=32, misa=0x40903127
48+
Info : [esp32h4.hp.cpu1] Examination succeed
49+
Info : [esp32h4.hp.cpu0] starting gdb server on 3333
4350
Info : Listening on port 3333 for gdb connections
4451
45-
.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32h2-builtin.cfg``
52+
.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32h4-builtin.cfg``
4653

4754
---
4855

4956
.. run-openocd-upload
5057

5158
::
5259

53-
openocd -f board/esp32h2-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit"
60+
openocd -f board/esp32h4-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit"
5461

5562
---
5663

5764
.. run-openocd-src-linux
5865

5966
.. code-block:: bash
6067

61-
src/openocd -f board/esp32h2-builtin.cfg
68+
src/openocd -f board/esp32h4-builtin.cfg
6269

6370
---
6471

6572
.. run-openocd-src-win
6673

6774
.. code-block:: batch
6875

69-
src\openocd -f board/esp32h2-builtin.cfg
76+
src\openocd -f board/esp32h4-builtin.cfg
7077

7178
---
7279

7380
.. idf-py-openocd-default-cfg
7481

75-
.. |idf-py-def-cfg| replace:: ``-f board/esp32h2-builtin.cfg``
82+
.. |idf-py-def-cfg| replace:: ``-f board/esp32h4-builtin.cfg``
7683

7784
---
7885

7986
.. run-openocd-appimage-offset
8087

8188
::
8289

83-
openocd -f board/esp32h2-builtin.cfg -c "init; halt; esp appimage_offset 0x210000"
90+
openocd -f board/esp32h4-builtin.cfg -c "init; halt; esp appimage_offset 0x210000"
8491

8592
---
8693

8794
.. openocd-cfg-files
8895

89-
.. list-table:: OpenOCD configuration files for ESP32-H2
96+
.. list-table:: OpenOCD configuration files for ESP32-H4
9097
:widths: 25 75
9198
:header-rows: 1
9299

93100
* - Name
94101
- Description
95-
* - ``board/esp32h2-builtin.cfg``
96-
- Board configuration file for ESP32-H2 through built-in USB, includes target and adapter configuration.
97-
* - ``board/esp32h2-ftdi.cfg``
98-
- Board configuration file for ESP32-H2 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration.
99-
* - ``target/esp32h2.cfg``
100-
- ESP32-H2 target configuration file. Can be used together with one of the ``interface/`` configuration files.
102+
* - ``board/esp32h4-builtin.cfg``
103+
- Board configuration file for ESP32-H4 through built-in USB, includes target and adapter configuration.
104+
* - ``board/esp32h4-ftdi.cfg``
105+
- Board configuration file for ESP32-H4 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration.
106+
* - ``target/esp32h4.cfg``
107+
- ESP32-H4 target configuration file. Can be used together with one of the ``interface/`` configuration files.
101108
* - ``interface/esp_usb_jtag.cfg``
102-
- JTAG adapter configuration file for ESP32-H2.
109+
- JTAG adapter configuration file for ESP32-H4.
103110
* - ``interface/ftdi/esp_ftdi.cfg``
104111
- JTAG adapter configuration file for ESP-Prog boards.
105112

@@ -113,39 +120,39 @@
113120

114121
.. jtag-pins
115122

116-
.. list-table:: ESP32-H2 pins and JTAG signals
123+
.. list-table:: ESP32-H4 pins and JTAG signals
117124
:widths: 25 75
118125
:header-rows: 1
119126

120-
* - ESP32-H2 Pin
127+
* - ESP32-H4 Pin
121128
- JTAG Signal
122-
* - MTDO / GPIO3
129+
* - MTDO / GPIO31
123130
- TDO
124-
* - MTDI / GPIO5
131+
* - MTDI / GPIO29
125132
- TDI
126-
* - MTCK / GPIO4
133+
* - MTCK / GPIO30
127134
- TCK
128-
* - MTMS / GPIO2
135+
* - MTMS / GPIO28
129136
- TMS
130137

131-
.. |jtag-sel-gpio| replace:: GPIO25
132-
.. |jtag-gpio-list| replace:: GPIO2-GPIO5
138+
.. |jtag-sel-gpio| replace:: GPIO36
139+
.. |jtag-gpio-list| replace:: GPIO28-GPIO31
133140

134141
---
135142

136143
.. run-openocd-d3
137144

138145
::
139146

140-
openocd -l openocd_log.txt -d3 -f board/esp32h2-builtin.cfg
147+
openocd -l openocd_log.txt -d3 -f board/esp32h4-builtin.cfg
141148

142149
---
143150

144151
.. run-openocd-d3-tee
145152

146153
::
147154

148-
openocd -d3 -f board/esp32h2-builtin.cfg 2>&1 | tee openocd.log
155+
openocd -d3 -f board/esp32h4-builtin.cfg 2>&1 | tee openocd.log
149156

150157
---
151158

@@ -159,13 +166,13 @@
159166

160167
.. devkit-defs
161168

162-
.. |devkit-name| replace:: ESP32-H2
163-
.. |devkit-name-with-link| replace:: :doc:`ESP32-H2 <../../hw-reference/index>`
169+
.. |devkit-name| replace:: ESP32-H4
170+
.. |devkit-name-with-link| replace:: :doc:`ESP32-H4 <../../hw-reference/index>`
164171

165172
---
166173

167174
.. devkit-hw-config
168175

169-
* Out of the box, ESP32-H2 doesn't need any additional hardware configuration for JTAG debugging.
176+
* Out of the box, ESP32-H4 doesn't need any additional hardware configuration for JTAG debugging.
170177
171178
---

‎docs/en/api-guides/jtag-debugging/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -184,7 +184,7 @@ Open a terminal and set it up for using the ESP-IDF as described in the :ref:`se
184184
:start-after: run-openocd
185185
:end-before: ---
186186

187-
{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"}
187+
{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"}
188188

189189
.. note::
190190

‎docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
:link_to_translation:`en:[English]`
55

6-
{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"}
6+
{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"}
77

88
关于适配 OpenOCD 和 {IDF_TARGET_NAME} 的 JTAG 接口选择问题，请参考 :ref:`jtag-debugging-selecting-jtag-adapter` 章节。然后按照以下步骤进行设置，使其正常工作。
99

‎docs/zh_CN/api-guides/jtag-debugging/esp32h4.inc‎

Lines changed: 32 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
1414
openocd -f board/esp32h4-builtin.cfg
1515
16-
.. |run-openocd-device-name| replace:: ESP32-H2 through built-in USB connection
16+
.. |run-openocd-device-name| replace:: ESP32-H4 through built-in USB connection
1717
1818
---
1919
@@ -22,24 +22,31 @@
2222
::
2323
2424
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32h4-builtin.cfg
25-
Open On-Chip Debugger v0.12.0-esp32-20221026-175-g0f5217b3-dirty (2023-02-02-11:32)
25+
Open On-Chip Debugger v0.12.0-esp32-20250707-152-g5b64e9cc-dirty (2025-09-02-09:30)
2626
Licensed under GNU GPL v2
2727
For bug reports, read
2828
http://openocd.org/doc/doxygen/bugs.html
2929
Info : only one transport option; autoselecting 'jtag'
3030
Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
3131
Info : esp_usb_jtag: capabilities descriptor set to 0x2000
32-
Warn : Transport "jtag" was already selected
3332
Info : Listening on port 6666 for tcl connections
3433
Info : Listening on port 4444 for telnet connections
35-
Info : esp_usb_jtag: serial (60:55:F9:F7:2C:3F)
34+
Info : esp_usb_jtag: serial (00:00:00:00:00:00)
3635
Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
3736
Info : clock speed 24000 kHz
38-
Info : JTAG tap: esp32h4.cpu tap/device found: 0x00010c25 (mfg: 0x612 (Espressif Systems), part: 0x0010, ver: 0x0)
39-
Info : datacount=2 progbufsize=16
40-
Info : Examined RISC-V core; found 1 harts
41-
Info : hart 0: XLEN=32, misa=0x40903105
42-
Info : starting gdb server for esp32h4 on 3333
37+
Info : JTAG tap: esp32h4.tap0 tap/device found: 0x0001cc25 (mfg: 0x612 (Espressif Systems), part: 0x001c, ver: 0x0)
38+
Info : [esp32h4.hp.cpu0] datacount=1 progbufsize=2
39+
Info : [esp32h4.hp.cpu0] Core 0 made part of halt group 1.
40+
Info : [esp32h4.hp.cpu0] Examined RISC-V core; found 2 harts
41+
Info : [esp32h4.hp.cpu0] XLEN=32, misa=0x40903127
42+
Info : [esp32h4.hp.cpu0] Examination succeed
43+
Info : [esp32h4.hp.cpu1] datacount=1 progbufsize=2
44+
Info : [esp32h4.hp.cpu1] Hart unexpectedly reset!
45+
Info : [esp32h4.hp.cpu1] Core 1 made part of halt group 1.
46+
Info : [esp32h4.hp.cpu1] Examined RISC-V core; found 2 harts
47+
Info : [esp32h4.hp.cpu1] XLEN=32, misa=0x40903127
48+
Info : [esp32h4.hp.cpu1] Examination succeed
49+
Info : [esp32h4.hp.cpu0] starting gdb server on 3333
4350
Info : Listening on port 3333 for gdb connections
4451
4552
.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32h4-builtin.cfg``
@@ -86,20 +93,20 @@
8693

8794
.. openocd-cfg-files
8895

89-
.. list-table:: OpenOCD configuration files for ESP32-H2
96+
.. list-table:: OpenOCD configuration files for ESP32-H4
9097
:widths: 25 75
9198
:header-rows: 1
9299

93100
* - Name
94101
- Description
95102
* - ``board/esp32h4-builtin.cfg``
96-
- Board configuration file for ESP32-H2 through built-in USB, includes target and adapter configuration.
103+
- Board configuration file for ESP32-H4 through built-in USB, includes target and adapter configuration.
97104
* - ``board/esp32h4-ftdi.cfg``
98-
- Board configuration file for ESP32-H2 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration.
105+
- Board configuration file for ESP32-H4 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration.
99106
* - ``target/esp32h4.cfg``
100-
- ESP32-H2 target configuration file. Can be used together with one of the ``interface/`` configuration files.
107+
- ESP32-H4 target configuration file. Can be used together with one of the ``interface/`` configuration files.
101108
* - ``interface/esp_usb_jtag.cfg``
102-
- JTAG adapter configuration file for ESP32-H2.
109+
- JTAG adapter configuration file for ESP32-H4.
103110
* - ``interface/ftdi/esp_ftdi.cfg``
104111
- JTAG adapter configuration file for ESP-Prog boards.
105112

@@ -113,23 +120,23 @@
113120

114121
.. jtag-pins
115122

116-
.. list-table:: ESP32-H2 pins and JTAG signals
123+
.. list-table:: ESP32-H4 pins and JTAG ESP32-H4
117124
:widths: 25 75
118125
:header-rows: 1
119126

120-
* - ESP32-H2 Pin
127+
* - ESP32-H4 Pin
121128
- JTAG Signal
122-
* - MTDO / GPIO3
129+
* - MTDO / GPIO31
123130
- TDO
124-
* - MTDI / GPIO5
131+
* - MTDI / GPIO29
125132
- TDI
126-
* - MTCK / GPIO4
133+
* - MTCK / GPIO30
127134
- TCK
128-
* - MTMS / GPIO2
135+
* - MTMS / GPIO28
129136
- TMS
130137

131-
.. |jtag-sel-gpio| replace:: GPIO25
132-
.. |jtag-gpio-list| replace:: GPIO2-GPIO5
138+
.. |jtag-sel-gpio| replace:: GPIO36
139+
.. |jtag-gpio-list| replace:: GPIO28-GPIO31
133140

134141
---
135142

@@ -159,13 +166,13 @@
159166

160167
.. devkit-defs
161168

162-
.. |devkit-name| replace:: ESP32-H2
163-
.. |devkit-name-with-link| replace:: :doc:`ESP32-H2 <../../hw-reference/index>`
169+
.. |devkit-name| replace:: ESP32-H4
170+
.. |devkit-name-with-link| replace:: :doc:`ESP32-H4 <../../hw-reference/index>`
164171

165172
---
166173

167174
.. devkit-hw-config
168175

169-
* Out of the box, ESP32-H2 doesn't need any additional hardware configuration for JTAG debugging.
176+
* Out of the box, ESP32-H4 doesn't need any additional hardware configuration for JTAG debugging.
170177
171178
---

‎docs/zh_CN/api-guides/jtag-debugging/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -184,7 +184,7 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG
184184
:start-after: run-openocd
185185
:end-before: ---
186186

187-
{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"}
187+
{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"}
188188

189189
.. note::
190190

0 commit comments

Comments
 (0)