3. GPIO驱动封装：标准GPIO接口设计
GPIO，说白了就是单片机的「手脚」。你要让灯亮、让蜂鸣器响、检测按键有没有按下，都得靠它。但很多新手写代码时，直接对着寄存器操作，今天换了个芯片，整个项目就废了。
我刚开始做嵌入式那几年，也踩过这个坑。一个项目里GPIO初始化散落在各处，读写的逻辑和业务混在一起。后来换MCU，改代码改到怀疑人生。从那以后，我养成了一个习惯——所有外设驱动，必须先封装一层标准接口。
这一章，我们就来聊聊GPIO驱动的封装。我会把我在多个项目里沉淀下来的接口设计思路，一步步拆给你看。
3.1 为什么需要封装？
先看一个反面教材。很多初学者会这样写：
// 点亮LED
GPIOA->BSRR = (1 << 5);这段代码有什么问题？
- 不可移植：换个芯片，寄存器名全变了
- 不可读：别人看不懂你在操作哪个引脚
- 不可维护：如果LED换到另一个引脚，你得满世界找
我见过一个项目，GPIO操作散落在200多个函数里。后来要改一个引脚功能，三个人花了一周才改完。嗯，这就是不封装的代价。
封装的核心目标就三个：
- 隔离硬件差异：上层代码不直接操作寄存器
- 统一调用方式：所有GPIO操作，接口长得一样
- 降低耦合：业务逻辑和硬件驱动分开
3.2 标准GPIO接口设计
我个人习惯把GPIO驱动接口分成三大类：初始化、读写、中断配置。下面这张图可以帮你快速建立整体认知：
3.3 初始化接口设计
初始化是GPIO驱动里最繁琐的部分。一个引脚要配置模式、上下拉、速度、复用功能……参数多了，接口就容易乱。
我推荐用结构体传参的方式。你看这样设计：
/* gpio.h - 标准GPIO接口头文件 */
/* 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_MODE_INPUT = 0, /* 输入模式 */
GPIO_MODE_OUTPUT_PP = 1, /* 推挽输出 */
GPIO_MODE_OUTPUT_OD = 2, /* 开漏输出 */
GPIO_MODE_AF_PP = 3, /* 复用推挽 */
GPIO_MODE_AF_OD = 4, /* 复用开漏 */
GPIO_MODE_ANALOG = 5 /* 模拟模式 */
} GPIO_Mode_t;
/* 初始化参数结构体 */
typedef struct {
GPIO_Port_t port; /* GPIO端口 */
GPIO_Pin_t pin; /* 引脚号 */
GPIO_Mode_t mode; /* 工作模式 */
uint8_t pull; /* 上下拉：0-无，1-上拉，2-下拉 */
uint8_t speed; /* 输出速度 */
uint8_t alt_func; /* 复用功能号（仅AF模式有效） */
} GPIO_Config_t;
/* 初始化函数 */
int32_t GPIO_Init(GPIO_Config_t *config);返回值设计也很关键。我习惯统一返回 int32_t：
- 0：成功
- -1：参数错误（比如引脚号超出范围）
- -2：硬件错误（比如时钟未使能）
为什么要用int32_t？因为可以扩展错误码。我见过有人用bool返回，结果出错了根本不知道哪里有问题。
3.4 读写接口设计
读写接口相对简单，但要注意原子操作。尤其是多任务环境下，读-改-写操作可能会被中断打断。
/* 写单个引脚 */
int32_t GPIO_WritePin(GPIO_Port_t port, GPIO_Pin_t pin, uint8_t level);
/* 读单个引脚 */
int32_t GPIO_ReadPin(GPIO_Port_t port, GPIO_Pin_t pin, uint8_t *level);
/* 写整个端口 */
int32_t GPIO_WritePort(GPIO_Port_t port, uint16_t value);
/* 读整个端口 */
int32_t GPIO_ReadPort(GPIO_Port_t port, uint16_t *value);
/* 翻转引脚 */
int32_t GPIO_TogglePin(GPIO_Port_t port, GPIO_Pin_t pin);这里有个细节——读引脚为什么要用指针传参？因为返回值要用来表示错误状态。如果直接返回引脚电平，那出错时返回0还是1？没法区分。
我曾经在一个项目中，发现读引脚偶尔会读到错误值。排查了半天，发现是读寄存器时被中断写操作打断了。后来在底层加了临界区保护，问题解决。你想想看，这种问题在单任务裸机下很少出现，但一旦上了RTOS，就很容易暴露。
3.5 中断配置接口
GPIO中断配置，是新手最容易翻车的地方。配置项多，而且不同MCU的差异很大。
我设计的接口长这样：
/* 中断触发方式 */
typedef enum {
GPIO_IRQ_RISING = 0, /* 上升沿触发 */
GPIO_IRQ_FALLING = 1, /* 下降沿触发 */
GPIO_IRQ_BOTH = 2, /* 双边沿触发 */
GPIO_IRQ_LOW_LEVEL = 3, /* 低电平触发 */
GPIO_IRQ_HIGH_LEVEL = 4 /* 高电平触发 */
} GPIO_IRQ_Trigger_t;
/* 中断配置结构体 */
typedef struct {
GPIO_Port_t port;
GPIO_Pin_t pin;
GPIO_IRQ_Trigger_t trigger; /* 触发方式 */
uint8_t priority; /* 中断优先级 */
void (*callback)(void); /* 回调函数指针 */
} GPIO_IRQ_Config_t;
/* 配置中断 */
int32_t GPIO_IRQ_Config(GPIO_IRQ_Config_t *config);
/* 使能/禁能中断 */
int32_t GPIO_IRQ_Enable(GPIO_Port_t port, GPIO_Pin_t pin, uint8_t enable);
/* 清除中断标志 */
int32_t GPIO_IRQ_ClearFlag(GPIO_Port_t port, GPIO_Pin_t pin);注意看，我在这里引入了回调函数。这样上层业务代码就不用关心中断向量表怎么写了，只需要注册一个函数：
/* 按键中断回调 */
void Key_IRQ_Handler(void) {
/* 这里只做标记，不做耗时操作 */
g_key_pressed = 1;
}
/* 配置按键中断 */
GPIO_IRQ_Config_t key_cfg = {
.port = GPIO_PORT_A,
.pin = GPIO_PIN_0,
.trigger = GPIO_IRQ_FALLING,
.priority = 2,
.callback = Key_IRQ_Handler
};
GPIO_IRQ_Config(&key_cfg);
GPIO_IRQ_Enable(GPIO_PORT_A, GPIO_PIN_0, 1);3.6 接口对比与选型建议
不同场景下，接口设计的侧重点不同。我整理了一个对比表：
| 场景 | 推荐接口风格 | 关键考量 |
|---|---|---|
| 裸机小项目 | 函数式接口，结构体传参 | 简单直接，代码量少 |
| RTOS多任务 | 加互斥锁/临界区保护 | 原子操作，防止竞争 |
| 跨平台移植 | 硬件抽象层+接口层分离 | 换芯片只改底层 |
| 低功耗场景 | 支持引脚电平保持/唤醒配置 | 中断唤醒+功耗优化 |
3.7 避坑总结
最后，把我这些年踩过的坑，列成清单给你：
- 不要直接操作寄存器——封装一层，以后换芯片你会感谢自己
- 初始化参数用结构体——别搞十几个参数排成一排，谁看了都头大
- 返回值统一用int32_t——bool不够用，void*太危险
- 中断回调里别做耗时操作——printf、延时、复杂计算，统统不要放进去
- 写引脚用置位/清零寄存器——别用读-改-写，除非你加了锁
- 读引脚用指针传参——返回值留给错误码
我曾经在一个量产项目里，因为GPIO中断回调里加了一个调试用的printf，导致系统在高频中断下死机。查了两天才找到原因。从那以后，我定了个规矩：中断回调里只做一件事——置标志位。
GPIO封装看起来简单，但设计得好不好，直接影响到后续所有外设驱动的开发效率。这一套接口设计思路，同样适用于UART、SPI、I2C等外设。你想想看，如果每个外设都有一套统一的初始化、读写、控制接口，整个项目的代码会变得多清爽？