disasm/_wip/Golf (JU)/OVERVIEW.md

Golf (JU)

ROM: _wip/Golf (JU)/Golf (JU).nes (24,592 bytes, iNES). Status: Pass 1 complete, Pass 2 substantial, Pass 3 started — PAUSED. PRG build is byte-identical.

Pass 1 (code/data split) — complete. Reachable code traced from RESET ($C000) and NMI ($C0A6); all 4,063 reachable instructions are explicit source. NMI callbacks ($C5A0=GameplayInputNmiCallback, $C6C8, $CFAA, $DAA2; continuations $CFC3/$D03E/$D08A) and controller/attract paths ($DAA2, $C0C7=InitializeRuntimeState) are in source. All remaining .incbin spans have zero code entry points and are confirmed data.

Pass 2 (label naming) — substantial. Startup/NMI/PPU/controller/course-decode routines named (batches 1–3 per PASS2_PLAN.md). All 112 subroutine-entry Label_ labels renamed to SubC<addr> (108) or semantic names (4: WaitForFramePreservingY, SpriteOffsetForController, SetPpuScrollAndMask, MultiplyABy32); 349 internal branch-target Label_ labels remain intentionally.

Pass 3 (data tables) — started, PAUSED. Conversions completed:

• Interrupt vectors at $FFFA–$FFFF → .word NmiHandler/Reset/IrqLoop
• Course-stream split pointer table at $E6C3/$E6D5 (18 entries) → CourseLayoutPointerLo/CourseLayoutPointerHi
• Bit-mask table $D6F4–$D6FB → BitMaskTable ($80 40 20 10 08 04 02 01)
• PPU write table $FD0A–$FD11 → PpuTableFd0a
• Score adjust table $D988–$D9B0 → D988ScoreAdjustTable
• PPU value table $FF85–$FF9F → FF85PpuValueTable
• Sprite/object tables (sprite_object_tables.inc) and gameplay PPU palette ($E1B8–$E1D7) already emitted as structured source.

Paused: Remaining .incbin spans are largely Iwata's compressed level data ($E6E7–$F905, ~4.6 KB) and opaque lookup tables ($C786–$C84C, $CD85–$CE63, $D304–$D3B6, $D563–$D659, $D823–$D8EC, $DC59–$DD77, $E1D8–$E281, $E3DE–$E3FB, $E588–$E6AF, $FBBF–$FC23). Without runtime tracing / a code/data log to confirm consumers and structure, converting these risks guessy rewrites. Per repo convention, they remain as .incbin with address comments.

Remaining .incbin spans ($C71E–$C720, $C786–$C84C, $CD85–$CE63, $D304–$D3B6, $D563–$D659, $D823–$D8EC, $DC59–$DD77, $E1D8–$E281, $E3DE–$E3FB, $E588–$E6AF, $E6E7–$F905, $FBBF–$FC23) remain as data per the no-guessy-rewrites convention; convert only when a consumer is identified.

Next Pass 3 candidates: when runtime tracing tools are available, remaining structured tables (course-stream data, opaque lookup spans) can be converted where structure is confirmed.

Promotion: not yet — _wip tier (PRG-only compare). Promotion requires full-ROM build (header.s/chr.s + vectors) and root inventory entry.

ROM Facts

Property	Value
Mapper	0 (NROM) — from the iNES header
PRG	16 KB (header claims map at CPU $C000–$FFFF)
CHR	8 KB
Mirroring	Horizontal
Battery-backed flag	clear
ROM SHA-256	70986ed4fb441199a9ff50c7b5c6388d9f7a17c29990d1b5f7214572ae0a4bc6
PRG SHA-256	9f729074cd7c74340f325460173519427b1180f5101f8dc37da7b1c2b9b604d5

Interrupt Vectors (taken from PRG $3FFA–$3FFF)

Vector	Target	Note
NMI	$C0A6	per-frame heartbeat
RESET	$C000	cold start at $C000 — the usual pattern in this repo
IRQ	$C0C4	target $C0C4 — verify during Pass 1

copilot/ Contents

File	Purpose
Golf (JU).nes	original ROM image (reference)
prg.bin / header.bin / chr.bin	split image, produced by _tools/splitnes.py
prg.s	Pass-1 skeleton: .incbin "prg.bin", $0000, $4000 (whole PRG)
symbols.inc	shared NES hardware constants (PPU/APU/controller, from the skeleton)
locals.inc	project-local zero-page aliases — empty for now (filled in Pass 2)
linker.cfg	PRG at $C000, 16 KB, fill = yes
Makefile	links reconstructed_prg.bin and cmps it against prg.bin
reconstructed_prg.bin	build output from the last verified build

Header/CHR are reproduced verbatim from header.bin/chr.bin (not linked): make verifies PRG bytes only at this stage, which is exactly what a skeleton proves. When this project is promoted to a full disassembly, header.s / chr.s (as e.g. Burger Time (U)) and a full-ROM make target get added.

Build

cd "_wip/Golf (JU)/copilot"
make        # → cmp reconstructed_prg.bin prg.bin → "BYTE-IDENTICAL"

Next Steps (per PROMPTS.md)

1. Pass 1 — replace the blanket .incbin with classified code/data: trace reachability from RESET ($C000) and NMI ($C0A6), emit per-instruction ; PRG:$xxxx AA BB annotations, keep unreached bytes as explicit .byte blocks.
2. Pass 2 — replace Label_/Sub_ names with semantic routine names; fill locals.inc.
3. Pass 3 — name data tables/structures; release provisional flags.
4. Promotion — move to a top-level <name>/copilot/ folder, add full-ROM build (header.s + chr.s + vectors), and write the power-on flow OVERVIEW.md in the established style; then it joins the root index's numbered inventory.