# 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