RT-Thread移植GD32VF103 RISC-V开发板实战：环境配置、BSP修改与问题排查

1. 项目概述：从一块开发板说起

去年九月份，RT-Thread社区的Andy Chen牵头定制了一批GD32V开发板，我有幸搭车拿到了一块。板子到手的第一印象是“精致”，Type-C接口集成了供电、调试和程序烧录，对于我这种桌面常年被各种线缆缠绕的人来说，简直是福音。但真正让我兴奋的，是板载的主控芯片——GD32VF103。这是一颗基于RISC-V内核的微控制器（MCU），对于一直关注开源指令集架构的我来说，吸引力是致命的。

GD32VF103系列是兆易创新（GigaDevice）与芯来科技（Nuclei）合作的产物，定位是物联网（IoT）领域。这颗芯片最高主频108MHz，片上Flash从16KB到128KB不等，SRAM从8KB到32KB。我们这批板子选用了顶配的VF103VBT6，Flash 128KB，SRAM 32KB，免去了选择的纠结。更难得的是，兆易开放了完整的中文用户手册（500多页），芯来也公开了其Bumblebee内核的指令架构手册。这意味着，你不仅能把它当一块普通的MCU来用，更能深入到RISC-V内核的机制里去学习，比如中断、异常、定时器、低功耗模式等，这对于学习和研究RISC-V来说，是个非常理想的硬件平台。

配套的SDK里包含了RT-Thread Nano、原理图、简易手册和烧录工具。不过，由于当时赶工，板载的JTAG接口留了点小“尾巴”，需要飞线才能用，这点在原理图里有注明。对于大多数应用，通过串口烧录已经足够。拿到板子后，我先是按照官方SDK跑通了RT-Thread Nano，过程很顺利。但作为一个喜欢折腾最新代码的人，用官方SDK显然不够“过瘾”，我的目标是把最新的RT-Thread主线代码（mainline）跑在这块RISC-V芯片上。这个过程，才是我这篇文章想分享的重点。

2. 环境搭建：在Windows下配置RISC-V编译链

RT-Thread的开发环境非常友好，其ENV工具提供了一个统一的配置和编译入口。我选择在Windows下进行开发，首先从RT-Thread官网下载ENV工具包。解压后，路径切记不要包含中文，否则后续可能遇到各种诡异问题。双击env.exe就能启动一个功能强大的命令行终端，我习惯把它固定到任务栏，方便随时打开。

注意：ENV工具默认只携带了ARM架构的GCC工具链（arm-none-eabi-gcc）。我们要编译RISC-V架构的代码，必须手动添加对应的工具链。

RISC-V的工具链我选择从xPack项目下载，它提供了预编译好的Windows版本，非常方便。下载地址是Github上的xpack-dev-tools/riscv-none-embed-gcc-xpack仓库。下载完成后，将其解压到ENV工具目录下的tools/gnu_gcc/risc-v/文件夹中。此时，你会在类似xpack-riscv-none-embed-gcc-10.2.0-1.2/bin的路径下看到riscv-none-embed-gcc.exe等可执行文件。

接下来是关键一步：让ENV工具认识这个新的工具链。我翻遍了《Env用户手册》和论坛，没有找到标准的添加方法。经过一番摸索，我发现可以通过修改ENV的环境变量配置文件来实现。具体路径在env/tools/ConEmu/ConEmu/CmdInit.cmd。找到设置RTT_EXEC_PATH环境变量的地方，将其值修改为你刚刚解压的RISC-V工具链的bin目录的绝对路径。例如：

set RTT_EXEC_PATH=C:\Your_ENV_Path\tools\gnu_gcc\risc-v\xpack-riscv-none-embed-gcc-10.2.0-1.2\bin

修改保存后，重新启动ENV命令行，输入riscv-none-embed-gcc -v，如果能看到版本信息，说明工具链配置成功。这个方法虽不是官方标准流程，但实测有效。如果你有更优雅的方式，欢迎交流。

3. 代码适配：为“简配”开发板修改主线BSP

环境准备好后，用Git克隆RT-Thread主线代码仓库。RT-Thread主线已经支持GD32VF103，但其BSP（板级支持包）是针对GigaDevice官方的gd32vf103-eval评估板编写的。这块评估板和我们手上的定制板有一个关键区别：外部高速晶振（HXTAL）。

官方评估板焊接了一颗8MHz的外部高速晶振，系统时钟通过PLL倍频自此。而我们手上的定制板为了成本考虑，没有贴装这颗外部晶振，芯片依靠内部的8MHz RC振荡器（IRC8M）工作。内部RC振荡器的精度（通常±1%）远不如外部晶振，但对于不涉及高精度定时或以太网通信的多数应用（比如GPIO控制、串口通信、基础传感器读取）来说，完全足够。

因此，我们需要修改系统时钟的初始化配置。代码位于bsp/gd32vf103v-eval/board/board.c的system_clock_config()函数附近。通常，这里会通过宏定义来选择时钟源。我们需要确保启用内部RC振荡器作为PLL的时钟源，并屏蔽外部晶振的选项。具体操作是：

1. 在rtconfig.h或相关的板级配置头文件中，确认或定义宏，将系统时钟源指向内部IRC8M。例如，可能需要将__SYSTEM_CLOCK_108M_PLL_IRC8M定义为1，而确保__SYSTEM_CLOCK_108M_PLL_HXTAL未被定义或为0。
2. 检查system_clock_config()函数内的逻辑，确保它根据上述宏定义，正确调用rcu_osci_on(RCU_IRC8M)并配置PLL的时钟源为RCU_PLLSRC_IRC8M_DIV2。

这个修改至关重要，如果时钟源配置错误，轻则系统频率不对导致串口波特率错误、定时器不准，重则根本无法启动。

4. 点亮LED：第一个驱动测试与代码分析

硬件平台适配好后，总要写个“Hello World”来验明正身。对于嵌入式开发，点灯就是我们的“Hello World”。我们这块板子上有三个用户LED，分别连接在GPIOE的Pin3、Pin4和Pin5上。

在applications/main.c的main()函数中，我添加了流水灯的代码。这个过程清晰地展示了RT-Thread下操作GD32VF103外设的流程，与标准库开发非常相似：

#include “gd32vf103.h” // 确保包含芯片头文件 int main(void) { // 打印启动信息，包含编译时间，便于区分不同版本固件 rt_kprintf(“Hello GD32VF103VBT6! build %s %s\n”, __DATE__, __TIME__); // 1. 使能GPIOE端口时钟 // 在GD32中，任何外设使用前必须先使能其时钟，这是节能设计的关键 rcu_periph_clock_enable(RCU_GPIOE); // 2. 初始化GPIO引脚 // GPIO_MODE_OUT_PP: 推挽输出模式，驱动能力强 // GPIO_OSPEED_2MHZ: 输出速度2MHz，对于LED闪烁足够，低速度有助于降低噪声和功耗 gpio_init(GPIOE, GPIO_MODE_OUT_PP, GPIO_OSPEED_2MHZ, GPIO_PIN_3); gpio_init(GPIOE, GPIO_MODE_OUT_PP, GPIO_OSPEED_2MHZ, GPIO_PIN_4); gpio_init(GPIOE, GPIO_MODE_OUT_PP, GPIO_OSPEED_2MHZ, GPIO_PIN_5); // 3. 主循环，实现流水灯效果 while (1) { // 点亮LED（假设低电平点亮，根据具体电路调整） gpio_bit_reset(GPIOE, GPIO_PIN_3); // PE3拉低 rt_thread_mdelay(300); // 延时300ms，使用RT-Thread的毫秒延时函数，会引发线程调度 gpio_bit_reset(GPIOE, GPIO_PIN_4); // PE4拉低 rt_thread_mdelay(300); gpio_bit_reset(GPIOE, GPIO_PIN_5); // PE5拉低 rt_thread_mdelay(300); // 熄灭LED gpio_bit_set(GPIOE, GPIO_PIN_3); // PE3拉高 rt_thread_mdelay(30); // 熄灭时间短一些，形成闪烁效果 gpio_bit_set(GPIOE, GPIO_PIN_4); rt_thread_mdelay(30); gpio_bit_set(GPIOE, GPIO_PIN_5); rt_thread_mdelay(30); } }

这段代码有几个值得注意的点：

• 时钟使能先行：rcu_periph_clock_enable(RCU_GPIOE)必须在GPIO初始化之前调用。这是很多新手容易忽略的地方，导致GPIO配置无效。
• 速度选择：GPIO_OSPEED_2MHZ对于驱动LED绰绰有余。在高速通信（如SPI、USART）时，才需要选择更高的速度（10MHz, 50MHz），但需注意更高的速度可能带来更大的过冲和EMI。
• 延时函数：rt_thread_mdelay()是RT-Thread提供的系统延时函数，它会使当前线程挂起，调度器可以切换到其他就绪的线程执行，从而更好地利用CPU资源。在简单的单任务程序中，它和简单的忙等待延时效果一样，但为后续引入多任务打下了基础。

我将适配和修改后的代码推送到了Gitee仓库，方便大家直接获取测试。

5. 编译与烧录：一键构建与固件下载

代码修改完成后，就可以进行编译了。在ENV命令行中，切换到RT-Thread源码的BSP目录bsp/gd32vf103v-eval/下，直接输入scons命令。SCons是RT-Thread默认使用的构建工具，它会自动读取当前目录下的SConscript脚本，调用我们之前配置好的RISC-V工具链进行编译。

如果一切顺利，编译结束后会在当前目录下生成rtthread.bin、rtthread.elf等文件。我们烧录使用的是rtthread.bin。

烧录工具是兆易创新提供的GigaDevice MCU ISP Programmer。烧录前需要注意几个关键步骤：

1. 连接与供电：使用Type-C线连接开发板和电脑。板子通过USB取电。
2. 进入烧录模式：GD32VF103通过Boot0引脚选择启动模式。我们需要手动使其进入系统存储器启动模式（即ISP模式）。操作方法是：按住板子上的BOOT0按键不放，再短暂按下RESET按键，然后松开RESET，最后松开BOOT0。此时，芯片运行的是一段内置的Bootloader程序，等待通过串口接收烧录指令。
3. 软件配置：打开ISP Programmer软件，选择正确的串口号（在设备管理器中查看）。波特率必须设置为256000，这是GD32 Bootloader通信的固定速率，不是常见的115200。然后选择编译生成的rtthread.bin文件。
4. 开始烧录：点击“开始编程”按钮。如果一切正常，软件会显示擦除、编程、校验成功的进度。

重要提示：串口调试工具（如Putty、Xshell）和ISP烧录软件会独占串口。因此，在烧录前，务必关闭任何可能占用该串口的调试终端，否则ISP软件将无法连接Bootloader，导致烧录失败。

烧录完成后，再次按下RESET按键（无需再按BOOT0），芯片将从主Flash启动。打开串口调试工具（波特率这次要设为115200，这是我们在程序中配置的调试输出波特率），如果看到RT-Thread的启动Logo以及我们代码中打印的“Hello GD32VF103VBT6!”信息，并且板载的三个LED开始循环闪烁，那么恭喜你，RT-Thread已经在RISC-V内核的GD32VF103上成功运行了！

6. 问题排查与调试心得实录

在实际操作中，几乎不可能一帆风顺。下面记录几个我遇到或可能遇到的典型问题及解决方法，希望能帮你少走弯路。

6.1 编译失败：工具链路径错误

• 现象：执行scons命令后，报错“riscv-none-embed-gcc: command not found”或类似提示。
• 排查：这明确指向RISC-V工具链未正确配置。
  1. 在ENV命令行中，输入riscv-none-embed-gcc -v，看是否有输出。无输出则证明环境变量未生效。
  2. 检查env/tools/ConEmu/ConEmu/CmdInit.cmd文件中RTT_EXEC_PATH的设置，路径是否指向了工具链bin目录的绝对路径？路径中是否有空格或中文？确保路径正确。
  3. 修改CmdInit.cmd后，必须关闭所有ENV命令行窗口并重新打开，新的环境变量才会被加载。
• 解决：确保路径正确并重启ENV。也可以尝试在ENV命令行内临时设置路径：set PATH=%PATH%;C:\Your_Toolchain_Path\bin，但这只是临时生效。

6.2 烧录失败：无法连接芯片

• 现象：ISP Programmer软件点击“开始编程”后，长时间无反应或提示“连接失败”。
• 排查：这是一个多因素问题，需要按顺序排查。
  1. 驱动问题：首次连接开发板，电脑需要安装USB转串口芯片（通常是CH340或CP2102）的驱动。检查设备管理器中是否有未识别的设备或带感叹号的串口设备。
  2. 串口占用：这是最常见的原因。确保所有的串口调试助手、终端软件、甚至其他可能占用串口的程序（如某些IDE的串口监视器）都已关闭。
  3. Boot模式进入错误：操作顺序必须是“先按住BOOT0，再按并松开RESET，最后松开BOOT0”。如果先按了RESET，芯片已经从Flash启动运行用户程序了，Bootloader就不会被激活。确保操作时，BOOT0按键在RESET按下前已按下，在RESET松开后仍保持按下状态一小会儿。
  4. 波特率错误：ISP软件中的波特率必须设置为256000，不是115200。
  5. 硬件连接：检查Type-C线是否完好，是否只用于供电而数据线未连接？换一根确认能传输数据的Type-C线试试。
• 解决：按照上述清单逐一检查。我个人习惯在烧录前，先在设备管理器里确认串口号，然后关闭所有可能占用该串口的软件，最后严格按照“BOOT0 -> RESET -> 松开RESET -> 松开BOOT0”的顺序操作。

6.3 系统启动失败或无输出

• 现象：烧录成功，复位后串口无任何输出，LED也不闪烁。
• 排查：
  1. 时钟配置错误：这是最可能的原因，尤其是对于没有外部晶振的板子。请再次仔细检查system_clock_config()函数，确认PLL的时钟源是内部IRC8M，并且系统时钟频率配置正确（108MHz）。如果时钟配置过高或过低，都会导致UART波特率生成错误，从而无法输出可识别的数据。
  2. 串口引脚配置：检查BSP中串口初始化代码（通常是USART0）。确认TX/RX引脚配置是否正确，是否与板子原理图一致。我们的板子调试串口通常连接在某个固定的USART上。
  3. 波特率不匹配：确保代码中调试串口的初始化波特率是115200，并且你的串口终端软件也设置为115200。
  4. 电源问题：虽然罕见，但可以测量一下板子供电电压是否正常。
• 解决：重点复查时钟和串口配置。可以尝试在初始化时钟后，通过翻转一个GPIO引脚并用示波器测量其周期来间接验证系统时钟频率是否大致正确。

6.4 关于启动时的“warning”提示

在成功启动的串口打印中，你可能会看到类似“warning: stack size of thread ‘xxx’ is less than recommended”的警告。这通常是因为某个线程的堆栈大小在rtconfig.h或线程创建时设置得过小，RT-Thread内核检测到并给出了提示。

• 影响：对于简单的流水灯例程，这个警告通常不影响运行。但堆栈过小是嵌入式系统极难调试的致命问题之一，它可能导致函数调用时数据被覆盖，引发随机性的死机或数据错误。
• 处理：不要忽视这个警告。你应该根据该线程的实际需求（局部变量大小、函数调用深度等）适当增加其堆栈大小。可以在rtconfig.h中修改默认线程栈大小（如RT_THREAD_STACK_SIZE），或者在创建线程时指定更大的栈空间。例如，将main线程的栈从默认的256字节增加到512或1024字节，往往能解决很多莫名奇妙的问题。

7. 深入探索：从BSP到内核机制

成功点亮LED并稳定运行RT-Thread，只是一个开始。GD32VF103作为RISC-V的入门利器，其价值远不止于此。基于这个稳定的基础，我们可以进行更深入的探索。

7.1 剖析BSP结构

RT-Thread的BSP目录结构清晰，是学习如何为一个新芯片移植RT-Thread的绝佳范例。以gd32vf103v-eval为例：

• board/：包含最核心的板级文件，如board.c（系统时钟、内存初始化）、linker_scripts/（链接脚本，定义Flash和RAM的布局）、drv_gpio.c（GPIO驱动框架对接层）。
• libraries/：存放芯片厂商提供的标准外设库（如GD32VF10x Firmware Library）。RT-Thread通常通过drv_xxx.c来封装这些库函数，以适配RT-Thread的设备驱动框架。
• drivers/：实现RT-Thread设备驱动框架下的具体驱动，如drv_usart.c。这里会实现rt_device接口的操作函数（open, close, read, write, control等），将RT-Thread的通用设备API映射到具体的芯片外设库函数上。
• applications/：用户应用程序目录，main.c就在这里。

通过阅读这些代码，你可以理解RT-Thread是如何实现“设备驱动框架”的抽象，以及如何将一款新的MCU纳入到这个生态中的。

7.2 利用RISC-V特权架构手册

芯来科技开放的Bumblebee内核手册是一份宝藏文档。当你想实现更底层的功能或优化时，它会变得必不可少。例如：

• 自定义中断处理：虽然RT-Thread提供了完善的中断管理API，但了解RISC-V的CLINT（核心本地中断器）和PLIC（平台级中断控制器）的寄存器布局，能让你在处理复杂中断嵌套、设置优先级时更有底气。
• 性能优化：了解RISC-V的CSR（控制和状态寄存器），比如mcycle（周期计数器）和minstret（指令计数器），可以用来做精细的代码性能分析。
• 低功耗实现：手册中详细描述了WFI（等待中断）指令以及相关的休眠模式。结合GD32VF103的用户手册，你可以实现比RT-Thread提供的rt_thread_delay()更底层的休眠，进一步降低系统功耗。

7.3 扩展外设驱动

RT-Thread的drivers目录目前可能只实现了最基础的UART、GPIO等驱动。你可以参考现有驱动，为GD32VF103的其他外设编写驱动，并提交到RT-Thread社区。例如：

1. SPI驱动：用于连接OLED屏幕、Flash存储器、传感器等。
2. I2C驱动：用于连接EEPROM、各种I2C传感器。
3. ADC驱动：读取模拟量信号。
4. PWM驱动：控制电机、调光LED等。

编写驱动的过程，是对RT-Thread设备驱动模型和GD32外设库的深度实践。你需要在drv_xxx.c中实现rt_device_ops结构体中的函数指针，并处理好中断、DMA等异步机制。

7.4 连接RT-Thread软件包生态系统

RT-Thread最大的优势之一是其丰富的软件包（packages）生态系统。一旦基础BSP稳定运行，你就可以通过ENV工具的menuconfig命令，像搭积木一样添加功能。

• 添加cJSON软件包，让你的设备具备处理JSON数据的能力，便于物联网通信。
• 添加webclient或mqtt软件包，轻松实现HTTP请求或MQTT协议接入云平台。
• 添加fal（Flash抽象层）和easyflash软件包，实现参数掉电存储、日志存储等功能。

使用scons --menuconfig进入配置界面，在“RT-Thread online packages”菜单中，你可以找到数百个经过验证的软件包。选中后，ENV会自动下载代码并集成到你的工程中。这极大地加速了产品原型开发。

8. 项目总结与进阶思考

将RT-Thread主线移植到GD32VF103开发板的过程，是一次完整的嵌入式开发实践。它涵盖了环境搭建、源码获取、板级适配、驱动编写、编译构建、固件烧录和问题调试的全流程。更重要的是，它以一个具体的RISC-V MCU为载体，让你能亲手触摸到开源指令集架构与成熟实时操作系统的结合。

从个人体验来看，GD32VF103的生态虽然相比STM32等老牌Arm Cortex-M芯片还有差距，但其完整的开源文档和RT-Thread的良好支持，已经为学习和中级应用提供了坚实的基础。兆易创新的产品线也在快速丰富，后续的RISC-V芯片性能更强、外设更多。

对于想深入RISC-V和RT-Thread的开发者，我建议下一步可以：

1. 仔细阅读芯来的《Bumblebee处理器内核指令架构手册》，特别是中断和异常章节，尝试写一个简单的裸机程序，不依赖RT-Thread，直接操作CSR来处理一个定时器中断。这能帮你建立最底层的认知。
2. 深入研究RT-Thread的调度器、IPC（线程间通信）机制。尝试在你的GD32V开发板上创建多个任务，使用信号量、邮箱、消息队列进行通信和同步，观察系统的行为。
3. 参与社区贡献。如果你为GD32VF103完善了某个外设驱动，或者修复了BSP中的某个问题，不妨向RT-Thread的GitHub仓库提交一个Pull Request。开源社区的力量正是来自于无数这样的微小贡献。

最后，关于那块板载JTAG接口的“小瑕疵”，如果你需要进行源码级调试（比如单步跟踪、查看变量），修复它是值得的。根据原理图，通常只需要用烙铁和细导线，将JTAG接口的TMS、TCK、TDO、TDI引脚分别飞线连接到芯片对应的引脚上，然后使用一款支持RISC-V的调试器（如基于FT2232的调试器，配合OpenOCD），就能实现强大的调试功能。这将是另一个精彩的故事了。