kidoz/cxbx

# CXBX [](LICENSE) [](https://mesonbuild.com/) [](meson.build) [](meson.build) [](cross/i686-windows-clang.ini) CXBX 是一款经典的初代 Xbox 模拟器。此代码树包含模拟器、 Win32 启动器/运行时代码、内置的 open-xdk 支持库，以及一个 现代化的基于 Meson 的构建/移植工作区。 这是经典的 caustik CXBX 代码库，而不是 Cxbx-Reloaded。目前它正作为 一个 32 位 Windows/x86 HLE 模拟器被推进，具备可重现的 构建文件、结构化的调试跟踪以及一个模拟器一致性测试套件。 当前活跃的开发者和维护者：Aleksandr Pavlov 。 ## 截图 ## 当前状态 本仓库用于开发和模拟器的推进。它不是一个完善的 最终用户发布版本。 - 构建系统：仅限 Meson。 - 主要目标：32 位 Windows (`i686-pc-windows-msvc`)，使用 clang/lld 工具链。 - 模拟模型：HLE 加载器/API 桥接；客户机 x86 代码直接在宿主机 CPU 上运行。 - 图形：Direct3D HLE 外加部分寄存器级的 NV2A 模型，用于 MMIO/RAMIN/PFIFO/PGRAPH 方法路径。这不是完整的 NV2A 光栅化。 - 调试：结构化的 `Emu`、`KTRACE|`、`NV2A|` 和一致性跟踪路径。 - 一致性：树内探测套件目前跟踪 CPU、内存、文件 I/O、内核、图形和 NV2A 的行为。 已知正在进行的活跃工作包括源码可移植性、x86 内联汇编/工具链 兼容性、内核导出覆盖率、连续内存行为和图形 推进。 ## CXBX 的工作原理 CXBX 是一个 HLE 模拟器： 1. 它加载一个 Xbox 可执行文件 (`.xbe`)。 2. 它映射客户机镜像并准备内核 thunk 表。 3. 它使用 OOVPA 签名识别 XDK 库函数。 4. 它将定位到的客户机函数 patch 为跳转到宿主机的实现。 5. 客户机 x86 代码在宿主机 CPU 上原生运行。 这使得大多数故障都是 API 边界故障，而不是 CPU 解释器 故障。典型的调试目标是缺失的 XDK 签名、错误的 HLE 实现、未实现的内核序号、FS 段状态以及 GPU MMIO 状态。 ## 快速上手 ### 前置条件 - **clang/LLVM** (clang、lld、llvm-lib、llvm-dlltool) — 主要的工具链。 在 Windows 上，通过 `scoop install llvm` 安装或从 llvm.org 下载。 - **Meson ≥ 0.56** 和 **Ninja** — `pip install meson ninja` 或 `scoop install meson ninja`。 - **Python 3.13+** 配合 **uv** 用于一致性套件和 OOVPA 工具： `pip install uv`。 - **just** (命令运行器) — 可选，但推荐： `scoop install just`。 - **Xbox XDK** (仅在针对 原始 SDK 库构建一致性探测时需要)。使用合法获取并在本地配置的 SDK 安装。 ### 一次性设置 模拟器是 32 位 x86 的，必须使用提供的交叉 文件进行配置。`build-min` 是由 `justfile`、 一致性运行器和文档使用的规范构建目录： ``` just init # uv sync --dev (Python tooling) meson setup build-min --cross-file cross/i686-windows-clang.ini ``` ### 构建 ``` just build # meson compile -C build-min ``` 构建选项（在设置时通过 `-D=` 或通过 `meson configure` 设置）： - `build_xiso` (默认为 `true`) — `xiso` 光盘镜像宿主机工具。它没有 模拟器依赖项，因此也可以在普通的本机目录中构建： `meson setup build-xiso` (无交叉文件)，然后运行 `meson compile -C build-xiso`。 - `build_xusb` (默认为 `false`) — 旧版 open-xdk xusb OHCI 栈。 ### 运行 Xbox 游戏 ``` meson devenv -C build-min cxbx --run "path/to/default.xbe" --log "session-output.txt" ``` 使用绝对路径 `--log` — 运行时子进程会相对于 `%TEMP%` 解析它。 ## 开发工作流 ``` just --list # all recipes just format # clang-format (src/ include/ tests/) + ruff format (tools/xtest) just lint # clang-tidy (src/ tests/) + ruff check + mypy (tools/xtest) just build # meson compile -C build-min ``` 格式化和 lint 已经涵盖 `src/*`，因此 `xiso` 工具和 `src/` 下的任何 新代码都会被自动覆盖。Python 工具使用 `uv` 进行管理 (`uv sync --dev`，通过 `just init` 运行一次)。 ## 一致性套件 `tests/suite/` 下的套件会构建小型的自检 Xbox 可执行文件，并 针对模拟器运行它们。每个探测会产生确定性的跟踪输出和 PASS/FAIL 检查。 ``` uv run python tools/xtest/xtest.py list uv run python tools/xtest/xtest.py run --emulator cxbx uv run python tools/xtest/xtest.py run --emulator cxbx --probe cpu_flags uv run python tools/xtest/xtest.py run --emulator cxbx --probe cpu_flags --update-golden ``` 该套件与模拟器无关；可以使用以下命令启动自定义目标： ``` uv run python tools/xtest/xtest.py run --emulator custom --cmd "myemu --run {xbe} --dvd {rundir}" ``` 使用已跟踪的 `tools/config.toml.example` 作为本地运行器 设置（如工具链和模拟器路径）的参考。Golden 文件位于 `tests/suite/golden/cxbx/`。 当前的探测领域包括： - CPU 标志和原生 x86 行为 - 内存分配和读写检查 - 通过 `D:` 的 FATX 风格文件 I/O - 内核 HLE 覆盖率和未实现导出捕获 - 帧缓冲区可用性检查 - NV2A PMC、中断、RAMIN、PFIFO 和 PGRAPH 方法路径 ## 调试 对于可重现的运行，优先使用基于文件的日志： ``` $env:CXBX_LOG_FILE = "session-output.txt" ``` 重要的跟踪通道： - `Emu (0x): ...` 用于常规的模拟器/运行时日志。 - `EmuFS (0x): ...` 用于 FS 段交换。 - `KTRACE| ...` 用于内核 thunk 诊断。 - `NV2A| ...` 用于 GPU MMIO/PFIFO/PGRAPH/RAMIN 跟踪。 - `XT| ...` 用于结构化的一致性探测输出。 调试工作流的核心是确定故障是 OOVPA 签名未命中、错误的 wrapper patch、未实现的内核导出、FS 交换不平衡，还是 NV2A 寄存器/模型差异。 要获取完整的调试跟踪（HLE patch 地址、每个定位到的函数），请构建 `_DEBUG_TRACE` 变体： ``` meson setup build-review --cross-file cross/i686-windows-clang.ini meson configure build-review "-Dcpp_args=['-D_DEBUG_TRACE']" "-Dc_args=['-D_DEBUG_TRACE']" meson compile -C build-review meson devenv -C build-review cxbx --run "path/to/default.xbe" --log "session-output.txt" ``` 随后日志将包含如下行： ``` Emu (0x7C48): 0x00194960 -> EmuIDirect3DDevice8_SetRenderTarget ``` ## 编写 OOVPA HLE 签名 当 Xbox 游戏调用 cxbx 尚未 patch 的 XDK 函数时，你需要 添加一个 OOVPA (Ordered Offset Value Pair Array) 签名来定位 客户机镜像中的函数，并将其路由到宿主机的 `Emu*` wrapper。工作流如下： 1. **在相关的 XDK 库中找到该函数**，并生成和验证 签名： python tools/oovpa/gen_oovpa.py \ --lib "path/to/sdk-library" \ --func "_D3DDevice_SetRenderTarget@8=IDirect3DDevice8_SetRenderTarget_1_0_4627" \ --verify-one "path/to/default.xbe" \ --verify "path/to/xbe-corpus/*/default.xbe" \ --pairs 8 签名在包含该函数的镜像中必须**只匹配一次**，并且 在任何地方都**绝不能超过一次**。工具会针对每个镜像报告 `OK` / `FAIL`。 2. **将 OOVPA 定义 + 注册条目添加**到相应的 特定版本 `.inl` 文件中 (例如 `src/cxbx/src/win32/CxbxKrnl/D3D8.1.0.4627.inl`)， 路由到 `EmuD3D8.cpp` / `include/.../EmuD3D8.h` 中现有或新的 `Emu*` wrapper。 3. **验证 patch 地址** — 构建 `_DEBUG_TRACE` 变体并确认 patch 落在由独立的符号或 反汇编工具报告的地址上。如果两个工具在地址上达成一致，则签名是 正确的。 4. **添加或更新一致性探测**，以便该行为被锁定以防回归 (有关模式，请参见 `tests/suite/probes/d3d_state/`)。 ## `xiso` 工具 (Xbox 光盘镜像) `xiso` 是一款第一方 C++17 宿主机工具，用于列出、提取、创建、 检查和验证 Xbox GDF/XDFS 光盘镜像。它在任何 构建目录中默认构建 (请参见 [构建](#build))： ``` meson devenv -C build-min xiso -l "game.iso" # list meson devenv -C build-min xiso -x -d destination "game.iso" # extract meson devenv -C build-min xiso -c source_dir output.iso # create meson devenv -C build-min xiso -i "game.iso" # header info meson devenv -C build-min xiso -V "game.iso" # verify ``` ## 仓库布局 ``` 3rdparty/dxsdk/ Bundled DirectX SDK headers docs/ Project documentation, reference notes, screenshots, branding Lib/ Bundled import libraries PostBuild/ Legacy post-build utilities Resource/ Win32 resources, icons, bitmaps, menus, dialogs cross/ Meson cross files include/cxbx/include/ CXBX public/internal headers include/open-xdk/include/ Bundled open-xdk headers src/cxbx/ Emulator launcher, core, and HLE runtime src/open-xdk/src/ Bundled open-xdk support libraries src/xiso/ xiso disc-image host tool tests/ Test assets and XBE probes tools/oovpa/ OOVPA signature generator tools/xtest/ Conformance-suite runner ``` ## 文档 有用的起点： - [docs/README.md](docs/README.md) - 文档索引。 - [docs/todo.md](docs/todo.md) - 任务列表和未决的工程主题。 - [docs/changelog.md](docs/changelog.md) - 项目历史变更。 - [docs/direct3d.md](docs/direct3d.md) - Direct3D 笔记。 - [docs/input.md](docs/input.md) - 输入笔记。 - [tests/suite/README.md](tests/suite/README.md) - 一致性套件指南。 - [tools/xtest/README.md](tools/xtest/README.md) - 探测运行器用法。 ## 法律声明 CXBX 基于 GNU 通用公共许可证版本 2 或更高版本授权。请参见 [LICENSE](LICENSE)。 本项目不包含 Xbox BIOS 镜像、零售游戏数据或主机 固件。它确实包含旧版兼容性材料，例如 DirectX 头文件 和导入库；在分发二进制文件或捆绑包之前请审查此代码树。 请仅使用您在法律上被允许使用的软件和游戏转储。CXBX 不隶属于 Microsoft。

标签：C, C++, HLE, Xbox, 数据擦除, 游戏, 逆向工具, 预握手