📚 课程目录第3章 GPIO驱动封装

3、GPIO驱动封装：标准GPIO接口定义、输入输出模式配置、中断注册与回调

GPIO 驱动封装，说白了就是给单片机最基础的引脚操作穿上「标准化外衣」。我做了这么多年嵌入式，见过太多项目因为 GPIO 接口不统一，移植时改得头皮发麻。今天咱们就把这件事彻底聊透。

3.1 为什么需要标准GPIO接口？

你想想看，一个项目里可能同时用 STM32、GD32、NXP 甚至国产 RISC-V 芯片。每个厂家的库函数都不一样——有的叫 GPIO_WriteBit，有的叫 gpio_set，还有的叫 HAL_GPIO_WritePin。如果业务代码里直接调用这些函数，换芯片就等于重写。

我在一个物联网网关项目里就吃过这个亏。当时用了某国产芯片，驱动层和业务层完全耦合。后来客户要求换成 STM32，我带着团队改了整整两周。从那以后，我坚持所有驱动必须加一层抽象。

  核心原则：业务代码只调用标准接口，底层实现可以随时替换。这就是驱动封装的「依赖倒置」思想。

3.2 标准GPIO接口定义

我个人习惯把 GPIO 接口分成三类：控制接口、状态接口、中断接口。下面这个结构体定义，是我在多个项目中沉淀下来的模板。

/* gpio_interface.h */
#ifndef __GPIO_INTERFACE_H__
#define __GPIO_INTERFACE_H__

#include <stdint.h>

/* GPIO 引脚号枚举 */
typedef enum {
    GPIO_PIN_0  = 0,
    GPIO_PIN_1  = 1,
    GPIO_PIN_2  = 2,
    /* ... 根据芯片实际引脚数扩展 */
    GPIO_PIN_15 = 15
} gpio_pin_t;

/* GPIO 端口枚举 */
typedef enum {
    GPIO_PORT_A = 0,
    GPIO_PORT_B = 1,
    GPIO_PORT_C = 2,
    GPIO_PORT_D = 3,
    GPIO_PORT_E = 4,
    GPIO_PORT_F = 5
} gpio_port_t;

/* GPIO 模式枚举 */
typedef enum {
    GPIO_MODE_INPUT         = 0x00,
    GPIO_MODE_OUTPUT_PP     = 0x01,  /* 推挽输出 */
    GPIO_MODE_OUTPUT_OD     = 0x02,  /* 开漏输出 */
    GPIO_MODE_AF_PP         = 0x03,  /* 复用推挽 */
    GPIO_MODE_AF_OD         = 0x04,  /* 复用开漏 */
    GPIO_MODE_ANALOG        = 0x05   /* 模拟模式 */
} gpio_mode_t;

/* 上下拉配置 */
typedef enum {
    GPIO_PULL_NONE  = 0x00,
    GPIO_PULL_UP    = 0x01,
    GPIO_PULL_DOWN  = 0x02
} gpio_pull_t;

/* 中断触发方式 */
typedef enum {
    GPIO_IRQ_RISING_EDGE   = 0x00,
    GPIO_IRQ_FALLING_EDGE  = 0x01,
    GPIO_IRQ_BOTH_EDGE     = 0x02,
    GPIO_IRQ_LOW_LEVEL     = 0x03,
    GPIO_IRQ_HIGH_LEVEL    = 0x04
} gpio_irq_mode_t;

/* 中断回调函数指针类型 */
typedef void (*gpio_irq_callback_t)(void *arg);

/* GPIO 对象结构体 */
typedef struct {
    gpio_port_t         port;
    gpio_pin_t          pin;
    gpio_mode_t         mode;
    gpio_pull_t         pull;
    uint8_t             speed;       /* 输出速度，0-3 */
    uint8_t             alt_func;    /* 复用功能号 */
    gpio_irq_callback_t irq_callback;/* 中断回调 */
    void               *irq_arg;     /* 回调参数 */
} gpio_cfg_t;

/* ========== 标准接口函数 ========== */

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

/* 设置引脚电平 */
void    gpio_set_level(gpio_port_t port, gpio_pin_t pin, uint8_t level);

/* 读取引脚电平 */
uint8_t gpio_get_level(gpio_port_t port, gpio_pin_t pin);

/* 翻转引脚电平 */
void    gpio_toggle(gpio_port_t port, gpio_pin_t pin);

/* 配置中断 */
int32_t gpio_irq_config(gpio_port_t port, gpio_pin_t pin, 
                        gpio_irq_mode_t mode, 
                        gpio_irq_callback_t callback, 
                        void *arg);

/* 使能/禁止中断 */
void    gpio_irq_enable(gpio_port_t port, gpio_pin_t pin, uint8_t enable);

#endif /* __GPIO_INTERFACE_H__ */

我的习惯：所有接口函数返回 int32_t，0 表示成功，负数表示错误码。这样上层可以统一做错误处理，而不是靠全局变量传状态。

3.3 输入输出模式配置

配置 GPIO 模式，其实就是在操作芯片的寄存器。但不同芯片的寄存器布局天差地别。比如 STM32 用 MODER、OTYPER、OSPEEDR、PUPDR 四个寄存器；而某些国产芯片把模式、上下拉、速度全塞在一个寄存器里。

下面这张图展示了标准接口与底层硬件的关系：

配置输入输出模式时，我建议用一张表来管理不同芯片的差异：

标准接口模式	STM32 HAL对应	GD32对应	NXP LPC对应
GPIO_MODE_INPUT	GPIO_MODE_INPUT	GPIO_MODE_INPUT	kGPIO_DigitalInput
GPIO_MODE_OUTPUT_PP	GPIO_MODE_OUTPUT_PP	GPIO_MODE_OUT_PP	kGPIO_DigitalOutput
GPIO_MODE_OUTPUT_OD	GPIO_MODE_OUTPUT_OD	GPIO_MODE_OUT_OD	kGPIO_OutputOD
GPIO_MODE_AF_PP	GPIO_MODE_AF_PP	GPIO_MODE_AF_PP	kGPIO_MuxAlt

曾经踩过的坑：某国产芯片的「推挽输出」和「开漏输出」在寄存器里只差一个bit，但如果不配置上下拉，开漏输出在高电平时会浮空。我排查了整整一天才发现是上下拉没设对。

3.4 中断注册与回调机制

中断处理是 GPIO 驱动里最容易出问题的地方。很多新手喜欢在中断服务函数里写业务逻辑，结果导致中断响应时间过长，系统卡死。

我的做法是：中断服务函数只做一件事——调用注册的回调函数。回调函数里再根据实际需求做处理。

下面是一个典型的实现示例：

/* gpio_stm32.c —— STM32平台适配层实现片段 */

/* 中断回调表：每个引脚一个回调 */
static gpio_irq_callback_t s_irq_cb[16] = {NULL};
static void *s_irq_arg[16] = {NULL};

/* 标准接口：配置中断 */
int32_t gpio_irq_config(gpio_port_t port, gpio_pin_t pin, 
                        gpio_irq_mode_t mode, 
                        gpio_irq_callback_t callback, 
                        void *arg)
{
    uint16_t gpio_pin = (1 << pin);
    uint32_t irq_num;
    
    /* 1. 配置触发方式 */
    switch(mode) {
        case GPIO_IRQ_RISING_EDGE:
            HAL_NVIC_SetPriority(/* ... */);
            break;
        case GPIO_IRQ_FALLING_EDGE:
            /* ... */
            break;
        default:
            return -1;
    }
    
    /* 2. 注册回调 */
    s_irq_cb[pin] = callback;
    s_irq_arg[pin] = arg;
    
    /* 3. 使能中断线 */
    HAL_NVIC_EnableIRQ(irq_num);
    
    return 0;
}

/* 中断服务函数（由芯片中断向量表调用） */
void EXTI0_IRQHandler(void)
{
    /* 检查中断标志 */
    if(__HAL_GPIO_EXTI_GET_IT(GPIO_PIN_0) != RESET) {
        /* 清除标志 */
        __HAL_GPIO_EXTI_CLEAR_IT(GPIO_PIN_0);
        
        /* 调用注册的回调 */
        if(s_irq_cb[0] != NULL) {
            s_irq_cb[0](s_irq_arg[0]);
        }
    }
}

个人建议：回调函数里不要做耗时操作，比如打印日志、延时等待。如果确实需要，用消息队列把事件抛给任务线程处理。我在一个电机控制项目里，就是因为中断里直接调了 printf，导致系统频繁死机。

3.5 移植实战：从STM32到GD32

假设你有一个项目原本跑在 STM32F103 上，现在要移植到 GD32F103。有了标准接口，你只需要重新实现适配层的几个函数。

对比一下两个平台的差异：

功能	STM32 HAL实现	GD32实现
初始化	HAL_GPIO_Init	gpio_mode_set + gpio_output_options_set
写电平	HAL_GPIO_WritePin	gpio_bit_set / gpio_bit_reset
读电平	HAL_GPIO_ReadPin	gpio_input_bit_get
中断配置	HAL_NVIC_SetPriority + HAL_GPIO_EXTI_ConfigLine	nvic_irq_enable + exti_init

你看，只要把适配层里每个函数的实现替换掉，业务代码一行都不用改。这就是标准接口的价值。

  移植工作量估算：一个典型的 GPIO 适配层大约 200-300 行代码。如果接口设计得好，换芯片只需要 1-2 天。相比直接改业务代码，效率提升 5-10 倍。

3.6 调试接口与测试

驱动写完了，怎么验证？我一般会加一组调试接口：

引脚状态转储：把当前所有 GPIO 的配置和电平打印出来
中断计数：统计每个引脚的中断触发次数，排查毛刺
回环测试：把两个引脚短接，一个输出一个输入，验证读写一致性

我曾经在一个工业控制项目里，用回环测试发现某批次芯片的 GPIO 输出驱动能力不足，导致高电平只能到 2.8V。要不是有调试接口，这种问题很难定位。

好了，GPIO 驱动封装的核心内容就这些。记住：接口标准化、适配层隔离、回调轻量化，这三点做到位，你的驱动就能在各种芯片间自由迁移。