# 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 |