Architecture¶
Build pipeline¶
scripts/build_linux.py runs these steps:
- Tool check —
git,cmake,ninjaand a C++ compiler. - PS2Recomp — clones
ran-j/PS2Recomp, checks out the commit inpatches/PS2RECOMP_COMMITand initializes the submodules. - Patches — applies the patches listed in
patches/series, in that order.tools/ci/patch_series.pyprints the same list for CI and checks that no file inpatches/is missing from it. From the repository root,python3 tools/ci/patch_series.pyshows the patches and their order; that is the reference for preparing a change on top of the pinned runtime.
The base is the Waffle565/God-Of-War-Native-Port runtime: ps2recomp-waffle-runtime.patch is the
c5a9d02..runtime diff. On top go small per-topic patches (adapted tests, VU0 VF0/VI0, native VU1 entry list,
GCC portability, native VU1 leak, and our fixes for presentation, frame pacing, pad mapping and rendering).
The script re-applies only the patches that are not yet applied, so a series that grew is continued, not restarted.
4. Native IOP (optional) — if GOW_IOP_MODULOS (default ~/.cache/gow-one-recomp/iopdump) holds a modules.txt,
tools/iop/iopn_gen.py precompiles the game's 8 IRX modules to C++ in ps2xIOP/src/native/. The folder is
produced by running the game once with PS2X_IOP_DUMP_MODULES=<folder> (tools/linux/capture_microcode.py does it
for you). Without it the IRX modules run in the IOP interpreter.
5. CMake — configures the checkout in Release mode with the options the Linux build needs (unity build and
precompiled header for the runner, no IPO, -march=x86-64-v2) and, when a VU1 microcode folder exists
(GOW_VU1_MICROCODIGO, default ~/.cache/gow-one-recomp/vu1cap), the native and compiled VU1 generators
(tools/vu1/vu1n_gen.py, tools/vu1/generate_vu1.cpp, extra entries from tools/vu1/vu1n_heads.txt).
6. Recompiler — builds the ps2_recomp target.
7. C++ generation — fills in config/recomp.template.toml (@ELF@, @MAP@, @OUT@) and runs ps2_recomp on
SCUS_973.99.
8. Runtime — copies the generated code, src/gow_overrides.cpp and src/*.h to ps2xRuntime/src/runner and builds
ps2EntryRunner.
The PS2X_ENABLE_RUNTIME_LOGS, PS2X_ENABLE_AGRESSIVE_LOGS and PS2X_ENABLE_IOP_RPC_TRACE traces are OFF by
default; --traces enables them for investigation. The GOW_PERF_DIAG profile is independent of these options.
Recompiler configuration¶
config/recomp.template.toml contains:
stubs— Sony library functions (sceMpeg*,sceIpu*,sceGs*,sceDma*,sceCd*, libc…) that the runtime implements natively.skipand instruction patches generated withps2xAnalyzerand tuned by hand.
config/funcmap.csv (Name,Start,End,Size) defines the boundaries of the ELF's 6,414 functions.
Overrides (src/gow_overrides.cpp)¶
They are registered with PS2_REGISTER_GAME_OVERRIDE for the SCUS_973.99 ELF (entry 0x00100008).
| Address | Function | Reason |
|---|---|---|
0x00296C48 |
sceSifInitRpc |
The recompiler discards it: it starts in the delay slot of a stray jr ra |
0x00294990 |
iWakeupThread |
Same case as the previous one |
0x0027AB00 |
sceCdReadDvdDualInfo |
No handler in the runtime; returns dual layer with layer 1 starting at LBN 2080544 |
0x0026BF28 |
snd_SendIOPCommandAndWait (989snd) |
Logs every command ([gow-snd]) and calls the original; with GOW_SND_STUB=1 it answers 0 without going through the IOP |
0x00298CE8 |
sceSifLoadStartModuleBuffer |
Embedded IOP module ck01: it is answered like a retail console (NO_RESIDENT_END) |
Runtime base (Waffle565)¶
The Waffle565 runtime replaces every piece of hardware the game used with native code:
| Layer | Native replacement |
|---|---|
| GS | OpenGL renderer by render targets (adjustable internal resolution, 16:9), texture/CLUT store instead of a VRAM model |
| VU1 | Microprograms precompiled to C++ (vu1n); the exact VU1 remains as a fallback |
| IOP | The game's 8 IRX modules precompiled (tools/iop/iopn_gen.py) |
| SPU2 | Native sound engine driven by the game's LIBSD calls |
| Pad / memory card | Native services, no SIO2 model |
| DMA / VIF / GIF | Packets go straight to the VU1 and the GS; the recompiler turns accesses to DMA registers, timers and GS display registers into native calls |
| Disc | Files read from your own ISO, each at its original sector |
Continuous integration¶
.github/workflows/tests.yml runs on every push to main and on every PR, without needing the game:
- Quick checks (seconds):
tools/ci/validate_config.pyvalidatesconfig/funcmap.csv(order, overlaps, sizes, names) andconfig/recomp.template.toml(@ELF@/@MAP@/@OUT@markers,name@0xADDRESSformat, addresses inside some function). Stubs that do not start a function and repeated addresses are warnings.- The launcher, the setup wizard and the AppImage entry point (
tests/test_gow_launcher.py,tests/test_gow_setup.py, an AppDir assembled withoutappimagetoolthat must hold no game files). - The GIF packet inspector,
tests/pad2_packet_test.cppandtests/pad_script_test.cpp. - Patches and runtime suite: downloads PS2Recomp at the commit in
patches/PS2RECOMP_COMMIT, applies the patches in the order ofpatches/series(tools/ci/patch_series.pyprints them and fails if anypatches/*.patchis not listed or does not apply), checks that every stub inrecomp.template.tomlhas a handler inps2_call_list.h(validate_config.py --runtime), buildsps2x_testsand runs the suite. It also buildssrc/*.cppagainst the headers of the already-patched runtime (declaring thesub_*they use), so an override that uses a runtime function that no patch defines fails here.tools/ci/check_tests.pyonly fails on tests that are not intests/known_failures.txt(empty today: the whole suite passes). CI includestools/ci/gs_tests.cmakeandtools/ci/vu1_tests.cmakein its temporary checkout of PS2Recomp to build and run the GS FINISH checks and the compiled VU1 checks (pairs, DIV, FMAC), the latter withGOW_VU1_NATIVE_OFF=1because the native VU1 goes first.
.github/workflows/status.yml regenerates the status map (manual/status-map/) when its data changes, and
.github/workflows/manual.yml builds and publishes this manual.