llvm-native-core 0.1.6

//! X86 Frame Lowering Extensions — advanced frame management beyond basic
//! prologue/epilogue. Implements shrink wrapping, local stack slot allocation
//! with graph coloring, slot merging, frame pointer vs stack pointer relative
//! access selection, emergency spill slot allocation, dynamic stack realignment
//! with AND, segmented stacks, safestack layout, stack clash protection,
//! patchpoint/stackmap frame handling, varargs frame setup per ABI, sret
//! demotion frame handling, and callee-saved register frame assignment.
//!
//! Clean-room behavioral reconstruction from:
//! - Intel® 64 and IA-32 Architectures Software Developer's Manual, Vol. 1 (Chapter 6: Stack)
//! - System V ABI: AMD64 Architecture Processor Supplement (stack frame, red zone, varargs)
//! - Microsoft x64 Software Conventions (shadow space, stack walking, varargs)
//! - GCC/LLVM shrink wrapping and stack realignment literature
//! - Linux kernel segmented stacks and stack clash protection
//! - PatchPoint/StackMap ABI specifications
//!
//! Coverage:
//! - Shrink wrapping: save/restore placement minimizing executed saves,
//!   domination-based save placement, post-domination restore placement,
//!   loop-aware save hoisting, multi-register save grouping
//! - Local stack slot allocation with graph coloring: interference graph
//!   construction, greedy coloring, slot merging by lifetime analysis,
//!   alignment-aware slot placement, vector slot handling
//! - Emergency spill slot allocation: scavenging register analysis,
//!   reserved frame slots, dynamic spill slot allocation during
//!   register scavenging, slot reuse with liveness tracking
//! - Dynamic stack realignment: AND-based alignment adjustment,
//!   alignment prologue/epilogue generation, aligned and unaligned
//!   frame pointer handling, MOVDQ2Q alignment constraints
//! - Segmented stacks: per-function stack limits, stack limit checking,
//!   __morestack call integration, goroutine-style stack growth
//! - SafeStack layout: safe/unsafe stack separation, unsafe stack
//!   pointer tracking, frame setup per stack region
//! - Stack clash protection: probe-based guard page protection,
//!   loop-probe emission, alloca probing, tail-call probing
//! - PatchPoint/StackMap: frame recording, live value tracking,
//!   stack map entry construction, deoptimization frame handling
//! - Varargs frame setup: System V AMD64 va_list registers+stack,
//!   Windows x64 va_list (stack-only), IA-32 cdecl varargs,
//!   registersave area, overflow_arg_area, reg_save_area
//! - Sret demotion: indirect sret pointer handling, frame slot
//!   allocation for demoted returns, alignment requirements
//!
//! Zero LLVM source code consultation. All behavior reconstructed from
//! published specifications and black-box oracle interrogation.

#![allow(non_upper_case_globals, dead_code)]

use crate::codegen::{MachineBasicBlock, MachineFunction, MachineInstr, MachineOperand, VirtReg};
use crate::x86::x86_instr_info::{X86InstrInfo, X86Opcode};
use crate::x86::x86_register_info::{
    EAX, R10, R11, R12, R13, R14, R15, R8, R9, RAX, RBP, RBX, RCX, RDI, RDX, RSI, RSP,
};
use std::collections::{BTreeMap, BTreeSet, BinaryHeap, HashMap, HashSet, VecDeque};

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

/// Minimum stack alignment for X86-64 (16 bytes per ABI).
pub const MIN_STACK_ALIGNMENT: u32 = 16;

/// Maximum stack alignment supported (AVX-512 requires up to 64 bytes).
pub const MAX_STACK_ALIGNMENT: u32 = 64;

/// Size of the Windows x64 shadow space (32 bytes = 4 * 8).
pub const WIN64_SHADOW_SPACE: i64 = 32;

/// Number of emergency spill slots reserved by default.
pub const DEFAULT_EMERGENCY_SLOTS: usize = 2;

/// Size of each emergency spill slot (8 bytes for GPR on x86-64).
pub const EMERGENCY_SLOT_SIZE: i64 = 8;

/// Default probe interval for stack clash protection (4096 = 1 page).
pub const DEFAULT_PROBE_INTERVAL: i64 = 4096;

/// Minimum stack size that triggers stack probing.
pub const MIN_STACK_FOR_PROBING: i64 = 4096;

/// Maximum frame size considered "small" (no probing needed).
pub const SMALL_FRAME_THRESHOLD: i64 = 1024;

/// DRAP (Dynamic Realignment Pointer) alternative register for X86-64.
pub const DRAP_REGISTER_ALT: u16 = R10;

/// DRAP register for IA-32.
pub const DRAP_REGISTER_32: u16 = EAX;

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

/// x86-64 callee-saved registers for shrink wrapping (Microsoft x64).
pub const SHRINK_WRAP_CANDIDATES_WIN64: &[u16] = &[RBX, RSI, RDI, R12, R13, R14, R15];

/// Maximum number of color registers for stack slot coloring.
pub const MAX_SLOT_COLORS: usize = 64;

/// T * (aligned size) threshold for merging small slots.
pub const SLOT_MERGE_SIZE_THRESHOLD: u32 = 16;

/// Maximum number of slots to consider for merging.
pub const MAX_SLOTS_FOR_MERGE: usize = 256;

// ============================================================================
// Calling convention enum for frame lowering
// ============================================================================

/// Calling convention for frame lowering decisions.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum FrameCallConv {
    /// System V AMD64 (Linux, macOS, FreeBSD).
    SystemVAMD64,
    /// Microsoft x64 (Windows).
    Win64,
    /// IA-32 cdecl.
    Cdecl32,
    /// IA-32 stdcall.
    Stdcall32,
    /// IA-32 fastcall.
    Fastcall32,
    /// IA-32 thiscall.
    Thiscall32,
    /// IA-32 vectorcall.
    Vectorcall32,
    /// X86-64 vectorcall.
    Vectorcall64,
}

impl FrameCallConv {
    /// Whether this convention uses a red zone.
    pub fn has_red_zone(&self) -> bool {
        matches!(self, Self::SystemVAMD64)
    }

    /// Whether this convention has a shadow space (home space).
    pub fn has_shadow_space(&self) -> bool {
        matches!(self, Self::Win64)
    }

    /// Whether the convention passes arguments partially in registers.
    pub fn is_register_based(&self) -> bool {
        matches!(
            self,
            Self::SystemVAMD64
                | Self::Win64
                | Self::Fastcall32
                | Self::Vectorcall32
                | Self::Vectorcall64
        )
    }

    /// Whether the convention is 64-bit.
    pub fn is_64bit(&self) -> bool {
        matches!(self, Self::SystemVAMD64 | Self::Win64 | Self::Vectorcall64)
    }

    /// Default stack alignment for this convention.
    pub fn stack_alignment(&self) -> u32 {
        if self.is_64bit() {
            16
        } else {
            16 // Modern compilers align to 16 on IA-32 too
        }
    }

    /// Red zone size (0 if not applicable).
    pub fn red_zone_size(&self) -> i64 {
        if self.has_red_zone() {
            128
        } else {
            0
        }
    }

    /// Shadow space size (0 if not applicable).
    pub fn shadow_space_size(&self) -> i64 {
        if self.has_shadow_space() {
            32
        } else {
            0
        }
    }
}

// ============================================================================
// Shrink Wrapping — save/restore placement optimization
// ============================================================================

/// Represents a region where callee-saved registers should be saved/restored.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SaveRestoreRegion {
    /// The register being saved/restored.
    pub reg: u16,
    /// Basic block where the save occurs.
    pub save_block: usize,
    /// Basic block where the restore occurs.
    pub restore_block: usize,
    /// Whether this region is in a loop.
    pub in_loop: bool,
    /// Nesting depth of the loop (0 = not in a loop).
    pub loop_depth: u32,
    /// Whether the save can be hoisted to the entry block.
    pub can_hoist_save: bool,
    /// Whether the restore can be sunk to exit blocks.
    pub can_sink_restore: bool,
}

impl SaveRestoreRegion {
    pub fn new(reg: u16, save_block: usize, restore_block: usize) -> Self {
        Self {
            reg,
            save_block,
            restore_block,
            in_loop: false,
            loop_depth: 0,
            can_hoist_save: true,
            can_sink_restore: true,
        }
    }

    /// Check if save is placed outside all loops (optimal).
    pub fn is_save_optimal(&self) -> bool {
        !self.in_loop && self.can_hoist_save
    }

    /// Check if restore is placed outside all loops (optimal).
    pub fn is_restore_optimal(&self) -> bool {
        !self.in_loop && self.can_sink_restore
    }
}

/// Dominator tree node for shrink wrapping analysis.
#[derive(Debug, Clone)]
pub struct DomTreeNode {
    /// Block index in the function.
    pub block: usize,
    /// Immediate dominator of this block.
    pub idom: Option<usize>,
    /// Children in the dominator tree.
    pub children: Vec<usize>,
    /// Depth in the dominator tree (entry = 0).
    pub depth: u32,
}

impl DomTreeNode {
    pub fn new(block: usize) -> Self {
        Self {
            block,
            idom: None,
            children: Vec::new(),
            depth: 0,
        }
    }

    /// Whether this node dominates `other` (i.e., `self` is an ancestor of `other`).
    pub fn dominates(&self, other: &DomTreeNode, dom_tree: &[DomTreeNode]) -> bool {
        let mut current = other.block;
        loop {
            if current == self.block {
                return true;
            }
            match dom_tree[current].idom {
                Some(idom) => current = idom,
                None => return false,
            }
        }
    }
}

/// Post-dominator tree for restore placement.
#[derive(Debug, Clone)]
pub struct PostDomTreeNode {
    pub block: usize,
    pub ipdom: Option<usize>,
    pub children: Vec<usize>,
}

impl PostDomTreeNode {
    pub fn new(block: usize) -> Self {
        Self {
            block,
            ipdom: None,
            children: Vec::new(),
        }
    }
}

/// Configuration for shrink wrapping.
#[derive(Debug, Clone)]
pub struct ShrinkWrapConfig {
    /// Whether shrink wrapping is enabled.
    pub enabled: bool,
    /// Whether to consider loop depth for placement.
    pub loop_aware: bool,
    /// Minimum number of saves to justify shrink wrapping.
    pub min_saves_for_wrapping: usize,
    /// Whether to group register saves (push multiple at once).
    pub group_saves: bool,
    /// Maximum nesting depth to analyze.
    pub max_loop_depth: u32,
    /// Target ABI.
    pub call_conv: FrameCallConv,
}

impl Default for ShrinkWrapConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            loop_aware: true,
            min_saves_for_wrapping: 2,
            group_saves: true,
            max_loop_depth: 8,
            call_conv: FrameCallConv::SystemVAMD64,
        }
    }
}

/// Result of shrink wrapping analysis for a function.
#[derive(Debug, Clone)]
pub struct ShrinkWrapResult {
    /// Save/restore regions for each callee-saved register.
    pub regions: Vec<SaveRestoreRegion>,
    /// Blocks that need saves.
    pub save_blocks: HashSet<usize>,
    /// Blocks that need restores.
    pub restore_blocks: HashSet<usize>,
    /// Whether shrink wrapping was applied.
    pub applied: bool,
    /// Estimated number of saved push/pop instructions.
    pub savings: usize,
}

// ============================================================================
// Stack Slot Allocation with Coloring
// ============================================================================

/// A live range for a stack slot, used for coloring.
#[derive(Debug, Clone)]
pub struct SlotLiveRange {
    /// The slot identifier.
    pub slot_id: usize,
    /// Size of the slot in bytes.
    pub size: u32,
    /// Required alignment.
    pub alignment: u32,
    /// Blocks where this slot is live.
    pub live_blocks: BTreeSet<usize>,
    /// Start of the live range (instruction index).
    pub start: usize,
    /// End of the live range (instruction index).
    pub end: usize,
    /// Whether this slot is for a vector type (needs special alignment).
    pub is_vector: bool,
    /// Whether this is an emergency spill slot.
    pub is_emergency: bool,
    /// Whether the slot is for a callee-saved register.
    pub is_callee_saved: bool,
    /// Spill weight (higher = more important to keep in fast memory).
    pub spill_weight: f64,
}

impl SlotLiveRange {
    pub fn new(slot_id: usize, size: u32, alignment: u32) -> Self {
        Self {
            slot_id,
            size,
            alignment,
            start: usize::MAX,
            end: 0,
            live_blocks: BTreeSet::new(),
            is_vector: false,
            is_emergency: false,
            is_callee_saved: false,
            spill_weight: 0.0,
        }
    }

    /// Check if two live ranges overlap (interfere).
    pub fn overlaps(&self, other: &SlotLiveRange) -> bool {
        if self.start >= other.end || other.start >= self.end {
            return false;
        }
        // Also check block-level overlap
        self.live_blocks
            .intersection(&other.live_blocks)
            .next()
            .is_some()
    }

    /// Extend this live range to include another.
    pub fn extend(&mut self, other: &SlotLiveRange) {
        self.start = self.start.min(other.start);
        self.end = self.end.max(other.end);
        self.live_blocks.extend(&other.live_blocks);
    }
}

/// Interference graph for stack slot coloring.
#[derive(Debug, Clone)]
pub struct SlotInterferenceGraph {
    /// Nodes in the graph (slot IDs).
    pub nodes: Vec<usize>,
    /// Adjacency list: for each node, list of conflicting nodes.
    pub edges: HashMap<usize, HashSet<usize>>,
    /// Live range for each slot.
    pub live_ranges: HashMap<usize, SlotLiveRange>,
}

impl SlotInterferenceGraph {
    pub fn new() -> Self {
        Self {
            nodes: Vec::new(),
            edges: HashMap::new(),
            live_ranges: HashMap::new(),
        }
    }

    /// Add a slot to the interference graph.
    pub fn add_slot(&mut self, range: SlotLiveRange) {
        let slot_id = range.slot_id;
        self.nodes.push(slot_id);
        self.edges.entry(slot_id).or_insert_with(HashSet::new);
        self.live_ranges.insert(slot_id, range);
    }

    /// Add an interference edge between two slots.
    pub fn add_edge(&mut self, a: usize, b: usize) {
        if a != b {
            self.edges.entry(a).or_insert_with(HashSet::new).insert(b);
            self.edges.entry(b).or_insert_with(HashSet::new).insert(a);
        }
    }

    /// Build the interference graph from live ranges.
    pub fn build(&mut self) {
        let slot_ids: Vec<usize> = self.nodes.clone();
        for i in 0..slot_ids.len() {
            for j in (i + 1)..slot_ids.len() {
                let a = slot_ids[i];
                let b = slot_ids[j];
                if let (Some(lr_a), Some(lr_b)) =
                    (self.live_ranges.get(&a), self.live_ranges.get(&b))
                {
                    if lr_a.overlaps(lr_b) {
                        self.add_edge(a, b);
                    }
                }
            }
        }
    }

    /// Color the interference graph using greedy coloring.
    /// Returns a mapping from slot_id to color (stack offset group).
    pub fn greedy_color(&self) -> HashMap<usize, usize> {
        let mut colors: HashMap<usize, usize> = HashMap::new();
        // Sort nodes by spill weight descending (most important first)
        let mut sorted_nodes = self.nodes.clone();
        sorted_nodes.sort_by(|a, b| {
            let wa = self
                .live_ranges
                .get(a)
                .map(|lr| lr.spill_weight)
                .unwrap_or(0.0);
            let wb = self
                .live_ranges
                .get(b)
                .map(|lr| lr.spill_weight)
                .unwrap_or(0.0);
            wb.partial_cmp(&wa).unwrap_or(std::cmp::Ordering::Equal)
        });

        for &node in &sorted_nodes {
            let neighbors = self.edges.get(&node).map(|n| n.clone()).unwrap_or_default();
            let used_colors: HashSet<usize> = neighbors
                .iter()
                .filter_map(|n| colors.get(n).copied())
                .collect();

            // Find the smallest available color
            let mut color = 0;
            while used_colors.contains(&color) && color < MAX_SLOT_COLORS {
                color += 1;
            }
            colors.insert(node, color);
        }

        colors
    }

    /// Get the degree (number of interferences) for a node.
    pub fn degree(&self, node: usize) -> usize {
        self.edges.get(&node).map(|n| n.len()).unwrap_or(0)
    }

    /// Get neighbors of a node.
    pub fn neighbors(&self, node: usize) -> Vec<usize> {
        self.edges
            .get(&node)
            .map(|n| n.iter().copied().collect())
            .unwrap_or_default()
    }
}

/// Stack slot allocation result after coloring.
#[derive(Debug, Clone)]
pub struct SlotAllocation {
    /// Offset from frame base for each slot.
    pub offsets: HashMap<usize, i32>,
    /// Size for each allocated slot (may be merged).
    pub sizes: HashMap<usize, u32>,
    /// Total frame size (local area only).
    pub total_local_size: i64,
    /// Alignment of the local area.
    pub local_alignment: u32,
    /// Whether any slots were merged.
    pub merged_slots: bool,
    /// Number of slots before merging.
    pub slot_count_before: usize,
    /// Number of slots after merging.
    pub slot_count_after: usize,
}

impl SlotAllocation {
    pub fn new() -> Self {
        Self {
            offsets: HashMap::new(),
            sizes: HashMap::new(),
            total_local_size: 0,
            local_alignment: 1,
            merged_slots: false,
            slot_count_before: 0,
            slot_count_after: 0,
        }
    }

    /// Get the offset for a slot.
    pub fn offset_of(&self, slot_id: usize) -> Option<i32> {
        self.offsets.get(&slot_id).copied()
    }

    /// Get the size for a slot.
    pub fn size_of(&self, slot_id: usize) -> Option<u32> {
        self.sizes.get(&slot_id).copied()
    }
}

// ============================================================================
// Stack Slot Merging
// ============================================================================

/// Configuration for stack slot merging.
#[derive(Debug, Clone)]
pub struct SlotMergeConfig {
    /// Maximum size of a slot to consider for merging (bytes).
    pub max_merge_size: u32,
    /// Whether to merge slots of different sizes.
    pub merge_different_sizes: bool,
    /// Whether to consider alignment for merging.
    pub alignment_aware: bool,
    /// Maximum number of merge candidates.
    pub max_candidates: usize,
}

impl Default for SlotMergeConfig {
    fn default() -> Self {
        Self {
            max_merge_size: SLOT_MERGE_SIZE_THRESHOLD,
            merge_different_sizes: false,
            alignment_aware: true,
            max_candidates: MAX_SLOTS_FOR_MERGE,
        }
    }
}

/// A merge candidate: two slots that can potentially be merged.
#[derive(Debug, Clone)]
pub struct MergeCandidate {
    /// First slot ID.
    pub slot_a: usize,
    /// Second slot ID.
    pub slot_b: usize,
    /// Size after merging.
    pub merged_size: u32,
    /// Alignment required after merging.
    pub merged_alignment: u32,
    /// Whether the slots are adjacent in memory.
    pub adjacent: bool,
    /// Space savings from merging (bytes).
    pub savings: u32,
}

impl MergeCandidate {
    pub fn new(slot_a: usize, slot_b: usize) -> Self {
        Self {
            slot_a,
            slot_b,
            merged_size: 0,
            merged_alignment: 1,
            adjacent: false,
            savings: 0,
        }
    }
}

/// Result of slot merging.
#[derive(Debug, Clone)]
pub struct SlotMergeResult {
    /// Merged groups: group ID → merged slot IDs.
    pub merged_groups: Vec<Vec<usize>>,
    /// Total bytes saved by merging.
    pub total_savings: u32,
    /// Number of slots eliminated.
    pub slots_eliminated: usize,
}

impl SlotMergeResult {
    pub fn new() -> Self {
        Self {
            merged_groups: Vec::new(),
            total_savings: 0,
            slots_eliminated: 0,
        }
    }
}

// ============================================================================
// Frame Pointer vs Stack Pointer Access Selection
// ============================================================================

/// Access mode for stack frame references.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrameAccessMode {
    /// Use frame pointer (%rbp) relative addressing.
    FramePointer,
    /// Use stack pointer (%rsp) relative addressing.
    StackPointer,
    /// Defer to target machine decision.
    Automatic,
}

/// Configuration for frame access selection.
#[derive(Debug, Clone)]
pub struct FrameAccessConfig {
    /// Preferred access mode.
    pub preferred_mode: FrameAccessMode,
    /// Whether frame pointer elimination is allowed.
    pub allow_fp_elim: bool,
    /// Maximum offset from %rsp for stack pointer relative access.
    pub max_rsp_offset: i32,
    /// Whether the function contains dynamic alloca.
    pub has_dynamic_alloca: bool,
    /// Whether the function has variable-length arrays.
    pub has_vla: bool,
    /// Whether the function calls alloca.
    pub has_alloca: bool,
    /// Whether the function is a leaf (no calls).
    pub is_leaf: bool,
}

impl Default for FrameAccessConfig {
    fn default() -> Self {
        Self {
            preferred_mode: FrameAccessMode::Automatic,
            allow_fp_elim: true,
            max_rsp_offset: 128,
            has_dynamic_alloca: false,
            has_vla: false,
            has_alloca: false,
            is_leaf: false,
        }
    }
}

/// Decision about how to access a frame slot.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrameAccessDecision {
    /// Access via frame pointer: [%rbp - offset].
    FpRelative { offset: i32 },
    /// Access via stack pointer: [%rsp + offset].
    SpRelative { offset: i32 },
    /// Access via dynamic realignment pointer: [drap + offset].
    DrapRelative { offset: i32 },
}

impl FrameAccessDecision {
    /// Get the register used for this access.
    pub fn base_register(&self) -> u16 {
        match self {
            Self::FpRelative { .. } => RBP,
            Self::SpRelative { .. } => RSP,
            Self::DrapRelative { .. } => DRAP_REGISTER_ALT,
        }
    }

    /// Get the offset from the base register.
    pub fn offset(&self) -> i32 {
        match self {
            Self::FpRelative { offset }
            | Self::SpRelative { offset }
            | Self::DrapRelative { offset } => *offset,
        }
    }

    /// Whether this is a frame-pointer-relative access.
    pub fn is_fp_relative(&self) -> bool {
        matches!(self, Self::FpRelative { .. })
    }

    /// Whether this is a stack-pointer-relative access.
    pub fn is_sp_relative(&self) -> bool {
        matches!(self, Self::SpRelative { .. })
    }
}

// ============================================================================
// Emergency Spill Slot Allocation
// ============================================================================

/// An emergency spill slot reserved for register scavenging.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct EmergencySpillSlot {
    /// Slot index.
    pub index: usize,
    /// Offset from the frame base.
    pub offset: i32,
    /// Size of the slot.
    pub size: i32,
    /// Whether this slot is currently in use.
    pub in_use: bool,
    /// The register currently spilled here (0 = none).
    pub spilled_reg: u16,
    /// Instruction index where the spill occurred.
    pub spill_at: usize,
}

impl EmergencySpillSlot {
    pub fn new(index: usize, offset: i32, size: i32) -> Self {
        Self {
            index,
            offset,
            size,
            in_use: false,
            spilled_reg: 0,
            spill_at: 0,
        }
    }

    /// Allocate this slot for an emergency spill.
    pub fn allocate(&mut self, reg: u16, at_inst: usize) {
        self.in_use = true;
        self.spilled_reg = reg;
        self.spill_at = at_inst;
    }

    /// Free this slot for reuse.
    pub fn free(&mut self) {
        self.in_use = false;
        self.spilled_reg = 0;
        self.spill_at = 0;
    }

    /// Whether this slot is available for allocation.
    pub fn is_available(&self) -> bool {
        !self.in_use
    }
}

/// Manager for emergency spill slots.
#[derive(Debug, Clone)]
pub struct EmergencySpillSlotManager {
    /// Reserved emergency slots.
    pub slots: Vec<EmergencySpillSlot>,
    /// Total number of slots.
    pub total_slots: usize,
    /// Offset in the frame where emergency slots begin.
    pub base_offset: i32,
    /// Allocation counter (for debugging/statistics).
    pub allocation_count: u64,
    /// Number of times all slots were exhausted.
    pub exhaustion_count: u64,
}

impl EmergencySpillSlotManager {
    /// Create a manager with a given number of emergency slots.
    pub fn new(count: usize, base_offset: i32) -> Self {
        let mut slots = Vec::with_capacity(count);
        for i in 0..count {
            let offset = base_offset - (i as i32 + 1) * EMERGENCY_SLOT_SIZE as i32;
            slots.push(EmergencySpillSlot::new(
                i,
                offset,
                EMERGENCY_SLOT_SIZE as i32,
            ));
        }
        Self {
            slots,
            total_slots: count,
            base_offset,
            allocation_count: 0,
            exhaustion_count: 0,
        }
    }

    /// Find an available emergency slot.
    pub fn find_available(&self) -> Option<usize> {
        self.slots.iter().position(|s| s.is_available())
    }

    /// Allocate an emergency slot for a register.
    pub fn allocate(&mut self, reg: u16, at_inst: usize) -> Option<usize> {
        if let Some(idx) = self.find_available() {
            self.slots[idx].allocate(reg, at_inst);
            self.allocation_count += 1;
            Some(idx)
        } else {
            self.exhaustion_count += 1;
            // Clobber the oldest slot
            let oldest = self
                .slots
                .iter()
                .enumerate()
                .min_by_key(|(_, s)| s.spill_at)
                .map(|(i, _)| i);
            if let Some(idx) = oldest {
                self.slots[idx].allocate(reg, at_inst);
                Some(idx)
            } else {
                None
            }
        }
    }

    /// Free an emergency slot.
    pub fn free(&mut self, index: usize) -> bool {
        if index < self.slots.len() {
            self.slots[index].free();
            true
        } else {
            false
        }
    }

    /// Free all slots.
    pub fn free_all(&mut self) {
        for slot in &mut self.slots {
            slot.free();
        }
    }

    /// Get the total size of the emergency spill area.
    pub fn total_size(&self) -> i64 {
        self.total_slots as i64 * EMERGENCY_SLOT_SIZE
    }
}

// ============================================================================
// Dynamic Stack Realignment
// ============================================================================

/// Configuration for dynamic stack realignment.
#[derive(Debug, Clone)]
pub struct StackRealignConfig {
    /// Whether dynamic realignment is needed.
    pub needed: bool,
    /// Required alignment (must be power of 2).
    pub required_alignment: u32,
    /// Whether to use a dedicated realignment pointer (DRAP).
    pub use_drap: bool,
    /// Register to use as DRAP, if applicable.
    pub drap_register: u16,
    /// Whether the function has variable-sized objects.
    pub has_variable_objects: bool,
}

impl Default for StackRealignConfig {
    fn default() -> Self {
        Self {
            needed: false,
            required_alignment: 16,
            use_drap: false,
            drap_register: DRAP_REGISTER_ALT,
            has_variable_objects: false,
        }
    }
}

/// Prologue sequence for dynamic stack realignment.
#[derive(Debug, Clone)]
pub struct RealignPrologue {
    /// Sequence of instructions for the alignment prologue.
    pub instructions: Vec<AlignInstr>,
    /// The stack adjustment after alignment.
    pub final_adjustment: i64,
    /// Whether DRAP was set up.
    pub drap_setup: bool,
}

/// Epilogue sequence for dynamic stack realignment.
#[derive(Debug, Clone)]
pub struct RealignEpilogue {
    /// Sequence of instructions for the alignment epilogue.
    pub instructions: Vec<AlignInstr>,
}

/// A single instruction in the alignment prologue/epilogue.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AlignInstr {
    /// Push a register: push reg.
    Push { reg: u16 },
    /// Pop a register: pop reg.
    Pop { reg: u16 },
    /// Move register to register: mov dst, src.
    MovRR { dst: u16, src: u16 },
    /// AND with immediate: and reg, imm.
    AndRI { reg: u16, imm: i64 },
    /// Subtract immediate from register: sub reg, imm.
    SubRI { reg: u16, imm: i64 },
    /// Add immediate to register: add reg, imm.
    AddRI { reg: u16, imm: i64 },
    /// Leave instruction: leave.
    Leave,
    /// Load effective address: lea dst, [src + offset].
    Lea { dst: u16, base: u16, offset: i32 },
    /// No operation (padding).
    Nop,
}

/// Compute the AND mask for stack alignment.
/// For alignment `align` (power of 2), the mask is `!(align - 1)`.
pub fn alignment_mask(align: u32) -> i64 {
    assert!(align.is_power_of_two(), "Alignment must be power of 2");
    !((align - 1) as i64)
}

/// Generate the realignment prologue sequence.
pub fn generate_realign_prologue(config: &StackRealignConfig, frame_size: i64) -> RealignPrologue {
    let mut instrs = Vec::new();
    let mut final_adjustment = 0i64;
    let mut drap_setup = false;

    if config.use_drap {
        // push %rbp
        instrs.push(AlignInstr::Push { reg: RBP });
        // mov %rbp, %rsp
        instrs.push(AlignInstr::MovRR { dst: RBP, src: RSP });
        // push drap_reg
        instrs.push(AlignInstr::Push {
            reg: config.drap_register,
        });
        // lea drap_reg, [%rsp + offset_for_saved_regs]
        instrs.push(AlignInstr::Lea {
            dst: config.drap_register,
            base: RSP,
            offset: 8, // past the pushed drap_reg
        });
        // and drap_reg, ~(align-1)
        let mask = alignment_mask(config.required_alignment);
        instrs.push(AlignInstr::AndRI {
            reg: config.drap_register,
            imm: mask,
        });
        // mov %rsp, drap_reg
        instrs.push(AlignInstr::MovRR {
            dst: RSP,
            src: config.drap_register,
        });
        drap_setup = true;
        final_adjustment = 0; // DRAP handles alignment
    } else {
        // Standard AND-based alignment
        // push %rbp
        instrs.push(AlignInstr::Push { reg: RBP });
        // mov %rbp, %rsp
        instrs.push(AlignInstr::MovRR { dst: RBP, src: RSP });
        // sub $frame_size, %rsp
        instrs.push(AlignInstr::SubRI {
            reg: RSP,
            imm: frame_size,
        });
        // and $mask, %rsp
        let mask = alignment_mask(config.required_alignment);
        instrs.push(AlignInstr::AndRI {
            reg: RSP,
            imm: mask,
        });
        final_adjustment = 0;
    }

    RealignPrologue {
        instructions: instrs,
        final_adjustment,
        drap_setup,
    }
}

/// Generate the realignment epilogue sequence.
pub fn generate_realign_epilogue(config: &StackRealignConfig) -> RealignEpilogue {
    let mut instrs = Vec::new();

    if config.use_drap {
        // lea %rsp, [drap - saved_reg_size]
        instrs.push(AlignInstr::Lea {
            dst: RSP,
            base: config.drap_register,
            offset: -16,
        });
        // pop drap_reg
        instrs.push(AlignInstr::Pop {
            reg: config.drap_register,
        });
        // pop %rbp
        instrs.push(AlignInstr::Pop { reg: RBP });
    } else {
        // mov %rsp, %rbp
        instrs.push(AlignInstr::MovRR { dst: RSP, src: RBP });
        // pop %rbp
        instrs.push(AlignInstr::Pop { reg: RBP });
    }

    RealignEpilogue {
        instructions: instrs,
    }
}

// ============================================================================
// Segmented Stacks Support
// ============================================================================

/// Configuration for segmented stacks (e.g., for Go, Rust with segmented stacks).
#[derive(Debug, Clone)]
pub struct SegmentedStackConfig {
    /// Whether segmented stacks are enabled.
    pub enabled: bool,
    /// Size of each stack segment.
    pub segment_size: i64,
    /// Symbol name for the __morestack function.
    pub morestack_symbol: String,
    /// Whether to use a thread-local stack limit.
    pub tls_stack_limit: bool,
    /// Offset in TLS for the stack limit.
    pub tls_stack_limit_offset: i64,
    /// Alignment of stack segments.
    pub segment_alignment: u32,
}

impl Default for SegmentedStackConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            segment_size: 4096 * 256, // 1 MB
            morestack_symbol: "__morestack".to_string(),
            tls_stack_limit: true,
            tls_stack_limit_offset: 0,
            segment_alignment: 16,
        }
    }
}

/// Prologue for segmented stacks: checks if stack expansion is needed.
#[derive(Debug, Clone)]
pub struct SegmentedStackPrologue {
    /// Instructions for the stack check.
    pub check_instructions: Vec<StackCheckInstr>,
    /// Whether stack expansion is likely needed.
    pub needs_expansion: bool,
    /// Estimated number of bytes needed.
    pub bytes_needed: i64,
}

/// A single instruction in the segmented stack check sequence.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum StackCheckInstr {
    /// Compare %rsp with stack limit: cmp %rsp, [limit].
    CmpStackLimit { limit_ref: String },
    /// Conditional jump: jae skip_morestack.
    Jae { target: String },
    /// Call __morestack: call __morestack.
    CallMorestack,
    /// Push registers before call.
    PushRegs { regs: Vec<u16> },
    /// Pop registers after call.
    PopRegs { regs: Vec<u16> },
    /// Label definition.
    Label { name: String },
    /// Adjust stack after morestack.
    SubRsp { amount: i64 },
    /// No-op.
    Nop,
}

/// Generate the segmented stack prologue check sequence.
pub fn generate_segmented_prologue(
    config: &SegmentedStackConfig,
    frame_size: i64,
) -> SegmentedStackPrologue {
    let label_skip = "L_segstack_skip".to_string();
    let label_more = "L_segstack_more".to_string();

    let mut check_instrs = Vec::new();

    if config.tls_stack_limit {
        // Load stack limit from TLS
        // cmp %rsp, %fs:stack_limit_offset
        check_instrs.push(StackCheckInstr::CmpStackLimit {
            limit_ref: format!("%fs:{}", config.tls_stack_limit_offset),
        });
    } else {
        // Load stack limit from a global symbol
        check_instrs.push(StackCheckInstr::CmpStackLimit {
            limit_ref: "__stack_limit".to_string(),
        });
    }

    // jae skip_morestack
    check_instrs.push(StackCheckInstr::Jae {
        target: label_skip.clone(),
    });

    // call __morestack
    check_instrs.push(StackCheckInstr::Label { name: label_more });
    check_instrs.push(StackCheckInstr::CallMorestack);

    // After morestack returns, adjust stack
    check_instrs.push(StackCheckInstr::SubRsp { amount: frame_size });

    // Skip label
    check_instrs.push(StackCheckInstr::Label { name: label_skip });

    SegmentedStackPrologue {
        check_instructions: check_instrs,
        needs_expansion: frame_size > config.segment_size,
        bytes_needed: frame_size,
    }
}

// ============================================================================
// SafeStack Layout
// ============================================================================

/// Configuration for SafeStack (separate safe/unsafe stack regions).
#[derive(Debug, Clone)]
pub struct SafeStackConfig {
    /// Whether SafeStack is enabled.
    pub enabled: bool,
    /// Size of the safe stack region.
    pub safe_stack_size: i64,
    /// Size of the unsafe stack region.
    pub unsafe_stack_size: i64,
    /// Alignment of the unsafe stack pointer.
    pub unsafe_stack_alignment: u32,
    /// Thread-local storage offset for the unsafe stack pointer.
    pub unsafe_stack_ptr_tls_offset: i64,
}

impl Default for SafeStackConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            safe_stack_size: 4096 * 8,    // 32 KB safe stack
            unsafe_stack_size: 4096 * 64, // 256 KB unsafe stack
            unsafe_stack_alignment: 16,
            unsafe_stack_ptr_tls_offset: 0,
        }
    }
}

/// Frame layout for SafeStack.
#[derive(Debug, Clone)]
pub struct SafeStackFrame {
    /// Objects allocated on the safe stack.
    pub safe_objects: Vec<SafeStackObject>,
    /// Objects allocated on the unsafe stack.
    pub unsafe_objects: Vec<SafeStackObject>,
    /// Total safe stack frame size.
    pub safe_frame_size: i64,
    /// Total unsafe stack frame size.
    pub unsafe_frame_size: i64,
    /// Whether unsafe stack pointer was loaded.
    pub unsafe_sp_loaded: bool,
}

/// An object on the safe or unsafe stack.
#[derive(Debug, Clone)]
pub struct SafeStackObject {
    /// Identifier for the object.
    pub id: usize,
    /// Size of the object.
    pub size: u32,
    /// Alignment of the object.
    pub alignment: u32,
    /// Offset from the base of its stack region.
    pub offset: i32,
    /// Whether this object has its address taken.
    pub address_taken: bool,
    /// Whether this object contains pointers to the safe stack.
    pub has_safe_pointers: bool,
}

impl SafeStackObject {
    pub fn new(id: usize, size: u32, alignment: u32) -> Self {
        Self {
            id,
            size,
            alignment,
            offset: 0,
            address_taken: false,
            has_safe_pointers: false,
        }
    }
}

/// Classify an object as safe stack or unsafe stack.
pub fn classify_safe_stack_object(obj: &SafeStackObject) -> bool {
    // Objects with address taken go on unsafe stack
    // Objects on safe stack must not have address taken
    !obj.address_taken
}

/// Layout the safe stack frame (address-taken objects go to unsafe stack).
pub fn layout_safe_stack(objects: &[SafeStackObject], config: &SafeStackConfig) -> SafeStackFrame {
    let mut safe_objects = Vec::new();
    let mut unsafe_objects = Vec::new();
    let mut safe_cur_offset = 0i32;
    let mut unsafe_cur_offset = 0i32;

    for obj in objects {
        if classify_safe_stack_object(obj) {
            let mut placed = obj.clone();
            let align_mask = (obj.alignment as i32) - 1;
            safe_cur_offset = (safe_cur_offset + align_mask) & !align_mask;
            placed.offset = safe_cur_offset;
            safe_cur_offset += obj.size as i32;
            safe_objects.push(placed);
        } else {
            let mut placed = obj.clone();
            let align_mask = (obj.alignment as i32) - 1;
            unsafe_cur_offset = (unsafe_cur_offset + align_mask) & !align_mask;
            placed.offset = unsafe_cur_offset;
            unsafe_cur_offset += obj.size as i32;
            unsafe_objects.push(placed);
        }
    }

    let unsafe_objects_empty = unsafe_objects.is_empty();
    SafeStackFrame {
        safe_objects,
        unsafe_objects,
        safe_frame_size: safe_cur_offset as i64,
        unsafe_frame_size: unsafe_cur_offset as i64,
        unsafe_sp_loaded: !unsafe_objects_empty,
    }
}

// ============================================================================
// Stack Clash Protection Frame Setup
// ============================================================================

/// Configuration for stack clash protection.
#[derive(Debug, Clone)]
pub struct StackClashProtectionConfig {
    /// Whether stack clash protection is enabled.
    pub enabled: bool,
    /// Probe interval (page size by default).
    pub probe_interval: i64,
    /// Minimum frame size that requires probing.
    pub min_probe_size: i64,
    /// Whether to use loop-based probing for large frames.
    pub use_loop_probe: bool,
    /// Whether to probe alloca sites.
    pub probe_allocas: bool,
    /// Whether to probe tail call sites.
    pub probe_tail_calls: bool,
    /// Operating system target (affects guard page behavior).
    pub target_os: TargetOS,
}

impl Default for StackClashProtectionConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            probe_interval: DEFAULT_PROBE_INTERVAL,
            min_probe_size: MIN_STACK_FOR_PROBING,
            use_loop_probe: true,
            probe_allocas: true,
            probe_tail_calls: true,
            target_os: TargetOS::Linux,
        }
    }
}

/// Target operating system for stack clash behavior.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TargetOS {
    Linux,
    Windows,
    MacOS,
    FreeBSD,
    NetBSD,
    OpenBSD,
    Solaris,
    Unknown,
}

/// A single stack probe instruction.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProbeInstr {
    /// The operation: OR [rsp + offset], 0 (touch the page).
    pub kind: ProbeKind,
    /// Offset from %rsp for the probe.
    pub offset: i32,
    /// Register used (usually %rsp).
    pub base_reg: u16,
}

/// Kind of stack probe.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProbeKind {
    /// OR [base + offset], 0 — touch the page.
    OrImm,
    /// MOV to memory — touch the page.
    MovImm,
    /// CMP with memory — touch the page.
    Cmp,
    /// Probe via loop iteration.
    LoopProbe,
}

/// Generate stack probes for a given frame size.
pub fn generate_stack_probes(
    config: &StackClashProtectionConfig,
    frame_size: i64,
) -> Vec<ProbeInstr> {
    if !config.enabled || frame_size < config.min_probe_size {
        return Vec::new();
    }

    let mut probes = Vec::new();
    let interval = config.probe_interval;

    if config.use_loop_probe && frame_size > interval * 4 {
        // Use loop-based probing for very large frames
        // sub $interval, %rsp (in a loop)
        // or $0, [%rsp]
        probes.push(ProbeInstr {
            kind: ProbeKind::LoopProbe,
            offset: 0,
            base_reg: RSP,
        });
    } else {
        // Emit probes at each page boundary
        let mut offset = -interval as i32;
        while offset > -frame_size as i32 {
            probes.push(ProbeInstr {
                kind: ProbeKind::OrImm,
                offset,
                base_reg: RSP,
            });
            offset -= interval as i32;
        }
    }

    probes
}

/// Check if stack clash protection is needed for a function.
pub fn needs_stack_clash_protection(config: &StackClashProtectionConfig, frame_size: i64) -> bool {
    config.enabled && frame_size >= config.min_probe_size
}

// ============================================================================
// PatchPoint / StackMap Frame Handling
// ============================================================================

/// A stack map entry: records the location of live values at a patchpoint.
#[derive(Debug, Clone)]
pub struct StackMapEntry {
    /// ID of the patchpoint/callsite.
    pub id: u64,
    /// Offset in the code where the patchpoint occurs.
    pub code_offset: u64,
    /// Locations of live values (register or stack slot).
    pub live_locations: Vec<StackMapLocation>,
    /// Number of live values.
    pub num_locations: u32,
    /// Size of the stack frame at the patchpoint.
    pub frame_size: u64,
    /// Flags (e.g., whether this is a deopt point).
    pub flags: u32,
}

/// A single live value location in a stack map.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StackMapLocation {
    /// Kind of location: register, direct stack, indirect stack, constant.
    pub kind: StackMapLocKind,
    /// Size of the value in bytes.
    pub size: u32,
    /// Register number (if kind is Register or Indirect).
    pub reg: u16,
    /// Offset (if kind is Direct or Indirect).
    pub offset: i32,
    /// Constant value (if kind is Constant).
    pub constant: i64,
}

/// Kind of stack map location.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum StackMapLocKind {
    /// Value is in a register.
    Register = 1,
    /// Value is on the stack at [reg + offset].
    Direct = 2,
    /// Value address is on the stack at [reg + offset] (pointer to value).
    Indirect = 3,
    /// Value is a known constant.
    Constant = 4,
    /// Value is a constant index into a global.
    ConstantIndex = 5,
}

impl StackMapLocation {
    pub fn new_register(reg: u16, size: u32) -> Self {
        Self {
            kind: StackMapLocKind::Register,
            size,
            reg,
            offset: 0,
            constant: 0,
        }
    }

    pub fn new_direct(reg: u16, offset: i32, size: u32) -> Self {
        Self {
            kind: StackMapLocKind::Direct,
            size,
            reg,
            offset,
            constant: 0,
        }
    }

    pub fn new_indirect(reg: u16, offset: i32, size: u32) -> Self {
        Self {
            kind: StackMapLocKind::Indirect,
            size,
            reg,
            offset,
            constant: 0,
        }
    }

    pub fn new_constant(value: i64) -> Self {
        Self {
            kind: StackMapLocKind::Constant,
            size: 8,
            reg: 0,
            offset: 0,
            constant: value,
        }
    }
}

/// Configuration for patchpoint/stackmap frame handling.
#[derive(Debug, Clone)]
pub struct PatchPointConfig {
    /// Whether to emit stack map entries.
    pub emit_stackmap: bool,
    /// Whether this is a patchpoint (modifiable call site).
    pub is_patchpoint: bool,
    /// Whether this is a statepoint (GC safe point).
    pub is_statepoint: bool,
    /// Number of NOP bytes to reserve for patchpoint patching.
    pub nop_bytes: u32,
    /// Calling convention at the patchpoint.
    pub call_conv: FrameCallConv,
}

impl Default for PatchPointConfig {
    fn default() -> Self {
        Self {
            emit_stackmap: true,
            is_patchpoint: false,
            is_statepoint: false,
            nop_bytes: 12,
            call_conv: FrameCallConv::SystemVAMD64,
        }
    }
}

/// Build a stack map entry for a patchpoint.
pub fn build_stack_map_entry(
    id: u64,
    code_offset: u64,
    live_locations: Vec<StackMapLocation>,
    frame_size: u64,
    flags: u32,
) -> StackMapEntry {
    let num_locations = live_locations.len() as u32;
    StackMapEntry {
        id,
        code_offset,
        live_locations,
        num_locations,
        frame_size,
        flags,
    }
}

// ============================================================================
// Varargs Frame Setup Per ABI
// ============================================================================

/// ABI-specific varargs configuration.
#[derive(Debug, Clone)]
pub struct VarArgsConfig {
    /// Target ABI.
    pub call_conv: FrameCallConv,
    /// Whether the function has variable arguments.
    pub has_varargs: bool,
    /// Number of fixed arguments.
    pub num_fixed_args: u32,
    /// Whether to save integer registers for varargs.
    pub save_int_regs: bool,
    /// Whether to save XMM registers for varargs.
    pub save_xmm_regs: bool,
    /// Alignment of the register save area.
    pub save_area_alignment: u32,
}

impl Default for VarArgsConfig {
    fn default() -> Self {
        Self {
            call_conv: FrameCallConv::SystemVAMD64,
            has_varargs: false,
            num_fixed_args: 0,
            save_int_regs: true,
            save_xmm_regs: true,
            save_area_alignment: 16,
        }
    }
}

/// Varargs frame layout for System V AMD64.
///
/// Layout:
/// ```text
///    +------------------------+ <- high address
///    | Overflow arguments     |  (args passed on stack)
///    +------------------------+
///    | Register save area     |  (GP regs: RDI, RSI, RDX, RCX, R8, R9)
///    | (GP + XMM registers)   |  (XMM regs: XMM0-XMM7)
///    +------------------------+ <- low address (%rsp after prologue)
/// ```
#[derive(Debug, Clone)]
pub struct SysVVarArgsFrame {
    /// Number of GP register save slots.
    pub num_gp_slots: u32,
    /// Number of XMM register save slots.
    pub num_xmm_slots: u32,
    /// Offset of the GP save area from %rbp.
    pub gp_save_offset: i32,
    /// Offset of the XMM save area from %rbp.
    pub xmm_save_offset: i32,
    /// Offset of the overflow arg area from %rbp.
    pub overflow_offset: i32,
    /// Total size of the varargs save area.
    pub total_save_area_size: i64,
    /// GP registers to save (in order).
    pub gp_regs: Vec<u16>,
    /// XMM registers to save (in order).
    pub xmm_regs: Vec<u16>,
}

impl SysVVarArgsFrame {
    /// Standard System V AMD64 GP registers for varargs.
    pub const STD_GP_REGS: [u16; 6] = [RDI, RSI, RDX, RCX, R8, R9];
    /// Standard System V AMD64 XMM registers for varargs.
    pub const STD_XMM_REGS: [u16; 8] = [0, 1, 2, 3, 4, 5, 6, 7]; // XMM0-XMM7 placeholders

    pub fn new(num_fixed_args: u32) -> Self {
        let gp_regs: Vec<u16> = Self::STD_GP_REGS
            .iter()
            .skip(num_fixed_args as usize)
            .copied()
            .collect();
        let xmm_regs: Vec<u16> = Self::STD_XMM_REGS
            .iter()
            .skip(num_fixed_args as usize)
            .copied()
            .collect();

        let num_gp_slots = gp_regs.len() as u32;
        let num_xmm_slots = xmm_regs.len() as u32;

        // 8 bytes per GP slot, 16 bytes per XMM slot
        let gp_size = num_gp_slots * 8;
        let xmm_size = num_xmm_slots * 16;

        Self {
            num_gp_slots,
            num_xmm_slots,
            gp_save_offset: -(gp_size as i32),
            xmm_save_offset: -((gp_size + xmm_size) as i32),
            overflow_offset: 16, // past return address + saved rbp
            total_save_area_size: (gp_size + xmm_size) as i64,
            gp_regs,
            xmm_regs,
        }
    }
}

/// Varargs frame layout for Microsoft x64 (Windows).
///
/// On Windows x64, varargs are always passed on the stack.
/// The shadow space (32 bytes at [%rsp+0]) is used for the first 4 args,
/// and additional args follow on the stack.
#[derive(Debug, Clone)]
pub struct Win64VarArgsFrame {
    /// Offset of the shadow space from %rbp.
    pub shadow_space_offset: i32,
    /// Offset of the overflow arg area from %rbp.
    pub overflow_offset: i32,
    /// Size of the shadow space.
    pub shadow_space_size: i64,
    /// Number of overflow argument slots.
    pub num_overflow_slots: u32,
}

impl Win64VarArgsFrame {
    pub fn new() -> Self {
        Self {
            shadow_space_offset: 16, // past return address + saved rbp
            overflow_offset: 48,     // past shadow space (32) + 16
            shadow_space_size: WIN64_SHADOW_SPACE,
            num_overflow_slots: 0,
        }
    }
}

/// Build a varargs frame for the given configuration.
pub fn build_varargs_frame(config: &VarArgsConfig) -> VarArgsFrameResult {
    match config.call_conv {
        FrameCallConv::SystemVAMD64 => {
            let sysv = SysVVarArgsFrame::new(config.num_fixed_args);
            VarArgsFrameResult::SystemV(sysv)
        }
        FrameCallConv::Win64 => {
            let win = Win64VarArgsFrame::new();
            VarArgsFrameResult::Win64(win)
        }
        _ => VarArgsFrameResult::Unsupported,
    }
}

/// Result of varargs frame construction.
#[derive(Debug, Clone)]
pub enum VarArgsFrameResult {
    SystemV(SysVVarArgsFrame),
    Win64(Win64VarArgsFrame),
    Unsupported,
}

// ============================================================================
// Sret Demotion Frame Handling
// ============================================================================

/// Configuration for sret (struct return) demotion.
#[derive(Debug, Clone)]
pub struct SretDemotionConfig {
    /// Whether sret demotion is needed.
    pub needed: bool,
    /// Size of the returned struct.
    pub struct_size: u32,
    /// Alignment of the returned struct.
    pub struct_alignment: u32,
    /// Whether the sret pointer is in a register.
    pub sret_in_reg: bool,
    /// Register holding the sret pointer.
    pub sret_reg: u16,
    /// Whether to allocate a local frame slot for the demoted struct.
    pub allocate_local: bool,
}

impl Default for SretDemotionConfig {
    fn default() -> Self {
        Self {
            needed: false,
            struct_size: 0,
            struct_alignment: 8,
            sret_in_reg: true,
            sret_reg: RAX, // System V AMD64: sret pointer in RAX
            allocate_local: true,
        }
    }
}

/// Frame slot for a demoted sret.
#[derive(Debug, Clone)]
pub struct SretFrameSlot {
    /// Offset in the frame.
    pub offset: i32,
    /// Size of the slot.
    pub size: u32,
    /// Alignment of the slot.
    pub alignment: u32,
    /// Whether the slot is initialized.
    pub initialized: bool,
}

impl SretFrameSlot {
    pub fn new(offset: i32, size: u32, alignment: u32) -> Self {
        Self {
            offset,
            size,
            alignment,
            initialized: false,
        }
    }
}

/// Demote sret to a local frame allocation.
pub fn demote_sret(config: &SretDemotionConfig, local_offset: &mut i32) -> SretFrameSlot {
    let align = config.struct_alignment;
    let align_mask = (align as i32) - 1;

    // Align the offset
    *local_offset = (*local_offset + align_mask) & !align_mask;
    let slot_offset = *local_offset;
    *local_offset += config.struct_size as i32;

    SretFrameSlot::new(slot_offset, config.struct_size, align)
}

// ============================================================================
// Callee-Saved Register Frame Assignment
// ============================================================================

/// A callee-saved register with its frame assignment.
#[derive(Debug, Clone)]
pub struct CalleeSavedReg {
    /// Register number.
    pub reg: u16,
    /// Offset from the frame base where this register is saved.
    pub frame_offset: i32,
    /// Size of the save slot.
    pub size: u32,
    /// Whether this register is actually used in the function.
    pub is_used: bool,
    /// Whether the save/restore can be eliminated.
    pub can_eliminate: bool,
    /// Whether this register was allocated as a general-purpose register.
    pub allocated: bool,
}

impl CalleeSavedReg {
    pub fn new(reg: u16, frame_offset: i32, size: u32) -> Self {
        Self {
            reg,
            frame_offset,
            size,
            is_used: false,
            can_eliminate: false,
            allocated: false,
        }
    }
}

/// Assignment of callee-saved registers in the frame.
#[derive(Debug, Clone)]
pub struct CalleeSavedAssignment {
    /// Registers that must be saved, with frame offsets.
    pub saved_regs: Vec<CalleeSavedReg>,
    /// Total size of the callee-saved area.
    pub saved_area_size: i64,
    /// Whether any registers are conditionally saved (shrink wrapped).
    pub has_conditional_saves: bool,
    /// Base offset where callee-saved area starts.
    pub base_offset: i32,
}

impl CalleeSavedAssignment {
    pub fn new() -> Self {
        Self {
            saved_regs: Vec::new(),
            saved_area_size: 0,
            has_conditional_saves: false,
            base_offset: 0,
        }
    }

    /// Add a callee-saved register to the assignment.
    pub fn add_reg(&mut self, reg: u16, size: u32) {
        let offset = self.base_offset - self.saved_area_size as i32 - size as i32;
        let csr = CalleeSavedReg::new(reg, offset, size);
        self.saved_regs.push(csr);
        self.saved_area_size += size as i64;
    }

    /// Get the frame offset for a specific callee-saved register.
    pub fn offset_for(&self, reg: u16) -> Option<i32> {
        self.saved_regs
            .iter()
            .find(|csr| csr.reg == reg)
            .map(|csr| csr.frame_offset)
    }

    /// Remove registers that are not used (eliminate unnecessary saves).
    pub fn eliminate_unused(&mut self) {
        self.saved_regs.retain(|csr| csr.is_used);
        // Recompute offsets
        let mut cur_offset = self.base_offset;
        for csr in &mut self.saved_regs {
            cur_offset -= csr.size as i32;
            csr.frame_offset = cur_offset;
        }
        self.saved_area_size = (self.base_offset - cur_offset) as i64;
    }

    /// Get all registers that need to be saved.
    pub fn used_regs(&self) -> Vec<u16> {
        self.saved_regs
            .iter()
            .filter(|csr| csr.is_used)
            .map(|csr| csr.reg)
            .collect()
    }

    /// Check if a specific register is saved.
    pub fn is_saved(&self, reg: u16) -> bool {
        self.saved_regs
            .iter()
            .any(|csr| csr.reg == reg && csr.is_used)
    }
}

// ============================================================================
// X86FrameLoweringExt — main frame lowering extension
// ============================================================================

/// Extended frame lowering for X86 targets.
///
/// Combines shrink wrapping, slot coloring, slot merging, emergency spill slot
/// management, dynamic realignment, segmented stacks, SafeStack, stack clash
/// protection, patchpoint frame handling, varargs frame setup, and sret demotion.
#[derive(Debug, Clone)]
pub struct X86FrameLoweringExt {
    /// Target calling convention.
    pub call_conv: FrameCallConv,
    /// Total frame size.
    pub frame_size: i64,
    /// Whether frame pointer is used.
    pub uses_frame_pointer: bool,
    /// Shrink wrapping configuration.
    pub shrink_wrap: ShrinkWrapConfig,
    /// Shrink wrapping result.
    pub shrink_result: Option<ShrinkWrapResult>,
    /// Stack slot interference graph.
    pub slot_graph: SlotInterferenceGraph,
    /// Stack slot allocation result.
    pub slot_allocation: SlotAllocation,
    /// Frame access configuration.
    pub frame_access: FrameAccessConfig,
    /// Access decisions for each slot.
    pub access_decisions: HashMap<usize, FrameAccessDecision>,
    /// Emergency spill slot manager.
    pub emergency_slots: EmergencySpillSlotManager,
    /// Dynamic realignment configuration.
    pub realign_config: StackRealignConfig,
    /// Segmented stack configuration.
    pub segmented_config: SegmentedStackConfig,
    /// SafeStack configuration.
    pub safestack_config: SafeStackConfig,
    /// Stack clash protection configuration.
    pub stack_clash_config: StackClashProtectionConfig,
    /// Patchpoint configuration.
    pub patchpoint_config: PatchPointConfig,
    /// Varargs configuration.
    pub varargs_config: VarArgsConfig,
    /// Sret demotion configuration.
    pub sret_config: SretDemotionConfig,
    /// Callee-saved register assignment.
    pub callee_saved: CalleeSavedAssignment,
    /// All emergency spill slots reserved.
    pub reserved_emergency_slots: Vec<EmergencySpillSlot>,
    /// Stack probes generated (if stack clash enabled).
    pub stack_probes: Vec<ProbeInstr>,
    /// Varargs frame (if applicable).
    pub varargs_frame: Option<VarArgsFrameResult>,
    /// Sret frame slot (if sret demoted).
    pub sret_slot: Option<SretFrameSlot>,
    /// Statistics for the frame lowering.
    pub stats: FrameLoweringExtStats,
}

/// Statistics collected during extended frame lowering.
#[derive(Debug, Clone, Default)]
pub struct FrameLoweringExtStats {
    /// Number of shrink-wrapped saves.
    pub shrink_wrapped_saves: usize,
    /// Number of slots merged.
    pub slots_merged: usize,
    /// Number of colors used for slot coloring.
    pub colors_used: usize,
    /// Emergency spill allocations performed.
    pub emergency_spills: u64,
    /// Stack probes emitted.
    pub probes_emitted: usize,
    /// Whether frame pointer was eliminated.
    pub fp_eliminated: bool,
    /// Total frame size after all optimizations.
    pub final_frame_size: i64,
    /// Whether dynamic realignment was applied.
    pub realignment_applied: bool,
    /// Whether segmented stacks are active.
    pub segmented_active: bool,
    /// Whether SafeStack is active.
    pub safestack_active: bool,
    /// Whether stack clash protection is active.
    pub stack_clash_active: bool,
}

impl X86FrameLoweringExt {
    /// Create a new extended frame lowering for the given calling convention.
    pub fn new(call_conv: FrameCallConv) -> Self {
        Self {
            call_conv,
            frame_size: 0,
            uses_frame_pointer: true,
            shrink_wrap: ShrinkWrapConfig::default(),
            shrink_result: None,
            slot_graph: SlotInterferenceGraph::new(),
            slot_allocation: SlotAllocation::new(),
            frame_access: FrameAccessConfig::default(),
            access_decisions: HashMap::new(),
            emergency_slots: EmergencySpillSlotManager::new(DEFAULT_EMERGENCY_SLOTS, 0),
            realign_config: StackRealignConfig::default(),
            segmented_config: SegmentedStackConfig::default(),
            safestack_config: SafeStackConfig::default(),
            stack_clash_config: StackClashProtectionConfig::default(),
            patchpoint_config: PatchPointConfig::default(),
            varargs_config: VarArgsConfig::default(),
            sret_config: SretDemotionConfig::default(),
            callee_saved: CalleeSavedAssignment::new(),
            reserved_emergency_slots: Vec::new(),
            stack_probes: Vec::new(),
            varargs_frame: None,
            sret_slot: None,
            stats: FrameLoweringExtStats::default(),
        }
    }

    // -----------------------------------------------------------------------
    // Shrink Wrapping
    // -----------------------------------------------------------------------

    /// Estimate which blocks need callee-saved registers based on block usage.
    pub fn analyze_register_usage(
        &self,
        blocks: &[MachineBasicBlock],
    ) -> Vec<(u16, BTreeSet<usize>)> {
        let candidates = if self.call_conv.is_64bit() {
            if self.call_conv == FrameCallConv::Win64 {
                SHRINK_WRAP_CANDIDATES_WIN64
            } else {
                SHRINK_WRAP_CANDIDATES_SYSV
            }
        } else {
            &[]
        };

        candidates
            .iter()
            .map(|&reg| {
                let mut used_blocks = BTreeSet::new();
                for (i, block) in blocks.iter().enumerate() {
                    // If block uses this register, mark it
                    for instr in &block.instructions {
                        if Self::instr_uses_reg(instr, reg) {
                            used_blocks.insert(i);
                            break;
                        }
                    }
                }
                (reg, used_blocks)
            })
            .collect()
    }

    /// Check if a machine instruction uses a given register.
    fn instr_uses_reg(instr: &MachineInstr, reg: u16) -> bool {
        instr
            .operands
            .iter()
            .any(|op| matches!(op, MachineOperand::PhysReg(r) if *r == reg as u32))
    }

    /// Compute dominators for all blocks in the function.
    pub fn compute_dominators(&self, blocks: &[MachineBasicBlock]) -> Vec<DomTreeNode> {
        let n = blocks.len();
        if n == 0 {
            return Vec::new();
        }

        let mut doms: Vec<Option<usize>> = vec![None; n];
        doms[0] = Some(0); // Entry dominates itself

        let mut changed = true;
        while changed {
            changed = false;
            for i in 1..n {
                let preds = &blocks[i].predecessors;
                // Find intersection of dominators of all predecessors
                let mut new_idom: Option<usize> = None;
                for &pred in preds {
                    if let Some(pdom) = doms[pred] {
                        new_idom = Some(match new_idom {
                            None => pdom,
                            Some(cur) => Self::intersect_dominators(pdom, cur, &doms),
                        });
                    }
                }
                if new_idom != doms[i] {
                    doms[i] = new_idom;
                    changed = true;
                }
            }
        }

        // Build tree nodes
        let mut nodes: Vec<DomTreeNode> = (0..n).map(DomTreeNode::new).collect();
        for (i, dom) in doms.iter().enumerate() {
            if let Some(idom) = dom {
                if i != *idom {
                    nodes[*idom].children.push(i);
                }
                nodes[i].idom = Some(*idom);
            }
        }

        // Compute depths
        Self::compute_dom_depths(&mut nodes, 0, 0);

        nodes
    }

    /// Intersection of two dominators.
    fn intersect_dominators(a: usize, b: usize, doms: &[Option<usize>]) -> usize {
        let mut finger1 = a;
        let mut finger2 = b;
        while finger1 != finger2 {
            while finger1 > finger2 {
                finger1 = doms[finger1].unwrap_or(0);
            }
            while finger2 > finger1 {
                finger2 = doms[finger2].unwrap_or(0);
            }
        }
        finger1
    }

    /// Compute depths recursively.
    fn compute_dom_depths(nodes: &mut [DomTreeNode], node: usize, depth: u32) {
        nodes[node].depth = depth;
        let children = nodes[node].children.clone();
        for child in children {
            Self::compute_dom_depths(nodes, child, depth + 1);
        }
    }

    /// Determine optimal save/restore placement using dominance analysis.
    pub fn compute_save_restore_placement(
        &self,
        reg_usage: &[(u16, BTreeSet<usize>)],
        dom_tree: &[DomTreeNode],
        blocks: &[MachineBasicBlock],
    ) -> ShrinkWrapResult {
        let mut regions = Vec::new();
        let mut save_blocks = HashSet::new();
        let mut restore_blocks = HashSet::new();

        for &(reg, ref used_blocks) in reg_usage {
            if used_blocks.is_empty() {
                continue;
            }

            // Find earliest block where register is used
            let save_block = self.find_earliest_dominated_block(used_blocks, dom_tree, blocks);
            // Find latest block where register is used
            let restore_block = self.find_latest_post_dominated_block(used_blocks, blocks);

            let in_loop = false; // MachineBasicBlock has no is_loop_header field
            let loop_depth = 0u32; // MachineBasicBlock has no loop_depth field

            regions.push(SaveRestoreRegion {
                reg,
                save_block,
                restore_block,
                in_loop,
                loop_depth,
                can_hoist_save: !in_loop,
                can_sink_restore: true,
            });

            save_blocks.insert(save_block);
            restore_blocks.insert(restore_block);
        }

        let applied = !regions.is_empty();
        let savings = regions.iter().filter(|r| r.is_save_optimal()).count()
            + regions.iter().filter(|r| r.is_restore_optimal()).count();

        ShrinkWrapResult {
            regions,
            save_blocks,
            restore_blocks,
            applied,
            savings,
        }
    }

    /// Find the earliest block dominated by the entry that contains all uses.
    fn find_earliest_dominated_block(
        &self,
        used_blocks: &BTreeSet<usize>,
        dom_tree: &[DomTreeNode],
        blocks: &[MachineBasicBlock],
    ) -> usize {
        // The save should go in the dominator of all used blocks
        if used_blocks.is_empty() {
            return 0;
        }
        let mut common_dom = *used_blocks.iter().next().unwrap();
        for &block in used_blocks.iter().skip(1) {
            common_dom = Self::intersect_block_dominator(common_dom, block, dom_tree);
        }
        common_dom
    }

    /// Find the latest block post-dominated by exits that contains all uses.
    fn find_latest_post_dominated_block(
        &self,
        used_blocks: &BTreeSet<usize>,
        blocks: &[MachineBasicBlock],
    ) -> usize {
        // For restore, use the last use among used blocks
        // Simple heuristic: the block with the maximum index among used blocks
        used_blocks.iter().last().copied().unwrap_or(0)
    }

    /// Intersect two blocks in the dominator tree.
    fn intersect_block_dominator(a: usize, b: usize, dom_tree: &[DomTreeNode]) -> usize {
        let mut finger1 = a;
        let mut finger2 = b;
        while finger1 != finger2 {
            while finger1 > finger2 {
                finger1 = dom_tree[finger1].idom.unwrap_or(0);
            }
            while finger2 > finger1 {
                finger2 = dom_tree[finger2].idom.unwrap_or(0);
            }
        }
        finger1
    }

    /// Run shrink wrapping on the function.
    pub fn run_shrink_wrapping(&mut self, blocks: &[MachineBasicBlock]) {
        if !self.shrink_wrap.enabled {
            return;
        }

        let reg_usage = self.analyze_register_usage(blocks);
        let dom_tree = self.compute_dominators(blocks);

        let result = self.compute_save_restore_placement(&reg_usage, &dom_tree, blocks);
        self.stats.shrink_wrapped_saves = result.savings;
        self.shrink_result = Some(result);
    }

    // -----------------------------------------------------------------------
    // Stack Slot Coloring
    // -----------------------------------------------------------------------

    /// Build the interference graph for stack slots.
    pub fn build_slot_interference_graph(&mut self, slots: &[SlotLiveRange]) {
        self.slot_graph = SlotInterferenceGraph::new();
        for slot in slots {
            self.slot_graph.add_slot(slot.clone());
        }
        self.slot_graph.build();
    }

    /// Color stack slots using greedy coloring.
    pub fn color_stack_slots(&mut self) {
        let colors = self.slot_graph.greedy_color();
        self.stats.colors_used = colors.values().collect::<HashSet<_>>().len();

        // Assign offsets based on colors
        let mut color_sizes: HashMap<usize, u32> = HashMap::new();
        for (&slot_id, &color) in &colors {
            let size = self
                .slot_graph
                .live_ranges
                .get(&slot_id)
                .map(|lr| lr.size)
                .unwrap_or(8);
            let entry = color_sizes.entry(color).or_insert(0);
            *entry = (*entry).max(size);
        }

        // Compute offsets cumulatively
        let mut cur_offset = 0i32;
        let mut sorted_colors: Vec<usize> = color_sizes.keys().copied().collect();
        sorted_colors.sort();

        let mut color_offsets: HashMap<usize, i32> = HashMap::new();
        for color in sorted_colors {
            let size = color_sizes[&color];
            let align_mask = (size as i32) - 1;
            cur_offset = (cur_offset + align_mask) & !align_mask;
            color_offsets.insert(color, -cur_offset - size as i32);
            cur_offset += size as i32;
        }

        // Map colors to slot offsets
        for (&slot_id, &color) in &colors {
            if let Some(&offset) = color_offsets.get(&color) {
                self.slot_allocation.offsets.insert(slot_id, offset);
                if let Some(lr) = self.slot_graph.live_ranges.get(&slot_id) {
                    self.slot_allocation.sizes.insert(slot_id, lr.size);
                }
            }
        }

        self.slot_allocation.total_local_size = cur_offset as i64;
        self.slot_allocation.local_alignment = 16;
        self.slot_allocation.slot_count_before = colors.len();
        self.slot_allocation.slot_count_after = color_offsets.len();
        self.slot_allocation.merged_slots = color_offsets.len() < colors.len();
        self.stats.slots_merged =
            self.slot_allocation.slot_count_before - self.slot_allocation.slot_count_after;
    }

    // -----------------------------------------------------------------------
    // Frame Access Selection
    // -----------------------------------------------------------------------

    /// Decide whether to use frame pointer or stack pointer for each slot.
    pub fn select_frame_access(&mut self, blocks: &[MachineBasicBlock]) {
        if self.frame_access.preferred_mode == FrameAccessMode::StackPointer
            || (self.frame_access.preferred_mode == FrameAccessMode::Automatic
                && self.frame_access.allow_fp_elim
                && !self.frame_access.has_dynamic_alloca
                && !self.frame_access.has_vla)
        {
            // Use stack pointer relative access
            for (&slot_id, &offset) in &self.slot_allocation.offsets {
                let abs_offset = offset.unsigned_abs() as i32;
                if abs_offset <= self.frame_access.max_rsp_offset {
                    self.access_decisions.insert(
                        slot_id,
                        FrameAccessDecision::SpRelative { offset: abs_offset },
                    );
                } else {
                    self.access_decisions
                        .insert(slot_id, FrameAccessDecision::FpRelative { offset });
                }
            }
            self.stats.fp_eliminated = true;
        } else {
            // Use frame pointer relative access
            for (&slot_id, &offset) in &self.slot_allocation.offsets {
                self.access_decisions
                    .insert(slot_id, FrameAccessDecision::FpRelative { offset });
            }
            self.stats.fp_eliminated = false;
        }
    }

    // -----------------------------------------------------------------------
    // Emergency Spill Slots
    // -----------------------------------------------------------------------

    /// Initialize emergency spill slots.
    pub fn init_emergency_slots(&mut self, count: usize) {
        let base_offset = -(self.callee_saved.saved_area_size as i32) - EMERGENCY_SLOT_SIZE as i32;
        self.emergency_slots = EmergencySpillSlotManager::new(count, base_offset);
    }

    /// Allocate an emergency spill slot.
    pub fn allocate_emergency_slot(&mut self, reg: u16, at_inst: usize) -> Option<usize> {
        let result = self.emergency_slots.allocate(reg, at_inst);
        self.stats.emergency_spills = self.emergency_slots.allocation_count;
        result
    }

    // -----------------------------------------------------------------------
    // Dynamic Realignment
    // -----------------------------------------------------------------------

    /// Enable dynamic realignment with the given alignment.
    pub fn enable_dynamic_realignment(&mut self, alignment: u32) {
        self.realign_config.needed = true;
        self.realign_config.required_alignment = alignment;
        self.stats.realignment_applied = true;
    }

    /// Generate the realignment prologue.
    pub fn gen_realign_prologue(&self) -> RealignPrologue {
        generate_realign_prologue(&self.realign_config, self.frame_size)
    }

    /// Generate the realignment epilogue.
    pub fn gen_realign_epilogue(&self) -> RealignEpilogue {
        generate_realign_epilogue(&self.realign_config)
    }

    // -----------------------------------------------------------------------
    // Segmented Stacks
    // -----------------------------------------------------------------------

    /// Enable segmented stacks.
    pub fn enable_segmented_stacks(&mut self, segment_size: i64) {
        self.segmented_config.enabled = true;
        self.segmented_config.segment_size = segment_size;
        self.stats.segmented_active = true;
    }

    /// Generate segmented stack prologue.
    pub fn gen_segmented_prologue(&self) -> SegmentedStackPrologue {
        generate_segmented_prologue(&self.segmented_config, self.frame_size)
    }

    // -----------------------------------------------------------------------
    // SafeStack
    // -----------------------------------------------------------------------

    /// Enable SafeStack.
    pub fn enable_safestack(&mut self) {
        self.safestack_config.enabled = true;
        self.stats.safestack_active = true;
    }

    /// Layout safe stack objects.
    pub fn layout_safestack(&self, objects: &[SafeStackObject]) -> SafeStackFrame {
        layout_safe_stack(objects, &self.safestack_config)
    }

    // -----------------------------------------------------------------------
    // Stack Clash Protection
    // -----------------------------------------------------------------------

    /// Enable stack clash protection.
    pub fn enable_stack_clash_protection(&mut self) {
        self.stack_clash_config.enabled = true;
        self.stats.stack_clash_active = true;
    }

    /// Generate stack probes for the current frame.
    pub fn gen_stack_probes(&mut self) {
        self.stack_probes = generate_stack_probes(&self.stack_clash_config, self.frame_size);
        self.stats.probes_emitted = self.stack_probes.len();
    }

    // -----------------------------------------------------------------------
    // Varargs Frame
    // -----------------------------------------------------------------------

    /// Set up varargs frame.
    pub fn setup_varargs_frame(&mut self, config: VarArgsConfig) {
        self.varargs_config = config;
        self.varargs_frame = Some(build_varargs_frame(&self.varargs_config));
    }

    // -----------------------------------------------------------------------
    // Sret Demotion
    // -----------------------------------------------------------------------

    /// Demote sret to a local frame slot.
    pub fn demote_sret_to_frame(&mut self, config: SretDemotionConfig) {
        let mut local_offset = -self.callee_saved.saved_area_size as i32;
        let slot = demote_sret(&config, &mut local_offset);
        self.sret_slot = Some(slot);
        self.sret_config = config;
    }

    // -----------------------------------------------------------------------
    // Callee-Saved Registers
    // -----------------------------------------------------------------------

    /// Assign callee-saved registers in the frame.
    pub fn assign_callee_saved_regs(&mut self, used_regs: &[u16]) {
        let all_candidates = if self.call_conv.is_64bit() {
            if self.call_conv == FrameCallConv::Win64 {
                SHRINK_WRAP_CANDIDATES_WIN64
            } else {
                SHRINK_WRAP_CANDIDATES_SYSV
            }
        } else {
            &[]
        };

        let used_set: HashSet<u16> = used_regs.iter().copied().collect();
        for &reg in all_candidates {
            let mut csr = CalleeSavedReg::new(reg, 0, 8);
            csr.is_used = used_set.contains(&reg);
            self.callee_saved.saved_regs.push(csr);
        }

        // Compute offsets
        let mut cur_offset = self.callee_saved.base_offset;
        for csr in &mut self.callee_saved.saved_regs {
            if csr.is_used {
                cur_offset -= csr.size as i32;
                csr.frame_offset = cur_offset;
            }
        }
        self.callee_saved.saved_area_size = (self.callee_saved.base_offset - cur_offset) as i64;
    }

    /// Compute the final frame size including all areas.
    pub fn compute_final_frame_size(&mut self) -> i64 {
        let mut total = 0i64;

        // Return address (pushed by call)
        total += 8;

        // Saved frame pointer (if used)
        if self.uses_frame_pointer {
            total += 8;
        }

        // Callee-saved registers
        total += self.callee_saved.saved_area_size;

        // Emergency spill slots
        total += self.emergency_slots.total_size();

        // Local variables
        total += self.slot_allocation.total_local_size;

        // Varargs save area
        if let Some(ref vf) = self.varargs_frame {
            match vf {
                VarArgsFrameResult::SystemV(sysv) => {
                    total += sysv.total_save_area_size;
                }
                VarArgsFrameResult::Win64(win) => {
                    total += win.shadow_space_size;
                }
                _ => {}
            }
        }

        // Sret slot
        if let Some(ref sret) = self.sret_slot {
            total += sret.size as i64;
        }

        // Align to ABI requirements
        let alignment = self.call_conv.stack_alignment() as i64;
        total = (total + alignment - 1) & !(alignment - 1);

        // Shadow space for Win64
        if self.call_conv.has_shadow_space() {
            total += self.call_conv.shadow_space_size();
        }

        self.frame_size = total;
        self.stats.final_frame_size = total;
        total
    }
}

// ============================================================================
// Builder/factory functions
// ============================================================================

/// Create an extended frame lowering for System V AMD64.
pub fn make_x86_64_frame_lowering_ext_sysv() -> X86FrameLoweringExt {
    X86FrameLoweringExt::new(FrameCallConv::SystemVAMD64)
}

/// Create an extended frame lowering for Microsoft x64.
pub fn make_x86_64_frame_lowering_ext_win64() -> X86FrameLoweringExt {
    X86FrameLoweringExt::new(FrameCallConv::Win64)
}

/// Create an extended frame lowering for IA-32 cdecl.
pub fn make_x86_32_frame_lowering_ext_cdecl() -> X86FrameLoweringExt {
    X86FrameLoweringExt::new(FrameCallConv::Cdecl32)
}

/// Create an extended frame lowering with custom configuration.
pub fn make_frame_lowering_ext_with_config(
    call_conv: FrameCallConv,
    shrink_wrap: ShrinkWrapConfig,
    frame_access: FrameAccessConfig,
    stack_clash: StackClashProtectionConfig,
) -> X86FrameLoweringExt {
    let mut ext = X86FrameLoweringExt::new(call_conv);
    ext.shrink_wrap = shrink_wrap;
    ext.frame_access = frame_access;
    ext.stack_clash_config = stack_clash;
    ext
}

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

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

    // -----------------------------------------------------------------------
    // FrameCallConv tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_frame_call_conv_properties() {
        let sysv = FrameCallConv::SystemVAMD64;
        assert!(sysv.has_red_zone());
        assert!(!sysv.has_shadow_space());
        assert!(sysv.is_64bit());
        assert_eq!(sysv.red_zone_size(), 128);
        assert_eq!(sysv.shadow_space_size(), 0);
        assert_eq!(sysv.stack_alignment(), 16);

        let win64 = FrameCallConv::Win64;
        assert!(!win64.has_red_zone());
        assert!(win64.has_shadow_space());
        assert!(win64.is_64bit());
        assert_eq!(win64.red_zone_size(), 0);
        assert_eq!(win64.shadow_space_size(), 32);

        let cdecl = FrameCallConv::Cdecl32;
        assert!(!cdecl.has_red_zone());
        assert!(!cdecl.has_shadow_space());
        assert!(!cdecl.is_64bit());
    }

    #[test]
    fn test_frame_call_conv_is_register_based() {
        assert!(FrameCallConv::SystemVAMD64.is_register_based());
        assert!(FrameCallConv::Win64.is_register_based());
        assert!(FrameCallConv::Fastcall32.is_register_based());
        assert!(!FrameCallConv::Cdecl32.is_register_based());
        assert!(!FrameCallConv::Stdcall32.is_register_based());
    }

    // -----------------------------------------------------------------------
    // SlotInterferenceGraph tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_empty_interference_graph() {
        let graph = SlotInterferenceGraph::new();
        assert!(graph.nodes.is_empty());
        assert!(graph.edges.is_empty());
    }

    #[test]
    fn test_add_slot() {
        let mut graph = SlotInterferenceGraph::new();
        let range = SlotLiveRange {
            slot_id: 1,
            size: 8,
            alignment: 8,
            live_blocks: [0, 1].iter().copied().collect(),
            start: 0,
            end: 10,
            is_vector: false,
            is_emergency: false,
            is_callee_saved: false,
            spill_weight: 1.0,
        };
        graph.add_slot(range);
        assert_eq!(graph.nodes.len(), 1);
        assert!(graph.edges.contains_key(&1));
    }

    #[test]
    fn test_interference_non_overlapping() {
        let mut graph = SlotInterferenceGraph::new();
        let range1 = SlotLiveRange {
            slot_id: 1,
            size: 8,
            alignment: 8,
            live_blocks: [0].iter().copied().collect(),
            start: 0,
            end: 5,
            is_vector: false,
            is_emergency: false,
            is_callee_saved: false,
            spill_weight: 1.0,
        };
        let range2 = SlotLiveRange {
            slot_id: 2,
            size: 8,
            alignment: 8,
            live_blocks: [1].iter().copied().collect(),
            start: 5,
            end: 10,
            is_vector: false,
            is_emergency: false,
            is_callee_saved: false,
            spill_weight: 1.0,
        };
        graph.add_slot(range1);
        graph.add_slot(range2);
        graph.build();

        // Non-overlapping in blocks but time ranges could touch;
        // edges should be empty since blocks don't overlap
        let edges = graph.edges.get(&1).unwrap();
        assert!(!edges.contains(&2));
    }

    #[test]
    fn test_interference_overlapping() {
        let mut graph = SlotInterferenceGraph::new();
        let range1 = SlotLiveRange {
            slot_id: 1,
            size: 8,
            alignment: 8,
            live_blocks: [0, 1].iter().copied().collect(),
            start: 0,
            end: 10,
            is_vector: false,
            is_emergency: false,
            is_callee_saved: false,
            spill_weight: 1.0,
        };
        let range2 = SlotLiveRange {
            slot_id: 2,
            size: 8,
            alignment: 8,
            live_blocks: [0, 1].iter().copied().collect(),
            start: 2,
            end: 8,
            is_vector: false,
            is_emergency: false,
            is_callee_saved: false,
            spill_weight: 1.0,
        };
        graph.add_slot(range1);
        graph.add_slot(range2);
        graph.build();

        let edges = graph.edges.get(&1).unwrap();
        assert!(edges.contains(&2));
    }

    #[test]
    fn test_greedy_coloring_basic() {
        let mut graph = SlotInterferenceGraph::new();
        for i in 0..4 {
            let range = SlotLiveRange {
                slot_id: i,
                size: 8,
                alignment: 8,
                live_blocks: [i].iter().copied().collect(),
                start: i * 10,
                end: i * 10 + 5,
                is_vector: false,
                is_emergency: false,
                is_callee_saved: false,
                spill_weight: (i + 1) as f64,
            };
            graph.add_slot(range);
        }
        // No overlaps, so all same color
        let colors = graph.greedy_color();
        assert_eq!(colors.len(), 4);
    }

    // -----------------------------------------------------------------------
    // DomTreeNode tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_dominates() {
        // Dom tree: 0 -> 1 -> 2
        let mut nodes = vec![
            DomTreeNode::new(0),
            DomTreeNode::new(1),
            DomTreeNode::new(2),
        ];
        nodes[1].idom = Some(0);
        nodes[2].idom = Some(1);
        nodes[0].children.push(1);
        nodes[1].children.push(2);

        assert!(nodes[0].dominates(&nodes[1], &nodes));
        assert!(nodes[0].dominates(&nodes[2], &nodes));
        assert!(nodes[1].dominates(&nodes[2], &nodes));
        assert!(!nodes[1].dominates(&nodes[0], &nodes));
        assert!(!nodes[2].dominates(&nodes[0], &nodes));
    }

    #[test]
    fn test_compute_dominators_simple() {
        let ext = X86FrameLoweringExt::new(FrameCallConv::SystemVAMD64);
        let mut b0 = MachineBasicBlock::new(0);
        let mut b1 = MachineBasicBlock::new(1);
        let mut b2 = MachineBasicBlock::new(2);

        b0.successors.push(1);
        b0.successors.push(2);
        b1.predecessors.push(0);
        b2.predecessors.push(0);

        let blocks = vec![b0, b1, b2];
        let doms = ext.compute_dominators(&blocks);

        assert_eq!(doms.len(), 3);
        // Entry dominates itself
        assert_eq!(doms[0].idom, Some(0));
        // b1 dominated by entry
        assert_eq!(doms[1].idom, Some(0));
        // b2 dominated by entry
        assert_eq!(doms[2].idom, Some(0));
    }

    // -----------------------------------------------------------------------
    // Emergency spill slot tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_emergency_slot_allocate_free() {
        let mut mgr = EmergencySpillSlotManager::new(2, -16);
        assert_eq!(mgr.slots.len(), 2);

        let idx = mgr.allocate(RBX, 5);
        assert!(idx.is_some());
        assert!(!mgr.slots[idx.unwrap()].is_available());

        mgr.free(idx.unwrap());
        assert!(mgr.slots[idx.unwrap()].is_available());
    }

    #[test]
    fn test_emergency_slot_exhaustion() {
        let mut mgr = EmergencySpillSlotManager::new(1, -16);
        // Allocate the only slot
        let _i1 = mgr.allocate(RBX, 1);
        // Should clobber the oldest slot
        let i2 = mgr.allocate(R12, 2);
        assert!(i2.is_some());
        assert_eq!(mgr.exhaustion_count, 1);
    }

    // -----------------------------------------------------------------------
    // Stack realignment tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_alignment_mask() {
        assert_eq!(alignment_mask(16), !15i64);
        assert_eq!(alignment_mask(32), !31i64);
        assert_eq!(alignment_mask(64), !63i64);
    }

    #[test]
    fn test_generate_realign_prologue() {
        let config = StackRealignConfig {
            needed: true,
            required_alignment: 32,
            use_drap: false,
            drap_register: DRAP_REGISTER_ALT,
            has_variable_objects: false,
        };
        let prologue = generate_realign_prologue(&config, 64);
        assert!(!prologue.instructions.is_empty());
        assert!(!prologue.drap_setup);
    }

    #[test]
    fn test_generate_realign_prologue_with_drap() {
        let config = StackRealignConfig {
            needed: true,
            required_alignment: 64,
            use_drap: true,
            drap_register: R10,
            has_variable_objects: true,
        };
        let prologue = generate_realign_prologue(&config, 128);
        assert!(prologue.drap_setup);
    }

    // -----------------------------------------------------------------------
    // Segmented stack tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_segmented_prologue_small_frame() {
        let config = SegmentedStackConfig::default();
        let prologue = generate_segmented_prologue(&config, 512);
        // 512 < 1MB, so no expansion needed
        assert!(!prologue.needs_expansion);
    }

    #[test]
    fn test_segmented_prologue_large_frame() {
        let mut config = SegmentedStackConfig::default();
        config.segment_size = 4096;
        let prologue = generate_segmented_prologue(&config, 16384);
        // 16384 > 4096, so expansion needed
        assert!(prologue.needs_expansion);
    }

    // -----------------------------------------------------------------------
    // SafeStack tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_classify_safe_stack_object() {
        let mut obj = SafeStackObject::new(0, 8, 8);
        assert!(classify_safe_stack_object(&obj));

        obj.address_taken = true;
        assert!(!classify_safe_stack_object(&obj));
    }

    #[test]
    fn test_layout_safe_stack() {
        let objects = vec![
            SafeStackObject {
                id: 0,
                size: 8,
                alignment: 8,
                offset: 0,
                address_taken: false,
                has_safe_pointers: false,
            },
            SafeStackObject {
                id: 1,
                size: 16,
                alignment: 16,
                offset: 0,
                address_taken: true,
                has_safe_pointers: false,
            },
        ];
        let config = SafeStackConfig::default();
        let frame = layout_safe_stack(&objects, &config);

        assert_eq!(frame.safe_objects.len(), 1);
        assert_eq!(frame.unsafe_objects.len(), 1);
        assert!(frame.safe_frame_size > 0);
        assert!(frame.unsafe_frame_size > 0);
    }

    // -----------------------------------------------------------------------
    // Stack clash protection tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_no_probes_for_small_frame() {
        let config = StackClashProtectionConfig::default();
        let probes = generate_stack_probes(&config, 512);
        assert!(probes.is_empty());
    }

    #[test]
    fn test_probes_for_large_frame() {
        let config = StackClashProtectionConfig::default();
        let probes = generate_stack_probes(&config, 16384);
        assert!(!probes.is_empty());
        // Should have at least 4 probes for 16384 with 4096 interval
        assert!(probes.len() >= 2);
    }

    #[test]
    fn test_needs_stack_clash_protection() {
        let config = StackClashProtectionConfig::default();
        assert!(!needs_stack_clash_protection(&config, 2048));
        assert!(needs_stack_clash_protection(&config, 8192));
    }

    // -----------------------------------------------------------------------
    // StackMap / PatchPoint tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_stack_map_location() {
        let reg_loc = StackMapLocation::new_register(RAX, 8);
        assert_eq!(reg_loc.kind, StackMapLocKind::Register);
        assert_eq!(reg_loc.reg, RAX);

        let direct = StackMapLocation::new_direct(RSP, -16, 8);
        assert_eq!(direct.kind, StackMapLocKind::Direct);
        assert_eq!(direct.offset, -16);

        let constant = StackMapLocation::new_constant(42);
        assert_eq!(constant.kind, StackMapLocKind::Constant);
        assert_eq!(constant.constant, 42);
    }

    #[test]
    fn test_build_stack_map_entry() {
        let locs = vec![StackMapLocation::new_register(R10, 8)];
        let entry = build_stack_map_entry(1, 0x100, locs.clone(), 64, 0);
        assert_eq!(entry.id, 1);
        assert_eq!(entry.code_offset, 0x100);
        assert_eq!(entry.num_locations, 1);
        assert_eq!(entry.frame_size, 64);
    }

    // -----------------------------------------------------------------------
    // Varargs frame tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_sysv_varargs_frame_no_fixed_args() {
        let frame = SysVVarArgsFrame::new(0);
        assert_eq!(frame.num_gp_slots, 6);
        assert_eq!(frame.num_xmm_slots, 8);
        assert!(frame.total_save_area_size > 0);
    }

    #[test]
    fn test_sysv_varargs_frame_with_fixed_args() {
        let frame = SysVVarArgsFrame::new(2);
        assert_eq!(frame.num_gp_slots, 4); // 6 - 2
        assert_eq!(frame.num_xmm_slots, 6); // 8 - 2
    }

    #[test]
    fn test_win64_varargs_frame() {
        let frame = Win64VarArgsFrame::new();
        assert_eq!(frame.shadow_space_size, 32);
    }

    #[test]
    fn test_build_varargs_frame_sysv() {
        let config = VarArgsConfig {
            call_conv: FrameCallConv::SystemVAMD64,
            has_varargs: true,
            num_fixed_args: 1,
            ..Default::default()
        };
        let result = build_varargs_frame(&config);
        match result {
            VarArgsFrameResult::SystemV(sysv) => {
                assert_eq!(sysv.num_gp_slots, 5);
            }
            _ => panic!("Expected SystemV varargs frame"),
        }
    }

    // -----------------------------------------------------------------------
    // Sret demotion tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_demote_sret() {
        let config = SretDemotionConfig {
            needed: true,
            struct_size: 32,
            struct_alignment: 16,
            ..Default::default()
        };
        let mut local_offset = -16i32;
        let slot = demote_sret(&config, &mut local_offset);
        assert_eq!(slot.size, 32);
        assert_eq!(slot.alignment, 16);
        assert_eq!(local_offset, -48);
    }

    // -----------------------------------------------------------------------
    // CalleeSavedAssignment tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_callee_saved_assignment_add() {
        let mut csa = CalleeSavedAssignment::new();
        csa.add_reg(RBX, 8);
        csa.add_reg(R12, 8);
        assert_eq!(csa.saved_regs.len(), 2);
        assert_eq!(csa.saved_area_size, 16);
    }

    #[test]
    fn test_callee_saved_offset_for() {
        let mut csa = CalleeSavedAssignment::new();
        csa.add_reg(RBX, 8);
        csa.add_reg(R12, 8);

        let rbx_off = csa.offset_for(RBX);
        assert!(rbx_off.is_some());
        assert!(rbx_off.unwrap() < 0); // negative offset

        let r13_off = csa.offset_for(R13);
        assert!(r13_off.is_none());
    }

    // -----------------------------------------------------------------------
    // X86FrameLoweringExt integration tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_make_x86_64_frame_lowering_ext() {
        let ext = make_x86_64_frame_lowering_ext_sysv();
        assert_eq!(ext.call_conv, FrameCallConv::SystemVAMD64);
        assert!(ext.uses_frame_pointer);
    }

    #[test]
    fn test_make_frame_lowering_ext_with_config() {
        let ext = make_frame_lowering_ext_with_config(
            FrameCallConv::Win64,
            ShrinkWrapConfig::default(),
            FrameAccessConfig::default(),
            StackClashProtectionConfig::default(),
        );
        assert_eq!(ext.call_conv, FrameCallConv::Win64);
    }

    #[test]
    fn test_compute_final_frame_size_basic() {
        let mut ext = X86FrameLoweringExt::new(FrameCallConv::SystemVAMD64);
        let used_regs = vec![RBX, R12];
        ext.assign_callee_saved_regs(&used_regs);

        // Add some slots
        let slots: Vec<SlotLiveRange> = vec![SlotLiveRange {
            slot_id: 0,
            size: 8,
            alignment: 8,
            live_blocks: [0].iter().copied().collect(),
            start: 0,
            end: 1,
            is_vector: false,
            is_emergency: false,
            is_callee_saved: false,
            spill_weight: 1.0,
        }];
        ext.build_slot_interference_graph(&slots);
        ext.color_stack_slots();

        let size = ext.compute_final_frame_size();
        assert!(size > 0);
        assert_eq!(size % 16, 0); // must be 16-byte aligned for System V
    }

    #[test]
    fn test_run_shrink_wrapping_analyzes_usage() {
        let mut ext = X86FrameLoweringExt::new(FrameCallConv::SystemVAMD64);
        let blocks = vec![MachineBasicBlock::new(0), MachineBasicBlock::new(1)];
        ext.run_shrink_wrapping(&blocks);
        // Whether shrink wrapping is applied depends on register usage
        // in the blocks; with empty blocks, no saves needed
        if let Some(ref result) = ext.shrink_result {
            assert_eq!(result.savings, 0);
        }
    }

    #[test]
    fn test_select_frame_access_sp_relative() {
        let mut ext = X86FrameLoweringExt::new(FrameCallConv::SystemVAMD64);
        ext.frame_access = FrameAccessConfig {
            preferred_mode: FrameAccessMode::Automatic,
            allow_fp_elim: true,
            max_rsp_offset: 128,
            has_dynamic_alloca: false,
            has_vla: false,
            has_alloca: false,
            is_leaf: true,
        };
        // Add a small slot
        ext.slot_allocation.offsets.insert(0, -8);
        ext.slot_allocation.sizes.insert(0, 8);
        ext.slot_allocation.total_local_size = 8;

        ext.select_frame_access(&[]);

        let decision = ext.access_decisions.get(&0);
        assert!(decision.is_some());
        assert!(decision.unwrap().is_sp_relative());
    }
}