llvm-native-core 0.1.5

//! X86 Frame Lowering — stack frame management for X86/X86-64 targets.
//!
//! Handles function prologue/epilogue emission, frame pointer management,
//! callee-saved register spill/restore, and frame size calculation.
//!
//! Supported ABIs:
//! - System V AMD64 (Linux, macOS, FreeBSD)
//! - Microsoft x64 (Windows)
//! - IA-32 (32-bit, cdecl/stdcall/fastcall)
//!
//! Frame layout (System V AMD64, frame pointer used):
//! ```text
//!         +----------------------+  <- high address (previous frame)
//!         |   Return Address     |  (pushed by CALL)
//!   %rbp  +----------------------+
//!         |   Previous %rbp      |  (pushed by prologue)
//!   -8    +----------------------+
//!         |   Saved Regs (RBX,   |
//!         |   R12-R15 as needed) |
//!         +----------------------+
//!         |   Local variables    |
//!         |   (allocas, spills)  |
//!         +----------------------+
//!         |   Outgoing args      |  (for calls within this function)
//!   %rsp  +----------------------+  <- low address
//! ```
//!
//! Red zone: On System V AMD64, the 128 bytes below %rsp are reserved
//! and may be used without adjusting %rsp, provided the function is a leaf
//! (makes no calls).
//!
//! Clean-room reconstruction from:
//! - System V Application Binary Interface: AMD64 Architecture Processor Supplement
//! - Microsoft x64 Software Conventions
//! - Intel® 64 and IA-32 Architectures Software Developer's Manual
//!
//! Zero LLVM source code consultation.

use crate::codegen::{MachineBasicBlock, MachineFunction, MachineInstr, MachineOperand, VirtReg};
use crate::x86::x86_instr_info::{X86InstrInfo, X86Opcode, RBP_CONST, RSP_CONST};
use crate::x86::x86_register_info::{EAX, R10, R11, R9, RAX, RBP, RSP};
use std::collections::HashMap;

// ============================================================================
// Constants
// ============================================================================

/// Size of the System V AMD64 red zone (128 bytes below %rsp).
pub const RED_ZONE_SIZE: i64 = 128;

/// Standard stack alignment for System V AMD64 ABI: 16 bytes.
pub const STACK_ALIGNMENT: i64 = 16;

/// Size of a GPR push on x86-64 (8 bytes).
pub const PUSH_SIZE_64: i64 = 8;

/// Size of a GPR push on x86-32 (4 bytes).
pub const PUSH_SIZE_32: i64 = 4;

// x86-64 register constants (mirrors x86_register_info.rs)
const RBX: u16 = 3;
const R12: u16 = 12;
const R13: u16 = 13;
const R14: u16 = 14;
const R15: u16 = 15;

// x86-32 register constants
const EBX32: u16 = 19;
const ESI32: u16 = 22;
const EDI32: u16 = 23;
const EBP32: u16 = 21;
const ESP32: u16 = 20;

/// x86-64 callee-saved registers (System V AMD64 ABI).
pub const CALLEE_SAVED_REGS_SYSV: &[u16] = &[RBX, R12, R13, R14, R15];

/// x86-64 callee-saved registers (Microsoft x64 ABI).
pub const CALLEE_SAVED_REGS_WIN64: &[u16] =
    &[RBX, RBP_CONST, RSI_CONST, RDI_CONST, R12, R13, R14, R15];

/// x86-32 callee-saved registers (cdecl/stdcall).
pub const CALLEE_SAVED_REGS_X86_32: &[u16] = &[EBX32, ESI32, EDI32, EBP32];

/// Flags register constant.
const FLAGS: u16 = 200;

const RSI_CONST: u16 = 6;
const RDI_CONST: u16 = 7;

// ============================================================================
// CallConv — calling convention enumeration
// ============================================================================

/// Supported calling conventions for frame lowering.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CallConv {
    /// System V AMD64 ABI (Linux, macOS, FreeBSD, etc.)
    SystemV,
    /// Microsoft x64 ABI (Windows)
    Win64,
    /// 32-bit cdecl (caller cleans stack)
    CDecl32,
    /// 32-bit stdcall (callee cleans stack)
    StdCall32,
    /// 32-bit fastcall (first two args in ECX, EDX)
    FastCall32,
}

impl CallConv {
    /// Returns true if this calling convention uses a red zone.
    pub fn uses_red_zone(&self) -> bool {
        matches!(self, CallConv::SystemV)
    }

    /// Returns true if this is a 64-bit calling convention.
    pub fn is_64bit(&self) -> bool {
        matches!(self, CallConv::SystemV | CallConv::Win64)
    }

    /// Returns true if this is a 32-bit calling convention.
    pub fn is_32bit(&self) -> bool {
        matches!(
            self,
            CallConv::CDecl32 | CallConv::StdCall32 | CallConv::FastCall32
        )
    }

    /// Returns the size of a register push on this architecture.
    pub fn push_size(&self) -> i64 {
        if self.is_64bit() {
            PUSH_SIZE_64
        } else {
            PUSH_SIZE_32
        }
    }

    /// Returns the callee-saved registers for this convention.
    pub fn callee_saved_regs(&self) -> &'static [u16] {
        match self {
            CallConv::SystemV => CALLEE_SAVED_REGS_SYSV,
            CallConv::Win64 => CALLEE_SAVED_REGS_WIN64,
            CallConv::CDecl32 | CallConv::StdCall32 | CallConv::FastCall32 => {
                CALLEE_SAVED_REGS_X86_32
            }
        }
    }

    /// Returns the frame pointer register ID for this convention.
    pub fn frame_pointer_reg(&self) -> u16 {
        if self.is_64bit() {
            RBP_CONST
        } else {
            EBP32
        }
    }

    /// Returns the stack pointer register ID for this convention.
    pub fn stack_pointer_reg(&self) -> u16 {
        if self.is_64bit() {
            RSP_CONST
        } else {
            ESP32
        }
    }
}

// ============================================================================
// X86FrameInfo — per-function frame metadata
// ============================================================================

/// Complete frame layout information for a single function.
#[derive(Debug, Clone)]
pub struct X86FrameInfo {
    /// Total size of the stack frame in bytes.
    pub frame_size: i64,
    /// Registers saved in the prologue (callee-saved that are used).
    pub saved_regs: Vec<u16>,
    /// Whether this function uses a frame pointer (%rbp).
    pub has_frame_pointer: bool,
    /// Whether this function contains call instructions.
    pub has_calls: bool,
    /// Whether this function contains variable-sized allocas (alloca with
    /// non-constant size, or dynamic stack realignment).
    pub has_var_sized_objects: bool,
    /// Whether the function can use the red zone (no calls, small frame).
    pub uses_red_zone: bool,
    /// Maximum outgoing argument space needed for calls in this function.
    pub max_call_frame_size: i64,
    /// Offset from frame pointer to the local variables area.
    pub local_area_offset: i64,
    /// Total size of callee-saved register spills.
    pub callee_saved_size: i64,
}

impl X86FrameInfo {
    /// Create default frame info.
    pub fn new() -> Self {
        X86FrameInfo {
            frame_size: 0,
            saved_regs: Vec::new(),
            has_frame_pointer: false,
            has_calls: false,
            has_var_sized_objects: false,
            uses_red_zone: false,
            max_call_frame_size: 0,
            local_area_offset: 0,
            callee_saved_size: 0,
        }
    }

    /// Returns the total frame size including alignment.
    pub fn total_frame_size(&self) -> i64 {
        self.frame_size
    }

    /// Returns the offset from %rbp where the locals area begins.
    /// Negative offset (below %rbp).
    pub fn local_start_offset(&self) -> i64 {
        -(self.callee_saved_size) - PUSH_SIZE_64
    }
}

impl Default for X86FrameInfo {
    fn default() -> Self {
        X86FrameInfo::new()
    }
}

// ============================================================================
// X86FrameLowering — main frame lowering engine
// ============================================================================

/// X86 stack frame lowering engine.
///
/// Responsible for emitting function prologues and epilogues, managing
/// the frame pointer, and coordinating callee-saved register spills.
pub struct X86FrameLowering {
    /// Calling convention for this compilation unit.
    pub call_conv: CallConv,
    /// Instruction info reference for building machine instructions.
    pub instr_info: X86InstrInfo,
}

impl X86FrameLowering {
    /// Construct a new X86FrameLowering for the given calling convention.
    pub fn new(call_conv: CallConv) -> Self {
        X86FrameLowering {
            call_conv,
            instr_info: X86InstrInfo::new(),
        }
    }

    // ====================================================================
    // Frame Size Calculation
    // ====================================================================

    /// Calculate the total frame size required for a function.
    ///
    /// Includes: callee-saved register spills, local variables, outgoing
    /// argument area, and alignment padding.
    pub fn calculate_frame_size(&self, frame_info: &X86FrameInfo) -> i64 {
        let mut size = frame_info.callee_saved_size;
        size += frame_info.local_area_offset.abs();
        size += frame_info.max_call_frame_size;
        size = self.align_frame_size(size, STACK_ALIGNMENT);
        size
    }

    /// Align a frame size to the given alignment boundary.
    pub fn align_frame_size(&self, size: i64, alignment: i64) -> i64 {
        if size % alignment == 0 {
            size
        } else {
            size + (alignment - (size % alignment))
        }
    }

    // ====================================================================
    // Frame Pointer Determination
    // ====================================================================

    /// Determine whether this function needs a frame pointer (%rbp).
    ///
    /// A frame pointer is required when:
    /// - The function has variable-sized objects (alloca with dynamic size)
    /// - The function requires dynamic stack realignment
    /// - On 32-bit, the function has stack arguments *and* no frame pointer
    ///   would make debugging/exception handling difficult
    /// - Explicitly requested (e.g., -fno-omit-frame-pointer)
    ///
    /// A frame pointer is NOT required for:
    /// - Simple leaf functions
    /// - Functions where all locals fit in the red zone (64-bit)
    pub fn needs_frame_pointer(&self, frame_info: &X86FrameInfo) -> bool {
        // Variable-sized objects always require a frame pointer
        if frame_info.has_var_sized_objects {
            return true;
        }

        // On 32-bit, any non-trivial frame benefits from a frame pointer
        if self.call_conv.is_32bit() && frame_info.frame_size > 0 {
            return true;
        }

        // Functions with significant stack usage that have calls
        if frame_info.has_calls && frame_info.frame_size > RED_ZONE_SIZE {
            return true;
        }

        // Large frames benefit from frame pointer for debugging
        if frame_info.frame_size > 4096 {
            return true;
        }

        false
    }

    // ====================================================================
    // Prologue Emission
    // ====================================================================

    /// Emit the function prologue for the given machine function.
    ///
    /// For System V AMD64, generates:
    /// ```asm
    /// pushq %rbp
    /// movq %rsp, %rbp
    /// subq $N, %rsp          (if frame > red zone or has calls)
    /// pushq %rbx             (saved regs as needed)
    /// pushq %r12
    /// ...
    /// ```
    pub fn emit_prologue(&self, mf: &mut MachineFunction) -> Vec<MachineInstr> {
        let frame_info = self.build_frame_info(mf);
        let mut instrs = Vec::new();
        let sp = self.call_conv.stack_pointer_reg();
        let fp = self.call_conv.frame_pointer_reg();
        let push_size = self.call_conv.push_size();

        if frame_info.has_frame_pointer {
            // push [frame_pointer]
            instrs.push(self.build_push(fp));

            // mov %rsp, %rbp  (or %esp, %ebp on 32-bit)
            instrs.push(self.build_mov_fp_from_sp(fp, sp));

            // Allocate stack space if needed
            if frame_info.frame_size > 0 {
                let alloc_size = self.align_frame_size(frame_info.frame_size, STACK_ALIGNMENT);
                if !frame_info.uses_red_zone || alloc_size > RED_ZONE_SIZE {
                    instrs.push(self.build_sub_sp(sp, alloc_size));
                }
            }
        } else {
            // No frame pointer — just allocate stack space
            if frame_info.frame_size > 0 {
                let alloc_size = self.align_frame_size(frame_info.frame_size, STACK_ALIGNMENT);
                if !frame_info.uses_red_zone || alloc_size > RED_ZONE_SIZE {
                    instrs.push(self.build_sub_sp(sp, alloc_size));
                }
            }
        }

        // Save callee-saved registers
        for &reg in &frame_info.saved_regs {
            if reg != fp {
                // Frame pointer already pushed above
                instrs.push(self.build_push(reg));
            }
        }

        // Win64: emit SEH annotations as comments (stub)
        if self.call_conv == CallConv::Win64 {
            self.emit_seh_prologue(&mut instrs, &frame_info);
        }

        instrs
    }

    /// Build a push instruction for the target architecture.
    fn build_push(&self, reg: u16) -> MachineInstr {
        let mut mi = MachineInstr::new(X86Opcode::PUSH as u32);
        mi.operands.push(MachineOperand::PhysReg(reg as u32));
        mi
    }

    /// Build a mov from stack pointer to frame pointer.
    fn build_mov_fp_from_sp(&self, fp: u16, sp: u16) -> MachineInstr {
        let mut mi = MachineInstr::new(X86Opcode::MOV as u32);
        mi.operands.push(MachineOperand::PhysReg(fp as u32));
        mi.operands.push(MachineOperand::PhysReg(sp as u32));
        mi
    }

    /// Build a sub immediate from stack pointer.
    fn build_sub_sp(&self, sp: u16, amount: i64) -> MachineInstr {
        let mut mi = MachineInstr::new(X86Opcode::SUB as u32);
        mi.operands.push(MachineOperand::PhysReg(sp as u32));
        mi.operands.push(MachineOperand::Imm(amount));
        mi
    }

    /// Emit Win64 SEH prologue annotations (stub — produces comments).
    fn emit_seh_prologue(&self, _instrs: &mut Vec<MachineInstr>, frame_info: &X86FrameInfo) {
        // In a full implementation, this would emit .seh_pushreg, .seh_setframe,
        // .seh_stackalloc, .seh_endprologue directives.
        // For now, these are documented but not emitted as actual machine instructions.
        let _ = frame_info;
    }

    // ====================================================================
    // Epilogue Emission
    // ====================================================================

    /// Emit the function epilogue for the given machine function.
    ///
    /// For System V AMD64, generates:
    /// ```asm
    /// movq %rbp, %rsp       (or leaq -N(%rbp), %rsp)
    /// popq %r12             (restore saved regs in reverse order)
    /// popq %rbx
    /// popq %rbp
    /// retq
    /// ```
    pub fn emit_epilogue(&self, mf: &mut MachineFunction) -> Vec<MachineInstr> {
        let frame_info = self.build_frame_info(mf);
        let mut instrs = Vec::new();
        let sp = self.call_conv.stack_pointer_reg();
        let fp = self.call_conv.frame_pointer_reg();

        // Win64: emit SEH epilogue annotations (stub)
        if self.call_conv == CallConv::Win64 {
            self.emit_seh_epilogue(&mut instrs, &frame_info);
        }

        if frame_info.has_frame_pointer {
            // Restore stack pointer from frame pointer
            if !frame_info.saved_regs.is_empty() || frame_info.frame_size > 0 {
                // lea -callee_saved_size(%rbp), %rsp
                let offset = -(frame_info.callee_saved_size);
                instrs.push(self.build_lea_sp_from_fp(sp, fp, offset));
            } else {
                // Simple: mov %rbp, %rsp
                instrs.push(self.build_mov_sp_from_fp(sp, fp));
            }

            // Restore callee-saved registers in reverse order
            for &reg in frame_info.saved_regs.iter().rev() {
                if reg != fp {
                    instrs.push(self.build_pop(reg));
                }
            }

            // Restore frame pointer
            instrs.push(self.build_pop(fp));
        } else {
            // No frame pointer — just restore stack pointer
            if frame_info.frame_size > 0 {
                let alloc_size = self.align_frame_size(frame_info.frame_size, STACK_ALIGNMENT);
                if !frame_info.uses_red_zone || alloc_size > RED_ZONE_SIZE {
                    instrs.push(self.build_add_sp(sp, alloc_size));
                }
            }

            // Restore callee-saved registers in reverse order
            for &reg in frame_info.saved_regs.iter().rev() {
                instrs.push(self.build_pop(reg));
            }
        }

        // Return
        instrs.push(self.build_ret());

        instrs
    }

    /// Build a pop instruction for the target architecture.
    fn build_pop(&self, reg: u16) -> MachineInstr {
        let mut mi = MachineInstr::new(X86Opcode::POP as u32);
        mi.operands.push(MachineOperand::PhysReg(reg as u32));
        mi
    }

    /// Build a mov from frame pointer to stack pointer.
    fn build_mov_sp_from_fp(&self, sp: u16, fp: u16) -> MachineInstr {
        let mut mi = MachineInstr::new(X86Opcode::MOV as u32);
        mi.operands.push(MachineOperand::PhysReg(sp as u32));
        mi.operands.push(MachineOperand::PhysReg(fp as u32));
        mi
    }

    /// Build a lea to restore stack pointer from frame pointer with offset.
    fn build_lea_sp_from_fp(&self, sp: u16, fp: u16, offset: i64) -> MachineInstr {
        let mut mi = MachineInstr::new(X86Opcode::LEA as u32);
        mi.operands.push(MachineOperand::PhysReg(sp as u32));
        // Memory operand: [fp + offset]
        // We represent this as two operands: base register and displacement
        mi.operands.push(MachineOperand::PhysReg(fp as u32));
        mi.operands.push(MachineOperand::Imm(offset));
        mi
    }

    /// Build an add immediate to stack pointer.
    fn build_add_sp(&self, sp: u16, amount: i64) -> MachineInstr {
        let mut mi = MachineInstr::new(X86Opcode::ADD as u32);
        mi.operands.push(MachineOperand::PhysReg(sp as u32));
        mi.operands.push(MachineOperand::Imm(amount));
        mi
    }

    /// Build a ret instruction.
    fn build_ret(&self) -> MachineInstr {
        MachineInstr::new(X86Opcode::RET as u32)
    }

    /// Emit Win64 SEH epilogue annotations (stub).
    fn emit_seh_epilogue(&self, _instrs: &mut Vec<MachineInstr>, frame_info: &X86FrameInfo) {
        // In a full implementation: .seh_endprologue, .seh_startepilogue
        let _ = frame_info;
    }

    // ====================================================================
    // Frame Information Construction
    // ====================================================================

    /// Build X86FrameInfo for a given machine function by analyzing its
    /// instructions and properties.
    pub fn build_frame_info(&self, mf: &MachineFunction) -> X86FrameInfo {
        let mut info = X86FrameInfo::new();

        // Analyze callee-saved register usage
        let used_regs = self.collect_used_callee_saved_regs(mf);
        let callee_saved_size = used_regs.len() as i64 * self.call_conv.push_size();
        info.saved_regs = used_regs;
        info.callee_saved_size = callee_saved_size;

        // Detect calls
        info.has_calls = self.function_has_calls(mf);

        // Estimate local variable space
        info.local_area_offset = self.estimate_local_area(mf);

        // Calculate total frame size
        info.frame_size = self.calculate_frame_size(&info);

        // Determine red zone eligibility
        info.uses_red_zone =
            self.call_conv.uses_red_zone() && !info.has_calls && info.frame_size <= RED_ZONE_SIZE;

        // Determine frame pointer requirement
        info.has_frame_pointer = self.needs_frame_pointer(&info);

        // Estimate max call frame size
        info.max_call_frame_size = self.estimate_max_call_args(mf);

        info
    }

    /// Collect which callee-saved registers are actually used in the function.
    fn collect_used_callee_saved_regs(&self, mf: &MachineFunction) -> Vec<u16> {
        let callee_regs = self.call_conv.callee_saved_regs();
        let mut used = Vec::new();
        let mut seen = HashMap::new();

        for block in &mf.blocks {
            for inst in &block.instructions {
                for op in &inst.operands {
                    match op {
                        MachineOperand::PhysReg(reg) => {
                            seen.insert(*reg, true);
                        }
                        MachineOperand::Reg(_) => {
                            // Virtual registers — skip for now (RA phase would map
                            // these to physical registers)
                        }
                        _ => {}
                    }
                }
            }
        }

        for &reg in callee_regs {
            if seen.contains_key(&(reg as u32)) {
                used.push(reg);
            }
        }
        used
    }

    /// Detect if the function contains call instructions.
    fn function_has_calls(&self, mf: &MachineFunction) -> bool {
        let call_opcode = X86Opcode::CALL as u32;
        for block in &mf.blocks {
            for inst in &block.instructions {
                if inst.opcode == call_opcode {
                    return true;
                }
            }
        }
        false
    }

    /// Estimate the local variable area size.
    fn estimate_local_area(&self, _mf: &MachineFunction) -> i64 {
        // In a real implementation, this would sum the sizes of all stack
        // slots allocated. For now, estimate based on vreg count.
        // Each vreg might need a spill slot (8 bytes).
        0
    }

    /// Estimate the maximum outgoing argument area needed.
    fn estimate_max_call_args(&self, mf: &MachineFunction) -> i64 {
        // Count the maximum number of arguments passed to any call in this function.
        // System V AMD64: first 6 integer args in registers, rest on stack.
        // Each stack arg is 8 bytes.
        let mut max_args = 0i64;
        let call_opcode = X86Opcode::CALL as u32;
        for block in &mf.blocks {
            for inst in &block.instructions {
                if inst.opcode == call_opcode {
                    // Count operands before the call as potential args.
                    // The call itself has 1 operand (the label), so args would
                    // be in preceding instructions. Simplified heuristic.
                    let arg_count = inst.operands.len() as i64;
                    if arg_count > max_args {
                        max_args = arg_count;
                    }
                }
            }
        }
        // Each arg is aligned to 8 bytes on 64-bit, 4 bytes on 32-bit
        let arg_size = self.call_conv.push_size();
        let register_args = if self.call_conv.is_64bit() { 6 } else { 0 };
        let stack_args = (max_args - register_args).max(0);
        self.align_frame_size(stack_args * arg_size, STACK_ALIGNMENT)
    }

    // ====================================================================
    // Frame Index Reference
    // ====================================================================

    /// Generate machine instructions to load from a frame slot.
    ///
    /// Frame index `fi` is an abstract stack slot identifier. `offset` is
    /// the byte offset from the frame base.
    pub fn get_frame_index_reference(
        &self,
        mf: &mut MachineFunction,
        fi: i64,
        offset: i64,
    ) -> Vec<MachineInstr> {
        let frame_info = self.build_frame_info(mf);
        let fp = self.call_conv.frame_pointer_reg();
        let mut instrs = Vec::new();

        // The actual frame slot address is computed as:
        //   [%rbp - callee_saved_size - local_offset + slot_offset]
        let base_offset = -(frame_info.callee_saved_size) - fi * PUSH_SIZE_64 + offset;

        // Load into a new virtual register
        let vreg = mf.new_vreg();
        let mut load = MachineInstr::new(X86Opcode::MOV as u32);
        load.operands.push(MachineOperand::Reg(vreg));
        load.operands.push(MachineOperand::PhysReg(fp as u32));
        load.operands.push(MachineOperand::Imm(base_offset));
        load.def = Some(vreg);
        instrs.push(load);

        let _ = mf; // used above via new_vreg
        instrs
    }

    // ====================================================================
    // Callee-Saved Spill Slots
    // ====================================================================

    /// Assign spill slots for callee-saved registers.
    ///
    /// Returns a vector of `(register_id, slot_offset)` pairs, where
    /// slot_offset is the offset from the frame pointer.
    pub fn assign_callee_saved_spill_slots(&self, mf: &MachineFunction) -> Vec<(u16, i64)> {
        let frame_info = self.build_frame_info(mf);
        let push_size = self.call_conv.push_size();
        let mut slots = Vec::new();
        let mut current_offset: i64 = 0;

        for &reg in &frame_info.saved_regs {
            if reg != self.call_conv.frame_pointer_reg() {
                // Slot is at negative offset from %rbp (below the saved %rbp)
                current_offset -= push_size;
                slots.push((reg, current_offset));
            }
        }

        slots
    }

    // ====================================================================
    // X86-32 Frame Lowering
    // ====================================================================

    /// Emit a 32-bit prologue (cdecl/stdcall/fastcall).
    ///
    /// 32-bit differs from 64-bit in:
    /// - Uses 4-byte pushes/pops
    /// - No red zone
    /// - ESP-based addressing when no frame pointer
    /// - Arguments always on stack (no register args for cdecl)
    pub fn emit_prologue_32(&self, mf: &mut MachineFunction) -> Vec<MachineInstr> {
        let frame_info = self.build_frame_info(mf);
        let mut instrs = Vec::new();
        let sp = ESP32;
        let fp = EBP32;

        // push %ebp
        instrs.push(self.build_push(fp));

        // mov %esp, %ebp
        instrs.push(self.build_mov_fp_from_sp(fp, sp));

        // sub $N, %esp (always, no red zone on x86-32)
        if frame_info.frame_size > 0 {
            let alloc_size = self.align_frame_size(frame_info.frame_size, STACK_ALIGNMENT);
            instrs.push(self.build_sub_sp(sp, alloc_size));
        }

        // Save callee-saved registers
        for &reg in &frame_info.saved_regs {
            if reg != fp {
                instrs.push(self.build_push(reg));
            }
        }

        instrs
    }

    /// Emit a 32-bit epilogue.
    pub fn emit_epilogue_32(&self, mf: &mut MachineFunction) -> Vec<MachineInstr> {
        let frame_info = self.build_frame_info(mf);
        let mut instrs = Vec::new();
        let sp = ESP32;
        let fp = EBP32;
        let alloc_size = self.align_frame_size(frame_info.frame_size, STACK_ALIGNMENT);

        // Restore callee-saved registers in reverse order
        for &reg in frame_info.saved_regs.iter().rev() {
            if reg != fp {
                instrs.push(self.build_pop(reg));
            }
        }

        if frame_info.has_frame_pointer {
            // mov %ebp, %esp
            instrs.push(self.build_mov_sp_from_fp(sp, fp));
            // pop %ebp
            instrs.push(self.build_pop(fp));
        } else if frame_info.frame_size > 0 {
            // add $N, %esp
            instrs.push(self.build_add_sp(sp, alloc_size));
        }

        // ret
        instrs.push(self.build_ret());

        instrs
    }

    // ====================================================================
    // Win64 Frame Lowering
    // ====================================================================

    /// Emit a Win64 prologue with SEH annotations.
    ///
    /// Win64 requires:
    /// - 16-byte stack alignment maintained
    /// - 32 bytes of shadow space (home space) for register parameters
    /// - SEH unwind metadata
    pub fn emit_prologue_win64(&self, mf: &mut MachineFunction) -> Vec<MachineInstr> {
        let frame_info = self.build_frame_info(mf);
        let mut instrs = Vec::new();
        let sp = RSP_CONST;
        let fp = RBP_CONST;

        // .seh_proc function_name (metadata, not an instruction)

        // push %rbp
        instrs.push(self.build_push(fp));
        // .seh_pushreg %rbp

        // mov %rsp, %rbp
        instrs.push(self.build_mov_fp_from_sp(fp, sp));
        // .seh_setframe %rbp, 0

        // Allocate stack space (including 32-byte shadow space)
        let alloc_size = self.align_frame_size(frame_info.frame_size + 32, STACK_ALIGNMENT);
        if alloc_size > 0 {
            instrs.push(self.build_sub_sp(sp, alloc_size));
            // .seh_stackalloc N
        }

        // Save non-volatile registers
        for &reg in &frame_info.saved_regs {
            if reg != fp {
                instrs.push(self.build_push(reg));
                // .seh_pushreg for each
            }
        }

        // .seh_endprologue
        instrs
    }

    /// Emit a Win64 epilogue.
    pub fn emit_epilogue_win64(&self, mf: &mut MachineFunction) -> Vec<MachineInstr> {
        let frame_info = self.build_frame_info(mf);
        let mut instrs = Vec::new();
        let sp = RSP_CONST;
        let fp = RBP_CONST;
        let alloc_size = self.align_frame_size(frame_info.frame_size + 32, STACK_ALIGNMENT);

        // Restore non-volatile registers in reverse order
        for &reg in frame_info.saved_regs.iter().rev() {
            if reg != fp {
                instrs.push(self.build_pop(reg));
            }
        }

        if frame_info.has_frame_pointer {
            // mov %rbp, %rsp
            instrs.push(self.build_mov_sp_from_fp(sp, fp));
            // pop %rbp
            instrs.push(self.build_pop(fp));
        } else if alloc_size > 0 {
            instrs.push(self.build_add_sp(sp, alloc_size));
        }

        // ret
        instrs.push(self.build_ret());

        instrs
    }
}

impl Default for X86FrameLowering {
    fn default() -> Self {
        X86FrameLowering::new(CallConv::SystemV)
    }
}

// ============================================================================
// Stack Probing — large frame handling for guard page interaction
// ============================================================================

/// Determines whether a frame requires stack probing.
///
/// Stack probing is required when the frame size exceeds the guard page
/// size. On Windows, the guard page is typically 4 KB (one page). Without
/// probing, a large `sub rsp, N` could skip past the guard page and access
/// uncommitted memory, causing an access violation that the OS cannot
/// handle as a stack extension.
///
/// On Linux, the kernel automatically extends the stack up to `RLIMIT_STACK`,
/// but the `__morestack` mechanism can be used for split stacks.
pub const GUARD_PAGE_SIZE: i64 = 4096;

/// Threshold above which stack probing is required.
pub const STACK_PROBE_THRESHOLD: i64 = 4096;

/// Represents the stack probing strategy for a function.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum StackProbeKind {
    /// No probing needed (small frame).
    #[default]
    None,
    /// Use `__chkstk` on Windows (touches pages at 4 KB intervals).
    ChkStk,
    /// Emit inline probe sequence (touch each guard page).
    Inline,
    /// Use `__morestack` for split-stack support (Linux).
    Morestack,
}

impl X86FrameLowering {
    /// Determine the stack probing strategy for the given frame.
    pub fn probe_kind(&self, frame_size: i64, is_windows: bool) -> StackProbeKind {
        if frame_size <= STACK_PROBE_THRESHOLD {
            return StackProbeKind::None;
        }
        if is_windows {
            StackProbeKind::ChkStk
        } else {
            StackProbeKind::Inline
        }
    }

    /// Emit stack probe instructions for a large frame.
    ///
    /// On Windows (x64), calls `__chkstk` which is provided by the CRT.
    /// The routine expects the allocation size in RAX and will touch each
    /// page between the current RSP and RSP - RAX.
    ///
    /// On Linux (System V), emits inline probe sequence:
    /// ```asm
    ///     mov  rax, rsp
    /// .Lprobe_loop:
    ///     sub  rsp, 4096
    ///     test [rsp], rsp    ; touch the page
    ///     cmp  rsp, rax
    ///     jne  .Lprobe_loop
    /// ```
    pub fn emit_stack_probe(
        &self,
        frame_size: i64,
        sp: u16,
        scratch: u16,
        is_windows: bool,
        label_counter: &mut u64,
    ) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();
        let kind = self.probe_kind(frame_size, is_windows);

        match kind {
            StackProbeKind::None => {}
            StackProbeKind::ChkStk => {
                // Windows: call __chkstk
                // mov rax, frame_size
                let mut mov_instr = MachineInstr::new(X86Opcode::MOV as u32);
                mov_instr.operands.push(MachineOperand::PhysReg(RAX as u32));
                mov_instr.operands.push(MachineOperand::Imm(frame_size));
                instrs.push(mov_instr);

                // call __chkstk
                let mut call_instr = MachineInstr::new(X86Opcode::CALL as u32);
                call_instr
                    .operands
                    .push(MachineOperand::Label("__chkstk".to_string()));
                instrs.push(call_instr);

                // sub rsp, rax (__chkstk adjusts RAX to the final value)
                let mut sub_instr = MachineInstr::new(X86Opcode::SUB as u32);
                sub_instr.operands.push(MachineOperand::PhysReg(sp as u32));
                sub_instr.operands.push(MachineOperand::PhysReg(RAX as u32));
                instrs.push(sub_instr);
            }
            StackProbeKind::Inline => {
                // Inline probing: touch each 4KB page
                // Save target SP in scratch register
                let mut mov_target = MachineInstr::new(X86Opcode::MOV as u32);
                mov_target
                    .operands
                    .push(MachineOperand::PhysReg(scratch as u32));
                mov_target.operands.push(MachineOperand::PhysReg(sp as u32));
                instrs.push(mov_target);

                // sub scratch, frame_size
                let mut sub_target = MachineInstr::new(X86Opcode::SUB as u32);
                sub_target
                    .operands
                    .push(MachineOperand::PhysReg(scratch as u32));
                sub_target.operands.push(MachineOperand::Imm(frame_size));
                instrs.push(sub_target);

                // Loop label
                let loop_label = format!(".Lprobe_loop_{}", label_counter);
                *label_counter += 1;
                let loop_out = format!(".Lprobe_done_{}", label_counter);
                *label_counter += 1;

                // .Lprobe_loop:
                //   sub rsp, 4096
                let mut sub_probe = MachineInstr::new(X86Opcode::SUB as u32);
                sub_probe.operands.push(MachineOperand::PhysReg(sp as u32));
                sub_probe
                    .operands
                    .push(MachineOperand::Imm(GUARD_PAGE_SIZE));
                instrs.push(sub_probe);

                //   test [rsp], rsp  (touch the page)
                let mut touch_instr = MachineInstr::new(X86Opcode::TEST as u32);
                touch_instr
                    .operands
                    .push(MachineOperand::PhysReg(sp as u32));
                touch_instr
                    .operands
                    .push(MachineOperand::PhysReg(sp as u32));
                instrs.push(touch_instr);

                //   cmp rsp, scratch
                let mut cmp_instr = MachineInstr::new(X86Opcode::CMP as u32);
                cmp_instr.operands.push(MachineOperand::PhysReg(sp as u32));
                cmp_instr
                    .operands
                    .push(MachineOperand::PhysReg(scratch as u32));
                instrs.push(cmp_instr);

                //   jne .Lprobe_loop
                let mut jne_instr = MachineInstr::new(X86Opcode::JNE as u32);
                jne_instr.operands.push(MachineOperand::Label(loop_label));
                instrs.push(jne_instr);
            }
            StackProbeKind::Morestack => {
                // Split-stack: call __morestack
                let mut call_instr = MachineInstr::new(X86Opcode::CALL as u32);
                call_instr
                    .operands
                    .push(MachineOperand::Label("__morestack".to_string()));
                instrs.push(call_instr);
            }
        }

        instrs
    }
}

// ============================================================================
// GPR Save/Restore Sequences — callee-saved general-purpose registers
// ============================================================================

impl X86FrameLowering {
    /// Build GPR save sequence using PUSH instructions.
    ///
    /// On x86-64, saves RBX, R12-R15 as needed.
    /// On x86-32, saves EBX, ESI, EDI as needed.
    /// Uses PUSH which is more compact than MOV to stack.
    pub fn build_gpr_save<'a>(&self, saved: &[u16], exclude_fp: u16) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();
        for &reg in saved {
            if reg != exclude_fp {
                let mut mi = MachineInstr::new(X86Opcode::PUSH as u32);
                mi.operands.push(MachineOperand::PhysReg(reg as u32));
                instrs.push(mi);
            }
        }
        instrs
    }

    /// Build GPR restore sequence using POP instructions (reverse order).
    pub fn build_gpr_restore<'a>(&self, saved: &[u16], exclude_fp: u16) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();
        for &reg in saved.iter().rev() {
            if reg != exclude_fp {
                let mut mi = MachineInstr::new(X86Opcode::POP as u32);
                mi.operands.push(MachineOperand::PhysReg(reg as u32));
                instrs.push(mi);
            }
        }
        instrs
    }

    /// Determine the ordered GPR save list for the frame.
    ///
    /// Pushes are ordered: R15, R14, R13, R12, RBX (for System V)
    /// so that the lowest callee-saved register is at the highest address.
    pub fn gpr_save_order(&self) -> Vec<u16> {
        if self.call_conv.is_64bit() {
            match self.call_conv {
                CallConv::SystemV => {
                    // Save order: highest reg number first (R15 down to RBX)
                    vec![R15, R14, R13, R12, RBX]
                }
                CallConv::Win64 => {
                    // Win64 saves: R15, R14, R13, R12, RDI, RSI, RBX
                    vec![R15, R14, R13, R12, RDI_CONST, RSI_CONST, RBX]
                }
                _ => vec![R15, R14, R13, R12, RBX],
            }
        } else {
            // 32-bit: ESI, EDI, EBX
            vec![ESI32, EDI32, EBX32]
        }
    }
}

// ============================================================================
// XMM Save/Restore Sequences — callee-saved SIMD registers
// ============================================================================

/// XMM save slot alignment requirement.
pub const XMM_SAVE_ALIGN: i64 = 16;

/// YMM save slot alignment requirement (AVX).
pub const YMM_SAVE_ALIGN: i64 = 32;

/// ZMM save slot alignment requirement (AVX-512).
pub const ZMM_SAVE_ALIGN: i64 = 64;

// XMM store/load opcodes (will be integrated into X86Opcode enum later)
const MOVAPS_STORE: u32 = 2200;
const MOVAPS_LOAD: u32 = 2201;

/// Information about XMM save slots in the frame.
#[derive(Debug, Clone)]
pub struct XmmSaveArea {
    /// Starting offset from the frame base for XMM saves.
    pub offset: i64,
    /// Number of XMM registers saved.
    pub count: usize,
    /// Size of each save slot (16 for XMM, 32 for YMM, 64 for ZMM).
    pub slot_size: i64,
    /// Required alignment for the save area.
    pub alignment: i64,
    /// The specific XMM register indices saved.
    pub registers: Vec<u8>,
}

impl Default for XmmSaveArea {
    fn default() -> Self {
        XmmSaveArea {
            offset: 0,
            count: 0,
            slot_size: 16,
            alignment: XMM_SAVE_ALIGN,
            registers: Vec::new(),
        }
    }
}

impl X86FrameLowering {
    /// Determine which XMM registers must be saved based on calling convention.
    ///
    /// System V AMD64: XMM registers are all caller-saved (none callee-saved).
    /// Microsoft x64: XMM6-XMM15 are callee-saved.
    pub fn get_xmm_callee_saved(&self) -> Vec<u8> {
        match self.call_conv {
            CallConv::Win64 => {
                // XMM6 through XMM15 inclusive
                (6..=15).collect()
            }
            _ => {
                // System V and 32-bit: no callee-saved XMM registers
                Vec::new()
            }
        }
    }

    /// Build XMM save sequence using MOVAPS to stack slots.
    ///
    /// Saves are done relative to the frame pointer when one exists, or
    /// relative to the stack pointer otherwise. Each XMM register is stored
    /// with a 16-byte aligned MOVAPS (or VMOVAPS for AVX).
    ///
    /// ```asm
    /// movaps  %xmm6,  -16(%rbp)
    /// movaps  %xmm7,  -32(%rbp)
    /// ...
    /// ```
    pub fn build_xmm_save(
        &self,
        xmm_regs: &[u8],
        base_reg: u16,
        base_offset: i64,
        slot_size: i64,
        has_frame_pointer: bool,
    ) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();
        let fp = if has_frame_pointer { -1i64 } else { 0i64 };
        let _ = fp; // marker for future frame-relative vs SP-relative

        for (i, &xmm_idx) in xmm_regs.iter().enumerate() {
            let offset = base_offset - (i as i64 + 1) * slot_size;
            // XMM physical register: XMM0 is at some index; here we use
            // the x86_register_info convention where XMM0 = 48, etc.
            let xmm_reg_id: u16 = 48u16 + xmm_idx as u16;

            let mut mi = MachineInstr::new(MOVAPS_STORE);
            // Destination: memory [base_reg + offset]
            mi.operands.push(MachineOperand::PhysReg(base_reg as u32));
            mi.operands.push(MachineOperand::Imm(offset));
            // Source: XMM register
            mi.operands.push(MachineOperand::PhysReg(xmm_reg_id as u32));
            instrs.push(mi);
        }

        instrs
    }

    /// Build XMM restore sequence using MOVAPS from stack slots.
    pub fn build_xmm_restore(
        &self,
        xmm_regs: &[u8],
        base_reg: u16,
        base_offset: i64,
        slot_size: i64,
    ) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();

        for (i, &xmm_idx) in xmm_regs.iter().enumerate() {
            let offset = base_offset - (i as i64 + 1) * slot_size;
            let xmm_reg_id: u16 = 48u16 + xmm_idx as u16;

            let mut mi = MachineInstr::new(MOVAPS_LOAD);
            // Destination: XMM register
            mi.operands.push(MachineOperand::PhysReg(xmm_reg_id as u32));
            // Source: memory [base_reg + offset]
            mi.operands.push(MachineOperand::PhysReg(base_reg as u32));
            mi.operands.push(MachineOperand::Imm(offset));
            instrs.push(mi);
        }

        instrs
    }

    /// Compute total XMM save area size including alignment padding.
    pub fn xmm_save_area_size(&self, xmm_regs: &[u8], slot_size: i64, alignment: i64) -> i64 {
        let raw_size = xmm_regs.len() as i64 * slot_size;
        if raw_size % alignment == 0 {
            raw_size
        } else {
            raw_size + (alignment - (raw_size % alignment))
        }
    }
}

// ============================================================================
// Stack Realignment — dynamic stack alignment for over-aligned locals
// ============================================================================

/// Maximum stack alignment supported by the x86 backend.
pub const MAX_STACK_ALIGNMENT: i64 = 64;

/// Information about stack realignment needs.
#[derive(Debug, Clone)]
pub struct StackRealignInfo {
    /// Whether stack realignment is required.
    pub needs_realignment: bool,
    /// Required alignment (e.g., 32 for AVX, 64 for AVX-512).
    pub alignment: i64,
    /// Scratch register used for alignment computation.
    pub scratch_reg: u16,
    /// Offset where the realignment adjustment is stored.
    pub adjustment_offset: i64,
}

impl Default for StackRealignInfo {
    fn default() -> Self {
        StackRealignInfo {
            needs_realignment: false,
            alignment: STACK_ALIGNMENT,
            scratch_reg: RAX,
            adjustment_offset: 0,
        }
    }
}

impl X86FrameLowering {
    /// Determine if stack realignment is required.
    ///
    /// Realignment is needed when:
    /// - A local variable requires alignment greater than the ABI default (16 bytes)
    /// - AVX/AVX-512 locals need 32/64 byte alignment
    /// - The function uses over-aligned allocas
    pub fn requires_stack_realignment(
        &self,
        frame_info: &X86FrameInfo,
        local_alignment: i64,
    ) -> bool {
        local_alignment > STACK_ALIGNMENT
            || frame_info.has_var_sized_objects
            || (self.call_conv == CallConv::Win64 && frame_info.frame_size > RED_ZONE_SIZE)
    }

    /// Emit stack realignment prologue.
    ///
    /// When the incoming stack is aligned to 16 bytes but we need 32 or 64,
    /// we must dynamically realign. The sequence is:
    /// ```asm
    /// push  rbp
    /// mov   rbp, rsp
    /// push  rbx             ; save scratch register
    /// mov   rbx, rsp        ; remember original RSP
    /// and   rsp, -ALIGN     ; align RSP down
    /// sub   rsp, frame_size ; allocate frame from aligned RSP
    /// ```
    pub fn emit_realign_prologue(
        &self,
        frame_size: i64,
        sp: u16,
        fp: u16,
        scratch: u16,
        alignment: i64,
    ) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();

        // push rbp
        let mut push_fp = MachineInstr::new(X86Opcode::PUSH as u32);
        push_fp.operands.push(MachineOperand::PhysReg(fp as u32));
        instrs.push(push_fp);

        // mov rbp, rsp
        let mut mov_fp = MachineInstr::new(X86Opcode::MOV as u32);
        mov_fp.operands.push(MachineOperand::PhysReg(fp as u32));
        mov_fp.operands.push(MachineOperand::PhysReg(sp as u32));
        instrs.push(mov_fp);

        // push scratch (save the register we'll use for alignment)
        let mut push_scratch = MachineInstr::new(X86Opcode::PUSH as u32);
        push_scratch
            .operands
            .push(MachineOperand::PhysReg(scratch as u32));
        instrs.push(push_scratch);

        // mov scratch, rsp  (remember original RSP)
        let mut mov_scratch = MachineInstr::new(X86Opcode::MOV as u32);
        mov_scratch
            .operands
            .push(MachineOperand::PhysReg(scratch as u32));
        mov_scratch
            .operands
            .push(MachineOperand::PhysReg(sp as u32));
        instrs.push(mov_scratch);

        // and rsp, -alignment  (align RSP down)
        let mut and_align = MachineInstr::new(X86Opcode::AND as u32);
        and_align.operands.push(MachineOperand::PhysReg(sp as u32));
        and_align.operands.push(MachineOperand::Imm(-alignment));
        instrs.push(and_align);

        // sub rsp, frame_size  (allocate frame from aligned position)
        if frame_size > 0 {
            let mut sub_frame = MachineInstr::new(X86Opcode::SUB as u32);
            sub_frame.operands.push(MachineOperand::PhysReg(sp as u32));
            sub_frame.operands.push(MachineOperand::Imm(frame_size));
            instrs.push(sub_frame);
        }

        instrs
    }

    /// Emit stack realignment epilogue.
    ///
    /// Restores RSP from the saved scratch register and pops saved registers.
    /// ```asm
    /// lea   rsp, [rbp - scratch_save_offset]
    /// pop   scratch
    /// pop   rbp
    /// ret
    /// ```
    pub fn emit_realign_epilogue(
        &self,
        sp: u16,
        fp: u16,
        scratch: u16,
        scratch_offset: i64,
    ) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();

        // lea rsp, [rbp + scratch_offset]
        let mut lea_instr = MachineInstr::new(X86Opcode::LEA as u32);
        lea_instr.operands.push(MachineOperand::PhysReg(sp as u32));
        lea_instr.operands.push(MachineOperand::PhysReg(fp as u32));
        lea_instr.operands.push(MachineOperand::Imm(scratch_offset));
        instrs.push(lea_instr);

        // Restore the alignment scratch register
        let mut pop_scratch = MachineInstr::new(X86Opcode::POP as u32);
        pop_scratch
            .operands
            .push(MachineOperand::PhysReg(scratch as u32));
        instrs.push(pop_scratch);

        // pop rbp
        let mut pop_fp = MachineInstr::new(X86Opcode::POP as u32);
        pop_fp.operands.push(MachineOperand::PhysReg(fp as u32));
        instrs.push(pop_fp);

        // ret
        instrs.push(self.build_ret());

        instrs
    }

    /// Find a suitable scratch register for stack realignment.
    ///
    /// Preference order: RAX (most common scratch), then R11, then R10.
    /// Avoids registers that are used for parameter passing.
    pub fn find_realignment_scratch(&self, used_regs: &[u16]) -> u16 {
        let candidates = if self.call_conv.is_64bit() {
            vec![RAX, R11, R10, R9]
        } else {
            vec![EAX]
        };

        for &cand in &candidates {
            if !used_regs.contains(&cand) {
                return cand;
            }
        }

        // Fallback: use RAX (caller must ensure it's saved/restored)
        if self.call_conv.is_64bit() {
            RAX
        } else {
            EAX
        }
    }
}

// ============================================================================
// Variable-Sized Object Frame — alloca/VLA dynamic stack adjustment
// ============================================================================

/// Metadata for variable-sized stack objects.
#[derive(Debug, Clone)]
pub struct VarSizedFrameInfo {
    /// Whether this function has dynamic allocas.
    pub has_dynamic_alloca: bool,
    /// Register holding the dynamic allocation size.
    pub size_reg: Option<VirtReg>,
    /// Total static frame size (excluding dynamic portion).
    pub static_frame_size: i64,
    /// Offset from frame pointer where dynamic area begins.
    pub dynamic_area_offset: i64,
}

impl Default for VarSizedFrameInfo {
    fn default() -> Self {
        VarSizedFrameInfo {
            has_dynamic_alloca: false,
            size_reg: None,
            static_frame_size: 0,
            dynamic_area_offset: 0,
        }
    }
}

impl X86FrameLowering {
    /// Detect if the function contains dynamic alloca instructions.
    pub fn has_dynamic_alloca(&self, mf: &MachineFunction) -> bool {
        for bb in &mf.blocks {
            for mi in &bb.instructions {
                // Check for alloca-like patterns: SUB RSP, reg (dynamic adjustment)
                // or explicit ALLOCA pseudo-instruction
                if mi.opcode == 3000u32 {
                    // Check if the size operand is not an immediate constant
                    if mi.operands.len() >= 2 {
                        if let MachineOperand::Reg(_) = mi.operands[1] {
                            return true;
                        }
                    }
                }
            }
        }
        false
    }

    /// Emit prologue for functions with variable-sized objects.
    ///
    /// The frame pointer is set up as usual, but SP is adjusted by a
    /// dynamic amount computed at runtime. The dynamic adjustment is
    /// stored relative to the frame pointer.
    ///
    /// ```asm
    /// push  rbp
    /// mov   rbp, rsp
    /// sub   rsp, static_frame_size
    /// push  rbx            ; saved regs...
    /// ; ... dynamic SP adjustment happens in the function body ...
    /// ```
    pub fn emit_var_sized_prologue(
        &self,
        static_frame_size: i64,
        sp: u16,
        fp: u16,
        saved_regs: &[u16],
    ) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();

        // push rbp
        instrs.push(self.build_push(fp));

        // mov rbp, rsp
        instrs.push(self.build_mov_fp_from_sp(fp, sp));

        // Allocate static portion of frame
        if static_frame_size > 0 {
            instrs.push(self.build_sub_sp(sp, static_frame_size));
        }

        // Save callee-saved GPRs
        for &reg in saved_regs {
            if reg != fp {
                instrs.push(self.build_push(reg));
            }
        }

        instrs
    }

    /// Emit epilogue for functions with variable-sized objects.
    ///
    /// Uses `mov rsp, rbp` to restore SP regardless of dynamic adjustments.
    pub fn emit_var_sized_epilogue(
        &self,
        sp: u16,
        fp: u16,
        saved_regs: &[u16],
    ) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();

        // Restore SP from FP (handles both static and dynamic frame)
        instrs.push(self.build_mov_sp_from_fp(sp, fp));

        // Restore callee-saved registers in reverse order
        for &reg in saved_regs.iter().rev() {
            if reg != fp {
                instrs.push(self.build_pop(reg));
            }
        }

        // Pop frame pointer
        instrs.push(self.build_pop(fp));

        // Return
        instrs.push(self.build_ret());

        instrs
    }

    /// Emit dynamic SP adjustment for alloca.
    ///
    /// ```asm
    /// mov   rax, alloca_size_reg
    /// add   rax, 15          ; align to 16 bytes
    /// and   rax, -16
    /// sub   rsp, rax
    /// mov   alloca_ptr_reg, rsp
    /// ```
    pub fn emit_dynamic_alloca(
        &self,
        size_reg: VirtReg,
        result_reg: VirtReg,
        sp: u16,
    ) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();

        // mov RAX, size_reg
        let mut mov_size = MachineInstr::new(X86Opcode::MOV as u32);
        mov_size.operands.push(MachineOperand::PhysReg(RAX as u32));
        mov_size.operands.push(MachineOperand::Reg(size_reg));
        mov_size.def = Some(result_reg);
        instrs.push(mov_size);

        // add RAX, 15  (for 16-byte alignment)
        let mut add_align = MachineInstr::new(X86Opcode::ADD as u32);
        add_align.operands.push(MachineOperand::PhysReg(RAX as u32));
        add_align.operands.push(MachineOperand::Imm(15));
        instrs.push(add_align);

        // and RAX, -16
        let mut and_align = MachineInstr::new(X86Opcode::AND as u32);
        and_align.operands.push(MachineOperand::PhysReg(RAX as u32));
        and_align.operands.push(MachineOperand::Imm(-16));
        instrs.push(and_align);

        // sub RSP, RAX
        let mut sub_sp = MachineInstr::new(X86Opcode::SUB as u32);
        sub_sp.operands.push(MachineOperand::PhysReg(sp as u32));
        sub_sp.operands.push(MachineOperand::PhysReg(RAX as u32));
        instrs.push(sub_sp);

        // mov result_reg, RSP  (return alloca pointer in result_reg)
        let mut mov_result = MachineInstr::new(X86Opcode::MOV as u32);
        mov_result.operands.push(MachineOperand::Reg(result_reg));
        mov_result.operands.push(MachineOperand::PhysReg(sp as u32));
        mov_result.def = Some(result_reg);
        instrs.push(mov_result);

        instrs
    }
}

// ============================================================================
// SEH (Structured Exception Handling) — Windows x64 unwind metadata
// ============================================================================

/// SEH unwind opcodes for Windows x64 exception handling.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SehUnwindOp {
    /// push a nonvolatile register: UWOP_PUSH_NONVOL
    PushNonVol(u16),
    /// allocate large stack: UWOP_ALLOC_LARGE
    AllocLarge(i64),
    /// allocate small stack: UWOP_ALLOC_SMALL
    AllocSmall(i64),
    /// set frame pointer register: UWOP_SET_FPREG
    SetFpReg,
    /// save nonvolatile register with MOV: UWOP_SAVE_NONVOL
    SaveNonVol(u16, i64),
    /// save XMM register: UWOP_SAVE_XMM128
    SaveXmm128(u16, i64),
    /// push machine frame (interrupt/trap): UWOP_PUSH_MACHFRAME
    PushMachFrame,
    /// end of prologue marker
    EndPrologue,
}

/// Complete Win64 unwind information for a function.
#[derive(Debug, Clone)]
pub struct Win64UnwindInfo {
    /// Version of the unwind info (1 or 2).
    pub version: u8,
    /// Flags (UNW_FLAG_EHANDLER, UNW_FLAG_UHANDLER, UNW_FLAG_CHAININFO).
    pub flags: u8,
    /// Size of the function prologue in bytes.
    pub prologue_size: u8,
    /// Number of unwind code slots.
    pub unwind_code_count: u8,
    /// Frame register (0 if none).
    pub frame_register: u8,
    /// Frame register offset (scaled by 16).
    pub frame_register_offset: u8,
    /// Unwind codes array.
    pub unwind_codes: Vec<SehUnwindOp>,
    /// Handler routine (RVA, 0 if none).
    pub exception_handler: u32,
    /// Handler data (RVA, 0 if none).
    pub handler_data: u32,
}

impl Default for Win64UnwindInfo {
    fn default() -> Self {
        Win64UnwindInfo {
            version: 1,
            flags: 0,
            prologue_size: 0,
            unwind_code_count: 0,
            frame_register: 0,
            frame_register_offset: 0,
            unwind_codes: Vec::new(),
            exception_handler: 0,
            handler_data: 0,
        }
    }
}

impl X86FrameLowering {
    /// Build complete Win64 unwind information for a function.
    ///
    /// This generates the .pdata and .xdata entries required by the Windows
    /// x64 exception handling mechanism. The unwind codes describe how to
    /// reverse the prologue to unwind the stack.
    pub fn build_win64_unwind_info(
        &self,
        frame_info: &X86FrameInfo,
        prologue_size: u8,
    ) -> Win64UnwindInfo {
        let mut info = Win64UnwindInfo::default();
        info.version = 1;
        info.prologue_size = prologue_size;

        // Build unwind codes in reverse order (as required by the spec)
        let mut codes = Vec::new();

        // End of prologue (always first in the reverse-order list)
        codes.push(SehUnwindOp::EndPrologue);

        // Frame pointer setup
        if frame_info.has_frame_pointer {
            codes.push(SehUnwindOp::SetFpReg);
            info.frame_register = RBP as u8;
            // Frame register offset = (RSP - RBP) / 16 after prologue
            // For a simple push rbp; mov rbp, rsp: offset is 0
            info.frame_register_offset = 0;
        }

        // Stack allocation
        if frame_info.frame_size > 0 {
            let alloc_size = self.align_frame_size(frame_info.frame_size, STACK_ALIGNMENT);
            if alloc_size <= 128 {
                codes.push(SehUnwindOp::AllocSmall(alloc_size));
            } else if alloc_size <= 524280 {
                codes.push(SehUnwindOp::AllocLarge(alloc_size));
            }
        }

        // Register saves (pushed in reverse order for unwind codes)
        // The unwind codes list is processed LIFO, so we list saves in
        // the order they would be undone (last push = first in list)
        for &reg in frame_info.saved_regs.iter() {
            if reg != self.call_conv.frame_pointer_reg() {
                codes.push(SehUnwindOp::PushNonVol(reg));
            }
        }

        // Push of frame pointer register (if used)
        if frame_info.has_frame_pointer {
            codes.push(SehUnwindOp::PushNonVol(self.call_conv.frame_pointer_reg()));
        }

        info.unwind_code_count = codes.len() as u8;
        info.unwind_codes = codes;

        info
    }

    /// Generate SEH .xdata assembly directives.
    pub fn emit_seh_directives(&self, unwind_info: &Win64UnwindInfo) -> Vec<String> {
        let mut directives = Vec::new();

        directives.push(format!(".seh_proc main",));

        for code in &unwind_info.unwind_codes {
            match *code {
                SehUnwindOp::PushNonVol(reg) => {
                    directives.push(format!(".seh_pushreg {}", reg));
                }
                SehUnwindOp::AllocLarge(size) => {
                    directives.push(format!(".seh_stackalloc {}", size));
                }
                SehUnwindOp::AllocSmall(size) => {
                    directives.push(format!(".seh_stackalloc {}", size));
                }
                SehUnwindOp::SetFpReg => {
                    directives.push(".seh_setframe %rbp, 0".to_string());
                }
                SehUnwindOp::SaveNonVol(reg, offset) => {
                    directives.push(format!(".seh_savereg {}, {}", reg, offset));
                }
                SehUnwindOp::SaveXmm128(reg, offset) => {
                    directives.push(format!(".seh_savexmm {}, {}", reg, offset));
                }
                SehUnwindOp::PushMachFrame => {
                    directives.push(".seh_pushframe".to_string());
                }
                SehUnwindOp::EndPrologue => {
                    directives.push(".seh_endprologue".to_string());
                }
            }
        }

        if unwind_info.exception_handler != 0 {
            directives.push(format!(".seh_handler __C_specific_handler, @except",));
        }

        directives.push(".seh_endproc".to_string());

        directives
    }
}

// ============================================================================
// Shrink Wrapping — move callee-save spills to cold path
// ============================================================================

/// Analysis result for shrink wrapping.
#[derive(Debug, Clone)]
pub struct ShrinkWrapInfo {
    /// Whether shrink wrapping is profitable for this function.
    pub profitable: bool,
    /// The basic block where saves should be placed (instead of entry).
    pub save_block: Option<usize>,
    /// The basic block where restores should be placed.
    pub restore_block: Option<usize>,
    /// Registers that can be shrink-wrapped (not used on early-exit paths).
    pub shrinkable_regs: Vec<u16>,
}

impl Default for ShrinkWrapInfo {
    fn default() -> Self {
        ShrinkWrapInfo {
            profitable: false,
            save_block: None,
            restore_block: None,
            shrinkable_regs: Vec::new(),
        }
    }
}

impl X86FrameLowering {
    /// Analyze whether shrink wrapping is beneficial.
    ///
    /// Shrink wrapping moves callee-saved register saves/restores from the
    /// function entry/exit to colder code paths. This is profitable when:
    /// - The function has early-exit paths (guard checks, fast returns)
    /// - Those early-exit paths don't use the callee-saved registers
    /// - The function has enough basic blocks to justify the complexity
    ///
    /// Returns a `ShrinkWrapInfo` describing where saves/restores should move.
    pub fn analyze_shrink_wrap(&self, mf: &MachineFunction) -> ShrinkWrapInfo {
        let mut info = ShrinkWrapInfo::default();

        // Don't shrink-wrap trivial functions
        if mf.blocks.len() < 2 {
            return info;
        }

        // Identify early-exit blocks (blocks that return and are
        // reachable without going through the main body)
        let callee_saved = self.call_conv.callee_saved_regs().to_vec();

        // For each callee-saved register, check if it's used in all
        // paths. If some paths don't use it, it's a shrink-wrap candidate.
        for &reg in &callee_saved {
            let mut used_in_all = true;

            for (block_idx, bb) in mf.blocks.iter().enumerate() {
                // Skip entry block (always uses saved regs if any)
                if block_idx == 0 {
                    continue;
                }

                // Check if this block is an early return (has RET)
                let is_ret_block = bb
                    .instructions
                    .iter()
                    .any(|mi| mi.opcode == X86Opcode::RET as u32);

                if is_ret_block {
                    let reg_used = bb.instructions.iter().any(|mi| {
                        mi.operands.iter().any(|op| {
                            if let MachineOperand::PhysReg(r) = *op {
                                r == reg as u32
                            } else {
                                false
                            }
                        })
                    });

                    if !reg_used {
                        used_in_all = false;
                        break;
                    }
                }
            }

            if !used_in_all {
                info.shrinkable_regs.push(reg);
            }
        }

        info.profitable = !info.shrinkable_regs.is_empty();

        // Determine save/restore placement
        if info.profitable {
            // Find the first block after entry that uses any callee-saved reg
            let mut first_use_block: Option<usize> = None;
            for (idx, bb) in mf.blocks.iter().enumerate().skip(1) {
                let uses_any = info.shrinkable_regs.iter().any(|&sr| {
                    bb.instructions.iter().any(|mi| {
                        mi.operands.iter().any(|op| {
                            if let MachineOperand::PhysReg(r) = *op {
                                r == sr as u32
                            } else {
                                false
                            }
                        })
                    })
                });
                if uses_any {
                    first_use_block = Some(idx);
                    break;
                }
            }

            if let Some(idx) = first_use_block {
                info.save_block = Some(idx);
                info.restore_block = Some(mf.blocks.len() - 1); // last block (usually has RET)
            }
        }

        info
    }

    /// Emit shrink-wrapped save sequence at a specific block.
    pub fn emit_shrink_wrapped_saves(&self, regs: &[u16], fp: u16) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();
        for &reg in regs {
            if reg != fp {
                instrs.push(self.build_push(reg));
            }
        }
        instrs
    }

    /// Emit shrink-wrapped restore sequence at a specific block.
    pub fn emit_shrink_wrapped_restores(&self, regs: &[u16], fp: u16) -> Vec<MachineInstr> {
        let mut instrs = Vec::new();
        for &reg in regs.iter().rev() {
            if reg != fp {
                instrs.push(self.build_pop(reg));
            }
        }
        instrs
    }
}

// ============================================================================
// DWARF Call Frame Information — .cfi_* directives
// ============================================================================

/// DWARF CFI directive for call frame unwinding.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CfiDirective {
    /// Define CFA rule: .cfi_def_cfa register, offset
    DefCfa(u16, i64),
    /// CFA offset: .cfi_def_cfa_offset offset
    DefCfaOffset(i64),
    /// CFA register: .cfi_def_cfa_register register
    DefCfaRegister(u16),
    /// Register offset from CFA: .cfi_offset register, offset
    Offset(u16, i64),
    /// Register is same value: .cfi_same_value register
    SameValue(u16),
    /// Register value: .cfi_register register, register2
    Register(u16, u16),
    /// Restore register to initial rule: .cfi_restore register
    Restore(u16),
    /// Remember state: .cfi_remember_state
    RememberState,
    /// Restore state: .cfi_restore_state
    RestoreState,
    /// Undefined register: .cfi_undefined register
    Undefined(u16),
    /// Escape bytes: .cfi_escape bytes...
    Escape(Vec<u8>),
    /// GNU window save: .cfi_window_save
    WindowSave,
    /// Argument pointer: .cfi_arg_pointer register
    ArgPointer(u16),
    /// Return address register: .cfi_return_column register
    ReturnColumn(u16),
    /// Signal frame: .cfi_signal_frame
    SignalFrame,
}

/// Call frame information for a function.
#[derive(Debug, Clone)]
pub struct CallFrameInfo {
    /// CFA (Canonical Frame Address) register.
    pub cfa_register: u16,
    /// CFA offset (from CFA register to CFA).
    pub cfa_offset: i64,
    /// Register offset rules: maps register to offset from CFA.
    pub reg_offsets: HashMap<u16, i64>,
    /// Register rules: maps register to the register holding its value.
    pub reg_rules: HashMap<u16, u16>,
    /// Return address column.
    pub return_column: u16,
}

impl Default for CallFrameInfo {
    fn default() -> Self {
        CallFrameInfo {
            cfa_register: RSP,
            cfa_offset: PUSH_SIZE_64, // return address pushed by CALL
            reg_offsets: HashMap::new(),
            reg_rules: HashMap::new(),
            return_column: 16, // RIP is DWARF register 16 on x86-64
        }
    }
}

impl X86FrameLowering {
    /// Build DWARF CFI directives for the function prologue.
    ///
    /// Generates a sequence of `.cfi_*` directives that describe how to
    /// unwind the stack at each point in the prologue.
    pub fn build_cfi_prologue(
        &self,
        frame_info: &X86FrameInfo,
        use_dwarf: bool,
    ) -> Vec<CfiDirective> {
        if !use_dwarf {
            return Vec::new();
        }

        let mut cfi = Vec::new();
        let fp = self.call_conv.frame_pointer_reg();

        if frame_info.has_frame_pointer {
            // Step 1: push rbp
            // CFA is now at RSP + 16 (return address 8 + saved RBP 8)
            cfi.push(CfiDirective::DefCfaOffset(PUSH_SIZE_64 * 2));
            cfi.push(CfiDirective::Offset(fp, -(PUSH_SIZE_64 * 2)));

            // Step 2: mov rbp, rsp
            // CFA is now [RBP + 16]
            cfi.push(CfiDirective::DefCfaRegister(fp));
        } else {
            // No frame pointer: CFA stays at RSP + adjustment
            if frame_info.frame_size > 0 {
                let alloc_size = self.align_frame_size(frame_info.frame_size, STACK_ALIGNMENT);
                cfi.push(CfiDirective::DefCfaOffset(PUSH_SIZE_64 + alloc_size));
            }
        }

        // Callee-saved register offsets (from CFA)
        let mut offset_from_cfa = if frame_info.has_frame_pointer {
            PUSH_SIZE_64 * 2
        } else {
            PUSH_SIZE_64
        };

        for &reg in &frame_info.saved_regs {
            if reg != fp {
                cfi.push(CfiDirective::Offset(reg, -offset_from_cfa));
                offset_from_cfa += self.call_conv.push_size();
            }
        }

        // Return address
        cfi.push(CfiDirective::Offset(16, -PUSH_SIZE_64));

        cfi
    }

    /// Build DWARF CFI directives for the function epilogue.
    ///
    /// Generates directives to restore the CFA and register states.
    pub fn build_cfi_epilogue(
        &self,
        frame_info: &X86FrameInfo,
        use_dwarf: bool,
    ) -> Vec<CfiDirective> {
        if !use_dwarf {
            return Vec::new();
        }

        let mut cfi = Vec::new();
        let fp = self.call_conv.frame_pointer_reg();
        let sp = self.call_conv.stack_pointer_reg();

        // Restore all callee-saved registers
        for &reg in &frame_info.saved_regs {
            cfi.push(CfiDirective::Restore(reg));
        }

        if frame_info.has_frame_pointer {
            // Pop rbp restores CFA to RSP + 8
            cfi.push(CfiDirective::Restore(fp));
            cfi.push(CfiDirective::DefCfa(sp, PUSH_SIZE_64));
        } else {
            // Restore SP
            cfi.push(CfiDirective::DefCfa(sp, PUSH_SIZE_64));
        }

        cfi
    }

    /// Emit CFI directives as assembly directives for the assembler.
    pub fn emit_cfi_directives(&self, cfi: &[CfiDirective]) -> Vec<String> {
        let mut lines = Vec::new();

        for directive in cfi {
            match *directive {
                CfiDirective::DefCfa(reg, offset) => {
                    lines.push(format!(".cfi_def_cfa {}, {}", reg, offset));
                }
                CfiDirective::DefCfaOffset(offset) => {
                    lines.push(format!(".cfi_def_cfa_offset {}", offset));
                }
                CfiDirective::DefCfaRegister(reg) => {
                    lines.push(format!(".cfi_def_cfa_register {}", reg));
                }
                CfiDirective::Offset(reg, offset) => {
                    lines.push(format!(".cfi_offset {}, {}", reg, offset));
                }
                CfiDirective::SameValue(reg) => {
                    lines.push(format!(".cfi_same_value {}", reg));
                }
                CfiDirective::Register(reg1, reg2) => {
                    lines.push(format!(".cfi_register {}, {}", reg1, reg2));
                }
                CfiDirective::Restore(reg) => {
                    lines.push(format!(".cfi_restore {}", reg));
                }
                CfiDirective::RememberState => {
                    lines.push(".cfi_remember_state".to_string());
                }
                CfiDirective::RestoreState => {
                    lines.push(".cfi_restore_state".to_string());
                }
                CfiDirective::Undefined(reg) => {
                    lines.push(format!(".cfi_undefined {}", reg));
                }
                CfiDirective::Escape(ref bytes) => {
                    let hex_bytes: Vec<String> =
                        bytes.iter().map(|b| format!("{:02x}", b)).collect();
                    lines.push(format!(".cfi_escape {}", hex_bytes.join(", ")));
                }
                CfiDirective::WindowSave => {
                    lines.push(".cfi_window_save".to_string());
                }
                CfiDirective::ArgPointer(reg) => {
                    lines.push(format!(".cfi_arg_pointer {}", reg));
                }
                CfiDirective::ReturnColumn(reg) => {
                    lines.push(format!(".cfi_return_column {}", reg));
                }
                CfiDirective::SignalFrame => {
                    lines.push(".cfi_signal_frame".to_string());
                }
            }
        }

        lines
    }
}

// ============================================================================
// Spill Slot Computation — assigning stack slots to virtual registers
// ============================================================================

/// Represents a stack slot assigned to a virtual register spill.
#[derive(Debug, Clone)]
pub struct SpillSlot {
    /// The virtual register this slot is for.
    pub vreg: VirtReg,
    /// Offset from the frame base (negative for below FP/RSP).
    pub offset: i64,
    /// Size of the spill slot in bytes.
    pub size: i64,
    /// Required alignment for this slot.
    pub alignment: i64,
    /// Register class of the spilled register.
    pub reg_class: SpillSlotClass,
    /// Whether this slot is fixed (cannot be moved).
    pub fixed: bool,
}

/// Register class for spill slot sizing and alignment.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SpillSlotClass {
    /// 8-byte GPR (RBX, R12, etc.)
    Gpr64,
    /// 4-byte GPR (EBX, etc.)
    Gpr32,
    /// 2-byte GPR
    Gpr16,
    /// 1-byte GPR
    Gpr8,
    /// 16-byte XMM register
    Xmm128,
    /// 32-byte YMM register (AVX)
    Ymm256,
    /// 64-byte ZMM register (AVX-512)
    Zmm512,
    /// 8-byte x87 FPU
    X87,
    /// 8-byte MMX
    Mmx64,
}

impl SpillSlotClass {
    /// Returns the size in bytes for this register class.
    pub fn size(&self) -> i64 {
        match self {
            SpillSlotClass::Gpr64 | SpillSlotClass::X87 | SpillSlotClass::Mmx64 => 8,
            SpillSlotClass::Gpr32 => 4,
            SpillSlotClass::Gpr16 => 2,
            SpillSlotClass::Gpr8 => 1,
            SpillSlotClass::Xmm128 => 16,
            SpillSlotClass::Ymm256 => 32,
            SpillSlotClass::Zmm512 => 64,
        }
    }

    /// Returns the required alignment for this register class.
    pub fn alignment(&self) -> i64 {
        match self {
            SpillSlotClass::Gpr64
            | SpillSlotClass::Gpr32
            | SpillSlotClass::Gpr16
            | SpillSlotClass::Gpr8 => PUSH_SIZE_64,
            SpillSlotClass::Xmm128 => XMM_SAVE_ALIGN,
            SpillSlotClass::Ymm256 => YMM_SAVE_ALIGN,
            SpillSlotClass::Zmm512 => ZMM_SAVE_ALIGN,
            SpillSlotClass::X87 | SpillSlotClass::Mmx64 => 8,
        }
    }
}

impl X86FrameLowering {
    /// Compute spill slot assignments for all spilled virtual registers.
    ///
    /// Allocates stack space for each spilled register, packing them
    /// efficiently while respecting alignment constraints. Returns a
    /// mapping from virtual register to its spill slot.
    pub fn compute_spill_slots(
        &self,
        spilled: &[(VirtReg, SpillSlotClass)],
        base_offset: i64,
    ) -> HashMap<VirtReg, SpillSlot> {
        let mut slots = HashMap::new();
        let mut current_offset = base_offset;

        // Sort by alignment (largest first) for optimal packing
        let mut sorted: Vec<_> = spilled.to_vec();
        sorted.sort_by(|a, b| b.1.alignment().cmp(&a.1.alignment()));

        for &(vreg, class) in &sorted {
            let align = class.alignment();
            let size = class.size();

            // Align the offset downward
            current_offset = self.align_frame_size(current_offset, align);

            slots.insert(
                vreg,
                SpillSlot {
                    vreg,
                    offset: current_offset,
                    size,
                    alignment: align,
                    reg_class: class,
                    fixed: false,
                },
            );

            current_offset += size;
        }

        slots
    }

    /// Compute the total spill area size for a set of registers.
    pub fn compute_spill_area_size(&self, spills: &[(VirtReg, SpillSlotClass)]) -> i64 {
        let slots = self.compute_spill_slots(spills, 0);

        if slots.is_empty() {
            return 0;
        }

        let max_end = slots.values().map(|s| s.offset + s.size).max().unwrap_or(0);

        self.align_frame_size(max_end, STACK_ALIGNMENT)
    }

    /// Decide the register class for a virtual register based on its usage.
    pub fn classify_spill_slot(&self, bit_width: u16) -> SpillSlotClass {
        match bit_width {
            1..=8 => SpillSlotClass::Gpr8,
            9..=16 => SpillSlotClass::Gpr16,
            17..=32 => SpillSlotClass::Gpr32,
            33..=64 => SpillSlotClass::Gpr64,
            65..=128 => SpillSlotClass::Xmm128,
            129..=256 => SpillSlotClass::Ymm256,
            257..=512 => SpillSlotClass::Zmm512,
            _ => SpillSlotClass::Gpr64, // default
        }
    }
}

// ============================================================================
// Frame Pointer Elimination — when to omit FP and use SP-relative
// ============================================================================

/// Decision information for frame pointer elimination.
#[derive(Debug, Clone)]
pub struct FramePointerElimInfo {
    /// Whether frame pointer elimination is performed.
    pub eliminated: bool,
    /// Reason for keeping the frame pointer (if not eliminated).
    pub reason: Option<FpElimReason>,
    /// Total frame offset to track instead of FP-relative.
    pub sp_offset: i64,
}

/// Reasons for keeping the frame pointer.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FpElimReason {
    /// Variable-sized stack objects (alloca/VLA).
    VarSizedObjects,
    /// Inline assembly that clobbers the stack pointer.
    InlineAsmClobberSp,
    /// Dynamic stack realignment required.
    StackRealignment,
    /// Function has too many locals for SP-relative addressing (x86-32).
    ManyLocals32,
    /// Debugging or profiling requires frame pointer.
    DebugInfo,
    /// Explicitly requested (e.g., -fno-omit-frame-pointer).
    ExplicitRequest,
}

impl X86FrameLowering {
    /// Determine whether frame pointer elimination can be performed.
    ///
    /// The frame pointer can be eliminated (omitted) when:
    /// - No variable-sized objects (alloca with dynamic size, VLAs)
    /// - No inline assembly that clobbers the stack pointer
    /// - No dynamic stack realignment requirement
    /// - The function's frame fits within SP-relative addressing
    /// - Debug info doesn't require FP (or we use DWARF CFI instead)
    pub fn can_eliminate_frame_pointer(
        &self,
        frame_info: &X86FrameInfo,
        has_inline_asm: bool,
        force_frame_pointer: bool,
        max_sp_offset: i64,
    ) -> FramePointerElimInfo {
        let mut info = FramePointerElimInfo {
            eliminated: false,
            reason: None,
            sp_offset: 0,
        };

        if force_frame_pointer {
            info.reason = Some(FpElimReason::ExplicitRequest);
            return info;
        }

        if frame_info.has_var_sized_objects {
            info.reason = Some(FpElimReason::VarSizedObjects);
            return info;
        }

        if has_inline_asm {
            // Conservative: assume inline asm may clobber SP
            info.reason = Some(FpElimReason::InlineAsmClobberSp);
            return info;
        }

        // On 32-bit, SP-relative addressing is limited to addressing modes
        // that may not cover large frames well
        if self.call_conv.is_32bit() && frame_info.frame_size > max_sp_offset {
            info.reason = Some(FpElimReason::ManyLocals32);
            return info;
        }

        // On 64-bit, SP-relative with large displacements works fine
        info.eliminated = true;
        info.sp_offset = frame_info.frame_size;
        info
    }

    /// Adjust SP-relative offset tracking throughout the function.
    ///
    /// When the frame pointer is eliminated, the compiler must track
    /// the current SP offset after every instruction that modifies SP.
    /// This function computes the adjusted offset.
    pub fn adjust_sp_offset(
        &self,
        current_offset: i64,
        opcode: u32,
        operands: &[MachineOperand],
    ) -> i64 {
        // Match against known X86Opcode discriminants
        match opcode {
            11u32 => current_offset + self.call_conv.push_size(), // PUSH
            12u32 => current_offset - self.call_conv.push_size(), // POP
            3u32 => {
                // SUB: If SUB targets RSP with an immediate, adjust offset
                if operands.len() >= 2 {
                    if let (MachineOperand::PhysReg(reg), MachineOperand::Imm(amount)) =
                        (&operands[0], &operands[1])
                    {
                        if *reg == self.call_conv.stack_pointer_reg() as u32 {
                            return current_offset + amount;
                        }
                    }
                }
                current_offset
            }
            2u32 => {
                // ADD: If ADD targets RSP with an immediate, adjust offset
                if operands.len() >= 2 {
                    if let (MachineOperand::PhysReg(reg), MachineOperand::Imm(amount)) =
                        (&operands[0], &operands[1])
                    {
                        if *reg == self.call_conv.stack_pointer_reg() as u32 {
                            return current_offset - amount;
                        }
                    }
                }
                current_offset
            }
            14u32 => {
                // CALL: pushes return address, but callee restores
                // SP before returning, so offset remains unchanged
                current_offset
            }
            _ => current_offset,
        }
    }
}

// ============================================================================
// Red Zone Handling — skip SP adjustment for leaf functions
// ============================================================================

impl X86FrameLowering {
    /// Determine if the function can use the red zone for its entire frame.
    ///
    /// The red zone is the 128 bytes below RSP that are reserved by the
    /// System V AMD64 ABI and can be used without adjusting RSP. Conditions:
    /// - Calling convention is System V (Linux, macOS)
    /// - Function is a leaf (makes no calls)
    /// - Frame size fits within the red zone (128 bytes)
    /// - No signal handlers or interrupt handlers in the function
    pub fn can_use_red_zone(&self, frame_info: &X86FrameInfo, is_signal_handler: bool) -> bool {
        if !self.call_conv.uses_red_zone() {
            return false;
        }
        if is_signal_handler {
            return false; // signal handlers must not use red zone
        }
        if frame_info.has_calls {
            return false; // calls clobber the red zone
        }
        if frame_info.has_var_sized_objects {
            return false; // dynamic SP adjustment cannot use red zone
        }
        frame_info.frame_size <= RED_ZONE_SIZE
    }

    /// Compute the effective red zone usage for a leaf function.
    ///
    /// Returns the amount of red zone that can be safely used. If the
    /// function can use the red zone, emit a NOP-adjusted prologue that
    /// doesn't modify RSP (just pushes RBP and maybe saves registers).
    pub fn compute_red_zone_usage(
        &self,
        frame_info: &X86FrameInfo,
        is_signal_handler: bool,
    ) -> i64 {
        if self.can_use_red_zone(frame_info, is_signal_handler) {
            frame_info.frame_size
        } else {
            0
        }
    }
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    // === Helper functions ===

    fn make_empty_mf(name: &str) -> MachineFunction {
        MachineFunction::new(name)
    }

    #[allow(dead_code)]
    fn make_leaf_mf(name: &str) -> MachineFunction {
        let mut mf = MachineFunction::new(name);
        let mut bb = MachineBasicBlock {
            name: "entry".to_string(),
            instructions: Vec::new(),
            successors: Vec::new(),
        };
        // Add some ALU instructions that use callee-saved regs
        bb.instructions.push({
            let mut mi = MachineInstr::new(X86Opcode::ADD as u32);
            mi.operands.push(MachineOperand::PhysReg(RBX as u32));
            mi.operands.push(MachineOperand::PhysReg(R12 as u32));
            mi
        });
        bb.instructions.push({
            let mut mi = MachineInstr::new(X86Opcode::RET as u32);
            mi
        });
        mf.push_block(bb);
        mf
    }

    fn make_mf_with_calls(name: &str) -> MachineFunction {
        let mut mf = MachineFunction::new(name);
        let mut bb = MachineBasicBlock {
            name: "entry".to_string(),
            instructions: Vec::new(),
            successors: Vec::new(),
        };
        bb.instructions.push({
            let mut mi = MachineInstr::new(X86Opcode::CALL as u32);
            mi.operands
                .push(MachineOperand::Label("other_func".to_string()));
            mi
        });
        bb.instructions.push({
            let mut mi = MachineInstr::new(X86Opcode::RET as u32);
            mi
        });
        mf.push_block(bb);
        mf
    }

    // === CallConv Tests ===

    #[test]
    fn test_call_conv_uses_red_zone() {
        assert!(CallConv::SystemV.uses_red_zone());
        assert!(!CallConv::Win64.uses_red_zone());
        assert!(!CallConv::CDecl32.uses_red_zone());
    }

    #[test]
    fn test_call_conv_is_64bit() {
        assert!(CallConv::SystemV.is_64bit());
        assert!(CallConv::Win64.is_64bit());
        assert!(!CallConv::CDecl32.is_64bit());
        assert!(!CallConv::StdCall32.is_64bit());
    }

    #[test]
    fn test_call_conv_is_32bit() {
        assert!(!CallConv::SystemV.is_32bit());
        assert!(!CallConv::Win64.is_32bit());
        assert!(CallConv::CDecl32.is_32bit());
        assert!(CallConv::FastCall32.is_32bit());
    }

    #[test]
    fn test_call_conv_push_size() {
        assert_eq!(CallConv::SystemV.push_size(), 8);
        assert_eq!(CallConv::Win64.push_size(), 8);
        assert_eq!(CallConv::CDecl32.push_size(), 4);
        assert_eq!(CallConv::StdCall32.push_size(), 4);
    }

    #[test]
    fn test_call_conv_callee_saved_regs() {
        let sysv = CallConv::SystemV.callee_saved_regs();
        assert!(sysv.contains(&RBX));
        assert!(sysv.contains(&R12));
        assert!(sysv.contains(&R15));

        let win64 = CallConv::Win64.callee_saved_regs();
        assert!(win64.contains(&RBX));
        assert!(win64.contains(&RDI_CONST));
        assert!(win64.contains(&RSI_CONST));

        let cdecl32 = CallConv::CDecl32.callee_saved_regs();
        assert!(cdecl32.contains(&EBX32));
        assert!(cdecl32.contains(&ESI32));
    }

    // === X86FrameInfo Tests ===

    #[test]
    fn test_frame_info_default() {
        let info = X86FrameInfo::new();
        assert_eq!(info.frame_size, 0);
        assert_eq!(info.saved_regs.len(), 0);
        assert!(!info.has_frame_pointer);
        assert!(!info.has_calls);
        assert!(!info.uses_red_zone);
    }

    #[test]
    fn test_frame_info_total_frame_size() {
        let mut info = X86FrameInfo::new();
        info.frame_size = 48;
        assert_eq!(info.total_frame_size(), 48);
    }

    // === X86FrameLowering Tests ===

    #[test]
    fn test_frame_lowering_new() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        assert_eq!(fl.call_conv, CallConv::SystemV);
    }

    #[test]
    fn test_frame_lowering_default() {
        let fl = X86FrameLowering::default();
        assert_eq!(fl.call_conv, CallConv::SystemV);
    }

    #[test]
    fn test_align_frame_size() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        assert_eq!(fl.align_frame_size(0, 16), 0);
        assert_eq!(fl.align_frame_size(16, 16), 16);
        assert_eq!(fl.align_frame_size(17, 16), 32);
        assert_eq!(fl.align_frame_size(20, 16), 32);
        assert_eq!(fl.align_frame_size(31, 16), 32);
        assert_eq!(fl.align_frame_size(32, 16), 32);
        assert_eq!(fl.align_frame_size(33, 16), 48);
    }

    #[test]
    fn test_calculate_frame_size() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mut info = X86FrameInfo::new();
        info.callee_saved_size = 16; // 2 saved regs
        info.local_area_offset = -24;
        info.max_call_frame_size = 8;
        let size = fl.calculate_frame_size(&info);
        // 16 + 24 + 8 = 48, already aligned to 16
        assert_eq!(size, 48);

        // Unaligned case
        let mut info2 = X86FrameInfo::new();
        info2.callee_saved_size = 8; // 1 saved reg
        info2.local_area_offset = -10;
        info2.max_call_frame_size = 0;
        let size2 = fl.calculate_frame_size(&info2);
        // 8 + 10 = 18 -> aligned to 32
        assert_eq!(size2, 32);
    }

    #[test]
    fn test_needs_frame_pointer_var_sized() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mut info = X86FrameInfo::new();
        info.has_var_sized_objects = true;
        assert!(fl.needs_frame_pointer(&info));
    }

    #[test]
    fn test_needs_frame_pointer_large_frame_with_calls() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mut info = X86FrameInfo::new();
        info.has_calls = true;
        info.frame_size = 256;
        assert!(fl.needs_frame_pointer(&info));
    }

    #[test]
    fn test_needs_frame_pointer_small_leaf() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mut info = X86FrameInfo::new();
        info.has_calls = false;
        info.frame_size = 64; // fits in red zone
        assert!(!fl.needs_frame_pointer(&info));
    }

    #[test]
    fn test_needs_frame_pointer_32bit() {
        let fl = X86FrameLowering::new(CallConv::CDecl32);
        let mut info = X86FrameInfo::new();
        info.frame_size = 16;
        assert!(fl.needs_frame_pointer(&info));
    }

    #[test]
    fn test_needs_frame_pointer_huge_frame() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mut info = X86FrameInfo::new();
        info.frame_size = 8192;
        assert!(fl.needs_frame_pointer(&info));
    }

    #[test]
    fn test_build_frame_info_leaf() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mf = make_leaf_mf("leaf_func");
        let info = fl.build_frame_info(&mf);
        assert!(!info.has_calls);
        // Leaf function with used callee-saved regs should detect them
        assert!(!info.saved_regs.is_empty());
        assert!(info.uses_red_zone || info.frame_size <= RED_ZONE_SIZE);
    }

    #[test]
    fn test_build_frame_info_with_calls() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mf = make_mf_with_calls("caller_func");
        let info = fl.build_frame_info(&mf);
        assert!(info.has_calls);
        assert!(!info.uses_red_zone);
    }

    #[test]
    fn test_emit_prologue_basic() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mut mf = make_leaf_mf("basic_func");
        // Manually set up some frame info expectations
        let instrs = fl.emit_prologue(&mut mf);
        // Even for a trivial function, we should get prologue instructions
        assert!(!instrs.is_empty(), "Prologue should emit instructions");
    }

    #[test]
    fn test_emit_epilogue_basic() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mut mf = make_empty_mf("basic_func");
        let instrs = fl.emit_epilogue(&mut mf);
        assert!(!instrs.is_empty(), "Epilogue should emit instructions");
        // Last instruction should be RET
        let last = instrs.last().unwrap();
        assert_eq!(last.opcode, X86Opcode::RET as u32);
    }

    #[test]
    fn test_emit_prologue_win64() {
        let fl = X86FrameLowering::new(CallConv::Win64);
        let mut mf = make_leaf_mf("win64_func");
        let instrs = fl.emit_prologue(&mut mf);
        assert!(!instrs.is_empty());
        // Win64 should use 64-bit push (check opcode)
        let push_count = instrs
            .iter()
            .filter(|i| i.opcode == X86Opcode::PUSH as u32)
            .count();
        assert!(
            push_count > 0,
            "Win64 prologue should contain push instructions"
        );
    }

    #[test]
    fn test_emit_prologue_32() {
        let fl = X86FrameLowering::new(CallConv::CDecl32);
        let mut mf = make_empty_mf("cdecl32_func");
        let instrs = fl.emit_prologue_32(&mut mf);
        assert!(!instrs.is_empty());
        let push_count = instrs
            .iter()
            .filter(|i| i.opcode == X86Opcode::PUSH as u32)
            .count();
        assert!(
            push_count > 0,
            "32-bit prologue should contain push instructions"
        );
    }

    #[test]
    fn test_emit_epilogue_32() {
        let fl = X86FrameLowering::new(CallConv::CDecl32);
        let mut mf = make_empty_mf("cdecl32_func");
        let instrs = fl.emit_epilogue_32(&mut mf);
        assert!(!instrs.is_empty());
        let last = instrs.last().unwrap();
        assert_eq!(last.opcode, X86Opcode::RET as u32);
    }

    #[test]
    fn test_assign_callee_saved_spill_slots() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mf = make_leaf_mf("spill_test");
        let slots = fl.assign_callee_saved_spill_slots(&mf);
        // Should have slots for used callee-saved regs (RBX and R12 from make_leaf_mf)
        assert!(!slots.is_empty(), "Should have spill slots for used regs");
        // Verify offsets are negative
        for (_reg, offset) in &slots {
            assert!(*offset < 0, "Spill slot offsets should be negative");
        }
    }

    #[test]
    fn test_get_frame_index_reference() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mut mf = make_empty_mf("fi_test");
        let instrs = fl.get_frame_index_reference(&mut mf, 0, 0);
        assert!(!instrs.is_empty());
        // Should produce a load instruction
        let load = &instrs[0];
        assert_eq!(load.opcode, X86Opcode::MOV as u32);
        assert!(load.def.is_some(), "Load should define a virtual register");
    }

    #[test]
    fn test_prologue_epilogue_roundtrip() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mut mf = make_empty_mf("roundtrip");
        let prologue = fl.emit_prologue(&mut mf);
        let epilogue = fl.emit_epilogue(&mut mf);

        // Prologue should save things, epilogue should restore them
        let prologue_pushes: Vec<_> = prologue
            .iter()
            .filter(|i| i.opcode == X86Opcode::PUSH as u32)
            .collect();
        let epilogue_pops: Vec<_> = epilogue
            .iter()
            .filter(|i| i.opcode == X86Opcode::POP as u32)
            .collect();
        // Number of saves should match number of restores (roughly)
        assert!(
            epilogue_pops.len() >= prologue_pushes.len(),
            "Epilogue should restore at least as many regs as prologue saves"
        );
    }

    #[test]
    fn test_red_zone_detection() {
        let fl = X86FrameLowering::new(CallConv::SystemV);
        let mf = make_leaf_mf("red_zone_test");
        let info = fl.build_frame_info(&mf);
        // Leaf functions with small frames should use red zone
        // The actual result depends on frame size calculation
        if !info.has_calls {
            // Red zone will be used if frame size is small enough
            assert!(
                info.uses_red_zone || info.frame_size > RED_ZONE_SIZE,
                "Leaf with small frame should use red zone, or frame_size exceeded red zone"
            );
        }
    }
}