kernbench2/docs/adr-ko/ADR-0010-api-cli-surface-and-semantics.md

ADR-0010: 명령줄 인터페이스 및 실행 시맨틱

Status

Accepted

Context

kernbench CLI는 시뮬레이터의 사용자 대면 진입점이다. 네 개의 서브명령을 노출한다:

• run — 토폴로지에 대해 벤치마크를 실행한다.
• list — 등록된 벤치마크 목록을 출력한다.
• probe — 레이턴시 / 대역폭 측정을 위한 진단 유틸리티.
• web — 인터랙티브 토폴로지 뷰어.

디바이스 열거는 CLI에 중앙 집중화되어 있다. runtime API와 시뮬레이션 엔진 모두 디바이스를 열거하지 않는다. 벤치마크는 설계상 단일 디바이스를 유지하며 입력으로 디바이스 식별자를 받는다.

Decision

D1. 벤치마크 계약 — 설계상 단일 디바이스

• 벤치마크는 반드시 단일 디바이스에 대한 동작만 정의해야 한다.
• 벤치마크는 반드시 디바이스 식별자를 입력으로 받아야 한다.
• 벤치마크는 다중 디바이스를 열거하거나 루프해서는 안 된다.

다중 디바이스 실행은 벤치마크의 관심사가 아니라 CLI의 관심사이다(D3).

D2. kernbench run — 벤치마크 실행

필수 인자:

• --topology <path>: 토폴로지 YAML 파일 경로. resolve_topology()를 통해 로드된다.
• --bench <identifier>: 벤치마크 식별자. kernbench.benches.registry.resolve()를 통해 해석되며, 등록된 kebab-case 이름(예: gemm-single-pe) 또는 kernbench list 의 숫자 인덱스를 모두 받는다.

선택 인자:

• --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 list — 등록된 벤치마크 목록 출력

인자 없음. 각 등록된 벤치의 자동 부여된 인덱스, 등록된 이름, 한 줄 설명을 출력한다.

벤치는 @bench(name=..., description=...) 데코레이터 (kernbench.benches.registry)를 통해 자기 자신을 등록한다. kernbench.benches/ 아래의 언더스코어로 시작하지 않는 모든 모듈은 반드시 최소 하나의 벤치를 등록해야 한다; 데코레이터가 누락되면 패키지 import 시점에 RuntimeError가 발생한다.

인덱스는 import 시점에 이름의 알파벳 순으로 부여된다. 인덱스는 --bench 의 축약 표기를 위한 CLI 편의 기능이며 안정적인 API가 아니다 — 알파벳 순으로 새 벤치가 끼면 이후 인덱스가 밀린다.

D5. kernbench probe — 레이턴시 / 대역폭 진단 유틸리티

필수 인자:

• --topology <path>: 토폴로지 YAML 파일 경로.

선택 인자:

• --case <name> (기본값: all) — 미리 정의된 트래픽 패턴을 실행하거나, all로 정의된 모든 케이스를 실행한다.

Probe는 시뮬레이션 엔진을 통해 각 패턴을 실행하고 케이스별로 다음을 보고한다:

• 종단 간 레이턴시(ns).
• 유효 대역폭(nbytes / total_ns).
• 병목 대역폭(선택된 경로상의 최소 엣지 BW).
• 활용률(유효 / 병목).

Probe는 추가로 단조성 불변식을 검증한다 — 예를 들어 local-HBM 접근 ≤ 큐브 내 PE 간 ≤ 큐브 간 ≤ SIP 간 — 그리고 위반을 보고한다. Probe는 레이턴시 / 대역폭 모델을 검증하기 위한 개발자 도구이다; 벤치마크가 아니다.

D6. kernbench web — 토폴로지 뷰어

선택 인자:

• --port <N> (기본값: 8765) — HTTP 포트.
• --no-open — 브라우저를 자동으로 열지 않는다.

컴파일된 토폴로지를 브라우저에서 렌더링하는 로컬 HTTP 서버를 띄운다. 정적인 docs/diagrams/ 산출물과는 구별된다:

• docs/diagrams/ 파일은 토폴로지 컴파일 시점에 파생된다(ADR-0006).
• kernbench web은 인터랙티브이다 — 팬/줌, 컴포넌트 속성 호버, SIP / CUBE / PE 뷰 간 전환.

D7. runtime API와 시뮬레이션 엔진은 디바이스 스코프를 유지한다

• runtime API 호출은 호출당 하나의 디바이스에서 동작한다.
• 시뮬레이션 엔진은 모든 요청을 결정론적으로 스케줄링한다.
• 어느 레이어도 디바이스를 열거하지 않는다.

이 불변식은 각 레이어를 독립적으로 테스트 가능하게 유지한다; 디바이스 열거와 다중 디바이스 팬아웃은 오직 CLI의 run 명령에만 존재한다(D3).

probe 구현은 kernbench.probes 아래에 있다 (kernbench.benches와 분리됨). 이는 probe가 등록된 벤치가 아니라 진단 유틸리티임을 반영한다.

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의 배경)