//! RV64 binary emission.

//!

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

use std::lang::il;

use std::lang::alloc;

use std::lang::gen;

use std::lang::gen::data;

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

use std::lang::gen::types;

use std::collections::dict;

use std::mem;

use super::encode;

/// Maximum number of instructions in code buffer.

export constant MAX_INSTRS: u32 = 2097152;

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

constant MAX_CODE_LEN: u32 = 0x7FFFFFFF / super::INSTR_SIZE as u32;

/// Maximum number of pending branches awaiting patching.

export constant MAX_PENDING: u32 = 65536;

/// Maximum number of function entries.

export constant MAX_FUNCS: u32 = 4096;

/// Maximum number of debug entries.

export constant MAX_DEBUG_ENTRIES: u32 = 524288;

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

// Emission Context //

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

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

export record PendingBranch: Copy {

    /// 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.

export union BranchKind: Copy {

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

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

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

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

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

    Jump,

}

/// Function call that needs offset patching.

export record PendingCall: Copy {

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

    index: u32,

    /// Target function name.

    target: *[u8],

}

/// Assembly jump that needs offset patching after all text is emitted.

export record PendingJump: Copy {

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

    index: u32,

    /// Target function name.

    target: *[u8],

    /// Destination register.

    rd: gen::Reg,

}

/// Address load that needs patching after layout is known.

export record PendingAddrLoad: Copy {

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

    index: u32,

    /// Target function or data symbol name.

    target: *[u8],

    /// Destination register.

    rd: gen::Reg,

    /// Whether this is an absolute data symbol address.

    isData: bool,

}

/// Adjusted base register and offset for addressing.

export record AdjustedOffset: Copy {

    /// Base register.

    base: gen::Reg,

    /// Byte offset from register.

    offset: i32,

}

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

export record SavedReg: Copy {

    /// Register to save/restore.

    reg: gen::Reg,

    /// Offset from SP.

    offset: i32,

}

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

export record Emitter {

    /// First failure. Further emission stops until the workspace is rebuilt.

    error: ?super::Error,

    /// Data address loads use the current domain package-state table.

    sharedData: bool,

    /// Emitted instructions storage.

    code: *mut [u32],

    /// Current number of emitted instructions.

    codeLen: u32,

    /// Local branches needing offset patching.

    pendingBranches: *mut [PendingBranch],

    /// Number of local branches that need patching.

    pendingBranchesLen: u32,

    /// Function calls needing offset patching.

    pendingCalls: *mut [PendingCall],

    /// Number of function calls that need patching.

    pendingCallsLen: u32,

    /// Assembly jumps needing offset patching.

    pendingJumps: *mut [PendingJump],

    /// Number of assembly jumps that need patching.

    pendingJumpsLen: u32,

    /// Function address loads needing offset patching.

    pendingAddrLoads: *mut [PendingAddrLoad],

    /// Number of function address loads that need patching.

    pendingAddrLoadsLen: u32,

    /// Block label tracking.

    labels: labels::Labels,

    /// Function start positions for printing.

    funcs: *mut [types::FuncAddr],

    /// Number of function start positions recorded.

    funcsLen: u32,

    /// Debug entries mapping PCs to source locations.

    debugEntries: *mut [types::DebugEntry],

    /// Number of debug entries recorded.

    debugEntriesLen: u32,

}

/// Caller-owned storage for program emission.

export record Storage {

    /// Emitted instruction buffer.

    code: *mut [u32],

    /// Local branch patch buffer.

    pendingBranches: *mut [PendingBranch],

    /// Function call patch buffer.

    pendingCalls: *mut [PendingCall],

    /// Assembly jump patch buffer.

    pendingJumps: *mut [PendingJump],

    /// Address load patch buffer.

    pendingAddrLoads: *mut [PendingAddrLoad],

    /// Per-function block offset buffer.

    blockOffsets: *mut [i32],

    /// Function label hash table storage.

    funcEntries: *mut [dict::Entry],

    /// Printed function address buffer.

    funcs: *mut [types::FuncAddr],

    /// Debug location buffer.

    debugEntries: *mut [types::DebugEntry],

}

/// Computed stack frame layout for a function.

export record Frame: Copy {

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

    totalSize: i32,

    /// Callee-saved registers and their offsets.

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

    savedRegs: [SavedReg; super::NUM_SAVED_REGISTERS],

    /// Number of saved registers.

    savedRegsLen: u32,

    /// Epilogue block index for return jumps.

    epilogueBlock: u32,

    /// Whether this is a leaf function. Leaf functions

    /// skip saving/restoring RA since it is never clobbered.

    isLeaf: bool,

    /// Whether the function has dynamic stack allocations.

    /// When false, SP never changes after the prologue.

    isDynamic: bool,

}

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

export fn computeFrame(localSize: i32, usedCalleeSaved: u32, epilogueBlock: u32, isLeaf: bool, isDynamic: bool) -> Frame {

    let mut frame = Frame {

        totalSize: 0,

        savedRegs: [SavedReg { reg: super::ZERO, offset: 0 }; super::NUM_SAVED_REGISTERS],

        savedRegsLen: 0,

        epilogueBlock,

        isLeaf,

        isDynamic,

    };

    // Skip frame allocation for leaf functions with no locals and no

    // callee-saved registers. Leaf functions don't call other functions,

    // so RA is never clobbered and doesn't need saving.

    if isLeaf and localSize == 0 and usedCalleeSaved == 0 {

        return frame;

    }

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

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

    let totalSize = mem::alignUpI32(

        localSize + savedRegs * super::DWORD_SIZE,

        super::STACK_ALIGNMENT

    );

    set 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 {

            set frame.savedRegs[frame.savedRegsLen] = SavedReg {

                reg,

                offset,

            };

            set frame.savedRegsLen += 1;

            set offset -= super::DWORD_SIZE;

        }

    }

    return frame;

}

/// Create a new emitter.

export unsafe fn emitter(arena: &mut alloc::Arena, debug: bool) -> Emitter throws (alloc::AllocError) {

    let storage = try allocateStorage(arena, debug);

    return emitterWithStorage(storage, debug);

}

/// Allocate emitter storage from an arena.

export unsafe fn allocateStorage(arena: &mut alloc::Arena, debug: bool) -> Storage 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 pendingJumps = try alloc::allocSlice(arena, @sizeOf(PendingJump), @alignOf(PendingJump), 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(types::FuncAddr), @alignOf(types::FuncAddr), MAX_FUNCS);

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

    if debug {

        set debugEntries = try alloc::allocSlice(

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

        ) as *mut [types::DebugEntry];

    }

    return Storage {

        code: code as *mut [u32],

        pendingBranches: pendingBranches as *mut [PendingBranch],

        pendingCalls: pendingCalls as *mut [PendingCall],

        pendingJumps: pendingJumps as *mut [PendingJump],

        pendingAddrLoads: pendingAddrLoads as *mut [PendingAddrLoad],

        blockOffsets: blockOffsets as *mut [i32],

        funcEntries: funcEntries as *mut [dict::Entry],

        funcs: funcs as *mut [types::FuncAddr],

        debugEntries,

    };

}

/// Create an emitter from caller-owned storage.

export fn emitterWithStorage(storage: Storage, debug: bool) -> Emitter {

    let case Storage {

        code, pendingBranches, pendingCalls, pendingJumps, pendingAddrLoads,

        blockOffsets, funcEntries, funcs, debugEntries,

    } = storage else panic "expected emitter storage";

    assert code.len >= MAX_INSTRS, "emitterWithStorage: code buffer too small";

    assert pendingBranches.len >= MAX_PENDING, "emitterWithStorage: branch buffer too small";

    assert pendingCalls.len >= MAX_PENDING, "emitterWithStorage: call buffer too small";

    assert pendingJumps.len >= MAX_PENDING, "emitterWithStorage: jump buffer too small";

    assert pendingAddrLoads.len >= MAX_PENDING, "emitterWithStorage: address buffer too small";

    assert blockOffsets.len >= labels::MAX_BLOCKS_PER_FN, "emitterWithStorage: block buffer too small";

    assert funcEntries.len >= labels::FUNC_TABLE_SIZE, "emitterWithStorage: label table too small";

    assert funcs.len >= MAX_FUNCS, "emitterWithStorage: function buffer too small";

    let mut activeDebugEntries: *mut [types::DebugEntry] = &mut [];

    if debug {

        assert debugEntries.len >= MAX_DEBUG_ENTRIES, "emitterWithStorage: debug buffer too small";

        set activeDebugEntries = debugEntries;

    }

    return Emitter {

        error: nil,

        sharedData: false,

        code,

        codeLen: 0,

        pendingBranches,

        pendingBranchesLen: 0,

        pendingCalls,

        pendingCallsLen: 0,

        pendingJumps,

        pendingJumpsLen: 0,

        pendingAddrLoads,

        pendingAddrLoadsLen: 0,

        labels: labels::init(blockOffsets, funcEntries),

        funcs,

        funcsLen: 0,

        debugEntries: activeDebugEntries,

        debugEntriesLen: 0,

    };

}

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

// Emission Helpers  //

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

/// Emit a single instruction.

export fn emit(e: &mut Emitter, instr: u32) {

    if e.error <> nil {

        return;

    }

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

        set e.error = super::Error::Capacity;

        return;

    }

    set e.code[e.codeLen] = instr;

    set e.codeLen += 1;

}

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

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

    if e.error <> nil {

        return 0;

    }

    let target = dict::get(&e.labels.funcs, name) else {

        set e.error = super::Error::Symbol; return 0;

    };

    return target - srcIndex as i32 * super::INSTR_SIZE;

}

/// Patch an instruction at a given index.

export fn patch(e: &mut Emitter, index: u32, instr: u32) {

    if e.error <> nil {

        return;

    }

    if index >= e.codeLen {

        set e.error = super::Error::Capacity;

        return;

    }

    set e.code[index] = instr;

}

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

export fn recordBlock(e: &mut Emitter, blockIdx: u32) {

    if e.error <> nil {

        return;

    }

    if e.codeLen > MAX_CODE_LEN or blockIdx >= e.labels.blockOffsets.len {

        set e.error = super::Error::Capacity; return;

    }

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

}

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

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

    let codeLen = e.codeLen;

    recordFuncOffsetAt(e, name, codeLen);

}

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

export fn recordFuncOffsetAt(e: &mut Emitter, name: *[u8], index: u32) {

    if e.error <> nil {

        return;

    }

    if index > MAX_CODE_LEN {

        set e.error = super::Error::Capacity;

        return;

    }

    if name.len == 0 {

        set e.error = super::Error::Symbol;

        return;

    }

    if e.labels.funcs.count >= e.labels.funcs.entries.len / 2 and dict::get(&e.labels.funcs, name) == nil {

        set e.error = super::Error::Capacity; return;

    }

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

}

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

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

    let codeLen = e.codeLen;

    recordFuncAt(e, name, codeLen);

}

/// Record a function's start position at `index` for printing.

export fn recordFuncAt(e: &mut Emitter, name: *[u8], index: u32) {

    if e.error <> nil {

        return;

    }

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

        set e.error = super::Error::Capacity;

        return;

    }

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

    set e.funcsLen += 1;

}

/// Record a local branch needing later patching.

/// Unconditional jumps use a single slot (J-type, +-1MB range).

/// Conditional branches use two slots (B-type has only +-4KB range,

/// so large functions may need the inverted-branch + JAL fallback).

export fn recordBranch(e: &mut Emitter, targetBlock: u32, kind: BranchKind) {

    if e.error <> nil {

        return;

    }

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

        set e.error = super::Error::Capacity;

        return;

    }

    set e.pendingBranches[e.pendingBranchesLen] = PendingBranch {

        index: e.codeLen,

        target: targetBlock,

        kind,

    };

    set e.pendingBranchesLen += 1;

    emit(e, encode::nop()); // First slot, always needed.

    match kind {

        case BranchKind::Jump => {},

        else => emit(e, encode::nop()), // Second slot for conditional branches.

    }

}

/// Record a function call needing later patching.

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

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

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

    if e.error <> nil {

        return;

    }

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

        set e.error = super::Error::Capacity;

        return;

    }

    set e.pendingCalls[e.pendingCallsLen] = PendingCall {

        index: e.codeLen,

        target,

    };

    set e.pendingCallsLen += 1;

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

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

}

/// Record a jump emitted by assembly that needs whole-program patching.

export fn recordJumpAt(e: &mut Emitter, target: *[u8], rd: gen::Reg, index: u32) {

    if e.error <> nil {

        return;

    }

    if e.pendingJumpsLen == e.pendingJumps.len {

        set e.error = super::Error::Capacity;

        return;

    }

    set e.pendingJumps[e.pendingJumpsLen] = PendingJump {

        index,

        target,

        rd,

    };

    set e.pendingJumpsLen += 1;

}

/// 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.

export fn recordAddrLoad(e: &mut Emitter, target: *[u8], rd: gen::Reg) {

    let codeLen = e.codeLen;

    recordAddrLoadAt(e, target, rd, codeLen);

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

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

}

/// Record a function address load already reserved by assembly.

export fn recordAddrLoadAt(e: &mut Emitter, target: *[u8], rd: gen::Reg, index: u32) {

    if e.error <> nil {

        return;

    }

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

        set e.error = super::Error::Capacity;

        return;

    }

    set e.pendingAddrLoads[e.pendingAddrLoadsLen] = PendingAddrLoad {

        index,

        target,

        rd,

        isData: false,

    };

    set e.pendingAddrLoadsLen += 1;

}

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

/// Reserves two instructions for a PC-relative address load.

export fn recordDataAddrLoad(e: &mut Emitter, target: *[u8], rd: gen::Reg) {

    if e.error <> nil {

        return;

    }

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

        set e.error = super::Error::Capacity;

        return;

    }

    set e.pendingAddrLoads[e.pendingAddrLoadsLen] = PendingAddrLoad {

        index: e.codeLen,

        target,

        rd,

        isData: true,

    };

    set e.pendingAddrLoadsLen += 1;

    emit(e, encode::nop()); // Address-load upper instruction.

    emit(e, encode::nop()); // Address-load lower instruction.

    if e.sharedData {

        emit(e, encode::nop()); // Package offset addition.

        emit(e, encode::nop()); // Package offset low bits.

    }

}

/// 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`.

export unsafe fn patchLocalBranches(e: &mut Emitter) {

    if e.error <> nil {

        return;

    }

    for i in 0..e.pendingBranchesLen {

        let p = e.pendingBranches[i];

        if p.target >= e.labels.blockCount {

            set e.error = super::Error::Symbol;

            return;

        }

        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) {

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

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

                } else {

                    let adj = offset - super::INSTR_SIZE;

                    if not encode::isJumpImm(adj) {

                        set e.error = super::Error::Relocation;

                        return;

                    }

                    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) {

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

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

                } else {

                    let adj = offset - super::INSTR_SIZE;

                    if not encode::isJumpImm(adj) {

                        set e.error = super::Error::Relocation;

                        return;

                    }

                    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 => {

                // Single-slot jump (J-type, +-1MB range).

                if not encode::isJumpImm(offset) {

                    set e.error = super::Error::Relocation;

                    return;

                }

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

            },

        }

    }

    set e.pendingBranchesLen = 0;

}

/// Encode a conditional branch instruction.

fn encodeCondBranch(op: il::CmpOp, rs1: gen::Reg, rs2: gen::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: gen::Reg, rs2: gen::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.

export fn patchCalls(e: &mut Emitter) {

    for i in 0..e.pendingCallsLen {

        let p = e.pendingCalls[i];

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

        if offset > 0x7ffff7ff {

            set e.error = super::Error::Relocation;

            return;

        }

        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 assembly jumps.

export fn patchJumps(e: &mut Emitter) {

    for i in 0..e.pendingJumpsLen {

        let p = e.pendingJumps[i];

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

        if not encode::isJumpImm(offset) {

            set e.error = super::Error::Relocation;

            return;

        }

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

    }

}

/// Patch all pending function and data address loads.

/// Called after all functions have been generated and data layout is known.

export fn patchAddrLoads(e: &mut Emitter, dataSymMap: &data::DataSymMap, codeBase: u64) throws (super::Error) {

    try check(e);

    for i in 0..e.pendingAddrLoadsLen {

        let p = e.pendingAddrLoads[i];

        if p.isData {

            let addr = data::lookupAddr(dataSymMap, p.target) else {

                throw super::Error::Symbol;

            };

            let offset = super::image::displacement(codeBase + p.index as u64 * 4, addr) else {

                throw super::Error::Relocation;

            };

            let s = splitImm(offset);

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

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

            continue;

        }

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

        if offset > 0x7ffff7ff {

            set e.error = super::Error::Relocation;

            return;

        }

        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));

    }

    try check(e);

}

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

// Immediate Handling  //

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

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

export record SplitImm: Copy {

    /// 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*.

export 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 {

        set 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: gen::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.

export fn loadImm(e: &mut Emitter, rd: gen::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));

    let chunkHi = (lower >> 21) & 0x7FF;

    if chunkHi <> 0 {

        emit(e, encode::addi(rd, rd, chunkHi));

    }

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

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

    let chunkMid = (lower >> 10) & 0x7FF;

    if chunkMid <> 0 {

        emit(e, encode::addi(rd, rd, chunkMid));

    }

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

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

    let chunkLo = lower & 0x3FF;

    if chunkLo <> 0 {

        emit(e, encode::addi(rd, rd, chunkLo));

    }

}

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

export fn emitAddImm(e: &mut Emitter, rd: gen::Reg, rs: gen::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.

export fn emitLoad(e: &mut Emitter, rd: gen::Reg, base: gen::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::lwu(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.

export fn emitSload(e: &mut Emitter, rd: gen::Reg, base: gen::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.

export fn emitStore(e: &mut Emitter, rs: gen::Reg, base: gen::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.

export fn emitLd(e: &mut Emitter, rd: gen::Reg, base: gen::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.

export fn emitSd(e: &mut Emitter, rs: gen::Reg, base: gen::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.

export fn emitLw(e: &mut Emitter, rd: gen::Reg, base: gen::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.

export fn emitSw(e: &mut Emitter, rs: gen::Reg, base: gen::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.

export fn emitLb(e: &mut Emitter, rd: gen::Reg, base: gen::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.

export fn emitSb(e: &mut Emitter, rs: gen::Reg, base: gen::Reg, offset: i32) {

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

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

}

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

// Prologue / Epilogue  //

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

/// Emit function prologue.

/// Allocate the frame and save registers. Save FP only for dynamic frames.

export 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.

    if not frame.isLeaf {

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

    }

    // Save and set FP only when dynamic allocations can move SP.

    if frame.isDynamic {

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

        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, or emit `ret` directly for leaf functions.

export fn emitReturn(e: &mut Emitter, frame: &Frame) {

    if frame.totalSize == 0 {

        // Leaf function: no frame to tear down, emit ret directly.

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

        return;

    }

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

}

/// Emit function epilogue.

/// Restore saved registers and release the frame. Restore FP only for dynamic frames.

export 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. Only needed when dynamic stack

    // allocation may have moved SP.

    if frame.isDynamic {

        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 FP only if the prologue saved and changed it.

    if frame.isDynamic {

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

    }

    // Restore return address.

    if not frame.isLeaf {

        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.

export fn getCode 'code (e: &'code Emitter) -> &'code [u32] {

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

}

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

/// Deduplicates consecutive entries with the same location.

export fn recordSrcLoc(e: &mut Emitter, loc: il::SrcLoc) {

    if e.error <> nil {

        return;

    }

    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 {

        set e.error = super::Error::Capacity;

        return;

    }

    set e.debugEntries[e.debugEntriesLen] = types::DebugEntry {

        pc,

        moduleId: loc.moduleId,

        offset: loc.offset,

    };

    set e.debugEntriesLen += 1;

}

/// Get debug entries as a slice.

export fn getDebugEntries 'code (e: &'code Emitter) -> &'code [types::DebugEntry] {

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

}

/// Return the first emission failure before any generated output is published.

export fn check(e: &Emitter) throws (super::Error) {

    if let error = e.error {

        throw error;

    }

}