ESP32 uses gdbgui for JTAG debugging

In this blog, you will learn how to use gdbgui for ESP32 JTAG debugging. The blog will be divided into the following sections:

1. gdbgui installation
1. ESP-Prog/Jlink hardware wiring method
1. Open OpenOCD
1. Open gdbgui and debug
1. gdbgui related operations

1. Installation of gdbgui

There are two mainstream installation methods for gdbgui (from the official gdbgui tutorial ):

Install using pipx
Install using pip

1.1 Use pipx to install (recommended)

Enter the following in the terminal to install pipx:

python3 -m pip install --user pipx
python3 -m userpath append ~/.local/bin

Then use pipx to install gdbgui

pipx install gdbgui

To upgrade run

pipx upgrade gdbgui

When the installation is complete, enter in a terminal gdbguito run gdbgui to, or enter gdbgui -hto view the help

If you want to uninstall gdbgui, type in the terminal

pipx uninstall gdbgui

You can also use pipx without installing gdbgui and use it directly, enter the following command in the terminal:

pipx run gdbgui

Then gdbgui will automatically open in your browser.

1.2 Use pip to install

Method 2: Using pip
If you prefer to use a virtual environment, you can activate a virtual environment and run:

pip install gdbgui

You can update gdbgui with the following command:

pip install --upgrade gdbgui

If you want to uninstall gdbgui, type in the terminal:

pip uninstall gdbgui

2. ESP-Prog/Jlink hardware wiring method

If you want to use JTAG/Jlink for debugging, you need to make some additional preparations on the hardware, which will not be repeated in this blog. For details, please enter the following link:

3. Install & open OpenOCD

3.1 Install OpenOCD

If you have installed ESP-IDF and its CMake build system as described in the esp-idf Quick Start article, then OpenOCD has been installed by default in your development system. After setting up the development environment, you should be able to run the following OpenOCD command in the terminal to check the OpenOCD version:

openocd --version

3.2 into the `openocd-esp32`directory

First you need to enter in the terminal openocd-esp32directory:

cd ~/esp/openocd-esp32/v0.10.0-esp32-20200406/openocd-esp32

Above openocd-esp32directory follow their openocd-esp32adjusts the directory.

View 3.3 `openocd-esp32`version (such as the use Jlink, you need to pay attention to this step, others please ignore)

Then you need to check openocd-esp32the version, the general has been marked in the corresponding folder, for example /esp/openocd-esp32/v0.10.0-esp32-20200406. If it is version 2019 or earlier, please ignore this step and jump directly to it 3.3 运行 openocd-esp32. If it is version 2020 and later, you need to do the following:

Enter openocd-esp32the following directories: /esp/openocd-esp32/v0.10.0-esp32-20200309/openocd-esp32/share/openocd/scripts/interfaceIn interfacelocate the folder jlink.cfgand open
In jlink.cfgadding adapter_khz 9600, then save and close the file (if not added in the subsequent run will be given instructions openocd)

Add adapter_khz 9600post jlink.cfgshould read as follows:

#
# SEGGER J-Link
#
# http://www.segger.com/jlink.html
#

interface jlink
adapter_khz 9600

# The serial number can be used to select a specific device in case more than
# one is connected to the host.
#
# Example: Select J-Link with serial number 123456789
#
# jlink serial 123456789

3.4 Operation `openocd-esp32`

Finally, you only need to use the following command to run openocd-esp32, here to ensure that the debugger has been connected by the above hardware configuration, such as the use Jlink also need to ensure that the 2020 version has been 3.2 查看 openocd-esp32 版本in the configuration. The default command openocd -s $OPENOCD_PATH/scripts/ -f "source [find interface/$DEBUG_DEVICE.cfg]" -f $OPENOCD_TARGET_SCRIPTis: .

Example: Using the JTAG debug Jlink performed when `3.3 运行 openocd-esp32`a corresponding operation instruction

Corresponding operation:

In the terminal into the corresponding openocd-esp32directory
Configuration and operation openocd-esp32

Terminal command:

cd ~/esp/openocd-esp32/v0.10.0-esp32-20200406/openocd-esp32
./bin/openocd -s share/openocd/scripts -f interface/jlink.cfg \
-f board/esp-wroom-32.cfg

Special attention: Please paste the second and third lines of the above instructions into the terminal together. Because the single-line instruction is too long, unnecessary errors will occur when directly converted to PDF (using \ + carriage return to carry out the instruction line feed).

Above openocd-esp32directory follow their openocd-esp32adjusts the directory. Above -f board/esp-wroom-32.cfgplease adjust according to their actual use of the development board.

4. Open gdbgui and debug

4.1 Compile and write the program that needs to be debugged

First, you need to compile and burn the program to be debugged into ESP32 (refer to the ESP-IDF Quick Start ), and you need to find and record the path where the corresponding elf file exists. For example, to compile and burn esp-idf Lane examples/getting-started/hello_worldafter example, you can in the examples/getting-started/hello_world/builddirectory to find hello-world.elfthe file. The path is at this time /home/username/esp/esp-idf/examples/get-started/hello_world/build/hello-world.elf.

4.2 Open & configure gdbgui

Use the following command to open gdbgui:

pipx run gdbgui --gdb $PATH_TO_ARM_GDB

Where you need to $PATH_TO_ARM_GDBchange your address corresponding tool gdb computer, such as gdb present in /home/username/.espressif/tools/xtensa-esp32-elf/esp-2020r1-8.2.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gdbthe can use the following commands:

pipx run gdbgui --gdb /home/username/.espressif/tools/xtensa-esp32-elf/esp-2020r1-8.2.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gdb

You will find that gdbgui will automatically open on your browser, and then you need to configure the following:

Enter in the console at the bottom of the gdbgui interface target remote :3333
In gdbgui the top of the screen Load Binary, enter the 4.1 编译烧写需要调试的程序elf address file to be debugged program is compiled

You can also use pipx run gdbgui --gdb xtensa-esp32-elf-gdb "build/hello-world.elf"to omit Load Binarysteps.

At this time, the debugged code should be displayed in the graphical interface, and you can start debugging, if prompted Function "main" not defined.. Simply add power off at the entrance of the app_main function and continue debugging. The instructions are as follows:

b app_main
c

thb app_main
c

The following is an introduction to different types of breakpoints

break(b) ordinary breakpoint
tbreak(tb) represents a temporary breakpoint, if you pause at this breakpoint, then this breakpoint will be automatically deleted
The parameter after rbreak(rb) is a regular expression, and all function names that match the regular expression are set as breakpoints
hbread(hb) hardware-assisted breakpoints, generally related to specific hardware
thbreak(thb) represents a hardware-assisted temporary breakpoint. Is a compound of tbreak and hbreak

Then you can try to enter the relevant commands gdb for debugging, such as input list, you can see the console output app_main function in the code. At this point, the gdbgui interface is as follows:
Insert picture description here
Start using gdbgui to debug ESP32~

4.3 Knowledge extension: generation & operation of gdbinit configuration file (not required)

The configuration of gdbgui can also be referred gdbinitto as follows:

target remote :3333
set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
thb app_main
c

First you have to write in the current directory gdbinitfile, then you also need to create another in the home directory .gdbinitfiles, and .gdbinitwrites the following years:

set auto-load safe-path /
set print pretty on
set print elements 0

After completing the above configuration, every time you open gdbgui, the gdbinit file in the current directory will be automatically run to help us with the initial configuration.

5. gdbgui related operations

The basic instructions are as follows:

carry on:c
Next step:n
Jump:s
Improvement:u

6. Related Resources

For other commands & API of gdbgui, please refer to: gdbgui API