📚 课程目录第2章硬件抽象层（HAL）设计原则

硬件抽象层（HAL）设计原则

说实话，很多嵌入式工程师写驱动，都是直接对着寄存器操作。GPIO 就写 GPIOA->ODR，UART 就翻数据手册找波特率寄存器。这么干在单个芯片上没问题，但一旦要换 MCU，那代码基本就得重写。

我早年吃过这个亏。一个产品从 STM32 换到 GD32，本以为兼容，结果底层寄存器地址全变了。改了一个星期的驱动，还漏了几个 bug。从那以后，我下定决心——不管项目多小，必须上 HAL 层。

HAL 的核心思想：隔离变化

硬件抽象层，说白了就是在芯片寄存器和你写的业务逻辑之间，加一层“翻译官”。

它的核心目标就三个：

屏蔽硬件差异：同样的 API，在 STM32 上能用，换到 NXP 或 GD32 也能用
降低耦合：业务代码不直接操作寄存器，只调用 HAL 接口
提升可移植性：换芯片时，只改 HAL 层实现，上层代码不动

一句话总结：HAL 层存在的意义，就是让你在换 MCU 时，不用重写整个项目。

接口规范：如何定义统一的 MCU 外设接口

接口怎么定？我个人的习惯是：面向功能，不面向寄存器。

什么意思？你想想看，一个 GPIO，业务层关心的是“输出高电平”“读取引脚状态”，而不是“往 ODR 寄存器写 1”。所以接口应该按功能来抽象。

GPIO 接口规范

函数名	功能描述	参数说明
`HAL_GPIO_Init()`	初始化 GPIO 引脚模式	端口、引脚、模式（输入/输出/复用）
`HAL_GPIO_WritePin()`	设置引脚输出电平	端口、引脚、电平值
`HAL_GPIO_ReadPin()`	读取引脚输入电平	端口、引脚
`HAL_GPIO_TogglePin()`	翻转引脚输出电平	端口、引脚

我的经验：GPIO 接口里，一定要把“引脚号”和“端口”分开传参，不要合成一个 uint32_t。否则换芯片时引脚映射会改到你怀疑人生。

UART 接口规范

函数名	功能描述	参数说明
`HAL_UART_Init()`	初始化串口参数	句柄、波特率、数据位、停止位、校验位
`HAL_UART_Transmit()`	发送数据（阻塞）	句柄、数据指针、长度、超时
`HAL_UART_Receive()`	接收数据（阻塞）	句柄、数据指针、长度、超时
`HAL_UART_ITConfig()`	配置中断模式	句柄、中断类型、使能/禁用

避坑指南：我曾经在 UART 接口里把“超时参数”写死了，结果换到低速芯片时，数据老是收不全。后来所有阻塞接口都加了超时参数，问题才解决。

I2C 接口规范

函数名	功能描述	参数说明
`HAL_I2C_Init()`	初始化 I2C 总线	句柄、速率、地址模式
`HAL_I2C_MasterTransmit()`	主机发送数据	句柄、从机地址、数据、长度
`HAL_I2C_MasterReceive()`	主机接收数据	句柄、从机地址、数据、长度
`HAL_I2C_MemWrite()`	写寄存器型设备	句柄、从机地址、寄存器地址、数据

SPI 接口规范

函数名	功能描述	参数说明
`HAL_SPI_Init()`	初始化 SPI 总线	句柄、模式、极性、相位、速率
`HAL_SPI_Transmit()`	发送数据	句柄、数据、长度
`HAL_SPI_Receive()`	接收数据	句柄、数据、长度
`HAL_SPI_TransmitReceive()`	全双工收发	句柄、发送数据、接收数据、长度

HAL 层代码组织与文件结构

代码怎么组织？我建议按外设类型分文件，不要把所有 HAL 代码塞到一个大文件里。否则后期维护时，找个函数都得翻半天。

这是我个人比较推荐的结构：

project/
├── hal/
│   ├── inc/
│   │   ├── hal_gpio.h
│   │   ├── hal_uart.h
│   │   ├── hal_i2c.h
│   │   ├── hal_spi.h
│   │   └── hal_common.h        // 公共类型定义
│   └── src/
│       ├── hal_gpio.c
│       ├── hal_uart.c
│       ├── hal_i2c.c
│       └── hal_spi.c
├── mcu/
│   └── stm32f4/                // 芯片级实现
│       ├── hal_gpio_stm32f4.c
│       ├── hal_uart_stm32f4.c
│       └── ...
└── app/
    └── main.c                  // 业务代码，只调用 hal_xxx.h

关键点：hal/inc 里的头文件是给上层业务代码看的，不暴露任何寄存器操作。mcu/ 目录下的文件才是真正的芯片级实现。

为什么要这么分？我举个例子。假设你从 STM32F4 换到 STM32H7，只需要在 mcu/ 目录下新增一套实现文件，hal/inc 里的接口头文件完全不用动。上层业务代码一行都不用改。

HAL 层核心架构图

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

接口定义示例代码

光说理论不够，咱们看一段实际的 GPIO HAL 接口头文件：

// hal_gpio.h
#ifndef _HAL_GPIO_H_
#define _HAL_GPIO_H_

#include "hal_common.h"

typedef enum {
    HAL_GPIO_MODE_INPUT  = 0,
    HAL_GPIO_MODE_OUTPUT = 1,
    HAL_GPIO_MODE_AF     = 2,  // 复用功能
    HAL_GPIO_MODE_ANALOG = 3
} HalGpioMode_t;

typedef enum {
    HAL_GPIO_PIN_0  = 0x0001,
    HAL_GPIO_PIN_1  = 0x0002,
    // ... 省略中间引脚
    HAL_GPIO_PIN_15 = 0x8000
} HalGpioPin_t;

typedef struct {
    HalGpioPort_t   port;   // GPIOA, GPIOB, ...
    HalGpioPin_t    pin;
    HalGpioMode_t   mode;
    uint8_t         speed;  // 0: low, 1: medium, 2: high
} HalGpioConfig_t;

void HAL_GPIO_Init(HalGpioConfig_t *config);
void HAL_GPIO_WritePin(HalGpioPort_t port, HalGpioPin_t pin, uint8_t state);
uint8_t HAL_GPIO_ReadPin(HalGpioPort_t port, HalGpioPin_t pin);
void HAL_GPIO_TogglePin(HalGpioPort_t port, HalGpioPin_t pin);

#endif

注意：这里用了枚举和结构体，而不是直接传 int。为什么？因为枚举有类型检查，能帮你提前发现传参错误。我见过太多人用 int 传引脚号，结果传了个负数进去，调试半天才发现。

实现层的典型写法

以 STM32F4 为例，看看 HAL_GPIO_WritePin 的实现：

// hal_gpio_stm32f4.c
#include "hal_gpio.h"
#include "stm32f4xx.h"

void HAL_GPIO_WritePin(HalGpioPort_t port, HalGpioPin_t pin, uint8_t state)
{
    GPIO_TypeDef *gpio;
    
    // 将抽象端口号映射到具体寄存器基址
    switch (port) {
        case HAL_GPIO_PORTA: gpio = GPIOA; break;
        case HAL_GPIO_PORTB: gpio = GPIOB; break;
        case HAL_GPIO_PORTC: gpio = GPIOC; break;
        // ... 其他端口
        default: return;
    }
    
    if (state) {
        gpio->BSRR = (uint32_t)pin;  // 置位
    } else {
        gpio->BSRR = (uint32_t)pin << 16;  // 复位
    }
}

你看，上层业务代码调用 HAL_GPIO_WritePin(GPIOA, PIN_0, 1)，完全不知道底层用的是 BSRR 寄存器还是 ODR 寄存器。这就是 HAL 层的价值。

我曾经踩过的坑：一开始我把端口映射写成了 if-else 链，结果代码又长又慢。后来改成查表法，用一个 const 数组把端口号和寄存器地址对应起来，性能提升了不少。建议你也用查表法。

HAL 层设计的几个关键原则

接口要稳定：一旦发布，不要轻易改函数签名。否则所有业务代码都得跟着改。
实现要隔离：不同 MCU 的实现文件要完全独立，不要用 #ifdef 在同一个文件里切分。
错误处理要统一：所有 HAL 函数返回统一的错误码类型，比如 HAL_OK、HAL_ERROR、HAL_TIMEOUT。
不要过度抽象：有些芯片特有的功能（比如 DMA 的硬件触发源），如果强行抽象反而会丢失灵活性。这时候可以加一个 HAL_XXX_IOCTL() 接口，让上层按需配置。

嗯，HAL 层设计就聊到这儿。记住一句话：接口是契约，实现是细节。把契约定好了，换芯片就是换文件的事。