Skip to content

spec-compilation.md

Latest commit

 

History

History
120 lines (88 loc) · 3.71 KB

spec-compilation.md

File metadata and controls

120 lines (88 loc) · 3.71 KB

LOOM Compilation Pipeline Specification

Overview

This document captures the compilation-side contract that turns source code or an SCF-level candidate region into a DFG suitable for mapping.

Stage Family

LOOM compilation is organized into these conceptual stages:

  1. source to LLVM IR
  2. LLVM dialect MLIR
  3. CF-stage MLIR
  4. SCF-stage MLIR
  5. DFG-domain selection
  6. DFG-stage lowering

Canonical Artifact Flow

The software-only artifact family is:

<name>.ll
<name>.llvm.mlir
<name>.cf.mlir
<name>.scf.mlir
<name>.dfg.mlir

Exact emission policy may vary by mode, but these stage boundaries are architecturally significant.

When compilation continues into mapping against a selected ADG, later artifacts that contain both software and hardware meaning must switch to mixed naming:

<dfg>.<adg>.map.json
<dfg>.<adg>.map.txt
<dfg>.<adg>.config.json
<dfg>.<adg>.config.bin
<dfg>.<adg>.config.h
<dfg>.<adg>.viz.html

Hardware-only artifacts such as the ADG itself continue to use <adg>.* names, for example:

<adg>.fabric.mlir
<adg>.fabric.viz.json

DFG-Domain Selection

LOOM does not hardcode "convert the whole function" as the only model. Instead:

  • a candidate region is selected from SCF-level IR
  • the candidate must respect SCF hierarchy boundaries
  • the chosen candidate is what proceeds into DFG lowering

The exploration logic itself is specified in spec-dse.md.

DFG-Stage Responsibilities

The DFG stage must produce a graph suitable for mapping and later validation.

Important LOOM-side requirements include:

  • unsupported fanout or merge patterns should be normalized away by the lowering pipeline when required by the mapper model
  • kernels with memory side effects must preserve enough structure for extmemory reconstruction and later validation
  • unused outputs are handled by discard semantics rather than by introducing handshake.sink as the primary model

Join Fan-In Legalization

The DFG stage must also respect the hardware join capacity exported by the ADG.

Normative rules:

  • the ADG exporter annotates the selected hardware with a maximum supported handshake.join fan-in
  • LOOM lowers this limit into the compilation pipeline as loom.adg_max_join_fanin
  • if the software DFG contains a handshake.join whose fan-in is less than or equal to that limit, it may remain unchanged
  • if the software DFG contains a handshake.join whose fan-in exceeds that limit, LOOM must rewrite it into a tree of smaller joins whose fan-in does not exceed the hardware limit
  • the current mapper/config encoding supports hardware join fan-in up to 64
  • if the hardware limit is less than 2, LOOM must reject any software join whose fan-in is greater than 1

This legalization happens before mapping. The mapper therefore only needs to handle software joins whose fan-in is within the ADG-advertised hardware capacity.

Multi-Port Memory and Tagging

LOOM retains the legacy design's broad direction that memory-related routing may involve tag mechanisms and explicit memory interface structure, but the current contract is no longer restricted to one hardware extmemory per software array.

Normative compilation-side expectations are:

  • DFG memory nodes must preserve enough identity for later mapping onto either distinct or shared hardware memory interfaces
  • multi-port or shared-interface memory traffic may require tagged routing and explicit tag-boundary structure
  • the detailed hardware-family and region-table rules live in spec-fabric-memory-interface.md

Relationship to Other Specs