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-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 (이러한 메커니즘 위에 구축된 레이턴시 모델 가정)
|
||||
|
||||
Reference in New Issue
Block a user