📚 课程目录第4章硬件抽象层(HAL)设计

4. 硬件抽象层(HAL)设计：HAL层的作用与设计方法

说到HAL层，很多初学者觉得它就是「包一层函数」。其实没那么简单。我做了十几年嵌入式，见过太多项目因为HAL设计得不好，后期移植时改到崩溃。

HAL层到底解决什么问题？说白了，就是让上层代码不关心底层寄存器。你写应用的人，不需要知道GPIO的ODR寄存器地址，也不需要管UART的波特率怎么配。这些脏活累活，HAL层帮你干了。

4.1 HAL层的作用

我习惯把HAL层比作「翻译官」。芯片厂商给你的是数据手册，里面全是寄存器位定义。你的应用层想要的是「点亮LED」「发送一帧数据」。HAL层就在中间做翻译。

HAL层的核心职责：

隔离硬件差异：换MCU型号，只改HAL层，上层代码不动
提供统一接口：不管底层是STM32还是GD32，API长一样
封装复杂时序：比如I2C的START/STOP/ACK时序，HAL帮你搞定
管理资源冲突：同一个外设被多个模块调用时，HAL做仲裁

我在一个项目中遇到过这种情况：产品用了三款不同的MCU做兼容设计。如果没有HAL层，应用代码要写三套。有了HAL层，应用代码只调HAL_GPIO_WritePin()，底层实现换芯片时重写就行。嗯，这就是HAL的价值。

4.2 HAL接口设计原则

设计HAL接口时，我总结了几条铁律。你想想看，如果接口设计得不好，后面所有依赖它的模块都得跟着改，那代价太大了。

原则	说明	反面案例
参数抽象	用枚举/结构体代替裸数字	HAL_GPIO_SetMode(1, 2) — 谁看得懂？
无状态设计	函数不依赖内部全局变量	UART_Send()依赖内部缓冲区状态
错误返回	统一用int返回错误码	void函数，出错了你不知道
超时机制	阻塞操作必须带超时参数	I2C_Read()死等，卡死整个系统

我的个人习惯：所有HAL接口的命名统一用 HAL_外设_动作() 格式。比如 HAL_GPIO_WritePin()、HAL_UART_Transmit()。这样团队里任何人一看就知道这个函数是干什么的。

4.3 GPIO的HAL封装

GPIO是最基础的外设。封装时要注意：不同芯片的GPIO寄存器结构差异很大。有的用ODR+BSRR，有的用OUT+SET+CLR。

我曾经在一个项目里，因为GPIO的HAL接口没设计好，导致上层代码里到处都是 #ifdef CHIP_A 这种宏。后来重构时，我把接口统一成下面这样：

/* GPIO HAL接口定义 */
typedef enum {
    HAL_GPIO_MODE_INPUT,
    HAL_GPIO_MODE_OUTPUT_PP,   /* 推挽输出 */
    HAL_GPIO_MODE_OUTPUT_OD,   /* 开漏输出 */
    HAL_GPIO_MODE_AF,          /* 复用功能 */
    HAL_GPIO_MODE_ANALOG
} HAL_GPIO_Mode_t;

typedef enum {
    HAL_GPIO_PULL_NONE,
    HAL_GPIO_PULL_UP,
    HAL_GPIO_PULL_DOWN
} HAL_GPIO_Pull_t;

/* 初始化结构体 */
typedef struct {
    uint16_t        Pin;
    HAL_GPIO_Mode_t Mode;
    HAL_GPIO_Pull_t Pull;
    uint8_t         Speed;      /* 0:low, 1:medium, 2:high */
} HAL_GPIO_Init_t;

/* 接口函数 */
int HAL_GPIO_Init(HAL_GPIO_Init_t *init);
int HAL_GPIO_WritePin(uint16_t pin, uint8_t level);
int HAL_GPIO_ReadPin(uint16_t pin);
int HAL_GPIO_TogglePin(uint16_t pin);

你看，上层调用时只需要填结构体，底层实现里再去操作寄存器。换芯片时，只要重写这5个函数就行。

4.4 UART的HAL封装

UART封装时有个坑：中断接收和DMA接收的处理方式完全不同。我建议把接收方式也抽象成参数，而不是写死。

/* UART HAL接口 */
typedef enum {
    HAL_UART_MODE_POLLING,
    HAL_UART_MODE_IT,       /* 中断模式 */
    HAL_UART_MODE_DMA
} HAL_UART_Mode_t;

typedef struct {
    uint32_t        BaudRate;
    uint8_t         DataBits;   /* 7 or 8 */
    uint8_t         StopBits;   /* 1 or 2 */
    uint8_t         Parity;     /* 0:none, 1:odd, 2:even */
    HAL_UART_Mode_t RxMode;
    HAL_UART_Mode_t TxMode;
} HAL_UART_Init_t;

/* 发送：阻塞模式，带超时 */
int HAL_UART_Transmit(uint8_t *data, uint16_t len, uint32_t timeout_ms);

/* 接收：非阻塞，注册回调 */
int HAL_UART_Receive_IT(uint8_t *buf, uint16_t len,
                        void (*callback)(uint8_t *data, uint16_t len));

/* 查询接收状态 */
int HAL_UART_GetState(void);

注意：UART的HAL层一定要处理 溢出错误 和 帧错误。我见过太多项目，UART收到乱码后直接死机，就是因为HAL层没做错误恢复。建议在HAL层内部加一个错误计数器，连续出错超过阈值就复位外设。

4.5 SPI的HAL封装

SPI的难点在于：不同设备的时序要求不一样。有的CPOL=0/CPHA=0，有的CPOL=1/CPHA=1。HAL层必须把这些参数暴露出来。

/* SPI HAL接口 */
typedef enum {
    HAL_SPI_MODE_MASTER,
    HAL_SPI_MODE_SLAVE
} HAL_SPI_Mode_t;

typedef struct {
    HAL_SPI_Mode_t  Mode;
    uint8_t         CPOL;       /* 时钟极性 */
    uint8_t         CPHA;       /* 时钟相位 */
    uint32_t        BaudRate;   /* 实际会取最接近的值 */
    uint8_t         DataSize;   /* 8 or 16 */
} HAL_SPI_Init_t;

/* 全双工收发 */
int HAL_SPI_TransmitReceive(uint8_t *tx_data, uint8_t *rx_data,
                            uint16_t len, uint32_t timeout_ms);

/* 只发送 */
int HAL_SPI_Transmit(uint8_t *data, uint16_t len, uint32_t timeout_ms);

/* 片选控制（留给上层自己控制） */
int HAL_SPI_CS_Select(void);
int HAL_SPI_CS_DeSelect(void);

我个人习惯把片选控制交给上层，而不是在HAL层内部自动控制。为什么？因为有些设备需要在发送前后保持片选低电平，有些需要中间拉高再拉低。HAL层猜不到这些，让上层自己控制更灵活。

4.6 I2C的HAL封装

I2C是所有外设里最麻烦的。它的时序要求严格，而且不同芯片的I2C控制器实现差异巨大。有的用状态机，有的用中断+DMA。

/* I2C HAL接口 */
typedef struct {
    uint32_t        ClockSpeed; /* 标准100k, 快速400k */
    uint8_t         OwnAddress; /* 从机地址（从机模式用） */
} HAL_I2C_Init_t;

/* 主机写 */
int HAL_I2C_Master_Transmit(uint8_t dev_addr, uint8_t *data,
                            uint16_t len, uint32_t timeout_ms);

/* 主机读 */
int HAL_I2C_Master_Receive(uint8_t dev_addr, uint8_t *data,
                           uint16_t len, uint32_t timeout_ms);

/* 写后读（复合操作，很多传感器需要） */
int HAL_I2C_Mem_Read(uint8_t dev_addr, uint8_t mem_addr,
                     uint8_t *data, uint16_t len, uint32_t timeout_ms);

/* 检测设备是否应答 */
int HAL_I2C_IsDeviceReady(uint8_t dev_addr, uint32_t timeout_ms);

避坑指南：I2C的HAL层一定要处理 总线仲裁丢失 和 NACK。我曾经在一个项目中，I2C从机没上电，主机一直等ACK，结果整个系统卡死了。后来我在HAL层加了超时重试机制，连续3次NACK就返回错误码，上层收到错误后做恢复处理。

4.7 HAL层架构总览

下面这张图展示了HAL层在整个软件架构中的位置。你可以看到，HAL层是承上启下的关键一层。

4.8 设计HAL时的几个坑

最后分享几个我踩过的坑，希望能帮你少走弯路。

坑1：HAL层里做太多事情

有人喜欢在HAL层里加协议解析、加数据缓存、加任务调度。千万别！HAL层只做一件事：把上层请求翻译成寄存器操作。其他事情交给上层去做。

坑2：接口参数太具体

比如 HAL_SPI_SetBaudRate(1000000)，这个接口看起来没问题。但换了个芯片，它不支持1MHz怎么办？我建议用枚举或范围值，比如 HAL_SPI_SPEED_HIGH，底层自己去映射。

坑3：忽略错误处理

很多HAL接口返回void，出错了也不告诉你。我建议所有可能失败的接口都返回int，0表示成功，负数表示错误码。上层可以根据错误码做恢复处理，而不是傻等。

嗯，HAL层设计就讲到这里。记住一句话：好的HAL层，让上层开发者感觉不到底层芯片的存在。如果你能做到这一点，你的HAL层设计就合格了。