esp-gdbstub

Intro

ESP8266 debugging tool intended to be used with esp-open-rtos. Based on Espressif/esp-gdbstub.

Usage

1. Build requires premake5 and xtensa-lx106-elf toolchain. Make sure both are in your PATH.

2. Configure with premake5 gmake. The following options are supported:

   • --with-eor=/path/to/esp-open-rtos: this option is required. It should point to an actual esp-open-rtos location.
   • --with-threads: enable RTOS task debugging. As for now, there is very basic support of threads, you will be able
     to see multiple tasks when a breakpoint is hit, but GDB will most likely crash shorlty after. This option also has
     a performance impact because a lot of data will be transferred through serial connection consider increasing
     the baudrate.

   When thread support is enabled, you need to add the following definitions to CFLAGS of your project before compiling FreeRTOS libs:

   EXTRA_CFLAGS+=-DportREMOVE_STATIC_QUALIFIER -DINCLUDE_pcTaskGetTaskName=1
   
   # The line above should go before including common.mk
   

   Run make clean after switching the state of this flag.

3. Run make

4. Add library to your project:

   PROGRAM=blink
   
   # Order is important!
   
   EXTRA_CFLAGS+=-I../../../esp-gdbstub/include
   EXTRA_LDFLAGS+=-L../../../esp-gdbstub/lib
   
   include ../../common.mk
   
   LIBS+=esp-gdbstub
   PROGRAM_CFLAGS+=-O0
   

5. Call gdbstub_init() after configuring UART speed.

Optimization, stack trace resolving and GDB

It has been observed that GDB may crash when user requests step over source in a file compiled with optimization turned on. I haven't figured out why exactly this happens, but it has something to do with stack frame resolving. Turning optimization off for the whole project would impact performance and code size that's why only PROGRAM_CFLAGS is modified.

Eclipse CDT setup

To use Eclipse CDT for debugging, open Eclipse, create a new project and create a debug configuration for C/C++ Remote Application.

You need to set the following options:

1. Main Application: Firmware ELF
2. Debugger: Uncheck Stop on startup at: main
3. Debugger Main: select GDB binary and .gdbinit file provided with esp-gdbstub
4. Debugger Connection Type: Serial
5. Debugger Connection Speed: 115200

Note that upon launching the debug session gdb will send continue command if the target is paused at gdbstub_do_break. If you want to stop right after debug session launch, place gdbstub_do_break macro twice in your code.

Notes

• Using software breakpoints ('br') only works on code that's in RAM. Code in flash can only have a hardware breakpoint ('hbr'). If you know where you want to break before downloading the program to the target, you can use gdbstub_do_break() macro as much as you want.
• Due to hardware limitations, only one hardware breakpount and one hardware watchpoint are available.