From 9e6333dca896253f7e982f8b7300611b6c3ab9a9 Mon Sep 17 00:00:00 2001 From: yelvlab Date: Sun, 10 Aug 2025 06:54:55 +0800 Subject: [PATCH] update readme --- .vscode/extensions.json | 26 ++++++++ README.md | 138 ++++++++++++++++++++++++++++++++++------ 2 files changed, 144 insertions(+), 20 deletions(-) create mode 100644 .vscode/extensions.json diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..3243635 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,26 @@ +{ + "recommendations": [ + "ms-vscode.cmake-tools", + "ms-vscode.cpptools", + "ms-vscode.cpptools-extension-pack", + "ms-vscode.cpptools-themes", + "ms-vscode.vscode-embedded-tools", + "ms-vscode.hexeditor", + "ms-vscode.notepadplusplus-keybindings", + "twxs.cmake", + "xaver.clang-format", + "marus25.cortex-debug", + "cheshirekow.cmake-format", + "mcu-debug.debug-tracker-vscode", + "mcu-debug.memory-view", + "mcu-debug.peripheral-viewer", + "mcu-debug.rtos-views", + "trond-snekvik.gnu-mapfiles", + "zixuanwang.linkerscript", + "gurumukhi.selected-lines-count", + "gruntfuggly.todo-tree", + "vscode-icons-team.vscode-icons", + "jeff-hykin.better-cpp-syntax", + "dan-c-underwood.arm" + ] +} \ No newline at end of file diff --git a/README.md b/README.md index 1306bb5..a2cadad 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,139 @@ # GD32E23x 工程模板 -本仓库为 GD32E23x 系列 MCU 的 CMake + VSCode 工程模板。 +本仓库为兆易创新 GD32E23x 系列 MCU 的 CMake + VSCode 工程模板，适合嵌入式开发快速上手和团队协作。 + +--- + +## 目录 + +- [适用范围](#适用范围) +- [默认配置](#默认配置) +- [工具链准备](#工具链准备) +- [使用说明](#使用说明) +- [时钟配置说明](#时钟配置说明) +- [vcpkg 依赖管理（可选）](#vcpkg-依赖管理可选) +- [建议补充内容](#建议补充内容) + +--- ## 适用范围 + - 适用于兆易创新 GD32E23x 系列 Cortex-M23 内核单片机 - 支持标准外设库开发 -- 推荐使用 VSCode + CMake + ARM GCC 工具链 +- 推荐开发环境：VSCode + CMake + ARM GCC 工具链 + +--- ## 默认配置 + - MCU 主频：内部 RC 振荡器，系统时钟配置为 72MHz -- 工程结构清晰，便于二次开发和移植 + +--- + +## 工具链准备 + +### 1. xPack GNU Arm Embedded GCC Toolchain + +- **版本**：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行） + +### 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` 中所有相关路径 + +--- ## 使用说明 -1. 手动准备工具链： - - 请将 ARM GCC 工具链（如 xpack-arm-none-eabi-gcc）和 OpenOCD 解压到本工程的 Toolchain 目录下。 - - Toolchain 目录内容不会被 git 跟踪，需自行维护。 -2. 使用 CMake 构建工程： - - 推荐使用 VSCode 的 CMake Tools 插件，或命令行执行： - ```bash - cmake -S . -B Build/Debug -G "Ninja" -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi-gcc.cmake - cmake --build Build/Debug - ``` -3. 通过 OpenOCD 烧录固件： - - 可直接使用 VSCode 任务栏的 Flash MCU 任务，或命令行运行 OpenOCD。 + +1. **准备工具链** + - 按上述说明下载并解压 ARM GCC 和 OpenOCD 到 Tools 目录。 + - Toolchain 目录内容不会被 git 跟踪，需自行维护。 + +2. **烧录固件** + - 可直接使用 VSCode 任务栏的 Flash MCU 任务，或命令行运行 OpenOCD。 + +--- ## 时钟配置说明 + 本工程默认系统时钟为内部 IRC8M 振荡器经 PLL 倍频后的 72MHz。 如需修改主频或时钟源，请编辑 `Src/system_gd32e23x.c` 文件： + 1. 查找如下宏定义区： - ```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) - ``` + ```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) + ``` 2. 取消你需要的时钟方案的注释，并注释掉其它方案。 3. 保存后重新编译工程即可生效。 详细时钟初始化流程可参考 `system_gd32e23x.c` 文件中的 `system_clock_config` 及相关函数实现。 + +--- + +## vcpkg 依赖管理（可选） + +本工程可选支持 vcpkg 作为 C/C++ 工具链和构建工具的自动化依赖管理方案。 + +- 自动下载和管理如 CMake、Ninja 等构建工具，简化环境配置。 +- 可扩展用于第三方 C/C++ 库的统一管理。 + +**启用方法**： +1. 在项目根目录创建 `vcpkg-configuration.json` 文件，内容如下： + + ```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" + } + } + ``` + +2. 启动 VSCode 或命令行，vcpkg 会自动检测并安装所需工具。 + +如不需要 vcpkg，可忽略本文件。 + +--- + +## 建议补充内容 + +- **快速上手示例**：如 main.c 的最小点灯/串口输出代码片段。 +- **常见问题与解答**：如构建失败、烧录失败的排查建议。 +- **调试说明**：如何用 VSCode 调试、断点、查看寄存器等。 +- **多板卡适配说明**：如有多种硬件，如何切换 BoardName。 +- **贡献指南**：如何提交 PR、代码风格约定等。 +- **License 说明**：开源协议和版权声明。 + +--- + +如需进一步完善或有其他建议，欢迎随时反馈！