mirror of https://github.com/RetroPortingToolKit/psxrecomp synced 2026-10-26 18:25:35 -04:00

Files

T

Matthew Stanley e6ce5006b4 docs: move root and stale docs into docs/ and docs/internal/

The repository root carried seven markdown files that were not onboarding
material, plus two that had been superseded by the code they described. This
sorts them: reader-facing docs to docs/, working notes to docs/internal/, and
the two superseded ones merged into the docs that replaced them.

Moved to docs/:            WIDESCREEN.md, ENHANCEMENTS.md, TCP_COMMANDS.md
Moved to docs/internal/:   PRINCIPLES.md, ISSUES.md, DEBUG.md, GTE_LM_FIX.md,
                           and from docs/: bios-hardening.md, overlay-status.md,
                           overlay-plan.md, overlay-recompilation-design.md,
                           overlay-discovery.md, TOMBA2_EXC_CONSULT_RESPONSE.md,
                           CASE_A_AOT_GAP.md, audit_inventory.md
Moved to docs/internal/upstream/: UPSTREAM_2026-08-20.md

The root keeps only what belongs there: README.md, CONTRIBUTING.md, LICENSE,
CLAUDE.md, THIRD_PARTY_ATTRIBUTION.md, RELEASE_NOTES.md, the dotfiles and
psxrecomp_cli.py.

MERGES

SPLITGEN_MIGRATION.md folded into docs/BUILDING.md as "Split generated C". Its
migration instructions were stale in a way that mattered: it told every game
repo to hand-edit its CMakeLists and add a file(GLOB ...) over
<serial>_full*.c, but runtime/runtime.cmake now does that itself. GEN_FULL_GLOB
is a multi-value argument of psxrecomp_add_game_runtime(); the loop at
runtime.cmake:1985 makes each pattern absolute against CMAKE_CURRENT_SOURCE_DIR,
expands it with file(GLOB), and concatenates the hits into
GAME_GENERATED_FULL_C. So a title names the pattern and gets however many shards
a regeneration produced. The rewritten section describes that, the two-step
fallback when the globs match nothing (GEN_FULL_FALLBACK, else <serial>_full.c
derived from the dispatch marker by substituting _dispatch.c), and the one
caveat the code actually has: that file(GLOB) is plain, not CONFIGURE_DEPENDS,
so a regeneration which changes the shard COUNT needs a re-configure to be seen.

psxrecomp-toml-readme.md folded into docs/GAME_PROJECT_SETUP.md as "EXE-only
autofill (psxrecomp-toml)", placed after "Disc autofill (probe_disc.py)" and
before "Project Studio" so the two autofill paths sit together. Its documented
flags were checked against the usage text in recompiler/src/main_toml.cpp:28-42
and against the argument parser at :150-165 -- all seven options match with no
drift, so the flag list is reproduced as-is. Added a pointer that probe_disc.py
is preferable when a cue exists, since that tool does the same EXE-header work
plus disc identity and netplay gates.

FUNCTIONAL FIXES

tools/gen_tcp_commands.py wrote to REPO/"TCP_COMMANDS.md". After the move that
path does not exist, so the generator would have created a new stray root file
and --check would have failed against it forever. Retargeted to
REPO/"docs"/"TCP_COMMANDS.md", along with the seven docstring and message
strings that name the path.

Running it surfaced two further problems, both fixed here:

  * The doc was genuinely stale -- pre-existing drift, not introduced by this
    commit (the moved file is byte-identical to origin/master, and no
    debug-server command table is touched here). Four commands registered since
    the last regeneration were missing from the index -- cdrom_timing_dump,
    savestate_status, ws_ui_groups, xprobe_watch -- and scanline had gained a
    backend. Regenerated: 307 -> 311 commands, and the change is confined to the
    AUTOGEN block (the hand-written head and tail are byte-identical to master).
    tools/gen_tcp_commands.py --check now exits 0.
  * DOC.write_text() has no newline argument, so Python translated every newline
    to os.linesep. On Windows that rewrote all 585 lines of the file to CRLF and
    turned a four-line index update into a whole-file diff -- measured: 589 CRLF
    / 0 LF after a run, against 0 CRLF / 585 LF in the repo. Now written through
    an explicit newline="" handle, verified to leave the file at 0 CRLF.

runtime/include/debug_server.h:9 and runtime/src/debug_server.c:8 cited "TCP.md
and DEBUG.md". TCP.md has never existed in this repo under that name; both now
name docs/TCP_COMMANDS.md and docs/internal/DEBUG.md.

LINK AND REFERENCE FIXES

Every inbound reference to a moved file was located by grepping each basename
across the whole tracked tree, not just the markdown. Markdown hrefs in
README.md, CONTRIBUTING.md, docs/ARCHITECTURE.md, docs/COMPILING_OVERLAYS.md,
docs/AOT_OVERLAY_PLAN.md, docs/RELOCATION_MANIFEST_FORMAT.md,
docs/config_schema.md, docs/OVERLAY_XREF.md, docs/TCP_COMMANDS.md and several
docs/internal/ files now point at the new locations; where two files became
siblings under docs/internal/ the path was shortened rather than lengthened
(bios-hardening.md's reference to overlay-discovery.md, for instance).
docs/COMPILING_OVERLAYS.md's "in this folder" phrasing was wrong once two of the
three files it listed moved, so it now names internal/ explicitly.

24 source-comment mentions of ENHANCEMENTS.md sections G1.x across 19 files
(recompiler, runtime, cmake) were retargeted to docs/ENHANCEMENTS.md with the
section numbers untouched. docs/SHADOW_ENHANCEMENTS.md is a DIFFERENT file and
was deliberately excluded.

20 rationale strings citing docs/CASE_A_AOT_GAP.md across the four
recompiler/seeds/*.json files were updated. Done as a byte-level substring
replacement rather than a JSON round-trip: two of those files are stored with
CRLF endings and two with LF, and re-serializing them reformatted 5,700 lines.
The byte-level version changes exactly 20 lines and each file still parses.

References that look similar but point elsewhere were deliberately left alone,
and are worth naming so a future pass does not "fix" them:

  * "recomp-template PRINCIPLES.md" / "NES recomp template PRINCIPLES.md" in
    CLAUDE.md:43, docs/SHADOW_ENHANCEMENTS.md:28,
    docs/internal/HLE_SCHEDULER_CARVEOUT_PLAN.md:5,
    runtime/src/debug_server.c:4934 and tools/parity_diff.py:8 are a different
    repository's file. Only the five that mean this repo's PRINCIPLES.md were
    updated.
  * Every remaining bare ISSUES.md mention is a GAME repo's tracker
    (MegaManX6Recomp 2/7/8/9, TombaRecomp 6), not this repo's.
  * docs/disc-speed.md:4,54,56 and docs/internal/bios-hardening.md:5 name
    overlay-discovery as a BRANCH, not a file, so no path applies.

INDEXES

README.md's "New here?" table gains rows for docs/WIDESCREEN.md,
docs/ENHANCEMENTS.md and docs/TCP_COMMANDS.md. docs/internal/README.md gains
sections indexing all fourteen documents that moved in, plus an "Upstream
contributor reviews" section describing upstream/ and the new sweep file, plus a
"Removed" bullet for CYCLE_TIMING_ARCH.md (deleted in the previous commit)
pointing at FAITHFUL_TIMING_PLAN.md, CYCLE_MODEL_BEETLE.md and
PRECISE_IRQ_SLICE.md -- following the SLJIT_PERSIST_CACHE.md precedent already
in that file.

docs/ENHANCEMENTS.md:7 claimed framework bugs live in "game repos' ISSUES.md
until a framework tracker exists". A framework tracker does exist; it now says
so and names the Beads epic.

VERIFICATION

A link checker was written to scan every tracked *.md for relative links,
resolving each against the tree being scanned. Baseline at origin/master: 129
files, 137 relative links, 3 broken. After both commits: 127 files, 159 relative
links, 3 broken -- the SAME three, all pre-existing and untouched here:

    docs/DATA_SHARDS.md -> INSTANT_LOADS_PARKED.md   (never existed)
    docs/DATA_SHARDS.md -> INSTANT_LOADS_SPIKE2.md   (never existed)
    docs/NETPLAY.md     -> ../lib/recomp-net/README.md  (inside a submodule)

Zero new broken links. The checker's own coverage was checked against a raw grep
for markdown link openers: the 3-link difference is C++ lambdas inside code
blocks, correctly not treated as links.

Also verified: py_compile over all 113 tracked tools/*.py plus psxrecomp_cli.py;
all four seed JSONs still parse; the test-registration guard still reports 123
test files all registered; recompiler/tests/test_coverage_vault.py still passes;
and no file in this commit had its line endings flipped (checked mechanically
across all 50 modified files, after two files were caught and redone).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

2026-09-03 07:39:07 -07:00

4.8 KiB

Raw Blame History

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 as docs/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 (epic beads-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 the rationale fields in recompiler/seeds/*.json.

BIOS / boot hardening

bios-hardening.md — BIOS boot hardening notes.

GTE / CPU investigations

GTE_LM_FIX.md — the GTE lm saturation-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 in 5b7e69b4 (2026-07-15). For the current model see runtime/src/overlay_loader.c (per-entry candidate validity), tools/compile_overlays.py (shard formation and the .ranges manifest), 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 see FAITHFUL_TIMING_PLAN.md (the authoritative plan), CYCLE_MODEL_BEETLE.md (the Beetle-derived cycle model), and PRECISE_IRQ_SLICE.md (exact-instruction IRQ delivery).

4.8 KiB Raw Blame History Unescape Escape