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

2. 硬件抽象层(HAL)设计：GPIO、UART、I2C、SPI的底层封装原则

做嵌入式开发这些年，我见过太多工程师直接对着寄存器操作外设。刚开始确实很爽，代码写起来快，感觉掌控了一切。但项目一复杂，问题就来了——换个芯片型号，所有代码重写；换个板子，GPIO引脚号全得改。说白了，这就是没有硬件抽象层的后果。

这一章，我就跟你聊聊HAL层的设计思路。不是讲STM32的HAL库怎么用，而是讲你自己怎么设计一套轻量、可移植的硬件抽象层。

2.1 什么是硬件抽象层？

硬件抽象层，就是在芯片寄存器和你写的业务逻辑之间，加一层中间代码。它把硬件细节藏起来，对外只暴露统一的接口。

核心思想：上层代码不关心底层用的是STM32还是GD32，不关心GPIO挂在哪条总线上，只关心"初始化"、"读"、"写"这三个动作。

我举个例子你就明白了。假设你要控制一个LED灯：

// 没有HAL层——直接操作寄存器
#define LED_PORT GPIOA
#define LED_PIN  GPIO_PIN_5

void led_on(void) {
    HAL_GPIO_WritePin(LED_PORT, LED_PIN, GPIO_PIN_SET);
}

// 有HAL层——抽象接口
void led_on(void) {
    hal_gpio_write(LED_CHANNEL_0, HAL_GPIO_LEVEL_HIGH);
}

看出区别了吗？第二种写法里，LED_CHANNEL_0映射到哪个引脚、哪个端口，全在HAL层内部处理。换板子？改HAL层就行，上层代码一行不动。

2.2 GPIO封装原则

GPIO是最基础的外设，但封装起来反而最容易踩坑。我个人习惯把GPIO封装成三层：

层次	职责	示例
芯片寄存器层	直接操作寄存器	GPIOA->ODR \|= (1<<5)
HAL抽象层	统一接口，管理引脚映射	hal_gpio_write(ch, level)
应用层	业务逻辑	led_on(), key_scan()

封装要点：

用枚举定义引脚功能——别用魔法数字。比如 typedef enum {LED_CH_0, LED_CH_1, KEY_ENTER, KEY_ESC} gpio_channel_t;
初始化参数结构体化——把模式、上下拉、速度打包成一个结构体传进去
提供批量操作接口——比如 hal_gpio_write_port()，一次写8位

我曾经踩过的坑：有一次把GPIO初始化放在中断里调用，结果中断嵌套导致配置没写完就被打断，引脚输出电平乱跳。后来我规定：所有HAL初始化函数只能在任务级调用，中断里只做状态切换。

2.3 UART封装原则

UART的封装，核心在于收发缓冲和超时处理。我见过很多新手直接把HAL_UART_Transmit丢给上层，结果阻塞了整个系统。

我的做法是这样的：

// UART HAL接口定义
typedef struct {
    void (*init)(uart_cfg_t *cfg);
    int32_t (*send)(uint8_t *data, uint32_t len, uint32_t timeout_ms);
    int32_t (*receive)(uint8_t *buf, uint32_t len, uint32_t timeout_ms);
    uint32_t (*available)(void);
} uart_hal_t;

注意看，send和receive都带了timeout_ms参数。为什么？因为实际项目中，串口通信经常遇到对端没响应的情况。没有超时机制，你的系统就死在那了。

UART封装避坑指南：

发送用DMA或中断——别用阻塞轮询，除非波特率极低
接收用环形缓冲区——中断里只往缓冲区丢数据，上层轮询读取
错误标志要暴露——溢出、帧错误、校验错误，这些信息对调试很重要

小技巧：我习惯在UART HAL层加一个"回环测试"接口。调试的时候调用一下，就能快速判断硬件连接有没有问题。这个习惯帮我省了不少排查时间。

2.4 I2C封装原则

I2C的封装，难点在于从机地址和寄存器地址的分离。很多传感器芯片，读写操作需要先发寄存器地址，再发数据。如果HAL层不处理好这个，上层代码会变得很啰嗦。

我推荐这样设计接口：

// I2C HAL接口
int32_t hal_i2c_write_reg(uint8_t dev_addr, uint8_t reg_addr, 
                          uint8_t *data, uint32_t len);
int32_t hal_i2c_read_reg(uint8_t dev_addr, uint8_t reg_addr,
                         uint8_t *buf, uint32_t len);

你看，调用者只需要告诉HAL层"哪个设备、哪个寄存器、读写什么数据"，底层怎么组合起始信号、怎么发地址、怎么处理ACK/NACK，全封装在内部。

I2C封装要点：

支持多主机——至少留个接口配置自己的从机地址
超时机制必须做——I2C总线很容易被拉死，没有超时恢复，整个总线就废了
错误恢复接口——比如发送停止信号复位总线状态机

我曾经遇到的情况：一个项目里用了3个I2C传感器，每个的寄存器地址长度不一样（有8位、有16位）。如果HAL层只支持8位寄存器地址，后面两个传感器就得绕开HAL直接操作寄存器。所以设计时就要考虑寄存器地址长度可配置。

2.5 SPI封装原则

SPI的封装，核心在于片选管理和数据帧格式。SPI不像I2C有设备地址，它靠片选线区分设备。如果片选管理不好，多个SPI设备同时操作时就会打架。

我的设计思路：

// SPI HAL接口
typedef struct {
    uint8_t mode;       // 0-3
    uint8_t data_size;  // 8或16位
    uint32_t speed_hz;  // 时钟频率
    void (*cs_ctrl)(uint8_t level); // 片选控制回调
} spi_cfg_t;

int32_t hal_spi_transfer(spi_cfg_t *cfg, uint8_t *tx, uint8_t *rx, uint32_t len);

注意cs_ctrl这个回调函数。为什么不用固定函数？因为不同设备的片选引脚可能挂在不同的GPIO上，甚至可能通过扩展芯片控制。用回调，灵活性就出来了。

SPI封装避坑指南：

全双工还是半双工要明确——有些SPI设备只支持半双工，接口要兼容
片选时序要可控——有些设备要求在传输前后保持片选低电平一段时间
DMA传输要加完成回调——不然上层不知道什么时候数据传完了

2.6 四种外设的封装对比

外设	核心抽象对象	关键参数	常见坑点
GPIO	通道号、电平	模式、上下拉、速度	中断中初始化、引脚复用冲突
UART	数据流、超时	波特率、数据位、校验位	阻塞发送、接收溢出
I2C	设备地址、寄存器地址	速率、地址位数	总线死锁、ACK丢失
SPI	片选、数据帧	模式、数据位宽、速率	片选竞争、时序不匹配

2.7 HAL层整体架构

最后，我把这四种外设的HAL层整合成一个整体架构。你想想看，一个完整的HAL层应该长什么样？

这个架构图你看明白了吗？从上到下依次是：应用层 → HAL接口层 → 芯片驱动层 → 硬件层。每一层只跟相邻层打交道，不跨层调用。

核心原则：换芯片不换接口，换板子不改逻辑。这就是HAL层存在的意义。

嗯，这一章的内容就这些。四种外设的封装原则，说到底就是一句话：把变化封装在内部，把稳定暴露给外部。你设计HAL层的时候，多想想"如果换一个芯片，这段代码要改多少？"想明白了，你的HAL层就合格了。