Template

Files

T

hulk 38db72d94f docs: 修正 README 并改进工具链检测

- README: 修正路径引用 (Tools→Toolchain, 去掉不存在的 Projects/ 层级)
- README: 新增快速开始 / 工程结构 / 板级配置 / 编译烧录章节
- README: 删除 '建议补充内容' 占位章
- cmake: arm-none-eabi-gcc.cmake 工具链找不到时 FATAL_ERROR 而非静默

2026-06-30 11:15:53 +08:00

7.8 KiB

Raw Blame History

GD32E23x 工程模板

本仓库为兆易创新 GD32E23x 系列 MCU 的 CMake + VSCode 工程模板，适合嵌入式开发快速上手和团队协作。

适用范围

适用于兆易创新 GD32E23x 系列 Cortex-M23 内核单片机
支持标准外设库开发
推荐开发环境：VSCode + CMake + ARM GCC 工具链

默认配置

MCU 主频：内部 RC 振荡器，系统时钟配置为 72MHz
调试串口：USART0（PA2 TX / PA3 RX），115200 波特率
I2C：默认硬件 I2C0（PF0 SDA / PF1 SCL），可通过 board_config.h 切换为软件 I2C

快速开始

基于模板创建新项目

克隆或复制本仓库

git clone https://gitea.hulk.wang/hulk/gd32e23x_template_cmake_vscode.git my-new-project
cd my-new-project

修改项目配置 — 编辑 cmake/project_config.cmake：

set(PROJECT_NAME "MyProject")     # 项目名称
set(BOARD_TYPE_CODE 20)           # 板卡类型码（协议帧中的标识）
set(VERSION_MAJOR 1)              # 主版本号
set(VERSION_MINOR 0)              # 次版本号
set(VERSION_PATCH 0)              # 修订号
set(BUILD_VARIANT "APP")          # 编译变体

添加业务源文件 — 编辑 CMakeLists.txt，在 TARGET_SRC 中添加你的 .c 文件。
配置板级引脚 — 编辑 Inc/board_config.h，修改 I2C、UART、LED 等引脚定义。
编译
```
cmake --preset Debug
cmake --build build/Debug
```
产物在 build/Debug/ 下，包含 .elf、.hex、.bin、.map、.list。

分支说明

分支	用途
`template_pc`	主模板（推荐），用于桌面端 VSCode 开发
`template_xl`	小琅适配版
`main`	早期版本，不推荐使用

工程结构

.
├── CMakeLists.txt              # 主构建文件
├── CMakePresets.json           # CMake 预设（Debug/Release）
├── cmake/
│   ├── arm-none-eabi-gcc.cmake # ARM GCC 工具链配置
│   ├── project.cmake           # 编译选项（-Os/-O0, -mcpu=cortex-m23）
│   ├── project_config.cmake    # 项目名/版本号/编译变体
│   └── version.h.in            # 自动生成固件版本头
├── Inc/                        # 头文件
│   ├── board_config.h          # 板级引脚定义 + 功能开关
│   ├── command.h               # 串口命令协议
│   ├── i2c.h / led.h / systick.h / uart.h
│   └── uart_ring_buffer.h / gd32e23x_it.h / gd32e23x_libopt.h
├── Src/                        # 源码
│   ├── main.c                  # 入口函数
│   ├── command.c               # 命令解析处理
│   ├── board_config.c          # MCU 型号自动检测
│   ├── i2c.c / led.c / systick.c / uart.c / uart_ring_buffer.c
│   └── gd32e23x_it.c / system_gd32e23x.c / syscalls.c
├── SDK/
│   ├── CMSIS/                  # ARM CMSIS Core (Cortex-M23) + GD 启动文件
│   └── GD32E23x_standard_peripheral/  # GD32 标准外设库
├── LD/gd32e23x_flash.ld        # 链接脚本
├── doc/                        # 芯片数据手册
└── .vscode/                    # VSCode 调试/烧录配置

板级配置

编辑 Inc/board_config.h 可切换以下功能：

/* I2C 类型：软件 I2C 或 硬件 I2C */
// #define SOFTWARE_IIC
#undef  SOFTWARE_IIC

/* 调试模式：开启 printf 输出 */
// #define DEBUG_MODE
#undef  DEBUG_MODE

/* 调试详细模式：I2C 扫描等额外信息 */
// #define DEBUG_VERBOSE
#undef  DEBUG_VERBOSE

引脚定义集中在同一文件中，按需修改：

#define I2C_SCL_PORT    GPIOF
#define I2C_SCL_PIN     GPIO_PIN_1
#define I2C_SDA_PORT    GPIOF
#define I2C_SDA_PIN     GPIO_PIN_0

#define LED_PORT        GPIOA
#define LED_PIN         GPIO_PIN_7

#define UART_TX_PIN     GPIO_PIN_2
#define UART_RX_PIN     GPIO_PIN_3

工具链准备

1. ARM GCC 工具链

版本：xpack-arm-none-eabi-gcc-11.3.1-1.1
建议解压路径：工程根目录下 Toolchain/xpack-arm-none-eabi-gcc-11.3.1-1.1
官方下载地址：https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases
路径自定义：如需自定义工具链路径，修改 cmake/arm-none-eabi-gcc.cmake 中的 _TOOLCHAIN_CANDIDATES 列表，或通过 CMake 参数传入：
```
cmake --preset Debug -DTOOLCHAIN_DIRECTORY=/your/path/bin
```

2. OpenOCD（调试/烧录）

版本：xpack-openocd-0.11.0-3
建议解压路径：任意位置（在 .vscode/launch.json 中配置路径）
获取地址：https://github.com/burakenez/gd32-tools-xpack-openocd/tree/v0.11.0-3
说明：
- 本版本提取自 Embedded Builder V1.4.1.23782。
- ⚠️ 请勿随意更换版本，因 GD32 MCU 支持有限，推荐严格使用此版本。
路径自定义：修改 .vscode/launch.json 中 miDebuggerPath 和 serverpath 指向你的 OpenOCD 路径。

使用说明

编译

# Debug 构建（-O0, -g3）
cmake --preset Debug
cmake --build build/Debug

# Release 构建（-Os, -g0）
cmake --preset Release
cmake --build build/Release

烧录

通过 VSCode 任务栏运行 Flash MCU 任务，或命令行：

openocd -f interface/cmsis-dap.cfg -f target/gd32e23x.cfg -c "program build/Debug/Application.elf verify reset exit"

产物

编译输出位于 build/<Config>/：

文件	说明
`Application.elf`	ELF 固件（调试用）
`{项目名}_{版本}_{编译条件}_{日期}.hex`	Hex 文件
`{项目名}_{版本}_{编译条件}_{日期}.bin`	二进制文件
`{项目名}_{版本}_{编译条件}_{日期}.list`	反汇编清单
`{项目名}_{版本}_{编译条件}_{日期}.map`	内存映射

时钟配置说明

本工程默认系统时钟为内部 IRC8M 振荡器经 PLL 倍频后的 72MHz。

如需修改主频或时钟源，请编辑 Src/system_gd32e23x.c 文件：

查找如下宏定义区：

// #define __SYSTEM_CLOCK_8M_HXTAL              (__HXTAL)
// #define __SYSTEM_CLOCK_8M_IRC8M              (__IRC8M)
// #define __SYSTEM_CLOCK_72M_PLL_HXTAL         (uint32_t)(72000000)
#define __SYSTEM_CLOCK_72M_PLL_IRC8M_DIV2    (uint32_t)(72000000)

取消你需要的时钟方案的注释，并注释掉其它方案。
保存后重新编译工程即可生效。

详细时钟初始化流程可参考 Src/system_gd32e23x.c 文件中的 system_clock_config 及相关函数实现。

vcpkg 依赖管理（可选）

本工程可选支持 vcpkg 作为 C/C++ 工具链和构建工具的自动化依赖管理方案。

自动下载和管理如 CMake、Ninja 等构建工具，简化环境配置。
可扩展用于第三方 C/C++ 库的统一管理。

启用方法：

在项目根目录创建 vcpkg-configuration.json 文件，内容如下：

{
  "registries": [
    {
      "name": "microsoft",
      "location": "https://aka.ms/vcpkg-ce-default",
      "kind": "artifact"
    },
    {
      "name": "arm",
      "location": "https://aka.ms/vcpkg-artifacts-arm",
      "kind": "artifact"
    }
  ],
  "requires": {
    "arm:tools/ninja-build/ninja": "^1.12.0",
    "arm:tools/kitware/cmake": "^3.28.4"
  }
}

启动 VSCode 或命令行，vcpkg 会自动检测并安装所需工具。

如不需要 vcpkg，可忽略本文件。

7.8 KiB Raw Blame History Unescape Escape