retroDE_ps2/docs/repo_layout.md

Proposed Repository Layout

This is the first-pass target repository shape for retroDE_ps2. The goal is to make the project grow around stable subsystem seams instead of one giant top-level.

This document describes the intended shape of the repository as the project matures. It is not a mandate to create every listed file immediately.

retroDE_ps2/
├── docs/
│   ├── README.md
│   ├── repo_layout.md
│   ├── phase0_checklist.md
│   ├── contracts/
│   │   ├── README.md
│   │   ├── platform.md
│   │   ├── memory.md
│   │   ├── ee.md
│   │   ├── iop.md
│   │   ├── intc.md
│   │   ├── dmac.md
│   │   ├── vif_vu.md
│   │   ├── gif_gs.md
│   │   ├── sif.md
│   │   ├── spu2.md
│   │   ├── peripherals.md
│   │   └── validation.md
│   └── decisions/
│       └── README.md
├── references/
│   └── ...
├── sim/
│   ├── README.md
│   ├── tb/
│   ├── traces/
│   ├── vectors/
│   └── golden/
├── rtl/
│   ├── common/
│   ├── platform/
│   ├── memory/
│   ├── ee/
│   ├── iop/
│   ├── dmac/
│   ├── vif_vu/
│   ├── gif_gs/
│   ├── sif/
│   ├── spu2/
│   ├── peripherals/
│   └── debug/
├── software/
│   ├── tests/
│   ├── loaders/
│   ├── diagnostics/
│   └── tools/
├── third_party/
│   ├── bios_notes/
│   ├── sdk_notes/
│   └── emulator_notes/
├── retroDE_ps2.sv
├── retroDE_ps2.qpf
├── retroDE_ps2.qsf
├── retroDE_ps2.sdc
├── compile_ps2.sh
└── post_flow.tcl

Directory Roles

Not every directory in the tree above needs to exist on day one. The immediate planning rule is:

• contracts first,
• simulation scaffolding early,
• RTL directories only when implementation for that subsystem is actually about to begin.

docs/

The contract layer. Nothing in here should depend on RTL already existing.

sim/

All simulation and comparison infrastructure. This should exist early, even if many tests initially run against stubs.

rtl/common/

Utilities shared by multiple blocks:

• FIFOs
• CDC helpers
• arbiters
• trace encoders
• register helpers

rtl/platform/

retroDE-specific integration:

• clocks and resets
• platform bridge plumbing
• audio/video adaptation
• top-level wrappers that should not live inside PS2-specific subsystems

rtl/memory/

Everything related to memory visibility and arbitration:

• EE RAM model
• IOP RAM model
• scratchpad
• BIOS ROM adapters
• GS VRAM abstraction
• SPU2 RAM abstraction
• interconnect and arbitration

rtl/ee/

Emotion Engine-side CPU and close coprocessor logic. If external cores or vendored logic ever land, they should still be wrapped here behind local interfaces.

rtl/iop/

IOP CPU and IOP-local bus/peripheral decode.

rtl/dmac/

EE DMAC plus any shared DMA-side helpers.

rtl/vif_vu/

VIF packet decode, VU0/VU1 local memories, macro/micro control, and related state machines.

rtl/gif_gs/

GIF path logic, GS register decode, VRAM-visible operations, and display path generation.

rtl/sif/

EE<->IOP communication block and DMA-visible coordination points.

rtl/spu2/

Audio engine, audio RAM path, DMA hooks, and retroDE output adapter boundary.

rtl/peripherals/

CDVD, SIO2, DEV9, USB, memory card visibility, and other console-completeness blocks that do not belong in the CPU/gfx/audio cores.

rtl/debug/

Trace taps and observation blocks. This is intentionally first-class.

software/

Bring-up payloads and utilities:

• tiny EE-side tests
• tiny IOP-side tests
• diagnostics
• host-side tooling

third_party/

Notes on imported or externally-derived material. This is a good place to track license, provenance, and local adaptation policy before source is actually vendored.

Initial Implementation Rule

No new subsystem directory should receive RTL until its matching contract file under docs/contracts/ exists.