hulk
8af9264ae4
- gd32e230_firmware_tool.py / test_fw_pack.py / README.md：v5/dev_fact 等会话自管理标签改为"双固件 bootloader"中性表述；参考产物 *_UPDATE_V5.bin 更名 *_UPDATE.bin（含验收包内 1.0.18），测试引用同步
- config.py：删除 _RENAMED_PROFILE 旧名迁移映射（ceramixnano_mb_v51 仅存在数小时；残留旧名加载 profile 时报错提示重选）
- AGENTS.md：留档出清进度，并修正"GUI 旧配置自动迁移"的过时表述（迁移映射已删）
- 55 项回归全绿；fw_pack.py 侧标签清理已随 5a85f68 入库
119 lines
8.7 KiB
Markdown
119 lines
8.7 KiB
Markdown
# 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`（源码版）。
|