retroDE_ps2/rtl/sif/README.md

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)