288 lines
8.6 KiB
Markdown
288 lines
8.6 KiB
Markdown
# GD32E23x 工程模板
|
||
|
||
本仓库为兆易创新 GD32E23x 系列 MCU 的 CMake + VSCode 工程模板，适合嵌入式开发快速上手和团队协作。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [适用范围](#适用范围)
|
||
- [默认配置](#默认配置)
|
||
- [快速开始](#快速开始)
|
||
- [工程结构](#工程结构)
|
||
- [板级配置](#板级配置)
|
||
- [Flash 偏移配置（配合 Bootloader）](#flash-偏移配置配合-bootloader)
|
||
- [工具链准备](#工具链准备)
|
||
- [使用说明](#使用说明)
|
||
- [时钟配置说明](#时钟配置说明)
|
||
- [vcpkg 依赖管理（可选）](#vcpkg-依赖管理可选)
|
||
|
||
---
|
||
|
||
## 适用范围
|
||
|
||
- 适用于兆易创新 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
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 基于模板创建新项目
|
||
|
||
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
|
||
```
|
||
|
||
---
|
||
|
||
## Flash 偏移配置（配合 Bootloader）
|
||
|
||
如果固件需要通过 Bootloader 启动（Bootloader 占用 Flash 前部区域），需修改两处：
|
||
|
||
**1. 链接脚本** — `LD/gd32e23x_flash.ld` 第 15 行：
|
||
```c
|
||
// 默认：从 Flash 起始运行
|
||
FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 16K
|
||
|
||
// 配合 Bootloader：前 8KB 留给 Bootloader，App 从 0x08002000 开始
|
||
FLASH (rx) : ORIGIN = 0x08002000, LENGTH = 8K
|
||
```
|
||
|
||
**2. 向量表偏移** — `Src/system_gd32e23x.c` 第 44 行：
|
||
```c
|
||
// 默认
|
||
#define VECT_TAB_OFFSET (uint32_t)0x00
|
||
|
||
// 配合 Bootloader（值 = Flash 偏移量，不含 0x0800 前缀）
|
||
#define VECT_TAB_OFFSET (uint32_t)0x2000
|
||
```
|
||
|
||
> ⚠️ 两个偏移值必须对应修改：`LD` 中的 `ORIGIN` 减去 `0x08000000` 应等于 `VECT_TAB_OFFSET`。
|
||
|
||
---
|
||
|
||
## 工具链准备
|
||
|
||
### 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 参数传入：
|
||
```bash
|
||
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 路径。
|
||
|
||
---
|
||
|
||
## 使用说明
|
||
|
||
### 编译
|
||
|
||
```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` | 内存映射 |
|
||
|
||
---
|
||
|
||
## 时钟配置说明
|
||
|
||
本工程默认系统时钟为内部 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)
|
||
```
|
||
2. 取消你需要的时钟方案的注释，并注释掉其它方案。
|
||
3. 保存后重新编译工程即可生效。
|
||
|
||
详细时钟初始化流程可参考 `Src/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，可忽略本文件。
|