ywkang
168b0c89f0
Follow-up to the bilingual-structure commit: docs/adr-ko/ now holds only Korean versions (24 files translated from English placeholders), ADR-0013 slug uses kebab-case in both folders, and the verify tool allows translated parenthetical commentary in the Status block. - Translate 24 English files in docs/adr-ko/ to Korean. The previous bilingual-structure commit had left these as English copies because their source content was already English; this commit fulfills the policy that docs/adr-ko/ contains only Korean. - Rename ADR-0013 in both adr/ and adr-ko/ from ver-verification_strategy.md to ver-verification-strategy.md (kebab-case consistency with other ADRs). - CLAUDE.md (ADR Translation Discipline): clarify that only the Status lifecycle keyword (Accepted / Proposed / Stub / Draft / Superseded by ADR-NNNN / Merged into ADR-NNNN) must match across EN and KO; parenthetical commentary and trailing list items may be translated. - tools/verify_adr_lang_pairs.py: replace byte-equal Status check with normalize_status_keyword() which strips parenthetical commentary and takes only the first non-empty line. - tests/test_verify_adr_lang_pairs.py: update existing test names, add coverage for translated parenthetical, translated trailing list, and Superseded-by-NNNN keyword equality. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
187 lines
5.5 KiB
Markdown
187 lines
5.5 KiB
Markdown
# 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 (토폴로지 컴파일 및 자동 다이어그램 생성)
|