akratch/n64-decomp-workbench

# N64 Decomp Workbench 这是一组小型、可组合的工具，适用于反编译在结构上已非常接近，但编译器行为仍在决定最后几条指令的阶段。 该工具集诞生于对四个庞大或难以攻克的 Diddy Kong Racing (DKR) 函数的最终匹配工作。这个独立的代码库保留了可重用的部分：重定位感知比较、可重复的候选活动、编译器跟踪分析、受保护的 static-recomp 插桩以及保留步骤重放。DKR 特有的材料仅作为实例展示，而非关于 IDO 的一般规则或对历史源码的证明。 此代码库不包含任何 ROM、提取的目标文件、专有编译器二进制文件或完全复制的翻译单元。 ## 适用场景 该工具集的大部分功能与项目和编译器无关： - `compare`、`compare-dumps`、排名和活动适用于 MIPS 对象和 GNU 兼容的 objdump 输出。 - Trace 解析器处理已记录的文本格式，可以由任何输出这些格式的编译器插桩提供数据。 - FIFO 重建对观察到的分配事件进行建模，而不依赖于 IDO。 - Pass replay 调用调用方提供的汇编阶段，并生成用于比较的对象。 `instrument-uopt*` 命令在适用范围上特意做出了限制。它们仅用于修补来自一个固定 IDO 5.3 static-recomp 版本生成的 `uopt.c`，会检查其 SHA-256 和锚点，并且默认拒绝未知输入。通用的 `ugen.c` 调用/空闲列表钩子可单独提供。该工具集不包含编译器、binutils、ROM 或游戏构建系统。 ## 选择你的工作流 | 我想要… | 从这里开始 | |---|---| | 在没有 N64 工具链的情况下评估该软件包 | [五分钟指南](#five-minute-tour) | | 验证两个 MIPS 对象是否匹配 | [对象匹配工作流][workflows-object] | | 搜索并对多个源码候选进行排名 | [活动编写工作流][workflows-campaign] | | 调查寄存器分配瓶颈 | [分配器工作流][workflows-allocator] | | 隔离编译器后期 Pass 的决策 | [Pass 边界工作流][workflows-pass] | | 为 static-recompiled IDO 添加受保护的 trace | [IDO 插桩工作流][workflows-ido] | | 使该软件包适应其他项目或编译器 | [维护者工作流][workflows-maintainer] | | 诊断错误或空结果 | [故障排除][troubleshooting] | 完整的[开发者工作流][workflows]说明了前置条件、预期输出和停止点。[四个 DKR 案例研究](#worked-examples) 展示了这些技术背后的证据；[范围指南][scope-and-claims] 将这些观察结果与更广泛的结论区分开来。 参考资料： - 操作：[对象比较][object-comparison]、[活动][campaigns]、[trace 分析][trace-analysis]、[pass replay][pass-replay] 和 [编译器插桩][compiler-instrumentation]。 - 证据：[历史工具清单][historical-inventory]、[经验教训][lessons-learned]、[来源出处][provenance] 和 [0.2.0 验证记录][validation-record]。 - 项目：[更新日志][changelog]、[贡献](CONTRIBUTING.md) 和 [许可证][license]。 ## 安装 需要 Python 3.10 或更高版本。安装的包仅使用标准库。 从此代码库的克隆副本中： ``` git clone https://github.com/akratch/n64-decomp-workbench.git cd n64-decomp-workbench python3 -m pip install -e . decomp-workbench --help ``` 在 PyPI 上发布后，也可以使用 `python3 -m pip install n64-decomp-workbench` 来安装该包。 若要开发此包： ``` python3 -m pip install -e ".[dev]" PYTHONPATH=src python3 -m unittest discover -s tests -v ruff check src tests ruff format --check src tests mypy src tests ``` ## 五分钟指南 这些示例使用保留的文本固件和合成的 trace，因此不需要 ROM、IDO 或 MIPS binutils。 ### 1. 比较两个重定位的指令流 ``` decomp-workbench compare-dumps \ examples/fixtures/target.objdump \ examples/fixtures/relocated-match.objdump \ --fail-on-mismatch ``` 原始字在 `jal` 目标和 `lui` 立即数上有所不同，但这两个字段都有匹配的重定位记录。工具集仅屏蔽由链接器控制的位，并报告 `words=0 raw=2`。 现在暴露一个真实的寄存器差异： ``` decomp-workbench compare-dumps \ examples/fixtures/target.objdump \ examples/fixtures/register-mismatch.objdump \ --show-diff ``` 这会报告一个字、归一化、寄存器和 FP-register 不匹配。 ### 2. 重放已追踪的临时寄存器 FIFO ``` decomp-workbench trace-fifo examples/traces/ugen-fifo.log \ --registers t6,t7,t8 \ --show-events \ --fail-on-violation ``` 前置的追加事件为队列提供种子。报告会将后续的每一次分配与 FIFO 的头部进行核对，并为物理寄存器事件分配稳定的逻辑值标识（`v1`、`v2`，…）。 ### 3. 对 globalcolor 活跃区间进行排名 ``` decomp-workbench trace-globalcolor \ examples/traces/globalcolor.log \ --dtype 13 ``` 这会解析保留的 `CSAVE`/`CUP` 格式以及所包含 profile 输出的后续 `[CDX]` 记录。历史字段名 `unk1C` 显示为 `weight`；原始值将被保留，且文档不主张超出实验所确立的更广泛的语义解释。 ### 4. 检查别名决策 ``` decomp-workbench trace-alias \ examples/traces/alias.log \ --show-queries ``` 这会将保留的、直接的和新生成的基路径分开，并总结每次观察到的别名查询的描述符类型和结果。该固件是合成的；字段名反映了固定的插桩 profile。 ## 命令映射 | 命令 | 用途 | |---|---| | `compare` | 反汇编并比较两个对象 | | `compare-dumps` | 比较可再发行的 GNU objdump 文本 | | `rank` | 对预构建的候选对象进行排名 | | `compile-rank` | 简单的顺序编译并排名循环 | | `campaign` | 带缓存和 JSONL 账本的并行编译 | | `trace-summary` | 统计事件、寄存器和源代码行数 | | `trace-alias` | 总结 uopt 基础来源和别名决策 | | `trace-fifo` | 验证并重建 FIFO 寄存器类 | | `trace-globalcolor` | 总结 uopt 分配开销和决策 | | `instrument-ugen` | 为生成的 `ugen.c` 添加可选的调用/空闲列表钩子 | | `instrument-uopt` | 组合兼容的固定 uopt profile | | `instrument-uopt-globalcolor` | 应用通过哈希固定的 IDO 5.3 uopt profile | | `instrument-uopt-alias` | 应用通过哈希固定的别名 trace profile | | `replay-as1` | 编辑保留的 ugen 列表并重新运行 as0/as1 | 当需要机器可读的输出时，每个报告命令都支持 JSON。编译器命令使用 `shlex` 进行分词并在不调用 shell 的情况下运行。 退出代码的含义和常见的工具链失败原因汇总在[故障排除][troubleshooting]中。 ## 各部分如何协同工作 ``` source candidates │ ▼ campaign ──────► candidate objects ──────► compare / asm-differ │ structural plateau ────┘ ▼ uopt / ugen traces │ │ │ ▼ ▼ ▼ coloring aliases FIFO replay │ │ │ └───────┼───────┘ ▼ focused source change retained ugen listing ──► replay-as1 ──► causal pass-boundary experiment ``` 预期的工作流是使用能够解答当前问题的侵入性最小的预言机。修改编译器是最后的诊断步骤，而不是默认的匹配技术。 ## 实例分析 案例研究重点介绍了工具及其揭示的证据： 1. [Globalcolor 跟踪揭示了一个表达式顺序平局][trackbg-case]。 2. [惩罚桶防止了一个有用的候选被丢弃][objects-case]。 3. [物理寄存器追踪变成了一个逻辑事件调度][racer-case]。 4. [Pass replay 发现了一条缺失的 `.noalias` 指令][menu-case]。 每个例子都将观察到的事实、诊断干预、最终匹配的源码修改以及结论的局限性区分开来。 ## 代码库映射 ``` src/decomp_workbench/ installable Python package tests/ standard-library unit tests examples/fixtures/ redistributable objdump text examples/traces/ small synthetic trace fixtures case-studies/ four DKR worked examples docs/workflows.md end-to-end developer journeys docs/troubleshooting.md failure modes and issue-report checklist docs/ focused guides, evidence, and reference research-archive/ index to preserved raw experiments .github/workflows/ci.yml release-equivalent continuous integration ``` 大量的历史活动——数百个变体、报告和特定于函数的脚本——仍然在 DKR Git 分支 [`archive/decomp-research-2026-07-26`][research-archive] 上可用。故意不将其混入公共 API 中。 ## 插桩安全性 跟踪编译器可能会扰乱编译器。请将此视为一个可测试的属性，而不是一个假设： 1. 构建未修改的 pass 和已插桩的 pass。 2. 在取消设置所有工作bench环境变量的情况下运行两者。 3. 比较目标对象、已匹配的附属对象以及完整的 ROM 或二进制文件。 4. 启用一个已知的 trace 作为阳性对照。 5. 仅将行为更改控制（例如 `CDX_FORCE`）用作因果探测。 uopt profile 被固定为某个生成的 IDO 5.3 `uopt.c` 的 SHA-256，并且默认情况下会拒绝其他源代码。请参阅 [编译器插桩][compiler-instrumentation] 指南，以获取确切的上游版本和验证清单。 ## 项目状态 版本 0.2.0 取代了最初的 `v0.1.0` 快照。重定位比较器、活动准备、trace 解析器、FIFO 模型、列表突变和插桩锚点检查均已通过合成测试。 实际的 IDO 和整个 ROM 的保真度检查需要用户提供的工具链和游戏输入，因此它们被记录为集成测试关卡，而不是可再发行单元套件所作出的声明。 ## 许可证 原始的 workbench 代码、固件和文档根据 [CC0 1.0 Universal][license] 奉献给公共领域。第三方工具以及用户提供的编译器或游戏输入保留其各自的使用条款。

标签：MIPS架构, SOC Prime, 云资产清单, 开发工具, 游戏开发, 编译器, 逆向工具, 逆向工程