3. 硬件抽象层(HAL)设计：HAL层分层架构、设备驱动抽象、寄存器操作封装、HAL层接口定义

好，咱们进入第三章。硬件抽象层，简称 HAL。这词听起来挺唬人，说白了就是给上层应用和底层硬件之间加一层“翻译官”。

我早年做项目，习惯直接把寄存器操作写在业务逻辑里。那时候代码跑得欢，但换颗芯片就傻眼了——几乎全部重写。后来我学乖了，开始认真设计 HAL 层。你想想看，如果能把硬件相关的代码都隔离起来，上层只管调用接口，移植起来多省心。

3.1 HAL 层分层架构

我个人习惯把 HAL 层分成三层。不是越复杂越好，而是刚好够用。

层级	名称	职责	依赖关系
L3	接口抽象层	定义统一 API，供上层模块调用	依赖 L2
L2	设备驱动抽象层	封装具体外设驱动逻辑	依赖 L1
L1	寄存器操作封装层	直接操作 MCU 寄存器	依赖芯片手册

这三层各司其职。L1 最贴近硬件，L3 最贴近业务。中间 L2 做适配和转换。我在项目中遇到过一种情况：团队里有人把 L3 的接口直接映射到 L1 的寄存器读写，跳过了 L2。结果换芯片时，L3 接口全得改，那叫一个痛苦。

3.2 设备驱动抽象

设备驱动抽象，说白了就是把“怎么操作这个设备”和“这个设备是什么”分开。

举个例子，GPIO 驱动。不管你是 STM32 还是 GD32，GPIO 无非就是：设置方向、输出高低、读取电平。差异在于寄存器地址和配置位。抽象层就把这些差异藏起来。

// 设备驱动抽象结构体示例
typedef struct {
    void (*init)(void);
    void (*set_direction)(uint8_t pin, uint8_t dir);
    void (*write_pin)(uint8_t pin, uint8_t level);
    uint8_t (*read_pin)(uint8_t pin);
} gpio_driver_t;

// 实例化一个具体的 GPIO 驱动
gpio_driver_t stm32_gpio = {
    .init = stm32_gpio_init,
    .set_direction = stm32_gpio_set_dir,
    .write_pin = stm32_gpio_write,
    .read_pin = stm32_gpio_read
};

你看，上层代码只需要拿到 gpio_driver_t 这个结构体指针，调用 write_pin 就行。至于底层是 STM32 还是 GD32，它不关心。这就是抽象的力量。

3.3 寄存器操作封装

寄存器操作封装是 HAL 层最底层的活。这里有个关键点：不要直接写魔法数字。

我见过不少代码，直接写 *(volatile uint32_t *)0x40020014 |= 0x01;。这种代码，三个月后自己都看不懂。正确的做法是用宏定义或内联函数把寄存器操作封装起来。

// 不好的写法
#define GPIOA_BSRR ((volatile uint32_t *)0x40020018)
#define GPIO_PIN_5 (1 << 5)

// 好的写法
static inline void gpio_set_pin(GPIO_TypeDef *gpio, uint16_t pin) {
    gpio->BSRR = pin;
}

static inline void gpio_reset_pin(GPIO_TypeDef *gpio, uint16_t pin) {
    gpio->BRR = pin;
}

内联函数的好处是：编译器会优化成和直接写寄存器一样的效率，但代码可读性和可维护性高得多。嗯，这里要注意：内联函数要放在头文件里，并且加上 static inline，避免链接冲突。

3.4 HAL 层接口定义

接口定义是 HAL 层的门面。接口好不好用，直接决定上层开发效率。

我总结了几条接口定义的原则：

• 一致性：同类设备的接口风格统一。比如所有初始化函数都叫 xxx_init，所有读写函数都叫 xxx_read/xxx_write。
• 最小化：接口数量越少越好。能 3 个接口搞定的，别搞 5 个。
• 无状态：接口不依赖内部状态。每次调用都是独立的。
• 错误返回：所有可能失败的接口都要返回错误码。

// HAL 层接口示例：UART
typedef enum {
    HAL_OK       = 0,
    HAL_ERROR    = 1,
    HAL_BUSY     = 2,
    HAL_TIMEOUT  = 3
} hal_status_t;

hal_status_t hal_uart_init(uart_handle_t *huart);
hal_status_t hal_uart_transmit(uart_handle_t *huart, uint8_t *data, uint16_t len, uint32_t timeout);
hal_status_t hal_uart_receive(uart_handle_t *huart, uint8_t *data, uint16_t len, uint32_t timeout);

你看，这三个接口覆盖了 UART 的基本操作。初始化、发送、接收。参数里都有超时时间，防止死等。这就是好的接口设计。

3.5 HAL 层整体结构图

下面这张图展示了 HAL 层的整体结构。你可以看到三层之间的关系，以及它们如何与上层应用和底层硬件交互。

3.6 接口定义实战要点

最后，我分享几个接口定义时的实战要点。这些都是我在项目里踩过的坑。

• 参数类型用标准类型：别用 uint8_t 表示长度，用 size_t。别用 int 表示状态，用枚举。
• 回调函数要谨慎：回调函数容易造成调用栈混乱。能用轮询解决的，别用回调。
• 初始化参数结构体化：如果初始化参数超过 3 个，建议用结构体传参。这样扩展起来方便。
• 接口版本号：在头文件里加个宏定义接口版本号。方便后续升级时做兼容性判断。

// 初始化参数结构体示例
typedef struct {
    uint32_t baudrate;
    uint8_t  data_bits;
    uint8_t  stop_bits;
    uint8_t  parity;
} uart_config_t;

hal_status_t hal_uart_init(uart_handle_t *huart, uart_config_t *config);

你看，这样传参，清晰明了。以后想加个流控制参数，直接在结构体里加字段就行，接口签名不用变。