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

Merge branch 'doc/esp32s2_jtag_guide_v4.2' into 'release/v4.2'

Browse Source 
docs: update JTAG debugging guide for ESP32-S2 (backport v4.2)

See merge request espressif/esp-idf!10311
This commit is contained in:
Krzysztof Budzynski
2020-09-27 14:37:40 +08:00
parent 4b10685fcc 1f011c3b2a
commit 81bbc8c88d
17 changed files with 1040 additions and 459 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/conf_common.py
View File

@ -152,7 +152,6 @@ LEGACY_DOCS = ['api-guides/build-system-legacy.rst',
'get-started-legacy/**']
ESP32_DOCS = ['api-guides/ulp_instruction_set.rst',
'api-guides/jtag-debugging/configure-wrover.rst',
'api-reference/system/himem.rst',
'api-guides/RF_calibration.rst',
'api-reference/system/ipc.rst',

69
docs/en/api-guides/jtag-debugging/configure-wrover.rst → docs/en/api-guides/jtag-debugging/configure-ft2232h-jtag.rst
View File

@ -1,52 +1,47 @@
Configure WROVER JTAG Interface
===============================
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: devkit-defs
:end-before: ---
Configure |devkit-name| JTAG Interface
======================================
:link_to_translation:`zh_CN:[中文]`
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.
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.
Configure Hardware
^^^^^^^^^^^^^^^^^^
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`.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: devkit-hw-config
:end-before: ---
2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:
+---+---------------+-------------+
| | ESP32 Pin | JTAG Signal |
+===+===============+=============+
| 1 | CHIP_PU | TRST_N |
+---+---------------+-------------+
| 2 | MTDO / GPIO15 | TDO |
+---+---------------+-------------+
| 3 | MTDI / GPIO12 | TDI |
+---+---------------+-------------+
| 4 | MTCK / GPIO13 | TCK |
+---+---------------+-------------+
| 5 | MTMS / GPIO14 | TMS |
+---+---------------+-------------+
* Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: jtag-pins
:end-before: ---
Configure USB Drivers
^^^^^^^^^^^^^^^^^^^^^
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.
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.
.. note:: ESP-WROVER-KIT uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.
.. note:: |devkit-name| uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.
Windows
"""""""
1. Using standard USB A / micro USB B cable connect ESP-WROVER-KIT to the computer. Switch the WROVER KIT on.
1. Using standard USB A / micro USB B cable connect |devkit-name| to the computer. Switch the |devkit-name| on.
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.
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.
3. Download Zadig tool (Zadig_X.X.exe) from https://zadig.akeo.ie/ and run it.
4. In Zadig tool go to "Options" and check "List All Devices".
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.
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.
.. figure:: ../../../_static/jtag-usb-configuration-zadig.jpg
:align: center
@ -55,19 +50,19 @@ Windows
Configuration of JTAG USB driver in Zadig tool
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.
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.
.. note::
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.
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.
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`.
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`.
Linux
"""""
1. Using standard USB A / micro USB B cable connect ESP-WROVER-KIT board to the computer. Power on the board.
1. Using standard USB A / micro USB B cable connect |devkit-name| board to the computer. Power on the board.
.. highlight:: none
@ -92,9 +87,9 @@ Linux
If you see similar result and you are a member of ``plugdev`` group, then the set up is complete.
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.
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.
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`.
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`.
MacOS
@ -104,14 +99,14 @@ On macOS, using FT2232 for JTAG and serial port at the same time needs some addi
1. Manually unload the FTDI serial port driver before starting OpenOCD, start OpenOCD, then load the serial port driver.
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.
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|.
Manually unloading the driver
.............................
1. Install FTDI driver from https://www.ftdichip.com/Drivers/VCP.htm
2. Connect USB cable to the WROVER KIT.
2. Connect USB cable to the |devkit-name|.
3. Unload the serial port driver::
@ -121,9 +116,11 @@ Manually unloading the driver
sudo kextunload -b com.apple.driver.AppleUSBFTDI
4. Run OpenOCD::
4. Run OpenOCD:
bin/openocd -f board/esp32-wrover-kit-3.3v.cfg
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd
:end-before: ---
5. In another terminal window, load FTDI serial port driver again::
@ -131,7 +128,7 @@ Manually unloading the driver
.. note::
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.
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.
This procedure can be wrapped into a shell script, if desired.

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

@ -10,41 +10,9 @@ Configure Hardware
1. Identify all pins / signals on JTAG interface and {IDF_TARGET_NAME} board, that should be connected to establish communication.
.. only:: esp32
+---+-----------------------+-------------+
| | ESP32 Pin | JTAG Signal |
+===+=======================+=============+
| 1 | CHIP_PU | TRST_N |
+---+-----------------------+-------------+
| 2 | MTDO / GPIO15 | TDO |
+---+-----------------------+-------------+
| 3 | MTDI / GPIO12 | TDI |
+---+-----------------------+-------------+
| 4 | MTCK / GPIO13 | TCK |
+---+-----------------------+-------------+
| 5 | MTMS / GPIO14 | TMS |
+---+-----------------------+-------------+
| 6 | GND | GND |
+---+-----------------------+-------------+
.. only:: esp32s2
+---+-----------------------+-------------+
| | ESP32-S2 Pin | JTAG Signal |
+===+=======================+=============+
| 1 | CHIP_PU | TRST_N |
+---+-----------------------+-------------+
| 2 | MTDO / GPIO40 | TDO |
+---+-----------------------+-------------+
| 3 | MTDI / GPIO41 | TDI |
+---+-----------------------+-------------+
| 4 | MTCK / GPIO39 | TCK |
+---+-----------------------+-------------+
| 5 | MTMS / GPIO42 | TMS |
+---+-----------------------+-------------+
| 6 | GND | GND |
+---+-----------------------+-------------+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: jtag-pins
:end-before: ---
2. Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation.

176
docs/en/api-guides/jtag-debugging/esp32.inc Normal file
View File

@ -0,0 +1,176 @@
.. This file gets included from other .rst files in this folder.
.. It contains target-specific snippets.
.. Comments and '---' lines act as delimiters.
..
.. This is necessary mainly because RST doesn't support substitutions
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. run-openocd
::
openocd -f board/esp32-wrover-kit-3.3v.cfg
.. |run-openocd-device-name| replace:: ESP-WROVER-KIT with ESP32-WROOM-32 module
---
.. run-openocd-output
::
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32-wrover-kit-3.3v.cfg
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
none separate
adapter speed: 20000 kHz
force hard breakpoints
Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
Info : clock speed 20000 kHz
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32-wrover-kit-3.3v.cfg``
---
.. run-openocd-upload
::
openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000 verify exit"
---
.. run-openocd-src-linux
.. code-block:: bash
src/openocd -f board/esp32-wrover-kit-3.3v.cfg
---
.. run-openocd-src-win
.. code-block:: batch
src\openocd -f board\esp32-wrover-kit-3.3v.cfg
---
.. idf-py-openocd-default-cfg
.. |idf-py-def-cfg| replace:: ``-f board/esp32-wrover-kit-3.3v.cfg``
---
.. run-openocd-appimage-offset
::
openocd -f board/esp32-wrover-kit-3.3v.cfg -c "init; halt; esp appimage_offset 0x210000"
---
.. openocd-cfg-files
.. list-table:: OpenOCD configuration files for ESP32
:widths: 25 75
:header-rows: 1
* - Name
- Description
* - ``board/esp32-wrover-kit-3.3v.cfg``
- Board configuration file for ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32 module or ESP32-WROVER-B / ESP32-WROVER-E module.
* - ``board/esp32-wrover-kit-1.8v.cfg``
- Board configuration file for ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module.
* - ``board/esp32-ethernet-kit-3.3v.cfg``
- Board configuration file for ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module.
* - ``target/esp32.cfg``
- ESP32 target configuration file. Can be used together with one of the ``interface/`` configuration files.
* - ``target/esp32-solo-1.cfg``
- Target configuration file for ESP32-SOLO-1 module. Different from ``esp32.cfg`` in that it only configures one CPU.
* - ``interface/ftdi/esp32_devkitj_v1.cfg``
- JTAG adapter configuration file for ESP-WROVER-KIT and ESP-Prog boards.
---
.. openocd-target-specific-config-vars
.. list-table:: ESP32-specific OpenOCD variables
:widths: 25 75
:header-rows: 1
* - Name
- Description
* - ``ESP32_FLASH_VOLTAGE``
- When using 1.8 V flash ESP32 based modules, set this variable to ``1.8``. Refer to :ref:`jtag-debugging-tip-code-flash-voltage`.
* - ``ESP32_ONLYCPU``
- For multi-core targets, can be set to ``1`` to only enable single core debugging.
---
.. jtag-pins
.. list-table:: ESP32 JTAG pins
:widths: 25 75
:header-rows: 1
* - ESP32 Pin
- JTAG Signal
* - MTDO / GPIO15
- TDO
* - MTDI / GPIO12
- TDI
* - MTCK / GPIO13
- TCK
* - MTMS / GPIO14
- TMS
* - GND
- GND
---
.. run-openocd-d3
::
openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg
---
.. run-openocd-d3-tee
::
openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log
---
.. run-gdb-remotelog
::
xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
---
.. devkit-defs
.. |devkit-name| replace:: ESP-WROVER-KIT
.. |devkit-name-with-link| replace:: :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`
---
.. devkit-hw-config
* 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`.
---

160
docs/en/api-guides/jtag-debugging/esp32s2.inc Normal file
View File

@ -0,0 +1,160 @@
.. This file gets included from other .rst files in this folder.
.. It contains target-specific snippets.
.. Comments and '---' lines act as delimiters.
..
.. This is necessary mainly because RST doesn't support substitutions
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. run-openocd
::
openocd -f board/esp32s2-kaluga-1.cfg
.. |run-openocd-device-name| replace:: ESP32-S2-Kaluga-1 board
---
.. run-openocd-output
::
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s2-kaluga-1.cfg
Open On-Chip Debugger v0.10.0-esp32-20200420 (2020-04-20-16:15)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
none separate
adapter speed: 20000 kHz
force hard breakpoints
Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
Info : clock speed 20000 kHz
Info : JTAG tap: esp32s2.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : esp32s2: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32s2: Core was reset (pwrstat=0x5F, after clear 0x0F).
.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s2-kaluga-1.cfg``
---
.. run-openocd-upload
::
openocd -f board/esp32s2-kaluga-1.cfg -c "program_esp filename.bin 0x10000 verify exit"
---
.. run-openocd-src-linux
.. code-block:: bash
src/openocd -f board/esp32s2-kaluga-1.cfg
---
.. run-openocd-src-win
.. code-block:: batch
src\openocd -f board/esp32s2-kaluga-1.cfg
---
.. idf-py-openocd-default-cfg
.. |idf-py-def-cfg| replace:: ``-f board/esp32s2-kaluga-1.cfg``
---
.. run-openocd-appimage-offset
::
openocd -f board/esp32s2-kaluga-1.cfg -c "init; halt; esp appimage_offset 0x210000"
---
.. openocd-cfg-files
.. list-table:: OpenOCD configuration files for ESP32-S2
:widths: 25 75
:header-rows: 1
* - Name
- Description
* - ``board/esp32s2-kaluga-1.cfg``
- Board configuration file for ESP32-S2-Kaluga-1, includes target and adapter configuration.
* - ``target/esp32s2.cfg``
- ESP32-S2 target configuration file. Can be used together with one of the ``interface/`` configuration files.
* - ``interface/ftdi/esp32s2_kaluga_v1.cfg``
- JTAG adapter configuration file for ESP32-S2-Kaluga-1 board.
* - ``interface/ftdi/esp32_devkitj_v1.cfg``
- JTAG adapter configuration file for ESP-Prog boards.
---
.. openocd-target-specific-config-vars
---
---
.. jtag-pins
.. list-table:: ESP32-S2 pins and JTAG signals
:widths: 25 75
:header-rows: 1
* - ESP32-S2 Pin
- JTAG Signal
* - MTDO / GPIO40
- TDO
* - MTDI / GPIO41
- TDI
* - MTCK / GPIO39
- TCK
* - MTMS / GPIO42
- TMS
---
.. run-openocd-d3
::
openocd -l openocd_log.txt -d3 -f board/esp32s2-kaluga-1.cfg
---
.. run-openocd-d3-tee
::
openocd -d3 -f board/esp32s2-kaluga-1.cfg 2>&1 | tee openocd.log
---
.. run-gdb-remotelog
::
xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
---
.. devkit-defs
.. |devkit-name| replace:: ESP-S2-Kaluga-1
.. |devkit-name-with-link| replace:: :doc:`ESP-S2-Kaluga-1 <../../hw-reference/modules-and-boards>`
---
.. devkit-hw-config
* Out of the box, ESP32-S2-Kaluga-1 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.
---

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

@ -25,6 +25,11 @@ GDB. The document is structured as follows:
This section provides collection of tips and quirks related JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: devkit-defs
:end-before: ---
.. _jtag-debugging-introduction:
Introduction
@ -42,7 +47,7 @@ This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and d
.. note::
Screenshots presented in this document have been made for Eclipse Neon 3 running on Ubuntu 16.04 LTE. There may be some small differences in what a particular user interface looks like, depending on whether you are using Windows, MacOS or Linux and / or a different release of Eclipse.
Screenshots presented in this document have been made for Eclipse Neon 3 running on Ubuntu 16.04 LTS. There may be some small differences in what a particular user interface looks like, depending on whether you are using Windows, MacOS or Linux and / or a different release of Eclipse.
.. _jtag-debugging-how-it-works:
@ -62,9 +67,7 @@ Under "Application Loading and Monitoring" there is another software and hardwar
Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse <https://www.eclipse.org/>`_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms.
.. only:: esp32
If the :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection.
If the |devkit-name-with-link| is used, then connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the one for UART connection.
Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal/command line, instead from Eclipse.
@ -74,7 +77,7 @@ Depending on user preferences, both `debugger` and `idf.py build` can be operate
Selecting JTAG Adapter
----------------------
The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
The quickest and most convenient way to start with JTAG debugging is by using |devkit-name-with-link|. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. |devkit-name| is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the {IDF_TARGET_NAME} as well as with the OpenOCD software. The JTAG port on the {IDF_TARGET_NAME} is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
@ -98,7 +101,7 @@ If you have already set up ESP-IDF with CMake build system according to the :doc
The output should be as follows (although the version may be more recent than listed here)::
Open On-Chip Debugger v0.10.0-{IDF_TARGET_TOOLCHAIN_NAME}-20190708 (2019-07-08-11:04)
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
@ -131,7 +134,7 @@ This step depends on JTAG and {IDF_TARGET_NAME} board you are using - see the tw
.. toctree::
:maxdepth: 1
:esp32: configure-wrover
configure-ft2232h-jtag
configure-other-jtag
@ -144,35 +147,26 @@ Once target is configured and connected to computer, you are ready to launch Ope
.. highlight:: bash
Open a terminal and set it up for using the ESP-IDF as described in the :ref:`setting up the environment <get-started-set-up-env>` section of the Getting Started Guide. Then run OpenOCD (this command works on Windows, Linux, and macOS)::
Open a terminal and set it up for using the ESP-IDF as described in the :ref:`setting up the environment <get-started-set-up-env>` section of the Getting Started Guide. Then run OpenOCD (this command works on Windows, Linux, and macOS):
openocd -f board/esp32-wrover-kit-3.3v.cfg
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd
:end-before: ---
.. note::
The files provided after ``-f`` above are specific for ESP-WROVER-KIT with esp32-wroom-32 module. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
The files provided after ``-f`` above are specific for |run-openocd-device-name|. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
.. highlight:: none
You should now see similar output (this log is for ESP-WROVER-KIT)::
You should now see similar output (this log is for |run-openocd-device-name|):
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32-wrover-kit-3.3v.cfg
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
none separate
adapter speed: 20000 kHz
force hard breakpoints
Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
Info : clock speed 20000 kHz
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-output
:end-before: ---
* If there is an error indicating permission problems, please see the "Permissions delegation" bit in the OpenOCD README file in ``~/esp/openocd-esp32`` directory.
* In case there is an error finding configuration files, e.g. ``Can't find board/esp32-wrover-kit-3.3v.cfg``, check the path after ``-s``. This path is used by OpenOCD to look for the files specified after ``-f``. Also check if the file is indeed under provided path.
* In case there is an error finding configuration files, e.g. |run-openocd-cfg-file-err|, check ``OPENOCD_SCRIPTS`` environment variable is set correctly. This variable is used by OpenOCD to look for the files specified after ``-f``. See :ref:`jtag-debugging-setup-openocd` section for details. Also check if the file is indeed under provided path.
* If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides {IDF_TARGET_NAME}'s pins, and see if everything is powered on.
@ -183,9 +177,11 @@ Upload application for debugging
Build and upload your application to {IDF_TARGET_NAME} as usual, see :ref:`get-started-build`.
Another option is to write application image to flash using OpenOCD via JTAG with commands like this::
Another option is to write application image to flash using OpenOCD via JTAG with commands like this:
openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000 verify exit"
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-upload
:end-before: ---
OpenOCD flashing command ``program_esp`` has the following format:
@ -251,26 +247,31 @@ Please refer to separate documents listed below, that describe build process.
The examples of invoking OpenOCD in this document assume using pre-built binary distribution described in section :ref:`jtag-debugging-setup-openocd`.
.. highlight:: bash
To use binaries build locally from sources, change the path to OpenOCD executable to ``src/openocd`` and set the ``OPENOCD_SCRIPTS`` environment variable so that OpenOCD can find the configuration files. For Linux and macOS:
To use binaries build locally from sources, change the path to OpenOCD executable to ``src/openocd`` and set the ``OPENOCD_SCRIPTS`` environment variable so that OpenOCD can find the configuration files. For Linux and macOS::
.. code-block:: bash
cd ~/esp/openocd-esp32
export OPENOCD_SCRIPTS=$PWD/tcl
For Windows::
For Windows:
.. code-block:: batch
cd %USERPROFILE%\esp\openocd-esp32
set "OPENOCD_SCRIPTS=%CD%\tcl"
Example of invoking OpenOCD build locally from sources, for Linux and macOS::
Example of invoking OpenOCD build locally from sources, for Linux and macOS:
src/openocd -f board/esp32-wrover-kit-3.3v.cfg
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-src-linux
:end-before: ---
and Windows::
src\openocd -f board\esp32-wrover-kit-3.3v.cfg
and Windows:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-src-win
:end-before: ---
.. _jtag-debugging-tips-and-quirks:

174
docs/en/api-guides/jtag-debugging/tips-and-quirks.rst
View File

@ -28,7 +28,7 @@ Flash Mappings vs SW Flash Breakpoints
In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the {IDF_TARGET_NAME} address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format:
``esp32 appimage_offset <offset>``
``esp appimage_offset <offset>``
Offset should be in hex format. To reset to the default behaviour you can specify ``-1`` as offset.
@ -36,7 +36,11 @@ Offset should be in hex format. To reset to the default behaviour you can specif
Since GDB requests memory map from OpenOCD only once when connecting to it, this command should be specified in one of the TCL configuration files, or passed to OpenOCD via its command line. In the latter case command line should look like below:
``openocd -f board/esp32-wrover-kit-3.3v.cfg.cfg -c "init; halt; esp32 appimage_offset 0x210000"``
.. highlight:: bash
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-appimage-offset
:end-before: ---
Another option is to execute that command via OpenOCD telnet session and then connect GDB, but it seems to be less handy.
@ -79,9 +83,9 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task
The MTDI pin of ESP32, being among four pins used for JTAG communication, is also one of ESP32's bootstrapping pins. On power up ESP32 is sampling binary level on MTDI to set it's internal voltage regulator used to supply power to external SPI flash chip. If binary level on MDTI pin on power up is low, the voltage regulator is set to deliver 3.3 V, if it is high, then the voltage is set to 1.8 V. The MTDI pin should have a pull-up or may rely on internal weak pull down resistor (see `ESP32 Series Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ for details), depending on the type of SPI chip used. Once JTAG is connected, it overrides the pull-up or pull-down resistor that is supposed to do the bootstrapping.
To handle this issue OpenOCD's board configuration file (e.g. ``boards\esp-wroom-32.cfg`` for ESP32-WROOM-32 module) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage.
To handle this issue OpenOCD's board configuration file (e.g. ``board\esp32-wrover-kit-3.3v.cfg`` for ESP-WROVER-KIT board) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage.
Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash, while WROVER modules use 1.8 V flash.
Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash. WROVER earlier than ESP32-WROVER-B use 1.8 V flash, while ESP32-WROVER-B and -E modules use 3.3 V flash.
.. _jtag-debugging-tip-optimize-jtag-speed:
@ -120,88 +124,65 @@ On startup, debugger is issuing sequence of commands to reset the chip and halt
Configuration of OpenOCD for specific target
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OpenOCD needs to be told what JTAG adapter to use and processor the JTAG adapter is connected to. To do so, use existing **board** configuration files located in OpenOCD's ``share/openocd/scripts/board`` folder.
There are several kinds of OpenOCD configuration files (``*.cfg``). All configuration files are located in subdirectories of ``share/openocd/scripts`` directory of OpenOCD distribution (or ``tcl/scripts`` directory of the source repository). For the purposes of this guide, the most important ones are ``board``, ``interface`` and ``target``.
For example, if you connect to ESP-WROVER-KIT with ESP-WROOM-32 module installed, use the following configuration files:
* ``interface`` configuration files describe the JTAG adapter. Examples of JTAG adapters are ESP-Prog and J-Link.
* ``target`` configuration files describe specific chips, or in some cases, modules.
* ``board`` configuration files are provided for development boards with a built-in JTAG adapter. Such files include an ``interface`` configuration file to choose the adapter, and ``target`` configuration file to choose the chip/module.
* ``board/esp32-wrover-kit-3.3v.cfg``
The following configuration files are available for {IDF_TARGET_NAME}:
Optionally prepare configuration by yourself. To do so, you can check existing files and modify them to match you specific hardware. Below is the summary of available configuration parameters for **board** configuration.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: openocd-cfg-files
:end-before: ---
.. highlight:: none
If you are using one of the boards which have a pre-defined configuration file, you only need to pass one ``-f`` argument to OpenOCD, specifying that file.
Adapter's clock speed
""""""""""""""""""""""
If you are using a board not listed here, you need to specify both the interface configuration file and target configuration file.
::
Custom configuration files
""""""""""""""""""""""""""
adapter_khz 20000
OpenOCD configuration files are written in TCL, and include a variety of choices for customization and scripting. This can be useful for non-standard debugging situations. Please refer to `OpenOCD Manual`_ for the TCL scripting reference.
See :ref:`jtag-debugging-tip-optimize-jtag-speed` for guidance how to set this value.
.. _jtag-debugging-tip-openocd-config-vars:
.. only:: esp32
OpenOCD configuration variables
"""""""""""""""""""""""""""""""
Single core debugging
"""""""""""""""""""""
The following variables can be optionally set before including the ESP-specific target configuration file. This can be done either in a custom configuration file, or from the command line.
::
The syntax for setting a variable in TCL is:
set ESP32_ONLYCPU 1
.. code-block:: tcl
Comment out this line for dual core debugging.
set VARIABLE_NAME value
To set a variable from the command line (replace the name of .cfg file with the correct file for your board):
Disable RTOS support
""""""""""""""""""""
.. code-block:: bash
::
openocd -c 'set VARIABLE_NAME value' -f board/esp-xxxxx-kit.cfg
set ESP32_RTOS none
It is important to set the variable before including the ESP-specific configuration file, otherwise the variable will not have effect. You can set multiple variables by repeating the ``-c`` option.
Comment out this line to have RTOS support.
.. list-table:: Common ESP-related OpenOCD variables
:widths: 25 75
:header-rows: 1
.. only:: esp32
Power supply voltage of ESP32's SPI flash chip
""""""""""""""""""""""""""""""""""""""""""""""
::
set ESP32_FLASH_VOLTAGE 1.8
Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage`
Configuration file for ESP32 targets
""""""""""""""""""""""""""""""""""""
::
source [find target/esp32.cfg]
.. note::
Do not change ``source [find target/esp32.cfg]`` line unless you are familiar with OpenOCD internals.
Currently ``target/esp32.cfg`` remains the only configuration file for ESP32 targets (esp108 and esp32). The matrix of supported configurations is as follows:
+---------------+---------------+---------------+
| Dual/single | RTOS | Target used |
+===============+===============+===============+
| dual | FreeRTOS | esp32 |
+---------------+---------------+---------------+
| single | FreeRTOS | esp108 (*) |
+---------------+---------------+---------------+
| dual | none | esp108 |
+---------------+---------------+---------------+
| single | none | esp108 |
+---------------+---------------+---------------+
(*) — we plan to fix this and add support for single core debugging with esp32 target in a subsequent commits.
Look inside ``board/esp-wroom-32.cfg`` for additional information provided in comments besides each configuration parameter.
* - Variable
- Description
* - ``ESP_RTOS``
- Set to ``none`` to disable RTOS support. In this case, thread list will not be available in GDB. Can be useful when debugging FreeRTOS itself, and stepping through the scheduler code.
* - ``ESP_FLASH_SIZE``
- Set to ``0`` to disable Flash breakpoints support.
* - ``ESP_SEMIHOST_BASEDIR``
- Set to the path (on the host) which will be the default directory for semihosting functions.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: openocd-target-specific-config-vars
:end-before: ---
.. _jtag-debugging-tip-reset-by-debugger:
@ -218,39 +199,15 @@ Do not use JTAG pins for something else
Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides {IDF_TARGET_NAME} module and JTAG adapter. {IDF_TARGET_NAME} JTAG us using the following pins:
.. only:: esp32
+---+-----------------------+-------------+
| | ESP32 Pin | JTAG Signal |
+===+=======================+=============+
| 1 | MTDO / GPIO15 | TDO |
+---+-----------------------+-------------+
| 2 | MTDI / GPIO12 | TDI |
+---+-----------------------+-------------+
| 3 | MTCK / GPIO13 | TCK |
+---+-----------------------+-------------+
| 4 | MTMS / GPIO14 | TMS |
+---+-----------------------+-------------+
.. only:: esp32s2
+---+-----------------------+-------------+
| | ESP32-S2 Pin | JTAG Signal |
+===+=======================+=============+
| 1 | MTDO / GPIO40 | TDO |
+---+-----------------------+-------------+
| 2 | MTDI / GPIO41 | TDI |
+---+-----------------------+-------------+
| 3 | MTCK / GPIO39 | TCK |
+---+-----------------------+-------------+
| 4 | MTMS / GPIO42 | TMS |
+---+-----------------------+-------------+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: jtag-pins
:end-before: ---
JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to connect Vtar to a JTAG adapter that needed it.
.. highlight:: none
Below is an excerpt from series of errors reported by GDB after the application stepped into the code that reconfigured MTDO / GPIO15 to be an input::
Below is an excerpt from series of errors reported by GDB after the application stepped into the code that reconfigured MTDO pin to be an input::
cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates target still busy!
cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an exception!
@ -273,9 +230,7 @@ However, OpenOCD may attempt to automatically read and write the flash in order
- Software breakpoints are incompatible with Flash Encryption, OpenOCD currently has no support for encrypting or decrypting flash contents.
- If Secure Boot is enabled, setting a software breakpoint will change the digest of a signed app and make the signature invalid. This means if a software breakpoint is set and then a reset occurs, the signature verification will fail on boot.
To disable software breakpoints while using JTAG, add an extra argument ``-c 'set ESP_FLASH_SIZE 0'`` to the start of the OpenOCD command line. For example::
openocd -c 'set ESP_FLASH_SIZE 0' -f board/esp32-wrover-kit-3.3v.cfg
To disable software breakpoints while using JTAG, add an extra argument ``-c 'set ESP_FLASH_SIZE 0'`` to the start of the OpenOCD command line, see :ref:`jtag-debugging-tip-openocd-config-vars`.
.. note::
@ -299,7 +254,7 @@ In case you encounter a problem with OpenOCD or GDB programs itself and do not f
1. In issue report provide details of your configuration:
a. JTAG adapter type.
a. JTAG adapter type, and the chip/module being debugged.
b. Release of ESP-IDF used to compile and load application that is being debugged.
c. Details of OS used for debugging.
d. Is OS running natively on a PC or on a virtual machine?
@ -312,23 +267,26 @@ In case you encounter a problem with OpenOCD or GDB programs itself and do not f
OpenOCD:
::
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-d3
:end-before: ---
openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg
Logging to a file this way will prevent information displayed on the terminal. This may be a good thing taken amount of information provided, when increased debug level ``-d3`` is set. If you still like to see the log on the screen, then use another command instead:
Logging to a file this way will prevent information displayed on the terminal. This may be a good thing taken amount of information provided, when increased debug level ``-d3`` is set. If you still like to see the log on the screen, then use another command instead:
::
openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-d3-tee
:end-before: ---
Debugger:
::
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-gdb-remotelog
:end-before: ---
xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
Optionally add command ``remotelogfile gdb_log.txt`` to the ``gdbinit`` file.
Optionally add command ``remotelogfile gdb_log.txt`` to the ``gdbinit`` file.
4. Attach both ``openocd_log.txt`` and ``gdb_log.txt`` files to your issue report.
.. _OpenOCD Manual: http://openocd.org/doc/html/index.html

65
docs/en/api-guides/jtag-debugging/using-debugger.rst
View File

@ -2,9 +2,11 @@ Using Debugger
--------------
:link_to_translation:`zh_CN:[中文]`
This section covers configuration and running debugger from :ref:`jtag-debugging-using-debugger-eclipse`
or from :ref:`jtag-debugging-using-debugger-command-line` or using :ref:`jtag-debugging-with-idf-py`.
It is recommended to first check if debugger works from :ref:`jtag-debugging-using-debugger-command-line` and then move to using Eclipse.
This section covers configuration and running debugger using several methods:
* from :ref:`jtag-debugging-using-debugger-eclipse`
* from :ref:`jtag-debugging-using-debugger-command-line`
* using :ref:`jtag-debugging-with-idf-py`.
.. _jtag-debugging-using-debugger-eclipse:
@ -12,6 +14,10 @@ It is recommended to first check if debugger works from :ref:`jtag-debugging-usi
Eclipse
^^^^^^^
.. note::
It is recommended to first check if debugger works using :ref:`jtag-debugging-with-idf-py` or from :ref:`jtag-debugging-using-debugger-command-line` and then move to using Eclipse.
Debugging functionality is provided out of box in standard Eclipse installation. Another option is to use pluggins like "GDB Hardware Debugging" plugin. We have found this plugin quite convenient and decided to use throughout this guide.
To begin with, install "GDB Hardware Debugging" plugin by opening Eclipse and going to `Help` > `Install` New Software.
@ -193,50 +199,51 @@ If you are not quite sure how to use GDB, check :ref:`jtag-debugging-examples-co
.. _jtag-debugging-with-idf-py:
Using idf.py debug targets
^^^^^^^^^^^^^^^^^^^^^^^^^^
idf.py debug targets
^^^^^^^^^^^^^^^^^^^^
It is also possible to execute the described debugging tools conveniently from ``idf.py``. These commands are supported:
1. ``idf.py openocd``
1. ``idf.py openocd``
Runs OpenOCD in a console with configuration defined in the environment or via command line.
It uses default script directory defined as ``OPENOCD_SCRIPTS`` environmental variable, which is automatically added
from an Export script (``export.sh`` or ``export.bat``). It is possible to override the script location
using command line argument ``--openocd-scripts``.
Runs OpenOCD in a console with configuration defined in the environment or via command line.
It uses default script directory defined as ``OPENOCD_SCRIPTS`` environmental variable, which is automatically added
from an Export script (``export.sh`` or ``export.bat``). It is possible to override the script location
using command line argument ``--openocd-scripts``.
As for the JTAG configuration of the current board, please use the environmental variable ``OPENOCD_COMMANDS``
or ``--openocd-commands`` command line argument. If none of the above is defined,
OpenOCD is started with ``-f board/esp32-wrover-kit-3.3v.cfg`` board definition.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: idf-py-openocd-default-cfg
:end-before: ---
As for the JTAG configuration of the current board, please use the environmental variable ``OPENOCD_COMMANDS``
or ``--openocd-commands`` command line argument. If none of the above is defined,
OpenOCD is started with |idf-py-def-cfg| board definition.
2. ``idf.py gdb``
2. ``idf.py gdb``
Starts the gdb the same way as the :ref:`jtag-debugging-using-debugger-command-line`, but generates the initial gdb scripts
referring to the current project elf file.
Starts the gdb the same way as the :ref:`jtag-debugging-using-debugger-command-line`, but generates the initial gdb scripts
referring to the current project elf file.
3. ``idf.py gdbtui``
3. ``idf.py gdbtui``
The same as `2`, but starts the gdb with ``tui`` argument allowing very simple source code view.
The same as `2`, but starts the gdb with ``tui`` argument allowing very simple source code view.
4. ``idf.py gdbgui``
4. ``idf.py gdbgui``
Starts `gdbgui <https://www.gdbgui.com>`_ debugger frontend enabling out-of-the-box debugging in a browser window.
Starts `gdbgui <https://www.gdbgui.com>`_ debugger frontend enabling out-of-the-box debugging in a browser window.
It is possible to combine these debugging actions on a single command line allowing convenient
setup of blocking and non-blocking actions in one step. ``idf.py`` implements a simple logic to move the background
actions (such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list.
It is possible to combine these debugging actions on a single command line allowing convenient
setup of blocking and non-blocking actions in one step. ``idf.py`` implements a simple logic to move the background
actions (such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list.
An example of a very useful combination is
::
An example of a very useful combination is::
idf.py openocd gdbgui monitor
.. highlight:: none
The above command runs OpenOCD in the background, starts `gdbgui <https://www.gdbgui.com>`_ to open a browser window
with active debugger frontend and opens a serial monitor in the active console.
The above command runs OpenOCD in the background, starts `gdbgui <https://www.gdbgui.com>`_ to open a browser window
with active debugger frontend and opens a serial monitor in the active console.

8
docs/page_redirects.txt
View File

@ -47,9 +47,9 @@ get-started-cmake/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wr
get-started-cmake/get-started-pico-kit hw-reference/esp32/get-started-pico-kit
get-started-cmake/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3
api-guide/build-system-cmake api-guide/build-system
api-guide/ulp-cmake api-guide/ulp
api-guide/unit-tests-cmake api-guide/unit-tests
api-guides/build-system-cmake api-guides/build-system
api-guides/ulp-cmake api-guides/ulp
api-guides/unit-tests-cmake api-guides/unit-tests
api-reference/network/tcpip_adapter api-reference/network/esp_netif
@ -67,3 +67,5 @@ hw-reference/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-k
hw-reference/get-started-ethernet-kit-v1.0 hw-reference/esp32/get-started-ethernet-kit-v1.0
hw-reference/get-started-ethernet-kit hw-reference/esp32/get-started-ethernet-kit
hw-reference/esp32s2/user-guide-kaluga-1-v1.2 hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit
api-guides/jtag-debugging/configure-wrover api-guides/jtag-debugging/configure-ft2232h-jtag

65
docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst → docs/zh_CN/api-guides/jtag-debugging/configure-ft2232h-jtag.rst
View File

@ -1,52 +1,47 @@
配置 WROVER 上的 JTAG 接口
==========================
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: devkit-defs
:end-before: ---
配置 |devkit-name| 上的 JTAG 接口
=====================================
:link_to_translation:`en:[English]`
所有版本的 ESP-WROVER-KIT 板子都内置了 JTAG 调试功能，要使其正常工作，还需要设置相关跳帽来启用 JTAG 功能，设置 SPI 闪存电压和配置 USB 驱动程序。具体步骤请参考以下说明。
所有版本的 |devkit-name| 板子都内置了 JTAG 调试功能，要使其正常工作，还需要设置相关跳帽来启用 JTAG 功能，设置 SPI 闪存电压和配置 USB 驱动程序。具体步骤请参考以下说明。
配置硬件
^^^^^^^^
1. 根据 :doc:`../../hw-reference/esp32/get-started-wrover-kit` 文档中 :ref:`get-started-esp-wrover-kit-v4.1-setup-options` 章节所描述的信息，设置 JP8 便可以启用 JTAG 功能。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: devkit-hw-config
:end-before: ---
2. 检查 ESP32 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。
+---+---------------+-----------+
| | ESP32 引脚 | JTAG 信号 |
+===+===============+===========+
| 1 | CHIP_PU | TRST_N |
+---+---------------+-----------+
| 2 | MTDO / GPIO15 | TDO |
+---+---------------+-----------+
| 3 | MTDI / GPIO12 | TDI |
+---+---------------+-----------+
| 4 | MTCK / GPIO13 | TCK |
+---+---------------+-----------+
| 5 | MTMS / GPIO14 | TMS |
+---+---------------+-----------+
* 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: jtag-pins
:end-before: ---
配置 USB 驱动
^^^^^^^^^^^^^
安装和配置 USB 驱动，这样 OpenOCD 才能够与 ESP-WROVER-KIT 板上的 JTAG 接口通信，并且使用 UART 接口上传待烧写的镜像文件。请根据你的操作系统按照以下步骤进行安装配置。
安装和配置 USB 驱动，这样 OpenOCD 才能够与 |devkit-name| 板上的 JTAG 接口通信，并且使用 UART 接口上传待烧写的镜像文件。请根据你的操作系统按照以下步骤进行安装配置。
.. note:: ESP-WROVER-KIT 使用了 FT2232 芯片实现了 JTAG 适配器，所以以下说明同样适用于其他基于 FT2232 的 JTAG 适配器。
.. note:: |devkit-name| 使用了 FT2232 芯片实现了 JTAG 适配器，所以以下说明同样适用于其他基于 FT2232 的 JTAG 适配器。
Windows
"""""""
1. 使用标准 USB A / micro USB B 线将 ESP-WROVER-KIT 与计算机相连接，并打开板子的电源。
1. 使用标准 USB A / micro USB B 线将 |devkit-name| 与计算机相连接，并打开板子的电源。
2. 等待 Windows 识别出 ESP-WROVER-KIT 并且为其安装驱动。如果驱动没有被自动安装，请前往 `官网 <https://www.ftdichip.com/Drivers/D2XX.htm>`_ 下载并手动安装。
2. 等待 Windows 识别出 |devkit-name| 并且为其安装驱动。如果驱动没有被自动安装，请前往 `官网 <https://www.ftdichip.com/Drivers/D2XX.htm>`_ 下载并手动安装。
3. 从 `Zadig 官网 <http://zadig.akeo.ie/>`_ 下载 Zadig 工具（Zadig_X.X.exe）并运行。
4. 在 Zadig 工具中，进入 “Options” 菜单中选中 “List All Devices”。
5. 检查设备列表，其中应该包含两条与 ESP-WROVER-KIT 相关的条目：“Dual RS232-HS (Interface 0)” 和 “Dual RS232-HS (Interface 1)”。驱动的名字应该是 “FTDIBUS (vxxxx)” 并且 USB ID 为：0403 6010。
5. 检查设备列表，其中应该包含两条与 |devkit-name| 相关的条目：“Dual RS232-HS (Interface 0)” 和 “Dual RS232-HS (Interface 1)”。驱动的名字应该是 “FTDIBUS (vxxxx)” 并且 USB ID 为：0403 6010。
.. figure:: ../../../_static/jtag-usb-configuration-zadig.jpg
:align: center
@ -55,19 +50,19 @@ Windows
在 Zadig 工具中配置 JTAG USB 驱动
6. 第一个设备 “Dual RS232-HS（Interface 0）” 连接到了 ESP32 的 JTAG 端口，此设备原来的 “FTDIBUS (vxxxx)” 驱动需要替换成 "WinUSB (v6xxxxx)"。为此，请选择 “Dual RS232-HS (Interface 0)” 并将驱动重新安装为 “WinUSB (v6xxxxx)”，具体可以参考上图。
6. 第一个设备 “Dual RS232-HS（Interface 0）” 连接到了 {IDF_TARGET_NAME} 的 JTAG 端口，此设备原来的 “FTDIBUS (vxxxx)” 驱动需要替换成 "WinUSB (v6xxxxx)"。为此，请选择 “Dual RS232-HS (Interface 0)” 并将驱动重新安装为 “WinUSB (v6xxxxx)”，具体可以参考上图。
.. note::
请勿更改第二个设备 “Dual RS232-HS（Interface 1）” 的驱动，它被连接到 ESP32 的串口（UART），用于上传应用程序映像给 ESP32 进行烧写。
请勿更改第二个设备 “Dual RS232-HS（Interface 1）” 的驱动，它被连接到 {IDF_TARGET_NAME} 的串口（UART），用于上传应用程序映像给 {IDF_TARGET_NAME} 进行烧写。
现在，ESP-WROVER-KIT 的 JTAG 接口应该可以被 OpenOCD 使用了，想要进一步设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。
现在，|devkit-name| 的 JTAG 接口应该可以被 OpenOCD 使用了，想要进一步设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。
Linux
"""""
1. 使用标准 USB A / micro USB B 线将 ESP-WROVER-KIT 与计算机相连接，并打开板子的电源。
1. 使用标准 USB A / micro USB B 线将 |devkit-name| 与计算机相连接，并打开板子的电源。
.. highlight:: none
@ -92,9 +87,9 @@ Linux
如果看到类似的输出结果，并且你也是 ``plugdev`` 组的成员， 那么设置工作就完成了。
具有较低编号的 ``/dev/ttyUSBn`` 接口用于 JTAG 通信，另一路接口被连接到 ESP32 的串口（UART），用于上传应用程序映像给 ESP32 进行烧写。
具有较低编号的 ``/dev/ttyUSBn`` 接口用于 JTAG 通信，另一路接口被连接到 {IDF_TARGET_NAME} 的串口（UART），用于上传应用程序映像给 {IDF_TARGET_NAME} 进行烧写。
现在，ESP-WROVER-KIT 的 JTAG 接口应该可以被 OpenOCD 使用了，想要进一步设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。
现在，|devkit-name| 的 JTAG 接口应该可以被 OpenOCD 使用了，想要进一步设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。
MacOS
@ -104,14 +99,14 @@ MacOS
1. 在启动 OpenOCD 之前手动卸载 FTDI 串口驱动程序，然后启动 OpenOCD，再加载串口驱动程序。
2. 修改 FTDI 驱动程序的配置，使其不会为 FT2232 芯片的通道 B 进行自我加载，该通道用于 ESP-WROVER-KIT 板上的 JTAG 通道。
2. 修改 FTDI 驱动程序的配置，使其不会为 FT2232 芯片的通道 B 进行自我加载，该通道用于 |devkit-name| 板上的 JTAG 通道。
手动卸载驱动程序
................
1. 从 `FTDI 官网 <https://www.ftdichip.com/Drivers/VCP.htm>`_ 安装驱动。
2. 使用 USB 线连接 ESP-WROVER-KIT。
2. 使用 USB 线连接 |devkit-name|。
3. 卸载串口驱动 ::
@ -123,7 +118,9 @@ MacOS
4. 运行 OpenOCD::
openocd -f board/esp32-wrover-kit-3.3v.cfg
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd
:end-before: ---
5. 在另一个终端窗口，再一次加载 FTDI 串口驱动::
@ -131,7 +128,7 @@ MacOS
.. note::
如果你需要重启 OpenOCD，则无需再次卸载 FTDI 驱动程序，只需停止 OpenOCD 并再次启动它。只有在重新连接 ESP-WROVER-KIT 或者切换了电源的情况下才需要再次卸载驱动。
如果你需要重启 OpenOCD，则无需再次卸载 FTDI 驱动程序，只需停止 OpenOCD 并再次启动它。只有在重新连接 |devkit-name| 或者切换了电源的情况下才需要再次卸载驱动。
你也可以根据自身需求，将此过程包装进 shell 脚本中。

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

@ -10,41 +10,9 @@
1. 找到 JTAG 接口和 {IDF_TARGET_NAME} 板上需要相互连接并建立通信的引脚/信号。
.. only:: esp32
+---+---------------+-----------+
| | ESP32 引脚 | JTAG 信号 |
+===+===============+===========+
| 1 | CHIP_PU | TRST_N |
+---+---------------+-----------+
| 2 | MTDO / GPIO15 | TDO |
+---+---------------+-----------+
| 3 | MTDI / GPIO12 | TDI |
+---+---------------+-----------+
| 4 | MTCK / GPIO13 | TCK |
+---+---------------+-----------+
| 5 | MTMS / GPIO14 | TMS |
+---+---------------+-----------+
| 6 | GND | GND |
+---+---------------+-----------+
.. only:: esp32s2
+---+-----------------------+-------------+
| | ESP32-S2 Pin | JTAG Signal |
+===+=======================+=============+
| 1 | CHIP_PU | TRST_N |
+---+-----------------------+-------------+
| 2 | MTDO / GPIO40 | TDO |
+---+-----------------------+-------------+
| 3 | MTDI / GPIO41 | TDI |
+---+-----------------------+-------------+
| 4 | MTCK / GPIO39 | TCK |
+---+-----------------------+-------------+
| 5 | MTMS / GPIO42 | TMS |
+---+-----------------------+-------------+
| 6 | GND | GND |
+---+-----------------------+-------------+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: jtag-pins
:end-before: ---
2. 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的的引脚是否被连接到了其它硬件上，这可能会影响 JTAG 的工作。

176
docs/zh_CN/api-guides/jtag-debugging/esp32.inc Normal file
View File

@ -0,0 +1,176 @@
.. This file gets included from other .rst files in this folder.
.. It contains target-specific snippets.
.. Comments and '---' lines act as delimiters.
..
.. This is necessary mainly because RST doesn't support substitutions
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. run-openocd
::
openocd -f board/esp32-wrover-kit-3.3v.cfg
.. |run-openocd-device-name| replace:: 板载 ESP32-WROOM-32 模组的 ESP-WROVER-KIT 开发板
---
.. run-openocd-output
::
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32-wrover-kit-3.3v.cfg
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
none separate
adapter speed: 20000 kHz
force hard breakpoints
Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
Info : clock speed 20000 kHz
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32-wrover-kit-3.3v.cfg``
---
.. run-openocd-upload
::
openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000 verify exit"
---
.. run-openocd-src-linux
.. code-block:: bash
src/openocd -f board/esp32-wrover-kit-3.3v.cfg
---
.. run-openocd-src-win
.. code-block:: batch
src\openocd -f board\esp32-wrover-kit-3.3v.cfg
---
.. idf-py-openocd-default-cfg
.. |idf-py-def-cfg| replace:: ``-f board/esp32-wrover-kit-3.3v.cfg``
---
.. run-openocd-appimage-offset
::
openocd -f board/esp32-wrover-kit-3.3v.cfg -c "init; halt; esp appimage_offset 0x210000"
---
.. openocd-cfg-files
.. list-table:: ESP32 相关的 OpenOCD 配置文件
:widths: 25 75
:header-rows: 1
* - 名字
- 描述
* - ``board/esp32-wrover-kit-3.3v.cfg``
- 板载 3.3V 模组（ESP32-WROOM-32，ESP32-WROVER-B，ESP32-WROVER-E）的 ESP-WROVER-KIT 开发板配置文件
* - ``board/esp32-wrover-kit-1.8v.cfg``
- 板载 1.8V 模组（ESP32-WROVER）的 ESP-WROVER-KIT 开发板配置文件
* - ``board/esp32-ethernet-kit-3.3v.cfg``
- 板载 3.3V 模组（ESP32-WROVER-B / ESP32-WROVER-E）的 ESP-Ethernet-KIT 开发板配置文件
* - ``target/esp32.cfg``
- ESP32 的目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用
* - ``target/esp32-solo-1.cfg``
- ESP32-SOLO-1 的目标配置文件，和 ``esp32.cfg`` 的差别在于它仅配置一个 CPU
* - ``interface/ftdi/esp32_devkitj_v1.cfg``
- 适用于 ESP-WROVER-KIT 和 ESP-Prog 板子的 JTAG 适配器配置文件
---
.. openocd-target-specific-config-vars
.. list-table:: ESP32 相关的 OpenOCD 变量
:widths: 25 75
:header-rows: 1
* - 名字
- 描述
* - ``ESP32_FLASH_VOLTAGE``
- 如果 ESP32 模组集成的是 1.8 V 的 Flash，将该变量设置为 ``1.8``，详情请参考 :ref:`jtag-debugging-tip-code-flash-voltage`
* - ``ESP32_ONLYCPU``
- 对于多核芯片，将该值设置为 ``1`` 可以仅启用单核调试功能
---
.. jtag-pins
.. list-table:: ESP32 引脚和 JTAG 接口信号
:widths: 25 75
:header-rows: 1
* - ESP32 引脚
- JTAG 信号
* - MTDO / GPIO15
- TDO
* - MTDI / GPIO12
- TDI
* - MTCK / GPIO13
- TCK
* - MTMS / GPIO14
- TMS
* - GND
- GND
---
.. run-openocd-d3
::
openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg
---
.. run-openocd-d3-tee
::
openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log
---
.. run-gdb-remotelog
::
xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
---
.. devkit-defs
.. |devkit-name| replace:: ESP-WROVER-KIT
.. |devkit-name-with-link| replace:: :doc:`ESP-WROVER-KIT 开发板 <../../hw-reference/modules-and-boards>`
---
.. devkit-hw-config
* 根据 :doc:`../../hw-reference/esp32/get-started-wrover-kit` 文档中 :ref:`get-started-esp-wrover-kit-v4.1-setup-options` 章节所描述的信息，设置 JP8 便可以启用 JTAG 功能。
---

160
docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc Normal file
View File

@ -0,0 +1,160 @@
.. This file gets included from other .rst files in this folder.
.. It contains target-specific snippets.
.. Comments and '---' lines act as delimiters.
..
.. This is necessary mainly because RST doesn't support substitutions
.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. run-openocd
::
openocd -f board/esp32s2-kaluga-1.cfg
.. |run-openocd-device-name| replace:: ESP32-S2-Kaluga-1 开发板
---
.. run-openocd-output
::
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s2-kaluga-1.cfg
Open On-Chip Debugger v0.10.0-esp32-20200420 (2020-04-20-16:15)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
none separate
adapter speed: 20000 kHz
force hard breakpoints
Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
Info : clock speed 20000 kHz
Info : JTAG tap: esp32s2.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : esp32s2: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32s2: Core was reset (pwrstat=0x5F, after clear 0x0F).
.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s2-kaluga-1.cfg``
---
.. run-openocd-upload
::
openocd -f board/esp32s2-kaluga-1.cfg -c "program_esp filename.bin 0x10000 verify exit"
---
.. run-openocd-src-linux
.. code-block:: bash
src/openocd -f board/esp32s2-kaluga-1.cfg
---
.. run-openocd-src-win
.. code-block:: batch
src\openocd -f board/esp32s2-kaluga-1.cfg
---
.. idf-py-openocd-default-cfg
.. |idf-py-def-cfg| replace:: ``-f board/esp32s2-kaluga-1.cfg``
---
.. run-openocd-appimage-offset
::
openocd -f board/esp32s2-kaluga-1.cfg -c "init; halt; esp appimage_offset 0x210000"
---
.. openocd-cfg-files
.. list-table:: ESP32-S2 相关的 OpenOCD 配置文件
:widths: 25 75
:header-rows: 1
* - 名字
- 描述
* - ``board/esp32s2-kaluga-1.cfg``
- ESP32-S2-Kaluga-1 开发板配置文件，内部已包含 ESP32-S2 目标配置和 JTAG 适配器配置
* - ``target/esp32s2.cfg``
- ESP32-S2 目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用
* - ``interface/ftdi/esp32s2_kaluga_v1.cfg``
- 适用于 ESP32-S2-Kaluga-1 开发板的 JTAG 适配器配置文件
* - ``interface/ftdi/esp32_devkitj_v1.cfg``
- 适用于 ESP-Prog 板子的 JTAG 适配器配置文件
---
.. openocd-target-specific-config-vars
---
---
.. jtag-pins
.. list-table:: ESP32-S2 引脚和 JTAG 接口信号
:widths: 25 75
:header-rows: 1
* - ESP32-S2 引脚
- JTAG 信号
* - MTDO / GPIO40
- TDO
* - MTDI / GPIO41
- TDI
* - MTCK / GPIO39
- TCK
* - MTMS / GPIO42
- TMS
---
.. run-openocd-d3
::
openocd -l openocd_log.txt -d3 -f board/esp32s2-kaluga-1.cfg
---
.. run-openocd-d3-tee
::
openocd -d3 -f board/esp32s2-kaluga-1.cfg 2>&1 | tee openocd.log
---
.. run-gdb-remotelog
::
xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
---
.. devkit-defs
.. |devkit-name| replace:: ESP-S2-Kaluga-1
.. |devkit-name-with-link| replace:: :doc:`ESP-S2-Kaluga-1 <../../hw-reference/modules-and-boards>`
---
.. devkit-hw-config
* 开箱即用，ESP32-S2-Kaluga-1 不需要任何其他硬件配置即可进行 JTAG 调试。 但是，如果遇到问题，请检查 “JTAG” DIP 开关的 2～5 号是否在 “ON” 的位置。
---

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

@ -23,6 +23,12 @@ JTAG 调试
:ref:`jtag-debugging-tips-and-quirks`
介绍使用 OpenOCD 和 GDB 通过 JTAG 接口调试 {IDF_TARGET_NAME} 时的注意事项和补充内容。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: devkit-defs
:end-before: ---
.. _jtag-debugging-introduction:
引言
@ -39,7 +45,7 @@ JTAG 调试
本文将指导如何在 Linux，Windows 和 MacOS 环境下为 {IDF_TARGET_NAME} 安装 OpenOCD，并使用 GDB 进行软件调试。除了个别操作系统的安装过程有所差别以外，软件用户界面和使用流程都是一样的。
.. note::
本文使用的图片素材来自于 Ubuntu 16.04 LTE 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows， MacOS 或者 Linux）和 Eclipse 软件版本在用户界面上可能会有细微的差别。
本文使用的图片素材来自于 Ubuntu 16.04 LTS 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows， MacOS 或者 Linux）和 Eclipse 软件版本在用户界面上可能会有细微的差别。
.. _jtag-debugging-how-it-works:
@ -60,7 +66,7 @@ JTAG 调试
`Eclipse <https://www.eclipse.org/>`__ 环境集成了 JTAG 调试和应用程序加载、监视的功能，它使得软件从编写、编译、加载到调试的迭代过程变得更加快速而简单。所有的软件均适用于 Windows，Linux 和 MacOS 平台。
如果你使用的是 :doc:`ESP-WROVER-KIT 开发板 <../../hw-reference/modules-and-boards>`，得益于板载的 FT232H 芯片，PC 和 {IDF_TARGET_NAME} 的连接仅仅需要一根 USB 线即可完成。FT232H 提供了两路 USB 通道，一路连接到 JTAG，另一路连接到 UART。
如果你使用的是 |devkit-name-with-link|，得益于板载的 FT232H 芯片，PC 和 {IDF_TARGET_NAME} 的连接仅仅需要一根 USB 线即可完成。FT232H 提供了两路 USB 通道，一路连接到 JTAG，另一路连接到 UART。
根据用户的喜好，除了使用 Eclipse 集成开发环境，还可以直接在命令行终端运行 `debugger` 和 `idf.py build`。
@ -69,7 +75,7 @@ JTAG 调试
选择 JTAG 适配器
----------------
上手 JTAG 最快速便捷的方式是使用 :doc:`ESP-WROVER-KIT 开发板 <../../hw-reference/modules-and-boards>`，因为它板载了 JTAG 调试接口，无需使用外部的 JTAG 硬件适配器和额外的线缆来连接 JTAG 与 {IDF_TARGET_NAME}。ESP-WROVER-KIT 采用 FT2232H 提供的 JTAG 接口，可以稳定运行在 20 MHz 的时钟频率，外接的适配器很难达到这个速度。
上手 JTAG 最快速便捷的方式是使用 |devkit-name-with-link|，因为它板载了 JTAG 调试接口，无需使用外部的 JTAG 硬件适配器和额外的线缆来连接 JTAG 与 {IDF_TARGET_NAME}。|devkit-name| 采用 FT2232H 提供的 JTAG 接口，可以稳定运行在 20 MHz 的时钟频率，外接的适配器很难达到这个速度。
如果你想使用单独的 JTAG 适配器，请确保其与 {IDF_TARGET_NAME} 的电平电压和 OpenOCD 软件都兼容。{IDF_TARGET_NAME} 使用的是业界标准的 JTAG 接口，它省略了（实际上也并不需要）TRST 信号脚。JTAG 使用的 IO 引脚由 VDD_3P3_RTC 电源引脚供电（通常连接到外部 3.3 V 的电源轨），因此 JTAG 硬件适配器的引脚需要能够在该电压范围内正常工作。
@ -127,7 +133,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
.. toctree::
:maxdepth: 1
:esp32: configure-wrover
configure-ft2232h-jtag
configure-other-jtag
@ -140,35 +146,26 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
.. highlight:: bash
打开终端，按照快速入门中的指南 :ref:`设置好开发环境 <get-started-set-up-env>` ，然后运行如下命令，启动 OpenOCD（该命令在 Windows，Linux，和 macOS 中通用）::
打开终端，按照快速入门中的指南 :ref:`设置好开发环境 <get-started-set-up-env>` ，然后运行如下命令，启动 OpenOCD（该命令在 Windows，Linux，和 macOS 中通用）:
openocd -f board/esp32-wrover-kit-3.3v.cfg
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd
:end-before: ---
.. note::
上述命令中 ``-f`` 选项后跟的配置文件专用于板载 esp32-wroom-32 模组的 ESP-WROVER-KIT 开发板。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。
上述命令中 ``-f`` 选项后跟的配置文件专用于 |run-openocd-device-name|。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。
.. highlight:: none
现在应该可以看到如下输入（此日志来自 ESP-WROVER-KIT）::
现在应该可以看到如下输入（此日志来自 |run-openocd-device-name|）:
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32-wrover-kit-3.3v.cfg
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
none separate
adapter speed: 20000 kHz
force hard breakpoints
Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
Info : clock speed 20000 kHz
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-output
:end-before: ---
- 如果出现指示权限问题的错误，请参阅 ``~/esp/openocd-esp32`` 目录下 OpenOCD README 文件中关于 “Permissions delegation” 的说明。
- 如果发现配置文件有错误，例如 ``Can't find board/esp32-wrover-kit-3.3v.cfg``，请检查 ``-s`` 后面的路径，OpenOCD 会根据此路径来查找 ``-f`` 指定的文件。此外，还需要检查配置文件是否确实位于该路径下。
- 如果发现配置文件有错误，例如 |run-openocd-cfg-file-err|，请检查 ``-s`` 后面的路径，OpenOCD 会根据此路径来查找 ``-f`` 指定的文件。此外，还需要检查配置文件是否确实位于该路径下。
- 如果看到 JTAG 错误（输出全是 1 或者全是 0），请检查硬件连接，除了 {IDF_TARGET_NAME} 的引脚之外是否还有其他信号连接到了 JTAG，并查看是否所有器件都已经上电。
@ -179,9 +176,11 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
您可以像往常一样构建并上传 {IDF_TARGET_NAME} 应用程序，具体请参阅 :ref:`get-started-build` 章节。
除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下::
除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下:
openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000 verify exit"
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-upload
:end-before: ---
其中 OpenOCD 的烧写命令 ``program_esp`` 具有以下格式：
@ -250,23 +249,31 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
.. highlight:: bash
如果要使用本地从源代码编译的 OpenOCD 程序，需要将相应可执行文件的路径修改为 ``src/openocd``，并设置 ``OPENOCD_SCRIPTS`` 环境变量，这样 OpenOCD 才能找到配置文件。Linux 和 macOS 用户可以执行::
如果要使用本地从源代码编译的 OpenOCD 程序，需要将相应可执行文件的路径修改为 ``src/openocd``，并设置 ``OPENOCD_SCRIPTS`` 环境变量，这样 OpenOCD 才能找到配置文件。Linux 和 macOS 用户可以执行:
.. code-block:: bash
cd ~/esp/openocd-esp32
export OPENOCD_SCRIPTS=$PWD/tcl
Windows 用户可以执行::
Windows 用户可以执行:
.. code-block:: batch
cd %USERPROFILE%\esp\openocd-esp32
set "OPENOCD_SCRIPTS=%CD%\tcl"
运行本地编译的 OpenOCD 的示例如下（Linux 和 macOS 用户）::
运行本地编译的 OpenOCD 的示例如下（Linux 和 macOS 用户）:
src/openocd -f board/esp32-wrover-kit-3.3v.cfg
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-src-linux
:end-before: ---
Windows 用户::
Windows 用户:
src\openocd -f board\esp32-wrover-kit-3.3v.cfg
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-src-win
:end-before: ---
.. _jtag-debugging-tips-and-quirks:

170
docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst
View File

@ -27,7 +27,7 @@
为了在闪存中设置或者清除软件断点，OpenOCD 需要知道它们在闪存中的地址。为了完成从 {IDF_TARGET_NAME} 的地址空间到闪存地址的转换，OpenOCD 使用闪存中程序代码区域的映射。这些映射被保存在程序映像的头部，位于二进制数据（代码段和数据段）之前，并且特定于写入闪存的每一个应用程序的映像。因此，为了支持软件闪存断点，OpenOCD 需要知道待调试的应用程序映像在闪存中的位置。默认情况下，OpenOCD 会在 0x8000 处读取分区表并使用第一个找到的应用程序映像的映射，但是也可能会存在无法工作的情况，比如分区表不在标准的闪存位置，甚至可能有多个映像：一个出厂映像和两个 OTA 映像，你可能想要调试其中的任意一个。为了涵盖所有可能的调试情况，OpenOCD 支持特殊的命令，用于指定待调试的应用程序映像在闪存中的具体位置。该命令具有以下格式：
``esp32 appimage_offset <offset>``
``esp appimage_offset <offset>``
偏移量应为十六进制格式，如果要恢复默认行为，可以将偏移地址设置为 ``-1`` 。
@ -35,7 +35,9 @@
由于 GDB 在连接 OpenOCD 时仅仅请求一次内存映射，所以可以在 TCL 配置文件中指定该命令，或者通过命令行传递给 OpenOCD。对于后者，命令行示例如下：
``openocd -f board/esp32-wrover-kit-3.3v.cfg -c "init; halt; esp32 appimage_offset 0x210000"``
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-appimage-offset
:end-before: ---
另外还可以通过 OpenOCD 的 telnet 会话执行该命令，然后再连接 GDB， 不过这种方式似乎没有那么便捷。
@ -76,9 +78,9 @@ OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRT
ESP32 的 MTDI 引脚是用于 JTAG 通信的四个引脚之一，同时也是 ESP32 的 bootstrapping 引脚。上电时，ESP32 会在 MTDI 引脚上采样二进制电平，据此来设置内部的稳压器，用于给外部的 SPI 闪存芯片供电。如果上电时 MTDI 引脚上的二进制电平为低电平，则稳压器会被设置为 3.3 V；如果 MTDI 引脚为高电平，则稳压器会被设置为 1.8 V。MTDI 引脚通常需要一个上拉电阻或者直接使能内部的弱下拉电阻（详见 `ESP32 系列芯片技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>`_ ），具体取决于所使用的 SPI 芯片的类型。但是一旦连接上 JTAG 后，原来用于实现 bootstrapping 功能的上拉或者下拉电阻都会被覆盖掉。
为了解决这个问题，OpenOCD 的板级配置文件（例如 ESP32-WROOM-32 模组的 ``boards\esp-wroom-32.cfg``）提供了 ``ESP32_FLASH_VOLTAGE`` 参数来设置 ``TDO`` 信号线在空闲状态下的二进制电平，这样就可以减少由于闪存电压不正确而导致的应用程序启动不良的几率。
为了解决这个问题，OpenOCD 的板级配置文件（例如 ESP-WROVER-KIT 开发板的 ``board\esp32-wrover-kit-3.3v.cfg``）提供了 ``ESP32_FLASH_VOLTAGE`` 参数来设置 ``TDO`` 信号线在空闲状态下的二进制电平，这样就可以减少由于闪存电压不正确而导致的应用程序启动不良的几率。
查看 JTAG 连接的 ESP32 模组的规格书，检查其 SPI 闪存芯片的供电电压值，然后再相应的设置 ``ESP32_FLASH_VOLTAGE``。大多数的 WROOM 模组使用 3.3 V 的闪存芯片，但是 WROVER 模组使用 1.8 V 的闪存芯片。
查看 JTAG 连接的 ESP32 模组的规格书，检查其 SPI 闪存芯片的供电电压值，然后再相应的设置 ``ESP32_FLASH_VOLTAGE``。大多数WROOM模块使用 3.3 V 的闪存芯片。 早于 ESP32-WROVER-B 的 WROVER 模块使用 1.8 V 闪存芯片，而ESP32-WROVER-B和-E模块使用 3.3 V 闪存芯片。
.. _jtag-debugging-tip-optimize-jtag-speed:
@ -113,93 +115,68 @@ OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRT
.. _jtag-debugging-tip-openocd-configure-target:
针对特定目标的 OpenOCD 配置
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Configuration of OpenOCD for specific target
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OpenOCD 需要知道当前使用的 JTAG 适配器的类型，以及其连接的目标板和处理器的类型。为此，请使用位于 OpenOCD 安装目录下 ``share/openocd/scripts/interface`` 和 ``share/openocd/scripts/board`` 文件夹中现有的配置文件。
There are several kinds of OpenOCD configuration files (``*.cfg``). All configuration files are located in subdirectories of ``share/openocd/scripts`` directory of OpenOCD distribution (or ``tcl/scripts`` directory of the source repository). For the purposes of this guide, the most important ones are ``board``, ``interface`` and ``target``.
例如，如果使用板载 ESP-WROOM-32 模组的 ESP-WROVER-KIT 开发板，请使用以下配置文件：
* ``interface`` configuration files describe the JTAG adapter. Examples of JTAG adapters are ESP-Prog and J-Link.
* ``target`` configuration files describe specific chips, or in some cases, modules.
* ``board`` configuration files are provided for development boards with a built-in JTAG adapter. Such files include an ``interface`` configuration file to choose the adapter, and ``target`` configuration file to choose the chip/module.
* ``board/esp32-wrover-kit-3.3v.cfg``
The following configuration files are available for {IDF_TARGET_NAME}:
当然也可以使用自定义的配置文件，建议在已有配置文件的基础上进行修改，以匹配你的硬件。下面列举一些常用的板级配置参数。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: openocd-cfg-files
:end-before: ---
.. highlight:: none
If you are using one of the boards which have a pre-defined configuration file, you only need to pass one ``-f`` argument to OpenOCD, specifying that file.
适配器的时钟速度
""""""""""""""""
If you are using a board not listed here, you need to specify both the interface configuration file and target configuration file.
::
Custom configuration files
""""""""""""""""""""""""""
adapter_khz 20000
OpenOCD configuration files are written in TCL, and include a variety of choices for customization and scripting. This can be useful for non-standard debugging situations. Please refer to `OpenOCD Manual`_ for the TCL scripting reference.
请参阅 :ref:`jtag-debugging-tip-optimize-jtag-speed` 以获取有关如何设置此值的指导。
.. _jtag-debugging-tip-openocd-config-vars:
OpenOCD configuration variables
"""""""""""""""""""""""""""""""
.. only:: esp32
The following variables can be optionally set before including the ESP-specific target configuration file. This can be done either in a custom configuration file, or from the command line.
单核调试
""""""""
The syntax for setting a variable in TCL is:
::
.. code-block:: tcl
set ESP32_ONLYCPU 1
set VARIABLE_NAME value
如果是双核调试，请注释掉这一行。
To set a variable from the command line (replace the name of .cfg file with the correct file for your board):
.. code-block:: bash
禁用 RTOS 支持
""""""""""""""
openocd -c 'set VARIABLE_NAME value' -f board/esp-xxxxx-kit.cfg
::
It is important to set the variable before including the ESP-specific configuration file, otherwise the variable will not have effect. You can set multiple variables by repeating the ``-c`` option.
set ESP32_RTOS none
.. list-table:: Common ESP-related OpenOCD variables
:widths: 25 75
:header-rows: 1
如果要支持 RTOS， 请注释掉这一行。
* - Variable
- Description
* - ``ESP_RTOS``
- Set to ``none`` to disable RTOS support. In this case, thread list will not be available in GDB. Can be useful when debugging FreeRTOS itself, and stepping through the scheduler code.
* - ``ESP_FLASH_SIZE``
- Set to ``0`` to disable Flash breakpoints support.
* - ``ESP_SEMIHOST_BASEDIR``
- Set to the path (on the host) which will be the default directory for semihosting functions.
.. only:: esp32
ESP32 的 SPI 闪存芯片的电源电压
""""""""""""""""""""""""""""""""""
::
set ESP32_FLASH_VOLTAGE 1.8
如果 SPI 闪存芯片的电源电压为 3.3 V， 请注释掉这一行，更多信息请参阅： :ref:`jtag-debugging-tip-code-flash-voltage`。
ESP32 的目标配置文件
""""""""""""""""""""
::
source [find target/esp32.cfg]
.. note::
除非你熟悉 OpenOCD 内部的工作原理，否则请不要更改 ``source [find target/esp32.cfg]`` 这一行。
目前 ``target/esp32.cfg`` 仍然是 ESP32 目标（esp108 和 esp32）的唯一配置文件。支持的配置矩阵如下所示：
+---------------+---------------+---------------+
| Dual/single | RTOS | Target used |
+===============+===============+===============+
| dual | FreeRTOS | esp32 |
+---------------+---------------+---------------+
| single | FreeRTOS | esp108 (*) |
+---------------+---------------+---------------+
| dual | none | esp108 |
+---------------+---------------+---------------+
| single | none | esp108 |
+---------------+---------------+---------------+
(*) — 我们计划修复此问题，并在后续提交中添加对 esp32 目标的单核调试的支持。
更多信息，请查看 ``board/esp-wroom-32.cfg`` 配置文件的注释部分。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: openocd-target-specific-config-vars
:end-before: ---
.. _jtag-debugging-tip-reset-by-debugger:
@ -217,36 +194,14 @@ OpenOCD 需要知道当前使用的 JTAG 适配器的类型，以及其连接的
如果除了 {IDF_TARGET_NAME} 模组和 JTAG 适配器之外的其他硬件也连接到了 JTAG 引脚，那么 JTAG 的操作可能会受到干扰。{IDF_TARGET_NAME} JTAG 使用以下引脚：
.. only:: esp32
+---+----------------+-------------+
| | ESP32 JTAG Pin | JTAG Signal |
+===+================+=============+
| 1 | MTDO / GPIO15 | TDO |
+---+----------------+-------------+
| 2 | MTDI / GPIO12 | TDI |
+---+----------------+-------------+
| 3 | MTCK / GPIO13 | TCK |
+---+----------------+-------------+
| 4 | MTMS / GPIO14 | TMS |
+---+----------------+-------------+
.. only:: esp32s2
+---+-----------------------+-------------+
| | ESP32-S2 Pin | JTAG Signal |
+===+=======================+=============+
| 1 | MTDO / GPIO40 | TDO |
+---+-----------------------+-------------+
| 2 | MTDI / GPIO41 | TDI |
+---+-----------------------+-------------+
| 3 | MTCK / GPIO39 | TCK |
+---+-----------------------+-------------+
| 4 | MTMS / GPIO42 | TMS |
+---+-----------------------+-------------+
如果用户应用程序更改了 JTAG 引脚的配置，JTAG 通信可能会失败。如果 OpenOCD 正确初始化（检测到两个 Tensilica 内核），但在程序运行期间失去了同步并报出大量 DTR/DIR 错误，则应用程序可能将 JTAG 引脚重新配置为其他功能或者用户忘记将 Vtar 连接到 JTAG 适配器。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: jtag-pins
:end-before: ---
.. highlight:: none
下面是 GDB 在应用程序进入重新配置 MTDO/GPIO15 作为输入代码后报告的一系列错误摘录::
@ -302,23 +257,26 @@ To disable software breakpoints while using JTAG, add an extra argument ``-c 'se
OpenOCD 端：
::
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-d3
:end-before: ---
openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg
这种方式会将日志输出到文件，但是它会阻止调试信息打印在终端上。当有大量信息需要输出的时候（比如调试等级提高到 ``-d3``）这是个不错的选择。如果你仍然希望在屏幕上看到调试日志，请改用以下命令：
这种方式会将日志输出到文件，但是它会阻止调试信息打印在终端上。当有大量信息需要输出的时候（比如调试等级提高到 ``-d3``）这是个不错的选择。如果你仍然希望在屏幕上看到调试日志，请改用以下命令：
::
openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-d3-tee
:end-before: ---
Debugger 端：
::
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-gdb-remotelog
:end-before: ---
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
也可以将命令 ``remotelogfile gdb_log.txt`` 添加到 ``gdbinit`` 文件中。
也可以将命令 ``remotelogfile gdb_log.txt`` 添加到 ``gdbinit`` 文件中。
4. 请将 ``openocd_log.txt`` 和 ``gdb_log.txt`` 文件附在你的问题报告中。
.. _OpenOCD Manual: http://openocd.org/doc/html/index.html

44
docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst
View File

@ -188,3 +188,47 @@
注意上面日志的倒数第三行显示了调试器已经在 ``app_main()`` 函数的断点处停止，该断点在 ``gdbinit`` 文件中设定。由于处理器已经暂停运行，LED 也不会闪烁。如果这也是你看到的现象，你可以开始调试了。
如果你不太了解 GDB 的常用方法，请查阅 :ref:`jtag-debugging-examples-command-line` 文章中的调试示例章节 :ref:`jtag-debugging-examples`。
.. _jtag-debugging-with-idf-py:
使用 idf.py 进行调试
^^^^^^^^^^^^^^^^^^^^
我们还可以使用 ``idf.py`` 更方便地执行上述提到的调试命令：
1. ``idf.py openocd``
在终端中运行 OpenOCD，其配置信息来源于环境变量或者命令行。默认会使用 ``OPENOCD_SCRIPTS`` 环境变量中指定的脚本路径，它是由 ESP-IDF 项目仓库中的导出脚本（``export.sh`` or ``export.bat``）添加到系统环境变量中的。
当然，我们可以在命令行中通过 ``--openocd-scripts`` 来覆盖这个变量的值。
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: idf-py-openocd-default-cfg
:end-before: ---
你可以定义 ``OPENOCD_COMMANDS`` 环境变量来指定当前开发板的 JTAG 配置，或者通过 ``--openocd-commands`` 传递该参数。如果这两者都没有被定义，那么 OpenOCD 会使用 |idf-py-def-cfg| 参数来启动。
2. ``idf.py gdb``
根据当前项目的 elf 文件自动生成 gdb 启动脚本， 然后会按照 :ref:`jtag-debugging-using-debugger-command-line` 中所描述的步骤启动 GDB。
3. ``idf.py gdbtui``
和步骤 2 相同，但是会在启动 GDB 的时候传递 ``tui`` 参数，这样可以方便在调试过程中查看源代码。
4. ``idf.py gdbgui``
启动 `gdbgui <https://www.gdbgui.com>`_，在浏览器中打开调试器的前端界面。
上述这些命令也可以合并到一起使用，``idf.py`` 会自动将后台进程（比如 openocd）最先运行，交互式进程（比图 gdb， monitor）最后运行。
常用的组合命令如下所示::
idf.py openocd gdbgui monitor
上述命令会将 OpenOCD 运行至后台，然后启动 `gdbgui <https://www.gdbgui.com>`_ 打开一个浏览器窗口，显示调试器的前端界面，最后在活动终端打开串口监视器。

13
tools/idf_py_actions/debug_ext.py
View File

@ -155,16 +155,19 @@ def action_extensions(base_actions, project_path):
"""
Execute openocd as external tool
"""
OPENOCD_TAGET_CONFIG = {
"esp32": "-f board/esp32-wrover-kit-3.3v.cfg",
"esp32s2": "-f board/esp32s2-kaluga-1.cfg",
}
if os.getenv("OPENOCD_SCRIPTS") is None:
raise FatalError("OPENOCD_SCRIPTS not found in the environment: Please run export.sh/export.bin", ctx)
raise FatalError("OPENOCD_SCRIPTS not found in the environment: Please run export.sh/export.bat", ctx)
openocd_arguments = os.getenv("OPENOCD_COMMANDS") if openocd_commands is None else openocd_commands
project_desc = get_project_desc(args, ctx)
if openocd_arguments is None:
# use default value if commands not defined in the environment nor command line
if project_desc["target"] == "esp32":
openocd_arguments = "-f board/esp32-wrover-kit-3.3v.cfg"
else:
openocd_arguments = "-f interface/ftdi/esp32_devkitj_v1.cfg -f target/{}.cfg".format(project_desc["target"])
target = project_desc["target"]
default_args = "-f interface/ftdi/esp32_devkitj_v1.cfg -f target/{}.cfg".format(target)
openocd_arguments = OPENOCD_TAGET_CONFIG.get(target, default_args)
print('Note: OpenOCD cfg not found (via env variable OPENOCD_COMMANDS nor as a --openocd-commands argument)\n'
'OpenOCD arguments default to: "{}"'.format(openocd_arguments))
# script directory is taken from the environment by OpenOCD, update only if command line arguments to override