docs: 更新 README 以新工具为主，旧 README 重命名为 README_old
This commit is contained in:
Hulk
@@ -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 布局
|
## Flash 布局
|
||||||
|
|
||||||
```
|
```
|
||||||
地址 内容
|
|
||||||
0x08000000 ┌──────────────────┐
|
0x08000000 ┌──────────────────┐
|
||||||
│ Bootloader │
|
│ Bootloader │ 8KB
|
||||||
0x08002000 ├──────────────────┤
|
0x08002000 ├──────────────────┤
|
||||||
│ Application │
|
│ │
|
||||||
│ ... │
|
│ Application │ 最大 54KB (F8) / 22KB (F6) / 6KB (F4)
|
||||||
│ (0xFF 填充) │
|
│ │
|
||||||
0x0800FFFC │ 0xEEEEEEEE │ ← 有效 APP 标志
|
0x0800F800 ├──────────────────┤
|
||||||
|
│ 校准数据 │ 1KB (预留)
|
||||||
|
0x0800FC00 ├──────────────────┤
|
||||||
|
│ 0xEEEE 标志 │ 1KB
|
||||||
0x08010000 └──────────────────┘
|
0x08010000 └──────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
- 空白区域填充 `0xFF`（Flash 擦除后的默认值）
|
- 空白区域填充 `0xFF`（Flash 擦除默认值）
|
||||||
- 标志位 `0xEEEEEEEE` 告诉 Bootloader：Flash 中已存在有效的 APP，可以直接跳转执行
|
- 标志位 `0xEEEE` 告诉 Bootloader：APP 有效，直接跳转
|
||||||
|
- 校准页当前为预留空间
|
||||||
|
|
||||||
## 环境要求
|
## 环境要求
|
||||||
|
|
||||||
- Python 3.x（标准安装即可，无需第三方库）
|
- Python 3.x，无第三方依赖
|
||||||
|
|
||||||
## 用法
|
## 快速开始
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python merge_bin.py <app.bin> [-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
|
||||||
```
|
```
|
||||||
|
|
||||||
### 参数说明
|
## 模式说明
|
||||||
|
|
||||||
| 参数 | 必填 | 默认值 | 说明 |
|
### `-m` / `--merge` — 合成完整镜像
|
||||||
|------|:----:|--------|------|
|
|
||||||
| `app` | ✅ | — | Application 的 .bin 文件路径 |
|
|
||||||
| `-b, --bootloader` | ❌ | `gd32e230f8_bootloader_hulk.bin` | Bootloader 的 .bin 文件路径 |
|
|
||||||
| `-o, --output` | ❌ | `<APP文件名>_BL.bin` | 输出文件路径 |
|
|
||||||
| `--app-addr` | ❌ | `0x08002000` | APP 在 Flash 中的起始地址 |
|
|
||||||
| `--flag-addr` | ❌ | `0x0800FFFC` | APP 有效标志位的地址 |
|
|
||||||
|
|
||||||
### 示例
|
将 Bootloader + APP + FLAG 合并为一个 Flash 镜像，直接整片烧录。**不补齐**（整片烧录无需考虑页对齐）。
|
||||||
|
|
||||||
**基本用法**（使用默认地址，输出自动命名为 `app_BL.bin`）：
|
|
||||||
|
|
||||||
```bash
|
```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
|
```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
|
```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
|
**merge 模式：**
|
||||||
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
|
芯片: GD32E230F8 (64KB)
|
||||||
Bootloader : 3272 字节 @ 0x08000000
|
|
||||||
Application: 25600 字节 @ 0x08002000
|
合成完成: CeramixNano-MB_V1.0.9_BL.bin
|
||||||
Flag : 0xEEEE @ 0x0800FFFC
|
芯片 : 64KB
|
||||||
总大小 : 65536 字节 (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
|
```bash
|
||||||
|
# OpenOCD
|
||||||
openocd -f interface/cmsis-dap.cfg -f target/gd32e23x.cfg \
|
openocd -f interface/cmsis-dap.cfg -f target/gd32e23x.cfg \
|
||||||
-c "init; reset halt; flash write_image erase merged.bin 0x08000000; reset; exit"
|
-c "init; reset halt; flash write_image erase merged.bin 0x08000000; reset; exit"
|
||||||
```
|
|
||||||
|
|
||||||
或使用 J-Link：
|
# J-Link
|
||||||
|
|
||||||
```bash
|
|
||||||
JFlash -openprj project.jflash -open merged.bin,0x08000000 -auto -exit
|
JFlash -openprj project.jflash -open merged.bin,0x08000000 -auto -exit
|
||||||
```
|
```
|
||||||
|
|
||||||
## 升级包整页补齐
|
|
||||||
|
|
||||||
如果 Bootloader 只支持整页传输（GD32E230F8 每页 1KB），可在打包升级文件前执行补齐脚本。
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python fill_bin.py <firmware.bin> [-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
|
|
||||||
```
|
|
||||||
|
|
||||||
脚本会将文件尾部补足到页大小的整数倍；若输入文件本身已对齐，会原样输出。
|
|
||||||
|
|
||||||
## 安全校验
|
## 安全校验
|
||||||
|
|
||||||
脚本内置以下校验，不满足时会报错退出：
|
- Bootloader 体积不超过 APP 起始偏移（8KB）
|
||||||
|
- APP 大小不超过芯片可用空间
|
||||||
- APP 地址和标志地址必须在 Flash 范围内（0x08000000 ~ 0x08010000）
|
- fill 模式补齐后再次校验容量上限
|
||||||
- Bootloader 体积不能超过 APP 起始偏移
|
- 芯片不支持自动检测，需通过 `-s` 手动指定
|
||||||
- APP 结束地址不能覆盖标志位地址
|
|
||||||
|
|
||||||
## 适配其他型号
|
|
||||||
|
|
||||||
修改脚本顶部常量即可适配不同 Flash 大小的 MCU：
|
|
||||||
|
|
||||||
```python
|
|
||||||
FLASH_BASE = 0x08000000
|
|
||||||
FLASH_SIZE = 64 * 1024 # 修改为目标 MCU 的 Flash 大小
|
|
||||||
```
|
|
||||||
|
|
||||||
通过 `--app-addr` 和 `--flag-addr` 参数适配不同的内存布局，无需修改代码。
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|||||||
+149
@@ -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 <app.bin> [-b bootloader.bin] [-o 输出文件] [--app-addr 地址] [--flag-addr 地址]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 参数说明
|
||||||
|
|
||||||
|
| 参数 | 必填 | 默认值 | 说明 |
|
||||||
|
|------|:----:|--------|------|
|
||||||
|
| `app` | ✅ | — | Application 的 .bin 文件路径 |
|
||||||
|
| `-b, --bootloader` | ❌ | `gd32e230f8_bootloader_hulk.bin` | Bootloader 的 .bin 文件路径 |
|
||||||
|
| `-o, --output` | ❌ | `<APP文件名>_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 <firmware.bin> [-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
|
||||||
Reference in New Issue
Block a user