:link_to_translation:zh_CN:[中文]
This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using GDB.
Note
You can also debug your {IDF_TARGET_NAME} without needing to setup JTAG or OpenOCD by using idf.py monitor. See: ../../api-guides/tools/idf-monitor and CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME.
none
The document is structured as follows:
jtag-debugging-introductionIntroduction to the purpose of this guide.
jtag-debugging-how-it-worksDescription how {IDF_TARGET_NAME}, JTAG interface, OpenOCD and GDB are interconnected and working together to enable debugging of {IDF_TARGET_NAME}.
jtag-debugging-selecting-jtag-adapterWhat are the criteria and options to select JTAG adapter hardware.
jtag-debugging-setup-openocdProcedure to install OpenOCD and verify that it is installed.
jtag-debugging-configuring-targetConfiguration of OpenOCD software and setting up of JTAG adapter hardware, which together make up the debugging target.
jtag-debugging-launching-debuggerSteps to start up a debug session with GDB from
jtag-debugging-using-debugger-eclipseand fromjtag-debugging-using-debugger-command-line.jtag-debugging-examplesIf you are not familiar with GDB, check this section for debugging examples provided from
jtag-debugging-examples-eclipseas well as fromjtag-debugging-examples-command-line.jtag-debugging-building-openocdProcedure to build OpenOCD from sources for
Windows <building-openocd-windows>,Linux <building-openocd-linux>andmacOS <building-openocd-macos>operating systems.jtag-debugging-tips-and-quirksThis section provides collection of tips and quirks related to JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB.
esp32
The ESP32 has two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeRTOS OS that comes with ESP-IDF is capable of multi-core preemptive scheduling, allowing for an intuitive way of writing software.
The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that is caused by two threads, running even simultaneously on two different CPU cores, can take a long time when all you have are printf() statements. A better (and in many cases quicker) way to debug such problems is by using a debugger, connected to the processors over a debug port.
Espressif has ported OpenOCD to support the {IDF_TARGET_NAME} processor and the multi-core FreeRTOS (which is the foundation of most {IDF_TARGET_NAME} apps). Additionally, some extra tools have been written to provide extra features that OpenOCD does not support natively.
This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using GDB under Linux, Windows and macOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems.
Note
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.
The key software and hardware components that perform debugging of {IDF_TARGET_NAME} with OpenOCD over JTAG (Joint Test Action Group) interface is presented in the diagram below under the "Debugging With JTAG" label. These components include {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb debugger, OpenOCD on chip debugger, and the JTAG adapter connected to {IDF_TARGET_NAME} target.
Likewise, the "Application Loading and Monitoring" label indicates the key software and hardware components that allow an application to be compiled, built, and flashed to {IDF_TARGET_NAME}, as well as to provide means to monitor diagnostic messages from {IDF_TARGET_NAME}.
"Debugging With JTAG" and "Application Loading and Monitoring" is integrated under the Eclipse IDE in order to provide a quick and easy transition between writing/compiling/loading/debugging code. The Eclipse IDE (and the integrated debugging software) is available for Windows, Linux and macOS platforms. Depending on user preferences, both the debugger and idf.py build can also be used directly from terminal/command line, instead of Eclipse.
esp32 or esp32s2
If the 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 other for UART connection.
SOC_USB_SERIAL_JTAG_SUPPORTED
The connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the {IDF_TARGET_NAME} chip itself, which provides two USB channels, one for JTAG and the other for the USB terminal connection. The USB cable should be connected to the D+/D- USB pins of {IDF_TARGET_NAME} and not to the serial RxD/TxD through a USB-to-UART chip. The proper connection is explained later in subsection jtag-debugging-configuring-target.
esp32c3
Note
Debugging through the USB interface implemented in {IDF_TARGET_NAME} requires to have a chip with revision 0.3 or newer. Please use other debugging options (e.g., with ESP-Prog) for chip revisions 0.1 and 0.2. The easiest way to determine the chip revision is to look for the boot: chip revision: v0.3 message at the beginning of the boot log. See SoC errata for more details.
esp32 or esp32s2
The quickest and most convenient way to start with JTAG debugging is by using . Each version of this development board has JTAG interface already built in. No need for an external JTAG adapter and extra wiring/cable to connect JTAG to {IDF_TARGET_NAME}. is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
SOC_USB_SERIAL_JTAG_SUPPORTED
The quickest and most convenient way to start with JTAG debugging is through a USB cable connected to the D+/D- USB pins of {IDF_TARGET_NAME}. No need for an external JTAG adapter and extra wiring/cable to connect JTAG to {IDF_TARGET_NAME}.
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.
On the software side, OpenOCD supports a fair amount of JTAG adapters. See https://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the {IDF_TARGET_NAME} does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g., ST-LINK debugging adapters for STM32 families, will not work.
The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the {IDF_TARGET_NAME} power line to a line called e.g., Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the {IDF_TARGET_NAME}, although for now, support in OpenOCD for that line is pretty minimal.
ESP-Prog is an example for using an external board for debugging by connecting it to the JTAG pins of {IDF_TARGET_NAME}.
bash
If you have already set up ESP-IDF with CMake build system according to the Getting Started Guide <../../get-started/index>, then OpenOCD is already installed. After setting up the environment <get-started-set-up-env> in your terminal, you should be able to run OpenOCD. Check this by executing the following command:
openocd --versionnone
The output should be as follows (although the version may be more recent than listed here):
Open On-Chip Debugger v0.12.0-esp32-20240318 (2024-03-18-18:25)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.htmlYou may also verify that OpenOCD knows where its configuration scripts are located by printing the value of OPENOCD_SCRIPTS environment variable, by typing echo $OPENOCD_SCRIPTS (for Linux and macOS) or echo %OPENOCD_SCRIPTS% (for Windows). If a valid path is printed, then OpenOCD is set up correctly.
If any of these steps do not work, please go back to the setting up the tools <get-started-set-up-tools> section (for Linux and macOS) or ESP-IDF Tools Installer <get-started-windows-tools-installer> (for Windows) section of the Getting Started Guide.
Note
It is also possible to build OpenOCD from source. Please refer to jtag-debugging-building-openocd section for details.
Once OpenOCD is installed, you can proceed to configuring the {IDF_TARGET_NAME} target (i.e {IDF_TARGET_NAME} board with JTAG interface). Configuring the target is split into the following three steps:
jtag-debugging-configure-and-connect-JTAG-interfacejtag-debugging-run-openocdjtag-upload-app-debug
This step depends on the JTAG and {IDF_TARGET_NAME} board you are using (see the two cases described below).
- esp32
configure-ft2232h-jtag
- esp32s2
configure-ft2232h-jtag
- SOC_USB_SERIAL_JTAG_SUPPORTED
configure-builtin-jtag
configure-other-jtag
Once target is configured and connected to computer, you are ready to launch OpenOCD.
bash
Open a terminal and set it up for using the ESP-IDF as described in the 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):
{IDF_TARGET_FTDI_CONFIG:default="Not Updated!", esp32s3="board/esp32s3-ftdi.cfg", esp32c3="board/esp32c3-ftdi.cfg", esp32c6="board/esp32c6-ftdi.cfg", esp32h2="board/esp32h2-ftdi.cfg"}
Note
The files provided after -f above are specific for . You may need to provide different files depending on the hardware that is used. For guidance see jtag-debugging-tip-openocd-configure-target.
SOC_USB_SERIAL_JTAG_SUPPORTED
For example, {IDF_TARGET_FTDI_CONFIG} can be used for a custom board with an FT2232H or FT232H chip used for JTAG connection, or with ESP-Prog.
none
You should now see similar output (this log is for ):
- If there is an error indicating permission problems, please see section on "Permissions delegation" in the OpenOCD README file located in the
~/esp/openocd-esp32directory. - In case there is an error in finding the configuration files, e.g., , check if the
OPENOCD_SCRIPTSenvironment variable is set correctly. This variable is used by OpenOCD to look for the files specified after the-foption. Seejtag-debugging-setup-openocdsection for details. Also check if the file is indeed under the provided path. - If you see JTAG errors (e.g.,
...all onesor...all zeroes), please check your JTAG connections, whether other signals are connected to JTAG besides {IDF_TARGET_NAME}'s pins, and see if everything is powered on correctly.
Build and upload your application to {IDF_TARGET_NAME} as usual, see get-started-build.
Another option is to write application image to flash using OpenOCD via JTAG with commands like this:
OpenOCD flashing command program_esp has the following format:
program_esp <image_file> <offset> [verify] [reset] [exit] [compress] [encrypt]
image_file- Path to program image file.offset- Offset in flash bank to write image.verify- Optional. Verify flash contents after writing.reset- Optional. Reset target after programming.exit- Optional. Finally exit OpenOCD.compress- Optional. Compress image file before programming.encrypt- Optional. Encrypt binary before writing to flash. Same functionality withidf.py encrypted-flash
You are now ready to start application debugging. Follow the steps described in the section below.
The toolchain for {IDF_TARGET_NAME} features GNU Debugger, in short GDB. It is available with other toolchain programs under filename: {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb. GDB can be called and operated directly from command line in a terminal. Another option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI instead of typing commands in a terminal.
The options of using debugger are discussed under links below.
jtag-debugging-using-debugger-eclipsejtag-debugging-using-debugger-command-line- Configuration for Visual Studio Code Debug
It is recommended to first check if debugger works from jtag-debugging-using-debugger-command-line and then move to using jtag-debugging-using-debugger-eclipse.
This section is intended for users not familiar with GDB. It presents example debugging session from jtag-debugging-examples-eclipse using simple application available under get-started/blink and covers the following debugging actions:
jtag-debugging-examples-eclipse-01jtag-debugging-examples-eclipse-02jtag-debugging-examples-eclipse-03jtag-debugging-examples-eclipse-04jtag-debugging-examples-eclipse-05jtag-debugging-examples-eclipse-06jtag-debugging-examples-eclipse-07
Similar debugging actions are provided using GDB from jtag-debugging-examples-command-line.
Note
jtag-debugging-examples-command-line-08 is currently only available for command line debugging.
Before proceeding to examples, set up your {IDF_TARGET_NAME} target and load it with get-started/blink.
Please refer to separate documents listed below, that describe build process.
Windows <building-openocd-windows> Linux <building-openocd-linux> macOS <building-openocd-macos>
The examples of invoking OpenOCD in this document assume using pre-built binary distribution described in section jtag-debugging-setup-openocd.
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:
cd ~/esp/openocd-esp32
export OPENOCD_SCRIPTS=$PWD/tclFor Windows:
cd %USERPROFILE%\esp\openocd-esp32
set "OPENOCD_SCRIPTS=%CD%\tcl"Example of invoking OpenOCD build locally from sources, for Linux and macOS:
and Windows:
This section provides collection of links to all tips and quirks referred to from various parts of this guide.
tips-and-quirks
- maxdepth
1
using-debugger debugging-examples tips-and-quirks ../app_trace
using-debuggerdebugging-examplestips-and-quirks../app_trace- Introduction to ESP-Prog Board