3. GPIO驱动封装思想：结构体封装GPIO配置、分层设计（HAL层与LL层）、实现GPIO_Set/Low/High/Toggle接口

好，我们直接进入正题。GPIO 驱动封装，说白了就是给寄存器操作穿上一件「合身的衣服」。很多初学者喜欢在 main 函数里直接写 GPIOA->ODR |= (1<<5)，这样写一时爽，项目大了就等着哭吧。

我个人习惯，不管多小的项目，GPIO 驱动一定要分层。为什么？因为我在一个量产项目里吃过亏——当时为了赶工期，所有 GPIO 操作都散落在各个模块里。结果后期换芯片，改到想砸电脑。从那以后，我定了个规矩：LL 层管寄存器，HAL 层管逻辑，上层只管调用。

3.1 结构体封装GPIO配置

先看最基础的东西。STM32 的 GPIO 配置寄存器有十几个，每次配置都要翻手册算位域，太容易出错了。我的做法是：用一个结构体把配置参数打包。

/* gpio_config.h */
typedef struct {
    uint16_t    Pin;            /* GPIO引脚号，0~15 */
    GPIOMode_TypeDef Mode;      /* 输入/输出/复用/模拟 */
    GPIOSpeed_TypeDef Speed;    /* 低速/中速/高速/超高速 */
    GPIOOType_TypeDef OType;    /* 推挽/开漏 */
    GPIOPuPd_TypeDef PuPd;      /* 上拉/下拉/浮空 */
} GPIO_Config_t;

你可能会问：「这不就是 HAL 库的结构体吗？」没错，思路是一样的。但我要强调的是：这个结构体是你的「契约」。所有 GPIO 初始化函数都只接受这个结构体作为参数，上层代码根本不需要知道寄存器长什么样。

举个例子，配置一个 LED 引脚：

GPIO_Config_t led_cfg = {
    .Pin   = GPIO_PIN_5,
    .Mode  = GPIO_MODE_OUTPUT_PP,
    .Speed = GPIO_SPEED_FREQ_LOW,
    .OType = GPIO_OTYPE_PP,
    .PuPd  = GPIO_PUPDR_NOPULL
};
GPIO_Init(GPIOA, &led_cfg);

嗯，这里要注意：结构体成员顺序不要随意调整。我见过有人为了省几个字节把成员重新排序，结果固件升级时新旧结构体不兼容，整个产线停了两小时。血的教训。

3.2 分层设计：HAL层与LL层

分层不是炫技，是生存法则。我画了一张图，你看完就明白了。

这张图我建议你保存下来。每次写驱动前看一眼，提醒自己：LL 层只做一件事——读写寄存器。HAL 层做两件事——组合 LL 层接口、加逻辑判断。

3.2.1 LL层实现

LL 层要足够「薄」。薄到什么程度？每个函数不超过 5 行代码。来看我的实现：

/* gpio_ll.c */
void GPIO_LL_WriteBit(GPIO_TypeDef* GPIOx, uint16_t Pin, BitAction BitVal)
{
    if (BitVal != RESET) {
        GPIOx->BSRR = Pin;      /* 写1输出高 */
    } else {
        GPIOx->BRR  = Pin;      /* 写1输出低 */
    }
}

uint8_t GPIO_LL_ReadBit(GPIO_TypeDef* GPIOx, uint16_t Pin)
{
    return (GPIOx->IDR & Pin) ? 1 : 0;
}

void GPIO_LL_Config(GPIO_TypeDef* GPIOx, uint16_t Pin, uint32_t Mode, uint32_t Speed)
{
    /* 直接操作CRL/CRH寄存器，略去具体位运算 */
    /* 注意：这里不做参数校验，校验交给HAL层 */
}

3.2.2 HAL层实现

HAL 层是「翻译官」。它把 LL 层的「寄存器语言」翻译成「业务语言」。

/* gpio_hal.c */
void GPIO_Set(GPIO_TypeDef* GPIOx, uint16_t Pin)
{
    /* 参数校验：防止传入非法引脚号 */
    if (Pin > 0xFFFF || Pin == 0) return;
    GPIO_LL_WriteBit(GPIOx, Pin, SET);
}

void GPIO_Reset(GPIO_TypeDef* GPIOx, uint16_t Pin)
{
    if (Pin > 0xFFFF || Pin == 0) return;
    GPIO_LL_WriteBit(GPIOx, Pin, RESET);
}

void GPIO_Toggle(GPIO_TypeDef* GPIOx, uint16_t Pin)
{
    if (Pin > 0xFFFF || Pin == 0) return;
    GPIOx->ODR ^= Pin;  /* 异或翻转，一行搞定 */
}

uint8_t GPIO_Read(GPIO_TypeDef* GPIOx, uint16_t Pin)
{
    if (Pin > 0xFFFF || Pin == 0) return 0;
    return GPIO_LL_ReadBit(GPIOx, Pin);
}

你发现没有？HAL 层的 GPIO_Set 和 GPIO_Reset 内部调的都是 GPIO_LL_WriteBit，只是传参不同。这就是分层的好处：底层接口稳定，上层逻辑灵活。

3.3 接口实现：GPIO_Set / Low / High / Toggle

接口命名是个学问。我见过五花八门的命名：GPIO_WritePin、GPIO_SetPin、GPIO_OutputHigh…… 团队里每个人风格不同，代码 review 时吵得不可开交。

后来我们统一了命名规范，用一张表定下来：

接口函数	功能	参数	返回值
GPIO_Set(GPIOx, Pin)	输出高电平	GPIO组, 引脚掩码	无
GPIO_Reset(GPIOx, Pin)	输出低电平	GPIO组, 引脚掩码	无
GPIO_Toggle(GPIOx, Pin)	翻转电平	GPIO组, 引脚掩码	无
GPIO_Read(GPIOx, Pin)	读取输入电平	GPIO组, 引脚掩码	0 或 1

命名原则很简单：动词 + 对象。Set 就是置高，Reset 就是置低，Toggle 就是翻转。不要搞什么 GPIO_OutputHighLevel 这种又臭又长的名字。

来看一个完整的使用示例：

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

int main(void)
{
    /* 配置PA5为推挽输出 */
    GPIO_Config_t cfg = {
        .Pin   = GPIO_PIN_5,
        .Mode  = GPIO_MODE_OUTPUT_PP,
        .Speed = GPIO_SPEED_FREQ_LOW,
        .OType = GPIO_OTYPE_PP,
        .PuPd  = GPIO_PUPDR_NOPULL
    };
    GPIO_Init(GPIOA, &cfg);

    while (1)
    {
        GPIO_Set(GPIOA, GPIO_PIN_5);      /* LED亮 */
        delay_ms(500);
        GPIO_Reset(GPIOA, GPIO_PIN_5);    /* LED灭 */
        delay_ms(500);
        GPIO_Toggle(GPIOA, GPIO_PIN_5);   /* 翻转，等价于取反 */
        delay_ms(500);
    }
}

3.4 避坑指南与个人经验

最后分享几个我这些年积累的经验，希望能帮你少走弯路。

• 不要在一个函数里同时操作多个引脚。 比如 GPIO_Set(GPIOA, PIN5 | PIN6 | PIN7)，看起来省事，但调试时根本不知道哪个引脚出了问题。我建议：一个函数调用只操作一个引脚。如果需要同时操作，封装一个批量接口。
• 位带操作慎用。 位带操作确实快，但可移植性差。如果你只在 STM32 上做项目，可以用；如果将来要移植到其他 MCU，建议用标准寄存器操作。
• 中断里不要调 HAL 层函数。 HAL 层可能有延时或校验逻辑，不适合在中断上下文执行。中断里直接调 LL 层函数，快进快出。
• 结构体初始化一定要清零。 C 语言不会自动初始化局部变量。我见过有人忘了清零，结果 Mode 成员是个随机值，GPIO 配置成了「薛定谔的模式」。建议用 = {0} 或 memset 清零。