Chapter 4. API Guides
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 ESP32-S2 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:
esp appimage_offset <offset>
Offset should be in hex format. To reset to the default behaviour you can specify -1 as offset.
Note: 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/esp32s2-kaluga-1.cfg -c "init; halt; esp appimage_offset 0x210000"
Another option is to execute that command via OpenOCD telnet session and then connect GDB, but it seems to be
less handy.
Why stepping with “next”does not bypass subroutine calls? When stepping through the code with next
command, GDB is internally setting a breakpoint (one out of two available) ahead in the code to bypass the subroutine
calls. This functionality will not work, if the two available breakpoints are already set elsewhere in the code. If this
is the case, delete breakpoints to have one“spare”. With both breakpoints already used, stepping through the code
with next command will work as like with step command and debugger will step inside subroutine calls.
Support options for OpenOCD at compile time ESP-IDF has some support options for OpenOCD debugging
which can be set at compile time:
• CONFIG_ESP32S2_DEBUG_OCDAWARE is enabled by default. If a panic or unhandled exception is thrown
and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
• CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK (disabled by default) sets watchpoint index 1 (the
second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows.
Click the link for more details.
Please see the project configuration menu menu for more details on setting compile-time options.
FreeRTOS support OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS tasks
as threads. Viewing them all can be done using the GDB i threads command, changing to a certain task is
done with thread n, with n being the number of the thread. FreeRTOS detection can be disabled in target’s
configuration. For more details see Configuration of OpenOCD for specific target.
Optimize JTAG speed In order to achieve higher data rates and minimize number of dropped packets it is rec-
ommended to optimize setting of JTAG clock frequency, so it is at maximum and still provides stable operation of
JTAG. To do so use the following tips.
1. The upper limit of JTAG clock frequency is 20 MHz if CPU runs at 80 MHz, or 26 MHz if CPU runs at 160
MHz or 240 MHz.
2. Depending on particular JTAG adapter and the length of connecting cables, you may need to reduce JTAG
frequency below 20 / 26 MHz.
3. In particular reduce frequency, if you get DSR/DIR errors (and they do not relate to OpenOCD trying to read
from a memory range without physical memory being present there).
4. ESP-WROVER-KIT operates stable at 20 / 26 MHz.
Espressif Systems 1383
Submit Document Feedback
Release v4.4