Zephyr RTOS 在 GigaDevice GD32F403Z-EVAL 开发板上的入门指南：构建、烧录与调试
【免费下载链接】zephyrPrimary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.项目地址: https://gitcode.com/GitHub_Trending/ze/zephyr
本指南以 Zephyr 仓库中 GD32F403Z-EVAL 板级文档 为主体，系统讲解这款基于 GigaDevice GD32F403ZE（Cortex-M4F）高性价比评估板的硬件资源、启动模式与跳线配置、Zephyr 工程构建流程，以及通过板载 GD-Link 和 ROM Bootloader 两种方式烧录与调试的完整实操步骤。读完本文，你将能够在 Zephyr 环境下独立完成该开发板的hello_world样例编译、烧录、串口监听与 GDB 调试。
开发板概述：面向 GD32F403 高性能 MCU 的调试平台
GD32F403Z-EVAL（board.yml 中定义，板名gd32f403z_eval、全称GD32F403Z-EVAL）是 GigaDevice 官方评估板，用于对 GD32F403 系列 Cortex-M4F 高性能 MCU 进行设计验证与调试。其核心器件 GD32F403ZE 具备以下特性：
- 单核 ARM Cortex-M4F处理器，带硬件浮点单元（FPU）；
- 最高168 MHz主频，Flash 访问零等待周期；
- 512 KiB片内 Flash、96 KiBSRAM；
- 112 个 GPIO引脚；
- 从板级配置 gd32f403z_eval.yaml 可以看到，该板在 Zephyr 中被声明为
arch: arm、ram: 96、flash: 512，支持 counter、pwm、watchdog、dma、spi 等外设，工具链支持zephyr与gnuarmemb。
板载硬件资源清单
按官方板级文档，GD32F403Z-EVAL 板载资源如下：
- USB 接口（mini-USB 连接器）
- 4 个用户 LED与4 个用户按键、复位按键
- CAN 接口
- ADC（连接至电位器）
- 2 路 DAC 通道
- GD25Q40 4 Mib SPI Flash
- HY27UF081G2A 1 GiB NAND Flash
- AT24C02C 2 KiB EEPROM
- 3.2 英寸 TFT LCD（320×240）
- PCM1770 立体声 DAC（带耳机放大器）
- Micro-SDHC 卡接口
- GD-Link 板载调试器——基于 CMSIS-DAP SWD 接口、通过 USB HID 实现调试通信
上述大部分外设在 Zephyr 设备树 gd32f403z_eval.dts 中均有对应节点或可扩展空间：例如 4 个 LED 分别映射到 GPIOF0–GPIOF3（led2~led5），4 个按键映射到 GPIOA0（唤醒键）、GPIOC13（篡改键）、GPIOF4/GPIOF5（用户键 1/2），并定义了led0 = &led2、sw0 = &user_key1、pwm-led0 = &pwm_led、watchdog0 = &fwdgt等别名，供 Zephyr 应用通过标准设备树别名直接引用。
串口：默认控制台配置
GD32F403Z-EVAL 共提供5 个串行通信端口，其中默认端口为UART0（即 USART0），位于PIN-9 / PIN-10。从 gd32f403z_eval-pinctrl.dtsi 的引脚复用定义可以确认：
USART0_TX_PA9_NORMP：TX 复用至 PA9；USART0_RX_PA10_NORMP：RX 复用至 PA10。
在 gd32f403z_eval.dts 中，chosen节点将控制台与 shell 串口均指向usart0（zephyr,console = &usart0、zephyr,shell-uart = &usart0），并配置current-speed = <115200>；gd32f403z_eval_defconfig 中则启用了CONFIG_CONSOLE=y、CONFIG_UART_CONSOLE=y、CONFIG_SERIAL=y。因此在默认配置下，hello_world等样例的输出会直接出现在 USART0 上，串口参数固定为115200 波特率、8 数据位、无校验、1 停止位（8N1）。
启动模式与跳线配置
在烧录程序之前，必须先配置好启动（Boot）设置与串口路由跳线。板级文档给出了两组关键的跳线表：
Boot-0 / Boot-1：启动源选择
| Boot-0 | Boot-1 | 功能 |
|---|---|---|
| 1-2 | 1-2 | SRAM（从 SRAM 启动） |
| 1-2 | 2-3 | Bootloader（从系统 ROM Bootloader 启动） |
| 2-3 | 任意 | Flash（从主 Flash 启动，正常运行模式） |
开发板默认从Flash 启动（Boot-0 = 2-3）。当需要使用 GD32 内置 ROM Bootloader 进行 ISP 烧录时，需将 Boot-0 跳线置于 1-2、Boot-1 置于 2-3，详见后文“使用 ROM Bootloader”一节。
JP-5 / JP-6：串口路由选择
| JP-5 | JP-6 | 功能 |
|---|---|---|
| 1-2 | 1-2 | USART0 连接到串口座 J2 |
| 2-3 | 2-3 | USB VBUS/ID 信号路由 |
| open | open | 悬空（Free） |
默认情况下 USART0 通过JP-5/6 = 1-2/1-2路由到 J2 串口座，配合 USB 转串口线（Linux 下通常识别为/dev/ttyUSB0）即可完成串口输出监听。
构建 Zephyr 内核与 hello_world 样例
在开始构建前，请确认已按 Zephyr 官方流程完成环境安装与工具链配置（west、CMake、Ninja 及对应的 ARM 交叉工具链）。构建命令如下：
west build -b gd32f403z_eval samples/hello_world该命令会以gd32f403z_eval为目标板编译 samples/hello_world 样例。构建产物中会包含可烧录的固件镜像；若需要以 OpenOCD 方式调试，板级 support/openocd.cfg 中提供了配套的 OpenOCD 目标配置：接口为cmsis-dap（对应 GD-Link）、传输方式swd、芯片名gd32f403ze、CPUTAPID 0x790007a3、FLASH_SIZE 0x80000（512 KiB），并复用了 stm32f1x 的目标脚本。
使用板载 GD-Link 烧录与调试
GD32F403Z-EVAL 板载了 GD-Link 编程/调试器，可通过 USB 完成固件烧录与在线调试；此外板上的 J1、J100 编程/调试排针也支持任何兼容 ARM 的工具（如外部 J-Link、OpenOCD）。
从 board.cmake 可以看到，该板同时注册了openocd与gd32isp两种 runner（其中gd32isp指定器件型号--device=GD32F403ZET6），因此west flash的默认行为取决于环境中的可用工具。
步骤 1：构建固件
west build -b gd32f403z_eval samples/hello_world步骤 2：监听串口输出
在 Linux 下，GD-Link 虚拟串口通常为/dev/ttyUSB0。使用 minicom 监听：
$ minicom -D /dev/ttyUSB0 -o-o选项表示 minicom 不发送 modem 初始化字符串。连接参数必须配置为：
- 速度（Speed）：115200
- 数据位（Data）：8 bits
- 校验（Parity）：None
- 停止位（Stop bits）：1
步骤 3：烧录镜像
west flash（完整形式为west build -b gd32f403z_eval samples/hello_world后执行west flash。）烧录完成后按复位键，终端应输出：
Hello World! gd32f403z_eval步骤 4：GDB 调试
west debug该命令会通过 GD-Link 的 SWD 接口启动调试会话。在 Zephyr 默认配置下，gd32f403z_eval_defconfig 还启用了CONFIG_ARM_MPU=y与CONFIG_HW_STACK_PROTECTION=y，即默认固件自带 MPU 硬件栈保护，调试时可利用硬件断点（gdb_breakpoint_override hard）进行可靠的单步与断点调试。
使用 ROM Bootloader（GD32 ISP）烧录
GD32F403 内置 ROM Bootloader，支持通过串口进行 ISP 编程，无需额外调试器。用户需要先安装 GigaDevice 官方提供的GD32 ISP Console软件（建议安装路径为$HOME/.local/bin，具体安装方式请以 GigaDevice 官方发布包为准）。
步骤 1：构建固件
west build -b gd32f403z_eval samples/hello_world步骤 2：进入 Bootloader 模式
- 移除 boot-0 跳线（即 Boot-0 由 2-3 拨到 1-2，配合 Boot-1 的 2-3 进入 Bootloader 启动源）；
- 按下复位按键，使 MCU 从 ROM Bootloader 启动。
步骤 3：通过 gd32isp runner 烧录
west flash -r gd32isp [--port=/dev/ttyUSB0]其中-r gd32isp显式指定使用 GD32 ISP 烧录方式（对应 board.cmake 中的gd32isprunner 与器件参数--device=GD32F403ZET6）；--port用于指定串口设备，Linux 下通常为/dev/ttyUSB0。
步骤 4：监听串口输出并复位
与 GD-Link 方式相同，监听串口：
$ minicom -D /dev/ttyUSB0 -o串口参数依旧为115200 / 8 / None / 1。烧录完成后，按下复位按键，使 MCU 从 Flash 启动运行新固件，终端应输出：
Hello World! gd32f403z_eval小结
GD32F403Z-EVAL 在 Zephyr 中提供了开箱即用的板级支持：设备树 gd32f403z_eval.dts 完整定义了 LED、按键、串口、ADC、PWM 与看门狗，引脚复用由 gd32f403z_eval-pinctrl.dtsi 统一管理；烧录调试方面同时支持板载 GD-Link（OpenOCD/CMSIS-DAP SWD）与 GD32 ROM Bootloader（gd32isp）两条路径。对于需要零等待 Flash 高性能执行、且预算敏感的 Cortex-M4F 应用场景，这块开发板是快速验证 Zephyr 应用的实用起点。
【免费下载链接】zephyrPrimary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.项目地址: https://gitcode.com/GitHub_Trending/ze/zephyr
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
