mirror of
https://github.com/RetroPortingToolKit/psxrecomp
synced 2026-10-26 02:11:36 -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>
263 lines
10 KiB
C
263 lines
10 KiB
C
/*
|
|
* debug_server.h -- TCP debug server for PSX recomp v4
|
|
*
|
|
* Non-blocking TCP server on localhost (default port 4370).
|
|
* JSON-over-newline protocol, polled once per vblank.
|
|
* Includes a 36000-frame ring buffer for retroactive state queries.
|
|
*
|
|
* Same public API names as nesrecomp/snesrecomp debug servers
|
|
* so docs/TCP_COMMANDS.md and docs/internal/DEBUG.md documentation is
|
|
* reusable across projects.
|
|
*/
|
|
#ifndef PSXRECOMP_DEBUG_SERVER_H
|
|
#define PSXRECOMP_DEBUG_SERVER_H
|
|
|
|
#include <stdint.h>
|
|
#include <stdio.h>
|
|
|
|
#include "cpu_state.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* ---- Ring buffer frame record ---- */
|
|
|
|
#define FRAME_HISTORY_CAP 36000 /* ~10 min @ 60fps */
|
|
#define MAX_FRAME_DIFFS 32
|
|
#define RAM_SNAPSHOT_REGIONS 4
|
|
#define RAM_SNAPSHOT_SIZE 128
|
|
|
|
typedef struct {
|
|
uint16_t addr;
|
|
uint8_t mine;
|
|
uint8_t theirs;
|
|
} FrameDiffEntry;
|
|
|
|
typedef struct {
|
|
uint32_t frame_number;
|
|
int verify_pass; /* 1=pass, 0=fail, -1=not checked */
|
|
int diff_count;
|
|
|
|
/* ---- MIPS CPU state ---- */
|
|
uint32_t gpr[32];
|
|
uint32_t hi, lo;
|
|
uint32_t cop0_sr;
|
|
uint32_t cop0_cause;
|
|
uint32_t cop0_epc;
|
|
|
|
/* ---- Interrupt state ---- */
|
|
uint32_t i_stat;
|
|
uint32_t i_mask;
|
|
|
|
/* ---- GPU display state ---- */
|
|
uint16_t display_area_x, display_area_y;
|
|
uint16_t display_w, display_h;
|
|
uint8_t display_disabled;
|
|
|
|
/* ---- SIO state ---- */
|
|
uint16_t pad_buttons;
|
|
uint16_t sio_stat;
|
|
uint16_t sio_ctrl;
|
|
|
|
/* ---- Timing ---- */
|
|
uint32_t dispatch_count;
|
|
uint64_t total_dispatches;
|
|
|
|
/* ---- Game-specific (filled by hook) ---- */
|
|
uint8_t game_data[32];
|
|
|
|
/* ---- Last function name ---- */
|
|
char last_func[32];
|
|
|
|
/* ---- Configurable RAM snapshot regions ---- */
|
|
uint32_t snapshot_addr[RAM_SNAPSHOT_REGIONS];
|
|
uint8_t snapshot_data[RAM_SNAPSHOT_REGIONS][RAM_SNAPSHOT_SIZE];
|
|
|
|
/* ---- Divergence diffs (verify mode) ---- */
|
|
FrameDiffEntry diffs[MAX_FRAME_DIFFS];
|
|
} PSXFrameRecord;
|
|
|
|
/* ---- Public API (same names as NES version) ---- */
|
|
|
|
/* Initialize the server. Call once at startup.
|
|
* port=0 uses the default (4370). */
|
|
void debug_server_init(int port);
|
|
|
|
/* Current listener status for heartbeat diagnostics. error is the platform
|
|
* socket error captured by init, or 0 when the listener is active. */
|
|
void debug_server_get_status(int *listening, int *port, int *error);
|
|
|
|
/* Poll for incoming connections and commands. Non-blocking.
|
|
* Call once per vblank. */
|
|
void debug_server_poll(void);
|
|
|
|
/* FMV quiet mode suppresses high-frequency trace rings while MDEC video is
|
|
* active. The TCP command pump stays live; expensive per-dispatch/per-frame
|
|
* recording backs off so debug builds can still play FMVs at speed. */
|
|
void debug_server_set_fmv_quiet(int quiet);
|
|
int debug_server_fmv_quiet(void);
|
|
|
|
/* TCP serve-stall telemetry: cumulative main-thread ms spent inside
|
|
* bounded TCP sends, and clients dropped for exceeding the send budget.
|
|
* Surfaced in the freeze heartbeat / wedge dumps so a TCP-throttled run
|
|
* is never misattributed to a guest-side stall. */
|
|
uint64_t debug_server_get_tcp_stall_ms(void);
|
|
uint32_t debug_server_get_tcp_drops(void);
|
|
|
|
/* Record the current frame's state into the ring buffer.
|
|
* Call after vblank processing. */
|
|
void debug_server_record_frame(void);
|
|
|
|
/* Block while paused, polling TCP + SDL events.
|
|
* Call from vblank callback before frame processing. */
|
|
void debug_server_wait_if_paused(void);
|
|
|
|
/* Graceful shutdown. Call at exit. */
|
|
void debug_server_shutdown(void);
|
|
|
|
/* Check if a TCP client is connected. */
|
|
int debug_server_is_connected(void);
|
|
|
|
/* ---- Tier 1 reverse debugger: write trace ---- */
|
|
|
|
/* Current dispatch target — set by psx_dispatch() before each call.
|
|
* Captured by the write-trace hook for function attribution. */
|
|
extern uint32_t g_debug_current_func_addr;
|
|
|
|
/* Multi-range write-trace check. Called from memory.c write paths.
|
|
* Iterates up to 8 configurable address ranges; records matching
|
|
* writes into the 1M-entry ring buffer with function + frame attribution. */
|
|
void debug_server_trace_write_check(uint32_t phys, uint32_t old_val,
|
|
uint32_t new_val, uint8_t width);
|
|
|
|
/* MMIO write trace — separate ring buffer for 0x1F801xxx writes. */
|
|
void debug_server_trace_mmio_write(uint32_t addr, uint32_t val, uint8_t width);
|
|
|
|
/* Dispatch trace — record every function dispatched. */
|
|
void debug_server_trace_dispatch(uint32_t func_addr);
|
|
void debug_server_trace_dispatch_return(uint32_t func_addr, CPUState *cpu);
|
|
|
|
/* Direct-call entry hook — emitted by the recompiler at the top of every
|
|
* generated function. Release (PSX_NO_DEBUG_TOOLS): inlined in cpu_state.h
|
|
* (stamp g_psx_last_fn_entry). Debug builds use the out-of-line ring path. */
|
|
extern volatile uint32_t g_psx_last_fn_entry;
|
|
#ifndef PSX_NO_DEBUG_TOOLS
|
|
void debug_server_log_call_entry(uint32_t func_addr);
|
|
#endif
|
|
void debug_server_log_call_entry_cpu(uint32_t func_addr, CPUState *cpu);
|
|
/* Addressable stub for overlay CPS callbacks (always out-of-line). */
|
|
void debug_server_log_call_entry_fn(uint32_t func_addr);
|
|
|
|
/* Last store instruction PC — set by the recompiler before every memory
|
|
* store (sb/sh/sw/swl/swr/swc2). Read by SIO/MMIO write handlers to
|
|
* attribute the writing instruction without needing a full call-stack
|
|
* walk. Stale across non-store instructions but every store updates it. */
|
|
extern uint32_t g_debug_last_store_pc;
|
|
|
|
/* SIO write PC tracer ring — records (pc, addr, value, byte_seq) for every
|
|
* write to SIO_DATA / SIO_CTRL / SIO_STAT. Always-on; pulled via TCP cmd
|
|
* "sio_pc_trace". */
|
|
void debug_server_log_sio_write(uint32_t addr, uint32_t value, uint8_t width);
|
|
|
|
/* Targeted generated-PC probe ring used for narrow control-flow diagnostics. */
|
|
void debug_server_log_probe(uint32_t pc, CPUState *cpu);
|
|
|
|
/* RestoreState / exception longjmp tracer. Records nonlocal exception
|
|
* control-flow events that can skip normal function epilogues. */
|
|
void debug_server_log_restore_event(uint32_t kind, uint32_t target_pc, uint32_t jmp_val);
|
|
|
|
/* BIOS ChangeThread / TCB context tracer. Records runtime thread switches
|
|
* and the saved register block belonging to the selected TCB. */
|
|
void debug_server_log_thread_event(uint32_t kind, CPUState *cpu,
|
|
uint32_t current_tcb,
|
|
uint32_t target_tcb,
|
|
uint32_t target_pc);
|
|
void debug_server_log_thread_event_ex(uint32_t kind, CPUState *cpu,
|
|
uint32_t current_tcb,
|
|
uint32_t target_tcb,
|
|
uint32_t target_pc,
|
|
uintptr_t current_fiber,
|
|
uintptr_t target_fiber);
|
|
|
|
/* Dirty-RAM dispatch break. Used by the dynamic-code interpreter to pause
|
|
* immediately when dispatch enters a configured address range, before a hot
|
|
* loop can overwrite the trace rings. */
|
|
int debug_server_dirty_break_maybe_pause(uint32_t target, CPUState *cpu);
|
|
|
|
/* ---- Watchpoint notifications ---- */
|
|
|
|
void debug_server_check_watchpoints(void);
|
|
|
|
/* ---- Input override ---- */
|
|
|
|
/* Returns >= 0 if the debug server wants to override pad input,
|
|
* -1 if no override is active. Value is PS1 16-bit button mask. */
|
|
int debug_server_get_input_override(void);
|
|
|
|
/* Optional analog-stick override set alongside set_input (lx/ly/rx/ry,
|
|
* 0..255, 0x80 = centre). Returns 1 and fills st[lx,ly,rx,ry] when armed,
|
|
* 0 when the injection is buttons-only. */
|
|
int debug_server_get_axis_override(unsigned char st[4]);
|
|
|
|
/* TCP-controlled turbo mode. When enabled the frontend skips presentation and
|
|
* wall-clock pacing at vblank, matching the keyboard TAB turbo path. */
|
|
int debug_server_turbo_enabled(void);
|
|
|
|
/* TCP-controlled turbo mode. When enabled the frontend skips presentation and
|
|
* wall-clock pacing at vblank, matching the keyboard TAB turbo path. */
|
|
int debug_server_turbo_enabled(void);
|
|
|
|
/* ---- Send helpers (for extensions) ---- */
|
|
|
|
/* Set the CPU state pointer for register queries. Call after CPU init. */
|
|
void debug_server_set_cpu(CPUState *cpu);
|
|
|
|
/* Global CPU pointer — set by debug_server_set_cpu(). Available for
|
|
* hardware simulation modules that need to read CPU state (e.g. GPU
|
|
* capturing stack values during A0 uploads). */
|
|
extern CPUState *debug_cpu_ptr;
|
|
|
|
void debug_server_send_line(const char *json);
|
|
void debug_server_send_fmt(const char *fmt, ...);
|
|
|
|
/* ---- Freeze auto-dump accessors ----
|
|
*
|
|
* Called from the freeze_heartbeat thread (NOT from TCP). Each function
|
|
* writes a JSON array `[entry1,entry2,...]` of the newest `max_count`
|
|
* entries from its ring directly to the given FILE*. Caller wraps with
|
|
* the field name (e.g. "wtrace_all":[ ... ]).
|
|
*
|
|
* Thread-safety: best-effort. The heartbeat thread fires these only
|
|
* after detecting a main-thread stall, so concurrent writers are rare,
|
|
* but a wedged loop that still touches RAM could tear an entry near the
|
|
* ring head. Forensic value is in the bulk of older entries which are
|
|
* stable. */
|
|
void debug_server_freeze_dump_wtrace_all_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_wtrace_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_mmio_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_frame_history_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_sio_pc_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_thread_trace_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_restore_trace_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_irq_check_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_first_zero_restore_json(FILE *f);
|
|
void debug_server_freeze_dump_entryint_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_cdrom_state_json(FILE *f);
|
|
void debug_server_freeze_dump_cdrom_trace_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_cdrom_sector_history_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_dma_state_json(FILE *f);
|
|
void debug_server_freeze_dump_dma_trace_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_exception_trace_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_thread_ctx_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_fn_entry_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_dirty_block_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_dirty_insn_json(FILE *f, uint32_t max_count);
|
|
void debug_server_freeze_dump_evcb_json(FILE *f, uint32_t max_count);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* PSXRECOMP_DEBUG_SERVER_H */
|