月度归档： 2026 年 4 月

Zephyr 提供了一个内置的状态机框架（SMF – State Machine Framework），位于 smf.h 和 smf.c。

核心数据结构

状态定义：struct smf_state

struct smf_state {
    const state_execution entry;  // 进入状态时调用
    const state_execution run;    // 状态运行时反复调用
    const state_execution exit;   // 退出状态时调用
    const struct smf_state *parent; // 父状态（仅层次状态机）
};

状态机上下文：struct smf_ctx

struct smf_ctx {
    const struct smf_state *current;   // 当前状态
    const struct smf_state *previous;  // 上一个状态
    int32_t terminate_val;             // 终止值
    uint32_t internal;                 // 内部标志
};

核心 API

两种模式

1. 扁平状态机（默认）

每个状态相互独立，无父子关系：

#include <zephyr/smf.h>

/* 定义状态枚举 */
enum my_state { STATE_A, STATE_B, STATE_C };

/* 用户对象（第一个成员必须是 smf_ctx）*/
static struct my_obj {
    struct smf_ctx ctx;    // 必须是第一个成员
    int event;
} obj;

/* 状态处理函数 */
static void state_a_entry(void *o) { /* 进入 A */ }
static void state_a_run(void *o) {
    struct my_obj *self = (struct my_obj *)o;
    if (self->event == 1)
        smf_set_state(SMF_CTX(o), &states[STATE_B]); // 转换到 B
}
static void state_a_exit(void *o) { /* 退出 A */ }

/* 状态表 */
static const struct smf_state states[] = {
    [STATE_A] = SMF_CREATE_STATE(state_a_entry, state_a_run, state_a_exit),
    [STATE_B] = SMF_CREATE_STATE(NULL, state_b_run, NULL),
    [STATE_C] = SMF_CREATE_STATE(NULL, state_c_run, NULL),
};

int main(void) {
    smf_set_initial(SMF_CTX(&obj), &states[STATE_A]); // 初始化

    while (1) {
        // 处理事件，更新 obj.event ...
        int ret = smf_run_state(SMF_CTX(&obj)); // 运行一次迭代
        if (ret) break; // 非零表示终止
    }
}

2. 层次状态机（开启 CONFIG_SMF_ANCESTOR_SUPPORT）

子状态共享父状态的行为，父状态的 entry/exit 在进入/退出子状态时自动执行（同级切换时不重复执行）：

// 父状态
static const struct smf_state states[] = {
    [PARENT_AB] = SMF_CREATE_STATE(parent_entry, parent_run, parent_exit, NULL),
    [STATE_A]   = SMF_CREATE_STATE(a_entry, a_run, a_exit, &states[PARENT_AB]),
    [STATE_B]   = SMF_CREATE_STATE(b_entry, b_run, b_exit, &states[PARENT_AB]),
    [STATE_C]   = SMF_CREATE_STATE(c_entry, c_run, c_exit, NULL), // 无父状态
};

层次状态机中执行顺序规则：

• entry：父状态先于子状态执行
• run：子状态先执行，若无状态转换则父状态再执行
• exit：子状态先于父状态执行
• 同级切换（A→B，共享 PARENT_AB）：父状态的 exit/entry 不重新执行

状态转换流程

smf_run_state() 调用 current->run()
        │
        └─ 内部调用 smf_set_state(ctx, new_state)
                │
                ├─ 执行 current->exit()
                ├─（层次模式）执行祖先 exit()
                ├─ 更新 ctx->current = new_state
                ├─（层次模式）执行祖先 entry()
                └─ 执行 new_state->entry()

Kconfig 选项

在 prj.conf 中启用：

CONFIG_SMF=y
CONFIG_SMF_ANCESTOR_SUPPORT=y  # 启用层次状态机（可选）

测试用例在 test_lib_flat_smf.c 和 test_lib_hierarchical_smf.c 中有完整示例，可参考学习。

SMF 对 Zephyr 的依赖非常少，移植到 FreeRTOS 主要需要处理以下几个方面：

依赖分析

smf.h 中的 Zephyr 依赖

smf.c 中的 Zephyr 依赖

具体修改步骤

第一步：新建 smf.h

#ifndef SMF_H_
#define SMF_H_

#include <stdint.h>
#include <stdbool.h>

/* 开启层次状态机支持，不需要则注释掉 */
#define SMF_ANCESTOR_SUPPORT

#ifdef SMF_ANCESTOR_SUPPORT
#define SMF_CREATE_STATE(_entry, _run, _exit, _parent) \
{ \
    .entry  = _entry, \
    .run    = _run,   \
    .exit   = _exit,  \
    .parent = _parent \
}
#else
#define SMF_CREATE_STATE(_entry, _run, _exit) \
{ \
    .entry = _entry, \
    .run   = _run,   \
    .exit  = _exit   \
}
#endif

#define SMF_CTX(o) ((struct smf_ctx *)o)

typedef void (*state_execution)(void *obj);

struct smf_state {
    const state_execution entry;
    const state_execution run;
    const state_execution exit;
#ifdef SMF_ANCESTOR_SUPPORT
    const struct smf_state *parent;
#endif
};

struct smf_ctx {
    const struct smf_state *current;
    const struct smf_state *previous;
    int32_t terminate_val;
    uint32_t internal;
};

void    smf_set_initial(struct smf_ctx *ctx, const struct smf_state *init_state);
void    smf_set_state(struct smf_ctx *ctx, const struct smf_state *new_state);
void    smf_set_terminate(struct smf_ctx *ctx, int32_t val);
int32_t smf_run_state(struct smf_ctx *ctx);

#endif /* SMF_H_ */

第二步：修改 smf.c

// 原来
#include <zephyr/smf.h>
#include <zephyr/logging/log.h>
LOG_MODULE_REGISTER(smf);

// 替换为
#include "smf.h"
#include <stdio.h>  // 用于 printf（可选）

// 原来
LOG_WRN("Calling %s from exit action", __func__);

// 替换为（或直接删掉这行）
printf("[SMF WRN] Calling %s from exit action\n", __func__);

// 原来
__unused static bool smf_execute_ancestor_entry_actions(...)
__unused static bool smf_execute_ancestor_run_actions(...)
__unused static bool smf_execute_ancestor_exit_actions(...)

// 替换为（GCC 通用属性）
__attribute__((unused)) static bool smf_execute_ancestor_entry_actions(...)

// 原来
if (IS_ENABLED(CONFIG_SMF_ANCESTOR_SUPPORT)) { ... }

// 替换为
#ifdef SMF_ANCESTOR_SUPPORT
    // ... 相关代码
#endif

总结

SMF 的核心逻辑（smf.c 中约 286 行）完全不依赖 FreeRTOS 任何 API，它只是一个纯 C 的状态机调度框架，没有涉及任务、队列、信号量等 RTOS 原语。

移植工作量非常小，归纳为 4 件事：

1. 将 #include <zephyr/kernel.h> 改为 <stdint.h> + <stdbool.h>
2. 将 CONFIG_SMF_ANCESTOR_SUPPORT 改为普通 #define，并将 IS_ENABLED(...) 改为 #ifdef
3. 删除 Zephyr 日志相关代码（LOG_MODULE_REGISTER、LOG_WRN）
4. 将 __unused 改为 __attribute__((unused)) 或直接删除

--specs=nano.specs (newlib-nano) 的影响

1. printf / sprintf 格式化限制

2. 堆内存相关

• malloc / free 使用的是精简版分配器
• 没有线程安全保护（裸机无所谓，FreeRTOS下需注意）
• _sbrk 需要你自己实现，否则 malloc 会 HardFault

3. 本地化 / 宽字符

• 不支持 wprintf / wchar_t 相关函数
• setlocale() 无效，中文字符处理受限

4. 文件 I/O

• fopen / fread 等是空桩（配合 nosys.specs）
• 需要自己实现 _write / _read 才能让 printf 输出到串口

5. 数学库

• libm 体积同样缩减，部分精度受影响
• 建议显式链接：-lm

⚠️ 最容易踩的坑，嵌入式中一定要自己重定向输出函数

/* [ARMCC] retarget the C library printf function to the USART */
int fputc(int ch, FILE *f)
{
    USART_Data_Send(USART2, (uint8_t)ch);
    while (USART_Flag_Status_Get(USART2, USART_FLAG_TXDE) == RESET)
        ;
    return (ch);
}

/* [GCC] retarget the C library printf function to the USART */
int _write(int file, char *data, int len)
{
    // if ((file != STDOUT_FILENO) && (file != STDERR_FILENO))
    // {
    //     errno = EBADF;
    //     return -1;
    // }
    for (int i = 0; i < len; i++) {
        USART_Data_Send(USART2, data[i]);
        while (USART_Flag_Status_Get(USART2, USART_FLAG_TXDE) == RESET)
            ;
    }
    return 0;
}

如果 _write 没有实现或者实现有误，printf 调用会静默丢弃所有输出