ESP32 Forum

Posted: **Mon Apr 28, 2025 7:30 am**

I had an idea to trigger a runtime gdbstub `CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME` during application execution. The idea came about when I implemented a quick panic stub assertion:

Code: Select all

#if CONFIG_ESP_SYSTEM_PANIC_STUB
#define ASSERT_GDB(expr)                                   \
    do {                                                   \
        if (!(expr)) {                                     \
            __builtin_trap();                              \
        }                                                  \
    } while (0)

This works, but this will cause a hardfault and I cannot continue my application from here, I essentially have to restart.
It would go something like this:

Code: Select all

#if CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME
#define ASSERT_GDB(expr)                                   \
    do {                                                   \
        if (!(expr)) {                                     \
            esp_gdbstub_handle_command("S", 2);            \
        }                                                  \
    } while (0)
#elif CONFIG_ESP_SYSTEM_PANIC_STUB
#define ASSERT_GDB(expr)                                   \
    do {                                                   \
        if (!(expr)) {                                     \
            __builtin_trap();                              \
        }                                                  \
    } while (0)
#else
    #define ASSERT_GDB(expr)
#endif

I think this idea will help everyone have a faster and smoother dev debug cycle.

Posted: **Sat Jul 11, 2026 1:38 pm**

核心概念通俗讲解
1. 什么是 gdbstub？
ESP32 的 GDB Stub 是芯片内置调试服务，通过串口 / JTAG 和电脑 GDB 调试器通信：
普通 Panic Stub（CONFIG_ESP_SYSTEM_PANIC_STUB）：只有程序崩溃、断言失败、死机时才启动 GDB；一旦触发 __builtin_trap() 硬件断点，CPU 卡死，调试完不能继续跑，必须重启。
Runtime GDBstub（CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME）：运行时调试桩，程序正常运行时随时手动触发暂停进入 GDB，调试完毕可以 continue 恢复程序继续执行，不用重启。
2. 作者原来代码的问题
__builtin_trap() 是 GCC 内置指令，直接触发 CPU 异常，属于致命故障：芯片进入崩溃处理流程，栈、任务环境被锁定，GDB 调试后无法恢复运行，只能复位。
3. 作者的改进思路
开启 CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME 后，调用 esp_gdbstub_handle_command("S", 2)：
主动发送 GDB 标准停止信号，温和暂停程序，不是崩溃；
电脑 GDB 连接后可以查看变量、栈、任务；
调试完成输入 c 即可恢复程序正常运行，不用重启板子。
4. ASSERT_GDB 宏作用
自定义断言：当括号内表达式为假（逻辑错误、数值异常）时，自动停下程序进入调试：
c
ASSERT_GDB(x > 0); // 如果x<=0，立刻暂停进GDB调试
两套配置自动兼容，不用手动改代码切换调试方式。
5. 适用场景
业务逻辑偶现 bug，不想设备频繁重启；
需要在线查看运行状态、任务内存、变量，保留现场继续跑流程；
代替传统死机式断言，缩短开发调试周期（帖子说 faster smoother dev cycle）。

ESP32 Forum

Debugging: Trigger runtime gdbstub from during execution

Debugging: Trigger runtime gdbstub from during execution

Re: Debugging: Trigger runtime gdbstub from during execution