📚 课程目录第3章 HAL层实战

3、HAL层实战：GPIO驱动抽象

好，我们直接进入正题。上一章讲了分层架构的理论，这一章咱们就动手，拿GPIO这个最基础的模块开刀。为什么选GPIO？因为它简单，但麻雀虽小五脏俱全——初始化、读写、中断，驱动开发的几个核心要素它全占了。

我个人习惯，做驱动抽象时，先想清楚接口长什么样，再去填实现。这样思路不会乱。

3.1 GPIO的HAL接口设计

先问自己一个问题：一个通用的GPIO驱动，到底要暴露哪些操作？

我总结了四个基本操作：

初始化：配置引脚方向、上下拉、输出类型、速度
写操作：输出高/低电平
读操作：读取引脚电平状态
中断控制：使能/禁止中断、配置触发边沿、注册回调

嗯，就这些。别小看这四类操作，把它们抽象好了，换MCU就是换一套实现的事。

下面是我常用的HAL接口定义，C语言风格，大家感受一下：

/* gpio_hal.h */
#ifndef __GPIO_HAL_H__
#define __GPIO_HAL_H__

#include <stdint.h>

/* GPIO引脚电平定义 */
typedef enum {
    GPIO_LEVEL_LOW  = 0,
    GPIO_LEVEL_HIGH = 1
} gpio_level_t;

/* GPIO方向定义 */
typedef enum {
    GPIO_DIR_INPUT  = 0,
    GPIO_DIR_OUTPUT = 1
} gpio_dir_t;

/* 上下拉配置 */
typedef enum {
    GPIO_PULL_NONE  = 0,
    GPIO_PULL_UP    = 1,
    GPIO_PULL_DOWN  = 2
} gpio_pull_t;

/* 中断触发边沿 */
typedef enum {
    GPIO_IRQ_RISING  = 0,
    GPIO_IRQ_FALLING = 1,
    GPIO_IRQ_BOTH    = 2
} gpio_irq_edge_t;

/* GPIO配置结构体 */
typedef struct {
    uint8_t       pin;       /* 引脚号 */
    gpio_dir_t    dir;       /* 方向 */
    gpio_pull_t   pull;      /* 上下拉 */
    uint8_t       speed;     /* 速度等级（MCU相关） */
} gpio_cfg_t;

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

/* ========== HAL接口函数 ========== */

/* 初始化：根据配置结构体设置引脚 */
int gpio_hal_init(gpio_cfg_t *cfg);

/* 写电平 */
void gpio_hal_write(uint8_t pin, gpio_level_t level);

/* 读电平 */
gpio_level_t gpio_hal_read(uint8_t pin);

/* 反转电平 */
void gpio_hal_toggle(uint8_t pin);

/* 中断控制 */
int gpio_hal_irq_enable(uint8_t pin, gpio_irq_edge_t edge);
int gpio_hal_irq_disable(uint8_t pin);
int gpio_hal_irq_register(uint8_t pin, gpio_irq_callback_t cb, void *arg);

#endif /* __GPIO_HAL_H__ */

设计要点：注意看，我把MCU相关的细节（比如速度等级）放到了配置结构体里，而不是接口参数里。这样接口签名就干净了，换平台时只需要改配置结构体的定义和实现。

3.2 典型MCU（STM32）的HAL实现

接口定好了，咱们拿STM32F4系列来填实现。说实话，STM32的HAL库本身已经封装了一层，但咱们要的是更薄、更可控的一层。

先看初始化实现：

/* gpio_hal_stm32f4.c */
#include "gpio_hal.h"
#include "stm32f4xx_hal.h"

/* 内部映射表：引脚号 → GPIO端口和PinMask */
typedef struct {
    GPIO_TypeDef *port;
    uint16_t      pin_mask;
} gpio_map_t;

/* 这里只做示例，实际项目中需要根据板级原理图建立完整映射 */
static gpio_map_t gpio_table[] = {
    {GPIOA, GPIO_PIN_0},   /* pin 0 → PA0 */
    {GPIOA, GPIO_PIN_1},   /* pin 1 → PA1 */
    /* ... 省略中间映射 ... */
    {GPIOB, GPIO_PIN_0},   /* pin 16 → PB0 */
    /* ... */
};

int gpio_hal_init(gpio_cfg_t *cfg)
{
    GPIO_InitTypeDef gpio_init = {0};
    gpio_map_t *map = &gpio_table[cfg->pin];

    /* 使能GPIO时钟（这里简化处理，实际需要查表） */
    __HAL_RCC_GPIOA_CLK_ENABLE();

    /* 填充STM32的初始化结构体 */
    gpio_init.Pin   = map->pin_mask;
    gpio_init.Mode  = (cfg->dir == GPIO_DIR_OUTPUT) ?
                       GPIO_MODE_OUTPUT_PP : GPIO_MODE_INPUT;
    gpio_init.Pull  = (cfg->pull == GPIO_PULL_UP)  ? GPIO_PULLUP :
                      (cfg->pull == GPIO_PULL_DOWN) ? GPIO_PULLDOWN :
                                                      GPIO_NOPULL;
    gpio_init.Speed = GPIO_SPEED_FREQ_HIGH;

    HAL_GPIO_Init(map->port, &gpio_init);
    return 0;
}

读写操作就简单了：

void gpio_hal_write(uint8_t pin, gpio_level_t level)
{
    gpio_map_t *map = &gpio_table[pin];
    HAL_GPIO_WritePin(map->port, map->pin_mask,
                      (level == GPIO_LEVEL_HIGH) ? GPIO_PIN_SET : GPIO_PIN_RESET);
}

gpio_level_t gpio_hal_read(uint8_t pin)
{
    gpio_map_t *map = &gpio_table[pin];
    return (HAL_GPIO_ReadPin(map->port, map->pin_mask) == GPIO_PIN_SET) ?
            GPIO_LEVEL_HIGH : GPIO_LEVEL_LOW;
}

void gpio_hal_toggle(uint8_t pin)
{
    gpio_map_t *map = &gpio_table[pin];
    HAL_GPIO_TogglePin(map->port, map->pin_mask);
}

注意：中断实现时，STM32的EXTI线是有限的（通常16条），而且每条EXTI线只能对应一个引脚。我曾经在一个项目里踩过这个坑——多个引脚配到同一条EXTI线上，结果中断全乱了。所以中断映射表一定要单独维护，不能偷懒。

3.3 跨平台移植案例分析

接口和实现都写好了，那换平台时到底要改什么？我拿一个实际案例来说明。

假设我们有一个项目，原来跑在STM32F4上，现在要移植到GD32F303（国产Cortex-M4兼容芯片）。

模块	需要修改的内容	工作量
gpio_hal.h	基本不用改，接口定义是平台无关的	0行
gpio_hal.c	替换所有HAL_GPIO_xxx调用为GD32的库函数	约50行
gpio_map_t	根据GD32的GPIO端口和引脚号重新建立映射表	约30行
时钟使能	从__HAL_RCC_GPIOx_CLK_ENABLE改为rcu_periph_clock_enable	约10行
中断部分	EXTI配置和NVIC设置需要重写	约40行

你看，总共改动不到150行代码。而且最关键的是——上层的业务逻辑代码一行都不用动。这就是HAL抽象的价值。

下面这张图展示了整个分层关系：

  核心思想：接口层是契约，实现层是履约。只要契约不变，换MCU就像换零件一样简单。

3.4 避坑指南与个人经验

做GPIO抽象时，有几个坑我替大家踩过了，直接说：

引脚映射表别写死：我见过有人把引脚映射直接硬编码在头文件里，换板子就得改头文件，重新编译所有模块。正确的做法是用一个单独的.c文件维护映射表，或者用结构体数组+初始化函数动态构建。
中断回调要加参数：回调函数一定要带void *arg参数，否则你没法区分同一个中断处理函数对应的是哪个设备。我曾经因为这个bug查了两天。
初始化要幂等：gpio_hal_init被调用多次时，不能产生副作用。比如重复使能时钟不会报错，重复配置GPIO不会导致状态异常。
速度等级别硬编码：不同MCU的速度等级定义不一样，放到配置结构体里让上层决定。

我的习惯：每个HAL接口都返回int，0表示成功，负数表示错误码。这样上层可以统一做错误处理，而不是靠全局变量或者HAL_StatusTypeDef这种MCU相关的类型。

嗯，这一章的内容就到这。GPIO的HAL抽象看起来简单，但它是整个驱动分层设计的基石。把这个搞透了，后面UART、SPI、I2C的抽象思路都是一脉相承的。