14、状态机调试：日志打印、状态跟踪、断点调试技巧

状态机写完了，跑起来了，然后呢？

十有八九，第一次运行结果是不对的。我做了这么多年嵌入式，还没见过谁的状态机一次跑通。状态跳错了、动作没执行、条件没触发……这些坑我全踩过。今天聊聊怎么把状态机调明白。

14.1 调试三板斧：日志、跟踪、断点

调试状态机，说白了就三招：日志打印让你看到发生了什么，状态跟踪让你知道怎么发生的，断点调试让你揪出为什么发生。这三招配合着用，大部分问题都能定位。

14.2 日志打印：给状态机装上黑匣子

日志是调试的第一道防线。我个人习惯，在状态机里至少打三种日志：状态进入日志、状态退出日志、事件触发日志。

// 状态机日志宏定义
#define SM_LOG(fmt, ...) \
    printf("[SM][%lu] " fmt "\r\n", get_tick_ms(), ##__VA_ARGS__)

// 状态进入时打印
void door_state_entry(door_state_t *me) {
    SM_LOG("STATE_ENTRY: %s", state_name(me->current_state));
    // 实际进入逻辑...
}

// 状态退出时打印
void door_state_exit(door_state_t *me) {
    SM_LOG("STATE_EXIT: %s", state_name(me->current_state));
    // 实际退出逻辑...
}

// 事件处理时打印
void door_state_handle(door_state_t *me, event_t *evt) {
    SM_LOG("EVENT: %s -> %s", 
           state_name(me->current_state), 
           event_name(evt->type));
    // 实际处理逻辑...
}

我在项目中遇到过一个问题：门禁系统偶尔会卡在某个状态不动。加了日志后发现，原来是某个事件在特定时序下被丢弃了。日志一打，问题就现形了。

14.3 状态跟踪：可视化你的状态机

日志是文本的，看多了眼睛疼。状态跟踪，说白了就是把状态机的运行过程画出来。我常用的方法有两种：

14.3.1 状态轨迹记录

用一个环形缓冲区，记录最近N次状态跳转。这样出问题时，可以回放状态机的运行轨迹。

#define TRACE_DEPTH 64

typedef struct {
    state_t from_state;
    state_t to_state;
    event_t trigger_event;
    uint32_t timestamp;
} trace_record_t;

typedef struct {
    trace_record_t records[TRACE_DEPTH];
    uint8_t head;
    uint8_t count;
} state_trace_t;

void trace_push(state_trace_t *trace, 
                state_t from, state_t to, 
                event_t *evt) {
    trace_record_t *rec = &trace->records[trace->head];
    rec->from_state = from;
    rec->to_state = to;
    rec->trigger_event = evt->type;
    rec->timestamp = get_tick_ms();
    
    trace->head = (trace->head + 1) % TRACE_DEPTH;
    if (trace->count < TRACE_DEPTH) {
        trace->count++;
    }
}

void trace_dump(state_trace_t *trace) {
    int start = (trace->count < TRACE_DEPTH) ? 0 : trace->head;
    int count = trace->count;
    
    for (int i = 0; i < count; i++) {
        int idx = (start + i) % TRACE_DEPTH;
        trace_record_t *rec = &trace->records[idx];
        printf("[%u] %s --(%s)--> %s\r\n",
               rec->timestamp,
               state_name(rec->from_state),
               event_name(rec->trigger_event),
               state_name(rec->to_state));
    }
}

14.3.2 状态机流程图可视化

下面这张图，是我调试状态机时常用的思维导图。它帮你理清状态、事件、动作之间的关系。

14.4 断点调试：精准打击问题点

日志和跟踪能告诉你「发生了什么」，但有时候你需要知道「为什么」。这时候断点调试就派上用场了。

14.4.1 条件断点

在状态机里，我最常用的断点技巧是条件断点。比如，我只想在状态跳转到某个特定状态时停下来。

// 在状态机主循环中设置条件断点
void state_machine_run(state_machine_t *sm) {
    while (1) {
        // 在这里设置断点，条件：sm->current_state == STATE_ERROR
        event_t *evt = get_next_event(sm);
        if (evt) {
            state_transition(sm, evt);
        }
    }
}

嗯，这里要注意：条件断点在某些IDE里会拖慢执行速度。如果状态机跑得很快，条件断点可能漏掉。我一般先用日志缩小范围，再用断点精准定位。

14.4.2 数据观察点

有些问题不是状态跳转错了，而是状态机的内部数据被意外修改了。这时候数据观察点（Watchpoint）比断点好用。

// 在调试器中设置数据观察点
// 监视 sm->internal_flags 这个变量
// 当它被修改时，调试器会自动停下来

typedef struct {
    state_t current_state;
    uint32_t internal_flags;  // 监视这个变量
    uint32_t timeout_value;
    // ...
} state_machine_t;

14.5 调试工具链推荐

工具用对了，事半功倍。下面是我常用的调试工具组合：

调试场景	推荐工具	适用场景
日志打印	SEGGER RTT / UART	实时性要求不高，需要长时间记录
状态跟踪	自定义环形缓冲区	需要回放状态机运行轨迹
断点调试	J-Link / ST-Link + IDE	精准定位问题点
数据观察	IDE Watchpoint	追踪变量被意外修改
时序分析	逻辑分析仪	分析状态机与外部信号的时序关系

14.6 实战：调试一个状态机bug

说个真实案例。我之前做的一个智能锁项目，状态机在「开锁」状态下偶尔会卡死。日志显示状态已经跳转到「开锁」，但电机没转。

我加了更详细的日志，发现状态进入动作里调用了电机驱动函数，但函数返回了错误码。再往下查，原来是电机驱动的初始化在状态机启动前没完成。

你看，问题不在状态机本身，而在外部依赖的时序。这就是为什么我强调：调试状态机，不要只盯着状态机本身，还要看它和外部模块的交互。

调试状态机，说白了就是「看轨迹、查日志、断点定位」三步走。别一上来就断点单步，先看日志和轨迹，缩小范围再上断点。这样效率最高。