thejayman77/retroDE_ps2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ec82764bef315a17cbdd7aaebf1535383e3b2aaf
retroDE_ps2/docs/contracts/memory.md
T
thejayman77 ec82764bef 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>
2026-06-29 20:10:50 -04:00

2.0 KiB
Raw Blame History

Memory Contract

Status: Draft

Purpose

Define the memory-visible contract of the system before any CPU or DMA block is implemented.

Scope

  • EE main RAM visibility and mirrors,
  • IOP RAM visibility,
  • scratchpad behavior,
  • BIOS ROM visibility,
  • GS VRAM abstraction,
  • SPU2 RAM abstraction,
  • arbitration between masters,
  • access ordering and observability requirements.

Explicitly owns

  • BIOS ROM storage, mapping, and address visibility.

Explicitly does not own

  • BIOS boot sequencing behavior after reset,
  • IOPBOOT / IOPBTCONF parsing and module-load execution flow,
  • interrupt-controller policy.

Must represent

  • 32 MiB EE main RAM with cached/uncached/mirrored views as required by the chosen bring-up scope,
  • 2 MiB IOP RAM,
  • 16 KiB scratchpad RAM,
  • 4 MiB BIOS ROM windowing,
  • 4 MiB GS VRAM,
  • 2 MiB SPU2 RAM.

Consumers / masters

  • EE core
  • EE DMAC
  • VIF/VU path
  • GIF/GS path
  • IOP core
  • IOP DMA
  • SPU2 path
  • optional HPS debug/service access

Contract questions to lock

  • Is there one central arbitration layer or separate local memories with bridges?
  • What ordering guarantees are required between CPU stores, DMA, and GS-visible operations?
  • Does the initial project model TLB/cache behavior directly, or only enough address translation to support staged bring-up?
  • Which regions are cycle-sensitive in Phase 1 versus functionally-correct only?

Required debug visibility

  • access trace: master, address, width, read/write, data when practical,
  • arbitration trace: grant decisions,
  • fault trace: unmapped or illegal accesses.

Allowed early stubs

  • BIOS ROM backed by placeholder image interface,
  • functionally-correct RAM without final timing,
  • GS VRAM as a simpler backing store before final internal organization is set.

Exit criteria for first implementation

  • BIOS fetch addresses resolve correctly,
  • EE RAM mirrors behave consistently for the chosen boot path,
  • scratchpad region is distinguishable from main RAM,
  • DMA and CPU accesses can be traced and correlated.
Reference in New Issue View Git Blame Copy Permalink