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

4. 硬件抽象层（HAL）设计：让软件与硬件“解耦”的艺术

说到硬件抽象层，我脑子里第一个蹦出来的画面，是十年前一个让我通宵三天的项目。那会儿我们给一家工业客户做电机控制板，芯片从 STM32F1 换到 GD32，就改了个寄存器地址，结果整个应用层代码崩了三分之一。从那以后，我彻底明白了——没有 HAL 的嵌入式系统，就像没打地基的房子，换个砖都得塌。

说白了，HAL 就是软件和硬件之间的一道“防火墙”。它把底层寄存器操作、外设时序、中断向量这些东西，封装成一组稳定、通用的接口。上层应用只管调用，不用管底下是 Cortex-M0 还是 RISC-V。

4.1 HAL 的作用与定位

HAL 在嵌入式软件架构里，处于中间层的位置。看下面这张图就清楚了：

你看，HAL 夹在应用和硬件之间。它不干活，但它让干活的人（应用层）不用关心底下是谁在干活。我个人习惯把 HAL 比作“硬件驱动程序的统一门面”——不管底层驱动多乱，HAL 接口必须干净。

HAL 的三大定位原则：

隔离性：应用层代码不能直接包含任何寄存器地址、位定义或硬件头文件。
可替换性：换 MCU 时，只替换 HAL 实现文件，应用层零修改。
可测试性：HAL 接口可以轻松打桩，让应用层在 PC 上做单元测试。

4.2 HAL 接口定义

接口定义是 HAL 设计里最考验功力的一环。我见过太多人把 HAL 接口写成“寄存器操作大全”——一个 GPIO 初始化函数传 8 个参数，谁看了都头大。

好的 HAL 接口，应该遵循“最小完备”原则：参数够用就行，不多不少。下面是我常用的 GPIO 模块 HAL 接口示例：

/* hal_gpio.h - GPIO 硬件抽象层接口 */
#ifndef HAL_GPIO_H
#define HAL_GPIO_H

#include <stdint.h>
#include <stdbool.h>

/* 枚举定义，不暴露任何硬件寄存器值 */
typedef enum {
    HAL_GPIO_PORT_A,
    HAL_GPIO_PORT_B,
    HAL_GPIO_PORT_C,
    HAL_GPIO_PORT_D,
    HAL_GPIO_PORT_MAX
} hal_gpio_port_t;

typedef enum {
    HAL_GPIO_PIN_0,
    HAL_GPIO_PIN_1,
    /* ... 省略中间引脚 ... */
    HAL_GPIO_PIN_15,
    HAL_GPIO_PIN_MAX
} hal_gpio_pin_t;

typedef enum {
    HAL_GPIO_MODE_INPUT,
    HAL_GPIO_MODE_OUTPUT_PP,    /* 推挽输出 */
    HAL_GPIO_MODE_OUTPUT_OD,    /* 开漏输出 */
    HAL_GPIO_MODE_AF_PP,        /* 复用推挽 */
    HAL_GPIO_MODE_AF_OD         /* 复用开漏 */
} hal_gpio_mode_t;

typedef enum {
    HAL_GPIO_PULL_NONE,
    HAL_GPIO_PULL_UP,
    HAL_GPIO_PULL_DOWN
} hal_gpio_pull_t;

/* 初始化结构体 - 只暴露必要参数 */
typedef struct {
    hal_gpio_port_t port;
    hal_gpio_pin_t  pin;
    hal_gpio_mode_t mode;
    hal_gpio_pull_t pull;
    bool            init_level;  /* 仅输出模式有效 */
} hal_gpio_config_t;

/* 接口函数 - 稳定、简洁、自文档化 */
void     hal_gpio_init(const hal_gpio_config_t *config);
void     hal_gpio_set(hal_gpio_port_t port, hal_gpio_pin_t pin);
void     hal_gpio_reset(hal_gpio_port_t port, hal_gpio_pin_t pin);
void     hal_gpio_toggle(hal_gpio_port_t port, hal_gpio_pin_t pin);
bool     hal_gpio_read(hal_gpio_port_t port, hal_gpio_pin_t pin);
void     hal_gpio_deinit(hal_gpio_port_t port, hal_gpio_pin_t pin);

#endif /* HAL_GPIO_H */

接口定义避坑指南：

参数类型用枚举，别用 int 或宏定义。枚举有类型检查，宏没有。
初始化用结构体传参，别写 6 个参数的函数。结构体可扩展，参数列表不行。
返回值统一用 bool 或错误码枚举，别混用 0/1 和负值。
函数命名加 hal_ 前缀，一看就知道是抽象层接口。

我曾经在一个项目里见过这样的接口：void GPIO_Init(uint32_t port, uint32_t pin, uint32_t mode, uint32_t speed, uint32_t otype, uint32_t pull);——6 个 uint32_t 参数，传错顺序编译器都不报错。后来重构时改成结构体传参，bug 率直接降了 70%。

4.3 HAL 实现策略

接口定义好了，怎么实现？这里有两个流派，我分别说说：

实现策略	核心思路	优点	缺点	适用场景
直接寄存器操作	在 HAL 实现文件中直接读写寄存器	性能高、无额外开销、代码体积小	移植需重写整个 .c 文件、可读性差	资源极度受限的 MCU（如 8 位机）
LL 库封装	基于厂商 LL 库实现 HAL 接口	移植快、利用厂商优化、可读性好	依赖厂商库版本、调试时需查两层	主流 ARM Cortex-M 系列
回调 + 注册机制	HAL 接口通过函数指针调用底层驱动	运行时切换硬件、支持模拟器	有函数指针调用开销、调试复杂	需要硬件在环（HIL）测试的场景

我个人最常用的是第二种——基于 LL 库封装。原因很简单：厂商的 LL 库已经做了寄存器映射和时序优化，我只需要包一层接口，工作量最小。但要注意，千万别把 HAL 实现写成“LL 库的二次转发”，那样就失去了抽象的意义。

下面是一个基于 LL 库的 GPIO HAL 实现片段：

/* hal_gpio.c - 基于 STM32 LL 库的实现 */
#include "hal_gpio.h"
#include "stm32g4xx_ll_gpio.h"

/* 端口映射表 - 移植时只需改这里 */
static GPIO_TypeDef *port_map[HAL_GPIO_PORT_MAX] = {
    [HAL_GPIO_PORT_A] = GPIOA,
    [HAL_GPIO_PORT_B] = GPIOB,
    [HAL_GPIO_PORT_C] = GPIOC,
    [HAL_GPIO_PORT_D] = GPIOD
};

void hal_gpio_init(const hal_gpio_config_t *config)
{
    GPIO_TypeDef *gpio = port_map[config->port];
    uint32_t pin_mask = 1UL << config->pin;

    /* 使能时钟 - 不同 MCU 时钟使能方式不同，但封装在这里 */
    if (config->port == HAL_GPIO_PORT_A) {
        LL_AHB2_GRP1_EnableClock(LL_AHB2_GRP1_PERIPH_GPIOA);
    }
    /* ... 其他端口类似 ... */

    /* 配置模式 */
    LL_GPIO_SetPinMode(gpio, pin_mask, (uint32_t)config->mode);
    LL_GPIO_SetPinPull(gpio, pin_mask, (uint32_t)config->pull);

    /* 设置初始电平 */
    if (config->mode == HAL_GPIO_MODE_OUTPUT_PP ||
        config->mode == HAL_GPIO_MODE_OUTPUT_OD) {
        if (config->init_level) {
            LL_GPIO_SetOutputPin(gpio, pin_mask);
        } else {
            LL_GPIO_ResetOutputPin(gpio, pin_mask);
        }
    }
}

void hal_gpio_set(hal_gpio_port_t port, hal_gpio_pin_t pin)
{
    LL_GPIO_SetOutputPin(port_map[port], 1UL << pin);
}

/* ... 其他函数实现类似 ... */

实现时的三个“绝对不要”：

绝对不要在 HAL 实现里做延时等待——延时是应用层的事，HAL 只负责配置和读写。
绝对不要在 HAL 接口里传裸指针——比如 void hal_uart_send(uint8_t *data, uint32_t len)，应用层可能传空指针。要么加长度校验，要么用 const 限定。
绝对不要在一个 HAL 函数里做多件事——比如 hal_gpio_init_and_set()，测试时你都不知道是初始化失败还是设置失败。

4.4 HAL 测试方法

HAL 层怎么测？这是个好问题。直接烧到板子上点灯，那不叫测试，叫“祈祷式开发”。

我的做法是：为 HAL 接口编写桩模块（Stub），在 PC 上做单元测试。这样不用硬件就能验证应用层逻辑。

具体来说，分三步走：

定义桩接口：写一个 hal_gpio_stub.c，实现所有 HAL 接口，但内部只操作内存变量。
记录调用历史：每个桩函数记录被调用的次数、参数值，方便断言验证。
模拟硬件行为：比如 hal_gpio_read() 可以返回预设值，模拟按键按下或传感器输出。

看一个 GPIO 桩模块的例子：

/* hal_gpio_stub.c - 用于单元测试的桩模块 */
#include "hal_gpio.h"
#include <string.h>
#include <assert.h>

/* 模拟的 GPIO 状态 */
static bool stub_pin_state[HAL_GPIO_PORT_MAX][HAL_GPIO_PIN_MAX];
static int  stub_init_count = 0;
static hal_gpio_config_t stub_last_config;

void hal_gpio_init(const hal_gpio_config_t *config)
{
    assert(config != NULL);
    assert(config->port < HAL_GPIO_PORT_MAX);
    assert(config->pin  < HAL_GPIO_PIN_MAX);

    stub_init_count++;
    memcpy(&stub_last_config, config, sizeof(hal_gpio_config_t));

    /* 模拟初始化后的默认电平 */
    stub_pin_state[config->port][config->pin] = config->init_level;
}

void hal_gpio_set(hal_gpio_port_t port, hal_gpio_pin_t pin)
{
    assert(port < HAL_GPIO_PORT_MAX);
    assert(pin  < HAL_GPIO_PIN_MAX);
    stub_pin_state[port][pin] = true;
}

bool hal_gpio_read(hal_gpio_port_t port, hal_gpio_pin_t pin)
{
    assert(port < HAL_GPIO_PORT_MAX);
    assert(pin  < HAL_GPIO_PIN_MAX);
    return stub_pin_state[port][pin];
}

/* 测试辅助函数 - 用于设置模拟输入值 */
void hal_gpio_stub_set_input(hal_gpio_port_t port, hal_gpio_pin_t pin, bool value)
{
    stub_pin_state[port][pin] = value;
}

/* 测试辅助函数 - 获取初始化次数 */
int hal_gpio_stub_get_init_count(void)
{
    return stub_init_count;
}

有了桩模块，应用层的单元测试就可以这样写：

/* test_led_controller.c - 使用 HAL 桩的单元测试 */
#include "unity.h"
#include "led_controller.h"  /* 应用层模块 */
#include "hal_gpio.h"

void setUp(void)
{
    /* 每个测试用例前重置桩状态 */
    hal_gpio_stub_reset();  /* 需要额外实现的复位函数 */
}

void test_led_turn_on_should_set_gpio_pin(void)
{
    /* 准备 */
    led_controller_init();

    /* 执行 */
    led_controller_turn_on(LED_ID_STATUS);

    /* 验证 - 检查 HAL 桩是否被正确调用 */
    TEST_ASSERT_TRUE(hal_gpio_read(HAL_GPIO_PORT_B, HAL_GPIO_PIN_5));
}

void test_led_init_should_call_hal_gpio_init(void)
{
    /* 执行 */
    led_controller_init();

    /* 验证 */
    TEST_ASSERT_EQUAL_INT(1, hal_gpio_stub_get_init_count());
}

HAL 测试的“黄金法则”：

桩模块必须与真实 HAL 接口完全一致（同一个头文件）。
桩模块要能记录调用历史，方便断言“某函数被调用了 N 次”。
桩模块要能模拟硬件故障（如返回错误码），测试应用层的异常处理。
真实 HAL 的集成测试，建议用开发板 + 自动化脚本跑，别用手点。

嗯，说到测试，我想起一个教训。有次我偷懒没写桩模块，直接在硬件上调试。结果应用层有个 bug，导致 GPIO 初始化顺序错了，查了两天才发现是 HAL 调用参数传反了。从那以后，我每个 HAL 接口都配桩，再也没犯过这种低级错误。

总结一下：HAL 设计的核心就三句话——接口要稳、实现要藏、测试要早。接口稳了，换芯片不慌；实现藏好了，代码可读性高；测试跟上了，半夜不用被电话叫醒去改 bug。