gd32e230f8_firmware_merge_tool/AGENTS.md

AGENTS.md — gd32e230f8_firmware_merge_tool

GD32E230 系列固件处理与烧录工具仓库。本文件为项目标杆文档，随开发持续更新。

项目约定

• 语言与运行环境：Python ≥3.10；GUI 用 CustomTkinter（py -m pip install customtkinter）， 无其他第三方依赖；Windows 为主平台。
• OpenOCD 工具链：目标板连接依赖 xPack OpenOCD 0.11.0-3 （本机 D:/toolchain/xpack-openocd-0.11.0-3，发布包整包自带于 release/DAPLinkFlash/toolchain/openocd/）。0.12 不用：adapter srst 命令语法不同且未经验证。
• 项目结构：
  • 根目录：gd32e230_firmware_tool.py 命令行固件工具 v2（默认双固件 profile 打包；-f/-m 触发 legacy 单槽模式），fw_pack.py 打包公共库（CLI 与 GUI 共用的单一真相：profile 解析/校验/CRC/A 包/B 包/FULL/FACTORY/回读复核/ MD5 清单），test_fw_pack.py 回归测试套件（55 项，含 CeramixNano 实测基准）； merge_bin.py/fill_bin.py 旧版脚本保留兼容， gd32e230f8_bootloader_hulk.bin 出厂 bootloader；
  • FlashTool/：DAPLink Flash GUI v2.6.0（烧录 + 打包 v2 + 补齐 Pad + 拼接 Merge），源码在 src/（flash_gui.py 入口与 CLI、app_gui.py 界面、 openocd_runner.py 命令构建、fw_image.py 旧补齐/拼接、config.py 设置、 build_exe.py/package_release.py/publish_gitea.py 发布流水线）； fw_pack 由仓库根导入（源码模式 sys.path 回退，打包模式 --paths 根 --hiddenimport fw_pack），不要往 src/ 复制副本；
  • FlashTool/cfgs/openocd_gdlink_gd32e23x.cfg：随包分发的工程定制 target cfg （含 reset_config srst_only srst_nogate connect_assert_srst，必须复位下连接， 因为应用固件运行后会把 SWD 引脚复用为 LED）。
• v2 打包规则（与 BL dev_fact v5.1 逐字一致，改前必读 UPGRADE_PLAN_v2.md）： CRC-16/XMODEM（自检向量 "123456789"→0x31C3）；A 包补 0xFF 至整 N 页 + 末 4B trailer{页数16|CRC16}，CRC 范围=去末 4B，恰整页或余量<4B 扩 1 页； B 包固定满槽 + 槽末 8B 记录{magic=0xC0DE|页数|CRC|2B FF}，CRC 范围=去末 8B， 固件>槽-8B 报错；FULL=BL+A 包+槽尾锚点(0x0800AFFC)+B 满槽+0xEEEE@0x0800FFFC； FACTORY=BL+B 满槽+flag 无 A（A 槽整体擦除态，上电判定链落 B 跳出厂固件）， 12 项字节校验；不再单独落盘 B 包文件（B 内容已含于 FULL/FACTORY）。 默认 profile 名为 CeramixNano_MB_Dual_FW（旧名 ceramixnano_mb_v51 已 废弃不留别名；迁移映射已删，配置残留旧名会在加载时报错提示重选）。 回归基准（CeramixNano 实测）：1.0.17→20 页 trailer=0xD30F0014；1.0.18→ 0x6F380014；V1.0.12 B→记录 DE C0 13 00 6F 18 FF FF；FULL 镜像 MD5 f704b837... 逐字节复现。改 fw_pack.py 后必须 python test_fw_pack.py 全绿再提交（真机固件路径见该文件头部，缺文件自动跳过）。
• 构建与发布：build_exe.py（PyInstaller onedir → release/DAPLinkFlash/） → package_release.py（组 zip，版本号取 DAPLinkFlash-v* git tag，工具链优先 FlashTool/toolchain/openocd → D:/toolchain/xpack-openocd-0.11.0-3） → publish_gitea.py（上传 Gitea Release，用环境变量 GITEA_TOKEN，需 --insecure）。 release/ 是机器生成区，只应有 DAPLinkFlash/（onedir）与 *.zip。
• OpenOCD 复位序列：所有操作（检测/烧录/擦除/读取/复位）统一带 CONNECT_SEQ = "adapter deassert srst; sleep 200; catch {reset halt}; reset halt" （0.11 语法），复刻 VSCode tasks.json 的任务链；烧录后复位前同样先释放 SRST。 改动 openocd_runner.py 的序列时保持与 VSCode 工程任务链一致。

开发进度

已完成

• 命令行固件工具 legacy 模式（校验链接地址 / 1K 页补齐 _update.bin / 拼接 bootloader _BL.bin / 有效标志 0xEEEEEEEE；-a/--app-addr 自定义落位）；
• DAPLink Flash GUI v2.5.2：单列仪表盘布局、OpenOCD 全操作（检测/烧录/擦除/ 读取/复位）、BIN/HEX/ELF、补齐 Pad / 拼接 Merge 弹窗、深浅色主题、 cfgs/ 自定义 cfg 机制、全操作 SRST 连接序列、整包 0.11 工具链、 Gitea Release 发布流水线；
• 2026-10-22 v2 彻底升级落地（UPGRADE_PLAN_v2.md 全部实现并自验收）：
  • fw_pack.py 公共库：布局 profile（内置 CeramixNano_MB_Dual_FW / f8_single_slot + JSON 自定义，完整性校验）、向量表自动识别 A/B 包 （显式指定冲突报错）、A 包动态补页+trailer+整页扩展、B 包固定满槽+记录、 FULL 整片镜像+槽尾锚点+flag、CRC-16/XMODEM 启动自检、写盘回读复核、 19 项 FULL 字节校验、MD5 清单+布局摘要、FULL 自动命名（项目/双版本/日期）；
  • gd32e230_firmware_tool.py v2.0.0 重构：默认 v2 模式（位置参数自动识别、 --a/--b/--bl/--profile/-o 目录/--no-full/--no-factory），-f/-m 保留 legacy 行为不变；
  • test_fw_pack.py 回归全绿（55 项）——规格第五节基准逐项复现（1.0.17 UPDATE 与验收包逐字节一致、FULL MD5 f704b837... 复现、恰整页/余量<4 扩页、 LDC1612 legacy update.bin 复现）、变体 profile（B 8K/28K/无）、错误路径、 CLI 冒烟；
  • FlashTool GUI v2.6.0：顶栏"打包 (v2)"弹窗（profile 下拉+JSON 浏览、BL/A/B 输入、输出目录、生成 FULL 开关），flash_gui.py --pack 命令行模式， build_exe.py 以 --paths+hiddenimport 收录根目录 fw_pack.py；
  • make_v5_update.py 已删除（能力并入 fw_pack.py）；README（根 + FlashTool） 已重写；尚未发布 GUI 新版 zip（待下次 build_exe.py→package_release.py）。
• 2026-10-22 FACTORY 工厂镜像改造 + profile 改名（上个会话收尾、本会话续完）：
  • fw_pack.py：新增 build_factory/verify_factory_blob/suggest_factory_name （BL+B 满槽+flag、无 A、12 项字节校验），pack_all 产物改为 UPDATE/FULL/ FACTORY/MD5，不再单独落盘 B 包文件；仅 B 输入时只出 FACTORY（不拼 FULL）；
  • CLI：根工具与 flash_gui --pack 均加 --no-factory（flash_gui 侧为 --pack-no-factory），GUI 弹窗文案/结果映射同步；
  • 内置 profile 改名 ceramixnano_mb_v51 → CeramixNano_MB_Dual_FW（旧名 废弃不留别名；CLI/GUI 默认值、config 默认+旧配置迁移、测试、文档全量同步）；
  • 参数拼接审计：flash_gui --pack -o 加目录护栏（拒绝 .bin 路径，对齐根工具）， 全链路冒烟（GUI 弹窗/CLI/命名拼接）通过；bootloader_disasm*.txt 为分析 副产物留在工作区未入库。
• 2026-10-22 v2.6.0 发布（tag DAPLinkFlash-v2.6.0）：重建 onedir exe （冻结新 fw_pack，--pack 默认 profile 显示 CeramixNano_MB_Dual_FW、 旧名拒绝、UPDATE/FULL/FACTORY 产物冻结态验证通过），组 zip 23.1 MB （内置 OpenOCD 0.11 工具链 + cfgs），已传 Gitea Release。
• 2026-10-22 内部迭代号出清（用户定规：v4/v4.1/v5/v5.1、dev_fact 等 会话自管理标签只许存在于 AGENTS/SKILL 等文档，不得出现在任何代码）： 清理 fw_pack.py/gd32e230_firmware_tool.py/test_fw_pack.py/README.md 注释中的标签表述（改"双固件 bootloader"）；删除 config.py 的 _RENAMED_PROFILE 旧名迁移映射（ceramixnano_mb_v51 仅存在数小时， 残留配置会在加载 profile 时报错提示重选）；同步 skill 缓存 （fw_pack.py / gd32e230_firmware_tool.py 重新逐字节一致）；参考产物 *_UPDATE_V5.bin 更名 *_UPDATE.bin（含验收包内 1.0.18），测试引用同步； 55 项回归全过。注：BL 侧 bootloader.c 同日清理 3 处注释标签（注释不影响 代码生成，已烧 BL bin 仍有效）。

计划 / TODO

• （待用户物理排查）当前目标板对 SWD 完全无应答（cannot read IDR，复位下 100k~4000k 全失败，同探针同工具链曾可连）：需确认目标板供电、DAPLink RST → GD32 NRST 连线、必要时拔插 DAPLink USB / 目标板断电重上电；恢复后用 release/DAPLinkFlash/DAPLinkFlash.exe 重新"检测设备"验证。

教训（避免复发）

• 不要运行 release/ 根目录下的任何 exe：09-14 旧 onefile 残留（已删）曾 导致 2026-10-20 误报"烧录不正常"——它用旧 0.12 工具链 + 原版 target cfg、 无 SRST 连接序列，与本工程固件（SWD 引脚复用为 LED）不兼容。运行入口只有 release/DAPLinkFlash/DAPLinkFlash.exe（打包版）或 start_flash_gui.bat（源码版）。