The DSLs and the kernels no longer make ops or set dialect attributes by name: each dialect package gets the builder or helper they were missing, and every consumer goes through it. This now fix ZML core files as well |
History
|
|
|---|---|---|
| .. | ||
| BUILD.bazel | ||
| builder.zig | ||
| dtype.zig | ||
| PORTING.md | ||
| README.md | ||
ZML Triton DSL — Author's Guide
A Zig builder for Triton IR (TTIR) that tries to read like triton.language
Python while staying in pure Zig. Used by zml/kernels/moe/triton/,
zml/kernels/paged_attention/triton/, and by anything else that wants to call
Triton kernels from a ZML model.
Two layers define the surface:
- Low layer —
dsl/triton/builder.zig: the IR builder primitives.Builder,Value,DType,ArgSpec. Use these directly when you need full control (custom op insertion, dynamic-arity arg lists, escape hatches).Builder.open/Builder.inittake an*mlir.Context— pass them azml.kernel.triton.newContext()(a throwaway context with the dialects the DSL emits),defer ctx.deinit()once you have the IR string. Not azml.Compiler'smlir_ctx: that one carries onlyfunc/stablehlo/sdy(a registeredllvmdialect makes XLA:TPU choke). - High layer —
zml.kernel.triton.Kernel(Config, spec): the declarative kernel form. Bundles a config type, a typed spec literal (name + namedinputs/outputs+ a typedrunfunction pointer), and produces a kernel type. Exposes.emit(allocator, cfg)(TTIR string; manages its own throwaway context) and.call(inputs, outputs, opts)(TTIR string +stablehlo.custom_callin one shot — the preferred form for production model code). Inputs and outputs are by-name structs generated from the spec, so missing / typo'd / extra arguments are compile errors at the callsite.
Table of contents
- Skeleton of a kernel
zml.kernel.triton.Kernel(Config, spec)— the declarative form- Calling kernels from a ZML model —
K.Kernel.call(...) - Argument specs
- The
Valuetype - Fluent methods on
Value - Polymorphic scalars
- Comptime vs runtime widths
- Shape helpers
- Loads and stores
- Reductions and scans
- Control flow
- Escape hatches
- Lower layer —
Builder.open - Python Triton ↔ Zig DSL cheat-sheet
- Pitfalls
Skeleton of a kernel
const tri = @import("zml").kernel.triton;
const zml = @import("zml");
pub const MyKernel = struct {
pub const Cfg = struct { BLOCK: i32 = 64 };
pub const Kernel = tri.Kernel(Cfg, .{
.name = "my_kernel",
.inputs = &.{ "x_ptr", "y_ptr", "n" },
.outputs = &.{"out"},
.run = run,
});
fn run(b: *tri.Builder, cfg: Cfg) tri.FinishError!void {
const a = try b.declareArgs(.{
.x_ptr = .{ .ptr = .f32 },
.y_ptr = .{ .ptr = .f32 },
.n = .{ .scalar = .i32 },
.out_ptr = .{ .ptr = .f32 },
});
const pid = b.programId(.x);
const offs = b.arange(0, cfg.BLOCK, .i32).add(pid.mul(cfg.BLOCK));
const mask = offs.lt(a.n);
const x = b.loadOpts(a.x_ptr.addPtr(offs), .{ .mask = mask });
const y = x.mul(2.0);
b.storeOpts(a.out_ptr.addPtr(offs), y, .{ .mask = mask });
}
};
A kernel is a struct {…} wrapper bundling three decls:
pub const Cfg— config type, an inlinestruct { ... }of comptime/runtime parameters. Use field defaults for sensible defaults.pub const Kernel = tri.Kernel(Cfg, .{ .name, .inputs, .outputs, .run })— the spec literal that turns into a kernel type.inputs/outputsare slices of[:0]const u8field names; the factory generatesInputs(struct ofTensor),Outputs(struct ofShape), andResults(struct ofTensor) types from those names. Therunfield is a typed function pointer — wrong signature is a compile error here.fn run(b, cfg)— the kernel body. First calltry b.declareArgs(.{…})to create thett.funcop and bind a struct ofValues named after the spec's fields. The rest ofrunbuilds the body viab.*helpers. No string return, no allocator, no manualtt.return— the factory terminates, verifies, and serializes for you.
The names in spec.inputs / spec.outputs are the call-site names
(used to build the Inputs / Outputs structs) and don't have to match
the names in b.declareArgs(...) (which are the TTIR-level arg names).
By convention they often do — pick whatever reads best at the boundary.
The arg spec inside b.declareArgs(...) is a struct literal — its variant
tags (.ptr, .scalar, etc.) are comptime-known per call site, but the
payload values (cfg.input_dtype, cfg.output_dtype, …) can be runtime
values. This is what makes the same form work for both comptime-pinned
configs (offline tools, simple kernels) and runtime configs (production
models where dtypes/sizes come from Tensor.dim() / Options).
Why the wrapper struct.
Cfghas to be a named type so the typedrun: *const fn (*Builder, Cfg) FinishError!voidfield in the spec can reference it. Wrapping the kernel inpub const MyKernel = struct {...}keepsCfg,Kernel, andrunscoped together and exposes them all to callers (MyKernel.Cfg,MyKernel.Kernel, plus everything the inner Kernel re-exports —MyKernel.Kernel.Config,.Inputs,.Outputs,.Results,.CallOpts).
Two ways to use a kernel
Offline / tooling — get the TTIR string (no MLIR context needed; emit
spins up and tears down its own):
const ttir = try MyKernel.Kernel.emit(allocator, .{ .BLOCK = 1024 });
defer allocator.free(ttir);
Inside a ZML forward(...) — emit TTIR and drop a stablehlo.custom_call
into the model in one shot:
const out = MyKernel.Kernel.call(
.{ .x_ptr = x_tensor, .y_ptr = y_tensor, .n = n_tensor }, // Inputs
.{ .out = x_tensor.shape() }, // Outputs (Shapes)
.{
.cfg = .{ .BLOCK = 1024 },
.grid = .{ ceilDiv(n, 1024), 1, 1 },
.num_warps = 4,
.num_stages = 2,
},
).out;
Kernel.call returns a Results struct (one Tensor per output name);
read fields by name (out.out, align_outs.sorted_token_ids, …).
zml.kernel.triton.Kernel(Config, spec) — the declarative form
zml.kernel.triton.Kernel(Config, spec) is a comptime function returning a
kernel type. Config is the per-call config type (used both for the
generated Inputs/Outputs/CallOpts and for the typed run signature);
spec is a Spec(Config) literal:
| Field | Type | Meaning |
|---|---|---|
.name |
[:0]const u8 |
Kernel name (used as the tt.func symbol). |
.inputs |
[]const [:0]const u8 |
Field names for the call-site Inputs struct (fields are Tensor). Order must match the tt.func arg order for input pointers. |
.outputs |
[]const [:0]const u8 |
Field names for the Outputs (struct of Shape) and Results (struct of Tensor). Order must match the tt.func arg order for output pointers — XLA's lowering passes inputs first, then outputs. |
.run |
*const fn (*Builder, Config) FinishError!void |
Typed function pointer to the kernel body. Wrong signature → compile error here, not at first call. |
Wrong arity, missing field, typo'd name on the call site → compile error
at the call site (because Inputs / Outputs are real struct types, not
tuples).
run is responsible for declaring the kernel's args (via
b.declareArgs(...)) and emitting the body. It emits ops via b.* helpers
and never returns a string; Kernel.emit(...) does the
terminate-verify-serialize dance after run returns.
Calling kernels from a ZML model — K.Kernel.call(...)
Inside a model's forward(...), drop in a Triton kernel alongside regular
ZML ops with K.Kernel.call(...):
pub fn forward(self: Model, x: zml.Tensor, y: zml.Tensor) zml.Tensor {
const x_pre = x.mul(2.0); // stablehlo
const out = MyKernel.Kernel.call(
.{ .x_ptr = x_pre, .y_ptr = y, .n = n_tensor }, // Inputs (by name)
.{ .out = x_pre.shape() }, // Outputs (Shapes)
.{
.cfg = .{ .BLOCK = 1024 }, // runtime config
.grid = .{ ceilDiv(x.dim(0), 1024), 1, 1 },
.num_warps = 4,
.num_stages = 2,
},
).out; // .out: Tensor
return out.relu(); // stablehlo
}
call is a thin wrapper over Kernel.emit(...) + zml.ops.triton(...).
It must be called from inside a Compilation (i.e., during
zml.Compiler.compile(...)) — emit builds the TTIR string in its own
throwaway context; zml.ops.triton(...) drops the stablehlo.custom_call
into the model's context. For offline tools, Kernel.emit(allocator, cfg)
gives you just the TTIR string.
Signature: Kernel.call(inputs: Inputs, outputs: Outputs, opts: CallOpts) Results.
| Positional arg | Type | Meaning |
|---|---|---|
inputs |
Kernel.Inputs |
Struct of Tensor, one field per name in spec.inputs. |
outputs |
Kernel.Outputs |
Struct of Shape, one field per name in spec.outputs. |
Kernel.CallOpts (typed struct, all fields named):
| Field | Type | Meaning |
|---|---|---|
.cfg |
Kernel.Config |
Per-call kernel config. |
.grid |
[3]i32 |
Triton launch grid (grid_x, grid_y, grid_z). |
.num_warps |
i32 |
Triton launch param. |
.num_stages |
i32 |
Triton launch param. |
.output_operand_aliases |
?zml.ops.CustomCallOutputOperandAliases(Inputs, Outputs) (default null) |
For in-place updates: each output field names the input it aliases — .{ .out = .x_ptr }. |
.debug |
bool (default false) |
Emit tt.debug = true on the custom call. |
Returns Kernel.Results — a struct of Tensor named like spec.outputs.
Read by name: out.out, attn_output.segm_max, etc.
The cfg value can be a comptime literal or a runtime expression built
from Tensor.dim() / Options fields. The kernel TTIR is regenerated per
call (cached by the MLIR canonicalizer / CSE pass at the XLA layer).
Why named
Inputs/Outputs. The previous form tookanytypetuples and matched by position; misordering 27 args (typical inunified_attention.zig) was a silent corruption hazard. With generated structs (Inputs = StructOf(spec.inputs, Tensor),Outputs = StructOf(spec.outputs, Shape)), Zig refuses unknown fields, missing fields, and wrong-typed values at the callsite.
Argument specs
Each field passed to b.declareArgs(...) is an ArgSpec.Kind tagged-union
literal.
The four arg kinds mirror what TTIR's tt.func can carry:
| Kind literal | MLIR type | Use case |
|---|---|---|
.{ .ptr = .f32 } |
!tt.ptr<f32> |
Pointers (default divisibility) |
.{ .scalar = .i32 } |
plain i32 |
Strides, sizes, flags |
.{ .tensor = .{ &.{64, 128}, .f32 } } |
tensor<64x128 x f32> |
Pre-built tensor input (rare) |
.{ .ptr_opts = .{ .dtype = .f32, .divisibility = 16 } } |
!tt.ptr<f32> with override |
Custom address_space/divisibility |
.{ .scalar_opts = .{ .dtype = .i32, .divisibility = 16 } } |
plain i32 with tt.divisibility = 16 : i32 |
Scalar with specialization hint |
.ptr gets a default tt.divisibility = 16 hint (matching Python Triton's
default). Use .ptr_opts to change that (or set divisibility = null to
suppress). .scalar carries no extra hint; switch to .scalar_opts when
you want to declare the same tt.divisibility Python's JIT auto-attaches
to int args whose runtime value is a multiple of 16.
Runtime dtypes: the variant tags (.ptr, .scalar, etc.) must be
fixed per kernel — every call to b.declareArgs(...) for a given kernel
uses the same struct shape. The variant payloads (the dtype enum, the
divisibility int) can be runtime values from cfg:
.a_ptr = .{ .ptr = cfg.a_dtype } works fine even when cfg.a_dtype is a
runtime field.
The Value type
pub const Value = struct {
inner: *const mlir.Value,
kernel: ?*Builder = null,
...
};
inneris the underlying MLIR SSA handle; reach for it when you need to call into rawttir.*/arith.*constructors.kernelis the owningBuilderpointer; all fluent methods route through it. The DSL populateskernelautomatically for every value it creates (emit,arg, loop-region args, reduction-region args, etc.). If you construct aValueby hand (.{ .inner = raw }), the fluent methods will panic — useBuilder.*static helpers instead.
Introspection methods always available:
| Method | Returns | Notes |
|---|---|---|
type_() |
*const mlir.Type |
Full MLIR type (scalar or tensor). |
elemType() |
*const mlir.Type |
Element type; same as type_() for scalars. |
isTensor() |
bool |
true for ranked tensors. |
rank() |
usize |
0 for scalars. |
dim(i) |
i64 |
Traps on scalars. |
shape() |
Shape (BoundedArray, MAX_RANK) |
Use .constSlice() to feed []const i64. |
isFloatElem() |
bool |
True for any float element type. |
isIntElem() |
bool |
True for any integer element type. |
Fluent methods on Value
Every fluent method returns a new Value. They dispatch to
arith.addi / arith.addf / ... based on the element type. The RHS is
anytype — see Polymorphic scalars.
Arithmetic
| Method | Int op | Float op | Notes |
|---|---|---|---|
.add(rhs) |
arith.addi |
arith.addf |
|
.sub(rhs) |
arith.subi |
arith.subf |
|
.mul(rhs) |
arith.muli |
arith.mulf |
|
.div(rhs) |
arith.divsi |
arith.divf |
Signed integer divide. |
.rem(rhs) |
arith.remsi |
arith.remf |
Signed integer remainder. |
.cdiv(rhs) |
arith.ceildivsi |
— | Int only — for tl.cdiv. |
.minimum(rhs) |
arith.minsi |
arith.minnumf |
Matches tl.minimum (non-NaN-prop). |
.maximum(rhs) |
arith.maxsi |
arith.maxnumf |
Matches tl.maximum (non-NaN-prop). |
.bitAnd(rhs) |
arith.andi |
— | Also handles i1 masks. |
.bitOr(rhs) |
arith.ori |
— |
Comparisons
All return i1 (scalar) or tensor<... x i1>. Signed integer predicates by
default; .olt / .oge / ... for floats.
| Method | Int predicate | Float predicate |
|---|---|---|
.lt(rhs) |
.slt |
.olt |
.le(rhs) |
.sle |
.ole |
.gt(rhs) |
.sgt |
.ogt |
.ge(rhs) |
.sge |
.oge |
.eq(rhs) |
.eq |
.oeq |
.ne(rhs) |
.ne |
.one |
Casts — .to(dtype)
v.to(.f32) chooses the right MLIR op based on the current vs target kind:
| Source kind | Target kind | MLIR op |
|---|---|---|
| int | wider int | arith.extsi |
| int | narrower int | arith.trunci |
| int | float | arith.sitofp |
| i1 | float | arith.uitofp (i1 is unsigned bool; sign-extending 1 would land at -1.0) |
| float | int | arith.fptosi |
| float | wider float | arith.extf (no rounding) |
| float | narrower float | fp8 involved or custom rounding → tt.fp_to_fp; otherwise arith.truncf |
| same type | same type | no-op (returns self) |
Triton's verifier rejects tt.fp_to_fp with a rounding attribute when the
target is not strictly narrower than the source (e.g. bf16 → f32, or
same-width bf16 ↔ f16). The DSL routes strict upcasts through
arith.extf to match Python Triton's own lowering; only genuine
downcasts carry the rtne rounding attribute.
For narrowing FP→FP, the dispatch follows
triton/python/triton/language/semantic.py:cast(): standard FP narrowing
between fp64 / fp32 / fp16 / bf16 lowers to arith.truncf (rank-independent
— scalar and tensor both), while tt.fp_to_fp is reserved for cases where
fp8 is on either side or the caller requested a non-default
fp_downcast_rounding.
Constants
There is no constant cache and no hoisting: every lifted literal emits its
own arith.constant where it is used (see Pitfall 5). zeros(shape, dtype),
ones(shape, dtype), full(shape, value, dtype) and splat of a literal
emit a scalar arith.constant and a tt.splat; splat(Value, shape) emits
the tt.splat alone.
Shape / pointer helpers
| Method | Effect |
|---|---|
v.expandDims(axis) / b.expandDims(v, axis) |
tt.expand_dims — insert a size-1 axis at axis. Mirrors v[:, None] (axis=1) / v[None, :] (axis=0). |
b.broadcastTo(v, shape) |
tt.broadcast — explicit broadcast (size-1 dims → target). Rarely needed; auto-broadcast handles it. |
.splatTo(shape) |
tt.splat this scalar to the given shape. |
.addPtr(offset) |
tt.addptr; offset can be a Value or a comptime int. |
Auto-broadcast is everywhere. Mirrors Triton's
semantic.broadcast_impl_value(triton/python/triton/language/semantic.py:724): rank-unification (prepend size-1 axes) + size-1 → size-N expansion. Applied transparently at:
- every fluent binop (
.add,.mul,.lt,.bitAnd, …).addPtr(offset)(either side may be scalar or rank-mismatched)b.where(cond, x, y)/b.select(...)maskandotherofb.loadOpts/b.storeOptsSo
v[:, None] * stride + w[None, :] * other_strideis just:v.expandDims(1).mul(stride).add(w.expandDims(0).mul(other_stride))No
broadcastTo, no full-shapett.splat— the broadcast materializes implicitly at theaddi. This matches Python's emit pattern op-for-op (Python's frontend never emits an eagertt.broadcastfollowed by aarith.mulieither; it emitsexpand_dims+splat<size-1> + muli).Reach for
b.broadcastToonly when the consumer is a low-level op that bypasses the DSL's auto-broadcast — directarith.*/ rawttir.*escape-hatch paths.
Polymorphic scalars
Every fluent method's RHS (and every b.splat / b.lift input) is anytype.
The lift rule:
Value→ pass through.comptime_int/comptime_float→ a constant whose element type matches the LHS operand.v_i64.mul(16)lifts16to i64,v_f32.add(1.0)lifts1.0to f32, and so on.- Runtime
i8/i16/i32,i64,f16/f32/f64, etc. → a constant that preserves the source Zig width. i8/i16/i32 (signed or unsigned) → i32 const; i64/u64 → i64 const; f16 → f16; f32 → f32; f64 → f64. Unsigned ints are bit-cast (bit pattern preserved), so@as(u32, 0xFFFF_FFFF)becomes an i32 with the same all-ones bit pattern.
This is why the common Python idiom offs < 64 works in Zig as
offs.lt(64) without any wrapper — as long as the comptime scalar can be
represented in offs's element type.
If you need to force a specific width for a runtime variable, cast at the call
site: pid.mul(@as(i32, @intCast(block_size))).
When is @as actually needed? (Rule of thumb)
Auto-lift covers most cases. @as(...) around a binop rhs is redundant
in all of these — drop it:
| Pattern | Auto-lifts to… |
|---|---|
v_i64.eq(0) / .div(16) / .add(-1) |
comptime_int → match lhs elem type |
v_f32.mul(1.0 / config.fp8_max) |
already-f32 expression → f32 const |
v_i64.lt(NUM_QUERY_HEADS) (Zig i64) |
runtime i64 → i64 const |
v_i32.add(pad_term) (Zig i32) |
runtime i32 → i32 const |
b.splat(-1, shape) / b.openFor(0, N, 1, ...) |
comptime → matches elem / the first Value bound |
b.constant(.i32, 0) |
constant takes anytype — wrap nothing |
@as(...) is required exactly when you're narrowing a runtime Zig int
to a smaller width that lift won't pick on its own. The idiom is
@as(i32, @intCast(X_i64)) — you need the @as because @intCast has no
target type to infer, and without the narrowing lift would emit an i64
constant, which widens the i32 lhs and the result to i64:
// BLOCK_Q is a Zig i64 (from config). lhs is i32. Must narrow.
q_start_raw.div(@as(i32, @intCast(BLOCK_Q))).add(seq_idx)
The alternative — q_start_raw.to(.i64).div(BLOCK_Q).to(.i32) — mirrors
Python's .to(tl.int64) style but costs two extra Value-level casts; prefer
the narrowing @as or a pre-declared const FOO_I32: i32 = @intCast(FOO);
when the same width cast recurs.
When do you need b.lift / b.constant?
Almost never. The DSL auto-lifts rhs for every fluent binop, b.splat,
b.full, b.openFor bounds, .addPtr offsets, etc. Reach for b.lift /
b.constant only when the DSL surface demands an existing Value and
there's no binop sibling to match against — typically:
- Loop seeds for
openWhile(.{inits}, ...)where you start with a raw comptime literal:const left_init = b.constant(.i32, 0);. - Mutable
var x: Value = b.constant(.i32, 0);that a later branch may reassign — the var needs an initial Value even if the comptime path would work on its own.
If the constant is about to flow through any .add / .mul / .splatTo
etc., skip the lift and let auto-lift do it. And if a stride is hardcoded
to 1, delete it: x.mul(1) is a no-op, the DSL isn't Python constexpr
where such names are required.
Scalar ↔ tensor auto-broadcast
Fluent arithmetic and comparison ops (.add, .sub, .mul, .div, .rem,
.cdiv, .bitAnd, .bitOr, .minimum, .maximum, .lt, .le, .gt,
.ge, .eq, .ne) are symmetric: if one operand is a tensor and the other a
scalar, the scalar is splatted to match. Either direction works:
const offs = iv.add(cols); // scalar iv + tensor cols → tensor
const offs = cols.add(iv); // tensor cols + scalar iv → tensor
This mirrors Triton/NumPy's i + cols. Size-1 and rank-unification
broadcasting also work (mirroring Python's
semantic.broadcast_impl_value): a (M, 1) and a (1, N) operand
broadcast to (M, N) automatically, and a (M,) lined up against a
(M, N) is first expand_dims'd to (1, M) and then broadcast. So
offs_token[:, None] + offs_k[None, :] is just:
const offs = b.expandDims(offs_token, 1).add(b.expandDims(offs_k, 0));
with no b.broadcastTo calls needed. b.where / b.select and the
mask / other operands of b.loadOpts / b.storeOpts also auto-broadcast,
so the only time b.broadcastTo is needed is when the consumer bypasses
the DSL (raw arith.* / ttir.* escape-hatch paths).
.addPtr auto-splats in both directions, matching Triton's
ptr + offset semantics: a scalar pointer is splatted to match a tensor
offset (x_ptr.addPtr(tensor_offs)), and a scalar offset is splatted to
match a tensor pointer (a_ptrs.addPtr(BLOCK_K)). Pre-splatting via
b.splat is no longer required for the loop-stride case.
When is scalar.splatTo(shape) redundant?
Because fluent binops (.add / .mul / …) already auto-splat scalars
against tensor siblings, and .addPtr auto-splats either side (scalar
pointer or scalar offset) against a tensor partner, a pre-emptive
scalar.splatTo(shape) is usually noise:
// redundant
pid_n.mul(N).splatTo(shape).add(b.arange(0, N, .i64)).rem(n_block.splatTo(shape))
// equivalent — scalars auto-splat against the tensor sibling
pid_n.mul(N).add(b.arange(0, N, .i64)).rem(n_block)
Keep the explicit splatTo only when the scalar feeds into a raw
arith.* / ttir.* escape-hatch op that doesn't go through the DSL's
auto-broadcast.
Comptime vs runtime widths
TTIR has no implicit int-width conversion — arith.muli(i32, i64) is a verifier
error. The DSL mirrors Python and auto-promotes integer binops when the
two runtime operands have different widths: it extsis the narrower side
to the wider, matching semantic.integer_promote_impl. So
v_i32.mul(v_i64) works without a manual .to(.i64) — it emits exactly
the same extsi + muli pair Python would.
For the rare case where you want explicit control, you can still cast yourself; the auto-promotion is a no-op when widths already agree.
Recurring example from zml/kernels/moe/triton/moe.zig:
// pid (i32) vs block (i64 because it came from a usize config)
const block_i32: i32 = @intCast(block);
const token_start_init = pid.mul(block_i32);
// alternative: pid.to(.i64).mul(block)
For pointer math it is often cleaner to promote everything to i64 up front:
const pid = b.programId(.x).to(.i64);
const offs = b.arange(0, BLOCK, .i64);
Shape helpers
| Helper | Effect |
|---|---|
b.arange(start, end, dtype) |
tl.arange(start, end).to(dtype). Pass .i32 for no-op cast. |
b.zeros(shape, dtype) |
tl.zeros(shape, dtype=dtype). |
b.ones(shape, dtype) |
Ones tensor. |
b.splat(value, shape) |
tl.splat; accepts Value or comptime scalar. |
b.expandDims(v, axis) / v.expandDims(axis) |
tt.expand_dims — insert a size-1 axis. Mirrors v[:, None] (axis=1) / v[None, :] (axis=0). |
b.mask2d(cond_m, cond_n, _, _) |
cond_m[:, None] & cond_n[None, :] — emits the (m,1) & (1,n) form; auto-broadcast at the next consumer. |
b.lift(value) |
Wrap a Zig scalar as a DSL Value; dtype inferred from source. |
b.constant(dtype, value) |
Wrap a Zig scalar as a DSL Value of a specific DType. |
b.constantLike(value, like) |
Wrap a Zig scalar as a DSL Value of like's element type. |
Loads and stores
Load helpers infer everything from the pointer's type — scalar !tt.ptr<T>
loads a scalar T, tensor<... x !tt.ptr<T>> loads a tensor<... x T>.
No result_type / shape / dtype arguments required.
| Helper | Python equivalent |
|---|---|
b.load(ptr) |
tl.load(ptr) — scalar or tensor. |
b.loadOpts(ptr, .{ .mask, .other, ... }) |
tl.load(ptrs, mask=..., other=..., cache_modifier=..., eviction_policy=..., volatile=...). |
b.store(ptr, value) |
tl.store(ptr, value). |
b.storeOpts(ptr, value, .{ .mask, ... }) |
tl.store(ptr, value, mask=..., cache_modifier=..., eviction_policy=...). |
LoadOpts / StoreOpts fields (.mask, .other, .cache_modifier,
.eviction_policy, .@"volatile") take DSL-level Values / enum literals —
no raw MLIR types needed.
Match Python's emit form for masked loads.
tl.load(ptr, mask=m, other=0.0)lowers to a 3-operandtt.loadop. To match it byte-for-byte in the Zig DSL, pass an explicit.other:const zero = b.zeros(&.{BLOCK}, dtype); const x = b.loadOpts(ptr, .{ .mask = mask, .other = zero });Calling
loadOptswith.maskonly (no.other) emits a 2-operandtt.load— semantically equivalent (out-of-bounds lanes are undefined, not zero), but the TTIR/TTGIR diff vs Python will not be empty. Triton'stl.load(ptr, mask=...)withoutother=lowers to the 2-operand form, so you only need the.otheroperand when the Python source explicitly passesother=.
Result-type inference
Most helpers that produce a new Value infer their result type from the inputs,
so user code never constructs *const mlir.Type manually:
| Helper | How the result type is derived |
|---|---|
b.load(ptr) / b.loadOpts(ptr, opts) |
From ptr.type_() (scalar or tensor of ptrs). |
b.dot(a, b, acc) / b.dotOpts(a, b, acc, opts) |
acc.type_(). |
b.dotScaled(...) / b.dotScaledOpts(...) |
acc.type_(). |
b.reshape(src, new_shape) / b.reshapeOpts(...) |
new_shape + src element type. |
b.gather(src, indices, axis) |
indices shape + src element type. |
b.histogram(src, num_bins) / b.histogramOpts(...) |
tensor<num_bins x i32>. |
b.fpToFp(src, out_dtype) / b.fpToFpOpts(...) |
src shape + out_dtype. |
b.convertf(src, out_dtype) / b.convertfOpts(...) |
src shape + out_dtype. |
b.scalingTruncf(src, scale, out_dtype) / …Opts |
src shape + out_dtype. |
b.descriptorLoad(desc, indices, shape, dtype) |
shape + dtype. |
Rule of thumb: you only supply things the op needs beyond what inputs carry —
a new_shape, a num_bins, an out_dtype, a TMA tile descriptor. The DSL
never asks you to restate information it can read off a Value.
b.scalarTy(dtype) / b.tensorTy(shape, dtype) are still available but only
needed for tensor result types in openIfElse / openWhile (scalar ones are
plain dtypes) and by the raw externElementwise / inlineAsmElementwise
escape hatches.
fn X / fn XOpts pattern
Every Builder method whose Python Triton counterpart has named keyword-only arguments comes in two flavours:
b.X(non_named_args...)— defaults applied; matchestl.X(args...)in Python, which in Python would use the zero-arg defaults.b.XOpts(non_named_args..., struct { named... })— full named-param set as a typed Zig struct literal with field defaults matching Triton.
Pairs in place today: load / loadOpts, store / storeOpts,
dot / dotOpts, reshape / reshapeOpts,
atomicRmw / atomicRmwOpts, atomicCas / atomicCasOpts,
fpToFp / fpToFpOpts, clampf / clampfOpts,
cast / castOpts, cat / catOpts,
convertf / convertfOpts, scalingTruncf / scalingTruncfOpts,
dotScaled / dotScaledOpts,
inlineAsmElementwise / inlineAsmElementwiseOpts,
externElementwise / externElementwiseOpts,
descriptorLoad / descriptorLoadOpts, histogram / histogramOpts,
devicePrint / devicePrintOpts,
deviceAssert / deviceAssertOpts,
maximum / maximumOpts, minimum / minimumOpts,
sum / sumOpts, max / maxOpts, min / minOpts,
cumsum / cumsumOpts, cumprod / cumprodOpts,
openFor / openForOpts (tl.range(..., num_stages=...)).
DSL-only pairs (no Python kwarg counterpart — .inline_return is about IR
block layout, see the returnIf / returnIfOpts section under Control flow):
returnIf / returnIfOpts, openReturnIf / openReturnIfOpts.
Ops with no kwargs in Python (pure positional): gather(src, indices, axis),
trans(src, order), permute(src, order), cat(lhs, rhs) (dim=0 default),
split(src), join(lhs, rhs), item(src), broadcast(a, b) (symmetric),
broadcastTo(value, shape), where(cond, x, y), zeros(shape, dtype),
full(shape, value, dtype).
Reductions and scans
const absmax = b.max(abs_y); // tl.max(abs_y) — axis=None (all dims)
const total = b.sum(padded_counts); // tl.sum(padded_counts)
const cumul = b.cumsum(x); // tl.cumsum(x, axis=0)
// Keyword arguments → the *Opts variant with a typed struct literal.
const axis0_max = b.maxOpts(abs_y, .{ .axis = 0 }); // tl.max(x, axis=0)
const absmax_kd = b.maxOpts(abs_y, .{ .axis = 0, .keep_dims = true }); // tl.max(x, 0, keep_dims=True)
const rev_cum = b.cumsumOpts(x, .{ .reverse = true }); // tl.cumsum(x, 0, reverse=True)
Under the hood these build the required tt.reduce / tt.scan region with a
matching arith.addf / arith.addi / maxnumf / maxsi combine function —
no more hand-rolled combiner closures for the common cases.
Gotcha —
maxnumfvsmaximumf(andminnumfvsminimumf): Triton'stl.max,tl.min,tl.maximum,tl.minimumall default to the non-NaN-propagating form (arith.maxnumf/arith.minnumf). The DSL fluent forms match Python:
Python DSL MLIR op tl.max(x)b.max(x)/x.max()arith.maxnumftl.min(x)b.min(x)/x.min()arith.minnumftl.maximum(a, b)a.maximum(b)/b.maximum(a, b)arith.maxnumftl.minimum(a, b)a.minimum(b)/b.minimum(a, b)arith.minnumftl.maximum(a, b, propagate_nan=NAN_ALL)a.maximumOpts(b, .{ .propagate_nan = .all })arith.maximumfThe lower-level builders
b.maximumf(a, b)/b.minimumf(a, b)skip Python's defaults and emit IEEE-754 NaN-propagating ops directly. Reach for them only when you genuinely want NaN propagation; otherwise stick withb.maximum/b.minimum(or the fluentValue.maximum/Value.minimum). Mismatched ops here cause subtle TTIR/LLIR diffs vs Python and are a frequent porting bug.
When .keep_dims = true, the DSL inserts a trailing
tt.expand_dims / splat so the result shape matches the input rank with a
size-1 reduced axis (matching Python Triton). For axis = null (the default),
the reduction goes through a tt.reshape allow_reorder first — even on rank-1
input — so the layout-assignment pass picks the same reduction-friendly
layout Python's frontend gets.
For custom combiners, use the low-level b.reduce(ctx, .{ .src, .axis, .elem, .result, .combine }) and b.scan(ctx, .{ .src, .axis, .elem, .result, .combine, .reverse }) — they take a fn(*Builder, Value, Value, CtxT) Value
closure for combine and give you full control.
Control flow
SCF regions are built with scope-based builders — b.openFor(...),
b.openIf(...) / b.openIfElse(...), b.openWhile(...) return a typed scope
value. You emit body ops into a bare {} block, terminate with yield /
yieldThen / yieldAfter (or close() for a scope without values), and read
results from scope.results afterward.
No ctx struct, no function literal, no kk/k split — lexical scope
carries captures because everything runs in the same function.
openFor — scf.for with iter_args
var loop = b.openFor(0, N, BLOCK, .{acc0});
{
const iv = loop.iv;
const acc = loop.carried[0];
const offs = iv.add(cols);
const tile = b.loadOpts(x_ptr.addPtr(offs), .{ .mask = offs.lt(N) });
const partial = tile.sum();
loop.yield(.{ acc.add(partial) });
}
const total = loop.results[0];
lower/upper/stepareanytype: pass Values, comptime ints, or runtime Zig ints. A bound that isn't a Value takes the type of the first one that is; with none,loweris lifted (i32when it fits) and the others follow it. Pass a typed constant (b.constant(.i64, 0)) to pick another width.initsis a tuple.{v1, v2, ...}or an array. Arity is comptime —carried,results, and theyield(...)values (also a tuple or an array) all have the same length.- Empty loops:
b.openFor(0, N, S, .{})+loop.close()(no iter_args). b.openForOpts(lower, upper, step, inits, .{ .num_stages = 3 })sets the loop's options (tt.num_stages,.unsigned_cmp).
openIf — scf.if without else (side-effects only)
var i = b.openIf(cond);
{
// then body
i.close(); // closes scope, builds scf.if with empty else
}
Use for conditional side-effects (no results). There is no else branch — the else block is auto-built empty.
openIfElse — scf.if with else and optional results
var i = b.openIfElse(cond, .{.f32}); // result types
{
// then body
i.yieldThen(.{ x });
}
{
// else body
i.yieldElse(.{ y });
}
const r = i.results[0];
result_typesis a tuple or array of dtypes (.f32), Values (for their types) or*const mlir.Types such asb.tensorTy(shape, dtype). Pass.{}for an if/else with no results but distinct then/else bodies, then end them withelseBranch()andclose().yieldThenswaps to the else block;yieldElsebuilds thescf.ifop.- Both branches must yield arity-matching tuples.
openWhile — scf.while
var w = b.openWhile(.{ i0 }, .{.i32});
{
// before region (condition)
const s = w.before_carried[0];
w.yieldBefore(s.lt(10), .{ s }); // scf.condition: cond + values forwarded to after
}
{
// after region (body)
const s = w.after_carried[0];
w.yieldAfter(.{ s.add(1) }); // values forwarded back to before
}
const r = w.results[0];
inits— a tuple or array ofValues; before-region arg types = their types.after_types— a tuple or array of dtypes (.f32), Values (for their types) or*const mlir.Types; after-region arg types + the scf.while's result types.yieldBefore(cond, forwarded)—forwardedarity must matchafter_types.yieldAfter(values)— arity must matchinits.
returnIf / returnIfOpts — early tt.return via cf.cond_br
// Python: if pid_m * BLOCK >= num_tokens_post_padded: return
const out_of_range = pid_m.mul(block).ge(num_tokens);
b.returnIf(out_of_range);
// ... ops here live in a fresh fall-through block ...
Lowers to:
cf.cond_br %out_of_range, ^ret, ^cont
^ret:
tt.return
^cont:
// subsequent ops
- Kernels return nothing, so neither form takes return values.
- Works only at the top-level
tt.funcbody — don't call inside anscf.if/scf.for/scf.whileregion (those must stay structured; cf branches can't escape their parent scf region). - After
returnIf, the kernel's current block is swapped to a fresh fall-through block — any subsequentb.*calls emit into that block, andb.finish()appends the finaltt.returnthere. - Use this to match Python Triton's
if cond: returnlowering exactly. Python emitscf.cond_brfor early-return idioms while usingscf.for/scf.iffor structured loops and value-carrying branches; our DSL does the same.
returnIfOpts(cond, .{ .inline_return = true }) — match Python's
per-return block layout. By default returnIf routes every return path
(every early returnIf / openReturnIf plus the natural fall-through from
b.finish) through one shared exit block holding the single tt.return.
Python's frontend does the opposite: each if cond: return (and the natural
exit) gets its own tt.return-only block, and LLVM's SimplifyCFG later
merges them into a single common.ret. The two are semantically identical
but differ in the function-exit block's label and position — which renumbers
every $L__BB label downstream and blows up the PTX diff. When the Python source contains any literal return statement (it then
has ≥2 ret blocks in LLVM — the explicit one(s) plus the implicit
function-end one — which SimplifyCFG merges into common.ret), pass
.{ .inline_return = true } on every return site, including each
openReturnIfOpts (see below). Each one
then emits tt.return inline and SimplifyCFG reproduces Python's
common.ret. The default shared exit block emits exactly one tt.return,
so the merge never fires and the function-exit block lands somewhere else.
openReturnIf — early tt.return with side-effects in the taken branch
// Python: if off_experts == -1: write_zeros_to_output(...); return
var scope = b.openReturnIf(is_dead); // or openReturnIfOpts, see `returnIfOpts` above
{
writeZerosToOutput(k, c_ptr, ...); // ops here emit into ^ret
scope.close(); // closes ^ret with tt.return (or cf.br ^exit)
}
// ... ops here emit into ^cont (fall-through) ...
Lowers to the same cf.cond_br ^ret, ^cont shape as returnIf, but the
taken branch can carry arbitrary side-effects between the cf.cond_br and
the tt.return. Use this instead of the
openIf(cond){body}close; returnIf(cond) pair — that pattern
duplicates the predicate (emits both scf.if and cf.cond_br on the same
boolean) and drifts from Triton's reference IR.
openReturnIfOpts(cond, .{ .inline_return = true }) makes close end
^ret with tt.return directly instead of cf.br ^exit. Use it on every
returnIf / openReturnIf of a kernel when matching a Python source that has
literal return statements.
Same restrictions as returnIf: top-level tt.func body only.
When to use cf (returnIf / openReturnIf) vs scf (openIf / openIfElse / openFor)
| Python source | Emits | DSL builder |
|---|---|---|
if cond: return |
cf |
b.returnIf(cond) |
if cond: <side-effects>; return |
cf |
var s = b.openReturnIf(cond); {...; s.close()} |
if cond: <side-effects> |
scf |
b.openIf(cond) {...; close()} |
if cond: x=A else: x=B (value-carrying) |
scf |
b.openIfElse(cond, .{ty}) {...; yieldThen(.{a})} {...; yieldElse(.{b})} |
for i in range(...) |
scf |
b.openFor(lo, hi, step, .{inits}) |
while cond: |
scf |
b.openWhile(.{inits}, .{after_types}) |
Rule of thumb: scf for structured, value-carrying control. cf for
early-exits. Both lower to identical PTX after the
convert-scf-to-cf pass — the difference only matters at the TTIR layer
(pattern-matching passes that run before lowering).
reduce / scan — custom combiners (still callback-based)
b.reduce(ctx, .{ .src, .axis, .elem, .result, .combine = fn (*Builder, Value, Value, Ctx) Value });
b.scan (ctx, .{ .src, .axis, .reverse = false, .elem, .result, .combine });
These stay on the callback pattern because the combine fn is a tiny pure
function ((a, b) -> a ⊕ b) where a ctx struct is a cleaner fit than a
scoped builder. Reach for b.sum / b.max / b.cumsum / etc. first — the
built-in reductions cover the common cases.
General tips
- Scopes stack naturally:
openFor { openIf { openFor { ... } } }all just push/pop the kernel's current-block stack (same foropenIfElse/openWhile). - Scopes without values end with
close():loop.close(),i.close(), andelseBranch()thenclose()for an if/else. - After any
yield*, the scope's.resultsfield holds the scf op's results as a[N]Value.
Escape hatches
Everything the DSL doesn't expose is still reachable — Builder is a
book-keeping layer, not a walled garden:
v.inner— the raw*const mlir.Value; feed it to anyttir.*/arith.*/math.*/scf.*constructor directly.b.ctx— the owning*mlir.Context.b.currentBlock()— the activemlir.Block(respectspushBlock/popBlock).b.emit(op)/b.emitMulti(op, n)— if you've built anmlir.Operationby hand, use these so the result comes back as aValuewith itskernelfield populated (you'll need that for any subsequent fluent calls).
When you drop to raw ops, remember to still append them to the current
block — b.emit(...) does that for you; _ = op.appendTo(b.currentBlock())
is the manual form.
Lower layer — Builder.open
The declarative zml.kernel.triton.Kernel(Config, spec) form covers most
cases. For dynamic-arity arg lists, or escape-hatch scenarios where you want
to drive the IR construction yourself, use the Builder directly:
const Builder = tri.Builder;
pub fn fusedMoeKernel(
allocator: std.mem.Allocator,
ctx: *mlir.Context,
config: GenerationConfig,
) ![:0]const u8 {
var b = try Builder.open(allocator, ctx, "fused_moe_kernel");
defer b.deinit();
const a = try b.declareArgs(.{
.a_ptr = .{ .ptr = config.a_dtype },
.b_ptr = .{ .ptr = config.b_dtype },
// ...
});
// ... emit body via b.* helpers; same DSL as inside `Kernel(...)` ...
return b.finish();
}
Builder.open(allocator, ctx, name)creates an empty builder, andb.declareArgs(spec)creates thett.funcand returns its arguments as the sameNamedArgs(Spec)struct as insideKernel(...)— exactly whatzml.kernel.triton.Kernel(...)does internally.b.declareArgsOpts(spec, .{ .@"noinline" = true })sets the function's options.b.finish()terminates withtt.return, verifies, and serializes to a[:0]const u8owned byallocator.b.deinit()frees the module.
For dynamic-arg-count construction, Builder.init(allocator, ctx, name, args) takes a runtime []const ArgSpec instead of a comptime struct
literal; you grab block args with b.arg(i).
Pass these constructors a zml.kernel.triton.newContext(), not a
Compilation's mlir_ctx; defer ctx.deinit() once you have the IR
string. Kernel.emit does this for you, which is why it takes no context.
Prefer zml.kernel.triton.Kernel(Config, spec) for the common case.
Python Triton ↔ Zig DSL cheat-sheet
| Python | Zig |
|---|---|
tl.program_id(0) |
b.programId(.x) |
tl.num_programs(0) |
b.numPrograms(.x) |
tl.arange(0, N) |
b.arange(0, N, .i32) |
x.to(tl.int64) |
x.to(.i64) |
a + b, a * b, a // b |
a.add(b), a.mul(b), a.div(b) |
a < b |
a.lt(b) |
mask & other |
mask.bitAnd(other) |
tl.where(c, a, b) |
b.where(c, a, b) (alias of b.select) |
vec[:, None] |
vec.expandDims(1) |
vec[None, :] |
vec.expandDims(0) |
m[:, None] & (c[None, :] < N) |
b.mask2d(m, c.lt(N), m_sz, n_sz) |
ptr + offs |
ptr.addPtr(offs) (auto-splats scalar↔tensor either way) |
tl.load(ptr) |
b.load(ptrs) |
tl.load(ptr, mask=m) |
b.loadOpts(ptrs, .{ .mask = m }) |
tl.load(ptr, mask=m, other=o) |
b.loadOpts(ptrs, .{ .mask = m, .other = o }) |
tl.store(ptr, v) |
b.store(ptr, v) |
tl.store(ptr, v, mask=mask) |
b.storeOpts(ptr, v, .{ .mask = mask }) |
tl.zeros((M, N), dtype=tl.float32) |
b.zeros(&.{ M, N }, .f32) |
tl.full((M, N), 3, tl.int32) |
b.full(&.{ M, N }, 3, .i32) |
tl.sum(x) |
b.sum(x) — axis=None default |
tl.sum(x, axis=0) |
b.sumOpts(x, .{ .axis = 0 }) |
tl.sum(x, axis=0, keep_dims=True) |
b.sumOpts(x, .{ .axis = 0, .keep_dims = true }) |
tl.max(x) / tl.min(x) |
b.max(x) / b.min(x) |
tl.max(x, axis=0) |
b.maxOpts(x, .{ .axis = 0 }) |
tl.maximum(a, b) / tl.minimum(a, b) |
a.maximum(b) / a.minimum(b) or b.maximum(a, b) |
tl.cumsum(x) / tl.cumprod(x) |
b.cumsum(x) / b.cumprod(x) |
tl.cumsum(x, axis=0, reverse=True) |
b.cumsumOpts(x, .{ .reverse = true }) |
tl.dot(a, b, acc=acc) |
b.dot(a, b, acc) — defaults to input_precision = tf32 (NVIDIA) |
tl.dot(a, b, acc, input_precision="ieee") |
b.dotOpts(a, b, acc, .{ .input_precision = .ieee }) |
tl.clamp(x, mn, mx) |
b.clampf(x, mn, mx) |
tl.clamp(x, mn, mx, propagate_nan=NAN_ALL) |
b.clampfOpts(x, mn, mx, .{ .propagate_nan = .all }) |
tl.atomic_add(p, v) |
b.atomicRmw(.add, p, v) |
tl.atomic_add(p, v, mask=m, sem="relaxed") |
b.atomicRmwOpts(.add, p, v, .{ .mask = m, .sem = .relaxed }) |
tl.histogram(x, num_bins) |
b.histogram(x, num_bins) |
tl.histogram(x, num_bins, mask=m) |
b.histogramOpts(x, num_bins, .{ .mask = m }) |
tl.reshape(x, shape) |
b.reshape(x, &.{ ...shape }) |
tl.reshape(x, shape, can_reorder=True) |
b.reshapeOpts(x, &.{ ...shape }, .{ .can_reorder = true }) |
tl.cast(x, tl.bfloat16) |
b.cast(x, .bf16) (or fluent x.to(.bf16)) |
tl.cast(x, tl.bf16, fp_downcast_rounding="rtne") |
b.castOpts(x, .bf16, .{ .fp_downcast_rounding = .rtne }) |
tl.cast(x, tl.int32, bitcast=True) |
b.castOpts(x, .i32, .{ .bitcast = true }) |
src[indices] (gather) |
b.gather(src, indices, axis) |
tl.trans(x, dims) / tl.permute(x, dims) |
b.trans(x, order) / b.permute(x, order) |
tl.cat(a, b) |
b.cat(a, b) (dim=0 default) |
tl.cat(a, b, can_reorder=True) |
b.catOpts(a, b, .{ .can_reorder = true }) |
tl.join(a, b) / tl.split(x) |
b.join(a, b) / b.split(x) |
tl.item(x) |
b.item(x) |
tl.abs(x) |
b.abs(x) (auto-dispatch) or fluent x.abs() |
tl.broadcast(a, b) (symmetric) |
b.broadcast(a, b) → .{ Value, Value } |
tl.broadcast_to(v, shape) |
b.broadcastTo(v, &.{ ...shape }) |
tl.umulhi(a, b) |
b.umulhi(a, b) |
tl.sqrt_rn(x) / tl.div_rn(x, y) |
b.sqrtRn(x) / b.divRn(x, y) |
tl.device_print("dbg", args...) |
b.devicePrint("dbg", args, is_signed) |
tl.device_assert(cond, "msg") |
b.deviceAssert(cond, "msg") |
tl.inline_asm_elementwise(...) |
b.inlineAsmElementwise(...) |
tl.extern_elementwise(...) |
b.externElementwise(srcs, shape, dtype, lib, path, sym) |
for i in range(0, N, S): ... |
var loop = b.openFor(0, N, S, .{inits...}); { ...; loop.yield(.{...}); } |
while cond: ... |
var w = b.openWhile(.{inits}, .{after_types}); { ...; w.yieldBefore(cond, .{...}); }; { ...; w.yieldAfter(.{...}); } |
if cond: ... (side-effects, no else) |
var i = b.openIf(cond); { ...; i.close(); } |
if cond: ... else: ... |
var i = b.openIfElse(cond, .{result_types}); { ...; i.yieldThen(.{...}); }; { ...; i.yieldElse(.{...}); } |
if cond: return (early exit) |
b.returnIf(cond); — emits cf.cond_br + tt.return, continues in fall-through block (b.returnIfOpts(cond, .{ .inline_return = true }) when matching a Python source that has literal returns) |
if cond: <stores>; return (early exit, with side-effects) |
var s = b.openReturnIf(cond); { ...; s.close(); } — single cf.cond_br; body emits into ^ret before the tt.return (b.openReturnIfOpts(cond, .{ .inline_return = true }) to match, alongside returnIfOpts) |
Pitfalls
-
Mixed integer widths widen.
v_i32.mul(v_i64)is an i64 multiply with anarith.extsion the i32 side, and so isv_i32.mul(x)for a runtime Zigi64x. Narrow with@as(i32, @intCast(x))or.to(.i32)when the result must stay i32. Comptime literals take the other operand's type instead. -
Tensor-of-pointers via
.addPtr. Auto-splats either side: scalar!tt.ptr<T>+ tensor offset (x_ptr.addPtr(tensor_offs)) and tensortensor<...x!tt.ptr<T>>+ scalar offset (a_ptrs.addPtr(BLOCK_K)) both work without manual.splatTo. -
Scope-based control flow — no closures needed.
openFor/openIf/openIfElse/openWhilepush a block onto the kernel's insertion stack; body ops emitted in the bare{}that follows go into that block. Captures are plain lexical scope, so you can reference outer Values, sizes, etc. directly — noctxstruct, no function literal. -
Value.kernel == nullpanics fluent calls. Only happens if you build aValueby hand via.{ .inner = raw }. Route throughb.emit(...)to keep the back-pointer populated — or just stick with the explicitBuilder.*helpers for that one op. -
Don't worry about duplicate constants. Every lifted literal (from
.add(42),.lt(0),b.splat(1.0, shape), anopenFor(0, N, 1, …)bound, etc.) emits a fresharith.constant. This matches Python Triton's own frontend — the MLIR canonicalizer + CSE pass collapses duplicates on the way to PTX, so the generated code is identical whether you emit one constant or a hundred. Optimize for readability at the builder level. -
finish()verifies before serializing. A verifier failure here almost always means an operand-type mismatch or a missing block terminator — a common one is forgetting thatscf.yieldoperand types must match the loop's result types. -
Yielding from loop / if / while bodies. Inside a scope (
openFor,openIf,openIfElse,openWhile), you don't return values — you callscope.yield(...)(oryieldThen/yieldElse/yieldBefore/yieldAfter) with a tuple of Values matching the scope's declared arity. Scopes with results (openFor,openIfElse,openWhile) store the scf op's results inscope.resultsas a fixed-size[N]Valuearray.openIfhas no results —close()closes and builds scf.if with an empty else block in one step.