hulk/gd32e23x_template_cmake_vscode
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
- README: 修正路径引用 (Tools→Toolchain, 去掉不存在的 Projects/ 层级)
- README: 新增快速开始 / 工程结构 / 板级配置 / 编译烧录章节
- README: 删除 '建议补充内容' 占位章
- cmake: arm-none-eabi-gcc.cmake 工具链找不到时 FATAL_ERROR 而非静默
This commit is contained in:
yelvlab
2026-06-30 11:15:53 +08:00
parent bfa311b70f
commit 38db72d94f
2 changed files with 166 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+162 -41
View File
@@ -8,11 +8,13 @@
- [适用范围](#适用范围)
- [默认配置](#默认配置)
- [快速开始](#快速开始)
- [工程结构](#工程结构)
- [板级配置](#板级配置)
- [工具链准备](#工具链准备)
- [使用说明](#使用说明)
- [时钟配置说明](#时钟配置说明)
- [vcpkg 依赖管理（可选）](#vcpkg-依赖管理可选)
- [建议补充内容](#建议补充内容)
---
@@ -27,44 +29,178 @@
## 默认配置
- MCU 主频：内部 RC 振荡器，系统时钟配置为 72MHz
- 调试串口：USART0（PA2 TX / PA3 RX），115200 波特率
- I2C：默认硬件 I2C0（PF0 SDA / PF1 SCL），可通过 `board_config.h` 切换为软件 I2C
---
## 快速开始
### 基于模板创建新项目
1. **克隆或复制本仓库**
```bash
git clone https://gitea.hulk.wang/hulk/gd32e23x_template_cmake_vscode.git my-new-project
cd my-new-project
```
2. **修改项目配置** — 编辑 `cmake/project_config.cmake`：
```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") # 编译变体
```
3. **添加业务源文件** — 编辑 `CMakeLists.txt`，在 `TARGET_SRC` 中添加你的 `.c` 文件。
4. **配置板级引脚** — 编辑 `Inc/board_config.h`，修改 I2C、UART、LED 等引脚定义。
5. **编译**
```bash
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` 可切换以下功能：
```c
/* I2C 类型：软件 I2C 或 硬件 I2C */
// #define SOFTWARE_IIC
#undef SOFTWARE_IIC
/* 调试模式：开启 printf 输出 */
// #define DEBUG_MODE
#undef DEBUG_MODE
/* 调试详细模式：I2C 扫描等额外信息 */
// #define DEBUG_VERBOSE
#undef DEBUG_VERBOSE
```
引脚定义集中在同一文件中，按需修改：
```c
#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. xPack GNU Arm Embedded GCC Toolchain
### 1. ARM GCC 工具链
- **版本**：xpack-arm-none-eabi-gcc-11.3.1-1.1
- **建议解压路径**：Tools/xpack-arm-none-eabi-gcc-11.3.1-1.1
- **官方下载地址**：https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases
- **路径自定义说明**：
如需自定义工具链路径，请同步修改以下文件：
- `Projects/<BoardName>/<ProjectName>/cmake/arm-none-eabi-gcc.cmake`（第2行）
- `Projects/<BoardName>/<ProjectName>/.vscode/launch.json`（第12行）
- **版本**：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 参数传入：
```bash
cmake --preset Debug -DTOOLCHAIN_DIRECTORY=/your/path/bin
```
### 2. OpenOCD
### 2. OpenOCD（调试/烧录）
- **版本**：xpack-openocd-0.11.0-3
- **建议解压路径**：Tools/xpack-openocd-0.11.0-3
- **获取地址**：https://github.com/burakenez/gd32-tools-xpack-openocd/tree/v0.11.0-3
- **说明**：
- 本版本提取自 Embedded Builder V1.4.1.23782。
- ⚠️ 请勿随意更换版本，因 GD32 MCU 支持有限，推荐严格使用此版本。
- **路径自定义说明**：
如需自定义 OpenOCD 路径，请同步修改以下文件：
- `Projects/<BoardName>/<ProjectName>/.vscode/launch.json`（第14、17行）
- `Projects/<BoardName>/<ProjectName>/.vscode/task.json` 中所有相关路径
- **版本**：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 路径。
---
## 使用说明
1. **准备工具链**
- 按上述说明下载并解压 ARM GCC 和 OpenOCD 到 Tools 目录。
- Toolchain 目录内容不会被 git 跟踪，需自行维护。
### 编译
2. **烧录固件**
- 可直接使用 VSCode 任务栏的 Flash MCU 任务，或命令行运行 OpenOCD。
```bash
# Debug 构建（-O0, -g3）
cmake --preset Debug
cmake --build build/Debug
# Release 构建（-Os, -g0）
cmake --preset Release
cmake --build build/Release
```
### 烧录
通过 VSCode 任务栏运行 `Flash MCU` 任务，或命令行：
```bash
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` | 内存映射 |
---
@@ -84,7 +220,7 @@
2. 取消你需要的时钟方案的注释，并注释掉其它方案。
3. 保存后重新编译工程即可生效。
详细时钟初始化流程可参考 `system_gd32e23x.c` 文件中的 `system_clock_config` 及相关函数实现。
详细时钟初始化流程可参考 `Src/system_gd32e23x.c` 文件中的 `system_clock_config` 及相关函数实现。
---
@@ -122,18 +258,3 @@
2. 启动 VSCode 或命令行，vcpkg 会自动检测并安装所需工具。
如不需要 vcpkg，可忽略本文件。
---
## 建议补充内容
- **快速上手示例**：如 main.c 的最小点灯/串口输出代码片段。
- **常见问题与解答**：如构建失败、烧录失败的排查建议。
- **调试说明**：如何用 VSCode 调试、断点、查看寄存器等。
- **多板卡适配说明**：如有多种硬件，如何切换 BoardName。
- **贡献指南**：如何提交 PR、代码风格约定等。
- **License 说明**：开源协议和版权声明。
---
如需进一步完善或有其他建议，欢迎随时反馈！