mirror of
https://github.com/RetroPortingToolKit/psxrecomp
synced 2026-10-25 18:05:12 -04:00
Matthew Stanley
e6ce5006b4
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>
185 lines
5.8 KiB
Markdown
185 lines
5.8 KiB
Markdown
# DEBUG LOOP (EXECUTION CONTRACT)
|
|
|
|
Follow EXACTLY. No deviation.
|
|
|
|
---
|
|
|
|
# RULE 0 — TOOL VALIDATION (FIRST USE)
|
|
|
|
On the FIRST use of ANY tool:
|
|
|
|
You MUST validate what it is doing and its output
|
|
|
|
Required:
|
|
1. Cross-check against another source
|
|
2. Verify structure AND content
|
|
3. Confirm assumptions
|
|
|
|
Never:
|
|
- Trust output blindly
|
|
- Assume correctness
|
|
|
|
If not validated:
|
|
-> ALL reasoning is INVALID
|
|
|
|
---
|
|
|
|
# LOOP
|
|
|
|
0. Tool validation (first use only)
|
|
1. Sync state (NOT frame number)
|
|
2. Dump full state (native + oracle) via TCP debug server
|
|
3. Diff bytes
|
|
4. Find FIRST divergence
|
|
5. Trace writer (function + instruction + call path)
|
|
6. Classify (codegen / runner / timing / config)
|
|
7. Fix the tool (never generated output)
|
|
|
|
If ANY step is skipped:
|
|
-> STOP and restart
|
|
|
|
All inspection must use TCP (Phase 2+).
|
|
Before TCP exists (Phase 1), use structured JSON artifacts only.
|
|
|
|
---
|
|
|
|
# PSX-SPECIFIC INSPECTION TARGETS
|
|
|
|
When comparing native vs DuckStation oracle:
|
|
|
|
- CPU registers (32 GPRs, HI, LO, PC, COP0)
|
|
- RAM contents at known kernel addresses (PCB, TCB, EvCB tables)
|
|
- VRAM contents (byte-for-byte)
|
|
- MMIO read/write sequences
|
|
- Timer counter values
|
|
- Interrupt fire ordering
|
|
- DMA transfer sequences
|
|
- GPU command streams
|
|
|
|
---
|
|
|
|
# CLASSIFICATION
|
|
|
|
codegen:
|
|
- Wrong C emitted by strict_translator
|
|
- Fix: recompiler/src/strict_translator.cpp
|
|
|
|
runner:
|
|
- Wrong hardware simulation (MMIO, DMA, IRQ, GPU, timers)
|
|
- Fix: runtime/src/*.c
|
|
|
|
timing:
|
|
- Events fire at wrong cycle / wrong order
|
|
- Fix: runtime timing logic
|
|
|
|
config:
|
|
- Missing function seed, wrong address alias
|
|
- Fix: seed files, address_aliases.json
|
|
|
|
discovery:
|
|
- Function not found, dispatch miss
|
|
- Fix: function finder pipeline
|
|
|
|
NEVER fix generated output. Fix the tool that produced it.
|
|
|
|
---
|
|
|
|
# END-TO-END COMPLETION RULE (NON-NEGOTIABLE)
|
|
|
|
When debugging boot/runtime flows, **never accept an internal milestone as success
|
|
unless the full user-visible loop closes.**
|
|
|
|
Examples of FALSE success:
|
|
- "counter reached 0" is NOT success if the shell still retries
|
|
- "IRQ fired" is NOT success if the waiting code still loops
|
|
- "callback returned" is NOT success if the owning state machine does not advance
|
|
- "data structure written" is NOT success if the consumer still rejects it
|
|
- "handler installed" is NOT success if the VBlank counter never increments
|
|
- "chain head populated" is NOT success if pixels don't reach the screen
|
|
|
|
Required method:
|
|
1. Define full end-to-end success criteria FIRST — what does the USER see when it works?
|
|
2. Trace producer AND consumer — follow the data from origin to final consumer
|
|
3. Find the first semantic divergence — where does the consumer's view differ from expected?
|
|
4. Fix subsystem behaviour — correct the root cause in the producing subsystem
|
|
5. Rerun the full flow — verify the entire loop closes, not just the intermediate step
|
|
6. Reject any patch that only changes intermediate state without closing the loop
|
|
|
|
## Stale Hypothesis Rule
|
|
|
|
If a handoff contains stale claims contradicted by new logs, **update the problem
|
|
statement before changing code**. Never continue debugging from an invalidated
|
|
hypothesis. If there are contradictions or stale data, STOP and inform the user
|
|
immediately before proceeding.
|
|
|
|
(Seen in the 2026-04-13 VBlank stall: the handoff said "handler is never installed"
|
|
but live TCP inspection proved the handler WAS installed at `0x800DFEE0` — the real
|
|
gap was one level up, in the kernel root-counter chain head at `*(0xA000E014)`. The
|
|
entire static-analysis cascade below that stale claim was wasted effort.)
|
|
|
|
---
|
|
|
|
# TOOLING RULE (NON-NEGOTIABLE)
|
|
|
|
If at ANY point during debugging the TCP debug server cannot answer a question
|
|
you need answered — **STOP IMMEDIATELY**. Do not:
|
|
|
|
- Guess the answer
|
|
- Work around it with printf/fprintf
|
|
- Proceed with partial information
|
|
- Make assumptions based on code reading alone
|
|
|
|
Instead:
|
|
|
|
1. **STOP** all current work
|
|
2. **INFORM the user** exactly what data is missing and what command is needed
|
|
3. **ASK the user** how to proceed (build the command? change approach?)
|
|
4. **BUILD the tooling** if approved, then resume
|
|
|
|
Adding a new command is cheap — the pattern is one handler in `runtime/src/debug_server.c`
|
|
(native) and a matching handler in `duckstation/src/core/psxrecomp_debug_server.cpp`
|
|
(DuckStation oracle, then regenerate `tools/duckstation/psxrecomp_oracle.patch`).
|
|
See [`../TCP_COMMANDS.md`](../TCP_COMMANDS.md) for the protocol.
|
|
|
|
A wrong answer from missing tooling costs MORE than the time to build the tool.
|
|
Every workaround becomes technical debt that hides the real bug longer.
|
|
|
|
---
|
|
|
|
# TOOL LIFECYCLE RULE (NON-NEGOTIABLE)
|
|
|
|
Claude builds, launches, and closes ALL tools. The user NEVER gatekeeps this.
|
|
|
|
- Build native: `(cd runtime && cmake --build build)` (with `PATH=/c/msys64/mingw64/bin:$PATH`)
|
|
- Build DuckStation oracle: `bash tools/duckstation/build.sh`
|
|
- Launch native: `./runtime/build/psx-runtime.exe &`
|
|
- Launch DuckStation oracle: `./duckstation/build/bin/duckstation-qt.exe -bios -nogui -fastboot &`
|
|
- Close / restart: `taskkill //F //IM psx-runtime.exe` or `//IM duckstation-qt.exe`
|
|
|
|
Do NOT ask the user to launch, close, or restart anything.
|
|
Do NOT tell the user what commands to run — just run them.
|
|
|
|
### Kill-and-rebuild procedure (Windows)
|
|
|
|
The exe file lock can persist after process exit (AV, delayed handle release).
|
|
Always use this sequence:
|
|
|
|
```bash
|
|
# 1. Kill any running instance
|
|
taskkill //F //IM psx-runtime.exe 2>/dev/null
|
|
taskkill //F //IM duckstation-qt.exe 2>/dev/null
|
|
|
|
# 2. If linker still fails with "Permission denied", delete the exe first
|
|
rm -f runtime/build/psx-runtime.exe
|
|
|
|
# 3. Rebuild
|
|
PATH=/c/msys64/mingw64/bin:$PATH
|
|
(cd runtime && cmake --build build -j)
|
|
|
|
# 4. Relaunch (one instance at a time — memory policy)
|
|
./runtime/build/psx-runtime.exe &
|
|
```
|
|
|
|
Never use `C:/msys64/msys2_shell.cmd` — it spawns orphan processes. Use `bash` with
|
|
`PATH=/c/msys64/mingw64/bin:$PATH` inline.
|