第4章 HAL接口规范：标准化的设备操作接口与错误码定义

说实话，HAL（硬件抽象层）接口规范这事儿，我早年吃过不少亏。那时候做项目，团队里每个人写驱动都有自己的风格——有人喜欢用 dev_open，有人用 device_init，还有人直接往结构体里塞函数指针。结果呢？换了个MCU平台，整个驱动层几乎重写。嗯，从那以后我就下定决心，必须把接口规范定死。

4.1 标准设备操作接口：open/close/read/write/ioctl

我个人的习惯是，HAL层对外暴露的接口越少越好，但每个接口的语义必须清晰。参考POSIX模型，但又不能照搬——嵌入式环境哪有文件描述符那一套？

核心接口就五个：

接口	原型	语义说明
open	int hal_open(void *dev, uint32_t flags)	初始化设备，申请硬件资源
close	int hal_close(void *dev)	释放设备，归还资源
read	int hal_read(void *dev, uint8_t *buf, uint32_t len)	从设备读取数据
write	int hal_write(void *dev, const uint8_t *buf, uint32_t len)	向设备写入数据
ioctl	int hal_ioctl(void *dev, uint32_t cmd, void *arg)	控制命令，配置参数

你想想看，如果每个设备的 open 参数都不一样，那上层应用怎么统一调用？所以必须把差异封装在设备实例内部。

4.2 接口实现规范

每个接口的返回值必须统一。我见过最坑的项目——有的驱动返回0表示成功，有的返回1，还有的返回负数表示错误码。调试的时候简直想骂人。

咱们定死规则：

• 返回0：操作成功
• 返回正数：成功，且返回值为实际处理的数据长度（read/write专用）
• 返回负数：操作失败，负数的绝对值就是错误码

举个例子：

// 标准实现模板
static int uart_open(void *dev, uint32_t flags) {
    uart_dev_t *uart = (uart_dev_t *)dev;
    
    if (uart == NULL) {
        return -HAL_ERR_INVALID_PARAM;
    }
    
    if (uart->state == HAL_STATE_OPENED) {
        return -HAL_ERR_BUSY;  // 设备已被打开
    }
    
    // 初始化硬件
    if (HAL_OK != uart_hw_init(uart->base_addr, flags)) {
        return -HAL_ERR_HW_FAIL;
    }
    
    uart->state = HAL_STATE_OPENED;
    return HAL_OK;  // 即 0
}

4.3 错误码定义与返回机制

错误码这事儿，说白了就是给上层一个明确的失败原因。不能所有错误都返回 -1，那跟没返回一样。

我习惯用枚举定义错误码，按模块分组：

// hal_error.h
typedef enum {
    HAL_OK                =  0,   // 成功
    HAL_ERR_BASE          = -1,   // 通用错误起始
    
    // 参数类错误 (-1 ~ -16)
    HAL_ERR_INVALID_PARAM = -1,   // 参数无效
    HAL_ERR_NULL_PTR      = -2,   // 空指针
    HAL_ERR_OUT_OF_RANGE  = -3,   // 参数越界
    
    // 状态类错误 (-17 ~ -32)
    HAL_ERR_BUSY          = -17,  // 设备忙
    HAL_ERR_TIMEOUT       = -18,  // 操作超时
    HAL_ERR_NOT_OPENED    = -19,  // 设备未打开
    HAL_ERR_NOT_SUPPORTED = -20,  // 不支持的操作
    
    // 硬件类错误 (-33 ~ -48)
    HAL_ERR_HW_FAIL       = -33,  // 硬件故障
    HAL_ERR_DMA_FAIL      = -34,  // DMA传输失败
    HAL_ERR_CRC_MISMATCH  = -35,  // CRC校验失败
    
    // 资源类错误 (-49 ~ -64)
    HAL_ERR_NO_MEM        = -49,  // 内存不足
    HAL_ERR_NO_RESOURCE   = -50,  // 资源不足
} hal_error_t;

4.4 错误码传播机制

错误码不能只停留在HAL层。上层应用需要知道哪里出了问题。我设计了一个简单的错误传播链：

// 错误信息结构体
typedef struct {
    hal_error_t  err_code;    // 错误码
    const char  *err_file;    // 发生错误的文件名
    uint32_t     err_line;    // 行号
    uint32_t     err_time;    // 时间戳（可选）
} hal_err_info_t;

// 全局错误记录（每个线程/任务独立）
hal_err_info_t g_hal_err_info;

// 设置错误信息
static inline void hal_set_error(hal_error_t code) {
    g_hal_err_info.err_code = code;
    g_hal_err_info.err_file = __FILE__;
    g_hal_err_info.err_line = __LINE__;
    g_hal_err_info.err_time = hal_get_tick();
}

// 使用示例
int hal_uart_write(void *dev, const uint8_t *buf, uint32_t len) {
    uart_dev_t *uart = (uart_dev_t *)dev;
    
    if (uart == NULL) {
        hal_set_error(HAL_ERR_NULL_PTR);
        return HAL_ERR_NULL_PTR;
    }
    
    if (uart->state != HAL_STATE_OPENED) {
        hal_set_error(HAL_ERR_NOT_OPENED);
        return HAL_ERR_NOT_OPENED;
    }
    
    // ... 实际写入逻辑
}

4.5 接口规范检查清单

每次写新驱动，我都会对照这个清单检查：

1. 参数检查：所有接口入口必须检查 dev 是否为NULL
2. 状态检查：read/write 前检查设备是否已 open
3. 返回值统一：成功返回0或正数，失败返回负数错误码
4. 错误码明确：不要返回 -1，用枚举值
5. 资源释放：close 必须释放所有 open 时申请的资源
6. 可重入性：接口内部如果使用全局变量，必须加锁

4.6 HAL接口调用流程图

下面这张图展示了标准HAL接口的调用流程，从上层应用到底层硬件：

4.7 实际项目中的接口适配

我记得有一次给一个SPI Flash芯片写驱动。芯片支持读、写、擦除、状态查询。按照标准接口，我这样映射：

标准接口	SPI Flash映射	说明
open	初始化SPI控制器，读取设备ID	验证芯片是否存在
close	关闭SPI控制器，进入低功耗	释放总线
read	读取指定地址的数据	支持任意长度
write	写入数据到页缓冲区	自动处理页对齐
ioctl	擦除操作、状态查询、设置写保护	用命令码区分

4.8 接口规范落地检查

最后，我分享一个实际用过的代码审查清单。每次提交HAL驱动代码前，对照检查：

• 所有接口是否都实现了参数有效性检查？
• 错误码是否使用了枚举值，而不是魔法数字？
• open 和 close 是否成对出现？资源有没有泄漏？
• 多任务环境下，接口是否可重入？
• 返回值是否严格遵循“0成功、正数数据长度、负数错误码”？

嗯，这套规范我用在三个不同的项目里，从STM32到GD32再到国产RISC-V芯片，上层应用代码一行没改。这就是接口规范的力量。