generated from hulk/gd32f4xx_template_cmake_vscode
106 lines
7.6 KiB
Markdown
106 lines
7.6 KiB
Markdown
# GD32F4xx 工程模板 — AGENTS.md
|
||
|
||
## 项目约定
|
||
|
||
- **用途**：兆易创新 GD32F4xx 系列 MCU（Cortex-M4）的 CMake + VSCode 工程模板，
|
||
组织方式与编译方法沿用 `E:\Hulk-Coding\gd32e23x_template_cmake_vscode`（其源头为
|
||
celalkismiroglu/gd32e23x-demo-suites-cmake）。
|
||
- **默认目标**：GD32F405RET6（设备宏 `GD32F405`，硬件 FPU fpv4-sp-d16 / hard ABI；
|
||
512K Flash / 128K RAM + 64K TCMRAM，链接脚本 xE）。
|
||
- **板级实际配置（demo 板实测）**：无外部晶振 → 时钟源 **IRC16M PLL 168MHz**
|
||
（`system_gd32f4xx.c` 启用 `__SYSTEM_CLOCK_168M_PLL_IRC16M`；HXTAL 方案在无晶振
|
||
时会死循环等待）；LED = **PA15**；调试串口 = **USART1（PA2 TX / PA3 RX，AF7，
|
||
纯串口非 RS485；GD 外设编号比 STM32 小 1，PA2/PA3=USART1@0x40004400）**，
|
||
printf 经 `syscalls.c` 的 `_write`→`__io_putchar` 重定向到
|
||
USART1（`DEBUG_UART` 宏），`DEBUG_MODE` 打开后输出（模板现阶段默认开启，
|
||
发布前改回 `CFG_DISABLE`）。
|
||
- **语言/工具链**：C（gnu11）+ ARM GCC 交叉工具链（本机已验证 xpack 15.2.1；
|
||
E23x 侧曾验证 11.3.1 / 12.3.1）、CMake ≥ 3.20 + Ninja、VSCode + CMake Tools +
|
||
cortex-debug。工具链路径经环境变量 `GD32_GCC_BIN` 提供，不入仓库。
|
||
- **目录约定**：
|
||
- `Build/` —— CMake 构建树与产物（`Build/<Debug|Release>`），gitignore，
|
||
可随时整目录删除。
|
||
- `SDK/` —— CMSIS（core_cm4 + GD32F4xx 设备头 + GCC 启动文件）、标准外设库
|
||
V3.3.3（取自 GD32F4xx_Demo_Suites_V3.3.3）、SEGGER_RTT。SDK 代码不做业务修改。
|
||
- `LD/` —— 链接脚本（xE 512K / xG 1024K / xK 2048K 三种容量，默认 xE）。
|
||
- `Inc/`+`Src/` —— 应用层；板级引脚与功能开关集中在 `Inc/board_config.h`。
|
||
- `OpenOCD/` —— 工程内 OpenOCD 会话配置（CMSIS-DAP + stm32f4x target 驱动 GD32F4）。
|
||
- `doc/` —— 芯片文档（数据手册/用户手册/固件库指南/AN，已齐备）。
|
||
- `GD32F4xx_Demo_Suites_V3.3.3/` —— 官方原始素材包，仅本地参考，已 gitignore。
|
||
- **编译方法**（与 E23x 一致）：
|
||
```bash
|
||
cmake --preset Debug && cmake --build Build/Debug
|
||
cmake --preset Release && cmake --build Build/Release
|
||
```
|
||
产物（elf/hex/bin/map/list 及版本化命名文件）全部生成在 `Build/<配置>/` 下。
|
||
- **构建特性**：`project_config.cmake` 管版本号/变体；`version.h` 自动生成；
|
||
POST_BUILD 产出 `[工程名_版本_变体_日期]` 系列文件；外设库为 OBJECT 库 +
|
||
`--gc-sections` 裁剪，未引用模块不进最终镜像。
|
||
- **换型号**：改 `GD32F405` 宏（project.cmake 与外设库 CMakeLists）、启动文件
|
||
（407_427 / 405_425 / 450_470）、链接脚本（xE/xG/xK），详见 README“更换目标型号”。
|
||
|
||
## 开发进度
|
||
|
||
### 已完成
|
||
|
||
- 模板骨架：目录结构、CMakeLists、CMakePresets（构建树位于工程根 `Build/`）、
|
||
工具链文件（cortex-m4 + 硬件 FPU + GCC15 兼容 `--no-warn-rwx-segments`）。
|
||
- **目标型号切换为 GD32F405RET6**：设备宏 `GD32F405`、启动文件 `startup_gd32f405_425.S`、
|
||
链接脚本 `gd32f405_407_xE_flash.ld`（512K）、J-Link device `GD32F405RE`、
|
||
OpenOCD cfg 更名 `gd32f405_gdlink_cmsis_dap.cfg`；切换后全新编译 Debug/Release 通过。
|
||
- **Flash 容量改为 CMake 编译期切换**：`GD32_FLASH_CAPACITY`（cache 变量，默认 xE）
|
||
决定链接脚本（xE/xG/xK）并注入 `GD32_FLASH_SIZE_KB` 宏；已验证 xG 切换生效。
|
||
- **删除 E230 式运行时串口分发结构**：去掉 `usart_config_t`/`g_usart_config`/
|
||
`mcu_detect_and_config()`/`Src/board_config.c`，串口静态绑定 USART0（宏直连），
|
||
中断直接调用处理函数；LED 改 demo 板实测引脚 **PA15**（复位默认 JTDI，
|
||
配 GPIO 输出即接管，不影响 SWD）。
|
||
- SDK 就位：CMSIS（core_cm4.h 系）、GD32F4xx 标准外设库 29 模块、SEGGER_RTT、
|
||
GCC 启动文件（F405/425）、三种容量链接脚本。
|
||
- 应用层移植（自 E23x 模板）：main / systick（M4 延时校准系数）/ led（心跳，
|
||
demo 板 PA15）/ uart（USART0 PA9/PA10 AF7、RS485 改 GPIO 控 DE）/
|
||
uart_ring_buffer / gd32f4xx_it（含 M4 特有 fault）/ syscalls（printf 重定向
|
||
USART0）/ system_gd32f4xx（168MHz_HXTAL，SystemInit 含 FPU 使能）。
|
||
- `GD32F4xx.svd` 已下载就位（社区镜像，与官方同源，覆盖全 F4 家族）。
|
||
- OpenOCD 工程内会话配置（借鉴 metax-sensors/gd32-cmake-example：CMSIS-DAP +
|
||
stm32f4x.cfg 驱动 GD32F4 flash）+ .vscode 全套（tasks/launch/settings/jlink 脚本）。
|
||
- 编译验证：Debug 与 Release 均通过（GCC 15.2.1），ELF 检查正确（vectors @
|
||
0x08000000、hard-float、.data 加载地址正确）。Release text≈7.6KB。
|
||
- **上板验证通过（GD-LINK/CMSIS-DAP + OpenOCD stm32f4x）**：芯片识别
|
||
`device id 0x16080413`（F405xE/512K）；固件烧录+verify OK；LED 心跳周期 2 秒整
|
||
（SysTick 1ms 精确，168MHz PLL 生效，SCSS=PLLP 硬件确认）；USART1 寄存器实测
|
||
CTL0=0x202C（使能+收发+RBNE 中断）、BAUD=365（42MHz APB1/115200 精确）、
|
||
TC=1（printf 数据完整发出）。
|
||
调试经验：GD32F4xx RCU 寄存器偏移为 CTL0=0x00、**PLL=0x04、CFG0=0x08**；
|
||
外设编号比 STM32 小 1（GD USART0=STM32 USART1@0x40011000、GD USART1=STM32
|
||
USART2@0x40004400、GD USART2=STM32 USART3@0x40004800），在线排查时勿混淆——
|
||
曾因按 STM32 习惯把 PA2/PA3 当 USART2 配置导致串口无输出，后更正为 USART1。
|
||
|
||
### 计划 / TODO（已提出尚未实现）
|
||
|
||
- [ ] **i2c 驱动移植**：从 E23x 工程 `Src/i2c.c`(50KB)/`Inc/i2c.h` 移植到 F4
|
||
（API 同名：i2c_clock_config/i2c_mode_addr_config 等已确认存在；引脚已定义
|
||
PB6/PB7 AF4；需将 include 的 gd32e23x* 改为 gd32f4xx*，并按 F4 时序实测
|
||
20kHz 总线速度与超时参数）。完成后在 CMakeLists 的 TARGET_SRC 启用 `Src/i2c.c`。
|
||
- [ ] **串口命令协议移植**：从 E23x 工程 `Src/command.c`/`Inc/command.h` 移植
|
||
（include 改 gd32f4xx_usart.h、core_cm23.h→core_cm4.h），启用后 main.c 中
|
||
打开 `command_process()` 调用。
|
||
- [ ] **上板验证（剩余项）**：串口助手（PA2/PA3，115200-8-N-1）实测 printf 输出与
|
||
收发；`stm32f4x mass_erase 0` 整片擦除命令实测；RTT 通道实测。
|
||
（已通过：烧录/verify、LED 心跳 2s、168MHz PLL、USART2 初始化与 printf 发送。）
|
||
- [ ] **delay_10us 校准**：M4@168MHz 系数为估算值（/300000），需逻辑分析仪实测修正。
|
||
- [x] **doc/ 已齐备**：GD32F405 数据手册 Rev2.8、GD32F4xx 用户手册 Rev3.3、
|
||
固件库使用指南 Rev1.2（中英）、AN059/AN200（用户补充+官方库包 Docs 拷贝）。
|
||
|
||
- **SDK 版本核对（2026-10）**：官网最新 GD32F4xx_Firmware_Library_V3.3.3（2026-02-05）
|
||
与工程 SDK（取自 Demo_Suites_V3.3.3）经逐文件 SHA1 对比**完全一致**，无需更新。
|
||
- **GD32F4xx_usb_library 已搬入 SDK**（源自官方包，temp 删除后不依赖）：含
|
||
driver/device/host/ustd 全量源码 + conf/ 模板配置（cdc_acm 例程基准）。
|
||
默认 `GD32_ENABLE_USB=OFF` 不参与构建；开启方式与限制见 SDK/GD32F4xx_usb_library/
|
||
CMakeLists.txt 头部注释（默认编译范围 = driver + device core + CDC 虚拟串口，
|
||
GCC 15 已验证；其余 class/host 依赖例程级 conf 宏，按注释从 Examples 取）。
|
||
|
||
## 备注
|
||
|
||
- 本机凭据/发布约定见用户级 `C:\Users\Lenovo\.zcode\AGENTS.md`。
|
||
- E23x 工程位置：`E:\Hulk-Coding\gd32e23x_template_cmake_vscode`（模板对标工程）。
|