kernbench2/docs/adr/ADR-0041-dev-cube-sram-component-model.md

# ADR-0041: Cube SRAM Component Model — terminal scratchpad on cube NoC

## Status

Accepted (2026-05-20).

ADR-0017 (Cube NOC and HBM Connectivity) describes SRAM as a cube-NoC
attachment but does not specify the SRAM component's own latency / response
model. This ADR fills that gap.

## First action

Inside `_worker`, immediately after pulling a Transaction off `_inbox`, the
very first action is `yield from self.run(env, txn.nbytes)`. Inside `run()`,
the component applies `env.timeout(node.attrs["overhead_ns"])`
(default `0.0`).

In short, **SRAM's first act is "express access overhead as simulator time"**.
After overhead, the worker yields `drain_ns` (the terminal BW-serialization
cost stamped on the Transaction) and then constructs and dispatches a
`ResponseMsg` on the reverse path.

This differs from a generic `ComponentBase._worker`: SRAM knows it is a
**terminal node**, so it does not go through `_forward_txn`. Its own worker
explicitly performs `run → drain → _send_response`.

## Context

The cube topology (`topology/builder.py`) creates the following named nodes
per cube:

- `sip{S}.cube{C}.m_cpu`
- `sip{S}.cube{C}.sram`
- `sip{S}.cube{C}.hbm_ctrl` (per-PE partitions)
- `sip{S}.cube{C}.pe{P}` (and its PE-internal sub-components)

SRAM is one of the cube-NoC attachments — `topology/mesh_gen.py` assigns it
to the nearest router by placement coordinates and adds `"sram"` to that
router's `attach` list. The builder lays bidirectional `sram ↔ router` edges
(BW: `sram_to_router_bw_gbs`, default `128.0 GB/s`).

SRAM has two intertwined roles:

1. **Fabric terminal**: the endpoint for cube-NoC memory-access Transactions
   destined for SRAM. SRAM consumes access overhead + drain, then sends a
   response back on the reverse path.
2. **One of the IPCQ slot tiers**: ADR-0023 D9.7 defines
   `buffer_kind ∈ {tcm, sram, hbm}`; the `sram` tier's per-access cost is
   `(512.0 GB/s, 2.0 ns)` in `common/ipcq_types._BUFFER_KIND_BW`. This is
   separate from the SRAM node's `overhead_ns` attr; PE_DMA accounts for it
   directly at the IPCQ slot-write moment.

Without an ADR covering both roles, the following questions are ambiguous:

- "What latency does SRAM model?" — fabric drain + overhead, or the IPCQ
  tier slot latency? — answers scatter.
- What does the `size_mb` (`32`) attr mean in the future? Currently it is not
  used; SRAM only models timing.
- Which cube router does SRAM attach to? (placement-based; lives in topology
  code only.)

## Decision

### D1. SRAM is a terminal scratchpad node on the cube NoC

`SramComponent` extends `ComponentBase` but overrides `_worker` to express
terminal semantics directly:

```
while True:
    txn = yield self._inbox.get()
    yield from self.run(env, txn.nbytes)     # overhead_ns
    if drain_ns > 0: yield env.timeout(drain_ns)
    yield from self._send_response(env, txn)
```

This pattern is necessary because SRAM must know the reverse path; the
generic `_forward_txn` (which forwards to the next hop) does not fit a
terminal.

#### D1.1. Currently dormant — the `_worker` override is an unused path

At the time of writing, **no component actually sends a Transaction to the
SRAM node**. The verified references to the SRAM node ID are:

- `policy/routing/router.py` and friends — guarantee path lookups.
- `components/builtin/pe_dma.py::_handle_ipcq_inbound` — for
  `buffer_kind == "sram"`, computes the *path* to
  `bank_node = f"{cube_prefix}.sram"` via `compute_drain_ns(path, ...)` and
  yields a **local** timeout. The Transaction itself does not flow to the
  SRAM node (see D4).
- `tests/test_routing.py` — checks connectivity via
  `find_path("sip0.cube0.pe0", "sip0.cube0.sram")`.

So the `_worker` / `_send_response` override is currently a **dormant code
path**. It is preserved deliberately:

- Topology changes that route fabric Transactions to SRAM terminally (e.g.,
  explicit M_CPU → SRAM accesses) would activate it immediately.
- ADR-0017's "cube-attached scratchpad" semantics naturally implies terminal
  behavior; the override is an intentional placeholder.

A future ADR (or a revision to this one) will mark dormancy resolved when an
actual sender is added.

### D2. ResponseMsg construction and reverse-path dispatch

`_send_response`:

1. `reverse_path = list(reversed(txn.path))` — derive the reverse path.
2. Construct `ResponseMsg(correlation_id=txn.request.correlation_id,
   request_id=..., src_cube=<this cube>, src_pe=-1, success=True)`.
3. Wrap in `Transaction(request=resp_msg, path=reverse_path, step=0,
   nbytes=0, done=env.event(), is_response=True)` and put on
   `out_ports[reverse_path[1]]`.
4. If the reverse path is too short (`< 2 hops`) or `ctx` is absent, fall
   back to calling the original `txn.done.succeed()`.

`src_pe = -1` means "SRAM is not PE-localized". `src_cube` is parsed from the
node ID (`sip{S}.cube{C}.sram`).

### D3. Timing parameters: `overhead_ns` and wire-side `drain_ns`

- **Component-side latency**: `node.attrs["overhead_ns"]`. Default topology
  uses `2.0 ns`.
- **Link-side serialization**: `drain_ns` arrives stamped on the Transaction
  — the wire-side BW serialization result from ADR-0015. SRAM only yields it.
- The `size_mb` (default `32 MiB`) attr is currently timing-neutral. If a
  capacity-aware model is added in the future, a separate ADR will give it
  meaning.

### D4. IPCQ slot accounting is not modeled by the SRAM component

Per ADR-0023 D9.7, the IPCQ slot-write latency for the SRAM tier is incurred
inside PE_DMA's `_handle_ipcq_inbound`, which calls
`slot_io_latency_ns("sram", nbytes)` using `_BUFFER_KIND_BW["sram"]`. That is:

- When SRAM receives a fabric Transaction (D1, D2, D3 apply), it processes
  normally.
- When an IPCQ slot lives on SRAM, PE_DMA pays the slot-write time directly —
  independent of the SRAM component.

This separation is intentional: IPCQ is a fast path (sub-cycle slot
bookkeeping) and does not traverse fabric Transactions, so SRAM does not need
to know about IPCQ.

### D5. SRAM's cube-NoC attachment is placement-driven

`topology/mesh_gen.py` reads `placement.sram.pos_mm` (default `[1.5, 9.0]` in
`topology.yaml`) and adds `"sram"` to the nearest router's `attach`. The
builder (`topology/builder.py`'s attachment loop) then lays bidirectional
edges between the `sram` node and that router.

This decision lives outside the SRAM component (mesh_gen / builder); the
component does not know which router it sits on. It only relies on
`txn.path` / `reverse_path` to reach it via a router.

### D6. SRAM is not a data store (timing only)

Same context as ADR-0040 D6: the SRAM component models time only; the data
payload (if any) lives in sim_engine's `memory_store`.

## Alternatives Considered

### A1. Use `_forward_txn` and route responses via separate nodes (à la IO_CPU / HBM_CTRL)

Rejected. SRAM is a terminal on the cube NoC; adding a response node would
introduce meaningless hops and violate ADR-0017's simplification spirit.

### A2. Model BW serialization inside SRAM with its own resource

Rejected. Wire-side BW serialization (`drain_ns`) already captures it. An
internal `simpy.Resource` would double-count against ADR-0015 (port/wire
model).

### A3. Handle IPCQ slot accounting in the SRAM component

Rejected. As D4 makes explicit, IPCQ is a fast path that does not traverse
fabric Transactions. If SRAM knew about IPCQ, the responsibility would split
across two places and obscure reasoning.

### A4. Capacity-aware latency from `size_mb`

Rejected for now. The capacity is currently a visualizer label; introducing
a capacity-aware timing model requires a dedicated ADR.

## Consequences

- SRAM's timing model is pinned at ADR level as
  `overhead_ns + drain_ns + ResponseMsg(reverse_path)`. Any proposal to push
  IPCQ slot latency into the SRAM component can be refused with D4.
- D3 records that `size_mb` is timing-neutral today, so a future
  capacity-aware model has a narrow compatibility scope.
- D5 documents the placement-driven attachment, so changes to the SRAM
  coordinate have a clearly bounded impact (`mesh_gen` only).