RT-Thread GD32 ARM 系列 BSP 外设驱动使用教程：使用 ENV 工具开启更多板载与片上资源

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS

本文基于 RT-Thread 仓库中 bsp/gd32/arm/docs/GD32_ARM系列BSP外设驱动使用教程.md 展开，面向需要在 RT-Thread 上使用更多 GD32 开发板资源的开发者。文章以 GD32407V-START 开发板开启 UART2 为例，完整演示 ENV 工具的 menuconfig 配置、软件包更新与工程重新生成的实战流程，并结合 BSP 源码剖析外设配置项背后的实现机制，读完即可举一反三地为 GD32 ARM 系列其他开发板开启任意外设。

一、适用范围与前置准备

GD32 ARM 系列 BSP 位于仓库的bsp/gd32/arm/目录，包含 gd32103c-eval、gd32307e-start、gd32407v-start、gd32e503v-eval、gd32h759i-eval 等二十余个开发板工程。这些 BSP 工程默认只开启了最基本的外设（通常只有 GPIO 和调试串口），而开发板上大量的板载资源（Flash、SD 卡、USB 等）和芯片的片上外设（UART、SPI、ADC、定时器、RTC 等）默认处于关闭状态。

要开启这些资源，核心工具是RT-Thread ENV 工具。ENV 是一个基于命令行的开发辅助工具，可以在 BSP 目录下直接运行menuconfig打开图形化配置界面，完成外设驱动的勾选与参数配置，并配合scons重新生成 Keil MDK / IAR 工程。

开始之前需要满足以下前提：

• 已安装并配置好 RT-Thread ENV 工具，掌握其基本操作（建议先通读 RT-Thread 官方《env 工具用户手册》）；
• 已准备好目标开发板对应的 BSP 工程目录，例如本教程使用的 bsp/gd32/arm/gd32407v-start；
• 已安装 MDK5（或 IAR）等编译下载工具链。

二、理解 GD32 BSP 的外设配置体系

在使用 ENV 工具之前，先了解外设选项是如何组织的，这有助于理解后续每一步操作的含义。

每个开发板工程的 Kconfig 都通过source语句把 RT-Thread 内核配置、GD32 公共库配置和板级配置串联起来。以 bsp/gd32/arm/gd32407v-start/Kconfig 为例：

mainmenu "RT-Thread Configuration" BSP_DIR := . RTT_DIR := ../../../.. PKGS_DIR := packages source "$(RTT_DIR)/Kconfig" osource "$PKGS_DIR/Kconfig" rsource "../libraries/Kconfig" rsource "board/Kconfig"

其中board/Kconfig定义了板级硬件配置菜单。打开 bsp/gd32/arm/gd32407v-start/board/Kconfig 可以看到，Hardware Drivers Config菜单下分为三大类：

板级 Kconfig 还通过source "$(BSP_DIR)/../libraries/gd32_drivers/Kconfig"引入了 GD32 公共驱动层的配置选项（如 USB 的 FS/HS 类型与 PHY 接口选择、硬件 I2C 的接收方案选择），详见 bsp/gd32/arm/libraries/gd32_drivers/Kconfig。

配置项最终会以#define宏的形式写入rtconfig.h，驱动源码通过#if defined(BSP_USING_xxx)决定是否编译和注册对应外设。因此，在 menuconfig 中勾选某个外设，等效于在工程中启用对应的驱动文件与设备注册代码，这就是"重新生成工程后驱动自动生效"的原理。

三、实战：在 GD32407V-START 上开启 UART2 驱动

下面以在 GD32407V-START 开发板上开启 UART2 为例，逐步演示 ENV 工具的完整使用流程。GD32407V-START 基于 GD32F407VKT6 芯片（主频最高 168MHz，3MB Flash、192KB RAM），板载 LED、按键、USB 接口与 GD-Link 调试器，开发板详情可参考 bsp/gd32/arm/gd32407v-start/README.md。

1）打开配置工具

在终端中进入 BSP 工程目录bsp/gd32/arm/gd32407v-start，输入命令打开 menuconfig 配置界面：

menuconfig

打开后的配置工具界面即 RT-Thread 的配置主菜单。通过键盘上下键移动光标，选中Hardware Drivers Config，按回车键进入硬件驱动配置菜单。

2）进入硬件驱动配置菜单

在硬件配置菜单中可以看到三个选项：板载外设配置菜单、片上外设配置菜单和扩展模块配置菜单，这与上一节介绍的 Kconfig 结构一一对应。按回车键进入板载外设配置菜单。

3）在板载外设配置菜单里开启 UART2

在板载外设配置菜单中找到Enable UART2选项，使用空格键将其勾选为*（选中状态），如下图所示：

从 bsp/gd32/arm/gd32407v-start/board/Kconfig 的源码可以看到，BSP_USING_UART2默认值为n（未开启），这正是 BSP 工程默认只有 GPIO 和串口 1 的原因；开启后 menuconfig 还会自动展开 UART2 的 TX/RX 引脚、复用功能等子配置项（详见第四节）。

4）保存退出

配置完成后，按键盘右方向键移动光标到下方菜单栏的Save，按回车键保存配置，然后按Esc键退出配置工具。

5）更新软件包

在 BSP 目录下执行如下命令，使软件包（packages）配置生效：

pkgs --update

该命令会根据配置拉取或更新packages目录下的软件包。若本次配置未涉及软件包，命令也会完成配置同步，为后续构建做好准备。

6）生成 MDK5 工程

执行 SCons 构建命令重新生成 MDK5 工程：

scons --target=mdk5

命令执行完成后，BSP 目录下会生成新的project.uvprojx工程文件。重新生成的关键作用在于：SCons 会根据rtconfig.h中的配置宏，把新增外设对应的驱动源文件（如 UART2 相关的注册代码）自动加入工程。

7）编译下载

打开重新生成的 MDK5 工程文件，点击编译（Build），编译通过后下载程序到开发板（GD32407V-START 默认使用 GD-Link 仿真器下载）。

8）查看运行结果

程序烧录并运行后，在串口终端中打开开发板的调试串口（默认 115200-8-1-N），进入msh命令行，输入list_device命令查看系统中已注册的设备：

msh >list_device

此时可以看到名为uart2的设备已被注册到 RT-Thread 设备框架中，说明 UART2 驱动已经成功启用。之后便可以在应用代码中通过rt_device_find("uart2")获取该设备句柄，使用 RT-Thread 的串口设备 API（rt_device_open/rt_device_read/rt_device_write等）进行收发操作。

四、UART 配置项深度解析：配置背后的源码机制

menuconfig 中看到的每一个配置项，最终都对应 Kconfig 定义与驱动源码中的条件编译分支。以 UART2 为例，可以从源码中印证完整的生效链路。

1）Kconfig 中的 UART2 选项

在 bsp/gd32/arm/gd32407v-start/board/Kconfig 中，UART2 的完整配置块如下（节选关键部分）：

menuconfig BSP_USING_UART2 bool "Enable UART2" default n if BSP_USING_UART2 config BSP_UART2_TX_PIN string "UART2 TX name, such as PA8" default "PB10" config BSP_UART2_RX_PIN string "UART2 RX name, such as PA9" default "PB11" config BSP_UART2_AFIO string "UART2 alternate function, such as AF7" default "AF7" ... endif

其中几个关键配置项的含义与默认值如下：

注意：BSP_UART2_TX_PIN/RX_PIN修改后必须与开发板实际接线一致，且AFIO复用号必须匹配目标引脚所在端口的复用功能表，否则串口无法正常工作。

2）引脚与寄存器配置宏

在 Kconfig 中配置的引脚名和复用号，会进一步传递给驱动配置文件 bsp/gd32/arm/libraries/gd32_drivers/config/uart_config.h，其中定义了 UART2 的硬件配置宏：

#if defined(BSP_USING_UART2) #ifndef UART2_CONFIG #define UART2_CONFIG \ { \ .uart_periph = USART2, \ .irqn = USART2_IRQn, \ .per_clk = RCU_USART2, \ .tx_pin_name = BSP_UART2_TX_PIN, \ .rx_pin_name = BSP_UART2_RX_PIN, \ .alternate = BSP_UART2_AFIO, \ .serial = &serial2, \ .device_name = "uart2", \ } #endif /* UART2_CONFIG */ #endif /* BSP_USING_UART2 */

这个宏把外设实例（USART2）、中断号（USART2_IRQn）、时钟（RCU_USART2）、引脚与复用号以及设备名uart2打包成一个结构体，供驱动初始化时使用。

3）驱动注册与初始化

在 bsp/gd32/arm/libraries/gd32_drivers/drv_usart.c 中，UART2_CONFIG被填入串口设备配置数组：

#ifdef BSP_USING_UART2 UART2_CONFIG, #endif

最终由rt_hw_usart_init完成底层初始化，并将uart2注册到 RT-Thread 设备框架。整个链路可归纳为：

menuconfig 勾选 Enable UART2 → rtconfig.h 生成 #define BSP_USING_UART2 → scons 重新生成工程，加入驱动源文件 → uart_config.h 中 UART2_CONFIG 宏生效 → drv_usart.c 注册 uart2 设备 → msh 下 list_device 可见 uart2

4）串口框架版本与 DMA 选项

GD32 的 UART 驱动同时支持 Serial V1 与 Serial V2 两套串口框架，可在Enable UART菜单下的Select UART framework version中选择：

• Use Serial V1 framework：经典串口框架（RT_USING_SERIAL），默认选项，兼容性好；
• Use Serial V2 framework：新一代串口框架（RT_USING_SERIAL_V2），支持更灵活的 DMA 收发。

若选择 Serial V2，UART2 下还会出现 DMA 相关配置（以BSP_USING_SERIAL_V2为条件，见 bsp/gd32/arm/gd32407v-start/board/Kconfig）：

DMA 收发需要先在内核配置中开启RT_SERIAL_USING_DMA，适用于大数据量、低 CPU 占用的串口应用场景；对普通调试串口，保持默认的 V1 框架即可。

五、开启更多片上外设与扩展模块

除 UART 外，GD32 ARM 系列 BSP 的片上外设配置菜单还提供了大量外设开关，同样遵循"勾选 → 保存 → 更新 → 重新生成工程"的流程。以 bsp/gd32/arm/gd32407v-start/board/Kconfig 为参考，常见外设选项及其自动关联的内核组件如下：

此外，GD32 公共驱动层还提供了细粒度的配置项，例如 USB 的 Full Speed / High Speed 类型选择、Embedded/UTMI/ULPI PHY 接口选择，以及硬件 I2C 主接收方案 A/B 的选择，均定义在 bsp/gd32/arm/libraries/gd32_drivers/Kconfig 中。对应的驱动实现（如drv_adc.c、drv_spi.c、drv_sdio.c、drv_usbd相关源码）全部位于 bsp/gd32/arm/libraries/gd32_drivers 目录，可根据需要深入阅读。

如何添加更多片上资源选项

如果现有配置项仍不满足需求，可以自行扩展。从源码结构看，为 BSP 新增一个外设选项通常需要三步：

1. 在 Kconfig 中声明配置项：在 bsp/gd32/arm/gd32407v-start/board/Kconfig 的On-chip Peripheral Drivers菜单下新增BSP_USING_XXX选项，并select对应的 RT-Thread 组件；
2. 在驱动库中实现条件编译注册：在 bsp/gd32/arm/libraries/gd32_drivers 对应驱动文件中用#ifdef BSP_USING_XXX包裹初始化与设备注册代码，并在 bsp/gd32/arm/libraries/gd32_drivers/SConscript 中确认源文件参与构建；
3. 重新生成工程验证：保存配置后执行pkgs --update与scons --target=mdk5，编译下载后通过list_device确认新设备是否注册成功。

新增或修改 Kconfig 属于对仓库源码的定制开发，实际项目中可参考仓库现有驱动的实现模式（例如对比drv_usart.c与drv_spi.c的注册方式）来完成。

六、总结

RT-Thread GD32 ARM 系列 BSP 的外设驱动使用流程可以概括为一句话：在 ENV 工具中使能相关外设，重新生成工程后对应驱动即自动生效。具体步骤为：

1. 在 BSP 目录下运行menuconfig，进入Hardware Drivers Config；
2. 在板载外设 / 片上外设 / 扩展模块菜单中勾选所需外设并配置参数（引脚、复用号、DMA、缓冲区等）；
3. 保存退出后执行pkgs --update更新软件包；
4. 执行scons --target=mdk5（或mdk4/iar）重新生成工程；
5. 编译下载，通过list_device验证设备注册结果。

这一机制依托 Kconfig 配置体系与条件编译的驱动实现，让开发者无需手工修改工程文件即可快速启用 UART、SPI、ADC、TIM、RTC、SDIO、USB 等外设，从而将精力集中在应用功能的开发上。本文涉及的配置选项与源码均可在仓库中进一步查阅：GD32_ARM 系列外设驱动使用教程、gd32407v-start 板级 Kconfig、UART 配置宏定义 与 GD32 公共驱动实现。

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS