233 lines
5.5 KiB
Markdown
233 lines
5.5 KiB
Markdown
# 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 (PA-first memory addressing)
|
|
- ADR-0007 (runtime_api vs sim_engine boundaries)
|
|
- ADR-0009 (kernel execution fan-out/aggregation)
|
|
- SPEC R2, R7, R8
|