电子产品世界 » 论坛首页 » 嵌入式开发 » STM32 » 嵌入式防错神器:编译期断言与运行时断言

共2条 1/1 1 跳转至页

嵌入式防错神器:编译期断言与运行时断言

菜鸟
2026-11-17 15:40:58     打赏
嵌入式断言:从编译期静态断言到运行时错误现场

comp_tool.zip

一些老嵌入式朋友可能会有疑问:断言是什么?断言是什么,我干了嵌入式好长时间了从来没有用过这个功能,你是不是在哄骗我使用这个功能,这个功能在嵌入式领域真的有用吗?那么作为21 世纪的新青年我就要开始犯颜直谏(笔者只是不想要你们放弃这么好的功能罢了,我能有什么坏心思呢嘿嘿)了,断言的价值在于把“应该永远成立的假设”写成代码,让编译器或运行时替我们检查。一旦假设失效,程序可以在发生错误的位置留下文件名、行号和现场信息,而不是莫名其妙地走进 HardFault,我们还要慢慢地栈回溯才能查找错误。

相信大家在嵌入式中都看到类似的代码:

#if 条件1
    // 条件1成立
#elif 条件2
    // 条件1不成立,条件2成立
#else
    // 所有条件都不成立
#endif

那么在现在,随着 cmake 的流行,我们可以在 CMakeLists.txt 里用 target_compile_definitions 添加两种宏:不分模式的 BUFFER_SIZE=64,以及仅在 Debug 模式下起作用的 $<$<CONFIG:Debug>:MCU_DEBUG_BUILD>(完整写法见 2.2)。笔者的断言实现就依赖 MCU_DEBUG_BUILD。

通过断言我们可以快速地在编译期间(编译报错)和运行期间(配合日志打印 uart、usb、RTT 等)快速定位问题出现的位置,配合 __FILE__、__LINE__、__func__ 可以快速地定位问题出现在哪一个文件、哪一行和哪一个函数,在日常使用中,断言出错不一定出现在函数中,也可能是空指针等,因此笔者以 __FILE__、__LINE__ 的方式进行开发,那么现在就正式进行讲解(本章内容对 RTT 实战篇有铺垫作用)。

本文从编译期的 STATIC_ASSERT 讲到运行时的 ASSERT / VERIFY,再用通信帧、DR16/SBUS 位域和 Cortex-M7 Cache Line 三个场景把写法落地。文中的 sizeof 结果来自实际编译(ARM GCC 与 MinGW GCC),换编译器时请以静态断言的结果为准。

断言失败的现场通过 LOG_ERROR 输出,实际工程里可以走 UART、USB 或 RTT;如果你还没搭好 RTT,可以先看 嵌入式芯片调试神器-J-LinkRTT。

感谢:说起来断言,回想起了第一次了解到断言时的高兴以及大佬对我的解答(人生贵人),感谢刘总带我入门嵌入式,可以说没有刘总,我现在还是个天天卡在 keil 的古人,我宣布我将一直热爱 xr(真心),同时感谢 https://forum.eepw.com.cn/ 给予我继续书写技术文章的兴趣和支持。

一、为什么嵌入式需要断言

1.1 从一次 HardFault 说起

没有断言时,一个典型的翻车现场是这样的:协议解析函数把长度写错,数组越界踩坏了旁边的变量;程序继续跑,几毫秒后某个完全不相干的任务触发 HardFault。你打开调试器,看到的是异常时的 PC、LR 和栈帧,真正的原因可能已经在几万条指令之前。栈回溯当然能查,但它要求你会看寄存器、会读反汇编,还得有完好的栈——而现场往往已经被踩坏了。

断言把这件事提前:在越界发生之前检查帧长 len == 8u,失败时直接打印 长度不匹配 和表达式 len == 8u。你不是在异常发生后猜,而是在假设被破坏的第一现场停下来。

场景没有断言有断言
通信帧长度写错数组越界,踩坏其他变量,最后 HardFaultASSERT(len == 8u) 停在解析函数
DMA 缓冲区没对齐Cache 回写踩数据,偶发、难复现静态断言或初始化断言直接暴露
空指针跳到非法地址,栈回溯打印 file:line:expression,一眼定位

1.2 断言使用场景

嵌入式工程中常见的场景包括:

  • 当规定了上位机和下位机传入长度时:上位机和下位机协议帧必须是固定长度,例如 8 字节。

  • 一些协议的字节长度要求,例如 SBUS:SBUS 接收帧必须是 25 字节,首字节和结束字节符合协议约定。

  • 接收和发送数据的结构体成员位置要求:结构体成员的偏移量必须符合线上协议格式。(这也是在开发中常见的使用位域 : 的原因)

  • 满足 Cortex-M7 的 Cache 的内存对齐要求:DMA 缓冲区的起始地址和大小必须满足 Cortex-M7 D-Cache 的 Cache Line 要求。(笔者被 Cache 折磨好长时间)

这些检查可以分成两类:

  • 编译期检查:使用 static_assert 或 C11 的 _Static_assert。条件不满足时,编译直接失败。

  • 运行时检查:使用 assert、自定义 ASSERT 或始终生效的 VERIFY。条件不满足时,记录现场并进入错误处理。

注意:断言不是错误恢复机制。对“用户输入错误、通信超时、传感器暂时离线”这类可预期事件,应该用正常的返回值、错误码和状态机处理;断言负责的是“按设计不该发生”的程序缺陷。正式产品还要靠看门狗、错误码和安全状态兜底——断言不是万能的。

二、两种检查时机与工程配置

2.1 编译期检查与运行时检查

对比项编译期检查运行时检查
工具STATIC_ASSERT、static_assertASSERT、VERIFY、标准 assert
检查对象常量表达式:sizeof、offsetof、枚举、对齐变量、指针、返回值、状态
失败表现编译错误,生成不了固件日志 + 停机或复位
运行成本0少量代码和 RAM,日志有额外开销
适用场景协议布局、类型宽度、配置约束不变量、边界、硬件调用结果

使用原则:能在编译期解决的,不要拖到运行时。协议结构体的大小、成员偏移、类型宽度、对齐要求,都是编译期就能确定的常量,这些尽量在编译期间解决,防止运行时出问题造成坏影响(接一次线很麻烦的好吧)。

2.2 用 CMake 区分 Debug 与 Release

Debug 打开 ASSERT,Release 保留 VERIFY,这是笔者推荐的做法。用 CMake 的生成器表达式,把 MCU_DEBUG_BUILD 只加进 Debug 配置:

target_compile_definitions(app PRIVATE
    BUFFER_SIZE=64
    $<$<CONFIG:Debug>:MCU_DEBUG_BUILD>
)

$<CONFIG:Debug> 只在当前配置是 Debug 时展开,因此 BUFFER_SIZE=64 两种配置都有,MCU_DEBUG_BUILD 只在 Debug 下存在。

对于单配置生成器(Makefile、Ninja),还要显式指定构建类型:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build

多配置生成器(Visual Studio、Xcode、Ninja Multi-Config)不使用 CMAKE_BUILD_TYPE,而是在构建时指定:

cmake --build build --config Debug

注意:两种方式不要混着配,给多配置生成器传 CMAKE_BUILD_TYPE 通常不会生效,结果就是宏没加上、断言没打开,所以说要明确使用哪一种类型(笔者还是喜欢 vscode 的 cmake 的“一键生成”)。

2.3 宏约定

笔者的代码约定如下:

宏DebugRelease作用
STATIC_ASSERT(expr, msg)编译期检查编译期检查检查常量假设
ASSERT(expr)检查并进入故障处理不执行 expr检查程序员假设
VERIFY(expr)检查并处理仍然检查并处理检查必须执行的安全条件
RM_UNUSED(x)消除未使用参数警告消除未使用参数警告保持编译器警告干净

ASSERT 和 VERIFY 的区别只有一句话:Release 下还要不要执行并检查。如果一个表达式包含必须执行的硬件操作,例如清除中断标志、写寄存器或更新状态,就不能放进会在 Release 中消失的 ASSERT;应该使用 VERIFY 或显式的错误处理。

三、编译期断言:STATIC_ASSERT

3.1 基本语法与兼容宏

C11 使用 _Static_assert,C++11 及更新标准使用 static_assert。如果工程同时支持 C 和 C++,可以提供一个统一宏:

#if defined(__cplusplus)
#define STATIC_ASSERT(condition, message) static_assert((condition), message)
#else
#define STATIC_ASSERT(condition, message) _Static_assert((condition), message)
#endif

条件必须是编译器能够计算的整数常量表达式:

#include <stdint.h>

STATIC_ASSERT(sizeof(uint32_t) == 4u, "uint32_t must be 4 bytes");

sizeof、offsetof、枚举值和对齐值都可以放进静态断言;普通变量不行,因为它们要到运行时才有值。

注意:C11 的 _Static_assert 必须带字符串消息,C++11 的 static_assert 也必须带;C23/C++17 才允许省略。所以使用兼容宏统一要求两个参数才能不烧心。

3.2 检查 8 字节上位机/下位机通信帧

无论是在设计上位机(如电脑 app)、小电脑的视觉协议时,我们都需要统一规范,进行规范化编程(没有规范出问题只能互相甩锅),这个时候对字节长度的检查就显得重要了(一不小心写代码上头了忘记规范,一看白写了就好笑了——根本没有这样的视觉),笔者以简单的通信帧举例:

#include <stddef.h>
#include <stdint.h>

/* 线上格式:SOF(1) + CMD(1) + SEQ(2) + VALUE(2) + CRC16(2) = 8 字节 */
typedef struct {
    uint8_t  sof;
    uint8_t  cmd;
    uint16_t sequence;
    int16_t  value;
    uint16_t crc16;
} HostToMcuFrame;

STATIC_ASSERT(sizeof(HostToMcuFrame) == 8u,
              "HostToMcuFrame must be exactly 8 bytes");

STATIC_ASSERT(offsetof(HostToMcuFrame, sof)      == 0u, "bad sof offset");
STATIC_ASSERT(offsetof(HostToMcuFrame, cmd)      == 1u, "bad cmd offset");
STATIC_ASSERT(offsetof(HostToMcuFrame, sequence) == 2u, "bad sequence offset");
STATIC_ASSERT(offsetof(HostToMcuFrame, value)    == 4u, "bad value offset");
STATIC_ASSERT(offsetof(HostToMcuFrame, crc16)    == 6u, "bad crc offset");

如果新增了字段、改变了类型,或者某个编译器/编译选项改变了默认对齐,上面的检查会立即失败。这样在写代码阶段就能发现协议被改坏,有效避免调试过程中因为协议原因甩锅(真是太可恶了,根本没有不甩锅的好队友——笔者只是怕了)。

在上下位机通信时要注意大小端,以防两者的不一样(这不就好玩了吗谁说谁有理)。

小知识:

  • 小端:最低有效字节在最低地址。0x12345678 的 data[0] 是 0x78。

  • 大端:最高有效字节在最低地址。0x12345678 的 data[0] 是 0x12。

3.3 检查特殊协议帧:DR16 与 SBUS

DJI 的 DR16 接收机通信协议是 18 字节,字段里既有 11 位的摇杆通道,也有 2 位的拨杆状态。很多工程会直接写成位域结构体:

#include <stdint.h>

typedef struct __attribute__((packed)) {
    uint16_t ch_r_x : 11;  /* 右摇杆 X 原始通道 */
    uint16_t ch_r_y : 11;  /* 右摇杆 Y 原始通道 */
    uint16_t ch_l_x : 11;  /* 左摇杆 X 原始通道 */
    uint16_t ch_l_y : 11;  /* 左摇杆 Y 原始通道 */
    uint8_t  sw_r   : 2;   /* 右拨杆位置 */
    uint8_t  sw_l   : 2;   /* 左拨杆位置 */
    int16_t  x;            /* 鼠标 X 增量 */
    int16_t  y;            /* 鼠标 Y 增量 */
    int16_t  z;            /* 鼠标滚轮增量 */
    uint8_t  press_l;      /* 鼠标左键状态 */
    uint8_t  press_r;      /* 鼠标右键状态 */
    uint16_t key;          /* 键盘按键位图 */
    uint16_t res;          /* 保留通道 */
} dr16_data_t;

STATIC_ASSERT(sizeof(dr16_data_t) == 18u, "DR16 frame must be 18 bytes");

小知识:

  • : 的作用——位域,限制该成员占用 11 个二进制位

  • __attribute__((packed)):表示紧凑对齐,此时将要求编译器不进行填充操作

3.4 Cortex-M7:用静态断言检查 32 字节 Cache Line 对齐

如果你有一天研究到了 Cortex-M7,你再次使用 DMA 时遇到关于 Cache 的问题,最简单的措施是用 mpu 将需要访问的区域设置为 Non-cacheable,但是你想使用 Cache 时就需要注意 32 字节对齐的要求,防止数据之间的相互影响,此时就可以用静态断言检查。

小知识:__attribute__((aligned(32))) 指定变量/类型的内存对齐要求(与 Cache 简直是天生一对,此时变量存储位置的首地址将满足 Cache 的对齐要求)。

C11 使用 _Alignas,C++11 使用 alignas;GCC/Clang 也支持 __attribute__((aligned(32)))。这些都是指定对齐要求。

小知识:__alignof__(type) 可以获取指定变量/类型的对齐要求。

C11 使用 _Alignof(type),C++11 使用 alignof(type);GCC/Clang 也支持 __alignof__(type)。推荐把对齐要求集中成宏,提高代码的可读性、可移植性和维护性。

#include <stdint.h>

#if !defined(__cplusplus)
#include <stdalign.h>
#endif
#define CACHE_LINE_SIZE 32u

#if defined(__cplusplus)
    #define CACHE_ALIGNED alignas(CACHE_LINE_SIZE)
    #define ALIGNOF(type) alignof(type)
#else
    #define CACHE_ALIGNED _Alignas(CACHE_LINE_SIZE)
    #define ALIGNOF(type) _Alignof(type)
#endif

/* 起始地址由 CACHE_ALIGNED 声明保证 32 字节对齐;下面的静态断言只检查数组长度是否为 Cache Line 的整数倍。 */
CACHE_ALIGNED static uint8_t dma_rx[256];

STATIC_ASSERT((sizeof(dma_rx) % CACHE_LINE_SIZE) == 0u,
              "DMA buffer size must be a multiple of cache line");

注意:对齐要求可以直接写在类型上(这就是传承哈哈——可惜我们断代了哎)。

例如:

typedef struct {
    CACHE_ALIGNED uint8_t bytes[256];
} DmaBuffer256;

STATIC_ASSERT(sizeof(DmaBuffer256) == 256u, "bad DMA buffer size");
STATIC_ASSERT(ALIGNOF(DmaBuffer256) == CACHE_LINE_SIZE,
              "bad DMA buffer alignment");

static DmaBuffer256 dma_tx;

四、运行时断言:ASSERT、VERIFY 与错误现场 verify_failed()

4.1 断言宏

首先列出我们使用的代码:

#include <stdint.h>

#ifdef MCU_DEBUG_BUILD
/**
 * @brief 如果表达式的值为假则运行处理函数
 *
 */
#define ASSERT(expr)                     \
  do {                                   \
    if (!(expr)) {                       \
      verify_failed(__FILE__, __LINE__); \
    }                                    \
  } while (0)

#else
/**
 * @brief 未定义DEBUG,表达式不会运行,断言被忽略
 *
 */
#define ASSERT(expr) ((void)(0))

#endif

#ifdef MCU_DEBUG_BUILD
/**
 * @brief 如果表达式的值为假则运行处理函数
 *
 */
#define VERIFY(expr)                     \
  do {                                   \
    if (!(expr)) {                       \
      verify_failed(__FILE__, __LINE__); \
    }                                    \
  } while (0)

#else
/**
 * @brief Release 下仍然执行表达式并检查结果
 *
 */
#define VERIFY(expr)                    

#endif

#ifndef RM_UNUSED
/**
 * @brief 标记未使用的参数,防止编译器警告
 *
 */
#define RM_UNUSED(X) ((void)X)

#endif

4.2 ASSERT 的典型用法:指针、数组和下标边界

在驱动内部,指针非空、数组下标没有越界、环形队列状态没有被破坏,通常属于程序员必须保证的不变量:

#include <stddef.h>
#include <stdint.h>

static void queue_write(uint8_t *buffer,
                        size_t capacity,
                        size_t index,
                        uint8_t value)
{
    ASSERT(buffer != NULL);
    ASSERT(capacity > 0u);
    ASSERT(index < capacity);
    buffer[index] = value;
}

这类检查的含义是“调用者的使用方式不应该出错”。违反了就说明驱动或上层有 bug,继续执行只会踩内存,所以用 ASSERT 直接停在第一现场是合理的。

4.3 VERIFY 的典型用法:必须执行的检查

VERIFY 适合“不管 Debug 还是 Release 都必须执行,而且失败代表系统已经不可信”的检查。最典型的例子是带返回值的硬件调用:

以 STM32 HAL 的 CAN 为例,HAL_CAN_AddTxMessage() 的返回值表示发送请求是否提交成功,mailbox 返回实际使用的发送邮箱。这个调用如果放进 ASSERT,Release 下会连同发送动作一起消失,所以必须用 VERIFY。

uint32_t mailbox = 0u;
VERIFY(HAL_CAN_AddTxMessage(&hcan, &header, tx_data, &mailbox) == HAL_OK); /* 没有空邮箱通常会返回错误 */

4.4 verify_failed()

在程序中出现 ASSERT 或者 VERIFY 的运行时断言错误的时候会执行 verify_failed(),在函数内部定义日志打印函数(uart、RTT)等,我们可以在上位机中快速定位错误,就不用慢慢 debug 或者是进入 HardFault 时栈回溯了(真的是太节省时间了笔者反正是爱了)。

小知识:

  • __FILE__:当前源文件名,通常是字符串字面量。

  • __LINE__:当前源代码行号,类型可按整数使用。

  • __func__:当前函数名。它不是宏,而是函数体内可用的预定义标识符。





关键词: 2026年     J-Link     RTT     LOG     日志     嵌    

菜鸟
2026-11-17 15:55:14     打赏
2楼

由于RTT的实战需要用到断言相关的知识所以就先分享出来这个前面一直在写实验报告和学cache(勉强入门了),就一直没写RTT的实战篇



共2条 1/1 1 跳转至页

回复

匿名不能发帖!请先 [ 登陆 注册 ]