# 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.

```text
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.