📚 课程目录第3章 GPIO抽象层设计

3. GPIO抽象层设计：定义GPIO初始化、读写、中断回调的标准接口

GPIO这玩意儿，说白了就是MCU最基础的“手脚”。你让它高它就高，让它低它就低。但问题来了——每家芯片厂的GPIO寄存器设计都不一样。STM32有GPIOx_BSRR、GD32有GPIOx_BOP、NXP有GPIOx_PSOR……换个芯片，底层操作全得重写。

我早年做项目时吃过这个亏。一个产品用了三款不同MCU做兼容设计，GPIO驱动写了三套，维护起来简直噩梦。后来我痛定思痛，决定搞一套抽象层，把差异全屏蔽掉。今天就把这套设计思路分享给你。

3.1 抽象层要解决什么问题？

先看一个实际对比：

操作	STM32 (HAL)	GD32 (Firmware)	NXP (SDK)
初始化	HAL_GPIO_Init()	gpio_init()	GPIO_PinInit()
写高电平	HAL_GPIO_WritePin()	gpio_bit_set()	GPIO_PinWrite()
读电平	HAL_GPIO_ReadPin()	gpio_input_bit_get()	GPIO_PinRead()
中断回调	HAL_GPIO_EXTI_Callback()	nvic_irq_enable() + 自定义	PINT_Callback()

看到没？函数名、参数结构、调用方式全不一样。应用层如果直接调用这些，换芯片就得改几百处代码。抽象层就是在这上面加一层“翻译官”。

3.2 接口定义：四件套

我个人习惯把GPIO抽象层拆成四个核心接口：初始化、写、读、中断回调注册。够用，不冗余。

3.2.1 数据结构设计

先定义一个通用的GPIO配置结构体，把所有MCU的差异参数都收进来：

/* gpio_hal.h */
typedef struct {
    uint32_t        port;       /* GPIO端口号: 0=PA, 1=PB, ... */
    uint32_t        pin;        /* 引脚号: 0~15 */
    uint8_t         mode;       /* 模式: 输入/输出/复用/模拟 */
    uint8_t         pull;       /* 上下拉: 无/上拉/下拉 */
    uint8_t         speed;      /* 速度: 低/中/高/极速 */
    uint8_t         alt_func;   /* 复用功能号 (仅复用模式有效) */
    uint8_t         irq_enable; /* 是否使能中断 */
    uint8_t         irq_trigger;/* 中断触发: 上升沿/下降沿/双边沿 */
    void          (*irq_callback)(void *arg); /* 中断回调函数指针 */
} gpio_cfg_t;

这个结构体覆盖了90%的MCU GPIO配置需求。你可能会问：“有些MCU还有驱动能力、开漏输出这些怎么办？”嗯，可以在mode字段里扩展，或者加一个reserved字段留给平台层自己玩。

3.2.2 初始化接口

/* 初始化GPIO */
int32_t gpio_init(gpio_cfg_t *cfg);

返回值统一：0表示成功，负数表示错误码。我在项目中遇到过有人把返回值设计成结构体指针，结果内存泄漏查了两天……所以，简单点，用int32_t返回状态。

3.2.3 读写接口

/* 写电平 */
void gpio_write(uint32_t port, uint32_t pin, uint8_t level);

/* 读电平 */
uint8_t gpio_read(uint32_t port, uint32_t pin);

/* 翻转电平 */
void gpio_toggle(uint32_t port, uint32_t pin);

这里注意：level参数统一用0和1，不要搞什么GPIO_HIGH/GPIO_LOW枚举。为什么？因为不同芯片库的枚举值可能不一样，抽象层就是要消除这种差异。

3.2.4 中断回调接口

/* 注册中断回调 */
int32_t gpio_irq_register(uint32_t port, uint32_t pin, 
                          void (*callback)(void *arg), void *arg);

/* 使能/禁能中断 */
int32_t gpio_irq_enable(uint32_t port, uint32_t pin, uint8_t enable);

中断回调这块坑最多。我曾经在一个项目里，不同中断源共用一个回调函数，结果参数传错了，导致按键按下时LED没亮，电机却转了……所以回调函数一定要带void *arg参数，让用户能把上下文传进去。

3.3 分层实现：平台层与抽象层分离

接口定义好了，怎么落地？我建议分两层：

抽象层 (gpio_hal.c/h)：只定义接口和数据结构，不涉及具体寄存器操作。
平台层 (gpio_stm32.c, gpio_gd32.c, ...)：针对具体MCU实现上述接口。

看个STM32平台层的实现片段：

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

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

int32_t gpio_init(gpio_cfg_t *cfg) {
    GPIO_InitTypeDef stm32_cfg = {0};
    
    /* 映射抽象层参数到HAL库参数 */
    stm32_cfg.Pin   = (1 << cfg->pin);
    stm32_cfg.Mode  = stm32_mode_map[cfg->mode];
    stm32_cfg.Pull  = stm32_pull_map[cfg->pull];
    stm32_cfg.Speed = stm32_speed_map[cfg->speed];
    
    HAL_GPIO_Init(port_map[cfg->port], &stm32_cfg);
    
    /* 如果使能中断，注册回调 */
    if (cfg->irq_enable) {
        gpio_irq_register(cfg->port, cfg->pin, 
                          cfg->irq_callback, NULL);
    }
    return 0;
}

你看，平台层做的事情就是“翻译”——把抽象层的通用参数转成HAL库能认的参数。换GD32？只要重写这个翻译过程就行，上层代码一行都不用改。

3.4 核心逻辑：一张图看懂

下面这张图展示了整个GPIO抽象层的分层结构和数据流：

3.5 避坑指南：我踩过的几个坑

坑1：中断回调的上下文丢失

我曾经在GD32上做中断回调时，直接把函数指针存在一个全局数组里。结果中断来了，回调执行到一半，另一个中断把数组内容改了……后来我加了临界区保护，才稳住。

技巧：用宏做平台切换

我习惯在gpio_hal.h里加一个平台选择宏：

/* 选择平台 */
#define GPIO_PLATFORM_STM32   1
#define GPIO_PLATFORM_GD32    2
#define GPIO_PLATFORM_NXP     3

/* 当前平台 */
#define GPIO_PLATFORM  GPIO_PLATFORM_STM32

#if GPIO_PLATFORM == GPIO_PLATFORM_STM32
  #include "gpio_stm32.h"
#elif GPIO_PLATFORM == GPIO_PLATFORM_GD32
  #include "gpio_gd32.h"
#endif

这样换平台时只要改一个宏定义，所有文件自动切换。

坑2：引脚号与端口号的边界检查

有次我传了个pin=16进去，STM32的HAL库没报错，但写了个寂寞。后来我在抽象层加了参数校验：

if (pin > 15 || port > max_port) return -1;

别指望底层库帮你检查，自己动手最靠谱。

3.6 完整接口一览

最后，把整个抽象层的接口汇总一下，方便你直接抄作业：

接口	原型	说明
gpio_init	int32_t gpio_init(gpio_cfg_t *cfg)	初始化GPIO，配置模式、上下拉、速度、中断等
gpio_write	void gpio_write(uint32_t port, uint32_t pin, uint8_t level)	设置引脚电平，level: 0=低, 1=高
gpio_read	uint8_t gpio_read(uint32_t port, uint32_t pin)	读取引脚电平，返回0或1
gpio_toggle	void gpio_toggle(uint32_t port, uint32_t pin)	翻转引脚电平
gpio_irq_register	int32_t gpio_irq_register(uint32_t port, uint32_t pin, void (cb)(void), void *arg)	注册中断回调函数
gpio_irq_enable	int32_t gpio_irq_enable(uint32_t port, uint32_t pin, uint8_t enable)	使能或禁能中断

这套接口我在三个项目里验证过，从STM32F103到GD32F450再到NXP LPC55S69，应用层代码零改动。你想想看，如果每个项目都要重写一遍按键扫描、LED控制、中断处理……那得多浪费时间？

抽象层就是花一周时间，省下后面几个月的时间。这笔账，划算。