兆易创新 GD32 微控制器开发指南

编制日期 2026-10-14 ｜ 版本号 Rev 1.0

从选型、环境搭建、第一个工程，到烧录与在线调试——一份面向工程师的实战参考

GD32 是兆易创新（GigaDevice）基于 Arm® Cortex®-M 与 RISC-V 内核的 32 位通用 MCU 家族，覆盖从入门级 Cortex-M23 到高性能 Cortex-M7 的全谱系，并与主流工具链（Keil / IAR / GCC / SEGGER / OpenOCD）及自有 GD32 Embedded Builder 全面兼容。本指南所有型号、工具名与启动模式均来自兆易创新官网与用户手册，可在文末附录 E 溯源。

建议阅读路径：第 2 章选型 → 第 3–4 章搭环境跑通 LED → 第 9–11 章搞懂启动 / 烧录 / 调试 → 第 19–21 章做 DMA、Flash 与量产升级 → 其余按需查阅。

1 · 文档导读与阅读路径

本章说明这份指南的边界、约定与可溯源方式，方便你快速判断「这份资料能不能解决我的问题」。

1.1 覆盖范围

本指南面向基于 GD32 MCU 的嵌入式 firmware 开发，主线覆盖：

• GD32 全系列家族定位、内核差异与选型方法；
• 官方软件工具链（GD32 Embedded Builder、标准固件库 SPL、GD32 All-In-One Programmer、GD-Link、GD32 ISP Console）的安装与使用；
• 第一个工程从新建、配置、编译到下载的完整链路；
• 工程结构、启动文件、系统时钟 RCU、GPIO/EXTI 等基础外设；
• 启动模式（BOOT0/BOOT1）、程序烧录（SWD / ISP / OpenOCD）与在线调试（SWD/JTAG、GDB、ITM）；
• 中断异常、低功耗、通信外设、定时器/ADC/DAC、RTOS 生态与故障速查；
• DMA 数据搬运、Flash 编程与 Option Bytes、量产烧录与固件升级（Bootloader + 双分区回滚）——从「能跑」到「能出货」的产品化环节。

1.2 不覆盖什么

为避免误导，以下内容不在本指南展开：具体某一型号的寄存器级寄存器清单（以对应系列 User Manual 为准）、Linux/RTOS 内核移植细节、图形界面 GUI 库的具体 API、以及第三方闭源中间件的源码级剖析。这些会在第 16 章给出接入路径与官方资源索引。

1.3 版本与事实来源标注约定

GD32 型号众多、各系列差异显著。文中所有「家族 / 内核 / 工具名 / 启动模式」均来自兆易创新官网；涉及具体主频、Flash/SRAM 容量、引脚与寄存器地址等会因系列而变的事实，统一标注「以对应系列 Data Sheet / User Manual 为准」，避免把某一子系列的数值套用到全家族。工具版本号（如 All-In-One 5.x、Embedded Builder 1.5.x）以官网下载中心发布页为准。

1.4 代码与命令的书写约定

• 代码块使用等宽字体；C 代码以 /* USER CODE BEGIN */ 保护区说明固件库生成代码的改写纪律；
• 命令行以 $ 开头表示在宿主机执行，(gdb) 表示 GDB 交互提示符；
• 寄存器名、外设名（如 RCU、GPIOA、USART0）沿用官方固件库命名。

1.5 关于芯参谋工具箱的联动

兆易创新自有生态之外，本系列其他专题（如存储器件选型）常借助「芯参谋」工具箱做料号解析与交叉比对。本指南聚焦 GD32 本身的开发流程；当你需要在 GD32 方案中搭配 XTX 存储器件（SPI NOR / NAND / SD NAND / eMMC）时，可回到对应存储专题的料号速查表做型号映射，二者通过本文附录 C 的命名规则互相对照。

2 · GD32 家族全景与选型

GD32 不是「一颗芯片」，而是一整套覆盖不同定位的 MCU 家族。选型的本质是先定定位，再定内核，最后定具体料号。

2.1 GD32 这个名字的三层含义

理解 GD32 命名，关键是把它拆成三层：

• 品牌层：GD32 是兆易创新（GigaDevice）32 位 MCU 的总品牌，对应竞品中的 STM32；
• 系列层：GD32 之后的字母+数字（如 F10x、F4xx、E5xx、H7xx、VF103）表示产品系列，决定内核、性能档与主打场景；
• 型号层：系列后的具体料号（如 GD32F103C8T6）决定封装、Flash/SRAM 容量与温度等级。

2.2 料号命名规则

以最常见的 GD32F103C8T6 为例，其拆解遵循「系列 + 子系列 + 引脚 + 容量 + 封装 + 温度」的约定：

2.3 七大定位全景

GD32 按应用场景分为七大定位，图 1 给出各定位下的系列与内核分布。

来源：来源：兆易创新官网 GD32 MCU 产品页 / 用户手册

2.4 主流系列详解

对大多数项目而言，主流型与高性能型是主战场：

2.5 低功耗 / 无线 / 车规

2.6 选型决策树

1. 先定功耗预算：纽扣电池 / 能量采集 → 低功耗系列（GD32L23，Cortex-M23）；否则继续。
2. 再定算力需求：需要 >200MHz、FPU/DSP、大容量 Flash → 高性能（F4/G5/F5/E5/H7）；常规控制 72–120MHz 足够 → 主流（F10/F30/C1/E1）。
3. 是否需要无线：Wi-Fi/BLE → GD32W515（M4）或 GD32VW553（RISC-V）；否则跳过。
4. 是否车规：AEC-Q100 / 功能安全 → 车规系列（A10/A490/A5/A7）。
5. 成本极致：大批量、引脚少 → 入门（C2/E23/F1x0/F3x0）。
6. 生态兼容：若原有 STM32F1 代码要平滑迁移，优先 GD32F10x（引脚/软件高度兼容）。

2.7 最容易忽略的四件事

2.8 文档体系的四份必读件

每个 GD32 系列都配套四份官方文档，开发前务必备齐：

3 · 开发环境工具链全景

GD32 的工具链可以概括为「一套 IDE + 一套固件库 + 两类烧录软件 + 一枚调试器」。先看清各自分工，再决定走哪条路。

3.1 四件套的分工

来源：来源：兆易创新 GD32 MCU 资料下载中心与生态系统页

3.2 GD32 Embedded Builder（官方 IDE）

兆易创新自有的集成开发环境 GD32 Embedded Builder（早期版本称 GD32 IDE），定位对标 STM32CubeIDE：

• 支持 图形化外设配置后自动生成初始化代码，再完成编译与调试，一条龙闭环；
• 同时支持 Arm（Cortex-M）与 RISC-V 双内核工程；
• 内置 GCC 工具链与调试器对接，开箱即用，无需自行拼装 Keil/OpenOCD；
• 版本随官网更新（本文写作时约 1.5.x），建议始终从下载中心取最新版。

3.3 GD32 标准固件库（SPL）

GD32 提供与 CMSIS（Cortex Microcontroller Software Interface Standard）兼容的标准固件库（Standard Peripheral Library），按系列分发：

固件库包含各外设的驱动函数、数据结构、宏定义以及完整例程，是绝大多数官方例程与评估板 Demo 的基础。即便使用 Embedded Builder 的代码生成，其底层也建立在固件库 / CMSIS 之上。

3.4 烧录与量产软件

• GD32 All-In-One Programmer：图形化烧录工具，支持多接口（串口、USB、GD ISP Bridge）与多协议（UART / I2C / OSPI / DFU / HID / CAN / LIN），可完成固件下载、芯片擦除、Flash 读写、Option Bytes 配置，覆盖开发、测试与量产。
• GD-Link Utility Programmer：配合 GD-Link 硬件使用，除读写 Flash、配置 Option Bytes 外，还支持 GD-Link 离线下载与固件升级。
• GD32 ISP Console：命令行版本的 ISP 烧录工具，提供 Windows 与 Linux 版本，适合脚本化、自动化产线。

3.5 第三方工具链怎么选

3.6 环境自检清单

• 已安装 GD32 Embedded Builder（或 Keil/IAR + 对应系列 DFP/AddOn）；
• 已安装 GD-Link 驱动，设备管理器中能看到 GD-Link 或虚拟串口；
• 已下载对应系列的标准固件库与 Data Sheet / User Manual；
• 开发板通过 USB 上电，板载 GD-Link 指示灯正常；
• 能打开 All-In-One Programmer 并识别到芯片（读出芯片型号与 Flash 大小）。

4 · 第一个工程：从零到 LED 闪烁

这一章用「点亮一颗 LED」把整条链路走通。流程见图 3：

4.1 硬件准备

• 一块 GD32 开发板（推荐 START 学习板、GD32F3 红枫派或任意 *-EVAL 全功能评估板，均板载 GD-Link）；
• 一根 USB 数据线（多数板载 GD-Link 一线复用「供电 + 调试 + 日志」）；
• 若用外置调试器，准备 GD-Link 或 J-Link 与 4 芯 SWD 排线。

4.2 第一步：新建工程

在 GD32 Embedded Builder 中选择 File → New → GD32 Project，在芯片选择器中选定具体型号（如 GD32F303xxxx）。向导会按型号拉起图形化配置界面，并自动带入该系列的时钟树与引脚默认约束。

4.3 第二步：配置时钟与 GPIO

在配置界面里：

• 启用外部高速晶振 HXTAL（如 8MHz），配置 RCU（Reset and Clock Unit）将系统时钟倍频到目标频率；
• 将 LED 所在引脚（如 PA1）配置为 GPIO 输出（推挽）；
• 保存配置，IDE 据此生成 rcu / gpio 的初始化代码。

4.4 第三步：生成代码

点击「生成代码 / Generate Code」。IDE 会在工程目录下写出 main.c、各外设初始化文件，并保留 /* USER CODE BEGIN */ 保护区，后续重新生成不会覆盖你写在这里的业务代码。

4.5 第四步：编写业务代码

在 main() 的 USER CODE 区加入闪烁逻辑：

while (1) {
    gpio_bit_set(GPIOA, GPIO_PIN_1);      /* LED 亮 */
    delay_1ms(500);
    gpio_bit_reset(GPIOA, GPIO_PIN_1);    /* LED 灭 */
    delay_1ms(500);
}

4.6 第五步：编译

点击 Build，控制台应出现 Build finished 并产出 .elf / .hex / .bin。若报找不到系列头文件，通常是固件库路径未加入工程包含目录，回到工程属性 → C/C++ Include 补上固件库 Include 路径即可。

4.7 第六步：下载与运行

点击 Download / Debug，IDE 通过板载 GD32-Link 以 SWD 方式把固件写入 Flash 并自动复位运行。也可脱离 IDE，用 All-In-One Programmer 打开 .hex 选择「下载」完成烧录。

4.8 第七步：验证

观察 LED 按 1Hz 周期闪烁即表示链路打通。此处验证的不只是 GPIO，而是时钟配置、链接脚本、启动文件、下载通道四者同时正确。

4.9 常见失败与排查