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>
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
# ADR-0012: Host ↔ IO_CPU Message Schema (PA-first, PE-tagged)
|
||||
# ADR-0012: Host ↔ IO_CPU 메시지 스키마 (PA-우선, PE-태깅)
|
||||
|
||||
## Status
|
||||
|
||||
@@ -6,63 +6,65 @@ Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Phase 0 uses a PA-first memory model (ADR-0011):
|
||||
Phase 0은 PA-우선 메모리 모델을 사용한다(ADR-0011):
|
||||
|
||||
- memory operations use device physical addresses (PA) only,
|
||||
- VA/MMU/IOMMU is not modeled.
|
||||
- 메모리 연산은 디바이스 물리 주소(PA)만 사용한다,
|
||||
- VA/MMU/IOMMU는 모델링하지 않는다.
|
||||
|
||||
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:
|
||||
호스트 대면 runtime API는 IO_CPU 엔드포인트를 통해 디바이스와
|
||||
상호작용한다. 다음을 보장하기 위해 Host ↔ IO_CPU에 대한 안정적이고
|
||||
최소한의 메시지 스키마를 정의한다:
|
||||
|
||||
- benchmarks remain stable,
|
||||
- IO_CPU-internal fan-out/aggregation can evolve independently,
|
||||
- completion and failure propagation is deterministic.
|
||||
- 벤치마크는 안정적으로 유지된다,
|
||||
- IO_CPU 내부의 팬아웃/집계는 독립적으로 진화할 수 있다,
|
||||
- 완료와 실패 전파는 결정론적이다.
|
||||
|
||||
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.
|
||||
또한 PE-태깅(A 방식)을 요구한다: 각 샤드는 (sip,cube,pe)를 명시적으로
|
||||
운반하여, IO_CPU가 PA 디코딩에 의존하지 않고 결정론적으로
|
||||
라우팅/팬아웃할 수 있도록 한다.
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
### D1. Contract scope
|
||||
### D1. 계약 범위
|
||||
|
||||
This schema is the stable contract ONLY for Host ↔ IO_CPU.
|
||||
본 스키마는 오직 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.
|
||||
IO_CPU를 넘어선 메시지(M_CPU, PE_CPU, 스케줄러, 엔진으로 가는 것)는
|
||||
컴포넌트 내부 사항이며 Phase 0에서 이 호스트 계약의 일부가 아니다.
|
||||
|
||||
---
|
||||
|
||||
### D2. Required message set
|
||||
### D2. 필수 메시지 집합
|
||||
|
||||
The runtime API MUST use only these message types for Host ↔ IO_CPU:
|
||||
runtime API는 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)
|
||||
### D3. 공통 envelope (모든 요청에 필수)
|
||||
|
||||
All Host ↔ IO_CPU requests MUST include:
|
||||
모든 Host ↔ IO_CPU 요청은 반드시 다음을 포함해야 한다:
|
||||
|
||||
- `msg_type: str`
|
||||
- `correlation_id: str`
|
||||
- generated by the host
|
||||
- used to match responses deterministically
|
||||
- 호스트에서 생성
|
||||
- 응답을 결정론적으로 매칭하는 데 사용
|
||||
- `request_id: str`
|
||||
- unique within a correlation_id
|
||||
- correlation_id 내에서 고유함
|
||||
- `target_device: str`
|
||||
- device identifier (e.g., "sip:0")
|
||||
- `timestamp_tag: str | None` (optional)
|
||||
- debug tag only; MUST NOT affect determinism
|
||||
- 디바이스 식별자(예: "sip:0")
|
||||
- `timestamp_tag: str | None` (선택)
|
||||
- 디버그 태그 전용; 결정성에 영향을 주어서는 안 됨
|
||||
|
||||
All Host ↔ IO_CPU responses MUST include:
|
||||
모든 Host ↔ IO_CPU 응답은 반드시 다음을 포함해야 한다:
|
||||
|
||||
- `correlation_id: str`
|
||||
- `request_id: str`
|
||||
@@ -70,120 +72,123 @@ All Host ↔ IO_CPU responses MUST include:
|
||||
|
||||
---
|
||||
|
||||
### D4. Completion schema (mandatory)
|
||||
### D4. Completion 스키마 (필수)
|
||||
|
||||
`Completion` MUST have:
|
||||
`Completion`은 반드시 다음을 가져야 한다:
|
||||
|
||||
- `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.
|
||||
- `ok == true`이면 `error_code`와 `error_message`는 반드시 null이어야 한다.
|
||||
- `ok == false`이면 `error_code`는 반드시 null이 아니어야 한다.
|
||||
- 완료 시맨틱은 결정론적이어야 한다.
|
||||
|
||||
---
|
||||
|
||||
### D5. MemoryWrite schema (PA-first, PE-tagged)
|
||||
### D5. MemoryWrite 스키마 (PA-우선, PE-태깅)
|
||||
|
||||
`MemoryWrite` represents a host-initiated write/initialize operation to device memory.
|
||||
`MemoryWrite`는 호스트에서 시작된 디바이스 메모리 쓰기/초기화 연산을
|
||||
나타낸다.
|
||||
|
||||
Mandatory fields:
|
||||
필수 필드:
|
||||
|
||||
- common envelope fields (D3)
|
||||
- destination placement tags (A 방식):
|
||||
- 공통 envelope 필드 (D3)
|
||||
- 목적지 배치 태그 (A 방식):
|
||||
- `dst_sip: int`
|
||||
- `dst_cube: int`
|
||||
- `dst_pe: int`
|
||||
- `dst_pa: int`
|
||||
- destination physical address in the destination PE's address space
|
||||
- 목적지 PE의 주소 공간 내 목적지 물리 주소
|
||||
- `nbytes: int`
|
||||
- `src_kind: "pattern" | "host_buffer_ref"`
|
||||
- Phase 0 MUST support "pattern"
|
||||
- Phase 0은 반드시 "pattern"을 지원해야 한다
|
||||
- `pattern: Pattern | None`
|
||||
- required if `src_kind == "pattern"`
|
||||
- `src_kind == "pattern"`인 경우 필수
|
||||
|
||||
`Pattern` (Phase 0 mandatory support):
|
||||
`Pattern` (Phase 0 필수 지원):
|
||||
|
||||
- `pattern_kind: "zero" | "fill_u8" | "fill_u16" | "fill_u32" | "fill_fp16" | "fill_fp32"`
|
||||
- `value: number | None`
|
||||
- required for fill_*; ignored for zero
|
||||
- fill_*에 필요; zero에서는 무시됨
|
||||
|
||||
Optional fields:
|
||||
선택 필드:
|
||||
|
||||
- `dst_mem_kind: "HBM" | "TCM" | "AUTO"` (default "AUTO")
|
||||
- `dst_mem_kind: "HBM" | "TCM" | "AUTO"` (기본값 "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.
|
||||
- 이 메시지는 Phase 0에서 대용량 텐서 데이터를 임베드해서는 안 된다.
|
||||
- 모든 레이턴시는 명시적인 그래프 순회 및 모델링된 컴포넌트로부터
|
||||
발생해야 한다.
|
||||
|
||||
---
|
||||
|
||||
### D6. MemoryRead schema (PA-first, PE-tagged)
|
||||
### D6. MemoryRead 스키마 (PA-우선, PE-태깅)
|
||||
|
||||
`MemoryRead` represents a host-initiated read from device memory.
|
||||
`MemoryRead`는 호스트에서 시작된 디바이스 메모리 읽기를 나타낸다.
|
||||
|
||||
Mandatory fields:
|
||||
필수 필드:
|
||||
|
||||
- common envelope fields (D3)
|
||||
- source placement tags (A 방식):
|
||||
- 공통 envelope 필드 (D3)
|
||||
- 소스 배치 태그 (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")
|
||||
- `dst_kind: "host_sink" | "discard"` (기본값 "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
|
||||
- Phase 0에서는 실제 바이트는 필요하지 않다(레이턴시/트레이스 중심)
|
||||
- 구현은 추후 새로운 ADR을 통해 가벼운 통계나 해시를 반환할 수 있다
|
||||
|
||||
---
|
||||
|
||||
### D7. KernelLaunch schema (PA-first, PE-tagged shards)
|
||||
### D7. KernelLaunch 스키마 (PA-우선, PE-태깅된 샤드)
|
||||
|
||||
`KernelLaunch` represents launching a kernel on a target device via IO_CPU.
|
||||
`KernelLaunch`는 IO_CPU를 통해 대상 디바이스에서 커널을 런치하는 것을
|
||||
나타낸다.
|
||||
|
||||
Mandatory fields:
|
||||
필수 필드:
|
||||
|
||||
- common envelope fields (D3)
|
||||
- 공통 envelope 필드 (D3)
|
||||
- `kernel_ref: KernelRef`
|
||||
- `args: list[KernelArg]`
|
||||
|
||||
`KernelRef` MUST have:
|
||||
`KernelRef`는 반드시 다음을 가져야 한다:
|
||||
|
||||
- `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)
|
||||
- `deploy_pa: int | None` — 커널 바이너리가 배치된 PA("deployed"에 필수)
|
||||
- `deploy_sip: int` — 바이너리가 위치한 SIP
|
||||
- `deploy_cube: int` — 바이너리가 위치한 큐브
|
||||
- `deploy_pe: int` — 바이너리가 위치한 PE
|
||||
- `nbytes_code: int` — 커널 바이너리 크기(BW 모델링용)
|
||||
|
||||
Kernel binaries MUST be pre-deployed to device memory via MemoryWrite.
|
||||
KernelLaunch MUST NOT embed kernel source code or IR in the launch message.
|
||||
커널 바이너리는 MemoryWrite를 통해 디바이스 메모리에 사전 배치되어야 한다.
|
||||
KernelLaunch는 커널 소스 코드나 IR을 런치 메시지에 임베드해서는 안 된다.
|
||||
|
||||
`KernelArg` supports tensor args by PA mapping and scalars by value.
|
||||
`KernelArg`는 PA 매핑을 통한 텐서 인자와 값을 통한 스칼라 인자를 지원한다.
|
||||
|
||||
Tensor arg (mandatory):
|
||||
텐서 인자 (필수):
|
||||
|
||||
- `arg_kind: "tensor"`
|
||||
- `tensor_pa_map: TensorPAMap`
|
||||
|
||||
`TensorPAMap` MUST have:
|
||||
`TensorPAMap`은 반드시 다음을 가져야 한다:
|
||||
|
||||
- `shards: list[TensorShard]`
|
||||
|
||||
`TensorShard` MUST have (A 방식 강제):
|
||||
`TensorShard`는 반드시 다음을 가져야 한다 (A 방식 강제):
|
||||
|
||||
- `sip: int`
|
||||
- `cube: int`
|
||||
@@ -192,42 +197,43 @@ Tensor arg (mandatory):
|
||||
- `nbytes: int`
|
||||
- `offset_bytes: int`
|
||||
|
||||
Scalar arg (mandatory):
|
||||
스칼라 인자 (필수):
|
||||
|
||||
- `arg_kind: "scalar"`
|
||||
- `dtype: "i32" | "i64" | "fp16" | "fp32" | "bool"`
|
||||
- `value: number | bool`
|
||||
|
||||
Optional KernelLaunch fields:
|
||||
KernelLaunch 선택 필드:
|
||||
|
||||
- `grid: dict | None`
|
||||
- `meta: dict | None`
|
||||
- `failure_policy: "fail_fast" | "collect_all"` (default "fail_fast")
|
||||
- `failure_policy: "fail_fast" | "collect_all"` (기본값 "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.
|
||||
- KernelLaunch는 대용량 텐서 데이터를 임베드해서는 안 된다.
|
||||
- KernelLaunch는 오직 IO_CPU 엔드포인트에만 제출되어야 한다.
|
||||
- IO_CPU는 샤드의 (sip,cube,pe) 태그를 사용하여 내부적으로 작업을
|
||||
팬아웃해야 한다.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
- 스키마 검증이 필수 필드 누락을 거부함,
|
||||
- 결정론적 correlation/응답 매칭,
|
||||
- MemoryWrite/Read/KernelLaunch가 명시적인 홉 트레이스를 생성함,
|
||||
- 라우팅된 모든 요청은 레이턴시 > 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)
|
||||
- ADR-0011 (메모리 주소 지정 — PA / VA / LA)
|
||||
- ADR-0007 (runtime_api와 sim_engine 경계)
|
||||
- ADR-0009 (커널 실행 팬아웃/집계)
|
||||
- ADR-0013 (검증 전략 — V1 메시지 스키마 검증)
|
||||
- SPEC R2, R7, R8
|
||||
|
||||
Reference in New Issue
Block a user