//! RV64 binary emission.

//!

//! Emits RV64 machine code as `u32` list.

use std::lang::il;

use std::lang::alloc;

use std::lang::gen::labels;

use std::collections::dict;

use std::mem;

use super::encode;

/// Maximum number of instructions in code buffer.

const MAX_INSTRS: u32 = 2097152;

/// Maximum code length before byte offset overflows 32-bits.

/// Computed as `0x7FFFFFFF` / [`super::INSTR_SIZE`].

const MAX_CODE_LEN: u32 = 0x3FFFFFFE;

/// Maximum number of pending branches awaiting patching.

const MAX_PENDING: u32 = 65536;

/// Maximum number of function entries.

const MAX_FUNCS: u32 = 4096;

/// Maximum number of debug entries.

const MAX_DEBUG_ENTRIES: u32 = 524288;

//////////////////////

// Emission Context //

//////////////////////

/// Branch/jump that needs offset patching after all blocks are emitted.

pub record PendingBranch {

    /// Index into code buffer where the branch instruction is.

    index: u32,

    /// Target block index.

    target: u32,

    /// Type of branch for re-encoding.

    kind: BranchKind,

}

/// Type of branch instruction.

pub union BranchKind {

    /// Conditional branch (B-type encoding).

    Cond { op: il::CmpOp, rs1: super::Reg, rs2: super::Reg },

    /// Inverted conditional branch (B-type encoding with negated condition).

    InvertedCond { op: il::CmpOp, rs1: super::Reg, rs2: super::Reg },

    /// Unconditional jump (J-type encoding).

    Jump,

}

/// Function call that needs offset patching.

pub record PendingCall {

    /// Index in code buffer where the call was emitted.

    index: u32,

    /// Target function name.

    target: *[u8],

}

/// Function address load that needs offset patching.

/// Used when taking a function's address as a value.

pub record PendingAddrLoad {

    /// Index in code buffer where the load was emitted.

    index: u32,

    /// Target function name.

    target: *[u8],

    /// Destination register.

    rd: super::Reg,

}

/// Function address entry for printing.

pub record FuncAddr {

    /// Function name.

    name: *[u8],

    /// Instruction index where this function starts.

    index: u32,

}

/// Debug entry mapping an instruction to a source location.

pub record DebugEntry {

    /// Byte offset of the instruction from the start of the program.

    pc: u32,

    /// Module identifier.

    moduleId: u16,

    /// Byte offset into the module's source file.

    offset: u32,

}

/// Adjusted base register and offset for addressing.

pub record AdjustedOffset {

    /// Base register.

    base: super::Reg,

    /// Byte offset from register.

    offset: i32,

}

/// Callee-saved register with its stack offset.

pub record SavedReg {

    /// Register to save/restore.

    reg: super::Reg,

    /// Offset from SP.

    offset: i32,

}

/// Emission context. Tracks state during code generation.

pub record Emitter {

    /// Emitted instructions storage.

    code: *mut [u32],

    /// Current number of emitted instructions.

    codeLen: u32,

    /// Local branches needing offset patching.

    pendingBranches: *mut [PendingBranch],

    /// Number of pending local branches.

    pendingBranchesLen: u32,

    /// Function calls needing offset patching.

    pendingCalls: *mut [PendingCall],

    /// Number of pending calls.

    pendingCallsLen: u32,

    /// Function address loads needing offset patching.

    pendingAddrLoads: *mut [PendingAddrLoad],

    /// Number of pending address loads.

    pendingAddrLoadsLen: u32,

    /// Block label tracking.

    labels: labels::Labels,

    /// Function start positions for printing.

    funcs: *mut [FuncAddr],

    /// Number of recorded functions.

    funcsLen: u32,

    /// Debug entries mapping PCs to source locations.

    debugEntries: *mut [DebugEntry],

    /// Number of debug entries recorded.

    debugEntriesLen: u32,

}

/// Computed stack frame layout for a function.

pub record Frame {

    /// Total frame size in bytes (aligned).

    totalSize: i32,

    /// Callee-saved registers and their offsets.

    // TODO: Use constant length when language supports it.

    savedRegs: [SavedReg; 11],

    /// Number of saved registers.

    savedRegsLen: u32,

    /// Epilogue block index for return jumps.

    epilogueBlock: u32,

}

/// Compute frame layout from local size and used callee-saved registers.

pub fn computeFrame(localSize: i32, usedCalleeSaved: u32, epilogueBlock: u32) -> Frame {

    let mut frame = Frame {

        totalSize: 0,

        savedRegs: undefined,

        savedRegsLen: 0,

        epilogueBlock,

    };

    // TODO: Skip frame allocation for leaf functions with no locals.

    // Compute total frame size. Includes RA and SP registers.

    let savedRegs = mem::popCount(usedCalleeSaved) + 2;

    let totalSize = mem::alignUpI32(

        localSize + savedRegs * super::DWORD_SIZE,

        super::STACK_ALIGNMENT

    );

    frame.totalSize = totalSize;

    // Build list of callee-saved registers with offsets.

    let mut offset = totalSize - (super::DWORD_SIZE * 3);

    for reg, i in super::CALLEE_SAVED {

        // Check if this register is in use.

        if (usedCalleeSaved & (1 << i)) != 0 {

            frame.savedRegs[frame.savedRegsLen] = SavedReg {

                reg,

                offset,

            };

            frame.savedRegsLen += 1;

            offset -= super::DWORD_SIZE;

        }

    }

    return frame;

}

/// Create a new emitter.

pub fn emitter(arena: *mut alloc::Arena, debug: bool) -> Emitter throws (alloc::AllocError) {

    let code = try alloc::allocSlice(arena, @sizeOf(u32), @alignOf(u32), MAX_INSTRS);

    let pendingBranches = try alloc::allocSlice(arena, @sizeOf(PendingBranch), @alignOf(PendingBranch), MAX_PENDING);

    let pendingCalls = try alloc::allocSlice(arena, @sizeOf(PendingCall), @alignOf(PendingCall), MAX_PENDING);

    let pendingAddrLoads = try alloc::allocSlice(arena, @sizeOf(PendingAddrLoad), @alignOf(PendingAddrLoad), MAX_PENDING);

    let blockOffsets = try alloc::allocSlice(arena, @sizeOf(i32), @alignOf(i32), labels::MAX_BLOCKS_PER_FN);

    let funcEntries = try alloc::allocSlice(arena, @sizeOf(dict::Entry), @alignOf(dict::Entry), labels::FUNC_TABLE_SIZE);

    let funcs = try alloc::allocSlice(arena, @sizeOf(FuncAddr), @alignOf(FuncAddr), MAX_FUNCS);

    let mut debugEntries: *mut [DebugEntry] = &mut [];

    if debug {

        debugEntries = try alloc::allocSlice(

            arena, @sizeOf(DebugEntry), @alignOf(DebugEntry), MAX_DEBUG_ENTRIES

        ) as *mut [DebugEntry];

    }

    return Emitter {

        code: code as *mut [u32],

        codeLen: 0,

        pendingBranches: pendingBranches as *mut [PendingBranch],

        pendingBranchesLen: 0,

        pendingCalls: pendingCalls as *mut [PendingCall],

        pendingCallsLen: 0,

        pendingAddrLoads: pendingAddrLoads as *mut [PendingAddrLoad],

        pendingAddrLoadsLen: 0,

        labels: labels::init(blockOffsets as *mut [i32], funcEntries as *mut [dict::Entry]),

        funcs: funcs as *mut [FuncAddr],

        funcsLen: 0,

        debugEntries,

        debugEntriesLen: 0,

    };

}

///////////////////////

// Emission Helpers  //

///////////////////////

/// Emit a single instruction.

pub fn emit(e: *mut Emitter, instr: u32) {

    if e.codeLen >= e.code.len {

        panic "emit: code buffer full";

    }

    e.code[e.codeLen] = instr;

    e.codeLen += 1;

}

/// Compute branch offset to a function by name.

pub fn branchOffsetToFunc(e: *Emitter, srcIndex: u32, name: *[u8]) -> i32 {

    return labels::branchToFunc(&e.labels, srcIndex, name, super::INSTR_SIZE);

}

/// Patch an instruction at a given index.

pub fn patch(e: *mut Emitter, index: u32, instr: u32) {

    e.code[index] = instr;

}

/// Record a block's address for branch resolution.

pub fn recordBlock(e: *mut Emitter, blockIdx: u32) {

    assert e.codeLen <= MAX_CODE_LEN;

    labels::recordBlock(&mut e.labels, blockIdx, e.codeLen as i32 * super::INSTR_SIZE);

}

/// Record a function's code offset for call resolution.

pub fn recordFuncOffset(e: *mut Emitter, name: *[u8]) {

    assert e.codeLen <= MAX_CODE_LEN;

    dict::insert(&mut e.labels.funcs, name, e.codeLen as i32 * super::INSTR_SIZE);

}

/// Record a function's start position for printing.

pub fn recordFunc(e: *mut Emitter, name: *[u8]) {

    if e.funcsLen >= e.funcs.len {

        panic "recordFunc: funcs buffer full";

    }

    e.funcs[e.funcsLen] = FuncAddr { name, index: e.codeLen };

    e.funcsLen += 1;

}

/// Record a local branch needing later patching.

/// Emits two placeholder instructions that will be patched later.

pub fn recordBranch(e: *mut Emitter, targetBlock: u32, kind: BranchKind) {

    if e.pendingBranchesLen >= e.pendingBranches.len {

        panic "recordBranch: buffer full";

    }

    e.pendingBranches[e.pendingBranchesLen] = PendingBranch {

        index: e.codeLen,

        target: targetBlock,

        kind: kind,

    };

    e.pendingBranchesLen += 1;

    emit(e, encode::nop()); // Placeholder for branch/auipc.

    emit(e, encode::nop()); // Placeholder for nop/jal/jalr.

}

/// Record a function call needing later patching.

/// Emits placeholder instructions that will be patched later.

/// Uses two slots to support long-distance calls.

pub fn recordCall(e: *mut Emitter, target: *[u8]) {

    if e.pendingCallsLen >= e.pendingCalls.len {

        panic "recordCall: buffer full";

    }

    e.pendingCalls[e.pendingCallsLen] = PendingCall {

        index: e.codeLen,

        target,

    };

    e.pendingCallsLen += 1;

    emit(e, encode::nop()); // Placeholder for AUIPC.

    emit(e, encode::nop()); // Placeholder for JALR.

}

/// Record a function address load needing later patching.

/// Emits placeholder instructions that will be patched to load the function's address.

/// Uses two slots to compute long-distance addresses.

pub fn recordAddrLoad(e: *mut Emitter, target: *[u8], rd: super::Reg) {

    if e.pendingAddrLoadsLen >= e.pendingAddrLoads.len {

        panic "recordAddrLoad: buffer full";

    }

    e.pendingAddrLoads[e.pendingAddrLoadsLen] = PendingAddrLoad {

        index: e.codeLen,

        target,

        rd: rd,

    };

    e.pendingAddrLoadsLen += 1;

    emit(e, encode::nop()); // Placeholder for AUIPC.

    emit(e, encode::nop()); // Placeholder for ADDI.

}

/// Patch local branches and clear the pending list.

///

/// Called after each function.

///

/// Uses two-instruction sequences: short branches use `branch` and `nop`,

/// long branches use inverted branch  and `jal` or `auipc` and `jalr`.

pub fn patchLocalBranches(e: *mut Emitter) {

    for i in 0..e.pendingBranchesLen {

        let p = e.pendingBranches[i];

        let offset = labels::branchToBlock(&e.labels, p.index, p.target, super::INSTR_SIZE);

        match p.kind {

            case BranchKind::Cond { op, rs1, rs2 } => {

                if encode::isBranchImm(offset) {

                    // Short: direct branch.

                    patch(e, p.index, encodeCondBranch(op, rs1, rs2, offset));

                    patch(e, p.index + 1, encode::nop());

                } else {

                    // Long: inverted branch skips `jal`; `jal` goes to target.

                    let adj = offset - super::INSTR_SIZE;

                    if not encode::isJumpImm(adj) {

                        panic "patchLocalBranches: branch offset too large";

                    }

                    patch(e, p.index, encodeInvertedBranch(op, rs1, rs2, super::INSTR_SIZE * 2));

                    patch(e, p.index + 1, encode::jal(super::ZERO, adj));

                }

            },

            case BranchKind::InvertedCond { op, rs1, rs2 } => {

                if encode::isBranchImm(offset) {

                    // Short: direct inverted branch.

                    patch(e, p.index, encodeInvertedBranch(op, rs1, rs2, offset));

                    patch(e, p.index + 1, encode::nop());

                } else {

                    // Long: non-inverted branch skips `jal`, jal goes to target.

                    let adj = offset - super::INSTR_SIZE;

                    if not encode::isJumpImm(adj) {

                        panic "patchLocalBranches: branch offset too large";

                    }

                    patch(e, p.index, encodeCondBranch(op, rs1, rs2, super::INSTR_SIZE * 2));

                    patch(e, p.index + 1, encode::jal(super::ZERO, adj));

                }

            },

            case BranchKind::Jump => {

                if encode::isJumpImm(offset) {

                    patch(e, p.index, encode::jal(super::ZERO, offset));

                    patch(e, p.index + 1, encode::nop());

                } else {

                    let s = splitImm(offset);

                    patch(e, p.index, encode::auipc(super::SCRATCH1, s.hi));

                    patch(e, p.index + 1, encode::jalr(super::ZERO, super::SCRATCH1, s.lo));

                }

            },

        }

    }

    e.pendingBranchesLen = 0;

}

/// Encode a conditional branch instruction.

fn encodeCondBranch(op: il::CmpOp, rs1: super::Reg, rs2: super::Reg, offset: i32) -> u32 {

    match op {

        case il::CmpOp::Eq => return encode::beq(rs1, rs2, offset),

        case il::CmpOp::Ne => return encode::bne(rs1, rs2, offset),

        case il::CmpOp::Slt => return encode::blt(rs1, rs2, offset),

        case il::CmpOp::Ult => return encode::bltu(rs1, rs2, offset),

    }

}

/// Encode an inverted conditional branch instruction.

fn encodeInvertedBranch(op: il::CmpOp, rs1: super::Reg, rs2: super::Reg, offset: i32) -> u32 {

    match op {

        case il::CmpOp::Eq => return encode::bne(rs1, rs2, offset),

        case il::CmpOp::Ne => return encode::beq(rs1, rs2, offset),

        case il::CmpOp::Slt => return encode::bge(rs1, rs2, offset),

        case il::CmpOp::Ult => return encode::bgeu(rs1, rs2, offset),

    }

}

/// Patch all pending function calls.

/// Called after all functions have been generated.

pub fn patchCalls(e: *mut Emitter) {

    for i in 0..e.pendingCallsLen {

        let p = e.pendingCalls[i];

        let offset = branchOffsetToFunc(e, p.index, p.target);

        let s = splitImm(offset);

        // `AUIPC scratch, hi(offset)`.

        patch(e, p.index, encode::auipc(super::SCRATCH1, s.hi));

        // `JALR ra, scratch, lo(offset)`.

        patch(e, p.index + 1, encode::jalr(super::RA, super::SCRATCH1, s.lo));

    }

}

/// Patch all pending function address loads.

/// Called after all functions have been generated.

/// Uses PC-relative addresses up to 2GB away.

pub fn patchAddrLoads(e: *mut Emitter) {

    for i in 0..e.pendingAddrLoadsLen {

        let p = e.pendingAddrLoads[i];

        let offset = branchOffsetToFunc(e, p.index, p.target);

        let s = splitImm(offset);

        // `AUIPC rd, hi(offset)`.

        patch(e, p.index, encode::auipc(p.rd, s.hi));

        // `ADDI rd, rd, lo(offset)`.

        patch(e, p.index + 1, encode::addi(p.rd, p.rd, s.lo));

    }

}

/////////////////////////

// Immediate Handling  //

/////////////////////////

/// Split immediate into `hi` and `lo` bits.

pub record SplitImm {

    /// Upper 20 bits.

    hi: i32,

    /// Lower 12 bits.

    lo: i32,

}

/// Split a 32-bit immediate for `AUIPC, ADDI` / `JALR` sequences.

/// Handles sign extension: if *lo* is negative, increment *hi*.

pub fn splitImm(imm: i32) -> SplitImm {

    let lo = imm & 0xFFF;

    let mut hi = (imm >> 12) & 0xFFFFF;

    // If `lo`'s sign bit is set, it will be sign-extended to negative.

    // Compensate by incrementing `hi`.

    if (lo & 0x800) != 0 {

        hi += 1;

        return SplitImm { hi, lo: lo | 0xFFFFF000 as i32 };

    }

    return SplitImm { hi, lo };

}

/// Adjust a large offset by loading *hi* bits into [`super::ADDR_SCRATCH`].

/// Returns adjusted base register and remaining offset.

///

/// When the offset fits a 12-bit signed immediate, returns it unchanged.

/// Otherwise uses [`super::ADDR_SCRATCH`] for the LUI+ADD decomposition.

fn adjustOffset(e: *mut Emitter, base: super::Reg, offset: i32) -> AdjustedOffset {

    if offset >= super::MIN_IMM and offset <= super::MAX_IMM {

        return AdjustedOffset { base, offset };

    }

    let s = splitImm(offset);

    emit(e, encode::lui(super::ADDR_SCRATCH, s.hi));

    emit(e, encode::add(super::ADDR_SCRATCH, super::ADDR_SCRATCH, base));

    return AdjustedOffset { base: super::ADDR_SCRATCH, offset: s.lo };

}

/// Load an immediate value into a register.

/// Handles the full range of 64-bit immediates.

/// For values fitting in 12 bits, uses a single `ADDI`.

/// For values fitting in 32 bits, uses `LUI` + `ADDIW`.

/// For wider values, loads upper and lower halves then combines with shift and add.

pub fn loadImm(e: *mut Emitter, rd: super::Reg, imm: i64) {

    let immMin = super::MIN_IMM as i64;

    let immMax = super::MAX_IMM as i64;

    if imm >= immMin and imm <= immMax {

        emit(e, encode::addi(rd, super::ZERO, imm as i32));

        return;

    }

    // Check if the value fits in 32 bits (sign-extended).

    let lo32 = imm as i32;

    if lo32 as i64 == imm {

        let s = splitImm(lo32);

        emit(e, encode::lui(rd, s.hi));

        if s.lo != 0 {

            emit(e, encode::addiw(rd, rd, s.lo));

        }

        return;

    }

    // Full 64-bit immediate: use only rd, no scratch registers.

    // Load upper 32 bits first via the 32-bit path (LUI+ADDIW),

    // then shift and add lower bits in 11-bit groups to avoid

    // sign-extension issues with ADDI's 12-bit signed immediate.

    let hi32 = (imm >> 32) as i32;

    let lower = imm as i32;

    // Load upper 32 bits.

    loadImm(e, rd, hi32 as i64);

    // Shift left by 11, add bits [31:21].

    emit(e, encode::slli(rd, rd, 11));

    emit(e, encode::addi(rd, rd, (lower >> 21) & 0x7FF));

    // Shift left by 11, add bits [20:10].

    emit(e, encode::slli(rd, rd, 11));

    emit(e, encode::addi(rd, rd, (lower >> 10) & 0x7FF));

    // Shift left by 10, add bits [9:0].

    emit(e, encode::slli(rd, rd, 10));

    emit(e, encode::addi(rd, rd, lower & 0x3FF));

}

/// Emit add-immediate, handling large immediates.

pub fn emitAddImm(e: *mut Emitter, rd: super::Reg, rs: super::Reg, imm: i32) {

    if imm >= super::MIN_IMM and imm <= super::MAX_IMM {

        emit(e, encode::addi(rd, rs, imm));

    } else {

        loadImm(e, super::SCRATCH1, imm as i64);

        emit(e, encode::add(rd, rs, super::SCRATCH1));

    }

}

////////////////////////

// Load/Store Helpers //

////////////////////////

/// Emit unsigned load with automatic offset adjustment.

pub fn emitLoad(e: *mut Emitter, rd: super::Reg, base: super::Reg, offset: i32, typ: il::Type) {

    let adj = adjustOffset(e, base, offset);

    match typ {

        case il::Type::W8 => emit(e, encode::lbu(rd, adj.base, adj.offset)),

        case il::Type::W16 => emit(e, encode::lhu(rd, adj.base, adj.offset)),

        case il::Type::W32 => emit(e, encode::lw(rd, adj.base, adj.offset)),

        case il::Type::W64 => emit(e, encode::ld(rd, adj.base, adj.offset)),

    }

}

/// Emit signed load with automatic offset adjustment.

pub fn emitSload(e: *mut Emitter, rd: super::Reg, base: super::Reg, offset: i32, typ: il::Type) {

    let adj = adjustOffset(e, base, offset);

    match typ {

        case il::Type::W8 => emit(e, encode::lb(rd, adj.base, adj.offset)),

        case il::Type::W16 => emit(e, encode::lh(rd, adj.base, adj.offset)),

        case il::Type::W32 => emit(e, encode::lw(rd, adj.base, adj.offset)),

        case il::Type::W64 => emit(e, encode::ld(rd, adj.base, adj.offset)),

    }

}

/// Emit store with automatic offset adjustment.

pub fn emitStore(e: *mut Emitter, rs: super::Reg, base: super::Reg, offset: i32, typ: il::Type) {

    let adj = adjustOffset(e, base, offset);

    match typ {

        case il::Type::W8 => emit(e, encode::sb(rs, adj.base, adj.offset)),

        case il::Type::W16 => emit(e, encode::sh(rs, adj.base, adj.offset)),

        case il::Type::W32 => emit(e, encode::sw(rs, adj.base, adj.offset)),

        case il::Type::W64 => emit(e, encode::sd(rs, adj.base, adj.offset)),

    }

}

/// Emit 64-bit load with automatic offset adjustment.

pub fn emitLd(e: *mut Emitter, rd: super::Reg, base: super::Reg, offset: i32) {

    let adj = adjustOffset(e, base, offset);

    emit(e, encode::ld(rd, adj.base, adj.offset));

}

/// Emit 64-bit store with automatic offset adjustment.

pub fn emitSd(e: *mut Emitter, rs: super::Reg, base: super::Reg, offset: i32) {

    let adj = adjustOffset(e, base, offset);

    emit(e, encode::sd(rs, adj.base, adj.offset));

}

/// Emit 32-bit load with automatic offset adjustment.

pub fn emitLw(e: *mut Emitter, rd: super::Reg, base: super::Reg, offset: i32) {

    let adj = adjustOffset(e, base, offset);

    emit(e, encode::lw(rd, adj.base, adj.offset));

}

/// Emit 32-bit store with automatic offset adjustment.

pub fn emitSw(e: *mut Emitter, rs: super::Reg, base: super::Reg, offset: i32) {

    let adj = adjustOffset(e, base, offset);

    emit(e, encode::sw(rs, adj.base, adj.offset));

}

/// Emit 8-bit load with automatic offset adjustment.

pub fn emitLb(e: *mut Emitter, rd: super::Reg, base: super::Reg, offset: i32) {

    let adj = adjustOffset(e, base, offset);

    emit(e, encode::lb(rd, adj.base, adj.offset));

}

/// Emit 8-bit store with automatic offset adjustment.

pub fn emitSb(e: *mut Emitter, rs: super::Reg, base: super::Reg, offset: i32) {

    let adj = adjustOffset(e, base, offset);

    emit(e, encode::sb(rs, adj.base, adj.offset));

}

//////////////////////////

// Prologue / Epilogue  //

//////////////////////////

/// Emit function prologue.

/// Allocates stack frame, saves RA/FP, saves callee-saved registers.

pub fn emitPrologue(e: *mut Emitter, frame: *Frame) {

    // Fast path: leaf function with no locals.

    if frame.totalSize == 0 {

        return;

    }

    let totalSize = frame.totalSize;

    // Allocate stack frame.

    let negFrame = 0 - totalSize;

    if negFrame >= super::MIN_IMM {

        emit(e, encode::addi(super::SP, super::SP, negFrame));

    } else {

        loadImm(e, super::SCRATCH1, totalSize as i64);

        emit(e, encode::sub(super::SP, super::SP, super::SCRATCH1));

    }

    // Save return address and frame pointer.

    emitSd(e, super::RA, super::SP, totalSize - super::DWORD_SIZE);

    emitSd(e, super::FP, super::SP, totalSize - super::DWORD_SIZE * 2);

    // Set up frame pointer.

    emitAddImm(e, super::FP, super::SP, totalSize);

    // Save callee-saved registers.

    for i in 0..frame.savedRegsLen {

        let sr = frame.savedRegs[i];

        emitSd(e, sr.reg, super::SP, sr.offset);

    }

}

/// Emit a return: jump to epilogue.

pub fn emitReturn(e: *mut Emitter, frame: *Frame) {

    recordBranch(e, frame.epilogueBlock, BranchKind::Jump);

}

/// Emit function epilogue.

/// Restores callee-saved registers, `RA/FP`, deallocates frame, returns.

pub fn emitEpilogue(e: *mut Emitter, frame: *Frame) {

    // Record epilogue block address for return jumps.

    recordBlock(e, frame.epilogueBlock);

    // Fast path: leaf function with no locals.

    if frame.totalSize == 0 {

        emit(e, encode::ret());

        return;

    }

    let totalSize = frame.totalSize;

    // Restore SP to post-prologue value. Required if we performed dynamic

    // stack allocation, as SP may have moved.

    //

    // Since we set FP to `SP + totalSize`, we now set SP to `FP - totalSize`.

    emitAddImm(e, super::SP, super::FP, 0 - totalSize);

    // Restore callee-saved registers.

    for i in 0..frame.savedRegsLen {

        let sr = frame.savedRegs[i];

        emitLd(e, sr.reg, super::SP, sr.offset);

    }

    // Restore frame pointer and return address.

    emitLd(e, super::FP, super::SP, totalSize - super::DWORD_SIZE * 2);

    emitLd(e, super::RA, super::SP, totalSize - super::DWORD_SIZE);

    // Deallocate stack frame.

    emitAddImm(e, super::SP, super::SP, totalSize);

    emit(e, encode::ret());

}

//////////////////

// Code Access  //

//////////////////

/// Get emitted code as a slice.

pub fn getCode(e: *Emitter) -> *[u32] {

    return &e.code[..e.codeLen];

}

/// Get function addresses for printing.

pub fn getFuncs(e: *Emitter) -> *[FuncAddr] {

    return &e.funcs[..e.funcsLen];

}

/// Record a debug entry mapping the current PC to a source location.

/// Deduplicates consecutive entries with the same location.

pub fn recordSrcLoc(e: *mut Emitter, loc: il::SrcLoc) {

    let pc = e.codeLen * super::INSTR_SIZE as u32;

    // Skip if this is the same location as the previous entry.

    if e.debugEntriesLen > 0 {

        let prev = &e.debugEntries[e.debugEntriesLen - 1];

        if prev.offset == loc.offset and prev.moduleId == loc.moduleId {

            return;

        }

    }

    if e.debugEntriesLen >= e.debugEntries.len {

        panic "recordSrcLoc: debug entry buffer full";

    }

    e.debugEntries[e.debugEntriesLen] = DebugEntry {

        pc,

        moduleId: loc.moduleId,

        offset: loc.offset,

    };

    e.debugEntriesLen += 1;

}

/// Get debug entries as a slice.

pub fn getDebugEntries(e: *Emitter) -> *[DebugEntry] {

    return &e.debugEntries[..e.debugEntriesLen];

}