retroDE_ps2/docs/ch289_closeout.md

# Ch289 closeout — syscall 0x78 HLE + runner-side observer; next is syscall 0x12 (handler install)

**Status:** Closed. **Verdict from re-running qbert.elf:**
`elf_first_unhandled_syscall (pc=0x00112A54 $v1=0x12 (=18))`.
qbert advanced 27,920 → **27,930 retires (+10)** through the
Ch289 syscall and into the next one. The new runner-side observer
worked first try:

```
syscall_0x78 = seen=1 count=1 first_pc=0x00112aa4
  $a0=0x00000000 $a1=0x00130000 $a2=0x20000000 $a3=0x001328c0 → $v0=0
```

count=1 means qbert called syscall 0x78 exactly once, took our
$v0=0 return, and continued. No tight loop or error branch — the
return shape is good for at least the first occurrence.

## What landed

### Dispatcher case — `rtl/ee/ee_core_stub.sv`

One new case in the existing Ch273 HLE switch, identical shape to
Ch285's 0x40 case:

```sv
32'h0000_0078: begin
    regfile[2]   <= 32'd0;
    gpr128[2]    <= 128'd0;
    pc           <= pc + 32'd4;
    retire_pulse <= 1'b1;
    state        <= S_IFETCH_REQ;
end
```

### Focused TB extension — `tb_ee_core_syscall_hle.sv`

The same mechanical pattern used for the Ch285 0x40 extension:
4 new BIOS slots (`S_ORI_V1_78` / `S_SYS_78` / `S_BNE_78` /
`S_DS_78`), a new latch group (`v0_after_78` / `seen_78_return`),
a new init in the initial block, a new arm in the trace
always_ff, a new post-halt assertion, and a new field in the final
display. The UN/FAIL slot indices bumped by 4. The TB now covers
five known syscall numbers (3C / 3D / 40 / 64 / 78) plus the
unknown-halt path.

Result: `retired=25 halt=1 trap=0 errors=0 PASS`. Final display:
```
$v0_after_3C=0x001e0000 $v0_after_3D=0x00000000 $v0_after_64=0x00000000 $v0_after_40=0x00000000 $v0_after_78=0x00000000 $v1_at_halt=0x00007777
```

### Runner-side observer — `tb_ee_core_elf_runner.sv`

Per Codex's "named trace/log line for syscall 0x78" ask, a small
observer block captures the first occurrence of the syscall during
the qbert run:

```sv
if (core_ev_valid && u_core.retired_instr == 32'h0000_000C
                  && u_core.regfile[3] == 32'h0000_0078) begin
    syscall_0x78_count <= syscall_0x78_count + 1;
    if (!seen_syscall_0x78) begin
        seen_syscall_0x78     <= 1'b1;
        syscall_0x78_first_pc <= u_core.retired_pc;
        syscall_0x78_first_a0 <= u_core.regfile[4];
        ...
    end
end
```

And a SUMMARY line:
```
[tb_ee_core_elf_runner]   syscall_0x78 = seen=1 count=1 first_pc=0x00112aa4
  $a0=0x00000000 $a1=0x00130000 $a2=0x20000000 $a3=0x001328c0 → $v0=0
```

Pattern is extensible: any future HLE'd syscall whose arg shape
matters can drop a parallel observer block in. Each new tracked
syscall costs ~10 LOC: declarations, init, observer, summary line.

## qbert progression

| Chapter | Blocker | retire_count |
|---|---|---|
| Post-Ch286 (EI)             | unmapped 0x1000E010 D_STAT | 27,907 |
| Post-Ch287 (DMAC ctrl)      | unmapped 0x1000C000 ch4    | 27,912 |
| Post-Ch288 (DMAC passive)   | syscall $v1=0x78 at 0x00112AA4 | 27,920 |
| **Post-Ch289 (syscall 0x78)** | **syscall $v1=0x12 at 0x00112A54** | **27,930** |

Three chapters in a row each in the +5 to +10 range — qbert is
sweeping through its kernel-init sequence one HLE call at a time.

## Ch290 framing — syscall 0x12

Args at halt (the new blocker):
- `$v1 = 0x12` (= 18 decimal)
- `$a0 = 0x00000005` — small int. Likely an IRQ number, priority,
  or handler slot index.
- `$a1 = 0x00112AB0` — falls in code segment (qbert main range
  was around 0x00112xxx). Almost certainly a **function pointer**.
- `$a2 = 0x00000000` — null/context.
- `$a3 = 0x001328C0` — data pointer (consistent with the
  $a3 seen in 0x78 and earlier syscalls — looks like a global
  context block).

Shape: `(int small_id, fn_ptr handler, void* ctx0, void* ctx1)` —
this is the classic **handler-install** pattern. PS2 standard
syscall table cites names like `AddIntcHandler` (syscall 16/0x10),
`RemoveIntcHandler` (syscall 17/0x11), and **`AddDmacHandler`**
(syscall 18/0x12) in this range — so $a0=5 is plausibly a DMAC
channel number (we landed in the DMAC region last chapter; channel
5 = SIF0).

Per the Ch285 precedent: first pass returns `$v0 = 0` ("handler
installed OK") and PC += 4. If qbert misbranches downstream, the
fallback shapes to try are: $v0 = $a0 (returns the slot index for
later RemoveIntcHandler), or $v0 = some non-zero handle. The
runner-side observer pattern from Ch289 makes the diagnostic cheap.

## Files changed

- `rtl/ee/ee_core_stub.sv` — one new HLE case (~10 LOC).
- `sim/tb/integration/tb_ee_core_syscall_hle.sv` — extended with
  syscall 0x78 case (slots / latch / assertion / display).
- `sim/tb/integration/tb_ee_core_elf_runner.sv` — syscall_0x78
  observer + SUMMARY line.

No new TB, no new Makefile target; regression count unchanged at
**175/175**.

## Pattern review (19 chapters)

| Ch  | Blocker      | Pattern |
|-----|--------------|---------|
| 271..286 | opcodes | opcode-era |
| 287 | DMAC ctrl MMIO | NEW MMIO stub |
| 288 | DMAC passive   | REUSE Ch287 pattern |
| **289** | **syscall 0x78** | **REUSE Ch273/285 dispatcher** |

Two narrow HLE extensions in five chapters (Ch285 + Ch289). The
Ch273 dispatcher's switch-by-$v1 architecture continues to absorb
new cases with minimal cost. The new runner-side observer pattern
is a small upgrade that pays for itself the first time a syscall
return value is wrong — instead of re-reading the trace file, the
SUMMARY block tells you immediately what qbert handed the kernel.

## Regression

**175/175 PASS** (unchanged from Ch288; no new TB added in this
chapter, existing tb_ee_core_syscall_hle extended in place and
runner observer added).