4、GPIO驱动HAL封装：从寄存器到接口的抽象之路

GPIO，说白了就是芯片最基础的“手脚”。点灯、按键、中断唤醒，哪样都离不开它。但不同芯片的GPIO寄存器布局千差万别，如果应用层直接操作寄存器，换个平台就得重写——这就是HAL层要解决的问题。

我个人习惯把GPIO的HAL封装分成三层：寄存器抽象层、标准接口层、回调机制层。下面我们一层层拆开看。

4.1 GPIO标准接口定义

先定接口。我见过不少团队一上来就写实现，结果接口五花八门，移植时改到崩溃。我的建议是：先定义一套稳定的API，再谈实现。

一套完整的GPIO HAL接口至少需要这些：

4.2 GPIO控制寄存器抽象

寄存器抽象是HAL层的核心。不同芯片的GPIO寄存器布局差异很大，但抽象出来无非这几类：

• 数据寄存器：读/写引脚电平
• 方向寄存器：控制输入/输出
• 上拉/下拉寄存器：配置内部电阻
• 中断控制寄存器：触发方式、标志位
• 复用功能寄存器：选择GPIO或其他外设功能

我曾在某款国产MCU上踩过坑——它的方向寄存器是写1为输入，跟常见的写1为输出完全相反。所以抽象层必须把“寄存器操作”和“逻辑语义”解耦。

看一个典型的寄存器抽象结构体：

typedef struct {
    volatile uint32_t *dat;      // 数据寄存器地址
    volatile uint32_t *dir;      // 方向寄存器地址
    volatile uint32_t *pupd;     // 上拉/下拉寄存器地址
    volatile uint32_t *isr;      // 中断状态寄存器
    volatile uint32_t *icr;      // 中断控制寄存器
    uint8_t  pin_offset;         // 引脚在寄存器中的位偏移
    uint8_t  pin_width;          // 引脚占用的位宽（有些芯片是2位控制一个引脚）
} gpio_reg_ctx_t;

4.3 中断回调注册机制

中断回调是GPIO HAL里最容易出问题的地方。我见过最典型的bug是：中断来了，回调函数里直接操作硬件，结果死锁了。

设计中断回调机制时，我建议遵循这几个原则：

1. 回调函数在中断上下文执行——不能阻塞、不能调用可能导致睡眠的函数
2. 回调函数尽量短——只做标记，具体处理放到任务/工作队列里
3. 支持多个回调注册——同一个引脚可能被多个模块关注
4. 提供注册/注销接口——动态管理，避免硬编码

来看一个中断回调注册的实现骨架：

// 回调函数类型定义
typedef void (*gpio_irq_handler_t)(uint8_t port, uint8_t pin, void *arg);

// 回调节点
typedef struct gpio_irq_node {
    uint8_t port;
    uint8_t pin;
    gpio_irq_handler_t handler;
    void *arg;
    struct gpio_irq_node *next;
} gpio_irq_node_t;

// 注册中断回调
int gpio_set_irq(uint8_t port, uint8_t pin, 
                 gpio_irq_mode_t mode, 
                 gpio_irq_handler_t handler, 
                 void *arg) {
    // 1. 配置中断触发方式（上升沿、下降沿、双边沿、低电平、高电平）
    // 2. 使能中断
    // 3. 将回调节点加入链表
    // 4. 返回成功/失败
}

// 中断服务例程（在底层中断处理中调用）
void gpio_irq_dispatch(uint8_t port, uint8_t pin) {
    gpio_irq_node_t *node = find_node(port, pin);
    if (node && node->handler) {
        node->handler(port, pin, node->arg);
    }
}

4.4 实战：GPIO点灯HAL层实现

理论说完了，咱们动手写一个完整的点灯示例。假设芯片是STM32F4系列，GPIOB的Pin0接了一个LED。

第一步：定义硬件相关的寄存器映射

// stm32f4_gpio_regs.h
#define GPIOB_BASE      0x40020400
#define GPIOB_MODER     (GPIOB_BASE + 0x00)  // 模式寄存器
#define GPIOB_ODR       (GPIOB_BASE + 0x14)  // 输出数据寄存器
#define GPIOB_BSRR      (GPIOB_BASE + 0x18)  // 位设置/复位寄存器

// 初始化GPIOB Pin0的寄存器上下文
gpio_reg_ctx_t led_ctx = {
    .dat  = (uint32_t *)GPIOB_ODR,
    .dir  = (uint32_t *)GPIOB_MODER,
    .pupd = NULL,  // 输出不需要上拉
    .pin_offset = 0,
    .pin_width  = 2  // STM32的MODER是2位控制一个引脚
};

第二步：实现HAL层接口

// gpio_hal.c
int gpio_set_direction(gpio_reg_ctx_t *ctx, gpio_dir_t dir) {
    uint32_t reg_val = *(ctx->dir);
    uint32_t mask = ((1 << ctx->pin_width) - 1) << (ctx->pin_offset * ctx->pin_width);
    
    if (dir == GPIO_DIR_OUTPUT) {
        reg_val = (reg_val & ~mask) | (0x01 << (ctx->pin_offset * ctx->pin_width));
    } else {
        reg_val = (reg_val & ~mask) | (0x00 << (ctx->pin_offset * ctx->pin_width));
    }
    
    *(ctx->dir) = reg_val;
    return 0;
}

int gpio_set_value(gpio_reg_ctx_t *ctx, uint8_t val) {
    if (val) {
        *(ctx->dat) |= (1 << ctx->pin_offset);
    } else {
        *(ctx->dat) &= ~(1 << ctx->pin_offset);
    }
    return 0;
}

第三步：应用层调用

// main.c
void led_init(void) {
    gpio_request(&led_ctx);
    gpio_set_direction(&led_ctx, GPIO_DIR_OUTPUT);
}

void led_toggle(void) {
    static uint8_t state = 0;
    state = !state;
    gpio_set_value(&led_ctx, state);
}

int main(void) {
    led_init();
    while (1) {
        led_toggle();
        delay_ms(500);  // 500ms闪烁
    }
}

4.5 GPIO HAL层整体架构

下面这张图展示了GPIO HAL层的完整架构，从应用层到硬件寄存器的调用链路：

从这张图可以看得很清楚：应用层只跟HAL标准接口打交道，不关心底层寄存器怎么操作。移植到新平台时，只需要重写寄存器抽象层和硬件驱动层，接口层和应用层代码完全不用动。