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>
5.5 KiB
5.5 KiB
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 (토폴로지 컴파일 및 자동 다이어그램 생성)