Raikaru/mwccps2-debugger

# MWCCPS2 Debugger [](https://github.com/Raikaru/mwccps2-debugger/actions/workflows/tests.yml) [](LICENSE) 一个用于 Metrowerks CodeWarrior PlayStation 2 C/C++ 编译器的动态分析与行为缩减工具包。它公开了选定的编译器内部阶段，以便匹配式反编译项目能够确定*为什么*等效的 C 源码会生成不同的 MIPS 目标代码。 该工具包是针对 Persona 3 FES 开发的，但其核心并非 P3 专属。任何使用确切受支持的 MWCCPS2 构建版本的项目都可以使用其指纹生成、PCode 快照、实验运行器、调度器捕获、寄存器分配捕获、语义重放器以及跨版本语料库。Persona 3 集成是位于仓库边界的一个可选适配器。 ## 状态和支持边界 完全验证的实时调试配置为： ``` Compiler: mwcps2-3.0.1b210-060308 SHA-256: 286548490e2e902cfef21dcf39cd5af23766731585d90dea747f8781eadcafd7 PE time: 0x440f429b Image base: 0x00400000 ``` 可移植指纹和直接目标语料库也支持 b151、b198 和 b205。不假设它们的实时内部布局与 b210 相同。 已验证的主机配置： ``` Windows 11 x64 Python 3.10.11 GNU GDB 16.3 with Python support ``` 本仓库不随附分发编译器和游戏数据。请提供您在合法授权下有权使用的编译器副本和零售版可执行文件。 ## 它能解答什么问题 对于一个被缩减的函数或表达式，调试器可以回答诸如此类的问题： - 两个源码变体在后端 PCode 生成时是否就已经存在差异？ - 指令调度是否重排了原本完全一致的操作？ - 寄存器分配是否为相同的虚拟角色分配了不同的物理寄存器？ - 明显的源码改动是否仅仅改变了不透明的图元数据，而语义 PCode 和最终目标字节保持不变？ - 某种行为是 b210 特有的，还是在 b151/b198/b205 中有所不同？ - 对于真实的 P3 不匹配情况，哪些源码塑造实验是合理的？ 捕获的阶段顺序为： ``` C / frontend IR ↓ codegen_entry ↓ before_scheduling ↓ after_scheduling ↓ before_register_allocation ↓ after_colorgraph_assignment ↓ after_register_allocation ↓ object code ``` 并非每个优化级别都会执行每个阶段。特别是，`-O2` 编译可能不会命中调度器断点；这会被报告为缺失阶段，而不是捏造数据。 ## 仓库结构 ``` mwccps2_probe.py PE fingerprint and static anchor report mwccps2_debug_launch.py suspended Windows launch for manual attach mwccps2_experiment.py normal PCode/regalloc differential runner mwccps2_scheduler_experiment.py live scheduler differential runner mwccps2_portability.py compiler discovery and cross-version corpus mwccps2_p3_reduce.py optional P3 verifier-report bundle adapter gdb/ mwccps2_b210_snapshot.py GDB command for PCode/regalloc snapshots mwccps2_b210_scheduler.py GDB command for scheduler decisions b210_*_model.py pure validation and normalization models decomp/ instruction_selection.py recovered selector decision model scheduler.py ready-queue and dependency semantic model register_allocation.py colorgraph replay frontend_optimizations.py bounded frontend rewrite model transports/ gdb.py Windows and retrowin32 command transports capabilities.py Wine/Wibo capability evidence capture_compare.py host-independent snapshot comparison experiments/ checked-in source-variant reducer corpus profiles/ exact fingerprints, anchors, and layouts analysis/ machine-readable behavioral conclusions reports/ concrete mismatch explanations tests/ deterministic regression suite build/ ignored local snapshots and summaries ``` ## 快速开始 ### 1. 验证前置条件 使用 Python 3.10 或更高版本。该项目在运行时仅使用标准库。 安装带有 Python 脚本支持的 GDB 构建，并确保 `gdb` 位于 `PATH` 中。 运行测试： ``` python -m unittest discover -s tests -p "test_*.py" ``` 预期的仓库基线： ``` Ran 368 tests OK ``` ### 2. 提取编译器指纹 ``` python mwccps2_probe.py D:/mwcps2-3.0.1b210-060308/mwccps2.exe ``` 生成可复用的报告： ``` python mwccps2_probe.py D:/mwcps2-3.0.1b210-060308/mwccps2.exe --json build/compiler-probe.json ``` 如果 SHA-256 不同，请不要继续使用 b210 实时配置。绝对地址和内部布局因可执行文件而异。 ### 3. 运行首次实验 每个输出目录都必须是本仓库中被忽略的 `build/` 目录下的一个全新子目录： ``` python mwccps2_experiment.py experiments/commutative_mul_s --output build/quickstart-mul ``` 如果编译器或 GDB 不在其默认位置： ``` python mwccps2_experiment.py experiments/commutative_mul_s --compiler C:/toolchains/mwcps2-3.0.1b210-060308/mwccps2.exe --gdb C:/tools/gdb/bin/gdb.exe --output build/quickstart-mul ``` 运行器会将每个变体编译两次： 1. 直接使用 MWCCPS2； 2. 在启用了内部快照的 GDB 环境下运行。 仅当两个目标文件的 SHA-256 值完全相同时，该变体才被接纳。摘要信息为： ``` build/quickstart-mul/experiment-summary-v1.json ``` 除了机器可读的 JSON 快照外，每个变体还包含人类可读的 `*.pcode.txt` 文件。 ### 4. 解读首次差异 请使用最早的*语义 PCode* 差异，而不是最早的原始图哈希变化： | 结果 | 解读 | | --- | --- | | `earliest_pcode_divergence: codegen_entry` | 源码/前端/选择形态已有差异。 | | 调度后的首次差异 | 调查依赖关系、延迟、资源和就绪队列关联。 | | PCode 在分配前一致但在分配后不同 | 调查干涉、合并、简化顺序和着色。 | | 原始图不同但 PCode 和目标文件一致 | 不透明/瞬态元数据发生改变；在该实验中不是有用的目标代码操纵手段。 | | PCode 一致但目标文件不同 | 调查后续的 lowering、帧/重定位/编码行为；切勿臆造捕获的成因。 | 有关完整工作流，请参阅[实验与产物解读](docs/experiments.md)。 ## 常用命令 运行普通的 b210 差异实验： ``` python mwccps2_experiment.py experiments/commutative_addu --output build/addu-analysis ``` 运行调度器实验（其清单中声明了 `-O3`）： ``` python mwccps2_scheduler_experiment.py experiments/scheduler_ready_tie --output build/scheduler-analysis ``` 重放观察到的颜色图分配： ``` python decomp/register_allocation.py build/regalloc-o3-smoke-out/variants/load_indexed/snapshots/000005-after_colorgraph_assignment.json ``` 发现本地编译器构建并验证 b210： ``` python mwccps2_portability.py --json build/compiler-portability.json ``` 跨所有可用且请求的构建版本运行缩减器语料库： ``` python mwccps2_portability.py --run-corpus --work-dir build/version-corpus --json build/version-corpus.json ``` 创建确定性的 P3 分析包： ``` python mwccps2_p3_reduce.py --config ../Persona3-FES-Decompilation/config/mwccps2-debugger.json --report ../Persona3-FES-Decompilation/build/h_sfdply_verify.json --function H_SfdPlay_UpdateTask --output build/H_SfdPlay_UpdateTask-analysis ``` 在使用调试器结果修改游戏源码之前，请参阅 [P3 匹配工作流](docs/p3-workflow.md)。 ## 证据规则 这些规则适用于人类和代码助手： 1. **零售版验证依然具有权威性。** 快照永远不能证明某个 P3 函数是匹配的。只有 P3 验证器才能报告 `MATCH`。 2. **要求直接/插桩的目标文件相等。** 如果 GDB 改变了目标文件，请将该捕获作为行为证据予以丢弃。 3. **将观察与推断分开。** 无法获取零售版编译器的瞬态状态。不要将零售版的干涉图、AST 或调度器队列描述为已观察到的。 4. **使用语义 PCode 进行阶段分类。** 原始堆地址和不透明的图元数据仅用于诊断。 5. **一次仅更改一个缩减器属性。** 否则首次差异无法确定有用的源码操纵手段。 6. **将生成的输出保留在 `build/` 下。** 它是本地的、被忽略的，并且可能包含特定于主机的路径。 7. **切勿提交编译器二进制文件、游戏二进制文件或提取的零售版字节。** ## 文档 - [入门指南](docs/getting-started.md) — 设置、编译器指纹、首次捕获和主机说明。 - [实验与产物](docs/experiments.md) — 清单格式、输出 schema、决策树、调度器和分配器工作流。 - [P3 匹配工作流](docs/p3-workflow.md) — 从主反编译项目使用调试器的确切代理/人类程序。 - [架构与扩展点](docs/architecture.md) — 进程边界、配置文件、GDB 收集器、纯模型，以及添加构建或捕获。 - [故障排除](docs/troubleshooting.md) — 指纹、GDB、调度、输出目录、编译器和解读失败。 ## 当前限制 - 实时内部捕获仅对确切的 b210 可执行文件进行了全面验证。 - 前端模型有目的地进行了限制；它不是一个完整的 AST/IR 反编译器。 - 无法从零售游戏的最终可执行文件中恢复其原始的瞬态编译器状态。 - 调度器捕获仅在编译器实际调用调度器时才适用。 - Retrowin32 命令构造已实现并经过测试，但此处尚未验证任何实时的本地 retrowin32 编译器会话。 - 对 Wine 和 Wibo 进行了能力探测；经验证的工作站上未安装这两者，目前也未将它们宣传为经过验证的快照传输方式。 - 这是一个用于诊断和实验的工具，而不是自动匹配引擎。 ## 许可证 本仓库中的原始工具和文档在 [MIT 许可证](LICENSE)下提供。该许可证不授予或暗示对 Metrowerks 编译器二进制文件、Persona 3 资产、零售可执行文件或其他第三方材料的任何权利。用户必须根据适用的权利，单独提供任何必需的第三方软件或游戏数据。

标签：Metrowerks CodeWarrior, MIPS架构, PlayStation 2, 云资产清单, 匹配反编译, 编译器调试, 逆向工具, 逆向工程