3. 开发环境搭建（下）：第一个Hello World程序（LED闪烁）、工程模板创建、烧录与调试流程
上一讲我们把工具链和IDE都装好了，但说实话，光有工具不跑个程序，心里总不踏实。这一讲我们就来点实际的——让GD32V开发板上的LED闪起来。这就是嵌入式世界的"Hello World"。
我个人习惯，每接触一块新开发板，第一件事就是点灯。为什么？因为LED闪烁能最直观地告诉你：编译器没问题、烧录没问题、芯片在跑、时钟在转。如果灯不亮，后面再复杂的程序都是白搭。
3.1 第一个LED闪烁程序
我们先从最简单的方式开始：直接操作寄存器，控制GPIO输出高低电平。
3.1.1 硬件原理
GD32V开发板上通常有一个用户LED，连接在某个GPIO引脚上。以最常见的GD32VF103C-START开发板为例，LED连接在PC13引脚。什么意思呢？就是你把PC13这个引脚输出高电平，LED就亮；输出低电平，LED就灭。
关键寄存器：
- RCU_APB2EN — 外设时钟使能寄存器。GPIO属于APB2总线上的外设，必须先打开它的时钟。
- GPIOx_CTL0/CTL1 — 端口配置寄存器。设置引脚是输入还是输出，推挽还是开漏。
- GPIOx_OCTL — 端口输出控制寄存器。写1输出高电平，写0输出低电平。
3.1.2 代码实现
打开Nuclei Studio，新建一个RISC-V C/C++项目。项目类型选"RISC-V Cross C/C++ Project"，目标芯片选GD32VF103。然后创建一个main.c文件，写入以下代码：
#include "gd32vf103.h"
void delay(void) {
volatile uint32_t i;
for (i = 0; i < 500000; i++);
}
int main(void) {
// 使能GPIOC时钟
RCU->APB2EN |= RCU_APB2EN_PCEN;
// 配置PC13为推挽输出，50MHz
GPIOC->CTL1 &= ~(0xF << 20); // 先清零
GPIOC->CTL1 |= (0x3 << 20); // 设为推挽输出
while (1) {
GPIOC->OCTL |= (1 << 13); // PC13输出高电平，LED亮
delay();
GPIOC->OCTL &= ~(1 << 13); // PC13输出低电平，LED灭
delay();
}
}
代码很简单，但有几个地方我想提醒你：
- volatile关键字不能省。delay函数里的循环变量如果不加volatile，编译器优化时可能直接把它优化没了，延时效果就没了。
- 寄存器操作要小心。先清零再置位是个好习惯，否则可能把其他引脚配置搞乱。
- 头文件路径要配好。gd32vf103.h这个头文件包含了所有寄存器地址定义，你得确保编译器能找到它。
小技巧： 如果你不确定LED接在哪个引脚，可以看原理图。一般丝印上会标LED对应的GPIO号。实在找不到，用万用表量一下，LED正极接的引脚就是控制脚。
3.2 工程模板创建
每次写新程序都从头配置寄存器？太累了。我建议你做一个工程模板，把基础框架搭好，以后直接复制。
3.2.1 模板结构
一个标准的GD32V工程模板应该包含以下部分：
| 目录/文件 | 说明 |
|---|---|
| src/ | 存放用户源文件（main.c等） |
| inc/ | 存放用户头文件 |
| startup/ | 启动文件（startup_gd32vf103.S） |
| linker/ | 链接脚本（gd32vf103.ld） |
| system/ | 系统初始化文件（system_gd32vf103.c） |
| Makefile | 编译规则 |
启动文件和链接脚本，我建议直接从官方SDK里复制。自己写？没必要，而且容易出错。官方已经帮你调好了，直接用就行。
3.2.2 创建步骤
- 复制SDK基础文件：从GD32官方固件库中复制startup_gd32vf103.S、system_gd32vf103.c和gd32vf103.ld到对应目录。
- 编写Makefile：指定编译器路径、芯片型号、源文件列表和链接脚本。
- 编写main.c模板：包含头文件、main函数框架、延时函数等。
- 测试编译：运行make，确保能生成.elf和.hex文件。
注意： 链接脚本里的RAM和Flash大小一定要和芯片型号匹配。GD32VF103C8T6是64KB Flash、20KB RAM。如果你用的是其他型号，记得改。我曾经见过有人把128KB的芯片用64KB的链接脚本，结果程序跑飞了，查了半天才发现是链接脚本不对。
3.3 烧录流程
程序编译好了，怎么把它烧进芯片？GD32V支持多种烧录方式，最常用的是通过JTAG/SWD调试器。
3.3.1 硬件连接
你需要一个RISC-V调试器，比如SiPEED的JTAG调试器，或者用J-Link（新版支持RISC-V）。连接方式如下：
| 调试器引脚 | 开发板引脚 | 说明 |
|---|---|---|
| TCK | TCK | 时钟 |
| TMS | TMS | 数据 |
| TDI | TDI | 数据输入（可选） |
| TDO | TDO | 数据输出（可选） |
| GND | GND | 地 |
| VCC | 3.3V | 电源（可选） |
连接好之后，打开设备管理器，确认调试器被识别。如果没识别，检查驱动是否安装。
3.3.2 使用OpenOCD烧录
OpenOCD是开源的调试烧录工具，对RISC-V支持很好。烧录命令如下：
openocd -f interface/ftdi/your_debugger.cfg \
-f target/gd32vf103.cfg \
-c "program your_program.hex verify reset exit"
解释一下：
-f interface/...指定调试器配置文件-f target/...指定目标芯片配置文件-c "program ..."执行烧录命令，verify是校验，reset是复位运行，exit是退出
经验之谈： 如果烧录失败，先检查连接线。JTAG线不要太长，超过20cm容易受干扰。另外，目标板要独立供电，不要只靠调试器供电，电流可能不够。
3.4 调试流程
烧录成功只是第一步。程序跑起来之后，怎么知道它运行得对不对？这就需要调试了。
3.4.1 启动GDB调试
Nuclei Studio集成了GDB调试功能。你只需要：
- 点击"Debug"按钮，选择"Debug Configurations"
- 新建一个"GDB OpenOCD Debugging"配置
- 指定可执行文件（.elf）路径
- 指定OpenOCD配置文件和GDB路径
- 点击"Debug"开始调试
调试界面会显示源代码、寄存器值、变量值。你可以设置断点、单步执行、查看内存。
3.4.2 常用调试技巧
- 设置断点：在main函数入口设一个断点，确保程序能跑到main。
- 查看寄存器：调试时查看GPIO控制寄存器的值，确认配置是否正确。
- 单步执行：逐行执行代码，观察LED状态变化。
- 查看反汇编：有时候C代码看起来没问题，但反汇编一看，指令顺序不对，可能是编译器优化导致的。
避坑指南： 我曾经在调试时发现程序卡在某个地方不动，单步也过不去。后来发现是优化等级设得太高（-O3），编译器把一些变量优化掉了，导致调试信息不准确。建议调试时用-O0或-Og优化等级。
3.5 知识体系总览
这一讲的内容比较多，我画了一张图帮你梳理一下整个流程：
从这张图可以看得很清楚：开发环境搭建是基础，工程模板是骨架，编写程序是血肉，编译烧录是过程，调试是验证手段。每一步都环环相扣。
3.6 常见问题与解决
最后，我整理了几个新手最容易遇到的问题，你遇到了可以先对照排查：
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 编译报错"undefined reference" | 启动文件或链接脚本未正确包含 | 检查Makefile中是否添加了startup.S和链接脚本 |
| 烧录失败"no device found" | 调试器未连接或驱动未安装 | 检查硬件连接，重新安装驱动 |
| LED不亮 | GPIO配置错误或引脚不对 | 核对原理图，检查寄存器配置值 |
| 程序跑飞 | 中断向量表未正确设置 | 检查启动文件中的中断向量表地址 |
| 调试时无法设置断点 | 优化等级太高 | 改用-O0或-Og编译 |
嗯，这一讲的内容就到这里。LED闪烁虽然简单，但它是你进入GD32V嵌入式开发世界的第一步。把这个流程跑通了，后面再复杂的项目，无非就是在这个基础上加更多的外设驱动、更复杂的逻辑而已。