bong-water-water-bong/amdnpu-ps1p
GitHub: bong-water-water-bong/amdnpu-ps1p
用于解析、提取、分析和重打包 AMD XDNA 2 NPU 的 $PS1p 固件容器格式的 Python 工具库。
Stars: 0 | Forks: 0
# AMD NPU $PS1p — Firmware Container 工具
[](LICENSE)
[](https://www.python.org/downloads/)
**ps1p** 是一个 Python 库，用于解析、提取、修改和分析
**$PS1p container 格式**的 AMD NPU (Neural Processing Unit) 固件镜像。
$PS1p 格式是 AMD XDNA™ 2 NPU
(Strix Halo / Ryzen AI 300 系列) 使用的固件打包格式，用于封装 IPU (Intelligent Processing Unit)
微控制器固件及其相关的 AI Engine (AIE2) 控制数据。
## 功能
- **解析** $PS1p 固件容器并提取所有 section
- **识别** 固件版本、SHA256 校验和、分区表
- **提取** IPU 微控制器代码、字符串表、AIE2 控制 payload
- **分析** 带有熵指标和内容分类的二进制 blob
- **转储** section 详情，包括 ARM Thumb 代码检测和 Xilinx bitstream 标记
- **重打包** 经过字节级修改的容器
- 提供 `info`、`extract`、`dump`、`repack` 命令的 **CLI**
- 用于编程调用的简洁 Python 接口 **API**
## 安装说明
```
pip install git+https://github.com/bong-water-water-bong/amdnpu-ps1p.git
# 或者从源码安装：
git clone https://github.com/bong-water-water-bong/amdnpu-ps1p.git
cd amdnpu-ps1p
pip install -e .
```
## 快速开始
```
# 显示 container 信息
ps1p info firmware.sbin
# 提取所有 section
ps1p extract firmware.sbin -o extracted/
# 转储 section 详情并进行 blob 分析
ps1p dump firmware.sbin sub_payload --blobs
# 提取 IPU 代码并进行分析
ps1p extract firmware.sbin
python3 -c "
from ps1p import open_ps1p
fw = open_ps1p('firmware.sbin')
fw.extract_all('out')
print(fw.summarize())
"
```
## 命令
| 命令 | 描述 |
|--------------------|-----------------------------------------------|
| `ps1p info ` | 显示容器元数据和 section 表 |
| `ps1p extract ` | 提取所有 section 到独立文件 |
| `ps1p dump ` | 显示某个 section 的详细分析 |
| `ps1p repack -o ` | 进行字节级 patch 并重打包 |
### 示例
```
# 以 JSON 格式显示信息
ps1p info firmware.sbin --json
# 提取到特定目录
ps1p extract firmware.sbin -o /tmp/extracted
# 转储 IPU 代码 section 详情
ps1p dump firmware.sbin ipu_code --verbose
# 在 AIE2 payload 中查找 sub-blob
ps1p dump firmware.sbin sub_payload --blobs --min-blob-size 128
# 在偏移量 0x220 处使用已修补的字节重新打包
ps1p repack firmware.sbin -o patched.sbin --replace 0x220,patched_code.bin
```
## Python API
```
from ps1p import open_ps1p, BlobAnalyzer
# 打开 firmware 文件
fw = open_ps1p('/path/to/firmware.sbin')
# 访问 section
code = fw.get_section('ipu_code')
payload = fw.get_section('sub_payload')
# Section 属性
print(f"IPU Code: {code.offset:#06x}-{code.end:#06x} ({code.size} bytes)")
print(f"Entropy: {code.entropy_value:.3f}")
print(f"SHA256: {code.sha256}")
# 提取所有内容
paths = fw.extract_all('/tmp/output/')
# Blob 分析
analysis = BlobAnalyzer.analyze(payload.data)
print(f"Classification: {analysis.classification}")
```
## 容器结构
$PS1p 容器按以下布局打包 NPU 固件：
| Section | 偏移量 (v1.1.x) | 描述 |
|-----------------|---------------------|-----------------------------------------------|
| Header | 0x00-0x21F | Magic ($PS1p), 版本, SHA256, RSA 签名 |
| IPU Code | 0x220-0x1C000 | VE2 VLIW 微控制器固件 |
| String Table | 0x1C000-0x20000 | 日志消息和调试字符串 |
| Sub-Payload | 0x20000-0x68C70 | AIE2 kernel, SOC 配置, bitstream |
| Partition Table | 0x68A00-0x68C70 | AIE 列分区映射 |
| RSA Signature | 0x68D70-0x68E70 | RSA-2048 签名 (256 bytes) |
## 固件来源
`.sbin` 固件文件可以在 AMD Linux 系统的以下路径找到：
```
/lib/firmware/amdnpu//npu.sbin.zst
```
在使用之前，请使用 `zstd` 进行解压：
```
zstd -dc /lib/firmware/amdnpu/17f0_11/npu.sbin.1.1.2.65.zst > firmware.sbin
```
## 前置条件
- Python 3.10+
- 无外部依赖（仅使用标准库）
- 用于固件解压的 `zstd` 命令行工具（系统工具）
## 开源协议
MIT
标签：AMD NPU, Python, 二进制解析, 云资产清单, 固件分析, 文档结构分析, 无后门, 逆向工具, 逆向工程