# retroDE_ps2 Planning Docs

This directory is the working design scaffold for the PS2 core.

Purpose:

- define the intended repository shape before RTL lands,
- define subsystem boundaries before implementation choices harden,
- document what each block owns, what crosses the boundary, and how we will
  validate it.

Recommended reading order:

1. [repo_layout.md](repo_layout.md)
2. [phase0_checklist.md](phase0_checklist.md)
3. [contracts/README.md](contracts/README.md)
4. [stub_module_plan.md](stub_module_plan.md)
5. [wave2_dma_gif_plan.md](wave2_dma_gif_plan.md)
6. [wave25_memory_backed_dma_plan.md](wave25_memory_backed_dma_plan.md)
7. [wave26_multi_beat_dma_plan.md](wave26_multi_beat_dma_plan.md)

Relationship to `references/`:

- `references/` is the research library.
- `docs/` is the project-definition layer.

Rule of thumb:

- If a file explains PS2 hardware as it exists, it belongs under `references/`.
- If a file explains how `retroDE_ps2` intends to model, partition, or validate
  that hardware, it belongs under `docs/`.