# Ch273 closeout — minimal EE syscall HLE; qbert clears its kernel-call prolog, next blocker is BEQL

**Status:** Closed. Codex's spec implemented exactly: minimal
HLE dispatcher for three crt0 syscalls (`EndOfHeap`,
`InitMainThread`, `FlushCache`), gated behind a parameter so
existing TBs are unaffected. **Verdict from re-running
qbert.elf:** `elf_first_unsupported_opcode (pc=0x001000C0
instr=0x50600004)` — **BEQL** (branch on equal likely), MIPS-II.
That frames Ch274.

## Numbers across the opcode/syscall chapters

| Chapter | Blocker | qbert retire_count | Verdict |
|---------|---------|---------------------|---------|
| Ch270 (init)     | SQ at 0x00100024     | 12       | first_unsupported_opcode |
| Post-Ch271 (SQ)  | DADDU at 0x00100068  | 26,958   | first_unsupported_opcode |
| Post-Ch272 (DADDU) | SYSCALL at 0x00100070 | 26,960 | `elf_halted` |
| **Post-Ch273 (SYSCALL HLE)** | **BEQL at 0x001000C0** | **26,980** | **`elf_first_unsupported_opcode`** |

20 more retires this chapter: all 3 syscalls dispatched, the
prolog used the returns to set up `$sp` and a small initializer-
table walker, and the trap fires at the FIRST instruction the
crt0 emits that we don't decode — `BEQL`.

## What landed

### RTL — 2 surgical additions in `ee_core_stub.sv`

1. **Parameter**: `EE_SYSCALL_HLE_ENABLE` (default `1'b0`) +
   `SYSCALL_HEAP_END` (default `32'h001E_0000`). Default-off so
   every existing TB whose `syscall` is a "halt-PASS-marker"
   (addi/slti/etc.) keeps its semantics.
2. **Dispatcher**: new `else if (EE_SYSCALL_HLE_ENABLE)` branch
   after the Ch199 special case. `case (regfile[3])` on `$v1`:

   | `$v1` | name           | `$v0` returned       | resume      |
   |-------|----------------|-----------------------|-------------|
   | 0x3C  | EndOfHeap      | `SYSCALL_HEAP_END`   | PC + 4      |
   | 0x3D  | InitMainThread | 0                     | PC + 4      |
   | 0x64  | FlushCache     | 0                     | PC + 4      |
   | other | (unhandled)    | (none)                | **halt**    |

   `pc <= pc + 4` (per Codex's correction — this is normal
   user-code SYSCALL resume, NOT RFE; RFE is Ch199's path).

### Focused TB — `tb_ee_core_syscall_hle`

Four cases:
1. `syscall` with `$v1=0x3C` → verify `$v0 = 0x001E0000`
2. `syscall` with `$v1=0x3D` → verify `$v0 = 0`
3. `syscall` with `$v1=0x64` → verify `$v0 = 0`
4. `syscall` with `$v1=0x7777` → verify HALT (PASS marker)

Independent verification: captures `$v0` at the cycle AFTER each
known syscall retires AND runs a `BNE $v0, expected, FAIL` chain.
Both must agree. Final PC + `$v1=0x7777` post-halt confirms we
landed on the unhandled-syscall path correctly.

Result: `retired=17 halt=1 trap=0 errors=0 PASS`.

### Runner update — `tb_ee_core_elf_runner.sv`

- Wires `EE_SYSCALL_HLE_ENABLE=1` on the ee_core_stub.
- Halt-time SUMMARY now includes the live register snapshot:
  ```
  saw_halt = 1  at_pc=0x... $v1=0x... $a0=0x... $a1=0x... $a2=0x... $a3=0x...
  ```
- New verdict shape `elf_first_unhandled_syscall` when the halt
  is on a `0x0000000C` instruction with unknown `$v1`. (For this
  qbert run, the dispatcher handled all 3 and the trap was a
  separate opcode issue — but the verdict shape is ready for
  whenever the next unknown SYSCALL surfaces.)

### Makefile

- `tb_ee_core_syscall_hle` target.
- Added to both regression lists.
- Regression: 160 → **161**.

## Codex Ch273 acceptance — line-by-line

| Requirement                                                                | Status |
|----------------------------------------------------------------------------|--------|
| Minimal HLE handler in ee_core_stub for normal user-mode SYSCALL           | ✅     |
| $v1=0x3C EndOfHeap → conservative top-of-RAM, PC+=4                         | ✅     |
| $v1=0x3D InitMainThread → success ($v0=0), no scheduler mutation, PC+=4    | ✅     |
| $v1=0x64 FlushCache → no-op success, PC+=4                                  | ✅     |
| **Not RFE — PC = syscall PC + 4**                                           | ✅     |
| Unhandled $v1 still halts; TB can read $v1/$a0-$a3 for verdict             | ✅     |
| Focused TB: 3 syscalls in sequence + 1 unknown-fallback                     | ✅     |
| Regression unchanged for default-off                                        | ✅     |
| Re-run qbert, report next blocker                                           | ✅     |

## qbert disassembly around the new blocker

```
0x001000A0: lui   $v0, 0x0013          ; $v0 = 0x00130000
0x001000A4: addiu $v0, $v0, 0xC800     ; $v0 = 0x0012C800
0x001000A8: lw    $v1, 0($v0)          ; $v1 = mem[0x0012C800]
0x001000AC: bne   $v1, $0, +7*4        ; skip ahead if non-zero
0x001000B0: nop                         ; delay
0x001000B4: lui   $v0, 0x0013
0x001000B8: addiu $v0, $v0, 0xC944     ; $v0 = 0x0012C944
0x001000BC: lw    $v1, 0($v0)          ; $v1 = mem[0x0012C944]  (= 0 per halt $v1=0)
0x001000C0: beql  $v1, $0, +4*4        ; <-- TRAPS HERE
0x001000C4: addiu $a0, $0, 0           ; delay slot (squashed if BEQL not taken)
0x001000C8: addiu $v0, $v1, 4
0x001000CC: lw    $a0, 0($v0)
0x001000D0: addiu $a1, $v0, 4
0x001000D4: jal   <constructor table walker>
```

This is the C++ static-constructor walker (or a similar
initialization table). The BEQL checks whether the table head
pointer is null — and **branch-likely semantics are
load-bearing**: the delay slot at `0x001000C4` clobbers `$a0`
to 0 only if the branch is taken. If we naïvely decode BEQL as
plain BEQ, the delay slot would execute on the not-taken path
too, silently corrupting `$a0`.

## Recommendation for Codex's Ch274

**Implement BEQL with proper "squash on not-taken" semantics.**

MIPS-II "branch likely" family: BEQL (0x14), BNEL (0x15), BLEZL
(0x16), BGTZL (0x17), and REGIMM BLTZL/BGEZL/BLTZALL/BGEZALL.
Compilers (especially older PS2 SDK gcc with `-fmoveloop-invariants`
or default for-loops) emit these as the canonical loop branch.

Three Ch274 framings, in order of scope:

1. **BEQL only.** Smallest change. Decode `is_beql`, share
   `branch_taken` logic with BEQ (rs==rt), but unlike BEQ, when
   not taken: PC += 8 (skip both the branch and its delay slot),
   no delay-slot execute. Adds `is_branch_likely` distinction
   in the retire/PC-advance logic.
2. **BEQL + BNEL** (the two most common). BNEL is the inverse
   condition (rs!=rt); same likely semantics. Both surface as
   `0x14` (BEQL) and `0x15` (BNEL) opcodes.
3. **Full branch-likely family.** BEQL/BNEL/BLEZL/BGTZL + REGIMM
   variants. Bigger surface; usually you only need 1–2 of these
   per chapter until qbert/a later ELF surfaces another.

**My read: (1) — BEQL only.** Same one-question-one-chapter
pattern. The next blocker after BEQL might or might not be
BNEL; let the runner pick.

The implementation hook: existing ee_core_stub has
`branch_pending` + `instr_in_delay_slot` + a `branch_taken`
combinational signal. For BEQL we need to gate "set
branch_pending + queue delay-slot execution" on `branch_taken`,
and on not-taken just `pc <= pc + 8` directly (skip the delay
slot). Probably a 5–8 line change.

Focused TB: 3 cases mirroring Ch272 shape —
- BEQL taken: `$v1==$0`, target reached, delay slot executed
  (writes $a0 to a sentinel value).
- BEQL not-taken: `$v1!=$0`, target NOT reached, delay slot
  squashed (sentinel value NOT written; the original $a0
  preserved).
- Cross-check vs BEQ: identical inputs through a BEQ should
  produce different $a0 on the not-taken case (BEQ's delay
  slot fires).

## Files changed

- `rtl/ee/ee_core_stub.sv` — 2 surgical additions (parameter +
  dispatcher case statement, ~30 LOC).
- `sim/tb/integration/tb_ee_core_syscall_hle.sv` — new focused TB.
- `sim/tb/integration/tb_ee_core_elf_runner.sv` — enable
  `EE_SYSCALL_HLE_ENABLE`; new halt-time register snapshot;
  `elf_first_unhandled_syscall` verdict shape.
- `sim/Makefile` — target + both regression lists.

## Regression

In flight; expected **161/161** (was 160, +1 for
`tb_ee_core_syscall_hle`).

## Process notes

- **Codex's PC+4 correction was right.** My initial closeout
  draft for Ch272 suggested "RFE-style return" — Codex caught
  it. RFE is for the Ch199 `_ReturnFromException` path; normal
  user-mode `syscall` resumes at PC+4, no Status stack pop.
  Filed this in the memory entry so a future chapter doesn't
  repeat the same wrong assumption.
- **Parameter gating is the right call.** Existing TBs that use
  `syscall` as a halt-PASS-marker would have broken if their
  `$v1` happened to be 0x3C/0x3D/0x64. Gating preserved 160
  passing tests trivially; only the ELF runner opts in.
- **The verdict shape now distinguishes 4 halts**: trap (strict
  opcode), unmapped MMIO, halt-on-syscall (with $v1/$a0..$a3),
  halt-on-other (unexpected). The runner is becoming a real
  triage tool.
