# PS2 Implementation Workstreams

This file is the planning map for "what would we actually have to account for?"
It is deliberately biased toward project decomposition rather than hardware
history.

## Executive Take

`ao486` is a reasonable organizational comparison, but only partially.

Why the comparison fits:

- both projects are full-system bring-ups, not narrow cartridge-style cores,
- both need firmware-aware boot behavior,
- both need host/media integration,
- both benefit from strong subsystem boundaries and platform glue isolation,
- both will need serious debug instrumentation.

Why the comparison breaks:

- PS2 leans harder on DMA orchestration and coprocessor interaction,
- PS2 has a more central "packetized graphics path" problem,
- PS2 has a stricter dual-CPU story with visible EE<->IOP coordination,
- PS2 includes vector units and fixed-function graphics behavior that are not
  naturally analogous to a PC chipset.

My planning conclusion: treat this as `ao486`-class or harder, but not
`ao486`-shaped internally.

## Workstream Map

### 1. Platform shell integration

Needed work:

- retroDE top-level wrapper,
- clock/reset sequencing,
- HDMI/video adaptation strategy,
- audio output integration,
- HPS bridge register map,
- manifest/backend planning.

Questions:

- What clocks are generated locally versus inherited from the shared shell?
- Does the first implementation target native-like timings internally and adapt
  outward, or simplify early output into a framebuffer path?

### 2. Main memory architecture

Needed work:

- 32 MiB EE main RAM behavior,
- 2 MiB IOP RAM behavior,
- 16 KiB scratchpad behavior,
- GS VRAM model,
- SPU2 RAM model,
- BIOS ROM visibility,
- arbitration between execution units, DMA, and graphics paths.

This is one of the hardest planning areas because the PS2 is not just "shared
DDR plus a CPU." Memory placement, visibility, and access rules are part of the
software contract.

### 3. EE / R5900 core

Needed work:

- MIPS III base behavior,
- relevant MIPS IV extensions,
- MMI instructions,
- exception / interrupt behavior,
- COP0 system behavior,
- FPU behavior and edge cases,
- TLB / mapping behavior or a scoped approximation if a staged bring-up allows.

A key planning question is whether there is any reusable R5900 implementation
candidate, or whether the project would require a major custom core effort.

### 4. VU / VIF complex

Needed work:

- VU0 and VU1 execution model,
- local code/data memories,
- microprogram upload path,
- VIF unpack / packet interpretation,
- synchronization rules between EE, VIF, VU, and GIF.

This is a major reason the project is not just "CPU + GPU." A lot of PS2-era
software performance depends on this path.

### 5. DMAC

Needed work:

- per-channel register behavior,
- channel scheduling / priority,
- stall / ring / status behavior,
- GIF, VIF, SIF, IPU, and scratchpad transfer semantics,
- interrupt generation.

If the DMAC is wrong, everything looks randomly broken. This is likely a
top-tier subsystem for instrumentation and standalone tests.

### 6. GIF + GS

Needed work:

- GIF tag/path handling,
- PATH prioritization behavior,
- GS command/register decode,
- VRAM layout / swizzle / formats,
- framebuffer / zbuffer behavior,
- display controller / output timing strategy,
- enough rendering fidelity to pass real software.

This is probably the subsystem most likely to dominate bring-up time after the
CPU/memory base exists.

### 7. IOP subsystem

Needed work:

- IOP CPU behavior,
- IOP RAM and I/O space,
- IOP DMA engine,
- interrupt/timer behavior,
- module boot expectations from BIOS,
- PS1-legacy-derived hardware blocks used in PS2 mode.

For planning purposes, the IOP should be treated as a real subsystem, not as
"peripheral glue."

### 8. SIF and EE<->IOP coordination

Needed work:

- SIF registers,
- DMA channels on both sides,
- command/flag behavior,
- RPC-visible behavior as exercised by system software.

This is likely one of the first places where "mostly works" breaks down when
moving from demos to real software.

### 9. Audio path

Needed work:

- SPU2 register behavior,
- SPU2 RAM behavior,
- DMA and AutoDMA cases,
- output mixing and timing,
- bridge into retroDE audio output.

A staged project might boot without accurate audio, but a believable PS2 core
cannot stop there.

### 10. Media and storage

Needed work:

- CDVD-visible behavior,
- optional HDD / DEV9 strategy,
- BIOS expectations around media presence,
- HPS-side image mounting or file-backed emulation.

This is one of the best arguments for an `ao486`-style host integration layer.
Media handling will almost certainly live partly on the HPS side.

### 11. Input and memory cards

Needed work:

- SIO2-visible controller path,
- memory card protocol / presence behavior,
- mapping retroDE input stack to DualShock-compatible semantics.

The good news is the retroDE platform already contains wired DualShock 2
controller work. That may help at the platform-input layer, even though it does
not solve PS2 console-side SIO2 semantics by itself.

### 12. BIOS / firmware strategy

Questions to settle early:

- Real dumped BIOS only?
- Any HLE stubs for debug-only bring-up?
- What is the policy for user-supplied ROM images and module assets?

This decision changes the bring-up plan significantly. A real BIOS path is more
authentic and more demanding. An HLE debug path may shorten early validation but
adds its own maintenance burden.

### 13. Debug and verification infrastructure

Needed work:

- trace taps for EE fetch/decode/exception flow,
- DMAC channel traces,
- GIF/GS packet capture,
- IOP/SIF event logging,
- golden-reference comparison points against emulators,
- tiny directed tests for memory map, DMA, VIF, GS, and SIF.

This project should probably assume that debug plumbing is a first-class feature,
not an afterthought.

## Suggested phased plan

### Phase 0: architecture lock

- choose upstream/reference strategy,
- choose BIOS policy,
- choose host/media policy,
- choose first display strategy,
- define subsystem boundaries.

### Phase 1: scaffold and observability

- create repo skeleton,
- define register/bridge map,
- add debug plumbing and trace formats,
- decide validation harnesses.

### Phase 2: minimal EE boot

- RAM/ROM map,
- reset vectors,
- enough EE behavior for BIOS progress,
- proof-of-life traces.

### Phase 3: first graphics proof

- minimal DMAC + GIF + GS path,
- simple visible output,
- likely driven by tiny test payloads before commercial software.

### Phase 4: IOP and SIF

- IOP bootstrap,
- SIF messaging and DMA,
- enough coordination for deeper BIOS progress.

### Phase 5: completeness layers

- VIF/VU correctness,
- SPU2,
- CDVD / DEV9 / storage,
- controller and memory card semantics,
- broader software compatibility work.

## Bottom line

If the question is "is this closer to `ao486` than to the simpler retroDE
cores?", the answer is yes.

If the question is "can we mostly copy the `ao486` strategy and just swap the
payload?", the answer is no.

The safe way to start is:

1. treat PS2 as a full-system architecture project,
2. lock memory / firmware / host integration decisions early,
3. build around subsystem ownership and instrumentation,
4. aim for staged proof-of-life milestones instead of "boots games" as the
   first success bar.
