kernbench2/docs/adr-ko/ADR-0012-api-host-io-message-schema.md

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