radiance · Radiance self-hosting compiler

compiler/ lib/ examples/ std/ arch/ rv64/ decode.rad 14.3 KiB emit.rad 24.2 KiB encode.rad 19.1 KiB isel.rad 47.4 KiB printer.rad 12.6 KiB tests.rad 15.7 KiB rv64.rad 8.8 KiB collections/ lang/ sys/ arch.rad 65 B collections.rad 36 B fmt.rad 3.8 KiB intrinsics.rad 399 B io.rad 1.2 KiB lang.rad 222 B mem.rad 2.1 KiB sys.rad 167 B testing.rad 2.3 KiB tests.rad 11.6 KiB vec.rad 3.1 KiB std.rad 231 B scripts/ seed/ test/ vim/ .gitignore 353 B .gitsigners 112 B LICENSE 1.1 KiB Makefile 3.0 KiB README 2.5 KiB std.lib 1.0 KiB std.lib.test 252 B
lib/std/arch/rv64/isel.rad 47.4 KiB raw
//! RV64 instruction selection.
//!
//! Walks IL and selects RV64 instructions for each operation.
//!
//! *Register resolution hierarchy*
//!
//!   getReg(ssa) -> Reg
//!     Primitive physical register lookup. Panics if the register is spilled.
//!     Used as a building block by the functions below.
//!
//!   getSrcReg(ssa, scratch) -> Reg
//!     Source register for an [`il::Reg`] operand. Returns the physical register,
//!     or loads a spilled value into `scratch`. Used for instruction fields
//!     typed as [`il::Reg`] (e.g. base addresses in Load/Store/Blit).
//!
//!   getDstReg(ssa, scratch) -> Reg
//!     Destination register for an instruction result. Returns the physical
//!     register, or records a pending spill and returns `scratch`. The pending
//!     spill is flushed by [`selectBlock`] after each instruction.
//!
//!   resolveVal(scratch, val) -> Reg
//!     Resolve an [`il::Val`] to whatever register holds it. Delegates to [`getSrcReg`]
//!     for register values; materializes immediates and symbols into `scratch`.
//!     Used for operands that can be consumed from any register.
//!
//!   loadVal(rd, val) -> Reg
//!     Force an [`il::Val`] into a specific register `rd`. Built on [`resolveVal`] + [`emitMv`].
//!     Used when the instruction requires the value in `rd` (e.g. `sub rd, rd, rs2`).

use std::mem;
use std::lang::il;
use std::lang::gen;
use std::lang::gen::regalloc;
use std::lang::gen::labels;
use std::lang::gen::data;

use super::encode;
use super::emit;

///////////////
// Constants //
///////////////

/// Shift amount for byte sign/zero extension.
const SHIFT_W8: i32 = 64 - 8;
/// Shift amount for halfword sign/zero extension.
const SHIFT_W16: i32 = 64 - 16;
/// Shift amount for word sign/zero extension.
const SHIFT_W32: i32 = 64 - 32;
/// Mask for extracting byte value.
const MASK_W8: i32 = 0xFF;
/// Maximum number of block arguments supported.
const MAX_BLOCK_ARGS: u32 = 16;

/// Signed integer range limits.
const I8_MIN: i64 = -128;
const I8_MAX: i64 = 127;
const I16_MIN: i64 = -32768;
const I16_MAX: i64 = 32767;
const I32_MIN: i64 = -2147483648;
const I32_MAX: i64 = 2147483647;

/// Unsigned integer range limits.
const U8_MAX: i64 = 255;
const U16_MAX: i64 = 65535;
const U32_MAX: i64 = 4294967295;

/// Binary operation.
union BinOp { Add, And, Or, Xor }
/// Shift operation.
union ShiftOp { Sll, Srl, Sra }
/// Compare operation.
union CmpOp { Slt, Ult }

/// Selector errors.
pub union SelectorError {
    Internal,
}

/// A pending spill store to be flushed after instruction selection.
record PendingSpill {
    /// The SSA register that was spilled.
    ssa: il::Reg,
    /// The physical register holding the value to store.
    rd: gen::Reg,
}

////////////////////
// Selector State //
////////////////////

/// Instruction selector state.
pub record Selector {
    /// Emitter for outputting instructions.
    e: *mut emit::Emitter,
    /// Register allocation result.
    ralloc: *regalloc::AllocResult,
    /// Hash-indexed data symbol map.
    dataSymMap: *data::DataSymMap,
    /// Total stack frame size.
    frameSize: i32,
    /// Running offset into the reserve region of the frame.
    /// Tracks current position within the pre-allocated reserve slots.
    reserveOffset: i32,
    /// Pending spill store, auto-committed after each instruction.
    pendingSpill: ?PendingSpill,
    /// Next synthetic block index for skip-branch targets.
    nextSynthBlock: u32,
    /// Whether dynamic allocations exist.
    isDynamic: bool,
}

/////////////////////////
// Register Allocation //
/////////////////////////

/// Get the physical register for an already-allocated SSA register.
fn getReg(s: *Selector, ssa: il::Reg) -> gen::Reg {
    let phys = s.ralloc.assignments[ssa.n] else {
        panic "getReg: spilled register has no physical assignment";
    };
    return phys;
}

/// Compute the offset for a spill slot.
/// When using FP (dynamic): offset from FP = `slot - totalSize`.
/// When using SP: offset from SP = `slot`.
fn spillOffset(s: *Selector, slot: i32) -> i32 {
    if s.isDynamic {
        return slot - s.frameSize;
    }
    return slot;
}

/// Get the base register for spill slot addressing (FP or SP).
fn spillBase(s: *Selector) -> gen::Reg {
    if s.isDynamic {
        return super::FP;
    }
    return super::SP;
}

/// Get the destination register for an SSA register.
/// If the register is spilled, records a pending spill and returns the scratch
/// register. The pending spill is auto-committed by [`selectBlock`] after each
/// instruction. If not spilled, returns the physical register.
fn getDstReg(s: *mut Selector, ssa: il::Reg, scratch: gen::Reg) -> gen::Reg {
    if let _ = regalloc::spill::spillSlot(&s.ralloc.spill, ssa) {
        s.pendingSpill = PendingSpill { ssa, rd: scratch };
        return scratch;
    }
    return getReg(s, ssa);
}

/// Get the source register for an SSA register.
/// If the register is spilled, loads the value from the spill slot into the
/// scratch register and returns it. Otherwise returns the physical register.
fn getSrcReg(s: *mut Selector, ssa: il::Reg, scratch: gen::Reg) -> gen::Reg {
    if let slot = regalloc::spill::spillSlot(&s.ralloc.spill, ssa) {
        emit::emitLd(s.e, scratch, spillBase(s), spillOffset(s, slot));
        return scratch;
    }
    return getReg(s, ssa);
}

/// Look up symbol address in data map.
fn lookupDataSym(s: *Selector, name: *[u8]) -> u32 throws (SelectorError) {
    let addr = data::lookupAddr(s.dataSymMap, name) else {
        throw SelectorError::Internal;
    };
    return addr;
}

/// Resolve an IL value to the physical register holding it.
/// For non-spilled register values, returns the physical register directly.
/// For immediates, symbols, and spilled registers, materializes into `scratch`.
fn resolveVal(s: *mut Selector, scratch: gen::Reg, val: il::Val) -> gen::Reg {
    match val {
        case il::Val::Reg(r) => {
            return getSrcReg(s, r, scratch);
        },
        case il::Val::Imm(imm) => {
            if imm == 0 {
                return super::ZERO;
            }
            emit::loadImm(s.e, scratch, imm);
            return scratch;
        },
        case il::Val::DataSym(name) => {
            let addr = try lookupDataSym(s, name) catch {
                panic "resolveVal: data symbol not found";
            };
            emit::loadImm(s.e, scratch, addr as i64);
            return scratch;
        },
        case il::Val::FnAddr(name) => {
            emit::recordAddrLoad(s.e, name, scratch);
            return scratch;
        },
        case il::Val::Undef => {
            return scratch;
        }
    }
}

/// Load an IL value into a specific physical register.
/// Like [`resolveVal`], but ensures the value ends up in `rd`.
fn loadVal(s: *mut Selector, rd: gen::Reg, val: il::Val) -> gen::Reg {
    let rs = resolveVal(s, rd, val);
    emitMv(s, rd, rs);
    return rd;
}

/// Emit a move instruction if source and destination differ.
fn emitMv(s: *mut Selector, rd: gen::Reg, rs: gen::Reg) {
    if *rd != *rs {
        emit::emit(s.e, encode::mv(rd, rs));
    }
}

/// Emit zero-extension from a sub-word type to the full register width.
fn emitZext(e: *mut emit::Emitter, rd: gen::Reg, rs: gen::Reg, typ: il::Type) {
    match typ {
        case il::Type::W8 => emit::emit(e, encode::andi(rd, rs, MASK_W8)),
        case il::Type::W16 => {
            emit::emit(e, encode::slli(rd, rs, SHIFT_W16));
            emit::emit(e, encode::srli(rd, rd, SHIFT_W16));
        },
        case il::Type::W32 => {
            emit::emit(e, encode::slli(rd, rs, SHIFT_W32));
            emit::emit(e, encode::srli(rd, rd, SHIFT_W32));
        },
        case il::Type::W64 => {}
    }
}

/// Emit sign-extension from a sub-word type to the full register width.
fn emitSext(e: *mut emit::Emitter, rd: gen::Reg, rs: gen::Reg, typ: il::Type) {
    match typ {
        case il::Type::W8 => {
            emit::emit(e, encode::slli(rd, rs, SHIFT_W8));
            emit::emit(e, encode::srai(rd, rd, SHIFT_W8));
        },
        case il::Type::W16 => {
            emit::emit(e, encode::slli(rd, rs, SHIFT_W16));
            emit::emit(e, encode::srai(rd, rd, SHIFT_W16));
        },
        case il::Type::W32 => {
            emit::emit(e, encode::addiw(rd, rs, 0));
        },
        case il::Type::W64 => {}
    }
}

/// Resolve a value, trap if zero (unless known non-zero), and return the register.
fn resolveAndTrapIfZero(s: *mut Selector, b: il::Val) -> gen::Reg {
    let rs2 = resolveVal(s, super::SCRATCH2, b);
    let mut knownNonZero = false;
    if let case il::Val::Imm(imm) = b {
        knownNonZero = imm != 0;
    }
    if not knownNonZero {
        emit::emit(s.e, encode::bne(rs2, super::ZERO, super::INSTR_SIZE * 2));
        emit::emit(s.e, encode::ebreak());
    }
    return rs2;
}

////////////////////////
// Instruction Select //
////////////////////////

/// Pre-scan result for reserve analysis.
record ReserveInfo {
    /// Total size needed for constant-sized reserves.
    size: i32,
    /// Whether any dynamic-sized reserves exist.
    isDynamic: bool,
}

/// Pre-scan all blocks for constant-sized reserve instructions.
/// Returns the total size needed for all static reserves, respecting alignment.
fn computeReserveInfo(func: *il::Fn) -> ReserveInfo {
    let mut offset: i32 = 0;
    let mut isDynamic = false;

    for b in 0..func.blocks.len {
        let block = &func.blocks[b];
        for instr in block.instrs {
            match instr {
                case il::Instr::Reserve { size, alignment, .. } => {
                    if let case il::Val::Imm(sz) = size {
                        offset = mem::alignUpI32(offset, alignment as i32);
                        offset += sz as i32;
                    } else {
                        isDynamic = true;
                    }
                },
                else => {},
            }
        }
    }
    return ReserveInfo { size: offset, isDynamic };
}

/// Select instructions for a function.
pub fn selectFn(
    e: *mut emit::Emitter,
    dataSymMap: *data::DataSymMap,
    ralloc: *regalloc::AllocResult,
    func: *il::Fn
) {
    // Reset block offsets for this function.
    labels::resetBlocks(&mut e.labels);
    // Pre-scan for constant-sized reserves to promote to fixed frame slots.
    let reserveInfo = computeReserveInfo(func);
    let isLeaf = func.isLeaf;
    // Compute frame layout from spill slots, reserve slots, and used callee-saved registers.
    let frame = emit::computeFrame(
        ralloc.spill.frameSize + reserveInfo.size,
        ralloc.usedCalleeSaved,
        func.blocks.len,
        isLeaf,
        reserveInfo.isDynamic
    );
    // Synthetic block indices start after real blocks and the epilogue block.
    let mut s = Selector {
        e, ralloc, dataSymMap, frameSize: frame.totalSize,
        reserveOffset: 0, pendingSpill: nil,
        nextSynthBlock: func.blocks.len + 1,
        isDynamic: frame.isDynamic,
    };
    // Record function name for printing.
    emit::recordFunc(s.e, func.name);
    // Record function code offset for call patching.
    emit::recordFuncOffset(s.e, func.name);
    // Emit prologue.
    emit::emitPrologue(s.e, &frame);

    // Move function params from arg registers to assigned registers.
    // Cross-call params may have been assigned to callee-saved registers
    // instead of their natural arg registers. Spilled params are stored
    // directly to their spill slots.
    for funcParam, i in func.params {
        if i < super::ARG_REGS.len {
            let param = funcParam.value;
            let argReg = super::ARG_REGS[i];

            if let slot = regalloc::spill::spillSlot(&ralloc.spill, param) {
                // Spilled parameter: store arg register to spill slot.
                emit::emitSd(s.e, argReg, spillBase(&s), spillOffset(&s, slot));
            } else if let assigned = ralloc.assignments[param.n] {
                emitMv(&mut s, assigned, argReg);
            }
        }
    }

    // Emit each block.
    for i in 0..func.blocks.len {
        selectBlock(&mut s, i, &func.blocks[i], &frame, func);
    }
    // Emit epilogue.
    emit::emitEpilogue(s.e, &frame);
    // Patch local branches now that all blocks are emitted.
    emit::patchLocalBranches(s.e);
}

/// Select instructions for a block.
fn selectBlock(s: *mut Selector, blockIdx: u32, block: *il::Block, frame: *emit::Frame, func: *il::Fn) {
    // Record block address for branch patching.
    emit::recordBlock(s.e, blockIdx);

    // Block parameters are handled at jump sites (in `Jmp`/`Br`).
    // By the time we enter the block, the arguments have already been
    // moved to the parameter registers by the predecessor's terminator.

    // Process each instruction, auto-committing any pending spill after each.
    let hasLocs = block.locs.len > 0;
    for instr, i in block.instrs {
        // Record debug location before emitting machine instructions.
        if hasLocs {
            emit::recordSrcLoc(s.e, block.locs[i]);
        }
        s.pendingSpill = nil;
        selectInstr(s, blockIdx, instr, frame, func);

        // Flush the pending spill store, if any.
        if let p = s.pendingSpill {
            if let slot = regalloc::spill::spillSlot(&s.ralloc.spill, p.ssa) {
                emit::emitSd(s.e, p.rd, spillBase(s), spillOffset(s, slot));
            }
            s.pendingSpill = nil;
        }
    }
}

/// Select instructions for a single IL instruction.
fn selectInstr(s: *mut Selector, blockIdx: u32, instr: il::Instr, frame: *emit::Frame, func: *il::Fn) {
    match instr {
        case il::Instr::BinOp { op, typ, dst, a, b } => {
            let rd = getDstReg(s, dst, super::SCRATCH1);
            let rs1 = resolveVal(s, super::SCRATCH1, a);
            selectAluBinOp(s, op, typ, rd, rs1, b);
        },
        case il::Instr::UnOp { op, typ, dst, a } => {
            let rd = getDstReg(s, dst, super::SCRATCH1);
            let rs = resolveVal(s, super::SCRATCH1, a);
            selectAluUnOp(s, op, typ, rd, rs);
        },
        case il::Instr::Load { typ, dst, src, offset } => {
            let rd = getDstReg(s, dst, super::SCRATCH1);
            let base = getSrcReg(s, src, super::SCRATCH2);
            emit::emitLoad(s.e, rd, base, offset, typ);
        },
        case il::Instr::Sload { typ, dst, src, offset } => {
            let rd = getDstReg(s, dst, super::SCRATCH1);
            let base = getSrcReg(s, src, super::SCRATCH2);
            emit::emitSload(s.e, rd, base, offset, typ);
        },
        case il::Instr::Store { typ, src, dst, offset } => {
            let base = getSrcReg(s, dst, super::SCRATCH2);
            let rs = resolveVal(s, super::SCRATCH1, src);
            emit::emitStore(s.e, rs, base, offset, typ);
        },
        case il::Instr::Copy { dst, val } => {
            let rd = getDstReg(s, dst, super::SCRATCH1);
            let rs = resolveVal(s, super::SCRATCH1, val);
            emitMv(s, rd, rs);
        },
        case il::Instr::Reserve { dst, size, alignment } => {
            match size {
                case il::Val::Imm(sz) => {
                    // Constant-sized reserve: use pre-allocated frame slot.
                    let rd = getDstReg(s, dst, super::SCRATCH1);
                    let aligned: i32 = mem::alignUpI32(s.reserveOffset, alignment as i32);
                    let base = spillBase(s);
                    let offset = s.ralloc.spill.frameSize + aligned
                        - (s.frameSize if s.isDynamic else 0);

                    emit::emitAddImm(s.e, rd, base, offset);
                    s.reserveOffset = aligned + (sz as i32);
                },
                case il::Val::Reg(r) => {
                    // Dynamic-sized reserve: runtime SP adjustment.
                    let rd = getDstReg(s, dst, super::SCRATCH1);
                    let rs = getSrcReg(s, r, super::SCRATCH2);

                    emit::emit(s.e, encode::sub(super::SP, super::SP, rs));

                    if alignment > 1 {
                        let mask = 0 - alignment as i32;
                        assert encode::isSmallImm(mask);

                        emit::emit(s.e, encode::andi(super::SP, super::SP, mask));
                    }
                    emit::emit(s.e, encode::mv(rd, super::SP));
                },
                else =>
                    panic "selectInstr: invalid reserve operand",
            }
        },
        case il::Instr::Blit { dst, src, size } => {
            let case il::Val::Imm(staticSize) = size
                else panic "selectInstr: blit requires immediate size";

            let bothSpilled = regalloc::spill::isSpilled(&s.ralloc.spill, dst)
                and regalloc::spill::isSpilled(&s.ralloc.spill, src);

            // When both are spilled, offsets must fit 12-bit immediates
            // since we can't advance base registers (they live in spill
            // slots, not real registers we can mutate).
            assert not (bothSpilled and staticSize as i32 > super::MAX_IMM), "selectInstr: blit both-spilled with large size";

            // Resolve dst/src base registers.
            let mut rdst = super::SCRATCH2;
            let mut rsrc = super::SCRATCH1;
            let mut srcReload: ?i32 = nil;

            if bothSpilled {
                let dstSlot = regalloc::spill::spillSlot(&s.ralloc.spill, dst) else {
                    panic "selectInstr: blit dst not spilled";
                };
                let srcSlot = regalloc::spill::spillSlot(&s.ralloc.spill, src) else {
                    panic "selectInstr: blit src not spilled";
                };
                emit::emitLd(s.e, super::SCRATCH2, spillBase(s), spillOffset(s, dstSlot));
                srcReload = spillOffset(s, srcSlot);
            } else {
                rdst = getSrcReg(s, dst, super::SCRATCH2);
                rsrc = getSrcReg(s, src, super::SCRATCH2);
            }
            let mut offset: i32 = 0;
            let mut remaining = staticSize as i32;

            // For large blits where both pointers are in real registers,
            // use an inline loop instead of unrolled LD/SD pairs.
            let dwordBytes = remaining & ~(super::DWORD_SIZE - 1);
            let canLoop = not bothSpilled
                and *rsrc != *super::SCRATCH1 and *rsrc != *super::SCRATCH2
                and *rdst != *super::SCRATCH1 and *rdst != *super::SCRATCH2;

            if canLoop and dwordBytes >= super::BLIT_LOOP_THRESHOLD {
                emit::emitAddImm(s.e, super::SCRATCH1, rsrc, dwordBytes);

                let loopStart = s.e.codeLen;

                emit::emitLd(s.e, super::SCRATCH2, rsrc, 0);
                emit::emitSd(s.e, super::SCRATCH2, rdst, 0);
                emit::emit(s.e, encode::addi(rsrc, rsrc, super::DWORD_SIZE));

                if *rdst != *rsrc {
                    emit::emit(s.e, encode::addi(rdst, rdst, super::DWORD_SIZE));
                }
                let brOff = (loopStart as i32 - s.e.codeLen as i32) * super::INSTR_SIZE;

                emit::emit(s.e, encode::bne(rsrc, super::SCRATCH1, brOff));
                remaining -= dwordBytes;
            }

            // Copy remaining: 8 bytes, then 4 bytes, then 1 byte at a time.
            // Before each load/store pair, check whether the offset is
            // about to exceed the 12-bit signed immediate range. When
            // it does, advance the base registers by the accumulated
            // offset and reset to zero.
            while remaining >= super::DWORD_SIZE {
                if offset > super::MAX_IMM - super::DWORD_SIZE {
                    emit::emitAddImm(s.e, rsrc, rsrc, offset);
                    if *rdst != *rsrc {
                        emit::emitAddImm(s.e, rdst, rdst, offset);
                    }
                    offset = 0;
                }
                if let off = srcReload {
                    emit::emitLd(s.e, super::SCRATCH1, spillBase(s), off);
                    emit::emitLd(s.e, super::SCRATCH1, super::SCRATCH1, offset);
                } else {
                    emit::emitLd(s.e, super::SCRATCH1, rsrc, offset);
                }
                emit::emitSd(s.e, super::SCRATCH1, rdst, offset);
                offset += super::DWORD_SIZE;
                remaining -= super::DWORD_SIZE;
            }
            if remaining >= super::WORD_SIZE {
                if offset > super::MAX_IMM - super::WORD_SIZE {
                    emit::emitAddImm(s.e, rsrc, rsrc, offset);
                    if *rdst != *rsrc {
                        emit::emitAddImm(s.e, rdst, rdst, offset);
                    }
                    offset = 0;
                }
                if let off = srcReload {
                    emit::emitLd(s.e, super::SCRATCH1, spillBase(s), off);
                    emit::emitLw(s.e, super::SCRATCH1, super::SCRATCH1, offset);
                } else {
                    emit::emitLw(s.e, super::SCRATCH1, rsrc, offset);
                }
                emit::emitSw(s.e, super::SCRATCH1, rdst, offset);
                offset += super::WORD_SIZE;
                remaining -= super::WORD_SIZE;
            }
            while remaining > 0 {
                if offset > super::MAX_IMM - 1 {
                    emit::emitAddImm(s.e, rsrc, rsrc, offset);
                    if *rdst != *rsrc {
                        emit::emitAddImm(s.e, rdst, rdst, offset);
                    }
                    offset = 0;
                }
                if let off = srcReload {
                    emit::emitLd(s.e, super::SCRATCH1, spillBase(s), off);
                    emit::emitLb(s.e, super::SCRATCH1, super::SCRATCH1, offset);
                } else {
                    emit::emitLb(s.e, super::SCRATCH1, rsrc, offset);
                }
                emit::emitSb(s.e, super::SCRATCH1, rdst, offset);
                offset += 1;
                remaining -= 1;
            }
            // Restore base registers if they were advanced (never happens
            // in the both-spilled case since size <= MAX_IMM).
            if not bothSpilled {
                let advanced = staticSize as i32 - offset;
                if advanced != 0 {
                    emit::emitAddImm(s.e, rsrc, rsrc, 0 - advanced);
                    if *rdst != *rsrc {
                        emit::emitAddImm(s.e, rdst, rdst, 0 - advanced);
                    }
                }
            }
        },
        case il::Instr::Zext { typ, dst, val } => {
            let rd = getDstReg(s, dst, super::SCRATCH1);
            let rs = resolveVal(s, super::SCRATCH1, val);
            emitZext(s.e, rd, rs, typ);
        },
        case il::Instr::Sext { typ, dst, val } => {
            let rd = getDstReg(s, dst, super::SCRATCH1);
            let rs = resolveVal(s, super::SCRATCH1, val);
            emitSext(s.e, rd, rs, typ);
        },
        case il::Instr::Ret { val } => {
            if let v = val {
                let rs = resolveVal(s, super::SCRATCH1, v);
                emitMv(s, super::A0, rs);
            }
            // Skip the jump to epilogue if this RET is in the last block,
            // since the epilogue immediately follows.
            if frame.totalSize != 0 and blockIdx + 1 == frame.epilogueBlock {
                // Epilogue is the next block; fallthrough is sufficient.
            } else {
                emit::emitReturn(s.e, frame);
            }
        },
        case il::Instr::Jmp { target, args } => {
            // Move arguments to target block's parameter registers.
            emitBlockArgs(s, func, target, args);
            // Skip branch if target is the next block (fallthrough).
            if target != blockIdx + 1 {
                emit::recordBranch(s.e, target, emit::BranchKind::Jump);
            }
        },
        case il::Instr::Br { op, typ, a, b, thenTarget, thenArgs, elseTarget, elseArgs } => {
            // Use zero register directly for immediate `0` operands.
            let aIsZero = isZeroImm(a);
            let bIsZero = isZeroImm(b);

            let rs1 = super::ZERO if aIsZero else resolveVal(s, super::SCRATCH1, a);
            let rs2 = super::ZERO if bIsZero else resolveVal(s, super::SCRATCH2, b);

            // Normalize sub-word operands so that both registers have the same
            // canonical representation. Without this, eg. `-1 : i8 ` loaded as
            // `0xFFFFFFFFFFFFFFFF` and `255 : i8` loaded as `0xFF` would compare
            // unequal even though they are the same 8-bit pattern.
            //
            // For SLT: sign-extension needed (signed comparison).
            // For ULT: zero-extension needed (unsigned magnitude comparison).
            // For EQ/NE with W32: sign-extension is cheaper.
            // For EQ/NE with W8/W16: keep zero-extension.
            // Skip extension for zero register.
            // Determine extension mode: sign-extend for W32 or SLT,
            // zero-extend otherwise.
            let mut useSext: bool = undefined;
            if let case il::CmpOp::Slt = op {
                useSext = true;
            } else {
                useSext = typ == il::Type::W32;
            }
            if useSext {
                if not aIsZero and not isExtendedImm(a, typ, true) {
                    emitSext(s.e, rs1, rs1, typ);
                }
                if not bIsZero and not isExtendedImm(b, typ, true) {
                    emitSext(s.e, rs2, rs2, typ);
                }
            } else {
                if not aIsZero and not isExtendedImm(a, typ, false) {
                    emitZext(s.e, rs1, rs1, typ);
                }
                if not bIsZero and not isExtendedImm(b, typ, false) {
                    emitZext(s.e, rs2, rs2, typ);
                }
            }
            // Block-argument moves must only execute on the taken path.
            // When `thenArgs` is non-empty, invert the branch so that the
            // then-moves land on the fall-through (taken) side.
            //
            // When one target is the next block in layout order, we can
            // eliminate the trailing unconditional jump by arranging the
            // conditional branch to skip to the *other* target and letting
            // execution fall through.
            if thenArgs.len > 0 and elseArgs.len > 0 {
                panic "selectInstr: both `then` and `else` have block arguments";
            } else if thenArgs.len > 0 {
                emit::recordBranch(s.e, elseTarget, emit::BranchKind::InvertedCond { op, rs1, rs2 });
                emitBlockArgs(s, func, thenTarget, thenArgs);
                // Skip trailing jump if then is the next block (fallthrough).
                if thenTarget != blockIdx + 1 {
                    emit::recordBranch(s.e, thenTarget, emit::BranchKind::Jump);
                }
            } else if thenTarget == blockIdx + 1 and elseArgs.len == 0 {
                // Then is the next block and no else args: invert the
                // condition to branch to else and fall through to then.
                emit::recordBranch(s.e, elseTarget, emit::BranchKind::InvertedCond { op, rs1, rs2 });
            } else {
                emit::recordBranch(s.e, thenTarget, emit::BranchKind::Cond { op, rs1, rs2 });
                emitBlockArgs(s, func, elseTarget, elseArgs);
                // Skip trailing jump if else is the next block (fallthrough).
                if elseTarget != blockIdx + 1 {
                    emit::recordBranch(s.e, elseTarget, emit::BranchKind::Jump);
                }
            }
        },
        case il::Instr::Switch { val, defaultTarget, defaultArgs, cases } => {
            let rs1 = resolveVal(s, super::SCRATCH1, val);
            // When a case has block args, invert the branch to skip past
            // the arg moves.
            for c in cases {
                emit::loadImm(s.e, super::SCRATCH2, c.value);

                if c.args.len > 0 {
                    let skip = s.nextSynthBlock;
                    s.nextSynthBlock = skip + 1;

                    emit::recordBranch(s.e, skip, emit::BranchKind::InvertedCond {
                        op: il::CmpOp::Eq, rs1, rs2: super::SCRATCH2,
                    });
                    emitBlockArgs(s, func, c.target, c.args);
                    emit::recordBranch(s.e, c.target, emit::BranchKind::Jump);
                    emit::recordBlock(s.e, skip);
                } else {
                    emit::recordBranch(s.e, c.target, emit::BranchKind::Cond {
                        op: il::CmpOp::Eq, rs1, rs2: super::SCRATCH2,
                    });
                }
            }
            // Fall through to default.
            emitBlockArgs(s, func, defaultTarget, defaultArgs);
            emit::recordBranch(s.e, defaultTarget, emit::BranchKind::Jump);
        },
        case il::Instr::Unreachable => {
            emit::emit(s.e, encode::ebreak());
        },
        case il::Instr::Call { retTy, dst, func, args } => {
            // For indirect calls, save target to scratch register before arg
            // setup can clobber it.
            if let case il::Val::Reg(r) = func {
                let target = getSrcReg(s, r, super::SCRATCH2);
                emitMv(s, super::SCRATCH2, target);
            }
            // Move arguments to A0-A7 using parallel move resolution.
            assert args.len <= super::ARG_REGS.len, "selectInstr: too many call arguments";
            emitParallelMoves(s, &super::ARG_REGS[..], args);

            // Emit call.
            match func {
                case il::Val::FnAddr(name) => {
                    emit::recordCall(s.e, name);
                },
                case il::Val::Reg(_) => {
                    emit::emit(s.e, encode::jalr(super::RA, super::SCRATCH2, 0));
                },
                else => {
                    panic "selectInstr: invalid call target";
                }
            }
            // Move result from A0.
            if let d = dst {
                let rd = getDstReg(s, d, super::SCRATCH1);
                emitMv(s, rd, super::A0);
            }
        },
        case il::Instr::Ecall { dst, num, a0, a1, a2, a3 } => {
            // Move arguments using parallel move.
            // TODO: Can't use slice literals here because the lowerer doesn't
            // support const-evaluating struct/union values in them.
            let ecallDsts: [gen::Reg; 5] = [super::A7, super::A0, super::A1, super::A2, super::A3];
            let ecallArgs: [il::Val; 5] = [num, a0, a1, a2, a3];

            emitParallelMoves(s, &ecallDsts[..], &ecallArgs[..]);
            emit::emit(s.e, encode::ecall());

            // Result in A0.
            let ecallRd = getDstReg(s, dst, super::SCRATCH1);
            emitMv(s, ecallRd, super::A0);
        },
        case il::Instr::Ebreak => {
            emit::emit(s.e, encode::ebreak());
        },
    }
}

/// Check if a value is an immediate that's already correctly extended.
/// `loadImm` produces the exact 64-bit value; this checks whether that value
/// already matches what sign/zero-extension to the given type would produce.
fn isExtendedImm(val: il::Val, typ: il::Type, signed: bool) -> bool {
    if let case il::Val::Imm(imm) = val {
        if signed {
            // Sign-extension truncates to the type width and sign-extends.
            // The 64-bit value is already correctly sign-extended if it
            // fits in the signed range of the target type.
            match typ {
                case il::Type::W8 => return imm >= I8_MIN and imm <= I8_MAX,
                case il::Type::W16 => return imm >= I16_MIN and imm <= I16_MAX,
                case il::Type::W32 => return imm >= I32_MIN and imm <= I32_MAX,
                case il::Type::W64 => return true,
            }
        } else {
            // Zero-extension: value must be non-negative and within unsigned range.
            match typ {
                case il::Type::W8 => return imm >= 0 and imm <= U8_MAX,
                case il::Type::W16 => return imm >= 0 and imm <= U16_MAX,
                case il::Type::W32 => return imm >= 0 and imm <= U32_MAX,
                case il::Type::W64 => return true,
            }
        }
    }
    return false;
}

/// Check if a value is an immediate zero.
fn isZeroImm(val: il::Val) -> bool {
    if let case il::Val::Imm(imm) = val {
        return imm == 0;
    }
    return false;
}

/// Select a binary ALU operation, dispatching to the appropriate
/// instruction pattern based on the operation kind and type.
fn selectAluBinOp(s: *mut Selector, op: il::BinOp, typ: il::Type, rd: gen::Reg, rs1: gen::Reg, b: il::Val) {
    match op {
        case il::BinOp::Add => {
            if typ == il::Type::W32 {
                // Inline W32 ADD with immediate optimization.
                if let case il::Val::Imm(imm) = b {
                    if encode::isSmallImm64(imm) {
                        emit::emit(s.e, encode::addiw(rd, rs1, imm as i32));
                        return;
                    }
                }
                let rs2 = resolveVal(s, super::SCRATCH2, b);
                emit::emit(s.e, encode::addw(rd, rs1, rs2));
            } else {
                selectBinOp(s, rd, rs1, b, BinOp::Add, super::SCRATCH2);
            }
        }
        case il::BinOp::Sub => {
            // Optimize subtraction by small immediate: use ADDI with negated value.
            if let case il::Val::Imm(imm) = b {
                let neg = -imm;
                if neg >= super::MIN_IMM as i64 and neg <= super::MAX_IMM as i64 {
                    emit::emit(s.e,
                        encode::addiw(rd, rs1, neg as i32)
                            if typ == il::Type::W32 else
                        encode::addi(rd, rs1, neg as i32));
                    return;
                }
            }
            let rs2 = resolveVal(s, super::SCRATCH2, b);

            emit::emit(s.e,
                encode::subw(rd, rs1, rs2)
                    if typ == il::Type::W32 else
                encode::sub(rd, rs1, rs2));
        }
        case il::BinOp::Mul => {
            // Strength-reduce multiplication by known constants.
            if let case il::Val::Imm(imm) = b {
                if imm == 0 {
                    emit::emit(s.e, encode::mv(rd, super::ZERO));
                    return;
                } else if imm == 1 {
                    emitMv(s, rd, rs1);
                    return;
                } else if imm == 2 {
                    emit::emit(s.e, encode::slli(rd, rs1, 1));
                    return;
                } else if imm == 4 {
                    emit::emit(s.e, encode::slli(rd, rs1, 2));
                    return;
                } else if imm == 8 {
                    emit::emit(s.e, encode::slli(rd, rs1, 3));
                    return;
                }
            }
            let rs2 = resolveVal(s, super::SCRATCH2, b);
            emit::emit(s.e,
                encode::mulw(rd, rs1, rs2)
                    if typ == il::Type::W32 else
                encode::mul(rd, rs1, rs2));
        }
        case il::BinOp::Sdiv => {
            let rs2 = resolveAndTrapIfZero(s, b);
            emit::emit(s.e,
                encode::divw(rd, rs1, rs2)
                    if typ == il::Type::W32 else
                encode::div(rd, rs1, rs2));
        }
        case il::BinOp::Udiv => {
            let rs2 = resolveAndTrapIfZero(s, b);
            emit::emit(s.e,
                encode::divuw(rd, rs1, rs2)
                    if typ == il::Type::W32 else
                encode::divu(rd, rs1, rs2));
        }
        case il::BinOp::Srem => {
            let rs2 = resolveAndTrapIfZero(s, b);
            emit::emit(s.e,
                encode::remw(rd, rs1, rs2)
                    if typ == il::Type::W32 else
                encode::rem(rd, rs1, rs2));
        }
        case il::BinOp::Urem => {
            let rs2 = resolveAndTrapIfZero(s, b);
            emit::emit(s.e,
                encode::remuw(rd, rs1, rs2)
                    if typ == il::Type::W32 else
                encode::remu(rd, rs1, rs2));
        }
        case il::BinOp::And =>
            selectBinOp(s, rd, rs1, b, BinOp::And, super::SCRATCH2),
        case il::BinOp::Or =>
            selectBinOp(s, rd, rs1, b, BinOp::Or, super::SCRATCH2),
        case il::BinOp::Xor =>
            selectBinOp(s, rd, rs1, b, BinOp::Xor, super::SCRATCH2),
        case il::BinOp::Shl =>
            selectShift(s, rd, rs1, b, ShiftOp::Sll, typ, super::SCRATCH2),
        case il::BinOp::Sshr =>
            selectShift(s, rd, rs1, b, ShiftOp::Sra, typ, super::SCRATCH2),
        case il::BinOp::Ushr =>
            selectShift(s, rd, rs1, b, ShiftOp::Srl, typ, super::SCRATCH2),
        case il::BinOp::Eq, il::BinOp::Ne => {
            let rs2 = resolveVal(s, super::SCRATCH2, b);
            // Canonicalize both operands to the declared width.
            if typ == il::Type::W32 {
                emitSext(s.e, rs1, rs1, typ);
                if not isExtendedImm(b, typ, true) {
                    emitSext(s.e, rs2, rs2, typ);
                }
            } else {
                emitZext(s.e, rs1, rs1, typ);
                if not isExtendedImm(b, typ, false) {
                    emitZext(s.e, rs2, rs2, typ);
                }
            }
            emit::emit(s.e, encode::xor(rd, rs1, rs2));
            if let case il::BinOp::Eq = op {
                emit::emit(s.e, encode::sltiu(rd, rd, 1));
            } else {
                emit::emit(s.e, encode::sltu(rd, super::ZERO, rd));
            }
        }
        case il::BinOp::Slt =>
            selectCmp(s, rd, rs1, b, CmpOp::Slt, super::SCRATCH2),
        case il::BinOp::Ult =>
            selectCmp(s, rd, rs1, b, CmpOp::Ult, super::SCRATCH2),
        case il::BinOp::Sge, il::BinOp::Uge => {
            let rs2 = resolveVal(s, super::SCRATCH2, b);
            if let case il::BinOp::Sge = op {
                emit::emit(s.e, encode::slt(rd, rs1, rs2));
            } else {
                emit::emit(s.e, encode::sltu(rd, rs1, rs2));
            }
            emit::emit(s.e, encode::xori(rd, rd, 1));
        }
    }
}

/// Select a unary ALU operation.
fn selectAluUnOp(s: *mut Selector, op: il::UnOp, typ: il::Type, rd: gen::Reg, rs: gen::Reg) {
    match op {
        case il::UnOp::Neg => {
            if typ == il::Type::W32 {
                emit::emit(s.e, encode::subw(rd, super::ZERO, rs));
            } else {
                emit::emit(s.e, encode::neg(rd, rs));
            }
        }
        case il::UnOp::Not =>
            emit::emit(s.e, encode::not_(rd, rs)),
    }
}

/// Select binary operation with immediate optimization.
fn selectBinOp(s: *mut Selector, rd: gen::Reg, rs1: gen::Reg, b: il::Val, op: BinOp, scratch: gen::Reg) {
    // Try immediate optimization first.
    if let case il::Val::Imm(imm) = b {
        if encode::isSmallImm64(imm) {
            let simm = imm as i32;
            match op {
                case BinOp::Add => emit::emit(s.e, encode::addi(rd, rs1, simm)),
                case BinOp::And => emit::emit(s.e, encode::andi(rd, rs1, simm)),
                case BinOp::Or  => emit::emit(s.e, encode::ori(rd, rs1, simm)),
                case BinOp::Xor => emit::emit(s.e, encode::xori(rd, rs1, simm)),
            }
            return;
        }
    }
    // Fallback: load into register.
    let rs2 = resolveVal(s, scratch, b);
    match op {
        case BinOp::Add => emit::emit(s.e, encode::add(rd, rs1, rs2)),
        case BinOp::And => emit::emit(s.e, encode::and_(rd, rs1, rs2)),
        case BinOp::Or  => emit::emit(s.e, encode::or_(rd, rs1, rs2)),
        case BinOp::Xor => emit::emit(s.e, encode::xor(rd, rs1, rs2)),
    }
}

/// Select shift operation with immediate optimization.
/// For 32-bit operations, uses the `*w` variants that operate on the lower 32 bits
/// and sign-extend the result.
fn selectShift(s: *mut Selector, rd: gen::Reg, rs1: gen::Reg, b: il::Val, op: ShiftOp, typ: il::Type, scratch: gen::Reg) {
    let isW32: bool = typ == il::Type::W32;

    // Try immediate optimization first.
    if let case il::Val::Imm(shamt) = b {
        // Keep immediate forms only for encodable shift amounts.
        // Otherwise fall back to register shifts, which naturally mask the count.
        if shamt >= 0 and ((isW32 and shamt < 32) or (not isW32 and shamt < 64)) {
            let sa = shamt as i32;
            if isW32 {
                match op {
                    case ShiftOp::Sll => emit::emit(s.e, encode::slliw(rd, rs1, sa)),
                    case ShiftOp::Srl => emit::emit(s.e, encode::srliw(rd, rs1, sa)),
                    case ShiftOp::Sra => emit::emit(s.e, encode::sraiw(rd, rs1, sa)),
                }
            } else {
                match op {
                    case ShiftOp::Sll => emit::emit(s.e, encode::slli(rd, rs1, sa)),
                    case ShiftOp::Srl => emit::emit(s.e, encode::srli(rd, rs1, sa)),
                    case ShiftOp::Sra => emit::emit(s.e, encode::srai(rd, rs1, sa)),
                }
            }
            return;
        }
    }
    // Fallback: load into register.
    let rs2 = resolveVal(s, scratch, b);
    if isW32 {
        match op {
            case ShiftOp::Sll => emit::emit(s.e, encode::sllw(rd, rs1, rs2)),
            case ShiftOp::Srl => emit::emit(s.e, encode::srlw(rd, rs1, rs2)),
            case ShiftOp::Sra => emit::emit(s.e, encode::sraw(rd, rs1, rs2)),
        }
    } else {
        match op {
            case ShiftOp::Sll => emit::emit(s.e, encode::sll(rd, rs1, rs2)),
            case ShiftOp::Srl => emit::emit(s.e, encode::srl(rd, rs1, rs2)),
            case ShiftOp::Sra => emit::emit(s.e, encode::sra(rd, rs1, rs2)),
        }
    }
}

/// Resolve parallel moves from IL values to physical destination registers.
///
/// The parallel move problem arises when moving values between registers where
/// there may be dependencies (e.g. moving A0 to A1 and A1 to A0 simultaneously).
///
/// This algorithm:
/// 1. Identifies "ready" moves.
/// 2. Executes ready moves.
/// 3. Breaks cycles using scratch register.
///
/// Entries with `ZERO` destination are skipped, as they are handled by caller.
fn emitParallelMoves(s: *mut Selector, dsts: *[gen::Reg], args: *[il::Val]) {
    let n: u32 = args.len;
    if n == 0 {
        return;
    }
    assert n <= MAX_BLOCK_ARGS, "emitParallelMoves: too many arguments";
    // Source registers for each arg.
    let mut srcRegs: [gen::Reg; MAX_BLOCK_ARGS] = [super::ZERO; MAX_BLOCK_ARGS];
    // If this is a register-to-register move.
    let mut isRegMove: [bool; MAX_BLOCK_ARGS] = [false; MAX_BLOCK_ARGS];
    // If this move still needs to be executed.
    let mut pending: [bool; MAX_BLOCK_ARGS] = [false; MAX_BLOCK_ARGS];
    // Number of pending moves.
    let mut numPending: u32 = 0;

    for i in 0..n {
        let dst = dsts[i];
        if dst != super::ZERO { // Skip entries with no destination.
            match args[i] {
                case il::Val::Reg(r) => {
                    if let _ = regalloc::spill::spillSlot(&s.ralloc.spill, r) {
                        // Spilled value needs load, not a register move.
                        pending[i] = true;
                        numPending += 1;
                    } else {
                        let src = getReg(s, r);
                        if src != dst {
                            // Register-to-register move needed.
                            srcRegs[i] = src;
                            isRegMove[i] = true;
                            pending[i] = true;
                            numPending += 1;
                        } else {
                            // No move needed.
                        }
                    }
                },
                case il::Val::Imm(_), il::Val::DataSym(_), il::Val::FnAddr(_) => {
                    pending[i] = true;
                    numPending += 1;
                },
                case il::Val::Undef => {
                    // Undefined values don't need any move.
                }
            }
        } else {
            // Nothing to do.
        }
    }

    // Execute parallel move algorithm.
    while numPending > 0 {
        let mut found = false;

        // Find a ready move: one whose destination is not a source of any
        // pending register move.
        for i in 0..n {
            if pending[i] {
                let dst = dsts[i];
                let mut isReady = true;

                // Check if `dst` is used as source by any other pending register move.
                for j in 0..n {
                    if j != i and pending[j] and isRegMove[j] and srcRegs[j] == dst {
                        isReady = false;
                        break;
                    }
                }
                if isReady {
                    // Execute this move.
                    if isRegMove[i] {
                        emitMv(s, dst, srcRegs[i]);
                    } else {
                        // Load immediate, symbol, or spilled value.
                        loadVal(s, dst, args[i]);
                    }
                    found = true;
                    pending[i] = false;
                    numPending -= 1;

                    break;
                }
            }
        }

        if not found {
            // No ready move, we have a cycle among register moves.
            // Break it by saving one source to scratch.
            for i in 0..n {
                if pending[i] and isRegMove[i] {
                    let src = srcRegs[i];
                    // Save this source to scratch.
                    emitMv(s, super::SCRATCH1, src);
                    // Update all pending moves that use this source.
                    for j in 0..n {
                        if pending[j] and isRegMove[j] and srcRegs[j] == src {
                            srcRegs[j] = super::SCRATCH1;
                        }
                    }
                    break;
                }
            }
        }
    }
}

/// Emit moves from block arguments to target block's parameter registers.
///
/// Handles spilled destinations directly, then delegates to [`emitParallelMoves`]
/// for the remaining register-to-register parallel move resolution.
fn emitBlockArgs(s: *mut Selector, func: *il::Fn, target: u32, args: *mut [il::Val]) {
    if args.len == 0 {
        return;
    }
    let block = &func.blocks[target];
    assert args.len == block.params.len, "emitBlockArgs: argument/parameter count mismatch";
    assert args.len <= MAX_BLOCK_ARGS, "emitBlockArgs: too many block arguments";

    // Destination registers for each arg.
    // Zero means the destination is spilled or skipped.
    let mut dsts: [gen::Reg; MAX_BLOCK_ARGS] = [super::ZERO; MAX_BLOCK_ARGS];

    for arg, i in args {
        let param = block.params[i].value;

        // Spilled destinations: store directly to spill slot.
        // These don't participate in the parallel move algorithm.
        if let slot = regalloc::spill::spillSlot(&s.ralloc.spill, param) {
            if let case il::Val::Undef = arg {
                // Undefined values don't need any move.
            } else {
                let rs = resolveVal(s, super::SCRATCH1, arg);
                emit::emitSd(s.e, rs, spillBase(s), spillOffset(s, slot));
            }
        } else {
            dsts[i] = getReg(s, param);
        }
    }
    emitParallelMoves(s, &dsts[..], args);
}

/// Select comparison with immediate optimization.
fn selectCmp(s: *mut Selector, rd: gen::Reg, rs1: gen::Reg, b: il::Val, op: CmpOp, scratch: gen::Reg) {
    // Try immediate optimization first.
    if let case il::Val::Imm(imm) = b {
        if encode::isSmallImm64(imm) {
            let simm = imm as i32;
            match op {
                case CmpOp::Slt => emit::emit(s.e, encode::slti(rd, rs1, simm)),
                case CmpOp::Ult => emit::emit(s.e, encode::sltiu(rd, rs1, simm)),
            }
            return;
        }
    }
    // Fallback: load into register.
    let rs2 = resolveVal(s, scratch, b);
    match op {
        case CmpOp::Slt => emit::emit(s.e, encode::slt(rd, rs1, rs2)),
        case CmpOp::Ult => emit::emit(s.e, encode::sltu(rd, rs1, rs2)),
    }
}