📚 课程目录第2章接口定义规范

接口定义规范：HAL设备结构体设计、操作函数指针集、错误码枚举、初始化与去初始化契约

接口定义规范，说白了就是给驱动框架立规矩。没有规矩，不成方圆。我见过太多项目，驱动代码写得像一盘散沙，换颗芯片就要重写一半。为什么？就是因为接口没定好。

这一节，我们就把规矩立清楚。从设备结构体怎么设计，到操作函数怎么组织，再到错误码怎么枚举，最后是初始化和去初始化的契约。一套下来，你的驱动代码就能做到「换芯片不换接口，换平台不换逻辑」。

2.1 HAL设备结构体设计

设备结构体是驱动的「身份证」。它描述了一个外设实例的所有属性和状态。我习惯把结构体分成三个区域：标识区、配置区、状态区。

区域	字段	说明
标识区	`uint8_t port`	外设端口号，比如 UART1、SPI2
	`uint8_t instance`	实例编号，同端口多实例时区分
配置区	`void *config`	指向具体配置结构体的指针
	`uint32_t timeout_ms`	超时时间，单位毫秒
状态区	`volatile uint8_t flags`	状态标志位，比如初始化完成、忙、错误
	`uint8_t error_code`	最近一次错误码

举个例子，一个典型的 UART 设备结构体长这样：

typedef struct {
    uint8_t port;              // 端口号：0=UART1, 1=UART2
    uint8_t instance;          // 实例编号，默认0
    void *config;              // 指向 UART_Config_t 的指针
    uint32_t timeout_ms;       // 超时时间
    volatile uint8_t flags;    // 状态标志
    uint8_t error_code;        // 错误码
} HAL_UART_Device_t;

个人经验： 我建议把 flags 声明为 volatile。为什么？因为中断服务程序可能会修改它。不加 volatile，编译器优化时可能把值缓存到寄存器里，导致主循环读不到最新状态。我曾经因为这个 bug 查了整整两天。

2.2 操作函数指针集

函数指针集是驱动的「操作手册」。它定义了一组标准操作，每个外设驱动都要实现这些操作。这样上层代码就不用关心底层是哪个芯片了。

我一般把操作函数指针集定义为一个结构体，里面放函数指针：

typedef struct {
    int32_t (*init)(void *device);
    int32_t (*deinit)(void *device);
    int32_t (*read)(void *device, uint8_t *buf, uint32_t len);
    int32_t (*write)(void *device, const uint8_t *buf, uint32_t len);
    int32_t (*ioctl)(void *device, uint32_t cmd, void *arg);
    int32_t (*control)(void *device, uint32_t ctrl, void *arg);
} HAL_Operations_t;

每个外设驱动都要提供一个 HAL_Operations_t 实例。比如 UART 驱动：

const HAL_Operations_t UART_Ops = {
    .init    = UART_Init,
    .deinit  = UART_Deinit,
    .read    = UART_Read,
    .write   = UART_Write,
    .ioctl   = UART_Ioctl,
    .control = UART_Control
};

核心思想： 设备结构体 + 操作函数指针集 = 一个完整的驱动实例。上层代码通过设备句柄调用操作函数，完全不需要知道底层实现细节。

2.3 错误码枚举

错误码是驱动的「诊断语言」。没有统一的错误码，调试时就像在黑暗中摸索。我见过有人用 -1 表示所有错误，结果出了问题根本不知道是哪里挂了。

我建议定义一个全局的错误码枚举：

typedef enum {
    HAL_OK       = 0,    // 成功
    HAL_ERROR    = -1,   // 通用错误
    HAL_BUSY     = -2,   // 设备忙
    HAL_TIMEOUT  = -3,   // 超时
    HAL_INVALID  = -4,   // 参数无效
    HAL_UNSUPPORTED = -5, // 不支持的操作
    HAL_NOMEM    = -6,   // 内存不足
    HAL_IO       = -7    // IO错误
} HAL_Error_t;

每个驱动函数都返回 int32_t，成功返回 HAL_OK，失败返回对应的错误码。这样上层代码就能根据错误码做不同的处理。

避坑指南： 我曾经在一个项目里看到有人把错误码定义成 uint8_t，结果 -1 变成了 255。上层代码判断 if (ret < 0) 永远不成立。所以错误码一定要用有符号类型，推荐 int32_t。

2.4 初始化与去初始化契约

初始化和去初始化是驱动的「生命周期管理」。它们必须成对出现，而且有严格的执行顺序。我称之为「契约」。

初始化契约：

调用 init 前，设备结构体必须清零
init 成功后，flags 的初始化位必须置1
如果 init 失败，必须回滚所有已分配的资源
init 不能重复调用，除非先调用 deinit

去初始化契约：

调用 deinit 前，必须确保没有正在进行的操作
deinit 必须释放所有资源（中断、DMA、内存等）
deinit 后，flags 的初始化位必须清零
deinit 可以重复调用，第二次调用直接返回 HAL_OK

int32_t UART_Init(void *device) {
    HAL_UART_Device_t *dev = (HAL_UART_Device_t *)device;
    if (dev == NULL) return HAL_INVALID;
    if (dev->flags & 0x01) return HAL_BUSY; // 已经初始化

    // 初始化硬件
    // ...

    dev->flags |= 0x01; // 标记初始化完成
    return HAL_OK;
}

int32_t UART_Deinit(void *device) {
    HAL_UART_Device_t *dev = (HAL_UART_Device_t *)device;
    if (dev == NULL) return HAL_INVALID;
    if (!(dev->flags & 0x01)) return HAL_OK; // 已经去初始化

    // 释放硬件资源
    // ...

    dev->flags &= ~0x01; // 清除初始化标记
    return HAL_OK;
}

个人习惯： 我总会在 deinit 里加一个「幂等」检查。就是第二次调用直接返回成功。为什么？因为系统关闭时，多个模块可能都会调用 deinit，如果第二次调用报错，整个关闭流程就乱了。

2.5 整体框架图

下面这张图展示了 HAL 设备结构体、操作函数指针集、错误码枚举和初始化契约之间的关系：

2.6 小结

接口定义规范是 HAL 框架的基石。设备结构体定义了「是什么」，操作函数指针集定义了「能做什么」，错误码枚举定义了「做得怎么样」，初始化契约定义了「怎么开始和结束」。四者缺一不可。

嗯，这里要注意：这些规范不是写出来就完事了。团队里每个人都要遵守，代码审查时要重点检查。我见过一个项目，接口规范写得漂漂亮亮，结果有人偷偷在驱动里加了个 HAL_MY_SPECIAL_ERROR，上层代码根本处理不了。所以，规范定了就要执行，不然就是一张废纸。