llvm-native-core 0.1.10

//! X86 Patchable Instructions — patchable function entry, patchable calls,
//! patchable branches, patchable constants, patchpoint/stackmap integration,
//! and deoptimization support for the X86/X86-64 architecture family.
//!
//! This module provides a complete implementation of the LLVM "patchable"
//! infrastructure: instructions that carry reserved NOP space for runtime
//! patching by JIT compilers, dynamic optimizers, and deoptimization
//! frameworks. The design follows the `patchable-function`, `patchable-*`,
//! `patchpoint`, `stackmap`, `statepoint`, and deoptimization conventions
//! used by managed runtimes (JVM, .NET, V8, LuaJIT) and profile-guided
//! optimization systems.
//!
//! ## Module Organization
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────────────┐
//! │                       X86 Patchable Instructions                         │
//! │  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────────────┐  │
//! │  │  PatchableEntry  │  │  PatchableCall   │  │  PatchableBranch     │  │
//! │  │  NOP sled before │  │  5-byte NOP      │  │  NOP before          │  │
//! │  │  function (pro-  │  │  before CALL for │  │  conditional/uncond  │  │
//! │  │  logue-reserved) │  │  hot-patching    │  │  branches (trace     │  │
//! │  │                  │  │  (trace points)  │  │  stitching, PGO)     │  │
//! │  └──────────────────┘  └──────────────────┘  └───────────────────────┘  │
//! │  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────────────┐  │
//! │  │  PatchableConst  │  │  PatchPoint /    │  │  Deoptimization      │  │
//! │  │  MOV-immediate   │  │  StackMap        │  │  Bundle, register    │  │
//! │  │  with reserved   │  │  integration     │  │  restore, frame      │  │
//! │  │  patch space      │  │  (JIT compilers) │  │  reconstruction      │  │
//! │  └──────────────────┘  └──────────────────┘  └───────────────────────┘  │
//! └─────────────────────────────────────────────────────────────────────────┘
//! ```
//!
//! ## Patchable Function Entry
//!
//! The "patchable-function" attribute reserves N bytes of NOP sled at the
//! function entry point. This enables:
//!
//! - **Hot-patching**: Replacing the function prologue with a JMP to an
//!   optimized version at runtime (used by Windows hot-patching, Linux
//!   ftrace/kpatch/livepatch, and managed runtimes).
//! - **Instrumentation**: Inserting tracing/profiling hooks without
//!   recompilation (e.g., `-pg` / `-mfentry` equivalent).
//! - **Function multi-versioning**: Patching dispatch logic at the
//!   function entry for dynamic ISA selection (AVX2 vs AVX-512, etc.).
//!
//! The NOP sled size is configurable; typical values are 2 (Windows x64
//! hot-patch), 5 (Linux ftrace 5-byte NOP), 11 (prologue + 11-byte NOP
//! for full prologue replacement), or 16 (cache-line-aligned stub).
//!
//! ## Patchable Calls
//!
//! A 5-byte NOP before each CALL instruction allows the runtime to
//! redirect the call to a different target:
//!
//! - **JIT compilation**: Replacing interpreted stubs with compiled
//!   method bodies (V8/TurboFan, HotSpot C1/C2, .NET RyuJIT).
//! - **Dynamic deoptimization**: Switching from optimized code back to
//!   the interpreter when speculative assumptions are violated.
//! - **Trace stitching**: Connecting JIT-compiled traces at runtime
//!   without full recompilation.
//!
//! ## Patchable Branches
//!
//! Reserved NOP space before conditional and unconditional branches:
//!
//! - **Profile-guided optimization (PGO)**: Reversing branch direction
//!   when runtime profiles contradict static heuristics.
//! - **Trace stitching**: Redirecting side-exits in JIT traces.
//! - **Guard insertion**: Adding speculative guards in JIT compilers.
//!
//! ## Patchable Constants
//!
//! MOV-immediate instructions with reserved patch space for runtime
//! value replacement:
//!
//! - **Constant pool patching**: Updating embedded constants without
//!   recompiling the containing function.
//! - **Security mitigations**: Randomizing embedded constants for ASLR.
//! - **Feature flags**: Enabling/disabling code paths at runtime.
//!
//! ## PatchPoint / StackMap Integration
//!
//! PatchPoints are call-like instructions that record the live state
//! at a program point, enabling:
//!
//! - **On-stack replacement (OSR)**: Switching from interpreted to
//!   compiled code mid-execution.
//! - **Deoptimization**: Transferring control from optimized code
//!   back to the interpreter with full frame reconstruction.
//! - **Garbage collection**: Recording GC roots (live references) at
//!   safe points for precise GC.
//!
//! StackMaps record the location of every live value (register or stack
//! slot) at each PatchPoint, enabling the runtime to walk the stack
//! and reconstruct interpreter frames.
//!
//! ## Deoptimization
//!
//! When speculative optimizations fail (e.g., a monomorphic inline
//! cache encounters an unexpected type), the optimized code must
//! transfer control to a deoptimization handler that:
//!
//! 1. Saves all live registers.
//! 2. Reconstructs the interpreter frame from the stackmap.
//! 3. Transfers control to the interpreter at the correct bytecode
//!    offset.
//!
//! ## Clean-room reconstruction from:
//!
//! - Intel® 64 and IA-32 Architectures Software Developer's Manual
//!   (volumes 1, 2A, 2B, 2C, 2D, 3A, 3B, 3C, 3D)
//! - System V ABI: AMD64 Architecture Processor Supplement
//! - Microsoft x64 Software Conventions
//! - LLVM StackMap and PatchPoint documentation (llvm.org/docs/StackMaps.html)
//! - LLVM Statepoints documentation (llvm.org/docs/Statepoints.html)
//! - Intel® 64 and IA-32 Architectures Optimization Reference Manual
//!   (Order #: 248966)
//! - Agner Fog's microarchitecture documentation
//! - Self, Strongtalk, and HotSpot deoptimization literature
//!   (Hölzle, Chambers, Ungar — Debugging Optimized Code with Dynamic
//!   Deoptimization, PLDI 1992)
//!
//! Zero LLVM source code consultation. All behavior reconstructed from
//! published specifications, oracle interrogation, and academic literature.

#![allow(non_upper_case_globals, dead_code)]

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

// ============================================================================
// Core types
// ============================================================================

/// The primary structure encapsulating all patchable-instruction logic for
/// X86/X86-64 targets.
#[derive(Debug, Clone)]
pub struct X86PatchableInstr {
    /// Target triple (e.g., "x86_64-unknown-linux-gnu").
    pub target_triple: String,
    /// Whether targeting 64-bit mode.
    pub is_64bit: bool,
    /// Configuration for patchable instruction generation.
    pub config: PatchableConfig,
    /// Accumulated statistics.
    pub stats: PatchableStats,
    /// StackMap records indexed by PatchPoint ID.
    pub stackmaps: HashMap<u64, StackMapRecord>,
    /// Deoptimization bundles indexed by deopt ID.
    pub deopt_bundles: HashMap<u64, DeoptBundle>,
    /// Live set of known patchable entry functions.
    pub patched_functions: HashSet<String>,
}

/// Configuration controlling patchable instruction behavior.
#[derive(Debug, Clone)]
pub struct PatchableConfig {
    /// NOP sled size (bytes) before each function entry.
    /// Common values: 2 (Win64 hotpatch), 5 (Linux ftrace), 11 (prologue),
    /// 16 (cache-aligned).
    pub patchable_function_entry_nops: usize,
    /// NOP size (bytes) before each CALL instruction for hot-patching.
    /// Typically 5 (JMP rel32) or 2 (short JMP).
    pub patchable_call_nops: usize,
    /// NOP size (bytes) before each conditional branch.
    pub patchable_cond_branch_nops: usize,
    /// NOP size (bytes) before each unconditional branch.
    pub patchable_uncond_branch_nops: usize,
    /// Byte width reserved for patchable constants (e.g., 8 for 8-byte
    /// immediate in MOVABS).
    pub patchable_constant_bytes: usize,
    /// Whether to emit stackmap records at patchpoints.
    pub emit_stackmaps: bool,
    /// Stackmap format version (0-3 as per LLVM documentation).
    pub stackmap_version: u8,
    /// Whether to emit deoptimization bundles.
    pub emit_deopt_bundles: bool,
    /// Whether to emit GC safepoint records (statepoints).
    pub emit_statepoints: bool,
    /// Whether function entries use 2-byte NOP (MOV EDI, EDI) for Win64
    /// hot-patching compatibility.
    pub win64_hotpatch: bool,
    /// Whether to align NOP sleds to cache-line boundaries.
    pub cache_line_align: bool,
    /// Cache line size for alignment (typically 64 for modern cores).
    pub cache_line_size: u32,
    /// Whether to use long NOPs (multi-byte NOP sequences) for better
    /// decode bandwidth on modern cores.
    pub use_long_nops: bool,
    /// Preferred NOP strategy for each NOP length.
    pub nop_strategy: NopStrategy,
}

impl Default for PatchableConfig {
    fn default() -> Self {
        Self {
            patchable_function_entry_nops: 5,
            patchable_call_nops: 5,
            patchable_cond_branch_nops: 2,
            patchable_uncond_branch_nops: 5,
            patchable_constant_bytes: 8,
            emit_stackmaps: true,
            stackmap_version: 3,
            emit_deopt_bundles: true,
            emit_statepoints: false,
            win64_hotpatch: false,
            cache_line_align: false,
            cache_line_size: 64,
            use_long_nops: true,
            nop_strategy: NopStrategy::Optimal,
        }
    }
}

/// Strategy for selecting NOP sequences.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NopStrategy {
    /// Always use single-byte NOPs (0x90). Fastest to decode, but wastes
    /// front-end bandwidth on long sleds.
    SingleByte,
    /// Use long NOPs for 2+ byte sequences. Better decode bandwidth on
    /// modern Intel/AMD cores.
    LongNop,
    /// Use the NOP that is optimal for the target microarchitecture:
    /// balance between decode bandwidth and μop cache occupancy.
    Optimal,
    /// Use the shortest possible encoding for the patchable region.
    /// Minimizes code size at the cost of decode bandwidth.
    MinSize,
    /// Use Intel-recommended NOP sequences for alignment.
    IntelRecommended,
    /// Use AMD-recommended NOP sequences for alignment.
    AmdRecommended,
}

/// Statistics collected during patchable instruction generation.
#[derive(Debug, Clone, Default)]
pub struct PatchableStats {
    /// Number of patchable function entries emitted.
    pub patchable_entries: usize,
    /// Total NOP bytes emitted at function entries.
    pub entry_nop_bytes: usize,
    /// Number of patchable call sites emitted.
    pub patchable_calls: usize,
    /// Total NOP bytes emitted before calls.
    pub call_nop_bytes: usize,
    /// Number of patchable conditional branches.
    pub patchable_cond_branches: usize,
    /// Number of patchable unconditional branches.
    pub patchable_uncond_branches: usize,
    /// Total NOP bytes emitted before branches.
    pub branch_nop_bytes: usize,
    /// Number of patchable constants emitted.
    pub patchable_constants: usize,
    /// Number of stackmap records generated.
    pub stackmap_records: usize,
    /// Number of deoptimization bundles generated.
    pub deopt_bundles: usize,
    /// Number of statepoint records generated.
    pub statepoint_records: usize,
}

// ============================================================================
// Patchable Entry
// ============================================================================

/// Describes a patchable function entry: a NOP sled placed before the
/// function body that can be overwritten at runtime with a JMP or CALL
/// to an alternative implementation.
#[derive(Debug, Clone)]
pub struct PatchableEntry {
    /// Symbol name of the function.
    pub function_name: String,
    /// Size of the NOP sled (bytes).
    pub nop_sled_size: usize,
    /// Raw NOP sled bytes.
    pub nop_sled_bytes: Vec<u8>,
    /// Offset of the NOP sled from the function start (0 = at entry).
    pub sled_offset: isize,
    /// Whether the sled is before the prologue (pre-prologue) or after.
    pub pre_prologue: bool,
    /// For Win64 hotpatching: whether the entry uses the 2-byte
    /// MOV EDI,EDI convention.
    pub win64_style: bool,
    /// Function entry alignment (for cache-line-aligned entries).
    pub alignment: u32,
}

impl PatchableEntry {
    /// Create a new patchable function entry.
    pub fn new(
        function_name: String,
        nop_sled_size: usize,
        is_64bit: bool,
        config: &PatchableConfig,
    ) -> Self {
        let nop_sled_bytes = generate_nop_sled(nop_sled_size, config.nop_strategy, is_64bit);
        PatchableEntry {
            function_name,
            nop_sled_size,
            nop_sled_bytes,
            sled_offset: 0,
            pre_prologue: true,
            win64_style: config.win64_hotpatch,
            alignment: if config.cache_line_align {
                config.cache_line_size
            } else {
                16
            },
        }
    }

    /// Emit the NOP sled as a sequence of bytes.
    pub fn emit_bytes(&self) -> Vec<u8> {
        self.nop_sled_bytes.clone()
    }

    /// Return the total size including alignment padding.
    pub fn total_size(&self) -> usize {
        self.nop_sled_size
    }
}

// ============================================================================
// Patchable Call
// ============================================================================

/// Describes a patchable call site: a CALL instruction preceded by a
/// NOP sled that can be overwritten to redirect the call target at
/// runtime.
#[derive(Debug, Clone)]
pub struct PatchableCall {
    /// Unique ID for this call site (used in stackmaps).
    pub patchpoint_id: u64,
    /// Original call target symbol.
    pub callee: String,
    /// NOP sled size before the CALL (bytes).
    pub nop_size: usize,
    /// Raw NOP sled bytes.
    pub nop_bytes: Vec<u8>,
    /// Whether this call is a tail call (JMP instead of CALL).
    pub is_tail_call: bool,
    /// Whether this is a direct call (rel32) or indirect (reg/mem).
    pub is_direct: bool,
    /// Number of arguments to the call.
    pub num_args: usize,
    /// Calling convention.
    pub calling_conv: CallingConvention,
    /// Whether this call site participates in deoptimization.
    pub deopt_capable: bool,
}

impl PatchableCall {
    /// Create a new patchable call site.
    pub fn new(
        patchpoint_id: u64,
        callee: String,
        nop_size: usize,
        is_tail_call: bool,
        is_direct: bool,
        num_args: usize,
        config: &PatchableConfig,
    ) -> Self {
        let nop_bytes = generate_nop_sled(nop_size, config.nop_strategy, true);
        PatchableCall {
            patchpoint_id,
            callee,
            nop_size,
            nop_bytes,
            is_tail_call,
            is_direct,
            num_args,
            calling_conv: CallingConvention::SystemV,
            deopt_capable: true,
        }
    }

    /// Emit the NOP sled for this call site as bytes.
    pub fn emit_nop_sled(&self) -> Vec<u8> {
        self.nop_bytes.clone()
    }

    /// Total patchable region size (NOP sled + CALL instruction).
    pub fn patchable_region_size(&self) -> usize {
        // NOP sled + 5-byte CALL rel32
        self.nop_size + 5
    }
}

// ============================================================================
// Patchable Branch
// ============================================================================

/// Describes a patchable branch: a conditional or unconditional branch
/// with reserved NOP space for runtime redirection.
#[derive(Debug, Clone)]
pub struct PatchableBranch {
    /// Unique ID for this branch site.
    pub branch_id: u64,
    /// Kind of branch: conditional (JCC) or unconditional (JMP).
    pub branch_kind: PatchableBranchKind,
    /// Condition code for conditional branches.
    pub condition: BranchCondition,
    /// Original branch target label.
    pub target_label: String,
    /// NOP sled size before the branch (bytes).
    pub nop_size: usize,
    /// Raw NOP sled bytes.
    pub nop_bytes: Vec<u8>,
    /// Whether this is a short (rel8) or near (rel32) branch.
    pub is_short: bool,
    /// Whether the fall-through path is the likely target (for PGO).
    pub fallthrough_likely: bool,
}

impl PatchableBranch {
    /// Create a new patchable branch.
    pub fn new(
        branch_id: u64,
        branch_kind: PatchableBranchKind,
        condition: BranchCondition,
        target_label: String,
        nop_size: usize,
        is_short: bool,
        config: &PatchableConfig,
    ) -> Self {
        let nop_bytes = generate_nop_sled(nop_size, config.nop_strategy, true);
        PatchableBranch {
            branch_id,
            branch_kind,
            condition,
            target_label,
            nop_size,
            nop_bytes,
            is_short,
            fallthrough_likely: true,
        }
    }

    /// Emit NOP sled for the branch as bytes.
    pub fn emit_nop_sled(&self) -> Vec<u8> {
        self.nop_bytes.clone()
    }

    /// Size of the original branch instruction (without NOP sled).
    pub fn branch_instr_size(&self) -> usize {
        if self.is_short {
            2 // opcode + rel8
        } else {
            6 // opcode + rel32
        }
    }

    /// Total patchable region size.
    pub fn patchable_region_size(&self) -> usize {
        self.nop_size + self.branch_instr_size()
    }
}

/// Kind of patchable branch.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PatchableBranchKind {
    /// Conditional branch (JCC): JE, JNE, JL, JG, etc.
    Conditional,
    /// Unconditional branch (JMP).
    Unconditional,
    /// Indirect branch (JMP reg/mem).
    Indirect,
}

/// Branch conditions for X86 JCC instructions.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum BranchCondition {
    /// Jump if above (CF=0 and ZF=0): JA / JNBE
    Above,
    /// Jump if above or equal (CF=0): JAE / JNB / JNC
    AboveOrEqual,
    /// Jump if below (CF=1): JB / JNAE / JC
    Below,
    /// Jump if below or equal (CF=1 or ZF=1): JBE / JNA
    BelowOrEqual,
    /// Jump if carry (CF=1): JC (same as JB)
    Carry,
    /// Jump if equal (ZF=1): JE / JZ
    Equal,
    /// Jump if greater (ZF=0 and SF=OF): JG / JNLE
    Greater,
    /// Jump if greater or equal (SF=OF): JGE / JNL
    GreaterOrEqual,
    /// Jump if less (SF!=OF): JL / JNGE
    Less,
    /// Jump if less or equal (ZF=1 or SF!=OF): JLE / JNG
    LessOrEqual,
    /// Jump if not above (CF=1 or ZF=1): JNA (same as JBE)
    NotAbove,
    /// Jump if not above or equal (CF=1): JNAE (same as JB)
    NotAboveOrEqual,
    /// Jump if not below (CF=0): JNB (same as JAE)
    NotBelow,
    /// Jump if not below or equal (CF=0 and ZF=0): JNBE (same as JA)
    NotBelowOrEqual,
    /// Jump if not carry (CF=0): JNC (same as JAE)
    NotCarry,
    /// Jump if not equal (ZF=0): JNE / JNZ
    NotEqual,
    /// Jump if not greater (ZF=1 or SF!=OF): JNG (same as JLE)
    NotGreater,
    /// Jump if not greater or equal (SF!=OF): JNGE (same as JL)
    NotGreaterOrEqual,
    /// Jump if not less (SF=OF): JNL (same as JGE)
    NotLess,
    /// Jump if not less or equal (ZF=0 and SF=OF): JNLE (same as JG)
    NotLessOrEqual,
    /// Jump if not overflow (OF=0): JNO
    NotOverflow,
    /// Jump if not parity (PF=0): JNP / JPO
    NotParity,
    /// Jump if not sign (SF=0): JNS
    NotSign,
    /// Jump if not zero (ZF=0): JNZ (same as JNE)
    NotZero,
    /// Jump if overflow (OF=1): JO
    Overflow,
    /// Jump if parity (PF=1): JP / JPE
    Parity,
    /// Jump if sign (SF=1): JS
    Sign,
    /// Jump if zero (ZF=1): JZ (same as JE)
    Zero,
    /// Jump if ECX is zero: JECXZ / JRCXZ
    CxZero,
}

impl BranchCondition {
    /// Get the JCC opcode byte for 8-bit displacement.
    pub fn opcode_rel8(&self) -> u8 {
        match self {
            BranchCondition::Above | BranchCondition::NotBelowOrEqual => 0x77,
            BranchCondition::AboveOrEqual | BranchCondition::NotBelow
            | BranchCondition::NotCarry => 0x73,
            BranchCondition::Below | BranchCondition::NotAboveOrEqual
            | BranchCondition::Carry => 0x72,
            BranchCondition::BelowOrEqual | BranchCondition::NotAbove => 0x76,
            BranchCondition::Equal | BranchCondition::Zero => 0x74,
            BranchCondition::Greater | BranchCondition::NotLessOrEqual => 0x7F,
            BranchCondition::GreaterOrEqual | BranchCondition::NotLess => 0x7D,
            BranchCondition::Less | BranchCondition::NotGreaterOrEqual => 0x7C,
            BranchCondition::LessOrEqual | BranchCondition::NotGreater => 0x7E,
            BranchCondition::NotEqual | BranchCondition::NotZero => 0x75,
            BranchCondition::NotOverflow => 0x71,
            BranchCondition::NotParity => 0x7B,
            BranchCondition::NotSign => 0x79,
            BranchCondition::Overflow => 0x70,
            BranchCondition::Parity => 0x7A,
            BranchCondition::Sign => 0x78,
            _ => 0x74, // default to JE
        }
    }

    /// Get the two-byte JCC opcode prefix for 32-bit displacement (0x0F 0x8x).
    pub fn opcode_rel32_prefix(&self) -> u8 {
        match self {
            BranchCondition::Above | BranchCondition::NotBelowOrEqual => 0x87,
            BranchCondition::AboveOrEqual | BranchCondition::NotBelow
            | BranchCondition::NotCarry => 0x83,
            BranchCondition::Below | BranchCondition::NotAboveOrEqual
            | BranchCondition::Carry => 0x82,
            BranchCondition::BelowOrEqual | BranchCondition::NotAbove => 0x86,
            BranchCondition::Equal | BranchCondition::Zero => 0x84,
            BranchCondition::Greater | BranchCondition::NotLessOrEqual => 0x8F,
            BranchCondition::GreaterOrEqual | BranchCondition::NotLess => 0x8D,
            BranchCondition::Less | BranchCondition::NotGreaterOrEqual => 0x8C,
            BranchCondition::LessOrEqual | BranchCondition::NotGreater => 0x8E,
            BranchCondition::NotEqual | BranchCondition::NotZero => 0x85,
            BranchCondition::NotOverflow => 0x81,
            BranchCondition::NotParity => 0x8B,
            BranchCondition::NotSign => 0x89,
            BranchCondition::Overflow => 0x80,
            BranchCondition::Parity => 0x8A,
            BranchCondition::Sign => 0x88,
            _ => 0x84, // default to JE near
        }
    }
}

// ============================================================================
// Patchable Constant
// ============================================================================

/// Describes a patchable constant: a MOV-immediate instruction whose
/// immediate operand can be replaced at runtime.
#[derive(Debug, Clone)]
pub struct PatchableConstant {
    /// Unique ID for this constant site.
    pub const_id: u64,
    /// Destination register (for MOV reg, imm).
    pub dest_register: X86Reg,
    /// Original immediate value (placeholder).
    pub initial_value: i64,
    /// Width of the immediate in bytes.
    pub width_bytes: usize,
    /// Byte offset of the immediate within the MOV instruction.
    pub imm_offset: usize,
    /// Total instruction size including the patching region.
    pub instr_size: usize,
    /// Whether this constant is a pointer (for GC tracking).
    pub is_pointer: bool,
    /// Symbol that this constant refers to (if any).
    pub symbol: Option<String>,
}

impl PatchableConstant {
    /// Create a new patchable constant.
    pub fn new(
        const_id: u64,
        dest_register: X86Reg,
        initial_value: i64,
        width_bytes: usize,
    ) -> Self {
        let instr_size = if dest_register.is_64bit() {
            10 // REX.W + MOV r64, imm64
        } else {
            5 // MOV r32, imm32
        };
        let imm_offset = if dest_register.is_64bit() { 2 } else { 1 };
        PatchableConstant {
            const_id,
            dest_register,
            initial_value,
            width_bytes,
            imm_offset,
            instr_size,
            is_pointer: false,
            symbol: None,
        }
    }

    /// Emit the MOV-immediate encoding with the current value.
    pub fn emit_bytes(&self) -> Vec<u8> {
        let mut bytes = Vec::with_capacity(self.instr_size);
        if self.dest_register.is_64bit() {
            // REX.W prefix
            bytes.push(0x48 | ((self.dest_register.rex_b_bit() as u8) << 2));
            // MOV r64, imm64: opcode B8+reg
            bytes.push(0xB8 | (self.dest_register.opcode_reg_num() & 0x07));
            let val = self.initial_value;
            bytes.extend_from_slice(&val.to_le_bytes());
        } else {
            // MOV r32, imm32: opcode B8+reg
            bytes.push(0xB8 | (self.dest_register.opcode_reg_num() & 0x07));
            let val = self.initial_value as i32;
            bytes.extend_from_slice(&val.to_le_bytes());
        }
        bytes
    }
}

// ============================================================================
// PatchPoint / StackMap Integration
// ============================================================================

/// A PatchPoint: a call-like instruction that records the live state
/// at a program point for on-stack replacement (OSR), deoptimization,
/// or garbage collection.
#[derive(Debug, Clone)]
pub struct PatchPoint {
    /// Unique PatchPoint ID.
    pub id: u64,
    /// NOP sled size in bytes.
    pub nop_sled_size: usize,
    /// Raw NOP sled bytes.
    pub nop_sled_bytes: Vec<u8>,
    /// Call encoding (typically a 5-byte CALL rel32).
    pub call_bytes: Vec<u8>,
    /// Number of live values at this point.
    pub num_live_values: usize,
    /// Live register mask (bit i = 1 means register i is live).
    pub live_reg_mask: u64,
    /// Live stack slots (byte offsets relative to RSP).
    pub live_stack_slots: Vec<i32>,
    /// StackMap record associated with this PatchPoint.
    pub stackmap: Option<StackMapRecord>,
    /// Whether this PatchPoint is a safepoint for GC.
    pub is_safepoint: bool,
    /// Whether this PatchPoint is a deoptimization point.
    pub is_deopt_point: bool,
    /// Deoptimization state (if this is a deopt point).
    pub deopt_state: Option<DeoptState>,
}

impl PatchPoint {
    /// Create a new PatchPoint.
    pub fn new(
        id: u64,
        nop_sled_size: usize,
        config: &PatchableConfig,
    ) -> Self {
        let nop_sled_bytes =
            generate_nop_sled(nop_sled_size, config.nop_strategy, true);
        // Default call is CALL rel32 to a runtime trampoline.
        let call_bytes = vec![0xE8, 0x00, 0x00, 0x00, 0x00];
        PatchPoint {
            id,
            nop_sled_size,
            nop_sled_bytes,
            call_bytes,
            num_live_values: 0,
            live_reg_mask: 0,
            live_stack_slots: vec![],
            stackmap: None,
            is_safepoint: false,
            is_deopt_point: false,
            deopt_state: None,
        }
    }

    /// Mark this PatchPoint as a GC safepoint.
    pub fn mark_safepoint(&mut self, live_refs: &[LiveRef]) {
        self.is_safepoint = true;
        self.num_live_values = live_refs.len();
    }

    /// Total size of the PatchPoint code sequence.
    pub fn total_size(&self) -> usize {
        self.nop_sled_size + self.call_bytes.len()
    }
}

/// Represents a live GC reference at a PatchPoint.
#[derive(Debug, Clone)]
pub struct LiveRef {
    /// Location of the reference.
    pub location: LiveLocation,
    /// Whether this is a derived pointer (interior pointer).
    pub is_derived: bool,
    /// Base pointer for derived references.
    pub base: Option<Box<LiveRef>>,
    /// GC meta-kind.
    pub meta_kind: GcMetaKind,
}

/// Location of a live value in the register file or stack.
#[derive(Debug, Clone)]
pub enum LiveLocation {
    /// Value is in a general-purpose register.
    Register(X86Reg),
    /// Value is at a stack offset (RSP-relative).
    StackOffset(i32),
    /// Value is at a fixed frame index.
    FrameIndex(usize),
    /// Value is a constant (known at patch time).
    Constant(i64),
}

/// GC metadata kind for live references.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GcMetaKind {
    /// Untagged object reference.
    Untagged,
    /// Tagged object reference (tag in low bits).
    Tagged,
    /// Interior pointer into an object.
    Interior,
    /// Nullable reference.
    Nullable,
    /// Non-null reference.
    NonNull,
}

// ============================================================================
// StackMap Records
// ============================================================================

/// A StackMap record: maps live values (registers and stack slots) at a
/// specific program point (PatchPoint) to enable stack walking and frame
/// reconstruction.
#[derive(Debug, Clone)]
pub struct StackMapRecord {
    /// StackMap ID (matches PatchPoint ID).
    pub id: u64,
    /// Code offset of the PatchPoint from the function start.
    pub instruction_offset: u32,
    /// Number of live locations recorded.
    pub num_locations: usize,
    /// Live locations.
    pub locations: Vec<LiveValueLocation>,
    /// Number of live-out registers.
    pub num_live_outs: usize,
    /// Live-out register locations.
    pub live_outs: Vec<LiveValueLocation>,
    /// Stack size at this call site.
    pub stack_size: u64,
    /// Deoptimization metadata (if this is a deopt point).
    pub deopt_meta: Option<DeoptMeta>,
    /// Calling convention at this point.
    pub calling_conv: CallingConvention,
}

/// Location of a live value as recorded in a StackMap.
#[derive(Debug, Clone)]
pub struct LiveValueLocation {
    /// Kind of location.
    pub kind: LocationKind,
    /// DWARF register number (for register locations).
    pub dwarf_reg_num: u16,
    /// Offset from register or frame pointer (for indirect locations).
    pub offset: i32,
    /// Size of the value in bytes.
    pub size: u8,
}

/// Location kind for stackmap records.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LocationKind {
    /// Value is in a register.
    Register,
    /// Value is in memory at [register + offset].
    Direct,
    /// Value is in memory at [register] (the register holds a pointer
    /// to the value).
    Indirect,
    /// Value is a known constant.
    Constant,
    /// Value is at a constant index offset.
    ConstIndex,
}

impl LocationKind {
    /// Encode location kind as per LLVM StackMap V3 format.
    pub fn encode(&self) -> u8 {
        match self {
            LocationKind::Register => 1,
            LocationKind::Direct => 2,
            LocationKind::Indirect => 3,
            LocationKind::Constant => 4,
            LocationKind::ConstIndex => 5,
        }
    }
}

/// Deoptimization metadata attached to a StackMap record.
#[derive(Debug, Clone)]
pub struct DeoptMeta {
    /// Bytecode offset to resume execution at after deoptimization.
    pub bytecode_offset: u64,
    /// Number of inline frames in the optimized code.
    pub num_inline_frames: u32,
    /// Per-frame deoptimization information.
    pub frames: Vec<DeoptFrameMeta>,
    /// Reason for deoptimization.
    pub deopt_reason: DeoptReason,
}

/// Deoptimization frame metadata for reconstructing an interpreter frame.
#[derive(Debug, Clone)]
pub struct DeoptFrameMeta {
    /// Method being executed in this frame.
    pub method_name: String,
    /// Bytecode offset within the method.
    pub bytecode_offset: u64,
    /// Number of locals in the frame.
    pub num_locals: u32,
    /// Number of expression stack slots.
    pub num_expr_stack: u32,
    /// Whether the frame has a monitor (synchronized method).
    pub has_monitor: bool,
    /// Whether this was an inlined frame.
    pub is_inlined: bool,
}

/// Reason for deoptimization.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DeoptReason {
    /// No deoptimization.
    None,
    /// Speculative type check failed.
    TypeCheckFailed,
    /// Speculative bounds check failed.
    BoundsCheckFailed,
    /// Speculative null check failed.
    NullCheckFailed,
    /// Speculative division by zero check failed.
    DivZeroCheckFailed,
    /// Speculative class hierarchy analysis (CHA) failed.
    CHAFailed,
    /// Unstable if condition (OSR to interpreter).
    UnstableIf,
    /// Debugger breakpoint.
    Debugger,
    /// Explicit deoptimization request.
    ExplicitDeopt,
    /// Other unspecified reason.
    Other,
}

impl fmt::Display for DeoptReason {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            DeoptReason::None => write!(f, "none"),
            DeoptReason::TypeCheckFailed => write!(f, "type_check"),
            DeoptReason::BoundsCheckFailed => write!(f, "bounds_check"),
            DeoptReason::NullCheckFailed => write!(f, "null_check"),
            DeoptReason::DivZeroCheckFailed => write!(f, "div_zero"),
            DeoptReason::CHAFailed => write!(f, "cha_failed"),
            DeoptReason::UnstableIf => write!(f, "unstable_if"),
            DeoptReason::Debugger => write!(f, "debugger"),
            DeoptReason::ExplicitDeopt => write!(f, "explicit"),
            DeoptReason::Other => write!(f, "other"),
        }
    }
}

// ============================================================================
// Deoptimization Bundle
// ============================================================================

/// A deoptimization bundle: the code, metadata, and frame reconstruction
/// information needed to transfer control from optimized code back to
/// the interpreter when speculative assumptions fail.
#[derive(Debug, Clone)]
pub struct DeoptBundle {
    /// Unique deoptimization ID.
    pub deopt_id: u64,
    /// PatchPoint ID that this bundle services.
    pub patchpoint_id: u64,
    /// Deoptimization state at this point.
    pub deopt_state: DeoptState,
    /// StackMap record for frame reconstruction.
    pub stackmap: Option<StackMapRecord>,
    /// Register restore sequence.
    pub reg_restore: Vec<RegRestoreOp>,
    /// Frame reconstruction operations.
    pub frame_reconstruction: Vec<FrameReconstructOp>,
    /// Target interpreter entry point.
    pub interpreter_entry: String,
}

/// Deoptimization state: the set of live values at a deopt point.
#[derive(Debug, Clone)]
pub struct DeoptState {
    /// Number of live registers.
    pub num_live_regs: usize,
    /// Bitmask of live general-purpose registers.
    pub live_gpr_mask: u16,
    /// Bitmask of live XMM registers.
    pub live_xmm_mask: u16,
    /// Stack slots that need to be restored.
    pub live_stack_slots: Vec<DeoptStackSlot>,
    /// Live values with their interpreter locations.
    pub live_values: Vec<DeoptValue>,
}

/// A stack slot that must be preserved during deoptimization.
#[derive(Debug, Clone)]
pub struct DeoptStackSlot {
    /// RSP-relative offset.
    pub offset: i32,
    /// Size in bytes.
    pub size: u8,
    /// Variable name (for debugging).
    pub name: String,
}

/// A live value that must be transferred to the interpreter frame.
#[derive(Debug, Clone)]
pub struct DeoptValue {
    /// The value's optimized location.
    pub source: LiveLocation,
    /// The value's target location in the interpreter frame.
    pub target: DeoptTargetLocation,
    /// Type of the value.
    pub value_type: DeoptValueType,
}

/// Target location for a deoptimized value in the interpreter frame.
#[derive(Debug, Clone)]
pub enum DeoptTargetLocation {
    /// Local variable at index N in the interpreter frame.
    Local(usize),
    /// Expression stack slot at depth N.
    ExprStack(usize),
    /// Lock object reference.
    Monitor,
    /// Return address.
    ReturnAddress,
    /// Operand stack pointer.
    StackPointer,
    /// Frame pointer.
    FramePointer,
    /// Bytecode offset.
    BytecodeOffset,
}

/// Type category of a deoptimized value.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DeoptValueType {
    /// 32-bit integer.
    Int32,
    /// 64-bit integer.
    Int64,
    /// 32-bit float.
    Float32,
    /// 64-bit float.
    Float64,
    /// Object reference (GC-tracked).
    ObjectRef,
    /// Raw pointer (not GC-tracked).
    RawPtr,
    /// 128-bit vector.
    Vec128,
    /// 256-bit vector.
    Vec256,
    /// Boolean.
    Bool,
    /// Byte.
    Byte,
    /// 16-bit short.
    Short,
}

/// A register restore operation.
#[derive(Debug, Clone)]
pub struct RegRestoreOp {
    /// Target register.
    pub reg: X86Reg,
    /// Source of the value.
    pub source: RestoreSource,
}

/// Source of a value used to restore a register.
#[derive(Debug, Clone)]
pub enum RestoreSource {
    /// Load from stack at offset.
    Stack(i32),
    /// Copy from another register.
    Register(X86Reg),
    /// Load a constant.
    Constant(i64),
    /// Load from the interpreter frame at a given local index.
    InterpreterLocal(usize),
    /// Load from the expression stack at a given depth.
    InterpreterExprStack(usize),
}

/// A frame reconstruction operation.
#[derive(Debug, Clone)]
pub enum FrameReconstructOp {
    /// Store a value from a register to an interpreter frame slot.
    StoreRegToLocal {
        reg: X86Reg,
        local_index: usize,
        size: u8,
    },
    /// Store a value from a register to the expression stack.
    StoreRegToExprStack {
        reg: X86Reg,
        depth: usize,
        size: u8,
    },
    /// Set the bytecode offset register.
    SetBci { reg: X86Reg, bci: u64 },
    /// Set the frame pointer for the interpreter.
    SetFramePtr { reg: X86Reg },
    /// Set the stack pointer for the interpreter.
    SetStackPtr { reg: X86Reg },
    /// Copy a value from one interpreter local to another.
    CopyLocal { src: usize, dst: usize, size: u8 },
    /// Clear a local variable (set to 0/null).
    ClearLocal { local_index: usize, size: u8 },
    /// Push a value onto the expression stack.
    PushExprStack { reg: X86Reg, size: u8 },
    /// Pop a value from the expression stack.
    PopExprStack { count: usize },
    /// Adjust the expression stack pointer.
    AdjustExprStack { delta: i32 },
    /// Emit a debug trap for debugging deoptimization.
    DebugTrap,
    /// Jump to the interpreter dispatch loop.
    JumpToInterpreter { entry_point: String },
    /// No operation (alignment padding).
    Nop,
}

// ============================================================================
// Statepoints
// ============================================================================

/// A GC statepoint: a program point where all live GC references are
/// recorded, enabling precise garbage collection.
#[derive(Debug, Clone)]
pub struct Statepoint {
    /// Unique statepoint ID.
    pub id: u64,
    /// Associated PatchPoint ID.
    pub patchpoint_id: u64,
    /// Number of call arguments.
    pub num_call_args: usize,
    /// Flags for this statepoint.
    pub flags: StatepointFlags,
    /// Number of deopt arguments.
    pub num_deopt_args: usize,
    /// GC transition arguments.
    pub gc_args: Vec<StatepointGcArg>,
    /// Call target.
    pub call_target: String,
    /// Transition kind.
    pub transition: GcTransition,
}

/// Flags for a statepoint.
#[derive(Debug, Clone)]
pub struct StatepointFlags {
    /// Whether this is a "gc-leaf-function" (no GC references live).
    pub gc_leaf_function: bool,
    /// Whether the call may return (false for noreturn calls).
    pub may_return: bool,
    /// Whether this is an invoke (vs a call).
    pub is_invoke: bool,
}

impl Default for StatepointFlags {
    fn default() -> Self {
        Self {
            gc_leaf_function: false,
            may_return: true,
            is_invoke: false,
        }
    }
}

/// A GC argument at a statepoint.
#[derive(Debug, Clone)]
pub struct StatepointGcArg {
    /// Index of the argument.
    pub index: usize,
    /// Whether this argument is a GC reference.
    pub is_gc_ref: bool,
    /// Location of the argument.
    pub location: LiveLocation,
}

/// GC transition type for a statepoint.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GcTransition {
    /// No GC transition.
    None,
    /// Transition from mutator to GC.
    ToSafepoint,
    /// Transition from GC back to mutator.
    FromSafepoint,
    /// Full GC cycle transition.
    Full,
}

// ============================================================================
// NOP Sled Generation
// ============================================================================

/// Generate a NOP sled of the given size using the specified strategy.
///
/// On X86/X86-64, NOP sleds are sequences of NOP instructions that can
/// be overwritten at runtime with real instructions. The sled must be
/// safely executable as NOPs before patching, and the total sequence
/// must have exactly `size` bytes.
pub fn generate_nop_sled(size: usize, strategy: NopStrategy, _is_64bit: bool) -> Vec<u8> {
    if size == 0 {
        return vec![];
    }

    match strategy {
        NopStrategy::SingleByte => {
            vec![0x90; size]
        }
        NopStrategy::LongNop | NopStrategy::Optimal => {
            generate_long_nop_sled(size)
        }
        NopStrategy::MinSize => {
            generate_min_size_nop_sled(size)
        }
        NopStrategy::IntelRecommended => {
            generate_intel_recommended_nop_sled(size)
        }
        NopStrategy::AmdRecommended => {
            generate_amd_recommended_nop_sled(size)
        }
    }
}

/// Generate a NOP sled using multi-byte NOP sequences for optimal decode
/// bandwidth on modern Intel/AMD cores.
fn generate_long_nop_sled(size: usize) -> Vec<u8> {
    let mut bytes = Vec::with_capacity(size);
    let mut remaining = size;

    // Use the largest possible NOP sequences to minimize the number of
    // instructions the decoder must process.
    while remaining > 0 {
        let nop_size = if remaining >= 15 {
            15
        } else {
            remaining
        };
        bytes.extend_from_slice(&get_multi_byte_nop(nop_size));
        remaining -= nop_size;
    }
    bytes
}

/// Get a multi-byte NOP sequence of the given length (1-15 bytes).
///
/// These sequences follow Intel's recommendations from the Intel® 64 and
/// IA-32 Architectures Optimization Reference Manual, Appendix B.
/// They use the "66 0F 1F /0" prefix with ModR/M and SIB encoding to
/// create NOPs up to 9 bytes. Longer NOPs (10-15 bytes) extend this
/// with additional prefixes.
fn get_multi_byte_nop(len: usize) -> Vec<u8> {
    match len {
        1 => vec![0x90],
        2 => vec![0x66, 0x90],
        3 => vec![0x0F, 0x1F, 0x00],
        4 => vec![0x0F, 0x1F, 0x40, 0x00],
        5 => vec![0x0F, 0x1F, 0x44, 0x00, 0x00],
        6 => vec![0x66, 0x0F, 0x1F, 0x44, 0x00, 0x00],
        7 => vec![0x0F, 0x1F, 0x80, 0x00, 0x00, 0x00, 0x00],
        8 => vec![0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00],
        9 => vec![0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00],
        10 => vec![
            0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
        ],
        11 => vec![
            0x66, 0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
        ],
        12 => vec![
            0x66, 0x66, 0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00,
            0x00,
        ],
        13 => vec![
            0x66, 0x66, 0x66, 0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00,
            0x00, 0x00,
        ],
        14 => vec![
            0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00,
            0x00, 0x00, 0x00,
        ],
        15 => vec![
            0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00,
            0x00, 0x00, 0x00, 0x00,
        ],
        _ => vec![0x90],
    }
}

/// Generate a NOP sled using the minimal number of instructions to
/// minimize code size.
fn generate_min_size_nop_sled(size: usize) -> Vec<u8> {
    let mut bytes = Vec::with_capacity(size);
    let mut remaining = size;

    // Use the largest NOP we can to minimize instruction count,
    // but prefer sequences that are known to be fast to decode.
    while remaining >= 15 {
        bytes.extend_from_slice(&get_multi_byte_nop(15));
        remaining -= 15;
    }
    while remaining >= 9 {
        bytes.extend_from_slice(&get_multi_byte_nop(9));
        remaining -= 9;
    }
    while remaining >= 4 {
        bytes.extend_from_slice(&get_multi_byte_nop(4));
        remaining -= 4;
    }
    while remaining >= 2 {
        bytes.extend_from_slice(&get_multi_byte_nop(2));
        remaining -= 2;
    }
    if remaining > 0 {
        bytes.push(0x90);
    }
    bytes
}

/// Generate a NOP sled using Intel's recommended sequences.
fn generate_intel_recommended_nop_sled(size: usize) -> Vec<u8> {
    let mut bytes = Vec::with_capacity(size);
    let mut remaining = size;

    // Intel recommends the following hierarchy for alignment padding
    // (from Optimization Reference Manual):
    // 11-byte: 66 66 66 0F 1F 84 00 00 00 00 00
    // 10-byte: 66 66 0F 1F 84 00 00 00 00 00
    // 9-byte:  66 0F 1F 84 00 00 00 00 00
    // 8-byte:  0F 1F 84 00 00 00 00 00
    // 7-byte:  0F 1F 80 00 00 00 00
    // 6-byte:  66 0F 1F 44 00 00
    // 5-byte:  0F 1F 44 00 00
    // 4-byte:  0F 1F 40 00
    // 3-byte:  0F 1F 00
    // 2-byte:  66 90
    // 1-byte:  90

    // Intel recommends using longer NOPs first for alignment.
    let nop_lengths: [(usize, fn() -> Vec<u8>); 1] = [
        (0, || vec![]),
    ];

    // Use a greedy approach: consume the largest NOPs first.
    while remaining >= 11 {
        bytes.extend_from_slice(&get_multi_byte_nop(11));
        remaining -= 11;
    }
    while remaining >= 10 {
        bytes.extend_from_slice(&get_multi_byte_nop(10));
        remaining -= 10;
    }
    while remaining >= 9 {
        bytes.extend_from_slice(&get_multi_byte_nop(9));
        remaining -= 9;
    }
    while remaining >= 8 {
        bytes.extend_from_slice(&get_multi_byte_nop(8));
        remaining -= 8;
    }
    while remaining >= 7 {
        bytes.extend_from_slice(&get_multi_byte_nop(7));
        remaining -= 7;
    }
    while remaining >= 6 {
        bytes.extend_from_slice(&get_multi_byte_nop(6));
        remaining -= 6;
    }
    while remaining >= 5 {
        bytes.extend_from_slice(&get_multi_byte_nop(5));
        remaining -= 5;
    }
    while remaining >= 4 {
        bytes.extend_from_slice(&get_multi_byte_nop(4));
        remaining -= 4;
    }
    while remaining >= 3 {
        bytes.extend_from_slice(&get_multi_byte_nop(3));
        remaining -= 3;
    }
    while remaining >= 2 {
        bytes.extend_from_slice(&get_multi_byte_nop(2));
        remaining -= 2;
    }
    if remaining > 0 {
        bytes.push(0x90);
    }
    bytes
}

/// Generate a NOP sled using AMD's recommended sequences.
fn generate_amd_recommended_nop_sled(size: usize) -> Vec<u8> {
    // AMD's recommendations are largely similar to Intel's but differ
    // slightly in the handling of the 0x66 prefix. AMD documents that
    // the 0x0F 0x1F family is the preferred NOP for all sizes.
    // For sizes 10+, AMD recommends:
    //   10 bytes: 66 2E 0F 1F 84 00 00 00 00 00
    //   11 bytes: 66 66 2E 0F 1F 84 00 00 00 00 00
    let mut bytes = Vec::with_capacity(size);
    let mut remaining = size;

    while remaining >= 11 {
        // AMD-specific 11-byte NOP with CS prefix override
        bytes.extend_from_slice(&[
            0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
        ]);
        remaining -= 11;
    }
    while remaining >= 10 {
        bytes.extend_from_slice(&[
            0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
        ]);
        remaining -= 10;
    }
    while remaining >= 9 {
        bytes.extend_from_slice(&get_multi_byte_nop(9));
        remaining -= 9;
    }
    while remaining >= 8 {
        bytes.extend_from_slice(&get_multi_byte_nop(8));
        remaining -= 8;
    }
    while remaining >= 7 {
        bytes.extend_from_slice(&get_multi_byte_nop(7));
        remaining -= 7;
    }
    while remaining >= 6 {
        bytes.extend_from_slice(&get_multi_byte_nop(6));
        remaining -= 6;
    }
    while remaining >= 5 {
        bytes.extend_from_slice(&get_multi_byte_nop(5));
        remaining -= 5;
    }
    while remaining >= 4 {
        bytes.extend_from_slice(&get_multi_byte_nop(4));
        remaining -= 4;
    }
    while remaining >= 3 {
        bytes.extend_from_slice(&get_multi_byte_nop(3));
        remaining -= 3;
    }
    while remaining >= 2 {
        bytes.extend_from_slice(&get_multi_byte_nop(2));
        remaining -= 2;
    }
    if remaining > 0 {
        bytes.push(0x90);
    }
    bytes
}

// ============================================================================
// PatchPoint Call Sequence Generation
// ============================================================================

/// Generate the complete PatchPoint call sequence including the NOP sled
/// and the CALL instruction.
pub fn generate_patchpoint_call_sequence(
    patchpoint_id: u64,
    nop_sled_size: usize,
    is_64bit: bool,
    config: &PatchableConfig,
) -> Vec<u8> {
    let mut bytes = Vec::new();

    // Emit NOP sled.
    bytes.extend_from_slice(&generate_nop_sled(
        nop_sled_size,
        config.nop_strategy,
        is_64bit,
    ));

    // Emit CALL rel32 (5 bytes: E8 + 4-byte displacement).
    // The displacement will be patched at link time; emit zeros as
    // placeholder.
    bytes.push(0xE8);
    bytes.extend_from_slice(&[0x00, 0x00, 0x00, 0x00]);

    bytes
}

/// Calculate the required NOP sled size for a PatchPoint to ensure the
/// total sequence (NOP sled + CALL) fits within the target patchable
/// region.
pub fn calculate_nop_sled_size(
    target_patchable_size: usize,
    call_size: usize,
) -> usize {
    if target_patchable_size < call_size {
        0
    } else {
        target_patchable_size - call_size
    }
}

// ============================================================================
// StackMap Record Generation
// ============================================================================

impl PatchPoint {
    /// Generate the StackMap record for this PatchPoint.
    pub fn generate_stackmap(
        &self,
        instruction_offset: u32,
        live_values: &[(LiveLocation, u8)],
        calling_conv: CallingConvention,
    ) -> StackMapRecord {
        let locations: Vec<LiveValueLocation> = live_values
            .iter()
            .map(|(loc, size)| LiveValueLocation {
                kind: match loc {
                    LiveLocation::Register(_) => LocationKind::Register,
                    LiveLocation::StackOffset(_) => LocationKind::Direct,
                    LiveLocation::FrameIndex(_) => LocationKind::Direct,
                    LiveLocation::Constant(_) => LocationKind::Constant,
                },
                dwarf_reg_num: match loc {
                    LiveLocation::Register(reg) => reg.dwarf_number() as u16,
                    LiveLocation::StackOffset(off) => {
                        // RSP = DWARF register 7
                        7
                    }
                    LiveLocation::FrameIndex(_) => {
                        // RBP = DWARF register 6
                        6
                    }
                    LiveLocation::Constant(_) => 0,
                },
                offset: match loc {
                    LiveLocation::StackOffset(off) => *off,
                    LiveLocation::FrameIndex(_) => 0,
                    _ => 0,
                },
                size: *size,
            })
            .collect();

        StackMapRecord {
            id: self.id,
            instruction_offset,
            num_locations: locations.len(),
            locations,
            num_live_outs: 0,
            live_outs: vec![],
            stack_size: 0,
            deopt_meta: None,
            calling_conv,
        }
    }
}

// ============================================================================
// Deoptimization: Register Restore Sequence
// ============================================================================

/// Generate the register restore sequence for a deoptimization bundle.
///
/// This function produces a sequence of MOV instructions that restore
/// the optimized register file to the state expected by the interpreter.
/// The stackmap tells us which registers hold which values, and the
/// deoptimization frame metadata tells us where those values belong in
/// the interpreter frame.
pub fn generate_register_restore_sequence(
    deopt_state: &DeoptState,
    stackmap: &StackMapRecord,
    deopt_meta: &DeoptMeta,
) -> Vec<RegRestoreOp> {
    let mut ops = Vec::new();

    // Map each live value from its optimized location to its interpreter
    // target.
    for value in &deopt_state.live_values {
        let restore_op = RegRestoreOp {
            reg: match &value.source {
                LiveLocation::Register(r) => *r,
                _ => X86Reg::Rax, // fallback
            },
            source: match &value.target {
                DeoptTargetLocation::Local(idx) => {
                    RestoreSource::InterpreterLocal(*idx)
                }
                DeoptTargetLocation::ExprStack(depth) => {
                    RestoreSource::InterpreterExprStack(*depth)
                }
                DeoptTargetLocation::Monitor => {
                    RestoreSource::Stack(0)
                }
                DeoptTargetLocation::ReturnAddress => {
                    RestoreSource::Stack(8)
                }
                DeoptTargetLocation::StackPointer => {
                    RestoreSource::Constant(0)
                }
                DeoptTargetLocation::FramePointer => {
                    RestoreSource::Constant(0)
                }
                DeoptTargetLocation::BytecodeOffset => {
                    RestoreSource::Constant(deopt_meta.bytecode_offset as i64)
                }
            },
        };
        ops.push(restore_op);
    }

    // Add return-address setup.
    ops.push(RegRestoreOp {
        reg: X86Reg::Rax,
        source: RestoreSource::Stack(8),
    });

    ops
}

// ============================================================================
// Frame Reconstruction
// ============================================================================

/// Generate the frame reconstruction sequence for a deoptimization
/// bundle.
///
/// This produces a sequence of operations that reconstruct the
/// interpreter frame from the optimized register file, enabling the
/// interpreter to resume execution at the correct bytecode offset.
pub fn generate_frame_reconstruction(
    deopt_state: &DeoptState,
    deopt_meta: &DeoptMeta,
    is_64bit: bool,
) -> Vec<FrameReconstructOp> {
    let mut ops = Vec::new();

    // Step 1: Set up the interpreter frame pointer.
    if is_64bit {
        ops.push(FrameReconstructOp::SetFramePtr { reg: X86Reg::Rbp });
        ops.push(FrameReconstructOp::SetStackPtr { reg: X86Reg::Rsp });
    } else {
        ops.push(FrameReconstructOp::SetFramePtr { reg: X86Reg::Ebp });
        ops.push(FrameReconstructOp::SetStackPtr { reg: X86Reg::Esp });
    }

    // Step 2: Restore each live value to its interpreter location.
    for value in &deopt_state.live_values {
        let reg = match &value.source {
            LiveLocation::Register(r) => *r,
            _ => continue,
        };
        let size = match value.value_type {
            DeoptValueType::Int32 | DeoptValueType::Float32 => 4,
            DeoptValueType::Int64 | DeoptValueType::Float64 | DeoptValueType::ObjectRef
            | DeoptValueType::RawPtr => 8,
            DeoptValueType::Vec128 => 16,
            DeoptValueType::Vec256 => 32,
            DeoptValueType::Bool | DeoptValueType::Byte => 1,
            DeoptValueType::Short => 2,
        };
        match &value.target {
            DeoptTargetLocation::Local(idx) => {
                ops.push(FrameReconstructOp::StoreRegToLocal {
                    reg,
                    local_index: *idx,
                    size,
                });
            }
            DeoptTargetLocation::ExprStack(depth) => {
                ops.push(FrameReconstructOp::StoreRegToExprStack {
                    reg,
                    depth: *depth,
                    size,
                });
            }
            _ => {}
        }
    }

    // Step 3: Set the bytecode offset.
    if is_64bit {
        ops.push(FrameReconstructOp::SetBci {
            reg: X86Reg::Rcx,
            bci: deopt_meta.bytecode_offset,
        });
    } else {
        ops.push(FrameReconstructOp::SetBci {
            reg: X86Reg::Ecx,
            bci: deopt_meta.bytecode_offset,
        });
    }

    // Step 4: Jump to the interpreter dispatch loop.
    ops.push(FrameReconstructOp::JumpToInterpreter {
        entry_point: "__interpreter_dispatch".to_string(),
    });

    ops
}

/// Emit the frame reconstruction sequence as X86 machine code bytes.
pub fn emit_frame_reconstruction_bytes(
    ops: &[FrameReconstructOp],
    is_64bit: bool,
) -> Vec<u8> {
    let mut bytes = Vec::with_capacity(ops.len() * 8);

    for op in ops {
        match op {
            FrameReconstructOp::SetFramePtr { reg } => {
                // MOV frame_ptr_reg, RBP
                if is_64bit {
                    bytes.extend_from_slice(&[0x48, 0x89, 0xE8 | reg.opcode_reg_num()]);
                } else {
                    bytes.extend_from_slice(&[0x89, 0xE8 | reg.opcode_reg_num()]);
                }
            }
            FrameReconstructOp::SetStackPtr { reg } => {
                if is_64bit {
                    bytes.extend_from_slice(&[0x48, 0x89, 0xE0 | reg.opcode_reg_num()]);
                } else {
                    bytes.extend_from_slice(&[0x89, 0xE0 | reg.opcode_reg_num()]);
                }
            }
            FrameReconstructOp::SetBci { reg, bci } => {
                if is_64bit {
                    bytes.push(0x48 | ((reg.rex_b_bit() as u8) << 2));
                    bytes.push(0xB8 | (reg.opcode_reg_num() & 0x07));
                    bytes.extend_from_slice(&bci.to_le_bytes());
                } else {
                    bytes.push(0xB8 | (reg.opcode_reg_num() & 0x07));
                    bytes.extend_from_slice(&(*bci as u32).to_le_bytes());
                }
            }
            FrameReconstructOp::JumpToInterpreter { entry_point: _ } => {
                // JMP rel32 placeholder
                bytes.push(0xE9);
                bytes.extend_from_slice(&[0x00, 0x00, 0x00, 0x00]);
            }
            FrameReconstructOp::Nop => {
                bytes.push(0x90);
            }
            FrameReconstructOp::DebugTrap => {
                bytes.push(0xCC); // INT3
            }
            _ => {
                // Other ops skipped in simple emit; they'd need a full
                // instruction encoder.
            }
        }
    }

    bytes
}

// ============================================================================
// X86 Register Model
// ============================================================================

/// Simplified X86 register representation for patchable instruction
/// generation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum X86Reg {
    // 64-bit registers
    Rax, Rcx, Rdx, Rbx, Rsp, Rbp, Rsi, Rdi,
    R8, R9, R10, R11, R12, R13, R14, R15,
    // 32-bit registers
    Eax, Ecx, Edx, Ebx, Esp, Ebp, Esi, Edi,
    R8d, R9d, R10d, R11d, R12d, R13d, R14d, R15d,
    // 16-bit registers
    Ax, Cx, Dx, Bx, Sp, Bp, Si, Di,
    R8w, R9w, R10w, R11w, R12w, R13w, R14w, R15w,
    // 8-bit registers
    Al, Cl, Dl, Bl, Ah, Ch, Dh, Bh,
    Spl, Bpl, Sil, Dil,
    R8b, R9b, R10b, R11b, R12b, R13b, R14b, R15b,
    // XMM registers
    Xmm0, Xmm1, Xmm2, Xmm3, Xmm4, Xmm5, Xmm6, Xmm7,
    Xmm8, Xmm9, Xmm10, Xmm11, Xmm12, Xmm13, Xmm14, Xmm15,
    // YMM registers
    Ymm0, Ymm1, Ymm2, Ymm3, Ymm4, Ymm5, Ymm6, Ymm7,
    Ymm8, Ymm9, Ymm10, Ymm11, Ymm12, Ymm13, Ymm14, Ymm15,
    // ZMM registers
    Zmm0, Zmm1, Zmm2, Zmm3, Zmm4, Zmm5, Zmm6, Zmm7,
    Zmm8, Zmm9, Zmm10, Zmm11, Zmm12, Zmm13, Zmm14, Zmm15,
    // Special registers
    Rip, Flags,
}

impl X86Reg {
    /// Whether this register is in the 64-bit class.
    pub fn is_64bit(&self) -> bool {
        matches!(
            self,
            X86Reg::Rax
                | X86Reg::Rcx
                | X86Reg::Rdx
                | X86Reg::Rbx
                | X86Reg::Rsp
                | X86Reg::Rbp
                | X86Reg::Rsi
                | X86Reg::Rdi
                | X86Reg::R8
                | X86Reg::R9
                | X86Reg::R10
                | X86Reg::R11
                | X86Reg::R12
                | X86Reg::R13
                | X86Reg::R14
                | X86Reg::R15
        )
    }

    /// Get the opcode register number (0-7).
    pub fn opcode_reg_num(&self) -> u8 {
        match self {
            X86Reg::Rax | X86Reg::Eax | X86Reg::Ax | X86Reg::Al => 0,
            X86Reg::Rcx | X86Reg::Ecx | X86Reg::Cx | X86Reg::Cl => 1,
            X86Reg::Rdx | X86Reg::Edx | X86Reg::Dx | X86Reg::Dl => 2,
            X86Reg::Rbx | X86Reg::Ebx | X86Reg::Bx | X86Reg::Bl => 3,
            X86Reg::Rsp | X86Reg::Esp | X86Reg::Sp | X86Reg::Spl | X86Reg::Ah => 4,
            X86Reg::Rbp | X86Reg::Ebp | X86Reg::Bp | X86Reg::Bpl | X86Reg::Ch => 5,
            X86Reg::Rsi | X86Reg::Esi | X86Reg::Si | X86Reg::Sil | X86Reg::Dh => 6,
            X86Reg::Rdi | X86Reg::Edi | X86Reg::Di | X86Reg::Dil | X86Reg::Bh => 7,
            X86Reg::R8 | X86Reg::R8d | X86Reg::R8w | X86Reg::R8b => 0,
            X86Reg::R9 | X86Reg::R9d | X86Reg::R9w | X86Reg::R9b => 1,
            X86Reg::R10 | X86Reg::R10d | X86Reg::R10w | X86Reg::R10b => 2,
            X86Reg::R11 | X86Reg::R11d | X86Reg::R11w | X86Reg::R11b => 3,
            X86Reg::R12 | X86Reg::R12d | X86Reg::R12w | X86Reg::R12b => 4,
            X86Reg::R13 | X86Reg::R13d | X86Reg::R13w | X86Reg::R13b => 5,
            X86Reg::R14 | X86Reg::R14d | X86Reg::R14w | X86Reg::R14b => 6,
            X86Reg::R15 | X86Reg::R15d | X86Reg::R15w | X86Reg::R15b => 7,
            X86Reg::Xmm0 | X86Reg::Ymm0 | X86Reg::Zmm0 => 0,
            X86Reg::Xmm1 | X86Reg::Ymm1 | X86Reg::Zmm1 => 1,
            X86Reg::Xmm2 | X86Reg::Ymm2 | X86Reg::Zmm2 => 2,
            X86Reg::Xmm3 | X86Reg::Ymm3 | X86Reg::Zmm3 => 3,
            X86Reg::Xmm4 | X86Reg::Ymm4 | X86Reg::Zmm4 => 4,
            X86Reg::Xmm5 | X86Reg::Ymm5 | X86Reg::Zmm5 => 5,
            X86Reg::Xmm6 | X86Reg::Ymm6 | X86Reg::Zmm6 => 6,
            X86Reg::Xmm7 | X86Reg::Ymm7 | X86Reg::Zmm7 => 7,
            X86Reg::Xmm8 | X86Reg::Ymm8 | X86Reg::Zmm8 => 0,
            X86Reg::Xmm9 | X86Reg::Ymm9 | X86Reg::Zmm9 => 1,
            X86Reg::Xmm10 | X86Reg::Ymm10 | X86Reg::Zmm10 => 2,
            X86Reg::Xmm11 | X86Reg::Ymm11 | X86Reg::Zmm11 => 3,
            X86Reg::Xmm12 | X86Reg::Ymm12 | X86Reg::Zmm12 => 4,
            X86Reg::Xmm13 | X86Reg::Ymm13 | X86Reg::Zmm13 => 5,
            X86Reg::Xmm14 | X86Reg::Ymm14 | X86Reg::Zmm14 => 6,
            X86Reg::Xmm15 | X86Reg::Ymm15 | X86Reg::Zmm15 => 7,
            _ => 0,
        }
    }

    /// Get the REX.B bit for this register (1 if reg >= 8).
    pub fn rex_b_bit(&self) -> bool {
        matches!(
            self,
            X86Reg::R8
                | X86Reg::R9
                | X86Reg::R10
                | X86Reg::R11
                | X86Reg::R12
                | X86Reg::R13
                | X86Reg::R14
                | X86Reg::R15
                | X86Reg::R8d
                | X86Reg::R9d
                | X86Reg::R10d
                | X86Reg::R11d
                | X86Reg::R12d
                | X86Reg::R13d
                | X86Reg::R14d
                | X86Reg::R15d
                | X86Reg::R8w
                | X86Reg::R9w
                | X86Reg::R10w
                | X86Reg::R11w
                | X86Reg::R12w
                | X86Reg::R13w
                | X86Reg::R14w
                | X86Reg::R15w
                | X86Reg::R8b
                | X86Reg::R9b
                | X86Reg::R10b
                | X86Reg::R11b
                | X86Reg::R12b
                | X86Reg::R13b
                | X86Reg::R14b
                | X86Reg::R15b
                | X86Reg::Spl
                | X86Reg::Bpl
                | X86Reg::Sil
                | X86Reg::Dil
        )
    }

    /// Get the DWARF register number.
    pub fn dwarf_number(&self) -> u8 {
        match self {
            X86Reg::Rax | X86Reg::Eax | X86Reg::Ax | X86Reg::Al => 0,
            X86Reg::Rdx | X86Reg::Edx | X86Reg::Dx | X86Reg::Dl => 1,
            X86Reg::Rcx | X86Reg::Ecx | X86Reg::Cx | X86Reg::Cl => 2,
            X86Reg::Rbx | X86Reg::Ebx | X86Reg::Bx | X86Reg::Bl => 3,
            X86Reg::Rsi | X86Reg::Esi | X86Reg::Si | X86Reg::Sil => 4,
            X86Reg::Rdi | X86Reg::Edi | X86Reg::Di | X86Reg::Dil => 5,
            X86Reg::Rbp | X86Reg::Ebp | X86Reg::Bp | X86Reg::Bpl => 6,
            X86Reg::Rsp | X86Reg::Esp | X86Reg::Sp | X86Reg::Spl => 7,
            X86Reg::R8 | X86Reg::R8d | X86Reg::R8w | X86Reg::R8b => 8,
            X86Reg::R9 | X86Reg::R9d | X86Reg::R9w | X86Reg::R9b => 9,
            X86Reg::R10 | X86Reg::R10d | X86Reg::R10w | X86Reg::R10b => 10,
            X86Reg::R11 | X86Reg::R11d | X86Reg::R11w | X86Reg::R11b => 11,
            X86Reg::R12 | X86Reg::R12d | X86Reg::R12w | X86Reg::R12b => 12,
            X86Reg::R13 | X86Reg::R13d | X86Reg::R13w | X86Reg::R13b => 13,
            X86Reg::R14 | X86Reg::R14d | X86Reg::R14w | X86Reg::R14b => 14,
            X86Reg::R15 | X86Reg::R15d | X86Reg::R15w | X86Reg::R15b => 15,
            X86Reg::Xmm0 => 17,
            X86Reg::Xmm1 => 18,
            X86Reg::Xmm2 => 19,
            X86Reg::Xmm3 => 20,
            X86Reg::Xmm4 => 21,
            X86Reg::Xmm5 => 22,
            X86Reg::Xmm6 => 23,
            X86Reg::Xmm7 => 24,
            X86Reg::Xmm8 => 25,
            X86Reg::Xmm9 => 26,
            X86Reg::Xmm10 => 27,
            X86Reg::Xmm11 => 28,
            X86Reg::Xmm12 => 29,
            X86Reg::Xmm13 => 30,
            X86Reg::Xmm14 => 31,
            X86Reg::Xmm15 => 32,
            _ => 0,
        }
    }
}

/// Calling convention specification.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum CallingConvention {
    /// System V AMD64 ABI (Linux, macOS, FreeBSD).
    SystemV,
    /// Microsoft x64 calling convention (Windows).
    Win64,
    /// 32-bit System V (i386 Linux).
    SystemV32,
    /// cdecl (32-bit).
    Cdecl,
    /// stdcall (32-bit Windows).
    Stdcall,
    /// fastcall (32-bit).
    Fastcall,
    /// thiscall (32-bit C++).
    Thiscall,
    /// vectorcall (32/64-bit).
    Vectorcall,
    /// regcall (register calling convention).
    Regcall,
    /// Custom calling convention.
    Custom,
}

// ============================================================================
// High-level API
// ============================================================================

impl X86PatchableInstr {
    /// Create a new X86PatchableInstr instance.
    pub fn new(target_triple: String, config: PatchableConfig) -> Self {
        let is_64bit = target_triple.contains("x86_64");
        X86PatchableInstr {
            target_triple,
            is_64bit,
            config,
            stats: PatchableStats::default(),
            stackmaps: HashMap::new(),
            deopt_bundles: HashMap::new(),
            patched_functions: HashSet::new(),
        }
    }

    /// Create a patchable function entry with the configured NOP sled size.
    pub fn create_patchable_entry(&mut self, function_name: &str) -> PatchableEntry {
        let entry = PatchableEntry::new(
            function_name.to_string(),
            self.config.patchable_function_entry_nops,
            self.is_64bit,
            &self.config,
        );
        self.stats.patchable_entries += 1;
        self.stats.entry_nop_bytes += entry.nop_sled_size;
        self.patched_functions.insert(function_name.to_string());
        entry
    }

    /// Create a patchable call site with the configured NOP sled size.
    pub fn create_patchable_call(
        &mut self,
        patchpoint_id: u64,
        callee: &str,
        is_tail_call: bool,
        is_direct: bool,
        num_args: usize,
    ) -> PatchableCall {
        let call = PatchableCall::new(
            patchpoint_id,
            callee.to_string(),
            self.config.patchable_call_nops,
            is_tail_call,
            is_direct,
            num_args,
            &self.config,
        );
        self.stats.patchable_calls += 1;
        self.stats.call_nop_bytes += call.nop_size;
        call
    }

    /// Create a patchable conditional branch.
    pub fn create_patchable_cond_branch(
        &mut self,
        branch_id: u64,
        condition: BranchCondition,
        target_label: &str,
        is_short: bool,
    ) -> PatchableBranch {
        let branch = PatchableBranch::new(
            branch_id,
            PatchableBranchKind::Conditional,
            condition,
            target_label.to_string(),
            self.config.patchable_cond_branch_nops,
            is_short,
            &self.config,
        );
        self.stats.patchable_cond_branches += 1;
        self.stats.branch_nop_bytes += branch.nop_size;
        branch
    }

    /// Create a patchable unconditional branch.
    pub fn create_patchable_uncond_branch(
        &mut self,
        branch_id: u64,
        target_label: &str,
        is_short: bool,
    ) -> PatchableBranch {
        let branch = PatchableBranch::new(
            branch_id,
            PatchableBranchKind::Unconditional,
            BranchCondition::Equal, // don't care for unconditional
            target_label.to_string(),
            self.config.patchable_uncond_branch_nops,
            is_short,
            &self.config,
        );
        self.stats.patchable_uncond_branches += 1;
        self.stats.branch_nop_bytes += branch.nop_size;
        branch
    }

    /// Create a patchable constant.
    pub fn create_patchable_constant(
        &mut self,
        const_id: u64,
        dest_register: X86Reg,
        initial_value: i64,
    ) -> PatchableConstant {
        let width = if dest_register.is_64bit() { 8 } else { 4 };
        let pc = PatchableConstant::new(const_id, dest_register, initial_value, width);
        self.stats.patchable_constants += 1;
        pc
    }

    /// Create a PatchPoint and its associated StackMap record.
    pub fn create_patchpoint(
        &mut self,
        patchpoint_id: u64,
        live_values: &[(LiveLocation, u8)],
        instruction_offset: u32,
        calling_conv: CallingConvention,
    ) -> PatchPoint {
        let mut pp = PatchPoint::new(
            patchpoint_id,
            self.config.patchable_call_nops,
            &self.config,
        );

        let stackmap = pp.generate_stackmap(instruction_offset, live_values, calling_conv);
        pp.stackmap = Some(stackmap.clone());
        self.stackmaps.insert(patchpoint_id, stackmap);
        self.stats.stackmap_records += 1;

        pp
    }

    /// Create a deoptimization bundle for a given PatchPoint.
    pub fn create_deopt_bundle(
        &mut self,
        deopt_id: u64,
        patchpoint_id: u64,
        deopt_state: DeoptState,
        stackmap: &StackMapRecord,
        deopt_meta: DeoptMeta,
    ) -> DeoptBundle {
        let reg_restore =
            generate_register_restore_sequence(&deopt_state, stackmap, &deopt_meta);
        let frame_reconstruction =
            generate_frame_reconstruction(&deopt_state, &deopt_meta, self.is_64bit);

        let bundle = DeoptBundle {
            deopt_id,
            patchpoint_id,
            deopt_state,
            stackmap: Some(stackmap.clone()),
            reg_restore,
            frame_reconstruction,
            interpreter_entry: "__interpreter_dispatch".to_string(),
        };

        self.deopt_bundles.insert(deopt_id, bundle.clone());
        self.stats.deopt_bundles += 1;

        bundle
    }

    /// Emit the complete prologue (including NOP sled) for a patchable
    /// function.
    pub fn emit_patchable_prologue_bytes(&self, entry: &PatchableEntry) -> Vec<u8> {
        let mut bytes = Vec::new();

        // Win64 hotpatch: 2-byte NOP (MOV EDI, EDI = 0x89 0xFF) at
        // function entry, followed by 5 more NOP bytes before the
        // prologue.
        if entry.win64_style && entry.nop_sled_size >= 2 {
            // MOV EDI, EDI (2-byte NOP per Windows hotpatch convention)
            bytes.push(0x89);
            bytes.push(0xFF);
            // Remaining NOPs
            let remaining = entry.nop_sled_size - 2;
            bytes.extend_from_slice(&generate_nop_sled(
                remaining,
                self.config.nop_strategy,
                self.is_64bit,
            ));
        } else {
            bytes.extend_from_slice(&entry.nop_sled_bytes);
        }

        // Standard prologue:
        //   push RBP
        //   mov RBP, RSP
        if self.is_64bit {
            bytes.push(0x55); // push rbp
            bytes.push(0x48); // REX.W
            bytes.push(0x89); // mov
            bytes.push(0xE5); // rbp, rsp
        } else {
            bytes.push(0x55); // push ebp
            bytes.push(0x89); // mov
            bytes.push(0xE5); // ebp, esp
        }

        bytes
    }

    /// Serialize a StackMapRecord to the LLVM StackMap V3 binary format.
    pub fn serialize_stackmap_v3(&self, record: &StackMapRecord) -> Vec<u8> {
        let mut buf = Vec::new();

        // Header
        buf.push(self.config.stackmap_version);
        buf.push(0); // reserved
        buf.push(0); // reserved
        buf.extend_from_slice(&(record.id as u16).to_le_bytes());

        // Function offset
        buf.extend_from_slice(&record.instruction_offset.to_le_bytes());

        // Record count (always 1 per serialized record, but the binary
        // format expects the total count).
        buf.extend_from_slice(&1u16.to_le_bytes());

        // Per-record data
        buf.extend_from_slice(&(record.id as u64).to_le_bytes());
        buf.extend_from_slice(&record.instruction_offset.to_le_bytes());
        buf.extend_from_slice(&(record.num_locations as u16).to_le_bytes());
        // Padding
        buf.push(0);
        buf.push(0);

        // Live-out count
        buf.extend_from_slice(&(record.num_live_outs as u16).to_le_bytes());
        buf.push(0);
        buf.push(0);

        // Locations
        for loc in &record.locations {
            buf.push(loc.kind.encode());
            buf.push(0); // reserved
            buf.extend_from_slice(&loc.dwarf_reg_num.to_le_bytes());
            buf.extend_from_slice(&loc.offset.to_le_bytes());
            // size is implicit in the type; in V3 we include it.
            buf.push(loc.size);
            buf.push(0); // reserved
            buf.push(0); // reserved
            buf.push(0); // reserved
        }

        // Live-outs (empty for non-calls)
        for live_out in &record.live_outs {
            buf.push(live_out.kind.encode());
            buf.push(0);
            buf.extend_from_slice(&live_out.dwarf_reg_num.to_le_bytes());
            buf.extend_from_slice(&live_out.offset.to_le_bytes());
            buf.push(live_out.size);
            buf.push(0);
            buf.push(0);
            buf.push(0);
        }

        // Alignment padding to 8 bytes
        while buf.len() % 8 != 0 {
            buf.push(0);
        }

        buf
    }

    /// Generate statistics summary.
    pub fn stats_summary(&self) -> String {
        format!(
            "X86PatchableInstr Stats:\n\
             - Patchable entries: {}\n\
             - Entry NOP bytes: {}\n\
             - Patchable calls: {}\n\
             - Call NOP bytes: {}\n\
             - Patchable cond branches: {}\n\
             - Patchable uncond branches: {}\n\
             - Branch NOP bytes: {}\n\
             - Patchable constants: {}\n\
             - Stackmap records: {}\n\
             - Deopt bundles: {}\n\
             - Statepoint records: {}\n\
             - Patched functions: {}",
            self.stats.patchable_entries,
            self.stats.entry_nop_bytes,
            self.stats.patchable_calls,
            self.stats.call_nop_bytes,
            self.stats.patchable_cond_branches,
            self.stats.patchable_uncond_branches,
            self.stats.branch_nop_bytes,
            self.stats.patchable_constants,
            self.stats.stackmap_records,
            self.stats.deopt_bundles,
            self.stats.statepoint_records,
            self.patched_functions.len(),
        )
    }

    /// Return whether CALL hot-patching is enabled.
    pub fn hot_patching_enabled(&self) -> bool {
        self.config.patchable_call_nops > 0
    }

    /// Return whether branch hot-patching is enabled.
    pub fn branch_patching_enabled(&self) -> bool {
        self.config.patchable_cond_branch_nops > 0
            || self.config.patchable_uncond_branch_nops > 0
    }
}

// ============================================================================
// Win64 Hot-Patching Convention
// ============================================================================

/// Generate a Windows x64 hot-patching compatible function entry.
///
/// Windows x64 requires at least 2 bytes of patch space (the "MOV EDI,EDI"
/// convention) before any function that may be hot-patched. This function
/// generates the full entry sequence.
pub fn generate_win64_hotpatch_entry(
    patchable_size: usize,
    is_64bit: bool,
) -> Vec<u8> {
    let mut bytes = Vec::with_capacity(patchable_size + 8);

    if patchable_size >= 2 {
        // MOV EDI, EDI = 0x89 0xFF (2-byte hotpatch pad)
        bytes.push(0x89);
        bytes.push(0xFF);
    }

    // Remaining NOPs (at least 5 for Win64)
    let remaining = if patchable_size > 2 {
        patchable_size - 2
    } else {
        0
    };

    if remaining > 0 {
        bytes.extend_from_slice(&generate_nop_sled(
            remaining,
            NopStrategy::Optimal,
            is_64bit,
        ));
    }

    bytes
}

/// Generate a Linux ftrace-compatible NOP sled.
///
/// The Linux kernel's ftrace subsystem uses a 5-byte NOP at the function
/// entry that can be atomically replaced with a CALL to the tracer.
pub fn generate_ftrace_nop_sled() -> Vec<u8> {
    // 5-byte NOP: 0F 1F 44 00 00
    vec![0x0F, 0x1F, 0x44, 0x00, 0x00]
}

/// Generate a kpatch/livepatch-compatible NOP sled.
///
/// Kernel live patching requires a 5-byte NOP that can be replaced with
/// a JMP to the patched function.
pub fn generate_livepatch_nop_sled() -> Vec<u8> {
    // Same as ftrace: 5-byte NOP
    vec![0x0F, 0x1F, 0x44, 0x00, 0x00]
}

// ============================================================================
// Patchable Instruction Byte Sequences
// ============================================================================

/// Generate the raw bytes for a patchable CALL instruction.
///
/// Returns (nop_sled_bytes, call_bytes).
pub fn generate_patchable_call_bytes(
    call_target_offset: i32,
    nop_size: usize,
    is_64bit: bool,
    strategy: NopStrategy,
) -> (Vec<u8>, Vec<u8>) {
    let nop_bytes = generate_nop_sled(nop_size, strategy, is_64bit);

    // CALL rel32: E8 + 4-byte signed displacement
    let mut call_bytes = vec![0xE8];
    call_bytes.extend_from_slice(&call_target_offset.to_le_bytes());

    (nop_bytes, call_bytes)
}

/// Generate the raw bytes for a patchable JMP instruction.
pub fn generate_patchable_jmp_bytes(
    jmp_target_offset: i32,
    nop_size: usize,
    is_64bit: bool,
    strategy: NopStrategy,
) -> (Vec<u8>, Vec<u8>) {
    let nop_bytes = generate_nop_sled(nop_size, strategy, is_64bit);

    // JMP rel32: E9 + 4-byte signed displacement
    let mut jmp_bytes = vec![0xE9];
    jmp_bytes.extend_from_slice(&jmp_target_offset.to_le_bytes());

    (nop_bytes, jmp_bytes)
}

/// Generate a patchable short JMP (2-byte encoding) with NOP sled.
pub fn generate_patchable_short_jmp_bytes(
    jmp_target_offset: i8,
    nop_size: usize,
    is_64bit: bool,
    strategy: NopStrategy,
) -> (Vec<u8>, Vec<u8>) {
    let nop_bytes = generate_nop_sled(nop_size, strategy, is_64bit);

    // JMP rel8: EB + 1-byte signed displacement
    let jmp_bytes = vec![0xEB, jmp_target_offset as u8];

    (nop_bytes, jmp_bytes)
}

/// Generate patchable JCC (conditional) bytes.
pub fn generate_patchable_jcc_bytes(
    condition: BranchCondition,
    target_offset: i32,
    is_short: bool,
    nop_size: usize,
    is_64bit: bool,
    strategy: NopStrategy,
) -> (Vec<u8>, Vec<u8>) {
    let nop_bytes = generate_nop_sled(nop_size, strategy, is_64bit);

    let jcc_bytes = if is_short {
        // JCC rel8: opcode + 1-byte displacement
        vec![condition.opcode_rel8(), target_offset as u8]
    } else {
        // JCC near rel32: 0x0F + 0x8x + 4-byte displacement
        let mut bytes = vec![0x0F, condition.opcode_rel32_prefix()];
        bytes.extend_from_slice(&target_offset.to_le_bytes());
        bytes
    };

    (nop_bytes, jcc_bytes)
}

// ============================================================================
// NOP Sled Size Calculation
// ============================================================================

/// Calculate the total patchable region size including the NOP sled and
/// the instruction it precedes.
pub fn calc_patchable_region_size(nop_size: usize, instr_size: usize) -> usize {
    nop_size + instr_size
}

/// Validate that a NOP sled is legal for the given instruction size.
///
/// On X86, the total patchable region must be at least as large as the
/// instruction it replaces (e.g., patching a 5-byte CALL requires at
/// least a 5-byte JMP target area).
pub fn validate_patchable_region(
    nop_size: usize,
    instr_size: usize,
) -> Result<usize, String> {
    if nop_size < instr_size {
        Err(format!(
            "NOP sled size {} is too small for instruction size {}: \
             cannot patch a {} byte instruction into a {} byte NOP sled",
            nop_size, instr_size, instr_size, nop_size
        ))
    } else {
        Ok(nop_size + instr_size)
    }
}

/// Determine the recommended NOP sled size for a CALL hot-patching site.
///
/// For direct calls, we need at least 5 bytes (JMP rel32) to redirect the
/// call. For indirect calls, we may need up to 14 bytes (MOV + JMP).
pub fn recommended_call_patch_size(is_direct: bool, is_64bit: bool) -> usize {
    if is_direct {
        5 // JMP rel32 can redirect a CALL rel32
    } else if is_64bit {
        14 // MOV RAX, imm64 + JMP RAX
    } else {
        7 // MOV EAX, imm32 + JMP EAX
    }
}

/// Determine the recommended NOP sled size for a branch hot-patching site.
pub fn recommended_branch_patch_size(is_conditional: bool) -> usize {
    if is_conditional {
        // Patching a conditional branch typically requires inverting the
        // condition and falling through, or replacing with a JMP.
        6 // 5-byte JMP rel32 + 1-byte NOP (for alignment)
    } else {
        5 // JMP rel32
    }
}

// ============================================================================
// Testing utilities
// ============================================================================

/// Create a default X86PatchableInstr for testing.
pub fn make_test_patchable_instr() -> X86PatchableInstr {
    X86PatchableInstr::new("x86_64-unknown-linux-gnu".to_string(), PatchableConfig::default())
}

/// Create a Win64 hotpatching configuration.
pub fn make_win64_patchable_instr() -> X86PatchableInstr {
    let config = PatchableConfig {
        patchable_function_entry_nops: 7,
        patchable_call_nops: 5,
        patchable_cond_branch_nops: 2,
        patchable_uncond_branch_nops: 5,
        patchable_constant_bytes: 8,
        win64_hotpatch: true,
        use_long_nops: true,
        nop_strategy: NopStrategy::IntelRecommended,
        ..PatchableConfig::default()
    };
    X86PatchableInstr::new("x86_64-pc-windows-msvc".to_string(), config)
}

/// Create a minimal patching configuration for code-size-constrained
/// environments.
pub fn make_minimal_patchable_instr() -> X86PatchableInstr {
    let config = PatchableConfig {
        patchable_function_entry_nops: 0,
        patchable_call_nops: 0,
        patchable_cond_branch_nops: 0,
        patchable_uncond_branch_nops: 0,
        patchable_constant_bytes: 0,
        nop_strategy: NopStrategy::MinSize,
        ..PatchableConfig::default()
    };
    X86PatchableInstr::new("x86_64-unknown-linux-gnu".to_string(), config)
}

/// Create a full-patching configuration with maximum NOP sleds.
pub fn make_full_patchable_instr() -> X86PatchableInstr {
    let config = PatchableConfig {
        patchable_function_entry_nops: 16,
        patchable_call_nops: 14,
        patchable_cond_branch_nops: 6,
        patchable_uncond_branch_nops: 14,
        patchable_constant_bytes: 16,
        cache_line_align: true,
        use_long_nops: true,
        nop_strategy: NopStrategy::Optimal,
        ..PatchableConfig::default()
    };
    X86PatchableInstr::new("x86_64-unknown-linux-gnu".to_string(), config)
}

// ============================================================================
// Edge Cases & Error Handling
// ============================================================================

/// Error type for patchable instruction operations.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PatchableError {
    /// NOP sled too small for the instruction it precedes.
    NopSledTooSmall {
        required: usize,
        actual: usize,
    },
    /// Cannot find a PatchPoint by ID.
    PatchPointNotFound(u64),
    /// Cannot find a StackMap record by ID.
    StackMapNotFound(u64),
    /// Cannot find a deoptimization bundle by ID.
    DeoptBundleNotFound(u64),
    /// Invalid NOP sled size (must be 0-15 on X86, but larger sleds
    /// are made of multiple NOP instructions).
    InvalidNopSize(usize),
    /// Unsupported calling convention for deopt.
    UnsupportedCallingConv(CallingConvention),
    /// Frame reconstruction would overflow the interpreter frame.
    FrameOverflow { requested: usize, available: usize },
}

impl fmt::Display for PatchableError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PatchableError::NopSledTooSmall { required, actual } => {
                write!(
                    f,
                    "NOP sled size {} is too small; need at least {} bytes",
                    actual, required
                )
            }
            PatchableError::PatchPointNotFound(id) => {
                write!(f, "PatchPoint with ID {} not found", id)
            }
            PatchableError::StackMapNotFound(id) => {
                write!(f, "StackMap record with ID {} not found", id)
            }
            PatchableError::DeoptBundleNotFound(id) => {
                write!(f, "Deoptimization bundle with ID {} not found", id)
            }
            PatchableError::InvalidNopSize(size) => {
                write!(f, "Invalid NOP size: {}", size)
            }
            PatchableError::UnsupportedCallingConv(cc) => {
                write!(f, "Unsupported calling convention for deopt: {:?}", cc)
            }
            PatchableError::FrameOverflow { requested, available } => {
                write!(
                    f,
                    "Interpreter frame overflow: requested {} bytes, {} available",
                    requested, available
                )
            }
        }
    }
}

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

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

    #[test]
    fn test_nop_sled_single_byte() {
        let sled = generate_nop_sled(5, NopStrategy::SingleByte, true);
        assert_eq!(sled.len(), 5);
        assert!(sled.iter().all(|&b| b == 0x90));
    }

    #[test]
    fn test_nop_sled_long_nops() {
        for size in 0..32 {
            let sled = generate_nop_sled(size, NopStrategy::LongNop, true);
            assert_eq!(sled.len(), size, "Size mismatch for NOP sled of size {}", size);
        }
    }

    #[test]
    fn test_nop_sled_zero_size() {
        let sled = generate_nop_sled(0, NopStrategy::Optimal, true);
        assert!(sled.is_empty());
    }

    #[test]
    fn test_multi_byte_nop_all_sizes() {
        for len in 1..=15 {
            let nop = get_multi_byte_nop(len);
            assert_eq!(nop.len(), len, "NOP length mismatch for {} bytes", len);
        }
    }

    #[test]
    fn test_intel_nop_sled() {
        for size in 0..64 {
            let sled = generate_intel_recommended_nop_sled(size);
            assert_eq!(sled.len(), size);
        }
    }

    #[test]
    fn test_amd_nop_sled() {
        for size in 0..64 {
            let sled = generate_amd_recommended_nop_sled(size);
            assert_eq!(sled.len(), size);
        }
    }

    #[test]
    fn test_patchable_entry_creation() {
        let mut pi = make_test_patchable_instr();
        let entry = pi.create_patchable_entry("my_function");
        assert_eq!(entry.function_name, "my_function");
        assert_eq!(entry.nop_sled_size, 5);
        assert_eq!(entry.nop_sled_bytes.len(), 5);
        assert_eq!(pi.stats.patchable_entries, 1);
    }

    #[test]
    fn test_patchable_call_creation() {
        let mut pi = make_test_patchable_instr();
        let call = pi.create_patchable_call(1, "target_fn", false, true, 2);
        assert_eq!(call.callee, "target_fn");
        assert_eq!(call.nop_size, 5);
        assert!(call.is_direct);
        assert!(!call.is_tail_call);
        assert_eq!(pi.stats.patchable_calls, 1);
    }

    #[test]
    fn test_patchable_branch_creation() {
        let mut pi = make_test_patchable_instr();
        let branch = pi.create_patchable_cond_branch(
            1,
            BranchCondition::Equal,
            "loop_header",
            true,
        );
        assert_eq!(branch.branch_kind, PatchableBranchKind::Conditional);
        assert_eq!(branch.condition, BranchCondition::Equal);
        assert_eq!(branch.target_label, "loop_header");
        assert!(branch.is_short);
    }

    #[test]
    fn test_patchable_constant() {
        let mut pi = make_test_patchable_instr();
        let pc = pi.create_patchable_constant(1, X86Reg::Rax, 0xDEADBEEF);
        assert_eq!(pc.initial_value, 0xDEADBEEF);
        assert_eq!(pc.width_bytes, 8);
        let emitted = pc.emit_bytes();
        assert_eq!(emitted.len(), 10); // REX.W + B8+0 + 8-byte imm
    }

    #[test]
    fn test_patchpoint_creation() {
        let mut pi = make_test_patchable_instr();
        let pp = pi.create_patchpoint(
            42,
            &[(LiveLocation::Register(X86Reg::Rax), 8)],
            0x100,
            CallingConvention::SystemV,
        );
        assert_eq!(pp.id, 42);
        assert_eq!(pp.num_live_values, 0); // set by mark_safepoint
        assert!(pp.stackmap.is_some());
    }

    #[test]
    fn test_win64_hotpatch_entry() {
        let entry = generate_win64_hotpatch_entry(7, true);
        // 2 bytes MOV EDI,EDI + 5 bytes NOP
        assert_eq!(entry.len(), 7);
        assert_eq!(entry[0], 0x89);
        assert_eq!(entry[1], 0xFF);
    }

    #[test]
    fn test_ftrace_nop_sled() {
        let sled = generate_ftrace_nop_sled();
        assert_eq!(sled.len(), 5);
        assert_eq!(sled, vec![0x0F, 0x1F, 0x44, 0x00, 0x00]);
    }

    #[test]
    fn test_livepatch_nop_sled() {
        let sled = generate_livepatch_nop_sled();
        assert_eq!(sled.len(), 5);
        assert_eq!(sled, vec![0x0F, 0x1F, 0x44, 0x00, 0x00]);
    }

    #[test]
    fn test_patchable_call_bytes() {
        let (nop, call) = generate_patchable_call_bytes(-5, 5, true, NopStrategy::Optimal);
        assert_eq!(nop.len(), 5);
        assert_eq!(call.len(), 5);
        assert_eq!(call[0], 0xE8);
    }

    #[test]
    fn test_patchable_jcc_bytes_short() {
        let (nop, jcc) = generate_patchable_jcc_bytes(
            BranchCondition::Equal,
            10,
            true,
            2,
            true,
            NopStrategy::Optimal,
        );
        assert_eq!(nop.len(), 2);
        assert_eq!(jcc.len(), 2);
        assert_eq!(jcc[0], 0x74); // JE rel8
        assert_eq!(jcc[1], 10);
    }

    #[test]
    fn test_validate_patchable_region() {
        assert!(validate_patchable_region(5, 5).is_ok());
        assert!(validate_patchable_region(3, 5).is_err());
        assert!(validate_patchable_region(6, 5).is_ok());
    }

    #[test]
    fn test_branch_condition_opcodes() {
        assert_eq!(BranchCondition::Equal.opcode_rel8(), 0x74);
        assert_eq!(BranchCondition::NotEqual.opcode_rel8(), 0x75);
        assert_eq!(BranchCondition::Greater.opcode_rel8(), 0x7F);
        assert_eq!(BranchCondition::Less.opcode_rel8(), 0x7C);
    }

    #[test]
    fn test_stackmap_serialization_v3() {
        let record = StackMapRecord {
            id: 1,
            instruction_offset: 0x100,
            num_locations: 1,
            locations: vec![LiveValueLocation {
                kind: LocationKind::Register,
                dwarf_reg_num: 0, // RAX
                offset: 0,
                size: 8,
            }],
            num_live_outs: 0,
            live_outs: vec![],
            stack_size: 0,
            deopt_meta: None,
            calling_conv: CallingConvention::SystemV,
        };

        let mut pi = make_test_patchable_instr();
        let serialized = pi.serialize_stackmap_v3(&record);
        // StackMap V3 header is 8 bytes + per-record data
        assert!(serialized.len() > 8);
        assert_eq!(serialized[0], 3); // version
    }

    #[test]
    fn test_deopt_bundle_creation() {
        let mut pi = make_test_patchable_instr();
        let deopt_state = DeoptState {
            num_live_regs: 1,
            live_gpr_mask: 0b0001, // RAX
            live_xmm_mask: 0,
            live_stack_slots: vec![],
            live_values: vec![],
        };
        let stackmap = StackMapRecord {
            id: 1,
            instruction_offset: 0x200,
            num_locations: 0,
            locations: vec![],
            num_live_outs: 0,
            live_outs: vec![],
            stack_size: 0,
            deopt_meta: None,
            calling_conv: CallingConvention::SystemV,
        };
        let deopt_meta = DeoptMeta {
            bytecode_offset: 42,
            num_inline_frames: 0,
            frames: vec![],
            deopt_reason: DeoptReason::TypeCheckFailed,
        };

        let bundle = pi.create_deopt_bundle(1, 1, deopt_state, &stackmap, deopt_meta);
        assert_eq!(bundle.deopt_id, 1);
        assert_eq!(bundle.patchpoint_id, 1);
        assert_eq!(pi.stats.deopt_bundles, 1);
    }

    #[test]
    fn test_frame_reconstruction_emission() {
        let ops = vec![
            FrameReconstructOp::SetFramePtr { reg: X86Reg::Rbp },
            FrameReconstructOp::DebugTrap,
            FrameReconstructOp::Nop,
        ];
        let bytes = emit_frame_reconstruction_bytes(&ops, true);
        assert!(!bytes.is_empty());
        // Should have: MOV RBP, RSP (3 bytes) + INT3 (1 byte) + NOP (1 byte)
        assert_eq!(bytes.len(), 5);
    }

    #[test]
    fn test_x86_reg_dwarf_numbers() {
        assert_eq!(X86Reg::Rax.dwarf_number(), 0);
        assert_eq!(X86Reg::Rsp.dwarf_number(), 7);
        assert_eq!(X86Reg::R8.dwarf_number(), 8);
        assert_eq!(X86Reg::Xmm0.dwarf_number(), 17);
    }

    #[test]
    fn test_patchable_error_display() {
        let err = PatchableError::NopSledTooSmall {
            required: 5,
            actual: 3,
        };
        let msg = format!("{}", err);
        assert!(msg.contains("5"));
        assert!(msg.contains("3"));
    }

    #[test]
    fn test_stats_summary() {
        let mut pi = make_test_patchable_instr();
        let _ = pi.create_patchable_entry("f1");
        let _ = pi.create_patchable_call(1, "f2", false, true, 0);
        let summary = pi.stats_summary();
        assert!(summary.contains("Patchable entries: 1"));
        assert!(summary.contains("Patchable calls: 1"));
    }

    #[test]
    fn test_branch_condition_rel32_prefix() {
        assert_eq!(BranchCondition::Equal.opcode_rel32_prefix(), 0x84);
        assert_eq!(BranchCondition::NotEqual.opcode_rel32_prefix(), 0x85);
        assert_eq!(BranchCondition::Greater.opcode_rel32_prefix(), 0x8F);
        assert_eq!(BranchCondition::Less.opcode_rel32_prefix(), 0x8C);
    }

    #[test]
    fn test_min_size_nop_sled() {
        for size in [1, 5, 11, 16, 32, 64] {
            let sled = generate_min_size_nop_sled(size);
            assert_eq!(sled.len(), size);
        }
    }

    #[test]
    fn test_smallest_nop_sled() {
        // Ensure 1-byte NOP sled works
        let sled = generate_nop_sled(1, NopStrategy::SingleByte, true);
        assert_eq!(sled, vec![0x90]);
    }

    #[test]
    fn test_largest_multi_byte_nop() {
        let nop = get_multi_byte_nop(15);
        assert_eq!(nop.len(), 15);
        // Each should start with 0x66 (prefix) then 0x0F 0x1F
        assert_eq!(nop[7], 0x0F);
        assert_eq!(nop[8], 0x1F);
    }

    #[test]
    fn test_location_kind_encoding() {
        assert_eq!(LocationKind::Register.encode(), 1);
        assert_eq!(LocationKind::Direct.encode(), 2);
        assert_eq!(LocationKind::Indirect.encode(), 3);
        assert_eq!(LocationKind::Constant.encode(), 4);
        assert_eq!(LocationKind::ConstIndex.encode(), 5);
    }

    #[test]
    fn test_deopt_reason_display() {
        assert_eq!(format!("{}", DeoptReason::TypeCheckFailed), "type_check");
        assert_eq!(format!("{}", DeoptReason::CHAFailed), "cha_failed");
        assert_eq!(format!("{}", DeoptReason::None), "none");
    }
}