3. GPIO驱动HAL封装：从寄存器到中断回调的完整实践

GPIO 驱动，说白了就是嵌入式开发里最基础也最绕不开的一环。我做了这么多年驱动，几乎每个项目都会跟 GPIO 打交道。但很多人写 GPIO 驱动就是直接操作寄存器，换个平台就得重写——这哪行？HAL 封装的目的，就是让你写一次，到处都能用。

这一章，我们就把 GPIO 的 HAL 封装拆开揉碎。从寄存器映射开始，到 Init/Write/Read/Toggle 四个核心接口，再到中断回调机制。嗯，每一步我都会结合项目里踩过的坑来讲。

3.1 GPIO寄存器映射：你得知道硬件长什么样

写驱动之前，第一件事就是搞清楚寄存器布局。我见过太多人上来就写代码，结果连 GPIO 的基地址都搞错了。

以 STM32F4 为例，GPIO 外设的寄存器组通常是这样组织的：

在 C 语言里，我们通常用结构体来映射这些寄存器：

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 AFRL;     // 0x20
    volatile uint32_t AFRH;     // 0x24
} GPIO_RegDef_t;

然后定义基地址指针：

#define GPIOA_BASE      0x40020000
#define GPIOB_BASE      0x40020400
#define GPIOC_BASE      0x40020800

#define GPIOA           ((GPIO_RegDef_t *)GPIOA_BASE)
#define GPIOB           ((GPIO_RegDef_t *)GPIOB_BASE)
#define GPIOC           ((GPIO_RegDef_t *)GPIOC_BASE)

你看，这样写完之后，操作寄存器就变成了 GPIOA->ODR |= (1 << 5); 这种直观的方式。但注意，这只是底层映射，还不是 HAL 封装。

3.2 HAL_GPIO_Init：配置的学问

Init 函数是 GPIO 驱动里最复杂的。为什么？因为你要把上面那一堆寄存器的配置逻辑，封装成一个统一的接口。

我设计的 HAL_GPIO_Init 原型是这样的：

typedef struct {
    uint16_t Pin;           // 引脚号 (GPIO_PIN_0 ~ GPIO_PIN_15)
    uint8_t Mode;           // 模式: INPUT, OUTPUT, AF, ANALOG
    uint8_t Pull;           // 上下拉: NOPULL, PULLUP, PULLDOWN
    uint8_t Speed;          // 速度: LOW, MEDIUM, HIGH, VERY_HIGH
    uint8_t OutputType;     // 输出类型: PUSH_PULL, OPEN_DRAIN
    uint8_t Alternate;      // 复用功能编号 (0~15)
} GPIO_InitTypeDef;

void HAL_GPIO_Init(GPIO_RegDef_t *GPIOx, GPIO_InitTypeDef *GPIO_Init);

实现的时候，核心逻辑就是根据配置参数，逐位设置对应的寄存器。我挑几个关键点说说：

• MODER 寄存器：每两位控制一个引脚。所以操作时要先清对应位，再写新值。千万别直接赋值，否则会影响到其他引脚。
• PUPDR 寄存器：跟 MODER 类似，也是每两位控制一个引脚。但要注意，模拟模式下上下拉必须关闭。
• AFRL/AFRH：引脚 0~7 用 AFRL，8~15 用 AFRH。每四位控制一个引脚的复用功能编号。

Init 函数的实现骨架：

void HAL_GPIO_Init(GPIO_RegDef_t *GPIOx, GPIO_InitTypeDef *GPIO_Init) {
    uint32_t position = 0;
    uint32_t temp = 0;

    // 1. 配置 MODER
    temp = GPIOx->MODER;
    temp &= ~(0x03 << (GPIO_Init->Pin * 2));
    temp |= (GPIO_Init->Mode << (GPIO_Init->Pin * 2));
    GPIOx->MODER = temp;

    // 2. 配置 PUPDR
    temp = GPIOx->PUPDR;
    temp &= ~(0x03 << (GPIO_Init->Pin * 2));
    temp |= (GPIO_Init->Pull << (GPIO_Init->Pin * 2));
    GPIOx->PUPDR = temp;

    // 3. 如果是输出模式，配置 OTYPER 和 OSPEEDR
    if (GPIO_Init->Mode == GPIO_MODE_OUTPUT) {
        // ... 类似操作
    }

    // 4. 如果是复用模式，配置 AFRL 或 AFRH
    if (GPIO_Init->Mode == GPIO_MODE_AF) {
        // ... 根据引脚号选择 AFRL 或 AFRH
    }
}

3.3 Write/Read/Toggle：三个最常用的接口

这三个接口相对简单，但细节决定成败。

HAL_GPIO_Write：

void HAL_GPIO_Write(GPIO_RegDef_t *GPIOx, uint16_t Pin, uint8_t PinState) {
    if (PinState == GPIO_PIN_SET) {
        GPIOx->BSRR = Pin;  // 用 BSRR 设置位，原子操作
    } else {
        GPIOx->BSRR = (uint32_t)Pin << 16;  // 用 BSRR 复位位
    }
}

为什么用 BSRR 而不是直接写 ODR？因为 BSRR 是原子操作。你想想看，如果直接操作 ODR，可能会被中断打断，导致读写不一致。BSRR 写 1 到低 16 位就是置位，写 1 到高 16 位就是复位，硬件保证一次性完成。

HAL_GPIO_Read：

uint8_t HAL_GPIO_Read(GPIO_RegDef_t *GPIOx, uint16_t Pin) {
    return (uint8_t)((GPIOx->IDR & Pin) ? GPIO_PIN_SET : GPIO_PIN_RESET);
}

读引脚状态一定要用 IDR（输入数据寄存器），而不是 ODR。ODR 是你写进去的值，IDR 才是引脚上实际的电平。如果引脚被外部电路拉低了，ODR 还是 1，但 IDR 已经是 0 了。

HAL_GPIO_Toggle：

void HAL_GPIO_Toggle(GPIO_RegDef_t *GPIOx, uint16_t Pin) {
    GPIOx->ODR ^= Pin;
}

Toggle 用异或操作，简单高效。但要注意，如果多个线程或中断同时操作同一个引脚，可能会有竞态。不过大多数场景下，GPIO 操作是单线程的，问题不大。

3.4 中断回调机制：让 GPIO 会"说话"

GPIO 中断是嵌入式系统里最常用的异步通知方式。按键检测、边沿触发、唤醒事件，都离不开它。

HAL 层的中断封装，核心思路是：把硬件中断向量和用户回调函数解耦。

我的做法是这样的：

1. 在 HAL 层维护一个回调函数指针数组，每个外部中断线对应一个。
2. 在中断服务函数（ISR）里，判断中断标志位，然后调用对应的回调函数。
3. 用户只需要注册自己的回调函数，不用关心底层中断处理细节。

数据结构定义：

typedef void (*GPIO_IRQCallback_t)(uint16_t Pin);

typedef struct {
    GPIO_IRQCallback_t Callback[16];  // 16条外部中断线
    uint8_t Initialized;
} GPIO_IRQHandler_t;

static GPIO_IRQHandler_t hgpio_irq = {0};

注册回调的接口：

void HAL_GPIO_RegisterIRQCallback(uint16_t Pin, GPIO_IRQCallback_t callback) {
    if (Pin & (GPIO_PIN_0 | GPIO_PIN_1 | ...)) {
        // 计算中断线编号
        uint8_t line = 0;
        while (Pin >>= 1) line++;
        hgpio_irq.Callback[line] = callback;
    }
}

中断处理函数（以 EXTI0_IRQHandler 为例）：

void EXTI0_IRQHandler(void) {
    // 检查中断标志位
    if (EXTI->PR & EXTI_PR_PR0) {
        // 清除中断标志位
        EXTI->PR = EXTI_PR_PR0;

        // 调用用户回调
        if (hgpio_irq.Callback[0] != NULL) {
            hgpio_irq.Callback[0](GPIO_PIN_0);
        }
    }
}

用户代码里怎么用？很简单：

void MyButtonCallback(uint16_t Pin) {
    // 按键按下后的处理逻辑
    HAL_GPIO_Toggle(GPIOB, GPIO_PIN_5);
}

int main(void) {
    HAL_GPIO_Init(GPIOA, &button_config);
    HAL_GPIO_RegisterIRQCallback(GPIO_PIN_0, MyButtonCallback);
    // 使能 NVIC 中断...
    while(1) {
        // 主循环做其他事
    }
}

你看，用户完全不需要知道 EXTI 寄存器怎么配，NVIC 优先级怎么设。这些都在 HAL_GPIO_Init 里封装好了。

3.5 整体架构：一张图看懂

下面这张图，把 GPIO HAL 封装的整体结构画出来了。从应用层到底层硬件，每一层各司其职。

从这张图可以看得很清楚：用户代码只跟 HAL API 层打交道。至于底层是 STM32 还是 GD32，甚至是国产某款 MCU，只要 HAL 接口不变，应用代码一行都不用改。这就是硬件抽象层的价值。

3.6 避坑指南：我这些年踩过的 GPIO 坑

最后，分享几个实战中容易出问题的地方：

• GPIO 初始化顺序：一定要先使能外设时钟，再配置寄存器。否则写寄存器等于白写。我见过有人把时钟使能放在 GPIO_Init 之后，结果引脚死活没反应。
• 中断优先级分组：整个系统只能用一次 NVIC_PriorityGroupConfig。如果 HAL 库和用户代码各调一次，中断行为就不可预测了。
• 回调函数不能阻塞：中断回调里不要做延时、打印、复杂计算。这些事放到任务队列或者主循环里做。否则会影响其他中断的响应。
• 引脚复用冲突：同一个引脚可能被多个外设共用。初始化之前，检查一下数据手册，确认没有冲突。