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:
2026-05-20 08:17:56 -07:00
parent a796c1d2f7
commit 168b0c89f0
29 changed files with 2631 additions and 2651 deletions
@@ -1,4 +1,4 @@
# ADR-0015: Component Port/Wire Model and Fabric Routing
# ADR-0015: 컴포넌트 포트/와이어 모델과 패브릭 라우팅
## Status
@@ -6,46 +6,44 @@ Accepted
## Context
Realistic hardware modeling — queues, contention, fan-out — requires
that components own fabric traversal while the simulation engine
handles only initialization and completion observation. Direct method
calls between components, or path-walking inside the engine, defeat
queueing and contention semantics.
현실적인 하드웨어 모델링 — 큐, 경합, fan-out — 을 위해서는
컴포넌트가 패브릭 순회를 소유하고, 시뮬레이션 엔진은 초기화와 완료
관측만 처리해야 한다. 컴포넌트 간의 직접 메서드 호출이나 엔진 내부의
경로 탐색은 큐잉과 경합 시맨틱을 무력화한다.
This ADR defines:
본 ADR은 다음을 정의한다:
- how components communicate via typed port queues,
- how propagation delay is modeled (wire processes with BW occupancy),
- the fabric paths for Memory R/W (M_CPU bypass) and Kernel Launch
(via M_CPU),
- the engine's reduced role (wire init + completion observation only),
- M_CPU.DMA as an internal subcomponent of M_CPU.
- 컴포넌트가 타입드 포트 큐를 통해 통신하는 방식,
- 전파 지연을 모델링하는 방식 (BW 점유를 포함한 와이어 프로세스),
- Memory R/W (M_CPU 우회)와 Kernel Launch (M_CPU 경유)의 패브릭 경로,
- 엔진의 축소된 역할 (와이어 초기화 + 완료 관측만),
- M_CPU의 내부 서브컴포넌트로서의 M_CPU.DMA.
---
## Decision
### D1. Component port model
### D1. 컴포넌트 포트 모델
Each component has typed input/output ports modeled as SimPy Stores:
각 컴포넌트는 SimPy Store로 모델링된 타입드 입출력 포트를 갖는다:
```text
in_ports: dict[str, simpy.Store] # keyed by source node_id
out_ports: dict[str, simpy.Store] # keyed by destination node_id
```
Ports are created at engine initialization based on graph edges.
Each directed edge (src → dst) results in:
포트는 그래프 엣지를 기반으로 엔진 초기화 시 생성된다.
각 유향 엣지(src → dst)는 다음을 생성한다:
- `src.out_ports[dst]`the sending end
- `dst.in_ports[src]`the receiving end
- `src.out_ports[dst]`송신측
- `dst.in_ports[src]`수신측
---
### D2. Wire process (propagation delay + BW occupancy)
### D2. 와이어 프로세스 (전파 지연 + BW 점유)
For each directed edge (src, dst) in the topology graph, a SimPy wire process
models propagation delay and BW occupancy:
토폴로지 그래프의 각 유향 엣지 (src, dst)에 대해 SimPy 와이어 프로세스가
전파 지연과 BW 점유를 모델링한다:
```python
def wire_process(env, out_port, in_port, delay_ns, bw_gbs):
@@ -63,39 +61,39 @@ def wire_process(env, out_port, in_port, delay_ns, bw_gbs):
yield in_port.put(cmd)
```
Wire processes are started at engine initialization.
Each directed edge maintains an `available_at` timestamp tracking when the link
becomes free for the next transaction. When a transaction occupies a link, the
next transaction on the same directed link must wait until occupancy clears
(back-to-back serialization). TX and RX directions are independent (separate
wire processes with separate `available_at` state).
와이어 프로세스는 엔진 초기화 시점에 시작된다.
각 유향 엣지는 링크가 다음 트랜잭션을 위해 비워지는 시점을 추적하는
`available_at` 타임스탬프를 유지한다. 한 트랜잭션이 링크를 점유하는 동안,
동일 유향 링크의 다음 트랜잭션은 점유가 해제될 때까지 대기해야 한다
(연속 직렬화). TX와 RX 방향은 독립적이다 (각각의 `available_at` 상태를
갖는 별개의 와이어 프로세스).
---
### D3. Engine role (reduced)
### D3. 엔진 역할 (축소)
The simulation engine MUST:
시뮬레이션 엔진은 다음을 수행해야 한다:
- wire components at initialization (create port Stores, start wire processes),
- identify the entry component for each request type (PCIE_EP),
- put the request into the entry component's in_port,
- wait for a completion event.
- 초기화 시점에 컴포넌트 와이어링 (포트 Store 생성, 와이어 프로세스 시작),
- 각 요청 타입별 진입 컴포넌트 식별 (PCIE_EP),
- 진입 컴포넌트의 in_port에 요청을 put,
- 완료 이벤트 대기.
The simulation engine MUST NOT:
시뮬레이션 엔진은 다음을 해서는 안 된다:
- walk the topology path during request execution,
- call component `run()` methods directly,
- track per-hop latency or decompose fan-out.
- 요청 실행 중 토폴로지 경로 탐색,
- 컴포넌트 `run()` 메서드 직접 호출,
- hop별 레이턴시 추적이나 fan-out 분해.
---
### D4. Fabric paths for Memory R/W and Kernel Launch
### D4. Memory R/W Kernel Launch의 패브릭 경로
Memory R/W and Kernel Launch use **different** fabric paths.
Memory operations bypass M_CPU and route directly to HBM via the crossbar.
Kernel Launch routes through M_CPU for PE fan-out.
Memory R/W Kernel Launch**서로 다른** 패브릭 경로를 사용한다.
메모리 연산은 M_CPU를 우회하여 크로스바를 통해 직접 HBM으로 라우팅된다.
Kernel Launch는 PE fan-out을 위해 M_CPU를 경유한다.
**Memory R/W forward path (pcie_ep → hbm_ctrl, M_CPU bypass):**
**Memory R/W forward 경로 (pcie_ep → hbm_ctrl, M_CPU 우회):**
```text
pcie_ep → io_noc → io_ucie
@@ -103,14 +101,14 @@ pcie_ep → io_noc → io_ucie
→ target cube: ucie_in → router mesh → hbm_ctrl
```
**Memory R/W completion path:**
**Memory R/W 완료 경로:**
```text
hbm_ctrl → router mesh → [transit cubes: ucie → router mesh → ucie]
→ io_ucie → io_noc → pcie_ep
```
**Kernel Launch forward path (pcie_ep → io_cpu → M_CPU → PE):**
**Kernel Launch forward 경로 (pcie_ep → io_cpu → M_CPU → PE):**
```text
pcie_ep → io_noc → io_cpu → io_noc → io_ucie
@@ -118,7 +116,7 @@ pcie_ep → io_noc → io_cpu → io_noc → io_ucie
→ target cube: ucie_in → noc → M_CPU → PE[0..n] (parallel fan-out)
```
**Kernel Launch completion path:**
**Kernel Launch 완료 경로:**
```text
PE[0..n] all complete → M_CPU (aggregation)
@@ -126,77 +124,79 @@ PE[0..n] all complete → M_CPU (aggregation)
→ io_ucie → io_noc → io_cpu → io_noc → pcie_ep
```
**Rationale for M_CPU bypass on Memory R/W:**
**Memory R/W가 M_CPU를 우회하는 근거:**
Memory write/read operations do not require command interpretation or PE
dispatch — they are direct data transfers to/from HBM. Routing through M_CPU
would add unnecessary overhead (5ns) without functional benefit. The io_noc
inside the IO chiplet handles the routing decision: memory operations go
directly to cube fabric, while kernel launches are forwarded to io_cpu first.
메모리 write/read 연산은 명령 해석이나 PE 디스패치가 필요하지 않다 —
HBM으로의/로부터의 직접 데이터 전송이다. M_CPU를 경유하면 기능적 이득
없이 불필요한 오버헤드(5ns)를 추가한다. IO 칩렛 내부의 io_noc가 라우팅
결정을 처리한다: 메모리 연산은 큐브 패브릭으로 직접 가고, kernel
launch는 io_cpu로 먼저 전달된다.
---
### D5. M_CPU.DMA is an internal subcomponent of M_CPU
### D5. M_CPU.DMA는 M_CPU의 내부 서브컴포넌트이다
M_CPU.DMA is NOT a separate topology node.
It is an internal subcomponent owned by the M_CPU component implementation.
M_CPU.DMA는 별개의 토폴로지 노드가 아니다.
M_CPU 컴포넌트 구현이 소유하는 내부 서브컴포넌트이다.
M_CPU.DMA:
M_CPU.DMA:
- owns the DMA READ and DMA WRITE queues (capacity=1 each, per ADR-0014 D4),
- issues memory requests over the NOC to hbm_ctrl,
- receives completion from hbm_ctrl via the NOC,
- reports completion to M_CPU,
- is created and managed inside M_CPU's `__init__` and `run()`.
- DMA READ DMA WRITE 큐를 소유한다 (각 capacity=1, ADR-0014 D4),
- NoC를 통해 hbm_ctrl에 메모리 요청을 발행한다,
- NoC를 통해 hbm_ctrl로부터 완료를 수신한다,
- M_CPU에 완료를 보고한다,
- M_CPU `__init__` `run()` 내부에서 생성·관리된다.
M_CPU.DMA does not appear as a node in the compiled topology graph.
M_CPU.DMA는 컴파일된 토폴로지 그래프에서 노드로 나타나지 않는다.
---
### D6. Transit cube forwarding
### D6. Transit 큐브 포워딩
A cube that is not the target of a memory or kernel request acts as a transit node.
Transit cubes forward requests without consuming them:
메모리나 커널 요청의 대상이 아닌 큐브는 transit 노드로 동작한다.
Transit 큐브는 요청을 소비하지 않고 포워딩한다:
```text
ucie_in (from upstream) → noc → ucie_out (to downstream)
```
Transit forwarding is implemented entirely within the ucie_in component.
The noc and ucie_out components in a transit cube forward the packet without modification.
Transit 포워딩은 ucie_in 컴포넌트 내부에서 전적으로 구현된다.
transit 큐브의 noc와 ucie_out 컴포넌트는 패킷을 수정 없이 포워딩한다.
---
### D7. _formula_latency is preserved as a lower-bound cross-check
### D7. _formula_latency는 하한 교차 검증 용도로 유지된다
The path-based formula latency function (`_formula_latency`) is preserved in the engine
as a lower bound for correctness verification.
경로 기반 공식 레이턴시 함수(`_formula_latency`)는 정확성 검증을 위한
하한값으로 엔진 내에 유지된다.
Invariant:
불변식:
- Phase 0: `_formula_latency == component model total_ns`
- Phase 1+: `_formula_latency <= component model total_ns` (contention adds queueing)
- Phase 1+: `_formula_latency <= component model total_ns` (경합이
큐잉을 추가)
This function is independent of the port/wire model and requires only the topology graph.
It is used for shard comparison in `_route_kernel` and as a regression guard.
이 함수는 포트/와이어 모델과 독립적이며 토폴로지 그래프만 요구한다.
`_route_kernel`의 샤드 비교와 회귀 가드로 사용된다.
---
## Consequences
- Components model realistic hardware behavior (queues, contention, fan-out).
- Propagation delay is modeled accurately per edge.
- Engine is decoupled from routing policy.
- Component implementations remain swappable via DI (ADR-0007 D3).
- 컴포넌트가 현실적인 하드웨어 동작(큐, 경합, fan-out)을 모델링한다.
- 전파 지연이 엣지마다 정확하게 모델링된다.
- 엔진이 라우팅 정책으로부터 분리된다.
- 컴포넌트 구현이 DI(ADR-0007 D3)를 통해 교체 가능하게 유지된다.
---
## Links
- ADR-0007 D2 (engine role boundary)
- ADR-0009 D3 (kernel execution fan-out hierarchy)
- ADR-0014 D4 (DMA engine capacity=1)
- ADR-0012 D1 (host ↔ IO_CPU message schema; M_CPU.DMA is component-internal)
- ADR-0016 (IOChiplet NOC and memory data path)
- ADR-0017 (cube NOC 2D mesh architecture)
- ADR-0033 (Latency model assumptions built on these mechanisms)
- ADR-0007 D2 (엔진 역할 경계)
- ADR-0009 D3 (커널 실행 fan-out 계층)
- ADR-0014 D4 (DMA 엔진 capacity=1)
- ADR-0012 D1 (호스트 ↔ IO_CPU 메시지 스키마; M_CPU.DMA는 컴포넌트
내부)
- ADR-0016 (IOChiplet NoC와 메모리 데이터 경로)
- ADR-0017 (큐브 NoC 2D 메시 아키텍처)
- ADR-0033 (이러한 메커니즘 위에 구축된 레이턴시 모델 가정)