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.2 KiB
5.2 KiB
ADR-0006: 토폴로지 컴파일, 거리 추출, 그리고 자동 다이어그램 생성
Status
Accepted
Context
시뮬레이터는 토폴로지 설정(예: topology.yaml)을 명시적인 모델 그래프로 컴파일하고, 라우팅 및 누적 레이턴시(거리)를 계산한다. 정합성을 보장하고 수작업으로 유지되는 토폴로지 도면을 피하기 위해, 다이어그램은 이 권위 있는 산출물로부터 생성되어야 한다.
또한 사용성을 위해, 다이어그램은 안정적인 위치로 자동 방출되어 개발자가 저장소 내에서 즉시 미리볼 수 있어야 한다.
Decision
D1. 토폴로지 컴파일은 유일한 진실 공급원이다
- topology.yaml(또는 동등한 설정)은 다음으로 컴파일된다:
- 명시적인 시스템 그래프,
- 노드/링크 속성,
- 라우팅 정책. 이 컴파일된 그래프가 시스템의 권위 있는 표현이다.
D2. 컴파일 중 거리 추출
- 토폴로지 컴파일 중 또는 그 직후, 시뮬레이터는 ADR-0002와 정합되는 거리 메타데이터(누적 레이턴시)를 계산해야 한다.
- 거리 메타데이터는 ADR-0005에서 정의한 거리 기반 다이어그램 레이아웃을 지원하기에 충분해야 한다.
- 분산된 패브릭 세그먼트(예: NoC)는 ADR-0002 D4에 따라 distance_mm = 0을 가질 수 있다. 이러한 노드의 레이아웃 배치는 거리 버킷이 아닌 명시적 위치 메타데이터를 사용한다.
D3. 다이어그램 생성은 파생 산출물이다
- 다이어그램은 다음으로부터 생성되어야 한다:
- 컴파일된 토폴로지 그래프,
- 추출된 거리 메타데이터,
- ADR-0005에 정의된 뷰/레이아웃 규칙.
- 다이어그램 생성은 추가적인 수작업 토폴로지 기술을 요구해서는 안 된다.
D4. 저장소로의 자동 다이어그램 방출
- 토폴로지 컴파일의 일부로서, 구현은 기본적으로 다음 다이어그램을 생성해야 한다:
- SIP 수준 다이어그램 (대표, 거리 인식)
- CUBE 수준 다이어그램 (대표, 거리 인식)
- PE 수준 다이어그램 (대표, 거리 인식)
- 기본 출력 디렉터리는 다음과 같다:
docs/diagrams/
- 생성기는 컴파일된 토폴로지(또는 다이어그램 규칙)가 변경되었을 때에만 덮어쓰기/업데이트해야 한다.
D5. 뷰별 투영 및 레이아웃
각 뷰(SIP / CUBE / PE)에 대해:
- 생성기는 컴파일된 그래프를 축소된 뷰 그래프로 투영해야 한다:
- ADR-0005에 따라 노드를 숨기거나 축약하고,
- 해당 뷰와 관련된 연결성 의미를 보존하고,
- 거리 버킷을 계산하여 레이아웃 레이어를 결정론적으로 할당한다.
- CUBE 수준 투영은 다음을 포함해야 한다:
- 라우터 메시 (cube_mesh.yaml로부터), HBM_CTRL, 공유 SRAM, M_CPU, UCIe 포트, 그리고 불투명 블록으로 표현된 PE.
- 모든 경로(HBM, 비-HBM, 명령)는 동일한 라우터 메시를 통해 라우팅된다 (ADR-0017).
- 기본 앵커는 암묵적이며 (ADR-0005) 인스턴스 인덱스를 요구해서는 안 된다.
D6. 출력 포맷과 결정론
- 생성기는 다음 중 최소 하나를 출력해야 한다:
- Mermaid (Markdown 네이티브)
- Graphviz DOT (rank 기반 제어)
- SVG (mm 단위 정확도 레이아웃, 외부 의존성 없음)
- 컴파일된 토폴로지로부터 mm 단위 정확도의 위치 메타데이터가 가용한 경우 SVG가 선호된다.
- 출력은 결정론적이어야 한다:
- 동일한 토폴로지 + 동일한 규칙 → 동일한 다이어그램 텍스트
- 파일 이름은 결정론적이고 안정적이어야 한다 (아래의 "출력 컨벤션" 참조).
D7. 성능 및 캐싱
- 다이어그램 생성은 지연(lazy) 및/또는 캐시될 수 있으며,
docs/diagrams/의 출력이 컴파일된 토폴로지와 정합을 유지하는 한 그렇다. - 구현은 다음을 기반으로 한 캐시 키를 사용해야 한다(SHOULD):
- 토폴로지 콘텐츠 해시,
- 라우팅 정책 버전,
- 다이어그램 규칙 버전,
- 뷰 유형 (SIP/CUBE/PE).
출력 컨벤션
디렉터리
docs/diagrams/는 생성된 다이어그램의 표준 출력 디렉터리이다.
파일 이름 (권장, 결정론적)
system_view.svg/system_view.mmd/system_view.dotsip_view.svg/sip_view.mmd/sip_view.dotcube_view.svg/cube_view.mmd/cube_view.dotpe_view.svg/pe_view.mmd/pe_view.dot
선택적으로, 멀티 토폴로지 워크플로우용:
sip_view__{topology_id}.svgcube_view__{topology_id}.svgpe_view__{topology_id}.svg
저장소 정책
- 생성된 다이어그램 파일은 diff 기반 리뷰가 가능하도록 저장소에 커밋될 수 있다.
- 커밋된 경우, 이는 토폴로지 컴파일로부터 재현 가능해야 한다.
Consequences
- 다이어그램은 항상 시뮬레이터 동작과 정합한다.
- 아키텍처 변경이 시각화에 자동으로 전파된다.
- 다이어그램 diff는 아키텍처 변경의 의미 있는 지표가 된다.
Links
- SPEC Section 4 (Output, Debuggability, and Diagrams)
- ADR-0002 (거리 의미)
- ADR-0005 (다이어그램 뷰 및 레이아웃 규칙)