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.1 KiB
5.1 KiB
ADR-0010: 명령줄 인터페이스 및 실행 시맨틱
Status
Accepted
Context
kernbench CLI는 시뮬레이터의 사용자 대면 진입점이다. 세 개의 서브명령을
노출한다:
run— 토폴로지에 대해 벤치마크를 실행한다.probe— 레이턴시 / 대역폭 측정을 위한 진단 유틸리티.web— 인터랙티브 토폴로지 뷰어.
디바이스 열거는 CLI에 중앙 집중화되어 있다. runtime API와 시뮬레이션 엔진 모두 디바이스를 열거하지 않는다. 벤치마크는 설계상 단일 디바이스를 유지하며 입력으로 디바이스 식별자를 받는다.
Decision
D1. 벤치마크 계약 — 설계상 단일 디바이스
- 벤치마크는 반드시 단일 디바이스에 대한 동작만 정의해야 한다.
- 벤치마크는 반드시 디바이스 식별자를 입력으로 받아야 한다.
- 벤치마크는 다중 디바이스를 열거하거나 루프해서는 안 된다.
다중 디바이스 실행은 벤치마크의 관심사가 아니라 CLI의 관심사이다(D3).
D2. kernbench run — 벤치마크 실행
필수 인자:
--topology <path>: 토폴로지 YAML 파일 경로.resolve_topology()를 통해 로드된다.--bench <name>: 벤치마크 이름.benches.loader.resolve_bench()를 통해 해석된다.
선택 인자:
--device <selector>(기본값:all):all— 발견된 SIP마다 한 번씩 실행한다(D3 참고).sip:<N>— SIP N에서만 실행한다.resolve_device()를 통해 파싱된다.
--verify-data(기본값: off) — Phase 2 데이터 검증을 활성화한다 (ADR-0020 참고). 설정되면engine_factory가 엔진을enable_data=True로 구성한다. 벤치마크 실행 후, 기록된 op들의 진단 요약이 출력된다.
각 호출은 단일 시뮬레이션 인스턴스 내에서 벤치마크를 한 번 실행한다.
D3. 다중 디바이스 실행은 논리적으로 병렬이다
--device all(또는 생략) 상태이며 토폴로지에 SIP가 여러 개일 때:
- 벤치마크 실행은 단일 시뮬레이션 엔진 인스턴스에 제출된다.
- 시뮬레이션 시간 상에서 실행은 논리적으로 병렬이다.
- 디바이스 간 경합(공유 패브릭 대역폭, SIP 간 트래픽 등)이 자연스럽게 모델링된다.
CLI는 여러 OS 프로세스나 독립된 시뮬레이션 실행을 생성하지 않는다 — 병렬성은 단일 시뮬레이션 인스턴스 내부에서 일어난다.
D4. kernbench probe — 레이턴시 / 대역폭 진단 유틸리티
필수 인자:
--topology <path>: 토폴로지 YAML 파일 경로.
선택 인자:
--case <name>(기본값:all) — 미리 정의된 트래픽 패턴을 실행하거나,all로 정의된 모든 케이스를 실행한다.
Probe는 시뮬레이션 엔진을 통해 각 패턴을 실행하고 케이스별로 다음을 보고한다:
- 종단 간 레이턴시(ns).
- 유효 대역폭(nbytes / total_ns).
- 병목 대역폭(선택된 경로상의 최소 엣지 BW).
- 활용률(유효 / 병목).
Probe는 추가로 단조성 불변식을 검증한다 — 예를 들어 local-HBM 접근 ≤ 큐브 내 PE 간 ≤ 큐브 간 ≤ SIP 간 — 그리고 위반을 보고한다. Probe는 레이턴시 / 대역폭 모델을 검증하기 위한 개발자 도구이다; 벤치마크가 아니다.
D5. kernbench web — 토폴로지 뷰어
선택 인자:
--port <N>(기본값:8765) — HTTP 포트.--no-open— 브라우저를 자동으로 열지 않는다.
컴파일된 토폴로지를 브라우저에서 렌더링하는 로컬 HTTP 서버를 띄운다.
정적인 docs/diagrams/ 산출물과는 구별된다:
docs/diagrams/파일은 토폴로지 컴파일 시점에 파생된다(ADR-0006).kernbench web은 인터랙티브이다 — 팬/줌, 컴포넌트 속성 호버, SIP / CUBE / PE 뷰 간 전환.
D6. runtime API와 시뮬레이션 엔진은 디바이스 스코프를 유지한다
- runtime API 호출은 호출당 하나의 디바이스에서 동작한다.
- 시뮬레이션 엔진은 모든 요청을 결정론적으로 스케줄링한다.
- 어느 레이어도 디바이스를 열거하지 않는다.
이 불변식은 각 레이어를 독립적으로 테스트 가능하게 유지한다; 디바이스
열거와 다중 디바이스 팬아웃은 오직 CLI의 run 명령에만 존재한다(D3).
Consequences
- 벤치마크 작성자는 단일 디바이스 로직을 작성한다; 다중 디바이스 동작은 CLI가 SIP들에 걸쳐 디스패치함으로써 자연스럽게 도출된다.
- 새로운 서브명령(예: 트레이스 내보내기, 리플레이) 추가는 벤치마크나 runtime API 변경을 요구하지 않는다 — CLI가 확장 포인트이다.
probe와web은 진단/시각화 도구이며 벤치마크가 아니다; 벤치마크 로더 경로를 우회한다.
Links
- SPEC R7, R8, R9
- ADR-0007 (Runtime API와 시뮬레이션 엔진 경계)
- ADR-0020 (Two-pass 데이터 실행 —
--verify-data) - ADR-0006 (토폴로지 컴파일과 다이어그램 생성 —
kernbench web의 배경)