TileLang Semantic Validation
Core principle
Reject a program only when the violated semantic invariant is established.
Keep these outcomes distinct:
| Finding |
Treatment |
| Semantically invalid for every supported lowering |
Default error |
| Valid in principle but unsupported by the current lowering |
Precise unsupported-case diagnostic or fallback |
| Valid but an optimization does not apply |
Warning or silent fallback, never a semantic error |
| Potentially invalid but not provable |
Warning, opt-in verifier, or no report |
Do not turn an optimizer limitation into a language rule. For example,
T.vectorized containing a loop-invariant T.serial is semantically valid even
though the current vectorization planner may scalarize it.
Workflow
1. Reconstruct the actual contract
Before proposing or changing a rule:
Locate the source API under tilelang/language/.
Determine its source TIR representation. Do not infer semantics from the
Python spelling alone: T.Pipelined is a serial For with annotations, and
T.Persistent expands early into binds plus a serial loop.
Trace the construct through the target pipelines and identify the first pass
that assumes the proposed invariant.
Search tests and examples for valid counterexamples.
Load the relevant domain reference completely:
- loop nesting and loop/storage ownership:
references/loop-rules.md;
- bounds, initialization, scopes, races, synchronization, barriers, or
async operations:
references/memory-concurrency.md;
- TileOps, software pipelines, reducers, layouts, kernel launch, or dtype
contracts:
references/operations-layout.md.
For loop-nesting work, also run:
python .agents/skills/tilelang-semantic/scripts/scan_loop_nesting.py
Absence from the repository is not proof that a construct is invalid. Confirm
the downstream assumption in code or with a minimal lowering test.
Treat the scanner as an inventory aid, not a proof: inspect non-literal
annotation dictionaries and generated TIR manually.
2. Specify the rule before implementing it
Write down all of the following:
- Scope: the exact node, storage scope, or lexical region covered.
- Invariant: what every valid program must satisfy.
- Proof criterion: what the checker must establish before reporting.
- Exemptions: atomics, reducers, generated IR, target-specific paths, etc.
- Near-neighbor valid case: the smallest similar program that must remain
accepted.
- Diagnostic: name the offending construct and give an actionable rewrite.
- Enforcement stage: frontend, pre-lower, early native verification,
post-inference, or backend-specific lowering.
For nesting rules, define a path as one lexical ancestor chain from the
function body to a leaf statement. Sequential sibling loops are different
paths.
3. Choose the earliest reliable enforcement stage
| Stage |
Use it for |
| Frontend API |
Invalid argument combinations or types known while constructing the loop/op |
PreLowerSemanticCheck |
Backend-independent source-TIR structure with user-facing syntax still recognizable |
Early native Verify* pass |
Analyzer-, effect-, region-, or dataflow-dependent checks shared by backends |
After LayoutInference |
Contracts involving inferred layout_map or parallel_loop_layout |
| Backend pipeline |
Rules that genuinely depend on target instructions or execution geometry |
Do not place a rule after a transform that erases the evidence needed to report
it. If an early expansion erases identity, preserve an explicit annotation
instead of pattern-matching incidental lowered shapes.
4. Implement a validator, not a transform
- Keep validation side-effect free.
- Maintain lexical state with a stack and restore it on every exit path.
- Use
For, Buffer, Var, and other ObjectRef handles for retained identity;
follow $tilelang-tvm-ir for C++ TIR code.
- Share traversal/variable-use utilities when rules need the same facts, but
keep diagnostics and rule ownership independent.
- Include source spans when the IR carries them.
- Use a stable prefix such as
[TileLang Semantic Check] and describe a legal
replacement.
- Honor the existing global pre-lower opt-out for compatibility. Do not add a
new per-rule opt-out for a proven-invalid rule unless compatibility requires
one; reserve fine-grained opt-outs for inconclusive analyses.
5. Test the semantic boundary
Add, at minimum:
- one failing test for each violation shape;
- one near-neighbor valid test;
- a proof-boundary case that remains accepted when the analysis is
inconclusive;
- alternate control-flow paths for state/lifecycle rules;
- target-specific accepted and unsupported cases when capability matters;
- a diagnostic assertion that checks the useful part of the message.
Also run affected backend codegen tests when a rule migrates existing kernels.
Use $tilelang-build for repository test commands. For a Python pre-lower
checker, start with:
python -m pytest testing/python/analysis -q
python -m ruff check <changed-python-files>
git diff --check
Validation ownership map
tilelang/engine/semantic_check.py: shared pre-lowering entry point.
tilelang/analysis/*checker.py: source-TIR structural rules and actionable
frontend diagnostics.
src/transform/verify_*.cc: native effect/dataflow verification such as
reducer lifecycle, buffer initialization, and parallel races.
src/transform/legalize_safe_memory_access.cc: bounds proof, global guards,
and optional local/shared warnings.
tilelang/language/*_op.py and tilelang/language/builtin.py: source API
operand and annotation validation.
src/transform/{pipeline_planning,inject_pipeline}.cc: pipeline dependency,
ordering, replayability, and multi-versioning contracts.
src/transform/layout_inference/parallel_loop_layout_validator.h:
post-inference parallel-layout annotation contract.
tilelang/{cuda,rocm,cpu,metal,webgpu}/pipeline.py: target pipeline order.
tilelang/transform/pass_config.py: opt-outs and strictness controls.
Read $tilelang-layout before changing rules whose truth depends on fragment
ownership, replication, loop partitioning, or inferred loop layouts.
Avoid
- Do not equate
T.Parallel with T.vectorized; they represent different
execution layers and use different lowering paths.
- Do not reject every construct that falls back to serial execution.
- Do not promote “cannot prove safe” to “proven unsafe.”
- Do not use Python
assert for new user-facing legality checks; assertions
disappear under optimized Python and usually produce poor diagnostics.
- Do not infer source intent from
ForKind alone when annotations define the
construct.
- Do not treat nested pipeline requests as backend-independent invalidity;
hierarchical-pipeline support is a backend capability.
- Do not require parallel extent to equal thread count or explicit layout
shape; partitioning, replication, and guarded tails intentionally permit
differences.
- Do not reject barriers merely because they occur inside
T.Parallel;
validate participant sets, path uniformity, and execution counts.
- Do not report a missing target feature or missed optimization as universal
semantic invalidity.
Resources
references/loop-rules.md: established loop contracts, representation
details, non-rules, and backend-specific nested-pipeline guidance.
references/memory-concurrency.md: buffer bounds/initialization/ownership,
aliasing, races, collective synchronization, barriers, and async lifetimes.
references/operations-layout.md: TileOp, pipeline, reducer, layout,
kernel/target, and dtype contracts plus the implementation roadmap.
scripts/scan_loop_nesting.py: inventory lexical loop pairs and detect
nested software-pipeline requests in Python sources without judging backend
support.
1---2name: tilelang-semantic3description: Design, implement, debug, or review TileLang semantic rules and validation, including loop nesting, buffer bounds/initialization/ownership, data races, synchronization and async lifecycles, TileOp shape/dtype/scope contracts, software pipelines, reducers, layouts, kernel launch constraints, and actionable diagnostics. Use when changing tilelang/analysis checkers, early Verify* passes, language legality rules, or regression tests for invalid TileLang programs.4metadata:5 source: https://skillmd.com/skills/tile-ai/tilelang-semantic6---78# TileLang Semantic Validation910## Core principle1112Reject a program only when the violated semantic invariant is established.13Keep these outcomes distinct:1415| Finding | Treatment |16|---|---|17| Semantically invalid for every supported lowering | Default error |18| Valid in principle but unsupported by the current lowering | Precise unsupported-case diagnostic or fallback |19| Valid but an optimization does not apply | Warning or silent fallback, never a semantic error |20| Potentially invalid but not provable | Warning, opt-in verifier, or no report |2122Do not turn an optimizer limitation into a language rule. For example,23`T.vectorized` containing a loop-invariant `T.serial` is semantically valid even24though the current vectorization planner may scalarize it.2526## Workflow2728### 1. Reconstruct the actual contract2930Before proposing or changing a rule:31321. Locate the source API under `tilelang/language/`.332. Determine its source TIR representation. Do not infer semantics from the34 Python spelling alone: `T.Pipelined` is a serial `For` with annotations, and35 `T.Persistent` expands early into binds plus a serial loop.363. Trace the construct through the target pipelines and identify the first pass37 that assumes the proposed invariant.384. Search tests and examples for valid counterexamples.395. Load the relevant domain reference completely:4041 - loop nesting and loop/storage ownership:42 `references/loop-rules.md`;43 - bounds, initialization, scopes, races, synchronization, barriers, or44 async operations: `references/memory-concurrency.md`;45 - TileOps, software pipelines, reducers, layouts, kernel launch, or dtype46 contracts: `references/operations-layout.md`.4748For loop-nesting work, also run:4950```bash51python .agents/skills/tilelang-semantic/scripts/scan_loop_nesting.py52```5354Absence from the repository is not proof that a construct is invalid. Confirm55the downstream assumption in code or with a minimal lowering test.56Treat the scanner as an inventory aid, not a proof: inspect non-literal57annotation dictionaries and generated TIR manually.5859### 2. Specify the rule before implementing it6061Write down all of the following:6263- **Scope:** the exact node, storage scope, or lexical region covered.64- **Invariant:** what every valid program must satisfy.65- **Proof criterion:** what the checker must establish before reporting.66- **Exemptions:** atomics, reducers, generated IR, target-specific paths, etc.67- **Near-neighbor valid case:** the smallest similar program that must remain68 accepted.69- **Diagnostic:** name the offending construct and give an actionable rewrite.70- **Enforcement stage:** frontend, pre-lower, early native verification,71 post-inference, or backend-specific lowering.7273For nesting rules, define a *path* as one lexical ancestor chain from the74function body to a leaf statement. Sequential sibling loops are different75paths.7677### 3. Choose the earliest reliable enforcement stage7879| Stage | Use it for |80|---|---|81| Frontend API | Invalid argument combinations or types known while constructing the loop/op |82| `PreLowerSemanticCheck` | Backend-independent source-TIR structure with user-facing syntax still recognizable |83| Early native `Verify*` pass | Analyzer-, effect-, region-, or dataflow-dependent checks shared by backends |84| After `LayoutInference` | Contracts involving inferred `layout_map` or `parallel_loop_layout` |85| Backend pipeline | Rules that genuinely depend on target instructions or execution geometry |8687Do not place a rule after a transform that erases the evidence needed to report88it. If an early expansion erases identity, preserve an explicit annotation89instead of pattern-matching incidental lowered shapes.9091### 4. Implement a validator, not a transform9293- Keep validation side-effect free.94- Maintain lexical state with a stack and restore it on every exit path.95- Use `For`, `Buffer`, `Var`, and other ObjectRef handles for retained identity;96 follow `$tilelang-tvm-ir` for C++ TIR code.97- Share traversal/variable-use utilities when rules need the same facts, but98 keep diagnostics and rule ownership independent.99- Include source spans when the IR carries them.100- Use a stable prefix such as `[TileLang Semantic Check]` and describe a legal101 replacement.102- Honor the existing global pre-lower opt-out for compatibility. Do not add a103 new per-rule opt-out for a proven-invalid rule unless compatibility requires104 one; reserve fine-grained opt-outs for inconclusive analyses.105106### 5. Test the semantic boundary107108Add, at minimum:1091101. one failing test for each violation shape;1112. one near-neighbor valid test;1123. a proof-boundary case that remains accepted when the analysis is113 inconclusive;1144. alternate control-flow paths for state/lifecycle rules;1155. target-specific accepted and unsupported cases when capability matters;1166. a diagnostic assertion that checks the useful part of the message.117118Also run affected backend codegen tests when a rule migrates existing kernels.119Use `$tilelang-build` for repository test commands. For a Python pre-lower120checker, start with:121122```bash123python -m pytest testing/python/analysis -q124python -m ruff check <changed-python-files>125git diff --check126```127128## Validation ownership map129130- `tilelang/engine/semantic_check.py`: shared pre-lowering entry point.131- `tilelang/analysis/*checker.py`: source-TIR structural rules and actionable132 frontend diagnostics.133- `src/transform/verify_*.cc`: native effect/dataflow verification such as134 reducer lifecycle, buffer initialization, and parallel races.135- `src/transform/legalize_safe_memory_access.cc`: bounds proof, global guards,136 and optional local/shared warnings.137- `tilelang/language/*_op.py` and `tilelang/language/builtin.py`: source API138 operand and annotation validation.139- `src/transform/{pipeline_planning,inject_pipeline}.cc`: pipeline dependency,140 ordering, replayability, and multi-versioning contracts.141- `src/transform/layout_inference/parallel_loop_layout_validator.h`:142 post-inference parallel-layout annotation contract.143- `tilelang/{cuda,rocm,cpu,metal,webgpu}/pipeline.py`: target pipeline order.144- `tilelang/transform/pass_config.py`: opt-outs and strictness controls.145146Read `$tilelang-layout` before changing rules whose truth depends on fragment147ownership, replication, loop partitioning, or inferred loop layouts.148149## Avoid150151- Do not equate `T.Parallel` with `T.vectorized`; they represent different152 execution layers and use different lowering paths.153- Do not reject every construct that falls back to serial execution.154- Do not promote “cannot prove safe” to “proven unsafe.”155- Do not use Python `assert` for new user-facing legality checks; assertions156 disappear under optimized Python and usually produce poor diagnostics.157- Do not infer source intent from `ForKind` alone when annotations define the158 construct.159- Do not treat nested pipeline requests as backend-independent invalidity;160 hierarchical-pipeline support is a backend capability.161- Do not require parallel extent to equal thread count or explicit layout162 shape; partitioning, replication, and guarded tails intentionally permit163 differences.164- Do not reject barriers merely because they occur inside `T.Parallel`;165 validate participant sets, path uniformity, and execution counts.166- Do not report a missing target feature or missed optimization as universal167 semantic invalidity.168169## Resources170171- `references/loop-rules.md`: established loop contracts, representation172 details, non-rules, and backend-specific nested-pipeline guidance.173- `references/memory-concurrency.md`: buffer bounds/initialization/ownership,174 aliasing, races, collective synchronization, barriers, and async lifetimes.175- `references/operations-layout.md`: TileOp, pipeline, reducer, layout,176 kernel/target, and dtype contracts plus the implementation roadmap.177- `scripts/scan_loop_nesting.py`: inventory lexical loop pairs and detect178 nested software-pipeline requests in Python sources without judging backend179 support.