3、硬件抽象层（HAL）设计：HAL的作用与分层、HAL接口定义规范、典型HAL实现（GPIO、UART、I2C、SPI）

做嵌入式开发久了，你会发现一个规律：代码写到最后，拼的不是算法多炫，而是移植起来有多省心。我见过太多项目，前期跑得飞快，一换芯片平台，整个软件栈几乎要重写。为什么？因为硬件操作和业务逻辑死死地耦合在一起。

硬件抽象层（HAL），就是用来解决这个问题的。说白了，它是在芯片寄存器和你写的应用代码之间，加了一层“翻译官”。

3.1 HAL的作用与分层

HAL的核心价值，我总结为三点：

• 隔离变化：芯片厂商的寄存器定义千奇百怪，HAL把这些差异挡在底层。
• 统一接口：不管底层是STM32还是GD32，上层调用的函数名、参数结构体都一样。
• 方便测试：你可以写一个模拟的HAL层，在PC上跑单元测试，不用每次都烧录硬件。

我个人习惯把HAL分成两层：

层级	名称	职责	依赖
LL层	底层硬件适配	直接操作寄存器，处理时钟、中断、DMA	芯片手册、CMSIS
HAL层	硬件抽象接口	提供结构体封装、超时机制、回调注册	LL层

LL层追求极致性能，HAL层追求易用性。你想想看，如果每次点个灯都要查一遍寄存器地址，那项目还做不做了？

我曾经在一个项目中，因为HAL层设计得太薄，导致换MCU时，应用层代码改了将近一半。后来我痛定思痛，把HAL层加厚，把外设的初始化、配置、状态查询全部封装进去。从那以后，换平台就像换衣服一样简单。

3.2 HAL接口定义规范

接口定义是HAL设计的灵魂。我见过最糟糕的HAL，函数名千奇百怪，参数顺序随心所欲。这样的HAL，还不如不用。

我推荐一套经过实战检验的命名规范：

• 模块前缀：所有函数以 HAL_ 开头，后面跟外设名，如 HAL_GPIO_、HAL_UART_。
• 动词统一：Init、DeInit、Read、Write、Control、Callback。
• 句柄传递：所有操作都通过句柄结构体，不依赖全局变量。

举个例子，GPIO的接口定义：

// 句柄结构体
typedef struct {
    uint32_t Pin;          // 引脚号
    uint32_t Mode;         // 输入/输出/复用
    uint32_t Pull;         // 上拉/下拉/浮空
    uint32_t Speed;        // 输出速度
} HAL_GPIO_InitTypeDef;

// 接口函数
HAL_StatusTypeDef HAL_GPIO_Init(GPIO_TypeDef *GPIOx, HAL_GPIO_InitTypeDef *Init);
HAL_StatusTypeDef HAL_GPIO_DeInit(GPIO_TypeDef *GPIOx, uint32_t Pin);
GPIO_PinState HAL_GPIO_ReadPin(GPIO_TypeDef *GPIOx, uint32_t Pin);
void HAL_GPIO_WritePin(GPIO_TypeDef *GPIOx, uint32_t Pin, GPIO_PinState PinState);
void HAL_GPIO_TogglePin(GPIO_TypeDef *GPIOx, uint32_t Pin);

嗯，这里要注意：句柄结构体里不要放平台相关的寄存器地址。我曾经看到有人把 GPIOx->ODR 的地址直接写进结构体，结果换芯片后，地址全变了，整个结构体都得重写。正确的做法是，句柄里只放逻辑参数，底层映射由LL层完成。

3.3 典型HAL实现：GPIO

GPIO是HAL层最简单的例子，但也是最能体现设计功力的地方。我们来看看初始化函数的实现：

HAL_StatusTypeDef HAL_GPIO_Init(GPIO_TypeDef *GPIOx, HAL_GPIO_InitTypeDef *Init) {
    uint32_t position = 0x00;
    uint32_t iocurrent = 0x00;
    uint32_t temp = 0x00;

    if (Init == NULL) return HAL_ERROR;

    // 遍历引脚位，逐位配置
    for (position = 0; position < 16; position++) {
        iocurrent = (uint32_t)1 << position;
        if ((Init->Pin & iocurrent) == iocurrent) {
            // 配置模式寄存器
            temp = GPIOx->MODER;
            temp &= ~(GPIO_MODER_MODER0 << (position * 2));
            temp |= (Init->Mode << (position * 2));
            GPIOx->MODER = temp;

            // 配置上下拉寄存器
            temp = GPIOx->PUPDR;
            temp &= ~(GPIO_PUPDR_PUPDR0 << (position * 2));
            temp |= (Init->Pull << (position * 2));
            GPIOx->PUPDR = temp;

            // 配置速度寄存器
            temp = GPIOx->OSPEEDR;
            temp &= ~(GPIO_OSPEEDR_OSPEED0 << (position * 2));
            temp |= (Init->Speed << (position * 2));
            GPIOx->OSPEEDR = temp;
        }
    }
    return HAL_OK;
}

这段代码看起来简单，但有几个坑：

• 一定要做参数校验，NULL指针检查不能省。
• 位操作要小心，先清空再赋值，否则会污染其他引脚配置。
• 循环遍历引脚时，用移位操作，不要用硬编码的魔数。

3.4 典型HAL实现：UART

UART比GPIO复杂一些，因为它涉及中断和环形缓冲区。我习惯把UART的HAL设计成“中断驱动+环形缓冲”模式：

typedef struct {
    USART_TypeDef *Instance;     // 外设基地址
    uint32_t BaudRate;           // 波特率
    uint32_t WordLength;         // 数据位
    uint32_t StopBits;           // 停止位
    uint32_t Parity;             // 校验位
    uint8_t *pRxBuffPtr;         // 接收缓冲区指针
    uint16_t RxXferSize;         // 接收数据长度
    uint16_t RxXferCount;        // 已接收计数
    uint8_t *pTxBuffPtr;         // 发送缓冲区指针
    uint16_t TxXferSize;         // 发送数据长度
    uint16_t TxXferCount;        // 已发送计数
    void (*RxCpltCallback)(struct __UART_HandleTypeDef *huart);  // 接收完成回调
    void (*TxCpltCallback)(struct __UART_HandleTypeDef *huart);  // 发送完成回调
} UART_HandleTypeDef;

中断服务函数里，只做两件事：把数据塞进环形缓冲区，或者从环形缓冲区取出数据。业务逻辑全部放在回调函数里。这样，上层应用完全不用关心中断优先级、寄存器状态这些细节。

你想想看，如果每个UART接收都要自己写中断处理，那项目里光中断函数就够你喝一壶的。

3.5 典型HAL实现：I2C与SPI

I2C和SPI的HAL设计，核心在于“状态机”。因为这两个协议都是主从模式，通信过程中需要管理总线状态。

I2C的状态机通常包含：

• IDLE：空闲状态
• START：发送起始信号
• SEND_ADDR：发送从机地址
• SEND_DATA：发送数据
• RECV_DATA：接收数据
• STOP：发送停止信号
• ERROR：错误处理

SPI相对简单一些，但要注意时钟极性和相位的配置。我见过一个案例，因为SPI的CPOL和CPHA配置反了，导致整个显示驱动花了两天排查。

下面这张图，展示了HAL层在整个嵌入式软件架构中的位置：

从这张图可以看得很清楚：HAL层是承上启下的关键。它把底层的寄存器操作封装成统一的接口，让上层的中间件和应用层完全不用关心硬件细节。

最后，我想说一句：HAL设计没有银弹。不同的项目、不同的团队、不同的芯片，HAL的粒度都会不一样。但核心思想是不变的——隔离变化，统一接口。只要把握住这个原则，你的代码就能经得起时间的考验。