llvm-native-core 0.1.10

//! X86 Garbage Collection, Statepoint, and Exception Handling Lowering Module
//! — complete unified lowering of GC intrinsics, statepoints, stack maps,
//! safepoints, and all major EH personalities for X86 targets.
//!
//! Clean-room behavioral reconstruction from:
//! - LLVM Garbage Collection documentation (Statepoint, PatchPoint intrinsics)
//! - LLVM Stack Map format specification (`.llvm_stackmaps` section, v3)
//! - Itanium C++ ABI: Exception Handling (§1–§5)
//! - System V ABI: AMD64 Architecture Processor Supplement (LSDA / CFI)
//! - Microsoft x64 Exception Handling (SEH / VEH / C++ EH)
//! - DWARF Debugging Information Format (CFI for unwinding)
//! - Intel® 64 and IA-32 Architectures Software Developer's Manual
//! - .NET CoreCLR GCInfo specification
//! - OCaml runtime GC interface (frame descriptor tables)
//! - Erlang BEAM runtime GC (per-process heap, reduction-based scheduling)
//!
//! Zero LLVM source code consultation. All behavior reconstructed from
//! published specifications and black-box oracle interrogation.
//!
//! ## Subsystems
//!
//! - **X86GCEHFull** — central struct governing GC/EH lowering configuration.
//! - **X86GCStrategy** — GC strategies: Statepoint, CoreCLR, OCaml, Erlang,
//!   ShadowStack.
//! - **X86StatepointLowering** — lowering `gc.statepoint`, `gc.result`,
//!   `gc.relocate` intrinsics.
//! - **X86GCRootEnumeration** — identify live GC pointers at safepoints.
//! - **X86GCStackMap** — stack map generation, `.llvm_stackmaps` section.
//! - **X86GCSafepoint** — safepoint insertion at back-edges and calls.
//! - **X86GCRewriteStatepoints** — RewriteStatepointsForGC pass logic.
//! - **X86ItaniumEH** — landingpad, resume, cleanupret, catchret,
//!   catchswitch, catchpad, cleanuppad.
//! - **X86SEH** — __C_specific_handler, __CxxFrameHandler3, filter functions.
//! - **X86DWARFEH** — .eh_frame, .gcc_except_table, LSDA encoding.
//! - **X86WindowsEH** — .xdata, .pdata, UNWIND_INFO, RUNTIME_FUNCTION.
//! - **X86EHPreparation** — outline landing pads, prune unreachable handlers.
//! - **X86EHOptimization** — merge identical landing pads, remove dead catches.
//! - **X86Personality** — __gxx_personality_v0, __gcc_personality_v0,
//!   __CxxFrameHandler3, __C_specific_handler, __objc_personality_v0,
//!   __gxx_personality_seh0.
//! - **X86StackMapSection** — .llvm_stackmaps emission, patchpoint lowering.

#![allow(non_upper_case_globals, dead_code)]

use std::collections::{BTreeMap, HashMap, HashSet};
use std::fmt;

use crate::codegen::MachineInstr;

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

/// Maximum number of GC roots tracked per function.
pub const GC_EH_MAX_ROOTS: usize = 1024;

/// Maximum number of safepoints per function.
pub const GC_EH_MAX_SAFEPOINTS: usize = 2048;

/// Maximum number of landing pads per function.
pub const GC_EH_MAX_LANDINGPADS: usize = 128;

/// Maximum number of catch clauses per landing pad.
pub const GC_EH_MAX_CATCH_CLAUSES: usize = 64;

/// Stack map version (LLVM current: 3).
pub const GC_EH_STACK_MAP_VERSION: u8 = 3;

/// Stack map section name.
pub const GC_EH_STACK_MAP_SECTION: &str = ".llvm_stackmaps";

/// Default number of bytes per stack map record.
pub const GC_EH_STACK_MAP_RECORD_SIZE: u32 = 24;

/// Maximum size of a patchpoint (in bytes).
pub const GC_EH_MAX_PATCHPOINT_SIZE: u32 = 256;

/// LSDA encoding: DW_EH_PE_omit | DW_EH_PE_udata4 | DW_EH_PE_datarel.
pub const GC_EH_LSDA_ENCODING: u8 = 0xFF;

/// FDE encoding: DW_EH_PE_absptr.
pub const GC_EH_FDE_ENCODING: u8 = 0x00;

/// Personality encoding: DW_EH_PE_udata4 | DW_EH_PE_indirect | DW_EH_PE_pcrel.
pub const GC_EH_PERSONALITY_ENCODING: u8 = 0x9B;

/// Default call-site table encoding.
pub const GC_EH_CALLSITE_ENCODING: u8 = 0x01; // uleb128

/// Exception header size per Itanium C++ ABI §1.2.
pub const GC_EH_CXA_EXCEPTION_HEADER_SIZE: usize = 128;

/// Size of an unwind code in bytes.
pub const GC_EH_UNWIND_CODE_SIZE: usize = 2;

/// Maximum number of unwind codes per function.
pub const GC_EH_MAX_UNWIND_CODES: usize = 256;

/// DWARF register numbers for X86-64 GPRs.
const DW_RAX: u16 = 0;
const DW_RDX: u16 = 1;
const DW_RCX: u16 = 2;
const DW_RBX: u16 = 3;
const DW_RSI: u16 = 4;
const DW_RDI: u16 = 5;
const DW_RBP: u16 = 6;
const DW_RSP: u16 = 7;
const DW_R8: u16 = 8;
const DW_R9: u16 = 9;
const DW_R10: u16 = 10;
const DW_R11: u16 = 11;
const DW_R12: u16 = 12;
const DW_R13: u16 = 13;
const DW_R14: u16 = 14;
const DW_R15: u16 = 15;
const DW_RIP: u16 = 16;

/// Callee-saved GPRs (DWARF numbers).
const CALLEE_SAVED_GPRS: &[u16] = &[DW_RBX, DW_RBP, DW_R12, DW_R13, DW_R14, DW_R15];

/// Caller-saved GPRs that may hold GC pointers.
const CALLER_SAVED_GPRS: &[u16] = &[
    DW_RAX, DW_RCX, DW_RDX, DW_RSI, DW_RDI, DW_R8, DW_R9, DW_R10, DW_R11,
];

/// GC pointer registers — registers the GC cares about.
const GC_POINTER_GPRS: &[u16] = &[
    DW_RAX, DW_RBX, DW_RCX, DW_RDX, DW_RSI, DW_RDI, DW_R8, DW_R9, DW_R10, DW_R11, DW_R12, DW_R13,
    DW_R14, DW_R15,
];

/// Maximum derived pointer offset.
pub const GC_EH_MAX_DERIVED_OFFSET: i64 = 4096;

/// Polling page address for cooperative safepoints.
pub const GC_EH_POLLING_PAGE: u64 = 0x7FFF_FFFF_FFFF_F000;

/// Safepoint polling page size.
pub const GC_EH_POLLING_PAGE_SIZE: u64 = 4096;

/// Stack alignment for X86-64.
pub const GC_EH_STACK_ALIGNMENT: u64 = 16;

/// Red zone size for System V AMD64 ABI.
pub const GC_EH_RED_ZONE_SIZE: i64 = 128;

/// Number of exception pointer registers per Itanium ABI.
pub const GC_EH_EXCEPTION_PTR_REGNO_COUNT: usize = 2;

// ============================================================================
// X86GCEHFull — master GC/EH lowering struct
// ============================================================================

/// Central configuration and state for X86 GC and EH lowering.
///
/// `X86GCEHFull` orchestrates the entire lowering pipeline:
/// 1. GC strategy selection and configuration
/// 2. Statepoint insertion and lowering
/// 3. GC root enumeration and stack map generation
/// 4. EH preparation and optimization
/// 5. Personality function lowering
/// 6. Stack map section emission
#[derive(Debug, Clone)]
pub struct X86GCEHFull {
    /// Selected GC strategy.
    pub gc_strategy: X86GCEHStrategy,
    /// Whether to generate statepoints.
    pub enable_statepoints: bool,
    /// Whether to generate stack maps.
    pub enable_stack_maps: bool,
    /// Whether to insert safepoints at loop backedges.
    pub safepoints_at_backedges: bool,
    /// Whether to insert safepoints before calls.
    pub safepoints_at_calls: bool,
    /// Whether to use cooperative polling.
    pub cooperative_polling: bool,
    /// EH personality function kind.
    pub personality: X86GCEHPersonality,
    /// Whether to emit DWARF EH frames.
    pub emit_dwarf_eh: bool,
    /// Whether to emit SEH unwind info.
    pub emit_seh: bool,
    /// Whether to outline landing pads.
    pub outline_landing_pads: bool,
    /// Whether to merge identical landing pads.
    pub merge_landing_pads: bool,
    /// Whether to prune unreachable handlers.
    pub prune_unreachable_handlers: bool,
    /// Target triple (e.g., "x86_64-unknown-linux-gnu").
    pub target_triple: String,
    /// Target data layout.
    pub data_layout: String,
    /// Pointer size in bytes (8 for X86-64).
    pub pointer_size: u8,
    /// Whether this is a 64-bit target.
    pub is_64bit: bool,
    /// Whether this is a Windows target.
    pub is_windows: bool,
    /// Whether this is a MinGW target.
    pub is_mingw: bool,
    /// Frame pointer register.
    pub frame_pointer_reg: u16,
    /// Stack pointer register.
    pub stack_pointer_reg: u16,
    /// Return address register (Dwarf).
    pub return_address_reg: u16,
    /// Accumulated stack maps.
    pub stack_maps: Vec<X86GCEHStackMapRecord>,
    /// Accumulated safepoints.
    pub safepoints: Vec<X86GCEHSafepoint>,
    /// Accumulated landing pads.
    pub landing_pads: Vec<X86GCEHLandingPad>,
    /// Accumulated personality functions referenced.
    pub personality_refs: HashSet<String>,
    /// Statepoint ID counter.
    next_statepoint_id: u64,
    /// Stack map ID counter.
    next_stack_map_id: u64,
    /// Safepoint ID counter.
    next_safepoint_id: u64,
    /// Landing pad ID counter.
    next_landingpad_id: u64,
    /// Catch clause ID counter.
    next_catch_id: u64,
    /// Unwind code buffer per function.
    unwind_codes: Vec<X86GCEHUnwindCode>,
    /// LSDA emission buffer.
    lsda_buffer: Vec<u8>,
    /// .eh_frame CIE buffer.
    eh_frame_cie: Vec<u8>,
    /// .eh_frame FDE buffer.
    eh_frame_fdes: Vec<u8>,
    /// .xdata section buffer.
    xdata_buffer: Vec<u8>,
    /// .pdata section buffer.
    pdata_buffer: Vec<u8>,
    /// Stack map section buffer.
    stack_map_buffer: Vec<u8>,
    /// GC roots currently tracked.
    active_roots: BTreeMap<u16, X86GCEHRoot>,
    /// Stack slots holding GC roots.
    stack_roots: Vec<X86GCEHStackSlot>,
    /// Call site table entries for current function.
    call_site_table: Vec<X86GCEHCallSiteEntry>,
    /// Type info table for current function (EH).
    type_info_table: Vec<X86GCEHTypeInfoEntry>,
    /// Action records for current function (EH).
    action_records: Vec<X86GCEHActionRecord>,
    /// Whether the current function uses GC.
    pub uses_gc: bool,
    /// Whether the current function uses EH.
    pub uses_eh: bool,
    /// Whether the current function has a personality function.
    pub has_personality: bool,
    /// Current function name being compiled.
    pub current_function: String,
}

impl Default for X86GCEHFull {
    fn default() -> Self {
        Self {
            gc_strategy: X86GCEHStrategy::Statepoint,
            enable_statepoints: true,
            enable_stack_maps: true,
            safepoints_at_backedges: true,
            safepoints_at_calls: true,
            cooperative_polling: false,
            personality: X86GCEHPersonality::GxxV0,
            emit_dwarf_eh: true,
            emit_seh: false,
            outline_landing_pads: true,
            merge_landing_pads: true,
            prune_unreachable_handlers: true,
            target_triple: "x86_64-unknown-linux-gnu".to_string(),
            data_layout: "e-m:e-p270:32:32-p271:32:32-p272:64:64-i64:64-i128:128-\
                          f80:128-n8:16:32:64-S128"
                .to_string(),
            pointer_size: 8,
            is_64bit: true,
            is_windows: false,
            is_mingw: false,
            frame_pointer_reg: DW_RBP,
            stack_pointer_reg: DW_RSP,
            return_address_reg: DW_RIP,
            stack_maps: Vec::new(),
            safepoints: Vec::new(),
            landing_pads: Vec::new(),
            personality_refs: HashSet::new(),
            next_statepoint_id: 0,
            next_stack_map_id: 0,
            next_safepoint_id: 0,
            next_landingpad_id: 0,
            next_catch_id: 0,
            unwind_codes: Vec::new(),
            lsda_buffer: Vec::new(),
            eh_frame_cie: Vec::new(),
            eh_frame_fdes: Vec::new(),
            xdata_buffer: Vec::new(),
            pdata_buffer: Vec::new(),
            stack_map_buffer: Vec::new(),
            active_roots: BTreeMap::new(),
            stack_roots: Vec::new(),
            call_site_table: Vec::new(),
            type_info_table: Vec::new(),
            action_records: Vec::new(),
            uses_gc: false,
            uses_eh: false,
            has_personality: false,
            current_function: String::new(),
        }
    }
}

impl X86GCEHFull {
    // ---- ID generation ----

    pub fn next_statepoint_id(&mut self) -> u64 {
        let id = self.next_statepoint_id;
        self.next_statepoint_id += 1;
        id
    }

    pub fn next_stack_map_id(&mut self) -> u64 {
        let id = self.next_stack_map_id;
        self.next_stack_map_id += 1;
        id
    }

    pub fn next_safepoint_id(&mut self) -> u64 {
        let id = self.next_safepoint_id;
        self.next_safepoint_id += 1;
        id
    }

    pub fn next_landingpad_id(&mut self) -> u64 {
        let id = self.next_landingpad_id;
        self.next_landingpad_id += 1;
        id
    }

    pub fn next_catch_id(&mut self) -> u64 {
        let id = self.next_catch_id;
        self.next_catch_id += 1;
        id
    }

    // ---- Function-level lifecycle ----

    /// Begin lowering for a new function, resetting per-function state.
    pub fn begin_function(&mut self, name: &str, uses_gc: bool, uses_eh: bool) {
        self.current_function = name.to_string();
        self.uses_gc = uses_gc;
        self.uses_eh = uses_eh;
        self.has_personality = uses_eh;
        self.active_roots.clear();
        self.stack_roots.clear();
        self.call_site_table.clear();
        self.type_info_table.clear();
        self.action_records.clear();
        self.unwind_codes.clear();
        self.lsda_buffer.clear();
        self.eh_frame_fdes.clear();
        self.xdata_buffer.clear();
        self.pdata_buffer.clear();
    }

    /// Finalize lowering for the current function.
    pub fn end_function(&mut self) {
        if self.uses_gc && self.enable_stack_maps {
            self.emit_function_stack_map();
        }
        if self.uses_eh {
            if self.emit_dwarf_eh {
                self.emit_dwarf_eh_frame();
            }
            if self.emit_seh {
                self.emit_seh_unwind_info();
            }
        }
    }

    /// Reset all state for module-level finalization.
    pub fn reset(&mut self) {
        *self = Self::default();
    }
}

// ============================================================================
// GC Strategy
// ============================================================================

/// GC strategies supported by the lowering module.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCEHStrategy {
    /// Statepoint-based precise GC.
    Statepoint,
    /// .NET CoreCLR GC with GCInfo tables.
    CoreCLR,
    /// OCaml-compatible GC with frame descriptor tables.
    OCaml,
    /// Erlang-style per-process GC.
    Erlang,
    /// Shadow stack GC (dual-stack model).
    ShadowStack,
    /// Custom GC strategy.
    Custom,
    /// No GC support.
    None,
}

impl fmt::Display for X86GCEHStrategy {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Statepoint => write!(f, "statepoint-example"),
            Self::CoreCLR => write!(f, "coreclr"),
            Self::OCaml => write!(f, "ocaml"),
            Self::Erlang => write!(f, "erlang"),
            Self::ShadowStack => write!(f, "shadow-stack"),
            Self::Custom => write!(f, "custom"),
            Self::None => write!(f, "none"),
        }
    }
}

impl X86GCEHStrategy {
    /// Returns true if this strategy uses statepoints.
    pub fn uses_statepoints(&self) -> bool {
        matches!(self, Self::Statepoint)
    }

    /// Returns true if this strategy uses a shadow stack.
    pub fn uses_shadow_stack(&self) -> bool {
        matches!(self, Self::ShadowStack)
    }

    /// Returns true if this strategy needs stack maps.
    pub fn needs_stack_maps(&self) -> bool {
        matches!(self, Self::Statepoint | Self::CoreCLR | Self::OCaml)
    }

    /// Returns true if this strategy requires write barriers.
    pub fn requires_write_barriers(&self) -> bool {
        matches!(
            self,
            Self::Statepoint | Self::CoreCLR | Self::Erlang | Self::OCaml
        )
    }

    /// Returns the LLVM gc-strategy attribute name.
    pub fn llvm_attr_name(&self) -> &str {
        match self {
            Self::Statepoint => "statepoint-example",
            Self::CoreCLR => "coreclr",
            Self::OCaml => "ocaml",
            Self::Erlang => "erlang",
            Self::ShadowStack => "shadow-stack",
            Self::Custom => "custom",
            Self::None => "",
        }
    }

    /// Returns cooperative suspension mechanism for the strategy.
    pub fn suspension(&self) -> X86GCEHSuspension {
        match self {
            Self::Statepoint | Self::CoreCLR | Self::OCaml => X86GCEHSuspension::Polling,
            Self::Erlang => X86GCEHSuspension::ReductionBased,
            Self::ShadowStack => X86GCEHSuspension::SignalBased,
            Self::Custom | Self::None => X86GCEHSuspension::None,
        }
    }
}

/// Cooperative suspension mechanism.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCEHSuspension {
    /// No cooperative suspension.
    None,
    /// Polling at loop backedges and function entries.
    Polling,
    /// Signal-based thread suspension.
    SignalBased,
    /// Page-fault-based suspension via guard page.
    PageFault,
    /// Erlang-style reduction-based scheduling.
    ReductionBased,
    /// Hybrid polling + signal fallback.
    Hybrid,
}

impl Default for X86GCEHSuspension {
    fn default() -> Self {
        Self::Polling
    }
}

// ============================================================================
// GC Root Types
// ============================================================================

/// A GC root — a live pointer at a safepoint.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct X86GCEHRoot {
    /// Root kind.
    pub kind: X86GCEHRootKind,
    /// Register number (Dwarf encoding for registers, `u16::MAX` for stack).
    pub location: X86GCEHRootLocation,
    /// Whether this root is a derived pointer (interior pointer).
    pub is_derived: bool,
    /// For derived pointers, the offset from the base object.
    pub derived_offset: i64,
    /// Whether this root is live at the current safepoint.
    pub is_live: bool,
    /// Human-readable description.
    pub description: String,
}

/// Kind classification of a GC root.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCEHRootKind {
    /// A regular (base) object pointer.
    ObjectPointer,
    /// A derived pointer (interior pointer into an object).
    DerivedPointer,
    /// A static/global root.
    StaticRoot,
    /// A thread-local root.
    ThreadLocal,
    /// A stack-allocated root.
    StackAllocated,
    /// An alloca-derived root.
    Alloca,
    /// A phi-derived root requiring relocation.
    PhiNode,
}

/// Location of a GC root.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCEHRootLocation {
    /// Root lives in a register (Dwarf regno).
    Register(u16),
    /// Root lives at a stack offset from the base pointer.
    StackOffset(i32),
    /// Root lives at a stack offset from the stack pointer.
    StackSPOffset(i32),
    /// Root lives at a fixed address (static root).
    FixedAddress(u64),
    /// Root is unknown/conservative.
    Unknown,
}

impl fmt::Display for X86GCEHRootLocation {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Register(r) => write!(f, "reg(D{})", r),
            Self::StackOffset(off) => write!(f, "bp{:+}", off),
            Self::StackSPOffset(off) => write!(f, "sp{:+}", off),
            Self::FixedAddress(addr) => write!(f, "addr(0x{:x})", addr),
            Self::Unknown => write!(f, "unknown"),
        }
    }
}

/// A stack slot that holds a GC root.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct X86GCEHStackSlot {
    /// Stack offset from the frame pointer.
    pub offset: i32,
    /// Size of the slot in bytes.
    pub size: u8,
    /// Whether the slot holds a derived pointer.
    pub is_derived: bool,
    /// Whether the slot is live at the current safepoint.
    pub is_live: bool,
    /// Debug name of the value stored.
    pub name: String,
}

// ============================================================================
// Statepoint Types
// ============================================================================

/// A statepoint — a GC safe point with explicit root tracking.
#[derive(Debug, Clone)]
pub struct X86GCEHStatepoint {
    /// Unique statepoint ID.
    pub id: u64,
    /// Program counter (instruction offset) of the statepoint call.
    pub pc_offset: u64,
    /// ID of the statepoint in the stack map.
    pub stack_map_id: u64,
    /// The call target being wrapped (if any).
    pub call_target: Option<String>,
    /// Number of call arguments.
    pub num_call_args: u32,
    /// Flags for the statepoint.
    pub flags: u32,
    /// Number of deoptimization state bytes.
    pub num_deopt_bytes: u32,
    /// Deoptimization state data.
    pub deopt_state: Vec<u8>,
    /// GC transition flags.
    pub gc_transition: X86GCEHGCTransition,
    /// Number of GC roots at this statepoint.
    pub num_roots: u32,
    /// GC roots live at this statepoint.
    pub roots: Vec<X86GCEHRoot>,
    /// Stack slot roots at this statepoint.
    pub stack_slots: Vec<X86GCEHStackSlot>,
}

/// GC transition flags for a statepoint.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCEHGCTransition {
    /// No GC transition — statepoint does not invoke GC.
    None,
    /// Statepoint may invoke GC (safepoint poll).
    Safepoint,
    /// Statepoint invokes GC and may relocate objects.
    Relocation,
    /// Statepoint is a deoptimization continuation point.
    Deopt,
}

/// A gc.relocate record — post-statepoint pointer relocation.
#[derive(Debug, Clone)]
pub struct X86GCEHRelocate {
    /// The statepoint ID this relocation belongs to.
    pub statepoint_id: u64,
    /// Base offset of the relocated pointer in the statepoint.
    pub base_offset: u32,
    /// Derived offset of the relocated pointer in the statepoint.
    pub derived_offset: u32,
    /// The original value before relocation.
    pub original_value: u64,
    /// The relocated value after GC.
    pub relocated_value: u64,
    /// Target register for the relocated pointer.
    pub target_reg: Option<u16>,
    /// Target stack slot for the relocated pointer.
    pub target_stack_offset: Option<i32>,
}

// ============================================================================
// Safepoint Types
// ============================================================================

/// A safepoint inserted into the instruction stream.
#[derive(Debug, Clone)]
pub struct X86GCEHSafepoint {
    /// Unique safepoint ID.
    pub id: u64,
    /// Kind of safepoint.
    pub kind: X86GCEHSafepointKind,
    /// Program counter offset where the safepoint is inserted.
    pub pc_offset: u64,
    /// Whether this safepoint may invoke GC.
    pub may_gc: bool,
    /// The statepoint associated with this safepoint (if any).
    pub statepoint_id: Option<u64>,
    /// Stack map ID for this safepoint.
    pub stack_map_id: Option<u64>,
}

/// Kinds of safepoints.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCEHSafepointKind {
    /// Safepoint before a call instruction.
    PreCall,
    /// Safepoint after a call instruction.
    PostCall,
    /// Safepoint at a loop backedge.
    LoopBackedge,
    /// Safepoint at function entry.
    FunctionEntry,
    /// Safepoint at function return.
    FunctionReturn,
    /// Safepoint for cooperative polling.
    Poll,
    /// Machine-level safepoint (only at instruction boundaries).
    MachineSafepoint,
}

impl fmt::Display for X86GCEHSafepointKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::PreCall => write!(f, "pre-call"),
            Self::PostCall => write!(f, "post-call"),
            Self::LoopBackedge => write!(f, "loop-backedge"),
            Self::FunctionEntry => write!(f, "entry"),
            Self::FunctionReturn => write!(f, "return"),
            Self::Poll => write!(f, "poll"),
            Self::MachineSafepoint => write!(f, "machine"),
        }
    }
}

// ============================================================================
// Stack Map Types
// ============================================================================

/// A stack map record as emitted in `.llvm_stackmaps`.
#[derive(Debug, Clone)]
pub struct X86GCEHStackMapRecord {
    /// Stack map ID (unique per function).
    pub id: u64,
    /// Function address (or offset).
    pub function_address: u64,
    /// Offset of the statepoint/call within the function.
    pub instruction_offset: u64,
    /// Number of locations in this record.
    pub num_locations: u16,
    /// Live locations (register or stack).
    pub locations: Vec<X86GCEHStackMapLocation>,
    /// Number of live-out registers.
    pub num_live_outs: u16,
    /// Live-out register values.
    pub live_outs: Vec<X86GCEHLiveOut>,
    /// Padding to align the next record.
    pub padding: u8,
}

/// A single location (root) in a stack map record.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct X86GCEHStackMapLocation {
    /// Dwarf expression byte for register (DWARF register number).
    pub dwarf_reg: u16,
    /// Reserved (must be 0).
    pub reserved: u16,
    /// Offset from the register (for stack slots: offset from RSP/CFA).
    pub offset: i32,
    /// Location kind.
    pub kind: X86GCEHStackMapLocationKind,
    /// Size in bytes of the location.
    pub size: u8,
}

/// Stack map location kinds (LLVM Stack Map v3).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum X86GCEHStackMapLocationKind {
    /// Register location.
    Register = 1,
    /// Direct memory address: reg + offset.
    Direct = 2,
    /// Indirect memory address: [reg + offset].
    Indirect = 3,
    /// Constant value.
    Constant = 4,
    /// Constant index (deopt state).
    ConstantIndex = 5,
}

/// A live-out register value in a stack map.
#[derive(Debug, Clone, Copy)]
pub struct X86GCEHLiveOut {
    /// Dwarf register number.
    pub dwarf_reg: u16,
    /// Reserved.
    pub reserved: u8,
    /// Size in bytes of the live-out value.
    pub size: u8,
}

// ============================================================================
// Patchpoint Types
// ============================================================================

/// A patchpoint intrinsic lowering.
#[derive(Debug, Clone)]
pub struct X86GCEHPatchpoint {
    /// Patchpoint ID.
    pub id: u64,
    /// Flags (bit 0: anyregcc).
    pub flags: u32,
    /// Number of bytes the call site occupies.
    pub num_bytes: u32,
    /// Number of call arguments.
    pub num_args: u32,
    /// Callee address (or constant).
    pub callee: u64,
    /// Number of args being passed.
    pub num_patch_args: u16,
    /// Call target location (register for indirect, 0 for direct).
    pub cc: u32,
    /// Stack map produced by this patchpoint.
    pub stack_map_id: Option<u64>,
}

// ============================================================================
// Itanium C++ ABI — Exception Handling Types
// ============================================================================

/// EH personality function kind.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCEHPersonality {
    /// GCC C++ personality: __gxx_personality_v0
    GxxV0,
    /// GCC C personality: __gcc_personality_v0
    GccV0,
    /// MSVC C++ SEH personality: __CxxFrameHandler3
    CxxFrameHandler3,
    /// MSVC C SEH personality: __C_specific_handler
    CSpecificHandler,
    /// ObjC personality: __objc_personality_v0
    ObjCV0,
    /// MinGW SEH personality: __gxx_personality_seh0
    GxxSeh0,
    /// No personality function.
    None,
}

impl X86GCEHPersonality {
    /// Returns the canonical symbol name.
    pub fn symbol_name(&self) -> &str {
        match self {
            Self::GxxV0 => "__gxx_personality_v0",
            Self::GccV0 => "__gcc_personality_v0",
            Self::CxxFrameHandler3 => "__CxxFrameHandler3",
            Self::CSpecificHandler => "__C_specific_handler",
            Self::ObjCV0 => "__objc_personality_v0",
            Self::GxxSeh0 => "__gxx_personality_seh0",
            Self::None => "",
        }
    }

    /// Returns true if this is an Itanium-style personality.
    pub fn is_itanium(&self) -> bool {
        matches!(self, Self::GxxV0 | Self::GccV0 | Self::ObjCV0)
    }

    /// Returns true if this is a Windows SEH personality.
    pub fn is_seh(&self) -> bool {
        matches!(
            self,
            Self::CxxFrameHandler3 | Self::CSpecificHandler | Self::GxxSeh0
        )
    }
}

/// A landing pad — the destination of an unwind edge.
#[derive(Debug, Clone)]
pub struct X86GCEHLandingPad {
    /// Unique landing pad ID.
    pub id: u64,
    /// The kind of landing pad instruction.
    pub kind: X86GCEHLandingPadKind,
    /// Exception pointer register number (per ABI).
    pub exc_ptr_reg: u16,
    /// Filter pointer register number (per ABI).
    pub filter_ptr_reg: u16,
    /// Catch clauses.
    pub clauses: Vec<X86GCEHClause>,
    /// Whether the landing pad is a cleanup-only pad.
    pub is_cleanup: bool,
    /// Whether to prune this landing pad as unreachable.
    pub is_unreachable: bool,
    /// Whether this pad has been outlined.
    pub is_outlined: bool,
    /// Call site table entries associated with this pad.
    pub call_site_entries: Vec<u32>,
    /// Merged from (IDs of pads merged into this one).
    pub merged_from: Vec<u64>,
}

/// Kinds of LLVM landing pad instructions.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum X86GCEHLandingPadKind {
    /// `landingpad` instruction — Itanium ABI catch/dispatch.
    LandingPad,
    /// `cleanuppad` — Windows EH cleanup.
    CleanupPad,
    /// `catchpad` — Windows EH catch handler.
    CatchPad,
    /// `catchswitch` — dispatches to catch handlers.
    CatchSwitch,
    /// `catchret` — return from catch to normal code.
    CatchRet,
    /// `cleanupret` — return from cleanup.
    CleanupRet,
    /// `resume` — resume unwinding after a landing pad.
    Resume,
}

/// A clause in a landing pad instruction.
#[derive(Debug, Clone)]
pub struct X86GCEHClause {
    /// Clause kind.
    pub kind: X86GCEHClauseKind,
    /// Type info for the caught type (null for catch-all, filter).
    pub type_info: Option<X86GCEHTypeInfoEntry>,
    /// Filter function for SEH filter expressions.
    pub filter_fn: Option<String>,
    /// Catch handler block reference.
    pub handler: Option<String>,
    /// Whether this is a catch-all clause.
    pub is_catch_all: bool,
}

/// Kinds of landing pad clauses.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86GCEHClauseKind {
    /// `catch (Type)` — matches a specific type.
    Catch,
    /// `catch (...)` — matches all types.
    CatchAll,
    /// `filter (fn)` — SEH filter expression.
    Filter,
    /// Cleanup — always selected.
    Cleanup,
}

/// A call site entry in the LSDA call-site table.
#[derive(Debug, Clone)]
pub struct X86GCEHCallSiteEntry {
    /// Start offset of the call site (relative to function start).
    pub cs_start: u32,
    /// Length of the call site in bytes.
    pub cs_length: u32,
    /// Offset to the landing pad (0 if no landing pad).
    pub cs_lp: u32,
    /// Action record index (0 if no action).
    pub cs_action: u32,
}

/// A type info entry in the LSDA type info table.
#[derive(Debug, Clone)]
pub struct X86GCEHTypeInfoEntry {
    /// Type info reference encoding.
    pub encoding: u8,
    /// Pointer/reference to the type info descriptor.
    pub type_info_ptr: u64,
    /// Mangled type name.
    pub type_name: String,
}

/// An action record in the LSDA action table.
#[derive(Debug, Clone)]
pub struct X86GCEHActionRecord {
    /// Type info table index for this action.
    pub type_filter: i32,
    /// Offset to the next action record (0 if last).
    pub next_action_offset: i32,
}

// ============================================================================
// SEH Types
// ============================================================================

/// Windows SEH unwind info (UNWIND_INFO).
#[derive(Debug, Clone)]
pub struct X86GCEHWinUnwindInfo {
    /// Version (1).
    pub version: u8,
    /// Flags: UNW_FLAG_NHANDLER, UNW_FLAG_EHANDLER, etc.
    pub flags: u8,
    /// Size of the function prologue in bytes.
    pub prologue_size: u8,
    /// Number of unwind code slots.
    pub count_of_codes: u8,
    /// Frame register (0 if none).
    pub frame_register: u8,
    /// Frame register offset.
    pub frame_offset: u8,
    /// Unwind codes.
    pub unwind_codes: Vec<X86GCEHUnwindCode>,
    /// Language-specific handler (personality) RVA.
    pub handler_rva: Option<u32>,
    /// Language-specific data RVA.
    pub handler_data_rva: Option<u32>,
}

/// A single unwind code in x64 UNWIND_INFO.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct X86GCEHUnwindCode {
    /// Code offset (prologue offset divided by instruction width).
    pub code_offset: u8,
    /// Unwind operation code.
    pub unwind_op: X86GCEHUnwindOp,
    /// Operation info (register number or scaled size).
    pub op_info: u8,
}

/// X86-64 unwind operation codes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum X86GCEHUnwindOp {
    PushNonVol = 0,
    AllocLarge = 1,
    AllocSmall = 2,
    SetFPReg = 3,
    SaveNonVol = 4,
    SaveNonVolFar = 5,
    SaveXmm128 = 8,
    SaveXmm128Far = 9,
    PushMachFrame = 10,
    Epilogue = 6,
    SpareCode = 7,
    SetMxcsr = 0x1E,
    RvaHandlers = 0x60,
}

impl X86GCEHUnwindOp {
    pub fn from_u8(v: u8) -> Option<Self> {
        match v {
            0 => Some(Self::PushNonVol),
            1 => Some(Self::AllocLarge),
            2 => Some(Self::AllocSmall),
            3 => Some(Self::SetFPReg),
            4 => Some(Self::SaveNonVol),
            5 => Some(Self::SaveNonVolFar),
            6 => Some(Self::Epilogue),
            7 => Some(Self::SpareCode),
            8 => Some(Self::SaveXmm128),
            9 => Some(Self::SaveXmm128Far),
            10 => Some(Self::PushMachFrame),
            0x1E => Some(Self::SetMxcsr),
            _ => None,
        }
    }
}

/// RUNTIME_FUNCTION entry for .pdata.
#[derive(Debug, Clone, Copy)]
pub struct X86GCEHRuntimeFunction {
    /// RVA of the function start.
    pub begin_address: u32,
    /// RVA of the function end.
    pub end_address: u32,
    /// RVA of the UNWIND_INFO structure.
    pub unwind_info: u32,
}

/// Function table entry for SEH filter functions.
#[derive(Debug, Clone)]
pub struct X86GCEHFilterFunction {
    /// The filter function name/symbol.
    pub name: String,
    /// Filter function address.
    pub address: u64,
    /// Return value meaning: EXCEPTION_EXECUTE_HANDLER, etc.
    pub filter_action: X86GCEHFilterAction,
}

/// Actions returned by SEH filter functions.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i32)]
pub enum X86GCEHFilterAction {
    /// Execute the exception handler.
    ExecuteHandler = 1,
    /// Continue searching for a handler.
    ContinueSearch = 0,
    /// Continue execution at the fault point.
    ContinueExecution = -1,
    /// Unhandled exception.
    ExceptionUnhandled = 0x80010007u32 as i32,
}

// ============================================================================
// DWARF EH Types
// ============================================================================

/// A DWARF Call Frame Information (CFI) entry.
#[derive(Debug, Clone)]
pub struct X86GCEHDwarfCIE {
    /// CIE length.
    pub length: u32,
    /// CIE ID (0 for CIE).
    pub cie_id: u32,
    /// Version (1, 3, or 4).
    pub version: u8,
    /// Augmentation string.
    pub augmentation: String,
    /// Code alignment factor.
    pub code_alignment_factor: u8,
    /// Data alignment factor (signed).
    pub data_alignment_factor: i8,
    /// Return address register (Dwarf).
    pub return_address_register: u8,
    /// Initial CFI instructions.
    pub initial_instructions: Vec<u8>,
    /// Address of the personality routine (for 'P' augmentation).
    pub personality_addr: Option<u64>,
    /// Personality encoding (for 'P' augmentation).
    pub personality_encoding: Option<u8>,
    /// LSDA pointer encoding (for 'L' augmentation).
    pub lsda_encoding: Option<u8>,
    /// FDE pointer encoding (for 'R' augmentation).
    pub fde_encoding: Option<u8>,
}

/// A DWARF Frame Description Entry (FDE).
#[derive(Debug, Clone)]
pub struct X86GCEHDwarfFDE {
    /// FDE length.
    pub length: u32,
    /// CIE pointer (offset back to CIE).
    pub cie_pointer: u32,
    /// Initial location (function start).
    pub initial_location: u64,
    /// Address range (function size).
    pub address_range: u64,
    /// CFI instructions for this frame.
    pub instructions: Vec<u8>,
    /// LSDA pointer (for augmentation 'L').
    pub lsda_pointer: Option<u64>,
}

/// LSDA (Language-Specific Data Area) header.
#[derive(Debug, Clone)]
pub struct X86GCEHLsda {
    /// Landing pad base — start of the landing pad area.
    pub landing_pad_base: u32,
    /// Type table (RTTI descriptors).
    pub type_table: Vec<u64>,
    /// Type table encoding.
    pub type_table_encoding: u8,
    /// Call site table entries.
    pub call_sites: Vec<X86GCEHCallSiteEntry>,
    /// Action records.
    pub actions: Vec<X86GCEHActionRecord>,
    /// Whether the LSDA uses the "GCC" exception table format.
    pub gcc_except_table: bool,
    /// Target of the TTBase label.
    pub tt_base: u32,
}

/// Augmentation string parser for DWARF CIE.
#[derive(Debug, Clone, Default)]
pub struct X86GCEHAugmentation {
    /// 'z' — has augmentation length field.
    pub has_aug_length: bool,
    /// 'L' — has LSDA pointer encoding.
    pub has_lsda: bool,
    /// 'P' — has personality pointer.
    pub has_personality: bool,
    /// 'R' — has FDE pointer encoding byte.
    pub has_fde_encoding: bool,
    /// 'S' — this CIE represents a signal frame.
    pub is_signal_frame: bool,
    /// 'B' — BFD CIE (GNU).
    pub is_bfd_cie: bool,
    /// 'G' — has GNU extension.
    pub is_gnu: bool,
}

impl X86GCEHAugmentation {
    pub fn parse(aug: &str) -> Self {
        let mut result = Self::default();
        for ch in aug.chars() {
            match ch {
                'z' => result.has_aug_length = true,
                'L' => result.has_lsda = true,
                'P' => result.has_personality = true,
                'R' => result.has_fde_encoding = true,
                'S' => result.is_signal_frame = true,
                'B' => result.is_bfd_cie = true,
                'G' => result.is_gnu = true,
                _ => {}
            }
        }
        result
    }

    pub fn to_string(&self) -> String {
        let mut s = String::new();
        if self.has_aug_length {
            s.push('z');
        }
        if self.has_lsda {
            s.push('L');
        }
        if self.has_personality {
            s.push('P');
        }
        if self.has_fde_encoding {
            s.push('R');
        }
        if self.is_signal_frame {
            s.push('S');
        }
        if self.is_bfd_cie {
            s.push('B');
        }
        if self.is_gnu {
            s.push('G');
        }
        s
    }
}

// ============================================================================
// Exception Pointer Types
// ============================================================================

/// Exception pointer information returned by `__builtin_eh_return_data_regno`.
#[derive(Debug, Clone, Copy)]
pub struct X86GCEHExceptionPointerRegs {
    /// Register for the exception pointer (exception object address).
    pub exception_pointer_reg: u16,
    /// Register for the selector (type info or filter value).
    pub selector_reg: u16,
}

impl X86GCEHExceptionPointerRegs {
    /// Per Itanium C++ ABI, X86-64 uses RAX for exception pointer and
    /// RDX for the selector.
    pub fn for_x86_64() -> Self {
        Self {
            exception_pointer_reg: DW_RAX,
            selector_reg: DW_RDX,
        }
    }

    /// Per GCC convention, X86-32 uses EAX and EDX.
    pub fn for_x86_32() -> Self {
        Self {
            exception_pointer_reg: 0, // EAX in DWARF for 32-bit
            selector_reg: 1,          // EDX
        }
    }

    /// Returns `__builtin_eh_return_data_regno(0)` and `(1)` equivalents.
    pub fn eh_return_data_regno(index: u32) -> Option<u16> {
        match index {
            0 => Some(DW_RAX),
            1 => Some(DW_RDX),
            _ => None,
        }
    }
}

// ============================================================================
// GC Strategy Interface Implementation
// ============================================================================

impl X86GCEHFull {
    /// Set the GC strategy for lowering.
    pub fn set_gc_strategy(&mut self, strategy: X86GCEHStrategy) {
        self.gc_strategy = strategy;
        self.enable_statepoints = strategy.uses_statepoints();
        self.enable_stack_maps = strategy.needs_stack_maps();
    }

    /// Configure the GC strategy from a function attribute string
    /// (e.g., `"statepoint-example"`, `"coreclr"`, `"ocaml"`).
    pub fn set_gc_strategy_from_attr(&mut self, attr: &str) {
        let strategy = match attr {
            "statepoint-example" => X86GCEHStrategy::Statepoint,
            "coreclr" => X86GCEHStrategy::CoreCLR,
            "ocaml" => X86GCEHStrategy::OCaml,
            "erlang" => X86GCEHStrategy::Erlang,
            "shadow-stack" => X86GCEHStrategy::ShadowStack,
            _ => X86GCEHStrategy::None,
        };
        self.set_gc_strategy(strategy);
    }

    /// Returns true if the current function needs GC support.
    pub fn needs_gc_support(&self) -> bool {
        self.uses_gc && self.gc_strategy != X86GCEHStrategy::None
    }

    /// Returns true if the current function needs EH support.
    pub fn needs_eh_support(&self) -> bool {
        self.uses_eh && self.personality != X86GCEHPersonality::None
    }
}

// ============================================================================
// gc.statepoint Lowering
// ============================================================================

impl X86GCEHFull {
    /// Lower a `gc.statepoint` intrinsic into machine instructions.
    ///
    /// The lowering generates:
    /// 1. A stack map record marking the statepoint location
    /// 2. A call instruction (if the statepoint wraps a call)
    /// 3. GC root reporting before the call
    /// 4. Post-call gc.relocate instructions for each relocated root
    ///
    /// See LLVM LangRef: `gc.statepoint` intrinsic.
    pub fn lower_gc_statepoint(
        &mut self,
        call_target: Option<&str>,
        num_call_args: u32,
        _call_args: &[X86GCEHRoot],
        transition: X86GCEHGCTransition,
        deopt_state: &[u8],
        flags: u32,
    ) -> X86GCEHStatepoint {
        let id = self.next_statepoint_id();
        let stack_map_id = self.next_stack_map_id();

        // Enumerate live GC roots at this program point.
        let roots = self.enumerate_live_roots();

        // Compute program counter offset.
        let pc_offset = self.compute_current_pc_offset();

        let statepoint = X86GCEHStatepoint {
            id,
            pc_offset,
            stack_map_id,
            call_target: call_target.map(String::from),
            num_call_args,
            flags,
            num_deopt_bytes: deopt_state.len() as u32,
            deopt_state: deopt_state.to_vec(),
            gc_transition: transition,
            num_roots: roots.len() as u32,
            roots: roots.clone(),
            stack_slots: self.stack_roots.clone(),
        };

        // Generate the stack map record for this statepoint.
        if self.enable_stack_maps {
            let record =
                self.build_stack_map_record(stack_map_id, pc_offset, &roots, &self.stack_roots);
            self.stack_maps.push(record);
        }

        // If this is a relocation statepoint, we'll emit gc.relocate
        // instructions for each root in a subsequent pass.
        if transition == X86GCEHGCTransition::Relocation {
            // Roots will be relocated post-call.
            for root in &roots {
                // The relocation will map the old value to the new one.
                let _loc = &root.location;
            }
        }

        let safepoint_id = self.next_safepoint_id();
        self.safepoints.push(X86GCEHSafepoint {
            id: safepoint_id,
            kind: X86GCEHSafepointKind::PreCall,
            pc_offset,
            may_gc: transition != X86GCEHGCTransition::None,
            statepoint_id: Some(id),
            stack_map_id: Some(stack_map_id),
        });

        statepoint
    }

    /// Compute the current PC offset for statepoint placement.
    fn compute_current_pc_offset(&self) -> u64 {
        // In a real lowering, this would be tracked by the instruction
        // emitter. Here we estimate based on accumulated instructions.
        self.stack_maps.len() as u64 * 4
    }
}

// ============================================================================
// gc.result and gc.relocate Lowering
// ============================================================================

impl X86GCEHFull {
    /// Lower a `gc.result` intrinsic — extract the call result from a statepoint.
    ///
    /// `gc.result` extracts the return value of the call wrapped by a statepoint.
    /// In practice this is a register copy from the call's return register.
    pub fn lower_gc_result(&self, statepoint_id: u64, result_reg: u16) -> X86GCEHRoot {
        X86GCEHRoot {
            kind: X86GCEHRootKind::ObjectPointer,
            location: X86GCEHRootLocation::Register(result_reg),
            is_derived: false,
            derived_offset: 0,
            is_live: true,
            description: format!(
                "gc.result of statepoint {} in reg D{}",
                statepoint_id, result_reg
            ),
        }
    }

    /// Lower a `gc.relocate` intrinsic — map a root across a statepoint.
    ///
    /// `gc.relocate` takes a base pointer and a derived pointer (both may
    /// be the same for base pointers), and returns the relocated value
    /// after the statepoint. The GC may have moved the object, so the
    /// returned pointer must be computed from the stack map.
    pub fn lower_gc_relocate(
        &self,
        statepoint_id: u64,
        base_offset: u32,
        derived_offset: u32,
        original_value: u64,
        relocated_value: u64,
    ) -> X86GCEHRelocate {
        X86GCEHRelocate {
            statepoint_id,
            base_offset,
            derived_offset,
            original_value,
            relocated_value,
            target_reg: None,
            target_stack_offset: None,
        }
    }

    /// Generate the code sequence for all gc.relocate instructions after
    /// a statepoint. Each relocated root gets a live-out in the stack map
    /// and a register copy to its new location.
    pub fn emit_gc_relocates(
        &mut self,
        statepoint_id: u64,
        relocated_roots: &[(u16, u64)],
    ) -> Vec<X86GCEHRelocate> {
        let mut result = Vec::new();
        for (reg, new_value) in relocated_roots {
            let relocate = self.lower_gc_relocate(
                statepoint_id,
                *reg as u32, // base offset
                *reg as u32, // derived offset (same for base ptrs)
                *new_value,  // original value
                *new_value,  // relocated value (same since we own it)
            );
            result.push(relocate);
        }
        result
    }
}

// ============================================================================
// GC Root Enumeration
// ============================================================================

impl X86GCEHFull {
    /// Enumerate all live GC roots at the current program point.
    ///
    /// Scans:
    /// - Active register roots (from register allocation info)
    /// - Stack slot roots (from frame lowering)
    /// - Static/global roots
    ///
    /// Returns a list of live roots sorted by location.
    pub fn enumerate_live_roots(&self) -> Vec<X86GCEHRoot> {
        let mut roots: Vec<X86GCEHRoot> = Vec::new();

        // Add register roots.
        for (_reg, root) in &self.active_roots {
            if root.is_live {
                roots.push(root.clone());
            }
        }

        // Add stack-slot roots.
        for slot in &self.stack_roots {
            if slot.is_live {
                roots.push(X86GCEHRoot {
                    kind: if slot.is_derived {
                        X86GCEHRootKind::DerivedPointer
                    } else {
                        X86GCEHRootKind::StackAllocated
                    },
                    location: X86GCEHRootLocation::StackOffset(slot.offset),
                    is_derived: slot.is_derived,
                    derived_offset: 0,
                    is_live: true,
                    description: format!("stack slot {} at sp{:+}", slot.name, slot.offset),
                });
            }
        }

        // Sort by location for deterministic output.
        roots.sort_by_key(|r| r.description.clone());
        roots
    }

    /// Register a GC root in a register.
    pub fn register_root(
        &mut self,
        reg: u16,
        kind: X86GCEHRootKind,
        is_derived: bool,
        derived_offset: i64,
        desc: &str,
    ) {
        self.active_roots.insert(
            reg,
            X86GCEHRoot {
                kind,
                location: X86GCEHRootLocation::Register(reg),
                is_derived,
                derived_offset,
                is_live: true,
                description: desc.to_string(),
            },
        );
    }

    /// Register a GC root in a stack slot.
    pub fn register_stack_root(&mut self, offset: i32, size: u8, is_derived: bool, name: &str) {
        self.stack_roots.push(X86GCEHStackSlot {
            offset,
            size,
            is_derived,
            is_live: true,
            name: name.to_string(),
        });
    }

    /// Kill a register root (mark as no longer live).
    pub fn kill_root(&mut self, reg: u16) {
        if let Some(root) = self.active_roots.get_mut(&reg) {
            root.is_live = false;
        }
    }

    /// Kill a stack root at the given offset.
    pub fn kill_stack_root(&mut self, offset: i32) {
        for slot in &mut self.stack_roots {
            if slot.offset == offset {
                slot.is_live = false;
            }
        }
    }

    /// Identify all roots in the set of callee-saved registers that
    /// hold live pointers across calls.
    pub fn enumerate_callee_saved_roots(&self) -> Vec<X86GCEHRoot> {
        let mut result = Vec::new();
        for reg in CALLEE_SAVED_GPRS {
            if let Some(root) = self.active_roots.get(reg) {
                if root.is_live {
                    result.push(root.clone());
                }
            }
        }
        result
    }

    /// Identify all roots in caller-saved registers.
    pub fn enumerate_caller_saved_roots(&self) -> Vec<X86GCEHRoot> {
        let mut result = Vec::new();
        for reg in CALLER_SAVED_GPRS {
            if let Some(root) = self.active_roots.get(reg) {
                if root.is_live {
                    result.push(root.clone());
                }
            }
        }
        result
    }
}

// ============================================================================
// Stack Map Generation
// ============================================================================

impl X86GCEHFull {
    /// Build a single stack map record from a set of live roots.
    pub fn build_stack_map_record(
        &self,
        id: u64,
        instruction_offset: u64,
        register_roots: &[X86GCEHRoot],
        stack_roots: &[X86GCEHStackSlot],
    ) -> X86GCEHStackMapRecord {
        let mut locations = Vec::new();
        let mut live_outs = Vec::new();

        // Map register roots to stack map locations.
        for root in register_roots {
            match &root.location {
                X86GCEHRootLocation::Register(reg) => {
                    locations.push(X86GCEHStackMapLocation {
                        dwarf_reg: *reg,
                        reserved: 0,
                        offset: root.derived_offset as i32,
                        kind: X86GCEHStackMapLocationKind::Register,
                        size: self.pointer_size,
                    });
                    // All register roots are also live-outs.
                    live_outs.push(X86GCEHLiveOut {
                        dwarf_reg: *reg,
                        reserved: 0,
                        size: self.pointer_size,
                    });
                }
                X86GCEHRootLocation::StackOffset(off) => {
                    locations.push(X86GCEHStackMapLocation {
                        dwarf_reg: self.frame_pointer_reg,
                        reserved: 0,
                        offset: *off,
                        kind: X86GCEHStackMapLocationKind::Indirect,
                        size: self.pointer_size,
                    });
                }
                X86GCEHRootLocation::FixedAddress(addr) => {
                    locations.push(X86GCEHStackMapLocation {
                        dwarf_reg: 0,
                        reserved: 0,
                        offset: *addr as i32,
                        kind: X86GCEHStackMapLocationKind::Constant,
                        size: self.pointer_size,
                    });
                }
                _ => {}
            }
        }

        // Map stack slot roots.
        for slot in stack_roots {
            locations.push(X86GCEHStackMapLocation {
                dwarf_reg: self.frame_pointer_reg,
                reserved: 0,
                offset: slot.offset,
                kind: X86GCEHStackMapLocationKind::Indirect,
                size: slot.size,
            });
        }

        X86GCEHStackMapRecord {
            id,
            function_address: 0, // Relocated at link time.
            instruction_offset,
            num_locations: locations.len() as u16,
            locations,
            num_live_outs: live_outs.len() as u16,
            live_outs,
            padding: 0,
        }
    }

    /// Emit the complete function stack map into the stack map section buffer.
    ///
    /// Format per LLVM Stack Map specification v3:
    /// ```text
    /// Header {
    ///   u8  version (3)
    ///   u8  reserved
    ///   u16 reserved
    /// }
    /// StkSizeRecord[num_functions] {
    ///   u64 function_address
    ///   u64 stack_size
    ///   u64 record_count
    /// }
    /// StkMapRecord[total_records] {
    ///   u64 patchpoint_id
    ///   u32 instruction_offset
    ///   u16 reserved
    ///   u16 num_locations
    ///   Location[num_locations]
    ///   u16 padding (if needed)
    ///   u16 num_live_outs
    ///   LiveOut[num_live_outs]
    ///   u32 padding (if needed)
    /// }
    /// ```
    pub fn emit_function_stack_map(&mut self) {
        let function_addr: u64 = 0; // Placeholder; linker fixes up.

        // StkSizeRecord: function address (8), stack size (8), record count (8)
        let stack_size: u64 = self.compute_current_stack_size();
        let record_count: u64 = self
            .stack_maps
            .iter()
            .filter(|r| r.function_address == 0)
            .count() as u64;

        // Append StkSizeRecord to buffer.
        Self::append_u64_to_buffer(&mut self.stack_map_buffer, function_addr);
        Self::append_u64_to_buffer(&mut self.stack_map_buffer, stack_size);
        Self::append_u64_to_buffer(&mut self.stack_map_buffer, record_count);

        // Emit each record.
        let mut pending = Vec::new();
        std::mem::swap(&mut pending, &mut self.stack_maps);

        for record in &pending {
            if record.id == 0 {
                // Skip placeholder.
                continue;
            }
            self.emit_single_stack_map_record(record);
        }

        // Preserve for subsequent functions.
        self.stack_maps = pending;
    }

    /// Emit a single stack map record into the buffer.
    fn emit_single_stack_map_record(&mut self, record: &X86GCEHStackMapRecord) {
        Self::append_u64_to_buffer(&mut self.stack_map_buffer, record.id);
        Self::append_u32_to_buffer(&mut self.stack_map_buffer, record.instruction_offset as u32);

        // reserved u16
        Self::append_u16_to_buffer(&mut self.stack_map_buffer, 0);

        let num_locations = record.locations.len() as u16;
        Self::append_u16_to_buffer(&mut self.stack_map_buffer, num_locations);

        // Locations.
        for loc in &record.locations {
            // Location kind (u8).
            Self::append_u8_to_buffer(&mut self.stack_map_buffer, loc.kind as u8);
            // Reserved (u8).
            Self::append_u8_to_buffer(&mut self.stack_map_buffer, 0);
            // Size (u16).
            Self::append_u16_to_buffer(&mut self.stack_map_buffer, loc.size as u16);
            // Dwarf reg (u16).
            Self::append_u16_to_buffer(&mut self.stack_map_buffer, loc.dwarf_reg);
            // Reserved (u16).
            Self::append_u16_to_buffer(&mut self.stack_map_buffer, 0);
            // Offset (i32).
            Self::append_i32_to_buffer(&mut self.stack_map_buffer, loc.offset);
        }

        // Padding to align live-outs to 4-byte boundary.
        if num_locations % 2 == 1 {
            Self::append_u16_to_buffer(&mut self.stack_map_buffer, 0);
        }

        // Live outs.
        let num_live_outs = record.live_outs.len() as u16;
        Self::append_u16_to_buffer(&mut self.stack_map_buffer, num_live_outs);

        for lo in &record.live_outs {
            Self::append_u16_to_buffer(&mut self.stack_map_buffer, lo.dwarf_reg);
            Self::append_u8_to_buffer(&mut self.stack_map_buffer, lo.reserved);
            Self::append_u8_to_buffer(&mut self.stack_map_buffer, lo.size);
        }

        // Final padding to 8-byte alignment.
        let current_len = (self.stack_map_buffer.len() as u32) % 8;
        if current_len != 0 {
            for _ in 0..(8 - current_len) {
                Self::append_u8_to_buffer(&mut self.stack_map_buffer, 0);
            }
        }
    }

    /// Compute the current stack size for the function.
    fn compute_current_stack_size(&self) -> u64 {
        let mut size = 0u64;
        for slot in &self.stack_roots {
            let end = (slot.offset as i64 + slot.size as i64) as u64;
            if end > size {
                size = end;
            }
        }
        // Align to 16 bytes.
        (size + 15) & !15
    }

    /// Serialize all accumulated stack maps into the final section content.
    pub fn finalize_stack_map_section(&self) -> Vec<u8> {
        let mut buf = Vec::new();
        // Header: version (1), reserved (1), reserved (2).
        buf.push(GC_EH_STACK_MAP_VERSION);
        buf.push(0);
        buf.extend_from_slice(&[0u8, 0u8]);
        // All function records.
        buf.extend_from_slice(&self.stack_map_buffer);
        buf
    }
}

// ============================================================================
// Buffer Append Helpers
// ============================================================================

impl X86GCEHFull {
    fn append_u8_to_buffer(buf: &mut Vec<u8>, val: u8) {
        buf.push(val);
    }

    fn append_u16_to_buffer(buf: &mut Vec<u8>, val: u16) {
        buf.extend_from_slice(&val.to_le_bytes());
    }

    fn append_u32_to_buffer(buf: &mut Vec<u8>, val: u32) {
        buf.extend_from_slice(&val.to_le_bytes());
    }

    fn append_i32_to_buffer(buf: &mut Vec<u8>, val: i32) {
        buf.extend_from_slice(&val.to_le_bytes());
    }

    fn append_u64_to_buffer(buf: &mut Vec<u8>, val: u64) {
        buf.extend_from_slice(&val.to_le_bytes());
    }
}

// ============================================================================
// Safepoint Insertion
// ============================================================================

impl X86GCEHFull {
    /// Insert a safepoint at a loop backedge.
    pub fn insert_loop_backedge_safepoint(&mut self, pc_offset: u64) -> Option<X86GCEHSafepoint> {
        if !self.safepoints_at_backedges {
            return None;
        }
        let id = self.next_safepoint_id();
        let sp = X86GCEHSafepoint {
            id,
            kind: X86GCEHSafepointKind::LoopBackedge,
            pc_offset,
            may_gc: true,
            statepoint_id: None,
            stack_map_id: None,
        };
        self.safepoints.push(sp.clone());
        Some(sp)
    }

    /// Insert a safepoint before a function call.
    pub fn insert_pre_call_safepoint(&mut self, pc_offset: u64) -> Option<X86GCEHSafepoint> {
        if !self.safepoints_at_calls {
            return None;
        }
        let id = self.next_safepoint_id();
        let sp = X86GCEHSafepoint {
            id,
            kind: X86GCEHSafepointKind::PreCall,
            pc_offset,
            may_gc: true,
            statepoint_id: None,
            stack_map_id: None,
        };
        self.safepoints.push(sp.clone());
        Some(sp)
    }

    /// Insert a cooperative polling safepoint.
    ///
    /// On X86-64, this emits a load from the polling page:
    /// ```asm
    /// mov rax, [rip + GC_EH_POLLING_PAGE]
    /// ```
    /// When the GC arms the page, the load faults and the signal handler
    /// pauses the thread.
    pub fn insert_polling_safepoint(&mut self, pc_offset: u64) -> Option<X86GCEHSafepoint> {
        if !self.cooperative_polling {
            return None;
        }
        let id = self.next_safepoint_id();
        let sp = X86GCEHSafepoint {
            id,
            kind: X86GCEHSafepointKind::Poll,
            pc_offset,
            may_gc: true,
            statepoint_id: None,
            stack_map_id: None,
        };
        self.safepoints.push(sp.clone());
        Some(sp)
    }

    /// Insert safepoint at function entry.
    pub fn insert_entry_safepoint(&mut self, pc_offset: u64) {
        let id = self.next_safepoint_id();
        self.safepoints.push(X86GCEHSafepoint {
            id,
            kind: X86GCEHSafepointKind::FunctionEntry,
            pc_offset,
            may_gc: false,
            statepoint_id: None,
            stack_map_id: None,
        });
    }

    /// Determine which safepoints to insert given the current strategy.
    pub fn compute_safepoint_placement(&mut self) -> Vec<u64> {
        let mut offsets = Vec::new();

        match self.gc_strategy {
            X86GCEHStrategy::Statepoint => {
                // Statepoint-based GC inserts safepoints at every call and
                // at each loop backedge.
                if self.safepoints_at_calls {
                    // Will be populated by the IR rewriting pass.
                }
                if self.safepoints_at_backedges {
                    // Backedge safepoints are inserted by the loop analysis.
                }
            }
            X86GCEHStrategy::CoreCLR => {
                // CoreCLR: fully interruptible everywhere or at specific points.
                // Polling at method entry, calls, and loop backedges.
            }
            X86GCEHStrategy::Erlang => {
                // Erlang checks reductions at function entries and loop heads.
            }
            X86GCEHStrategy::OCaml => {
                // OCaml inserts `caml_call_gc` at allocation points.
            }
            _ => {}
        }

        // Collect all already-placed safepoint offsets.
        for sp in &self.safepoints {
            offsets.push(sp.pc_offset);
        }

        offsets.sort();
        offsets.dedup();
        offsets
    }
}

// ============================================================================
// RewriteStatepointsForGC
// ============================================================================

impl X86GCEHFull {
    /// Rewrite the IR to insert explicit statepoints for all GC-managed calls.
    ///
    /// This implements the RewriteStatepointsForGC pass logic:
    /// 1. Identify all call sites that need safepoints (calls to non-GC-
    ///    leaf functions).
    /// 2. For each such call, wrap the call in a `gc.statepoint`.
    /// 3. Insert `gc.relocate` for every live GC pointer across the call.
    /// 4. Replace uses of original pointers with relocated pointers.
    pub fn rewrite_statepoints_for_gc(
        &mut self,
        call_sites: &[(u64, Option<String>, u32)],
        live_roots: &[X86GCEHRoot],
    ) -> Vec<X86GCEHStatepoint> {
        let mut statepoints = Vec::new();

        for (_pc_offset, call_target, num_args) in call_sites {
            let statepoint = self.lower_gc_statepoint(
                call_target.as_deref(),
                *num_args,
                live_roots,
                X86GCEHGCTransition::Relocation,
                &[],
                0,
            );
            statepoints.push(statepoint);
        }

        // Now emit gc.relocate instructions for each live root at each
        // statepoint. In practice, each root that was live across the
        // statepoint gets a relocation pair.
        for sp in &statepoints {
            for root in live_roots {
                if let X86GCEHRootLocation::Register(reg) = root.location {
                    let _ = self.lower_gc_relocate(sp.id, reg as u32, reg as u32, 0, 0);
                }
            }
        }

        statepoints
    }

    /// Determine whether a call needs a statepoint.
    ///
    /// A call needs a statepoint if:
    /// - The function uses GC
    /// - The call is not to a known GC-leaf function
    /// - The call may trigger GC (allocation, runtime call, etc.)
    pub fn call_needs_statepoint(&self, call_target: &str, is_leaf: bool) -> bool {
        if !self.uses_gc {
            return false;
        }
        // Known leaf functions that never trigger GC.
        let gc_leaves: &[&str] = &[
            "memcpy",
            "memmove",
            "memset",
            "bzero",
            "llvm.memcpy",
            "llvm.memmove",
            "llvm.memset",
            "llvm.sqrt",
            "llvm.sin",
            "llvm.cos",
            "llvm.x86.sse",
            "llvm.x86.sse2",
        ];
        if is_leaf || gc_leaves.contains(&call_target) {
            return false;
        }
        true
    }

    /// Replace all uses of a pointer with its relocated version after a statepoint.
    ///
    /// This creates the def-use chain: original -> statepoint -> gc.relocate -> uses.
    pub fn replace_with_relocated(
        &mut self,
        original_reg: u16,
        statepoint_id: u64,
    ) -> X86GCEHRelocate {
        self.lower_gc_relocate(
            statepoint_id,
            original_reg as u32,
            original_reg as u32,
            0, // original value
            0, // relocated value (placeholder)
        )
    }
}

// ============================================================================
// Itanium C++ ABI: Landing Pad, Resume, CleanupRet, CatchRet, CatchSwitch,
// CatchPad, CleanupPad
// ============================================================================

impl X86GCEHFull {
    /// Lower a `landingpad` instruction.
    ///
    /// The landingpad is the entry point for exception handling in a function.
    /// It receives the exception pointer and selector from the personality
    /// routine, then dispatches to catch blocks.
    ///
    /// LLVM IR:
    /// ```llvm
    /// %lp = landingpad { i8*, i32 }
    ///   catch i8* @typeid1
    ///   catch i8* @typeid2
    ///   filter [1 x i8*] [@typeid3]
    ///   cleanup
    /// ```
    pub fn lower_landingpad(
        &mut self,
        clauses: Vec<X86GCEHClause>,
        is_cleanup: bool,
    ) -> X86GCEHLandingPad {
        let id = self.next_landingpad_id();
        let exc_regs = X86GCEHExceptionPointerRegs::for_x86_64();

        self.landing_pads.push(X86GCEHLandingPad {
            id,
            kind: X86GCEHLandingPadKind::LandingPad,
            exc_ptr_reg: exc_regs.exception_pointer_reg,
            filter_ptr_reg: exc_regs.selector_reg,
            clauses: clauses.clone(),
            is_cleanup,
            is_unreachable: false,
            is_outlined: false,
            call_site_entries: Vec::new(),
            merged_from: Vec::new(),
        });

        // Build call-site entries for each clause.
        for clause in &clauses {
            let call_site = X86GCEHCallSiteEntry {
                cs_start: 0,
                cs_length: 0,
                cs_lp: id as u32,
                cs_action: self.compute_action_index(clause),
            };
            self.call_site_table.push(call_site);
        }

        self.landing_pads.last().cloned().unwrap()
    }

    /// Compute the action record index for a clause.
    fn compute_action_index(&mut self, clause: &X86GCEHClause) -> u32 {
        match clause.kind {
            X86GCEHClauseKind::Catch | X86GCEHClauseKind::CatchAll => {
                let type_index = if let Some(ref _ti) = clause.type_info {
                    self.type_info_table.len() as i32
                } else {
                    -1 // catch-all
                };
                let action = X86GCEHActionRecord {
                    type_filter: if clause.is_catch_all {
                        0
                    } else {
                        type_index + 1
                    },
                    next_action_offset: 0,
                };
                self.action_records.push(action);
                self.action_records.len() as u32
            }
            X86GCEHClauseKind::Filter => {
                let action = X86GCEHActionRecord {
                    type_filter: 0,
                    next_action_offset: 0,
                };
                self.action_records.push(action);
                self.action_records.len() as u32
            }
            X86GCEHClauseKind::Cleanup => {
                // Cleanup has no action record.
                0
            }
        }
    }

    /// Lower a `resume` instruction.
    ///
    /// The `resume` instruction re-throws or continues unwinding after a
    /// landing pad did not handle the exception. It takes the landing pad
    /// result and passes it back to the unwinder.
    ///
    /// ```llvm
    /// resume { i8*, i32 } %lp_val
    /// ```
    pub fn lower_resume(&mut self, _landing_pad_id: u64) -> X86GCEHLandingPad {
        let id = self.next_landingpad_id();
        let pad = X86GCEHLandingPad {
            id,
            kind: X86GCEHLandingPadKind::Resume,
            exc_ptr_reg: DW_RAX,
            filter_ptr_reg: DW_RDX,
            clauses: Vec::new(),
            is_cleanup: false,
            is_unreachable: false,
            is_outlined: false,
            call_site_entries: Vec::new(),
            merged_from: Vec::new(),
        };
        self.landing_pads.push(pad.clone());
        pad
    }

    /// Lower a `cleanupret` instruction.
    ///
    /// CleanupRet returns from a cleanup pad to the caller.
    /// ```llvm
    /// cleanupret from %cleanuppad unwind to caller
    /// ```
    /// Or:
    /// ```llvm
    /// cleanupret from %cleanuppad unwind label %next_dest
    /// ```
    pub fn lower_cleanupret(
        &mut self,
        _from_pad_id: u64,
        _unwind_target: Option<u64>,
    ) -> X86GCEHLandingPad {
        let id = self.next_landingpad_id();
        let pad = X86GCEHLandingPad {
            id,
            kind: X86GCEHLandingPadKind::CleanupRet,
            exc_ptr_reg: 0,
            filter_ptr_reg: 0,
            clauses: Vec::new(),
            is_cleanup: true,
            is_unreachable: false,
            is_outlined: false,
            call_site_entries: Vec::new(),
            merged_from: Vec::new(),
        };
        self.landing_pads.push(pad.clone());
        pad
    }

    /// Lower a `catchret` instruction.
    ///
    /// CatchRet returns from a catch handler to the normal continuation.
    /// ```llvm
    /// catchret from %catchpad to label %continue
    /// ```
    pub fn lower_catchret(&mut self, _from_pad_id: u64, _target_label: &str) -> X86GCEHLandingPad {
        let id = self.next_landingpad_id();
        let pad = X86GCEHLandingPad {
            id,
            kind: X86GCEHLandingPadKind::CatchRet,
            exc_ptr_reg: 0,
            filter_ptr_reg: 0,
            clauses: Vec::new(),
            is_cleanup: false,
            is_unreachable: false,
            is_outlined: false,
            call_site_entries: Vec::new(),
            merged_from: Vec::new(),
        };
        self.landing_pads.push(pad.clone());
        pad
    }

    /// Lower a `catchswitch` instruction.
    ///
    /// CatchSwitch dispatches to one of several catch handlers based on
    /// the exception type.
    /// ```llvm
    /// %cs = catchswitch within none [label %catch1, label %catch2] unwind to caller
    /// ```
    pub fn lower_catchswitch(
        &mut self,
        _targets: &[u64],
        _unwind_target: Option<u64>,
    ) -> X86GCEHLandingPad {
        let id = self.next_landingpad_id();
        let pad = X86GCEHLandingPad {
            id,
            kind: X86GCEHLandingPadKind::CatchSwitch,
            exc_ptr_reg: 0,
            filter_ptr_reg: 0,
            clauses: Vec::new(),
            is_cleanup: false,
            is_unreachable: false,
            is_outlined: false,
            call_site_entries: Vec::new(),
            merged_from: Vec::new(),
        };
        self.landing_pads.push(pad.clone());
        pad
    }

    /// Lower a `catchpad` instruction.
    ///
    /// CatchPad is the entry point into a catch handler (Windows EH).
    /// ```llvm
    /// catchpad within %cs [i8* @typeid]
    /// ```
    pub fn lower_catchpad(
        &mut self,
        _parent_switch_id: u64,
        type_info: Option<X86GCEHTypeInfoEntry>,
    ) -> X86GCEHLandingPad {
        let id = self.next_landingpad_id();
        let pad = X86GCEHLandingPad {
            id,
            kind: X86GCEHLandingPadKind::CatchPad,
            exc_ptr_reg: 0,
            filter_ptr_reg: 0,
            clauses: vec![X86GCEHClause {
                kind: X86GCEHClauseKind::Catch,
                type_info,
                filter_fn: None,
                handler: None,
                is_catch_all: false,
            }],
            is_cleanup: false,
            is_unreachable: false,
            is_outlined: false,
            call_site_entries: Vec::new(),
            merged_from: Vec::new(),
        };
        self.landing_pads.push(pad.clone());
        pad
    }

    /// Lower a `cleanuppad` instruction.
    ///
    /// CleanupPad is the entry point into a cleanup handler (Windows EH).
    /// ```llvm
    /// cleanuppad within none []
    /// ```
    pub fn lower_cleanuppad(&mut self) -> X86GCEHLandingPad {
        let id = self.next_landingpad_id();
        let pad = X86GCEHLandingPad {
            id,
            kind: X86GCEHLandingPadKind::CleanupPad,
            exc_ptr_reg: 0,
            filter_ptr_reg: 0,
            clauses: Vec::new(),
            is_cleanup: true,
            is_unreachable: false,
            is_outlined: false,
            call_site_entries: Vec::new(),
            merged_from: Vec::new(),
        };
        self.landing_pads.push(pad.clone());
        pad
    }
}

// ============================================================================
// SEH: __C_specific_handler, __CxxFrameHandler3, Filter Functions
// ============================================================================

impl X86GCEHFull {
    /// Configure for MSVC C exception handling using __C_specific_handler.
    ///
    /// This personality handles basic C structured exceptions (__try/__except).
    pub fn configure_c_specific_handler(&mut self) {
        self.personality = X86GCEHPersonality::CSpecificHandler;
        self.emit_seh = true;
        self.emit_dwarf_eh = false;
        self.personality_refs
            .insert("__C_specific_handler".to_string());
    }

    /// Configure for MSVC C++ exception handling using __CxxFrameHandler3.
    ///
    /// This personality handles C++ exceptions with SEH:
    /// - __try/__except (C SEH)
    /// - __try/__finally (C SEH cleanup)
    /// - try/catch (C++ EH)
    /// - try/__finally (C++ SEH cleanup)
    pub fn configure_cxx_frame_handler3(&mut self) {
        self.personality = X86GCEHPersonality::CxxFrameHandler3;
        self.emit_seh = true;
        self.emit_dwarf_eh = true;
        self.personality_refs
            .insert("__CxxFrameHandler3".to_string());
    }

    /// Lower an SEH filter function.
    ///
    /// Filter functions are called by __C_specific_handler to determine
    /// whether to execute the exception handler. They receive
    /// EXCEPTION_POINTERS and return a filter action.
    pub fn lower_seh_filter(
        &mut self,
        name: &str,
        address: u64,
        action: X86GCEHFilterAction,
    ) -> X86GCEHFilterFunction {
        X86GCEHFilterFunction {
            name: name.to_string(),
            address,
            filter_action: action,
        }
    }

    /// Add an SEH handler scope (__try block).
    ///
    /// Each __try block is represented by a scope with a filter function
    /// and a handler entry point.
    pub fn add_seh_scope(
        &mut self,
        try_start: u32,
        try_end: u32,
        filter_fn: Option<&str>,
        handler_rva: u32,
    ) {
        // In the LSDA for SEH, each scope is encoded in the scope table.
        // For X86-64, the scope table entries have the format:
        // struct _SCOPE_TABLE_AMD64 {
        //   u32 Count;
        //   struct {
        //     u32 BeginAddress;
        //     u32 EndAddress;
        //     u32 HandlerAddress;
        //     u32 JumpTarget;
        //   } ScopeRecord[Count];
        // }
        let call_site = X86GCEHCallSiteEntry {
            cs_start: try_start,
            cs_length: try_end - try_start,
            cs_lp: handler_rva,
            cs_action: if filter_fn.is_some() { 1 } else { 0 },
        };
        self.call_site_table.push(call_site);

        if let Some(filter_name) = filter_fn {
            self.personality_refs.insert(filter_name.to_string());
        }
    }

    /// Emit the _SCOPE_TABLE_AMD64 for the current function.
    pub fn emit_seh_scope_table(&self) -> Vec<u8> {
        let mut buf = Vec::new();
        // Count of scope records (u32).
        let count = self.call_site_table.len() as u32;
        buf.extend_from_slice(&count.to_le_bytes());

        for cs in &self.call_site_table {
            buf.extend_from_slice(&cs.cs_start.to_le_bytes());
            buf.extend_from_slice(&(cs.cs_start + cs.cs_length).to_le_bytes());
            buf.extend_from_slice(&cs.cs_lp.to_le_bytes());
            // JumpTarget (for finally, 0 for except).
            buf.extend_from_slice(&0u32.to_le_bytes());
        }
        buf
    }
}

// ============================================================================
// DWARF EH: .eh_frame, .gcc_except_table, LSDA Encoding
// ============================================================================

impl X86GCEHFull {
    /// Build a Common Information Entry (CIE) for .eh_frame.
    ///
    /// The CIE provides frame-unwinding parameters shared by all FDEs.
    pub fn build_dwarf_cie(&mut self) -> X86GCEHDwarfCIE {
        let aug = X86GCEHAugmentation {
            has_aug_length: true,
            has_lsda: true,
            has_personality: true,
            has_fde_encoding: true,
            is_signal_frame: false,
            is_bfd_cie: false,
            is_gnu: false,
        };

        X86GCEHDwarfCIE {
            length: 0, // Computed later.
            cie_id: 0,
            version: 3, // DWARF 3 for .eh_frame
            augmentation: aug.to_string(),
            code_alignment_factor: 1,
            data_alignment_factor: -8, // -8 for X86-64 (stack grows down, 8 bytes)
            return_address_register: DW_RIP as u8,
            initial_instructions: self.build_cie_initial_instructions(),
            personality_addr: None,
            personality_encoding: Some(0x9B), // DW_EH_PE_udata4 | DW_EH_PE_indirect | DW_EH_PE_pcrel
            lsda_encoding: Some(0xFF),        // DW_EH_PE_omit (GCC style)
            fde_encoding: Some(0x1B),         // DW_EH_PE_pcrel | DW_EH_PE_sdata4
        }
    }

    /// Build initial CIE instructions (CFA setup).
    fn build_cie_initial_instructions(&self) -> Vec<u8> {
        let mut insns = Vec::new();
        // DW_CFA_def_cfa: r7 (RSP) offset 8
        // (On entry, CFA = RSP + 8, because return address was pushed)
        insns.push(0x0C); // DW_CFA_def_cfa
        insns.push(DW_RSP as u8);
        insns.push(8);
        // DW_CFA_offset: r16 (RIP) at CFA - 8
        insns.push(0x80 | DW_RIP as u8); // DW_CFA_offset + reg
        insns.push(1); // factored offset
        insns
    }

    /// Build a Frame Description Entry (FDE) for a function.
    pub fn build_dwarf_fde(
        &mut self,
        function_start: u64,
        function_size: u64,
        lsda_address: Option<u64>,
    ) -> X86GCEHDwarfFDE {
        let fde = X86GCEHDwarfFDE {
            length: 0, // Computed later.
            cie_pointer: 0,
            initial_location: function_start,
            address_range: function_size,
            instructions: self.build_fde_instructions(),
            lsda_pointer: lsda_address,
        };
        self.eh_frame_fdes
            .extend_from_slice(&X86GCEHFull::serialize_fde(&fde));
        fde
    }

    /// Build FDE CFI instructions for the current function.
    fn build_fde_instructions(&self) -> Vec<u8> {
        let mut insns = Vec::new();
        // If using frame pointer, emit DW_CFA_def_cfa_offset and
        // DW_CFA_offset for RBP.
        if self.frame_pointer_reg == DW_RBP {
            // push rbp: CFA = RSP + 16
            insns.push(0x0C); // DW_CFA_def_cfa
            insns.push(DW_RSP as u8);
            insns.push(16);
            // rbp saved at CFA - 16
            insns.push(0x80 | DW_RBP as u8); // DW_CFA_offset + reg
            insns.push(2); // factored offset of 2 * 8 = 16

            // If there are callee-saved regs saved, add them too.
            for (i, reg) in CALLEE_SAVED_GPRS.iter().enumerate() {
                if *reg != DW_RBP {
                    // Offset = (2 + i + 1) * 8 from CFA
                    insns.push(0x80 | *reg as u8);
                    insns.push((3 + i) as u8);
                }
            }
        }
        insns
    }

    /// Serialize a CIE to bytes.
    pub fn serialize_cie(cie: &X86GCEHDwarfCIE) -> Vec<u8> {
        let mut buf = Vec::new();
        // Length (placeholder, will be computed after).
        let length_offset = buf.len();
        buf.extend_from_slice(&[0u8; 4]);

        // CIE ID
        buf.extend_from_slice(&cie.cie_id.to_le_bytes());

        // Version
        buf.push(cie.version);

        // Augmentation string
        buf.extend_from_slice(cie.augmentation.as_bytes());
        buf.push(0); // NUL terminator

        // Code alignment factor (ULEB128)
        buf.extend_from_slice(&uleb128(cie.code_alignment_factor as u64));

        // Data alignment factor (SLEB128)
        buf.extend_from_slice(&sleb128(cie.data_alignment_factor as i64));

        // Return address register
        buf.push(cie.return_address_register);

        // Augmentation data (if 'z' augmentation)
        if cie.augmentation.contains('z') {
            // Personality encoding
            if let Some(pe) = cie.personality_encoding {
                buf.push(pe);
            }
            // LSDA encoding
            if let Some(le) = cie.lsda_encoding {
                buf.push(le);
            }
            // FDE encoding
            if let Some(fe) = cie.fde_encoding {
                buf.push(fe);
            }
        }

        // Initial instructions
        buf.extend_from_slice(&cie.initial_instructions);

        // Fix up length.
        let total_len = buf.len() - length_offset - 4;
        let len_bytes = (total_len as u32).to_le_bytes();
        buf[length_offset..length_offset + 4].copy_from_slice(&len_bytes);

        buf
    }

    /// Serialize an FDE to bytes.
    pub fn serialize_fde(fde: &X86GCEHDwarfFDE) -> Vec<u8> {
        let mut buf = Vec::new();
        let length_offset = buf.len();
        buf.extend_from_slice(&[0u8; 4]);

        // CIE pointer (offset back to CIE from this location)
        buf.extend_from_slice(&fde.cie_pointer.to_le_bytes());

        // Initial location (pcrel)
        buf.extend_from_slice(&fde.initial_location.to_le_bytes());

        // Address range
        buf.extend_from_slice(&fde.address_range.to_le_bytes());

        // Augmentation data (if CIE has 'z')
        // LSDA pointer if present.
        if let Some(lsda) = fde.lsda_pointer {
            buf.extend_from_slice(&lsda.to_le_bytes());
        }

        // CFI instructions
        buf.extend_from_slice(&fde.instructions);

        // Fix up length
        let total_len = buf.len() - length_offset - 4;
        let len_bytes = (total_len as u32).to_le_bytes();
        buf[length_offset..length_offset + 4].copy_from_slice(&len_bytes);

        buf
    }

    // ---- Emit .eh_frame for the current function ----

    /// Emit the .eh_frame CIE and FDE for the current function.
    pub fn emit_dwarf_eh_frame(&mut self) {
        let cie = self.build_dwarf_cie();
        self.eh_frame_cie = X86GCEHFull::serialize_cie(&cie);
    }

    // ---- LSDA encoding ----

    /// Build the LSDA (Language-Specific Data Area) for the current function.
    pub fn build_lsda(&mut self) -> X86GCEHLsda {
        X86GCEHLsda {
            landing_pad_base: 0,
            type_table: Vec::new(),
            type_table_encoding: 0xFF, // DW_EH_PE_omit
            call_sites: self.call_site_table.clone(),
            actions: self.action_records.clone(),
            gcc_except_table: true,
            tt_base: 0,
        }
    }

    /// Encode the LSDA into the binary format used by `.gcc_except_table`.
    ///
    /// Format (GCC-style):
    /// ```text
    /// u8  landing_pad_base_encoding  (DW_EH_PE_omit for abs)
    /// u8  landing_pad_base (uleb128) — omitted if encoding is omit
    /// u8  type_table_encoding
    /// u8  type_table_offset (uleb128) — from TTBase
    /// u8  call_site_encoding
    /// u32 call_site_table_length
    ///   call-site entry 1
    ///   ...
    /// ```
    pub fn encode_lsda(&mut self) -> Vec<u8> {
        let mut buf = Vec::new();

        // Landing pad base encoding (DW_EH_PE_udata4 or omit).
        buf.push(0xFF); // omit

        // Type table encoding.
        buf.push(0xFF); // omit (GCC uses TTBase-relative)

        // Call site encoding.
        buf.push(GC_EH_CALLSITE_ENCODING); // uleb128

        // Call site table length in bytes (placeholder).
        let cs_length_offset = buf.len();
        buf.extend_from_slice(&[0u8; 4]);

        // Encode call site entries.
        let cs_start = buf.len();
        for cs in &self.call_site_table {
            let start = uleb128(cs.cs_start as u64);
            let length = uleb128(cs.cs_length as u64);
            let lp = uleb128(cs.cs_lp as u64);
            let action = uleb128(cs.cs_action as u64);
            buf.extend_from_slice(&start);
            buf.extend_from_slice(&length);
            buf.extend_from_slice(&lp);
            buf.extend_from_slice(&action);
        }
        let cs_len = (buf.len() - cs_start) as u32;
        buf[cs_length_offset..cs_length_offset + 4].copy_from_slice(&cs_len.to_le_bytes());

        buf
    }
}

// ============================================================================
// Windows EH: .xdata, .pdata, UNWIND_INFO, RUNTIME_FUNCTION
// ============================================================================

impl X86GCEHFull {
    /// Build UNWIND_INFO for the current function.
    ///
    /// UNWIND_INFO describes the function prologue and which non-volatile
    /// registers are saved, so the unwinder can reverse the prologue.
    pub fn build_unwind_info(&mut self) -> X86GCEHWinUnwindInfo {
        X86GCEHWinUnwindInfo {
            version: 1,
            flags: if self.has_personality { 0x01 } else { 0x00 }, // UNW_FLAG_EHANDLER
            prologue_size: 0,                                      // Set by frame lowering.
            count_of_codes: self.unwind_codes.len() as u8,
            frame_register: if self.frame_pointer_reg != DW_RSP {
                self.frame_pointer_reg as u8
            } else {
                0
            },
            frame_offset: 0,
            unwind_codes: self.unwind_codes.clone(),
            handler_rva: if self.has_personality { Some(0) } else { None },
            handler_data_rva: if self.has_personality { Some(0) } else { None },
        }
    }

    /// Add a push-nonvolatile unwind code.
    pub fn add_unwind_push_nonvol(&mut self, reg: u8, offset: u8) {
        self.unwind_codes.push(X86GCEHUnwindCode {
            code_offset: offset,
            unwind_op: X86GCEHUnwindOp::PushNonVol,
            op_info: reg,
        });
    }

    /// Add a small stack allocation unwind code (alloc <= 128).
    pub fn add_unwind_alloc_small(&mut self, size: u8, offset: u8) {
        self.unwind_codes.push(X86GCEHUnwindCode {
            code_offset: offset,
            unwind_op: X86GCEHUnwindOp::AllocSmall,
            op_info: size / 8 - 1,
        });
    }

    /// Add a large stack allocation unwind code (alloc > 128).
    pub fn add_unwind_alloc_large(&mut self, size: u32, offset: u8) {
        if size <= 512 * 1024 - 8 {
            // Record size / 8 as u16.
            self.unwind_codes.push(X86GCEHUnwindCode {
                code_offset: offset,
                unwind_op: X86GCEHUnwindOp::AllocLarge,
                op_info: 0, // Uses u16.
            });
            let size_u16: u16 = (size / 8) as u16;
            // In practice, the u16 follows as the next code slot.
            self.unwind_codes.push(X86GCEHUnwindCode {
                code_offset: (size_u16 & 0xFF) as u8,
                unwind_op: X86GCEHUnwindOp::AllocLarge,
                op_info: (size_u16 >> 8) as u8,
            });
        } else {
            // 32-bit size.
            self.unwind_codes.push(X86GCEHUnwindCode {
                code_offset: offset,
                unwind_op: X86GCEHUnwindOp::AllocLarge,
                op_info: 1, // Uses u32.
            });
        }
    }

    /// Add a set-frame-pointer unwind code.
    pub fn add_unwind_set_fp(&mut self, offset: u8) {
        self.unwind_codes.push(X86GCEHUnwindCode {
            code_offset: offset,
            unwind_op: X86GCEHUnwindOp::SetFPReg,
            op_info: 0,
        });
    }

    /// Add a save-nonvolatile unwind code.
    pub fn add_unwind_save_nonvol(&mut self, reg: u8, stack_offset: u8, code_offset: u8) {
        self.unwind_codes.push(X86GCEHUnwindCode {
            code_offset,
            unwind_op: X86GCEHUnwindOp::SaveNonVol,
            op_info: (reg << 4) | ((stack_offset / 8) & 0xF),
        });
    }

    /// Serialize UNWIND_INFO into .xdata buffer.
    pub fn serialize_unwind_info(info: &X86GCEHWinUnwindInfo) -> Vec<u8> {
        let mut buf = Vec::new();
        // Flags: version (lower 3 bits) + flags (upper 5 bits).
        buf.push(info.version | (info.flags << 3));
        buf.push(info.prologue_size);
        buf.push(info.count_of_codes);
        buf.push(info.frame_register | (info.frame_offset << 4));

        // Unwind codes (aligned to u16 boundary, written in reverse order).
        let mut code_bytes = Vec::new();
        for code in &info.unwind_codes {
            code_bytes.push(code.code_offset);
            code_bytes.push((code.unwind_op as u8) << 4 | (code.op_info & 0x0F));
        }
        // Align to 4-byte boundary for u32 handler fields.
        while code_bytes.len() % 4 != 0 {
            code_bytes.push(0);
        }
        buf.extend_from_slice(&code_bytes);

        // Handler RVA (if present).
        if info.flags & 0x01 != 0 {
            buf.extend_from_slice(&info.handler_rva.unwrap_or(0).to_le_bytes());
            buf.extend_from_slice(&info.handler_data_rva.unwrap_or(0).to_le_bytes());
        }

        buf
    }

    /// Build a RUNTIME_FUNCTION entry for .pdata.
    pub fn build_runtime_function(
        begin_address: u32,
        end_address: u32,
        unwind_info_rva: u32,
    ) -> X86GCEHRuntimeFunction {
        X86GCEHRuntimeFunction {
            begin_address,
            end_address,
            unwind_info: unwind_info_rva,
        }
    }

    /// Serialize a RUNTIME_FUNCTION entry.
    pub fn serialize_runtime_function(rf: &X86GCEHRuntimeFunction) -> [u8; 12] {
        let mut buf = [0u8; 12];
        buf[0..4].copy_from_slice(&rf.begin_address.to_le_bytes());
        buf[4..8].copy_from_slice(&rf.end_address.to_le_bytes());
        buf[8..12].copy_from_slice(&rf.unwind_info.to_le_bytes());
        buf
    }

    /// Emit SEH unwind info for the current function.
    pub fn emit_seh_unwind_info(&mut self) {
        let info = self.build_unwind_info();
        self.xdata_buffer = X86GCEHFull::serialize_unwind_info(&info);
    }

    /// Emit the RUNTIME_FUNCTION entry for the current function.
    pub fn emit_pdata_entry(&mut self, begin: u32, end: u32, unwind_rva: u32) {
        let rf = X86GCEHFull::build_runtime_function(begin, end, unwind_rva);
        self.pdata_buffer
            .extend_from_slice(&X86GCEHFull::serialize_runtime_function(&rf));
    }
}

// ============================================================================
// EH Preparation: Outline Landing Pads, Prune Unreachable Handlers
// ============================================================================

impl X86GCEHFull {
    /// Outline landing pads into separate functions (or cold sections).
    ///
    /// Outlining improves I-cache utilization by moving cold exception
    /// handling code away from the hot path. Each landing pad becomes
    /// a stub that restores state and jumps to the actual handler.
    pub fn outline_landing_pads(&mut self) {
        if !self.outline_landing_pads {
            return;
        }
        for pad in &mut self.landing_pads {
            if !pad.is_outlined && !pad.is_unreachable {
                pad.is_outlined = true;
                // In practice, the landing pad body is moved to a cold
                // basic block and the original pad becomes a stub with
                // a jump to the outlined code.
            }
        }
    }

    /// Prune unreachable EH handlers.
    ///
    /// An unreachable handler is one that:
    /// - Is in a region that post-dominates an `unreachable` terminator
    /// - Contains no live catch clauses (all types impossible to throw)
    /// - Is a catch-all that can never be reached
    pub fn prune_unreachable_handlers(&mut self) -> Vec<u64> {
        if !self.prune_unreachable_handlers {
            return Vec::new();
        }
        let mut pruned = Vec::new();
        for pad in &mut self.landing_pads {
            if pad.is_unreachable {
                pruned.push(pad.id);
            }
        }
        pruned
    }

    /// Check if a catch clause type can actually be thrown in the function.
    ///
    /// If no call in the function's call chain can throw the given type,
    /// the catch clause is dead and can be removed.
    pub fn is_catch_dead(&self, _type_name: &str) -> bool {
        // Walk all call sites; if none can throw `type_name`, the catch is dead.
        // For simplicity, we conservatively return false (never dead).
        // A real implementation would analyze the call graph and type hierarchy.
        false
    }

    /// Prepare exception handling for the current function.
    ///
    /// Steps:
    /// 1. Identify all landing pads and associated call sites.
    /// 2. Build the call-site table and action records.
    /// 3. Outline landing pads if requested.
    /// 4. Prune unreachable handlers if requested.
    /// 5. Merge identical landing pads if requested.
    pub fn prepare_eh(&mut self) {
        if !self.uses_eh {
            return;
        }

        // Build call-site table entries for each call that can throw.
        // Each landing pad gets entries for its covered call sites.

        if self.outline_landing_pads {
            self.outline_landing_pads();
        }

        if self.prune_unreachable_handlers {
            self.prune_unreachable_handlers();
        }

        if self.merge_landing_pads {
            self.merge_identical_landing_pads();
        }
    }
}

// ============================================================================
// EH Optimization: Merge Identical Landing Pads, Remove Dead Catches
// ============================================================================

impl X86GCEHFull {
    /// Merge landing pads that have identical clauses.
    ///
    /// Two landing pads are identical if they have the same clause list
    /// (same types, same order, same cleanup flag). They can be merged
    /// into a single pad to reduce code size.
    pub fn merge_identical_landing_pads(&mut self) -> u32 {
        if !self.merge_landing_pads || self.landing_pads.len() < 2 {
            return 0;
        }

        let mut merged_count = 0u32;
        let mut seen: HashMap<Vec<X86GCEHClauseKind>, u64> = HashMap::new();

        let pads = std::mem::take(&mut self.landing_pads);
        let mut result = Vec::new();

        for pad in pads {
            if pad.is_cleanup && pad.clauses.is_empty() {
                // Cleanup-only pads are always identical to other cleanup-only pads.
                let key = vec![X86GCEHClauseKind::Cleanup];
                if let Some(&existing_id) = seen.get(&key) {
                    // Merge into existing.
                    if let Some(existing) = result
                        .iter_mut()
                        .find(|p: &&mut X86GCEHLandingPad| p.id == existing_id)
                    {
                        existing.merged_from.push(pad.id);
                        merged_count += 1;
                        continue;
                    }
                }
                seen.insert(key, pad.id);
            } else {
                // Build key from clause kinds.
                let key: Vec<X86GCEHClauseKind> = pad.clauses.iter().map(|c| c.kind).collect();
                if let Some(&existing_id) = seen.get(&key) {
                    // Check if truly identical (same type infos).
                    let existing = result
                        .iter()
                        .find(|p: &&X86GCEHLandingPad| p.id == existing_id)
                        .unwrap();
                    let clauses_match = existing.clauses.len() == pad.clauses.len()
                        && existing.clauses.iter().zip(&pad.clauses).all(|(a, b)| {
                            match (&a.type_info, &b.type_info) {
                                (Some(a_ti), Some(b_ti)) => a_ti.type_name == b_ti.type_name,
                                (None, None) => true,
                                _ => false,
                            }
                        });
                    if clauses_match {
                        result
                            .iter_mut()
                            .find(|p: &&mut X86GCEHLandingPad| p.id == existing_id)
                            .unwrap()
                            .merged_from
                            .push(pad.id);
                        merged_count += 1;
                        continue;
                    }
                }
                seen.insert(key, pad.id);
            }
            result.push(pad);
        }

        self.landing_pads = result;
        merged_count
    }

    /// Remove dead catch clauses.
    ///
    /// A catch clause is dead if the type it catches can never be thrown
    /// in the function's throw scope. This analysis looks at the call
    /// graph and type hierarchy to determine feasibility.
    pub fn remove_dead_catches(&mut self) -> u32 {
        let mut removed_count = 0u32;

        // Collect which type names are dead before mutating landing_pads
        let dead_types: Vec<(usize, Vec<bool>)> = self
            .landing_pads
            .iter()
            .map(|pad| {
                let dead: Vec<bool> = pad
                    .clauses
                    .iter()
                    .map(|c| match &c.type_info {
                        Some(ti) => self.is_catch_dead(&ti.type_name),
                        None => false,
                    })
                    .collect();
                dead
            })
            .enumerate()
            .map(|(i, dead)| (i, dead))
            .collect();

        for (i, dead_mask) in dead_types {
            let pad = &mut self.landing_pads[i];
            let before = pad.clauses.len();
            let mut j = 0;
            pad.clauses.retain(|_| {
                let keep = !dead_mask.get(j).copied().unwrap_or(false);
                j += 1;
                keep
            });
            removed_count += (before - pad.clauses.len()) as u32;
        }

        removed_count
    }

    /// Deduplicate call-site table entries.
    ///
    /// If two call sites have the same landing pad and action, they can
    /// share the entry by merging their ranges.
    pub fn deduplicate_call_sites(&mut self) {
        let mut i = 0;
        while i + 1 < self.call_site_table.len() {
            let a = &self.call_site_table[i];
            let b = &self.call_site_table[i + 1];
            if a.cs_lp == b.cs_lp
                && a.cs_action == b.cs_action
                && a.cs_start + a.cs_length == b.cs_start
            {
                // Adjacent entries with same LP/action — merge them.
                let merged_length = a.cs_length + b.cs_length;
                self.call_site_table[i].cs_length = merged_length;
                self.call_site_table.remove(i + 1);
            } else {
                i += 1;
            }
        }
    }
}

// ============================================================================
// Personality Functions
// ============================================================================

impl X86GCEHFull {
    /// Lower a reference to `__gxx_personality_v0` (GCC C++ personality).
    ///
    /// This personality handles C++ exceptions per the Itanium C++ ABI.
    /// It is used by GCC and Clang on Linux, macOS, and other ELF/Mach-O
    /// platforms.
    pub fn personality_gxx_v0(&mut self) {
        self.personality = X86GCEHPersonality::GxxV0;
        self.emit_dwarf_eh = true;
        self.emit_seh = false;
        self.personality_refs
            .insert("__gxx_personality_v0".to_string());
    }

    /// Lower a reference to `__gcc_personality_v0` (GCC C personality).
    ///
    /// This personality handles C exceptions via the Itanium unwind APIs.
    /// Used by GCC when compiling C code with `-fexceptions`.
    pub fn personality_gcc_v0(&mut self) {
        self.personality = X86GCEHPersonality::GccV0;
        self.emit_dwarf_eh = true;
        self.emit_seh = false;
        self.personality_refs
            .insert("__gcc_personality_v0".to_string());
    }

    /// Lower a reference to `__CxxFrameHandler3` (MSVC C++ SEH personality).
    pub fn personality_cxx_frame_handler3(&mut self) {
        self.configure_cxx_frame_handler3();
    }

    /// Lower a reference to `__C_specific_handler` (MSVC C SEH personality).
    pub fn personality_c_specific_handler(&mut self) {
        self.configure_c_specific_handler();
    }

    /// Lower a reference to `__objc_personality_v0` (Objective-C EH).
    ///
    /// This personality handles Objective-C exceptions. It extends the
    /// Itanium C++ ABI with ObjC-specific features like `@catch` and
    /// `@finally`.
    pub fn personality_objc_v0(&mut self) {
        self.personality = X86GCEHPersonality::ObjCV0;
        self.emit_dwarf_eh = true;
        self.emit_seh = false;
        self.personality_refs
            .insert("__objc_personality_v0".to_string());
    }

    /// Lower a reference to `__gxx_personality_seh0` (MinGW SEH).
    ///
    /// This personality is used by MinGW-w64 to bridge between the Itanium
    /// C++ ABI personality and Windows SEH. It converts SEH exceptions to
    /// Itanium-style exceptions.
    pub fn personality_gxx_seh0(&mut self) {
        self.personality = X86GCEHPersonality::GxxSeh0;
        self.emit_dwarf_eh = true;
        self.emit_seh = true;
        self.is_mingw = true;
        self.personality_refs
            .insert("__gxx_personality_seh0".to_string());
    }

    /// Return personality-specific setup for the unwind context.
    ///
    /// Different personalities have different expectations for:
    /// - Which registers hold the exception pointer and selector
    /// - Whether to stop at cleanup pads during phase 1
    /// - Whether foreign exceptions need special handling
    pub fn get_personality_config(&self) -> X86GCEHPersonalityConfig {
        match self.personality {
            X86GCEHPersonality::GxxV0 => X86GCEHPersonalityConfig {
                exc_ptr_reg: DW_RAX,
                selector_reg: DW_RDX,
                cleanups_in_phase1: false,
                handles_foreign: true,
                uses_two_phase: true,
                match_catch_type_adjusted_ptr: true,
            },
            X86GCEHPersonality::GccV0 => X86GCEHPersonalityConfig {
                exc_ptr_reg: DW_RAX,
                selector_reg: DW_RDX,
                cleanups_in_phase1: false,
                handles_foreign: false,
                uses_two_phase: true,
                match_catch_type_adjusted_ptr: false,
            },
            X86GCEHPersonality::CxxFrameHandler3 => X86GCEHPersonalityConfig {
                exc_ptr_reg: DW_RAX,
                selector_reg: DW_RDX,
                cleanups_in_phase1: true,
                handles_foreign: true,
                uses_two_phase: true,
                match_catch_type_adjusted_ptr: true,
            },
            X86GCEHPersonality::CSpecificHandler => X86GCEHPersonalityConfig {
                exc_ptr_reg: DW_RAX,
                selector_reg: DW_RDX,
                cleanups_in_phase1: true,
                handles_foreign: true,
                uses_two_phase: false,
                match_catch_type_adjusted_ptr: false,
            },
            X86GCEHPersonality::ObjCV0 => X86GCEHPersonalityConfig {
                exc_ptr_reg: DW_RAX,
                selector_reg: DW_RDX,
                cleanups_in_phase1: false,
                handles_foreign: true,
                uses_two_phase: true,
                match_catch_type_adjusted_ptr: true,
            },
            X86GCEHPersonality::GxxSeh0 => X86GCEHPersonalityConfig {
                exc_ptr_reg: DW_RAX,
                selector_reg: DW_RDX,
                cleanups_in_phase1: false,
                handles_foreign: true,
                uses_two_phase: true,
                match_catch_type_adjusted_ptr: true,
            },
            X86GCEHPersonality::None => X86GCEHPersonalityConfig {
                exc_ptr_reg: 0,
                selector_reg: 0,
                cleanups_in_phase1: false,
                handles_foreign: false,
                uses_two_phase: false,
                match_catch_type_adjusted_ptr: false,
            },
        }
    }
}

/// Configuration for a personality function.
#[derive(Debug, Clone, Copy)]
pub struct X86GCEHPersonalityConfig {
    /// Register for the exception pointer.
    pub exc_ptr_reg: u16,
    /// Register for the selector value.
    pub selector_reg: u16,
    /// Whether cleanups are checked in phase 1 (search).
    pub cleanups_in_phase1: bool,
    /// Whether foreign exceptions are handled.
    pub handles_foreign: bool,
    /// Whether the personality uses the two-phase EH model.
    pub uses_two_phase: bool,
    /// Whether catch matching uses the adjusted pointer.
    pub match_catch_type_adjusted_ptr: bool,
}

// ============================================================================
// Exception Pointer Extraction
// ============================================================================

impl X86GCEHFull {
    /// Get the exception pointer register for a given `__builtin_eh_return_data_regno`.
    ///
    /// Per GCC/Clang:
    /// - `__builtin_eh_return_data_regno(0)` → RAX (exception pointer)
    /// - `__builtin_eh_return_data_regno(1)` → RDX (selector / filter value)
    pub fn get_eh_return_data_regno(index: u32) -> Option<u16> {
        X86GCEHExceptionPointerRegs::eh_return_data_regno(index)
    }

    /// Extract the exception pointer from the landing pad result.
    ///
    /// The landing pad returns `{ i8*, i32 }` — the exception pointer and
    /// the selector. This method extracts the exception pointer.
    pub fn extract_exception_pointer(&self) -> u16 {
        let config = self.get_personality_config();
        config.exc_ptr_reg
    }

    /// Extract the selector value from the landing pad result.
    pub fn extract_selector(&self) -> u16 {
        let config = self.get_personality_config();
        config.selector_reg
    }

    /// Build the code sequence that extracts exception pointers from a
    /// landing pad. This involves:
    /// 1. `extractvalue { i8*, i32 } %lp, 0` → exception pointer
    /// 2. `extractvalue { i8*, i32 } %lp, 1` → selector
    pub fn lower_eh_extract_values(&self, _lp_reg: u16) -> (X86GCEHRoot, X86GCEHRoot) {
        let exc_ptr = X86GCEHRoot {
            kind: X86GCEHRootKind::ObjectPointer,
            location: X86GCEHRootLocation::Register(self.extract_exception_pointer()),
            is_derived: false,
            derived_offset: 0,
            is_live: true,
            description: "exception pointer from landingpad".to_string(),
        };
        let selector = X86GCEHRoot {
            kind: X86GCEHRootKind::ObjectPointer,
            location: X86GCEHRootLocation::Register(self.extract_selector()),
            is_derived: false,
            derived_offset: 0,
            is_live: true,
            description: "selector from landingpad".to_string(),
        };
        (exc_ptr, selector)
    }
}

// ============================================================================
// Stack Map Section: .llvm_stackmaps
// ============================================================================

impl X86GCEHFull {
    /// Emit the complete `.llvm_stackmaps` section.
    ///
    /// This section is used by the LLVM stack map infrastructure to
    /// communicate GC and deoptimization information to the runtime.
    ///
    /// See LLVM Stack Map documentation for the binary format.
    pub fn emit_llvm_stackmaps_section(&self) -> Vec<u8> {
        let mut section = Vec::new();

        // Section header
        // Version (u8): 3
        section.push(3);
        // Reserved (u8): 0
        section.push(0);
        // Reserved (u16): 0
        section.extend_from_slice(&[0u8, 0u8]);

        // Since we flushed per-function in emit_function_stack_map,
        // all data is in stack_map_buffer.
        section.extend_from_slice(&self.stack_map_buffer);

        section
    }

    /// Emit the patchpoint lowering for a given patchpoint.
    ///
    /// Patchpoints are used by dynamic language runtimes (e.g., JVM,
    /// JavaScript) to enable inline cache patching and deoptimization.
    pub fn lower_patchpoint(&mut self, _patchpoint: &X86GCEHPatchpoint) -> X86GCEHStackMapRecord {
        let id = self.next_stack_map_id();
        let record = X86GCEHStackMapRecord {
            id,
            function_address: 0,
            instruction_offset: id * 4,
            num_locations: 0,
            locations: Vec::new(),
            num_live_outs: 0,
            live_outs: Vec::new(),
            padding: 0,
        };
        self.stack_maps.push(record.clone());
        record
    }

    /// Emit the statepoint lowering for a given statepoint.
    ///
    /// Statepoints wrap calls and provide GC with live pointer information.
    pub fn lower_statepoint(&mut self, statepoint: &X86GCEHStatepoint) -> X86GCEHStackMapRecord {
        let record = self.build_stack_map_record(
            statepoint.stack_map_id,
            statepoint.pc_offset,
            &statepoint.roots,
            &statepoint.stack_slots,
        );
        self.stack_maps.push(record.clone());
        record
    }

    /// Get the total stack map buffer for emission.
    pub fn get_stack_map_section(&self) -> Vec<u8> {
        self.finalize_stack_map_section()
    }
}

// ============================================================================
// Patchpoint Intrinsic Lowering
// ============================================================================

impl X86GCEHFull {
    /// Lower a `llvm.experimental.patchpoint.*` intrinsic.
    ///
    /// Patchpoints provide a way to emit a call with a variable-sized nop
    /// region that can be patched at runtime. This is used by:
    /// - MCJIT for runtime code patching
    /// - Deoptimization frameworks
    /// - Inline cache implementations
    pub fn lower_llvm_patchpoint(
        &mut self,
        flags: u32,
        num_bytes: u32,
        num_args: u32,
        callee: u64,
        num_patch_args: u16,
        cc: u32,
    ) -> X86GCEHPatchpoint {
        let id = self.next_statepoint_id();
        let stack_map_id = self.next_stack_map_id();

        // Pending stack map record — will be emitted during stack map
        // section finalization.
        let _record = X86GCEHStackMapRecord {
            id: stack_map_id,
            function_address: 0,
            instruction_offset: id * num_bytes as u64,
            num_locations: num_patch_args,
            locations: Vec::new(),
            num_live_outs: 0,
            live_outs: Vec::new(),
            padding: 0,
        };

        X86GCEHPatchpoint {
            id,
            flags,
            num_bytes,
            num_args,
            callee,
            num_patch_args,
            cc,
            stack_map_id: Some(stack_map_id),
        }
    }

    /// Build a nop sled for a patchpoint.
    ///
    /// The nop sled fills `num_bytes` with multi-byte NOPs that can be
    /// safely overwritten at runtime with a call or jump.
    pub fn build_patchpoint_nop_sled(num_bytes: u32) -> Vec<u8> {
        let mut sled = Vec::with_capacity(num_bytes as usize);
        let mut remaining = num_bytes;

        while remaining > 0 {
            if remaining >= 9 {
                // 9-byte NOP: 0x66 0x0F 0x1F 0x84 0x00 0x00 0x00 0x00 0x00
                sled.extend_from_slice(&[0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00]);
                remaining -= 9;
            } else if remaining >= 8 {
                sled.extend_from_slice(&[0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00]);
                remaining -= 8;
            } else if remaining >= 7 {
                sled.extend_from_slice(&[0x0F, 0x1F, 0x80, 0x00, 0x00, 0x00, 0x00]);
                remaining -= 7;
            } else if remaining >= 6 {
                sled.extend_from_slice(&[0x66, 0x0F, 0x1F, 0x44, 0x00, 0x00]);
                remaining -= 6;
            } else if remaining >= 5 {
                sled.extend_from_slice(&[0x0F, 0x1F, 0x44, 0x00, 0x00]);
                remaining -= 5;
            } else if remaining >= 4 {
                sled.extend_from_slice(&[0x0F, 0x1F, 0x40, 0x00]);
                remaining -= 4;
            } else if remaining >= 3 {
                sled.extend_from_slice(&[0x0F, 0x1F, 0x00]);
                remaining -= 3;
            } else if remaining >= 2 {
                sled.extend_from_slice(&[0x66, 0x90]);
                remaining -= 2;
            } else {
                sled.push(0x90);
                remaining -= 1;
            }
        }

        sled
    }
}

// ============================================================================
// GC/EH Unified Pipeline
// ============================================================================

impl X86GCEHFull {
    /// Run the complete GC/EH lowering pipeline on the current function.
    ///
    /// This is the main entry point for lowering. It orchestrates:
    /// 1. GC root enumeration
    /// 2. Statepoint insertion and lowering
    /// 3. Safepoint placement
    /// 4. EH preparation
    /// 5. EH optimization
    /// 6. Stack map generation
    /// 7. Unwind info emission
    pub fn run_pipeline(&mut self) {
        if self.uses_gc {
            // Enumerate roots.
            let _roots = self.enumerate_live_roots();

            // Place safepoints.
            let _offsets = self.compute_safepoint_placement();

            // If using statepoints, rewrite calls.
            if self.enable_statepoints {
                // In practice, this runs the RewriteStatepointsForGC pass
                // on the IR before instruction selection.
            }
        }

        if self.uses_eh {
            self.prepare_eh();
        }

        // Generate stack maps.
        if self.enable_stack_maps && self.uses_gc {
            // Stack maps are emitted during end_function.
        }

        self.end_function();
    }

    /// Get a summary of the current lowering state.
    pub fn summary(&self) -> String {
        format!(
            "X86GCEHFull: function={}, gc_strategy={}, personality={}, \
             safepoints={}, landing_pads={}, stack_maps={}, roots={}, \
             uses_gc={}, uses_eh={}",
            self.current_function,
            self.gc_strategy,
            self.personality.symbol_name(),
            self.safepoints.len(),
            self.landing_pads.len(),
            self.stack_maps.len(),
            self.active_roots.len(),
            self.uses_gc,
            self.uses_eh,
        )
    }

    /// Validate the current state.
    pub fn validate(&self) -> Result<(), String> {
        if self.uses_gc && self.gc_strategy == X86GCEHStrategy::None {
            return Err(format!(
                "function '{}' uses GC but no GC strategy selected",
                self.current_function
            ));
        }
        if self.uses_eh && self.personality == X86GCEHPersonality::None {
            return Err(format!(
                "function '{}' uses EH but no personality selected",
                self.current_function
            ));
        }
        if self.enable_stack_maps && self.stack_maps.len() > GC_EH_MAX_SAFEPOINTS {
            return Err(format!(
                "function '{}' exceeds maximum safepoints ({} > {})",
                self.current_function,
                self.stack_maps.len(),
                GC_EH_MAX_SAFEPOINTS,
            ));
        }
        Ok(())
    }
}

// ============================================================================
// DWARF Expression Helpers
// ============================================================================

/// Encode a ULEB128 value.
fn uleb128(mut value: u64) -> Vec<u8> {
    let mut buf = Vec::new();
    loop {
        let mut byte = (value & 0x7F) as u8;
        value >>= 7;
        if value != 0 {
            byte |= 0x80;
        }
        buf.push(byte);
        if value == 0 {
            break;
        }
    }
    buf
}

/// Encode a SLEB128 value.
fn sleb128(mut value: i64) -> Vec<u8> {
    let mut buf = Vec::new();
    loop {
        let mut byte = (value & 0x7F) as u8;
        value >>= 7;
        let more = !((value == 0 && (byte & 0x40) == 0) || (value == -1 && (byte & 0x40) != 0));
        if more {
            byte |= 0x80;
        }
        buf.push(byte);
        if !more {
            break;
        }
    }
    buf
}

/// Decode a ULEB128 value from a byte slice.
pub fn decode_uleb128(data: &[u8]) -> Option<(u64, usize)> {
    let mut value: u64 = 0;
    let mut shift = 0u32;
    for (i, &byte) in data.iter().enumerate() {
        value |= ((byte & 0x7F) as u64) << shift;
        if byte & 0x80 == 0 {
            return Some((value, i + 1));
        }
        shift += 7;
        if shift >= 64 {
            return None; // Overflow.
        }
    }
    None
}

/// Compute CFA (Canonical Frame Address) for a given RSP value.
pub fn compute_cfa(rsp: u64, stack_size: u64) -> u64 {
    rsp + stack_size
}

/// Compute the return address location from CFA.
pub fn compute_return_address_location(cfa: u64) -> u64 {
    cfa - 8 // Return address is at CFA - 8 on X86-64.
}

// ============================================================================
// Machine Instruction Integration
// ============================================================================

impl X86GCEHFull {
    /// Build a machine instruction for a safepoint poll.
    pub fn build_machine_safepoint_poll(&self) -> MachineInstr {
        // Placeholder: the actual machine instruction is created by the
        // instruction selector.
        MachineInstr::default()
    }

    /// Build a machine instruction for `__builtin_eh_return`.
    ///
    /// On X86-64, `__builtin_eh_return` is lowered to:
    /// ```asm
    /// mov rsp, rbp   ; restore stack pointer
    /// pop rbp        ; restore frame pointer
    /// ret            ; return to exception handler
    /// ```
    pub fn build_machine_eh_return(&self, _stack_adjust: u64, _target_addr: u64) -> MachineInstr {
        // Placeholder.
        MachineInstr::default()
    }

    /// Build a machine instruction for a stack map/patchpoint call.
    pub fn build_machine_patchpoint_call(&self, _patchpoint: &X86GCEHPatchpoint) -> MachineInstr {
        // Placeholder.
        MachineInstr::default()
    }
}

// ============================================================================
// Utility: GC Strategy Analysis
// ============================================================================

impl X86GCEHFull {
    /// Determine whether a given call can trigger GC.
    ///
    /// Calls to allocation functions, runtime helpers, and non-leaf
    /// functions may trigger GC depending on the strategy.
    pub fn call_may_trigger_gc(&self, callee: &str) -> bool {
        if !self.uses_gc {
            return false;
        }
        match self.gc_strategy {
            X86GCEHStrategy::Statepoint => {
                // Statepoint GC: any call that is not explicitly marked
                // as a GC leaf can trigger GC.
                !self.call_needs_statepoint(callee, true)
            }
            X86GCEHStrategy::CoreCLR => {
                // CoreCLR: only calls that go through the GC hole can
                // trigger GC. Allocation helpers and runtime calls.
                callee.starts_with("JIT_")
                    || callee.starts_with("GC_")
                    || callee == "new"
                    || callee == "alloc"
            }
            X86GCEHStrategy::OCaml => {
                // OCaml: only caml_call_gc and C calls can trigger GC.
                callee == "caml_call_gc" || callee == "caml_alloc" || callee.starts_with("caml_")
            }
            X86GCEHStrategy::Erlang => {
                // Erlang: GC triggered after N reductions.
                callee == "erts_gc" || callee.starts_with("erts_")
            }
            X86GCEHStrategy::ShadowStack => {
                // ShadowStack: all calls can trigger GC because the
                // shadow stack tracks roots precisely.
                true
            }
            _ => false,
        }
    }

    /// Compute the set of registers that must be treated as GC roots
    /// at a given call site.
    pub fn compute_call_gc_roots(&self, _call_target: &str) -> Vec<X86GCEHRoot> {
        self.enumerate_live_roots()
    }
}

// ============================================================================
// X86GCEHFullBuilder — Builder pattern for constructing X86GCEHFull
// ============================================================================

/// Builder for X86GCEHFull — allows ergonomic construction.
#[derive(Debug, Default)]
pub struct X86GCEHFullBuilder {
    inner: X86GCEHFull,
}

impl X86GCEHFullBuilder {
    pub fn new() -> Self {
        Self {
            inner: X86GCEHFull::default(),
        }
    }

    pub fn gc_strategy(mut self, strategy: X86GCEHStrategy) -> Self {
        self.inner.set_gc_strategy(strategy);
        self
    }

    pub fn personality(mut self, personality: X86GCEHPersonality) -> Self {
        self.inner.personality = personality;
        self
    }

    pub fn target_triple(mut self, triple: &str) -> Self {
        self.inner.target_triple = triple.to_string();
        self
    }

    pub fn data_layout(mut self, layout: &str) -> Self {
        self.inner.data_layout = layout.to_string();
        self
    }

    pub fn safepoints_at_backedges(mut self, v: bool) -> Self {
        self.inner.safepoints_at_backedges = v;
        self
    }

    pub fn safepoints_at_calls(mut self, v: bool) -> Self {
        self.inner.safepoints_at_calls = v;
        self
    }

    pub fn enable_statepoints(mut self, v: bool) -> Self {
        self.inner.enable_statepoints = v;
        self
    }

    pub fn enable_stack_maps(mut self, v: bool) -> Self {
        self.inner.enable_stack_maps = v;
        self
    }

    pub fn emit_dwarf_eh(mut self, v: bool) -> Self {
        self.inner.emit_dwarf_eh = v;
        self
    }

    pub fn emit_seh(mut self, v: bool) -> Self {
        self.inner.emit_seh = v;
        self
    }

    pub fn outline_landing_pads(mut self, v: bool) -> Self {
        self.inner.outline_landing_pads = v;
        self
    }

    pub fn merge_landing_pads(mut self, v: bool) -> Self {
        self.inner.merge_landing_pads = v;
        self
    }

    pub fn prune_unreachable_handlers(mut self, v: bool) -> Self {
        self.inner.prune_unreachable_handlers = v;
        self
    }

    pub fn build(self) -> X86GCEHFull {
        self.inner
    }
}

// ============================================================================
// Display Implementations
// ============================================================================

impl fmt::Display for X86GCEHFull {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        writeln!(f, "X86GCEHFull {{")?;
        writeln!(f, "  gc_strategy: {}", self.gc_strategy)?;
        writeln!(f, "  personality: {}", self.personality.symbol_name())?;
        writeln!(f, "  target_triple: {}", self.target_triple)?;
        writeln!(
            f,
            "  is_64bit: {}, is_windows: {}, is_mingw: {}",
            self.is_64bit, self.is_windows, self.is_mingw
        )?;
        writeln!(
            f,
            "  enable_statepoints: {}, enable_stack_maps: {}",
            self.enable_statepoints, self.enable_stack_maps
        )?;
        writeln!(f, "  safepoints: {}", self.safepoints.len())?;
        writeln!(f, "  landing_pads: {}", self.landing_pads.len())?;
        writeln!(f, "  stack_maps: {}", self.stack_maps.len())?;
        writeln!(f, "  active_roots: {}", self.active_roots.len())?;
        writeln!(f, "  current_function: {}", self.current_function)?;
        write!(f, "}}")
    }
}

impl fmt::Display for X86GCEHLandingPad {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "LandingPad(id={}, kind={:?}, clauses={}, cleanup={})",
            self.id,
            self.kind,
            self.clauses.len(),
            self.is_cleanup
        )
    }
}

impl fmt::Display for X86GCEHStatepoint {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "Statepoint(id={}, sm={}, roots={})",
            self.id, self.stack_map_id, self.num_roots
        )
    }
}

impl fmt::Display for X86GCEHStackMapRecord {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "StackMap(id={}, locs={}, liveouts={})",
            self.id, self.num_locations, self.num_live_outs
        )
    }
}

// ============================================================================
// ============================================================================
// Comprehensive Test Suite
// ============================================================================
// ============================================================================

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

    // ================================================================
    // Test Helpers
    // ================================================================

    fn make_default_state() -> X86GCEHFull {
        let mut state = X86GCEHFull::default();
        state.begin_function("test_fn", true, true);
        state
    }

    fn make_linux_gc_state() -> X86GCEHFull {
        X86GCEHFullBuilder::new()
            .gc_strategy(X86GCEHStrategy::Statepoint)
            .personality(X86GCEHPersonality::GxxV0)
            .target_triple("x86_64-unknown-linux-gnu")
            .enable_statepoints(true)
            .enable_stack_maps(true)
            .emit_dwarf_eh(true)
            .emit_seh(false)
            .build()
    }

    fn make_windows_eh_state() -> X86GCEHFull {
        X86GCEHFullBuilder::new()
            .gc_strategy(X86GCEHStrategy::None)
            .personality(X86GCEHPersonality::CxxFrameHandler3)
            .target_triple("x86_64-pc-windows-msvc")
            .emit_dwarf_eh(true)
            .emit_seh(true)
            .build()
    }

    // ================================================================
    // X86GCEHFull Core Tests
    // ================================================================

    #[test]
    fn test_default_construction() {
        let state = X86GCEHFull::default();
        assert_eq!(state.gc_strategy, X86GCEHStrategy::Statepoint);
        assert_eq!(state.personality, X86GCEHPersonality::GxxV0);
        assert!(state.enable_statepoints);
        assert!(state.enable_stack_maps);
        assert!(state.is_64bit);
        assert!(!state.is_windows);
        assert!(!state.is_mingw);
        assert_eq!(state.pointer_size, 8);
        assert_eq!(state.frame_pointer_reg, DW_RBP);
        assert_eq!(state.stack_pointer_reg, DW_RSP);
        assert!(state.active_roots.is_empty());
        assert!(state.stack_roots.is_empty());
        assert!(state.stack_maps.is_empty());
        assert!(state.safepoints.is_empty());
        assert!(state.landing_pads.is_empty());
    }

    #[test]
    fn test_begin_function_resets_state() {
        let mut state = make_default_state();
        state.register_root(
            DW_RAX,
            X86GCEHRootKind::ObjectPointer,
            false,
            0,
            "test_root",
        );
        state.register_stack_root(-8, 8, false, "stack_root");
        state.lower_landingpad(vec![], true);

        state.begin_function("new_fn", true, false);

        assert_eq!(state.current_function, "new_fn");
        assert!(state.active_roots.is_empty());
        assert!(state.stack_roots.is_empty());
        assert!(state.call_site_table.is_empty());
        assert!(state.action_records.is_empty());
        assert!(!state.uses_eh);
    }

    #[test]
    fn test_id_generation_monotonic() {
        let mut state = make_default_state();
        let a = state.next_statepoint_id();
        let b = state.next_statepoint_id();
        let c = state.next_statepoint_id();
        assert!(a < b);
        assert!(b < c);

        let s1 = state.next_safepoint_id();
        let s2 = state.next_safepoint_id();
        assert!(s1 < s2);

        let lp1 = state.next_landingpad_id();
        let lp2 = state.next_landingpad_id();
        assert!(lp1 < lp2);
    }

    #[test]
    fn test_reset() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "root");
        state.safepoints.push(X86GCEHSafepoint {
            id: 1,
            kind: X86GCEHSafepointKind::PreCall,
            pc_offset: 0,
            may_gc: true,
            statepoint_id: None,
            stack_map_id: None,
        });
        state.reset();

        assert_eq!(state.gc_strategy, X86GCEHStrategy::Statepoint);
        assert!(state.active_roots.is_empty());
        assert!(state.safepoints.is_empty());
        assert_eq!(state.next_statepoint_id, 0);
    }

    // ================================================================
    // GC Strategy Tests
    // ================================================================

    #[test]
    fn test_gc_strategy_statepoint() {
        let s = X86GCEHStrategy::Statepoint;
        assert!(s.uses_statepoints());
        assert!(!s.uses_shadow_stack());
        assert!(s.needs_stack_maps());
        assert!(s.requires_write_barriers());
        assert_eq!(s.llvm_attr_name(), "statepoint-example");
    }

    #[test]
    fn test_gc_strategy_coreclr() {
        let s = X86GCEHStrategy::CoreCLR;
        assert!(!s.uses_statepoints());
        assert!(!s.uses_shadow_stack());
        assert!(s.needs_stack_maps());
        assert!(s.requires_write_barriers());
        assert_eq!(s.llvm_attr_name(), "coreclr");
    }

    #[test]
    fn test_gc_strategy_ocaml() {
        let s = X86GCEHStrategy::OCaml;
        assert!(!s.uses_statepoints());
        assert!(!s.uses_shadow_stack());
        assert!(s.needs_stack_maps());
        assert!(s.requires_write_barriers());
        assert_eq!(s.llvm_attr_name(), "ocaml");
    }

    #[test]
    fn test_gc_strategy_erlang() {
        let s = X86GCEHStrategy::Erlang;
        assert!(!s.uses_statepoints());
        assert!(!s.uses_shadow_stack());
        assert!(!s.needs_stack_maps());
        assert!(s.requires_write_barriers());
        assert_eq!(s.llvm_attr_name(), "erlang");
    }

    #[test]
    fn test_gc_strategy_shadow_stack() {
        let s = X86GCEHStrategy::ShadowStack;
        assert!(!s.uses_statepoints());
        assert!(s.uses_shadow_stack());
        assert!(!s.needs_stack_maps());
        assert!(!s.requires_write_barriers());
        assert_eq!(s.llvm_attr_name(), "shadow-stack");
    }

    #[test]
    fn test_set_gc_strategy_from_attr() {
        let mut state = X86GCEHFull::default();
        state.set_gc_strategy_from_attr("statepoint-example");
        assert_eq!(state.gc_strategy, X86GCEHStrategy::Statepoint);

        state.set_gc_strategy_from_attr("coreclr");
        assert_eq!(state.gc_strategy, X86GCEHStrategy::CoreCLR);

        state.set_gc_strategy_from_attr("ocaml");
        assert_eq!(state.gc_strategy, X86GCEHStrategy::OCaml);

        state.set_gc_strategy_from_attr("unknown");
        assert_eq!(state.gc_strategy, X86GCEHStrategy::None);
    }

    #[test]
    fn test_needs_gc_support() {
        let mut state = X86GCEHFull::default();
        state.uses_gc = true;
        state.gc_strategy = X86GCEHStrategy::Statepoint;
        assert!(state.needs_gc_support());

        state.gc_strategy = X86GCEHStrategy::None;
        assert!(!state.needs_gc_support());

        state.uses_gc = false;
        assert!(!state.needs_gc_support());
    }

    #[test]
    fn test_needs_eh_support() {
        let mut state = X86GCEHFull::default();
        state.uses_eh = true;
        state.personality = X86GCEHPersonality::GxxV0;
        assert!(state.needs_eh_support());

        state.personality = X86GCEHPersonality::None;
        assert!(!state.needs_eh_support());

        state.uses_eh = false;
        assert!(!state.needs_eh_support());
    }

    // ================================================================
    // GC Root Tests
    // ================================================================

    #[test]
    fn test_register_root() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax_root");
        assert_eq!(state.active_roots.len(), 1);
        let root = state.active_roots.get(&DW_RAX).unwrap();
        assert_eq!(root.kind, X86GCEHRootKind::ObjectPointer);
        assert!(matches!(
            root.location,
            X86GCEHRootLocation::Register(DW_RAX)
        ));
        assert!(root.is_live);
        assert!(!root.is_derived);
    }

    #[test]
    fn test_register_derived_root() {
        let mut state = make_default_state();
        state.register_root(DW_R12, X86GCEHRootKind::DerivedPointer, true, 16, "derived");
        let root = state.active_roots.get(&DW_R12).unwrap();
        assert!(root.is_derived);
        assert_eq!(root.derived_offset, 16);
        assert_eq!(root.kind, X86GCEHRootKind::DerivedPointer);
    }

    #[test]
    fn test_stack_root() {
        let mut state = make_default_state();
        state.register_stack_root(-8, 8, false, "local_ptr");
        assert_eq!(state.stack_roots.len(), 1);
        assert_eq!(state.stack_roots[0].offset, -8);
        assert_eq!(state.stack_roots[0].size, 8);
        assert!(!state.stack_roots[0].is_derived);
        assert!(state.stack_roots[0].is_live);
    }

    #[test]
    fn test_kill_root() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");
        assert!(state.active_roots.get(&DW_RAX).unwrap().is_live);
        state.kill_root(DW_RAX);
        assert!(!state.active_roots.get(&DW_RAX).unwrap().is_live);
    }

    #[test]
    fn test_kill_stack_root() {
        let mut state = make_default_state();
        state.register_stack_root(-8, 8, false, "slot1");
        state.register_stack_root(-16, 8, false, "slot2");
        state.kill_stack_root(-8);
        assert!(!state.stack_roots[0].is_live);
        assert!(state.stack_roots[1].is_live);
    }

    #[test]
    fn test_enumerate_live_roots() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");
        state.register_root(DW_RBX, X86GCEHRootKind::ObjectPointer, false, 0, "rbx");
        state.kill_root(DW_RBX);
        state.register_stack_root(-8, 8, false, "slot1");

        let roots = state.enumerate_live_roots();
        assert_eq!(roots.len(), 2); // rax live, rbx dead, slot live
        let has_rax = roots
            .iter()
            .any(|r| matches!(r.location, X86GCEHRootLocation::Register(DW_RAX)));
        assert!(has_rax);
    }

    #[test]
    fn test_enumerate_callee_saved_roots() {
        let mut state = make_default_state();
        state.register_root(DW_RBX, X86GCEHRootKind::ObjectPointer, false, 0, "rbx");
        state.register_root(DW_R12, X86GCEHRootKind::ObjectPointer, false, 0, "r12");
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");
        // RAX is caller-saved, not callee-saved.
        let callee = state.enumerate_callee_saved_roots();
        assert_eq!(callee.len(), 2);
        assert!(callee.iter().any(|r| r.description == "rbx"));
        assert!(callee.iter().any(|r| r.description == "r12"));
    }

    #[test]
    fn test_enumerate_caller_saved_roots() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");
        state.register_root(DW_RDI, X86GCEHRootKind::ObjectPointer, false, 0, "rdi");
        state.register_root(DW_RBX, X86GCEHRootKind::ObjectPointer, false, 0, "rbx"); // Callee-saved
        let caller = state.enumerate_caller_saved_roots();
        assert_eq!(caller.len(), 2);
    }

    // ================================================================
    // Statepoint Tests
    // ================================================================

    #[test]
    fn test_lower_gc_statepoint() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");

        let sp = state.lower_gc_statepoint(
            Some("malloc"),
            2,
            &[],
            X86GCEHGCTransition::Relocation,
            &[0x42, 0x43],
            0,
        );
        assert_eq!(sp.call_target.as_deref(), Some("malloc"));
        assert_eq!(sp.num_call_args, 2);
        assert_eq!(sp.gc_transition, X86GCEHGCTransition::Relocation);
        assert_eq!(sp.deopt_state, vec![0x42, 0x43]);
        assert_eq!(sp.num_deopt_bytes, 2);
    }

    #[test]
    fn test_lower_gc_statepoint_creates_stack_map() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");

        let sp = state.lower_gc_statepoint(None, 1, &[], X86GCEHGCTransition::Safepoint, &[], 0);
        // Stack map should be created.
        assert!(!state.stack_maps.is_empty());
        let sm = &state.stack_maps[0];
        assert_eq!(sm.id, sp.stack_map_id);
        assert!(sm.num_locations >= 1);
        assert!(sm.num_live_outs >= 1);
    }

    #[test]
    fn test_lower_gc_statepoint_creates_safepoint() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");

        let sp =
            state.lower_gc_statepoint(Some("foo"), 0, &[], X86GCEHGCTransition::Relocation, &[], 0);
        assert!(!state.safepoints.is_empty());
        let sf = &state.safepoints[0];
        assert_eq!(sf.statepoint_id, Some(sp.id));
        assert_eq!(sf.may_gc, true);
        assert_eq!(sf.kind, X86GCEHSafepointKind::PreCall);
    }

    #[test]
    fn test_lower_gc_statepoint_no_gc_transition() {
        let mut state = make_default_state();
        let sp =
            state.lower_gc_statepoint(Some("leaf_fn"), 0, &[], X86GCEHGCTransition::None, &[], 0);
        let sf = &state.safepoints[0];
        assert!(!sf.may_gc);
    }

    // ================================================================
    // gc.result / gc.relocate Tests
    // ================================================================

    #[test]
    fn test_lower_gc_result() {
        let state = make_default_state();
        let root = state.lower_gc_result(42, DW_R8);
        assert_eq!(root.kind, X86GCEHRootKind::ObjectPointer);
        assert!(matches!(
            root.location,
            X86GCEHRootLocation::Register(DW_R8)
        ));
        assert!(root.description.contains("gc.result"));
        assert!(root.description.contains("42"));
        assert!(root.description.contains("D8"));
    }

    #[test]
    fn test_lower_gc_relocate() {
        let state = make_default_state();
        let reloc = state.lower_gc_relocate(10, 7, 7, 0x1000, 0x2000);
        assert_eq!(reloc.statepoint_id, 10);
        assert_eq!(reloc.base_offset, 7);
        assert_eq!(reloc.derived_offset, 7);
        assert_eq!(reloc.original_value, 0x1000);
        assert_eq!(reloc.relocated_value, 0x2000);
    }

    #[test]
    fn test_emit_gc_relocates() {
        let mut state = make_default_state();
        let relocs =
            state.emit_gc_relocates(5, &[(DW_RAX as u16, 0x1000), (DW_RBX as u16, 0x2000)]);
        assert_eq!(relocs.len(), 2);
        assert_eq!(relocs[0].statepoint_id, 5);
        assert_eq!(relocs[1].statepoint_id, 5);
    }

    // ================================================================
    // Safepoint Tests
    // ================================================================

    #[test]
    fn test_insert_loop_backedge_safepoint() {
        let mut state = make_default_state();
        let sp = state.insert_loop_backedge_safepoint(0x100);
        assert!(sp.is_some());
        assert_eq!(sp.unwrap().kind, X86GCEHSafepointKind::LoopBackedge);
        assert_eq!(state.safepoints.len(), 1);
    }

    #[test]
    fn test_insert_loop_backedge_safepoint_disabled() {
        let mut state = make_default_state();
        state.safepoints_at_backedges = false;
        let sp = state.insert_loop_backedge_safepoint(0x100);
        assert!(sp.is_none());
    }

    #[test]
    fn test_insert_pre_call_safepoint() {
        let mut state = make_default_state();
        let sp = state.insert_pre_call_safepoint(0x200);
        assert!(sp.is_some());
        assert_eq!(state.safepoints.len(), 1);
    }

    #[test]
    fn test_insert_pre_call_safepoint_disabled() {
        let mut state = make_default_state();
        state.safepoints_at_calls = false;
        let sp = state.insert_pre_call_safepoint(0x200);
        assert!(sp.is_none());
    }

    #[test]
    fn test_insert_polling_safepoint() {
        let mut state = make_default_state();
        state.cooperative_polling = true;
        let sp = state.insert_polling_safepoint(0x300);
        assert!(sp.is_some());
        assert_eq!(sp.unwrap().kind, X86GCEHSafepointKind::Poll);
    }

    #[test]
    fn test_insert_polling_safepoint_disabled() {
        let mut state = make_default_state();
        state.cooperative_polling = false;
        let sp = state.insert_polling_safepoint(0x300);
        assert!(sp.is_none());
    }

    #[test]
    fn test_compute_safepoint_placement() {
        let mut state = make_default_state();
        state.insert_loop_backedge_safepoint(0x100);
        state.insert_pre_call_safepoint(0x100); // Duplicate offset.
        state.insert_entry_safepoint(0x50);
        let offsets = state.compute_safepoint_placement();
        assert_eq!(offsets.len(), 2); // 0x50, 0x100 (deduped).
        assert_eq!(offsets[0], 0x50);
        assert_eq!(offsets[1], 0x100);
    }

    // ================================================================
    // RewriteStatepointsForGC Tests
    // ================================================================

    #[test]
    fn test_call_needs_statepoint() {
        let mut state = make_default_state();
        state.uses_gc = true;

        // Known leaf — no statepoint needed.
        assert!(!state.call_needs_statepoint("memcpy", true));
        assert!(!state.call_needs_statepoint("llvm.memcpy", true));
        assert!(!state.call_needs_statepoint("llvm.sqrt", true));

        // Non-leaf — statepoint needed.
        assert!(state.call_needs_statepoint("malloc", false));
        assert!(state.call_needs_statepoint("operator_new", false));
    }

    #[test]
    fn test_call_needs_statepoint_no_gc() {
        let mut state = make_default_state();
        state.uses_gc = false;
        assert!(!state.call_needs_statepoint("malloc", false));
    }

    #[test]
    fn test_rewrite_statepoints_for_gc() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");

        let roots = state.enumerate_live_roots();
        let statepoints =
            state.rewrite_statepoints_for_gc(&[(0x100, Some("malloc".to_string()), 2)], &roots);
        assert_eq!(statepoints.len(), 1);
        assert_eq!(statepoints[0].call_target.as_deref(), Some("malloc"));
    }

    // ================================================================
    // Landing Pad Tests
    // ================================================================

    #[test]
    fn test_lower_landingpad_cleanup_only() {
        let mut state = make_default_state();
        let lp = state.lower_landingpad(vec![], true);
        assert_eq!(lp.kind, X86GCEHLandingPadKind::LandingPad);
        assert!(lp.is_cleanup);
        assert!(lp.clauses.is_empty());
    }

    #[test]
    fn test_lower_landingpad_with_catch() {
        let mut state = make_default_state();
        let ti = X86GCEHTypeInfoEntry {
            encoding: 0,
            type_info_ptr: 0xDEAD,
            type_name: "std::runtime_error".to_string(),
        };
        let clause = X86GCEHClause {
            kind: X86GCEHClauseKind::Catch,
            type_info: Some(ti),
            filter_fn: None,
            handler: Some("catch_handler".to_string()),
            is_catch_all: false,
        };
        let lp = state.lower_landingpad(vec![clause], false);
        assert_eq!(lp.clauses.len(), 1);
        assert!(!lp.is_cleanup);
    }

    #[test]
    fn test_lower_landingpad_catch_all() {
        let mut state = make_default_state();
        let clause = X86GCEHClause {
            kind: X86GCEHClauseKind::CatchAll,
            type_info: None,
            filter_fn: None,
            handler: None,
            is_catch_all: true,
        };
        let lp = state.lower_landingpad(vec![clause], true);
        assert_eq!(lp.clauses.len(), 1);
        assert!(lp.clauses[0].is_catch_all);
    }

    #[test]
    fn test_lower_resume() {
        let mut state = make_default_state();
        let resume = state.lower_resume(0);
        assert_eq!(resume.kind, X86GCEHLandingPadKind::Resume);
    }

    #[test]
    fn test_lower_cleanupret() {
        let mut state = make_default_state();
        let ret = state.lower_cleanupret(1, Some(2));
        assert_eq!(ret.kind, X86GCEHLandingPadKind::CleanupRet);
        assert!(ret.is_cleanup);
    }

    #[test]
    fn test_lower_catchret() {
        let mut state = make_default_state();
        let ret = state.lower_catchret(1, "continue.bb");
        assert_eq!(ret.kind, X86GCEHLandingPadKind::CatchRet);
    }

    #[test]
    fn test_lower_catchswitch() {
        let mut state = make_default_state();
        let cs = state.lower_catchswitch(&[10, 20], None);
        assert_eq!(cs.kind, X86GCEHLandingPadKind::CatchSwitch);
    }

    #[test]
    fn test_lower_catchpad() {
        let mut state = make_default_state();
        let pad = state.lower_catchpad(1, None);
        assert_eq!(pad.kind, X86GCEHLandingPadKind::CatchPad);
    }

    #[test]
    fn test_lower_cleanuppad() {
        let mut state = make_default_state();
        let pad = state.lower_cleanuppad();
        assert_eq!(pad.kind, X86GCEHLandingPadKind::CleanupPad);
        assert!(pad.is_cleanup);
    }

    // ================================================================
    // SEH Tests
    // ================================================================

    #[test]
    fn test_configure_c_specific_handler() {
        let mut state = X86GCEHFull::default();
        state.configure_c_specific_handler();
        assert_eq!(state.personality, X86GCEHPersonality::CSpecificHandler);
        assert!(state.emit_seh);
        assert!(!state.emit_dwarf_eh);
        assert!(state.personality_refs.contains("__C_specific_handler"));
    }

    #[test]
    fn test_configure_cxx_frame_handler3() {
        let mut state = X86GCEHFull::default();
        state.configure_cxx_frame_handler3();
        assert_eq!(state.personality, X86GCEHPersonality::CxxFrameHandler3);
        assert!(state.emit_seh);
        assert!(state.personality_refs.contains("__CxxFrameHandler3"));
    }

    #[test]
    fn test_lower_seh_filter() {
        let mut state = make_default_state();
        let filter =
            state.lower_seh_filter("my_filter", 0x4000, X86GCEHFilterAction::ExecuteHandler);
        assert_eq!(filter.name, "my_filter");
        assert_eq!(filter.address, 0x4000);
        assert_eq!(filter.filter_action, X86GCEHFilterAction::ExecuteHandler);
    }

    #[test]
    fn test_add_seh_scope() {
        let mut state = make_default_state();
        state.add_seh_scope(0x100, 0x200, Some("filter_fn"), 0x300);
        assert_eq!(state.call_site_table.len(), 1);
        assert!(state.personality_refs.contains("filter_fn"));
        let cs = &state.call_site_table[0];
        assert_eq!(cs.cs_start, 0x100);
        assert_eq!(cs.cs_length, 0x100);
        assert_eq!(cs.cs_lp, 0x300);
    }

    #[test]
    fn test_emit_seh_scope_table() {
        let mut state = make_default_state();
        state.add_seh_scope(0x100, 0x200, Some("filter_fn"), 0x300);
        state.add_seh_scope(0x300, 0x400, None, 0x500);
        let table = state.emit_seh_scope_table();
        // 4 bytes count + 2 * 16 bytes per scope = 36 bytes.
        assert_eq!(table.len(), 36);
    }

    // ================================================================
    // DWARF EH Tests
    // ================================================================

    #[test]
    fn test_build_dwarf_cie() {
        let mut state = make_default_state();
        let cie = state.build_dwarf_cie();
        assert_eq!(cie.version, 3);
        assert_eq!(cie.cie_id, 0);
        assert_eq!(cie.code_alignment_factor, 1);
        assert_eq!(cie.data_alignment_factor, -8);
        assert_eq!(cie.return_address_register, DW_RIP as u8);
        assert!(cie.augmentation.contains('z'));
        assert!(cie.augmentation.contains('L'));
        assert!(cie.augmentation.contains('P'));
        assert!(cie.augmentation.contains('R'));
    }

    #[test]
    fn test_serialize_cie() {
        let mut state = make_default_state();
        let cie = state.build_dwarf_cie();
        let bytes = X86GCEHFull::serialize_cie(&cie);
        assert!(!bytes.is_empty());
        // First 4 bytes are length, then CIE ID (4 bytes of zeros).
        assert_eq!(&bytes[4..8], &[0u8, 0, 0, 0]);
    }

    #[test]
    fn test_build_dwarf_fde() {
        let mut state = make_default_state();
        let fde = state.build_dwarf_fde(0x400000, 0x100, None);
        assert_eq!(fde.initial_location, 0x400000);
        assert_eq!(fde.address_range, 0x100);
    }

    #[test]
    fn test_serialize_fde() {
        let mut state = make_default_state();
        let fde = state.build_dwarf_fde(0x400000, 0x100, None);
        let bytes = X86GCEHFull::serialize_fde(&fde);
        assert!(!bytes.is_empty());
    }

    // ================================================================
    // Windows EH Tests
    // ================================================================

    #[test]
    fn test_build_unwind_info() {
        let mut state = make_default_state();
        let info = state.build_unwind_info();
        assert_eq!(info.version, 1);
        assert_eq!(info.flags, 1); // Has EH handler.
    }

    #[test]
    fn test_add_unwind_push_nonvol() {
        let mut state = make_default_state();
        state.add_unwind_push_nonvol(3, 1); // RBP at offset 1.
        assert_eq!(state.unwind_codes.len(), 1);
        let code = &state.unwind_codes[0];
        assert_eq!(code.unwind_op, X86GCEHUnwindOp::PushNonVol);
        assert_eq!(code.op_info, 3);
    }

    #[test]
    fn test_add_unwind_alloc_small() {
        let mut state = make_default_state();
        state.add_unwind_alloc_small(64, 2);
        let code = &state.unwind_codes[0];
        assert_eq!(code.unwind_op, X86GCEHUnwindOp::AllocSmall);
        assert_eq!(code.op_info, 64 / 8 - 1); // 7
    }

    #[test]
    fn test_serialize_unwind_info() {
        let mut state = make_default_state();
        state.add_unwind_push_nonvol(3, 1);
        let info = state.build_unwind_info();
        let bytes = X86GCEHFull::serialize_unwind_info(&info);
        assert!(!bytes.is_empty());
    }

    #[test]
    fn test_build_and_serialize_runtime_function() {
        let rf = X86GCEHFull::build_runtime_function(0x1000, 0x1200, 0x2000);
        assert_eq!(rf.begin_address, 0x1000);
        assert_eq!(rf.end_address, 0x1200);
        assert_eq!(rf.unwind_info, 0x2000);

        let bytes = X86GCEHFull::serialize_runtime_function(&rf);
        assert_eq!(bytes.len(), 12);
    }

    // ================================================================
    // EH Preparation Tests
    // ================================================================

    #[test]
    fn test_outline_landing_pads() {
        let mut state = make_default_state();
        state.lower_landingpad(vec![], true);
        state.lower_landingpad(vec![], false);
        state.outline_landing_pads();
        for pad in &state.landing_pads {
            assert!(pad.is_outlined);
        }
    }

    #[test]
    fn test_outline_landing_pads_disabled() {
        let mut state = make_default_state();
        state.outline_landing_pads = false;
        state.lower_landingpad(vec![], true);
        state.outline_landing_pads();
        assert!(!state.landing_pads[0].is_outlined);
    }

    #[test]
    fn test_prune_unreachable_handlers() {
        let mut state = make_default_state();
        let mut lp1 = state.lower_landingpad(vec![], true);
        lp1.is_unreachable = true;
        // Overwrite:
        state.landing_pads[0].is_unreachable = true;

        let pruned = state.prune_unreachable_handlers();
        assert_eq!(pruned.len(), 1);
    }

    #[test]
    fn test_is_catch_dead() {
        let state = make_default_state();
        // Currently always returns false (conservative).
        assert!(!state.is_catch_dead("std::bad_alloc"));
        assert!(!state.is_catch_dead("int"));
    }

    // ================================================================
    // EH Optimization Tests
    // ================================================================

    #[test]
    fn test_merge_identical_landing_pads() {
        let mut state = make_default_state();
        // Two cleanup-only pads.
        let pad1 = state.lower_cleanuppad();
        let pad2 = state.lower_cleanuppad();
        let merged = state.merge_identical_landing_pads();
        assert_eq!(merged, 1);
        assert_eq!(state.landing_pads.len(), 1);
        assert!(state.landing_pads[0].merged_from.contains(&pad2.id));
    }

    #[test]
    fn test_merge_identical_landing_pads_no_merge() {
        let mut state = make_default_state();
        let lp1 = state.lower_landingpad(vec![], true);
        let ti = X86GCEHTypeInfoEntry {
            encoding: 0,
            type_info_ptr: 0,
            type_name: "int".to_string(),
        };
        let lp2 = state.lower_landingpad(
            vec![X86GCEHClause {
                kind: X86GCEHClauseKind::Catch,
                type_info: Some(ti),
                filter_fn: None,
                handler: None,
                is_catch_all: false,
            }],
            false,
        );
        let merged = state.merge_identical_landing_pads();
        assert_eq!(merged, 0);
        assert_eq!(state.landing_pads.len(), 2);
    }

    #[test]
    fn test_merge_landing_pads_disabled() {
        let mut state = make_default_state();
        state.merge_landing_pads = false;
        state.lower_cleanuppad();
        state.lower_cleanuppad();
        let merged = state.merge_identical_landing_pads();
        assert_eq!(merged, 0);
    }

    #[test]
    fn test_remove_dead_catches() {
        let mut state = make_default_state();
        let ti = X86GCEHTypeInfoEntry {
            encoding: 0,
            type_info_ptr: 0,
            type_name: "std::bad_alloc".to_string(),
        };
        state.lower_landingpad(
            vec![X86GCEHClause {
                kind: X86GCEHClauseKind::Catch,
                type_info: Some(ti),
                filter_fn: None,
                handler: None,
                is_catch_all: false,
            }],
            false,
        );
        let removed = state.remove_dead_catches();
        // Currently is_catch_dead is conservative, returns 0.
        assert_eq!(removed, 0);
    }

    #[test]
    fn test_deduplicate_call_sites() {
        let mut state = make_default_state();
        state.call_site_table.push(X86GCEHCallSiteEntry {
            cs_start: 0,
            cs_length: 4,
            cs_lp: 1,
            cs_action: 0,
        });
        state.call_site_table.push(X86GCEHCallSiteEntry {
            cs_start: 4,
            cs_length: 4,
            cs_lp: 1,
            cs_action: 0,
        });
        state.call_site_table.push(X86GCEHCallSiteEntry {
            cs_start: 8,
            cs_length: 4,
            cs_lp: 2,
            cs_action: 1,
        });
        assert_eq!(state.call_site_table.len(), 3);
        state.deduplicate_call_sites();
        assert_eq!(state.call_site_table.len(), 2);
        assert_eq!(state.call_site_table[0].cs_length, 8);
    }

    // ================================================================
    // Personality Tests
    // ================================================================

    #[test]
    fn test_personality_symbol_names() {
        assert_eq!(
            X86GCEHPersonality::GxxV0.symbol_name(),
            "__gxx_personality_v0"
        );
        assert_eq!(
            X86GCEHPersonality::GccV0.symbol_name(),
            "__gcc_personality_v0"
        );
        assert_eq!(
            X86GCEHPersonality::CxxFrameHandler3.symbol_name(),
            "__CxxFrameHandler3"
        );
        assert_eq!(
            X86GCEHPersonality::CSpecificHandler.symbol_name(),
            "__C_specific_handler"
        );
        assert_eq!(
            X86GCEHPersonality::ObjCV0.symbol_name(),
            "__objc_personality_v0"
        );
        assert_eq!(
            X86GCEHPersonality::GxxSeh0.symbol_name(),
            "__gxx_personality_seh0"
        );
        assert_eq!(X86GCEHPersonality::None.symbol_name(), "");
    }

    #[test]
    fn test_is_itanium() {
        assert!(X86GCEHPersonality::GxxV0.is_itanium());
        assert!(X86GCEHPersonality::GccV0.is_itanium());
        assert!(X86GCEHPersonality::ObjCV0.is_itanium());
        assert!(!X86GCEHPersonality::CxxFrameHandler3.is_itanium());
        assert!(!X86GCEHPersonality::CSpecificHandler.is_itanium());
    }

    #[test]
    fn test_is_seh() {
        assert!(X86GCEHPersonality::CxxFrameHandler3.is_seh());
        assert!(X86GCEHPersonality::CSpecificHandler.is_seh());
        assert!(X86GCEHPersonality::GxxSeh0.is_seh());
        assert!(!X86GCEHPersonality::GxxV0.is_seh());
    }

    #[test]
    fn test_personality_gxx_v0() {
        let mut state = X86GCEHFull::default();
        state.personality_gxx_v0();
        assert_eq!(state.personality, X86GCEHPersonality::GxxV0);
        assert!(state.emit_dwarf_eh);
        assert!(!state.emit_seh);
        assert!(state.personality_refs.contains("__gxx_personality_v0"));
    }

    #[test]
    fn test_personality_gcc_v0() {
        let mut state = X86GCEHFull::default();
        state.personality_gcc_v0();
        assert_eq!(state.personality, X86GCEHPersonality::GccV0);
    }

    #[test]
    fn test_personality_cxx_frame_handler3() {
        let mut state = X86GCEHFull::default();
        state.personality_cxx_frame_handler3();
        assert_eq!(state.personality, X86GCEHPersonality::CxxFrameHandler3);
        assert!(state.emit_seh);
    }

    #[test]
    fn test_personality_c_specific_handler() {
        let mut state = X86GCEHFull::default();
        state.personality_c_specific_handler();
        assert_eq!(state.personality, X86GCEHPersonality::CSpecificHandler);
    }

    #[test]
    fn test_personality_objc_v0() {
        let mut state = X86GCEHFull::default();
        state.personality_objc_v0();
        assert_eq!(state.personality, X86GCEHPersonality::ObjCV0);
    }

    #[test]
    fn test_personality_gxx_seh0() {
        let mut state = X86GCEHFull::default();
        state.personality_gxx_seh0();
        assert_eq!(state.personality, X86GCEHPersonality::GxxSeh0);
        assert!(state.is_mingw);
        assert!(state.emit_seh);
    }

    #[test]
    fn test_get_personality_config_gxx() {
        let mut state = X86GCEHFull::default();
        state.personality_gxx_v0();
        let cfg = state.get_personality_config();
        assert_eq!(cfg.exc_ptr_reg, DW_RAX);
        assert_eq!(cfg.selector_reg, DW_RDX);
        assert!(cfg.handles_foreign);
        assert!(cfg.uses_two_phase);
        assert!(!cfg.cleanups_in_phase1);
    }

    #[test]
    fn test_get_personality_config_cxxframe() {
        let mut state = X86GCEHFull::default();
        state.personality_cxx_frame_handler3();
        let cfg = state.get_personality_config();
        assert!(cfg.cleanups_in_phase1);
        assert!(cfg.handles_foreign);
    }

    // ================================================================
    // Exception Pointer Tests
    // ================================================================

    #[test]
    fn test_get_eh_return_data_regno() {
        assert_eq!(X86GCEHFull::get_eh_return_data_regno(0), Some(DW_RAX));
        assert_eq!(X86GCEHFull::get_eh_return_data_regno(1), Some(DW_RDX));
        assert_eq!(X86GCEHFull::get_eh_return_data_regno(2), None);
        assert_eq!(X86GCEHFull::get_eh_return_data_regno(42), None);
    }

    #[test]
    fn test_extract_exception_pointer() {
        let mut state = X86GCEHFull::default();
        state.personality_gxx_v0();
        assert_eq!(state.extract_exception_pointer(), DW_RAX);
    }

    #[test]
    fn test_extract_selector() {
        let mut state = X86GCEHFull::default();
        state.personality_gxx_v0();
        assert_eq!(state.extract_selector(), DW_RDX);
    }

    #[test]
    fn test_lower_eh_extract_values() {
        let state = X86GCEHFull::default();
        let (exc_ptr, selector) = state.lower_eh_extract_values(0);
        assert!(matches!(
            exc_ptr.location,
            X86GCEHRootLocation::Register(DW_RAX)
        ));
        assert!(matches!(
            selector.location,
            X86GCEHRootLocation::Register(DW_RDX)
        ));
    }

    // ================================================================
    // Stack Map Tests
    // ================================================================

    #[test]
    fn test_build_stack_map_record() {
        let state = make_default_state();
        let roots = vec![X86GCEHRoot {
            kind: X86GCEHRootKind::ObjectPointer,
            location: X86GCEHRootLocation::Register(DW_RAX),
            is_derived: false,
            derived_offset: 0,
            is_live: true,
            description: "rax".to_string(),
        }];
        let stack_slots = vec![X86GCEHStackSlot {
            offset: -8,
            size: 8,
            is_derived: false,
            is_live: true,
            name: "slot1".to_string(),
        }];

        let record = state.build_stack_map_record(1, 0x100, &roots, &stack_slots);
        assert_eq!(record.id, 1);
        assert_eq!(record.num_locations, 2);
        assert_eq!(record.num_live_outs, 1);
        assert_eq!(record.live_outs[0].dwarf_reg, DW_RAX);
    }

    #[test]
    fn test_emit_function_stack_map() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");
        state.lower_gc_statepoint(Some("bar"), 0, &[], X86GCEHGCTransition::Relocation, &[], 0);
        state.emit_function_stack_map();
        assert!(!state.stack_map_buffer.is_empty());
    }

    #[test]
    fn test_finalize_stack_map_section() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");
        state.lower_gc_statepoint(None, 0, &[], X86GCEHGCTransition::Safepoint, &[], 0);
        state.emit_function_stack_map();
        let section = state.finalize_stack_map_section();
        assert_eq!(section[0], 3); // Version.
        assert_eq!(section[1], 0); // Reserved.
        assert_eq!(section[2], 0); // Reserved.
        assert_eq!(section[3], 0); // Reserved.
    }

    // ================================================================
    // Patchpoint Tests
    // ================================================================

    #[test]
    fn test_lower_llvm_patchpoint() {
        let mut state = make_default_state();
        let pp = state.lower_llvm_patchpoint(0, 16, 2, 0x5000, 2, 0x1234);
        assert_eq!(pp.flags, 0);
        assert_eq!(pp.num_bytes, 16);
        assert_eq!(pp.num_args, 2);
        assert_eq!(pp.callee, 0x5000);
        assert_eq!(pp.num_patch_args, 2);
        assert!(pp.stack_map_id.is_some());
    }

    #[test]
    fn test_build_patchpoint_nop_sled() {
        let sled = X86GCEHFull::build_patchpoint_nop_sled(16);
        assert_eq!(sled.len(), 16);
        // Should be a valid nop sequence.
        for &byte in &sled {
            // All nop bytes should be recognizable X86 nop forms.
            assert!(
                byte == 0x90
                    || byte == 0x66
                    || byte == 0x0F
                    || byte == 0x1F
                    || byte == 0x00
                    || byte == 0x40
                    || byte == 0x44
                    || byte == 0x80
                    || byte == 0x84,
                "unexpected nop byte: 0x{:02X}",
                byte
            );
        }
    }

    #[test]
    fn test_build_patchpoint_nop_sled_odd_size() {
        let sled = X86GCEHFull::build_patchpoint_nop_sled(7);
        assert_eq!(sled.len(), 7);
    }

    #[test]
    fn test_build_patchpoint_nop_sled_small() {
        let sled = X86GCEHFull::build_patchpoint_nop_sled(2);
        assert_eq!(sled.len(), 2);
        assert_eq!(sled, vec![0x66, 0x90]);
    }

    // ================================================================
    // LSDA Tests
    // ================================================================

    #[test]
    fn test_build_lsda() {
        let mut state = make_default_state();
        state.lower_landingpad(vec![], true);
        let lsda = state.build_lsda();
        assert!(lsda.gcc_except_table);
    }

    #[test]
    fn test_encode_lsda() {
        let mut state = make_default_state();
        state.lower_landingpad(vec![], true);
        let encoded = state.encode_lsda();
        assert!(!encoded.is_empty());
        // First byte: LP base encoding (0xFF = omit).
        assert_eq!(encoded[0], 0xFF);
        // Second byte: TT encoding (0xFF = omit).
        assert_eq!(encoded[1], 0xFF);
    }

    // ================================================================
    // ULEB/SLEB Tests
    // ================================================================

    #[test]
    fn test_uleb128_zero() {
        assert_eq!(uleb128(0), vec![0]);
    }

    #[test]
    fn test_uleb128_small() {
        assert_eq!(uleb128(1), vec![1]);
        assert_eq!(uleb128(127), vec![127]);
    }

    #[test]
    fn test_uleb128_large() {
        assert_eq!(uleb128(128), vec![0x80, 0x01]);
        assert_eq!(uleb128(16383), vec![0xFF, 0x7F]);
    }

    #[test]
    fn test_sleb128_zero() {
        assert_eq!(sleb128(0), vec![0]);
    }

    #[test]
    fn test_sleb128_positive() {
        assert_eq!(sleb128(1), vec![1]);
        assert_eq!(sleb128(64), vec![0xC0, 0x00]);
    }

    #[test]
    fn test_sleb128_negative() {
        assert_eq!(sleb128(-1), vec![0x7F]);
        assert_eq!(sleb128(-64), vec![0x40]);
    }

    #[test]
    fn test_decode_uleb128() {
        let encoded = uleb128(300);
        let (value, consumed) = decode_uleb128(&encoded).unwrap();
        assert_eq!(value, 300);
        assert_eq!(consumed, encoded.len());
    }

    #[test]
    fn test_decode_uleb128_zero() {
        let (value, consumed) = decode_uleb128(&[0]).unwrap();
        assert_eq!(value, 0);
        assert_eq!(consumed, 1);
    }

    #[test]
    fn test_decode_uleb128_invalid() {
        // Should detect overflow (too many bytes).
        let overflow = [0x80u8; 20];
        assert!(decode_uleb128(&overflow).is_none());
    }

    // ================================================================
    // CFA / Return Address Tests
    // ================================================================

    #[test]
    fn test_compute_cfa() {
        let cfa = compute_cfa(0x7FFFFFFF0, 0x40);
        assert_eq!(cfa, 0x7FFFFFFF0 + 0x40);
    }

    #[test]
    fn test_compute_return_address_location() {
        let cfa = 0x7FFFFFFF0;
        let ra = compute_return_address_location(cfa);
        assert_eq!(ra, cfa - 8);
    }

    // ================================================================
    // Call GC Strategy Tests
    // ================================================================

    #[test]
    fn test_call_may_trigger_gc_statepoint() {
        let state = make_linux_gc_state();
        // Non-leaf call can trigger GC in statepoint mode.
        // "malloc" is NOT in the gc_leaves list.
        assert!(state.call_may_trigger_gc("malloc"));
    }

    #[test]
    fn test_call_may_trigger_gc_leaf() {
        let state = make_linux_gc_state();
        // memcpy IS in the gc_leaves list.
        assert!(!state.call_may_trigger_gc("memcpy"));
    }

    #[test]
    fn test_call_may_trigger_gc_coreclr() {
        let state = X86GCEHFullBuilder::new()
            .gc_strategy(X86GCEHStrategy::CoreCLR)
            .build();
        // Not set up with uses_gc, so after construction:
        let mut s = state;
        s.uses_gc = true;
        assert!(s.call_may_trigger_gc("JIT_New"));
        assert!(!s.call_may_trigger_gc("printf"));
    }

    #[test]
    fn test_call_may_trigger_gc_no_gc() {
        let mut state = X86GCEHFull::default();
        state.uses_gc = false;
        assert!(!state.call_may_trigger_gc("malloc"));
    }

    // ================================================================
    // Builder Tests
    // ================================================================

    #[test]
    fn test_builder_defaults() {
        let state = X86GCEHFullBuilder::new().build();
        assert_eq!(state.gc_strategy, X86GCEHStrategy::Statepoint);
        assert_eq!(state.personality, X86GCEHPersonality::GxxV0);
    }

    #[test]
    fn test_builder_custom() {
        let state = X86GCEHFullBuilder::new()
            .gc_strategy(X86GCEHStrategy::OCaml)
            .personality(X86GCEHPersonality::ObjCV0)
            .target_triple("x86_64-apple-darwin")
            .safepoints_at_backedges(false)
            .safepoints_at_calls(false)
            .emit_dwarf_eh(true)
            .emit_seh(false)
            .outline_landing_pads(false)
            .merge_landing_pads(false)
            .prune_unreachable_handlers(false)
            .build();

        assert_eq!(state.gc_strategy, X86GCEHStrategy::OCaml);
        assert_eq!(state.personality, X86GCEHPersonality::ObjCV0);
        assert_eq!(state.target_triple, "x86_64-apple-darwin");
        assert!(!state.safepoints_at_backedges);
        assert!(!state.safepoints_at_calls);
        assert!(!state.outline_landing_pads);
        assert!(!state.merge_landing_pads);
        assert!(!state.prune_unreachable_handlers);
    }

    // ================================================================
    // Pipeline Tests
    // ================================================================

    #[test]
    fn test_run_pipeline_gc_only() {
        let mut state = X86GCEHFullBuilder::new()
            .gc_strategy(X86GCEHStrategy::Statepoint)
            .personality(X86GCEHPersonality::None)
            .build();
        state.begin_function("gc_test", true, false);
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");
        state.run_pipeline();
        // No errors.
    }

    #[test]
    fn test_run_pipeline_eh_only() {
        let mut state = X86GCEHFullBuilder::new()
            .gc_strategy(X86GCEHStrategy::None)
            .personality(X86GCEHPersonality::GxxV0)
            .build();
        state.begin_function("eh_test", false, true);
        state.lower_landingpad(vec![], true);
        state.run_pipeline();
        // No errors.
    }

    #[test]
    fn test_run_pipeline_both() {
        let mut state = make_linux_gc_state();
        state.begin_function("full_test", true, true);
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");
        state.lower_landingpad(vec![], true);
        state.run_pipeline();
    }

    #[test]
    fn test_summary() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");
        let summary = state.summary();
        assert!(summary.contains("X86GCEHFull"));
        assert!(summary.contains("test_fn"));
        assert!(summary.contains("Statepoint"));
        assert!(summary.contains("__gxx_personality_v0"));
    }

    #[test]
    fn test_validate_ok() {
        let mut state = make_default_state();
        state.uses_gc = true;
        state.gc_strategy = X86GCEHStrategy::Statepoint;
        state.uses_eh = true;
        state.personality = X86GCEHPersonality::GxxV0;
        assert!(state.validate().is_ok());
    }

    #[test]
    fn test_validate_no_gc_strategy() {
        let mut state = make_default_state();
        state.uses_gc = true;
        state.gc_strategy = X86GCEHStrategy::None;
        let result = state.validate();
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("no GC strategy"));
    }

    #[test]
    fn test_validate_no_personality() {
        let mut state = make_default_state();
        state.uses_eh = true;
        state.personality = X86GCEHPersonality::None;
        let result = state.validate();
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("no personality"));
    }

    // ================================================================
    // Display Tests
    // ================================================================

    #[test]
    fn test_display_x86_full() {
        let state = make_default_state();
        let s = format!("{}", state);
        assert!(s.contains("X86GCEHFull"));
        assert!(s.contains("test_fn"));
        assert!(s.contains("Statepoint"));
    }

    #[test]
    fn test_display_landing_pad() {
        let lp = X86GCEHLandingPad {
            id: 1,
            kind: X86GCEHLandingPadKind::LandingPad,
            exc_ptr_reg: DW_RAX,
            filter_ptr_reg: DW_RDX,
            clauses: vec![],
            is_cleanup: true,
            is_unreachable: false,
            is_outlined: false,
            call_site_entries: vec![],
            merged_from: vec![],
        };
        let s = format!("{}", lp);
        assert!(s.contains("LandingPad"));
        assert!(s.contains("cleanup=true"));
    }

    #[test]
    fn test_display_statepoint() {
        let sp = X86GCEHStatepoint {
            id: 42,
            pc_offset: 0,
            stack_map_id: 7,
            call_target: Some("foo".to_string()),
            num_call_args: 3,
            flags: 0,
            num_deopt_bytes: 0,
            deopt_state: vec![],
            gc_transition: X86GCEHGCTransition::Relocation,
            num_roots: 5,
            roots: vec![],
            stack_slots: vec![],
        };
        let s = format!("{}", sp);
        assert!(s.contains("Statepoint"));
        assert!(s.contains("42"));
    }

    #[test]
    fn test_display_stack_map() {
        let sm = X86GCEHStackMapRecord {
            id: 1,
            function_address: 0,
            instruction_offset: 0,
            num_locations: 10,
            locations: vec![],
            num_live_outs: 3,
            live_outs: vec![],
            padding: 0,
        };
        let s = format!("{}", sm);
        assert!(s.contains("StackMap"));
        assert!(s.contains("locs=10"));
    }

    // ================================================================
    // GC Strategy Display Tests
    // ================================================================

    #[test]
    fn test_gc_strategy_display() {
        assert_eq!(
            format!("{}", X86GCEHStrategy::Statepoint),
            "statepoint-example"
        );
        assert_eq!(format!("{}", X86GCEHStrategy::CoreCLR), "coreclr");
        assert_eq!(format!("{}", X86GCEHStrategy::OCaml), "ocaml");
        assert_eq!(format!("{}", X86GCEHStrategy::Erlang), "erlang");
        assert_eq!(format!("{}", X86GCEHStrategy::ShadowStack), "shadow-stack");
        assert_eq!(format!("{}", X86GCEHStrategy::Custom), "custom");
        assert_eq!(format!("{}", X86GCEHStrategy::None), "none");
    }

    // ================================================================
    // Safepoint Kind Display Tests
    // ================================================================

    #[test]
    fn test_safepoint_kind_display() {
        assert_eq!(format!("{}", X86GCEHSafepointKind::PreCall), "pre-call");
        assert_eq!(format!("{}", X86GCEHSafepointKind::PostCall), "post-call");
        assert_eq!(
            format!("{}", X86GCEHSafepointKind::LoopBackedge),
            "loop-backedge"
        );
        assert_eq!(format!("{}", X86GCEHSafepointKind::FunctionEntry), "entry");
        assert_eq!(
            format!("{}", X86GCEHSafepointKind::FunctionReturn),
            "return"
        );
        assert_eq!(format!("{}", X86GCEHSafepointKind::Poll), "poll");
        assert_eq!(
            format!("{}", X86GCEHSafepointKind::MachineSafepoint),
            "machine"
        );
    }

    // ================================================================
    // Root Location Display Tests
    // ================================================================

    #[test]
    fn test_root_location_display() {
        assert_eq!(
            format!("{}", X86GCEHRootLocation::Register(DW_RAX)),
            "reg(D0)"
        );
        assert_eq!(format!("{}", X86GCEHRootLocation::StackOffset(-8)), "bp-8");
        assert_eq!(
            format!("{}", X86GCEHRootLocation::StackSPOffset(16)),
            "sp+16"
        );
        assert_eq!(
            format!("{}", X86GCEHRootLocation::FixedAddress(0xDEADBEEF)),
            "addr(0xdeadbeef)"
        );
        assert_eq!(format!("{}", X86GCEHRootLocation::Unknown), "unknown");
    }

    // ================================================================
    // Augmentation Parser Tests
    // ================================================================

    #[test]
    fn test_augmentation_parse_full() {
        let aug = X86GCEHAugmentation::parse("zLPRSBG");
        assert!(aug.has_aug_length);
        assert!(aug.has_lsda);
        assert!(aug.has_personality);
        assert!(aug.has_fde_encoding);
        assert!(aug.is_signal_frame);
        assert!(aug.is_bfd_cie);
        assert!(aug.is_gnu);
    }

    #[test]
    fn test_augmentation_parse_empty() {
        let aug = X86GCEHAugmentation::parse("");
        assert!(!aug.has_aug_length);
        assert!(!aug.has_lsda);
        assert!(!aug.has_personality);
    }

    #[test]
    fn test_augmentation_parse_unknown() {
        let aug = X86GCEHAugmentation::parse("zRxy");
        assert!(aug.has_aug_length);
        assert!(aug.has_fde_encoding);
        assert!(!aug.has_lsda);
    }

    #[test]
    fn test_augmentation_to_string() {
        let aug = X86GCEHAugmentation {
            has_aug_length: true,
            has_lsda: true,
            has_personality: true,
            has_fde_encoding: true,
            is_signal_frame: false,
            is_bfd_cie: false,
            is_gnu: false,
        };
        assert_eq!(aug.to_string(), "zLPR");
    }

    // ================================================================
    // UnwindOp Tests
    // ================================================================

    #[test]
    fn test_unwind_op_from_u8() {
        assert_eq!(
            X86GCEHUnwindOp::from_u8(0),
            Some(X86GCEHUnwindOp::PushNonVol)
        );
        assert_eq!(X86GCEHUnwindOp::from_u8(3), Some(X86GCEHUnwindOp::SetFPReg));
        assert_eq!(
            X86GCEHUnwindOp::from_u8(10),
            Some(X86GCEHUnwindOp::PushMachFrame)
        );
        assert_eq!(
            X86GCEHUnwindOp::from_u8(0x1E),
            Some(X86GCEHUnwindOp::SetMxcsr)
        );
        assert_eq!(X86GCEHUnwindOp::from_u8(99), None);
    }

    // ================================================================
    // Edge Cases
    // ================================================================

    #[test]
    fn test_empty_function() {
        let mut state = make_default_state();
        state.run_pipeline();
        assert!(state.stack_maps.is_empty());
        assert!(state.landing_pads.is_empty());
    }

    #[test]
    fn test_many_roots() {
        let mut state = make_default_state();
        for i in 0..100 {
            let reg = (DW_RAX + i as u16) % 16;
            state.register_root(
                reg,
                X86GCEHRootKind::ObjectPointer,
                false,
                0,
                &format!("root_{}", i),
            );
        }
        let roots = state.enumerate_live_roots();
        assert_eq!(roots.len(), 100);
    }

    #[test]
    fn test_many_safepoints() {
        let mut state = make_default_state();
        for i in 0..50 {
            state.insert_loop_backedge_safepoint(i * 10);
            state.insert_pre_call_safepoint(i * 10 + 5);
        }
        assert_eq!(state.safepoints.len(), 100);
    }

    #[test]
    fn test_many_landing_pads() {
        let mut state = make_default_state();
        for i in 0..20 {
            state.lower_landingpad(vec![], true);
        }
        assert_eq!(state.landing_pads.len(), 20);
    }

    #[test]
    fn test_replace_with_relocated() {
        let mut state = make_default_state();
        let reloc = state.replace_with_relocated(DW_RAX, 42);
        assert_eq!(reloc.statepoint_id, 42);
        assert_eq!(reloc.base_offset, DW_RAX as u32);
    }

    #[test]
    fn test_gc_transition_enum() {
        assert_eq!(X86GCEHGCTransition::None as u32, 0); // Derives are at front.
                                                         // Just verify the enum variants exist.
        let _ = X86GCEHGCTransition::None;
        let _ = X86GCEHGCTransition::Safepoint;
        let _ = X86GCEHGCTransition::Relocation;
        let _ = X86GCEHGCTransition::Deopt;
    }

    #[test]
    fn test_suspension_enum() {
        assert_eq!(
            format!("{}", X86GCEHSuspension::default()),
            "polling" // Default.
        );
    }

    #[test]
    fn test_call_compute_gc_roots() {
        let mut state = make_default_state();
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "rax");
        state.register_root(DW_RDI, X86GCEHRootKind::ObjectPointer, false, 0, "rdi");
        let roots = state.compute_call_gc_roots("malloc");
        assert_eq!(roots.len(), 2);
    }

    #[test]
    fn test_exception_pointer_regs_x86_32() {
        let regs = X86GCEHExceptionPointerRegs::for_x86_32();
        assert_eq!(regs.exception_pointer_reg, 0);
        assert_eq!(regs.selector_reg, 1);
    }

    #[test]
    fn test_exception_pointer_regs_x86_64() {
        let regs = X86GCEHExceptionPointerRegs::for_x86_64();
        assert_eq!(regs.exception_pointer_reg, DW_RAX);
        assert_eq!(regs.selector_reg, DW_RDX);
    }

    // ================================================================
    // Stress / Integration Tests
    // ================================================================

    #[test]
    fn test_full_gc_eh_pipeline_integration() {
        let mut state = make_linux_gc_state();
        state.begin_function("integrated_test", true, true);

        // Set up GC roots.
        state.register_root(DW_RAX, X86GCEHRootKind::ObjectPointer, false, 0, "obj_ptr");
        state.register_root(
            DW_R12,
            X86GCEHRootKind::DerivedPointer,
            true,
            8,
            "derived_ptr",
        );
        state.register_stack_root(-8, 8, false, "local_root");
        state.register_stack_root(-16, 8, true, "local_derived");

        // Insert statepoint (rewrites a call).
        let _sp = state.lower_gc_statepoint(
            Some("allocate"),
            2,
            &[],
            X86GCEHGCTransition::Relocation,
            &[0xAA, 0xBB],
            0x01,
        );

        // Insert safepoints.
        state.insert_entry_safepoint(0);
        state.insert_loop_backedge_safepoint(0x40);
        state.insert_pre_call_safepoint(0x80);

        // Lower EH.
        state.personality_gxx_v0();
        let ti_std = X86GCEHTypeInfoEntry {
            encoding: 0,
            type_info_ptr: 0xDEAD,
            type_name: "std::exception".to_string(),
        };
        let _lp = state.lower_landingpad(
            vec![
                X86GCEHClause {
                    kind: X86GCEHClauseKind::Catch,
                    type_info: Some(ti_std),
                    filter_fn: None,
                    handler: Some("catch_h".to_string()),
                    is_catch_all: false,
                },
                X86GCEHClause {
                    kind: X86GCEHClauseKind::Cleanup,
                    type_info: None,
                    filter_fn: None,
                    handler: None,
                    is_catch_all: false,
                },
            ],
            true,
        );

        // Run optimization passes.
        state.outline_landing_pads();
        state.deduplicate_call_sites();
        let _pruned = state.prune_unreachable_handlers();

        // Validate.
        assert!(state.validate().is_ok());
    }

    #[test]
    fn test_windows_full_pipeline() {
        let mut state = make_windows_eh_state();
        state.begin_function("windows_test", false, true);

        // Configure Windows EH.
        state.configure_cxx_frame_handler3();

        // Add SEH scopes.
        state.add_seh_scope(0x100, 0x200, Some("__except_filter"), 0x300);
        state.add_seh_scope(0x240, 0x2A0, None, 0x350); // __finally

        // Emit scope table.
        let _table = state.emit_seh_scope_table();

        // Build unwind info with codes.
        state.add_unwind_push_nonvol(DW_RBP as u8, 1);
        state.add_unwind_alloc_small(32, 2);
        state.add_unwind_set_fp(3);

        let unwind_info = state.build_unwind_info();
        assert_eq!(unwind_info.count_of_codes, 3);

        let serialized = X86GCEHFull::serialize_unwind_info(&unwind_info);
        assert!(!serialized.is_empty());

        // Emit .pdata entry.
        state.emit_pdata_entry(0x1000, 0x1200, 0x2000);
        assert!(!state.pdata_buffer.is_empty());
    }

    #[test]
    fn test_dwarf_full_pipeline() {
        let mut state = make_linux_gc_state();
        state.begin_function("dwarf_test", false, true);
        state.personality_gxx_v0();
        state.lower_landingpad(vec![], true);

        // Build and serialize CIE/FDE.
        let _cie = state.build_dwarf_cie();
        state.emit_dwarf_eh_frame();

        let fde = state.build_dwarf_fde(0x400000, 0x200, None);
        let fde_bytes = X86GCEHFull::serialize_fde(&fde);
        assert!(!fde_bytes.is_empty());

        // Encode LSDA.
        let _lsda_bytes = state.encode_lsda();
    }
}