tmerritt
71ada15de0
Pass 3 named the 10 data regions in prg.s, then the project was promoted
out of _wip/ so `make` now proves header + PRG + CHR against the original
ROM instead of only the PRG bank.
Data regions named:
LevelPtrTable $C000-$C03B (60 B) level header data
ObjectPtrTable $C03C-$C043 (8 B) 4 pointer pairs
LevelDataPtrTable $C044-$C79D (1882 B) level data pointers
SpriteInitPtrTable labelled at $C4B0 see residue note
UnreachedCode_D650 $D650-$D696 (71 B) unreached code
UnreachedCode_E144 $E144-$E165 (34 B) unreached code
MusicDataTable $F55B-$FA47 (1261 B) music/sound data
APUDataTable $FAE6-$FB74 (143 B) APU pulse/noise tables
SfxDataTable $FE59-$FFEF (407 B) sound-effect data
VectorTable $FFF6-$FFFF (10 B) padding + NMI/RESET/IRQ
Promotion (per the AGENTS.md checklist):
- git mv "_wip/Donkey Kong (JU)" "Donkey Kong (JU)"
- add copilot/rom.nes -> ../Donkey Kong (JU).nes symlink
- add header.s / chr.s (one-line .incbin of header.bin / chr.bin)
- linker.cfg gains HEADER ($0000/16 B) and CHR ($0000/8 KB)
- Makefile switched from `cmp reconstructed_prg.bin prg.bin` to
`cmp reconstructed.nes rom.nes`
- no _tools path change (this Makefile never referenced _tools/)
and no `make regen` pipeline exists for it
Doc corrections:
- project OVERVIEW.md said Mirroring Vertical; header byte 6 = $00
means Horizontal (the root index was right) — fixed
- root OVERVIEW.md: row 18 now BYTE-IDENTICAL, tier paragraph and
summary table refreshed (they had drifted around the Lunar Pool and
Urban Champion promotions), new per-project detail entry
- counts corrected to 19 top-level / 17 _wip in OVERVIEW.md,
TODO.md and AGENTS.md
Residue recorded rather than guessed:
- Pass 2 is partial: 919 Label_ definitions remain (214 semantic
labels applied); noted in TODO.md so nobody reads the promotion as
full semantic naming
- SpriteInitPtrTable's label sits at $C4B0: the routine at $C807 reads
$C4A7,x/$C4A8,x, but that table starts mid-row and a label there
would split the canonical 16-byte audit-comment line
Verification:
make clean && make -> "Byte-identical ROM verified."
verify_pass1.py -> 19/19 top-level build, Donkey Kong (JU) OK
(6014 instr / 12505 B), all comments canonical
Doc-drift sweep: build tiers, mirroring, and stale status tails
Reconciled the docs against verified reality after the Lunar Pool / Urban
Champion / Donkey Kong (JU) promotions and the 2026-10-19 audit-comment
standardization. No source behaviour changed except the two build fixes below.
Build tier (whole-ROM vs PRG-only)
- AGENTS.md: the 17 `_wip/` projects are real disassemblies at the PRG-build
tier, not "skeletons"; header.s/chr.s/rom.nes are promotion additions;
verify_pass1.py covers the top-level projects.
- Root OVERVIEW.md: `_wip` prose, audit-comment narrative and summary table
refreshed (37.5% figure, SEEDED vs OK wording, re-trace false alarm).
- Promoted projects whose build blocks still claimed `make` emits
`reconstructed_prg.bin` compared to `prg.bin` (Balloon Fight, Baseball,
CIRCUS, Clu Clu Land, Excitebike, NES PowerPad, Pac-Man (USA), Tennis):
now describe the whole-ROM `reconstructed.nes` vs `rom.nes`.
- Lunar Pool / Urban Champion / CIRCUS also had stale `cd "_wip/..."`
build paths and "Promotion" items; retargeted to their top-level folders.
Mirroring (header byte 6 bit 0: 0 = Horizontal, 1 = Vertical)
- Corrected DK Jr. prose "horizontal mirroring (flag 6 = $01)" -> vertical,
and both `_wip/Pac-Man` variant notes "Both use vertical mirroring" ->
horizontal (both are byte-6 = $00).
- Re-audited every project OVERVIEW: 0 rows and 0 prose claims now disagree.
Stale status tails
- Retitled/restatused the `_wip` OVERVIEWs to their real `prg.s` (Golf,
Ice Climber (U), Lode Runner, Millipede, Pac-Man Tengen, Pac-Man (U),
Popeye 0/1, Raid, Raid a2, Hogan's Alley, Mario Bros); Golf's
skeleton-era contents rows and Next Steps corrected.
- Dropped the skeleton-era "## Next Steps (per `PROMPTS.md`)" heading and
the "(from the skeleton)" wording across all project OVERVIEWs.
- Rewrote Lunar Pool / Urban Champion Next Steps (both already Pass 1-3
complete and promoted; their tails still described pending Pass 2 and
promotion); fixed root row 13 (Wild Gunman) and row 20 (Duck Hunt).
Also lands two code fixes carried with this sweep:
- `_wip/Hogan's Alley (JU)`: $E9F1-$E9FD and $EA13-$EA14 reclassified as
data with canonical audit comments (the seeded build had decoded a data
table base as code, breaking the build since 2ae09f7). `make` ->
BYTE-IDENTICAL again; reconstructed_prg.bin/.lbl refreshed.
- `_wip/Pyramid (U)`: `Label_D72E` -> `NMI:` (byte-identical).
Verification:
make (Hogan's Alley, Pyramid) -> BYTE-IDENTICAL, BYTE-IDENTICAL
_tools/verify_pass1.py -> 19/19 build, all canonical,
"No truncated or unfaithful Pass 1"
mirroring audit (rows + prose) -> 0 mismatches
Donkey Kong (JU): complete Pass 2 — all 919 Label_ definitions named
The last non-zero Label_ residue in the repo is now gone. Every one of the
919 address-derived definitions in copilot/prg.s is replaced:
* 319 routine entry points (jsr/jmp targets):
- 102 named from observed behaviour (LoadSpriteInitPointerToZp00 $C807,
CopyVramDataToBuffer $CBDF, CheckSpriteListCollision $D8AD,
UpdateRandomSeed $F4ED, ReadControllers $F50E, UpdateSoundEngine $FA48, ...)
- 217 left as SubC<addr> — honest residue where the body is too
context-dependent to name without guessing (Golf: 108, Mario Bros: 223)
- the 77 already-named entries untouched
* 600 internal branch targets named <Routine>_Block / <Routine>_Block_n in
address order within their owning routine (DK Jr./Balloon Fight convention).
Ownership is control-flow containment, so a loop that physically precedes
its own entry lands correctly (FlushPpuBuffer_Block $F1EC under $F228).
* Two proposal collisions disambiguated by indexing zero-page slot:
UpdateObjectListZp5D/DispatchObjectStateZp5E ($DA16/$DA4C) vs
UpdateObjectListZpAE/DispatchObjectStateZpAF ($E1E9/$E250).
jsr/jmp operands stay numeric (Wild Gunman style); only branch operands are
symbolic. Applied with _tools/pass2.py apply (919 defs + 2,622 refs rewritten,
comments re-aligned); the ROM still rebuilds byte-identically and
verify_pass1.py reports 19/19 canonical with no truncated split.
Docs synced: project OVERVIEW.md gains a Pass 2 Details section, root
OVERVIEW.md rows + conventions, TODO.md section 4 closed. dk_full_map.tsv now
records the complete applied map (its zp rows remain unapplied proposals).
_wip status correction: five false "Pass 2 complete" claims + map audit
The `_wip` tier's "Pass 2 complete" headers counted their draft maps' rows, not
the names actually present in `prg.s`, and described the count of *neutral*
`ZpXX` slots in `locals.inc` as "zero-page semantic aliases". Verified against
the sources and corrected in the root inventory rows, the project OVERVIEWs and
TODO:
project named/total Label_ left drafted map
Pinball (JU) 180 / 681 501 210 rows, 179 applied
Ice Climber (JE) 76 / 973 897 255 rows, 76 applied
Donkey Kong Jr. Math 64 / 1035 971 243 rows, 62 applied
Duck Hunt (JUE) 31 / 472 441 272 rows, 31 applied
Ice Climber (U) 2 / 973 971 none - Pass 2 not started
No `_wip` project is Pass 2 complete. Ice Climber (U) was the worst case: the
2026-10-19 sweep itself restated it "Pass 2 complete" while describing its 971
`Label_` definitions in the same paragraph - a copy-paste from (JE); (U) has no
map file at all.
Drafted maps audited row by row against the committed split: they are not
applicable. 100/243 (DK Jr. Math), 96/255 (Ice Climber (JE)) and 17/210
(Pinball) rows point at addresses that are not instruction boundaries - they
were built against an older code/data split - while most of the rest are
unlabelled boundaries that no operand references, or (Duck Hunt) competing
candidate names for one label (`Label_C2BF` alone carries 205). Rows that are
both insertable and corroborated by control flow: 0 in every map. Recorded as
stale and kept for provenance; Pass 2 here needs a fresh map derived from the
committed split.
Also corrected while verifying:
- Mario Bros entry counts (docs said 252 / 90 + 165 / 477 sites / 156 neutral
slots; the file holds 262 distinct `jsr`/`jmp` targets = 39 semantic + 223
`SubC<addr>`, 478 sites, 151 slots).
- root `_wip` prose line/label ranges (4,482-17,180 lines, 192-971 `Label_`,
11,126 total) and the Ice Climber code figure (74.6% / 6,112 instr, not
74.7% / 6,113).
- TODO §4 re-scoped to the promoted tier, with the `_wip` residue table added.
Verification: `make` across all 17 `_wip` projects -> BYTE-IDENTICAL (17/17);
`_tools/verify_pass1.py` -> 19/19 build, all canonical, "No truncated or
unfaithful Pass 1 found". No source bytes changed.
Balloon Fight (JU): apply locals.inc/symbols.inc names to prg.s (Pass 3)
Substitutes symbol names for 922 numeric operands: 125 hardware registers
(symbols.inc) and 797 of 813 zero-page/RAM operands (locals.inc). The 15
multi-alias addresses were resolved per routine; 16 operands stay numeric
because $13 is used there as a plain high-byte scratch beside Temp12 and
none of its three aliases fits.
- _tools/apply_symbols.py: the substitution tool (dry run by default;
--sites supplies per-routine choices for multi-alias addresses, --report
lists the residue). Only the operand token is rewritten, so the
`; CPU:$.... PRG:.... XX XX` audit comments survive byte for byte.
- prg.s: operand tokens only. make prints "Byte-identical ROM verified."
- OVERVIEW.md (project): instruction quotes now match prg.s, new
alias-reuse table, and section 10 rewritten from the stale "497 Label_"
prose to the real naming state and the 16-site residue.
- OVERVIEW.md (root), TODO.md, AGENTS.md: status, counts, tool list.
verify_pass1.py: 19/19 OK, all audit comments canonical.
Bomberman (U): apply locals.inc/symbols.inc names to prg.s (Pass 3)
Substitutes 362 zero-page operands in copilot/prg.s with the names already
declared in copilot/locals.inc: 354 from single-name addresses and 8 from the
two multi-alias addresses, resolved per site:
$E0/$E1 IndirectPtrLo/Hi in the RAM-clear loop
(InitializeSystemAndRunMainLoop -> Main_WriteSoundDispatchIndex_C317,
which writes $00 across $0100-$07FF via (ptr),y),
SoundDelay0 (the base of the per-channel delay table, indexed by X)
in the sound engine;
No symbols.inc substitution was needed: copilot/prg.s contains no numeric
hardware operands ($2000-$4017) at all. All 362 operands were already written
with two hex digits, so no ca65 `a:` prefix was required.
make -> Byte-identical ROM verified. Operand token only; mnemonics, spacing and
the trailing `; CPU:$.... PRG:.... XX XX` audit comments are untouched.
Remaining numeric operands (758) address bytes that no .inc file names:
505 zero-page (133 addresses), 171 RAM $0100-$07FF (46 addresses) and 82
table reads in $8000+ (54 addresses).
Bomberman (U): substitute 24 in-file table labels at ROM operand sites
Uses the new `--labels` option of `apply_symbols.py` with the
ld65 `-Ln` output (`reconstructed.lbl`). Only labels that prg.s
actually defines and that live in the PRG (+) are considered,
so CHR/header segment labels cannot leak in.
24 numeric operands (`lda ,x`, `adc ,y`, etc.) now read
`lda SystemPaletteData,x`, `adc GameplayObjectClassTable,y`, etc.
All 24 point at exact label addresses; the remaining 58 ROM-space
numeric operands point at interior bytes or unlabelled tables and
stay numeric.
make -> Byte-identical ROM verified.
Bomberman (U): update docs for Pass 3 symbol application
- Project OVERVIEW.md: corrected source file from main.s to prg.s/header.s/chr.s;
output name from reconstructed_bomberman.nes to reconstructed.nes;
rewritten §10 Zero-Page/RAM Symbols table to match locals.inc (with aliases
and unnamed residue documented);
fixed §4 step 1/4 to use IndirectPtrLo/Hi and SoundDelay0 names;
fixed §11 InesHeader location (now header.s);
added §2 Pass 3 summary table;
added §13 notes on legacy main.s and Main_WriteSoundDispatchIndex_C317 misnomer.
- Root OVERVIEW.md §3: updated source line count (7,553), file list, and added
Pass 3 summary.
Both builds verified byte-identical.
Pass 3 symbol application to all 19 top-level projects (2026-10-19)
Ran _tools/apply_symbols.py --write on all 19 promoted projects to substitute
symbolic names from symbols.inc (hardware registers) and locals.inc (zero-page
RAM aliases, forward references) into prg.s operands. The tool preserves the
canonical audit comments (; CPU:$XXXX PRG:XXXX AA BB) and preserves byte
identity — all projects still rebuild byte-identical to their original ROMs.
Per-project operand substitutions:
Baseball (UE) 121 (85 single + 36 hardware)
Tennis (JU) 18 (18 single)
Pac-Man (USA) (Namco) 524 (524 single; 727 multi-alias residues)
CIRCUS 118 (38 single + 80 hardware; 23 multi-alias residues)
Wild Gunman (U) 76 (11 single + 65 hardware)
Joypad Test Cartridge (U) 47 (47 hardware)
NES PowerPad Test Card (U) 89 (89 hardware)
MUSCLE (U) 220 (91 single + 129 hardware)
Lunar Pool (U) 45 (18 single + 27 hardware)
Donkey Kong (JU) 75 (17 single + 58 hardware)
Urban Champion (JU) 70 (4 single + 66 hardware)
Already had symbols applied: Balloon Fight, Bomberman, Burger Time,
Clu Clu Land, Defender 2, Donkey Kong 3, Donkey Kong Jr.
Skipped: Excitebike (JU) — inline prg.s definitions conflict with locals.inc
values and source operands don't match ROM byte encodings; automatic
substitution breaks byte identity.
Documentation updated:
OVERVIEW.md — added Pass 3 symbol notes to all 19 project entries,
added Urban Champion as section #36
TODO.md — current state now reflects complete symbol application across
the promoted tier
Verification: python3 _tools/verify_pass1.py reports all 19 projects OK/SEEDED,
all canonical comments, no truncated or unfaithful Pass 1.
277 lines
16 KiB
Markdown
277 lines
16 KiB
Markdown
# Joypad Test Cartridge (U) — Game Flow from Power-On
|
||
|
||
This document describes the execution flow of the disassembled Joypad Test Cartridge (U) PRG bank (16 KB, mapped at CPU **$C000–$FFFF**), starting from power-on. It is based entirely on `copilot/prg.s` in the repository. The rebuild is verified **byte-identical** to the original `prg.bin`.
|
||
|
||
---
|
||
|
||
## 1. ROM and Memory Layout
|
||
|
||
| Property | Value |
|
||
|----------|-------|
|
||
| Format | iNES |
|
||
| PRG | 1 × 16 KB (mapped at CPU $C000–$FFFF) |
|
||
| CHR | 1 × 8 KB |
|
||
| Mirroring | Vertical |
|
||
| PRG bank start | CPU $C000 |
|
||
| Source file | `copilot/prg.s` (4,516 lines with headers) |
|
||
| Output | `reconstructed.nes` (24,592 bytes) |
|
||
|
||
### Interrupt vectors (CPU $FFFA–$FFFF)
|
||
|
||
| Vector | Address | Handler |
|
||
|--------|---------|---------|
|
||
| NMI | $CCF7 | `NmiHandler` |
|
||
| RESET | $C000 | `Reset` |
|
||
| IRQ / BRK | $C000 | Reuses `Reset` |
|
||
|
||
---
|
||
|
||
## 2. Build Status
|
||
|
||
`make` in `copilot/` assembles `prg.s` with `ca65`, links with `ld65`, and verifies against `prg.bin`.
|
||
|
||
**Verification result: BYTE-IDENTICAL** — `make` compares the whole reconstructed ROM against `copilot/rom.nes` and prints `Byte-identical ROM verified.` Byte accounting is exact: 3,836 code + 12,548 data = 16,384 of 16,384 bytes.
|
||
|
||
---
|
||
|
||
## 3. Pass Status
|
||
|
||
| Pass | Status | Description |
|
||
|------|--------|-------------|
|
||
| Pass 1 | **Redone** | Was badly truncated: 282 instructions / 580 bytes (3.5%). Now **1,773 instructions / 3,836 bytes (23.4%)** — a 6.6x increase. Root cause: the tracer only knew the 151 official opcodes and halted at `$C09E` on `DCP $3C20` (`$CF`), filing 3,256 bytes of real code as `.byte`. Verified against a fresh trace: 1,769 emitted instructions + 4 undocumented opcodes written as explicit bytes = 1,773, an exact match |
|
||
| Pass 2 | **Complete** | 202 labels, **zero `Label_Cxxxx` remaining**; 202 routine headers, all describing real behaviour (no "undetermined in Pass 1" boilerplate); `locals.inc` carries 99 aliases, half of them proven semantic names sitting beside the generated `ZpXX` entries |
|
||
| Pass 3 | **Complete** | The single data region `$CF06–$FFFF` has been broken into 20 named sub-blocks: VRAM command streams read by `VramWriteLoop`/`RetAddrUpdate`, seven 32-byte OAM table groups read by `CopyOamFromTable`/`CopyOamFromTable70`, the 32-byte sprite template read by `CopySpriteTemplateTable`, the 32-byte button OAM template read by `PrepareButtonOam`, and 10,517 bytes of `$FF` ROM padding. The `RetAddrUpdate` VRAM command stream opcode set has been decoded (`$4C` = jump, `$60` = deferred PPUCTRL, bit-7-clear bytes = VRAM write with PPU addr + data, bit 6 of data = long/short command selector). |
|
||
|
||
### Why Pass 1 was truncated
|
||
|
||
The tracer descended from the three vectors, following direct `jsr`/`jmp`/branch
|
||
targets. It stopped at `$C09E`, where the byte is `$CF` = `DCP $3C20` — an
|
||
undocumented read-modify-write op used here as ordinary code. Everything after
|
||
that point was written out as data until a later run promoted it.
|
||
|
||
This cartridge is an unusually clear demonstration: nothing exotic is involved,
|
||
just one undocumented opcode in the middle of the main loop. `nesdis.py` now
|
||
takes `--undocumented` (default **off**, so other projects' `make regen` stays
|
||
byte-stable) to decode all 105 undocumented NMOS opcodes.
|
||
|
||
ca65 V2.19 implements none of them, so the 4 affected instructions
|
||
(`DCP $3C20`, `LAX $20D4`, `NOP $C1,X`, `RRA ($D0),X`) are emitted as explicit
|
||
`.byte` with the disassembly in the comment. They stay in the code region, so
|
||
the split and the audit trail are both preserved.
|
||
|
||
---
|
||
|
||
## 4. Reset — CPU $FFFC → $C000
|
||
|
||
**`Reset`** ($C000)
|
||
|
||
On power-on or reset:
|
||
|
||
1. **Wait for three PPU warm-up vblanks** — `WaitVblank2` ($C005) and `WaitVblank3` ($C00A) each poll `$2002` bit 7, following an initial poll at $C000.
|
||
2. **Clear RAM** — `ClearRAM1_Loop` ($C013) clears pages $0000–$07FF via indirect indexed store (`STA VramPtrLo,X` / `STA $0100,X` etc.).
|
||
3. **Initialize PPU** — `InitPPU_1` ($C031): `STA $2000` with $10 (PPUCTRL, NMI disabled), shadow in `PpuCtrlShadow` ($EF); `STA $2001` with $00 (PPUMASK off), shadow in `PpuMaskValue` ($EE).
|
||
4. **OAM DMA** — `OamDma` ($C03F): `STA $4014` with $02 (DMA from $0200–$02FF).
|
||
5. **Clear controller state** — `ClearController` ($C044): clears $2003 (OAMADDR) and state variables.
|
||
6. `JSR PpuScrollLatch` ($CE3C) — latch scroll and control registers.
|
||
7. `LDX #$FF / TXS` — initialize stack pointer.
|
||
8. `JSR PpuMaskSetup` ($CD2F) — set PPUMASK from shadow.
|
||
9. **Clear RAM again** — `ClearRAM2_Loop` ($C05D) clears pages $0000–$06FF.
|
||
10. **Re-initialize PPU** — `InitPPU_2` ($C078): same as InitPPU_1.
|
||
11. **VRAM write** — `VramWriteSetup1` ($C086): set up address/length for a VRAM write via `VramWrite` ($CDEE).
|
||
12. `JSR ClearOAM_Routine` ($C174) — clear OAM with sprite flush value $F4.
|
||
13. `JSR VramPtrWrite` ($CD3F) — write VRAM data via pointer table.
|
||
14. `ToggleFlag` ($C095) — toggle `VramToggleFlag` ($CF).
|
||
15. `JSR PpuScrollLatch` ($CE3C) and `JSR VramPtrWrite` ($CD3F) again.
|
||
16. **Main loop** — spins, toggling $CF each iteration and calling PPU/VRAM update routines.
|
||
|
||
---
|
||
|
||
## 5. NMI / Frame Heartbeat — `NmiHandler` ($CCF7)
|
||
|
||
The NMI fires once per frame:
|
||
|
||
1. **Save registers** (`PHA / TXA / PHA / TYA / PHA`).
|
||
2. `JSR PpuCtrlSetup` ($CD17) — latch PPUSTATUS, clear NMI bit in `PpuCtrlShadow` ($EF), write to PPUCTRL.
|
||
3. `JSR OamDmaSetup` ($CD24) — set OAMADDR=0, trigger OAM DMA ($4014=$02).
|
||
4. Check `$0300` (vblank flag) — if nonzero, `JSR VramBurstWrite` ($CE4F) to burst-write VRAM data from table at $0302.
|
||
5. `JSR PpuScrollLatch` ($CE3C) — latch scroll and control.
|
||
6. Clear `NmiFlagByte` ($E0) to 0.
|
||
7. **Restore registers** (`PLA / TAX / PLA / TAY / PLA / RTI`).
|
||
|
||
---
|
||
|
||
## 6. Key Subroutines
|
||
|
||
| Label | Address | Description |
|
||
|-------|---------|-------------|
|
||
| `Reset` | $C000 | Cold-start initialization: vblank waits, RAM clear, PPU init, OAM DMA |
|
||
| `WaitVblank2` | $C005 | Wait for second PPU warm-up vblank |
|
||
| `WaitVblank3` | $C00A | Wait for third PPU warm-up vblank |
|
||
| `ClearRAM1_Loop` | $C013 | Clear RAM pages $00–$07 |
|
||
| `InitPPU_1` | $C031 | Initialize PPUCTRL and PPUMASK |
|
||
| `OamDma` | $C03F | Trigger OAM DMA via $4014 |
|
||
| `ClearController` | $C044 | Clear OAMADDR and controller state |
|
||
| `PpuScrollLatch` | $CE3C | Latch PPU scroll X/Y and control register |
|
||
| `InitStack` | $C052 | Initialize stack pointer to $FF |
|
||
| `PpuMaskSetup` | $CD2F | Set PPUMASK from shadow register |
|
||
| `ClearRAM2_Loop` | $C05D | Clear RAM pages $00–$06 |
|
||
| `InitPPU_2` | $C078 | Re-initialize PPU control and mask |
|
||
| `VramWriteSetup1` | $C086 | Set up VRAM write parameters |
|
||
| `ClearOAM_Call` | $C08F | Call OAM clear routine |
|
||
| `VramPtrWrite1` | $C092 | Write VRAM data via pointer table |
|
||
| `ToggleFlag` | $C095 | Toggle VramToggleFlag ($CF) |
|
||
| `SetupScroll2` | $C097 | Latch PPU scroll and control |
|
||
| `VramPtrWrite2` | $C09A | Write VRAM data via pointer table again |
|
||
| `ClearOAM_Routine` | $C174 | Clear OAM ($0200–$02FF) with $F4 |
|
||
| `NmiHandler` | $CCF7 | Per-frame NMI: PPU updates, OAM DMA, VRAM burst write |
|
||
| `NmiContinue` | $CD0A | Continue NMI: latch PPU scroll, clear flag |
|
||
| `PpuCtrlSetup` | $CD17 | Latch PPUSTATUS, write PPUCTRL from shadow |
|
||
| `OamDmaSetup` | $CD24 | Set OAMADDR=0, trigger OAM DMA |
|
||
| `PpuMaskSetup` | $CD2F | Set PPUMASK from shadow |
|
||
| `VramPtrWrite` | $CD3F | Write VRAM via pointer table (uses RetAddrUpdate) |
|
||
| `VramWriteLoop` | $CD45 | Loop writing bytes from indirect pointer to PPUDATA |
|
||
| `VramPtrTableRead` | $CD99 | Read from pointer table at $0000 |
|
||
| `RetAddrUpdate` | $CDC8 | Get return address from stack, advance by 2 |
|
||
| `VramWrite` | $CDEE | Set PPU address, write data bytes to PPUDATA |
|
||
| `VramBurstWrite` | $CE4F | Burst-write VRAM from table at $0302 |
|
||
|
||
---
|
||
|
||
## 7. Zero-Page Aliases (`locals.inc`)
|
||
|
||
| Alias | Address | Role |
|
||
|-------|---------|------|
|
||
| `VramPtrLo` | $00 | VRAM write pointer low byte |
|
||
| `VramPtrHi` | $01 | VRAM write pointer high byte |
|
||
| `VramLen` | $02 | VRAM write data length |
|
||
| `PpuScrollX` | $03 | PPU horizontal scroll |
|
||
| `RetAddrTempLo` | $05 | Return address temp lo |
|
||
| `RetAddrTempHi` | $06 | Return address temp hi |
|
||
| `PpuMaskShadow` | $0E | PPUMASK shadow |
|
||
| `PpuCtrlShadow` | $EF | PPUCTRL shadow (NMI bit cleared) |
|
||
| `VramToggleFlag` | $CF | Frame toggle flag |
|
||
| `NmiFlagByte` | $E0 | NMI flag byte |
|
||
| `JoyBtnStateBase` | $4E | Base for indexed button states |
|
||
| `FrameCounterLo` | $53 | Frame counter low byte |
|
||
| `FrameCounterHi` | $54 | Frame counter high byte |
|
||
|
||
Full list in `copilot/locals.inc`.
|
||
|
||
---
|
||
|
||
## 8. Data Regions
|
||
|
||
The PRG is **23.4% code / 76.6% data** (3,836 / 12,548 bytes). The data region `$CF06–$FFFF` has been broken into 20 named sub-blocks:
|
||
|
||
| Address | Size | Name | Contents |
|
||
|---------|------|------|----------|
|
||
| `$CF06–$CF28` | 35 B | `VramCommandStream1` | VRAM command stream start — PPU addr/data pairs read by `VramWriteLoop` |
|
||
| `$CF29` | 1 B | `VramStream1Terminator` | `$FF` terminator ending first command stream |
|
||
| `$CF2A–$CF3F` | 22 B | `VramCommandInlineCode` | Inline code after `jsr $CE98` — `lax $20D4`, `nop $C1,X`, `$61` padding |
|
||
| `$CF40–$D061` | 290 B | `VramCommandBlock2` | VRAM command/data block — PPU writes and OAM attribute patterns |
|
||
| `$D062` | 1 B | `VramStream2Terminator` | `$FF` terminator ending second command stream |
|
||
| `$D063–$D1F3` | 401 B | `VramCommandBlock3` | VRAM command/data block — continues command stream patterns |
|
||
| `$D1F4` | 1 B | `VramStream3Terminator` | `$FF` terminator ending third command stream |
|
||
| `$D1F5–$D4AD` | 697 B | `VramCommandBlock4` | Largest VRAM command/data block — 697 bytes of command stream |
|
||
| `$D4AE` | 1 B | `OamTableStreamTerminator` | `$FF` terminator before OAM gap data |
|
||
| `$D4AF–$D4E1` | 51 B | `OamTableGap` | Gap data before OAM table at `$D4E3` |
|
||
| `$D4E2` | 1 B | `OamTable1Terminator` | `$FF` terminator before OAM table group 1 |
|
||
| `$D4E3–$D5C2` | 224 B | `OamTableGroups1` | OAM table groups 1-7 (`CopyOamFromTable` reads `$D4E3`) — 7×32 byte tables, each with 8 entries of Y/tile/attr/X |
|
||
| `$D5C3` | 1 B | `OamTableStream2Terminator` | `$FF` terminator before second OAM table group |
|
||
| `$D5C4–$D603` | 64 B | `OamTableGroups2` | OAM table groups 1-2 (`CopyOamFromTable70` reads `$D5C4`) — 2×32 byte tables |
|
||
| `$D604–$D643` | 64 B | `OamSpritePadding` | 64 bytes of `$F4` sprite off-screen padding |
|
||
| `$D644–$D6A3` | 96 B | `OamTableGroups3` | OAM table groups 3-5 — 3×32 byte tables before sprite template |
|
||
| `$D6A4` | 1 B | `SpriteTableTerminator` | `$FF` terminator before sprite template table |
|
||
| `$D6A5–$D6C4` | 32 B | `SpriteTemplateTable` | Sprite template — 8×4 Y/tile/attr/X entries (`CopySpriteTemplateTable` reads `$D6A5`) |
|
||
| `$D6C5–$D6E4` | 32 B | `ButtonOamTemplateTable` | Button OAM template — 8×4 Y/tile/attr/X entries (`PrepareButtonOam` reads `$D6C5`) |
|
||
| `$D6E5–$FFF9` | 10,517 B | `RomPadding` | `$FF` ROM padding |
|
||
| `$FFFA–$FFFF` | 6 B | `ResetVectors` | Reset/NMI/IRQ vectors |
|
||
|
||
The previous Pass 3 claimed four data regions totalling ~15.8 KB, including `$C09E–$C173` and `$C17F–$CCF6`. Both are code. Those claims were an artefact of the truncated Pass 1 and have been removed.
|
||
|
||
### VRAM Command Stream Format
|
||
|
||
The VRAM command stream is read by `VramWriteLoop` (`$CD45`), dispatched through `VramPtrTableRead` (`$CD99`) and `RetAddrUpdate` (`$CDC8`). The stream uses the `RetAddrUpdate` return-address modification trick: `jsr $CE98` (`DispatchVramOp`) pushes a return address, `RetAddrUpdate` advances it by 2 to skip the command byte, and execution resumes inline after the dispatch returns.
|
||
|
||
Command byte format (read by `DispatchVramOp` at `$CE98`):
|
||
- **Low 4 bits**: data length (number of bytes following)
|
||
- **High 4 bits**: command type
|
||
|
||
Opcodes:
|
||
- `$4C` (`HandleJmpOpcode`): jump — reads 2-byte address from stream, rewrites dispatch pointer
|
||
- `$60` (`HandlePpuCtrlOpcode`): deferred PPUCTRL write — pops return address from stack as new stream pointer
|
||
- Bit 7 clear, not `$4C`/`$60` (`VramWriteLoop`): VRAM write — opcode byte = PPU addr high, next byte = PPU addr low, then data bytes. Bit 6 of each data byte selects short (1 byte) vs long (multiple bytes) command.
|
||
- Bit 7 set: end of stream
|
||
|
||
### OAM Table Structure
|
||
|
||
OAM tables consist of 8 entries of 4 bytes each (Y, tile, attr, X), matching the NES OAM layout:
|
||
- `SpriteTemplateTable` (`$D6A5`): Y=$79 for all entries, player sprite tiles
|
||
- `ButtonOamTemplateTable` (`$D6C5`): Y=$79 for all entries, button indicator tiles
|
||
- `OamTableGroups1` (`$D4E3`): 7 groups with varying Y values ($37, $67, $57, $97, $87, $C7, $B7, $5F, $6F)
|
||
- `OamTableGroups2` (`$D5C4`): 2 groups with Y values $37 and $67
|
||
- `OamTableGroups3` (`$D644`): 3 groups with Y values $27, $37, $57, $67
|
||
|
||
Notable data structures (addresses from the code that reads them):
|
||
|
||
- VRAM pointer at `$00/$01`, read indirectly by `VramPtrTableRead` ($CD99), `WriteVramStreamByte` ($CD74) and `DispatchVramOp` ($CE98)
|
||
- VRAM burst command table at `$0302`, read by `VramBurstWrite` ($CE4F) and written by `StoreVramOpResult` ($CEB2); `SetBurstWriteIndex` primes it with `$22`
|
||
- VRAM op length limit at `$0300`, tested by `VramOpLengthCheck` ($CEF3)
|
||
- Sprite template tables at `$D6A5` (`CopySpriteTemplateTable`) and `$D6C5` (`PrepareButtonOam`), copied into the OAM shadow at `$02E0`
|
||
- Further OAM tables at `$D4E3` (`CopyOamFromTable`) and `$D5C4` (`CopyOamFromTable70`)
|
||
|
||
---
|
||
|
||
## 9. Build
|
||
|
||
```bash
|
||
cd "Joypad Test Cartridge (U)/copilot"
|
||
make # → ca65 + ld65 + cmp reconstructed.nes rom.nes → "Byte-identical ROM verified."
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Notes
|
||
|
||
- The NMI handler drives per-frame updates; the main loop spins waiting for NMI phase changes.
|
||
- `RetAddrUpdate` ($CDC8) implements a return-address modification trick: it reads the return address from the stack, advances it by 2, and stores it back. This is used with `VramPtrWrite` ($CD3F) to implement runtime-computed control flow (effectively a coroutine/threaded dispatch).
|
||
- The IRQ vector points to $C000 (Reset) and is effectively unused.
|
||
- Large portions of the PRG are test pattern and button mapping data, not executable code.
|
||
- `PollExpansionPortLoop` reads `$4017` and compares bits 0-1, but nothing consumes
|
||
the result — the branch is always taken the same way. The read is present but inert.
|
||
- `MarkerVar01`–`MarkerVar12` (zero page `$5A`, `$5B`, `$56`–$5F`, `$60`, `$61`, `$63`,
|
||
`$64`) drive the twelve `MarkerUpdateN` indicator groups. Which player and button each
|
||
belongs to is **not** established, so they are named by position rather than by button.
|
||
- A draft Pass 2 `locals.inc` called `$55` a "P1 Down timer". The instructions do not
|
||
support that: `ApplyMarkerValueEnableAudio` stores `$70`/`$88`/`$A0` there and
|
||
`DispatchOnMarkerValue` compares it against `$70` and `$88`. It is `MarkerValue`.
|
||
|
||
---
|
||
|
||
## 11. Next Steps
|
||
|
||
- **Pass 3 is complete.** All 20 data sub-blocks are named (section 8), the VRAM command stream opcode set is decoded, and the OAM table structure is documented.
|
||
- **MarkerVar mapping** (from `locals.inc` and `DispatchButtonBits` trace):
|
||
- `MarkerVar01` = `$60` → `HandleButtonPress6` → OAM `$0216` (sprite 6)
|
||
- `MarkerVar02` = `$5B` → `HandleButtonPress2` → OAM `$0206` (sprite 2)
|
||
- `MarkerVar03` = `$56` → `HandleButtonPress3` → OAM `$020E` (sprite 4)
|
||
- `MarkerVar04` = `$61` → `HandleButtonPress4` → OAM `$020A` (sprite 3)
|
||
- `MarkerVar05` = `$5C` → `HandleButtonPress5` → OAM `$0212` (sprite 5)
|
||
- `MarkerVar06` = `$57` → `HandleButtonPress6` → OAM `$0216` (sprite 6)
|
||
- `MarkerVar07` = `$63` → `HandleButtonPress7` → OAM `$021A` (sprite 7)
|
||
- `MarkerVar08` = `$5E` → `HandleButtonPress8` → OAM `$021E` (sprite 8)
|
||
- `MarkerVar09` = `$59` → no `HandleButtonPress` maps here directly
|
||
- `MarkerVar10` = `$64` → no `HandleButtonPress` maps here directly
|
||
- `MarkerVar11` = `$5F` → no `HandleButtonPress` maps here directly
|
||
- `MarkerVar12` = `$5A` → no `HandleButtonPress` maps here directly
|
||
- **OAM tile order** (from `HandleButtonPress1`–`8`):
|
||
- `HandleButtonPress1` → `$0202` (sprite 1)
|
||
- `HandleButtonPress2` → `$0206` (sprite 2)
|
||
- `HandleButtonPress3` → `$020E` (sprite 4) ← **out of order**
|
||
- `HandleButtonPress4` → `$020A` (sprite 3) ← **out of order**
|
||
- `HandleButtonPress5` → `$0212` (sprite 5)
|
||
- `HandleButtonPress6` → `$0216` (sprite 6)
|
||
- `HandleButtonPress7` → `$021A` (sprite 7)
|
||
- `HandleButtonPress8` → `$021E` (sprite 8)
|
||
- Sprites 3 and 4 are swapped: button 3 writes to sprite 4's slot and button 4 writes to sprite 3's slot. This is a genuine quirk of the game's OAM layout, not a disassembly error.
|