第2章 HAL架构设计：分层架构思想、接口设计原则与驱动模型抽象

做嵌入式驱动开发这些年，我见过太多"一把梭"式的代码——应用层直接操作寄存器，中断处理里塞业务逻辑，换个芯片平台就要重写大半。说白了，这就是没有架构思维。HAL层存在的意义，就是给上层一个稳定的接口，把硬件差异挡在下面。

这一章，我们聊聊HAL架构设计的核心思路。不是讲空理论，而是结合我踩过的坑，把分层思想、接口设计、驱动抽象和设备树这些事儿说透。

2.1 分层架构思想：为什么非要分层？

先看一个反面教材。我早年接手过一个项目，GPIO控制函数直接写在业务逻辑里：

// 业务代码里直接操作寄存器
void set_led_on(void) {
    *(volatile uint32_t *)0x40020C14 |= (1 << 13);  // 直接写GPIOB_BSRR
}

这种代码跑起来没问题，但换一颗MCU就全废。更可怕的是，硬件工程师改了引脚映射，你得满世界找那个魔法数字。

分层架构要解决的就是这个痛点。典型的嵌入式软件分层是这样的：

我个人习惯把HAL层再拆成两层：

• HAL接口层：定义纯虚接口，与具体硬件无关
• HAL实现层：针对具体芯片的驱动实现

为什么要这么拆？你想想看，如果你的产品要支持STM32和GD32两套方案，接口层可以共用，只需要换实现层。我在做某款工业控制器时就用了这个思路，换主控芯片只改了不到200行代码。

2.2 HAL层接口设计原则

接口设计是HAL层的灵魂。设计得好，上层开发人员可以不知道底层是什么芯片；设计得烂，HAL层就是个摆设。

我总结了四条核心原则，每条都是用教训换来的：

原则	说明	反面案例
1. 接口原子化	每个函数只做一件事	gpio_init_and_set() 这种缝合怪
2. 参数抽象化	用枚举/结构体代替魔法数字	uart_config(115200, 8, 1, 0) 谁记得参数顺序？
3. 返回值标准化	统一返回错误码	有的返回-1，有的返回NULL，有的直接死机
4. 上下文无关	不依赖全局状态	函数内部偷偷改了别的外设配置

举个例子，一个合格的HAL接口应该长这样：

// 好的接口设计
typedef enum {
    GPIO_PIN_0 = 0,
    GPIO_PIN_1,
    // ...
    GPIO_PIN_15
} gpio_pin_t;

typedef enum {
    GPIO_MODE_INPUT,
    GPIO_MODE_OUTPUT,
    GPIO_MODE_AF,
    GPIO_MODE_ANALOG
} gpio_mode_t;

typedef struct {
    gpio_pin_t pin;
    gpio_mode_t mode;
    bool pull_up;
    bool pull_down;
} gpio_config_t;

hal_err_t hal_gpio_init(gpio_port_t port, const gpio_config_t *config);
hal_err_t hal_gpio_set(gpio_port_t port, gpio_pin_t pin, bool level);
hal_err_t hal_gpio_get(gpio_port_t port, gpio_pin_t pin, bool *level);

2.3 驱动模型抽象

驱动模型抽象，说白了就是找到不同硬件之间的"最大公约数"。比如I2C，不管哪家芯片，核心操作就是：发起始信号、发地址、读写数据、收停止信号。把这些抽象出来，就是驱动模型。

我常用的驱动模型分层结构：

// 驱动模型抽象层 - 定义操作接口
typedef struct {
    hal_err_t (*init)(void *handle, const void *config);
    hal_err_t (*deinit)(void *handle);
    hal_err_t (*read)(void *handle, uint8_t *buf, uint32_t len);
    hal_err_t (*write)(void *handle, const uint8_t *buf, uint32_t len);
    hal_err_t (*ioctl)(void *handle, uint32_t cmd, void *arg);
} hal_driver_ops_t;

// 驱动实例结构体
typedef struct {
    const hal_driver_ops_t *ops;
    void *priv;  // 私有数据，指向具体硬件实现
} hal_driver_t;

这种设计的好处是：上层拿着 hal_driver_t 指针就能操作任何外设，根本不用关心底层是SPI Flash还是I2C EEPROM。我在做传感器融合项目时，用这套模型同时管理了6种不同接口的传感器，上层代码一行没改。

2.4 设备树与HAL的关系

设备树（Device Tree）这个概念最早来自Linux内核，现在很多RTOS和裸机项目也开始借鉴。它的核心思想是：用数据描述硬件，而不是用代码。

设备树和HAL层的关系，我画了一张图来说明：

设备树文件（.dts）编译成二进制（.dtb）后，由解析器在运行时读取。HAL层驱动根据解析出的参数完成初始化。这样做的好处是：换硬件只需要改.dts文件，驱动代码不用动。

举个实际例子，我在一个项目里用设备树描述UART引脚：

// uart.dts 片段
uart0: uart@40011000 {
    compatible = "vendor,uart-v1";
    reg = <0x40011000 0x400>;
    interrupts = <37>;
    clocks = <&clk_uart0>;
    pinctrl-0 = <&uart0_pins>;
    pinctrl-names = "default";
    status = "okay";
};

uart0_pins: uart0-pins {
    pinmux = <GPIO_A_9 AF7>,  // TX
             <GPIO_A_10 AF7>; // RX
};

HAL层驱动解析这个节点后，自动完成GPIO复用配置、时钟使能、中断注册。上层应用调用 hal_uart_send() 时，根本不知道底层引脚是A9/A10还是B6/B7。

2.5 架构设计的落地建议

说了这么多，最后给几条实操建议：

1. 先画分层图，再写代码。我每次新项目都会在白板上画出各层之间的接口关系，确认没有循环依赖再动手。
2. 接口先行。先定义好HAL层的头文件，让应用层开发人员可以基于头文件写代码，底层实现可以后面再补。
3. 留好扩展点。比如在驱动结构体里预留 ioctl 接口，方便以后加特殊功能。
4. 性能与抽象的平衡。高频路径可以加 inline 或者直接提供寄存器操作宏，但要用命名规范区分开。