PickleIR
The typed, block-structured IR the backend consumes, with real output.
Compilation lowers a checked module to PickleIR, and the backend lowers that to machine code. PickleIR is deliberately small: it is a flat list of functions, each a list of basic blocks, each block a list of instructions and exactly one terminator.
A worked example
Given this module:
fn add(a: int, b: int) -> int {
return a + b
}
fn main() {
println(add(2, 3))
}
pickle ir prints:
fn add(a: int64, b: int64) -> int64 @pkl_add
@entry:
t0 = load slot s0
t1 = load slot s1
t2 = binop.add t0, t1
return t2
@1:
unreachable
main fn main() -> unit @pickle_main
@entry:
t0 = const 2
t1 = const 3
t2 = call fn#0(t0, t1)
call extern#0(t2)
call extern#1()
t3 = const 0
return
Things worth reading off that output:
- Types are lowered.
intis alreadyint64at this point, andmainis-> unit. - Symbols are mangled.
addbecomes@pkl_add; the backend needs a collision-free symbol, not a source name. - Parameters arrive in slots.
s0ands1are the incoming arguments, andload slotreads them. - Values are SSA-style temporaries. Every result is a fresh
tN. There is no reassignment of a temporary. - Blocks are explicit and unstructured.
@entryis the entry block and@1is a numbered block, with nolooporwhileconcept. Control flow isunreachableat the end of a block that always returns. - Calls name their callee.
call fn#0is a module function;call extern#Nis a runtime symbol.printlnis two externs here, one per argument it formats.
The type set is seven types wide
This is the single most important fact about PickleIR:
enum IrTy {
Bool
Char
Int
Float
Str
Unit
Ptr
}
There is no List, no Map, no class, no struct, no tuple and no option type
in the IR. Every aggregate is a Ptr. That is the mechanical reason lists,
maps, class instances and structs have reference semantics and identity ==
in the language above, by the time a value reaches the backend, "list" and
"map" and "class instance" are all just an address.
Temporaries, slots and blocks
Values are referred to by plain integer index rather than by a typed handle:
| Reference | What it identifies |
|---|---|
| A temporary index | An SSA value inside a function |
| A slot index | A parameter or local that outlives a single expression |
| A block index | A label, with @entry and @N naming them in the text form |
An index into IrModule.strings |
An interned string |
An index into IrModule.funcs |
A function in the module |
An index into IrModule.externs |
A runtime symbol |
Constants
enum IrConst {
Int(v: int)
Float(v: float)
Bool(b: bool)
Char(c: char)
Null
Str(id: int)
}
Str holds an index into the module's string table, so the same literal
lowered twice refers to one entry. Null is the only non-value constant and
stands for the absence of a value.
Instructions and terminators
The whole instruction set:
Const UnOp BinOp Copy Itof Ftoi Chartoi Itochar
LoadSlot StoreSlot LocalAddr LoadRaw StoreRaw Call CallInd
and the whole terminator set:
Branch BranchIf Return Unreachable
UnOp is Neg, Not, BitNot. BinOp is Add, Sub, Mul, Div,
Mod, Shl, Shr, BitAnd, BitOr, BitXor, Eq, Ne, Lt, Le,
Gt, Ge, so every comparison in the language is one instruction, and there
is no separate compare-and-branch.
The Raw and LocalAddr instructions are the unsafe surface: they are how
&x, *p and a store through a pointer reach the backend.
Call names a Callee, which is either Func(id: int) into the module's
function table or Extern(id: int) into its extern table. CallInd is the
indirect form, used when the callee is a function value.
IRX: the lossless form
pickle irx writes the same IR as text with nothing thrown away, including
the full extern and string tables and per-function slots, tags and entry
point. Names are hex-encoded so the format is byte-exact:
irx externs 2
extern 0 7069636b6c655f7072696e745f693634
esig int64 unit
extern 1 7069636b6c655f7072696e745f6e65776c696e65
esig unit
irx strings 0
irx funcs 2
func 0 616464 706b6c5f616464 0 0 0 int64
params 2 61 int64 62 int64
slots 2 int64 int64
tags 0
blocks 2
block 0
load 0 0
load 1 1
binop 2 add 0 1
return 2
block 1
unreachable
7069636b6c655f7072696e745f693634 is pickle_print_i64 and
7069636b6c655f7072696e745f6e65776c696e65 is pickle_print_newline, which
is where the two extern calls in the ir output above come from.
pickle irx-run parses an IRX file back into a module and runs its main
with the JIT. The round trip is exact, it re-parses into the same module,
which is what makes IRX a stable, diffable contract you can check in CI.
