3. GPIO驱动HAL抽象：标准GPIO接口定义与跨MCU实现

GPIO，说白了就是芯片的「手脚」——用来输出高低电平，或者读取外部信号。但不同MCU的GPIO寄存器、中断配置、上下拉方式千差万别。我早年做项目时，光移植GPIO驱动就折腾了两周，后来痛定思痛，才总结出这套抽象方法。

今天我们就来聊聊：如何设计一套通用的GPIO-HAL接口，让它能在STM32、NXP、GD32、ESP32上无缝跑起来。

3.1 标准GPIO接口设计：四件套

我习惯把GPIO抽象成四个基本操作。你想想看，不管多复杂的MCU，最终都逃不过这四件事：

接口函数	功能	参数说明
gpio_config()	配置引脚模式（输入/输出/复用/模拟）	引脚号、模式、上下拉、速度
gpio_write()	设置引脚输出电平	引脚号、电平值（0/1）
gpio_read()	读取引脚输入电平	引脚号，返回0或1
gpio_irq_register()	注册中断回调	引脚号、触发边沿、回调函数

嗯，这里要注意：中断回调函数必须用函数指针，不能硬编码。我曾经见过有人把中断处理写死在驱动里，换一个板子就得改底层代码——这完全违背了HAL的初衷。

3.2 数据结构设计：用结构体封装引脚信息

每个GPIO引脚，在HAL层应该用一个结构体来描述。我推荐这样设计：

/* gpio_hal.h */
typedef struct {
    uint8_t  port;      /* GPIO端口号，如0=A, 1=B */
    uint8_t  pin;       /* 引脚号，0~15 */
    uint8_t  mode;      /* 输入/输出/复用/模拟 */
    uint8_t  pull;      /* 上下拉：NONE/UP/DOWN */
    uint8_t  speed;     /* 输出速度：LOW/MEDIUM/HIGH */
    uint8_t  alt_func;  /* 复用功能编号 */
} gpio_pin_t;

/* 模式枚举 */
typedef enum {
    GPIO_MODE_INPUT  = 0,
    GPIO_MODE_OUTPUT = 1,
    GPIO_MODE_AF     = 2,  /* 复用功能 */
    GPIO_MODE_ANALOG = 3
} gpio_mode_t;

/* 中断配置 */
typedef struct {
    gpio_pin_t pin;
    uint8_t    trigger;  /* RISING/FALLING/BOTH */
    void      (*callback)(void* arg);
    void      *arg;
} gpio_irq_cfg_t;

这个结构体，说白了就是「引脚身份证」。上层应用只需要填充这个结构体，然后传给 gpio_config()，底层驱动自己去解析寄存器。

3.3 跨MCU实现：以STM32和ESP32为例

光说理论没意思，咱们直接看代码。我拿两个最典型的MCU来对比：STM32F4（标准库）和 ESP32（ESP-IDF）。

3.3.1 STM32实现

/* gpio_hal_stm32.c */
#include "gpio_hal.h"

static GPIO_TypeDef* port_map[] = {
    [0] = GPIOA, [1] = GPIOB, [2] = GPIOC
};

void gpio_config(gpio_pin_t *pin) {
    GPIO_TypeDef *gpio = port_map[pin->port];
    uint16_t gpio_pin = (1 << pin->pin);

    /* 开启时钟 */
    RCC_AHB1PeriphClockCmd(1 << (pin->port + 0), ENABLE);

    /* 配置模式 */
    GPIO_InitTypeDef init = {0};
    init.GPIO_Pin   = gpio_pin;
    init.GPIO_Mode  = (GPIOMode_TypeDef)pin->mode;
    init.GPIO_PuPd  = (GPIOPuPd_TypeDef)pin->pull;
    init.GPIO_Speed = (GPIOSpeed_TypeDef)pin->speed;
    GPIO_Init(gpio, &init);
}

void gpio_write(gpio_pin_t *pin, uint8_t level) {
    GPIO_WriteBit(port_map[pin->port], 1 << pin->pin, 
                  level ? Bit_SET : Bit_RESET);
}

uint8_t gpio_read(gpio_pin_t *pin) {
    return GPIO_ReadInputDataBit(port_map[pin->port], 
                                 1 << pin->pin);
}

3.3.2 ESP32实现

/* gpio_hal_esp32.c */
#include "gpio_hal.h"
#include "driver/gpio.h"

void gpio_config(gpio_pin_t *pin) {
    gpio_config_t cfg = {
        .pin_bit_mask = (1ULL << pin->pin),
        .mode         = (gpio_mode_t)pin->mode,
        .pull_up_en   = (pin->pull == GPIO_PULL_UP) ? 1 : 0,
        .pull_down_en = (pin->pull == GPIO_PULL_DOWN) ? 1 : 0,
    };
    gpio_config(&cfg);
}

void gpio_write(gpio_pin_t *pin, uint8_t level) {
    gpio_set_level(pin->pin, level);
}

uint8_t gpio_read(gpio_pin_t *pin) {
    return gpio_get_level(pin->pin);
}

你看，上层调用的接口完全一样，只是底层实现不同。这就是HAL抽象的价值——换MCU时，只需要换一个 .c 文件，应用代码一行都不用改。

3.4 中断抽象：统一回调机制

中断是GPIO里最头疼的部分。不同MCU的中断控制器、优先级、嵌套方式都不一样。我的做法是：在HAL层统一注册回调，底层负责把硬件中断转成函数调用。

/* 中断注册接口 */
int gpio_irq_register(gpio_irq_cfg_t *irq_cfg) {
    /* 底层实现：配置NVIC、使能中断、保存回调指针 */
    /* 返回0成功，-1失败 */
}

/* 底层中断服务函数（在startup_xxx.s里调用） */
void HAL_GPIO_EXTI_IRQHandler(uint16_t GPIO_Pin) {
    /* 查找注册的回调表，执行对应的callback */
    if (callback_table[GPIO_Pin]) {
        callback_table[GPIO_Pin](callback_args[GPIO_Pin]);
    }
    /* 清除中断标志 */
}

嗯，这里有个细节：回调函数不能执行太久。中断里只做标记，具体处理放到任务里。我曾经在回调里直接调 printf()，结果串口中断优先级比GPIO低，直接死锁了——血的教训。

3.5 整体架构图

下面这张图，展示了GPIO-HAL层的完整调用关系。我建议你把它打印出来贴在工位上：

3.6 移植要点总结

最后，我把自己做GPIO移植时踩过的坑，整理成一张清单：

移植项	常见问题	我的建议
引脚编号	STM32用PA0，ESP32用GPIO_NUM_0	统一用 port + pin 结构体，底层做映射表
时钟使能	不同MCU时钟树差异大	在 gpio_config() 里自动使能，不要留给用户
中断优先级	STM32有抢占优先级和子优先级	HAL层只提供 priority 字段，底层自己分组
上下拉电阻	有些MCU内部没有下拉	在 gpio_config() 里返回错误码，或者用外部电阻
输出速度	高速模式可能引入EMI问题	默认用中等速度，除非明确需要高速