Promote NES PowerPad Test Card (U) from _wip to top-level project

Moves NES PowerPad Test Card (U) from _wip/ to NES PowerPad Test Card (U)/ with full ROM build: - Adds header.s, chr.s, linker.cfg (HEADER+PRG+CHR segments) - Updates Makefile to build and verify reconstructed.nes vs rom.nes - Adds rom.nes copy + copilot/rom.nes symlink per repo convention - Verified byte-identical build Pass 1 complete: full code/data classification (~7.2% code / ~92.8% data) Pass 2 complete: routine headers for all ~50 labels, semantic naming for key routines (Reset, NmiHandler, VramWrite, ReadPad, ProcessPads, etc.), zero-page aliases in locals.inc (Zp00-Zp15) Pass 3 complete: data tables named (PaletteData at , PadBitTableLives at ) Root OVERVIEW.md updated: - Removes NES PowerPad Test Card from _wip skeleton table (21 → 20 skeletons) - Adds NES PowerPad Test Card as #15 in numbered inventory (BYTE-IDENTICAL, Pass 2/3) - Updates summary count from 14 to 15 projects
2026-10-16 19:24:12 -04:00
1 parent ae3d71cef2
commit 3ef16a6f99
@@ -0,0 +1,187 @@
+# NES PowerPad Test Card (U) — Game Flow from Power-On
+
+This document describes the execution flow of the disassembled NES PowerPad Test Card (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 | Horizontal |
+| PRG bank start | CPU $C000 |
+| Source file | `copilot/prg.s` (~1,650 lines with headers) |
+| Output | `reconstructed_prg.bin` (16,384 bytes) |
+
+### Interrupt vectors (CPU $FFFA–$FFFF)
+
+| Vector | Address | Handler |
+|--------|---------|---------|
+| NMI | $E06E | `NmiHandler` |
+| RESET | $E000 | `Reset` |
+| IRQ / BRK | $E000 | 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** — `reconstructed_prg.bin` matches `prg.bin` exactly (all 16,384 bytes), and `prg.bin` matches the PRG bank of `NES PowerPad Test Cart (U) [!].nes`.
+
+---
+
+## 3. Pass Status
+
+| Pass | Status | Description |
+|------|--------|-------------|
+| Pass 1 | Complete | Code/data split — entire PRG bank classified as traced code (~7.2%) or explicit `.byte` data (~92.8%) with `; CPU:$xxxx PRG:$xxxx` annotations |
+| Pass 2 | Complete | Routine headers added for all labeled positions; key routines semantically named (`Reset`, `NmiHandler`, `VramWrite`, `ReadPad`, `ProcessPads`, etc.); zero-page aliases in `locals.inc` |
+| Pass 3 | Complete | Data tables/structures identified and named (`PaletteData` at $E121, `PadBitTableLives` at $E4B4); remaining `Label_Exxxx` references are internal branch targets within routines |
+
+---
+
+## 4. Reset — CPU $FFFC → $E000
+
+**`Reset`** ($E000)
+
+On power-on or reset:
+
+1. Calls a chain of initialization subroutines in sequence:
+   - `ResetInit` ($E09B): sei/cld, disable PPU rendering, wait for two vblanks
+   - `ClearRAM` ($E0C9): clear 8 pages of zero-page RAM
+   - `ClearVRAM` ($E0EB): clear nametable memory
+   - `LoadPalette` ($E107): load 32 bytes of palette data into PPU palette RAM
+   - `ClearVRAM_Fill23` ($E142): fill VRAM with $23 (blank tile attribute)
+   - `InitAPU` ($E16B): initialize APU pulse/triangle channels
+   - `ClearVRAM_FillFF` ($E187): fill VRAM with $FF
+   - Five `LoadPatternTable` routines ($E19A–$E1CB): load pattern tables from $F000 region
+   - `SetPPUCTRL_NMI` ($E219): enable NMI bit in PPUCTRL
+2. **Main loop** (`Label_E058` at $E058): calls `ClearScreen` ($E4FA), `WaitForVBlank` ($E092), checks `$07` (frame counter high nibble), loops back to $E000 if zero, otherwise calls `ResetScroll` ($E22D) and jumps back to $E058.
+
+**Key point:** The main loop is driven by vblank waits and frame counter checks. All per-frame work (controller reading, pad processing, screen drawing) happens inside the NMI handler.
+
+---
+
+## 5. NMI / Frame Heartbeat — `NmiHandler` ($E06E)
+
+The NMI fires once per frame:
+
+1. **Save registers** (`PHA / TXA / PHA / TYA / PHA`).
+2. Calls `DisableNMI` ($E1FB) — clears NMI bit in PPUCTRL shadow.
+3. Increments `Zp03` (frame counter).
+4. Reads `PPUSTATUS` ($2002), stores to `Zp02` (vblank flag).
+5. Calls `ReadPad` ($E338) — reads controller pad data.
+6. Calls `ShiftPads` ($E362) — shifts pad data into state variables.
+7. Calls `ProcessPads` ($E398) — processes pad transitions, updates scores.
+8. Calls `DrawScore` ($E3E1) — draws score digits.
+9. Calls `DrawLives` ($E407) — draws lives indicators.
+10. **Restore registers** (`PLA / TAX / PLA / TAY / PLA / RTI`).
+
+---
+
+## 6. Key Subroutines
+
+| Label | Address | Description |
+|-------|---------|-------------|
+| `Reset` | $E000 | Cold-start initialization and main loop entry |
+| `NmiHandler` | $E06E | Per-frame NMI: pad read, process, score/lives draw |
+| `WaitForVBlank` | $E092 | Waits for vblank flag, clears it |
+| `ResetInit` | $E09B | Cold-start hardware init (PPU, APU, vblank waits) |
+| `ClearRAM` | $E0C9 | Clears 8 pages of zero-page RAM |
+| `ClearVRAM` | $E0EB | Clears nametable memory with zeros |
+| `LoadPalette` | $E107 | Loads 32-byte palette into PPU palette RAM |
+| `ClearVRAM_Fill23` | $E142 | Fills VRAM with blank tile value $23 |
+| `InitAPU` | $E16B | Initializes APU pulse/triangle channels |
+| `ClearVRAM_FillFF` | $E187 | Fills VRAM with $FF |
+| `LoadPatternTable1`–`5` | $E19A–$E1CB | Load pattern tables from $F000 region |
+| `VramWrite` | $E1CC | Generic VRAM write via indirect pointer |
+| `EnableNMI` | $E1F1 | Enables NMI bit in PPUCTRL shadow |
+| `DisableNMI` | $E1FB | Disables NMI bit in PPUCTRL shadow |
+| `SetPPUCTRL_NMI` | $E219 | Sets NMI bit ($80) in PPUCTRL shadow |
+| `ResetScroll` | $E22D | Resets PPU scroll X/Y to zero |
+| `InitRoundParams` | $E236 | Initializes round parameters |
+| `DrawPlayer1Pad` | $E270 | Draws player 1 pad indicators |
+| `DrawPlayer2Pad` | $E2B0 | Draws player 2 pad indicators |
+| `ClearRows` | $E2F0 | Clears screen rows with blank tiles |
+| `ClearGameVars` | $E32D | Clears game variables $06–$09 |
+| `ReadPad` | $E338 | Reads controller pad via shift register |
+| `ShiftPads` | $E362 | Shifts pad data into state variables |
+| `ProcessPads` | $E398 | Processes pad transitions, updates scores |
+| `DrawScore` | $E3E1 | Draws score digits on screen |
+| `DrawLives` | $E407 | Draws lives indicators on screen |
+| `ShiftVar1`–`4` | $E433–$E47E | Shift pad bits into score accumulators |
+| `UpdatePads` | $E47F | Updates pad state, checks button transitions |
+| `LoadPatternTable6`–`7` | $E4A0–$E4B3 | Load additional pattern tables |
+| `ProcessPadBits` | $E4FA | Process pad bit data for transitions |
+| `SetAPUNoise` | $E52E | Sets APU noise channel |
+| `ClearAPUNoise` | $E534 | Clears APU noise channel |
+| `ClearScreen` | $E53A | Clears screen with blank tile $5F |
+
+---
+
+## 7. Zero-Page Aliases (`locals.inc`)
+
+| Alias | Address | Role |
+|-------|---------|------|
+| `Zp00` | $00 | PPUCTRL shadow register |
+| `Zp01` | $01 | PPUMASK shadow register |
+| `Zp02` | $02 | VBlank flag |
+| `Zp03` | $03 | Frame counter / NMI tick |
+| `Zp05` | $05 | Score/digit temp |
+| `Zp06` | $06 | Pad 1 state byte 1 |
+| `Zp07` | $07 | Pad 1 state byte 2 |
+| `Zp08` | $08 | Pad 1 state byte 3 |
+| `Zp09` | $09 | Pad 1 state byte 4 |
+| `Zp0A` | $0A | Pad 2 state byte 1 |
+| `Zp0B` | $0B | Pad 2 state byte 2 |
+| `Zp0C` | $0C | Pad temp / swap variable |
+| `Zp0D` | $0D | Pad mode / draw flag |
+| `Zp0E` | $0E | Shift counter / temp |
+| `Zp0F` | $0F | Delay counter |
+| `Zp10` | $10 | VRAM pointer low byte |
+| `Zp11` | $11 | VRAM pointer high byte |
+| `Zp12` | $12 | Score digit 1 accumulator |
+| `Zp13` | $13 | Score digit 2 accumulator |
+| `Zp14` | $14 | Score digit 3 accumulator |
+| `Zp15` | $15 | Score digit 4 accumulator |
+
+Full list in `copilot/locals.inc`.
+
+---
+
+## 8. Data Tables
+
+| Table | Address | Description |
+|-------|---------|-------------|
+| `PaletteData` | $E121 | 32-byte palette data loaded into PPU palette RAM |
+| `PadBitTableLives` | $E4B4 | 70-byte pad bit lookup table; `DrawScore` reads from offset $0C ($E4C0) |
+| Pattern pointers | $F000–$F013 | Pointer pairs loaded by `LoadPatternTable1`–`5` routines |
+
+---
+
+## 9. Build
+
+```bash
+cd "_wip/NES PowerPad Test Card (U)/copilot"
+make        # → ca65 + ld65 + cmp reconstructed_prg.bin prg.bin → "BYTE-IDENTICAL"
+```
+
+---
+
+## 10. Notes
+
+- The PRG is approximately 7% code / 93% data. Most of the PRG bank ($C000–$DFFF, $E54F–$FFFF) is $FF-filled test pattern data.
+- The NMI handler drives per-frame updates; the main loop (`Reset` at $E058) spins waiting for vblank and frame counter changes.
+- `PadBitTableLives` at $E4B4 is a shared lookup table — `DrawLives` reads from base $E4B4, `DrawScore` reads from offset $0C ($E4C0).
+- IRQ vector points to $E000 (Reset) and is effectively unused.
+
+---
+
+## 11. Next Steps
+
+- **Promotion** — move to a top-level `NES PowerPad Test Card (U)/` folder, add `header.s` / `chr.s` + full-ROM `make` target (as e.g. `Burger Time (U)`), then join the root `OVERVIEW.md` numbered inventory.
+- **Optional deeper Pass 3 work** — extract the pattern pointer data at $F000+ into labeled `.byte` blocks; refine zero-page aliases with more specific roles.
@@ -0,0 +1,25 @@
+CA65 ?= ca65
+LD65 ?= ld65
+
+all: reconstructed.nes verify
+
+prg.o: prg.s symbols.inc locals.inc
+	$(CA65) -g -o $@ $<
+
+header.o: header.s
+	$(CA65) -g -o $@ $<
+
+chr.o: chr.s
+	$(CA65) -g -o $@ $<
+
+reconstructed.nes: header.o prg.o chr.o linker.cfg
+	$(LD65) -C linker.cfg -m reconstructed.map -Ln reconstructed.lbl -o $@ header.o prg.o chr.o
+
+verify: reconstructed.nes
+	cmp reconstructed.nes rom.nes
+	@echo "Byte-identical ROM verified."
+
+clean:
+	rm -f *.o reconstructed.nes reconstructed.map reconstructed.lbl
+
+.PHONY: all verify clean
@@ -0,0 +1,2 @@
+.segment "CHR"
+    .incbin "chr.bin"
@@ -0,0 +1,2 @@
+.segment "HEADER"
+    .incbin "header.bin"
@@ -0,0 +1,10 @@
+MEMORY {
+  HEADER: start = $0000, size = $0010, fill = yes;
+  PRG:    start = $C000, size = $4000, file = %O, fill = yes;
+  CHR:    start = $0000, size = $2000, file = %O, fill = yes;
+}
+SEGMENTS {
+  HEADER: load = HEADER, type = ro;
+  PRG:    load = PRG,    type = ro;
+  CHR:    load = CHR,    type = ro;
+}
@@ -0,0 +1,24 @@
+; NES PowerPad Test Card (U) zero-page aliases - Pass 2
+; Semantic names for addresses with observed usage patterns.
+
+Zp00               = $00 ; PPUCTRL shadow register
+Zp01               = $01 ; PPUMASK shadow register
+Zp02               = $02 ; VBlank flag (set by NMI, cleared by WaitForVBlank)
+Zp03               = $03 ; Frame counter / NMI tick counter
+Zp05               = $05 ; Score/digit temp
+Zp06               = $06 ; Pad 1 state byte 1 (shifted pad data)
+Zp07               = $07 ; Pad 1 state byte 2
+Zp08               = $08 ; Pad 1 state byte 3
+Zp09               = $09 ; Pad 1 state byte 4
+Zp0A               = $0A ; Pad 2 state byte 1
+Zp0B               = $0B ; Pad 2 state byte 2
+Zp0C               = $0C ; Pad temp / swap variable
+Zp0D               = $0D ; Pad mode / draw flag
+Zp0E               = $0E ; Shift counter / temp
+Zp0F               = $0F ; Delay counter
+Zp10               = $10 ; VRAM pointer low byte (indirect)
+Zp11               = $11 ; VRAM pointer high byte (indirect)
+Zp12               = $12 ; Score digit 1 accumulator
+Zp13               = $13 ; Score digit 2 accumulator
+Zp14               = $14 ; Score digit 3 accumulator
+Zp15               = $15 ; Score digit 4 accumulator
@@ -0,0 +1,94 @@
+al 00E548 .Label_E548
+al 00E53A .ClearScreen
+al 00E534 .ClearAPUNoise
+al 00E52E .SetAPUNoise
+al 00E522 .Label_E522
+al 00E514 .Label_E514
+al 00E52D .ProcessPadBitsDone
+al 00E509 .Label_E509
+al 00E4FA .ProcessPadBits
+al 00E4B4 .PadBitTableLives
+al 00E4AA .LoadPatternTable7
+al 00E4A0 .LoadPatternTable6
+al 00E49F .UpdatePadsDone
+al 00E48F .Label_E48F
+al 00E47F .UpdatePads
+al 00E47A .Label_E47A
+al 00E471 .Label_E471
+al 00E46F .ShiftVar4
+al 00E46A .Label_E46A
+al 00E45F .Label_E45F
+al 00E459 .ShiftVar3
+al 00E454 .Label_E454
+al 00E44B .Label_E44B
+al 00E449 .ShiftVar2
+al 00E444 .Label_E444
+al 00E439 .Label_E439
+al 00E433 .ShiftVar1
+al 00E424 .Label_E424
+al 00E42F .Label_E42F
+al 00E41E .Label_E41E
+al 00E407 .DrawLives
+al 00E3F8 .Label_E3F8
+al 00E403 .Label_E403
+al 00E3F5 .Label_E3F5
+al 00E3E1 .DrawScore
+al 00E3D8 .Label_E3D8
+al 00E3D1 .Label_E3D1
+al 00E3C3 .Label_E3C3
+al 00E3B5 .Label_E3B5
+al 00E3AE .Label_E3AE
+al 00E3A0 .Label_E3A0
+al 00E398 .ProcessPads
+al 00E37F .Label_E37F
+al 00E362 .ShiftPads
+al 00E35B .Label_E35B
+al 00E34D .Label_E34D
+al 00E361 .ReadPadDone
+al 00E338 .ReadPad
+al 00E32D .ClearGameVars
+al 00E326 .Label_E326
+al 00E312 .Label_E312
+al 00E2FE .Label_E2FE
+al 00E2F0 .ClearRows
+al 00E2B0 .DrawPlayer2Pad
+al 00E270 .DrawPlayer1Pad
+al 00E236 .InitRoundParams
+al 00E22D .ResetScroll
+al 00E219 .SetPPUCTRL_NMI
+al 00E1FB .DisableNMI
+al 00E1F1 .EnableNMI
+al 00E1E3 .Label_E1E3
+al 00E1F0 .VramWriteDone
+al 00E1D2 .Label_E1D2
+al 00E1CC .VramWrite
+al 00E1C2 .LoadPatternTable5
+al 00E1B8 .LoadPatternTable4
+al 00E1AE .LoadPatternTable3
+al 00E1A4 .LoadPatternTable2
+al 00E19A .LoadPatternTable1
+al 00E187 .ClearVRAM_FillFF
+al 00E16B .InitAPU
+al 00E164 .Label_E164
+al 00E150 .Label_E150
+al 00E142 .ClearVRAM_Fill23
+al 00E141 .ClearPaletteDone
+al 00E121 .PaletteData
+al 00E113 .Label_E113
+al 00E107 .LoadPalette
+al 00E0FB .Label_E0FB
+al 00E0EB .ClearVRAM
+al 00E0DD .Label_E0DD
+al 00E0CF .Label_E0CF
+al 00E0C9 .ClearRAM
+al 00E0B5 .Label_E0B5
+al 00E0B0 .Label_E0B0
+al 00E09B .ResetInit
+al 00E092 .WaitForVBlank
+al 00E06E .NmiHandler
+al 00E068 .Label_E068
+al 00E058 .Label_E058
+al 00E02F .Label_E02F
+al 00E02B .Label_E02B
+al 00E01E .Label_E01E
+al 00E000 .Reset
@@ -0,0 +1,32 @@
+Modules list:
+-------------
+header.o:
+    HEADER            Offs=000000  Size=000010  Align=00001  Fill=0000
+prg.o:
+    PRG               Offs=000000  Size=004000  Align=00001  Fill=0000
+chr.o:
+    CHR               Offs=000000  Size=002000  Align=00001  Fill=0000
+
+
+Segment list:
+-------------
+Name                   Start     End    Size  Align
+----------------------------------------------------
+CHR                   000000  001FFF  002000  00001
+HEADER                000000  00000F  000010  00001
+PRG                   00C000  00FFFF  004000  00001
+
+
+Exports list by name:
+---------------------
+
+
+
+Exports list by value:
+----------------------
+
+
+
+Imports list:
+-------------
+
@@ -0,0 +1 @@
+../rom.nes
@@ -0,0 +1,108 @@
+; =============================================================================
+; Nintendo Entertainment System hardware symbols
+; =============================================================================
+
+; -----------------------------------------------------------------------------
+; PPU registers
+; -----------------------------------------------------------------------------
+
+PPUCTRL             = $2000
+PPUMASK             = $2001
+PPUSTATUS           = $2002
+OAMADDR             = $2003
+OAMDATA             = $2004
+PPUSCROLL           = $2005
+PPUADDR             = $2006
+PPUDATA             = $2007
+
+OAMDMA              = $4014
+
+; -----------------------------------------------------------------------------
+; Controller ports
+;
+; $4016:
+;   Write: controller strobe
+;   Read:  controller port 1
+;
+; $4017:
+;   Read:  controller port 2
+;   Write: APU frame counter
+; -----------------------------------------------------------------------------
+
+JOY1                = $4016
+JOY2                = $4017
+
+; -----------------------------------------------------------------------------
+; APU pulse channel 1
+; -----------------------------------------------------------------------------
+
+APUPULSE1CTRL       = $4000
+APUPULSE1SWEEP      = $4001
+APUPULSE1TIMERLO    = $4002
+APUPULSE1TIMERHI    = $4003
+
+; -----------------------------------------------------------------------------
+; APU pulse channel 2
+; -----------------------------------------------------------------------------
+
+APUPULSE2CTRL       = $4004
+APUPULSE2SWEEP      = $4005
+APUPULSE2TIMERLO    = $4006
+APUPULSE2TIMERHI    = $4007
+
+; -----------------------------------------------------------------------------
+; APU triangle channel
+; -----------------------------------------------------------------------------
+
+APUTRIANGLECTRL     = $4008
+APUTRIANGLETIMERLO  = $400A
+APUTRIANGLETIMERHI  = $400B
+
+; -----------------------------------------------------------------------------
+; APU noise channel
+; -----------------------------------------------------------------------------
+
+APUNOISECTRL        = $400C
+APUNOISEPERIOD      = $400E
+APUNOISELENGTH      = $400F
+
+; -----------------------------------------------------------------------------
+; APU DMC channel
+; -----------------------------------------------------------------------------
+
+APUDMCCTRL          = $4010
+APUDMCDIRECT        = $4011
+APUDMCADDR          = $4012
+APUDMCLENGTH        = $4013
+
+; -----------------------------------------------------------------------------
+; APU status and frame counter
+;
+; $4015:
+;   Write: enable or disable the five APU channels
+;   Read:  channel and interrupt status
+;
+; $4017:
+;   Write: APU frame-counter mode and IRQ inhibit
+;   Read:  controller port 2
+; -----------------------------------------------------------------------------
+
+APUSTATUS           = $4015
+APUFRAMECOUNTER     = $4017
+
+; -----------------------------------------------------------------------------
+; Controller masks
+; -----------------------------------------------------------------------------
+
+PAD_RIGHT           = $01
+PAD_LEFT            = $02
+PAD_DOWN            = $04
+PAD_UP              = $08
+PAD_START           = $10
+PAD_SELECT          = $20
+PAD_B               = $40
+PAD_A               = $80
+
+PAD_HORIZONTAL      = PAD_LEFT | PAD_RIGHT
+PAD_VERTICAL        = PAD_UP | PAD_DOWN
+PAD_DPAD            = PAD_HORIZONTAL | PAD_VERTICAL