3. 主流HAL框架对比
接口规范这事儿，说大不大，说小不小。我见过太多项目，前期没人管命名，后期联调时鸡飞狗跳。你想想看，一个硬件抽象层，少则几十个接口，多则上百个，要是没个统一规矩，后面移植适配的时候，光改名字就能改到你怀疑人生。
这一章，我就把我在几个大型 SoC 项目里沉淀下来的接口规范讲透。说白了，就是让你写出来的 HAL 接口，别人一看就懂，一调就对，一出错就知道怎么回事。
3.1 命名规范：一眼看懂是干什么的
命名这件事，我个人的习惯是「模块前缀 + 动词 + 对象」三段式。举个例子：
// 好的命名
int32_t gpio_set_direction(gpio_port_t port, gpio_pin_t pin, gpio_dir_t dir);
int32_t i2c_master_transfer(i2c_bus_t bus, i2c_msg_t *msg, uint32_t count);
// 差的命名
int32_t set_gpio(int a, int b, int c); // 鬼知道参数是什么
int32_t i2c_write(int bus, int addr); // 功能太模糊具体规则我列在下面：
| 要素 | 规则 | 示例 |
|---|---|---|
| 模块前缀 | 小写 + 下划线，对应硬件模块 | gpio_、i2c_、spi_、uart_ |
| 动词 | 使用标准动词，避免自造词 | set、get、open、close、read、write、transfer |
| 对象 | 描述操作的目标资源 | direction、config、status、buffer |
| 回调函数 | 加 _callback 或 _handler 后缀 |
gpio_irq_callback、i2c_event_handler |
init、deinit、open、close、read、write、ioctl。超过这个范围，说明你的接口设计可能太碎了。
3.2 参数规范：少即是多
参数设计上，我踩过最大的坑就是「参数膨胀」。曾经有个同事写了个 SPI 发送接口，参数多达 8 个，每次调用都要翻手册查参数顺序。后来重构时，我们把相关参数打包成结构体，接口瞬间清爽了。
我的建议是：
- 参数不超过 4 个。超过 4 个，就用结构体传参。
- 第一个参数是句柄或设备 ID。这是 HAL 层的惯例，方便多实例管理。
- 输入参数用
const修饰。告诉调用者：这个参数我不会改。 - 输出参数用指针，并在命名上加
out_前缀。
// 推荐：参数打包成结构体
typedef struct {
uint32_t baudrate;
uint8_t data_bits;
uint8_t stop_bits;
uint8_t parity;
} uart_config_t;
int32_t uart_open(uart_port_t port, const uart_config_t *config);
// 不推荐：参数散落
int32_t uart_open(uart_port_t port, uint32_t baud, uint8_t bits, uint8_t stop, uint8_t parity);const 指针。我曾经见过有人传结构体副本，结果栈空间直接爆了——嵌入式环境，栈资源金贵着呢。
3.3 返回值规范：让调用者知道发生了什么
返回值这块，我见过最离谱的做法是：成功返回 0，失败返回 -1。然后调用者只知道「出错了」，但完全不知道错在哪。
我的做法是：统一使用 int32_t 作为返回值类型。0 表示成功，正数表示警告或信息，负数表示错误码。
// 标准返回值模式
int32_t gpio_write(gpio_port_t port, gpio_pin_t pin, uint8_t value);
// 调用方处理
int32_t ret = gpio_write(PORTA, PIN_5, 1);
if (ret < 0) {
// 根据错误码做针对性处理
if (ret == -ERR_INVALID_PARAM) {
// 参数错误
} else if (ret == -ERR_TIMEOUT) {
// 超时
}
}3.4 错误码定义：别用魔法数字
错误码这件事，我吃过一次大亏。有一次项目联调，底层驱动返回了个 -23，上层应用完全不知道什么意思，查代码查了整整一天。后来发现是缓冲区溢出——但 -23 这个数字，鬼知道对应什么。
所以，错误码必须用枚举定义，而且要分层：
// 基础错误码（0x0000 - 0x00FF）
typedef enum {
ERR_OK = 0, // 成功
ERR_GENERIC = -1, // 通用错误
ERR_NOT_SUPPORTED = -2, // 不支持
ERR_INVALID_PARAM = -3, // 参数无效
ERR_TIMEOUT = -4, // 超时
ERR_BUSY = -5, // 资源忙
ERR_NOMEM = -6, // 内存不足
ERR_IO = -7, // IO 错误
} hal_err_t;
// 模块扩展错误码（0x0100 - 0xFFFF）
#define ERR_I2C_NACK (-256) // I2C 无应答
#define ERR_SPI_CRC (-257) // SPI CRC 校验失败| 错误码范围 | 用途 | 示例 |
|---|---|---|
| 0 | 成功 | ERR_OK |
| -1 ~ -127 | 通用错误（所有模块共用） | ERR_INVALID_PARAM |
| -128 ~ -1023 | 模块专用错误 | ERR_I2C_NACK |
| -1024 以下 | 驱动层私有错误 | 芯片厂商自定义 |
3.5 回调函数设计：别让调用者猜
回调函数是 HAL 层和上层应用之间的「桥梁」。设计得好，上层代码写起来行云流水；设计得烂，上层开发者恨不得顺着网线过来打你。
我总结了几条铁律：
- 回调函数指针必须用 typedef 定义，方便阅读和维护。
- 回调的第一个参数必须是
void *user_data，用于传递上下文。 - 回调中不要做耗时操作。回调通常运行在中断上下文，你在这里做延时，整个系统都得崩。
- 提供注册和注销接口，成对出现。
// 定义回调类型
typedef void (*gpio_irq_callback_t)(gpio_port_t port, gpio_pin_t pin, void *user_data);
// 注册回调
int32_t gpio_register_irq_callback(gpio_port_t port, gpio_pin_t pin,
gpio_irq_callback_t callback, void *user_data);
// 注销回调
int32_t gpio_unregister_irq_callback(gpio_port_t port, gpio_pin_t pin);
// 使用示例
void my_irq_handler(gpio_port_t port, gpio_pin_t pin, void *user_data) {
// 注意：这里不能做 printf、malloc 等操作
// 只能做轻量级处理，比如设置标志位
*(volatile uint32_t *)user_data = 1;
}
uint32_t irq_flag = 0;
gpio_register_irq_callback(PORTA, PIN_5, my_irq_handler, &irq_flag);printf，结果中断一触发，系统就死机。查了两天才发现是 printf 内部用了互斥锁，而中断里拿不到锁。记住：回调里只做「标记」，不做「处理」。
3.6 知识结构总览
下面这张图，把 HAL 层接口设计的核心要素串起来了。你可以把它当作一个检查清单——每次设计新接口时，对着过一遍：
嗯，这一章的内容就这些。接口规范看起来是「小事」，但实际项目里，往往是这些「小事」决定了开发效率。你按这套规范去写，至少能保证：新人上手快、移植不出错、调试不抓狂。