# ADR-0035: M_CPU 및 M_CPU.DMA 컴포넌트 모델

## Status

Accepted

## Context

M_CPU는 큐브 수준의 명령 프로세서이다. IO_CPU로부터(또는 엔진이
Memory R/W를 폴백으로 M_CPU를 거쳐 라우팅할 때 PCIE_EP로부터) 명령을
수신하여 자신의 큐브 내 PE들로 팬아웃하고, PE별 응답을 단일 ResponseMsg로
집계하여 역방향 경로를 통해 IO_CPU로 되돌려 보낸다.

M_CPU.DMA는 Memory R/W 팬아웃을 처리하는 큐브 수준의 DMA 채널 쌍이다.
ADR-0015 D5에 따라 별도의 토폴로지 노드가 **아니다** — `MCpuComponent`의
내부 상태로서 존재한다.

본 ADR은 위의 책임들을 실현하는 M_CPU 컴포넌트 구현을 문서화한다. 여기에는
세 가지 구별되는 팬아웃 경로(Memory R/W, Kernel Launch, MMU Map/Unmap),
M_CPU.DMA 자원 모델, 그리고 응답 집계 계약이 포함된다.

## Decision

### D1. 역할

M_CPU는 세 가지 책임을 갖는다:

1. **Transit 포워딩** — 종단 홉이 아닐 때(예: 역방향 응답 경로 PE →
   M_CPU → IO_CPU), 사전 계산된 경로의 `next_hop`으로 Transaction을
   전달한다.
2. **종단 홉에서의 멀티 PE 팬아웃** — 요청 타입에 따라 세 팬아웃 경로
   중 하나로 디스패치한다(D2).
3. **응답 집계** — PE별 응답을 수집하여 역방향 경로를 통해 단일 집계
   ResponseMsg를 IO_CPU로 되돌려 보낸다.

호출당(`run()`): 들어오는 Transaction마다 `overhead_ns`를 한 번 적용한다.

M_CPU는 다음을 하지 **않는다**:

- 라우팅 결정 — 경로는 라우터에 의해 사전 계산된다(ADR-0002).
- PE 내부 실행 처리 — PE_CPU / PE_SCHEDULER / 엔진들이 담당(ADR-0014).
- 주소 디코드 — `ctx.resolver.resolve(pa)`가 PE별 `hbm_ctrl.pe{X}`를
  직접 반환한다(ADR-0017 D9).
- 텐서 또는 커널 의미 해석 — 팬아웃 디스패치는 Python isinstance
  체크만으로 이루어진다.

### D2. 요청 타입으로 디스패치되는 세 가지 팬아웃 경로

종단 홉에서 워커는 요청 타입에 따라 디스패치한다:

```python
elif self.ctx is not None and txn.request is not None:
    if isinstance(txn.request, KernelLaunchMsg):
        env.process(self._kernel_launch_fanout(env, txn))
    elif isinstance(txn.request, (MmuMapMsg, MmuUnmapMsg)):
        env.process(self._mmu_msg_fanout(env, txn))
    else:
        env.process(self._dma_fanout(env, txn))
```

각 경로는 서로 다른 라우터 메서드를 사용한다:

- `_dma_fanout`은 `ctx.router.find_mcpu_dma_path()`를 사용 — PE 파이프라인
  노드를 우회하는 M_CPU 전용 DMA 경로.
- `_kernel_launch_fanout`은 `ctx.router.find_node_path()`를 사용 — PE_CPU로
  향하는 범용 NOC 명령 경로.
- `_mmu_msg_fanout`은 `ctx.router.find_node_path()`를 사용 — PE_MMU로
  향하는 NOC 명령 경로.

### D3. M_CPU.DMA 내부 서브 컴포넌트 (ADR-0015 D5)

`MCpuComponent.start()`는 두 개의 SimPy 자원을 초기화한다:

```python
self._dma_write = simpy.Resource(env, capacity=1)  # MemoryWriteMsg
self._dma_read  = simpy.Resource(env, capacity=1)  # MemoryReadMsg
```

특성:

- **토폴로지 노드가 아님** — 전적으로 `MCpuComponent` 내부에서 관리됨;
  `topology.yaml`이나 컴파일된 그래프에 나타나지 않는다.
- **독립된 읽기/쓰기 채널** — 동시 in-flight Memory R/W가 허용된다.
- **채널당 capacity=1**은 본 M_CPU에서 동시 in-flight Memory R/W 요청의
  **디스패치 단계**(`yield self.out_ports[...].put(...)`)를 직렬화한다.
  실제 패브릭 전송 시간은 컴포넌트 사이의 와이어 프로세스(ADR-0015 D2)와
  종단 홉의 `drain_ns`로 모델링되며, DMA 자원은 전송 지속 시간을
  게이팅하지 않는다.

자원 선택은 요청 타입에 기반한다:

```python
dma_res = self._dma_write if isinstance(request, MemoryWriteMsg) else self._dma_read
```

### D4. 비종단 홉에서의 transit 포워딩

`txn.next_hop`이 None이 아닐 때 — 전형적으로 역방향 응답 경로(PE →
M_CPU → IO_CPU)에서 — 워커는 정상적으로 전달한다:

```python
if next_hop:
    yield self.out_ports[next_hop].put(txn.advance())
```

팬아웃 분기는 종단 홉에서만 발화한다. 따라서 동일한 컴포넌트가 정방향
명령 디스패치 역할과 역방향 응답 중계 역할을 모두 수행한다.

### D5. DMA 팬아웃 (`_dma_fanout` — Memory R/W)

종단 홉에서 각 Memory R/W 요청에 대해:

1. `_resolve_dma_destinations(request)`가 요청의 PA로부터
   `ctx.resolver.resolve(PhysAddr.decode(pa))`를 통해 도출된 PE별
   `hbm_ctrl.pe{X}`를 반환한다(ADR-0017 D9).
2. 각 목적지에 대해:
   - `with dma_res.request() as req`를 통해 적절한 DMA 자원(`_dma_write`
     또는 `_dma_read`)을 획득.
   - `ctx.router.find_mcpu_dma_path()`로 경로를 해석.
   - `drain_ns = ctx.compute_drain_ns(path, nbytes)`를 계산.
   - `drain_ns`를 운반하는 서브 Transaction을 생성하여 `path[1]`로
     디스패치.
3. 목적지들에 걸쳐 `max_drain_ns`를 추적하고, 모든 응답 도착 후
   `txn.result_data["xfer_ns"]`로 기록한다.
4. PE별 응답이 모두 수집된 후(D8), IO_CPU로 되돌아가는 역방향 명령
   경로로 집계 ResponseMsg를 전송한다.

PA 디코드 폴백(`f"{cube_prefix}.hbm_ctrl"`)은 레거시 데드 코드이다 —
ADR-0017 D4의 PE별 파티셔닝 이후로 그러한 노드는 존재하지 않는다.
방어적으로 남겨두었으나 실제 목적지로 라우팅되지는 않는다.

### D6. Kernel launch 팬아웃 (`_kernel_launch_fanout`)

종단 홉에서 `KernelLaunchMsg`에 대해:

1. `_resolve_pe_ids(target_pe)` → 본 큐브 내 PE id 리스트.
2. 각 PE에 대해: `ctx.router.find_node_path()`를 통해
   `f"{cube_prefix}.pe{pe_id}.pe_cpu"`로의 경로를 찾음.
3. **`target_start_ns` 처리**(ADR-0009 D5):
   - 요청에 이미 `target_start_ns`가 실려 있으면(IO_CPU가
     ADR-0036 D3에 따라 스탬프함): **변경 없이 통과**.
   - 없으면(단위 테스트에서의 직접 M_CPU 런치):
     `env.now + max(PE별 leg 레이턴시)`로 큐브별 배리어를 계산하고
     `dataclasses.replace`로 스탬프.
4. `nbytes=0`인 서브 Transaction으로 디스패치(커널 런치는 제어 메시지;
   nbytes=0 유지는 팬아웃을 공유 first-hop 패브릭 BW에서 떼어내며,
   ADR-0036 D4를 미러링).
5. PE별 응답이 모두 도착한 후(D8), 각 서브 Transaction의 `result_data`로부터
   PE별 메트릭을 부모 트랜잭션으로 집계한다:

   ```python
   txn.result_data["pe_exec_ns"]  = max(existing, max(pe_exec_values))
   txn.result_data["dma_ns"]      = max(existing, max(dma_values))
   txn.result_data["compute_ns"]  = max(existing, max(compute_values))
   ```

   기존 값과의 max 병합이 중요한 이유는 크로스 큐브 IO_CPU 팬아웃이
   동일한 부모 `result_data`를 공유하기 때문이다; 병합을 통해 한 큐브가
   다른 큐브의 메트릭을 덮어쓰는 일을 방지한다.
6. IO_CPU로 되돌아가는 역방향 경로로 집계 ResponseMsg를 전송.

### D7. MMU map/unmap 팬아웃 (`_mmu_msg_fanout`)

종단 홉에서 `MmuMapMsg` / `MmuUnmapMsg`에 대해:

1. `_resolve_pe_ids(target_pe)` → PE id들.
2. 각 PE에 대해: `find_node_path()`를 통해
   `f"{cube_prefix}.pe{pe_id}.pe_mmu"`로의 경로를 찾음.
3. `nbytes=0`인 서브 Transaction으로 디스패치.
4. PE_MMU는 종단 노드이다 — ResponseMsg를 되돌려 보내지 **않는다**.
   대신 서브 Transaction 자체의 `sub_done` 이벤트가 완료 시그널 역할을
   한다.
5. 모든 `sub_done` 이벤트를 인라인으로 기다림(`_pending` 카운터를 사용
   **하지 않음** — D8은 응답을 동반하는 팬아웃 전용).
6. IO_CPU로 되돌아가는 역방향 경로로 집계 ResponseMsg를 전송.

### D8. 응답 집계 (`_pending` + `_parent_txns`)

DMA 및 kernel-launch 팬아웃(역방향 경로로 도착하는 PE별 ResponseMsg를
예상함)에 대해:

```python
self._pending: dict[str, tuple[int, int, simpy.Event]] = {}
self._parent_txns: dict[str, Any] = {}
```

- 디스패치 시: `(expected, received=0, all_done)`을 등록하고 부모
  트랜잭션을 기억.
- `_worker`는 `is_response=True`로 응답을 인식하여 `_collect_response`로
  라우팅하며, `_collect_response`는 `received`를 증가시키고 `received >=
  expected`일 때 `all_done`을 시그널한다.
- `yield all_done` 후, 팬아웃 경로는 집계 ResponseMsg를 구성한다:

  ```python
  resp_msg = ResponseMsg(
      correlation_id=request.correlation_id,
      request_id=request.request_id,
      src_cube=cube_id,
      src_pe=-1,             # -1 = M_CPU 집계, 단일 PE가 아님
      success=True,          # 실패 의미는 구현되어 있지 않음
  )
  ```

- 응답 Transaction은 `list(reversed(txn.path))`를 따라 IO_CPU로
  되돌아간다.

MMU 팬아웃(D7)은 PE_MMU가 종단이므로 더 단순한 `sub_done` 이벤트의
인라인 리스트를 사용한다 — 가로챌 ResponseMsg 경로가 없다.

### D9. 헬퍼와 설정 가능한 속성

`_resolve_pe_ids(target_pe)`:

- `int` → `[target_pe]`
- `tuple[int, ...]` → `list(target_pe)`
- `"all"` → `range(n_slices)`, 여기서 `n_slices`는 큐브
  `memory_map.hbm_slices_per_cube`(기본 8)에서 가져온다.

Kernel-launch 및 MMU 팬아웃 경로에서 사용된다.

인스턴스별 레이턴시를 결정하는 단일 설정 가능 속성:

| 사이트 | impl 이름 | overhead_ns |
| --- | --- | --- |
| 큐브 `m_cpu` | `builtin.m_cpu` | 5.0 |

Transaction마다 `run()`에서 한 번 적용 — M_CPU에서의 명령 해석 및
디스패치 결정 시간을 모델링한다.

## Consequences

### Positive

- 세 가지 팬아웃 경로가 요청 타입에 의해 명확히 분리됨 — 새로운 요청
  종류 추가는 isinstance 분기 한 줄과 팬아웃 메서드 하나로 가능.
- M_CPU.DMA 채널은 독립적이며(읽기/쓰기가 동시 실행됨) capacity=1에서
  디스패치 단계만 직렬화된다.
- Transit 대 종단 동작이 단일 `if next_hop` 체크이므로, 동일한 컴포넌트가
  역할 중복 없이 정방향 디스패치와 역방향 응답 중계를 처리한다.
- `target_start_ns` 통과(D6)는 IO_CPU가 수립한 크로스 큐브 배리어
  (ADR-0036 D3)를 보존하며, 폴백 계산은 직접 M_CPU 단위 테스트가 계속
  동작하도록 한다.
- 부모 `result_data`의 기존 값에 대한 PE별 메트릭의 `max` 병합은 동일한
  부모를 공유하는 크로스 큐브 IO_CPU 팬아웃에 견고하다.

### Negative

- 부분 실패 의미가 없음 — 누락된 PE별 응답은 부모 `all_done`을 무기한
  스톨시킨다. 시뮬레이션 용도로는 수용 가능하나 프로덕션 스타일의
  엔드포인트로는 적합하지 않다.
- `_resolve_dma_destinations`의 큐브 전역 hbm_ctrl 폴백은 데드 코드이다
  (ADR-0017 D4 이후 그런 노드는 존재하지 않음). 방어적으로 남겨두었으나
  혼동을 유발하므로 후속 정리가 권장된다.
- DMA 자원 직렬화는 디스패치에만 적용된다(언바운드 store에서 `put`
  호출은 즉시적). capacity=1 채널은 "본 M_CPU에서 동시에 in-flight인
  요청은 하나"를 모델링하며 "전송 지속 시간 직렬화"를 모델링하지 않는다
  — 실제 전송 병렬성은 와이어 프로세스(ADR-0015 D2)와 `drain_ns`를
  참조해야 한다.

## Links

- ADR-0009 D3 (M_CPU 팬아웃 및 집계 완료 의미)
- ADR-0009 D5 (`target_start_ns` — 존재 시 변경 없이 통과; 부재 시
  큐브별 배리어로 계산)
- ADR-0011 D-VA3 (MmuMapMsg 패브릭 경로에 M_CPU가 PE 팬아웃 지점으로
  포함됨)
- ADR-0014 D4 (DMA 엔진 capacity=1; M_CPU.DMA가 큐브 수준에서 동일한
  계약을 미러링)
- ADR-0015 D5 (M_CPU.DMA는 M_CPU의 내부 서브 컴포넌트이며 토폴로지
  노드가 아님)
- ADR-0017 D9 (AddressResolver가 PE별 `hbm_ctrl.pe{X}`를 반환)
- ADR-0036 D3 / D4 (IO_CPU가 `target_start_ns`를 스탬프; M_CPU는 변경
  없이 통과; 팬아웃 전반에서 nbytes=0 불변식 보존)