150 lines
3.9 KiB
Markdown
150 lines
3.9 KiB
Markdown
# 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
|