# rtl/memory

Memory visibility, storage, and arbitration. Matches `docs/contracts/memory.md`.

Per the BIOS-ownership split (memory owns storage, IOP owns behavior), this
directory contains the storage/mapping layer. BIOS boot sequencing
(IOPBOOT / IOPBTCONF parsing) belongs under `rtl/iop/`.

## Wave 1 contents

- `bios_rom_stub.sv` — 4 MiB BIOS ROM adapter. Loads a user-supplied hex
  image via `$readmemh` when `IMAGE_FILE` is set, otherwise falls back to a
  synthetic NOP sled. One-cycle read latency.
- `ee_memory_map_stub.sv` — EE-side address decode. Wave 2.7 revision adds
  a DMAC read-master port (128-bit data, physical addressing) with its own
  RAM-window decode at 0x00000000-0x01FFFFFF routing to `ee_ram_stub`. EE
  fetch path still uses kseg-aliased decode and is BIOS-only.

## Wave 2.5 addition

- `ee_ram_stub.sv` — small addressable EE-RAM block (default 16 KiB,
  128-bit data path). First real memory source for DMAC-backed transfers.
  Read port: `rd_en/rd_addr/rd_data/rd_valid`. Write port: `wr_en/wr_addr/
  wr_data/wr_be`. Caller-provided `master_id` gets tagged into MEM READ /
  WRITE trace events. Not the final 32 MiB EE-RAM model — see
  `docs/wave25_memory_backed_dma_plan.md` for scope boundaries.

## BIOS policy note

Per `docs/decisions/0002-bios-policy.md`, no BIOS image is distributed from
this repository. Synthetic fixture is the default so the project can run
stubs without any Sony firmware. Real BIOS usage requires a user-supplied
dump placed at the path passed to `IMAGE_FILE`.