ywkang
a796c1d2f7
Establish English as the canonical ADR language with Korean translations held in a parallel docs/adr-ko/ tree as derived artifacts (1:1 mirror). Promotion from adr-proposed/ to adr/ now writes English to adr/ and the Korean to adr-ko/; bidirectional sync rule documented in CLAUDE.md. - Migrate 30 ADRs in docs/adr/: 28 Korean-only translated to English, 2 bilingual pairs (ADR-0020, ADR-0023) consolidated (.en.md suffix dropped). ADR-0023 EN regenerated against KO source which had newer HW Realization Notes (D16-D23) section. - docs/adr-history/ left frozen by design (transitional state). - CLAUDE.md (Part 2): update ADR Lifecycle for 4-folder layout, mark docs/adr-ko/ as a Derived Artifact, add ADR Translation Discipline section covering bidirectional sync, conflict resolution (EN wins), and proposed-language freedom. - tools/verify_adr_lang_pairs.py: new verification tool checking pair completeness, filename mirroring, ADR-ID match, Status byte-equality. Pre-commit hook intentionally not added; run on demand or in CI. - tests/test_verify_adr_lang_pairs.py: 11 cases including CRLF/LF normalization, em-dash title separator, underscore-slug edge case. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
187 lines
4.6 KiB
Markdown
187 lines
4.6 KiB
Markdown
# ADR-0005: Diagram Views & Distance-Aware Layout Rules
|
||
|
||
## Status
|
||
|
||
Accepted
|
||
|
||
## Context
|
||
|
||
We require verifiable and inspectable system modeling for a large-scale,
|
||
parameterized AI Accelerator system.
|
||
|
||
Humans must be able to:
|
||
|
||
- visually inspect the modeled topology,
|
||
- reason about communication structure and relative distance,
|
||
- do so at multiple abstraction levels without being overwhelmed by detail.
|
||
|
||
The simulator models distance (accumulated latency) as a first-class concept.
|
||
Diagrams must reflect this distance by default.
|
||
|
||
---
|
||
|
||
## Decision
|
||
|
||
### D1. Global Defaults
|
||
|
||
- All diagrams MUST be **distance-aware by default**.
|
||
- All diagrams MUST render **representative views** of the architecture.
|
||
- Instance indices (e.g., sip0, cube2, pe3) MUST NOT be required for diagram generation.
|
||
- Instance indices MAY be used ONLY:
|
||
- to define a distance anchor in asymmetric or debugging scenarios, or
|
||
- when explicitly requested.
|
||
|
||
---
|
||
|
||
### D2. Representative Rendering Rule
|
||
|
||
- All CUBEs share the same internal structure.
|
||
- All PEs share the same internal structure.
|
||
|
||
Therefore:
|
||
|
||
- SIP-level diagrams render representative CUBEs and IO chiplets.
|
||
- CUBE-level diagrams render representative PEs as opaque blocks.
|
||
- PE-level diagrams render a representative PE with fully expanded internals.
|
||
|
||
Diagrams MUST NOT depend on specific SIP, CUBE, or PE indices
|
||
unless explicitly requested.
|
||
|
||
---
|
||
|
||
### D3. Diagram Views
|
||
|
||
#### View A — SIP-Level Diagram
|
||
|
||
**Purpose**
|
||
Explain system-scale structure and connectivity.
|
||
|
||
**Visible elements**
|
||
|
||
- SIP boundaries (optional)
|
||
- CUBEs (opaque blocks)
|
||
- IO chiplets (opaque blocks)
|
||
- Optional UCIe stubs only if needed to clarify connectivity
|
||
|
||
**Hidden elements**
|
||
|
||
- PE internals
|
||
- CUBE internal fabric
|
||
- IO chiplet internals
|
||
|
||
**Visible links**
|
||
|
||
- Host ↔ IO chiplets (PCIe)
|
||
- SIP ↔ SIP (PCIe / UAL via switches)
|
||
- IO ↔ CUBE (on-package links)
|
||
|
||
---
|
||
|
||
#### View B — CUBE-Level Diagram
|
||
|
||
**Purpose**
|
||
Explain cube-internal structure and data/control flow.
|
||
|
||
**Visible elements**
|
||
|
||
- Router mesh: 2D grid of NOC routers (from cube_mesh.yaml), all traffic routes through mesh
|
||
- HBM_CTRL attached to PE routers (local HBM = 0 hop)
|
||
- HBM subsystem (HBM_CTRL)
|
||
- Shared SRAM: cube-level shared memory
|
||
- Management CPU (M_CPU)
|
||
- PEs as opaque blocks (PE[0..N−1])
|
||
- UCIe endpoints (N/E/W/S) as ports
|
||
|
||
**Hidden elements**
|
||
|
||
- PE internals
|
||
|
||
**Visible links**
|
||
|
||
- PE → router (HBM + non-HBM data path via mesh)
|
||
- Router ↔ HBM_CTRL (local HBM access)
|
||
- Router ↔ Router (mesh hops for remote access)
|
||
- Router ↔ UCIe endpoints
|
||
- Router ↔ shared SRAM
|
||
- M_CPU ↔ router (command path)
|
||
- Router → PE_CPU (command delivery, collapsed into PE block)
|
||
|
||
---
|
||
|
||
#### View C — PE-Level Diagram
|
||
|
||
**Purpose**
|
||
Explain internal PE behavior and execution structure.
|
||
|
||
**Visible elements**
|
||
|
||
- PE_CPU
|
||
- Command handler / scheduler
|
||
- PE_TCM (local SRAM)
|
||
- HW accelerators (DMA, GEMM, MATH, etc.)
|
||
- Local HBM interface
|
||
- Optional IPCQ / messaging endpoints
|
||
|
||
**Visible links**
|
||
|
||
- Control paths (CPU → scheduler → engines)
|
||
- Data paths (engines ↔ TCM, DMA ↔ local HBM)
|
||
- External fabric ports as abstract ports only
|
||
|
||
---
|
||
|
||
### D4. Distance-Aware Layout (Default)
|
||
|
||
#### Distance definition
|
||
|
||
- Distance is defined as **accumulated latency**, consistent with ADR-0002.
|
||
- Distance is computed from a single anchor node.
|
||
|
||
#### Default anchor selection
|
||
|
||
- SIP view: IO chiplet (or Host CPU if present)
|
||
- CUBE view: a representative PE
|
||
- PE view: PE_CPU or Command Handler
|
||
|
||
Anchors are **implicit defaults** and MUST NOT be required to be specified.
|
||
|
||
#### Layout rules
|
||
|
||
- Diagrams MUST be laid out in layers based on distance buckets.
|
||
- Layout direction MUST be consistent within a view type
|
||
(preferred: left-to-right).
|
||
- Nodes with equal distance MUST have stable ordering
|
||
(by role or identifier, deterministically).
|
||
|
||
Cycles MAY be rendered using dashed or curved edges for readability,
|
||
without affecting distance semantics.
|
||
|
||
---
|
||
|
||
### D5. Generation Contract (for Tools / Claude Code)
|
||
|
||
When generating diagrams:
|
||
|
||
- Assume distance-aware layout by default.
|
||
- Assume representative rendering by default.
|
||
- Do NOT ask for SIP/CUBE/PE indices unless required.
|
||
- Do NOT expand hidden abstraction levels.
|
||
- Prefer architectural clarity over micro-hop fidelity.
|
||
|
||
---
|
||
|
||
## Consequences
|
||
|
||
- Diagrams are stable across topology scaling.
|
||
- Changes in distance or routing policy are reflected visually.
|
||
- Diagrams serve as verifiable artifacts derived from the simulator model,
|
||
not as hand-maintained documentation.
|
||
|
||
---
|
||
|
||
## Links
|
||
|
||
- SPEC Section 4 (Output, Debuggability, and Diagrams)
|
||
- ADR-0002 (Routing distance semantics)
|
||
- ADR-0006 (Topology compilation & automatic diagram generation)
|