kernbench2/docs/adr-ko/ADR-0053-dev-topology-builder-algorithms.md

ADR-0053: Topology Builder + Visualizer Algorithms

Status

Accepted (2026-05-22).

topology/builder.py, topology/mesh_gen.py, topology/visualizer.py 가 함께 수행하는 토폴로지 컴파일·시각화 파이프라인의 핵심 알고리즘 선택 (placement-driven router attachment, mesh auto-layout, source_hash 캐시, view projection, SVG rendering) 을 명시한다. ADR-0006 가 topology compilation 의 high-level intent (compiled topology, distance extraction, automatic diagram generation) 를 정의하나, builder 가 실제로 어떤 알고리즘을 사용하는지 는 코드 grep 으로만 확인 가능했다.

First action (제일 처음에 하는 일)

resolve_topology(path_str) 가 호출되면 다음 4 단계가 순서대로 일어난다:

1. 경로 검증 (builder.py::resolve_topology): Path(path_str).expanduser().resolve(), 존재 확인, file 여부 확인. 실패 시 FileNotFoundError 또는 ValueError.
2. YAML 파싱 (_read_spec): yaml.safe_load. parse error 면 line/ column 정보 포함한 ValueError. dict 가 아니면 reject.
3. mesh 자동 생성 (mesh_gen.ensure_mesh_file): topology yaml 과 같은 디렉터리에 cube_mesh.yaml 을 만들거나 (캐시 invalid 시) 재사용 (캐시 hit 시). 이 단계가 cube NoC 의 라우터 grid 와 부착 정보를 결정.
4. graph 컴파일 (_compile_graph): system → IO chiplets → cubes → inter-cube edges → IO↔cube edges → system↔IO edges 순으로 nodes/edges 를 누적, 그 다음 4 개의 view projection (system, sip, cube, pe) 을 생성하여 TopologyGraph 로 묶음.

즉, topology compile 의 첫 일은 "topology.yaml 을 dict 로 읽고, 동일 디렉터리에 cube_mesh.yaml 을 생성/검증한 뒤, system→sip→cube→pe 순으로 flat graph + 4-view projection 을 만드는 것" 이다.

Context

topology/ 패키지의 책임:

• builder.py (1207 줄): topology.yaml 을 받아 TopologyGraph (nodes
  • edges + 4 view projections) 를 컴파일.
• mesh_gen.py (305 줄): cube NoC 의 라우터 grid 와 PE/UCIe/M_CPU/SRAM 부착 위치를 자동 결정하여 cube_mesh.yaml 로 캐시.
• visualizer.py (887 줄): TopologyGraph 로부터 SVG 다이어그램 4종 (system / sip / cube / pe) 을 생성.

ADR-0006 가 "topology compilation 의 결과는 distance metadata 와 diagram generation 의 single source" 라는 high-level 결정을 정의하나, 구체 알고리즘 (예: placement-driven nearest-router attachment, HBM 제외 zone 산출, source_hash 의 어떤 필드가 invalidation 을 트리거하는가) 은 ADR 에 없다.

특히 다음 결정들이 ADR-level 에 부재:

• 왜 mesh_gen 이 별도 파일 (cube_mesh.yaml) 로 캐시되는가?
• source_hash 가 어떤 필드를 포함하며, 어떤 변경이 재생성을 강제하는가?
• placement coordinate 가 cube 좌표가 아닌 mm 단위인 이유?
• HBM zone 제외와 UCIe N/S/E/W 분배가 mesh 안에서 어떻게 결정되는가?
• view projection 4 개 (system/sip/cube/pe) 의 추상화 레벨 차이?

이 ADR 이 이 결정들을 한 곳에 정리한다.

Decision

D1. compile 파이프라인 — 6 단계

_compile_graph(spec):

1. 시스템 노드 생성 (_instantiate_system): fabric.switch0, host CPU 등 system-level 노드 추가.
2. per-SIP loop (for sip_id in range(system.sips.count)):
   • IO chiplets (_instantiate_io_chiplets): pcie_ep / io_cpu / io_noc / io_ucie PHY / conn 노드 + 내부 양방향 edge 생성.
   • cube instantiation (_instantiate_cube): cube_mesh.yaml 의 router grid 를 토대로 cube-별 라우터, PE sub-components (pe_cpu, pe_dma, pe_fetch_store, pe_gemm, pe_math, pe_mmu, pe_tcm, pe_scheduler, pe_ipcq), m_cpu, sram, hbm_ctrl 인스턴스화 + 내부 edge 깔기.
   • inter-cube edges (_add_inter_cube_edges): UCIe N/S/E/W mesh edge.
   • IO ↔ cube edges (_add_io_to_cube_edges): io_noc 와 cube 의 edge UCIe phy 사이 연결.
3. switch ↔ IO edges (_add_system_to_io_edges): fabric.switch0 와 각 SIP 의 pcie_ep 사이 양방향 edge (ADR-0038 D3 + ADR-0010 의 cross-SIP IPCQ 경로).
4. view projections 4 종 build:
   • _build_system_view(spec) — Tray 레벨, SIP 들과 system switch.
   • _build_sip_view(spec) — SIP 안의 cube mesh + IO chiplet.
   • _build_cube_view(spec) — 단일 cube 안의 router grid + PE/M_CPU/SRAM/ HBM_CTRL 부착.
   • _build_pe_view(spec) — 단일 PE 안의 9 sub-components + 내부 edge.
5. TopologyGraph 리턴: TopologyGraph(spec, nodes, edges, system_view, sip_view, cube_view, pe_view).

이 6 단계는 순서가 의미를 가진다: cubes 가 만들어진 후에야 inter-cube edges 가 valid 한 src/dst 를 갖고, IO chiplet 이 먼저 만들어져야 IO ↔ cube edge 가 그를 참조할 수 있다. 새 노드 종류를 끼울 때는 의존 관계를 보고 적절한 위치에 삽입해야 한다.

D2. cube_mesh.yaml — 별도 파일 + source_hash 캐시

mesh_gen.ensure_mesh_file(cube_spec, mesh_path):

1. source_hash = _compute_source_hash(cube_spec) 산출. 입력 필드:
   • geometry (cube_mm.w/h 등).
   • pe_layout (corners, pe_per_corner).
   • ucie.n_connections.
   • memory_map.hbm_mapping_mode.
   • placement (m_cpu/sram pos_mm).
2. mesh_path (= topology.yaml 와 같은 디렉터리의 cube_mesh.yaml) 이 존재하고 existing.source_hash == source_hash 면 재사용 (캐시 hit).
3. 아니면 _generate_mesh(cube_spec, source_hash) 로 새 mesh 생성 후 yaml 로 저장.

별도 파일로 캐시하는 이유:

• mesh 생성은 PE/UCIe/router 부착 계산이 들어가 매번 다시 하기 무거움.
• 같은 cube spec 으로 여러 번 실행 시 동일 mesh 가 보장되어야 함.
• 사람이 직접 mesh 를 inspect / debug 할 수 있는 artifact 가 됨.

source_hash 가 list 한 5 개 필드가 mesh 형상을 결정하는 핵심이며, 그 외 (예: bandwidth, overhead_ns) 변경은 mesh 재생성을 트리거하지 않는다.

D3. cube NoC mesh auto-layout 알고리즘

_generate_mesh(cube_spec):

D3.1. 행/열 결정

• pe_positions = _corner_pe_positions(cube_w, cube_h): 4 corner (NW/NE/ SW/SE) 마다 PE center 좌표 (mm). hardcoded (1.5, 1.5) / (cube_w-1.5, cube_h-1.5) 패턴 + pe_per_corner=2 면 각 corner 에 2 PE 위치.
• col_xs = _compute_col_positions(...): PE 들의 x 좌표 union + max_spacing = 3.0 mm 보다 큰 gap 에 relay 컬럼 삽입.
• row_ys, rows_per_half = _compute_row_positions(cube_h, n_connections, pe_positions):
  • n_conn = max(n_connections, 2) (hot path minimum).
  • rows_per_half = ceil(n_conn / 2).
  • top 절반 + HBM 두 row + bottom 절반. HBM 은 `(cube_h/2 - 1.5, cube_h/2
    • 1.5)에 위치. PE rows 와 HBM rows 사이hbm_gap = 1.5 mm`.

D3.2. HBM 제외 zone

hbm_row_start = rows_per_half, hbm_row_end = rows_per_half + 1. hbm_col_start = n_cols // 2 - 1, hbm_col_end = n_cols // 2.

이 (row, col) 사각형 안의 router 슬롯은 None 으로 마킹 (라우터 없음). 실제 HBM 컨트롤러는 별도 hbm_ctrl.pe{X} 노드로 ADR-0017 D9 의 per-PE 파티션 패턴을 따라 부착.

D3.3. PE 부착

각 corner 의 PE 들은 다음 row 에 매핑:

• Top half: NW → row 0, NE → row 1 (top_corners 안의 index).
• Bottom half: SW → row hbm_row_end + 1, SE → row hbm_row_end + 2.

각 PE 의 x 좌표가 가장 가까운 col 의 router 에 부착 (min(range(n_cols), key=lambda c: abs(col_xs[c] - pe_x))). 부착 항목은 pe{pe_idx}.dma, pe{pe_idx}.cpu, pe{pe_idx}.hbm 세 가지 (router 별 attach list 에 push).

D3.4. M_CPU / SRAM 부착 — nearest router by Euclidean distance

placement.m_cpu.pos_mm (default [1.5, 5.5]) 와 placement.sram.pos_mm (default [1.5, 8.5]) 의 좌표에서 가장 가까운 router 를 Euclidean distance 로 찾아 attach list 에 "m_cpu" / "sram" 추가.

D3.5. UCIe N/S/E/W 분배

ucie_pe_rows = top_pe_rows + bot_pe_rows (총 2 * rows_per_half 개).

• UCIe-E: 매 PE row 마다 rightmost col 의 router 에 ucie_e.c{i}.
• UCIe-W: leftmost col 의 router 에 ucie_w.c{i} (E 의 mirror).
• UCIe-N/S: PE column 들 중 절반을 좌측, 절반을 우측으로 나눠 top row / bottom row 의 해당 col 에 부착.

각 UCIe connection 은 c{i} index 가 붙어 ucie_n_connections 만큼의 PHY 가 분산된다 (ADR-0017 D5+).

D4. node 명명 규칙 — 단일 소유자

builder.py 는 다음 명명 규칙으로 노드를 만든다 (ADR-0051 D5 의 단일 소유자 원칙):

• fabric.switch0 — system-level switch.
• sip{S}.{io_id}.{pcie_ep|io_cpu|io_noc|io_ucie.{dir}|conn.{id}} — IO chiplet.
• sip{S}.cube{C}.{m_cpu|sram|hbm_ctrl.pe{X}|noc.r{R}c{C}|...} — cube 내부.
• sip{S}.cube{C}.pe{P}.{pe_cpu|pe_dma|pe_fetch_store|pe_gemm|pe_math|pe_mmu|pe_tcm|pe_scheduler|pe_ipcq} — PE sub-components.

이 명명 규칙을 변경하려면 builder.py 와 router.py (ADR-0051) 의 helper 양쪽이 함께 갱신되어야 한다. 컴포넌트는 명명 규칙을 직접 알지 못하고 helper 만 호출한다.

D5. edge kind 분류

각 edge 가 부여받는 kind 가 라우팅 정책 (ADR-0051 D2) 의 입력. 주요 kind 값:

• "pe_internal" — PE 내부 sub-component 간.
• "pe_to_router" — PE_DMA ↔ cube NoC router.
• "router_mesh" — cube NoC router 간.
• "router_to_hbm", "router_to_mcpu", "router_to_sram", "sram_to_router" 등 — cube-attached component 간.
• "ucie_internal", "ucie_conn_to_router", "router_to_ucie_conn", "ucie_conn_to_noc", "noc_to_ucie_conn", "ucie_mesh" — UCIe 관련.
• "io_internal" — IO chiplet 내부.
• "io_to_cube", "cube_to_io" — IO ↔ cube 경계.
• "pcie" — switch ↔ pcie_ep.
• "command" — control-plane only edges (M_CPU ↔ NOC 등; PE DMA path 에서 제외).

새 edge kind 를 추가하면 router.py 의 4 adjacency graph (ADR-0051 D2) 의 어느 카테고리에 속할지 결정해야 한다 — 그렇지 않으면 default 로 _adj_all 에만 포함되어 의도와 다른 routing 발생 가능.

D6. view projection — 4 추상화 레벨

TopologyGraph 는 flat (nodes + edges) 외에 4 개의 view projection 을 보유:

• system_view (_build_system_view): Tray 레벨. SIP 박스들 + fabric. switch0. PCIE 링크 표시. 외부 발표용 high-level overview.
• sip_view (_build_sip_view): 한 SIP 안. cube mesh + IO chiplet (pcie_ep + io_cpu + io_noc). UCIe N/S/E/W 가 cube 간 연결로 보임.
• cube_view (_build_cube_view): 한 cube 안. router grid + PE/M_CPU/ SRAM/HBM_CTRL 부착 + UCIe PHY edge 부분. cube 내부 라우팅 / placement 진단용.
• pe_view (_build_pe_view): 한 PE 안. 9 sub-components + 내부 edge (pe_internal kind). 자세한 PE 내부 dataflow 검토용.

view 는 spec 에서 visualization.emit_views: [system, sip, cube] 같이 선택적으로 출력 (ADR-0006). pe view 는 기본 출력에서 빠져 있으나 코드는 유지 (자세한 디버그용).

D7. visualizer.py — SVG 다이어그램 출력

emit_diagrams(graph, out_dir) 가 모든 view 를 SVG 로 렌더. 핵심 함수:

• _render_view_svg(view) — 일반적인 view 렌더 (router grid 가 없는 경우).
• _render_cube_view_svg(view, spec) — cube view 전용 (HBM block 그리기, router grid layout, PE/M_CPU/SRAM/HBM positioning).
• _draw_node, _draw_edge — 노드 / edge 의 시각적 표현.
• _pick_scale, _compute_node_sizes — 자동 스케일링.

visualizer 는 derived artifact (ADR-0006) 로 분류되며, 코드 변경 시 production check 대상이 아니다. CLAUDE.md 의 "Derived Artifacts" 항목과 정합.

D8. spec 변경의 영향 범위

spec 필드	영향	mesh 재생성
system.sips.count	SIP 갯수, node 수	No
sip.cube_mesh.w/h	cube mesh 형상	No
cube.geometry.cube_mm.w/h	cube 크기 (mm)	Yes
cube.pe_layout.corners/pe_per_corner	PE 부착 위치	Yes
cube.ucie.n_connections	UCIe PHY 분배	Yes
cube.memory_map.hbm_mapping_mode	HBM 분배 모드	Yes
cube.placement	M_CPU/SRAM 위치	Yes
cube.memory_map.* (위 제외)	HBM 용량 / BW	No
*.links.*.bw_gbs	edge bandwidth	No
*.attrs.overhead_ns	컴포넌트 latency	No

위 표가 D2 의 _compute_source_hash 입력과 일치. mesh 재생성이 필요한 변경은 cube_mesh.yaml 의 source_hash 가 자동 invalidate.

Alternatives Considered

A1. mesh 를 별도 캐시 파일 없이 매 compile 시 재생성

기각. 같은 spec 으로 여러 번 호출되는 케이스 (CLI run, probe, test) 마다 mesh 생성 비용을 다시 지불. 또한 사람이 mesh 를 inspect 할 수 있는 artifact 가 사라짐.

A2. mesh 생성을 builder.py 에 합치기

기각 (현재). 305 줄 짜리 자체 알고리즘이며, mesh layout 의 결정 (placement- driven router attachment, HBM exclusion zone) 이 builder 의 일반적인 node/edge 생성 책임과 다르다. 분리 유지가 단일 책임 원칙에 더 부합.

A3. placement coordinate 를 cube 좌표 (col/row) 로 표현

기각. mm 단위 좌표가 시각화 측 (visualizer) 과 mesh layout 측 (nearest- router 산출) 양쪽에서 일관되게 쓰인다. cube 좌표는 router grid 가 결정 되기 전까지는 정의되지 않으므로 placement 입력에 부적절.

A4. view projection 을 lazy 하게 생성

기각 (현재). 4 개 view 의 생성 비용이 작고 (보통 < 100 ms), eager 생성이 TopologyGraph 를 통한 single source of truth 를 보장.

A5. visualizer 출력 형식을 SVG 외 (PNG/PDF) 도

기각. SVG 가 vector + 텍스트 검색 가능 + 브라우저 직접 렌더가 가능한 가장 유연한 형식. PNG 변환이 필요하면 별도 도구 (rsvg-convert 등) 로 후처리.

Consequences

• ADR-0006 의 high-level intent 가 D1–D7 로 구체화되어, topology 변경 영향을 D8 표로 빠르게 가늠 가능.
• D3 의 mesh auto-layout 알고리즘이 ADR-level 에서 굳어져, 추후 새 PE 부착 패턴 (예: HBM 의 6-zone 분할) 도입 시 어느 단계가 영향받는지 명확.
• D5 의 edge kind 목록과 D7 의 view 구조가 명시되어, 새 component 종류 추가 시 (builder + router + visualizer) 어디까지 손대야 하는지 PR reviewer 가 한눈에 파악 가능.
• D2 의 source_hash invalidation 규칙이 명시되어, cube_mesh.yaml 이 stale 하게 남는 경우 (예: bw 값만 바꿨을 때) 가 정상 동작임이 분명.