disasm/_wip/Mario Bros (JU)/OVERVIEW.md

Mario Bros (JU) — Pass 1 Disassembly (Pass 2 substantial)

ROM: _wip/Mario Bros (JU)/Mario Bros (JU).nes (24,592 bytes, iNES). Status: Pass 1 complete (72.2% code); Pass 2 substantial. copilot/prg.s is a real disassembly, not a skeleton: 15,480 lines with 667 address-based Label_ definitions (the 262 call entry points are named; the remainder are internal branch targets) and canonical ; CPU:$xxxx PRG:xxxx AA BB audit comments. It builds byte-identical at the PRG level (cmp reconstructed_prg.bin prg.bin).

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	Vertical
Battery-backed flag	clear
ROM SHA-256	2810051c21132abd8b9b1e1bf741b302ee6c1d4af983e0df7fe50bd05ac0a5c8
PRG SHA-256	699ae2908486fce5a0fffdd051285e1144021f616d9af88eb511f319539acce1

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

Vector	Target	Note
NMI	$C07D	per-frame heartbeat
RESET	$C000	cold start at $C000 — the usual pattern in this repo
IRQ	$C000	redirects to RESET — unused placeholder

copilot/ Contents

File	Purpose
Mario Bros (JU).nes	original ROM image (reference)
prg.bin / header.bin / chr.bin	split image, produced by _tools/splitnes.py
prg.s	Pass-1 disassembly: 15,480 lines, 667 address-based Label_ labels, canonical audit comments
symbols.inc	shared NES hardware constants (PPU/APU/controller)
locals.inc	151 neutral ZpXX zero-page aliases (Pass 2 has not assigned semantic names)
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 not linked: copilot/ keeps the raw header.bin/chr.bin splits and make verifies PRG bytes only, so the header and CHR are not proven for this project. Promotion to the top level adds header.s / chr.s (as e.g. Burger Time (U)), a HEADER/PRG/CHR linker.cfg, and a full-ROM make target.

Build

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

Pass Status

Pass	Status	Description
Pass 0	Superseded	prg.s was a 12-line .incbin of the whole PRG — no disassembly at all
Pass 1	Complete	5,735 instructions / 11,829 code bytes (72.2%) / 4,555 data bytes. Byte accounting exact: 11,800 + 4,584 = 16,384. 937 labels, 937 routine headers
Pass 2	Substantial	262 call entry points named (all jsr/jmp targets resolved from raw $XXXX to labels): 39 semantic names (audio/sound engine, gameplay helpers) + 223 address-based SubCxxxx names for the remainder. 667 Label_Cxxxx internal branch targets remain — these are local control-flow targets (loop starts, branch destinations) within routines, not subroutine entry points, and do not need semantic names for the call graph to be readable. Zero raw $XXXX call operands remain.
Pass 3	Outstanding	Data regions inside the 4,555 unreached bytes need naming

How Pass 1 got to 72.2%

Step	Instructions	Code
Vectors + direct jsr/jmp/branch, official opcodes	1,185	2,392 B (14.6%)
--undocumented (105 extra NMOS opcodes)	1,210	2,445 B (14.9%)
--auto-seed (recovered 61 table-referenced entries)	4,187	8,375 B (51.1%)
--extra-seed 0xC0B6,0xC5A3	5,735	11,829 B (72.2%)

A plain vector trace reaches only 14.6% because almost all of this game sits behind computed dispatch.

The dispatch mechanisms

1. Function-pointer tables, dispatched through the stack. $CD9E is the single choke point:

$CDA1  pla / sta $14        ; pop the table address the caller pushed
$CDA4  pla / sta $15
$CDA7  lda ($14),y / tax    ; read the entry, indexed by A*2
$CDAB  lda ($14),y / sta $15
$CDB1  jmp ($0014)          ; and jump to it

The table pointer arrives via pla, not lda, so it cannot be followed statically from the dispatcher — the pushed value is only known in the caller's frame. This is why INDIRECT: [('0xcdb1', '0x14')] is reported and left unfollowed.

2. A 20-entry table of JSR thunks at $C5A3. Probing it linearly yields twenty valid jsrs followed by rts:

$C5A3  jsr $D56E / jsr $D202 / jsr $D301 / jsr $C5DB / jsr $C66A / jsr $E783 ...

Seeding $C5A3 pulls in all twenty targets at once, which is most of the jump from 51% to 72%.

3. The NMI phase dispatcher at $C0B6, reached only by computed dispatch:

$C0B6  lda $B0 / beq $C0BF
$C0BA  lda $0320 / bne $C0C2
$C0BF  jmp $C149

Seeding $C0B6 recovered 677 bytes that the vector trace could not see.

Tracer fixes required to get there

Two overlapping-decode bugs had to be fixed in _tools/nesdis.py first:

• Control-flow targets must win over fall-through. bne at $C4BA targets $C528, but the fall-through path had decoded $C527 as a 2-byte NOP #$A5 whose operand swallowed $C528. No real assembler branches into the middle of an instruction, so the spanning decode is now dropped in favour of the target. Its bytes fall out as data, so byte accounting is unaffected.
• Branch targets inside a surviving instruction must be pruned. Otherwise emit_code's linear walk consumes those bytes as an operand, the label is referenced but never defined, and the file does not assemble at all — Error: Symbol 'Label_C528' is undefined.

Neither change affects any already-regen-stable project; MUSCLE's make regen was re-checked and still reproduces prg.s byte-for-byte.

Known remaining gaps

• The tracer still reports INVALID: ['0xc5a7'] and three overlaps ($C528, $C5A2, $C5A4). The overlaps are now resolved in favour of the control-flow target, so they are diagnostics rather than defects, but the $C5A2/$C5A4 pair means the alignment between the D4-padding run and the $C5A3 thunk table is not fully settled.
• 4,555 bytes (27.8%) are still data. Reaching more needs the tables that the stack dispatcher at $CD9E reads, which means resolving the pushed addresses in the callers' frames — that is Pass 2/3 work, not more seeding.

Pass 2 so far, and why it is partial

Two mechanical wins came first:

• 478 jsr/jmp operands rewritten from raw $XXXX to labels. The tracer emits call and jump targets as hex, so the call graph was unreadable — the most-called routine appeared as jsr $CCA0 14 times. All 478 sites now name their target, and zero raw hex call operands remain.
• 262 call entry points named: 39 with semantic names (audio/sound engine routines in $F8xx-$F9xx, gameplay helpers like CheckZpB3Return, CheckRangeReturn012, ToggleZpFC_Bit3) + 223 with address-based names (SubCxxxx) for the remainder. All 262 distinct jsr/jmp targets now resolve to labels. (These counts were re-verified against prg.s on 2026-10-19; the earlier "477 / 252 / 90 / 165" did not match the file.)

667 Label_Cxxxx internal branch targets remain, and that is the honest state. These are local control-flow destinations (loop starts, conditional branch targets) within routines — not subroutine entry points. Naming them requires reading ~5,700 instructions across 935 routines to establish what each one does; doing it from the call graph and the NES convention alone would be guesswork, and PROMPTS.md explicitly forbids skipping ahead to guessy rewrites.

The productive next step is not more naming but more reach: the 4,555 unreached bytes are where most of the remaining unnamed routines live, and they are gated behind the stack-pointer dispatch at $CD9E. Resolving the pushed table addresses would enlarge both the code set and the set of names worth assigning.

Next Steps

1. Pass 1 — complete (72.2% code, byte accounting exact).
2. Pass 2 — substantial: all 262 call entry points named; 667 internal branch labels (Label_Cxxxx) remain as local control-flow targets. Filling locals.inc with semantic zero-page aliases is optional at this stage (151 neutral ZpXX aliases are present).
3. Pass 3 — name data tables/structures in the 4,555 unreached bytes; 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.

Still owed: this file was retitled and restatused in the 2026-10-19 doc-drift sweep to match the actual prg.s; the power-on flow analysis the top-level OVERVIEW.mds carry is still to be written here.