# ADR-0005: 다이어그램 뷰 및 거리 기반 레이아웃 규칙

## Status

Accepted

## Context

대규모, 매개변수화된 AI Accelerator 시스템에 대해 검증 가능하고 점검 가능한
시스템 모델링이 필요하다.

사람이 다음을 할 수 있어야 한다:

- 모델링된 토폴로지를 시각적으로 점검하고,
- 통신 구조와 상대적 거리에 대해 추론하고,
- 세부 사항에 압도되지 않으면서 여러 추상화 수준에서 이를 수행한다.

시뮬레이터는 거리(누적 레이턴시)를 1급 개념(first-class concept)으로 모델링한다.
다이어그램은 기본적으로 이 거리를 반영해야 한다.

---

## Decision

### D1. Global Defaults

- 모든 다이어그램은 기본적으로 **거리 인식(distance-aware)** 이어야 한다.
- 모든 다이어그램은 아키텍처의 **대표 뷰(representative view)** 를 렌더링해야 한다.
- 인스턴스 인덱스(예: sip0, cube2, pe3)는 다이어그램 생성에 필수가 아니어야 한다.
- 인스턴스 인덱스는 다음의 경우에만 사용될 수 있다:
  - 비대칭 또는 디버깅 시나리오에서 거리 앵커를 정의하기 위한 경우, 또는
  - 명시적으로 요청된 경우.

---

### D2. Representative Rendering Rule

- 모든 CUBE는 동일한 내부 구조를 공유한다.
- 모든 PE는 동일한 내부 구조를 공유한다.

따라서:

- SIP 수준 다이어그램은 대표 CUBE와 IO 칩렛을 렌더링한다.
- CUBE 수준 다이어그램은 대표 PE를 불투명 블록으로 렌더링한다.
- PE 수준 다이어그램은 내부가 완전히 전개된 대표 PE를 렌더링한다.

다이어그램은 명시적으로 요청되지 않는 한
특정 SIP, CUBE, 또는 PE 인덱스에 의존해서는 안 된다.

---

### D3. Diagram Views

#### View A — SIP 수준 다이어그램

**목적**
시스템 규모의 구조와 연결성을 설명한다.

**가시 요소**

- SIP 경계 (선택사항)
- CUBE (불투명 블록)
- IO 칩렛 (불투명 블록)
- 연결성 명확화에 필요한 경우에만 선택적 UCIe 스텁

**비가시 요소**

- PE 내부
- CUBE 내부 패브릭
- IO 칩렛 내부

**가시 링크**

- 호스트 ↔ IO 칩렛 (PCIe)
- SIP ↔ SIP (스위치를 통한 PCIe / UAL)
- IO ↔ CUBE (온패키지 링크)

---

#### View B — CUBE 수준 다이어그램

**목적**
큐브 내부 구조와 데이터/제어 흐름을 설명한다.

**가시 요소**

- 라우터 메시: NoC 라우터의 2D 격자 (cube_mesh.yaml로부터), 모든 트래픽은 메시를 통해 라우팅됨
- PE 라우터에 부착된 HBM_CTRL (로컬 HBM = 0 홉)
- HBM 서브시스템 (HBM_CTRL)
- 공유 SRAM: 큐브 수준 공유 메모리
- 관리 CPU (M_CPU)
- 불투명 블록으로 표현된 PE (PE[0..N−1])
- 포트로 표현된 UCIe 엔드포인트 (N/E/W/S)

**비가시 요소**

- PE 내부

**가시 링크**

- PE → 라우터 (메시를 통한 HBM + 비-HBM 데이터 경로)
- 라우터 ↔ HBM_CTRL (로컬 HBM 액세스)
- 라우터 ↔ 라우터 (원격 액세스를 위한 메시 홉)
- 라우터 ↔ UCIe 엔드포인트
- 라우터 ↔ 공유 SRAM
- M_CPU ↔ 라우터 (명령 경로)
- 라우터 → PE_CPU (명령 전달, PE 블록 내부로 축약됨)

---

#### View C — PE 수준 다이어그램

**목적**
PE 내부 동작과 실행 구조를 설명한다.

**가시 요소**

- PE_CPU
- 명령 핸들러 / 스케줄러
- PE_TCM (로컬 SRAM)
- HW 가속기 (DMA, GEMM, MATH 등)
- 로컬 HBM 인터페이스
- 선택적 IPCQ / 메시징 엔드포인트

**가시 링크**

- 제어 경로 (CPU → 스케줄러 → 엔진)
- 데이터 경로 (엔진 ↔ TCM, DMA ↔ 로컬 HBM)
- 외부 패브릭 포트는 추상 포트로만 표현

---

### D4. 거리 기반 레이아웃 (기본)

#### 거리 정의

- 거리는 ADR-0002와 정합되도록 **누적 레이턴시(accumulated latency)** 로 정의된다.
- 거리는 단일 앵커 노드로부터 계산된다.

#### 기본 앵커 선택

- SIP 뷰: IO 칩렛 (또는 존재한다면 호스트 CPU)
- CUBE 뷰: 대표 PE
- PE 뷰: PE_CPU 또는 명령 핸들러

앵커는 **암묵적 기본값**이며, 지정이 강제되어서는 안 된다.

#### 레이아웃 규칙

- 다이어그램은 거리 버킷에 기반한 레이어로 배치되어야 한다.
- 레이아웃 방향은 뷰 유형 내에서 일관되어야 한다
  (선호: 좌→우).
- 동일 거리의 노드는 결정론적으로 안정된 순서를 가져야 한다
  (역할 또는 식별자 기준).

가독성을 위해 사이클은 점선 또는 곡선 엣지로 렌더링될 수 있으며,
이는 거리 의미에 영향을 주지 않는다.

---

### D5. 생성 컨트랙트 (도구 / Claude Code용)

다이어그램 생성 시:

- 기본적으로 거리 기반 레이아웃을 가정한다.
- 기본적으로 대표 렌더링을 가정한다.
- 필요한 경우가 아니면 SIP/CUBE/PE 인덱스를 묻지 않는다.
- 숨겨진 추상화 수준을 전개하지 않는다.
- 마이크로 홉의 정밀도보다 아키텍처적 명확성을 우선한다.

---

## Consequences

- 다이어그램은 토폴로지 스케일링에 걸쳐 안정적으로 유지된다.
- 거리 또는 라우팅 정책의 변경이 시각적으로 반영된다.
- 다이어그램은 수작업으로 유지되는 문서가 아닌, 시뮬레이터 모델로부터
  파생된 검증 가능한 산출물의 역할을 한다.

---

## Links

- SPEC Section 4 (Output, Debuggability, and Diagrams)
- ADR-0002 (라우팅 거리 의미)
- ADR-0006 (토폴로지 컴파일 및 자동 다이어그램 생성)