2. HAL接口设计规范：命名、参数、错误码与跨平台

接口设计规范这东西，说白了就是团队里的「通用语言」。我早年吃过不少亏——不同模块的驱动接口风格各异，有的用下划线，有的用驼峰，参数顺序也随心情。结果集成时光是适配就花了两周。后来我定下了一套规矩，也就是今天要聊的这套HAL接口设计规范。

2.1 接口命名规则

命名这件事，我个人的习惯是「一看就懂，一写就对」。HAL接口的命名应该遵循以下几条核心原则：

• 模块前缀 + 动作 + 对象：比如 hal_i2c_write()、hal_gpio_set()。前缀表明所属模块，动作清晰，对象明确。
• 全小写 + 下划线分隔：这是嵌入式C的通行做法。避免驼峰，因为不同编译器对大小写的处理可能有细微差异。
• 动词开头，参数在后：hal_uart_send() 而不是 hal_uart_data_send()。动词放前面，读起来像自然语言。
• 避免缩写歧义：hal_timer_config() 比 hal_tmr_cfg() 好。省那几个字符不值得。

我曾经在一个项目里见过有人用 HAL_I2C_Master_Transmit_IT() 这种命名——太长，而且「IT」是中断的缩写，新人根本看不懂。后来我们统一改成 hal_i2c_write_it()，简洁多了。

2.2 参数传递约定

参数传递这块，坑特别多。我总结了几条铁律：

• 输入参数放前面，输出参数放后面：hal_spi_read(handle, rx_buf, len) 中 handle 和 len 是输入，rx_buf 是输出。这个顺序符合直觉。
• 句柄作为第一个参数：所有操作都依赖设备句柄，把它放在第一位，方便阅读和扩展。
• 长度参数紧跟缓冲区：hal_uart_send(handle, data, len)，不要写成 hal_uart_send(handle, len, data)。缓冲区与长度挨着，逻辑上更紧凑。
• 避免使用全局变量传参：HAL层应该无状态，所有状态都通过句柄传递。全局变量会让多实例支持变得极其痛苦。

2.3 返回值与错误码定义

返回值设计是HAL接口的「脸面」。用户拿到返回值，应该立刻知道发生了什么。我常用的做法是：

• 统一返回类型：所有HAL接口返回 hal_err_t 枚举类型。成功返回 HAL_OK，失败返回具体错误码。
• 错误码分层：模块级错误码从 0x100 开始，驱动级从 0x200 开始，方便定位。
• 数据通过参数返回：返回值只表示执行状态，真正的数据通过输出参数传递。

typedef enum {
    HAL_OK       = 0,      // 成功
    HAL_ERROR    = -1,     // 通用错误
    HAL_BUSY     = -2,     // 设备忙
    HAL_TIMEOUT  = -3,     // 超时
    HAL_INVALID  = -4,     // 参数无效
    HAL_NOMEM    = -5,     // 内存不足
    
    // I2C 模块错误 (0x100 起)
    HAL_I2C_BUS_ERROR   = 0x101,
    HAL_I2C_NACK_ERROR  = 0x102,
    HAL_I2C_ARB_LOST    = 0x103,
    
    // SPI 模块错误 (0x200 起)
    HAL_SPI_CRC_ERROR   = 0x201,
    HAL_SPI_MODE_ERROR  = 0x202,
} hal_err_t;

嗯，这里要注意：错误码不要用正数。正数容易和成功混淆。我见过有人用 0 表示成功，1 表示失败——结果调用方写 if (ret) 时逻辑是反的，调试了一下午才发现。

2.4 跨平台兼容性设计

跨平台是HAL层的核心价值。你想想看，如果换一个MCU就要重写所有驱动，那HAL还有什么意义？

我常用的跨平台策略包括：

• 数据类型抽象：用 uint32_t、int16_t 等标准类型，避免 int、long 这种平台相关的类型。
• 寄存器操作封装：所有对硬件寄存器的读写都通过宏或内联函数，比如 REG_READ(addr)、REG_WRITE(addr, val)。
• 中断处理标准化：HAL层不直接操作中断向量表，而是注册回调函数，由底层平台适配。
• 时钟与延时抽象：提供 hal_delay_ms()、hal_get_tick() 等接口，底层实现由平台提供。

// hal_platform.h — 平台抽象头文件
#ifndef HAL_PLATFORM_H
#define HAL_PLATFORM_H

// 数据类型抽象
#include <stdint.h>

// 寄存器操作宏
#define REG_READ(addr)     (*(volatile uint32_t *)(addr))
#define REG_WRITE(addr, v) (*(volatile uint32_t *)(addr) = (v))

// 平台需实现的接口
void hal_platform_init(void);
uint32_t hal_get_tick(void);
void hal_delay_ms(uint32_t ms);
void hal_enter_critical(void);
void hal_exit_critical(void);

#endif

我曾经把一个项目从STM32F4移植到GD32F3，只改了底层适配层的5个函数，上层HAL接口一行代码没动。这就是跨平台设计的价值。

2.5 知识体系总览

下面这张图把HAL接口设计规范的核心脉络梳理了一遍。你可以把它当作设计时的检查清单。

这张图把四个核心维度串在了一起。你设计接口时，可以对照着检查：命名是否统一？参数顺序是否合理？错误码是否可追溯？跨平台适配层是否完整？