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>
131 lines
5.2 KiB
Markdown
131 lines
5.2 KiB
Markdown
# 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.dot`
|
|
- `sip_view.svg` / `sip_view.mmd` / `sip_view.dot`
|
|
- `cube_view.svg` / `cube_view.mmd` / `cube_view.dot`
|
|
- `pe_view.svg` / `pe_view.mmd` / `pe_view.dot`
|
|
|
|
선택적으로, 멀티 토폴로지 워크플로우용:
|
|
|
|
- `sip_view__{topology_id}.svg`
|
|
- `cube_view__{topology_id}.svg`
|
|
- `pe_view__{topology_id}.svg`
|
|
|
|
### 저장소 정책
|
|
|
|
- 생성된 다이어그램 파일은 diff 기반 리뷰가 가능하도록 저장소에 커밋될 수 있다.
|
|
- 커밋된 경우, 이는 토폴로지 컴파일로부터 재현 가능해야 한다.
|
|
|
|
---
|
|
|
|
## Consequences
|
|
|
|
- 다이어그램은 항상 시뮬레이터 동작과 정합한다.
|
|
- 아키텍처 변경이 시각화에 자동으로 전파된다.
|
|
- 다이어그램 diff는 아키텍처 변경의 의미 있는 지표가 된다.
|
|
|
|
---
|
|
|
|
## Links
|
|
|
|
- SPEC Section 4 (Output, Debuggability, and Diagrams)
|
|
- ADR-0002 (거리 의미)
|
|
- ADR-0005 (다이어그램 뷰 및 레이아웃 규칙)
|