201 lines
6.5 KiB
Markdown
201 lines
6.5 KiB
Markdown
# GD32E230 固件工具
|
||
|
||
本仓库提供 GD32E230 系列固件的处理与烧录工具：
|
||
|
||
- **DAPLink Flash GUI（推荐）**：图形界面烧录工具，位于 `FlashTool/`
|
||
- **命令行固件工具**：`gd32e230_firmware_tool.py`（合成 + 补齐二合一）
|
||
- **旧版脚本**：`merge_bin.py`、`fill_bin.py`（保留兼容）
|
||
|
||
## Flash 布局
|
||
|
||
```text
|
||
0x08000000 ┌──────────────────┐
|
||
│ Bootloader │ 8KB
|
||
0x08002000 ├──────────────────┤
|
||
│ │
|
||
│ Application │ 最大 54KB (F8) / 22KB (F6) / 6KB (F4)
|
||
│ │
|
||
0x0800F800 ├──────────────────┤
|
||
│ 校准数据 │ 1KB (预留)
|
||
0x0800FC00 ├──────────────────┤
|
||
│ 0xEEEE 标志 │ 1KB
|
||
0x08010000 └──────────────────┘
|
||
```
|
||
|
||
- 空白区域填充 `0xFF`（Flash 擦除默认值）
|
||
- 标志位 `0xEEEE` 告诉 Bootloader：APP 有效，直接跳转
|
||
- 校准页当前为预留空间
|
||
|
||
## DAPLink Flash GUI（推荐）
|
||
|
||
日常烧录优先使用图形界面工具，不需要打开 VSCode，也不需要记忆 OpenOCD 命令。
|
||
|
||
- **免安装版**：到 [Gitea Releases](https://gitea.hulk.wang/hulk/gd32e230f8_firmware_merge_tool/releases)
|
||
下载 `DAPLinkFlash-vX.Y.Z-win64.zip`，解压后进入 `DAPLinkFlash` 文件夹
|
||
双击 `DAPLinkFlash.exe` 即可，**包内自带 OpenOCD 工具链**
|
||
（`toolchain/openocd/`），目标机器无需任何环境。
|
||
- **源码运行**：`python FlashTool/src/flash_gui.py` 或双击 `FlashTool\start_flash_gui.bat`
|
||
（需 Python 3.10+ 与 `pip install customtkinter`；OpenOCD 默认找 `D:/toolchain`）。
|
||
|
||
详细说明见 [FlashTool/README.md](FlashTool/README.md)（GUI 截图说明、命令行模式、
|
||
构建与发布流程）。下面是旧单文件版说明保留的要点：
|
||
|
||
### 功能
|
||
|
||
- 烧录操作：检测设备、整片擦除、烧录固件、读取 Flash、复位芯片、停止
|
||
- 固件格式：BIN / HEX / ELF
|
||
- BIN：手动填写烧录基地址
|
||
- HEX / ELF：自动使用文件内地址
|
||
- 芯片型号：GD32E230F4 / F6 / F8 / C8，自动带出 Flash 大小和 target 配置
|
||
- 烧录器：DAPLink / CMSIS-DAP、GD-Link、ST-Link、J-Link
|
||
- 烧录参数：适配器速度、探针序列号、烧录前擦除、烧录后校验、烧录后复位运行
|
||
- 固件处理：补齐（1K / 2K / 4K）、拼接 Bootloader + APP + 有效标志
|
||
- 工具链自动定位：内置（exe 旁 `toolchain/openocd`）→ 本机 `D:/toolchain` → PATH
|
||
|
||
### 配置
|
||
|
||
- 配置文件：`flash_gui_settings.json`，保存在程序目录（exe 旁 / FlashTool 根），
|
||
自动保存与恢复
|
||
- 旧版 `config/flash_gui_<主机名>.json` 在新版首次启动时自动迁移
|
||
|
||
### 使用步骤
|
||
|
||
1. 连接烧录器（DAPLink / GD-Link 等）到目标板 SWD：SWDIO、SWCLK、GND
|
||
2. 启动 GUI，选择芯片型号和烧录器型号
|
||
3. 选择固件文件并确认地址：
|
||
- 完整镜像（bootloader + app）：`0x08000000`
|
||
- 单独烧录 APP：`0x08002000`
|
||
4. 点击“检测设备”确认连接正常
|
||
5. 点击“烧录固件”
|
||
|
||
> Bootloader 的 Y-Modem 只按 1K 整包接收，OTA 升级包发送前请先用“补齐”功能处理。
|
||
|
||
## 命令行固件工具
|
||
|
||
### 快速开始
|
||
|
||
```bash
|
||
# 合成完整镜像（整片烧录用）
|
||
python gd32e230_firmware_tool.py -m app.bin
|
||
|
||
# 补齐升级包（Ymodem 升级用）
|
||
python gd32e230_firmware_tool.py -f app.bin
|
||
```
|
||
|
||
### 模式说明
|
||
|
||
#### `-m` / `--merge` — 合成完整镜像
|
||
|
||
将 Bootloader + APP + FLAG 合并为一个 Flash 镜像，直接整片烧录。**不补齐**（整片烧录无需考虑页对齐）。
|
||
|
||
```bash
|
||
python gd32e230_firmware_tool.py -m CeramixNano-MB_V1.0.9.bin
|
||
```
|
||
|
||
输出：`CeramixNano-MB_V1.0.9_BL.bin`
|
||
|
||
#### `-f` / `--fill` — 补齐升级包
|
||
|
||
将 APP 尾部补 `0xFF` 到 1KB 页边界，供 Bootloader 的 Ymodem 接收端使用。补齐后自动检查是否超过芯片 APP 容量上限。
|
||
|
||
```bash
|
||
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
|
||
# 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
|
||
```
|
||
|
||
### 输出示例
|
||
|
||
**merge 模式：**
|
||
|
||
```text
|
||
芯片: 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 模式：**
|
||
|
||
```text
|
||
芯片: GD32E230F8 (64KB)
|
||
补齐完成: app_UPDATE.bin
|
||
原始大小: 25000B
|
||
页大小 : 1024B (1KB)
|
||
补齐字节: 600B
|
||
输出大小: 25600B
|
||
APP 上限: 55296B (54KB) → 剩余 29696B
|
||
```
|
||
|
||
**超限拦截：**
|
||
|
||
```text
|
||
错误：APP (60000B / 58.6KB) 超过最大容量 (55296B / 54KB)
|
||
芯片 64KB: 64KB - 8KB(BL) - 1KB(校准) - 1KB(Flag) = 54KB
|
||
```
|
||
|
||
### 旧版脚本
|
||
|
||
`merge_bin.py` / `fill_bin.py` 为旧版命令行脚本，功能已合并进 `gd32e230_firmware_tool.py`，历史说明见 [README_old.md](README_old.md)。
|
||
|
||
### 烧录
|
||
|
||
```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
|
||
JFlash -openprj project.jflash -open merged.bin,0x08000000 -auto -exit
|
||
```
|
||
|
||
### 安全校验
|
||
|
||
- Bootloader 体积不超过 APP 起始偏移（8KB）
|
||
- APP 大小不超过芯片可用空间
|
||
- fill 模式补齐后再次校验容量上限
|
||
- 芯片不支持自动检测，需通过 `-s` 手动指定
|
||
|
||
## License
|
||
|
||
MIT
|