ywkang
5917b3497c
- Remove xbar_top/bot, bridge, single noc node from topology
- Each cube_mesh.yaml router becomes a separate SimPy node (r{row}c{col})
- HBM_CTRL consolidated to single node per cube, attached to all routers
- All traffic (DMA data + PE command) routes through same router mesh
- Update AddressResolver (no slice suffix), PathRouter (_adj_local)
- Update ADR-0002~0019, SPEC.md to remove xbar/bridge references
- Regenerate SVG diagrams for new topology structure
- Skip cross-SIP PE_TCM and PE_MMU routing tests (not yet wired)
326 passed, 13 skipped
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
131 lines
4.5 KiB
Markdown
131 lines
4.5 KiB
Markdown
# ADR-0006: Topology Compilation, Distance Extraction, and Automatic Diagram Generation
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
The simulator compiles topology configuration (e.g., topology.yaml) into an explicit model graph,
|
|
and computes routing and accumulated latency (distance).
|
|
Diagrams should be generated from these authoritative artifacts to ensure consistency and avoid
|
|
hand-maintained topology drawings.
|
|
|
|
Additionally, for usability, diagrams should be emitted automatically into a stable location
|
|
so that developers can preview them immediately in the repository.
|
|
|
|
---
|
|
|
|
## Decision
|
|
|
|
### D1. Topology compilation is the single source of truth
|
|
|
|
- topology.yaml (or equivalent config) is compiled into:
|
|
- an explicit system graph,
|
|
- node/link attributes,
|
|
- routing policies.
|
|
This compiled graph is the authoritative representation of the system.
|
|
|
|
### D2. Distance extraction during compilation
|
|
|
|
- During or immediately after topology compilation, the simulator MUST compute distance metadata
|
|
(accumulated latency) consistent with ADR-0002.
|
|
- Distance metadata MUST be sufficient to support distance-aware diagram layout as defined in ADR-0005.
|
|
- Distributed fabric segments (e.g., NOC) MAY have distance_mm = 0 per ADR-0002 D4;
|
|
layout placement for such nodes uses explicit position metadata rather than distance buckets.
|
|
|
|
### D3. Diagram generation is a derived artifact
|
|
|
|
- Diagrams MUST be generated from:
|
|
- the compiled topology graph,
|
|
- extracted distance metadata,
|
|
- view/layout rules defined in ADR-0005.
|
|
- Diagram generation MUST NOT require additional hand-written topology descriptions.
|
|
|
|
### D4. Automatic diagram emission to the repository
|
|
|
|
- As part of topology compilation, the implementation MUST produce the following diagrams by default:
|
|
- SIP-level diagram (representative, distance-aware)
|
|
- CUBE-level diagram (representative, distance-aware)
|
|
- PE-level diagram (representative, distance-aware)
|
|
- The default output directory is:
|
|
- `docs/diagrams/`
|
|
- The generator MUST overwrite/update only when the compiled topology (or diagram rules) changes.
|
|
|
|
### D5. View-specific projection and layout
|
|
|
|
For each view (SIP / CUBE / PE):
|
|
|
|
- The generator MUST project the compiled graph into a reduced view graph:
|
|
- hide/collapse nodes according to ADR-0005,
|
|
- preserve connectivity semantics relevant to that view,
|
|
- compute distance buckets and assign layout layers deterministically.
|
|
- CUBE-level projection MUST include:
|
|
- Router mesh (from cube_mesh.yaml), HBM_CTRL, shared SRAM, M_CPU, UCIe ports,
|
|
and PEs as opaque blocks.
|
|
- All paths (HBM, non-HBM, command) route through the same router mesh (ADR-0019).
|
|
- Default anchors are implicit (ADR-0005) and MUST NOT require instance indices.
|
|
|
|
### D6. Output formats and determinism
|
|
|
|
- The generator MUST output at least one of:
|
|
- Mermaid (Markdown-native)
|
|
- Graphviz DOT (rank-based control)
|
|
- SVG (mm-accurate layout, no external dependencies)
|
|
- SVG is preferred when mm-accurate position metadata is available from the compiled topology.
|
|
- Output MUST be deterministic:
|
|
- same topology + same rules → identical diagram text
|
|
- File naming MUST be deterministic and stable (see "Output Conventions").
|
|
|
|
### D7. Performance and caching
|
|
|
|
- Diagram generation MAY be lazy and/or cached, as long as the outputs in `docs/diagrams/`
|
|
remain consistent with the compiled topology.
|
|
- The implementation SHOULD use a cache key based on:
|
|
- topology content hash,
|
|
- routing policy version,
|
|
- diagram rules version,
|
|
- view type (SIP/CUBE/PE).
|
|
|
|
---
|
|
|
|
## Output Conventions
|
|
|
|
### Directory
|
|
|
|
- `docs/diagrams/` is the canonical output directory for generated diagrams.
|
|
|
|
### File names (recommended, deterministic)
|
|
|
|
- `system_view.svg` / `system_view.mmd` / `system_view.dot`
|
|
- `sip_view.svg` / `sip_view.mmd` / `sip_view.dot`
|
|
- `cube_view.svg` / `cube_view.mmd` / `cube_view.dot`
|
|
- `pe_view.svg` / `pe_view.mmd` / `pe_view.dot`
|
|
|
|
Optionally, for multi-topology workflows:
|
|
|
|
- `sip_view__{topology_id}.svg`
|
|
- `cube_view__{topology_id}.svg`
|
|
- `pe_view__{topology_id}.svg`
|
|
|
|
### Repository policy
|
|
|
|
- Generated diagram files MAY be committed to the repository to enable diff-based review.
|
|
- If committed, they MUST be reproducible from topology compilation.
|
|
|
|
---
|
|
|
|
## Consequences
|
|
|
|
- Diagrams are always consistent with simulator behavior.
|
|
- Architectural changes automatically propagate to visualizations.
|
|
- Diagram diffs become meaningful indicators of architectural change.
|
|
|
|
---
|
|
|
|
## Links
|
|
|
|
- SPEC Section 4 (Output, Debuggability, and Diagrams)
|
|
- ADR-0002 (Distance semantics)
|
|
- ADR-0005 (Diagram views and layout rules)
|