2. GPIO驱动封装（基础篇）：从寄存器到HAL库，设计一个通用的GPIO驱动结构体与初始化接口

GPIO，说白了就是芯片的“手脚”。你让它高它就高，让它低它就低。但实际项目中，GPIO的配置远不止“拉高拉低”这么简单。我见过不少新手，直接在main函数里对着寄存器一顿操作，结果换了个芯片型号，代码全废了。

这一章，我们就来解决这个问题。我会带你从寄存器底层看起，再过渡到HAL库，最后封装出一个通用的GPIO驱动结构体。这套思路，我在多个项目里验证过，确实好用。

2.1 为什么需要封装？直接操作寄存器不香吗？

先问个问题：你写代码是为了什么？是为了炫技，还是为了稳定交付？

直接操作寄存器，确实快，也确实“看起来”很专业。但你想过没有：

• 可读性差：GPIOA->ODR |= 0x01 << 5，这行代码是干嘛的？不查手册谁知道。
• 移植性差：从STM32F1换到STM32F4，寄存器地址变了，你得重写。
• 容易出错：配置一个GPIO，要操作CRL、CRH、ODR、BSRR、BRR……少配一个，板子就不干活。

HAL库解决了部分问题，但HAL库的代码太“啰嗦”了。一个简单的GPIO初始化，HAL_GPIO_Init函数里几十行代码，大部分是防御性检查。在性能敏感的场景下，这些检查就是浪费。

所以，我的思路是：在寄存器的高效和HAL库的易用之间，找一个平衡点。这就是我们封装驱动结构体的初衷。

2.2 从寄存器说起：GPIO的“五脏六腑”

要封装，先得懂底层。STM32的GPIO，每个端口（如GPIOA）都有一组寄存器。我整理了一个表格，把最常用的几个列出来：

寄存器	全称	作用	位宽
MODER	Mode Register	配置输入/输出/复用/模拟	2位/引脚
OTYPER	Output Type Register	配置推挽或开漏输出	1位/引脚
OSPEEDR	Output Speed Register	配置输出速度（低速/中速/高速/极高速）	2位/引脚
PUPDR	Pull-up/Pull-down Register	配置上拉/下拉/浮空	2位/引脚
ODR	Output Data Register	输出数据（写1高电平，写0低电平）	1位/引脚
IDR	Input Data Register	读取输入电平	1位/引脚
BSRR	Bit Set/Reset Register	原子操作置位或复位（写1有效）	32位

你看，每个引脚需要配置的东西还挺多。如果每个地方都写一遍 GPIOA->MODER &= ~(0x03 << (pin*2))，代码会变得又臭又长。

我记得有一次做量产测试工具，需要快速切换几十个GPIO的状态。如果用HAL库的HAL_GPIO_WritePin，每次调用都要经过好几层函数跳转，测试周期根本压不下来。后来我直接用BSRR寄存器做原子操作，速度直接提升了3倍。

2.3 设计通用GPIO驱动结构体

好，现在开始动手。我们要设计一个结构体，把GPIO的“身份信息”和“配置信息”打包在一起。

先看代码：

/**
 * @brief 通用GPIO驱动结构体
 */
typedef struct {
    GPIO_TypeDef *port;      // GPIO端口基地址，如GPIOA、GPIOB
    uint16_t       pin;      // 引脚号，如GPIO_PIN_0
    uint8_t        mode;     // 模式：输入/输出/复用/模拟
    uint8_t        otype;    // 输出类型：推挽/开漏
    uint8_t        speed;    // 输出速度：低速/中速/高速/极高速
    uint8_t        pull;     // 上下拉：无/上拉/下拉
    uint8_t        alt_func; // 复用功能号（仅复用模式有效）
} gpio_cfg_t;

这个结构体，把GPIO的所有配置项都收进来了。你可能会问：为什么不用HAL库的GPIO_InitTypeDef？

原因有两个：

1. HAL库的结构体太“重”：它里面包含了Alternate成员，但如果你用的是输出模式，这个成员就是浪费。我们的结构体更“瘦”。
2. HAL库的初始化函数太“黑盒”：你调了HAL_GPIO_Init，里面到底配了哪些寄存器？出了问题你很难定位。我们的封装，可以让你看到每一步。

2.4 初始化接口设计：从配置到生效

结构体定义好了，接下来就是初始化接口。我的设计思路是：一个函数，搞定所有配置。

先看接口原型：

/**
 * @brief 通用GPIO初始化函数
 * @param cfg 指向gpio_cfg_t结构体的指针
 * @return 0表示成功，-1表示参数错误
 */
int gpio_init(const gpio_cfg_t *cfg);

这个函数内部，我会做以下几件事：

• 参数校验：检查cfg指针是否为NULL，port和pin是否合法。
• 时钟使能：根据port，使能对应的GPIO时钟（RCC寄存器操作）。
• 模式配置：写MODER寄存器。
• 输出类型配置：写OTYPER寄存器。
• 速度配置：写OSPEEDR寄存器。
• 上下拉配置：写PUPDR寄存器。
• 复用功能配置：如果是复用模式，写AFR寄存器。

这里有个细节：时钟使能必须放在最前面。我曾经犯过一个错，先配了寄存器再开时钟，结果配置没写进去，查了半天才发现是时钟没开。

下面是gpio_init函数的实现框架：

int gpio_init(const gpio_cfg_t *cfg) {
    // 1. 参数校验
    if (cfg == NULL) return -1;
    if (cfg->port == NULL) return -1;
    if (cfg->pin > 15) return -1;

    // 2. 使能GPIO时钟（以STM32F4为例）
    uint32_t clock_en = 0;
    if (cfg->port == GPIOA) clock_en = RCC_AHB1ENR_GPIOAEN;
    else if (cfg->port == GPIOB) clock_en = RCC_AHB1ENR_GPIOBEN;
    // ... 其他端口
    RCC->AHB1ENR |= clock_en;

    // 3. 配置模式（MODER）
    cfg->port->MODER &= ~(0x03 << (cfg->pin * 2));
    cfg->port->MODER |= (cfg->mode & 0x03) << (cfg->pin * 2);

    // 4. 配置输出类型（OTYPER）
    cfg->port->OTYPER &= ~(0x01 << cfg->pin);
    cfg->port->OTYPER |= (cfg->otype & 0x01) << cfg->pin;

    // 5. 配置速度（OSPEEDR）
    cfg->port->OSPEEDR &= ~(0x03 << (cfg->pin * 2));
    cfg->port->OSPEEDR |= (cfg->speed & 0x03) << (cfg->pin * 2);

    // 6. 配置上下拉（PUPDR）
    cfg->port->PUPDR &= ~(0x03 << (cfg->pin * 2));
    cfg->port->PUPDR |= (cfg->pull & 0x03) << (cfg->pin * 2);

    // 7. 配置复用功能（AFR）
    if (cfg->mode == GPIO_MODE_AF) {
        uint32_t afr_index = cfg->pin / 8;
        uint32_t afr_offset = (cfg->pin % 8) * 4;
        cfg->port->AFR[afr_index] &= ~(0x0F << afr_offset);
        cfg->port->AFR[afr_index] |= (cfg->alt_func & 0x0F) << afr_offset;
    }

    return 0;
}

你看，整个函数没有用任何HAL库的API，全是寄存器操作。但通过结构体，调用者根本不需要关心寄存器细节。

2.5 使用示例：点亮一个LED

光说不练假把式。我们用一个实际例子来演示怎么用这个驱动。

假设板子上有一个LED，接在PA5上，高电平点亮。配置如下：

• 模式：输出（GPIO_MODE_OUTPUT）
• 输出类型：推挽（GPIO_OTYPE_PP）
• 速度：低速（GPIO_SPEED_LOW）
• 上下拉：无（GPIO_PULL_NONE）

代码这样写：

// 定义配置结构体
gpio_cfg_t led_cfg = {
    .port = GPIOA,
    .pin  = GPIO_PIN_5,
    .mode = GPIO_MODE_OUTPUT,
    .otype = GPIO_OTYPE_PP,
    .speed = GPIO_SPEED_LOW,
    .pull  = GPIO_PULL_NONE,
    .alt_func = 0  // 输出模式不需要复用功能，填0即可
};

// 初始化
gpio_init(&led_cfg);

// 点亮LED（使用BSRR原子操作）
led_cfg.port->BSRR = led_cfg.pin;  // 置位

// 熄灭LED
led_cfg.port->BSRR = (uint32_t)led_cfg.pin << 16;  // 复位

是不是很简洁？而且，如果你想换一个引脚，只需要改结构体里的port和pin，其他代码完全不用动。

2.6 知识结构图：GPIO驱动封装的核心逻辑

为了让你更直观地理解整个设计思路，我画了一张图：

从这张图可以看得很清楚：用户代码只跟结构体和初始化函数打交道，底层的寄存器操作被完全隐藏了。这就是封装的魅力。

2.7 扩展思考：如何支持中断？

这一章我们只讲了基本的输入输出配置。但实际项目中，GPIO中断是绕不开的。比如按键检测，总不能一直轮询吧？

我的做法是：在gpio_cfg_t结构体里，预留一个中断相关的成员。比如：

typedef struct {
    // ... 前面的成员不变
    uint8_t        irq_enable;  // 中断使能：0-关闭，1-使能
    uint8_t        irq_trigger; // 触发方式：上升沿/下降沿/双边沿
    void          (*irq_callback)(void); // 中断回调函数指针
} gpio_cfg_t;

然后在gpio_init函数里，如果检测到irq_enable为1，就自动配置NVIC和EXTI。这样，中断的配置也统一了。

不过，中断涉及的东西比较多（NVIC优先级、EXTI线映射等），我会在后面的章节专门讲。这里先提个思路，让你知道我们的结构体是“可扩展”的。

2.8 本章小结

这一章，我们从寄存器出发，设计了一个通用的GPIO驱动结构体和初始化接口。核心要点就三个：

• 结构体封装配置：把GPIO的所有配置项打包，提高代码可读性和可移植性。
• 寄存器级初始化：绕过HAL库的冗余代码，直接操作寄存器，提升性能。
• 接口统一：一个gpio_init函数，搞定所有配置，调用者无需关心底层细节。

这套设计思路，不仅适用于GPIO，也适用于UART、SPI、I2C等外设。说白了，就是“配置结构化，操作接口化”。你掌握了这个思想，后面学其他外设驱动封装，就会轻松很多。