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

## Status

Accepted (2026-05-20).

ADR-0017 (Cube NOC and HBM Connectivity) 에서 SRAM이 cube NoC의 attachment로
존재한다고만 언급되는 점을 보완하여, SRAM 컴포넌트 자체의 latency/response
모델을 명시한다.

## First action (제일 처음에 하는 일)

`_worker`가 `_inbox`에서 Transaction을 한 건 꺼낸 직후 가장 먼저 하는 일은
`yield from self.run(env, txn.nbytes)` 호출이고, 그 안에서
`node.attrs["overhead_ns"]` (default `0.0`) 만큼 `env.timeout()`을 발생시킨다.

즉, **SRAM의 첫 일은 "access overhead를 시간으로 표현하는 것"**이다.
overhead 소비 이후에 `drain_ns` (그 Transaction에 부여된 terminal BW 직렬화 비용)
를 yield하고, 그 다음에 reverse path로 `ResponseMsg`를 생성하여 발사한다.

이는 일반 `ComponentBase._worker`와 다른 점이 있다: SRAM은 **terminal node**
임을 알고 있어서 `_forward_txn`을 거치지 않고 자체 워커가 `run → drain →
_send_response` 순서를 명시한다.

## Context

cube 토폴로지 (`topology/builder.py`) 는 cube마다 다음 명명된 노드를 만든다:

- `sip{S}.cube{C}.m_cpu`
- `sip{S}.cube{C}.sram`
- `sip{S}.cube{C}.hbm_ctrl` (PE당 partition)
- `sip{S}.cube{C}.pe{P}` (PE 내부 sub-component들)

SRAM은 cube NoC 의 attachment 중 하나로, 가장 가까운 router에 부착된다
(`topology/mesh_gen.py`가 placement 좌표로 nearest router 결정 후 `attach`에
추가). 빌더는 `sram ↔ router` 양방향 엣지를 깐다 (BW: `sram_to_router_bw_gbs`,
기본 `128.0 GB/s`).

SRAM의 두 가지 핵심 역할:

1. **fabric terminal**: cube NoC에서 SRAM으로 향한 메모리 access Transaction의
   끝점. SRAM이 access overhead와 drain을 소비하고 response를 reverse path로
   되돌린다.
2. **IPCQ slot tier 중 하나**: ADR-0023 D9.7 가 정의한 `buffer_kind ∈ {tcm,
   sram, hbm}` 중 `sram` 티어의 slot bw/overhead를
   `common/ipcq_types._BUFFER_KIND_BW`에서 참조 — 현재 값 `(512.0 GB/s, 2.0 ns)`.
   이 값은 SRAM 노드 attrs의 `overhead_ns`와는 별도이며, IPCQ slot 회계 시점에서
   PE_DMA가 시간으로 환산한다.

이 두 역할은 하나의 SRAM 컴포넌트에서 동시에 충족되는데, 별도 ADR이 없으면:

- "SRAM은 어떤 latency를 모델링하나?" — fabric drain + overhead, 아니면 IPCQ
  티어의 slot latency? — 답이 흩어진다.
- 미래에 SRAM 크기 (`size_mb`) attr이 실제로 어떤 의미를 갖는지 불명확. 현재
  코드는 size를 사용하지 않으며 timing만 모델링한다.
- SRAM이 cube의 어떤 router에 붙는지 (placement-based)에 대한 의사결정 근거가
  토폴로지 코드 안에만 있다.

## Decision

### D1. SRAM은 cube NoC의 terminal scratchpad 노드다

`SramComponent`는 `ComponentBase`를 상속하나 `_worker`를 오버라이드해서 terminal
의미를 직접 표현한다:

```
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)
```

이 패턴은 SRAM이 reverse path를 알아야 하므로 일반 `_forward_txn` (다음 hop으로
forward)이 아닌 자체 워커가 필요하다.

#### D1.1. 현재 미사용 — `_worker` 오버라이드는 dormant 경로다

본 ADR 작성 시점의 코드베이스에서는, **어떤 컴포넌트도 SRAM 노드로 Transaction
을 실제로 전송하지 않는다**. 확인된 SRAM 노드 ID 참조 위치:

- `policy/routing/router.py` 등 routing helper — path 조회 가능성만 보장.
- `components/builtin/pe_dma.py::_handle_ipcq_inbound` — IPCQ slot의
  `buffer_kind == "sram"` 일 때 `bank_node = f"{cube_prefix}.sram"` 의 *path*
  만 조회하여 `compute_drain_ns(path, ...)` 로 환산, **로컬에서 timeout** 한다.
  Transaction 자체는 SRAM 노드로 흘러가지 않는다 (D4 참고).
- `tests/test_routing.py` — `find_path("sip0.cube0.pe0", "sip0.cube0.sram")`
  로 connectivity만 검증.

따라서 `_worker`/`_send_response` 오버라이드는 **dormant code path** 이다.
삭제하지 않고 보존하는 이유:

- 향후 SRAM이 실제 fabric Transaction의 종점(예: M_CPU → SRAM 명시 access)이
  되는 토폴로지 변경 시 즉시 사용 가능.
- ADR-0017 (Cube NOC) 가 정의한 cube-attached scratchpad 의미에서 종점 동작은
  의미상 자연스러우므로, 의도된 placeholder 다.

이 dormant 상태가 종료되는 시점은 별도 ADR(또는 본 ADR의 후속 revision)이
명시한다.

### D2. ResponseMsg 생성과 reverse path 발사

`_send_response`는:

1. `reverse_path = list(reversed(txn.path))`로 역방향 경로 산출.
2. `ResponseMsg(correlation_id=txn.request.correlation_id, request_id=...,
   src_cube=<this cube>, src_pe=-1, success=True)` 생성.
3. `Transaction(request=resp_msg, path=reverse_path, step=0, nbytes=0,
   done=env.event(), is_response=True)` 로 감싸 `out_ports[reverse_path[1]]` 로
   put.
4. reverse path가 비정상이거나 (`< 2 hops`) ctx가 없으면, fallback으로 원본
   `txn.done.succeed()` 만 호출.

`src_pe = -1`은 "SRAM은 PE-localized가 아니다"를 의미한다. `src_cube`은 노드
ID (`sip{S}.cube{C}.sram`) 의 cube 인덱스를 파싱해 채운다.

### D3. Timing 파라미터는 `overhead_ns`와 wire-side `drain_ns`로 분리

- **컴포넌트 측 latency**: `node.attrs["overhead_ns"]`. 기본 토폴로지에서는 `2.0
  ns` 정도로 세팅.
- **링크 측 직렬화**: `drain_ns`는 Transaction이 도착 시점에 carry해 온 값으로,
  ADR-0015 (port/wire 모델) 의 wire-side BW 직렬화 결과다. SRAM은 이를 그대로
  yield하기만 한다.
- `size_mb` (default `32 MiB`) attr은 현재 timing에 사용되지 않는다 — 향후
  capacity-aware 모델이 도입되면 그때 의미를 부여한다 (별도 ADR에서).

### D4. IPCQ slot 회계는 SRAM 컴포넌트가 직접 모델링하지 않는다

ADR-0023 D9.7 에 따른 IPCQ slot의 SRAM-티어 write latency는 PE_DMA의
`_handle_ipcq_inbound`가 직접 `slot_io_latency_ns("sram", nbytes)`를 호출하여
시간을 소비한다 (그 함수는 `common/ipcq_types._BUFFER_KIND_BW["sram"]` 의 값을
사용). 즉:

- SRAM 컴포넌트가 fabric Transaction을 받아 처리할 때는 **D1·D2·D3** 만 적용.
- IPCQ slot이 SRAM에 살 때는 PE_DMA가 IPCQ slot-write 시점에 별도로 시간을
  지불 — 이는 SRAM 컴포넌트 코드와 무관하며, IPCQ 측 회계다.

이 분리는 의도된 것: IPCQ는 fast path (sub-cycle slot bookkeeping) 라 fabric
Transaction을 거치지 않으므로, SRAM이 IPCQ를 인지할 필요가 없다.

### D5. SRAM의 cube NoC 부착 위치는 placement-driven

`topology/mesh_gen.py`는 `placement.sram.pos_mm` (`topology.yaml` 기본
`[1.5, 9.0]`)을 보고 가장 가까운 router의 `attach`에 `"sram"`을 추가한다. 빌더
(`topology/builder.py` 의 attachment 루프)가 그 attach 정보를 보고 `sram` 노드와
router 사이에 양방향 엣지를 깐다.

이 의사결정은 SRAM 컴포넌트 코드 외부 (mesh_gen / builder) 에 있으며, 컴포넌트
는 어느 router에 붙었는지 알 필요가 없다. 컴포넌트는 `txn.path` / `reverse_path`
가 router를 거쳐 자신에게 도달한다는 사실만 알면 된다.

### D6. SRAM은 자체 데이터 저장소가 아니다 (timing-only)

ADR-0040 D6 과 같은 맥락: SRAM 컴포넌트는 시간만 모델링하며, 실제 데이터
페이로드는 sim_engine의 `memory_store` (있을 때) 가 보관한다.

## Alternatives Considered

### A1. SRAM이 `_forward_txn`을 그대로 사용하고 IO_CPU / HBM_CTRL 처럼 별도 응답 노드를 두기

기각. cube NoC 상에서 SRAM은 terminal이며, 응답을 받아 줄 별도 노드를 두면
의미 없는 hop이 늘어나고 ADR-0017 의 cube NoC 단순화 정신에 어긋난다.

### A2. SRAM이 BW 직렬화를 자체 resource로 모델링

기각. 링크 측 BW 직렬화 (`drain_ns`) 가 이미 의미를 충분히 잡고 있다. 컴포넌트
내부에 또 `simpy.Resource`를 두면 ADR-0015 wire-side 모델과 이중계산을 야기.

### A3. SRAM이 IPCQ slot 회계를 컴포넌트 측에서 처리

기각. D4에서 명시한 대로 IPCQ는 fast path며 fabric Transaction을 통과하지
않는다. SRAM이 IPCQ를 인지하면 책임이 두 갈래로 갈라져 추론이 어려워진다.

### A4. `size_mb`로 capacity-aware latency 모델

기각 (현재 단계). capacity는 토폴로지 visualizer 측 라벨링 정도에만 쓰이며,
실제 timing 영향은 아직 모델링하지 않는다. 필요해지면 별도 ADR로 도입.

## Consequences

- SRAM의 timing 모델이 `overhead_ns + drain_ns + ResponseMsg(reverse_path)`로
  ADR-level에서 굳어지므로, 누군가 IPCQ slot latency를 SRAM 컴포넌트에 추가하려
  할 때 D4를 근거로 거절할 수 있다.
- `size_mb` 가 현재 timing-neutral 임이 명시되어 (D3), 미래의 capacity-aware
  모델 도입 시 호환성 영향 범위가 좁다.
- placement-driven router 부착 (D5) 이 명시되어, SRAM 좌표 이동 시 어떤 부분에
  파급이 있는지 (`mesh_gen`만) 명확해진다.