Matthew Stanley
19 KiB
PSXRecomp v4 — Rules
This file is the constitution for v4. Read it at the start of every session before doing any work.
⛔ RULE -1: BUILD THE FAITHFUL CORE — NO HACKS, NO PRESERVATION
This ecosystem is being BUILT, not maintained. There is nothing to preserve.
- The correct fix is ALWAYS the faithful, hardware-accurate, class-level core.
NEVER a surgical per-game patch, a symptom workaround, a
game.tomlhack (e.g.overlay_native_block), or "make native agree with interp even if both are fake." - When a narrow patch and a general faithfulness fix both exist, the faithfulness fix WINS — even if larger, even if it breaks other titles. Other games were built on a faulty ecosystem and will be regenerated. Backward-compatibility is NOT a constraint.
- The recurring failure mode (weeks lost) is veering into a quick hack that doesn't even work and burns the session. Do not do this. If you catch yourself proposing a "surgical"/"temporary"/"just for this title" fix — STOP and build the real thing.
- PSX timing specifically: the faithful core = ONE shared per-instruction cycle-cost function for BOTH backends (compiled + dirty-RAM interp), exact block cycle totals (delay-slot ownership), timers derived on-demand from a global guest-cycle counter, devices on scheduled event deadlines, every basic-block leader re-enterable. Confer with ChatGPT via the Chrome MCP browser (chatgpt.com, "PSX Static Recompiler Debug" chat), not the codex CLI.
This supersedes any pressure to ship fast. Completeness is absolute here.
Scope (refined 2026-06-29 — faithfulness is the FOUNDATION, not the
destination). The rule above governs FOUNDATION work — building the faithful
core — and forbids per-game patches / symptom-workarounds / game.toml hacks
as a way to fake faithfulness. It does NOT forbid them forever: once the
faithful core is proven, per-game shims/hacks are the legitimate tool of the
enhancement phase — accelerated load times (toward 0), widescreen, etc. (see
docs/ENHANCEMENTS.md). Likewise LLE is the BASELINE, not an absolute: a
faithful, Beetle-validated HLE subsystem replacement is permitted at a genuine
LLE landmine (non-determinism with no hardware analog, or profound performance
loss), never as the starting point — see §0's amendment below and
recomp-template PRINCIPLES.md → "LLE Is the Baseline; HLE Is a Subsystem
Replacement, Not a Starting Point".
The authoritative game plan is docs/internal/FAITHFUL_TIMING_PLAN.md — READ IT EACH
SESSION (north star, phased plan P1–P6, current status/log). Update its
Status/Log section every session. The full-coverage accuracy burndown across ALL
axes (semantics, cycle, IRQ, MMIO, peripherals, static-vs-dynamic, determinism)
lives in docs/internal/ACCURACY_BURNDOWN.md — every item must be cross-referenced against an
external comparative (psx-spx / in-tree Beetle source / DuckStation / HW test
ROMs), not asserted. Axis 5 (peripherals — esp. SIO/controller, the hybrid-pad
bug) is the suspected-weakest second front after the cycle axis.
0. The architecture is locked
v4 implements Architecture A: static MIPS-to-C recompilation of
bios/SCPH1001.BIN, producing native C that links into the runtime as
real compiled functions.
There is no MIPS interpreter in v4 for the BIOS path. Not as a fallback. Not as a "temporary" measure. Not for "code we couldn't recompile yet". If a BIOS function cannot be recompiled, the recompiler is wrong and must be fixed. The interpreter does not exist. Do not write one.
For the faithful reference, the BIOS remains recompiled code. The historical
no-HLE restriction below is superseded for deliberate replacements by the owner
HLE policy in this section. Historically there was no HLE BIOS layer in v4. No bios.c with case branches
intercepting A0/B0/C0 vectors. No C reimplementations of OpenEvent or
StartCard or alloc_kernel_memory. The BIOS IS the recompiled C
output of SCPH1001.BIN. If a BIOS routine misbehaves, the answer is
to fix the recompiler or fix the hardware simulation it touches via
MMIO — never to write a C "shim" that produces the answer the BIOS
would have produced.
There are no stubs. A function is either fully implemented or it
aborts with a fatal error. return 0;, return 1;, cpu->v0 = 1; return; are all stubs. // TODO, // FIXME, // for now are all
stubs. Hand-delivering an event because the chain handler isn't
installed is a stub wearing a costume and is the worst kind because it
hides the missing integration.
Owner HLE policy, 2026-10-06. The older HLE amendments are superseded by
F:/Projects/recomp-template/HLE.md and the build integration.
Keep LLE buildable and runnable as the correctness reference. Qualified HLE is
the default performance implementation, selected at build time. Preserve actual
caller inputs, outputs, required memory/register effects, continuation and
observable completion ordering. Batching, native/GPU algorithms, private host
state, caching and approximate internal timing are allowed. Small practically
unnoticeable differences are already authorized. HLE need not support every game,
dual-execute, retain a live LLE state or provide a runtime switch. Compare exact
outputs exactly, intentional approximations within their declared contract, and
measure useful performance. Missing effects, false success and material gameplay
changes remain defects. Faithful-core accuracy requirements apply to the LLE
reference, not to unobserved HLE internals.
1. The BIOS is recompilation target #1, the game is target #2
Phase 1-3 of docs/internal/PLAN.md exist to get the BIOS recompiled and booting on its own. The BIOS must reach the Sony logo and the BIOS shell, running entirely as native C, before any game work begins. There is no path that loads a game EXE before the BIOS is fully working in v4. Do not load a game ISO. Do not load a game EXE. Tomba does not exist in v4 until Phase 5.
If you find yourself needing to load a game to "test something", whatever you're testing belongs to a phase that hasn't started yet.
2. Three sources of truth, in priority order
Truth comes from three sources, in this order:
- BIOS disassembly at
docs/psx_bios_disasm.txtfor what the BIOS code is supposed to do. Human-annotated pseudocode with named functions, kernel data structures (IntRP, ExCB, TCB, TCBH), A0/B0/C0 tables, boot sequence, and exception handler logic. Check this FIRST. - Ghidra MCP for what the raw bytes are at a given address (static
analysis of
SCPH1001.BINloaded at0xBFC00000). Use when the disasm doesn't cover a function or you need exact instruction-level detail. - Beetle PSX oracle (embedded in
psx-beetleoracle.exe) for what real PS1 hardware does at runtime. Beetle PSX (mednafen-psx libretro core) runs in-process with the native runtime, sharing the same debug server. Oracle commands:find_first_divergence,emu_read_ram,emu_sio_trace,emu_trace_addr,emu_step. Where Beetle has gaps, build new tooling and visibility — don't guess, don't route around.
Use all three, never just one. Don't guess. Don't say "probably". If you cannot answer a question from the disasm, Ghidra, or the Beetle oracle, the answer is "I don't know yet" — not a confident guess.
3. No printf debugging. No log files. Ever.
If you need to inspect runtime state, build a TCP debug server
command for it. The v3 build accumulated 555 GB of boot_trace*.log
and card_test*.log files because previous sessions used fprintf for
"just this one thing". The rule is absolute: no fprintf(stderr, ...)
in source code, ever, for any reason.
When the v4 runtime is built (Phase 2+), it will have a TCP debug server on a fresh port. All inspection goes through that.
4. Never modify generated code
The output of the recompiler — files in recompiler/output/ or
generated/SCPH1001_full.c etc. — is a build artifact. If the
generated code is wrong, the fix is in the recompiler source
(recompiler/src/code_generator.cpp and friends), not in the
generated file.
This is the same rule as v3 had, and it stays.
5. Don't accept partial milestones
Phase completion requires the user-visible end state, not "I think it should work now". Phase 3 is "Sony logo displays on screen". Not "the recompiler emitted code that probably draws the logo". Not "the GPU command stream looks right in the debug server". The pixels appear on screen, or the phase is not done.
This was the v3 failure mode: declaring "memory card screen freeze RESOLVED" when in fact the screen had been unlocked by hand-delivering a fake event. The fake delivery was not progress, it was theater.
6. Session start checklist
At the start of every session, before any code change:
- Read this file (CLAUDE.md).
- Read docs/internal/PLAN.md to confirm what phase we are in and what the next concrete milestone is.
- Verify
docs/psx_bios_disasm.txtexists (primary reference). - Verify Ghidra MCP is reachable. If not, stop and ask.
- State out loud: "Architecture A is locked. No interpreter. No stubs. LLE default + oracle; HLE only per the §0 amendments (opt-in tier, LLE fallback, no fakes). BIOS first. Game never until Phase 5."
If any of these fail, do not proceed with the user's task — surface the failure first.
7. Salvage from v3 — what's allowed and what's not
The recompiler in recompiler/ was salvaged from v3 because the
core MIPS-to-C translator pieces (basic_block.cpp, control_flow.cpp,
function_analysis.cpp, mips_decoder.cpp, code_generator.cpp)
operate on raw MIPS bytes and have nothing wrong with them. They just
need a new entry point that ingests a flat ROM at 0xBFC00000 instead
of a PS-X EXE-headered file, plus extensions to code_generator.cpp
to handle COP0 kernel-mode instructions the BIOS uses.
The runner from v3 was not salvaged. Specifically:
bios.c(1808 LOC HLE shims) — discardedinterpreter.c(919 LOC MIPS interpreter) — discardedevents.c,threads.c— discarded (recompiled BIOS manages its own EvCB/TCB)bios_trace.c,func_logger.c— discarded (interpreter-era helpers)main_runner.cpp— discarded (drove the interpreter)
The hardware simulation files from v3 (memory.c, gpu.c,
gpu_sw_renderer.c, dma.c, interrupts.c, timers.c, sio.c,
memcard.c, cdrom.c, iso_reader.cpp, gte.cpp, spu.c,
debug_server.c) are eligible for salvage in Phase 2 when v4
needs them, but they will be copied in one at a time, audited for
HLE-state-leakage and stub patterns first, and only the parts that are
hardware simulation (not BIOS state simulation) are kept.
Do not bulk-copy psxrecomp/runner/src/ from v3. Doing so will
re-import the disease.
8. Reference the right project for examples
PSXRecomp v4 is a sibling project to:
- N64Recomp (RT64 team) — proven static recompilation model for N64
- SuperMarioWorldRecomp (
F:/Projects/SuperMarioWorldRecomp/) — sibling SNES recomp - SuperMarioWorldRecomp-oracle (
F:/Projects/SuperMarioWorldRecomp-oracle/) - NESRecomp — referenced in v3's debug_server.c comments
When you need to know "how does a recomp project handle X?", read those
projects. Do not look at v1 (F:/Projects/psxrecomp/) or v2
(F:/Projects/psxrecomp-v2/) or v3 (F:/Projects/psxrecomp-projects-v3/)
for architectural guidance. They are reference for what failed, not
what worked.
9. Memory and prior session context
Auto-memory continues to work across sessions. Existing v3-era memories about printf rules, no-stubs, BIOS-first, DuckStation oracle, etc. all still apply. New v4-specific memories should be tagged so future sessions can tell them apart from v3 memories. The most important new memory is: "v3 failed because it was an interpreter+HLE emulator masquerading as a recompiler. v4 fixes this by ACTUALLY recompiling the BIOS."
10. No speculative progress
If a step involves:
- indirect jumps
- relocation
- hardware interaction
You MUST produce:
- manifest
- proof artifact
Code without proof is invalid.
11. First milestone is absolute
Before any Phase 2 work:
- docs/internal/FIRST_MILESTONE.md must be complete
- boot_slice must compile
- all instructions must be supported
No exceptions.
12. Relocation is mandatory before full BIOS
Do NOT attempt full BIOS recompilation until:
- BOOT_RELOCATION_PLAN.md is implemented
- address_aliases.json exists
- duplicate code is impossible
13. No large-step execution
You may NOT:
- "recompile the full BIOS"
- "walk the entire ROM"
Until:
- function discovery pipeline exists
- manifest output is verified
14. Unknown is acceptable. Guessing is not.
If something is unknown:
→ STOP
→ produce artifact showing unknown
Do NOT guess behavior.
15. Broken tooling is never acceptable. Fix it when identified.
If a tool, command, or verification mechanism fails or returns unexpected results:
→ Fix the tool, immediately, the moment you identify the breakage. Diagnose why it failed and repair it before continuing the investigation that surfaced it. → Do NOT route around it with indirect evidence. → Do NOT infer correctness from two broken implementations agreeing. → Do NOT log the breakage as a "caveat to live with" or carry it forward in handoffs as a known limitation. A known-broken tool is a debt that compounds: every later session pays interest in the form of reconstructed-from-fragments evidence and shaky conclusions.
"The screenshot command returns black" is not a reason to skip visual verification. It is a reason to fix the screenshot command.
"Both the native runtime and interpreter show the same wrong value" does not make the value correct. It means both have the same bug.
"Beetle's fntrace caller_pc field is always 0, so we'll lean on ra chains" is not an acceptable workaround. It is a reason to fix the fntrace hook before the next investigation pass.
If you cannot fix the tool, ask the user what they observe. Never declare a result "correct" without direct verification against the oracle.
16. Two independent processes, identical debug harness
v4 runs two processes for cross-checking, NEVER one process with both backends in it:
psx-runtime.exe— recompiled BIOS only. SDL window, keyboard input, TCP debug server on port 4370.psx-beetle.exe— Beetle PSX (mednafen-psx libretro core) only. SDL window, keyboard input, TCP debug server on port 4380.
Both binaries expose the same JSON wire protocol for debug
commands — read_ram, press, set_input, clear_input,
pad_status, wtrace_*, fntrace_*, screenshot, ping, etc.
This means a tool written against psx-runtime works unchanged against
psx-beetle just by switching ports. Implementations differ (psx-beetle
uses libretro hooks; psx-runtime uses recomp-emitted instrumentation),
but the protocol is identical.
Why two processes, not one: the embedded-oracle approach
(psx-beetleoracle.exe, retired 2026-05-05) shared input across both
backends in lockstep. They desynced constantly — once their internal
state diverged, the same keypress drove them to different screens, and
"compare on the same press" became unreliable. Two independent
processes is the only setup where each backend can be navigated to its
own state and queried on its own timeline. Cross-process comparison
is done by querying both ports from a tool, NOT by sharing memory.
# Build beetle-psx static lib (one-time, or after modifying beetle-psx/ source)
cd beetle-psx && make platform=mingw_x86_64 STATIC_LINKING=1 HAVE_LIGHTREC=0 -j8
cp mednafen_psx_libretro.dll libmednafen_psx.a && cd ..
# Build both binaries
PATH=/c/msys64/mingw64/bin:$PATH
cd runtime/build && cmake --build . --target psx-runtime psx-beetle && cd ../..
# Run independently. Either can run alone; both can run together.
taskkill //F //IM psx-runtime.exe 2>/dev/null
taskkill //F //IM psx-beetle.exe 2>/dev/null
start "" "./runtime/build/psx-runtime.exe" "./bios/SCPH1001.BIN"
start "" "./runtime/build/psx-beetle.exe" "./bios/SCPH1001.BIN"
Key files:
beetle-psx/— cloned beetle-psx-libretro repobeetle-psx/libmednafen_psx.a— static library used by psx-beetleruntime/src/main.cpp+runtime/src/debug_server.c— psx-runtimeruntime/src/beetle_main.cpp+runtime/src/beetle_debug_server.cruntime/src/beetle_libretro.cpp— psx-beetle
Where Beetle has gaps, build new tooling. Do not fall back to DuckStation. Do not guess. Build the diagnostic tool that gives you the visibility you need.
17. Phase 5 gate — fix hardware stubs before loading a game
docs/internal/STUBS_TO_FIX.md lists every known stub in the runtime. Before any
Phase 5 work (loading Tomba or any game EXE), every stub marked
"Phase 5+" in that file must be implemented and oracle-verified:
- S3 — MDEC decoder (FMV playback)
- S4 — SPU audio synthesis (sound output)
- S5 — DMA channels 0/1/3/4 (MDEC, CDROM, SPU data pipes)
These cannot be tested until disc data flows, but they cannot be skipped either. The first task of Phase 5 is to implement them, not to load the game and see what breaks. Loading the game with known stubs is how v3 ended up with 1808 lines of shims.
18. Self-modifying / install-at-runtime RAM is interpreted, not HLE'd
The PSX BIOS dynamically writes 4-instruction dispatch stubs into kernel RAM (e.g. RAM 0xCF0 for the SIO data-byte handler) and then transfers control to those addresses. The static recompiler CANNOT see those instructions, because they don't exist at compile time — only the program's intent to install them does.
The correct answer is to interpret, not to HLE. A small MIPS
interpreter in the runtime tracks writes into the kernel-RAM code region,
marks affected pages "dirty", and runs any psx_dispatch whose target
falls in a dirty page through the interpreter. The interpreter executes
the program's own instructions on the CPU register state. After the basic
block, control returns to static-recompiled C.
This is not HLE. HLE means "the program would have produced result X, so we synthesize X ourselves and skip the program's code." This rule is the opposite: we run the program's code, exactly as the BIOS author wrote it. The only difference from a pure static recompile is the source of the instructions (RAM-written-at-runtime vs ROM-at-compile-time).
This rule does NOT relax Rule 0. The interpreter is not a fallback for code the recompiler failed to translate. If a function exists in ROM at recompile time, it MUST be statically recompiled. The interpreter only runs against PCs in pages that have been written to since boot — i.e., code that was put there at runtime by the program.
Mature static-recompilation projects (N64Recomp, mednafen-PSX's dynarec) all handle install-at-runtime code this way. PSXRecomp v4 follows suit.
Implementation lives in runtime/src/dirty_ram_interp.c (or similar). It
is intentionally small (~300 LOC), modular, and isolated. It does NOT
expand into a general-purpose CPU emulator.