第3章 HAL层接口规范：标准API定义原则、参数传递规范与返回值错误码设计
接口规范这事儿，说白了就是HAL层的"交通规则"。我见过太多项目，硬件换了、芯片换了，结果上层应用代码改得面目全非——根子就在接口没定好。今天咱们就把这块掰开揉碎了讲。
3.1 标准API定义原则
定义HAL接口时，我习惯先问自己三个问题：这个接口是否通用？是否简洁？是否可预测？
- 通用性：接口不能绑定某个具体硬件。比如别写
gpio_set_stm32_pin()，要写hal_gpio_write()。 - 简洁性：一个接口只做一件事。我见过一个函数传了8个参数，调试时自己都忘了第5个是啥意思。
- 可预测性：同样的输入，永远产生同样的行为。别搞"这次调用成功，下次调用失败"这种玄学。
核心原则：HAL接口是"契约"，不是"实现"。上层只认契约，底层怎么折腾是底层的事。
3.2 参数传递规范
参数传递这块，坑特别多。我调过的一个项目，就因为参数类型不一致，在ARM Cortex-M4上跑得好好的，换到RISC-V上直接崩了。
3.2.1 参数类型选择
| 参数类型 | 推荐场景 | 避坑说明 |
|---|---|---|
uint32_t |
寄存器地址、掩码、超时值 | 跨平台宽度一致，别用int |
uint8_t |
小范围枚举、标志位 | 节省栈空间，但注意对齐 |
void * |
回调上下文、DMA缓冲区 | 必须配合长度参数，否则越界 |
const 指针 |
只读配置结构体 | 编译器能优化，还能防误改 |
我曾经踩过的坑：用int传GPIO引脚号，结果在64位平台上int是32位，但指针是64位，结构体对齐全乱了。从那以后，HAL接口里我统一用uint32_t和uint8_t，绝不偷懒。
3.2.2 参数传递方式
- 值传递：适合小数据（≤4字节），比如配置值、状态码。
- 指针传递：适合大数据或需要修改的内容，比如DMA缓冲区、配置结构体。
- 引用传递：C语言里没有，但C++的HAL层可以用。我个人建议C项目别用，移植时麻烦。
3.3 返回值与错误码设计
返回值设计得好，调试时能省一半时间。设计得不好……嗯，你懂的，满屏的-1根本不知道错在哪。
3.3.1 返回值类型
| 返回值类型 | 典型值 | 使用场景 |
|---|---|---|
int32_t |
≥0成功，<0错误码 | 通用API，最常用 |
uint32_t |
0成功，非0错误码 | 位域错误码场景 |
bool |
true/false | 简单查询，如是否就绪 |
void |
无返回值 | 中断回调、通知类接口 |
3.3.2 错误码设计规范
我习惯把错误码分成几个大类，每个大类留足扩展空间：
/* 通用错误码：0x0000 - 0x00FF */
#define HAL_OK 0x0000
#define HAL_ERROR 0x0001
#define HAL_BUSY 0x0002
#define HAL_TIMEOUT 0x0003
/* 参数错误：0x0100 - 0x01FF */
#define HAL_ERR_PARAM 0x0100
#define HAL_ERR_NULL 0x0101
#define HAL_ERR_RANGE 0x0102
/* 硬件错误：0x0200 - 0x02FF */
#define HAL_ERR_HW 0x0200
#define HAL_ERR_NACK 0x0201
#define HAL_ERR_OVERRUN 0x0202
/* 资源错误：0x0300 - 0x03FF */
#define HAL_ERR_NOMEM 0x0300
#define HAL_ERR_BUSY 0x0301
#define HAL_ERR_UNINIT 0x0302小技巧：错误码用16位，高8位表示错误类别，低8位表示具体错误。这样上层可以快速判断是"参数问题"还是"硬件问题"，不用逐个查表。
3.4 接口规范知识体系
下面这张图，是我做HAL层设计时脑子里始终挂着的结构。你把它记牢了，接口设计就不会跑偏。
3.5 实战中的避坑指南
讲几个我实际项目中遇到的教训，你记下来，以后能少走弯路。
避坑1：别用可变参数
我曾经在一个UART驱动里用了printf风格的可变参数，结果换到新平台后，参数栈布局变了，数据全乱套。HAL接口里，参数个数和类型必须固定。
避坑2：错误码别用0表示成功以外的含义
有个项目把0定义为"设备忙"，结果上层判断if (ret)时，以为0是成功，直接往下走了。设备根本没准备好，数据全丢了。从那以后，我规定：0永远表示成功，非0才是错误。
避坑3：参数顺序要统一
我习惯把所有HAL接口的参数顺序统一为：句柄 → 配置 → 数据 → 长度 → 超时。这样上层调用时，不用每次翻手册查参数顺序，代码可读性也高。
3.6 接口规范检查清单
每次写完HAL接口，我都会拿这张清单过一遍。你也试试：
- 接口名是否以
hal_开头？ - 参数类型是否跨平台一致（不用
int、long）？ - 指针参数是否加了
const（如果只读）？ - 返回值是否统一（0成功，非0错误）？
- 错误码是否按类别分组，预留了扩展空间？
- 参数顺序是否和同模块其他接口一致？
- 接口是否只做一件事？（单一职责）
嗯，这一章的内容就这些。接口规范看着简单，但真正做好，需要你在每个项目里反复打磨。记住：好的接口，让上层开发者感觉不到底层换了硬件——这才是HAL层的终极目标。