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 布局
|
||||
|
||||
```
|
||||
地址 内容
|
||||
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 <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
|
||||
```
|
||||
|
||||
### 参数说明
|
||||
## 模式说明
|
||||
|
||||
| 参数 | 必填 | 默认值 | 说明 |
|
||||
|------|:----:|--------|------|
|
||||
| `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 有效标志位的地址 |
|
||||
### `-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
|
||||
芯片: GD32E230F8 (64KB)
|
||||
|
||||
合成完成: CeramixNano-MB_V1.0.9_BL.bin
|
||||
芯片 : 64KB
|
||||
Bootloader : 3272B @ 0x08000000
|
||||
Application: 25600B @ 0x08002000
|
||||
Flag : 0xEEEE @ 0x0800FFFC
|
||||
总大小 : 65536 字节 (64KB)
|
||||
校准预留 : 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 <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` 参数适配不同的内存布局，无需修改代码。
|
||||
- Bootloader 体积不超过 APP 起始偏移（8KB）
|
||||
- APP 大小不超过芯片可用空间
|
||||
- fill 模式补齐后再次校验容量上限
|
||||
- 芯片不支持自动检测，需通过 `-s` 手动指定
|
||||
|
||||
## 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