# hex2bin_dump

**Repository Path**: Akira-Jack/hex2bin_dump

## Basic Information

- **Project Name**: hex2bin_dump
- **Description**: python 实现 hex 转 bin 并以多种数据宽度 hex_dump 打印
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 固件工具箱 — HEX / S19 / ELF / BIN 解析 · 转储 · 校验

把三个命令行脚本(HEX→BIN 转换转储、Excel 导出、固件信息/校验值解析)整合成一个完整的桌面应用,
公共业务逻辑收敛到 `fwcore.py`,命令行与图形界面共用同一套实现。

## 快速开始

```bat
:: 图形界面(双击也可以)
run_fwgui.bat
python fwgui.py                      :: 直接启动
python fwgui.py app.elf              :: 启动并自动打开文件

:: 自检(核心算法 + 三个脚本 + 界面, 300+ 项断言)
python selftest.py
```

图形界面四个页签:

| 页签 | 内容 |
| --- | --- |
| 固件信息 | 起始地址、结束地址、固件长度、有效数据、空洞、数据段、入口地址、解析告警, 以及 CRC32 / Checksum 全文报告 |
| 内存转储 | 8 / 16 / 32 位宽度切换, 分页浏览, 按地址跳转, 按十六进制或文本搜索 |
| 校验值 | 四种 CRC32 与七种 Checksum 的表格视图, 一键复制 |
| 日志 | 每一步操作的记录 |

顶部工具条可设置 **BIN 起始地址**、**空洞填充字节**、**最大间隔**、**补齐到指定大小**(含填充值与
「必须为 2 的幂」开关),并支持另存 BIN、导出 Excel、保存报告、复制摘要。

## 支持的输入格式

| 格式 | 扩展名 | 解析说明 |
| --- | --- | --- |
| Intel HEX | `.hex` `.ihex` `.ihx` `.h86` `.hex32` | 记录类型 00/01/02/03/04/05, 逐条校验和验证 |
| Motorola S-record | `.s19` `.s28` `.s37` `.srec` `.sre` `.mot` `.s1` `.s2` `.s3` | S0/S1/S2/S3/S5/S6/S7/S8/S9, 逐条校验和验证, 记录计数核对 |
| ELF | `.elf` `.axf` `.out` `.elf32` `.elf64` | 32/64 位、大小端均可; 优先用 `PT_LOAD` 段(取物理地址 `p_paddr`), 没有段表时回退到 `SHF_ALLOC` 节表; `.bss`(memsz > filesz)只占内存, 会单独列出 |
| 裸 BIN | `.bin` `.rom` `.img` | 不含地址信息, 起始地址由 `--base` 指定(界面里是「BIN 起始地址」), 默认 `0x00000000` |

* 扩展名认不出来时按**内容嗅探**: 以 `\x7fELF` 开头 → ELF, 首个非空白字符 `:` → Intel HEX,
  `S` + 数字 → S-record, 其它一律当作 BIN。
* 前三种格式自带地址, 会被解析成**连续 BIN 镜像**(地址空洞按「空洞填充字节」补齐);
  同一份固件的 `.elf` / `.hex` / `.s19` 解析结果与 `objcopy -O binary` 完全一致, CRC32 也相同。
* 数据段之间跨度超过 256MB 时直接报错, 提示用 `--max-gap` / 界面「最大间隔」限定范围
  (例如 ELF 里带有 RAM 段时填 `1M`, 只保留烧录区附近的数据)。

## 补齐到指定大小

解析得到镜像后, 常需要补成 32KB / 64KB 这类整块大小再烧录。补齐大小**可以自己输入**
(不限于下拉框里的档位), 并且会立即检查它是不是 2 的幂:

| 入口 | 用法 |
| --- | --- |
| 图形界面 | 「补齐到」下拉框**可直接手输** `96K`、`0x18000`、`65536` 等, 右侧实时提示该大小是否为 2 的幂(显示 `✔ 2 的幂 (2^16)` 或 `⚠ 不是 2 的幂` 以及邻近的两个 2 的幂); 勾选「必须为 2 的幂」后, 不是 2 的幂会直接弹错 |
| `hex2bin_info.py` | `--pad-to 64K`、`--pad-to 96K`、`--pad-to auto`、`--pad-fill 0xFF`、`--pad-pow2` |
| `hex2bin_dump.py` | 同上, 选项可写在任意位置 |
| `hex2bin_dump_write_excel.py` | 同上, 与 `--excel` 可混用 |

```bat
:: 手输一个不是 2 的幂的大小: 默认只告警, 报告里标注 ⚠ 与邻近的 2 的幂
python hex2bin_info.py app.elf --pad-to 96K -o app_96k.bin

:: 加上 --pad-pow2 就变成硬性要求, 96K 会直接报错退出(退出码 2)
python hex2bin_info.py app.elf --pad-to 96K --pad-pow2

:: 让它自己取最合适的 2 的幂
python hex2bin_dump.py app.s19 app_128.bin --pad-to auto --pad-fill 0xFF
```

2 的幂检查的三种口径:

| 场景 | 行为 |
| --- | --- |
| 手输的大小**是** 2 的幂 | 报告里标注 `[✔ 2 的幂 (2^16 = 65536 字节)]` |
| 手输的大小**不是** 2 的幂, 未开严格模式 | 照常补齐, 但报告里标注 `[⚠ 不是 2 的幂]`、列出「补齐大小检查」与邻近的 2 的幂, 并把告警写进告警列表 / stderr |
| 手输的大小不是 2 的幂, 且开启严格模式(`--pad-pow2` / 界面勾选) | 直接报错, 提示邻近的两个 2 的幂, 并建议改用 `auto` |
| 填 `auto` | 取**不小于镜像长度的最近的 2 的幂**, 此时不做手输检查 |

其余规则:

* 从镜像**末尾**补齐(地址增大方向), 补齐后结束地址随之延长。
* 目标大小支持 `32K` / `64KB` / `1M` / `0x10000` / `65536`(大小写、空格、下划线都不敏感)。
* 填充值默认跟随「空洞填充字节」, 用 `--pad-fill` / 界面的「填充」可单独指定 —— 常见组合是
  空洞补 `0x00`、尾部补 `0xFF`。
* 镜像已经不小于目标时**不做补齐也不截断**, 报告里会注明原因。
* 补齐后的完整镜像参与 CRC32 / Checksum 计算, 导出的 BIN、Excel、转储视图都是补齐后的内容。
* 报告会同时给出 `固件长度`(补齐后)、`补齐前长度`、`补齐前结束地址` 与 `补齐字节`。

## 文件说明

| 文件 | 作用 |
| --- | --- |
| `fwcore.py` | 公共核心: HEX / S-record / ELF / BIN 解析、镜像转换、地址/长度统计、CRC32、Checksum、转储、Excel 导出 |
| `fwgui.py` | 图形界面主程序(Tkinter, 零第三方依赖) |
| `hex2bin_dump.py` | 命令行: 固件 → BIN, 并打印 8/16/32 位十六进制转储 |
| `hex2bin_dump_write_excel.py` | 命令行: 在上一项基础上增加 Excel 导出(8bit/16bit/32bit 三张表) |
| `hex2bin_info.py` | 命令行: 解析固件信息并计算 CRC32 与 Checksum |
| `selftest.py` | 自检脚本 |
| `run_fwgui.bat` | 图形界面启动器 |

## 命令行用法

```bat
python hex2bin_dump.py app.hex [app.bin] [--base ADDR] [--pad-to 64K] [--pad-fill 0xFF]
                       [--pad-pow2] [--max-gap 1M]
python hex2bin_dump_write_excel.py app.elf [app.bin] [--excel app.xlsx] [--pad-to 64K]
                       [--pad-fill 0xFF] [--pad-pow2] [--base ADDR] [--max-gap 1M]
python hex2bin_info.py app.s19 [更多文件 ...] [-o app.bin] [--base 0x08000000] [--fill 0xFF]
                       [--pad-to 64K] [--pad-fill 0xFF] [--pad-pow2] [--max-gap 1M] [--no-bin]
```

* 输入是 HEX / S19 / ELF 时先转换成连续 BIN 镜像(空洞按填充字节补齐)再统计;输入是 BIN 时直接加载。
* `--base` 只对 BIN 输入有意义, 自带地址的格式一律使用文件里的地址。
* `--max-gap` 用于丢弃远离最低地址数据段的数据(ELF 的 RAM 段、稀疏 HEX 里零散的记录)。
* `hex2bin_info.py` 可一次分析多个文件并打印汇总表(`--no-bin` 表示只分析不落盘)。

## 统计与算法口径

* **起始地址 / 结束地址**: 数据中的最小 / 最大地址, 结束地址为含端点值;补齐后结束地址延长。
* **固件长度**: `结束地址 - 起始地址 + 1`, 即 BIN 镜像字节数(含空洞填充与补齐)。
* **有效数据 / 空洞**: 文件里真实出现的字节数, 与为补齐地址跨度而填充的字节数。
* **补齐字节**: 为达到 `--pad-to` 目标而从末尾追加的字节数(见上一节)。
* **CRC32**(多项式 `0x04C11DB7`, 均为完整镜像):

  | 变体 | init | 反射 | xorout | `"123456789"` 校验值 |
  | --- | --- | --- | --- | --- |
  | ISO-HDLC(等同 `zlib.crc32`) | 0xFFFFFFFF | 是 | 0xFFFFFFFF | 0xCBF43926 |
  | MPEG-2 | 0xFFFFFFFF | 否 | 0x00000000 | 0x0376E6E7 |
  | BZIP2 | 0xFFFFFFFF | 否 | 0xFFFFFFFF | 0xFC891918 |
  | JAMCRC | 0xFFFFFFFF | 是 | 0x00000000 | 0x340BC6D9 |

* **Checksum**: 8/16/32 位累加和、8 位异或和、8 位累加和求补、16 位字累加和(小端)、
  32 位双字累加和(小端);奇数长度时末尾字节按低位处理。

## 依赖

* Python 3.8+(开发环境 3.14)+ Tkinter(标准库, 图形界面需要)
* `openpyxl`: 仅"导出 Excel"需要;缺失时程序仍可正常运行, 只是该功能不可用
  (`pip install openpyxl`), 自检会跳过 Excel 内容校验并给出提示

## 健壮性说明

* HEX / S-record 记录逐条校验和验证;坏校验和、未知记录类型、缺少 EOF/结束记录、记录计数不符
  会作为告警列出, 记录被截断等硬错误直接报错, 不会静默产出错误镜像。
* ELF 只接受可执行文件/共享库, `ET_REL` 目标文件、只有重定位数据的文件会明确报错。
* 地址跨度超过 64MB 的稀疏镜像会提示"空洞会一并参与校验", 超过 256MB 直接报错并建议用 `--max-gap`,
  避免 CRC 与预期不符时摸不着头脑。
* 报告里的 `✔` / `⚠` 在 GBK 控制台上也能正常输出: 优先切到 UTF-8(必要时同时切换控制台代码页),
  切不过去就退化为 `?`, 不会因为编码问题半路崩掉。
* 大文件解析与 Excel 导出在后台线程执行, 界面不会被卡住。