【10】实现自己的GPIO库【模仿HAL库】 | 立创开发板技术文档中心

编写者：LCKFB-YZH
版本：v1.0
日期：2026-08-21
更新记录：
v1.0（2026-08-21）：完成自制 GPIO 库、双 LED 板级封装、工程接入、编译下载、调试验证与工程实践说明。

一本章简介

前面用几行寄存器代码就能让 LED 闪烁，但“能控制一个引脚”和“写出一套可复用的驱动”是两件事。本章从零实现一套 TK_GPIO_ 教学库：自己定义寄存器结构体，设计类似 HAL 的初始化结构体和函数接口，再用板级支持包（Board Support Package，BSP）统一控制天空星核心板 PB2 LED 与筑基学习板 PB8 LED。

这篇教程可以独立学习。寄存器地址、读—改—写（Read-Modify-Write，RMW）、位掩码、BSRR、LED 有效电平、工程接入、编译、下载和调试都会在本章讲清楚，不要求先阅读寄存器点灯章节，但是软件操作相关的内容不会再重复赘述，，如果你连软件基础使用都不知道的话，还是回去看一下第九章吧。

IMPORTANT

本章的目标不是替代 STM32 HAL，而是要和大家一起亲手走完“芯片手册 → 寄存器定义 → 驱动接口 → BSP → 应用”的路径。

1.1 学习目标

完成本章后，应当能够：

序号	学习目标	重要度	验证方式
1	说明 GPIO 地址、寄存器结构体和成员偏移之间的关系	⭐⭐⭐⭐⭐	能由 `GPIOB_BASE + 0x18` 得到 `GPIOB->BSRR`
2	用位掩码表示一个或多个引脚	⭐⭐⭐⭐⭐	能解释 `TK_GPIO_PIN_2 \| TK_GPIO_PIN_8` 的结果
3	区分普通读—改—写与 `BSRR` 写入	⭐⭐⭐⭐⭐	能说明为什么设置输出电平优先写 `BSRR`
4	设计并实现 GPIO 初始化接口	⭐⭐⭐⭐⭐	能读懂 `TK_GPIO_InitTypeDef` 与 `TK_GPIO_Init()`
5	正确处理不同 LED 的有效电平	⭐⭐⭐⭐⭐	能让 PB2 与 PB8 两颗 LED 同时亮、同时灭
6	把芯片驱动与板级资源分层	⭐⭐⭐⭐	更换 LED 引脚或极性时只修改 BSP
7	独立完成工程编译、下载和寄存器调试	⭐⭐⭐⭐⭐	构建无代码警告，下载后 LED 周期闪烁，寄存器值符合预期
8	判断教学库在并发、复位值和可移植性方面的边界	⭐⭐⭐⭐	能指出 `TogglePin`、`DeInit` 和端口时钟接口的限制

1.2 硬件与软件准备

需要准备：

天空星 STM32F407 核心板与天空星筑基学习板。
LCKFB DAPLink 仿真器及 SWD 排线；ST-Link、J-Link 也可以，但调试器设置需要按对应工具调整。
下列环境任选一种：
- Keil MDK，适合第一次完成本章；
- VS Code + EIDE；
- CLion + Arm GNU Toolchain + CMake。
已安装 STM32F4 设备支持包、对应编译器与调试器驱动。

配套的最小工程已经包含启动文件、链接脚本、SVD 文件和三种工程配置，可以直接作为本章起点：

如果从空目录手工创建，8.2～8.5 会给出完整步骤。

1.3 阅读路线

初学者建议按顺序阅读，先让双 LED 正常闪烁，再回看 10.2～10.6 的工程细节。第一次不必记住全部寄存器位，只要抓住三条主线：

结构体成员的位置必须和寄存器偏移一致。
初始化要先配置电气属性，最后才把引脚切换到目标模式。
BSP 负责“哪颗灯、什么电平亮”，GPIO 驱动只负责“引脚输出高或低”。

有驱动经验的读者可以重点看 6.4、6.6、6.9 和第十章，其中包含时钟使能后的回读、输出瞬态控制、BSRR 的原子写边界、反初始化语义和并发约束。

1.4 最终文件

本章最终得到 5 个文件：

文件	所属层	职责
`tkx_stm32f407.h`	芯片描述层	定义 GPIO、RCC 寄存器布局、外设地址和时钟位
`tk_gpio.h`	驱动接口层	定义引脚、模式、速度、上下拉、复用功能和 API
`tk_gpio.c`	驱动实现层	访问寄存器并完成初始化、读写、翻转和反初始化
`bsp_led.h/.c`	板级层	描述 PB2/PB8 LED 的端口、引脚与有效电平
`main.c`	应用层	只表达“两颗 LED 周期翻转”

二先看硬件：同样是 LED，点亮电平却相反

2.1 连接 DAPLink

先断开板卡电源，按 DAPLink 接口丝印连接 3V3、GND、SWDIO、SWCLK，确认方向无误后再上电。实物连接如下。

如果使用本图以外的转接线或调试器，请逐一核对信号名，不能只根据线色判断。DAPLink 接口定义可查看配套 DAPLink 仿真器说明。

2.2 核心板 PB2 LED：高电平点亮

核心板用户 LED 连接在 PB2。原理图中电流路径为 PB2 → LED1 → 电阻 → GND，因此 PB2 输出高电平时有电流流过 LED。

PB2 还与 BOOT1 功能复用，板上 10 kΩ 下拉保证复位采样状态确定。程序运行后把 PB2 配置为普通 GPIO 输出，不影响本章点灯。

2.3 筑基学习板 PB8 LED：低电平点亮

筑基学习板 LED16 连接在 PB8，LED 的另一端通过限流电阻接 3.3 V。PB8 输出低电平时，电流从 3.3 V 流向 PB8，所以这颗 LED 是低电平有效。

两颗 LED 的逻辑状态与引脚电平关系如下：

LED	引脚	点亮时引脚电平	熄灭时引脚电平
核心板用户 LED	PB2	高	低
筑基学习板 LED16	PB8	低	高

如果 main.c 直接写 PB2/PB8 电平，应用层必须反复记住这张表。BSP 的价值就是把电气极性封装起来，让上层只表达“亮”和“灭”。

2.4 为什么切换到输出模式前要先写“熄灭电平”

GPIO 的输出数据寄存器（Output Data Register，ODR）保存输出锁存值。引脚还是输入模式时，也可以通过位设置/复位寄存器（Bit Set/Reset Register，BSRR）预先改变这个锁存值；等 MODER 切换为输出模式，引脚立即输出已经准备好的电平。

本章初始化顺序是：

使能 GPIOB 时钟。
预置 PB2 为低、PB8 为高，让两颗 LED 都处于熄灭状态。
配置输出类型、速度、上下拉。
最后把 PB2 和 PB8 切换为输出模式。

这样可以减少上电初始化时 LED 短暂闪亮。通用 GPIO 库不知道外部负载的安全电平，因此“预置哪个电平”应由 BSP 或外设驱动决定。

三从裸寄存器代码到 GPIO 库

3.1 寄存器就是外设的控制面板

可以把 GPIO 外设理解为一个控制面板：

MODER 决定引脚处于输入、输出、复用还是模拟模式；
OTYPER 决定输出为推挽还是开漏；
OSPEEDR 决定输出边沿速度等级；
PUPDR 决定内部上拉、下拉或无上下拉；
IDR 读取引脚当前输入电平；
ODR 保存输出锁存状态；
BSRR 对输出位执行设置或复位。

这个比喻只用于理解职责边界。寄存器不是独立的物理拨动开关，CPU 实际上通过地址在片上总线上发起读写，外设硬件再解释这次访问。

点亮 PB2 的裸寄存器核心代码大致如下：

RCC->AHB1ENR |= RCC_AHB1ENR_GPIOBEN;
GPIOB->MODER = (GPIOB->MODER & ~(0x3UL << 4U)) | (0x1UL << 4U);
GPIOB->BSRR = 1UL << 2U;

代码很短，但应用层知道了时钟寄存器、模式位位置和 LED 有效电平。引脚一多，同样的位运算会不断复制，修改和审查都容易遗漏。

3.2 我们希望上层怎样调用

封装后，GPIO 配置由结构体描述：

TK_GPIO_InitTypeDef init = {0};

TK_GPIO_ClockEnable(GPIOB);
init.Pin = TK_GPIO_PIN_2 | TK_GPIO_PIN_8;
init.Mode = TK_GPIO_MODE_OUTPUT_PP;
init.Pull = TK_GPIO_NOPULL;
init.Speed = TK_GPIO_SPEED_LOW;
init.Alternate = TK_GPIO_AF_0;
TK_GPIO_Init(GPIOB, &init);

这不是为了让代码看起来高级，既是为了方便阅读，也是为了把固定规则集中到驱动层：

每个引脚占几位；
不同配置写哪个寄存器；
怎样保留同一端口其他引脚；
怎样用 BSRR 设置和复位输出；
参数不合法时怎样避免误写未知地址。

3.3 分层关系

flowchart TD
    A["main.c
应用：两颗 LED 周期翻转"] --> B["bsp_led.c
板级资源：PB2/PB8 与有效电平"]
    B --> C["tk_gpio.c
GPIO 驱动：初始化、读、写、翻转"]
    C --> D["tkx_stm32f407.h
芯片描述：地址、结构体、位掩码"]
    D --> E["STM32F407 硬件寄存器"]

移植到另一块板时，通常只改 BSP；增加串口、SPI 等外设时，可以继续复用芯片描述层；替换为官方 HAL 时，应用层与 BSP 的改动范围也更容易控制。

3.4 本章库的边界

TK_GPIO_ 支持 STM32F407 的 GPIOA～GPIOI，提供输入、输出、复用、模拟、上下拉、速度和复用功能号配置，并支持多引脚位掩码。

它有意不实现以下内容：

外部中断与 SYSCFG/EXTI；
GPIO 配置锁定序列；
GPIO 端口时钟关闭和低功耗策略；
运行时错误码、断言钩子与线程锁；
不同 STM32 系列之间的兼容层。

GPIOA～GPIOI 是芯片外设实例，不代表任意封装都引出了每个端口的全部引脚。最终可用引脚必须按具体料号封装和 DS8626 Rev 12 的引脚表核对。

四用 C 结构体映射 GPIO 寄存器

4.1 基地址加偏移地址

STM32F407 把外设寄存器映射到统一地址空间。下面的 RM0090 Rev 21 存储器映射图中，GPIOA 从 0x4002 0000 开始，GPIOB 从 0x4002 0400 开始，RCC 从 0x4002 3800 开始。

“基地址 + 偏移”可以类比为“楼栋地址 + 房间号”：GPIOB_BASE 先找到 GPIOB 这栋楼，0x18 再找到 BSRR 房间。类比的边界是，寄存器可能只读、只写或具有特殊写入语义，不能把它当成普通内存随意读写。

对象	地址或偏移	计算结果
GPIOB 基地址	`0x4002 0400`	`0x4002 0400`
`MODER` 偏移	`0x00`	`0x4002 0400`
`ODR` 偏移	`0x14`	`0x4002 0414`
`BSRR` 偏移	`0x18`	`0x4002 0418`
RCC 基地址 + `AHB1ENR` 偏移	`0x4002 3800 + 0x30`	`0x4002 3830`

4.2 GPIO 寄存器排列

GPIO 端口的寄存器按固定顺序排列。C 结构体的第一个 uint32_t 成员占 4 字节，后续成员也各占 4 字节，因此只要成员顺序正确，就能让 GPIOx->成员名 对应正确偏移。

需要注意，复位值不一定全为 0。例如 GPIOB 的 MODER 复位值为 0x0000 0280，因为 PB3 和 PB4 复位后保留调试相关复用状态。自制 DeInit 把目标引脚恢复为“输入、推挽、低速、无上下拉、AF0”，这是一组统一的教学默认值，不等于每个引脚的芯片真实复位状态。

4.3 `volatile`、只读与保留成员

寄存器值可能被硬件、DMA、中断或调试器改变，编译器不能把一次读取长期缓存起来，所以寄存器成员必须带 volatile。

本章定义三种访问限定：

宏	展开结果	用途
`TKX_I`	`volatile const`	软件只读，例如 `IDR`
`TKX_O`	`volatile`	软件只写语义，例如 `BSRR`
`TKX_IO`	`volatile`	软件可读写，例如 `MODER`、`ODR`

其中 TKX_O 无法让 C 编译器真正禁止读取，只是在结构体中表达设计意图；寄存器是否允许读取以及读取返回什么，仍以 RM0090 Rev 21 为准。

RCC 结构体中的 RESERVED0 和 RESERVED1 不是可用寄存器，而是为未使用地址留出空间。如果删掉它们，AHB1ENR 会被错误地放到 0x28，后续所有访问都会写错地址。

4.4 用编译期断言检查关键偏移

offsetof(GPIO_TypeDef, BSRR) 可以在编译期得到成员偏移。本章用 C11 _Static_assert 检查三个关键位置：

_Static_assert(offsetof(GPIO_TypeDef, BSRR) == 0x18U,
               "GPIO BSRR offset mismatch");
_Static_assert(offsetof(GPIO_TypeDef, AFR) == 0x20U,
               "GPIO AFR offset mismatch");
_Static_assert(offsetof(RCC_TypeDef, AHB1ENR) == 0x30U,
               "RCC AHB1ENR offset mismatch");

如果有人调整了结构体成员却没有同步手册偏移，编译会立即失败，比等到板上出现异常再排查更可靠。

4.5 完整 `tkx_stm32f407.h`

新建 Core/Inc/tkx_stm32f407.h：

/**
 * @file tkx_stm32f407.h
 * @author LCKFB-YZH
 * @brief STM32F407 GPIO 与 RCC 的最小寄存器定义。
 */

#ifndef TKX_STM32F407_H
#define TKX_STM32F407_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define TKX_I  volatile const
#define TKX_O  volatile
#define TKX_IO volatile

typedef struct
{
    TKX_IO uint32_t MODER;       /* Offset 0x00. */
    TKX_IO uint32_t OTYPER;      /* Offset 0x04. */
    TKX_IO uint32_t OSPEEDR;     /* Offset 0x08. */
    TKX_IO uint32_t PUPDR;       /* Offset 0x0C. */
    TKX_I  uint32_t IDR;         /* Offset 0x10. */
    TKX_IO uint32_t ODR;         /* Offset 0x14. */
    TKX_O  uint32_t BSRR;        /* Offset 0x18. */
    TKX_IO uint32_t LCKR;        /* Offset 0x1C. */
    TKX_IO uint32_t AFR[2];      /* Offset 0x20-0x24. */
} GPIO_TypeDef;

typedef struct
{
    TKX_IO uint32_t CR;          /* Offset 0x00. */
    TKX_IO uint32_t PLLCFGR;     /* Offset 0x04. */
    TKX_IO uint32_t CFGR;        /* Offset 0x08. */
    TKX_IO uint32_t CIR;         /* Offset 0x0C. */
    TKX_IO uint32_t AHB1RSTR;    /* Offset 0x10. */
    TKX_IO uint32_t AHB2RSTR;    /* Offset 0x14. */
    TKX_IO uint32_t AHB3RSTR;    /* Offset 0x18. */
    uint32_t RESERVED0;          /* Offset 0x1C. */
    TKX_IO uint32_t APB1RSTR;    /* Offset 0x20. */
    TKX_IO uint32_t APB2RSTR;    /* Offset 0x24. */
    uint32_t RESERVED1[2];       /* Offset 0x28-0x2C. */
    TKX_IO uint32_t AHB1ENR;     /* Offset 0x30. */
} RCC_TypeDef;

#define PERIPH_BASE          (0x40000000UL)
#define AHB1PERIPH_BASE      (PERIPH_BASE + 0x00020000UL)

#define GPIOA_BASE           (AHB1PERIPH_BASE + 0x0000UL)
#define GPIOB_BASE           (AHB1PERIPH_BASE + 0x0400UL)
#define GPIOC_BASE           (AHB1PERIPH_BASE + 0x0800UL)
#define GPIOD_BASE           (AHB1PERIPH_BASE + 0x0C00UL)
#define GPIOE_BASE           (AHB1PERIPH_BASE + 0x1000UL)
#define GPIOF_BASE           (AHB1PERIPH_BASE + 0x1400UL)
#define GPIOG_BASE           (AHB1PERIPH_BASE + 0x1800UL)
#define GPIOH_BASE           (AHB1PERIPH_BASE + 0x1C00UL)
#define GPIOI_BASE           (AHB1PERIPH_BASE + 0x2000UL)
#define RCC_BASE             (AHB1PERIPH_BASE + 0x3800UL)

#define GPIOA                ((GPIO_TypeDef *)GPIOA_BASE)
#define GPIOB                ((GPIO_TypeDef *)GPIOB_BASE)
#define GPIOC                ((GPIO_TypeDef *)GPIOC_BASE)
#define GPIOD                ((GPIO_TypeDef *)GPIOD_BASE)
#define GPIOE                ((GPIO_TypeDef *)GPIOE_BASE)
#define GPIOF                ((GPIO_TypeDef *)GPIOF_BASE)
#define GPIOG                ((GPIO_TypeDef *)GPIOG_BASE)
#define GPIOH                ((GPIO_TypeDef *)GPIOH_BASE)
#define GPIOI                ((GPIO_TypeDef *)GPIOI_BASE)
#define RCC                  ((RCC_TypeDef *)RCC_BASE)

#define RCC_AHB1ENR_GPIOAEN  (1UL << 0U)
#define RCC_AHB1ENR_GPIOBEN  (1UL << 1U)
#define RCC_AHB1ENR_GPIOCEN  (1UL << 2U)
#define RCC_AHB1ENR_GPIODEN  (1UL << 3U)
#define RCC_AHB1ENR_GPIOEEN  (1UL << 4U)
#define RCC_AHB1ENR_GPIOFEN  (1UL << 5U)
#define RCC_AHB1ENR_GPIOGEN  (1UL << 6U)
#define RCC_AHB1ENR_GPIOHEN  (1UL << 7U)
#define RCC_AHB1ENR_GPIOIEN  (1UL << 8U)

#if defined(__cplusplus) && (__cplusplus >= 201103L)
static_assert(offsetof(GPIO_TypeDef, BSRR) == 0x18U,
              "GPIO BSRR offset mismatch");
static_assert(offsetof(GPIO_TypeDef, AFR) == 0x20U,
              "GPIO AFR offset mismatch");
static_assert(offsetof(RCC_TypeDef, AHB1ENR) == 0x30U,
              "RCC AHB1ENR offset mismatch");
#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L)
_Static_assert(offsetof(GPIO_TypeDef, BSRR) == 0x18U,
               "GPIO BSRR offset mismatch");
_Static_assert(offsetof(GPIO_TypeDef, AFR) == 0x20U,
               "GPIO AFR offset mismatch");
_Static_assert(offsetof(RCC_TypeDef, AHB1ENR) == 0x30U,
               "RCC AHB1ENR offset mismatch");
#endif

#ifdef __cplusplus
}
#endif

#endif /* TKX_STM32F407_H */

文件名使用 tkx_stm32f407.h，不要命名为官方的 stm32f407xx.h。这样以后接入 CMSIS/HAL 时不会因同名头文件和包含路径顺序产生冲突。

这份最小头文件与官方 CMSIS 设备头文件是二选一关系，不能在同一编译单元同时包含，因为二者都会定义 GPIO_TypeDef、RCC_TypeDef 等芯片级类型。切换到 HAL 工程时，应删除本章的最小寄存器定义，让 TK_GPIO_ 驱动改为包含并复用官方 stm32f407xx.h。

五设计 `tk_gpio.h`：先把接口想清楚

5.1 用位掩码表示引脚

每个 GPIO 端口最多有 16 个引脚。让 bit0 对应 Pin0、bit1 对应 Pin1，就能用一个 16 位掩码同时选择多个引脚：

#define TK_GPIO_PIN_2  (1UL << 2U)   /* 0x0004 */
#define TK_GPIO_PIN_8  (1UL << 8U)   /* 0x0100 */

两者按位或：

text

TK_GPIO_PIN_2 | TK_GPIO_PIN_8
= 0x0004 | 0x0100
= 0x0104

0x0104 的 bit2、bit8 为 1，初始化函数遍历 16 个位置时就能选中 PB2 和 PB8。这里的 TK_GPIO_PIN_2 是掩码 1 << 2，不是普通数字 2。

5.2 模式宏为什么包含两类信息

MODER 中每个引脚占 2 bit：

`MODER` 位值	模式
`00`	输入
`01`	通用输出
`10`	复用功能
`11`	模拟

OTYPER 每个引脚只占 1 bit，0 为推挽，1 为开漏：

为了让一个 Mode 字段同时表达“主模式”和“输出类型”，本章把低 2 bit 用作 MODER 值，把 bit4 用作 OTYPER 值：

模式宏	值	低 2 bit	bit4	含义
`TK_GPIO_MODE_INPUT`	`0x00`	`00`	`0`	输入
`TK_GPIO_MODE_OUTPUT_PP`	`0x01`	`01`	`0`	推挽输出
`TK_GPIO_MODE_OUTPUT_OD`	`0x11`	`01`	`1`	开漏输出
`TK_GPIO_MODE_AF_PP`	`0x02`	`10`	`0`	推挽复用
`TK_GPIO_MODE_AF_OD`	`0x12`	`10`	`1`	开漏复用
`TK_GPIO_MODE_ANALOG`	`0x03`	`11`	`0`	模拟

这种编码便于教学和实现，但它不是芯片寄存器的原始整体值，也不是跨平台 ABI。外部代码应使用宏，不要依赖 0x10 这个私有编码细节。

5.3 速度、上下拉和复用功能

OSPEEDR 与 PUPDR 也是每个引脚 2 bit：

速度等级描述输出驱动边沿能力，不等同于程序翻转频率。没有高速信号完整性需求时优先低速，可减小边沿过冲、串扰和动态功耗。开漏输出只负责主动拉低，高电平需要内部或外部上拉；I²C 等总线还必须按总线电容和时序选取外部上拉电阻。

Alternate 保存 AF0～AF15 复用功能号，只在 TK_GPIO_MODE_AF_PP 或 TK_GPIO_MODE_AF_OD 下使用。具体引脚能选择哪个外设功能，必须查 DS8626 Rev 12 的 Alternate function mapping 表，不能只根据 AF 数字猜测。

5.4 初始化结构体

typedef struct
{
    uint32_t Pin;
    uint32_t Mode;
    uint32_t Pull;
    uint32_t Speed;
    uint32_t Alternate;
} TK_GPIO_InitTypeDef;

把相关参数放进结构体有三个好处：

调用处能按字段名表达含义，减少位置参数传错。
一个结构体可以同时初始化同一端口的多个同配置引脚。
后续增加字段时，不必把所有调用改成更长的函数参数列表。

结构体先用 {0} 初始化，避免未填写字段带入栈上随机值。即使输出模式不使用 Alternate，本章示例仍明确赋为 TK_GPIO_AF_0，便于代码审查。

5.5 完整 `tk_gpio.h`

新建 Drivers/TK_GPIO/Inc/tk_gpio.h：

/**
 * @file tk_gpio.h
 * @author LCKFB-YZH
 * @brief 教学用 STM32F407 GPIO 驱动接口。
 */

#ifndef TK_GPIO_H
#define TK_GPIO_H

#include "tkx_stm32f407.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef enum
{
    TK_GPIO_PIN_RESET = 0U,
    TK_GPIO_PIN_SET = 1U
} TK_GPIO_PinState;

#define TK_GPIO_PIN_0         (1UL << 0U)
#define TK_GPIO_PIN_1         (1UL << 1U)
#define TK_GPIO_PIN_2         (1UL << 2U)
#define TK_GPIO_PIN_3         (1UL << 3U)
#define TK_GPIO_PIN_4         (1UL << 4U)
#define TK_GPIO_PIN_5         (1UL << 5U)
#define TK_GPIO_PIN_6         (1UL << 6U)
#define TK_GPIO_PIN_7         (1UL << 7U)
#define TK_GPIO_PIN_8         (1UL << 8U)
#define TK_GPIO_PIN_9         (1UL << 9U)
#define TK_GPIO_PIN_10        (1UL << 10U)
#define TK_GPIO_PIN_11        (1UL << 11U)
#define TK_GPIO_PIN_12        (1UL << 12U)
#define TK_GPIO_PIN_13        (1UL << 13U)
#define TK_GPIO_PIN_14        (1UL << 14U)
#define TK_GPIO_PIN_15        (1UL << 15U)
#define TK_GPIO_PIN_ALL       (0xFFFFUL)

#define TK_GPIO_MODE_INPUT       (0x00000000UL)
#define TK_GPIO_MODE_OUTPUT_PP   (0x00000001UL)
#define TK_GPIO_MODE_OUTPUT_OD   (0x00000011UL)
#define TK_GPIO_MODE_AF_PP       (0x00000002UL)
#define TK_GPIO_MODE_AF_OD       (0x00000012UL)
#define TK_GPIO_MODE_ANALOG      (0x00000003UL)

#define TK_GPIO_NOPULL           (0x00000000UL)
#define TK_GPIO_PULLUP           (0x00000001UL)
#define TK_GPIO_PULLDOWN         (0x00000002UL)

#define TK_GPIO_SPEED_LOW        (0x00000000UL)
#define TK_GPIO_SPEED_MEDIUM     (0x00000001UL)
#define TK_GPIO_SPEED_HIGH       (0x00000002UL)
#define TK_GPIO_SPEED_VERY_HIGH  (0x00000003UL)

#define TK_GPIO_AF_0             (0x00000000UL)
#define TK_GPIO_AF_1             (0x00000001UL)
#define TK_GPIO_AF_2             (0x00000002UL)
#define TK_GPIO_AF_3             (0x00000003UL)
#define TK_GPIO_AF_4             (0x00000004UL)
#define TK_GPIO_AF_5             (0x00000005UL)
#define TK_GPIO_AF_6             (0x00000006UL)
#define TK_GPIO_AF_7             (0x00000007UL)
#define TK_GPIO_AF_8             (0x00000008UL)
#define TK_GPIO_AF_9             (0x00000009UL)
#define TK_GPIO_AF_10            (0x0000000AUL)
#define TK_GPIO_AF_11            (0x0000000BUL)
#define TK_GPIO_AF_12            (0x0000000CUL)
#define TK_GPIO_AF_13            (0x0000000DUL)
#define TK_GPIO_AF_14            (0x0000000EUL)
#define TK_GPIO_AF_15            (0x0000000FUL)

typedef struct
{
    uint32_t Pin;
    uint32_t Mode;
    uint32_t Pull;
    uint32_t Speed;
    uint32_t Alternate;
} TK_GPIO_InitTypeDef;

void TK_GPIO_ClockEnable(GPIO_TypeDef *GPIOx);
void TK_GPIO_Init(GPIO_TypeDef *GPIOx,
                  const TK_GPIO_InitTypeDef *GPIO_Init);
void TK_GPIO_DeInit(GPIO_TypeDef *GPIOx, uint32_t GPIO_Pin);
void TK_GPIO_WritePin(GPIO_TypeDef *GPIOx,
                      uint32_t GPIO_Pin,
                      TK_GPIO_PinState PinState);
TK_GPIO_PinState TK_GPIO_ReadPin(GPIO_TypeDef *GPIOx,
                                 uint32_t GPIO_Pin);
void TK_GPIO_TogglePin(GPIO_TypeDef *GPIOx, uint32_t GPIO_Pin);

#ifdef __cplusplus
}
#endif

#endif /* TK_GPIO_H */

头文件保护避免重复包含；extern "C" 让这套 C 接口以后可被 C++ 文件调用而不发生名称改编。头文件只放公开类型、宏和函数声明，内部校验函数与私有掩码留在 tk_gpio.c。

六实现 `tk_gpio.c`

6.1 初始化函数的总体流程

TK_GPIO_Init() 先拒绝空指针、未知端口、空引脚掩码、越界掩码和非法配置，再逐位处理被选中的引脚。

flowchart TD
    A["检查端口、指针、引脚掩码和配置值"] --> B["遍历 Pin0～Pin15"]
    B --> C{"当前位是否被 Pin 掩码选中"}
    C -- "否" --> B
    C -- "是" --> D["输出/复用：写 OSPEEDR 与 OTYPER"]
    D --> E["写 PUPDR；模拟模式强制无上下拉"]
    E --> F{"是否为复用模式"}
    F -- "是" --> G["写 AFR[0] 或 AFR[1]"]
    F -- "否" --> H["最后写 MODER"]
    G --> H
    H --> B

把 MODER 放在最后写，是为了让电气属性和复用功能先准备好，再让引脚真正切换模式。输出锁存值仍需像 2.4 所述，由 BSP 在调用初始化前预置。

6.2 时钟使能与回读

GPIO 位于 AHB1，总线时钟由 RCC->AHB1ENR 控制。GPIOB 对应 bit1：

RCC->AHB1ENR |= RCC_AHB1ENR_GPIOBEN;
(void)RCC->AHB1ENR;

第二行不是多余代码。STM32F407 的 ES0182 Rev 16 第 2.2.13 节说明，使能外设时钟后立即访问该外设可能需要延迟；官方 HAL 的 RCC 使能宏也通过一次回读形成所需等待。本章采用相同思路。

这里使用 |= 是为了保留 AHB1 上其他外设时钟位。它仍属于读—改—写，如果多个中断或任务在运行期无保护地同时修改 AHB1ENR，可能发生更新丢失。通常把时钟初始化集中在启动阶段；复杂系统应由 RCC/Clock 模块统一管理，而不是让每个外设驱动各自争用寄存器。

6.3 用 PB8 看懂读—改—写

PB8 在 MODER 中占 bit17:16。要把它写成输出模式 01，不能直接覆盖整个寄存器，否则同一端口的其他 15 个引脚会被一起改变。

uint32_t temp = GPIOB->MODER;
temp &= ~(0x3UL << 16U);  /* Clear PB8 field. */
temp |=  (0x1UL << 16U);  /* Select output mode. */
GPIOB->MODER = temp;

这是一次“读 → 改 → 写”：

读出完整寄存器。
用掩码只清除目标字段。
把新值放到目标位置。
写回完整寄存器。

对配置寄存器而言，这种操作直观且必要，但整个序列不是原子的。如果中断在第 1 步和第 4 步之间修改同一个寄存器，主线程最后写回的旧副本可能覆盖中断更新。因此同一端口的配置应明确所有者，并尽量集中在单线程初始化阶段。

6.4 为什么输出电平写 `BSRR`

BSRR 低 16 位是置位区，高 16 位是复位区：

写入位置	写 0	写 1
bit0～bit15	无影响	对应输出位置 1
bit16～bit31	无影响	对应输出位清 0

所以：

GPIOB->BSRR = TK_GPIO_PIN_2;          /* PB2 output high. */
GPIOB->BSRR = TK_GPIO_PIN_2 << 16U;   /* PB2 output low. */

BSRR 使用直接赋值，不使用 |=。一次写入可以同时设置一组位、复位另一组位，不需要先读 ODR，因此不会把同一端口其他输出位的状态带入写回过程。

NOTE

BSRR 只能保证“这一次写操作”按位生效。TK_GPIO_TogglePin() 必须先读取 ODR 才知道哪些位需要翻转，所以“读 ODR → 写 BSRR”整个过程仍可能和中断或其他任务竞争。

6.5 输入读取的返回语义

TK_GPIO_ReadPin() 读取 IDR：

return ((GPIOx->IDR & GPIO_Pin) != 0UL) ?
       TK_GPIO_PIN_SET : TK_GPIO_PIN_RESET;

传入单个引脚时，返回值就是该引脚电平。传入多个引脚时，只要其中任意一个为高就返回 TK_GPIO_PIN_SET，它不能告诉调用者具体哪一位为高。因此读取输入通常一次传一个 TK_GPIO_PIN_x；若要获得整组位状态，应另设计返回掩码的端口读取接口。

6.6 `DeInit` 恢复的是教学默认值

本章的 TK_GPIO_DeInit() 先把目标引脚切换为输入，再清除其复用、上下拉、输出类型和速度配置；它不修改 ODR 锁存值，也不处理 SYSCFG/EXTI。

这不是严格的“恢复芯片复位值”。PB3、PB4 等引脚的真实复位模式并非普通输入，且不同端口、封装可能有调试或晶振相关默认状态。需要恢复真实复位状态时，应使用 RCC 的端口复位机制或按 RM0090 Rev 21 的复位值逐项处理，并评估对同一端口其他引脚的影响。

6.7 完整 `tk_gpio.c`

新建 Drivers/TK_GPIO/Src/tk_gpio.c：

/**
 * @file tk_gpio.c
 * @author LCKFB-YZH
 * @brief 教学用 STM32F407 GPIO 驱动实现。
 */

#include "tk_gpio.h"

#define TK_GPIO_MODE_FIELD_MASK  (0x3UL)
#define TK_GPIO_TYPE_FIELD_MASK  (0x10UL)
#define TK_GPIO_FIELD_2BIT_MASK  (0x3UL)
#define TK_GPIO_FIELD_4BIT_MASK  (0xFUL)
#define TK_GPIO_PIN_COUNT        (16U)

static uint32_t TK_GPIO_IsValidInstance(const GPIO_TypeDef *GPIOx)
{
    return ((GPIOx == GPIOA) || (GPIOx == GPIOB) ||
            (GPIOx == GPIOC) || (GPIOx == GPIOD) ||
            (GPIOx == GPIOE) || (GPIOx == GPIOF) ||
            (GPIOx == GPIOG) || (GPIOx == GPIOH) ||
            (GPIOx == GPIOI)) ? 1UL : 0UL;
}

static uint32_t TK_GPIO_IsValidPinMask(uint32_t GPIO_Pin)
{
    return ((GPIO_Pin != 0UL) &&
            ((GPIO_Pin & ~TK_GPIO_PIN_ALL) == 0UL)) ? 1UL : 0UL;
}

static uint32_t TK_GPIO_IsValidMode(uint32_t Mode)
{
    return ((Mode == TK_GPIO_MODE_INPUT) ||
            (Mode == TK_GPIO_MODE_OUTPUT_PP) ||
            (Mode == TK_GPIO_MODE_OUTPUT_OD) ||
            (Mode == TK_GPIO_MODE_AF_PP) ||
            (Mode == TK_GPIO_MODE_AF_OD) ||
            (Mode == TK_GPIO_MODE_ANALOG)) ? 1UL : 0UL;
}

static uint32_t TK_GPIO_IsAlternateMode(uint32_t Mode)
{
    return (((Mode & TK_GPIO_MODE_FIELD_MASK) ==
             (TK_GPIO_MODE_AF_PP & TK_GPIO_MODE_FIELD_MASK))) ? 1UL : 0UL;
}

static uint32_t TK_GPIO_IsOutputOrAlternateMode(uint32_t Mode)
{
    const uint32_t mode_field = Mode & TK_GPIO_MODE_FIELD_MASK;

    return ((mode_field ==
             (TK_GPIO_MODE_OUTPUT_PP & TK_GPIO_MODE_FIELD_MASK)) ||
            (mode_field ==
             (TK_GPIO_MODE_AF_PP & TK_GPIO_MODE_FIELD_MASK))) ? 1UL : 0UL;
}

static uint32_t TK_GPIO_GetClockMask(const GPIO_TypeDef *GPIOx)
{
    uint32_t clock_mask = 0UL;

    if (GPIOx == GPIOA)
    {
        clock_mask = RCC_AHB1ENR_GPIOAEN;
    }
    else if (GPIOx == GPIOB)
    {
        clock_mask = RCC_AHB1ENR_GPIOBEN;
    }
    else if (GPIOx == GPIOC)
    {
        clock_mask = RCC_AHB1ENR_GPIOCEN;
    }
    else if (GPIOx == GPIOD)
    {
        clock_mask = RCC_AHB1ENR_GPIODEN;
    }
    else if (GPIOx == GPIOE)
    {
        clock_mask = RCC_AHB1ENR_GPIOEEN;
    }
    else if (GPIOx == GPIOF)
    {
        clock_mask = RCC_AHB1ENR_GPIOFEN;
    }
    else if (GPIOx == GPIOG)
    {
        clock_mask = RCC_AHB1ENR_GPIOGEN;
    }
    else if (GPIOx == GPIOH)
    {
        clock_mask = RCC_AHB1ENR_GPIOHEN;
    }
    else if (GPIOx == GPIOI)
    {
        clock_mask = RCC_AHB1ENR_GPIOIEN;
    }
    else
    {
        /* Invalid instances are rejected by the caller. */
    }

    return clock_mask;
}

void TK_GPIO_ClockEnable(GPIO_TypeDef *GPIOx)
{
    uint32_t clock_mask;

    if (TK_GPIO_IsValidInstance(GPIOx) == 0UL)
    {
        return;
    }

    clock_mask = TK_GPIO_GetClockMask(GPIOx);
    RCC->AHB1ENR |= clock_mask;

    /* Read back once so the clock is active before GPIO access. */
    (void)RCC->AHB1ENR;
}

void TK_GPIO_Init(GPIO_TypeDef *GPIOx,
                  const TK_GPIO_InitTypeDef *GPIO_Init)
{
    uint32_t position;
    uint32_t mode_field;

    if ((GPIO_Init == NULL) ||
        (TK_GPIO_IsValidInstance(GPIOx) == 0UL) ||
        (TK_GPIO_IsValidPinMask(GPIO_Init->Pin) == 0UL) ||
        (TK_GPIO_IsValidMode(GPIO_Init->Mode) == 0UL) ||
        (GPIO_Init->Pull > TK_GPIO_PULLDOWN) ||
        (GPIO_Init->Speed > TK_GPIO_SPEED_VERY_HIGH) ||
        ((TK_GPIO_IsAlternateMode(GPIO_Init->Mode) != 0UL) &&
         (GPIO_Init->Alternate > TK_GPIO_AF_15)))
    {
        return;
    }

    mode_field = GPIO_Init->Mode & TK_GPIO_MODE_FIELD_MASK;

    for (position = 0U; position < TK_GPIO_PIN_COUNT; ++position)
    {
        const uint32_t pin_mask = 1UL << position;
        const uint32_t shift_2bit = position * 2U;
        uint32_t temp;

        if ((GPIO_Init->Pin & pin_mask) == 0UL)
        {
            continue;
        }

        if (TK_GPIO_IsOutputOrAlternateMode(GPIO_Init->Mode) != 0UL)
        {
            temp = GPIOx->OSPEEDR;
            temp &= ~(TK_GPIO_FIELD_2BIT_MASK << shift_2bit);
            temp |= GPIO_Init->Speed << shift_2bit;
            GPIOx->OSPEEDR = temp;

            temp = GPIOx->OTYPER;
            temp &= ~pin_mask;
            temp |= ((GPIO_Init->Mode & TK_GPIO_TYPE_FIELD_MASK) >> 4U)
                    << position;
            GPIOx->OTYPER = temp;
        }

        temp = GPIOx->PUPDR;
        temp &= ~(TK_GPIO_FIELD_2BIT_MASK << shift_2bit);
        if (mode_field != TK_GPIO_MODE_ANALOG)
        {
            temp |= GPIO_Init->Pull << shift_2bit;
        }
        GPIOx->PUPDR = temp;

        if (TK_GPIO_IsAlternateMode(GPIO_Init->Mode) != 0UL)
        {
            const uint32_t afr_index = position >> 3U;
            const uint32_t afr_shift = (position & 0x7U) * 4U;

            temp = GPIOx->AFR[afr_index];
            temp &= ~(TK_GPIO_FIELD_4BIT_MASK << afr_shift);
            temp |= GPIO_Init->Alternate << afr_shift;
            GPIOx->AFR[afr_index] = temp;
        }

        /* Switch the pin mode last to reduce output transients. */
        temp = GPIOx->MODER;
        temp &= ~(TK_GPIO_FIELD_2BIT_MASK << shift_2bit);
        temp |= mode_field << shift_2bit;
        GPIOx->MODER = temp;
    }
}

void TK_GPIO_DeInit(GPIO_TypeDef *GPIOx, uint32_t GPIO_Pin)
{
    uint32_t position;

    if ((TK_GPIO_IsValidInstance(GPIOx) == 0UL) ||
        (TK_GPIO_IsValidPinMask(GPIO_Pin) == 0UL))
    {
        return;
    }

    for (position = 0U; position < TK_GPIO_PIN_COUNT; ++position)
    {
        const uint32_t pin_mask = 1UL << position;
        const uint32_t shift_2bit = position * 2U;
        const uint32_t afr_index = position >> 3U;
        const uint32_t afr_shift = (position & 0x7U) * 4U;
        uint32_t temp;

        if ((GPIO_Pin & pin_mask) == 0UL)
        {
            continue;
        }

        /* Release the pin first, then clear the remaining configuration. */
        temp = GPIOx->MODER;
        temp &= ~(TK_GPIO_FIELD_2BIT_MASK << shift_2bit);
        GPIOx->MODER = temp;

        temp = GPIOx->AFR[afr_index];
        temp &= ~(TK_GPIO_FIELD_4BIT_MASK << afr_shift);
        GPIOx->AFR[afr_index] = temp;

        temp = GPIOx->PUPDR;
        temp &= ~(TK_GPIO_FIELD_2BIT_MASK << shift_2bit);
        GPIOx->PUPDR = temp;

        GPIOx->OTYPER &= ~pin_mask;

        temp = GPIOx->OSPEEDR;
        temp &= ~(TK_GPIO_FIELD_2BIT_MASK << shift_2bit);
        GPIOx->OSPEEDR = temp;
    }
}

void TK_GPIO_WritePin(GPIO_TypeDef *GPIOx,
                      uint32_t GPIO_Pin,
                      TK_GPIO_PinState PinState)
{
    if ((TK_GPIO_IsValidInstance(GPIOx) == 0UL) ||
        (TK_GPIO_IsValidPinMask(GPIO_Pin) == 0UL) ||
        ((PinState != TK_GPIO_PIN_RESET) &&
         (PinState != TK_GPIO_PIN_SET)))
    {
        return;
    }

    if (PinState == TK_GPIO_PIN_SET)
    {
        GPIOx->BSRR = GPIO_Pin;
    }
    else
    {
        GPIOx->BSRR = GPIO_Pin << 16U;
    }
}

TK_GPIO_PinState TK_GPIO_ReadPin(GPIO_TypeDef *GPIOx,
                                 uint32_t GPIO_Pin)
{
    if ((TK_GPIO_IsValidInstance(GPIOx) == 0UL) ||
        (TK_GPIO_IsValidPinMask(GPIO_Pin) == 0UL))
    {
        return TK_GPIO_PIN_RESET;
    }

    return ((GPIOx->IDR & GPIO_Pin) != 0UL) ?
           TK_GPIO_PIN_SET : TK_GPIO_PIN_RESET;
}

void TK_GPIO_TogglePin(GPIO_TypeDef *GPIOx, uint32_t GPIO_Pin)
{
    uint32_t odr;
    uint32_t set_mask;
    uint32_t reset_mask;

    if ((TK_GPIO_IsValidInstance(GPIOx) == 0UL) ||
        (TK_GPIO_IsValidPinMask(GPIO_Pin) == 0UL))
    {
        return;
    }

    odr = GPIOx->ODR;
    set_mask = (~odr) & GPIO_Pin;
    reset_mask = odr & GPIO_Pin;
    GPIOx->BSRR = set_mask | (reset_mask << 16U);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287

6.8 用 PB2/PB8 推导初始化结果

BSP_LED_Init() 给两个引脚使用相同配置：

init.Pin = TK_GPIO_PIN_2 | TK_GPIO_PIN_8;
init.Mode = TK_GPIO_MODE_OUTPUT_PP;
init.Pull = TK_GPIO_NOPULL;
init.Speed = TK_GPIO_SPEED_LOW;

各寄存器目标字段为：

寄存器	PB2 字段	PB8 字段	目标值
`RCC->AHB1ENR`	GPIOB 时钟 bit1	同一端口共用	bit1 = 1
`GPIOB->MODER`	bit5:4	bit17:16	`01`
`GPIOB->OTYPER`	bit2	bit8	`0`，推挽
`GPIOB->OSPEEDR`	bit5:4	bit17:16	`00`，低速
`GPIOB->PUPDR`	bit5:4	bit17:16	`00`，无上下拉
`GPIOB->ODR`	bit2	bit8	初始分别为 0、1

判断寄存器是否正确时只检查目标字段，不要把整个 MODER 和 0 比较。GPIOB 其他位可能保留调试接口的复位配置，调试器或其他模块也可能已经配置同端口其他引脚。

6.9 参数保护能做什么、不能做什么

本章会拒绝以下参数：

GPIOx 不是 GPIOA～GPIOI；
初始化结构体为空；
引脚掩码为 0 或超出 bit15；
模式、上下拉、速度不在已定义范围；
复用模式下 Alternate > 15；
写引脚时状态不是 RESET/SET。

接口返回 void，非法参数只会提前返回。这符合教学库保持接口简洁的目标，但不适合需要故障可观测性的安全关键或量产项目。工程化版本可以增加错误码、调试断言、错误钩子和单元测试。

七用 BSP 隔离 LED 极性

7.1 为什么还要再封装一层

TK_GPIO_WritePin() 只理解物理电平，不应该知道天空星开发板或者筑基学习板上哪颗 LED 是低电平有效。BSP 用一张描述表保存端口、引脚和点亮状态：

BSP 设备	端口	引脚	`ActiveState`
`BSP_LED_CORE`	GPIOB	Pin2	`TK_GPIO_PIN_SET`
`BSP_LED_BASE`	GPIOB	Pin8	`TK_GPIO_PIN_RESET`

这样 BSP_LED_Set(led, 1) 始终表示点亮，电平换算只发生在 BSP 内部。

7.2 完整 `bsp_led.h`

新建 Bsp/Inc/bsp_led.h：

/**
 * @file bsp_led.h
 * @author LCKFB-YZH
 * @brief 天空星核心板与筑基学习板 LED 板级接口。
 */

#ifndef BSP_LED_H
#define BSP_LED_H

#include "tk_gpio.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef enum
{
    BSP_LED_CORE = 0U,
    BSP_LED_BASE,
    BSP_LED_COUNT
} BSP_LED_Id;

void BSP_LED_Init(void);
void BSP_LED_Set(BSP_LED_Id led, uint32_t is_on);
void BSP_LED_Toggle(BSP_LED_Id led);

#ifdef __cplusplus
}
#endif

#endif /* BSP_LED_H */

7.3 完整 `bsp_led.c`

新建 Bsp/Src/bsp_led.c：

/**
 * @file bsp_led.c
 * @author LCKFB-YZH
 * @brief 天空星核心板与筑基学习板 LED 板级实现。
 */

#include "bsp_led.h"

typedef struct
{
    GPIO_TypeDef *Port;
    uint32_t Pin;
    TK_GPIO_PinState ActiveState;
} BSP_LED_Descriptor;

static const BSP_LED_Descriptor s_leds[BSP_LED_COUNT] =
{
    {GPIOB, TK_GPIO_PIN_2, TK_GPIO_PIN_SET},
    {GPIOB, TK_GPIO_PIN_8, TK_GPIO_PIN_RESET}
};

void BSP_LED_Init(void)
{
    TK_GPIO_InitTypeDef init = {0};

    TK_GPIO_ClockEnable(GPIOB);

    /* Preload the inactive levels before changing MODER to output. */
    TK_GPIO_WritePin(GPIOB, TK_GPIO_PIN_2, TK_GPIO_PIN_RESET);
    TK_GPIO_WritePin(GPIOB, TK_GPIO_PIN_8, TK_GPIO_PIN_SET);

    init.Pin = TK_GPIO_PIN_2 | TK_GPIO_PIN_8;
    init.Mode = TK_GPIO_MODE_OUTPUT_PP;
    init.Pull = TK_GPIO_NOPULL;
    init.Speed = TK_GPIO_SPEED_LOW;
    init.Alternate = TK_GPIO_AF_0;
    TK_GPIO_Init(GPIOB, &init);
}

void BSP_LED_Set(BSP_LED_Id led, uint32_t is_on)
{
    TK_GPIO_PinState state;

    if (led >= BSP_LED_COUNT)
    {
        return;
    }

    state = s_leds[led].ActiveState;
    if (is_on == 0UL)
    {
        state = (state == TK_GPIO_PIN_SET) ?
                TK_GPIO_PIN_RESET : TK_GPIO_PIN_SET;
    }

    TK_GPIO_WritePin(s_leds[led].Port, s_leds[led].Pin, state);
}

void BSP_LED_Toggle(BSP_LED_Id led)
{
    if (led >= BSP_LED_COUNT)
    {
        return;
    }

    TK_GPIO_TogglePin(s_leds[led].Port, s_leds[led].Pin);
}

7.4 完整 `main.c`

新建 Core/Src/main.c：

/**
 * @file main.c
 * @author LCKFB-YZH
 * @brief 使用自制 GPIO 库控制两颗不同有效电平的 LED。
 */

#include "bsp_led.h"

static void DelaySimple(uint32_t cycles);

int main(void)
{
    BSP_LED_Init();

    while (1)
    {
        BSP_LED_Toggle(BSP_LED_CORE);
        BSP_LED_Toggle(BSP_LED_BASE);
        DelaySimple(500000UL);
    }
}

void SystemInit(void)
{
    /* 保持复位后的 HSI 时钟，满足本章最小工程需要。 */
}

static void DelaySimple(uint32_t cycles)
{
    while (cycles > 0UL)
    {
        __asm volatile ("nop");
        --cycles;
    }
}

启动文件会先调用 SystemInit() 再调用 main()，所以最小工程需要提供这个符号。本章保持复位后的 HSI 时钟，不做系统时钟树配置。如果工程已经加入官方 system_stm32f4xx.c，应删除 main.c 中这个空实现，避免 SystemInit 重复定义。

DelaySimple() 只是可见效果用的阻塞延时。实际时长受系统频率、编译器版本和优化等级影响，不能用于通信时序、超时保护或任务调度。

八从零接入工程

8.1 先规划目录

将工程整理成下面的结构。启动文件、链接脚本、SVD 和工程配置来自 1.2 的最小工程，新增文件按职责分目录：

text

custom-gpio-library/
├── Bsp/
│   ├── Inc/
│   │   └── bsp_led.h
│   └── Src/
│       └── bsp_led.c
├── Core/
│   ├── Inc/
│   │   └── tkx_stm32f407.h
│   └── Src/
│       └── main.c
├── Drivers/
│   └── TK_GPIO/
│       ├── Inc/
│       │   └── tk_gpio.h
│       └── Src/
│           └── tk_gpio.c
├── startup_stm32f407xx.s
├── STM32F407VEX.ld
├── STM32F407.svd
└── IDE 或 CMake 工程文件

Core 放芯片入口和最小芯片描述，Drivers 放与具体开发板无关的 GPIO 驱动，Bsp 放天空星板级资源。后续增加按键或蜂鸣器时，不要把它们的引脚定义塞进 tk_gpio.h。

8.2 获取启动文件时必须匹配工具链

startup_stm32f407xx.s 完成初始栈指针、中断向量、.data/.bss 初始化，并调用 SystemInit() 和 main()。同名启动文件可能分别采用 Arm、GCC 或 IAR 汇编语法，不能混用：

工具链	STM32CubeF4 模板目录	本章使用场景
Arm Compiler	`Source/Templates/arm`	Keil MDK
Arm GNU Toolchain	`Source/Templates/gcc`	EIDE、CLion/CMake
IAR	`Source/Templates/iar`	本章不展开

最稳妥的做法是直接使用 1.2 配套工程中对应 IDE 的启动文件。也可以从 ST 官方 CMSIS Device F4 仓库获取模板，但要保持启动文件、编译器、链接脚本和目标芯片一致。

STM32F407VEX.ld 按 STM32F407VET6 的 512 KiB Flash 配置。高配版 STM32F407VGT6 有更大 Flash，使用 VE 的较小配置仍可运行本章程序，但正式工程应按实际料号选择正确链接脚本，防止链接器错误估计可用空间。

8.3 Keil MDK 创建与接入

第一次实践推荐使用 Keil，按下面步骤可以从空目录建立工程【请重点去参考第九章的软件使用教程】】：

新建 custom-gpio-library 文件夹，按 8.1 创建子目录并放入源码。
打开 Keil，选择 Project → New µVision Project...，把工程保存在该文件夹。
低配核心板选择 STM32F407VETx，高配核心板选择 STM32F407VGTx。
弹出 Manage Run-Time Environment 时不要再添加另一套 Startup；本章使用手工加入的启动文件。
建立 Core、TK_GPIO、BSP、Startup 四个 Group。
右键 Group 选择 Add Existing Files to Group...，加入对应的 .c 与 Arm 版本 startup_stm32f407xx.s。
打开 Options for Target → C/C++ → Include Paths，加入：
- .\Core\Inc
- .\Drivers\TK_GPIO\Inc
- .\Bsp\Inc
本章 SystemInit() 没有开启浮点单元，Target 页的 Floating Point Hardware 选择 Not Used。如果改用官方 system_stm32f4xx.c 并按官方流程开启 FPU，再与编译器选项保持一致。

Keil 新建工程入口如下：

选择与核心板实际料号对应的 STM32F407：

添加已有源码文件时使用下面的入口：

最小 SystemInit() 与浮点选项的对应设置如下：

8.4 VS Code + EIDE 创建与接入

使用 EIDE 时按以下步骤操作：

在 VS Code 左侧打开 EIDE，选择“新建项目 → 空项目 → Cortex-M 项目”。
工具链选择已安装的 Arm GNU Toolchain，CPU 选择 Cortex-M4。
使用 GCC 版本 startup_stm32f407xx.s 与 STM32F407VEX.ld。
把 8.1 的源码放入项目，右键“项目资源”将 .c 和 .s 文件加入构建。
在 C/C++ 包含目录中加入 Core/Inc、Drivers/TK_GPIO/Inc、Bsp/Inc。
将 SVD 文件设为 STM32F407.svd，方便调试时按名称查看 RCC 和 GPIOB。
最小 SystemInit() 未开启 FPU，编译选项采用 soft/no-FPU；若使用 hard-float，必须先用官方系统初始化代码正确使能 FPU。

从 EIDE 入口新建空 Cortex-M 工程：

通过“项目资源”添加源码和启动文件：

8.5 CLion/CMake 接入

使用 1.2 配套工程的 project 目录时，保留 gcc-arm-none-eabi.cmake、STM32F407VEX.ld、startup_stm32f407xx.s 和 lckfb-skystar.cfg。本章空 SystemInit() 没有使能 FPU，应先把工具链文件中的 TARGET_FLAGS 调整为不生成硬件浮点指令：

cmake

set(TARGET_FLAGS "-mcpu=cortex-m4 -mthumb -mfloat-abi=soft")

然后把 CMakeLists.txt 的源文件与包含目录改成：

cmake

target_sources(project PRIVATE
    Core/Src/main.c
    Drivers/TK_GPIO/Src/tk_gpio.c
    Bsp/Src/bsp_led.c
    startup_stm32f407xx.s
)

target_include_directories(project PRIVATE
    Core/Inc
    Drivers/TK_GPIO/Inc
    Bsp/Inc
)

然后执行：

powershell

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j

如果 CMake 找不到 arm-none-eabi-gcc，先确认工具链的 bin 已加入 PATH，或在 Toolchain 配置中使用编译器绝对路径。若链接提示 undefined reference to TK_GPIO_Init，说明 tk_gpio.c 没加入 target_sources；若编译提示找不到 tk_gpio.h，说明包含目录不完整。

九编译、下载与调试闭环

9.1 先完成编译

本章完整 C 代码已使用 Arm GNU Toolchain 13.3.1、C11 和 -Wall -Wextra -Wpedantic -Wconversion -Wshadow -Wundef 完成编译检查，并与配套 GCC 启动文件、STM32F407VET6 链接脚本生成 ELF 文件。这个结果只能证明源码和链接关系成立，不能替代目标板上的下载与实机测试。

在 Keil 中点击 Rebuild：

构建成功至少应满足：

tk_gpio.c、bsp_led.c、main.c 和启动文件都出现在构建过程；
0 Error；
没有本章源码警告；
生成 .axf 或 .elf；
Map 文件中能找到 TK_GPIO_Init、BSP_LED_Init 和 main。

9.2 配置 DAPLink 并下载

Keil 下载步骤如下：

确认 DAPLink 与开发板按 2.1 连接，开发板已供电。
打开 Options for Target → Debug，选择 CMSIS-DAP Debugger。
点击 Settings，选择 LCKFB DAPLink，端口使用 SWD；右侧应能识别目标器件。
如果识别不稳定，把 SWD Clock 从较高值降到 1 MHz 再试，并检查 GND/SWDIO/SWCLK。
在 Flash Download 页勾选 Reset and Run。
在 Utilities 页勾选 Use Debug Driver。
重新构建后点击 Download。输出窗口应显示擦除、编程和校验成功，随后程序自动运行。

选择 CMSIS-DAP 并确认能识别 SWD 目标：

下载后自动复位运行：

9.3 用调用栈确认分层真的生效

进入 Debug，在 BSP_LED_Init() 第一行设置断点。程序停住后单步进入，应看到调用路径：

text

main
└── BSP_LED_Init
    ├── TK_GPIO_ClockEnable
    ├── TK_GPIO_WritePin
    └── TK_GPIO_Init

这一步不只是确认代码“执行到了”。它同时检查：

启动文件成功进入 main；
BSP 和驱动源码确实参与链接；
符号与调试信息可用；
应用层没有绕过 BSP 直接写寄存器。

9.4 检查寄存器字段

让程序执行完 BSP_LED_Init()，在 while (1) 前暂停。使用 Peripheral/SVD 窗口查看命名字段，也可以在 Memory 窗口查看地址：

对象	地址	期望字段
`RCC->AHB1ENR`	`0x4002 3830`	`GPIOBEN = 1`
`GPIOB->MODER`	`0x4002 0400`	PB2、PB8 均为 `01`
`GPIOB->OTYPER`	`0x4002 0404`	PB2、PB8 均为 `0`
`GPIOB->OSPEEDR`	`0x4002 0408`	PB2、PB8 均为 `00`
`GPIOB->PUPDR`	`0x4002 040C`	PB2、PB8 均为 `00`
`GPIOB->ODR`	`0x4002 0414`	bit2 = 0、bit8 = 1，两灯初始熄灭

用掩码核对时，(GPIOB->MODER & 0x00030030UL) 应为 0x00010010UL；(GPIOB->ODR & 0x0104UL) 初始应为 0x0100UL。只比较目标位，其他位不作要求。

9.5 单步观察 `BSRR` 与 `ODR`

在 TK_GPIO_TogglePin() 的最后一行设置断点。第一次翻转前：

PB2 的 ODR 位为 0，需要在 BSRR 低半区写 bit2；
PB8 的 ODR 位为 1，需要在 BSRR 高半区写 bit8。

两个 BSP 调用完成后，(GPIOB->ODR & 0x0104UL) 应由 0x0100 变为 0x0004，两颗 LED 同时进入逻辑点亮状态。下一轮又回到 0x0100。

调试器对只写寄存器的显示可能为 0、旧值或不可用， BSRR 的寄存器回读是没有意义的。真正结果应通过 ODR、引脚电平和 LED 现象交叉验证。

9.6 观察两颗 LED 的最终现象

退出调试或继续全速运行。正确现象是：

复位后两颗 LED 先保持熄灭，不应明显闪一下。
核心板 PB2 LED 与筑基学习板 PB8 LED 同步点亮、同步熄灭。
两颗灯的引脚电平始终相反，但逻辑状态相同。
闪烁快慢只用于观察，不作为定时精度验收项。

十工程师还应看懂的设计边界

10.1 与官方 HAL 的接口对应

本章接口刻意采用与 HAL 相近的使用方式，但使用 TK_GPIO_ 前缀避免符号冲突：

本章接口	官方 HAL 接口	主要区别
`TK_GPIO_InitTypeDef`	`GPIO_InitTypeDef`	本章仅覆盖 GPIO 基本配置
`TK_GPIO_Init`	`HAL_GPIO_Init`	HAL 还处理 EXTI 等模式和官方参数断言
`TK_GPIO_DeInit`	`HAL_GPIO_DeInit`	本章恢复统一教学默认值
`TK_GPIO_WritePin`	`HAL_GPIO_WritePin`	都通过 `BSRR` 写电平
`TK_GPIO_ReadPin`	`HAL_GPIO_ReadPin`	单引脚返回语义相近
`TK_GPIO_TogglePin`	`HAL_GPIO_TogglePin`	都先读 `ODR`，再写 `BSRR`

可以直接对照 ST 官方 stm32f4xx_hal_gpio.c 和 stm32f4xx_hal_gpio.h。官方实现同样先配置速度、输出类型、上下拉和复用功能，最后写 MODER；本章没有照搬源码，而是保留最小可读实现并明确其能力边界。

10.2 `volatile` 不等于线程安全

volatile 只约束编译器必须实际访问寄存器，不能提供以下保证：

多条指令组成的读—改—写原子性；
中断与任务之间的互斥；
多核系统的缓存一致性；
业务操作的先后顺序正确；
参数或寄存器值合法。

在本章单线程初始化和主循环中，不会有并发写者。进入 RTOS、ISR 或 DMA 驱动工程后，应明确每个端口和寄存器的所有者：

场景	风险	推荐处理
初始化阶段修改 `MODER/PUPDR`	通常无并发	集中在启动阶段配置
任务和 ISR 同时改同一配置寄存器	RMW 更新丢失	禁止运行期并发配置，或在临界区修改
多个上下文只设置/复位不同输出位	直接写 `BSRR`	每次写可按位生效，仍要定义业务所有权
多个上下文调用 `TogglePin`	读 `ODR` 后状态可能变化	加锁/临界区，或由单一任务维护期望状态
多模块修改 `RCC->AHB1ENR`	端口时钟位更新丢失	由统一 RCC 模块管理

10.3 输出模式最后写，安全电平更早写

官方 HAL 把 MODER 放在 GPIO 初始化靠后位置，本章进一步让 BSP 在调用 TK_GPIO_Init() 前预置 ODR。这两层措施解决的是不同问题：

驱动层先准备输出类型、速度、上下拉和 AF，减少模式切换期间的中间状态。
板级层先准备负载安全电平，避免输出模式一生效就点亮 LED、拉低片选或启动电机驱动。

对继电器、MOS 管、片选、复位脚和电源使能脚，初始化默认电平属于硬件安全需求，不能只靠函数调用顺序“碰巧正确”。量产设计还应结合外部上下拉，保证 MCU 复位、下载和程序尚未运行期间也处于安全状态。

10.4 `DeInit`、端口复位和真实复位值

三个动作不要混为一谈：

动作	作用范围	特点
本章 `TK_GPIO_DeInit(pin)`	指定引脚的几个 GPIO 配置字段	不改 `ODR`，不处理 EXTI，不保证真实复位值
官方 HAL `HAL_GPIO_DeInit(pin)`	指定引脚，并处理 HAL 覆盖的关联配置	语义按官方版本实现
RCC 端口复位	整个 GPIO 端口	更接近硬件复位，会影响该端口全部引脚

如果一个端口同时连接显示屏、SD 卡和状态 LED，不能为了释放一个 LED 就复位整个端口。资源所有权和影响范围要先设计，再决定反初始化策略。

10.5 代码大小与维护成本要同条件比较

“寄存器库一定比 HAL 小”不能作为没有数据的结论。最终 Flash/RAM 取决于编译器、优化等级、链接时垃圾回收、启用的 HAL 模块、断言、日志和链接库。公平比较至少要保持：

同一芯片、启动文件和链接脚本；
同一编译器版本与优化等级；
同一功能和初始化结果；
同样开启或关闭 -ffunction-sections、--gc-sections；
使用 Map/size 输出，而不是只比较源码行数。

10.6 位带可以做单 bit 访问，但不是首选接口

Cortex-M4 的外设位带（bit-band）可以把位带区中的一个 bit 映射为别名区中的一个 32 位字。GPIOB 位于外设位带区内，因此理论上可以通过别名地址原子读写 ODR 的单个位，地址关系见 PM0214 Rev 10。

本章仍选择 BSRR：

语义直接对应 GPIO 的置位/复位功能；
一次写可以同时设置和复位多个输出位；
代码更容易和 STM32 HAL、参考手册交叉核对；
位带不是所有 Cortex-M 内核和 STM32 系列都支持，移植边界更大。

如果项目使用位带，必须用官方内核与芯片资料确认支持范围，不能把 Cortex-M4 的别名地址公式复制到 Cortex-M7、RISC-V 或其他 MCU。

十一常见问题

11.1 提示 `undefined reference to TK_GPIO_Init`

现象： 头文件不报错，链接阶段提示找不到 TK_GPIO_Init。

原因： 编译器看到了 tk_gpio.h 的声明，但 tk_gpio.c 没有参与构建。

检查：

构建日志中是否出现 tk_gpio.c。
Keil Group 或 EIDE 项目资源中是否真正加入文件。
CMake 的 target_sources 是否包含该路径。

解决： 把 tk_gpio.c 加入当前目标并执行全量重建；只把文件复制进目录还不等于参加编译。

11.2 提示找不到 `tk_gpio.h` 或 `tkx_stm32f407.h`

现象： 编译时报 No such file or directory。

原因： 包含路径未配置，或目录层级与 #include 写法不一致。

检查： 确认 Core/Inc、Drivers/TK_GPIO/Inc、Bsp/Inc 均在编译器 Include Paths 中。

解决： 增加缺失路径后全量重建，不要用跨越多级目录的 ../../../ 临时绕过工程配置。

11.3 能下载，但两颗 LED 都不闪

现象： 下载成功，程序似乎在运行，LED 无变化。

原因： 常见于 GPIOB 时钟未开启、SystemInit 重复/缺失、程序没有进入 main、启动文件与工具链不匹配。

检查：

在 main 和 BSP_LED_Init 设置断点。
查看 RCC->AHB1ENR.GPIOBEN 是否为 1。
查看调用栈是否从 Reset Handler 进入 main。
检查是否误用了 GCC/Arm 不匹配的启动文件。

解决： 先恢复到 9.3 的调用栈闭环，再检查 GPIO 字段，不要只靠反复修改延时次数排查。

11.4 PB2 正常，PB8 的亮灭相反

现象： PB2 符合预期，PB8 在调用“灭”时反而点亮。

原因： PB8 LED 是低电平有效，应用层直接按物理高低电平控制，或 BSP 描述表把 ActiveState 写成了 SET。

检查： 查看 s_leds[BSP_LED_BASE] 是否为 TK_GPIO_PIN_RESET，并对照 2.3 原理图。

解决： 让应用只调用 BSP_LED_Set/BSP_LED_Toggle，把有效电平留在 BSP 内部转换。

11.5 复位瞬间 LED 闪一下

现象： 正常运行后闪烁正确，但复位或重新下载时 LED 短暂点亮。

原因： MODER 先切到输出，ODR 的旧锁存值随后才被修改；也可能是 MCU 复位期间外部电路没有提供确定默认电平。

检查：

BSP_LED_Init 是否先写 PB2=0、PB8=1。
TK_GPIO_Init 是否最后写 MODER。
用示波器观察复位期间引脚，而不是只看肉眼。

解决： 保持“先预置安全电平、最后切模式”；对高风险负载增加合适的外部上下拉或硬件使能门控。

11.6 调试器里 `BSRR` 总是 0

现象： 单步写 BSRR 后，Peripheral 窗口仍显示 0。

原因： BSRR 是写入命令语义，回读值不能作为执行结果；不同调试器对只写寄存器的显示也不同。

检查： 观察 ODR 对应位、引脚实测电平和 LED 状态。

解决： 按 9.5 交叉验证，不要用 BSRR 回读判断写入是否成功。

十二总结、练习与参考资料

12.1 本章小结

本章完成了一个可编译、可链接、可接入真实工程的最小 GPIO 库，并用天空星两颗有效电平相反的 LED 验证分层设计：

tkx_stm32f407.h 用基地址、结构体成员和偏移断言描述芯片。
tk_gpio.h/.c 用位掩码和初始化结构体统一 GPIO 配置。
配置寄存器使用读—改—写保留其他引脚，输出电平使用 BSRR。
初始化先准备电气配置、最后写 MODER，BSP 更早预置安全电平。
bsp_led.c 隔离 PB2 高有效与 PB8 低有效差异。
编译、调用栈、寄存器、ODR、LED 和双通道波形共同组成验证闭环。

真正重要的不是记住 TK_GPIO_ 这个前缀，而是能把官方手册中的地址和位域，转化为边界清晰、可核对、可维护的驱动代码。

12.2 动手练习

按难度从低到高完成：

增加 BSP_LED_AllSet(uint32_t is_on)，让上层用一次函数调用控制两颗灯。
新增输入接口实例，选择一个已确认硬件连接的按键引脚，配置内部上下拉并读取 IDR。
给 TK_GPIO_Init 增加错误码，区分空指针、非法端口、非法掩码和非法 AF。
设计 TK_GPIO_WriteMasked(GPIOx, set_mask, reset_mask)，检查两组掩码重叠时如何处理。

12.3 延伸阅读

如果希望继续深入某个主题，可以选择阅读：

【7】如何理解寄存器：内核寄存器、特殊寄存器语义、屏障和调试方法。
【8】认识GPIO：GPIO 电气结构、全部模式、锁定寄存器和更多引脚配置。
ST 官方 HAL GPIO 实现源码与接口头文件。

12.4 官方资料

资料	本章采用版本	用途
DS8626	Rev 12	STM32F407VE 引脚、封装、电气参数与复用功能
RM0090	Rev 21	存储器映射、RCC、GPIO 寄存器与位域
ES0182	Rev 16	STM32F405/407 芯片限制与时钟使能后延迟说明
PM0214	Rev 10	Cortex-M4 存储器模型、位带和内核编程说明

GPIO基础

定时器与PWM基础

​

一 本章简介 ​

1.1 学习目标 ​

1.2 硬件与软件准备 ​

1.3 阅读路线 ​

1.4 最终文件 ​

二 先看硬件：同样是 LED，点亮电平却相反 ​

2.1 连接 DAPLink ​

2.2 核心板 PB2 LED：高电平点亮 ​

2.3 筑基学习板 PB8 LED：低电平点亮 ​

2.4 为什么切换到输出模式前要先写“熄灭电平” ​

三 从裸寄存器代码到 GPIO 库 ​

3.1 寄存器就是外设的控制面板 ​

3.2 我们希望上层怎样调用 ​

3.3 分层关系 ​

3.4 本章库的边界 ​

四 用 C 结构体映射 GPIO 寄存器 ​

4.1 基地址加偏移地址 ​

4.2 GPIO 寄存器排列 ​

4.3 volatile、只读与保留成员 ​

4.4 用编译期断言检查关键偏移 ​

4.5 完整 tkx_stm32f407.h ​

五 设计 tk_gpio.h：先把接口想清楚 ​

5.1 用位掩码表示引脚 ​

5.2 模式宏为什么包含两类信息 ​

5.3 速度、上下拉和复用功能 ​

5.4 初始化结构体 ​

5.5 完整 tk_gpio.h ​

六 实现 tk_gpio.c ​

6.1 初始化函数的总体流程 ​

6.2 时钟使能与回读 ​

6.3 用 PB8 看懂读—改—写 ​

6.4 为什么输出电平写 BSRR ​

6.5 输入读取的返回语义 ​

6.6 DeInit 恢复的是教学默认值 ​

6.7 完整 tk_gpio.c ​

6.8 用 PB2/PB8 推导初始化结果 ​

6.9 参数保护能做什么、不能做什么 ​

七 用 BSP 隔离 LED 极性 ​

7.1 为什么还要再封装一层 ​

7.2 完整 bsp_led.h ​

7.3 完整 bsp_led.c ​

7.4 完整 main.c ​

八 从零接入工程 ​

8.1 先规划目录 ​

8.2 获取启动文件时必须匹配工具链 ​

8.3 Keil MDK 创建与接入 ​

8.4 VS Code + EIDE 创建与接入 ​

8.5 CLion/CMake 接入 ​

九 编译、下载与调试闭环 ​

9.1 先完成编译 ​

9.2 配置 DAPLink 并下载 ​

9.3 用调用栈确认分层真的生效 ​

9.4 检查寄存器字段 ​

9.5 单步观察 BSRR 与 ODR ​

9.6 观察两颗 LED 的最终现象 ​

十 工程师还应看懂的设计边界 ​

10.1 与官方 HAL 的接口对应 ​

10.2 volatile 不等于线程安全 ​

10.3 输出模式最后写，安全电平更早写 ​

10.4 DeInit、端口复位和真实复位值 ​

10.5 代码大小与维护成本要同条件比较 ​

10.6 位带可以做单 bit 访问，但不是首选接口 ​

十一 常见问题 ​

11.1 提示 undefined reference to TK_GPIO_Init ​

11.2 提示找不到 tk_gpio.h 或 tkx_stm32f407.h ​

11.3 能下载，但两颗 LED 都不闪 ​

11.4 PB2 正常，PB8 的亮灭相反 ​

11.5 复位瞬间 LED 闪一下 ​

11.6 调试器里 BSRR 总是 0 ​

十二 总结、练习与参考资料 ​

12.1 本章小结 ​

12.2 动手练习 ​

12.3 延伸阅读 ​

12.4 官方资料 ​

一本章简介

1.1 学习目标

1.2 硬件与软件准备

1.3 阅读路线

1.4 最终文件

二先看硬件：同样是 LED，点亮电平却相反

2.1 连接 DAPLink

2.2 核心板 PB2 LED：高电平点亮

2.3 筑基学习板 PB8 LED：低电平点亮

2.4 为什么切换到输出模式前要先写“熄灭电平”

三从裸寄存器代码到 GPIO 库

3.1 寄存器就是外设的控制面板

3.2 我们希望上层怎样调用

3.3 分层关系

3.4 本章库的边界

四用 C 结构体映射 GPIO 寄存器

4.1 基地址加偏移地址

4.2 GPIO 寄存器排列

4.3 `volatile`、只读与保留成员

4.4 用编译期断言检查关键偏移

4.5 完整 `tkx_stm32f407.h`

五设计 `tk_gpio.h`：先把接口想清楚

5.1 用位掩码表示引脚

5.2 模式宏为什么包含两类信息

5.3 速度、上下拉和复用功能

5.4 初始化结构体

5.5 完整 `tk_gpio.h`

六实现 `tk_gpio.c`

6.1 初始化函数的总体流程

6.2 时钟使能与回读

6.3 用 PB8 看懂读—改—写

6.4 为什么输出电平写 `BSRR`

6.5 输入读取的返回语义

6.6 `DeInit` 恢复的是教学默认值

6.7 完整 `tk_gpio.c`

6.8 用 PB2/PB8 推导初始化结果

6.9 参数保护能做什么、不能做什么

七用 BSP 隔离 LED 极性

7.1 为什么还要再封装一层

7.2 完整 `bsp_led.h`

7.3 完整 `bsp_led.c`

7.4 完整 `main.c`

八从零接入工程

8.1 先规划目录

8.2 获取启动文件时必须匹配工具链

8.3 Keil MDK 创建与接入

8.4 VS Code + EIDE 创建与接入

8.5 CLion/CMake 接入

九编译、下载与调试闭环

9.1 先完成编译

9.2 配置 DAPLink 并下载

9.3 用调用栈确认分层真的生效

9.4 检查寄存器字段

9.5 单步观察 `BSRR` 与 `ODR`

9.6 观察两颗 LED 的最终现象

十工程师还应看懂的设计边界

10.1 与官方 HAL 的接口对应

10.2 `volatile` 不等于线程安全

10.3 输出模式最后写，安全电平更早写

10.4 `DeInit`、端口复位和真实复位值

10.5 代码大小与维护成本要同条件比较

10.6 位带可以做单 bit 访问，但不是首选接口

十一常见问题

11.1 提示 `undefined reference to TK_GPIO_Init`

11.2 提示找不到 `tk_gpio.h` 或 `tkx_stm32f407.h`

11.3 能下载，但两颗 LED 都不闪

11.4 PB2 正常，PB8 的亮灭相反

11.5 复位瞬间 LED 闪一下

11.6 调试器里 `BSRR` 总是 0

十二总结、练习与参考资料

12.1 本章小结

12.2 动手练习

12.3 延伸阅读

12.4 官方资料