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