ywkang/kernbench2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e77e4a17031808b2401ef63f1a05f1742a2b2fb4
kernbench2/docs/adr-ko/ADR-0012-api-host-io-message-schema.md
T
ywkang 168b0c89f0 ADR: translate adr-ko/ to Korean, fix ADR-0013 slug, refine Status check 
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>
2026-05-20 08:17:56 -07:00

240 lines
6.6 KiB
Markdown
Raw Blame History

# ADR-0012: Host ↔ IO_CPU 메시지 스키마 (PA-우선, PE-태깅)
## Status
Accepted
## Context
Phase 0은 PA-우선 메모리 모델을 사용한다(ADR-0011):
- 메모리 연산은 디바이스 물리 주소(PA)만 사용한다,
- VA/MMU/IOMMU는 모델링하지 않는다.
호스트 대면 runtime API는 IO_CPU 엔드포인트를 통해 디바이스와
상호작용한다. 다음을 보장하기 위해 Host ↔ IO_CPU에 대한 안정적이고
최소한의 메시지 스키마를 정의한다:
- 벤치마크는 안정적으로 유지된다,
- IO_CPU 내부의 팬아웃/집계는 독립적으로 진화할 수 있다,
- 완료와 실패 전파는 결정론적이다.
또한 PE-태깅(A 방식)을 요구한다: 각 샤드는 (sip,cube,pe)를 명시적으로
운반하여, IO_CPU가 PA 디코딩에 의존하지 않고 결정론적으로
라우팅/팬아웃할 수 있도록 한다.
---
## Decision
### D1. 계약 범위
본 스키마는 오직 Host ↔ IO_CPU에 대해서만 안정적인 계약이다.
IO_CPU를 넘어선 메시지(M_CPU, PE_CPU, 스케줄러, 엔진으로 가는 것)는
컴포넌트 내부 사항이며 Phase 0에서 이 호스트 계약의 일부가 아니다.
---
### D2. 필수 메시지 집합
runtime API는 Host ↔ IO_CPU에 대해 오직 다음 메시지 타입만 사용해야 한다:
- MemoryWrite
- MemoryRead
- KernelLaunch
벤치마크가 필요로 하는 모든 연산(텐서 초기화/복사, 커널 실행)은 이
메시지들로 표현 가능해야 한다.
---
### D3. 공통 envelope (모든 요청에 필수)
모든 Host ↔ IO_CPU 요청은 반드시 다음을 포함해야 한다:
- `msg_type: str`
- `correlation_id: str`
- 호스트에서 생성
- 응답을 결정론적으로 매칭하는 데 사용
- `request_id: str`
- correlation_id 내에서 고유함
- `target_device: str`
- 디바이스 식별자(예: "sip:0")
- `timestamp_tag: str | None` (선택)
- 디버그 태그 전용; 결정성에 영향을 주어서는 안 됨
모든 Host ↔ IO_CPU 응답은 반드시 다음을 포함해야 한다:
- `correlation_id: str`
- `request_id: str`
- `completion: Completion`
---
### D4. Completion 스키마 (필수)
`Completion`은 반드시 다음을 가져야 한다:
- `ok: bool`
- `error_code: str | None`
- `error_message: str | None`
규칙:
- `ok == true`이면 `error_code`와 `error_message`는 반드시 null이어야 한다.
- `ok == false`이면 `error_code`는 반드시 null이 아니어야 한다.
- 완료 시맨틱은 결정론적이어야 한다.
---
### D5. MemoryWrite 스키마 (PA-우선, PE-태깅)
`MemoryWrite`는 호스트에서 시작된 디바이스 메모리 쓰기/초기화 연산을
나타낸다.
필수 필드:
- 공통 envelope 필드 (D3)
- 목적지 배치 태그 (A 방식):
- `dst_sip: int`
- `dst_cube: int`
- `dst_pe: int`
- `dst_pa: int`
- 목적지 PE의 주소 공간 내 목적지 물리 주소
- `nbytes: int`
- `src_kind: "pattern" | "host_buffer_ref"`
- Phase 0은 반드시 "pattern"을 지원해야 한다
- `pattern: Pattern | None`
- `src_kind == "pattern"`인 경우 필수
`Pattern` (Phase 0 필수 지원):
- `pattern_kind: "zero" | "fill_u8" | "fill_u16" | "fill_u32" | "fill_fp16" | "fill_fp32"`
- `value: number | None`
- fill_*에 필요; zero에서는 무시됨
선택 필드:
- `dst_mem_kind: "HBM" | "TCM" | "AUTO"` (기본값 "AUTO")
- `debug_label: str | None`
비고:
- 이 메시지는 Phase 0에서 대용량 텐서 데이터를 임베드해서는 안 된다.
- 모든 레이턴시는 명시적인 그래프 순회 및 모델링된 컴포넌트로부터
발생해야 한다.
---
### D6. MemoryRead 스키마 (PA-우선, PE-태깅)
`MemoryRead`는 호스트에서 시작된 디바이스 메모리 읽기를 나타낸다.
필수 필드:
- 공통 envelope 필드 (D3)
- 소스 배치 태그 (A 방식):
- `src_sip: int`
- `src_cube: int`
- `src_pe: int`
- `src_pa: int`
- `nbytes: int`
선택 필드:
- `dst_kind: "host_sink" | "discard"` (기본값 "host_sink")
- `debug_label: str | None`
응답 페이로드:
- Phase 0에서는 실제 바이트는 필요하지 않다(레이턴시/트레이스 중심)
- 구현은 추후 새로운 ADR을 통해 가벼운 통계나 해시를 반환할 수 있다
---
### D7. KernelLaunch 스키마 (PA-우선, PE-태깅된 샤드)
`KernelLaunch`는 IO_CPU를 통해 대상 디바이스에서 커널을 런치하는 것을
나타낸다.
필수 필드:
- 공통 envelope 필드 (D3)
- `kernel_ref: KernelRef`
- `args: list[KernelArg]`
`KernelRef`는 반드시 다음을 가져야 한다:
- `name: str`
- `kind: "deployed" | "builtin"`
- `deploy_pa: int | None` — 커널 바이너리가 배치된 PA("deployed"에 필수)
- `deploy_sip: int` — 바이너리가 위치한 SIP
- `deploy_cube: int` — 바이너리가 위치한 큐브
- `deploy_pe: int` — 바이너리가 위치한 PE
- `nbytes_code: int` — 커널 바이너리 크기(BW 모델링용)
커널 바이너리는 MemoryWrite를 통해 디바이스 메모리에 사전 배치되어야 한다.
KernelLaunch는 커널 소스 코드나 IR을 런치 메시지에 임베드해서는 안 된다.
`KernelArg`는 PA 매핑을 통한 텐서 인자와 값을 통한 스칼라 인자를 지원한다.
텐서 인자 (필수):
- `arg_kind: "tensor"`
- `tensor_pa_map: TensorPAMap`
`TensorPAMap`은 반드시 다음을 가져야 한다:
- `shards: list[TensorShard]`
`TensorShard`는 반드시 다음을 가져야 한다 (A 방식 강제):
- `sip: int`
- `cube: int`
- `pe: int`
- `pa: int`
- `nbytes: int`
- `offset_bytes: int`
스칼라 인자 (필수):
- `arg_kind: "scalar"`
- `dtype: "i32" | "i64" | "fp16" | "fp32" | "bool"`
- `value: number | bool`
KernelLaunch 선택 필드:
- `grid: dict | None`
- `meta: dict | None`
- `failure_policy: "fail_fast" | "collect_all"` (기본값 "fail_fast")
- `debug_label: str | None`
비고:
- KernelLaunch는 대용량 텐서 데이터를 임베드해서는 안 된다.
- KernelLaunch는 오직 IO_CPU 엔드포인트에만 제출되어야 한다.
- IO_CPU는 샤드의 (sip,cube,pe) 태그를 사용하여 내부적으로 작업을
팬아웃해야 한다.
---
## Verification Notes
테스트는 다음을 검증해야 한다:
- 스키마 검증이 필수 필드 누락을 거부함,
- 결정론적 correlation/응답 매칭,
- MemoryWrite/Read/KernelLaunch가 명시적인 홉 트레이스를 생성함,
- 라우팅된 모든 요청은 레이턴시 > 0을 가짐.
---
## Links
- ADR-0011 (메모리 주소 지정 — PA / VA / LA)
- ADR-0007 (runtime_api와 sim_engine 경계)
- ADR-0009 (커널 실행 팬아웃/집계)
- ADR-0013 (검증 전략 — V1 메시지 스키마 검증)
- SPEC R2, R7, R8
Reference in New Issue View Git Blame Copy Permalink