Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
362 changes: 37 additions & 325 deletions docs/spec/analysis.md

Large diffs are not rendered by default.

37 changes: 7 additions & 30 deletions docs/spec/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ graph TD
hir["<b>hir</b>"]
tir["<b>tir</b>"]
analysis["<b>analysis</b>"]
schedule["<b>schedule</b>"]
passes["<b>passes</b>"]
target["<b>target</b>"]
runtime["<b>runtime</b>"]
Expand All @@ -46,15 +45,11 @@ graph TD
coreir --> hir
coreir --> tir
hir --> analysis
hir --> schedule
schedule --> passes
hir --> passes
tir --> passes
passes --> target
target --> runtime
analysis -. facts read by .-> schedule
target -. projects declared Facts .-> analysis
target -. projects declared Facts .-> schedule

types -. carried by Expr type .-> coreir
shard -. layout sublayer .-> types
Expand All @@ -69,14 +64,11 @@ graph TD
evaluator -. reference oracle .-> hir
cli -. user entry surface .-> parser
cli -. reports .-> analysis
cli -. reports .-> schedule
```

A TileFoundry compilation flows left to right along the **pipeline**:
`parser → core-ir → {hir, tir} → passes → target → runtime`. Typed HIR MAY
first pass through the public `schedule` operation before pass sequencing; the
algorithm it selects decides over the facts the `analysis` layer states about the
same HIR, and the direction is one-way. The
`parser → core-ir → {hir, tir} → passes → target → runtime`. The `analysis`
layer states facts about the same typed HIR without joining that flow. The
**type system** (types + shard) and the **IR framework**
(visitor-mutator + visitor-registry) cut across every pipeline stage:
they are co-designed with the IR, not standalone modules. Auxiliary
Expand Down Expand Up @@ -146,29 +138,15 @@ This stage layers two concerns on top of the same IR:
are both ordinary stages in that manager. A pass may use a
pass-private intermediate representation without elevating it to a
peer IR layer.
3. **Fact layer** — the polyhedral model of one HIR `Function` body and
the authored-HIR metrics ([analysis](./analysis.md)). It is neither a
pass nor an IR layer: it measures, and the scheduling algorithms below
decide over what it measures. The facts a scheduling decision is made
*over* — the atom catalogue and the store a tile lives in — belong to
the scheduling layer that decides, not here
([schedule](./schedule.md)).
3. **Fact layer** — the authored-HIR metrics measured over one HIR
`Function` ([analysis](./analysis.md)). It is neither a pass nor an IR
layer: it measures, and it decides nothing over what it measures.

IR traversal / rewrite utilities (`ExprVisitor` / `ExprCloner` /
`StmtVisitor` / `StmtMutator` / mixed stmt-expr rewriters) are shared
infrastructure used by both passes and codegen walkers; the framework
contract lives in [visitor-mutator](./visitor-mutator.md).

Scheduling is one explicit public operation, not a pass-manager stage and not a
Target-owned service. A caller names the program and one level of the hierarchy
that program declares; the algorithm registered for that exact hardware and level
answers with a Plan it owns entirely. What a Plan states is a decision about a
program, never a rewritten one: no scheduling algorithm materializes its selection
into HIR, and applying a decision is a separate operation a caller asks for. The
invocation contract, the result boundary, and the Plan base are owned by
[schedule](./schedule.md). An algorithm reads the hardware it decides over by
projecting the same Target for the aggregates it declares.

## 6. Target / codegen

Codegen is the back end. **TIR is the lowest IR**, and each target
Expand Down Expand Up @@ -229,14 +207,13 @@ This table is the authoritative spec-to-box map. Each row lists the
| **[evaluator](./evaluator.md)** | HIR reference interpreter: `evaluate` entry, `Value` family (`TensorValue` / `TupleValue`), `register_eval` op registry, node-evaluation + `GridRegionExpr` + layout-domain rules. Logical reference oracle, no codegen / runtime |
| **[visitor-registry](./visitor-registry.md)** | Derived-visitor dispatch pattern: `AnalysisRegistry`, per-class handler registration, four instances (`typeinfer` / `verify` / `codegen_<target>` / `cost`) with their Context / Visitor derivations |
| **[semantic-analysis](./semantic-analysis.md)** | Static analysis service semantics: type propagation (relation-derived type behavior), access relation analysis, shard propagation (logical shape → layout domain, relation-driven propagation, output storage + mesh/layout compatibility). The registration mechanism itself is owned by visitor-registry |
| **[analysis](./analysis.md)** | Fact layer: the polyhedral model of one HIR Function body (`TileGraph` / `extract`, authored-loop modelling, and the facts measured over a time relation), and the composed authored-HIR measurement — its analysis families, their owned Metadata records, and the narrow Target Facts each family declares |
| **[analysis](./analysis.md)** | Fact layer: the composed authored-HIR measurement — its analysis families, their owned Metadata records, and the narrow Target Facts each family declares |
| **[visitor-mutator](./visitor-mutator.md)** | IR traversal / rewrite infrastructure: expr / stmt visitors, mutators, identity-preserving rewrite invariants, mixed stmt-expr traversal |
| **[passes](./passes.md)** | Pass framework + implemented passes: `Pass` / `PassManager`, three pass granularities, per-pass subsections (lowering / optimization rules) |
| **[schedule](./schedule.md)** | The public scheduling operation: invocation contract, exact algorithm registration, shared options, result boundary, the extensible Plan base, the typed plan each algorithm family exports, the schedule-tree construction and scaffold emission stages an algorithm composes its solve from, and the facts it projects (`AtomFact`, plus each family's own closed facts) |
| **[target](./target.md)** | Target capability descriptors, architecture/device facts, Facts projection, and admitted program topology levels |
| **[codegen](./codegen.md)** | Target-selected CodeGenerator services, emit / link products (`LinkableFunction` / `LinkableModule` / `LinkedModule`), dispatch + shape-scalar ABI, program-shape / dynamic-CTA source contract, ShardLayout emission |
| **[runtime](./runtime.md)** | `RuntimeModule` / launcher ABI, C++ runtime surface, `runtime.h` umbrella header, runtime op free-function contract |
| **[cli](./cli.md)** | Command-line grammar and behavior for models, spec, tutorial, check, analyze, schedule, and inspect |
| **[cli](./cli.md)** | Command-line grammar and behavior for models, spec, tutorial, check, analyze, and inspect |
| **[code-organization](./code-organization.md)** | Implementation guide (not architectural): Python source tree layout |

**Cross-spec sync.** Downstream specs link back to the relevant § of
Expand Down
10 changes: 5 additions & 5 deletions docs/spec/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -334,7 +334,7 @@ explicit analysis; there is no ordinary `--target` option.
analysis option.
- `analyze` MUST invoke the public operation once with every requested root,
so their union dependency closure runs on one inlined Function view
([analysis §3](./analysis.md#3-composed-analysis)). Each closure member MUST
([analysis §2](./analysis.md#2-composed-analysis)). Each closure member MUST
run once, and requesting another root MUST NOT let one analyzer change
Metadata owned by another.
- A selection MUST resolve to a Module. A bare Function MUST be rejected
Expand All @@ -350,7 +350,7 @@ explicit analysis; there is no ordinary `--target` option.
It MUST be refused as an argument-combination error when no analysis flag was
supplied, naming that a report needs a requested root and printing the
`analyze` usage. Both formats MUST carry the same conclusions
([analysis §2](./analysis.md#2-authored-hir-metrics)).
([analysis §1](./analysis.md#1-authored-hir-metrics)).
- `--operands` MUST add each operand's share of a call's traffic to that call's
annotation, and MUST NOT change the JSON report, which carries that split
either way. It is the traffic the annotation already states, one layer finer,
Expand All @@ -368,7 +368,7 @@ explicit analysis; there is no ordinary `--target` option.
MUST be repeatable to bind several. One dimension MUST receive one extent;
a comma-separated list of extents for one dimension MUST be rejected because
several extents together are a `check` request. It MUST be passed through as the
operation's `dims` ([analysis §2.2](./analysis.md#22-analysis-families));
operation's `dims` ([analysis §1.2](./analysis.md#12-analysis-families));
the CLI MUST NOT specialise the selection itself, because then what it
wrote would be about a program the operation never saw.
- A `--dim` argument that is not `NAME=EXTENT`, or whose extent is not an
Expand Down Expand Up @@ -397,7 +397,7 @@ explicit analysis; there is no ordinary `--target` option.
- Output MUST report the analyses that were requested. A dependency that ran
because a requested root needed it MUST appear in the executed list and, other
than the bounded roofline support view defined by
[analysis §2](./analysis.md#2-authored-hir-metrics), MUST NOT have its own
[analysis §1](./analysis.md#1-authored-hir-metrics), MUST NOT have its own
measurements reported.
- The report's `target` field MUST be the concrete Target value's `identity`,
so two products served by one Target class remain distinguishable.
Expand Down Expand Up @@ -444,7 +444,7 @@ interface that claims to list every Facts projection it supports.
already occupied by any other importable module MUST likewise be rejected
without replacing that module in `sys.modules`.
- Every command MUST replay the registry before doing its own work, so an
added Target is equally available to inspection, analysis, and scheduling.
added Target is equally available to inspection and analysis.
A missing or changed source MUST produce a warning naming that entry while
valid entries continue to load and the requested command continues.
- The default writable registry MUST be
Expand Down
Loading
Loading