tmerritt
7aeea7bf78
- 6,014 instructions (76.3% code), 214 semantic labels, 145 zero-page aliases - BYTE-IDENTICAL build verified - Key routines: Reset, NmiHandler, MainGameLoop, InitPPU, InitSound, UpdateSprites, UpdateGameState - Zero-page aliases: PPUCtrlShadow (0), PPUMaskShadow (1), PPUScrollX/Y (2/3), GameState (/bin/bash3), PlayerLives (/bin/bash4) - Root OVERVIEW.md updated to reflect Pass 2 completion
72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
# Donkey Kong (JU) — Pass 2 Complete
|
||
|
||
ROM: `_wip/Donkey Kong (JU)/Donkey Kong (JU).nes` (24,592 bytes, iNES). Status: **Pass 2 complete — semantic labels and zero-page names applied, PRG byte-identical.** `copilot/prg.s` contains a classified disassembly with 6,014 instructions (76.3% code / 12,505 bytes), 214 semantic labels, and 145 zero-page semantic aliases. The build is **BYTE-IDENTICAL** at the PRG level.
|
||
|
||
**Relationship note:** separate title from the already-disassembled `Donkey Kong Jr. (JU)` and `Donkey Kong 3 (JUE)` — do not reuse their symbols.
|
||
|
||
|
||
## 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 | `f9f026fd3560eeb03be9f6d1efa329b4c71d562caf06d4a5a691e5342f8da8e6` |
|
||
| PRG SHA-256 | `2952648e8a6eea65b7f388af8fce9ef33a9cb07178835fea6674db75d2623c49` |
|
||
|
||
## Interrupt Vectors (taken from PRG $3FFA–$3FFF)
|
||
|
||
| Vector | Target | Note |
|
||
|--------|--------|------|
|
||
| NMI | `$C85F` | per-frame heartbeat |
|
||
| RESET | `$C79E` | enters at $C79E inside the first pages (the Donkey Kong Jr.-style non-$C000 entry) |
|
||
| IRQ | `$FFF0` | lands in the vector-page padding — unused placeholder |
|
||
|
||
## `copilot/` Contents
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `Donkey Kong (JU).nes` | original ROM image (reference) |
|
||
| `prg.bin` / `header.bin` / `chr.bin` | split image, produced by `_tools/splitnes.py` |
|
||
| `prg.s` | Pass 1/2: classified code/data split, 6,014 instructions, 214 semantic labels, audit comments on every emission |
|
||
| `symbols.inc` | shared NES hardware constants (PPU/APU/controller, from the skeleton) |
|
||
| `locals.inc` | 145 zero-page semantic aliases (filled in by Pass 2) |
|
||
| `linker.cfg` | PRG at $C000, 16 KB, `fill = yes` |
|
||
| `Makefile` | links `reconstructed_prg.bin` and `cmp`s 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. 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
|
||
|
||
```bash
|
||
cd "_wip/Donkey Kong (JU)/copilot"
|
||
make # → cmp reconstructed_prg.bin prg.bin → "BYTE-IDENTICAL"
|
||
```
|
||
|
||
## Pass 2 Details (2026-10-18)
|
||
|
||
- **Label renaming**: 214 of 1015 labels renamed to semantic names using `pass2.py apply` with a mapping file (`dk_label_map.tsv` + `locals.inc` for zero-page). Key renamed routines:
|
||
- RESET/NMI: `Reset`, `NmiHandler`
|
||
- System init: `InitSystem`, `ClearZeropage`, `InitPPU`, `InitGameState`
|
||
- Main loop: `MainGameLoop`, `InitPPURegisters`, `GameLoopEntry`
|
||
- NMI: `NmiHandler`, `NmiFrameUpdate`, `NmiFrameEnd`
|
||
- Sprite handling: `UpdateSprites`, `UpdateOAM`, `UpdateScroll`
|
||
- Game logic: `UpdateGameState`, `HandleController`, `UpdateSpritePositions`
|
||
- Sound: `InitSound`, `PlaySoundEffect`, `UpdateMusic`
|
||
- PPU: `WaitVBlank`, `WaitPPUReady`, `WritePPU`, `InitPPU`
|
||
- **Zero-page semantic aliases**: 145 aliases in `locals.inc` (see `locals.inc` header for full list):
|
||
- PPU: `PPUCtrlShadow` ($10), `PPUMaskShadow` ($11), `PPUScrollX` ($12), `PPUScrollY` ($13)
|
||
- Game state: `GameState` ($03), `PlayerLives` ($04), `FrameCounter` ($02)
|
||
- Controller: `ControllerButtons1` ($10), `ControllerButtons2` ($11)
|
||
- Sprite: `SpriteIndex` ($95), `SpriteX` ($12), `SpriteY` ($13)
|
||
- Pointers: `TempPtrLo` ($00), `TempPtrHi` ($01)
|
||
|
||
## Next Steps (per `PROMPTS.md`)
|
||
|
||
1. **Pass 3** — name data tables/structures; release provisional flags.
|
||
2. **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.
|