kernbench2/docs/adr-ko/ADR-0017-dev-cube-noc-and-hbm-connectivity.md

# ADR-0017: 큐브 NoC와 HBM 연결성

## Status

Accepted

## Context

CUBE 레벨의 NoC는 모든 큐브 내부 요청을 운반하는 2D 라우터 메시이다:
PE-HBM 데이터, PE-PE 트래픽, 명령 경로(M_CPU↔PE_CPU), 공유 SRAM 접근,
큐브 간 UCIe 트래픽.

CUBE의 HBM은 PE 라우터에 부착된 PE별 컨트롤러 엔드포인트를 통해 노출된다.
이러한 PE별 분할 덕분에 로컬-vs-원격 HBM이 메시 거리로 구분 가능하다:
PE 자신의 HBM 파티션은 자신의 라우터에 위치하고(스위칭 오버헤드만 발생),
다른 PE의 HBM 파티션은 해당 PE의 라우터로 메시 hop을 거쳐 도달 가능하다.

설계 공간에서는 두 가지 채널 매핑 모드를 지원한다:

- **n:1 (default, 구현됨)** — 각 PE의 HBM 파티션이 `channels_per_pe`
  pseudo-channel을 하나의 엔드포인트로 집계한다. 유효 PE당 BW =
  N × per-channel BW.
- **1:1 (future)** — 각 PE 라우터가 채널별 미니 라우터로 분해된다;
  채널별 BW 경합을 직접 모델링한다.

두 모드 모두 PE당 유효 BW는 동일하다; 연결 입도만 다르다.

## Decision

### D1. 2D 라우터 메시

각 큐브는 `mesh_gen.py`가 생성하는 2D 라우터 메시를 포함한다.

- 노드 명명: `sip{S}.cube{C}.r{row}c{col}` (예: `sip0.cube0.r0c0`).
- 구현: `forwarding_v1`. NoC `overhead_ns = 0`.
- 기본 6×6 그리드 (PE 코너 배치 + UCIe 부착 개수로 산정); 더 큰 PE
  개수는 그리드를 확장한다.
- HBM 제외 영역: HBM 다이가 물리적으로 점유하는 중앙 행/열을 제외한다
  (예: 6×6의 경우 r2c2, r2c3, r3c2, r3c3).
- 레이턴시 = Manhattan 거리 × `ns_per_mm`.

### D2. XY 라우팅 알고리즘

결정론적 XY 라우팅:

1. 수평 구간: 소스 X에서 목적지 X까지 소스 Y에서 라우팅.
2. 수직 구간: 소스 Y의 목적지 X에서 목적지 Y까지 라우팅.

각 유향 구간은 고유 키를 운반한다:

- 수평: `("H", y_band, x_min, x_max, direction)`
- 수직:   `("V", x_band, y_min, y_max, direction)`

그리드 위치는 HBM 영역을 제외하고 라우터 그리드에 스냅된다.

### D3. 구간별 경합 모델

각 유향 XY 구간은 `simpy.Resource(capacity=1)`이다. 동일 구간을 공유하는
트랜잭션(동일한 행 또는 열 밴드, 동일한 방향)은 자원을 두고 경합한다 —
wormhole 라우팅 메시에서의 링크 수준 직렬화를 모델링한다.

경합이 없을 때 NoC 순회 레이턴시는 Manhattan 거리 × `ns_per_mm`이다.
경합이 있을 때는 SimPy의 자원 스케줄링이 큐잉 지연을 추가한다.

### D4. NoC 부착 지점 (PE별 HBM 파티션)

모든 PE 라우터는 세 개의 부착을 갖는다: `pe{idx}.dma`, `pe{idx}.cpu`,
그리고 `pe{idx}.hbm`. 마지막은 PE별 HBM 컨트롤러 엔드포인트로
`sip{S}.cube{C}.hbm_ctrl.pe{idx}`이며, 큐브 HBM의 한 슬라이스를
소유한다 (하나의 pseudo-channel 그룹; D8 참조).

기타 부착:

- M_CPU와 공유 SRAM은 각각 전용 edge 라우터를 점유한다.
- UCIe 엔드포인트(N/S/E/W)는 각각 해당 변에 분산된 4개의 연결 라우터를
  노출한다 (D6 참조).

```text
                    UCIe-N (conn x4)
                         |
           +---------+---+---+---------+
           |         |       |         |
PE0.dma ---+  r0c0   |  ...  |  r0c5  +--- PE2.dma
PE0.cpu <--+ +hbm.pe0|       | +hbm.pe2+--< PE2.cpu
           |         |       |         |
UCIe-W ----+  ...    | [HBM] |  ...   +---- UCIe-E
(conn x4)  |         | zone  |         |  (conn x4)
           |  r2c0   |       |         |
M_CPU <--->+         |       |         |
           |  r3c0   |       |         |
SRAM <---->+         |       |         |
           |         |       |         |
PE4.dma ---+  r4c0   |  ...  |  r4c5  +--- PE6.dma
PE4.cpu <--+ +hbm.pe4|       | +hbm.pe6+--< PE6.cpu
           |         |       |         |
           +---------+---+---+---------+
                         |
                    UCIe-S (conn x4)
```

PE별 HBM 분할은 로컬 vs 크로스-PE HBM을 메시 거리로 구분 가능하게 만드는
핵심 불변식이다 (D7 참조).

### D5. NoC 엣지 대역폭과 거리

| Connection                    | BW (GB/s)  | Distance      | Notes                                       |
| ----------------------------- | ---------- | ------------- | ------------------------------------------- |
| PE_DMA → NOC                  | 256.0      | Physical (PE) | 로컬-HBM 집계 BW와 일치                     |
| NOC → PE_CPU                  | —          | 0.0 mm        | 명령 경로 전용                              |
| Router ↔ hbm_ctrl.pe{idx}     | 256.0      | 0.0 mm        | PE 라우터당; N × per-channel BW (D8 참조)   |
| NOC ↔ M_CPU                   | —          | 0.0 mm        | 명령 경로                                   |
| NOC ↔ SRAM                    | 128.0 × 4  | 0.0 mm        | 512 GB/s 집계                               |
| NOC ↔ UCIe conn               | 128.0      | 0.0 mm        | 연결당; 포트당 4개 conn                     |

`0.0 mm` 거리는 NoC의 분산 특성을 반영한다; 실제 순회 거리는 라우터
그리드 내에서 Manhattan 거리로 계산된다.

### D6. UCIe 분해와 큐브 간 트래픽

4개의 UCIe 포트(N, S, E, W) 각각은 다음으로 분해된다:

- `ucie-{PORT}` 노드 1개: UCIe 프로토콜 엔드포인트 (`overhead = 8.0 ns`).
- `ucie-{PORT}.conn{0-3}` 노드 4개: NoC와 UCIe 간 연결 브리지.

이 분해로 포트당 4개의 독립 NoC↔UCIe 연결이 생성되며, 각각 128 GB/s
대역폭을 갖는다 (포트당 집계 512 GB/s).

큐브 간 트래픽 경로:

```text
Source: PE_DMA → NOC → conn{i} → ucie-{PORT}
                  [UCIe link: 512 GB/s, 1.0mm seam distance]
Target: ucie-{PORT} → conn{i} → r{x}c{y} → (mesh hops) → hbm_ctrl.pe{idx}
```

UCIe 오버헤드(8.0 ns)는 각 `ucie-{PORT}` 노드에서 적용되므로 전체 횡단은
16 ns(TX 포트 + RX 포트)가 소요된다.

### D7. NoC를 통한 데이터 경로

모든 큐브 내부 트래픽은 동일한 라우터 메시를 사용한다 — 별도의 fast path는
없다.

**로컬 HBM** (동일 PE의 자신 파티션; 0 메시 hop):

```text
PE_DMA → r{x}c{y} → hbm_ctrl.pe{idx}   (switching overhead only)
```

**큐브 내 크로스-PE HBM** (대상 PE의 파티션, 메시로 도달):

```text
PE_DMA → r{x}c{y} → (mesh hops) → r{x'}c{y'} → hbm_ctrl.pe{idx'}
```

예시: PE0(`r0c0` 위)이 PE2의 HBM(PE2는 `r1c4` 위)에 접근:

```text
PE0.pe_dma → r0c0 → r0c1 → r0c2 → r0c3 → r0c4 → r1c4 → hbm_ctrl.pe2
```

Dijkstra가 메시 내 최단 경로를 계산한다.

**큐브 간 HBM** (UCIe 횡단):

```text
PE_DMA → r{x}c{y} → conn → ucie-{PORT} → [seam] → ucie-{PORT'} → conn
       → r{x'}c{y'} → hbm_ctrl.pe{idx'}
```

**PE로의 커널 launch 명령**:

```text
[from io_noc] → ucie → conn → r{x}c{y} → (mesh) → M_CPU → (mesh) → PE_CPU
```

**공유 SRAM 접근**:

```text
PE_DMA → r{x}c{y} → (mesh) → SRAM
```

### D8. HBM 채널 매핑 모드

채널 매핑은 큐브 범위에서 구성된다:

```yaml
cube:
  memory_map:
    hbm_mapping_mode: n_to_one       # one_to_one | n_to_one
    hbm_pseudo_channels: 64          # total pseudo-channel count
    hbm_channels_per_pe: 8           # per-PE local channel count
    hbm_channel_bw_gbs: 32.0         # per-channel bandwidth (GB/s)
    hbm_slices_per_cube: 8           # number of per-PE partitions
    hbm_total_gb_per_cube: 48
```

**n:1 모드 (default, 구현됨).** 각 PE의 HBM 파티션은 `channels_per_pe`
pseudo-channel을 집계하는 단일 엔드포인트 `hbm_ctrl.pe{idx}`이다.
`Router ↔ hbm_ctrl.pe{idx}` 링크 대역폭은 `channels_per_pe ×
hbm_channel_bw_gbs`와 같다. Pseudo-channel은 인터리브된다고 가정하며,
PE당 집계 BW만 모델링한다. 별도의 집계 라우터 노드는 존재하지 않는다 —
PE별 라우터 자체가 그 역할을 한다.

**1:1 모드 (future).** 각 PE 라우터가 N개의 채널 미니 라우터로
분해된다; 채널별 라우팅이 완전히 해석된 PA + channel ID를 운반한다.
`ChannelSplitter`가 논리적 접근을 N개의 채널별 물리 요청으로 해결한다.
채널별 링크가 BW 경합을 모델링한다. 크로스-PE 채널 접근 시맨틱은
구현 ADR로 연기된다.

**BW 계산 (default 값).**

| Parameter                          | Value                      |
| ---------------------------------- | -------------------------- |
| 큐브당 pseudo channel              | 64 (parameter)             |
| 큐브당 PE                          | 8 (parameter)              |
| PE당 channel (N)                   | 64 / 8 = 8                 |
| 채널당 BW                          | 32 GB/s (parameter)        |
| PE당 로컬 BW                       | N × 32 = 256 GB/s          |
| 큐브 전체 HBM BW                   | 64 × 32 = 2048 GB/s        |

두 모드 모두 PE당 유효 BW는 동일하다; 요청 형태와 경합 모델만 다르다.

### D9. AddressResolver — PE별 HBM 엔드포인트

주소 리졸버는 PA의 HBM 오프셋을 소유 PE의 파티션으로 디코딩한다:

```python
# policy/routing/router.py
hbm_slice_bytes = hbm_total_gb_per_cube * (1 << 30) // hbm_slices_per_cube

if addr.kind == "hbm":
    pe_id = int(addr.hbm_offset) // hbm_slice_bytes
    return f"sip{s}.cube{d}.hbm_ctrl.pe{pe_id}"
```

pe_id 계산은 라우팅 레이어의 본질적 일부이다 (토폴로지 시점 관심사가
아니다). 모든 HBM PA는 정확히 하나의 파티션에 속하므로 결정론적 라우팅이
보장된다.

외부 호출자(예: M_CPU DMA, PCIE_EP로부터의 Memory R/W)도 동일한 리졸버
경로를 따른다 — 별도의 fast path는 존재하지 않는다.

### D10. 메시 생성 파라미터

`mesh_gen.py`는 다음으로부터 `cube_mesh.yaml`을 생성한다:

- `cube.pe_layout`: 코너 배치(NW, NE, SW, SE)와 코너당 PE 개수.
- `cube.geometry`: 큐브 물리 치수와 HBM 영역.
- `cube.ucie.n_connections`: UCIe 부착용 라우터 개수를 결정.

출력 `mesh_data` 딕셔너리는 다음을 포함한다:

- 위치 및 HBM 제외 영역을 갖는 라우터 그리드.
- PE-라우터 부착 (PE별 `pe{idx}.dma`, `pe{idx}.cpu`, `pe{idx}.hbm`).
- UCIe-라우터 부착 (N/S/E/W가 edge 라우터에 분산).
- M_CPU와 SRAM 라우터 부착.

## Consequences

- 로컬 HBM(0 메시 hop, 스위칭 오버헤드만)과 크로스-PE HBM(메시 hop)이
  자연스럽게 구분되어 SPEC R5(다중 도메인 통신)와 ADR-0002(end-to-end
  제로 레이턴시 경로 금지)를 만족한다.
- 모든 큐브 내부 트래픽이 하나의 메시를 통해 라우팅된다 — 단일 경합
  모델, 단일 레이아웃, 단일 엣지 BW 집합.
- PE별 HBM 분할이 LA 모델(ADR-0011)에 깔끔하게 매핑된다: 각 PE의
  파티션은 할당된 pseudo-channel의 n:1 집계이다.
- 1:1 모드 확장이 구조적으로 자연스럽다 — 각 PE 라우터를 N개의 채널
  라우터로 분해한다.
- 메시 생성이 `topology.yaml`로 완전히 파라미터화된다; PE/큐브 기하
  변경이 코드 수정 없이 전파된다.

## Links

- ADR-0002 (라우팅 거리, 순서, 제로 레이턴시 경로 금지)
- ADR-0003 D3 (큐브 레벨 NoC 정의 — 본 ADR에서 확장)
- ADR-0004 (메모리 시맨틱, 로컬 HBM)
- ADR-0011 (메모리 주소 지정 — LA 모델이 PE별 파티션을 소비)
- ADR-0014 D1 (라우터 메시를 통한 PE_DMA egress)
- ADR-0015 D4 (Memory R/W와 Kernel Launch의 패브릭 경로)
- ADR-0016 (IOChiplet io_noc — IO 칩렛 레벨에서의 유사 패턴)
- ADR-0033 (레이턴시 모델: PC당 병렬성, 스위치 패널티)