hulk/FilmForge
1
0
Fork 0
generated from hulk/gd32f4xx_template_cmake_vscode
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity
Files
8feba5e015347a1d66a43ebce68ddd704341cf7f
FilmForge/AGENTS.md
T
hulk 8feba5e015 Initial commit
2026-10-09 18:45:50 +08:00

7.6 KiB
Raw Blame History

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 一致）： 
    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），需逻辑分析仪实测修正。

  • 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（模板对标工程）。
Reference in New Issue View Git Blame Copy Permalink