mirror of
https://github.com/RetroPortingToolKit/psxrecomp
synced 2026-10-28 02:56:36 -04:00
Shokunin
c981b3a2d7
The cached line-leader rule charges a fetch at every 16-byte line start of the runtime PC. The BIOS emitter tested bits[3:0] of the ROM address instead and assumed every copy window preserves them. OpenBIOS copies its kernel from ROM 0x1FC1E4D4 to RAM 0x500, which shifts them by 4. Each kernel line crossing was charged one instruction early, where it is a hit, and the real crossing went uncharged. 1,152 kernel instruction sites differed from the interpreter. The test now uses the runtime PC that relocate_ra already computes. In the OpenBIOS kernel, 823 misplaced fetch sites go and 773 are added at runtime line starts. Retail profiles are unaffected: SCPH-1001's copy windows are 16-byte aligned and SCPH-101/5552 declare none. The uncached_fetch_charge ctest now also replays every cached OpenBIOS run from a cold cache against the interpreter's fetch path and the Beetle transcription. R4 (OpenBIOS, recompiled kernel, HLE boot) reaches the game entry 6,013 guest cycles later than with the uncached fix alone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Internal dev-logs & design notes
These are the working design documents and burn-down logs the project was built from. They are historical/working notes, not contributor onboarding docs — they capture decisions, phased plans, and deep subsystem investigations in the order they happened, and some sections are superseded by later ones.
If you're new here, start with the top-level README.md,
then docs/ARCHITECTURE.md,
docs/EXECUTION_MODEL.md,
docs/BUILDING.md, and
CONTRIBUTING.md. Come here when you need the why
behind a specific subsystem.
Plans & roadmap
PLAN.md— the original phased build plan (P1–P6).FAITHFUL_TIMING_PLAN.md— the authoritative cycle-accuracy north-star plan and status log.FIRST_MILESTONE.md— the first-boot milestone gate.STUBS_TO_FIX.md— hardware-stub burn-down (pre-game gate).
Cycle accuracy & timing
PRECISE_IRQ_SLICE.md— exact-instruction IRQ delivery.CYCLE_MODEL_BEETLE.md— the Beetle-derived cycle model.ACCURACY_BURNDOWN.md— full accuracy burn-down across all axes (semantics, cycle, IRQ, MMIO, peripherals, determinism).COSIM_ORACLE.md— the first-divergence co-sim oracle.
BIOS / scheduler
HLE_SCHEDULER_CARVEOUT_PLAN.md— the cooperative-thread scheduler HLE carve-out.WEDGE_load4_shell_rootcause.md— a specific boot-shell wedge root-cause writeup.
Renderer / widescreen
GL_RENDERER_HANDOFF.md— OpenGL renderer design.NATIVE_WIDE_PLAN.md— native-wide 16:9 (GTE FOV) plan.BACKDROP_PRELOAD.md— widescreen backdrop preload.
Project conventions & tracking
PRINCIPLES.md— this repo's debugging and enhancement principles (first-divergence, verified-enhancement HLE). Source comments cite it asdocs/internal/PRINCIPLES.md; a "recomp-template PRINCIPLES.md" citation means a different repo's file.ISSUES.md— the historical framework issue log. Live framework work is tracked in Beads (epicbeads-eio.3), not here.DEBUG.md— the debugging playbook behind the TCP debug server; the command reference itself is../TCP_COMMANDS.md.audit_inventory.md— what the codegen/GTE audit pipeline covers and why.
Overlay design & discovery
overlay-recompilation-design.md— the design and rationale for overlay recompilation.overlay-plan.md— the phased overlay implementation plan.overlay-discovery.md— how overlays are discovered on disc and at runtime.overlay-status.md— living what-works / what's-broken status for the overlay capture/compile/cache path.CASE_A_AOT_GAP.md— the Case-A AOT dispatch-miss gap; cited by therationalefields inrecompiler/seeds/*.json.
BIOS / boot hardening
bios-hardening.md— BIOS boot hardening notes.
GTE / CPU investigations
GTE_LM_FIX.md— the GTElmsaturation-flag fix writeup.TOMBA2_EXC_CONSULT_RESPONSE.md— exception -path consultation response for the Tomba 2 bring-up.
Upstream contributor reviews
upstream/ holds per-PR review notes for community contributions, one file per
change, named <contributor>-<pr>-<topic>.md.
upstream/UPSTREAM_2026-08-20.md— the 2026-08-20 upstreaming sweep: which contributed changes are framework-general and which are title configuration.
Overlay cache internals
SLJIT_PERSIST_CACHE.md— removed. It described the persisted shard cache of the sljit Tier-2 backend, which was deleted in5b7e69b4(2026-07-15). For the current model seeruntime/src/overlay_loader.c(per-entry candidate validity),tools/compile_overlays.py(shard formation and the.rangesmanifest), and../COMPILING_OVERLAYS.md.
Removed
CYCLE_TIMING_ARCH.md— removed. Its cycle-timing architecture sketch was superseded and nothing linked to it. For the current model seeFAITHFUL_TIMING_PLAN.md(the authoritative plan),CYCLE_MODEL_BEETLE.md(the Beetle-derived cycle model), andPRECISE_IRQ_SLICE.md(exact-instruction IRQ delivery).