MIR — Manticore's mid-level IR

Status: shipped. Overview of the mid-level IR and the pass pipeline.

MIR is the typed, tree-shaped IR between the AST and LLVM. Every analysis, transform, and lowering step operates on it. This doc is the map: data structures, the type lattice, the node taxonomy, the pass pipeline, and the memory-management contract that turns escape analysis into concrete retain/release/free/arena ops.

PHP → Lexer → Parser → AST → LowerFromAst → MIR → …passes… → EmitLlvm → LLVM IR → clang → binary

Source lives under src/Compile/Mir/. Codegen (EmitLlvm*) consumes MIR but is not part of it.

1. Shape and philosophy#

• Tree, not basic blocks. MIR keeps PHP's structured control flow as nodes (If_, While_, For_, Foreach_, Switch_, Match_, TryCatch_). There is no CFG / phi layer — "SSA-ish" means each transform rewrites the tree in place. LLVM's own SSA construction happens in EmitLlvm.
• Flat node shape. Node is a kind discriminant plus per-subclass payload (see §4). Deep subclass hierarchies are avoided on purpose: the self-host front-end pre-scans nodes by narrowing on kind, and a deep tree would push the compiled compiler past current limits. Type follows the same flat-kind rule (§3).
• Mirrors the AST. MIR node layout deliberately echoes Parser\Ast\Expr so a self-host walker can traverse both with the same idioms.
• Every node carries a Type. Lowering seeds Type::unknown(); passes refine toward a concrete shape. Later passes read the type as a precondition.
• Mutable children, readonly leaves. Child node refs (->left, ->value, …) are not readonly — transform passes rewrite the tree. Leaf payloads (literal values, op strings, function names) stay readonly; a rewrite replaces the whole node rather than mutating a payload. Standard HHIR / Cranelift / LLVM discipline.

2. Top-level structures#

Module global cells (globalNames/globalDefaults, globalVarNames) back static props, static $x locals, and global $x — stored as parallel arrays, not a map of objects, because the self-host backend mishandles that.

passesApplied (markPassApplied / hasPassApplied) lets passes assert preconditions and powers dump-mir --after=<pass>.

3. Type lattice (Type.php)#

HHIR-inspired: scalar primitives, one unified array kind, object-by-class, a tagged-union cell, and a static object union.

Merges. unionWith() joins types at control-flow merges: same kind → refined join, else unknown. Object arms lift to a static union. Arrays join element- and key-wise so a loop back-edge that appends a typed value does not reset vec[string] to vec[unknown]; a null key (vec) joined with a string key lifts to the string key. Never collapse two known types to unknown when a refinement exists — that's a load-bearing principle.

toString() renders vec[…] / assoc[k, v] / obj<C> / cell{a|b} / a|b — golden-stable, used by dump-mir.

4. Node taxonomy (Node.php + Nodes.php)#

kind constants live on Node; concrete subclasses in Nodes.php, grouped:

• Constants — IntConst, FloatConst, StringConst, BoolConst, NullConst.
• Locals — LoadLocal, StoreLocal; RefAlias_ ($y = &$x), RefBind_ (&fn()).
• Arithmetic / unary — Add,Sub,Mul,Div,Mod,Neg,Not_,BitOp (shl/shr/and/or/xor),BitNot_,Concat. Binary nodes keep left/right in the same slot order so a base-Node read in Walk lands identically across them.
• Compare / misc expr — Cmp, Ternary, Cast, Instanceof_, NullCoalesce_, IncDec, ClassName_, Isset_, Unset_.
• Statements — Echo_, Return_, Call, Block, Throw_, Yield_.
• Control flow — If_, While_, For_, DoWhile_, Foreach_, Switch_(+SwitchArm_), Match_(+MatchArm_), Break_, Continue_, TryCatch_(+MirCatch).
• Containers — ArrayLit(+ArrayElement_), ArrayAccess_, StoreElement, Spread_.
• Objects — NewObj, Clone_(+CloneWith, 8.5 clone-with), PropertyAccess_, StoreProperty, DynProp_/StoreDynProp_, MethodCall_, StaticCall_ (carries staticClass for late-static-binding), Closure_/Invoke_.
• Statics / globals — StaticProp_, StoreStaticProp_, StaticLocalDecl_.
• Memory — MemoryOp_ (§6), inserted by InsertMemoryOps.

Notable payloads worth knowing:

• Call.function is non-readonly — Monomorphize repoints it to a specialized copy (f$mono$p0_vec_int) in place.
• Foreach_ carries iterClass / iterAggregate (object-iterator dispatch, set by InferTypes) and genSlotBase (frame slot when inside a generator, so iterator state survives a yield).
• TryCatch_ carries generator frame-slot indices (genDepthSlot, genOuterSlot, genPendSlot) so depth/finally state survives suspension.
• Closure_ captures are index-parallel with captureByRef (by-value packs the value; by-ref packs the slot address).

Walk.php = generic child traversal / rewrite helpers; NodeClone.php = deep copy (used by Monomorphize and inlining); Dump.php = the dump-mir printer.

5. Pass pipeline#

Every pass implements Pass (Pass.php): name(), requires() (declared dependency pass names), run(Module): Module. Each stamps markPassApplied. requires() is declarative; the actual valid order is the fixed chain in lower_module() (src/Manticore/Main.php; compile_via_mir then runs EmitLlvm, and CompileCommand drives both). Run order:

Then EmitLlvm (not a Pass) emits LLVM IR.

6. Memory-management contract#

The reason MIR carries effect/alloc metadata: EmitLlvm must consume explicit memory ops, never invent retain/release from ad-hoc feature handlers. Four staged steps drive it.

Step 3 — Effects (Effects.php, filled by InferEffects). Per-node memory effect set, unioned into the function aggregate: alloc (fresh heap value), escape (outlives the frame — return/throw/store- to-heap), throw (may unwind), callUnknown (opaque callee), storeHeap (writes into a heap slot). retain/release stay false here — they're vocabulary reserved for step 5.

Step 4 — AllocationKind (AllocationKind.php, decided by InferAllocKind). Where an allocating value lives / how it's reclaimed:

• RcHeap — escapes → reference-counted heap.
• NoRefcount — proven frame-confined → freed at scope exit, no RC.
• Arena — bump-alloc, bulk-freed at arena scope end (see arena-arrays work).
• Borrowed — owned elsewhere (alias of a param/caller value).
• Static — global/constant lifetime, never freed.

Soundness rule: default to RcHeap; downgrade to NoRefcount/Arena only when non-escape is proven. Over-marking RcHeap is merely slower; under-marking is a use-after-free once step 5 acts on it.

Step 5a — MemoryMode (MemoryMode.php, applied by ApplyMemoryMode). --memory=<rc|arena|hybrid> maps the verdict to a strategy. Default is hybrid: confined → Arena, escaping → RcHeap. rc: confined → NoRefcount, escaping → RcHeap. arena: everything → Arena (escaping needs a runtime bypass guard to stay UAF-safe).

Step 5b — MemoryOps (MemoryOp_, inserted by InsertMemoryOps). Concrete ops EmitLlvm lowers: op ∈ retain/release/cow/root/arena_enter/arena_leave; flavor ∈ string/vec/assoc/obj/cell (the heap family the runtime helper dispatches on); target = the acted-on value (or null for whole-frame arena enter/leave).

Arena arrays: the flat-scalar non-escaping array arena path is a live feature (default on, MANTICORE_ARENA_ARRAYS). See memory.md.

7. Inspecting MIR#

bin/manticore dump-mir prog.php            # MIR after the full pipeline
bin/manticore dump-mir prog.php --prelude  # include the Throwable hierarchy
bin/manticore dump-mir prog.php --effects  # annotate each op with inferred effects
bin/manticore dump-ast prog.php            # the AST it lowered from
bin/manticore dump-llvm-mir prog.php       # MIR pipeline + EmitLlvm → LLVM IR
bin/manticore dump-sig prog.php            # the exported symbol table
bin/manticore analyze prog.php             # static diagnostics, no codegen

The printer is Dump.php; type rendering is Type::toString().

⚠ dump-mir --after=<pass> is not implemented — dump-mir always prints the state after the full pipeline. Landing it is a roadmap item.

⚠ The dump-* commands do not link the stdlib, so a call into it resolves as unknown. When that matters, read the final binary.

8. Reference files#

Related design docs: type-system-v2.md, monomorphization.md, generators-and-pointers.md, ../memory.md.

Edit this page on GitHub