# rtl/sif

EE↔IOP subsystem interface. Matches `docs/contracts/sif.md`.

## Current contents

- `sif_mailbox_stub.sv` — minimal four-register mailbox/flag shell
  (MSCOM / SMCOM / MSFLG / SMFLG). Independent EE-side and IOP-side register
  ports. Directional set/clear semantics deferred; this phase only proves
  that both sides observe consistent storage and that side-of-origin is
  trace-visible. Per-register write arbitration: EE wins on same-register
  collision, independent writes to different registers coexist.
- `sif_dma_stub.sv` — receive-side DMA endpoint. Accepts qwords from a
  DMAC channel's `ep_*` port into a small internal buffer (default DEPTH=8).
  Capacity-safe: `in_ready` drops when `rx_count >= DEPTH`, `full_o`
  exposed for testbench observation. TB-controlled `stall_in` input for
  explicit stall testing. Read port for payload verification. No consume
  path yet — once full, stays full. NOT an IOP — purely a bounded receive
  buffer with trace emission per accepted beat.
- `sif_mailbox_peer_stub.sv` — tiny active peer used in integration tests
  to play "the IOP side" of a specific mailbox protocol. Re-armable
  command-echo state machine (poll MSFLG → read MSCOM → write SMCOM →
  write SMFLG → wait for TB to clear MSFLG → repeat). Refuses to re-fire
  while the doorbell bit stays high, so lifecycle is explicit. Exposes
  `ack_count_o` for testbench synchronisation.
  Explicitly NOT an IOP core: no code execution, no BIOS bring-up, no
  implicit flag clearing (re-arm is the TB's responsibility). Kept under
  `rtl/sif/` precisely so it does not get misread as IOP maturity progress.
- `sif_dma_iop_ram_bridge_stub.sv` — width-adapting bridge from a 128-bit
  SIF DMA endpoint to 32-bit IOP-side writes. Splits each incoming qword
  into four 32-bit writes at consecutive physical addresses from
  `DEST_BASE_ADDR`. Little-endian unpacking. Drives the IOP memory map's
  bridge-write port (`bridge_wr_*`). In-ready drops while the bridge is
  flushing a qword — natural backpressure to the DMAC.
- `sif_dma_ack_peer_stub.sv` — protocol combiner for the first combined
  control+data SIF milestone. Observes a mailbox doorbell (MSFLG pending
  bit) AND `sif_dma_stub.last_seen` (payload completion); only emits the
  ack sequence (SMCOM=cmd + SMFLG=ACK) once both are true. Composes two
  existing SIF primitives; does not fatten the plain mailbox peer with
  DMA awareness.
  Explicitly NOT an IOP.
- `sif_dma_ee_ram_bridge_stub.sv` — width-adapting bridge from a 32-bit
  SIF DMA endpoint (IOP→EE egress) to 128-bit EE-side writes. Mirror of
  `sif_dma_iop_ram_bridge_stub` in the other direction: accumulates four
  consecutive 32-bit beats into a qword (little-endian), then issues
  one write through the EE memory map's bridge write port. Drops
  `in_ready` during the one-cycle emit for natural back-pressure.
  Handles partial-quad on `in_last` via byte-enable masking. Exposes
  `last_seen_o` — a level-held latch that rises when the final beat of
  a transfer is accepted, so EE-side protocol combiners can gate on
  "payload fully landed."
- `sif_dma_ee_ack_peer_stub.sv` — protocol combiner for the first
  IOP-driven combined control+data SIF milestone. Polarity mirror of
  `sif_dma_ack_peer_stub`: observes the mailbox's EE side for an IOP
  doorbell (SMFLG pending bit), gates on
  `sif_dma_ee_ram_bridge_stub.last_seen_o`, and only then reads SMCOM
  and echoes MSCOM + MSFLG=ACK back IOP-ward. One-shot. Explicitly NOT
  an EE core — purely a composition of two existing SIF primitives.

## Current status

The SIF seam is feature-complete for staged bring-up in both directions.
Storage, active peer, lifecycle/re-arm, negative-path, EE→IOP DMA, three
classes of backpressure (start / mid-transfer / full-stop), EE-driven
combined control+data gating, a reverse-direction (IOP→EE) data path
with its own stall semantics, AND the matching IOP-driven combined
control+data handshake are all proven end-to-end. Further SIF-only work
would be symmetry-chasing rather than unlocking new architectural
questions.

## Deferred follow-ons (not gaps)

These are known extension points, intentionally not pursued yet:

- **Re-armable combined control+data handshakes.** Both directions are
  currently one-shot; re-arm mostly composes pieces already proven
  separately. Nice-to-have.
- **Directional write-ownership + flag set/clear semantics.** Currently
  both sides of the mailbox can write any register with plain replace
  semantics; real PS2 has directional set/W1C rules.
- **Real EE↔IOP coordination.** Arrives once an IOP-side execution
  primitive exists that can observe SIF as "IOP behaviour," not as a
  peer stub.

## Scope boundary

This directory owns the SIF register shell and DMA-visible coordination.
It does **not** own:
- IOP CPU execution (`rtl/iop/`, not yet created)
- EE-side addressing / kseg stripping for SIF registers (memory-map work)
- Interrupt routing to INTC on SIF transitions (Wave 3)