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

# ADR-0012: Host ↔ IO_CPU Message Schema (PA-first, PE-tagged)

## Status

Accepted

## Context

Phase 0 uses a PA-first memory model (ADR-0011):

- memory operations use device physical addresses (PA) only,
- VA/MMU/IOMMU is not modeled.

The host-facing runtime API interacts with the device via the IO_CPU endpoint.
We define stable, minimal message schemas for Host ↔ IO_CPU so that:

- benchmarks remain stable,
- IO_CPU-internal fan-out/aggregation can evolve independently,
- completion and failure propagation is deterministic.

We also require PE-tagging (A 방식): each shard explicitly carries (sip,cube,pe)
so IO_CPU can deterministically route/fan-out without relying on PA decoding.

---

## Decision

### D1. Contract scope

This schema is the stable contract ONLY for Host ↔ IO_CPU.

Messages beyond IO_CPU (to M_CPU, PE_CPU, schedulers, engines) are component-internal
and are NOT part of this host contract in Phase 0.

---

### D2. Required message set

The runtime API MUST use only these message types for Host ↔ IO_CPU:

- MemoryWrite
- MemoryRead
- KernelLaunch

All operations required by benchmarks (tensor init/copy, kernel run) MUST be expressible
with these messages.

---

### D3. Common envelope (mandatory for all requests)

All Host ↔ IO_CPU requests MUST include:

- `msg_type: str`
- `correlation_id: str`
  - generated by the host
  - used to match responses deterministically
- `request_id: str`
  - unique within a correlation_id
- `target_device: str`
  - device identifier (e.g., "sip:0")
- `timestamp_tag: str | None` (optional)
  - debug tag only; MUST NOT affect determinism

All Host ↔ IO_CPU responses MUST include:

- `correlation_id: str`
- `request_id: str`
- `completion: Completion`

---

### D4. Completion schema (mandatory)

`Completion` MUST have:

- `ok: bool`
- `error_code: str | None`
- `error_message: str | None`

Rules:

- If `ok == true` then `error_code` and `error_message` MUST be null.
- If `ok == false` then `error_code` MUST be non-null.
- Completion semantics MUST be deterministic.

---

### D5. MemoryWrite schema (PA-first, PE-tagged)

`MemoryWrite` represents a host-initiated write/initialize operation to device memory.

Mandatory fields:

- common envelope fields (D3)
- destination placement tags (A 방식):
  - `dst_sip: int`
  - `dst_cube: int`
  - `dst_pe: int`
- `dst_pa: int`
  - destination physical address in the destination PE's address space
- `nbytes: int`
- `src_kind: "pattern" | "host_buffer_ref"`
  - Phase 0 MUST support "pattern"
- `pattern: Pattern | None`
  - required if `src_kind == "pattern"`

`Pattern` (Phase 0 mandatory support):

- `pattern_kind: "zero" | "fill_u8" | "fill_u16" | "fill_u32" | "fill_fp16" | "fill_fp32"`
- `value: number | None`
  - required for fill_*; ignored for zero

Optional fields:

- `dst_mem_kind: "HBM" | "TCM" | "AUTO"` (default "AUTO")
- `debug_label: str | None`

Notes:

- This message MUST NOT embed bulk tensor data in Phase 0.
- All latency MUST come from explicit graph traversal and modeled components.

---

### D6. MemoryRead schema (PA-first, PE-tagged)

`MemoryRead` represents a host-initiated read from device memory.

Mandatory fields:

- common envelope fields (D3)
- source placement tags (A 방식):
  - `src_sip: int`
  - `src_cube: int`
  - `src_pe: int`
- `src_pa: int`
- `nbytes: int`

Optional fields:

- `dst_kind: "host_sink" | "discard"` (default "host_sink")
- `debug_label: str | None`

Response payload:

- actual bytes are NOT required in Phase 0 (latency/traces focus)
- implementations MAY return lightweight stats or hashes later via a new ADR

---

### D7. KernelLaunch schema (PA-first, PE-tagged shards)

`KernelLaunch` represents launching a kernel on a target device via IO_CPU.

Mandatory fields:

- common envelope fields (D3)
- `kernel_ref: KernelRef`
- `args: list[KernelArg]`

`KernelRef` MUST have:

- `name: str`
- `kind: "deployed" | "builtin"`
- `deploy_pa: int | None` — PA where kernel binary was deployed (required for "deployed")
- `deploy_sip: int` — SIP where binary resides
- `deploy_cube: int` — cube where binary resides
- `deploy_pe: int` — PE where binary resides
- `nbytes_code: int` — kernel binary size (for BW modeling)

Kernel binaries MUST be pre-deployed to device memory via MemoryWrite.
KernelLaunch MUST NOT embed kernel source code or IR in the launch message.

`KernelArg` supports tensor args by PA mapping and scalars by value.

Tensor arg (mandatory):

- `arg_kind: "tensor"`
- `tensor_pa_map: TensorPAMap`

`TensorPAMap` MUST have:

- `shards: list[TensorShard]`

`TensorShard` MUST have (A 방식 강제):

- `sip: int`
- `cube: int`
- `pe: int`
- `pa: int`
- `nbytes: int`
- `offset_bytes: int`

Scalar arg (mandatory):

- `arg_kind: "scalar"`
- `dtype: "i32" | "i64" | "fp16" | "fp32" | "bool"`
- `value: number | bool`

Optional KernelLaunch fields:

- `grid: dict | None`
- `meta: dict | None`
- `failure_policy: "fail_fast" | "collect_all"` (default "fail_fast")
- `debug_label: str | None`

Notes:

- KernelLaunch MUST NOT embed bulk tensor data.
- KernelLaunch MUST be submitted only to the IO_CPU endpoint.
- IO_CPU MUST fan-out work internally using the shard (sip,cube,pe) tags.

---

## Verification Notes

Tests SHOULD validate:

- schema validation rejects missing mandatory fields,
- deterministic correlation/response matching,
- MemoryWrite/Read/KernelLaunch produce explicit hop traces,
- all routed requests incur latency > 0.

---

## Links

- ADR-0011 (Memory Addressing — PA / VA / LA)
- ADR-0007 (runtime_api vs sim_engine boundaries)
- ADR-0009 (kernel execution fan-out/aggregation)
- ADR-0013 (Verification strategy — V1 message schema validation)
- SPEC R2, R7, R8