Initial commit: retroDE_ps2 — first-of-its-kind PS2 GS FPGA core (DE25-Nano / Agilex 5)
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>
This commit is contained in:
@@ -0,0 +1,179 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user