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（标准安装即可，无需第三方库）

用法

python merge_bin.py <bootloader.bin> <app.bin> [-o 输出文件] [--app-addr 地址] [--flag-addr 地址]

参数说明

参数	必填	默认值	说明
bootloader	✅	—	Bootloader 的 .bin 文件路径
app	✅	—	Application 的 .bin 文件路径
-o, --output	❌	merged.bin	输出文件路径
--app-addr	❌	0x08002000	APP 在 Flash 中的起始地址
--flag-addr	❌	0x0800FFFC	APP 有效标志位的地址

示例

基本用法（使用默认地址）：

python merge_bin.py bootloader.bin app.bin -o merged.bin

指定自定义地址：

python merge_bin.py bootloader.bin app.bin --app-addr 0x08002000 --flag-addr 0x0800FFFC -o merged.bin

实际项目示例：

python merge_bin.py \
  gd32e23x_V1.0.0_bootloader_2026-03-23.bin \
  CeramixNano-MB_V1.0.9_APP_2026-03-23.bin \
  -o CeramixNano-MB_V1.0.9_APP_BL_2026-03-23.bin

输出示例

合成完成: merged.bin
  Bootloader :   3272 字节  @ 0x08000000
  Application:  25600 字节  @ 0x08002000
  Flag       : 0xEEEE         @ 0x0800FFFC
  总大小     :  65536 字节  (64KB)

烧录

合成后的 bin 文件可直接用 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：

JFlash -openprj project.jflash -open merged.bin,0x08000000 -auto -exit

安全校验

脚本内置以下校验，不满足时会报错退出：

• APP 地址和标志地址必须在 Flash 范围内（0x08000000 ~ 0x08010000）
• Bootloader 体积不能超过 APP 起始偏移
• APP 结束地址不能覆盖标志位地址

适配其他型号

修改脚本顶部常量即可适配不同 Flash 大小的 MCU：

FLASH_BASE = 0x08000000
FLASH_SIZE = 64 * 1024  # 修改为目标 MCU 的 Flash 大小

通过 --app-addr 和 --flag-addr 参数适配不同的内存布局，无需修改代码。

License

MIT