import { ValType, ValTypeRef, ValTypeRefNull, valTypeToOpcode, } from '../wasm.zena'; import { IrBody, IrBlock, IrOp, IrRef, isIrTerminator } from './ir.zena'; import { simdInstruction } from '../../simd.zena'; import { TemplateRecorder } from './template.zena'; import { growable } from 'zena:core'; /** * Compares ref targets by OBJECT IDENTITY, not type-section index: * indices are all -1 until layout() runs, so index equality spuriously * merges distinct types in bodies built pre-layout (the generator * split pass builds bodies there). Identity is equivalent to index * equality for laid-out types — see valTypeKeyEquals in * wasm-module.zena for the same reasoning. */ export function valTypesStrictlyEqual(a: ValType, b: ValType): boolean { return match (a) { case ValTypeRef as ta: match (b) { case ValTypeRef as tb: ta.target === tb.target case _: false } case ValTypeRefNull as ta: match (b) { case ValTypeRefNull as tb: ta.target === tb.target case _: false } case _: valTypeToOpcode(a) == valTypeToOpcode(b) }; } /** * ZIR construction API. * * The builder owns an IrBody under construction. Blocks are created with * newBlock(); instructions append to the current block (switchTo) until a * terminator is emitted, which closes the block. Types and refs are interned * into the body's tables. * * The builder enforces only local well-formedness (no emission into a * terminated or unselected block); global SSA invariants (dominance, branch * arity) are the verifier's job. */ export final class IrBuilder { body = new IrBody(); var #current: i32 = -1; /** * Template mode (template.zena): every `internType` call appends a * type-table entry instead of interning, so two lowerings of one * method name their types by call order and their tables line up * entry for entry; the recorder collects lowering's guards. Null * otherwise. */ var recorder: TemplateRecorder | null = null; /** * The result types of the function, while its returns are redirected * to one block (`redirectReturns`); null otherwise. */ var #redirectedReturnTypes: GrowableArray | null = null; /** The block redirected returns go to, or -1 until one is emitted. */ var #redirectedReturnBlock: i32 = -1; /** Total blocks created so far. */ numBlocks(): i32 { return this.body.blocks.length; } /** * Allocate a fresh block. It is not current until switchTo(b) is called. */ newBlock(): i32 { let idx = this.body.blocks.length; this.body.blocks.push(new IrBlock()); return idx; } /** * Select `block` as the insertion target for subsequent emissions. Fails if * `block` has already received a terminator instruction. */ switchTo(block: i32): void { if (block < 0 || block >= this.body.blocks.length) { throw new Error('switchTo: no such block'); } if (this.#isTerminated(block)) { throw new Error('switchTo: block already terminated'); } this.#current = block; } /** Current insertion target (-1 before first switchTo). */ currentBlock(): i32 { return this.#current; } /** * Adds a parameter to a block. Parameters may be added until the block * gains its terminator (on-demand params are how loop-carried values * appear during lowering). */ blockParam(block: i32, type: ValType): i32 { if (this.#isTerminated(block)) { throw new Error('blockParam: block already terminated'); } let blk = this.body.blocks[block]; let inst = this.#newInst(IrOp.param, this.internType(type), blk.params.length, -1, block); blk.params.push(inst); return inst; } internType(type: ValType): i32 { let table = this.body.typeTable; if (this.recorder != null) { table.push(type); return table.length - 1; } var i = 0; while (i < table.length) { if (valTypesStrictlyEqual(table[i], type)) { return i; } i += 1; } table.push(type); return table.length - 1; } addRef(ref: IrRef): i32 { this.body.refTable.push(ref); return this.body.refTable.length - 1; } // -- Mutable variables (ir.md §5.1) ---------------------------------- /** Allocates a fresh mutable variable of type `vt`; returns its id. */ newVar(vt: ValType): i32 { this.body.varTypes.push(vt); return this.body.varTypes.length - 1; } /** Reads a mutable variable at its declared type. */ varGet(varId: i32): i32 { return this.#emitInCurrent(IrOp.var_get, this.internType(this.body.varTypes[varId]), -1, varId); } /** Writes `value` into a mutable variable. */ varSet(varId: i32, value: i32): void { this.#emitInCurrent(IrOp.var_set, -1, value, varId); } // -- Low-level emission ---------------------------------------------- /** Emits a value-producing instruction with inline operands. */ emit(op: IrOp, type: ValType, a: i32, b: i32): i32 { return this.#emitInCurrent(op, this.internType(type), a, b); } /** Emits a void instruction with inline operands. */ emitVoid(op: IrOp, a: i32, b: i32): i32 { return this.#emitInCurrent(op, -1, a, b); } /** Copies `values` into the extra pool, returning the start index. */ pushExtra(values: GrowableArray): i32 { let start = this.body.extra.length; for (let v in values) { this.body.extra.push(v); } return start; } /** Copies [argc, args...] into the extra pool. */ pushArgList(args: GrowableArray): i32 { let start = this.body.extra.length; this.body.extra.push(args.length); for (let v in args) { this.body.extra.push(v); } return start; } // -- Typed helpers ------------------------------------------------------ constI32(value: i32, type: ValType): i32 { return this.emit(IrOp.const_i32, type, value, -1); } constI64(value: i64, type: ValType): i32 { this.body.constI64.push(value); return this.emit(IrOp.const_i64, type, this.body.constI64.length - 1, -1); } constF64(value: f64, type: ValType): i32 { this.body.constF64.push(value); return this.emit(IrOp.const_f64, type, this.body.constF64.length - 1, -1); } /** f32 constants share the f64 pool (f32→f64 widening is exact). */ constF32(value: f64, type: ValType): i32 { this.body.constF64.push(value); return this.emit(IrOp.const_f32, type, this.body.constF64.length - 1, -1); } /** * The all-zero vector. Wasm has no `v128` counterpart to `i32.const` * — the only vector constant is the 16-byte `v128.const` — so a zero * `v128` is an instruction with a sixteen-byte immediate rather than * a pooled literal. */ constV128Zero(type: ValType): i32 { let instr = simdInstruction('v128.const'); if (instr == null) { throw new Error('v128.const is missing from the SIMD table'); } let imm = growable([instr.opcode]); var i = 0; while (i < 16) { imm.push(0); i += 1; } return this.emit(IrOp.simd_const, type, -1, this.pushExtra(imm)); } binary(op: IrOp, type: ValType, x: i32, y: i32): i32 { return this.emit(op, type, x, y); } callFunc(funcRef: i32, args: GrowableArray, resultType: ValType | null): i32 { let argsIdx = this.pushArgList(args); if (resultType == null) { return this.#emitInCurrent(IrOp.call, -1, argsIdx, funcRef); } return this.#emitInCurrent(IrOp.call, this.internType(resultType), argsIdx, funcRef); } /** * Multi-result call: the call itself produces no single value; one * mv_get projection per result is emitted immediately after it, in * ascending result order (emission relies on that adjacency+order). */ callFuncMulti(funcRef: i32, args: GrowableArray, resultTypes: GrowableArray): GrowableArray { let argsIdx = this.pushArgList(args); let call = this.#emitInCurrent(IrOp.call, -1, argsIdx, funcRef); let projections = new Array(resultTypes.length); for (var k = 0; k < resultTypes.length; k += 1) { projections.push(this.#emitInCurrent(IrOp.mv_get, this.internType(resultTypes[k]), call, k)); } return projections; } /** * A wide-arithmetic instruction: two i64 results, low half first, * read through mv_get projections under the same contract as a * multi-result call (emitted immediately after, ascending order). * `operands` is the pair for the multiplies and the * [lhsLo, lhsHi, rhsLo, rhsHi] quadruple for add128/sub128. */ wideArith(op: IrOp, operands: GrowableArray, resultType: ValType): GrowableArray { let producer = if (operands.length == 2) { this.#emitInCurrent(op, -1, operands[0], operands[1]) } else { this.#emitInCurrent(op, -1, this.pushExtra(operands), -1) }; let projections = new Array(2); for (var k = 0; k < 2; k += 1) { projections.push(this.#emitInCurrent(IrOp.mv_get, this.internType(resultType), producer, k)); } return projections; } /** Multi-value return. */ retMulti(values: GrowableArray): void { if (this.#redirectedReturnTypes != null) { this.br(this.#returnTarget(), values); return; } let idx = this.body.extra.length; this.body.extra.push(values.length); for (let v in values) { this.body.extra.push(v); } this.#emitInCurrent(IrOp.ret_multi, -1, idx, -1); } /** array.new_data: bytes [offset, offset+length) of data segment * `dataIndex` as a fresh array of the given (byte) array type. */ arrayNewData(offset: i32, length: i32, dataIndex: i32, typeRef: i32, resultType: ValType): i32 { let idx = this.body.extra.length; this.body.extra.push(offset); this.body.extra.push(length); this.body.extra.push(dataIndex); return this.#emitInCurrent(IrOp.array_new_data, this.internType(resultType), idx, typeRef); } /** Multi-result call_ref; same projection contract as callFuncMulti. */ callRefMulti(callee: i32, args: GrowableArray, resultTypes: GrowableArray): GrowableArray { let start = this.body.extra.length; this.body.extra.push(callee); this.body.extra.push(args.length); for (let v in args) { this.body.extra.push(v); } let call = this.#emitInCurrent(IrOp.call_ref, -1, start, -1); let projections = new Array(resultTypes.length); for (var k = 0; k < resultTypes.length; k += 1) { projections.push(this.#emitInCurrent(IrOp.mv_get, this.internType(resultTypes[k]), call, k)); } return projections; } /** call_ref through a funcref value: extra = [callee, argc, arg*]. */ callRef(callee: i32, args: GrowableArray, resultType: ValType | null): i32 { let start = this.body.extra.length; this.body.extra.push(callee); this.body.extra.push(args.length); for (let v in args) { this.body.extra.push(v); } if (resultType == null) { return this.#emitInCurrent(IrOp.call_ref, -1, start, -1); } return this.#emitInCurrent(IrOp.call_ref, this.internType(resultType), start, -1); } // -- Terminators --------------------------------------------------------- br(target: i32, args: GrowableArray): void { let idx = this.body.extra.length; this.body.extra.push(target); this.body.extra.push(args.length); for (let v in args) { this.body.extra.push(v); } this.#emitInCurrent(IrOp.br, -1, idx, -1); } brIf(cond: i32, thenTarget: i32, thenArgs: GrowableArray, elseTarget: i32, elseArgs: GrowableArray): void { let idx = this.body.extra.length; this.body.extra.push(thenTarget); this.body.extra.push(thenArgs.length); for (let v in thenArgs) { this.body.extra.push(v); } this.body.extra.push(elseTarget); this.body.extra.push(elseArgs.length); for (let v in elseArgs) { this.body.extra.push(v); } this.#emitInCurrent(IrOp.br_if, -1, cond, idx); } /** try_br: a = tag ref, b = [bodyTarget, argc, arg*, catchTarget, * argc, arg*]. Terminator; both edges carry block arguments. * Returns the instruction id so lowering can record the region's * join in `body.tryJoin` once it exists. */ tryBr(tagRef: i32, bodyTarget: i32, bodyArgs: GrowableArray, catchTarget: i32, catchArgs: GrowableArray): i32 { let idx = this.body.extra.length; this.body.extra.push(bodyTarget); this.body.extra.push(bodyArgs.length); for (let v in bodyArgs) { this.body.extra.push(v); } this.body.extra.push(catchTarget); this.body.extra.push(catchArgs.length); for (let v in catchArgs) { this.body.extra.push(v); } return this.#emitInCurrent(IrOp.try_br, -1, tagRef, idx); } ret(value: i32): i32 { if (this.#redirectedReturnTypes != null) { this.br(this.#returnTarget(), growable([value])); return -1; } return this.#emitInCurrent(IrOp.ret, -1, value, -1); } /** * From here on, a return branches to one block that takes the * returned values as its parameters, of the function's result * `types`. A function with postconditions checks them there and then * returns (docs/design/contracts.md). The block is made by the first * return to reach it, so a function that never returns has none. */ redirectReturns(types: GrowableArray): void { this.#redirectedReturnTypes = types; this.#redirectedReturnBlock = -1; } /** * Stops redirecting returns. Answers the block they went to, or -1 * when none was emitted. */ endReturnRedirect(): i32 { this.#redirectedReturnTypes = null; return this.#redirectedReturnBlock; } #returnTarget(): i32 { if (this.#redirectedReturnBlock < 0) { let block = this.newBlock(); for (let type in this.#redirectedReturnTypes as GrowableArray) { this.blockParam(block, type); } this.#redirectedReturnBlock = block; } return this.#redirectedReturnBlock; } /** * `ret_call`: a tail call to a known function, encoded exactly as * `call` but terminating the block and producing no value — the * callee's results are this function's results * (docs/design/tail-calls.md). The caller owes the wasm rule that * the callee's results are subtypes of this function's. */ retCall(funcRef: i32, args: GrowableArray): void { let argsIdx = this.pushArgList(args); this.#emitInCurrent(IrOp.ret_call, -1, argsIdx, funcRef); } /** `ret_call_ref`: the same, through a funcref. Encoded exactly as * `call_ref` — [callee, argc, arg*] — and terminating. */ retCallRef(callee: i32, args: GrowableArray): void { let start = this.body.extra.length; this.body.extra.push(callee); this.body.extra.push(args.length); for (let v in args) { this.body.extra.push(v); } this.#emitInCurrent(IrOp.ret_call_ref, -1, start, -1); } /** yield_: a = yielded value, b = [resumeTarget, argc, arg*]. * Suspension terminator for presplit generator bodies; the split * pass rewrites every yield before emission. */ yieldTo(value: i32, resumeTarget: i32, args: GrowableArray): void { let idx = this.body.extra.length; this.body.extra.push(resumeTarget); this.body.extra.push(args.length); for (let v in args) { this.body.extra.push(v); } this.#emitInCurrent(IrOp.yield_, -1, value, idx); } /** await_: a = awaited future, b = [resumeTarget, argc, arg*]. * Suspension terminator for presplit async bodies; the split pass * rewrites every await before emission. */ awaitTo(future: i32, resumeTarget: i32, args: GrowableArray): i32 { let idx = this.body.extra.length; this.body.extra.push(resumeTarget); this.body.extra.push(args.length); for (let v in args) { this.body.extra.push(v); } return this.#emitInCurrent(IrOp.await_, -1, future, idx); } retVoid(): void { if (this.#redirectedReturnTypes != null) { this.br(this.#returnTarget(), new Array(0)); return; } this.#emitInCurrent(IrOp.ret, -1, -1, -1); } unreachable(): void { this.#emitInCurrent(IrOp.unreachable, -1, -1, -1); } /** throw: extra = [argc, arg*], b = tag ref. Terminator. */ throwWithTag(args: GrowableArray, tagRef: i32): void { let idx = this.body.extra.length; this.body.extra.push(args.length); for (let v in args) { this.body.extra.push(v); } this.#emitInCurrent(IrOp.throw, -1, idx, tagRef); } /** * Finishes construction and returns the body. Structural validity * (all blocks terminated, SSA invariants) is checked by the verifier, * not here, so tests can construct deliberately broken bodies. */ finish(): IrBody { this.#current = -1; return this.body; } // -- Internals ------------------------------------------------------ #isTerminated(block: i32): boolean { let insts = this.body.blocks[block].insts; if (insts.length == 0) { return false; } return isIrTerminator(this.body.op(insts[insts.length - 1])); } #newInst(op: IrOp, typeId: i32, a: i32, b: i32, block: i32): i32 { let {body} = this; body.opcode.push(op as i32); body.typeId.push(typeId); body.a.push(a); body.b.push(b); body.instBlock.push(block); return body.opcode.length - 1; } #emitInCurrent(op: IrOp, typeId: i32, a: i32, b: i32): i32 { if (this.#current < 0) { throw new Error('emit: no current block'); } if (this.#isTerminated(this.#current)) { throw new Error('emit: current block already terminated'); } let inst = this.#newInst(op, typeId, a, b, this.#current); this.body.blocks[this.#current].insts.push(inst); return inst; } }