thejayman77
ec82764bef
RTL (GS rasterizer, EE core stub, platform bridge, LPDDR4B path), sim regression (272 TBs), docs, and tooling. Copyrighted PS2 content (BIOS, game code, GS dumps, and all dump-derived textures/traces) is excluded via .gitignore and stays local. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
180 lines
4.2 KiB
Markdown
180 lines
4.2 KiB
Markdown
# 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.
|