diff --git a/README.md b/README.md index c6ec464..3d2ffba 100644 --- a/README.md +++ b/README.md @@ -1,148 +1,151 @@ -# GD32 Firmware Merge Tool +# GD32E230 固件工具 -将 Bootloader 和 Application 的 bin 文件合成为一个完整的 Flash 镜像，用于 GD32 系列 MCU 的初始烧录。 +Bootloader + Application 固件处理工具，支持合成整片烧录镜像和 Ymodem 升级包补齐。 + +> **旧工具** `merge_bin.py` / `fill_bin.py` 仍保留（→ [README_old.md](README_old.md)），本仓库推荐使用新工具。 ## Flash 布局 ``` -地址 内容 0x08000000 ┌──────────────────┐ - │ Bootloader │ + │ Bootloader │ 8KB 0x08002000 ├──────────────────┤ - │ Application │ - │ ... │ - │ (0xFF 填充) │ -0x0800FFFC │ 0xEEEEEEEE │ ← 有效 APP 标志 + │ │ + │ Application │ 最大 54KB (F8) / 22KB (F6) / 6KB (F4) + │ │ +0x0800F800 ├──────────────────┤ + │ 校准数据 │ 1KB (预留) +0x0800FC00 ├──────────────────┤ + │ 0xEEEE 标志 │ 1KB 0x08010000 └──────────────────┘ ``` -- 空白区域填充 `0xFF`（Flash 擦除后的默认值） -- 标志位 `0xEEEEEEEE` 告诉 Bootloader：Flash 中已存在有效的 APP，可以直接跳转执行 +- 空白区域填充 `0xFF`（Flash 擦除默认值） +- 标志位 `0xEEEE` 告诉 Bootloader：APP 有效，直接跳转 +- 校准页当前为预留空间 ## 环境要求 -- Python 3.x（标准安装即可，无需第三方库） +- Python 3.x，无第三方依赖 -## 用法 +## 快速开始 ```bash -python merge_bin.py [-b bootloader.bin] [-o 输出文件] [--app-addr 地址] [--flag-addr 地址] +# 合成完整镜像（整片烧录用） +python gd32e230_firmware_tool.py -m app.bin + +# 补齐升级包（Ymodem 升级用） +python gd32e230_firmware_tool.py -f app.bin ``` -### 参数说明 +## 模式说明 -| 参数 | 必填 | 默认值 | 说明 | -|------|:----:|--------|------| -| `app` | ✅ | — | Application 的 .bin 文件路径 | -| `-b, --bootloader` | ❌ | `gd32e230f8_bootloader_hulk.bin` | Bootloader 的 .bin 文件路径 | -| `-o, --output` | ❌ | `_BL.bin` | 输出文件路径 | -| `--app-addr` | ❌ | `0x08002000` | APP 在 Flash 中的起始地址 | -| `--flag-addr` | ❌ | `0x0800FFFC` | APP 有效标志位的地址 | +### `-m` / `--merge` — 合成完整镜像 -### 示例 - -**基本用法**（使用默认地址，输出自动命名为 `app_BL.bin`）： +将 Bootloader + APP + FLAG 合并为一个 Flash 镜像，直接整片烧录。**不补齐**（整片烧录无需考虑页对齐）。 ```bash -python merge_bin.py app.bin +python gd32e230_firmware_tool.py -m CeramixNano-MB_V1.0.9.bin ``` -默认会读取当前目录下固定文件名：`gd32e230f8_bootloader_hulk.bin`。 +输出：`CeramixNano-MB_V1.0.9_BL.bin` -**指定 Bootloader 文件**： +### `-f` / `--fill` — 补齐升级包 + +将 APP 尾部补 `0xFF` 到 1KB 页边界，供 Bootloader 的 Ymodem 接收端使用。补齐后自动检查是否超过芯片 APP 容量上限。 ```bash -python merge_bin.py app.bin -b bootloader.bin +python gd32e230_firmware_tool.py -f CeramixNano-MB_V1.0.9.bin ``` -**指定自定义地址**： +输出：`CeramixNano-MB_V1.0.9_UPDATE.bin` + +## 参数 + +| 参数 | 默认值 | 说明 | +|------|--------|------| +| `app` | (必填) | APP 的 .bin 文件 | +| `-m, --merge` | — | 合成完整 Flash 镜像 | +| `-f, --fill` | — | 补齐到整页边界 | +| `-s, --flash-size` | `F8` | 芯片型号：`F4`(16K) `F6`(32K) `F8`(64K) | +| `-b, --bootloader` | `gd32e230f8_bootloader_hulk.bin` | Bootloader .bin 路径 | +| `-o, --output` | 自动生成 | 输出文件路径 | +| `-h, --help` | — | 查看帮助 | + +> **`-m` 和 `-f` 互斥**，每次只能选一种模式。 + +## 使用示例 ```bash -python merge_bin.py app.bin -b bootloader.bin --app-addr 0x08002000 --flag-addr 0x0800FFFC -o merged.bin +# F8 合成镜像（默认） +python gd32e230_firmware_tool.py -m CeramixNano-MB_V1.0.9.bin + +# F6 合成镜像 +python gd32e230_firmware_tool.py -m app.bin -s F6 + +# F8 补齐升级包（默认） +python gd32e230_firmware_tool.py -f app.bin + +# F4 补齐升级包 +python gd32e230_firmware_tool.py -f app.bin -s F4 + +# 自定义 Bootloader 和输出路径 +python gd32e230_firmware_tool.py -m app.bin -b my_bootloader.bin -o release.bin ``` -**实际项目示例**（默认输出为 `CeramixNano-MB_V1.0.9_APP_2026-03-23_BL.bin`）： +## 输出示例 -```bash -python merge_bin.py \ - CeramixNano-MB_V1.0.9_APP_2026-03-23.bin -``` - -**指定输出文件名**： - -```bash -python merge_bin.py \ - CeramixNano-MB_V1.0.9_APP_2026-03-23.bin \ - -o custom_output.bin -``` - -### 输出示例 +**merge 模式：** ``` -合成完成: CeramixNano-MB_V1.0.9_APP_2026-03-23_BL.bin - Bootloader : 3272 字节 @ 0x08000000 - Application: 25600 字节 @ 0x08002000 - Flag : 0xEEEE @ 0x0800FFFC - 总大小 : 65536 字节 (64KB) +芯片: GD32E230F8 (64KB) + +合成完成: CeramixNano-MB_V1.0.9_BL.bin + 芯片 : 64KB + Bootloader : 3272B @ 0x08000000 + Application: 25600B @ 0x08002000 + Flag : 0xEEEE @ 0x0800FFFC + 校准预留 : 1KB @ 0x0800F800 + APP 剩余 : 29696B + 总大小 : 65536B (64KB) +``` + +**fill 模式：** + +``` +芯片: GD32E230F8 (64KB) +补齐完成: app_UPDATE.bin + 原始大小: 25000B + 页大小 : 1024B (1KB) + 补齐字节: 600B + 输出大小: 25600B + APP 上限: 55296B (54KB) → 剩余 29696B +``` + +**超限拦截：** + +``` +错误：APP (60000B / 58.6KB) 超过最大容量 (55296B / 54KB) + 芯片 64KB: 64KB - 8KB(BL) - 1KB(校准) - 1KB(Flag) = 54KB ``` ## 烧录 -合成后的 bin 文件可直接用 OpenOCD 整片烧录： - ```bash +# OpenOCD openocd -f interface/cmsis-dap.cfg -f target/gd32e23x.cfg \ -c "init; reset halt; flash write_image erase merged.bin 0x08000000; reset; exit" -``` -或使用 J-Link： - -```bash +# J-Link JFlash -openprj project.jflash -open merged.bin,0x08000000 -auto -exit ``` -## 升级包整页补齐 - -如果 Bootloader 只支持整页传输（GD32E230F8 每页 1KB），可在打包升级文件前执行补齐脚本。 - -```bash -python fill_bin.py [-o 输出文件] [--page-size 1024] [--fill 0xFF] -``` - -### 示例 - -使用默认参数（1KB 页、0xFF 补齐）： - -```bash -python fill_bin.py CeramixNano-MB_V1.0.9_APP_2026-03-22.bin -``` - -指定输出文件名： - -```bash -python fill_bin.py CeramixNano-MB_V1.0.9_APP_2026-03-22.bin -o CeramixNano-MB_V1.0.9_APP_2026-03-22_UPDATE.bin -``` - -脚本会将文件尾部补足到页大小的整数倍；若输入文件本身已对齐，会原样输出。 - ## 安全校验 -脚本内置以下校验，不满足时会报错退出： - -- APP 地址和标志地址必须在 Flash 范围内（0x08000000 ~ 0x08010000） -- Bootloader 体积不能超过 APP 起始偏移 -- APP 结束地址不能覆盖标志位地址 - -## 适配其他型号 - -修改脚本顶部常量即可适配不同 Flash 大小的 MCU： - -```python -FLASH_BASE = 0x08000000 -FLASH_SIZE = 64 * 1024 # 修改为目标 MCU 的 Flash 大小 -``` - -通过 `--app-addr` 和 `--flag-addr` 参数适配不同的内存布局，无需修改代码。 +- Bootloader 体积不超过 APP 起始偏移（8KB） +- APP 大小不超过芯片可用空间 +- fill 模式补齐后再次校验容量上限 +- 芯片不支持自动检测，需通过 `-s` 手动指定 ## License diff --git a/README_old.md b/README_old.md new file mode 100644 index 0000000..c6ec464 --- /dev/null +++ b/README_old.md @@ -0,0 +1,149 @@ +# GD32 Firmware Merge Tool + +将 Bootloader 和 Application 的 bin 文件合成为一个完整的 Flash 镜像，用于 GD32 系列 MCU 的初始烧录。 + +## Flash 布局 + +``` +地址 内容 +0x08000000 ┌──────────────────┐ + │ Bootloader │ +0x08002000 ├──────────────────┤ + │ Application │ + │ ... │ + │ (0xFF 填充) │ +0x0800FFFC │ 0xEEEEEEEE │ ← 有效 APP 标志 +0x08010000 └──────────────────┘ +``` + +- 空白区域填充 `0xFF`（Flash 擦除后的默认值） +- 标志位 `0xEEEEEEEE` 告诉 Bootloader：Flash 中已存在有效的 APP，可以直接跳转执行 + +## 环境要求 + +- Python 3.x（标准安装即可，无需第三方库） + +## 用法 + +```bash +python merge_bin.py [-b bootloader.bin] [-o 输出文件] [--app-addr 地址] [--flag-addr 地址] +``` + +### 参数说明 + +| 参数 | 必填 | 默认值 | 说明 | +|------|:----:|--------|------| +| `app` | ✅ | — | Application 的 .bin 文件路径 | +| `-b, --bootloader` | ❌ | `gd32e230f8_bootloader_hulk.bin` | Bootloader 的 .bin 文件路径 | +| `-o, --output` | ❌ | `_BL.bin` | 输出文件路径 | +| `--app-addr` | ❌ | `0x08002000` | APP 在 Flash 中的起始地址 | +| `--flag-addr` | ❌ | `0x0800FFFC` | APP 有效标志位的地址 | + +### 示例 + +**基本用法**（使用默认地址，输出自动命名为 `app_BL.bin`）： + +```bash +python merge_bin.py app.bin +``` + +默认会读取当前目录下固定文件名：`gd32e230f8_bootloader_hulk.bin`。 + +**指定 Bootloader 文件**： + +```bash +python merge_bin.py app.bin -b bootloader.bin +``` + +**指定自定义地址**： + +```bash +python merge_bin.py app.bin -b bootloader.bin --app-addr 0x08002000 --flag-addr 0x0800FFFC -o merged.bin +``` + +**实际项目示例**（默认输出为 `CeramixNano-MB_V1.0.9_APP_2026-03-23_BL.bin`）： + +```bash +python merge_bin.py \ + CeramixNano-MB_V1.0.9_APP_2026-03-23.bin +``` + +**指定输出文件名**： + +```bash +python merge_bin.py \ + CeramixNano-MB_V1.0.9_APP_2026-03-23.bin \ + -o custom_output.bin +``` + +### 输出示例 + +``` +合成完成: CeramixNano-MB_V1.0.9_APP_2026-03-23_BL.bin + Bootloader : 3272 字节 @ 0x08000000 + Application: 25600 字节 @ 0x08002000 + Flag : 0xEEEE @ 0x0800FFFC + 总大小 : 65536 字节 (64KB) +``` + +## 烧录 + +合成后的 bin 文件可直接用 OpenOCD 整片烧录： + +```bash +openocd -f interface/cmsis-dap.cfg -f target/gd32e23x.cfg \ + -c "init; reset halt; flash write_image erase merged.bin 0x08000000; reset; exit" +``` + +或使用 J-Link： + +```bash +JFlash -openprj project.jflash -open merged.bin,0x08000000 -auto -exit +``` + +## 升级包整页补齐 + +如果 Bootloader 只支持整页传输（GD32E230F8 每页 1KB），可在打包升级文件前执行补齐脚本。 + +```bash +python fill_bin.py [-o 输出文件] [--page-size 1024] [--fill 0xFF] +``` + +### 示例 + +使用默认参数（1KB 页、0xFF 补齐）： + +```bash +python fill_bin.py CeramixNano-MB_V1.0.9_APP_2026-03-22.bin +``` + +指定输出文件名： + +```bash +python fill_bin.py CeramixNano-MB_V1.0.9_APP_2026-03-22.bin -o CeramixNano-MB_V1.0.9_APP_2026-03-22_UPDATE.bin +``` + +脚本会将文件尾部补足到页大小的整数倍；若输入文件本身已对齐，会原样输出。 + +## 安全校验 + +脚本内置以下校验，不满足时会报错退出： + +- APP 地址和标志地址必须在 Flash 范围内（0x08000000 ~ 0x08010000） +- Bootloader 体积不能超过 APP 起始偏移 +- APP 结束地址不能覆盖标志位地址 + +## 适配其他型号 + +修改脚本顶部常量即可适配不同 Flash 大小的 MCU： + +```python +FLASH_BASE = 0x08000000 +FLASH_SIZE = 64 * 1024 # 修改为目标 MCU 的 Flash 大小 +``` + +通过 `--app-addr` 和 `--flag-addr` 参数适配不同的内存布局，无需修改代码。 + +## License + +MIT