psxrecomp/docs/PROVENANCE.md

Where runtime code and its facts come from

This note is for anyone who writes or reviews runtime code (runtime/src, runtime/include). It explains which outside sources we use and how, and lists the places that still need work. Issue #443 tracks the series of changes that removes the remaining passages.

The rules

1. Hardware facts are cited to documentation. When a comment states how the PlayStation behaves (a register bit, a table, a timing, a quirk), it names PSX-SPX and the page and section where the fact is written. PSX-SPX is published at https://psx-spx.consoledev.net/. A page is cited by its name in the address, for example graphicsprocessingunitgpu for https://psx-spx.consoledev.net/graphicsprocessingunitgpu/, followed by the section heading in quotes.
2. Emulators are black-box references. We run Beetle PSX, DuckStation, Mednafen or PCSX-Redux and compare what they output with what we output. That is how the oracle tools (psx-beetle, the trace and diff commands) are used, and comments may say "the Beetle reference gives the same result".
3. We do not copy from emulator source. Do not copy code, tables, constants, identifiers or the structure of a routine from an emulator's source, and do not quote emulator source in a comment. Their licences (GPL for Beetle, Mednafen and PCSX-Redux, CC BY-NC-ND for DuckStation) differ from this project's, and CONTRIBUTING.md already rules out copying from incompatible licences.
4. When documentation is silent, measure. If PSX-SPX does not state a fact, write a small test program, run it on hardware or on the references, and record what it shows. Say in the comment that the value was measured and where the measurement lives.
5. When PSX-SPX and the code disagree, say so. Write both in the comment and leave the behaviour as it is. Changing it is a separate change with its own evidence.

What the first change of the series did

It changed comments and documentation only; no code changed.

• Comments that named an emulator's source file, function or line as the authority for a hardware fact now cite PSX-SPX, where PSX-SPX states the fact. Each new citation was checked against the PSX-SPX text.
• Two comments quoted emulator source: the I-cache store rule in psx_icache.c and the interrupt line rule in interrupts.c. The quotes are removed. The comments now describe the behaviour and cite PSX-SPX.
• Where PSX-SPX says something different from the code, the comment now says so (GP0 commands 03h and FFh in gpu.c, the I-cache tag value in psx_icache.c).

What is still to do

These passages say that code follows an emulator's source, or they name a source file, function or line. Rewording would hide that, so they stay as they are until the code itself is replaced. The order is the one agreed on #443.

Change	Files	What the comments say today
2. spu	spu.c, spu_gauss.h	The envelope rate decoder is "ported verbatim" from Beetle's CalcVCDelta; envelope steps follow RunEnvelope; several Beetle spu.cpp line references; the Gaussian table names DuckStation's spu.cpp.
3. cpu/icache and memory/cycles	psx_icache.c, psx_icache.h, psx_instr_cost.h, psx_cyc.h, psx_cycles.c, memory.c, cpu_state.h, dirty_ram_interp.c, main.cpp, docs/internal/CYCLE_MODEL_BEETLE.md	The fetch, load-timing and I-cache models are "transcribed" from Beetle cpu.cpp; MULT/DIV and GTE latencies are transcribed from Beetle; ReadAbsorb/LDWhich names; the MTC0 software-interrupt check is labelled with a PCSX-Redux function name.
4. mdec	mdec.c	The zig-zag table, IDCT matrix load and passes, dequantisation and RGB packing follow Beetle mdec.cpp with line references.
5. cdrom	cdrom.c, cdrom.h	Command latencies (ID, ReadTOC, Pause, Init) and the data-ready notification follow Beetle PS_CDC functions; DuckStation cdrom.cpp handlers are cited for command cancellation and read restarts.

Passages found in areas the agreed series does not cover yet:

Area	Files	What the comments say today
GPU rasteriser	gpu.c	The triangle edge stepping cites DuckStation gpu_sw_rasterizer.inl (makefp_xy, makestep_xy).
GPU display crop	gpu.c	The vertical crop follows DuckStation GetFullDisplayResolution.
Texture sampling	gpu_uv.h, gpu_sw_renderer.c, gpu_gl_renderer.c	The UV offset model and bilinear filter are described as the Beetle / parallel-psx formulation (Calc_UVOffsets_Adjust_Verts).
SPU DMA cost	dma.c	The 48-cycle per-word cost cites Beetle dma.cpp lines.
PGXP cache	gte.cpp	The vertex cache layout names Beetle pgxp_gpu.c and DuckStation cpu_pgxp.cpp.

Comparisons with the references (what the oracle showed, which emulator agrees), the oracle tools themselves, and the DuckStation texture-pack file format (duckstation_texture_pack.*, docs/DUCKSTATION_TEXTURE_FORMAT.md) are not on these lists: they compare outputs or read a published file format, which the rules allow.