From 38db72d94faad903c5d34832682d25bb88a8421d Mon Sep 17 00:00:00 2001 From: yelvlab Date: Tue, 30 Jun 2026 11:15:53 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=20README=20=E5=B9=B6?= =?UTF-8?q?=E6=94=B9=E8=BF=9B=E5=B7=A5=E5=85=B7=E9=93=BE=E6=A3=80=E6=B5=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: 修正路径引用 (Tools→Toolchain, 去掉不存在的 Projects/ 层级) - README: 新增快速开始 / 工程结构 / 板级配置 / 编译烧录章节 - README: 删除 '建议补充内容' 占位章 - cmake: arm-none-eabi-gcc.cmake 工具链找不到时 FATAL_ERROR 而非静默 --- README.md | 203 +++++++++++++++++++++++++++------- cmake/arm-none-eabi-gcc.cmake | 4 + 2 files changed, 166 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index a2cadad..dfdb2e7 100644 --- a/README.md +++ b/README.md @@ -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///cmake/arm-none-eabi-gcc.cmake`（第2行） - - `Projects///.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///.vscode/launch.json`（第14、17行） - - `Projects///.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//`： + +| 文件 | 说明 | +|------|------| +| `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 说明**：开源协议和版权声明。 - ---- - -如需进一步完善或有其他建议，欢迎随时反馈！ diff --git a/cmake/arm-none-eabi-gcc.cmake b/cmake/arm-none-eabi-gcc.cmake index 1860b4b..52f84c2 100644 --- a/cmake/arm-none-eabi-gcc.cmake +++ b/cmake/arm-none-eabi-gcc.cmake @@ -26,6 +26,10 @@ set(CMAKE_C_FLAGS_RELEASE "") set(CMAKE_CXX_FLAGS_RELEASE "") set(CMAKE_ASM_FLAGS_RELEASE "") +if(NOT TOOLCHAIN_DIRECTORY) + message(FATAL_ERROR "Cannot find ARM GCC toolchain. Set TOOLCHAIN_DIRECTORY cache variable or install toolchain in one of the default locations.") +endif() + set(CMAKE_COLOR_DIAGNOSTICS ON) set(CMAKE_EXPORT_COMPILE_COMMANDS ON CACHE INTERNAL "")