ADR housekeeping: category prefixes, lifecycle folders, retroactive 0034-0037
Filename + lifecycle:
- ADR rename to ADR-NNNN-<cat>-title.md with 8 3-letter category prefixes
(dev / mem / lat / prog / algo / par / api / ver). Numbers stay immutable.
- ADR Lifecycle split into 3 folders, documented in CLAUDE.md Part 2:
docs/adr/ (Accepted), docs/adr-proposed/ (Proposed/Stub/Draft),
docs/adr-history/ (Superseded/Merged). Status field gains "Draft" for
retroactive docs pending verification.
Merges (one ADR per topic, no change-history annotations):
- ADR-0017 absorbs ADR-0019 (Cube NOC + per-PE HBM connectivity, 10 D-items)
- ADR-0014 absorbs ADR-0021 (PE pipeline execution model, 8 D-items incl.
TileToken self-routing and multi-op composite epilogue scope)
- ADR-0023 absorbs docs/ipcq-dma-codesign-hw.md as new "HW Realization
Notes (Informative)" section (D16-D23 + Open HW Questions). codesign-hw.md
deleted; ADR-0019/0021 moved to adr-history with one-line stub status
Retroactive documentation (G4 closures, code-verified):
- ADR-0037 forwarding component (TransitComponent: first-flit overhead,
serial worker, path-based routing, single impl/multiple names)
- ADR-0036 IO_CPU component (target_start_ns global barrier stamping,
per-cube fan-out, response aggregation)
- ADR-0035 M_CPU & M_CPU.DMA component (3 fan-out paths, DMA Resources,
target_start_ns passthrough)
- ADR-0034 HBM controller internal design (per-PC state, address-based
selection, flit-aware per-flit commit, async finalize, command-only
fallback path)
Content updates:
- ADR-0010 expanded to full CLI surface (run/probe/web), retitled
"Command Line Interface and Execution Semantics"
- ADR-0007 D2 rewritten to current state; ADR-0015 supersession notes pruned
- ADR-0005 wrapped in Decision header with D1-D5; ADR-0022 metadata
block replaced with standard Status header
- ADR-0024 trimmed to rank=SIP launcher essentials (D1-D4);
ADR-0027 cleaned of supersession history
- ADR-0033 D6 cleanup: address-based PC selection moved out of future-work
(now documented in ADR-0034 D3); related D1/D3 wording realigned
- Cross-references back-filled in 5 ADRs (G3 gaps closed)
Onboarding docs split:
- docs/onboarding/ created
- moved: hw-architecture-overview.md, latency-model.md, di-presentation.md,
ccl-author-guide{,.en}.md
- references updated in README, ADR-0023{,.en}, src/kernbench/ccl/__init__.py
Source / test / yaml: ADR-NNNN cross-references in docstrings and YAML
comments updated after the merges (ADR-0021->0014 D6, ADR-0019->0017 D8).
No behavior change.
Tooling:
- tools/verify_adr_lang_pairs.py + tests/test_verify_adr_lang_pairs.py
(ADR EN/KO pair invariant checker)
- .claude/commands/report.md tracked (/report slash command)
- .gitignore: allow .claude/commands/*.md while keeping settings files ignored
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,186 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user