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

3. 硬件抽象层（HAL）设计：如何用C语言结构体和函数指针实现硬件无关的接口层

做嵌入式久了，你会发现一个很现实的问题：代码和硬件绑得太死。

换一颗MCU，或者只是换个引脚，整个驱动层就得重写。我早年吃过这个亏——一个项目从STM32F1迁移到F4，底层GPIO操作全改了一遍，上层逻辑也跟着遭殃。那之后我就开始琢磨：能不能在硬件和业务逻辑之间，砌一堵墙？

这堵墙，就是硬件抽象层（HAL）。

3.1 什么是硬件抽象层？

说白了，HAL就是一套统一的接口。它把底层寄存器操作、外设配置、引脚电平这些东西，全部封装成标准函数。上层代码只跟这些函数打交道，不关心底下是STM32还是GD32，甚至是模拟器。

核心目标：上层代码不包含任何硬件相关的宏、寄存器地址、位操作。所有硬件细节都被隔离在HAL内部。

我习惯把HAL比作“硬件驱动程序的接口契约”。你定义好这个契约，然后为每一款芯片写一份实现。上层代码只认契约，不认芯片。

3.2 用结构体+函数指针实现HAL

C语言没有面向对象的class，但我们可以用结构体+函数指针模拟出类似的效果。这是嵌入式领域最经典、最实用的抽象手法。

3.2.1 定义接口结构体

先想清楚：一个典型的硬件外设，需要暴露哪些操作？以GPIO为例：

初始化引脚模式（输入、输出、复用等）
设置引脚电平
读取引脚电平
配置中断

把这些操作声明成函数指针，放进一个结构体里：

/* hal_gpio.h */
#ifndef HAL_GPIO_H
#define HAL_GPIO_H

#include <stdint.h>

/* 引脚模式枚举 */
typedef enum {
    GPIO_MODE_INPUT,
    GPIO_MODE_OUTPUT_PP,    /* 推挽输出 */
    GPIO_MODE_OUTPUT_OD,    /* 开漏输出 */
    GPIO_MODE_AF_PP,        /* 复用推挽 */
    GPIO_MODE_AF_OD         /* 复用开漏 */
} gpio_mode_t;

/* 引脚电平枚举 */
typedef enum {
    GPIO_PIN_RESET = 0,
    GPIO_PIN_SET = 1
} gpio_pin_state_t;

/* 中断触发方式 */
typedef enum {
    GPIO_INT_RISING,
    GPIO_INT_FALLING,
    GPIO_INT_BOTH
} gpio_int_trigger_t;

/* HAL接口结构体 —— 这就是契约 */
typedef struct {
    void     (*init)(uint8_t port, uint8_t pin, gpio_mode_t mode);
    void     (*write)(uint8_t port, uint8_t pin, gpio_pin_state_t state);
    gpio_pin_state_t (*read)(uint8_t port, uint8_t pin);
    void     (*toggle)(uint8_t port, uint8_t pin);
    void     (*enable_interrupt)(uint8_t port, uint8_t pin, gpio_int_trigger_t trigger);
    void     (*disable_interrupt)(uint8_t port, uint8_t pin);
    void     (*clear_interrupt_flag)(uint8_t port, uint8_t pin);
} hal_gpio_t;

/* 全局接口实例，由具体平台初始化时赋值 */
extern const hal_gpio_t* hal_gpio;

#endif /* HAL_GPIO_H */

我的习惯：接口结构体用 const 修饰，防止运行时被意外篡改。具体实现放在只读区（如Flash），既安全又省RAM。

3.2.2 为具体芯片实现接口

假设我们有一款基于STM32F4的平台。在它的驱动文件里，填充这些函数指针：

/* hal_gpio_stm32f4.c */
#include "hal_gpio.h"
#include "stm32f4xx_hal.h"  /* 厂商库 */

static void stm32_init(uint8_t port, uint8_t pin, gpio_mode_t mode) {
    GPIO_InitTypeDef GPIO_InitStruct = {0};
    GPIO_InitStruct.Pin = (1 << pin);
    /* 根据mode参数映射到HAL库的枚举 */
    switch(mode) {
        case GPIO_MODE_OUTPUT_PP:
            GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
            break;
        /* ... 其他模式映射 ... */
        default:
            break;
    }
    GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_HIGH;
    HAL_GPIO_Init((GPIO_TypeDef*)(GPIOA_BASE + port * 0x400), &GPIO_InitStruct);
}

static void stm32_write(uint8_t port, uint8_t pin, gpio_pin_state_t state) {
    HAL_GPIO_WritePin((GPIO_TypeDef*)(GPIOA_BASE + port * 0x400), (1 << pin), state);
}

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

/* 实例化接口，赋值给全局指针 */
const hal_gpio_t hal_gpio_stm32f4 = {
    .init = stm32_init,
    .write = stm32_write,
    .read = stm32_read,
    .toggle = stm32_toggle,
    .enable_interrupt = stm32_enable_interrupt,
    .disable_interrupt = stm32_disable_interrupt,
    .clear_interrupt_flag = stm32_clear_interrupt_flag
};

然后在系统初始化时，把全局指针指向这个实例：

/* main.c 或 board_init.c */
#include "hal_gpio.h"

const hal_gpio_t* hal_gpio = &hal_gpio_stm32f4;

3.2.3 上层代码如何使用

业务逻辑层完全不知道底下是什么芯片。它只调用接口：

/* led_controller.c —— 完全与硬件无关 */
#include "hal_gpio.h"

#define LED_PORT    0   /* PA */
#define LED_PIN     5   /* Pin 5 */

void led_init(void) {
    hal_gpio->init(LED_PORT, LED_PIN, GPIO_MODE_OUTPUT_PP);
    hal_gpio->write(LED_PORT, LED_PIN, GPIO_PIN_RESET);
}

void led_on(void) {
    hal_gpio->write(LED_PORT, LED_PIN, GPIO_PIN_SET);
}

void led_off(void) {
    hal_gpio->write(LED_PORT, LED_PIN, GPIO_PIN_RESET);
}

void led_toggle(void) {
    hal_gpio->toggle(LED_PORT, LED_PIN);
}

你看，led_controller.c 里没有一行寄存器操作，没有 GPIOA->ODR，没有 HAL_GPIO_WritePin。它只依赖 hal_gpio 这个接口指针。

注意：函数指针调用会带来一次间接跳转，性能敏感场景（如GPIO翻转频率超过10MHz）需要评估开销。我通常的做法是：高频路径用宏或内联函数直接操作寄存器，低频路径走HAL接口。但接口定义本身要保持一致。

3.3 接口隔离的层次结构

一个完整的HAL设计，通常分三层。我画了张图帮你理解：

3.4 设计HAL接口的几条铁律

这些年我踩过不少坑，总结出几条经验，分享给你：

原则	说明	反例
参数通用化	接口参数使用抽象枚举，不暴露芯片特有的宏	`void init(GPIO_TypeDef* port, uint16_t pin);`
返回值标准化	统一返回 `int32_t`，0表示成功，负数表示错误码	有的返回 `HAL_StatusTypeDef`，有的返回 `bool`
不依赖全局状态	接口函数尽量可重入，不隐含使用全局变量	内部偷偷用了一个 `static` 数组记录引脚状态
最小化依赖	HAL头文件只包含 `<stdint.h>` 等基础类型	在 `hal_gpio.h` 里 `#include "stm32f4xx_hal.h"`
提供默认实现	对于非关键接口，可以给一个空函数或断言	接口定义了但不实现，链接时报错

避坑指南：我曾经在一个项目里，把 hal_uart.h 的 send() 参数设计成 uint8_t* buffer, uint16_t len。结果换到另一款芯片时，它的UART FIFO深度只有4字节，大包发送必须分包。但接口已经定了，改起来牵一发动全身。后来我学乖了：接口参数要预留扩展空间，比如加一个 uint32_t timeout_ms，或者用结构体传参。

3.5 多平台切换实战

假设你的产品同时支持STM32和GD32。你只需要在板级初始化时，根据宏定义选择不同的实现：

/* board_init.c */
#include "hal_gpio.h"

#ifdef USE_CHIP_STM32F4
    extern const hal_gpio_t hal_gpio_stm32f4;
    const hal_gpio_t* hal_gpio = &hal_gpio_stm32f4;
#elif defined(USE_CHIP_GD32F3)
    extern const hal_gpio_t hal_gpio_gd32f3;
    const hal_gpio_t* hal_gpio = &hal_gpio_gd32f3;
#else
    #error "No chip defined!"
#endif

上层代码一行都不用改。编译时指定宏，链接不同的目标文件即可。这就是接口隔离带来的威力。

3.6 性能与灵活性的权衡

函数指针有开销，这是事实。但大多数场景下，这个开销可以忽略。我一般这样取舍：

控制类外设（GPIO、UART、I2C、SPI）：走HAL接口，开发效率远大于那点性能损失。
数据流类外设（DMA、高速ADC、定时器PWM）：HAL接口只做配置，数据通路直接操作寄存器或使用回调。
极端性能路径（如1MHz以上的GPIO翻转）：提供 inline 函数或宏，但接口定义保持一致。

我的建议：先写出干净的HAL接口，让代码可移植、可测试。等性能瓶颈出现时，再用profiler定位热点，针对性优化。不要为了省几个CPU周期，把整个架构搞成一团乱麻。

3.7 小结

用C语言的结构体和函数指针实现HAL，是嵌入式架构中最基础也最实用的技能。它不依赖任何高级语言特性，纯C就能搞定。你只需要：

定义一套抽象的接口结构体
为每款芯片写一份实现
在初始化时把接口指针指向对应的实现
上层代码只调用接口指针