企业官网建设流程全解析

简介：面向GD32F303VCT6开发者的Demo板软硬件资料包，覆盖PDF原理图、中文使用说明、23个基础例程以及GD固件库，构成从电路理解到代码移植的完整开发链路，适合嵌入式入门工程师和电子爱好者进行单片机评估与原型验证。压缩包内共480个文件，以C/H源码文件、Keil与IAR工程文件、PDF文档和文本说明为主，整体仅3.84MB，目录按例程编号组织，便于按需检索和对照实验。23个例程覆盖GPIO按键中断/轮询、USART打印与DMA收发、ADC双通道采集、DAC输出电压、I2C EEPROM、SPI Flash、I2S音频播放、EXMC扩展NAND Flash与触摸屏、SDIO读写SD卡、CAN组网、RCU时钟输出、CTC校准、PMU低功耗唤醒等典型外设场景，并配有中文说明与原理图，读者可以结合硬件电路学习初始化代码和中断配置思路，加深对GD32库函数风格与外设寄存器配置的理解。GD固件库代码同样可用于其他GD32F30x系列项目，减少重复移植工作，提升开发效率。目前已有484人学习下载，资料完整且体积小巧，非常适合嵌入式开发学习者对照动手实践。

1. GD32F303VCT6 Demo 板资料包的打开方式

拆开快递袋时，桌上通常有两样东西：一块 GD32F303VCT6 Demo 板，和一个名为“GD固件库资料.zip”的压缩包。包里装着 PDF 原理图、中文使用说明、23 个开发板例程和整套 GD 固件库。这套资料要解决的核心问题只有一个：在尽可能短的时间里，确认这颗 Cortex-M4 内核、120MHz 主频、256KB Flash、96KB SRAM 的国产 MCU，能不能在硬件和软件两个层面平替手上的 STM32F103 方案。Demo 板例程提供的是“能跑的最小工程”，固件库解决的是“API 从哪来”，而原理图则回答了“复刻这块板需要带走哪些电路”。适读人群是准备换料评估的硬件工程师、从 ST 标准库转过来的嵌入式工程师，以及需要拿例程给客户做方案验证的 FAE。下面按拿到资料包之后最常见的操作顺序展开：先读原理图，再跑例程，最后把例程改到自己板子上。

2. 先看 PDF 原理图：BOOT、时钟、SWD 三个网络决定硬件能不能跑

原理图在压缩包的硬件资料目录下，打开后不用急着逐脚核对 MCU 的每个网络。先看三组网络：BOOT0/BOOT1、OSC_IN/OSC_OUT、SWDIO/SWCLK/NRST。它们决定了一件事——这块板能不能烧录、能不能启动、能不能把主频配到 120MHz。把这几个网络在 PDF 里用文本搜索定位，比肉眼在整张图上追线快得多。

2.1 BOOT0/BOOT1 跳线：启动介质选择与烧录模式切换

原理图上 BOOT 引脚旁边通常有一组排针或跳线帽，丝印写着 BOOT0、BOOT1。GD32F303 的启动模式表和 STM32F103 基本一致，只是芯片内部 bootloader 存放位置不同。Demo 板默认把跳线帽插在主 Flash 启动位置，对应 BOOT0 拉低。

烧录后复位不进 main，先检查这个跳线帽是不是从“ISP 模式”拨回了“Flash 模式”。用串口 ISP 做固件升级时，把 BOOT0 置 1、BOOT1 置 0，上电后由 bootloader 接管串口，下载完成再拨回 0。BOOT0 为 0 时 BOOT1 电平被忽略，所以日常运行时不用纠结 BOOT1 的状态。顺着丝印“BT0”“BT1”找到引脚后，用万用表量一下实际电平和跳线位置是否一致，能排除排针接触不良的隐性故障。

2.2 外部 8MHz 晶振与 HXTAL 等待：没有它就没有 120MHz

原理图里晶振附近标注 8MHz，两脚分别接 OS_IN/OS_OUT 或 PD0/PD1，具体以 PDF 网络标号为准。GD32F303 上电后默认从内部 IRC8M 启动，此时内核只有约 8MHz。想要跑到 120MHz，必须由外部高速晶振 HXTAL 作为 PLL 输入源，固件库里对应的配置函数会先等待 HXTAL 起振，再配置倍频器。

while (0U == (RCU_CTL & RCU_CTL_HXTALSTB)) { /* wait until HXTAL ready */ }

这段代码逻辑上等价于固件库里 system_gd32f30x.c 的 HXTAL 等待循环：RCU_CTL 是时钟控制寄存器，RCU_CTL_HXTALSTB 位为 1 表示外部高速晶振已经起振。如果自己画的板子晶振虚焊、负载电容不匹配，程序会卡在这个 while 里，表现为主循环完全不跑。快速定位方法：示波器探头点 OSC_OUT 引脚，看不到波形就先把两个负载电容换成原理图推荐值，再查晶振两脚到 MCU 引脚的走线。常见时钟源对照如下。

2.3 SWD 调试口与供电路径：三线连接失败的常见解

SWD 调试口在原理图上只画三根线：SWDIO、SWCLK、GND。三线能应对大部分连接场景，但连接失败时不要第一时间怀疑调试器，先回到原理图查两个东西：NRST 网络和 VDDA 去耦电路。把 NRST 也接到调试器，并在 MDK 的 Debug 设置里选择 Connect under Reset，能绕过已经跑飞或把 SWD 引脚复用成 GPIO 的程序。调试器与 Demo 板各自独立供电时，GND 必须先连通再上电，否则第一次握手大概率失败；共地之后，SWDIO/SWCLK 两脚旁边通常有 10k 量级的上拉电阻，不要在这两条线上再并联强下拉，否则信号电平会被压到识别阈值以下。

提示：原理图里如果用网络标号而不是连线画法，直接在 PDF 搜索框输入 SWDIO、NRST、VBAT，几秒钟就能定位相关引脚，省去整图肉眼的追踪时间。

3. 固件库与 23 个例程：把最小链路跑通

例程的价值不是让你全部看一遍，而是让你用最少的调试工作量验证开发环境、烧录链路和外设时钟树。23 个例程对应 23 个外设场景，其中真正高频用到的是 GPIO、USART、TIMER 三组。先把这三组跑通，后面迁移到自己的板子时才有一个干净对照物。

3.1 固件库资料.zip 解压后，目录结构决定工程能否打开

拿到 zip 第一件事是解压到无中文、无空格的纯英文路径，比如D:\gd32f303_demo。中文路径在 MDK 工程里偶尔会触发头文件包含失败，报错形式五花八门，最容易误导人。解压后典型目录结构如下。

GD32F303_Demo/ ├── Demo_Code/ │ ├── 01_GPIO_LED/ │ ├── 02_USART_Printf/ │ └── ... ├── Doc/ │ ├── GD32F303_Demo_User_Guide_CN.pdf │ └── GD32F303VCT6_Demo_原理图.pdf └── GD32F303_Firmware_Library/ ├── Firmware/ # 标准外设库源码 ├── CMSIS/ # 内核头文件与启动文件 └── Examples/ # 官方外设示例

目录名可能略有出入，但大致是应用工程、文档、固件库三层。MDK 打开.uvprojx后报找不到头文件，通常不是文件缺失，而是uvprojx里的相对路径假设 Demo_Code 和 Firmware_Library 在同一父目录下。只把例程文件夹拷走、固件库留在原地，工程当然打不开。23 个例程共用同一个固件库，正确做法是让每个工程都指回这份公共库路径，而不是往单个工程里复制代码。工程选项里 C/C++ 页面的 Preprocessor Symbols 需要确认GD32F303和USE_STDPERIPH_DRIVER两个宏都在，少了宏会出现外设寄存器定义缺失的编译错误。

3.2 23 个例程怎么挑：先跑 GPIO_LED、USART、TIMER

按依赖顺序挑三个例程就能覆盖最小系统、外设时钟树、中断这三个基础链路。GPIO 例程验证最小系统和推挽输出；USART 例程验证系统时钟配置、串口波特率和 printf 重定向；TIMER 例程验证外设时钟分频和 NVIC 中断路径。这三个跑通后，I2C、SPI、ADC 这些例程会顺很多。

LED 不亮先查 GPIOB 等引脚对应的 RCU 时钟有没有使能；串口输出乱码查波特率分频和外部晶振频率是否匹配；定时器中断不触发查 RCU_APB1/APB2 分频系数。如果 Demo 板原理图上 LED 网络标号不是 PB0/PB1，改一下 main.c 里的引脚宏即可，例程里通常已经把引脚定义放在头文件顶部，方便统一修改。

3.3 编译、烧录的最短命令路径

MDK 需要先安装 GD32F30x 系列的 Device Pack，否则 Device 下拉列表里找不到 GD32F303VC。安装后在 Options for Target 的 Device 页选择 GD32F303VC，Debug 页按实际调试器选择 J-LINK 或 CMSIS-DAP，编译用 F7，下载用 F8。不想每次开 IDE，也可以把烧录命令收敛成一个脚本：

JLinkExe -device GD32F303VC -if SWD -speed 4000 -autoconnect 1 \ -CommanderScript flash.jlink

flash.jlink里放烧录动作：

loadfile ./build/app.hex r g exit

参数说明：-device要与工程选择的型号一致，GD32F303VC 对应 LQFP100、256KB Flash；-if SWD指定调试接口；-speed 4000表示 4MHz SWD 时钟，线长超过 10cm 时降到 1000 更可靠；loadfile会根据后缀自动识别 hex/bin 格式，烧录后r复位、g运行。连接失败就回到 2.3 节把 NRST 接上，用 Connect under Reset 模式再试一次。

4. 把例程迁到自己板子：系统时钟、引脚复用与 printf 三个坑

Demo 板例程能在官方板上跑，换到自己画的板子上通常不会一次成功，问题集中在三处：系统时钟配置宏、GPIO 复用方式、printf 重定向。这三个坑按顺序排查，就能把官方例程改造成自定义硬件的底层驱动模板。

4.1 system_gd32f30x.c 里的时钟宏：120MHz 还是 72MHz

GD32F303 的系统时钟初始化在system_gd32f30x.c中完成，具体行为由文件顶部预定义的宏决定。下载到的例程可能默认开启 120MHz 配置，也可能是 72MHz 兼容配置，直接烧录到板上表现不同。

void system_clock_config(void) { #if defined(__SYSTEM_CLOCK_120M_PLL_8M_HXTAL) if (HXTAL_STATUS_OK == hxtal_state_wait()) { system_clock_120m_hxtal(); } #elif defined(__SYSTEM_CLOCK_72M_PLL_8M_HXTAL) system_clock_72m_hxtal(); #else system_clock_irc8m(); #endif }

宏开关只需要保留一个，多个同时定义会导致第一个分支始终生效，读代码时容易误判。自画板卡在 PLL 等待时，临时把宏改成__SYSTEM_CLOCK_IRC8M让内核先跑起来，就能区分是软件配置问题还是外部晶振硬件问题。GD32F303 的 120MHz 配置与 STM32F103 的 72MHz 配置在 PLL 倍频寄存器和等待周期上不同，不能直接拿 ST 标准库的 SystemInit 来用。

4.2 GPIO 初始化与重映射：不是只改一个引脚号

从 ST 标准库转过来的代码通常会写GPIO_InitStructure.GPIO_Mode = GPIO_Mode_AF_PP。GD 固件库 V2.0 把这套结构体初始化拆成了gpio_mode_set和gpio_output_options_set两个函数，参数含义不变但调用方式变了。以串口 USART1 的引脚初始化为例：

void usart1_pin_init(void) { rcu_periph_clock_enable(RCU_GPIOA); rcu_periph_clock_enable(RCU_USART1); rcu_periph_clock_enable(RCU_AFIO); gpio_mode_set(GPIOA, GPIO_MODE_AF_PP, GPIO_PIN_2); /* TX */ gpio_output_options_set(GPIOA, GPIO_OTYPE_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_2); gpio_mode_set(GPIOA, GPIO_MODE_IN_FLOATING, GPIO_PIN_3); /* RX */ usart_deinit(USART1); usart_baudrate_set(USART1, 115200U); usart_receive_config(USART1, USART_RECEIVE_ENABLE); usart_transmit_config(USART1, USART_TRANSMIT_ENABLE); usart_enable(USART1); }

TX 引脚配成复用推挽GPIO_MODE_AF_PP，RX 引脚配成输入浮空，这是串口引脚最常见配置。RCU_AFIO时钟只有在调用gpio_pin_remap_config改变默认引脚映射时才必须使能，默认映射下写上也不影响。注意 GD32F303 的 USART1 默认引脚在 PA2/PA3，与 STM32F103 习惯用的 PA9/PA10 不同，换芯片型号时先翻资料包里芯片手册的引脚复用表，别直接依据 ST 记忆连线。

4.3 printf 重定向：TBE 标志与 MicroLIB 缺一不可

例程里 printf 能输出，是因为工程里已经重写了fputc。自己建工程时最容易漏掉这一步：

int fputc(int ch, FILE *f) { while (RESET == usart_flag_get(USART1, USART_FLAG_TBE)); usart_data_transmit(USART1, (uint8_t)ch); return ch; }

等待标志用USART_FLAG_TBE而不是USART_FLAG_TC。TBE 表示发送数据寄存器已空，可以立刻写入下一个字符；TC 表示整个发送移位过程结束，用 TC 会让每个字符额外等待一位传输时间。MDK 环境下如果编译器没勾选 Use MicroLIB，这个fputc会触发半主机模式调试请求，程序在第一次 printf 后跑飞。重定向的串口要和实际外设对应，若把 USART1 换成 USART0，usart_flag_get和usart_data_transmit里的USART1参数也要同步替换。

5. 三个验证技巧：SysTick 校时、固件库版本差异、读回校验

5.1 用 SysTick 翻转 LED 校准 120MHz 主频

volatile uint32_t tick_ms = 0; void SysTick_Handler(void) { tick_ms++; } int main(void) { SystemInit(); systick_clock_source_config(SYSTICK_CLOCKSOURCE_HCLK); SysTick_Config(SystemCoreClock / 1000); while (1) { if (tick_ms >= 1000U) { tick_ms = 0U; gpio_bit_toggle(GPIOB, GPIO_PIN_0); /* 板载 LED */ } } }

systick_clock_source_config把 SysTick 计数源设为 HCLK，SystemCoreClock在固件库中与实际主频同步更新。120MHz 配置下，SysTick_Config的重装值是 120000，LED 每秒翻转一次。用示波器看这个引脚，方波周期应该是 2 秒。周期明显偏长，说明 SetCoreClock 宏和实际 PLL 配置不一致；周期异常短则要检查是否误用了 IRC8M 配置。这个验证不依赖串口，板子只接电源和地就能完成。

5.2 固件库 V1.x 与 V2.x 差异：报错别先怀疑自己

网上的 GD32 老例程很多基于 V1.x 库，函数名是GPIO_Init、USART_Init的 ST 风格；V2.0 固件库改成分段式 API，并把外设前缀统一成小写命名。例程编译报“未定义标识符 GPIO_Init”时，先确认 zip 里固件库版本，而不是逐行改调用处。诊断方法：在工程里搜索usart_baudrate_set，能搜到说明已经切到 V2.0 API。迁移老代码时，把新旧库的gd32f30x_usart.h头文件并排打开，按函数功能对照替换，改动量比想象中小得多。

5.3 下载完成后做一次 Flash 读回校验

MDK 的 Flash Download 页面勾选 Verify Code Download，每次下载结束会自动读回比较。勾选后下载变慢，通常是校验范围覆盖了整个 Flash 而不是程序实际占用区域。命令行下单独执行校验更直接：

JLinkExe -device GD32F303VC -if SWD -speed 4000 -autoconnect 1

在 JLink 控制台输入verifybin app.bin 0x08000000，程序区域与 bin 文件一致时返回校验通过。读回校验通过只代表内容一致，不保证业务逻辑正确，但能快速暴露 Flash 下载算法与芯片型号不匹配的问题。量产阶段把这个校验步骤写进烧录脚本，比依赖下载器界面上的绿色对勾更可靠。

本文还有配套的精品资源，点击获取