retroDE_ps2/references/implementation_workstreams.md

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.