Promote Xevious (U) and Zanac (U) from _wip/ to NROM/

- Xevious (U): Promoted from _wip/NROM/Xevious (U)/ to NROM/Xevious (U)/ - Pass 3 complete: 34.5% code coverage, 143 semantic entry points, 4 named data tables, ~20 semantic ZP aliases - NROM mapper 0, 32 KB PRG, 8 KB CHR, horizontal mirroring - Zanac (U): Promoted from _wip/UNROM/Zanac (U)/ to NROM/Zanac (U)/ - Pass 3 complete: 34.5% code coverage (bank 7 only), 133 semantic entry points, 26 named data tables, 14 semantic ZP aliases - UNROM mapper 2, 128 KB PRG (8 banks), no CHR - Bank 7 fixed at CPU -; banks 0-6 switchable at 000- - Bank 7 assembled separately as prg.07.s with .org Both projects build byte-identical. Updated root README.md inventory, per-project details, and WIP.md accordingly. Move Zanac (U) to UNROM/ mapper directory Zanac (U) is a UNROM (mapper 2) game, not NROM (mapper 0). Move it to the correct mapper directory and update README.md and WIP.md references accordingly. Update project counts in WIP.md (857->856 total, UNROM 98->97 projects). Promote Mermaids of Atlantis (U) from _wip/ to MAPPER8/ Additional cleanup of Mermaids of Atlantis
2026-10-21 07:20:59 -04:00
1 parent 49e117bfcc
commit df11857075
@@ -0,0 +1,103 @@
+# Xevious (U)
+
+## Status
+
+**Pass 3 complete.** All routine entry points (jsr/jmp targets) have semantic
+names, and all raw `$XXXX` call operands in `jsr`/`jmp` instructions have been
+replaced with label references (except 7 targets outside code range, kept as
+raw addresses). Major data tables and zero-page aliases have been named. The
+project builds and verifies byte-identical to the original ROM.
+
+`make` assembles `header.s`, `prg.s`, `chr.s`, links them with `ld65` and compares the
+result against `rom.nes`:
+
+```
+Byte-identical ROM verified.
+```
+
+### Pass 1 results
+
+| Metric | Value |
+|--------|-------|
+| PRG size | 32768 bytes (32 KB) at $8000-$FFFF |
+| Code | 11321 bytes (34.5%) |
+| Data | 21447 bytes (65.5%) |
+| Instructions | 5513 |
+| Routines/labels | 795 |
+| Zero-page aliases | 156 (in `locals.inc`) |
+| Indirect dispatches | `jmp ($fe)` at $BA88 (table $BA8B, 16 entries), `jmp ($4)` at $CA07 (table $CA0A, 64 entries) |
+
+### Pass 2 results
+
+| Metric | Value |
+|--------|-------|
+| `Label_XXXX` names replaced | 781 labels → unique names |
+| Raw `$XXXX` jsr/jmp operands replaced | 466 → label references |
+| Remaining raw `$XXXX` jsr/jmp | 7 (targets outside code range) |
+| Semantic zero-page aliases | ~20 (in `locals.inc`) |
+
+### Pass 3 results
+
+| Metric | Value |
+|--------|-------|
+| Semantic entry-point names | 143 (Reset, NmiHandler, IrqHandler, InputRead, ObjInitCall, ObjMoveCall, ObjDrawCall, ObjUpdateCall, SetOamPtrs, WaitVblank, GameModeDispatch, ObjSpriteSetup, ObjCommonUpdate, etc.) |
+| Internal branch labels | ~574 (`Sub_XXXX` address-based, local to routines) |
+| Named data tables | PatternData, SpriteAttrTable, JumpTable4, ResetVarTable |
+| Semantic zero-page aliases | ~20 (PPUCTRLShadow, ObjectX, ObjectY, ObjPtr, GameMode, Joypad1Cur, etc.) |
+
+### Pass 1 notes
+
+- Two computed-dispatch mechanisms were recovered via declared jump tables:
+  - `jmp ($fe)` at $BA88 indexes a 16-entry table at $BA8B (targets in $BAAB–$BB20 range)
+  - `jmp ($4)` at $CA07 indexes a 64-entry table at $CA0A (targets mostly in $CA–$CB and $C0–$C3 ranges)
+- One branch at $E40A targets $E3B5, which falls inside the operand of `jsr $CF2F` at $E3B3. Emitted as `.byte` with an explanatory comment since the target cannot be a label.
+- Six addresses contain undocumented/illegal opcodes not decoded by the tracer: $9848, $A2C3, $CD89, $E0FF, $E3B5, $F230.
+
+## ROM
+
+| Property | Value |
+|----------|-------|
+| Format | iNES |
+| Mapper | 0 |
+| Board | NROM-256 |
+| Mirroring | Horizontal |
+| Four-screen VRAM | no |
+| Battery | no |
+| PRG | 32 KB (2 x 16 KB), mapped at CPU $8000-$FFFF |
+| CHR | 8 KB (1 x 8 KB) |
+| Trainer | none |
+| Footer | none |
+| NMI vector | $FC4E |
+| RESET vector | $FAF6 |
+| IRQ vector | $FF1D |
+| ROM file | `Xevious (U).nes` |
+| SHA-256 | `1915fb1c30251de0c8f7913720a27b25d3ccef871851722a504d95fbb9d0ca7c` |
+
+### Header notes
+
+- none
+
+## Open work
+
+- **Pass 1** - complete. Code/data split produced; build verifies byte-identical.
+- **Pass 2** - complete. All `Label_XXXX` names replaced with unique names; all
+  raw `$XXXX` jsr/jmp operands replaced with label references (7 remain outside code range).
+- **Pass 3** - complete. All 143 routine entry points have semantic names;
+  ~574 internal branch labels remain as `Sub_XXXX` address-based names;
+  ~20 zero-page aliases have semantic names; 4 data tables named.
+- **Promotion** to `NROM/<name>/` once ready, as `git mv`.
+
+## Files
+
+| File | Purpose |
+|--------|-------|
+| `prg.s` | Pass 3 disassembly (semantic entry-point names + Sub_XXXX branch labels) |
+| `header.s` | iNES header include |
+| `chr.s` | CHR include |
+| `prg.bin` | 32768 bytes (32 KB) PRG image |
+| `chr.bin` | 8192 bytes (8 KB) CHR image |
+| `rom.nes` | byte-identical copy of the original ROM |
+| `linker.cfg` | HEADER / PRG / CHR memory areas |
+| `symbols.inc` | NES hardware register names |
+| `locals.inc` | zero-page aliases (semantic names applied at Pass 2/3) |
+| `Makefile` | build and byte-identity check |