IRGen: the scalar subset¶
Status: implemented in M4 (#5).
piac --emit=mlir file.pia lowers a program to the pia and pia_contract dialects (ADR 0018), with control flow in upstream scf and functions in func. This page describes the subset it accepts and how each construct lowers. Anything outside the subset is reported as "not supported yet" at its source location.
The pipeline¶
- Parse (
src/syntax) to the uniform syntax tree. - Expand metaprograms (
src/meta, meta.md). Binary operators become calls of core builtins,@deriveruns, and thelet metaitems are removed. - Sema (
src/sema) resolves written types and collects the signature of every top-levellet, so a function can be called before its definition. It reports items outside the subset (types, modules, metaprograms) before any code is generated. - IRGen (
src/irgen) type checks expressions as it lowers them. A separate typed AST comes when the language outgrows the scalar subset. - The module is run through the MLIR verifier.
Types¶
| Pia | IR |
|---|---|
u8 u16 u32 u64, i8 ... i64 |
!pia.int<lo, hi> with the machine range |
usize, isize |
the 64-bit ranges, printed as the aliases !usize and !isize |
int{lo..hi} |
!pia.int<lo, hi> (bounds are integer literals for now) |
bool |
i1 |
[T; n] |
!pia.array<n x T> (n is a literal for now) |
[T] |
!pia.slice<T> |
unit |
no value; a function returning unit has no results |
let pixel = type { r : u8; ... } |
!pia.record<"pixel", r : !pia.int<0, 255>, ...>, printed as !pixel |
Types are structural: u64 and usize are the same type. int{0..255} is u8. Records are the exception: they are named, so two record types with the same fields are different types. let byte = type u8 is another name for u8.
Integers¶
- Literals take the type the context expects. With no context they are
i32, ori64oru64if the value does not fit. A suffix (42u8) fixes the type. A literal that does not fit its type is an error. - Binary operators arrive from expansion as calls of core builtins (
a + bisadd a b, meta.md). IRGen lowers a builtin call as the operator it stands for. They compute at the join of the operand types, the smallest range holding both. When the context expects a wider integer, they compute at that type, sodst.[i] <- src.[i] * 3withu8source andu16destination multiplies atu16. The other operand is widened withpia.convert. A literal takes the other operand's type, whichever side it is on. - Conversions: wherever a value meets a declared type (a parameter, a return type, an annotated
let, an assignment, an element store), IRGen insertspia.convert. Widening always holds. Narrowing is a proof obligation for the verifier (M5). - Overflow:
+ - * / %lower topia.add,sub,mul,div,remwith the function's overflow mode. The default isproof.@overflow(wrap | saturate | trap)on the return annotation sets another mode, and+|-|always saturate.modis%. - Negation
-xis0 - xat x's type, so it is an obligation for unsigned and minimum values.-5is a literal. - Comparisons lower to
pia.cmpat the joined type.=and<>on bools lower toarith.cmpi.
Bindings and mutation¶
let x = e in bodybinds an SSA value. An annotation convertseto the declared type.- There is no shadowing (ADR 0022). A
let, parameter, loop variable or quantifier binder may not reuse the name of a local in scope, a function, a type or a core builtin. Assigning to a mutable local is not shadowing. The error suggests a primed name instead:x', orx''if that is taken. A prime is an ordinary identifier character, solet x' = x + 1 in ...names a value related tox. let x : mutable T = e in ...makesxassignable. There is no memory: eachx <- vrebinds the SSA value, and structured control flow threads it through. A mutable local assigned insideifbecomes an extrascf.ifresult, and one assigned inside a loop becomes a loop-carried value (iter_argsforfor,scf.whileoperands).- Parameters are mutable only with
mutable. Their modifiers are kept as thepia.modifiersargument attribute. xs.[i]lowers topia.loadandxs.[i] <- vtopia.store. Writing requires the parameter to beoutorinout. Indices go throughpia.to_index.len xsispia.lenfollowed bypia.from_indextousize.
Control flow¶
if c then a else blowers toscf.ifwith the joined result type. Anifwithoutelsemust have type unit.&&,||and==>in code short-circuit, so they lower toscf.if. This keepsi < len xs && xs.[i] <> xfrom loading out of bounds.for i in lo..hi step s do ... donelowers toscf.foroverindex. The bounds are joined to one type, andiis bound withpia.from_indexat that type. The range is half-open. Two literal bounds areusize.while c do ... donelowers toscf.while. The condition is computed in thebeforeregion.a; bevaluatesafor its effects.
Contracts¶
| Pia | IR |
|---|---|
requires p |
pia_contract.requires at function entry |
ensures p |
pia_contract.ensures before the return, with result bound to the return value |
decreases m on a function |
pia_contract.decreases at entry |
invariant p, decreases m on a loop |
at the head of each iteration: the start of the for body, or the before region of scf.while |
assert p, assume p |
pia_contract.assert, pia_contract.assume |
old e |
pia_contract.old |
forall (i in lo..hi). p |
pia_contract.forall whose block argument is i, yielding (lo <= i && i < hi) ==> p |
exists (i in lo..hi). p |
pia_contract.exists, yielding lo <= i && i < hi && p |
forall (k : u8). p |
quantifies over the whole type, with no guard |
Several binders nest one quantifier op per name, so a later range can mention an earlier name. Inside contracts, which have no effects, &&, || and ==> are plain arith logic, and ==> is (a xor true) or b. Whether arithmetic in contracts is exact or follows the overflow mode is settled with the verifier in M5. Quantifiers are rejected outside contracts and assertions.
Records¶
A let name = type { field : T; ... } item defines a record type. Records are values, like integers.
- Literals.
{ r = v; g = 0; b = 0; a = 255 }lowers topia.record, with the fields in declaration order, whatever order they are written in. Its type comes from the context. Failing that, it is the one record type whose fields are exactly these. Every field must be given, once. - Field reads.
p.rlowers topia.field %p, "r". - Field assignment.
q.r <- von a mutable local record rebuildsqwith one field replaced. So, like any mutable local,qis an SSA value threaded throughscf.ifand loops. - Equality.
p = qon records callseq_<name>, which@derive(eq)makes (meta.md).<>negates it. - Not yet supported: arrays and slices of records, buffers inside records, and attributes on type items other than
@derive.
The verifier and code generation do not see records. transforms::scalarizeRecords replaces each record value with its fields first, using MLIR's 1:N dialect conversion. A pixel parameter becomes four parameters named p.r, p.g, p.b and p.a, a pixel result becomes four results, and pia.record and pia.field disappear. old p becomes old of each field.
Functions¶
Each top-level let f (x : T) ... : R = body becomes func.func @f. Parameters need annotations. A let with no parameters becomes a function with no arguments, and its uses call it. The return type may be left out, and then it comes from the body. Such a function cannot be called before its definition, or recursively. Calls must pass every argument, since partial application and functions as values come later.
Not yet¶
Local functions and lambdas, match, variants, dyn, floats, spread and tiles (M8), slicing xs.[a .. b], type-level lengths ([T; n]), refinements (where), modules, and concepts and generic types.