# Dynamic handler install — RAM 0xCF0 (and friends)

This document describes a class of BIOS behavior that requires special
runtime handling: **the BIOS writes MIPS instructions into kernel RAM
at runtime and then transfers control to those addresses.** A pure
static recompiler cannot follow this — only the runtime-installed
instructions do the dispatch — so PSXRecomp v4 maintains a small MIPS
interpreter for "dirty" RAM pages.

## The concrete case: SIO data-byte handler

When a memcard read command is in flight, the BIOS needs to read 128
bytes of sector data byte-by-byte over SIO. It does this not via the
chain dispatcher (which only has 13 handler slots), but via a stub
installed at RAM 0xCF0 that runs once per SIO IRQ.

### Install path

The function at ROM 0xBFC15EBC is the install entry. It:

1. Clears `mem[0x75c0] = 0` (the "data-mode active" flag).
2. Copies four words from RAM 0x6408 (= ROM 0xBFC15F08) to
   RAM 0xCF0..0xCFC. Those four words are:

   ```
   lui   v0, 0x0
   addiu v0, v0, 0x641C
   jalr  v0
   nop
   ```

   At runtime this resolves to `v0 = 0x641C` (the data-byte handler in
   RAM, which is ROM 0xBFC15F1C reached via the kernel's part-2 RAM
   image), then `jalr v0`. The `nop` is the delay slot.

3. Tail-jumps to a B0 vector trampoline at RAM 0x6A70.

The companion entry at ROM 0xBFC15E80 is the "set [0x75c0] = 1"
function (B0:0x80), which R11 calls on success at the end of the
read-protocol setup phase.

### Dispatch path

When an SIO IRQ fires, the kernel exception handler at RAM 0xC80
(= ROM 0xBFC10780) runs. It saves registers, calls a helper at
RAM 0xEA0, masks the cause register, and (for non-syscall causes)
falls through to:

```
RAM 0xCEC: sw v1, 0x80(k0)    ; save scratch
RAM 0xCF0: lui v0, 0x0        ; ←—— installed stub starts here
RAM 0xCF4: addiu v0, v0, 0x641C
RAM 0xCF8: jalr v0
RAM 0xCFC: nop
```

The installed stub `jalr`s to RAM 0x641C (= ROM 0xBFC15F1C), the
data-byte handler. That handler:

1. Reads `[0x75c0]`. If 0, returns immediately.
2. Reads SIO_DATA (the data byte from the card).
3. Stores it at `*mem[0x75c4]` (the running buffer pointer).
4. Increments `mem[0x75c4]`.
5. Acks SIO IRQ.
6. Returns.

After 128 such invocations, the BIOS clears `[0x75c0]` and the chain
dispatcher resumes for R12 (checksum) and R13 (end-byte 'G').

## Why static recompilation can't follow this

`generated/SCPH1001_full.c` was emitted from the ROM image. At ROM
addresses 0xBFC107F0..0xBFC107FC the bytes are NOPs — that's all the
recompiler sees. It emits:

```c
/* 0xBFC107F0: 00000000  nop */
/* nop */
/* 0xBFC107F4: 00000000  nop */
/* nop */
...
```

The recompiler has no way to know that the BIOS overwrites these
runtime addresses with a working dispatch stub. Even if it did, it
couldn't statically know the destination — `addiu v0, v0, 0x641C` is
a runtime computation against `lui v0, 0x0`, which by itself is
underspecified.

## The interpreter (runtime fix)

### Dirty-page tracking

The runtime maintains a bitmap covering all writable RAM pages
(typically 64 KB at 4 KB granularity = 16 bits). Any write into the
kernel code region (RAM 0x000..0xFFFF) sets the bit for that page.

### Dispatch interception

`psx_dispatch(addr)` checks the dirty bit for `addr`. If clean,
calls the static-recompiled function as before. If dirty, hands
control to the interpreter.

### The interpreter

A small MIPS interpreter (~300 LOC) executes the basic block at
`addr` against `cpu->gpr[]`, `cpu->cop0[]`, etc. It supports the
small subset of instructions that BIOS install stubs actually use
(arithmetic, loads/stores, branches, jr/jalr). Unsupported
instructions abort fatally — they should never appear in install
stubs.

After the interpreter executes the block (terminating at jr/j/jalr),
control returns to `psx_dispatch` for the next basic block. The
combined effect is that BIOS-installed code at RAM 0xCF0 *runs*,
correctly, on the same CPU register state as static-recompiled C.

## Discoverability

Other install slots may exist. The tracker should detect them
mechanically by:

- Logging every write into `RAM 0x000..0xFFFF` (kernel code area).
- Reporting any PC dispatch that hits a written page.

Known/suspected slots to verify after the SIO data handler works:

- VBlank pad poll fast-path (?)
- Memcard slot-1 detection
- CD-ROM ready handler
- Anything in `RAM 0xC80..0xFFF` (kernel hook region)

## NOT HLE

This mechanism is explicitly *not* high-level emulation:

- We do not synthesize what the handler "would have produced".
- We do not intercept events, mark them delivered, or short-circuit
  any BIOS state machine.
- We do not write C reimplementations of `_card_read`, `OpenEvent`,
  or anything else.

We let the BIOS run its own code. The only thing we add is the
ability for that code to live in dirty RAM rather than ROM. That is
a property of the program; we accommodate it. See CLAUDE.md Rule 18.