psxrecomp/HANDOFF_PHASE3.md

# PSXRecomp v4 — Phase 3 HANDOFF (FRESH SESSION)

You have ZERO prior context. Follow this exactly.

---

## 0. FIRST ACTION

Read these files in order:

1. CLAUDE.md
2. PLAN.md (Phase 3 starts ~line 1047)
3. PRINCIPLES.md
4. DEBUG.md
5. MEMORY.md

Then state EXACTLY:

"Architecture A is locked. No interpreter. No HLE. No stubs. BIOS first. Game never until Phase 5."

If you cannot confidently state this, STOP.

---

## 1. CURRENT STATE (DO NOT REDO)

Phase 1 COMPLETE — recompiler proven correct on SCPH1001.BIN
Phase 2 COMPLETE — runtime executes recompiled BIOS
Phase 3 IN PROGRESS — BIOS boots into shell loop, no display yet

### What works RIGHT NOW

The recompiled BIOS executes from reset through kernel init, copies
kernel Part 2 to RAM, sets up A0/B0/C0 function tables, processes a
SYSCALL, copies the shell from ROM to RAM 0x80030000, enters the shell,
and runs in a stable loop for 3+ seconds without crashing.

**97,000+ trampoline resolutions per 3-second run.**
**~800 seeds, ~793 emitted functions, 46,499 instructions.**

### Trusted baseline files

Generated (DO NOT MODIFY — fix the recompiler instead):
- `generated/SCPH1001_full.c` — 793 functions, 46,499 instructions
- `generated/SCPH1001_dispatch.c` — binary-search dispatch with 795 entries

Runtime:
- `runtime/src/main.cpp` — loads BIOS, initializes CPU, calls dispatch
- `runtime/src/memory.c` — memory + MMIO routing (SEE STUB AUDIT BELOW)
- `runtime/src/traps.c` — SYSCALL handler + trampoline resolver
- `runtime/include/cpu_state.h` — CPU state definition

Recompiler (changes made this session):
- `recompiler/src/full_function_emitter.cpp` — fallthrough codegen, J/JAL relocation, shell normalization
- `recompiler/src/function_discovery.cpp` — normalization range fix
- `recompiler/src/strict_translator.cpp` — MTHI/MTLO added
- `recompiler/seeds/phase2_ghidra_seeds.json` — 800 seeds

### Architecture invariants (STILL TRUE)

- Functions: `void func_XXXXXXXX(CPUState*)`
- All memory via function pointers (read/write)
- Address normalization: `addr & 0x1FFFFFFF` + relocation rules
- Two relocation zones:
  - Kernel Part 2: ROM `0x1FC10000-0x1FC17FFF` ↔ RAM `0x500-0x8500`
  - Shell: ROM `0x1FC18000-0x1FC427FF` ↔ RAM `0x30000-0x5A7FF`
- Dispatch: `psx_dispatch(cpu, addr)` with binary search
- JAL → direct call; JR $ra → return; JALR/indirect JR → `psx_dispatch`
- Runtime trampoline resolver handles A0/B0/C0 vectors in RAM
- SYSCALL simulates R3000A exception (EPC, Cause, SR push, vector dispatch)

---

## 2. STUB AUDIT — WHAT IS REAL VS FAKE

This is the critical section. Read `runtime/src/memory.c` carefully.

### REAL hardware simulation (correct behavior):
- Memory control registers (0x1F801000-0x1F801020): store/recall
- RAM size register (0x1F801060): store/recall
- Cache control (0xFFFE0130): store/recall
- Interrupt I_STAT (0x1F801070): AND-acknowledge semantics ✓
- Interrupt I_MASK (0x1F801074): store with 0x7FF mask ✓
- SPU registers (0x1F801C00-0x1F801FFF): store/recall (no audio needed)
- Expansion 1 (0x1F000000-0x1F7FFFFF): returns 0xFFFFFFFF (open bus) ✓
- Expansion 2 / POST (0x1F802000-0x1F802FFF): ignored ✓

### STUBS that MUST be replaced with real simulation:

**GPU (0x1F801810, 0x1F801814) — CRITICAL for Sony logo:**
- GP0 write: silently dropped (line 150)
- GP1 write: silently dropped (line 151)
- GPUREAD: returns 0 (line 102)
- GPUSTAT: returns fixed 0x1C000000 (line 103)
- REALITY: needs full GP0 command parser, FIFO, VRAM writes, display params

**DMA (0x1F801080-0x1F8010FF) — CRITICAL for GPU data transfer:**
- All reads return 0 (line 90-92)
- All writes silently dropped (line 138-140)
- REALITY: needs per-channel MADR/BCR/CHCR, DPCR/DICR, transfer execution
- GPU DMA (channel 2) transfers polygon/texture data from RAM to GPU

**Timers (0x1F801100-0x1F80112F) — NEEDED for vblank:**
- All reads return 0 (line 93-96)
- All writes silently dropped (line 141-143)
- REALITY: needs counter values, mode registers, target values, overflow flags
- Timer 1 (hblank) drives the vblank interrupt

### STUBS that are ACCEPTABLE for Phase 3:
- SIO (0x1F801040-0x1F80105F): returns TX ready — OK until Phase 4
- CDROM (0x1F801800-0x1F801803): returns 0 — OK until Phase 5
- MDEC (0x1F801820-0x1F801824): returns 0 — not needed for Sony logo

### unmapped_fatal is a concern:
- Currently returns silently instead of aborting (line 62-68)
- This was necessary for BIOS RAM-size probing during init
- BUT it could mask real bugs during shell execution
- Consider: re-enable fatal abort for writes, keep silent for reads

---

## 3. PHASE 3 REMAINING GOAL

Render the Sony Computer Entertainment logo.

REQUIREMENT: VRAM output must match DuckStation byte-for-byte.

---

## 4. WHAT MUST BE BUILT NEXT (in order)

### Step 1: GPU command processor
The shell is writing GP0/GP1 commands that are being silently dropped.
Implement:
- GP1 command parser (display mode, display area, drawing area, reset)
- GP0 command parser (fill rect, copy rect, draw polygon, draw sprite)
- 1MB VRAM buffer (1024×512 × 16-bit)
- GPUSTAT register with real status bits

### Step 2: DMA channel 2 (GPU)
The shell uses DMA to transfer large command lists to the GPU.
Implement:
- Per-channel registers (MADR, BCR, CHCR) for all 7 channels
- DPCR (channel enable/priority)
- DICR (DMA interrupt control)
- Channel 2 (GPU) linked-list and block transfer modes
- Channel 6 (OTC — ordering table clear)

### Step 3: Timer + vblank interrupt
The shell waits for vblank to sync frame display.
Implement:
- Timer 0/1/2 counter registers
- Timer mode registers (clock source, target, IRQ)
- Vblank interrupt delivery (I_STAT bit 0)
- Simple frame timing (call vblank at ~60Hz equivalent)

### Step 4: SDL2 display window
- Add SDL2 dependency to CMakeLists.txt
- Create window (640×480 or 320×240)
- Blit VRAM framebuffer region to SDL surface each frame
- Main loop: execute BIOS → check vblank → blit → SDL_PollEvent

---

## 5. SALVAGE SOURCE (v3 reference, NOT copy-paste)

v3 hardware sim files at:
`F:/Projects/psxrecomp-projects-v3/psxrecomp/runner/src/`

- `gpu.c` (1200+ lines) — GP0/GP1 command parser, FIFO, GPUSTAT
- `gpu_sw_renderer.c` — software rasterizer (polygon, sprite, fill)
- `dma.c` (378 lines) — DMA channel transfer engine
- `interrupts.c` (325 lines) — I_STAT/I_MASK + exception dispatch
- `timers.c` (150+ lines) — counter advance, mode flags, clock sources

AUDIT RULES (from CLAUDE.md §7):
- REMOVE: all bios_*, interpreter_*, events/threading, HLE logic, kernel mirrors
- KEEP ONLY: pure hardware register simulation, state machines
- Integrate ONE file at a time → wire into memory.c → test immediately

---

## 6. BIOS ROM MEMORY MAP (verified)

Code regions (scan for functions HERE ONLY):
- `BFC00000-BFC0DC60` — Kernel Part 1 (~56KB)
- `BFC10000-BFC16760` — Kernel Part 2 (~26KB, relocated to RAM 0x500)
- `BFC18000-BFC42800` — Shell (~172KB, copied to RAM 0x80030000)

Data regions (NEVER scan, NEVER treat as code):
- `BFC0DC60-BFC0FFFF` — zero padding
- `BFC16760-BFC17FFF` — data tables + zero padding
- `BFC42800-BFC63FFF` — graphics (TIM textures, strings, CLUTs)
- `BFC64000-BFC7FFFF` — font bitmaps (112KB)

---

## 7. BUILD

```
PATH=/c/msys64/mingw64/bin:$PATH
export TMP=/c/msys64/tmp TEMP=/c/msys64/tmp

# Recompiler (only if recompiler source changes):
cd recompiler/build && cmake --build .

# Re-emit (only if seeds or recompiler changes):
cd ../.. && recompiler/build/psxrecomp-bios.exe bios/SCPH1001.BIN generated \
  --emit-full recompiler/seeds/phase2_ghidra_seeds.json

# Runtime:
cd runtime/build && cmake --build .

# Run:
cd ../.. && runtime/build/psx-runtime.exe bios/SCPH1001.BIN
```

Current behavior: runs silently in a loop (shell executing with stubbed hardware).
Expected after GPU impl: should render Sony logo to VRAM, display via SDL2.

---

## 8. DEBUGGING METHOD

DuckStation TCP debug server:
- Location: `F:/Projects/psxrecomp-v4/duckstation/build/bin/`
- Launch: `duckstation-qt.exe -bios`
- Port: 4371
- Commands: ping, read_ram, get_registers, gpu_state, pause, step

For EVERY GPU command or DMA transfer you implement, verify against
DuckStation's output for the same boot sequence.

---

## 9. HARD CONSTRAINTS (still in force)

NEVER:
- Return dummy MMIO values without understanding what the BIOS expects
- Skip hardware behavior  
- Use printf debugging (no fprintf to stderr/stdout in runtime code)
- Modify generated code
- Add HLE behavior
- Load a game ISO or EXE

If an MMIO read value is unknown:
1. Check DuckStation (TCP debug server)
2. Check Ghidra for the calling BIOS code's usage pattern
3. Implement the correct producing logic

---

## 10. KNOWN ISSUES

1. `unmapped_fatal` is silent — could mask bugs. Consider re-enabling for writes.

2. GPUSTAT returns fixed `0x1C000000` — the shell reads this to check GPU
   readiness. When GPU is implemented, this must reflect real FIFO/busy state.

3. SIO_STAT returns fixed `0x00000005` — adequate for Phase 3 but must be
   real for Phase 4 (controller/memcard).

4. The trampoline resolver in `traps.c` handles runtime-written code at
   A0/B0/C0 vectors. It simulates delay slots for `li+jr` patterns.
   This is NOT an interpreter — it's a dispatch chain resolver. But verify
   it handles all patterns the shell uses.

5. One BIOS function skipped (COP1/FPU at BFC02324) — not reached during boot.

---

## 11. SUCCESS CRITERIA

Phase 3 is DONE when:
- SDL2 window opens
- Sony Computer Entertainment logo renders on screen
- VRAM contents match DuckStation byte-for-byte

Phase 3 is NOT done if:
- "The GPU command stream looks right" (PIXELS ON SCREEN)
- "VRAM has some data" (MATCHES DUCKSTATION)
- "It mostly works" (BYTE FOR BYTE)

---

BEGIN.