retroDE_ps2/docs/ch270_closeout.md

# Ch270 closeout — BIOS-bypass EE ELF runner; synthetic test passes

**Status:** Closed. Ch270 is the framework chapter — the first time
this core executes "real code at a real entry point" through a
generic loader rather than a hardcoded BIOS path. The synthetic
test passes; the verdict shape is exactly what Codex framed; the
infrastructure is reusable for real PS2 ELFs.

**Synthetic verdict:** `elf_timeout_with_hot_pc` with
`hot_pc = 0x80100010 (count=128 / ring=256)`. The hot PC matches
the J-self instruction in the synthetic 5-instruction loop, and
the 128/256 ratio matches the J + delay-slot NOP pair retiring 1:1.

## What landed

### Tools
- `tools/generate_synthetic_image.py` — emits a tiny EE-RAM image
  (4 MIPS instructions + NOPs) and a manifest (entry, stack-top)
  in iverilog `$readmemh` format. No external dependencies. The
  generated image places code at PHYS `0x00100000` with entry at
  kseg0 VA `0x80100008` (real PS2 ELFs use kseg0 too, because the
  ee_memory_map_stub routes useg to a separate shadow region).
- `tools/elf_to_eeram.py` — minimal ELF32-LE-MIPS converter:
  parses PT_LOAD segments, strips kseg/kuseg alias bits (low 29
  bits of p_vaddr → phys offset), emits the same `image.hex` +
  `manifest.hex` pair. Pure stdlib (struct module), no pyelftools.

### Testbench
- `sim/tb/integration/tb_ee_core_elf_runner.sv` — instantiates
  `ee_core_stub` with `STRICT_UNSUPPORTED=1` + `ee_memory_map_stub`
  + 2 MiB `ee_ram_stub` + `bios_rom_stub`. Bootstrap: TB pokes a
  4-instruction trampoline at `0xBFC00000` (LUI/ORI/JR/NOP) that
  loads the ELF entry into `$at` and jumps. Then a 50 ms watchdog
  + live-latch trackers for: `entry_reached`, first strict trap
  (PC + instr), first unmapped MMIO (EA + PC), halt, and a hot-PC
  histogram over the last 256 retires (chosen per
  [[feedback-observer-design-for-lineage]] — bounded ring with
  trigger-time read, not a fill-from-boot array).

5-way verdict:

| Verdict                         | Meaning                                        |
|---------------------------------|------------------------------------------------|
| `elf_first_unsupported_opcode`  | strict trap on a missing decode → Ch271+ adds the opcode |
| `elf_first_unmapped_mmio`       | ev_arg3 == REGION_UNMAPPED → Ch271+ adds the device stub |
| `elf_halted`                    | core asserted halt_o; ELF ran a HALT pattern   |
| `elf_timeout_with_hot_pc`       | watchdog fired; reports the most-retired PC of the last 256 |
| `elf_entry_unreached` / `elf_no_retires` | bootstrap failure; fail fast        |

Verdict precedence enforces "first decisive event wins": strict
trap > unmapped MMIO > halt > timeout > bootstrap diagnostics.

### Makefile
- `tb_ee_core_elf_runner` (default, synthetic) — regenerates the
  synthetic image via Python on each build (cheap; Python emits in
  < 1s).
- `tb_ee_core_elf_runner_real ELF=/path/to/game.elf` — converts the
  user-supplied ELF and runs it. The exact same TB, just different
  input.
- Added to both PHONY list (line 407) and the `run:` master list
  (line 2337) per the dual-list rule in
  [[feedback-makefile-two-lists]].

## Synthetic test result

```
[tb_ee_core_elf_runner] elf_entry=0x80100008 elf_stack_top=0x801ffff0
[tb_ee_core_elf_runner] BIOS trampoline @0xBFC00000:
  lui $1, 0x8010
  ori $1, $1, 0x0008
  jr  $1
  nop
[tb_ee_core_elf_runner] SUMMARY:
  elf_entry           = 0x80100008
  entry_reached       = 1
  retire_count        = 1666665
  saw_trap            = 0
  saw_unmapped_mmio   = 0
  saw_halt            = 0
  hot_pc              = 0x80100010 (count=128 / ring=256)
[tb_ee_core_elf_runner] verdict=elf_timeout_with_hot_pc (...)
```

- **1.67M instructions retired in 50 ms sim time.** The synthetic
  loop is a 2-instruction body (J self + delay-slot NOP), so
  retires_per_loop_cycle ≈ 1.67M / 50 ms / 2 = ~16.7 cycles per
  loop iteration. Per the existing
  [[reference-ee-core-stub-timing]] memory (18 cyc/iter for a
  similar tight loop), this is right in band.
- **`saw_unmapped_mmio = 0`** means the EE never accessed
  anything outside the EE RAM region — the J self loop confines
  execution to two known instructions.
- **hot_pc = 0x80100010 (the J), count=128 / ring=256** — exactly
  half the ring is the J PC, the other half is the delay-slot PC
  at 0x80100014. Confirms the loop is the dominant flow.

## What this enables

The runner is now ready for **real PS2 ELFs**. Run:

```
make tb_ee_core_elf_runner_real ELF=/path/to/game.elf
```

…and the first verdict will be one of:

- `elf_first_unsupported_opcode (pc=... instr=...)` — Ch271 implements
  the missing opcode. This is the **incremental-growth path** that
  built BIOS support; same pattern now applies to game code.
- `elf_first_unmapped_mmio (ea=... pc=...)` — Ch271 adds a region
  stub. Most likely candidates for first hit on a real game ELF:
  EE timers, EE GS_PRIV, VIF0/VIF1, DMAC channels we haven't
  mapped, scratch/SPRAM.
- `elf_timeout_with_hot_pc` with a non-loop hot PC — the game is
  in a wait-for-service loop (libpad/libcdvd polling), which
  guides what subsystem to model next.

Codex's framing was right: the first real-ELF blocker is more
informative than another BIOS-flow autopsy, because it tells us
which subsystem to model in priority order driven by what real
software actually exercises.

## Bumps hit during implementation (and notes for future TBs)

1. **iverilog 12: `@(posedge clk)` inside `always_ff` is illegal.**
   The first compile attempt used `always_ff` for the "watch for
   decisive event then $finish" block, with an extra
   `@(posedge clk)` inside for trace-sink flush. iverilog errored.
   Fix: use plain `always @(posedge clk)` (not `always_ff`) when
   the block needs multiple event controls. Saved as a one-line
   note here because the broader pattern was already covered by
   [[feedback-observer-design-for-lineage]].

2. **EE memory map routes useg (top bit 0) to a separate
   shadow.** Initial synthetic test used `entry = 0x00100008`
   (kuseg). The TB loaded code into `ee_ram` at PHYS 0x100000,
   but the EE core fetching VA 0x00100008 saw zeros from the
   useg_shadow region (a Ch33 de-aliasing decision documented
   in `ee_memory_map_stub.sv`). Switched the synthetic entry to
   `0x80100008` (kseg0) so the fetch is routed to ee_ram via
   phys-strip. **Real PS2 ELFs use kseg0 for their text segment
   anyway** — this matches reality. The
   `tools/elf_to_eeram.py` converter already strips alias bits
   to compute phys placement, so it works for either kseg0 or
   kuseg entries — only the synthetic generator's default
   needed updating.

3. **Trampoline at 0xBFC00000 instead of `PC_RESET` override.**
   ee_core_stub does have a `PC_RESET` parameter, but it's
   elaboration-time only. To keep the runtime ELF entry
   selectable via plusarg, the TB pokes a LUI/ORI/JR trampoline
   into bios_rom's writeable `mem` array (sim-only hierarchical
   access). EE boots at `0xBFC00000`, runs the 3-instruction
   trampoline, and jumps to the ELF entry. Same technique the
   existing addi/slti TBs use to install instruction images.

## Regression

Adding `tb_ee_core_elf_runner` to the run: list bumps the
expected PASS count from 157 to 158. Regression in flight.

## Recommendation for Codex's Ch271 call

The synthetic test is the framework smoke. The real signal is
what happens when a user-supplied game ELF lands:

> `make tb_ee_core_elf_runner_real ELF=<game.elf>`

Whatever verdict that emits is Ch271's framing. If
`elf_first_unsupported_opcode`, implement that opcode. If
`elf_first_unmapped_mmio`, add that region stub. The chapter is
one question — "what's the first blocker?" — and the verdict
answers it.

**Standing by for the first real ELF run.** The user can supply
any PS2 ELF — a homebrew demo, an extracted SLUS/SCUS executable
from a disc image, or a small libtoolchain test binary. The
framework treats them all identically; the verdict tells us
where to spend Ch271.