3. GPIO驱动HAL化：从寄存器到回调的完整封装

GPIO 是嵌入式开发里最基础、也最容易被轻视的外设。很多人写 GPIO 驱动就是直接操作寄存器，今天拉高明天拉低，项目小的时候没问题。但一旦换芯片、换平台，你就得从头改一遍——这就是没有 HAL 层的代价。

这一章，我带你从寄存器操作开始，一步步把 GPIO 封装成可移植的 HAL 接口。核心就三件事：寄存器操作抽象、输入输出模式统一、中断回调机制设计。

3.1 寄存器操作封装：别让硬件细节泄露出去

先看一段典型的“裸写”代码：

// 直接操作寄存器（不推荐）
#define GPIOA_BASE      0x40020000
#define GPIOA_MODER     (*(volatile uint32_t *)(GPIOA_BASE + 0x00))
#define GPIOA_ODR       (*(volatile uint32_t *)(GPIOA_BASE + 0x14))

void led_on(void) {
    GPIOA_MODER &= ~(0x3 << (5 * 2));  // 清零模式位
    GPIOA_MODER |= (0x1 << (5 * 2));   // 设为输出
    GPIOA_ODR |= (1 << 5);             // 拉高
}

这段代码能跑，但问题很大。你把芯片的寄存器地址、位域偏移全暴露在业务逻辑里。换一颗 STM32F4 到 GD32，地址可能一样，但模式位定义不同，你就得改所有文件。

我个人的习惯是：先定义寄存器访问结构体，再用宏或内联函数封装。看下面这个例子：

// gpio_hw.h — 硬件抽象层内部使用
typedef struct {
    volatile uint32_t MODER;   // 偏移 0x00
    volatile uint32_t OTYPER;  // 偏移 0x04
    volatile uint32_t OSPEEDR; // 偏移 0x08
    volatile uint32_t PUPDR;   // 偏移 0x0C
    volatile uint32_t IDR;     // 偏移 0x10
    volatile uint32_t ODR;     // 偏移 0x14
    volatile uint32_t BSRR;    // 偏移 0x18
    volatile uint32_t LCKR;    // 偏移 0x1C
    volatile uint32_t AFR[2];  // 偏移 0x20, 0x24
} GPIO_Regs;

#define GPIOA ((GPIO_Regs *)0x40020000)
#define GPIOB ((GPIO_Regs *)0x40020400)

这样写的好处是：寄存器偏移和结构体成员一一对应，编译器自动计算地址。而且你只需要改这个头文件，就能适配不同芯片。

3.2 输入输出模式抽象：统一接口，屏蔽差异

不同芯片的 GPIO 模式定义千差万别。STM32 用 2 位 MODER 控制模式，NXP 的 LPC 系列用一位方向寄存器，TI 的 MSP430 甚至用不同的寄存器组。HAL 层的任务就是把这些差异“抹平”。

我定义了一个枚举，覆盖最常见的 GPIO 模式：

// gpio_hal.h — 公共 HAL 接口
typedef enum {
    GPIO_MODE_INPUT,          // 浮空输入
    GPIO_MODE_OUTPUT_PP,      // 推挽输出
    GPIO_MODE_OUTPUT_OD,      // 开漏输出
    GPIO_MODE_AF_PP,          // 复用推挽
    GPIO_MODE_AF_OD,          // 复用开漏
    GPIO_MODE_ANALOG,         // 模拟模式
    GPIO_MODE_IT_RISING,      // 上升沿中断
    GPIO_MODE_IT_FALLING,     // 下降沿中断
    GPIO_MODE_IT_BOTH         // 双边沿中断
} GPIO_Mode;

然后写一个 GPIO_Init() 函数，内部根据芯片平台做模式映射：

// gpio_hal.c — 平台相关实现
void GPIO_Init(GPIO_Pin *pin, GPIO_Mode mode) {
    GPIO_Regs *regs = (GPIO_Regs *)pin->port;
    uint32_t pos = pin->pin;
    uint32_t moder_val;

    switch (mode) {
        case GPIO_MODE_INPUT:
            moder_val = 0x0;  // 输入模式
            break;
        case GPIO_MODE_OUTPUT_PP:
            moder_val = 0x1;  // 通用输出
            break;
        case GPIO_MODE_AF_PP:
            moder_val = 0x2;  // 复用功能
            break;
        case GPIO_MODE_ANALOG:
            moder_val = 0x3;  // 模拟模式
            break;
        // ... 中断模式单独处理
        default:
            return;
    }

    regs->MODER &= ~(0x3 << (pos * 2));
    regs->MODER |= (moder_val << (pos * 2));
}

3.3 中断回调机制设计：让用户只关心“发生什么”

GPIO 中断是 HAL 层里最容易出坑的地方。我见过太多人把中断处理函数写得又臭又长，还在里面做延时、打印——这是大忌。

我的设计思路是：HAL 层只负责中断的使能、标志位清除和回调分发，具体业务逻辑由用户注册的回调函数处理。

先定义回调函数类型：

// gpio_hal.h
typedef void (*GPIO_IRQCallback)(void *arg);

再设计一个回调注册结构：

typedef struct {
    GPIO_Pin         pin;
    GPIO_IRQCallback callback;
    void            *arg;
    uint8_t          enabled;
} GPIO_IRQHandler;

#define GPIO_IRQ_HANDLER_MAX  16

static GPIO_IRQHandler g_irq_handlers[GPIO_IRQ_HANDLER_MAX];

用户注册回调：

void GPIO_RegisterIRQ(GPIO_Pin *pin, GPIO_IRQCallback cb, void *arg) {
    for (int i = 0; i < GPIO_IRQ_HANDLER_MAX; i++) {
        if (!g_irq_handlers[i].enabled) {
            g_irq_handlers[i].pin      = *pin;
            g_irq_handlers[i].callback = cb;
            g_irq_handlers[i].arg      = arg;
            g_irq_handlers[i].enabled  = 1;
            break;
        }
    }
}

然后在芯片的 GPIO 中断服务函数里统一分发：

// 以 STM32 EXTI 为例
void EXTI0_IRQHandler(void) {
    // 检查中断标志位
    if (EXTI->PR & (1 << 0)) {
        // 清除标志位（必须在回调之前）
        EXTI->PR = (1 << 0);

        // 遍历回调表，找到对应引脚的回调
        for (int i = 0; i < GPIO_IRQ_HANDLER_MAX; i++) {
            if (g_irq_handlers[i].enabled &&
                g_irq_handlers[i].pin.pin == 0) {
                if (g_irq_handlers[i].callback) {
                    g_irq_handlers[i].callback(g_irq_handlers[i].arg);
                }
                break;
            }
        }
    }
}

3.4 整体架构：一张图看懂 GPIO HAL 层

下面这张图展示了 GPIO HAL 层的三层结构：

3.5 完整示例：按键中断控制 LED

把上面所有东西串起来，写一个实际例子。按键按下触发中断，翻转 LED 状态：

// main.c — 用户业务代码
#include "gpio_hal.h"

// 定义引脚
GPIO_Pin led_pin = {.port = GPIOA_BASE, .pin = 5};
GPIO_Pin btn_pin = {.port = GPIOC_BASE, .pin = 13};

// 按键中断回调
void btn_irq_handler(void *arg) {
    // 注意：这里不能做延时！
    GPIO_TogglePin(&led_pin);
}

int main(void) {
    // 初始化 LED 为推挽输出
    GPIO_Init(&led_pin, GPIO_MODE_OUTPUT_PP);
    GPIO_WritePin(&led_pin, 0);

    // 初始化按键为上升沿中断
    GPIO_Init(&btn_pin, GPIO_MODE_IT_RISING);

    // 注册中断回调
    GPIO_RegisterIRQ(&btn_pin, btn_irq_handler, NULL);

    // 使能全局中断（芯片相关）
    __enable_irq();

    while (1) {
        // 主循环做其他事情
        // 按键中断完全由 HAL 层处理
    }
}

3.6 避坑指南：我踩过的 GPIO HAL 坑