TileLang → FlyDSL Conversion Skill
What this skill is for
You are translating a kernel written in TileLang (Apache TVM TIR-based,
@T.prim_func decorated, used in tile-ai/tilelang and the TileKernels
operator collection from DeepSeek) into FlyDSL (Python DSL on top of an
MLIR-native fly dialect that targets ROCm/HIP via ROCDL). FlyDSL is a
lower-level kernel authoring surface: tile and thread mappings are explicit,
copies are atom-call based, and GEMMs are emitted through MFMA atoms instead of
a dispatched T.gemm.
Treat the TileLang source as a specification — match its observable
behaviour (input/output shapes, dtypes, math) — and re-derive an equivalent
FlyDSL kernel. Mechanical line-by-line translation rarely works because the two
DSLs sit at different abstraction levels.
When to invoke
Invoke (or load) this skill when any of the following is true:
- The user asks to "port", "convert", "translate", "rewrite" a kernel from
TileLang to FlyDSL, or vice versa references both projects.
- The user references TileKernels (
tile_kernels/...), @T.prim_func,
T.Kernel, T.alloc_shared, etc. and wants the result to land in a FlyDSL
codebase.
- A test in
TileKernels/tests/... must keep passing while the Python wrapper
is re-implemented on top of FlyDSL.
Do not invoke for changes that stay within a single DSL.
Operating constraint: no execution
This skill assumes that you cannot build or run either project from this
environment (no GPU, neither tilelang nor flydsl is necessarily installed).
That means:
- Validation is review-based, not test-based. Use the workflow in
references/workflow.md and the gotcha list in references/gotchas.md to
audit each converted kernel before declaring it complete.
- Never claim "tests pass" or "kernel verified" unless the user has actually
run them and shared the output.
- When a behavioural ambiguity blocks progress, surface it to the user as a
question rather than guessing.
Mental model — the four hard problems
Every TileLang→FlyDSL conversion reduces to four sub-problems. Solve them in
order:
- Launch shape. Translate
with T.Kernel(gx, gy, gz, threads=N) as (pid_x, pid_y, pid_z): into a @flyc.jit host function that calls
kernel(...).launch(grid=(gx, gy, gz), block=(N, 1, 1), stream=stream),
plus bid = fx.block_idx.{x,y,z} and tid = fx.thread_idx.x reads inside
the @flyc.kernel body. Multi-dim block (threads=(tx, ty)) is rare in
TileKernels but does occur — preserve it.
- Memory map. Map every
T.alloc_* to its FlyDSL counterpart:
alloc_shared → SmemAllocator.allocate_array (with finalize() in the
jit body), alloc_local/alloc_fragment → fx.memref_alloca with a
register-space memref type, scalar alloc_var(init=v) → a Python value
threaded through range(..., init=[...]) if it must be loop-carried,
otherwise just a normal Float/Int variable.
- Loop nest. Map
T.Parallel, T.serial, T.unroll, T.vectorized,
T.Pipelined (see references/api_mapping.md row "Loops"). The trickiest
one is T.Parallel — it has no direct FlyDSL counterpart and you must
thread-distribute by hand using tid arithmetic or a tiled copy.
- Data movement.
T.copy(global, shared) and T.copy(shared, global)
call sites become tiled copies in FlyDSL: fx.rocdl.make_buffer_tensor →
zipped_divide/logical_divide → make_tiled_copy(...) →
thr_copy.partition_S/D → fx.copy(copy_atom, ...). A literal
arr[i, j] = ... write becomes a single fx.copy_atom_call(...) with a
one-element register memref, or — when many threads write contiguously —
the same tiled copy machinery.
The compute body in between (arithmetic, reductions, control flow) usually
maps cleanly once 1–4 are in place.
Workflow
Follow references/workflow.md step-by-step on each kernel. The high-level
loop is:
- Read the TileLang source end-to-end. Note the kernel signature, every
T.alloc_*, every T.copy / T.gemm, every loop kind, every reduction.
Identify what is constexpr vs runtime dynamic.
- Read the test that calls it. The Python wrapper signature
(
transpose(x: torch.Tensor), topk_gate(scores, num_topk), ...) is the
contract you must preserve. The test imports
tile_kernels.<module>.<func> and compares against a reference. Keep the
wrapper, replace the JIT factory body.
- Sketch the FlyDSL skeleton using
references/idioms.md for the closest
matching pattern (elementwise / reduction / shared-mem rearrange / GEMM).
- Fill in compute, copy, and reduction blocks. Use
references/api_mapping.md
as a translation dictionary, but do not blindly inline — re-derive the
thread-to-data mapping each time.
- Audit against
references/gotchas.md. Run through every entry; each
one is something the agent has gotten wrong before.
- Report status. Tell the user exactly which review checks you completed
and which require GPU execution to verify.
Reference files
Read these on demand — they are organised as quick lookups, not narrative:
references/api_mapping.md — comprehensive symbol table:
every T.* primitive used in TileKernels paired with its FlyDSL spelling.
references/idioms.md — side-by-side patterns for the five kernel
archetypes: elementwise/cast, reduction (norm / softmax / topk),
shared-memory rearrange (transpose), GEMM, fused
copy+compute+reduce.
references/gotchas.md — pitfalls and review checklist. Read before
declaring a conversion done.
references/workflow.md — the procedure to follow per kernel, including
how to handle the "I cannot run it" constraint with a static review pass.
references/worked_examples/normalize_weight.md — full conversion of a
small reduction kernel (tile_kernels/moe/normalize_weight_kernel.py).
references/worked_examples/batched_transpose.md — full conversion of a
shared-memory rearrange kernel (tile_kernels/transpose/...).
references/worked_examples/gemm_skeleton.md — annotated FlyDSL GEMM
skeleton you can adapt when a TileLang kernel uses T.gemm.
Project structure assumptions
The skill is portable. When applying to a new project, locate these things in
the target codebase rather than assuming the paths from the worked examples:
- TileLang sources usually live at
<repo>/tilelang/tilelang/language/...
if vendored, otherwise tilelang is just a pip dependency. Public surface
is from tilelang import language as T.
- FlyDSL Python expression API is at
<flydsl-checkout>/python/flydsl/expr/{primitive,gpu,buffer_ops,rocdl,vector,math,numeric,typing}.py.
- FlyDSL pre-built kernels at
<flydsl-checkout>/kernels/*.py are the most
reliable references for production patterns (softmax_kernel.py and
rmsnorm_kernel.py are the closest to TileKernels-style elementwise+reduction
kernels; preshuffle_gemm.py is the closest to GEMM).
When asked to convert an unfamiliar TileKernels kernel, default to:
Read the TileLang source.
Read the matching test under TileKernels/tests/<module>/test_<name>.py.
Grep <flydsl>/kernels/ for an analogous existing FlyDSL kernel and
Read it as a structural template.
- Then proceed with the workflow above.
1---2name: tilelang-to-flydsl3description: >4 Port a kernel written in TileLang (the `@T.prim_func` / `with T.Kernel(...)` DSL5 used by TileKernels and other tile-ai projects) into an equivalent FlyDSL6 kernel (`@flyc.kernel` / `@flyc.jit` with explicit layout algebra,7 copy atoms, MMA atoms, and SmemAllocator). Use whenever the task is to8 rewrite, translate, or migrate a TileLang `@T.prim_func` body into FlyDSL,9 including converting individual operators in the TileKernels test suite10 while preserving the Python wrapper signatures so the existing pytest11 cases keep validating the new implementation.12allowed-tools: Read Edit Write Bash Grep Glob Agent13metadata:14 source: https://skillmd.com/skills/wenyi-li/tilelang-to-flydsl15---1617# TileLang → FlyDSL Conversion Skill1819## What this skill is for2021You are translating a kernel written in **TileLang** (Apache TVM TIR-based,22`@T.prim_func` decorated, used in `tile-ai/tilelang` and the `TileKernels`23operator collection from DeepSeek) into **FlyDSL** (Python DSL on top of an24MLIR-native `fly` dialect that targets ROCm/HIP via ROCDL). FlyDSL is a25*lower-level* kernel authoring surface: tile and thread mappings are explicit,26copies are atom-call based, and GEMMs are emitted through MFMA atoms instead of27a dispatched `T.gemm`.2829Treat the TileLang source as a **specification** — match its observable30behaviour (input/output shapes, dtypes, math) — and re-derive an equivalent31FlyDSL kernel. Mechanical line-by-line translation rarely works because the two32DSLs sit at different abstraction levels.3334## When to invoke3536Invoke (or load) this skill when any of the following is true:3738- The user asks to "port", "convert", "translate", "rewrite" a kernel from39 TileLang to FlyDSL, or vice versa references both projects.40- The user references TileKernels (`tile_kernels/...`), `@T.prim_func`,41 `T.Kernel`, `T.alloc_shared`, etc. and wants the result to land in a FlyDSL42 codebase.43- A test in `TileKernels/tests/...` must keep passing while the Python wrapper44 is re-implemented on top of FlyDSL.4546Do **not** invoke for changes that stay within a single DSL.4748## Operating constraint: no execution4950This skill assumes that you cannot build or run either project from this51environment (no GPU, neither `tilelang` nor `flydsl` is necessarily installed).52That means:5354- Validation is **review-based**, not test-based. Use the workflow in55 `references/workflow.md` and the gotcha list in `references/gotchas.md` to56 audit each converted kernel before declaring it complete.57- Never claim "tests pass" or "kernel verified" unless the user has actually58 run them and shared the output.59- When a behavioural ambiguity blocks progress, surface it to the user as a60 question rather than guessing.6162## Mental model — the four hard problems6364Every TileLang→FlyDSL conversion reduces to four sub-problems. Solve them in65order:66671. **Launch shape.** Translate `with T.Kernel(gx, gy, gz, threads=N) as68 (pid_x, pid_y, pid_z):` into a `@flyc.jit` host function that calls69 `kernel(...).launch(grid=(gx, gy, gz), block=(N, 1, 1), stream=stream)`,70 plus `bid = fx.block_idx.{x,y,z}` and `tid = fx.thread_idx.x` reads inside71 the `@flyc.kernel` body. Multi-dim block (`threads=(tx, ty)`) is rare in72 TileKernels but does occur — preserve it.732. **Memory map.** Map every `T.alloc_*` to its FlyDSL counterpart:74 `alloc_shared` → `SmemAllocator.allocate_array` (with `finalize()` in the75 jit body), `alloc_local`/`alloc_fragment` → `fx.memref_alloca` with a76 register-space memref type, scalar `alloc_var(init=v)` → a Python value77 threaded through `range(..., init=[...])` if it must be loop-carried,78 otherwise just a normal Float/Int variable.793. **Loop nest.** Map `T.Parallel`, `T.serial`, `T.unroll`, `T.vectorized`,80 `T.Pipelined` (see `references/api_mapping.md` row "Loops"). The trickiest81 one is `T.Parallel` — it has *no direct* FlyDSL counterpart and you must82 thread-distribute by hand using `tid` arithmetic or a tiled copy.834. **Data movement.** `T.copy(global, shared)` and `T.copy(shared, global)`84 call sites become tiled copies in FlyDSL: `fx.rocdl.make_buffer_tensor` →85 `zipped_divide`/`logical_divide` → `make_tiled_copy(...)` →86 `thr_copy.partition_S/D` → `fx.copy(copy_atom, ...)`. A literal87 `arr[i, j] = ...` write becomes a single `fx.copy_atom_call(...)` with a88 one-element register memref, or — when many threads write contiguously —89 the same tiled copy machinery.9091The compute body in between (arithmetic, reductions, control flow) usually92maps cleanly once 1–4 are in place.9394## Workflow9596Follow `references/workflow.md` step-by-step on each kernel. The high-level97loop is:98991. **Read the TileLang source end-to-end.** Note the kernel signature, every100 `T.alloc_*`, every `T.copy` / `T.gemm`, every loop kind, every reduction.101 Identify what is *constexpr* vs *runtime dynamic*.1022. **Read the test that calls it.** The Python wrapper signature103 (`transpose(x: torch.Tensor)`, `topk_gate(scores, num_topk)`, ...) is the104 contract you must preserve. The test imports105 `tile_kernels.<module>.<func>` and compares against a reference. Keep the106 wrapper, replace the JIT factory body.1073. **Sketch the FlyDSL skeleton** using `references/idioms.md` for the closest108 matching pattern (elementwise / reduction / shared-mem rearrange / GEMM).1094. **Fill in compute, copy, and reduction blocks.** Use `references/api_mapping.md`110 as a translation dictionary, but do not blindly inline — re-derive the111 thread-to-data mapping each time.1125. **Audit against `references/gotchas.md`.** Run through every entry; each113 one is something the agent has gotten wrong before.1146. **Report status.** Tell the user exactly which review checks you completed115 and which require GPU execution to verify.116117## Reference files118119Read these on demand — they are organised as quick lookups, not narrative:120121- `references/api_mapping.md` — comprehensive symbol table:122 every `T.*` primitive used in TileKernels paired with its FlyDSL spelling.123- `references/idioms.md` — side-by-side patterns for the five kernel124 archetypes: elementwise/cast, reduction (norm / softmax / topk),125 shared-memory rearrange (transpose), GEMM, fused126 copy+compute+reduce.127- `references/gotchas.md` — pitfalls and review checklist. Read **before**128 declaring a conversion done.129- `references/workflow.md` — the procedure to follow per kernel, including130 how to handle the "I cannot run it" constraint with a static review pass.131- `references/worked_examples/normalize_weight.md` — full conversion of a132 small reduction kernel (`tile_kernels/moe/normalize_weight_kernel.py`).133- `references/worked_examples/batched_transpose.md` — full conversion of a134 shared-memory rearrange kernel (`tile_kernels/transpose/...`).135- `references/worked_examples/gemm_skeleton.md` — annotated FlyDSL GEMM136 skeleton you can adapt when a TileLang kernel uses `T.gemm`.137138## Project structure assumptions139140The skill is portable. When applying to a new project, locate these things in141the target codebase rather than assuming the paths from the worked examples:142143- TileLang sources usually live at `<repo>/tilelang/tilelang/language/...`144 if vendored, otherwise `tilelang` is just a pip dependency. Public surface145 is `from tilelang import language as T`.146- FlyDSL Python expression API is at147 `<flydsl-checkout>/python/flydsl/expr/{primitive,gpu,buffer_ops,rocdl,vector,math,numeric,typing}.py`.148- FlyDSL pre-built kernels at `<flydsl-checkout>/kernels/*.py` are the most149 reliable references for production patterns (softmax_kernel.py and150 rmsnorm_kernel.py are the closest to TileKernels-style elementwise+reduction151 kernels; preshuffle_gemm.py is the closest to GEMM).152153When asked to convert an unfamiliar TileKernels kernel, default to:1541551. `Read` the TileLang source.1562. `Read` the matching test under `TileKernels/tests/<module>/test_<name>.py`.1573. `Grep` `<flydsl>/kernels/` for an analogous existing FlyDSL kernel and158 `Read` it as a structural template.1594. Then proceed with the workflow above.