Skip to content

Commit 580fe80

Browse files
igrrigrr
committed
Merge branch 'doc/esp32s2_jtag_guide' into 'master'
docs: update JTAG debugging guide for ESP32-S2 Closes FCS-469 See merge request espressif/esp-idf!9473
2 parents cef10fd + e6a94e9 commit 580fe80

17 files changed

+1039
-458
lines changed

‎docs/conf_common.py

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,6 @@
150150
'get-started-legacy/**']
151151

152152
ESP32_DOCS = ['api-guides/ulp_instruction_set.rst',
153-
'api-guides/jtag-debugging/configure-wrover.rst',
154153
'api-reference/system/himem.rst',
155154
'api-guides/RF_calibration.rst',
156155
'api-reference/system/ipc.rst',

‎docs/en/api-guides/jtag-debugging/configure-wrover.rst renamed to ‎docs/en/api-guides/jtag-debugging/configure-ft2232h-jtag.rst

Lines changed: 33 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,47 @@
1-
Configure WROVER JTAG Interface
2-
===============================
3-
:link_to_translation:`zh_CN:[中文]`
1+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
2+
:start-after: devkit-defs
3+
:end-before: ---
4+
45

5-
All versions of ESP-WROVER-KIT boards have built-in JTAG functionality. Putting it to work requires setting jumpers to enable JTAG functionality, setting SPI flash voltage and configuring USB drivers. Please refer to step by step instructions below.
6+
Configure |devkit-name| JTAG Interface
7+
======================================
8+
:link_to_translation:`zh_CN:[中文]`
69

10+
All versions of |devkit-name| boards have built-in JTAG functionality. Putting it to work requires setting jumpers or DIP switches to enable JTAG functionality, and configuring USB drivers. Please refer to step by step instructions below.
711

812
Configure Hardware
913
^^^^^^^^^^^^^^^^^^
1014

11-
1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/esp32/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options`.
12-
13-
2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:
15+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
16+
:start-after: devkit-hw-config
17+
:end-before: ---
1418

15-
+---+---------------+-------------+
16-
| | ESP32 Pin | JTAG Signal |
17-
+===+===============+=============+
18-
| 1 | CHIP_PU | TRST_N |
19-
+---+---------------+-------------+
20-
| 2 | MTDO / GPIO15 | TDO |
21-
+---+---------------+-------------+
22-
| 3 | MTDI / GPIO12 | TDI |
23-
+---+---------------+-------------+
24-
| 4 | MTCK / GPIO13 | TCK |
25-
+---+---------------+-------------+
26-
| 5 | MTMS / GPIO14 | TMS |
27-
+---+---------------+-------------+
19+
* Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:
2820

21+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
22+
:start-after: jtag-pins
23+
:end-before: ---
2924

3025
Configure USB Drivers
3126
^^^^^^^^^^^^^^^^^^^^^
3227

33-
Install and configure USB drivers, so OpenOCD is able to communicate with JTAG interface on ESP-WROVER-KIT board as well as with UART interface used to upload application for flash. Follow steps below specific to your operating system.
28+
Install and configure USB drivers, so OpenOCD is able to communicate with JTAG interface on |devkit-name| board as well as with UART interface used to upload application for flash. Follow steps below specific to your operating system.
3429

35-
.. note:: ESP-WROVER-KIT uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.
30+
.. note:: |devkit-name| uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.
3631

3732

3833
Windows
3934
"""""""
4035

41-
1. Using standard USB A / micro USB B cable connect ESP-WROVER-KIT to the computer. Switch the WROVER KIT on.
36+
1. Using standard USB A / micro USB B cable connect |devkit-name| to the computer. Switch the |devkit-name| on.
4237

43-
2. Wait until USB ports of WROVER KIT are recognized by Windows and drives are installed. If they do not install automatically, then download them from https://www.ftdichip.com/Drivers/D2XX.htm and install manually.
38+
2. Wait until USB ports of |devkit-name| are recognized by Windows and drives are installed. If they do not install automatically, then download them from https://www.ftdichip.com/Drivers/D2XX.htm and install manually.
4439

4540
3. Download Zadig tool (Zadig_X.X.exe) from https://zadig.akeo.ie/ and run it.
4641

4742
4. In Zadig tool go to "Options" and check "List All Devices".
4843

49-
5. Check the list of devices that should contain two WROVER specific USB entries: "Dual RS232-HS (Interface 0)" and "Dual RS232-HS (Interface 1)". The driver name would be "FTDIBUS (vxxxx)" and USB ID: 0403 6010.
44+
5. Check the list of devices that should contain two |devkit-name| specific USB entries: "Dual RS232-HS (Interface 0)" and "Dual RS232-HS (Interface 1)". The driver name would be "FTDIBUS (vxxxx)" and USB ID: 0403 6010.
5045

5146
.. figure:: ../../../_static/jtag-usb-configuration-zadig.jpg
5247
:align: center
@@ -55,19 +50,19 @@ Windows
5550

5651
Configuration of JTAG USB driver in Zadig tool
5752

58-
6. The first device (Dual RS232-HS (Interface 0)) is connected to the JTAG port of the ESP32. Original "FTDIBUS (vxxxx)" driver of this device should be replaced with "WinUSB (v6xxxxx)". To do so, select "Dual RS232-HS (Interface 0) and reinstall attached driver to the "WinUSB (v6xxxxx)", see picture above.
53+
6. The first device (Dual RS232-HS (Interface 0)) is connected to the JTAG port of the {IDF_TARGET_NAME}. Original "FTDIBUS (vxxxx)" driver of this device should be replaced with "WinUSB (v6xxxxx)". To do so, select "Dual RS232-HS (Interface 0) and reinstall attached driver to the "WinUSB (v6xxxxx)", see picture above.
5954

6055
.. note::
6156

62-
Do not change the second device "Dual RS232-HS (Interface 1)". It is routed to ESP32's serial port (UART) used for upload of application to ESP32's flash.
57+
Do not change the second device "Dual RS232-HS (Interface 1)". It is routed to {IDF_TARGET_NAME}'s serial port (UART) used for upload of application to {IDF_TARGET_NAME}'s flash.
6358

64-
Now ESP-WROVER-KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
59+
Now |devkit-name|'s JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
6560

6661

6762
Linux
6863
"""""
6964

70-
1. Using standard USB A / micro USB B cable connect ESP-WROVER-KIT board to the computer. Power on the board.
65+
1. Using standard USB A / micro USB B cable connect |devkit-name| board to the computer. Power on the board.
7166

7267
.. highlight:: none
7368

@@ -92,9 +87,9 @@ Linux
9287

9388
If you see similar result and you are a member of ``plugdev`` group, then the set up is complete.
9489

95-
The ``/dev/ttyUSBn`` interface with lower number is used for JTAG communication. The other interface is routed to ESP32's serial port (UART) used for upload of application to ESP32's flash.
90+
The ``/dev/ttyUSBn`` interface with lower number is used for JTAG communication. The other interface is routed to {IDF_TARGET_NAME}'s serial port (UART) used for upload of application to {IDF_TARGET_NAME}'s flash.
9691

97-
Now ESP-WROVER-KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
92+
Now |devkit-name|'s JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
9893

9994

10095
MacOS
@@ -104,14 +99,14 @@ On macOS, using FT2232 for JTAG and serial port at the same time needs some addi
10499

105100
1. Manually unload the FTDI serial port driver before starting OpenOCD, start OpenOCD, then load the serial port driver.
106101

107-
2. Modify FTDI driver configuration so that it doesn't load itself for channel B of FT2232 chip, which is the channel used for JTAG on WROVER KIT.
102+
2. Modify FTDI driver configuration so that it doesn't load itself for channel B of FT2232 chip, which is the channel used for JTAG on |devkit-name|.
108103

109104
Manually unloading the driver
110105
.............................
111106

112107
1. Install FTDI driver from https://www.ftdichip.com/Drivers/VCP.htm
113108

114-
2. Connect USB cable to the WROVER KIT.
109+
2. Connect USB cable to the |devkit-name|.
115110

116111
3. Unload the serial port driver::
117112

@@ -121,17 +116,19 @@ Manually unloading the driver
121116

122117
sudo kextunload -b com.apple.driver.AppleUSBFTDI
123118

124-
4. Run OpenOCD::
119+
4. Run OpenOCD:
125120

126-
bin/openocd -f board/esp32-wrover-kit-3.3v.cfg
121+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
122+
:start-after: run-openocd
123+
:end-before: ---
127124

128125
5. In another terminal window, load FTDI serial port driver again::
129126

130127
sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver
131128

132129
.. note::
133130

134-
If you need to restart OpenOCD, there is no need to unload FTDI driver again — just stop OpenOCD and start it again. The driver only needs to be unloaded if WROVER KIT was reconnected or power was toggled.
131+
If you need to restart OpenOCD, there is no need to unload FTDI driver again — just stop OpenOCD and start it again. The driver only needs to be unloaded if |devkit-name| was reconnected or power was toggled.
135132

136133
This procedure can be wrapped into a shell script, if desired.
137134

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

Lines changed: 3 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -10,41 +10,9 @@ Configure Hardware
1010

1111
1. Identify all pins / signals on JTAG interface and {IDF_TARGET_NAME} board, that should be connected to establish communication.
1212

13-
.. only:: esp32
14-
15-
+---+-----------------------+-------------+
16-
| | ESP32 Pin | JTAG Signal |
17-
+===+=======================+=============+
18-
| 1 | CHIP_PU | TRST_N |
19-
+---+-----------------------+-------------+
20-
| 2 | MTDO / GPIO15 | TDO |
21-
+---+-----------------------+-------------+
22-
| 3 | MTDI / GPIO12 | TDI |
23-
+---+-----------------------+-------------+
24-
| 4 | MTCK / GPIO13 | TCK |
25-
+---+-----------------------+-------------+
26-
| 5 | MTMS / GPIO14 | TMS |
27-
+---+-----------------------+-------------+
28-
| 6 | GND | GND |
29-
+---+-----------------------+-------------+
30-
31-
.. only:: esp32s2
32-
33-
+---+-----------------------+-------------+
34-
| | ESP32-S2 Pin | JTAG Signal |
35-
+===+=======================+=============+
36-
| 1 | CHIP_PU | TRST_N |
37-
+---+-----------------------+-------------+
38-
| 2 | MTDO / GPIO40 | TDO |
39-
+---+-----------------------+-------------+
40-
| 3 | MTDI / GPIO41 | TDI |
41-
+---+-----------------------+-------------+
42-
| 4 | MTCK / GPIO39 | TCK |
43-
+---+-----------------------+-------------+
44-
| 5 | MTMS / GPIO42 | TMS |
45-
+---+-----------------------+-------------+
46-
| 6 | GND | GND |
47-
+---+-----------------------+-------------+
13+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
14+
:start-after: jtag-pins
15+
:end-before: ---
4816

4917
2. Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation.
5018

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

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
.. This file gets included from other .rst files in this folder.
2+
.. It contains target-specific snippets.
3+
.. Comments and '---' lines act as delimiters.
4+
..
5+
.. This is necessary mainly because RST doesn't support substitutions
6+
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
7+
.. These code blocks can be moved back to the main .rst files, with target-specific
8+
.. file names being replaced by substitutions.
9+
10+
11+
.. run-openocd
12+
13+
::
14+
15+
openocd -f board/esp32-wrover-kit-3.3v.cfg
16+
17+
.. |run-openocd-device-name| replace:: ESP-WROVER-KIT with ESP32-WROOM-32 module
18+
19+
---
20+
21+
.. run-openocd-output
22+
23+
::
24+
25+
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32-wrover-kit-3.3v.cfg
26+
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
27+
Licensed under GNU GPL v2
28+
For bug reports, read
29+
http://openocd.org/doc/doxygen/bugs.html
30+
none separate
31+
adapter speed: 20000 kHz
32+
force hard breakpoints
33+
Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
34+
Info : clock speed 20000 kHz
35+
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
36+
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
37+
Info : esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
38+
Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
39+
40+
.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32-wrover-kit-3.3v.cfg``
41+
42+
---
43+
44+
.. run-openocd-upload
45+
46+
::
47+
48+
openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000 verify exit"
49+
50+
---
51+
52+
.. run-openocd-src-linux
53+
54+
.. code-block:: bash
55+
56+
src/openocd -f board/esp32-wrover-kit-3.3v.cfg
57+
58+
---
59+
60+
.. run-openocd-src-win
61+
62+
.. code-block:: batch
63+
64+
src\openocd -f board\esp32-wrover-kit-3.3v.cfg
65+
66+
---
67+
68+
.. idf-py-openocd-default-cfg
69+
70+
.. |idf-py-def-cfg| replace:: ``-f board/esp32-wrover-kit-3.3v.cfg``
71+
72+
---
73+
74+
.. run-openocd-appimage-offset
75+
76+
::
77+
78+
openocd -f board/esp32-wrover-kit-3.3v.cfg -c "init; halt; esp appimage_offset 0x210000"
79+
80+
---
81+
82+
.. openocd-cfg-files
83+
84+
.. list-table:: OpenOCD configuration files for ESP32
85+
:widths: 25 75
86+
:header-rows: 1
87+
88+
* - Name
89+
- Description
90+
* - ``board/esp32-wrover-kit-3.3v.cfg``
91+
- Board configuration file for ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32 module or ESP32-WROVER-B / ESP32-WROVER-E module.
92+
* - ``board/esp32-wrover-kit-1.8v.cfg``
93+
- Board configuration file for ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module.
94+
* - ``board/esp32-ethernet-kit-3.3v.cfg``
95+
- Board configuration file for ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module.
96+
* - ``target/esp32.cfg``
97+
- ESP32 target configuration file. Can be used together with one of the ``interface/`` configuration files.
98+
* - ``target/esp32-solo-1.cfg``
99+
- Target configuration file for ESP32-SOLO-1 module. Different from ``esp32.cfg`` in that it only configures one CPU.
100+
* - ``interface/ftdi/esp32_devkitj_v1.cfg``
101+
- JTAG adapter configuration file for ESP-WROVER-KIT and ESP-Prog boards.
102+
103+
---
104+
105+
.. openocd-target-specific-config-vars
106+
107+
.. list-table:: ESP32-specific OpenOCD variables
108+
:widths: 25 75
109+
:header-rows: 1
110+
111+
* - Name
112+
- Description
113+
* - ``ESP32_FLASH_VOLTAGE``
114+
- When using 1.8 V flash ESP32 based modules, set this variable to ``1.8``. Refer to :ref:`jtag-debugging-tip-code-flash-voltage`.
115+
* - ``ESP32_ONLYCPU``
116+
- For multi-core targets, can be set to ``1`` to only enable single core debugging.
117+
118+
---
119+
120+
.. jtag-pins
121+
122+
.. list-table:: ESP32 JTAG pins
123+
:widths: 25 75
124+
:header-rows: 1
125+
126+
* - ESP32 Pin
127+
- JTAG Signal
128+
* - MTDO / GPIO15
129+
- TDO
130+
* - MTDI / GPIO12
131+
- TDI
132+
* - MTCK / GPIO13
133+
- TCK
134+
* - MTMS / GPIO14
135+
- TMS
136+
* - GND
137+
- GND
138+
139+
---
140+
141+
.. run-openocd-d3
142+
143+
::
144+
145+
openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg
146+
147+
---
148+
149+
.. run-openocd-d3-tee
150+
151+
::
152+
153+
openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log
154+
155+
---
156+
157+
.. run-gdb-remotelog
158+
159+
::
160+
161+
xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
162+
163+
---
164+
165+
.. devkit-defs
166+
167+
.. |devkit-name| replace:: ESP-WROVER-KIT
168+
.. |devkit-name-with-link| replace:: :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`
169+
170+
---
171+
172+
.. devkit-hw-config
173+
174+
* Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/esp32/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options`.
175+
176+
---

0 commit comments

Comments
 (0)