BFM-decomp/docs/psyq-sample-idioms.md

PsyQ SDK sample-source notes (P31 T2 seed — grows as the drafting lanes consume it)

What this is. The PsyQ 4.0 dev CD on disk (tools/psyq/…(Track 1).bin) contains Sony's SDK sample C source — the skeletons era programmers (Square included) started from. Extracted in P31 T2 to tools/reference/psyq-sdk/ (gitignored, regenerable — see docs/SETUP.md §5.6 for the exact command + counts). This doc is the committed knowledge: what's there, the toolchain provenance found on the disc, and the style conventions that should inform drafts. It is a SEED — extend it as agents mine specific samples for specific BFM subsystems (R16).

Why it matters for matching (not for the libraries)

The PsyQ code inside BFM is already byte-identical via object linking (LINKED 959, Phases 7–8) — nothing to decompile there. The samples matter for Square's own code that calls PsyQ: byte matching is sensitive to source shape (variable order, loop idiom, temp usage), and Sony's samples are the canonical shapes those call sites were written from. Highest-leverage consumers: main's ~1,034 remaining stubs (boot/CD/GPU/pad — the most sample-like code in the game) and any overlay function anchored on PsyQ calls.

Inventory (extracted 2026-08-14)

• 2,374 files / 231.6 MB from the ISO (7 out-of-track .DA audio files skipped — audio tracks, no code). 400 .c files: 382 under PSX/ (373 in PSX/SAMPLE/), 17 PSSN/, 1 3RDPARTY/.
• PSX/SAMPLE/ groups: CD/ (EARTH, MOVIE, STR3D, TUTO) · GRAPHICS/ · SOUND/ · MODULE/ · ETC/ · MATH/ · CMPLR/ (compiler-behavior demos!) · KANJI/ · PRESS/ · DS/ · SCEA/ · SCEE/ · AUTOPAD/ · DONGLE/.
• Also on the disc: PSX/INCLUDE + PSX/LIB (another copy of headers/libs), DOC/, GNU/ (compiler binaries + SN documentation — no GNU source on the disc), CDGEN/, BETA/.

Toolchain provenance found on the disc (feeds the §31 map's source-version note)

GNU/SNGNUVER.TXT — SN Systems' own build-history for the PSX gcc: lineage 2.7.2.SN32.3.x, current at disc mastering 2.7.2.SN32.3.7.0002 (14.5.97), with a per-build changelog naming the exact files SN patched vs vanilla 2.7.2:

• MIPS.C — temp-file handling fixes (non-codegen)
• CCCP.C — DOS-path/.OBJ-suffix preprocessor fixes (non-codegen)
• SDBOUT.C — debug-output dimensions (non-codegen)
• N64.H — no __main insertion when main() defined (startup, non-codegen for our fns)
• UNROLL.C — "parameterise max. number of insns allowed in an unrolled loop" (CODEGEN-RELEVANT): the one named SN divergence from vanilla 2.7.2 that could move bytes (loop-unrolling limits). If a loop-unroll-shaped residual ever defies the vanilla-2.7.2 unroll.c model, this is the first place to look. (GNU/SNGNUBUG.TXT = known-bugs list, same vintage.)

Everything else in the changelog is plumbing — consistent with 26 phases of byte evidence that our pinned vanilla-shaped cc1 reproduces the game's codegen.

Style conventions (first skim — STR3D/TUTO0.C and peers; refine per-subsystem as mined)

• /* $PSLibId: Run-time Library Release 4.0$ */ header stamps; Shift-JIS comments alongside English.
• File-scope static state over locals-passed-around; globals for buffers with ALL-CAPS #define addresses (#define TEX_ADDR 0x80010000).
• #define-driven feature config (#if defined(...)) rather than runtime flags.
• Init/start/poll function triples for streamed subsystems (init_anim / start_anim / poll_anim) — a shape to expect in BFM's loader/streaming code.
• Old-style parameter lists and int-heavy typing (K&R-adjacent), consistent with the loose-typing wall measured in BFM's engine.

How to consume (the lane hook)

When drafting a PsyQ-call-anchored stub (especially main), grep -ril <PsyQ-fn> over tools/reference/psyq-sdk/PSX/SAMPLE/ and hand the closest sample to the drafter as a style prior. SAMPLE/CMPLR/ is a bonus corpus: Sony's own compiler-behavior demos, useful as §31-map exemplar inputs.