benches: package as kernbench.benches, add @bench registry + list subcommand

Move benches/ -> src/kernbench/benches/ and src/kernbench/cli/probe.py ->
src/kernbench/probes/probe.py. Each bench self-registers via
@bench(name=..., description=...); kernbench list enumerates benches
with auto-assigned indices, --bench accepts kebab-case name or numeric
index. Audit at package-import time fails if any non-underscore module
forgets the decorator. ADR-0010 (EN + KO) updated to reflect the new
resolver path, list subcommand, and probes package separation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-20 14:42:10 -07:00
parent 168b0c89f0
commit 049e3d8bb3
28 changed files with 398 additions and 79 deletions
@@ -6,10 +6,11 @@ Accepted
## Context
`kernbench` CLI는 시뮬레이터의 사용자 대면 진입점이다. 개의 서브명령을
`kernbench` CLI는 시뮬레이터의 사용자 대면 진입점이다. 개의 서브명령을
노출한다:
- `run` — 토폴로지에 대해 벤치마크를 실행한다.
- `list` — 등록된 벤치마크 목록을 출력한다.
- `probe` — 레이턴시 / 대역폭 측정을 위한 진단 유틸리티.
- `web` — 인터랙티브 토폴로지 뷰어.
@@ -33,8 +34,9 @@ Accepted
- `--topology <path>`: 토폴로지 YAML 파일 경로. `resolve_topology()`
통해 로드된다.
- `--bench <name>`: 벤치마크 이름. `benches.loader.resolve_bench()`
통해 해석된다.
- `--bench <identifier>`: 벤치마크 식별자. `kernbench.benches.registry.resolve()`
통해 해석되며, 등록된 kebab-case 이름(예: `gemm-single-pe`) 또는
`kernbench list` 의 숫자 인덱스를 모두 받는다.
선택 인자:
@@ -61,7 +63,22 @@ Accepted
CLI는 여러 OS 프로세스나 독립된 시뮬레이션 실행을 생성하지 **않는다**
병렬성은 단일 시뮬레이션 인스턴스 내부에서 일어난다.
### D4. `kernbench probe` — 레이턴시 / 대역폭 진단 유틸리티
### D4. `kernbench list` — 등록된 벤치마크 목록 출력
인자 없음. 각 등록된 벤치의 자동 부여된 인덱스, 등록된 이름,
한 줄 설명을 출력한다.
벤치는 `@bench(name=..., description=...)` 데코레이터
(`kernbench.benches.registry`)를 통해 자기 자신을 등록한다.
`kernbench.benches/` 아래의 언더스코어로 시작하지 않는 모든 모듈은
반드시 최소 하나의 벤치를 등록해야 한다; 데코레이터가 누락되면
패키지 import 시점에 `RuntimeError`가 발생한다.
인덱스는 import 시점에 이름의 알파벳 순으로 부여된다. 인덱스는
`--bench` 의 축약 표기를 위한 CLI 편의 기능이며 안정적인 API가
아니다 — 알파벳 순으로 새 벤치가 끼면 이후 인덱스가 밀린다.
### D5. `kernbench probe` — 레이턴시 / 대역폭 진단 유틸리티
필수 인자:
@@ -85,7 +102,7 @@ Probe는 추가로 단조성 불변식을 검증한다 — 예를 들어 local-H
레이턴시 / 대역폭 모델을 검증하기 위한 개발자 도구이다; 벤치마크가
아니다.
### D5. `kernbench web` — 토폴로지 뷰어
### D6. `kernbench web` — 토폴로지 뷰어
선택 인자:
@@ -99,7 +116,7 @@ Probe는 추가로 단조성 불변식을 검증한다 — 예를 들어 local-H
- `kernbench web`은 인터랙티브이다 — 팬/줌, 컴포넌트 속성 호버,
SIP / CUBE / PE 뷰 간 전환.
### D6. runtime API와 시뮬레이션 엔진은 디바이스 스코프를 유지한다
### D7. runtime API와 시뮬레이션 엔진은 디바이스 스코프를 유지한다
- runtime API 호출은 호출당 하나의 디바이스에서 동작한다.
- 시뮬레이션 엔진은 모든 요청을 결정론적으로 스케줄링한다.
@@ -108,6 +125,9 @@ Probe는 추가로 단조성 불변식을 검증한다 — 예를 들어 local-H
이 불변식은 각 레이어를 독립적으로 테스트 가능하게 유지한다; 디바이스
열거와 다중 디바이스 팬아웃은 오직 CLI의 `run` 명령에만 존재한다(D3).
`probe` 구현은 `kernbench.probes` 아래에 있다 (`kernbench.benches`
분리됨). 이는 probe가 등록된 벤치가 아니라 진단 유틸리티임을 반영한다.
## Consequences
- 벤치마크 작성자는 단일 디바이스 로직을 작성한다; 다중 디바이스 동작은