一些老嵌入式朋友可能会有疑问:断言是什么?断言是什么,我干了嵌入式好长时间了从来没有用过这个功能,你是不是在哄骗我使用这个功能,这个功能在嵌入式领域真的有用吗?那么作为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。你不是在异常发生后猜,而是在假设被破坏的第一现场停下来。
| 通信帧长度写错 | 数组越界,踩坏其他变量,最后 HardFault | ASSERT(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_assert | ASSERT、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 宏约定
笔者的代码约定如下:
| 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)
#endif4.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__:当前函数名。它不是宏,而是函数体内可用的预定义标识符。

我要赚赏金
