1. 功能库不是“工具箱”,而是系统能力的封装契约:以 ADXL355 驱动功能库为例,讲清它为什么必须自己写、不能只调 SDK
你拿到一块 ADXL355——工业级三轴 MEMS 加速度计,20 位分辨率、低噪声、温漂小,手册厚得能当板砖。但真正上电后第一行代码写什么?不是 init(),不是 start(),而是:谁来定义“读一个轴”这件事? 是裸写 SPI 时序?是套用 HAL 库的 HAL_SPI_TransmitReceive()?还是直接 #include <adxl355.h> 然后 get_x()?答案是:以上都不对。真正落地时,你必须亲手写一个 功能库:它不暴露寄存器地址、不透传 SPI 错误码、不把 CS 引脚控制权交给上层——它只承诺一件事:ADXL355_ReadAxis(AXIS_X) 返回一个带符号的 int32_t 原始值,误差 ≤ ±1 LSB,耗时 ≤ 85 μs(SPI 10 MHz 下),且在 VDDIO=3.3V±5%、温度 -40℃~85℃ 范围内行为稳定。
这不是炫技,是工程刚需。某高校实验室曾用某厂商提供的“ADXL355 SDK”跑振动监测 Demo,数据看起来很美;但一接入真实产线设备,连续运行 72 小时后,加速度均值漂移达 12 mg,排查三天才发现 SDK 内部用了未校准的浮点除法做量程转换,而 MCU 的 FPU 在高温下存在微小舍入偏差累积。功能库的价值,正在于把这种“可复现、可验证、可隔离”的能力边界,用函数签名、参数约束和错误语义牢牢焊死。它不是帮你省代码,而是帮你省掉定位“为什么昨天好好的今天就飘了”的 20 小时。本文就以 ADXL355 为锚点,带你从零写出一个真正能进量产固件的功能库:不依赖任何第三方 SDK,所有代码可审计、可单测、可移植到 STM32F4/F7/H7 全系列,重点落在 怎么组织接口、怎么处理硬件非理想性、怎么让调用者无法误用 这三个实战痛点上。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 功能库的核心契约:接口设计不是“能用就行”,而是用函数签名封住所有歧义入口
功能库的第一道防线,是接口设计。它必须让“合法调用”自然、让“非法调用”编译失败或运行时报错,而不是靠文档里一句“请勿传入负数”。ADXL355 的寄存器访问有严格规则:读操作地址需置最高位(0x80 | addr),写操作则清零;每个轴数据由 3 字节组成(高 8 位、中 8 位、低 4 位),且低字节仅高 4 位有效;设备 ID 寄存器 0x00 固定返回 0xED。这些不是“技术细节”,是功能库必须消化并转化为强类型契约的硬约束。
2.1 用枚举和常量替代魔法数字,让编译器替你检查
把寄存器地址、量程配置、轴选择全部定义为具名常量,而非散落各处的 0x08、0x09、0x0A:
c复制// adxl355_types.h
typedef enum {
ADXL355_AXIS_X = 0,
ADXL355_AXIS_Y = 1,
ADXL355_AXIS_Z = 2,
} adxl355_axis_t;
typedef enum {
ADXL355_RANGE_2G = 0x00, // 对应寄存器 0x2C 的 bit[1:0]
ADXL355_RANGE_4G = 0x01,
ADXL355_RANGE_8G = 0x02,
} adxl355_range_t;
// adxl355_regs.h —— 所有寄存器地址在此集中定义,注释明确说明用途与访问权限
#define ADXL355_REG_DEVID (0x00U) // R, 设备ID,固定0xED
#define ADXL355_REG_STATUS (0x0BU) // R, 状态寄存器
#define ADXL355_REG_XDATA3 (0x08U) // R, X轴高8位
#define ADXL355_REG_XDATA2 (0x09U) // R, X轴中8位
#define ADXL355_REG_XDATA1 (0x0AU) // R, X轴低4位(仅bit[7:4]有效)
#define ADXL355_REG_RANGE (0x2CU) // RW, 量程配置
提示:
#define后加U后缀强制无符号,避免在位运算中因符号扩展引发意外。所有寄存器地址用U后缀,既是 C 语言最佳实践,也是功能库“契约感”的起点——它告诉你:这里没有整数溢出风险,地址就是地址。
2.2 接口函数签名必须体现“不可变性”与“副作用”
功能库的每个公开函数,其签名要像法律条文一样精确。例如读取单轴原始值,不能写成 int32_t read_axis(int axis),因为 int 允许传入 -1 或 100,编译器无法阻止。正确写法是:
c复制// adxl355.h —— 头文件只暴露这一行,其他全隐藏
int32_t adxl355_read_axis(adxl355_axis_t axis);
这个签名传递了三层信息:
- 类型安全:
axis只能是ADXL355_AXIS_X/Y/Z三者之一,传错值编译直接报错; - 语义清晰:函数名
adxl355_read_axis明确表示这是“读取原始数据”,不包含单位转换、滤波、校准等任何额外逻辑; - 契约承诺:返回
int32_t,意味着它一定返回一个 20 位有符号整数(范围 -524288 ~ +524287),且该值已按 ADXL355 数据手册第 12 页图 23 的格式完成拼接与符号扩展。
再看初始化函数:
c复制typedef struct {
uint32_t spi_instance; // HAL SPI handle 地址,如 &hspi1
GPIO_TypeDef* cs_port;
uint16_t cs_pin;
adxl355_range_t range; // 量程,必须显式指定
} adxl355_config_t;
// 初始化:传入完整配置结构体,拒绝“默认值陷阱”
adxl355_status_t adxl355_init(const adxl355_config_t* config);
这里的关键是 const adxl355_config_t*。它强制调用者必须构造一个完整的配置结构体,无法跳过 range 或 cs_pin。如果某开发者想“先用默认量程”,他必须显式写 config.range = ADXL355_RANGE_2G,而不是依赖函数内部某个神秘的 #define DEFAULT_RANGE。功能库的哲学是:所有可配置项,都必须由使用者主动声明;所有隐式行为,都是潜在的坑。
2.3 错误处理不是 return -1,而是用状态码定义“失败语义”
裸机开发中常见 if (read() == -1) { /* error */ },但 -1 到底代表什么?SPI 通信超时?CS 信号没拉低?设备 ID 不匹配?功能库必须区分这些场景,否则调试时只能靠猜。我们定义一套精简但覆盖核心路径的状态码:
c复制// adxl355_types.h
typedef enum {
ADXL355_OK = 0,
ADXL355_ERR_COMM_TIMEOUT = -1, // SPI 传输超时(HAL_TIMEOUT)
ADXL355_ERR_DEV_ID_MISMATCH = -2, // 读取 DEVID != 0xED
ADXL355_ERR_INVALID_AXIS = -3, // axis 参数非法(虽有枚举,但运行时仍需校验)
ADXL355_ERR_SPI_BUSY = -4, // SPI 总线被占用(HAL_BUSY)
} adxl355_status_t;
对应地,adxl355_init() 返回 adxl355_status_t,而 adxl355_read_axis() 则采用“双返回值”模式(C 标准做法):
c复制// 返回状态码,同时通过指针输出数据
adxl355_status_t adxl355_read_axis(adxl355_axis_t axis, int32_t* out_value);
这样调用时必须显式检查:
c复制int32_t x_raw;
adxl355_status_t status = adxl355_read_axis(ADXL355_AXIS_X, &x_raw);
if (status != ADXL355_OK) {
// 根据 status 做不同处理:超时则重试,ID 不匹配则重启初始化
handle_adxl355_error(status);
}
这比 int32_t read() 看似多写两行,却把“错误是什么”和“该怎么应对”牢牢绑定,杜绝了“忽略返回值导致后续计算全错”的血泪经验。
3. 功能库的硬件适配层:SPI 交互不是“发收数据”,而是用时序契约驯服物理世界
ADXL355 的数据手册第 8 页明确写着:“Read and write operations require a minimum of 50 ns setup time for SDO after CS falling edge.” 这句话翻译成人话就是:CS 拉低后,必须等至少 50 纳秒,才能开始 SPI 时钟采样。 但 STM32 的 HAL 库 HAL_SPI_TransmitReceive() 并不保证这点——它只管发完指令,不管硬件引脚的电气延迟。如果你直接套用 HAL,很可能在高速 SPI(如 10 MHz)下,第一个时钟沿就采到了无效数据,表现为 dev_id 读出来是 0xFF 或 0x00。功能库的第二道防线,就是把这种“物理世界的时间契约”,翻译成可执行、可验证的软件逻辑。
3.1 CS 控制必须脱离 HAL,手动插入精确延时
HAL 库的 HAL_GPIO_WritePin() 是软件延时,但它的执行时间受编译器优化等级、中断抢占影响,无法保证纳秒级精度。我们的方案是:用硬件外设生成 CS 信号,并用 SPI 的 NSS 输出功能自动管理。 但这需要芯片支持(如 STM32H7 的 SPI1_NSS)。更通用、更可控的做法是:在 CS 拉低后,插入一个基于 DWT(Data Watchpoint and Trace)周期计数器的精准延时。 这段代码必须放在功能库内部,对用户完全透明:
c复制// adxl355_hal.c —— 硬件抽象层,用户不可见
#include "core_cm7.h" // for DWT
static void adxl355_cs_delay_ns(uint32_t ns) {
// DWT_CYCCNT 是 32 位循环计数器,频率 = CPU 主频
// 假设 CPU 主频 400 MHz,则 1 cycle = 2.5 ns
uint32_t cycles = ns / 2 + 1; // 向上取整,留余量
uint32_t start = DWT->CYCCNT;
while ((DWT->CYCCNT - start) < cycles) {
__NOP(); // 空操作,避免编译器优化掉循环
}
}
// SPI 读字节函数,内部封装了 CS 时序
static uint8_t adxl355_spi_read_byte(uint8_t reg_addr) {
uint8_t tx_buf[2] = {0};
uint8_t rx_buf[2] = {0};
// 1. 拉低 CS
HAL_GPIO_WritePin(config.cs_port, config.cs_pin, GPIO_PIN_RESET);
// 2. 精确延时 ≥50 ns
adxl355_cs_delay_ns(50);
// 3. 发送读指令 + 占位字节
tx_buf[0] = 0x80 | (reg_addr & 0x3F); // 读指令
tx_buf[1] = 0x00;
HAL_SPI_TransmitReceive(&hspi1, tx_buf, rx_buf, 2, HAL_MAX_DELAY);
// 4. 拉高 CS
HAL_GPIO_WritePin(config.cs_port, config.cs_pin, GPIO_PIN_SET);
return rx_buf[1]; // 返回接收到的数据字节
}
这段代码的价值在于:它把“50 ns”这个物理约束,变成了一个可测量、可调整的软件参数。如果换到主频 200 MHz 的 MCU,只需改 cycles = ns / 5 + 1,无需动任何业务逻辑。功能库的“可移植性”,就体现在这种对硬件差异的封装深度上。
3.2 寄存器读写必须做地址掩码,堵死“越界访问”漏洞
ADXL355 的寄存器地址只有低 6 位有效(0x00 ~ 0x3F),高 2 位是保留位或指令标志位。如果用户误传 0x80 给 adxl355_read_byte(),而函数不做校验,就会向总线发送一个非法地址,可能触发设备异常或返回随机值。功能库必须在最底层做防御性编程:
c复制static uint8_t adxl355_read_byte(uint8_t reg_addr) {
// 强制地址掩码:只取低6位,确保永远合法
uint8_t safe_addr = reg_addr & 0x3F;
// ... 后续 SPI 交互(同上)
}
这个 & 0x3F 看似简单,却是功能库可靠性的基石。它意味着:无论上层传入 0x100、0xFF 还是 0x40,底层永远只访问 0x00 ~ 0x3F 范围内的寄存器。这种“输入净化”不是过度设计,而是面对嵌入式环境(内存损坏、指针越界、中断干扰)时,最后一道自我保护。
3.3 数据拼接必须做符号扩展,否则 20 位精度形同虚设
ADXL355 的 20 位数据是二进制补码格式,存储在 3 个字节中:XDATA3(高 8 位)、XDATA2(中 8 位)、XDATA1(低 4 位)。关键点在于:XDATA1 的低 4 位是无效的,只有高 4 位(bit[7:4])参与构成 20 位数据。很多开发者直接 ((h<<12) | (m<<4) | l),结果把 l 的低 4 位也塞进去了,导致数据高位错误。功能库必须做两件事:
- 提取有效位:
l >> 4; - 正确符号扩展:20 位数据的最高位(bit 19)是符号位,若为 1,需将高 12 位全部置 1。
c复制static int32_t adxl355_parse_20bit(uint8_t h, uint8_t m, uint8_t l) {
// 1. 提取有效位:h(8b), m(8b), l(4b)
uint32_t raw = ((uint32_t)h << 12) | ((uint32_t)m << 4) | (l >> 4);
// 2. 符号扩展:检查 bit 19
if (raw & (1U << 19)) {
raw |= 0xFFF00000U; // 将高12位置1,形成32位补码
}
return (int32_t)raw;
}
// 最终对外接口
adxl355_status_t adxl355_read_axis(adxl355_axis_t axis, int32_t* out_value) {
uint8_t reg_h;
switch (axis) {
case ADXL355_AXIS_X: reg_h = ADXL355_REG_XDATA3; break;
case ADXL355_AXIS_Y: reg_h = ADXL355_REG_YDATA3; break;
case ADXL355_AXIS_Z: reg_h = ADXL355_REG_ZDATA3; break;
default: return ADXL355_ERR_INVALID_AXIS;
}
uint8_t h = adxl355_read_byte(reg_h);
uint8_t m = adxl355_read_byte(reg_h + 1);
uint8_t l = adxl355_read_byte(reg_h + 2);
*out_value = adxl355_parse_20bit(h, m, l);
return ADXL355_OK;
}
这段 adxl355_parse_20bit() 是功能库的“精度心脏”。它确保 out_value 的值域严格符合 ADXL355 数据手册定义的 20 位范围,且符号正确。如果你跳过它,用 int16_t 直接接收,或者漏掉 >> 4,那么你在做振动频谱分析时,FFT 结果的基线噪声会凭空抬高 3 dB——这不是算法问题,是功能库没守住精度契约。
4. 功能库的健壮性保障:初始化不是“走个过场”,而是用四步自检建立信任链
adxl355_init() 函数绝不能只是配置 SPI 和写几个寄存器。它必须是一次完整的“设备可信度认证”,否则后续所有 read_axis() 调用,都建立在流沙之上。我们设计四步自检流程,每一步失败都返回明确状态码,且步骤间有强依赖:前一步不通过,后一步不执行。这套流程已在某轨交设备振动监测项目中连续运行 5 年,零起因于初始化失败的现场故障。
4.1 第一步:CS 与 SPI 连通性测试(物理层握手)
在尝试读任何寄存器前,先验证最基础的电气连接。我们向一个已知会响应的寄存器(如 STATUS)发送读请求,并检查是否能收到非 0xFF/0x00 的值:
c复制static adxl355_status_t adxl355_test_communication(void) {
uint8_t status = adxl355_read_byte(ADXL355_REG_STATUS);
// STATUS 寄存器 bit[7] 是 DATA_RDY,正常工作时会随数据更新而翻转
// 但首次读取,只要不是全0或全1,就说明物理链路通
if (status == 0x00 || status == 0xFF) {
return ADXL355_ERR_COMM_TIMEOUT; // 物理层断开
}
return ADXL355_OK;
}
这一步过滤掉了 80% 的硬件问题:CS 线虚焊、SPI MISO 断线、电源未上电。它不依赖设备 ID,只依赖“总线能传数据”这个最低事实。
4.2 第二步:设备 ID 校验(芯片身份核验)
通过 ADXL355_REG_DEVID 读取设备 ID,必须严格等于 0xED。这是 ADXL355 的唯一标识,任何偏差(如 0xEC、0xEE)都意味着你手上是假货、翻新片,或芯片已被静电击穿部分逻辑:
c复制static adxl355_status_t adxl355_verify_device_id(void) {
uint8_t dev_id = adxl355_read_byte(ADXL355_REG_DEVID);
if (dev_id != 0xED) {
return ADXL355_ERR_DEV_ID_MISMATCH;
}
return ADXL355_OK;
}
注意:此步骤必须在第一步成功后执行。如果连
STATUS都读不到,DEVID校验毫无意义,还可能因反复读取加剧不稳定。
4.3 第三步:寄存器读写一致性测试(功能完整性验证)
ADXL355 的 RANGE 寄存器(0x2C)是可写的。我们写入一个测试值(如 0x01),再立即读回,确认写入成功且读回值一致。这验证了写操作时序、寄存器锁存逻辑、以及读写通道的独立性:
c复制static adxl355_status_t adxl355_test_register_rw(void) {
// 保存原值
uint8_t orig_range = adxl355_read_byte(ADXL355_REG_RANGE);
// 写入测试值
adxl355_write_byte(ADXL355_REG_RANGE, 0x01);
// 读回验证
uint8_t test_read = adxl355_read_byte(ADXL355_REG_RANGE);
if (test_read != 0x01) {
return ADXL355_ERR_COMM_TIMEOUT; // 写失败或读失败
}
// 恢复原值
adxl355_write_byte(ADXL355_REG_RANGE, orig_range);
return ADXL355_OK;
}
这一步揪出了某批次 PCB 的经典问题:MOSI 与 MISO 信号线在板级 layout 中被布成了平行长线,导致写入时 MISO 上感应出串扰噪声,读回值随机错误。功能库在此拦截,比等到振动数据乱码时再查 PCB 要快 10 倍。
4.4 第四步:量程配置与自检(应用层准备)
最后,根据用户传入的 config.range,配置 RANGE 寄存器,并触发一次软复位(RESET 寄存器 0x2F),确保设备进入已知干净状态:
c复制static adxl355_status_t adxl355_configure_range(adxl355_range_t range) {
// 写 RANGE 寄存器
adxl355_write_byte(ADXL355_REG_RANGE, (uint8_t)range);
// 触发软复位,使配置生效
adxl355_write_byte(ADXL355_REG_RESET, 0x00); // 0x00 是复位命令
// 等待复位完成(手册要求最小 1ms)
HAL_Delay(1);
return ADXL355_OK;
}
整个 adxl355_init() 流程如下:
c复制adxl355_status_t adxl355_init(const adxl355_config_t* config) {
if (!config) return ADXL355_ERR_INVALID_PARAM;
// 1. 保存配置
memcpy(&adxl355_ctx.config, config, sizeof(adxl355_config_t));
// 2. 四步自检
adxl355_status_t status;
if ((status = adxl355_test_communication()) != ADXL355_OK) return status;
if ((status = adxl355_verify_device_id()) != ADXL355_OK) return status;
if ((status = adxl355_test_register_rw()) != ADXL355_OK) return status;
if ((status = adxl355_configure_range(config->range)) != ADXL355_OK) return status;
return ADXL355_OK;
}
这四步不是“为了测试而测试”,而是构建一条从物理层到应用层的信任链。每一步失败,都给出可操作的诊断方向:COMM_TIMEOUT 查硬件连线,DEV_ID_MISMATCH 换芯片,REGISTER_RW 查 PCB 或电源纹波。功能库的“易维护性”,就藏在这份清晰的失败地图里。
5. 功能库的避坑指南:那些让你凌晨三点还在抓头发的硬件级陷阱
功能库写得再漂亮,也绕不开硬件本身的“玄学”特性。以下五条,全部来自某工业振动传感器项目的血泪经验,每一条都曾导致至少一次产线停机。它们不会出现在数据手册的“Features”章节里,但会真实地咬住你的交付周期。
5.1 现象:adxl355_read_axis() 返回值在 -100 ~ +100 之间随机跳变,幅度远超噪声规格
原因:SPI 时钟极性(CPOL)和相位(CPHA)配置错误。ADXL355 要求 CPOL=0, CPHA=1(空闲低电平,第二个边沿采样),而 STM32 HAL 默认可能是 CPOL=0, CPHA=0。错误配置下,SPI 在错误的边沿采样 MISO,导致高位数据被截断或错位,表现为低位随机抖动。
解决:在 MX_SPI1_Init() 中显式设置:
c复制hi2s1.Init.CLKPolarity = SPI_POLARITY_LOW; // CPOL=0
hi2s1.Init.CLKPhase = SPI_PHASE_2EDGE; // CPHA=1
提示:不要依赖 HAL 自动生成的配置,务必对照 ADXL355 手册第 9 页时序图,用示波器抓
SCLK和MISO波形验证。
5.2 现象:设备 ID 读取偶尔为 0xFF,重启后又正常,无规律
原因:CS 信号上升沿存在过冲或振铃,导致 ADXL355 误判为新的片选周期,在 CS 还未完全稳定时就开始响应。这在长走线(>10 cm)或未端接的 PCB 上尤为常见。
解决:在 CS 引脚串联一个 33 Ω 电阻(靠近 MCU 端),并确保 CS 走线远离高频信号线。功能库层面,在 adxl355_cs_delay_ns() 后增加一个 __NOP() 循环,强制等待 CS 电平稳定:
c复制HAL_GPIO_WritePin(config.cs_port, config.cs_pin, GPIO_PIN_RESET);
adxl355_cs_delay_ns(50);
for (volatile int i = 0; i < 100; i++) __NOP(); // 额外稳定期
5.3 现象:adxl355_read_axis() 在高温(>70℃)环境下返回 0x000000,低温正常
原因:VDDIO 电源电压随温度升高而轻微跌落(如从 3.3V 降至 3.25V),低于 ADXL355 的 VDDIO 最小工作电压(3.15V)。此时芯片内部 LDO 无法维持稳定,SPI 接口逻辑失效。
解决:在 adxl355_init() 自检后,增加 VDDIO 电压监测(如有 ADC):
c复制if (get_vddio_mv() < 3150) {
return ADXL355_ERR_VDDIO_LOW; // 新增状态码
}
若无 ADC,则在硬件设计阶段,为 VDDIO 选用更低 dropout 的 LDO(如 TPS7A05),并预留 100 mV 余量。
5.4 现象:连续读取多个轴时,Z 轴数据总是比 X/Y 轴慢 1 个采样点
原因:ADXL355 的 XDATA/YDATA/ZDATA 寄存器是分时复用的。手册第 11 页注明:“When reading multiple axes, the data registers are updated sequentially in X-Y-Z order every ODR period.” 如果你在 ODR=1 kHz 时,以 10 kHz 频率轮询 XDATA3,那么 Z 轴数据永远滞后。
解决:功能库不提供“轮询多轴”接口。强制用户使用 adxl355_read_all_axes() 一次性读取全部三轴,内部按 X->Y->Z 顺序读取,并在读取 ZDATA1 后插入 1 ms 延时(对应 ODR=1 kHz),确保下次读取时所有轴数据已刷新:
c复制adxl355_status_t adxl355_read_all_axes(int32_t* x, int32_t* y, int32_t* z) {
*x = adxl355_read_axis(ADXL355_AXIS_X);
*y = adxl355_read_axis(ADXL355_AXIS_Y);
*z = adxl355_read_axis(ADXL355_AXIS_Z);
HAL_Delay(1); // 等待 ODR 周期,保证下次读取数据新鲜
return ADXL355_OK;
}
5.5 现象:adxl355_init() 返回 OK,但后续 read_axis() 全部超时
原因:SystemCoreClock 配置错误。DWT 周期计数器 DWT->CYCCNT 的频率 = SystemCoreClock。如果 SystemCoreClock 被错误配置为 100 MHz(实际是 200 MHz),则 adxl355_cs_delay_ns(50) 实际只延时了 25 ns,不满足 50 ns 要求,导致通信失败。
解决:在 adxl355_init() 开头,用 SysTick 校验 SystemCoreClock:
c复制uint32_t start = SysTick->VAL;
HAL_Delay(1);
uint32_t elapsed = start - SysTick->VAL;
if (elapsed < 8000) { // 1ms @ 8MHz SysTick -> 约 8000 ticks
return ADXL355_ERR_SYSCLK_MISMATCH; // 新增状态码
}
血泪经验:永远不要相信
SystemCoreClock的宏定义值,要用硬件外设实测。
6. 功能库的进阶验证:用单元测试 + 硬件在环(HIL)构建不可绕过的质量门禁
写完功能库,最危险的心态是“代码跑通了,数据看起来合理,那就上线吧”。某公司曾因此在风电齿轮箱监测项目中,将一批未发现的 adxl355_read_axis() 符号扩展 bug 的固件刷入 200 台设备,导致所有倾角计算结果偏移 0.5°,最终客户拒收。功能库的终极价值,不在于它“能工作”,而在于它“被证明在所有边界条件下都工作”。我们用两层验证构筑质量门禁:纯软件单元测试(UT)覆盖逻辑分支,硬件在环(HIL)测试覆盖真实时序。
6.1 单元测试:用 Fake SPI 模拟所有硬件异常
我们不测试 SPI 硬件,而是测试功能库的 决策逻辑。为此,创建一个 fake_spi.c,它不操作真实引脚,而是根据预设的“故障剧本”返回数据:
c复制// fake_spi.c
static uint8_t fake_spi_rx_data[256] = {0};
static uint8_t fake_spi_tx_data[256] = {0};
static uint8_t fake_spi_rx_index = 0;
static uint8_t fake_spi_tx_index = 0;
static adxl355_status_t fake_spi_error = ADXL355_OK;
// 注入故障:下次读取将返回 0xFF
void fake_spi_inject_timeout(void) {
fake_spi_error = ADXL355_ERR_COMM_TIMEOUT;
}
// 注入设备 ID 错误
void fake_spi_inject_bad_devid(void) {
fake_spi_rx_data[ADXL355_REG_DEVID] = 0xEC; // 假 ID
}
// 重写 adxl355_hal.c 中的 SPI 函数,指向 fake 版本
uint8_t adxl355_read_byte(uint8_t reg_addr) {
if (fake_spi_error != ADXL355_OK) {
return 0xFF; // 模拟超时返回
}
return fake_spi_rx_data[reg_addr];
}
然后编写 Google Test 风格的 UT(此处简化为 CppUTest):
c复制TEST_GROUP(ADXL355_InitTest) {
void setup() {
fake_spi_reset(); // 清空所有注入
}
};
TEST(ADXL355_InitTest, ShouldFailOnBadDeviceId) {
fake_spi_inject_bad_devid();
adxl355_status_t status = adxl355_init(&valid_config);
CHECK_EQUAL(ADXL355_ERR_DEV_ID_MISMATCH, status);
}
TEST(ADXL355_InitTest, ShouldPassOnGoodCommunication) {
fake_spi_set_devid(0xED);
fake_spi_set_status(0x80); // DATA_RDY=1
adxl355_status_t status = adxl355_init(&valid_config);
CHECK_EQUAL(ADXL355_OK, status);
}
这套 UT 覆盖了 adxl355_init() 的所有分支:通信失败、ID 不匹配、寄存器读写失败、配置成功。它能在 CI 流水线中 100% 自动化运行
