llvm-native-core 0.1.16

//! X86 NOP Sled — comprehensive NOP generation, alignment padding, NOP sled
//! construction for hot-patching and code alignment on the X86/X86-64
//! architecture family.
//!
//! This module provides a complete catalog of X86 NOP encodings, from the
//! single-byte `0x90` through multi-byte sequences up to 15 bytes, following
//! both Intel and AMD optimization guidelines. It supports all common
//! alignment scenarios: function entry alignment (16/32/64-byte boundaries),
//! loop header alignment, branch target alignment, and NOP sleds for
//! hot-patching.
//!
//! ## Module Organization
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────────────┐
//! │                          X86 NOP Sled                                    │
//! │  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────────────┐  │
//! │  │  NOP Generation  │  │  Alignment NOP   │  │  Hot-Patch Sled     │  │
//! │  │  1–15 byte NOPs  │  │  16/32/64-byte   │  │  ftrace / kpatch    │  │
//! │  │  Intel / AMD opt │  │  Function entry  │  │  / livepatch sleds  │  │
//! │  │  guides reference │  │  alignment       │  │                      │  │
//! │  └──────────────────┘  └──────────────────┘  └───────────────────────┘  │
//! │  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────────────┐  │
//! │  │  Loop Alignment  │  │  Branch Target   │  │  NOP Selection       │  │
//! │  │  Loop header     │  │  Alignment       │  │  Code size vs decode │  │
//! │  │  alignment rules │  │  BTB-friendly    │  │  bandwidth tradeoffs │  │
//! │  └──────────────────┘  └──────────────────┘  └───────────────────────┘  │
//! └─────────────────────────────────────────────────────────────────────────┘
//! ```
//!
//! ## NOP Encodings
//!
//! The X86 ISA defines several official and unofficial NOP encodings:
//!
//! | Bytes | Intel Recommended Encoding              | AMD Recommended Encoding               |
//! |-------|----------------------------------------|----------------------------------------|
//! | 1     | `90`                                   | `90`                                   |
//! | 2     | `66 90`                                | `66 90`                                |
//! | 3     | `0F 1F 00`                             | `0F 1F 00`                             |
//! | 4     | `0F 1F 40 00`                          | `0F 1F 40 00`                          |
//! | 5     | `0F 1F 44 00 00`                       | `0F 1F 44 00 00`                       |
//! | 6     | `66 0F 1F 44 00 00`                    | `66 0F 1F 44 00 00`                    |
//! | 7     | `0F 1F 80 00 00 00 00`                 | `0F 1F 80 00 00 00 00`                 |
//! | 8     | `0F 1F 84 00 00 00 00 00`              | `0F 1F 84 00 00 00 00 00`              |
//! | 9     | `66 0F 1F 84 00 00 00 00 00`           | `66 0F 1F 84 00 00 00 00 00`           |
//! | 10    | `66 66 0F 1F 84 00 00 00 00 00`        | `66 2E 0F 1F 84 00 00 00 00 00`        |
//! | 11    | `66 66 66 0F 1F 84 00 00 00 00 00`     | `66 66 2E 0F 1F 84 00 00 00 00 00`     |
//! | 12    | `66 66 66 66 0F 1F 84 00 00 00 00 00`  | `2E 66 66 2E 0F 1F 84 00 00 00 00 00`  |
//! | 13    | `66 66 66 66 66 0F 1F 84 00 00 00 ...` | `66 2E 66 2E 0F 1F 84 00 00 00 00 00`  |
//! | 14    | 6 × `66` + `0F 1F 84 00 00 00 00 00`   | multi-prefix variant                   |
//! | 15    | 7 × `66` + `0F 1F 84 00 00 00 00 00`   | multi-prefix variant                   |
//!
//! ## Multi-byte NOP Internals
//!
//! The canonical multi-byte NOP uses the two-byte opcode `0F 1F` (NOP with
//! ModR/M byte). The ModR/M byte and optional SIB/displacement bytes are
//! ignored by the CPU, so they can be used as padding. The encoding is:
//!
//! ```
//! [prefixes...] 0F 1F [ModR/M] [SIB] [disp32]
//! ```
//!
//! Prefixes accepted before the NOP opcode include:
//! - `66` (operand-size override)
//! - `2E` (CS segment override)
//! - `3E` (DS segment override)
//! - `26` (ES segment override)
//! - `64` (FS segment override)
//! - `65` (GS segment override)
//! - `67` (address-size override)
//! - `F0` (LOCK prefix — discouraged for NOPs)
//! - `F2` (REPNE prefix)
//! - `F3` (REP prefix)
//!
//! ## Alignment Strategies
//!
//! Different alignment targets benefit from different NOP strategies:
//!
//! - **Function entries (16-byte)**: On modern Intel/AMD cores, aligning
//!   function entries to 16-byte boundaries improves fetch bandwidth.
//!   Use `NopStrategy::IntelRecommended`.
//! - **Loop headers (16/32/64-byte)**: Loop alignment reduces front-end
//!   stalls by ensuring the loop body fits within the μop cache and LSD
//!   (Loop Stream Detector). Use `AlignmentTarget::LoopHeader`.
//! - **Branch targets (16-byte)**: Aligning branch targets (especially
//!   unconditional jump targets) improves BTB (Branch Target Buffer)
//!   utilization and reduces branch misprediction penalties.
//! - **Hot-patch sleds**: NOP sleds for runtime patching must be
//!   overwritable with real instructions. The sled size dictates the
//!   maximum instruction that can be patched in.
//!
//! ## Clean-room reconstruction from:
//!
//! - Intel® 64 and IA-32 Architectures Software Developer's Manual
//!   (volumes 1, 2A, 2B, 2C, 2D, 3A, 3B, 3C, 3D)
//! - Intel® 64 and IA-32 Architectures Optimization Reference Manual
//!   (Order #: 248966, Appendix B: Using NOPs for Code Alignment)
//! - AMD64 Architecture Programmer's Manual (volumes 1-5)
//! - AMD Software Optimization Guide for AMD Family Processors
//! - Agner Fog's microarchitecture documentation
//! - Intel® Atom™ Microarchitecture Optimization Guide
//! - Intel® Silvermont/Goldmont Microarchitecture Optimization Guide
//!
//! Zero LLVM source code consultation. All behavior reconstructed from
//! published specifications and black-box oracle interrogation.

#![allow(non_upper_case_globals, dead_code)]

use std::fmt;

// ============================================================================
// Core Types
// ============================================================================

/// The primary NOP sled generator for X86/X86-64.
#[derive(Debug, Clone)]
pub struct X86NopSled {
    /// Whether targeting 64-bit mode (affects address-size prefix usage).
    pub is_64bit: bool,
    /// The NOP strategy to use.
    pub strategy: NopSledStrategy,
    /// Target microarchitecture for tuning (affects NOP preference).
    pub microarch: NopMicroArch,
    /// Current offset counter for alignment calculation.
    pub current_offset: u64,
    /// Statistics accumulated during generation.
    pub stats: NopSledStats,
}

/// NOP generation strategy.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NopSledStrategy {
    /// Always emit single-byte NOPs (`0x90`). Fastest to decode but
    /// wastes front-end bandwidth on long sleds.
    SingleByte,
    /// Emit the optimal multi-byte NOP sequence for each length,
    /// balancing decode bandwidth with μop cache occupancy.
    Optimal,
    /// Use Intel's recommended NOP sequences from the Optimization
    /// Reference Manual.
    Intel,
    /// Use AMD's recommended NOP sequences from the Software
    /// Optimization Guide.
    Amd,
    /// Minimize code size: use the fewest NOP instructions possible.
    MinSize,
    /// Minimize decode cost: use the shortest NOP instructions to
    /// saturate the decoders without creating long-NOP decode bubbles.
    MinDecode,
    /// Use only the official NOP encodings documented in the Intel SDM.
    /// Avoids prefix-heavy NOPs for maximum compatibility.
    Compat,
    /// Maximize the number of contiguous patchable bytes for
    /// hot-patching (prefer single large NOPs).
    MaxPatchable,
}

/// Target microarchitecture for NOP tuning.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum NopMicroArch {
    /// Generic x86-64 (use safe defaults).
    Generic,
    // Intel P-cores
    SandyBridge,
    IvyBridge,
    Haswell,
    Broadwell,
    Skylake,
    KabyLake,
    CoffeeLake,
    CometLake,
    CascadeLake,
    IceLake,
    TigerLake,
    RocketLake,
    AlderLakeP,
    RaptorLakeP,
    MeteorLakeP,
    ArrowLakeP,
    LunarLakeP,
    GraniteRapids,
    // Intel E-cores
    Goldmont,
    GoldmontPlus,
    Tremont,
    Gracemont,
    Crestmont,
    Skymont,
    Darkmont,
    // Intel Atom (in-order)
    Bonnell,
    Saltwell,
    Silvermont,
    Airmont,
    // AMD
    Zen1,
    Zen2,
    Zen3,
    Zen4,
    Zen5,
    Zen6,
    // Via
    Nano,
    NanoX2,
    NanoX4,
}

impl NopMicroArch {
    /// Whether this microarchitecture prefers long NOPs.
    pub fn prefers_long_nops(&self) -> bool {
        match self {
            NopMicroArch::Generic
            | NopMicroArch::SandyBridge
            | NopMicroArch::IvyBridge
            | NopMicroArch::Haswell
            | NopMicroArch::Broadwell
            | NopMicroArch::Skylake
            | NopMicroArch::KabyLake
            | NopMicroArch::CoffeeLake
            | NopMicroArch::CometLake
            | NopMicroArch::CascadeLake
            | NopMicroArch::IceLake
            | NopMicroArch::TigerLake
            | NopMicroArch::RocketLake
            | NopMicroArch::AlderLakeP
            | NopMicroArch::RaptorLakeP
            | NopMicroArch::MeteorLakeP
            | NopMicroArch::ArrowLakeP
            | NopMicroArch::LunarLakeP
            | NopMicroArch::GraniteRapids
            | NopMicroArch::Zen1
            | NopMicroArch::Zen2
            | NopMicroArch::Zen3
            | NopMicroArch::Zen4
            | NopMicroArch::Zen5
            | NopMicroArch::Zen6 => true,
            NopMicroArch::Bonnell
            | NopMicroArch::Saltwell
            | NopMicroArch::Silvermont
            | NopMicroArch::Airmont
            | NopMicroArch::Goldmont
            | NopMicroArch::GoldmontPlus => false,
            NopMicroArch::Tremont
            | NopMicroArch::Gracemont
            | NopMicroArch::Crestmont
            | NopMicroArch::Skymont
            | NopMicroArch::Darkmont => true,
            _ => false,
        }
    }

    /// The decoder width (instructions per cycle) for this microarchitecture.
    pub fn decode_width(&self) -> u8 {
        match self {
            NopMicroArch::Bonnell | NopMicroArch::Saltwell => 2,
            NopMicroArch::Silvermont | NopMicroArch::Airmont => 2,
            NopMicroArch::Goldmont | NopMicroArch::GoldmontPlus => 3,
            NopMicroArch::Tremont | NopMicroArch::Gracemont => 6, // 2×3 clusters
            NopMicroArch::Crestmont | NopMicroArch::Skymont => 6,
            NopMicroArch::Darkmont => 6,
            NopMicroArch::SandyBridge | NopMicroArch::IvyBridge => 4,
            NopMicroArch::Haswell | NopMicroArch::Broadwell => 4,
            NopMicroArch::Skylake
            | NopMicroArch::KabyLake
            | NopMicroArch::CoffeeLake
            | NopMicroArch::CometLake
            | NopMicroArch::CascadeLake => 5, // 4+1 complex decoder
            NopMicroArch::IceLake | NopMicroArch::TigerLake | NopMicroArch::RocketLake => 5,
            NopMicroArch::AlderLakeP | NopMicroArch::RaptorLakeP => 6,
            NopMicroArch::MeteorLakeP | NopMicroArch::ArrowLakeP | NopMicroArch::LunarLakeP => 6,
            NopMicroArch::GraniteRapids => 6,
            NopMicroArch::Zen1 | NopMicroArch::Zen2 => 4,
            NopMicroArch::Zen3 | NopMicroArch::Zen4 => 4,
            NopMicroArch::Zen5 | NopMicroArch::Zen6 => 4, // dual-4 = 8 macro-ops
            _ => 4,
        }
    }

    /// Preferred cache-line size for alignment on this microarchitecture.
    pub fn cache_line_size(&self) -> u32 {
        match self {
            NopMicroArch::Bonnell | NopMicroArch::Saltwell => 64,
            _ => 64, // All modern x86 cores use 64-byte cache lines
        }
    }
}

/// Statistics for NOP sled generation.
#[derive(Debug, Clone, Default)]
pub struct NopSledStats {
    /// Total NOP bytes emitted.
    pub total_nop_bytes: u64,
    /// Number of single-byte NOPs emitted.
    pub single_byte_nops: u64,
    /// Number of multi-byte NOPs emitted.
    pub multi_byte_nops: u64,
    /// Total alignment padding bytes emitted.
    pub alignment_bytes: u64,
    /// Number of function-entry alignments performed.
    pub function_alignments: u64,
    /// Number of loop-header alignments performed.
    pub loop_alignments: u64,
    /// Number of branch-target alignments performed.
    pub branch_alignments: u64,
}

// ============================================================================
// NOP Sequence Catalog
// ============================================================================

/// A single NOP instruction encoding, 1 to 15 bytes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NopSequence {
    /// The raw byte sequence for this NOP.
    pub bytes: Vec<u8>,
    /// Length in bytes (1–15).
    pub len: usize,
    /// The variant of this NOP sequence.
    pub variant: NopVariant,
    /// Whether this NOP uses segment-override prefixes.
    pub uses_segment_override: bool,
    /// Number of prefix bytes before the opcode.
    pub prefix_count: u8,
    /// Estimated decode cost (cycles).
    pub decode_cost: u8,
}

/// Variant of NOP sequence.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NopVariant {
    /// Single-byte XCHG EAX,EAX (0x90).
    XchgEaxEax,
    /// Operand-size override + XCHG AX,AX (66 90).
    OpSizeXchg,
    /// Two-byte opcode 0F 1F with ModR/M.
    TwoByte0F1F,
    /// Two-byte opcode 0F 1F with ModR/M + SIB.
    TwoByte0F1FSib,
    /// Two-byte opcode 0F 1F with ModR/M + disp32.
    TwoByte0F1FDisp32,
    /// Two-byte opcode 0F 1F with ModR/M + SIB + disp32 (canonical long NOP).
    LongNop0F1F,
    /// Segment-prefix-based NOP (AMD convention).
    SegmentNop,
    /// Multi-prefix NOP (many 66/2E prefixes).
    MultiPrefixNop,
}

impl NopVariant {
    /// Whether this NOP variant is considered "official" per Intel SDM.
    pub fn is_official_intel(&self) -> bool {
        match self {
            NopVariant::XchgEaxEax
            | NopVariant::OpSizeXchg
            | NopVariant::TwoByte0F1F
            | NopVariant::TwoByte0F1FSib
            | NopVariant::TwoByte0F1FDisp32
            | NopVariant::LongNop0F1F => true,
            NopVariant::SegmentNop | NopVariant::MultiPrefixNop => false,
        }
    }

    /// Whether this NOP variant is recommended by AMD.
    pub fn is_amd_recommended(&self) -> bool {
        match self {
            NopVariant::XchgEaxEax
            | NopVariant::OpSizeXchg
            | NopVariant::TwoByte0F1F
            | NopVariant::TwoByte0F1FSib
            | NopVariant::TwoByte0F1FDisp32
            | NopVariant::LongNop0F1F
            | NopVariant::SegmentNop => true,
            NopVariant::MultiPrefixNop => false,
        }
    }
}

// ============================================================================
// NOP Sequence Tables
// ============================================================================

/// The complete catalog of NOP sequences indexed by byte length (1–15)
/// for Intel's recommended encodings.
pub fn intel_nop_sequence(len: usize) -> Option<NopSequence> {
    match len {
        1 => Some(NopSequence {
            bytes: vec![0x90],
            len: 1,
            variant: NopVariant::XchgEaxEax,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        2 => Some(NopSequence {
            bytes: vec![0x66, 0x90],
            len: 2,
            variant: NopVariant::OpSizeXchg,
            uses_segment_override: false,
            prefix_count: 1,
            decode_cost: 1,
        }),
        3 => Some(NopSequence {
            bytes: vec![0x0F, 0x1F, 0x00],
            len: 3,
            variant: NopVariant::TwoByte0F1F,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        4 => Some(NopSequence {
            bytes: vec![0x0F, 0x1F, 0x40, 0x00],
            len: 4,
            variant: NopVariant::TwoByte0F1FSib,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        5 => Some(NopSequence {
            bytes: vec![0x0F, 0x1F, 0x44, 0x00, 0x00],
            len: 5,
            variant: NopVariant::LongNop0F1F,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        6 => Some(NopSequence {
            bytes: vec![0x66, 0x0F, 0x1F, 0x44, 0x00, 0x00],
            len: 6,
            variant: NopVariant::LongNop0F1F,
            uses_segment_override: false,
            prefix_count: 1,
            decode_cost: 1,
        }),
        7 => Some(NopSequence {
            bytes: vec![0x0F, 0x1F, 0x80, 0x00, 0x00, 0x00, 0x00],
            len: 7,
            variant: NopVariant::TwoByte0F1FDisp32,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        8 => Some(NopSequence {
            bytes: vec![0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00],
            len: 8,
            variant: NopVariant::LongNop0F1F,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        9 => Some(NopSequence {
            bytes: vec![0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00],
            len: 9,
            variant: NopVariant::LongNop0F1F,
            uses_segment_override: false,
            prefix_count: 1,
            decode_cost: 1,
        }),
        10 => Some(NopSequence {
            bytes: vec![0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00],
            len: 10,
            variant: NopVariant::MultiPrefixNop,
            uses_segment_override: false,
            prefix_count: 2,
            decode_cost: 1,
        }),
        11 => Some(NopSequence {
            bytes: vec![
                0x66, 0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
            ],
            len: 11,
            variant: NopVariant::MultiPrefixNop,
            uses_segment_override: false,
            prefix_count: 3,
            decode_cost: 2,
        }),
        12 => Some(NopSequence {
            bytes: vec![
                0x66, 0x66, 0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
            ],
            len: 12,
            variant: NopVariant::MultiPrefixNop,
            uses_segment_override: false,
            prefix_count: 4,
            decode_cost: 2,
        }),
        13 => Some(NopSequence {
            bytes: vec![
                0x66, 0x66, 0x66, 0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
            ],
            len: 13,
            variant: NopVariant::MultiPrefixNop,
            uses_segment_override: false,
            prefix_count: 5,
            decode_cost: 2,
        }),
        14 => Some(NopSequence {
            bytes: vec![
                0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
            ],
            len: 14,
            variant: NopVariant::MultiPrefixNop,
            uses_segment_override: false,
            prefix_count: 6,
            decode_cost: 2,
        }),
        15 => Some(NopSequence {
            bytes: vec![
                0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00,
                0x00,
            ],
            len: 15,
            variant: NopVariant::MultiPrefixNop,
            uses_segment_override: false,
            prefix_count: 7,
            decode_cost: 2,
        }),
        _ => None,
    }
}

/// The complete catalog of NOP sequences indexed by byte length (1–15)
/// for AMD's recommended encodings.
pub fn amd_nop_sequence(len: usize) -> Option<NopSequence> {
    match len {
        1 => Some(NopSequence {
            bytes: vec![0x90],
            len: 1,
            variant: NopVariant::XchgEaxEax,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        2 => Some(NopSequence {
            bytes: vec![0x66, 0x90],
            len: 2,
            variant: NopVariant::OpSizeXchg,
            uses_segment_override: false,
            prefix_count: 1,
            decode_cost: 1,
        }),
        3 => Some(NopSequence {
            bytes: vec![0x0F, 0x1F, 0x00],
            len: 3,
            variant: NopVariant::TwoByte0F1F,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        4 => Some(NopSequence {
            bytes: vec![0x0F, 0x1F, 0x40, 0x00],
            len: 4,
            variant: NopVariant::TwoByte0F1FSib,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        5 => Some(NopSequence {
            bytes: vec![0x0F, 0x1F, 0x44, 0x00, 0x00],
            len: 5,
            variant: NopVariant::LongNop0F1F,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        6 => Some(NopSequence {
            bytes: vec![0x66, 0x0F, 0x1F, 0x44, 0x00, 0x00],
            len: 6,
            variant: NopVariant::LongNop0F1F,
            uses_segment_override: false,
            prefix_count: 1,
            decode_cost: 1,
        }),
        7 => Some(NopSequence {
            bytes: vec![0x0F, 0x1F, 0x80, 0x00, 0x00, 0x00, 0x00],
            len: 7,
            variant: NopVariant::TwoByte0F1FDisp32,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        8 => Some(NopSequence {
            bytes: vec![0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00],
            len: 8,
            variant: NopVariant::LongNop0F1F,
            uses_segment_override: false,
            prefix_count: 0,
            decode_cost: 1,
        }),
        9 => Some(NopSequence {
            bytes: vec![0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00],
            len: 9,
            variant: NopVariant::LongNop0F1F,
            uses_segment_override: false,
            prefix_count: 1,
            decode_cost: 1,
        }),
        10 => Some(NopSequence {
            // AMD convention: use CS segment override instead of 66 prefix
            bytes: vec![0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00],
            len: 10,
            variant: NopVariant::SegmentNop,
            uses_segment_override: true,
            prefix_count: 2,
            decode_cost: 1,
        }),
        11 => Some(NopSequence {
            bytes: vec![
                0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
            ],
            len: 11,
            variant: NopVariant::SegmentNop,
            uses_segment_override: true,
            prefix_count: 3,
            decode_cost: 2,
        }),
        12 => Some(NopSequence {
            bytes: vec![
                0x66, 0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
            ],
            len: 12,
            variant: NopVariant::SegmentNop,
            uses_segment_override: true,
            prefix_count: 4,
            decode_cost: 2,
        }),
        13 => Some(NopSequence {
            bytes: vec![
                0x66, 0x66, 0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
            ],
            len: 13,
            variant: NopVariant::SegmentNop,
            uses_segment_override: true,
            prefix_count: 5,
            decode_cost: 2,
        }),
        14 => Some(NopSequence {
            bytes: vec![
                0x66, 0x66, 0x66, 0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
            ],
            len: 14,
            variant: NopVariant::SegmentNop,
            uses_segment_override: true,
            prefix_count: 6,
            decode_cost: 3,
        }),
        15 => Some(NopSequence {
            bytes: vec![
                0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00,
                0x00,
            ],
            len: 15,
            variant: NopVariant::SegmentNop,
            uses_segment_override: true,
            prefix_count: 7,
            decode_cost: 3,
        }),
        _ => None,
    }
}

/// Get the NOP sequence for a given length using the "optimal" strategy,
/// which balances decode bandwidth, μop cache occupancy, and code size.
pub fn optimal_nop_sequence(len: usize) -> Option<NopSequence> {
    if len == 0 {
        return None;
    }
    if len > 15 {
        return None;
    }

    // For lengths 1–9, use the Intel/standard encoding.
    // For lengths 10–15, prefer the shorter decode-cost variant.
    if len <= 9 {
        intel_nop_sequence(len)
    } else {
        // Compare Intel vs AMD for decode cost; prefer the lower-cost one.
        let intel = intel_nop_sequence(len);
        let amd = amd_nop_sequence(len);

        match (intel, amd) {
            (Some(i), Some(a)) => {
                if i.decode_cost <= a.decode_cost {
                    Some(i)
                } else {
                    Some(a)
                }
            }
            (Some(i), None) => Some(i),
            (None, Some(a)) => Some(a),
            (None, None) => None,
        }
    }
}

/// Get a NOP sequence using the "compatible" strategy — use only
/// officially documented NOP encodings, avoiding excessive prefixes.
pub fn compat_nop_sequence(len: usize) -> Option<NopSequence> {
    if len == 0 {
        return None;
    }
    if len > 9 {
        // For >9 bytes, we must use prefix-heavy NOPs, but we can
        // limit to the minimum.
        // Use the largest official NOP (9 bytes) plus single-byte NOPs.
        None // Caller should decompose into smaller sequences.
    } else {
        intel_nop_sequence(len)
    }
}

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

impl X86NopSled {
    /// Create a new NOP sled generator.
    pub fn new(is_64bit: bool, strategy: NopSledStrategy, microarch: NopMicroArch) -> Self {
        X86NopSled {
            is_64bit,
            strategy,
            microarch,
            current_offset: 0,
            stats: NopSledStats::default(),
        }
    }

    /// Create a NOP sled generator with the default optimal strategy.
    pub fn default_for(is_64bit: bool) -> Self {
        Self::new(is_64bit, NopSledStrategy::Optimal, NopMicroArch::Generic)
    }

    /// Generate a NOP sled of exactly `size` bytes.
    ///
    /// Uses the configured strategy to decide which NOP sequences to emit.
    /// For sizes > 15, the sled is decomposed into multiple NOP instructions
    /// whose total length equals `size`.
    pub fn generate_sled(&mut self, size: usize) -> Vec<u8> {
        if size == 0 {
            return vec![];
        }

        let bytes = match self.strategy {
            NopSledStrategy::SingleByte => {
                self.stats.single_byte_nops += size as u64;
                self.stats.total_nop_bytes += size as u64;
                vec![0x90; size]
            }
            NopSledStrategy::Optimal => {
                self.generate_sled_with_strategy(size, optimal_nop_sequence)
            }
            NopSledStrategy::Intel => self.generate_sled_with_strategy(size, intel_nop_sequence),
            NopSledStrategy::Amd => self.generate_sled_with_strategy(size, amd_nop_sequence),
            NopSledStrategy::MinSize => self.generate_min_size_sled(size),
            NopSledStrategy::MinDecode => self.generate_min_decode_sled(size),
            NopSledStrategy::Compat => self.generate_compat_sled(size),
            NopSledStrategy::MaxPatchable => self.generate_max_patchable_sled(size),
        };

        self.current_offset += bytes.len() as u64;
        bytes
    }

    /// Generate a sled using a given NOP-sequence lookup function.
    fn generate_sled_with_strategy<F>(&mut self, size: usize, get_nop: F) -> Vec<u8>
    where
        F: Fn(usize) -> Option<NopSequence>,
    {
        let mut bytes = Vec::with_capacity(size);
        let mut remaining = size;

        while remaining > 0 {
            // Try to use the largest possible NOP.
            let nop_len = if remaining > 15 { 15 } else { remaining };
            if let Some(nop) = get_nop(nop_len) {
                bytes.extend_from_slice(&nop.bytes);
                self.stats.multi_byte_nops += 1;
                self.stats.total_nop_bytes += nop.len as u64;
                remaining -= nop.len;
            } else {
                // Fallback to single-byte NOPs.
                let count = remaining.min(15);
                bytes.extend(std::iter::repeat(0x90).take(count));
                self.stats.single_byte_nops += count as u64;
                self.stats.total_nop_bytes += count as u64;
                remaining -= count;
            }
        }

        bytes
    }

    /// Generate a sled that minimizes total code size.
    fn generate_min_size_sled(&mut self, size: usize) -> Vec<u8> {
        let mut bytes = Vec::with_capacity(size);
        let mut remaining = size;

        // Greedy: use largest NOPs first.
        let nop_lengths = [15, 9, 8, 7, 6, 5, 4, 3, 2, 1];
        for &nop_len in &nop_lengths {
            while remaining >= nop_len {
                let nop_seq = match self.strategy {
                    NopSledStrategy::Amd => amd_nop_sequence(nop_len),
                    _ => intel_nop_sequence(nop_len),
                };
                if let Some(nop) = nop_seq {
                    bytes.extend_from_slice(&nop.bytes);
                    remaining -= nop_len;
                    self.stats.multi_byte_nops += 1;
                    self.stats.total_nop_bytes += nop_len as u64;
                }
            }
        }

        bytes
    }

    /// Generate a sled that minimizes decode cost.
    /// Uses the smallest NOPs possible to avoid long-NOP decode bubbles.
    fn generate_min_decode_sled(&mut self, size: usize) -> Vec<u8> {
        // On modern Intel cores (Skylake+), the decoder can handle 4-6
        // instructions per cycle. Short NOPs (1-2 bytes) maximize the
        // number of NOPs that can be decoded in parallel. However, for
        // large sleds, this wastes μop cache space.
        //
        // Strategy: use 1-byte NOPs for small gaps (< 8 bytes) and
        // 2-4 byte NOPs for larger gaps.

        let mut bytes = Vec::with_capacity(size);
        let mut remaining = size;

        while remaining >= 4 {
            if let Some(nop) = intel_nop_sequence(4) {
                bytes.extend_from_slice(&nop.bytes);
                remaining -= 4;
                self.stats.multi_byte_nops += 1;
                self.stats.total_nop_bytes += 4;
            }
        }
        while remaining >= 2 {
            if let Some(nop) = intel_nop_sequence(2) {
                bytes.extend_from_slice(&nop.bytes);
                remaining -= 2;
                self.stats.multi_byte_nops += 1;
                self.stats.total_nop_bytes += 2;
            }
        }
        if remaining > 0 {
            bytes.push(0x90);
            self.stats.single_byte_nops += 1;
            self.stats.total_nop_bytes += 1;
        }

        bytes
    }

    /// Generate a sled using only officially documented NOP encodings.
    fn generate_compat_sled(&mut self, size: usize) -> Vec<u8> {
        let mut bytes = Vec::with_capacity(size);
        let mut remaining = size;

        // For compatibility, use only lengths 1-9 with canonical
        // encodings. For larger gaps, combine 9+N NOPs.
        while remaining >= 9 {
            if let Some(nop) = intel_nop_sequence(9) {
                bytes.extend_from_slice(&nop.bytes);
                remaining -= 9;
                self.stats.multi_byte_nops += 1;
                self.stats.total_nop_bytes += 9;
            }
        }
        while remaining > 0 {
            let nop_len = remaining.min(9);
            if let Some(nop) = intel_nop_sequence(nop_len) {
                bytes.extend_from_slice(&nop.bytes);
                remaining -= nop_len;
                self.stats.multi_byte_nops += 1;
                self.stats.total_nop_bytes += nop_len as u64;
            } else {
                bytes.push(0x90);
                remaining -= 1;
                self.stats.single_byte_nops += 1;
                self.stats.total_nop_bytes += 1;
            }
        }

        bytes
    }

    /// Generate a sled that maximizes the contiguous patchable region.
    fn generate_max_patchable_sled(&mut self, size: usize) -> Vec<u8> {
        // For hot-patching, we want the largest possible NOP that can
        // be overwritten atomically. A 15-byte NOP is the maximum.
        let mut bytes = Vec::with_capacity(size);
        let mut remaining = size;

        while remaining >= 15 {
            if let Some(nop) = intel_nop_sequence(15) {
                bytes.extend_from_slice(&nop.bytes);
                remaining -= 15;
                self.stats.multi_byte_nops += 1;
                self.stats.total_nop_bytes += 15;
            }
        }
        if remaining > 0 {
            if let Some(nop) = intel_nop_sequence(remaining) {
                bytes.extend_from_slice(&nop.bytes);
                self.stats.multi_byte_nops += 1;
                self.stats.total_nop_bytes += remaining as u64;
            } else {
                bytes.extend(std::iter::repeat(0x90).take(remaining));
                self.stats.single_byte_nops += remaining as u64;
                self.stats.total_nop_bytes += remaining as u64;
            }
        }

        bytes
    }

    /// Generate alignment padding to align the current offset to the
    /// given boundary.
    ///
    /// Returns the NOP bytes needed for alignment. Does NOT advance
    /// `current_offset`; the caller must update it after emitting.
    pub fn align_to(&mut self, boundary: u64) -> Vec<u8> {
        let misalignment = self.current_offset % boundary;
        if misalignment == 0 {
            return vec![];
        }
        let pad_size = (boundary - misalignment) as usize;
        self.stats.alignment_bytes += pad_size as u64;
        self.generate_sled(pad_size)
    }

    /// Align to a 16-byte boundary (typical function entry alignment).
    pub fn align_to_16(&mut self) -> Vec<u8> {
        self.align_to(16)
    }

    /// Align to a 32-byte boundary.
    pub fn align_to_32(&mut self) -> Vec<u8> {
        self.align_to(32)
    }

    /// Align to a 64-byte boundary (cache-line alignment).
    pub fn align_to_64(&mut self) -> Vec<u8> {
        self.align_to(64)
    }

    /// Align to a boundary appropriate for the current microarchitecture.
    pub fn align_to_microarch(&mut self) -> Vec<u8> {
        let boundary = self.microarch.cache_line_size() as u64;
        self.align_to(boundary)
    }

    /// Reset the offset counter (e.g., at the start of a new section).
    pub fn reset_offset(&mut self) {
        self.current_offset = 0;
    }

    /// Advance the offset counter (after emitting non-NOP instructions).
    pub fn advance_offset(&mut self, bytes: u64) {
        self.current_offset += bytes;
    }
}

// ============================================================================
// Function Entry Alignment
// ============================================================================

/// Generate NOP padding to align a function entry to the specified boundary.
///
/// On modern x86 cores, aligning function entries to 16-byte boundaries
/// can improve fetch bandwidth by ensuring the first instruction of the
/// function starts on a cache-line-aligned boundary. For hot functions,
/// 32-byte or 64-byte alignment may further reduce front-end stalls.
pub fn generate_function_entry_alignment(
    current_offset: u64,
    boundary: u32,
    strategy: NopSledStrategy,
    microarch: NopMicroArch,
    is_64bit: bool,
) -> Vec<u8> {
    let mut sled = X86NopSled::new(is_64bit, strategy, microarch);
    sled.current_offset = current_offset;
    sled.align_to(boundary as u64)
}

/// Alignment target specification.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AlignmentTarget {
    /// Align to 16-byte boundary (default function entry).
    FunctionEntry16,
    /// Align to 32-byte boundary (hot function entry).
    FunctionEntry32,
    /// Align to 64-byte boundary (critical function entry).
    FunctionEntry64,
    /// Align to 16-byte boundary (loop header).
    LoopHeader16,
    /// Align to 32-byte boundary (hot loop header).
    LoopHeader32,
    /// Align to 64-byte boundary (critical loop header).
    LoopHeader64,
    /// Align to 16-byte boundary (branch target).
    BranchTarget16,
    /// Align to 32-byte boundary (indirect branch target).
    BranchTarget32,
    /// Align to 8-byte boundary (basic block start).
    BasicBlock8,
    /// No alignment.
    NoAlignment,
}

impl AlignmentTarget {
    /// Get the alignment boundary in bytes.
    pub fn boundary(&self) -> u64 {
        match self {
            AlignmentTarget::FunctionEntry16 => 16,
            AlignmentTarget::FunctionEntry32 => 32,
            AlignmentTarget::FunctionEntry64 => 64,
            AlignmentTarget::LoopHeader16 => 16,
            AlignmentTarget::LoopHeader32 => 32,
            AlignmentTarget::LoopHeader64 => 64,
            AlignmentTarget::BranchTarget16 => 16,
            AlignmentTarget::BranchTarget32 => 32,
            AlignmentTarget::BasicBlock8 => 8,
            AlignmentTarget::NoAlignment => 1,
        }
    }

    /// Maximum NOP bytes to use for alignment.
    /// If alignment would require more than this many NOP bytes,
    /// the alignment is skipped (cost exceeds benefit).
    pub fn max_nop_bytes(&self) -> usize {
        match self {
            AlignmentTarget::FunctionEntry16 => 15,
            AlignmentTarget::FunctionEntry32 => 31,
            AlignmentTarget::FunctionEntry64 => 48,
            AlignmentTarget::LoopHeader16 => 15,
            AlignmentTarget::LoopHeader32 => 24,
            AlignmentTarget::LoopHeader64 => 48,
            AlignmentTarget::BranchTarget16 => 15,
            AlignmentTarget::BranchTarget32 => 24,
            AlignmentTarget::BasicBlock8 => 7,
            AlignmentTarget::NoAlignment => 0,
        }
    }

    /// Whether this alignment should use long NOPs.
    pub fn use_long_nops(&self) -> bool {
        match self {
            AlignmentTarget::NoAlignment | AlignmentTarget::BasicBlock8 => false,
            _ => true,
        }
    }

    /// Recommended strategy for this alignment target.
    pub fn recommended_strategy(&self) -> NopSledStrategy {
        if self.use_long_nops() {
            NopSledStrategy::Optimal
        } else {
            NopSledStrategy::MinDecode
        }
    }
}

// ============================================================================
// Loop Header Alignment
// ============================================================================

/// Generate alignment padding for a loop header.
///
/// Loop header alignment is critical for performance on modern x86:
/// - Aligned loops reduce front-end stalls and improve μop cache
///   utilization.
/// - Intel's LSD (Loop Stream Detector) and AMD's Loop Buffer work
///   best when the loop fits within their capacity and is aligned.
/// - The loop alignment rules vary by microarchitecture.
pub fn generate_loop_header_alignment(
    current_offset: u64,
    microarch: NopMicroArch,
    is_64bit: bool,
) -> (Vec<u8>, AlignmentTarget) {
    let target = loop_alignment_target(microarch);
    let max_nops = target.max_nop_bytes();

    let misalignment = current_offset % target.boundary();
    if misalignment == 0 {
        return (vec![], target);
    }

    let pad_size = (target.boundary() - misalignment) as usize;
    if pad_size > max_nops {
        // Too much padding, skip alignment.
        return (vec![], AlignmentTarget::NoAlignment);
    }

    let strategy = target.recommended_strategy();
    let padding = generate_function_entry_alignment(
        current_offset,
        target.boundary() as u32,
        strategy,
        microarch,
        is_64bit,
    );

    (padding, target)
}

/// Determine the recommended loop alignment target for a given
/// microarchitecture.
pub fn loop_alignment_target(microarch: NopMicroArch) -> AlignmentTarget {
    match microarch {
        NopMicroArch::Bonnell | NopMicroArch::Saltwell => {
            // In-order Atom: 8-byte alignment recommended
            AlignmentTarget::BasicBlock8
        }
        NopMicroArch::Silvermont
        | NopMicroArch::Airmont
        | NopMicroArch::Goldmont
        | NopMicroArch::GoldmontPlus => AlignmentTarget::LoopHeader16,
        NopMicroArch::SandyBridge
        | NopMicroArch::IvyBridge
        | NopMicroArch::Haswell
        | NopMicroArch::Broadwell => {
            // 16-byte for small loops, 32 for hot loops
            AlignmentTarget::LoopHeader16
        }
        NopMicroArch::Skylake
        | NopMicroArch::KabyLake
        | NopMicroArch::CoffeeLake
        | NopMicroArch::CometLake
        | NopMicroArch::CascadeLake => {
            // Skylake has a microcode update that makes alignment less
            // critical, but 16-byte is still the safe default.
            AlignmentTarget::LoopHeader16
        }
        NopMicroArch::IceLake
        | NopMicroArch::TigerLake
        | NopMicroArch::RocketLake
        | NopMicroArch::AlderLakeP
        | NopMicroArch::RaptorLakeP
        | NopMicroArch::MeteorLakeP
        | NopMicroArch::ArrowLakeP
        | NopMicroArch::LunarLakeP
        | NopMicroArch::GraniteRapids => AlignmentTarget::LoopHeader32,
        NopMicroArch::Tremont
        | NopMicroArch::Gracemont
        | NopMicroArch::Crestmont
        | NopMicroArch::Skymont
        | NopMicroArch::Darkmont => AlignmentTarget::LoopHeader32,
        NopMicroArch::Zen1 | NopMicroArch::Zen2 => {
            // Zen 1/2: 32-byte alignment is important due to the
            // μop cache (OC) having 32-byte fetch windows.
            AlignmentTarget::LoopHeader32
        }
        NopMicroArch::Zen3 | NopMicroArch::Zen4 => {
            // Zen 3/4: 32-byte alignment for OP cache efficiency
            AlignmentTarget::LoopHeader32
        }
        NopMicroArch::Zen5 | NopMicroArch::Zen6 => {
            // Zen 5/6: 64-byte alignment for optimal fetch
            AlignmentTarget::LoopHeader64
        }
        _ => AlignmentTarget::LoopHeader16,
    }
}

/// Check whether loop alignment is beneficial for a loop of a given
/// size on the specified microarchitecture.
pub fn is_loop_alignment_beneficial(loop_byte_size: usize, microarch: NopMicroArch) -> bool {
    // Don't align loops that are too small (alignment cost > loop body).
    if loop_byte_size < 8 {
        return false;
    }

    // Don't align loops that won't fit in the LSD/loop buffer.
    match microarch {
        NopMicroArch::SandyBridge | NopMicroArch::IvyBridge => {
            // LSD capacity: 28 μops (≈ ~84 bytes)
            loop_byte_size <= 84
        }
        NopMicroArch::Haswell | NopMicroArch::Broadwell => {
            // LSD capacity: 28 μops (≈ ~60 bytes for AVX2-heavy loops)
            loop_byte_size <= 60
        }
        NopMicroArch::Skylake
        | NopMicroArch::KabyLake
        | NopMicroArch::CoffeeLake
        | NopMicroArch::CometLake
        | NopMicroArch::CascadeLake => {
            // LSD disabled by microcode on most SKL+ parts
            loop_byte_size <= 64
        }
        NopMicroArch::IceLake | NopMicroArch::TigerLake | NopMicroArch::RocketLake => {
            loop_byte_size <= 128
        }
        NopMicroArch::Zen1
        | NopMicroArch::Zen2
        | NopMicroArch::Zen3
        | NopMicroArch::Zen4
        | NopMicroArch::Zen5
        | NopMicroArch::Zen6 => {
            // AMD OP cache can hold ~4096 μops; alignment always helps
            // but only for frequently-executed loops.
            loop_byte_size <= 512
        }
        _ => loop_byte_size <= 128,
    }
}

// ============================================================================
// Branch Target Alignment
// ============================================================================

/// Generate alignment padding for a branch target.
///
/// Aligning branch targets can improve branch prediction accuracy by
/// reducing BTB aliasing. On Intel processors with a 2-level BTB,
/// aligning indirect branch targets to 32-byte boundaries can
/// significantly reduce mispredictions for polymorphic call sites.
pub fn generate_branch_target_alignment(
    current_offset: u64,
    _is_indirect: bool,
    microarch: NopMicroArch,
    is_64bit: bool,
) -> Vec<u8> {
    let boundary = match microarch {
        NopMicroArch::SandyBridge
        | NopMicroArch::IvyBridge
        | NopMicroArch::Haswell
        | NopMicroArch::Broadwell => 16u64,
        NopMicroArch::Skylake
        | NopMicroArch::KabyLake
        | NopMicroArch::CoffeeLake
        | NopMicroArch::CometLake
        | NopMicroArch::CascadeLake
        | NopMicroArch::IceLake
        | NopMicroArch::TigerLake
        | NopMicroArch::RocketLake => 16,
        NopMicroArch::AlderLakeP
        | NopMicroArch::RaptorLakeP
        | NopMicroArch::MeteorLakeP
        | NopMicroArch::ArrowLakeP
        | NopMicroArch::LunarLakeP
        | NopMicroArch::GraniteRapids => 32,
        NopMicroArch::Zen1
        | NopMicroArch::Zen2
        | NopMicroArch::Zen3
        | NopMicroArch::Zen4
        | NopMicroArch::Zen5
        | NopMicroArch::Zen6 => 32,
        _ => 16,
    };

    let misalignment = current_offset % boundary;
    if misalignment == 0 {
        return vec![];
    }

    let pad_size = (boundary - misalignment) as usize;
    // Cap NOP padding at 15 bytes for branch targets.
    if pad_size > 15 {
        return vec![];
    }

    let mut sled = X86NopSled::new(is_64bit, NopSledStrategy::Optimal, microarch);
    sled.current_offset = current_offset;
    sled.align_to(boundary)
}

// ============================================================================
// Hot-patching NOP Sleds
// ============================================================================

/// Generate a hot-patching NOP sled for the function entry.
///
/// The size parameter determines how many bytes of patchable NOP space
/// are available. Common sizes:
/// - 2 bytes: Windows x64 hot-patch (MOV EDI,EDI = 0x89 0xFF)
/// - 5 bytes: Linux ftrace/kpatch/livepatch (CALL/JMP rel32)
/// - 11 bytes: Full prologue replacement
/// - 16 bytes: Cache-line-aligned hot-patch entry
pub fn generate_hotpatch_sled(
    size: usize,
    style: HotPatchStyle,
    strategy: NopSledStrategy,
    is_64bit: bool,
) -> Vec<u8> {
    match style {
        HotPatchStyle::None => vec![],
        HotPatchStyle::Win64 => generate_win64_hotpatch_sled(size, strategy, is_64bit),
        HotPatchStyle::LinuxFtrace => generate_ftrace_sled(size, strategy, is_64bit),
        HotPatchStyle::LinuxLivepatch => generate_livepatch_sled(size, strategy, is_64bit),
        HotPatchStyle::Generic => {
            let mut sled = X86NopSled::new(is_64bit, strategy, NopMicroArch::Generic);
            sled.generate_sled(size)
        }
        HotPatchStyle::JitCompiler => generate_jit_sled(size, strategy, is_64bit),
    }
}

/// Hot-patching style.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HotPatchStyle {
    /// No hot-patching NOP sled.
    None,
    /// Windows x64 hot-patching: at least 2 bytes before the function
    /// entry, using MOV EDI,EDI convention.
    Win64,
    /// Linux ftrace: 5-byte NOP (0F 1F 44 00 00) at function entry.
    LinuxFtrace,
    /// Linux livepatch: 5-byte NOP at function entry.
    LinuxLivepatch,
    /// Generic hot-patching: NOP sled only, no platform convention.
    Generic,
    /// JIT compiler hot-patching: larger NOP sled for patchable stubs.
    JitCompiler,
}

/// Generate a Windows x64 hot-patching sled.
fn generate_win64_hotpatch_sled(size: usize, strategy: NopSledStrategy, is_64bit: bool) -> Vec<u8> {
    let mut bytes = Vec::with_capacity(size);
    let mut remaining = size;

    if remaining >= 2 {
        // MOV EDI, EDI = 0x89 0xFF (Win64 hot-patch convention)
        bytes.push(0x89);
        bytes.push(0xFF);
        remaining -= 2;
    }

    if remaining > 0 {
        let mut sled = X86NopSled::new(is_64bit, strategy, NopMicroArch::Generic);
        bytes.extend(sled.generate_sled(remaining));
    }

    bytes
}

/// Generate a Linux ftrace-compatible NOP sled.
fn generate_ftrace_sled(size: usize, strategy: NopSledStrategy, is_64bit: bool) -> Vec<u8> {
    let mut bytes = Vec::with_capacity(size);
    let mut remaining = size;

    // ftrace needs at least 5 bytes of NOP.
    if remaining >= 5 {
        // Standard 5-byte NOP for ftrace
        bytes.extend_from_slice(&[0x0F, 0x1F, 0x44, 0x00, 0x00]);
        remaining -= 5;
    }

    if remaining > 0 {
        let mut sled = X86NopSled::new(is_64bit, strategy, NopMicroArch::Generic);
        bytes.extend(sled.generate_sled(remaining));
    }

    bytes
}

/// Generate a Linux livepatch-compatible NOP sled.
fn generate_livepatch_sled(size: usize, strategy: NopSledStrategy, is_64bit: bool) -> Vec<u8> {
    // Livepatch uses the same 5-byte NOP as ftrace.
    generate_ftrace_sled(size, strategy, is_64bit)
}

/// Generate a JIT-compiler-friendly NOP sled with large patchable
/// regions.
fn generate_jit_sled(size: usize, strategy: NopSledStrategy, is_64bit: bool) -> Vec<u8> {
    let mut sled = X86NopSled::new(
        is_64bit,
        NopSledStrategy::MaxPatchable,
        NopMicroArch::Generic,
    );
    sled.generate_sled(size)
}

// ============================================================================
// NOP Selection: Code Size vs Decode Bandwidth Tradeoffs
// ============================================================================

/// Select the optimal NOP sequence length given the padding size and
/// microarchitectural constraints.
///
/// Returns the recommended NOP length (1–15) for the remaining padding.
/// The decision balances:
/// - **Decode bandwidth**: Short NOPs decode faster but consume more
///   decoder slots.
/// - **μop cache occupancy**: Long NOPs take fewer μop cache entries.
/// - **Code size**: Single-byte NOPs are wasteful for large gaps.
pub fn select_optimal_nop_length(
    remaining_padding: usize,
    microarch: NopMicroArch,
    is_loop: bool,
) -> usize {
    if remaining_padding == 0 {
        return 0;
    }

    // Clamp to max instruction length.
    let remaining = remaining_padding.min(15);

    if remaining <= 2 {
        return remaining;
    }

    match microarch {
        NopMicroArch::Bonnell | NopMicroArch::Saltwell => {
            // In-order Atom: prefer short NOPs to avoid stalling the
            // dual-decode pipeline.
            if remaining >= 4 {
                4
            } else {
                remaining
            }
        }
        NopMicroArch::Silvermont | NopMicroArch::Airmont => {
            if remaining >= 4 {
                4
            } else {
                remaining
            }
        }
        NopMicroArch::Goldmont | NopMicroArch::GoldmontPlus => {
            if remaining >= 5 {
                5
            } else {
                remaining
            }
        }
        NopMicroArch::SandyBridge | NopMicroArch::IvyBridge => {
            // 4-wide decoder; prefer NOPs that don't hog decode slots.
            if is_loop {
                // For loops, use the largest NOP to fit within the LSD.
                remaining
            } else if remaining >= 4 {
                4
            } else {
                remaining
            }
        }
        NopMicroArch::Haswell | NopMicroArch::Broadwell => {
            if remaining >= 5 {
                5
            } else {
                remaining
            }
        }
        NopMicroArch::Skylake
        | NopMicroArch::KabyLake
        | NopMicroArch::CoffeeLake
        | NopMicroArch::CometLake
        | NopMicroArch::CascadeLake => {
            // 5-wide (4+1) decoder; prefers larger NOPs to reduce
            // μop cache pressure.
            remaining
        }
        NopMicroArch::IceLake | NopMicroArch::TigerLake | NopMicroArch::RocketLake => remaining,
        _ => remaining,
    }
}

/// Compute the decode cost of a NOP sled given the sequence of NOP
/// lengths used.
pub fn nop_sled_decode_cost(nop_lengths: &[usize], decode_width: u8) -> u64 {
    if nop_lengths.is_empty() {
        return 0;
    }

    let mut cycles = 0u64;
    let mut instrs_in_cycle = 0u8;

    for &len in nop_lengths {
        let complexity = if len <= 2 { 1 } else { 1 };
        if instrs_in_cycle + complexity > decode_width {
            cycles += 1;
            instrs_in_cycle = complexity;
        } else {
            instrs_in_cycle += complexity;
        }
    }

    if instrs_in_cycle > 0 {
        cycles += 1;
    }

    cycles
}

/// Compute the μop count of a NOP sequence.
///
/// On modern Intel/AMD cores, NOPs are eliminated at the rename stage
/// (they consume zero execution resources). However, they still occupy
/// μop cache entries and decoder slots.
pub fn nop_uop_count(nop_len: usize, microarch: NopMicroArch) -> u8 {
    match microarch {
        NopMicroArch::SandyBridge
        | NopMicroArch::IvyBridge
        | NopMicroArch::Haswell
        | NopMicroArch::Broadwell
        | NopMicroArch::Skylake
        | NopMicroArch::KabyLake
        | NopMicroArch::CoffeeLake
        | NopMicroArch::CometLake
        | NopMicroArch::CascadeLake
        | NopMicroArch::IceLake
        | NopMicroArch::TigerLake
        | NopMicroArch::RocketLake
        | NopMicroArch::AlderLakeP
        | NopMicroArch::RaptorLakeP
        | NopMicroArch::MeteorLakeP
        | NopMicroArch::ArrowLakeP
        | NopMicroArch::LunarLakeP
        | NopMicroArch::GraniteRapids => {
            // Intel: NOP is eliminated (0 μops executed), but
            // "occupies" 1 μop cache slot.
            1
        }
        NopMicroArch::Zen1
        | NopMicroArch::Zen2
        | NopMicroArch::Zen3
        | NopMicroArch::Zen4
        | NopMicroArch::Zen5
        | NopMicroArch::Zen6 => {
            // AMD: NOP is eliminated, 1 macro-op.
            1
        }
        NopMicroArch::Bonnell
        | NopMicroArch::Saltwell
        | NopMicroArch::Silvermont
        | NopMicroArch::Airmont
        | NopMicroArch::Goldmont
        | NopMicroArch::GoldmontPlus
        | NopMicroArch::Tremont
        | NopMicroArch::Gracemont
        | NopMicroArch::Crestmont
        | NopMicroArch::Skymont
        | NopMicroArch::Darkmont => {
            // Atom/E-core: NOP is a real μop but very cheap.
            1
        }
        _ => 1,
    }
}

// ============================================================================
// Intel vs AMD NOP Recommendations
// ============================================================================

/// Intel's recommended NOP sequence for alignment padding, straight
/// from Chapter 3 and Appendix B of the Optimization Reference Manual.
pub fn intel_alignment_nops(pad_size: usize) -> Vec<u8> {
    match pad_size {
        0 => vec![],
        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,
        ],
        _ => {
            // Decompose into multiple NOPs.
            let mut result = Vec::with_capacity(pad_size);
            let mut remaining = pad_size;
            while remaining >= 15 {
                result.extend_from_slice(&intel_alignment_nops(15));
                remaining -= 15;
            }
            if remaining > 0 {
                result.extend_from_slice(&intel_alignment_nops(remaining));
            }
            result
        }
    }
}

/// AMD's recommended NOP sequence for alignment padding, from the
/// AMD Software Optimization Guide.
pub fn amd_alignment_nops(pad_size: usize) -> Vec<u8> {
    match pad_size {
        0 => vec![],
        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, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00],
        11 => vec![
            0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
        ],
        12 => vec![
            0x66, 0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
        ],
        13 => vec![
            0x66, 0x66, 0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
        ],
        14 => vec![
            0x66, 0x66, 0x66, 0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00,
        ],
        15 => vec![
            0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x2E, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00,
            0x00,
        ],
        _ => {
            let mut result = Vec::with_capacity(pad_size);
            let mut remaining = pad_size;
            while remaining >= 15 {
                result.extend_from_slice(&amd_alignment_nops(15));
                remaining -= 15;
            }
            if remaining > 0 {
                result.extend_from_slice(&amd_alignment_nops(remaining));
            }
            result
        }
    }
}

// ============================================================================
// NOP Sled Validation
// ============================================================================

/// Validate that a NOP sled is safe: all bytes in the sled must be
/// valid NOP instructions that do not modify architectural state.
pub fn validate_nop_sled(sled: &[u8]) -> Result<(), String> {
    if sled.is_empty() {
        return Ok(());
    }

    let mut i = 0;
    while i < sled.len() {
        let remaining = sled.len() - i;
        let (valid, consumed) = is_valid_nop(&sled[i..]);

        if !valid {
            return Err(format!(
                "Invalid NOP sequence at byte offset {}: byte 0x{:02X} is not a valid NOP",
                i, sled[i]
            ));
        }

        if consumed == 0 || consumed > remaining {
            return Err(format!(
                "NOP decoder error at offset {}: consumed={}, remaining={}",
                i, consumed, remaining
            ));
        }

        i += consumed;
    }

    Ok(())
}

/// Check whether the bytes at `data[0..]` form a valid NOP instruction.
/// Returns `(valid, bytes_consumed)`.
fn is_valid_nop(data: &[u8]) -> (bool, usize) {
    if data.is_empty() {
        return (false, 0);
    }

    // Single-byte NOP: 0x90
    if data[0] == 0x90 {
        return (true, 1);
    }

    // 0x66 prefix + ... leading to a NOP
    let mut pos = 0;
    let mut has_66 = false;
    let mut has_segment = false;

    // Consume prefixes.
    while pos < data.len() {
        match data[pos] {
            0x66 => {
                has_66 = true;
                pos += 1;
            }
            0x2E | 0x3E | 0x26 | 0x64 | 0x65 | 0x67 => {
                has_segment = true;
                pos += 1;
            }
            0xF0 | 0xF2 | 0xF3 => {
                // LOCK/REPNE/REP — not recommended for NOPs but
                // technically valid before 0F 1F.
                pos += 1;
            }
            _ => break,
        }
    }

    if pos >= data.len() {
        return (false, pos);
    }

    // Check for 0F 1F (multi-byte NOP).
    if pos + 1 < data.len() && data[pos] == 0x0F && data[pos + 1] == 0x1F {
        pos += 2;

        if pos >= data.len() {
            return (false, pos);
        }

        // Parse ModR/M byte.
        let modrm = data[pos];
        pos += 1;
        let mod_bits = (modrm >> 6) & 0x03;
        let rm = modrm & 0x07;

        // Check for SIB byte.
        if rm == 0x04 && mod_bits != 0x03 {
            if pos >= data.len() {
                return (false, pos);
            }
            let sib = data[pos];
            pos += 1;
            let base = sib & 0x07;

            // If base == 0x05 and mod == 0x00, there's a disp32.
            if base == 0x05 && mod_bits == 0x00 {
                if pos + 4 > data.len() {
                    return (false, pos);
                }
                pos += 4;
            }
        }

        // Check for displacement.
        match mod_bits {
            0x01 => {
                // disp8
                if pos >= data.len() {
                    return (false, pos);
                }
                pos += 1;
            }
            0x02 => {
                // disp32
                if pos + 4 > data.len() {
                    return (false, pos);
                }
                pos += 4;
            }
            _ => {}
        }

        return (true, pos);
    }

    // Not a recognized NOP.
    (false, pos.max(1))
}

/// Check if a byte is a valid NOP prefix.
pub fn is_nop_prefix(byte: u8) -> bool {
    matches!(
        byte,
        0x66 | // operand-size override
        0x67 | // address-size override
        0x2E | // CS segment override
        0x3E | // DS segment override
        0x26 | // ES segment override
        0x64 | // FS segment override
        0x65 | // GS segment override
        0xF0 | // LOCK (discouraged)
        0xF2 | // REPNE
        0xF3 // REP
    )
}

// ============================================================================
// NOP Sled Optimization
// ============================================================================

/// Optimize a NOP sled for the given microarchitecture.
///
/// Pass 1: Replace consecutive single-byte NOPs with multi-byte NOPs
/// for better decode bandwidth.
/// Pass 2: Break long NOPs into shorter ones if they exceed the
/// preferred NOP length for the microarchitecture.
pub fn optimize_nop_sled(sled: &[u8], microarch: NopMicroArch) -> Vec<u8> {
    if sled.len() <= 3 {
        return sled.to_vec();
    }

    let preferred_len = select_optimal_nop_length(sled.len(), microarch, false);

    if preferred_len == 0 || preferred_len >= sled.len() {
        return sled.to_vec();
    }

    // Rebuild sled using the preferred NOP length.
    let mut result = Vec::with_capacity(sled.len());
    let mut remaining = sled.len();

    while remaining >= preferred_len {
        let nop = intel_alignment_nops(preferred_len);
        result.extend_from_slice(&nop);
        remaining -= preferred_len;
    }

    if remaining > 0 {
        let nop = intel_alignment_nops(remaining);
        result.extend_from_slice(&nop);
    }

    result
}

/// Minimize the number of NOP instructions in a sled.
///
/// This function reconstructs the sled using the largest possible NOPs
/// to minimize the total number of instructions the decoder must
/// process.
pub fn minimize_nop_count(sled: &[u8]) -> Vec<u8> {
    if sled.len() <= 15 {
        return intel_alignment_nops(sled.len());
    }

    let mut result = Vec::with_capacity(sled.len());
    let mut remaining = sled.len();

    while remaining >= 15 {
        result.extend_from_slice(&intel_alignment_nops(15));
        remaining -= 15;
    }
    if remaining > 0 {
        result.extend_from_slice(&intel_alignment_nops(remaining));
    }

    result
}

// ============================================================================
// Utility: NOP sled display / debugging
// ============================================================================

impl fmt::Display for NopSequence {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "NOP({}B) [", self.len)?;
        for (i, b) in self.bytes.iter().enumerate() {
            if i > 0 {
                write!(f, " ")?;
            }
            write!(f, "{:02X}", b)?;
        }
        write!(f, "] variant={:?} dc={}", self.variant, self.decode_cost)
    }
}

impl X86NopSled {
    /// Dump a summary of the statistics.
    pub fn stats_summary(&self) -> String {
        format!(
            "X86NopSled Stats:\n\
             - Total NOP bytes: {}\n\
             - Single-byte NOPs: {}\n\
             - Multi-byte NOPs: {}\n\
             - Alignment bytes: {}\n\
             - Function alignments: {}\n\
             - Loop alignments: {}\n\
             - Branch alignments: {}\n\
             - Current offset: 0x{:X}\n\
             - Strategy: {:?}\n\
             - Microarch: {:?}",
            self.stats.total_nop_bytes,
            self.stats.single_byte_nops,
            self.stats.multi_byte_nops,
            self.stats.alignment_bytes,
            self.stats.function_alignments,
            self.stats.loop_alignments,
            self.stats.branch_alignments,
            self.current_offset,
            self.strategy,
            self.microarch,
        )
    }

    /// Dump a sled as a human-readable disassembly of NOP instructions.
    pub fn disassemble_sled(sled: &[u8]) -> String {
        let mut result = String::new();
        let mut offset = 0usize;

        while offset < sled.len() {
            let remaining = sled.len() - offset;
            let (valid, consumed) = is_valid_nop(&sled[offset..]);
            if valid {
                result.push_str(&format!(
                    "  {:04X}: NOP ({})\n",
                    offset,
                    hex_str(&sled[offset..offset + consumed])
                ));
                offset += consumed;
            } else {
                result.push_str(&format!("  {:04X}: ??? {:02X}\n", offset, sled[offset]));
                offset += 1;
            }
        }

        result
    }
}

/// Format a byte slice as a hex string.
fn hex_str(bytes: &[u8]) -> String {
    bytes
        .iter()
        .map(|b| format!("{:02X}", b))
        .collect::<Vec<_>>()
        .join(" ")
}

// ============================================================================
// Constant NOP Sequences for Common Alignment Sizes
// ============================================================================

/// Pre-computed NOP sequences for common alignment sizes.
/// These are static, compile-time-constant slices for use in code
/// generation where deterministic output is preferred.
pub mod constant_nops {
    /// 1-byte NOP: 0x90
    pub const NOP1: [u8; 1] = [0x90];
    /// 2-byte NOP: 66 90
    pub const NOP2: [u8; 2] = [0x66, 0x90];
    /// 3-byte NOP: 0F 1F 00
    pub const NOP3: [u8; 3] = [0x0F, 0x1F, 0x00];
    /// 4-byte NOP: 0F 1F 40 00
    pub const NOP4: [u8; 4] = [0x0F, 0x1F, 0x40, 0x00];
    /// 5-byte NOP: 0F 1F 44 00 00
    pub const NOP5: [u8; 5] = [0x0F, 0x1F, 0x44, 0x00, 0x00];
    /// 6-byte NOP: 66 0F 1F 44 00 00
    pub const NOP6: [u8; 6] = [0x66, 0x0F, 0x1F, 0x44, 0x00, 0x00];
    /// 7-byte NOP: 0F 1F 80 00 00 00 00
    pub const NOP7: [u8; 7] = [0x0F, 0x1F, 0x80, 0x00, 0x00, 0x00, 0x00];
    /// 8-byte NOP: 0F 1F 84 00 00 00 00 00
    pub const NOP8: [u8; 8] = [0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00];
    /// 9-byte NOP: 66 0F 1F 84 00 00 00 00 00
    pub const NOP9: [u8; 9] = [0x66, 0x0F, 0x1F, 0x84, 0x00, 0x00, 0x00, 0x00, 0x00];
}

// ============================================================================
// Factory Functions for Testing
// ============================================================================

/// Create an X86NopSled for testing with the optimal strategy.
pub fn make_test_nop_sled() -> X86NopSled {
    X86NopSled::default_for(true)
}

/// Create an X86NopSled for testing with Intel's recommended strategy.
pub fn make_intel_nop_sled() -> X86NopSled {
    X86NopSled::new(true, NopSledStrategy::Intel, NopMicroArch::Generic)
}

/// Create an X86NopSled for testing with AMD's recommended strategy.
pub fn make_amd_nop_sled() -> X86NopSled {
    X86NopSled::new(true, NopSledStrategy::Amd, NopMicroArch::Generic)
}

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

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

    #[test]
    fn test_nop_sled_single_byte() {
        let mut sled = make_test_nop_sled();
        sled.strategy = NopSledStrategy::SingleByte;
        let bytes = sled.generate_sled(10);
        assert_eq!(bytes.len(), 10);
        assert!(bytes.iter().all(|&b| b == 0x90));
    }

    #[test]
    fn test_nop_sled_optimal() {
        let mut sled = make_test_nop_sled();
        for size in [0, 1, 5, 9, 15, 16, 32, 64, 128] {
            let bytes = sled.generate_sled(size);
            assert_eq!(bytes.len(), size, "Size mismatch for {} bytes", size);
        }
    }

    #[test]
    fn test_intel_nop_sequences_all_sizes() {
        for len in 1..=15 {
            let seq = intel_nop_sequence(len);
            assert!(seq.is_some(), "Missing Intel NOP for {} bytes", len);
            let seq = seq.unwrap();
            assert_eq!(seq.bytes.len(), len);
        }
    }

    #[test]
    fn test_amd_nop_sequences_all_sizes() {
        for len in 1..=15 {
            let seq = amd_nop_sequence(len);
            assert!(seq.is_some(), "Missing AMD NOP for {} bytes", len);
            let seq = seq.unwrap();
            assert_eq!(seq.bytes.len(), len);
        }
    }

    #[test]
    fn test_optimal_nop_sequence() {
        for len in 1..=15 {
            let seq = optimal_nop_sequence(len);
            assert!(seq.is_some(), "Missing optimal NOP for {} bytes", len);
        }
    }

    #[test]
    fn test_intel_alignment_nops() {
        for size in 0..32 {
            let nops = intel_alignment_nops(size);
            assert_eq!(nops.len(), size);
        }
    }

    #[test]
    fn test_amd_alignment_nops() {
        for size in 0..32 {
            let nops = amd_alignment_nops(size);
            assert_eq!(nops.len(), size);
        }
    }

    #[test]
    fn test_validate_nop_sled() {
        // Valid single-byte NOP
        assert!(validate_nop_sled(&[0x90]).is_ok());
        // Valid multi-byte NOP
        let nop5 = intel_alignment_nops(5);
        assert!(validate_nop_sled(&nop5).is_ok());
        // Empty sled
        assert!(validate_nop_sled(&[]).is_ok());
        // Invalid byte
        assert!(validate_nop_sled(&[0xCC]).is_err()); // INT3 is not NOP
                                                      // Large valid sled
        let large = intel_alignment_nops(64);
        assert!(validate_nop_sled(&large).is_ok());
    }

    #[test]
    fn test_validate_nop_sled_sizes() {
        for size in 1..64 {
            let sled = intel_alignment_nops(size);
            assert_eq!(sled.len(), size);
            let result = validate_nop_sled(&sled);
            assert!(
                result.is_ok(),
                "Validation failed for {} bytes: {:?}",
                size,
                result
            );
        }
    }

    #[test]
    fn test_is_nop_prefix() {
        assert!(is_nop_prefix(0x66));
        assert!(is_nop_prefix(0x67));
        assert!(is_nop_prefix(0x2E));
        assert!(is_nop_prefix(0x3E));
        assert!(is_nop_prefix(0x26));
        assert!(is_nop_prefix(0x64));
        assert!(is_nop_prefix(0x65));
        assert!(is_nop_prefix(0xF0));
        assert!(is_nop_prefix(0xF2));
        assert!(is_nop_prefix(0xF3));
        assert!(!is_nop_prefix(0x90));
        assert!(!is_nop_prefix(0x00));
    }

    #[test]
    fn test_alignment_to_16() {
        let mut sled = make_test_nop_sled();
        sled.current_offset = 3;
        let pad = sled.align_to_16();
        assert_eq!(pad.len(), 13); // 16 - 3 = 13
        assert_eq!(sled.current_offset, 16);
    }

    #[test]
    fn test_alignment_to_64() {
        let mut sled = make_test_nop_sled();
        sled.current_offset = 60;
        let pad = sled.align_to_64();
        assert_eq!(pad.len(), 4); // 64 - 60 = 4
    }

    #[test]
    fn test_no_alignment_needed() {
        let mut sled = make_test_nop_sled();
        sled.current_offset = 16;
        let pad = sled.align_to_16();
        assert!(pad.is_empty());
    }

    #[test]
    fn test_win64_hotpatch_sled() {
        let sled = generate_hotpatch_sled(7, HotPatchStyle::Win64, NopSledStrategy::Optimal, true);
        assert_eq!(sled.len(), 7);
        assert_eq!(sled[0], 0x89); // MOV
        assert_eq!(sled[1], 0xFF); // EDI, EDI
    }

    #[test]
    fn test_ftrace_sled() {
        let sled = generate_hotpatch_sled(
            5,
            HotPatchStyle::LinuxFtrace,
            NopSledStrategy::Optimal,
            true,
        );
        assert_eq!(sled.len(), 5);
        assert_eq!(&sled[0..5], &[0x0F, 0x1F, 0x44, 0x00, 0x00]);
    }

    #[test]
    fn test_livepatch_sled() {
        let sled = generate_hotpatch_sled(
            5,
            HotPatchStyle::LinuxLivepatch,
            NopSledStrategy::Optimal,
            true,
        );
        assert_eq!(sled.len(), 5);
    }

    #[test]
    fn test_jit_sled() {
        let sled = generate_hotpatch_sled(
            16,
            HotPatchStyle::JitCompiler,
            NopSledStrategy::Optimal,
            true,
        );
        assert_eq!(sled.len(), 16);
    }

    #[test]
    fn test_loop_alignment_target() {
        let target = loop_alignment_target(NopMicroArch::Skylake);
        assert_eq!(target.boundary(), 16);
        let target_zen4 = loop_alignment_target(NopMicroArch::Zen4);
        assert_eq!(target_zen4.boundary(), 32);
    }

    #[test]
    fn test_is_loop_alignment_beneficial() {
        // Small loop: not beneficial
        assert!(!is_loop_alignment_beneficial(4, NopMicroArch::Skylake));
        // Medium loop: beneficial
        assert!(is_loop_alignment_beneficial(32, NopMicroArch::Skylake));
        // Very large loop on Zen: beneficial up to 512
        assert!(is_loop_alignment_beneficial(256, NopMicroArch::Zen4));
        assert!(!is_loop_alignment_beneficial(1024, NopMicroArch::Zen4));
    }

    #[test]
    fn test_nop_sled_decode_cost() {
        let cost = nop_sled_decode_cost(&[1, 1, 1, 1], 4);
        assert_eq!(cost, 1); // 4 single-byte NOPs fit in 1 cycle

        let cost2 = nop_sled_decode_cost(&[1, 1, 1, 1, 1], 4);
        assert!(cost2 >= 2); // 5 NOPs take at least 2 cycles
    }

    #[test]
    fn test_select_optimal_nop_length() {
        // 3 bytes remaining, Skylake: should return 3
        assert_eq!(
            select_optimal_nop_length(3, NopMicroArch::Skylake, false),
            3
        );
        // 8 bytes remaining, Skylake: should return 8
        assert_eq!(
            select_optimal_nop_length(8, NopMicroArch::Skylake, false),
            8
        );
        // 1 byte: return 1
        assert_eq!(
            select_optimal_nop_length(1, NopMicroArch::Skylake, false),
            1
        );
    }

    #[test]
    fn test_nop_variant_official() {
        assert!(NopVariant::XchgEaxEax.is_official_intel());
        assert!(NopVariant::LongNop0F1F.is_official_intel());
        assert!(!NopVariant::MultiPrefixNop.is_official_intel());
    }

    #[test]
    fn test_nop_variant_amd() {
        assert!(NopVariant::SegmentNop.is_amd_recommended());
        assert!(!NopVariant::MultiPrefixNop.is_amd_recommended());
    }

    #[test]
    fn test_optimize_nop_sled() {
        let original = vec![0x90; 16]; // 16 single-byte NOPs
        let optimized = optimize_nop_sled(&original, NopMicroArch::Skylake);
        assert_eq!(optimized.len(), 16);
        // Should contain at least one multi-byte NOP
        assert!(optimized.contains(&0x0F));
    }

    #[test]
    fn test_minimize_nop_count() {
        let original = vec![0x90; 30];
        let minimized = minimize_nop_count(&original);
        assert_eq!(minimized.len(), 30);
        // Two 15-byte NOPs = 2 instructions vs 30 single-byte NOPs
    }

    #[test]
    fn test_disassemble_sled() {
        let sled = intel_alignment_nops(5);
        let disasm = X86NopSled::disassemble_sled(&sled);
        assert!(disasm.contains("NOP"));
        assert!(disasm.contains("0000"));
    }

    #[test]
    fn test_stats_summary() {
        let mut sled = make_test_nop_sled();
        sled.generate_sled(16);
        let summary = sled.stats_summary();
        assert!(summary.contains("Total NOP bytes: 16"));
        assert!(summary.contains("Strategy: Optimal"));
    }

    #[test]
    fn test_microarch_decode_width() {
        assert_eq!(NopMicroArch::Skylake.decode_width(), 5);
        assert_eq!(NopMicroArch::Zen4.decode_width(), 4);
        assert_eq!(NopMicroArch::AlderLakeP.decode_width(), 6);
        assert_eq!(NopMicroArch::Goldmont.decode_width(), 3);
        assert_eq!(NopMicroArch::Bonnell.decode_width(), 2);
    }

    #[test]
    fn test_microarch_cache_line() {
        assert_eq!(NopMicroArch::Skylake.cache_line_size(), 64);
        assert_eq!(NopMicroArch::Zen4.cache_line_size(), 64);
    }

    #[test]
    fn test_nop_display() {
        let seq = intel_nop_sequence(5).unwrap();
        let display = format!("{}", seq);
        assert!(display.contains("NOP(5B)"));
        assert!(display.contains("0F 1F 44 00 00"));
    }

    #[test]
    fn test_constant_nops() {
        assert_eq!(constant_nops::NOP1.len(), 1);
        assert_eq!(constant_nops::NOP1[0], 0x90);
        assert_eq!(constant_nops::NOP5.len(), 5);
        assert_eq!(&constant_nops::NOP5[..], &[0x0F, 0x1F, 0x44, 0x00, 0x00]);
    }

    #[test]
    fn test_function_entry_alignment_64() {
        let padding = generate_function_entry_alignment(
            50,
            64,
            NopSledStrategy::Optimal,
            NopMicroArch::Generic,
            true,
        );
        assert_eq!(padding.len(), 14); // 64 - 50
    }

    #[test]
    fn test_loop_header_alignment_generation() {
        let (padding, target) = generate_loop_header_alignment(10, NopMicroArch::Zen4, true);
        assert_eq!(target.boundary(), 32);
        // 32 - 10 = 22, but max_nop_bytes for LoopHeader32 is 24
        // So we should get padding.
        assert!(!padding.is_empty());
    }

    #[test]
    fn test_branch_target_alignment() {
        let padding = generate_branch_target_alignment(7, false, NopMicroArch::Skylake, true);
        assert_eq!(padding.len(), 9); // 16 - 7
    }

    #[test]
    fn test_compat_nop_sequence() {
        // Compat should handle 1-9 bytes directly.
        for len in 1..=9 {
            let seq = compat_nop_sequence(len);
            assert!(seq.is_some());
        }
        // >9 bytes should return None (caller must decompose).
        assert!(compat_nop_sequence(10).is_none());
    }

    #[test]
    fn test_nop_uop_count() {
        // All modern cores: NOP = 1 μop slot, 0 executed
        assert_eq!(nop_uop_count(5, NopMicroArch::Skylake), 1);
        assert_eq!(nop_uop_count(5, NopMicroArch::Zen4), 1);
    }

    #[test]
    fn test_alignment_target_max_nops() {
        assert_eq!(AlignmentTarget::FunctionEntry16.max_nop_bytes(), 15);
        assert_eq!(AlignmentTarget::LoopHeader32.max_nop_bytes(), 24);
        assert_eq!(AlignmentTarget::NoAlignment.max_nop_bytes(), 0);
    }

    #[test]
    fn test_is_valid_nop_edge_cases() {
        // Prefix-only bytes (incomplete)
        let (valid, _) = is_valid_nop(&[0x66]);
        assert!(!valid);
        // 0x0F only (incomplete)
        let (valid, _) = is_valid_nop(&[0x0F]);
        assert!(!valid);
        // 0x0F 0x1F without ModR/M (incomplete)
        let (valid, _) = is_valid_nop(&[0x0F, 0x1F]);
        assert!(!valid);
    }

    #[test]
    fn test_advance_offset() {
        let mut sled = make_test_nop_sled();
        sled.advance_offset(42);
        assert_eq!(sled.current_offset, 42);
    }

    #[test]
    fn test_reset_offset() {
        let mut sled = make_test_nop_sled();
        sled.advance_offset(100);
        sled.reset_offset();
        assert_eq!(sled.current_offset, 0);
    }

    #[test]
    fn test_hotpatch_style_enum() {
        // Verify all variants exist and are distinct.
        let styles = [
            HotPatchStyle::None,
            HotPatchStyle::Win64,
            HotPatchStyle::LinuxFtrace,
            HotPatchStyle::LinuxLivepatch,
            HotPatchStyle::Generic,
            HotPatchStyle::JitCompiler,
        ];
        for (i, a) in styles.iter().enumerate() {
            for (j, b) in styles.iter().enumerate() {
                if i == j {
                    assert_eq!(a, b);
                } else {
                    assert_ne!(a, b);
                }
            }
        }
    }

    #[test]
    fn test_nop_sled_strategy_enum() {
        let strategies = [
            NopSledStrategy::SingleByte,
            NopSledStrategy::Optimal,
            NopSledStrategy::Intel,
            NopSledStrategy::Amd,
            NopSledStrategy::MinSize,
            NopSledStrategy::MinDecode,
            NopSledStrategy::Compat,
            NopSledStrategy::MaxPatchable,
        ];
        for (i, a) in strategies.iter().enumerate() {
            for (j, b) in strategies.iter().enumerate() {
                if i == j {
                    assert_eq!(a, b);
                } else {
                    assert_ne!(a, b);
                }
            }
        }
    }

    #[test]
    fn test_microarch_prefers_long_nops() {
        // All modern OoO cores prefer long NOPs.
        assert!(NopMicroArch::Skylake.prefers_long_nops());
        assert!(NopMicroArch::Zen4.prefers_long_nops());
        assert!(NopMicroArch::AlderLakeP.prefers_long_nops());
        // In-order Atom does not.
        assert!(!NopMicroArch::Bonnell.prefers_long_nops());
    }

    #[test]
    fn test_loop_alignment_target_all_microarchs() {
        // Every defined microarch should return a valid alignment target.
        let microarchs = [
            NopMicroArch::Bonnell,
            NopMicroArch::Silvermont,
            NopMicroArch::Goldmont,
            NopMicroArch::Tremont,
            NopMicroArch::Skylake,
            NopMicroArch::IceLake,
            NopMicroArch::Zen3,
            NopMicroArch::Zen5,
        ];
        for ma in &microarchs {
            let target = loop_alignment_target(*ma);
            assert!(target.boundary() >= 8);
        }
    }

    #[test]
    fn test_hotpatch_sled_all_styles() {
        for style in &[
            HotPatchStyle::None,
            HotPatchStyle::Win64,
            HotPatchStyle::LinuxFtrace,
            HotPatchStyle::LinuxLivepatch,
            HotPatchStyle::Generic,
            HotPatchStyle::JitCompiler,
        ] {
            let sled = generate_hotpatch_sled(16, *style, NopSledStrategy::Optimal, true);
            if *style == HotPatchStyle::None {
                assert!(sled.is_empty());
            } else {
                assert_eq!(sled.len(), 16);
                // Verify validity.
                assert!(validate_nop_sled(&sled).is_ok());
            }
        }
    }

    #[test]
    fn test_is_nop_prefix_all() {
        let prefixes: &[u8] = &[0x66, 0x67, 0x2E, 0x3E, 0x26, 0x64, 0x65, 0xF0, 0xF2, 0xF3];
        for &p in prefixes {
            assert!(is_nop_prefix(p), "0x{:02X} should be a NOP prefix", p);
        }
    }

    #[test]
    fn test_validate_nop_sled_complex() {
        // A complex sled with mixed NOP sizes.
        let mut sled = make_test_nop_sled();
        sled.strategy = NopSledStrategy::Optimal;
        let bytes = sled.generate_sled(67);
        assert_eq!(bytes.len(), 67);
        assert!(validate_nop_sled(&bytes).is_ok());

        // Intel strategy.
        sled.strategy = NopSledStrategy::Intel;
        let bytes = sled.generate_sled(67);
        assert_eq!(bytes.len(), 67);
        assert!(validate_nop_sled(&bytes).is_ok());

        // AMD strategy.
        sled.strategy = NopSledStrategy::Amd;
        let bytes = sled.generate_sled(67);
        assert_eq!(bytes.len(), 67);
        assert!(validate_nop_sled(&bytes).is_ok());
    }

    #[test]
    fn test_sled_across_strategies() {
        // All strategies should produce the correct size.
        let strategies = [
            NopSledStrategy::SingleByte,
            NopSledStrategy::Optimal,
            NopSledStrategy::Intel,
            NopSledStrategy::Amd,
            NopSledStrategy::MinSize,
            NopSledStrategy::MinDecode,
            NopSledStrategy::Compat,
            NopSledStrategy::MaxPatchable,
        ];
        for &strat in &strategies {
            let mut sled = X86NopSled::new(true, strat, NopMicroArch::Generic);
            for size in [0, 1, 2, 3, 7, 11, 15, 16, 32, 64, 100, 127] {
                let bytes = sled.generate_sled(size);
                assert_eq!(
                    bytes.len(),
                    size,
                    "Strategy {:?} failed for size {}",
                    strat,
                    size
                );
            }
        }
    }

    #[test]
    fn test_branch_target_alignment_multiple() {
        for offset in 0..20 {
            let padding =
                generate_branch_target_alignment(offset, false, NopMicroArch::Skylake, true);
            let new_offset = offset + padding.len() as u64;
            if padding.len() <= 15 {
                assert_eq!(new_offset % 16, 0);
            }
        }
    }

    #[test]
    fn test_no_loop_alignment_when_too_much_padding() {
        // If the loop is at offset 1, aligning to 32 would need 31 bytes,
        // which exceeds the max_nop_bytes of 24 for LoopHeader32.
        let (padding, _) = generate_loop_header_alignment(1, NopMicroArch::Zen4, true);
        // Should be empty because 31 > 24.
        assert!(padding.is_empty());
    }

    #[test]
    fn test_nop_sequence_display_format() {
        let seq = amd_nop_sequence(10).unwrap();
        let s = format!("{}", seq);
        assert!(s.contains("NOP(10B)"));
        assert!(s.contains("SegmentNop"));
    }

    #[test]
    fn test_hex_str_utility() {
        assert_eq!(hex_str(&[0x90]), "90");
        assert_eq!(hex_str(&[0x0F, 0x1F, 0x00]), "0F 1F 00");
        assert_eq!(hex_str(&[]), "");
    }

    #[test]
    fn test_alignment_targets_boundary() {
        assert_eq!(AlignmentTarget::FunctionEntry16.boundary(), 16);
        assert_eq!(AlignmentTarget::FunctionEntry32.boundary(), 32);
        assert_eq!(AlignmentTarget::FunctionEntry64.boundary(), 64);
        assert_eq!(AlignmentTarget::LoopHeader16.boundary(), 16);
        assert_eq!(AlignmentTarget::LoopHeader32.boundary(), 32);
        assert_eq!(AlignmentTarget::LoopHeader64.boundary(), 64);
        assert_eq!(AlignmentTarget::BranchTarget16.boundary(), 16);
        assert_eq!(AlignmentTarget::BranchTarget32.boundary(), 32);
        assert_eq!(AlignmentTarget::BasicBlock8.boundary(), 8);
        assert_eq!(AlignmentTarget::NoAlignment.boundary(), 1);
    }

    #[test]
    fn test_alignment_target_use_long_nops() {
        assert!(AlignmentTarget::FunctionEntry16.use_long_nops());
        assert!(!AlignmentTarget::BasicBlock8.use_long_nops());
        assert!(!AlignmentTarget::NoAlignment.use_long_nops());
    }

    #[test]
    fn test_nop_sled_32bit_vs_64bit() {
        let mut sled_64 = make_test_nop_sled();
        let mut sled_32 = X86NopSled::default_for(false);

        let b64 = sled_64.generate_sled(16);
        let b32 = sled_32.generate_sled(16);
        // Both should produce 16 bytes.
        assert_eq!(b64.len(), 16);
        assert_eq!(b32.len(), 16);
    }

    #[test]
    fn test_optimal_nop_prefers_lower_decode_cost() {
        // For sizes where Intel and AMD differ, optimal should pick
        // the lower decode cost.
        let seq10 = optimal_nop_sequence(10).unwrap();
        // Both Intel and AMD have decode_cost 1 for 10 bytes.
        assert_eq!(seq10.decode_cost, 1);
    }

    #[test]
    fn test_function_entry_alignment_skip_when_aligned() {
        // Already aligned to 16.
        let pad = generate_function_entry_alignment(
            32,
            16,
            NopSledStrategy::Optimal,
            NopMicroArch::Generic,
            true,
        );
        assert!(pad.is_empty());
    }

    #[test]
    fn test_nop_sled_validation_rejects_invalid() {
        // 0xCC (INT3) is not a NOP.
        assert!(validate_nop_sled(&[0xCC]).is_err());
        // 0xC3 (RET) is not a NOP.
        assert!(validate_nop_sled(&[0xC3]).is_err());
        // Mix of valid and invalid.
        assert!(validate_nop_sled(&[0x90, 0xCC]).is_err());
    }

    #[test]
    fn test_minimize_nop_count_large_sled() {
        let original = vec![0x90; 150];
        let minimized = minimize_nop_count(&original);
        assert_eq!(minimized.len(), 150);
        // Should use 10 x 15-byte NOPs.
    }

    #[test]
    fn test_decode_cost_monotonicity() {
        // Larger NOP sleds should have >= decode cost.
        let c1 = nop_sled_decode_cost(&[5], 4);
        let c2 = nop_sled_decode_cost(&[5, 5], 4);
        assert!(c2 >= c1);
    }

    #[test]
    fn test_nop_uop_count_all_microarchs() {
        let microarchs = [
            NopMicroArch::Skylake,
            NopMicroArch::Zen4,
            NopMicroArch::Bonnell,
            NopMicroArch::Goldmont,
            NopMicroArch::Tremont,
        ];
        for ma in &microarchs {
            // NOP should always use 1 μop slot.
            assert_eq!(nop_uop_count(5, *ma), 1);
        }
    }

    #[test]
    fn test_advance_offset_then_align() {
        let mut sled = make_test_nop_sled();
        sled.advance_offset(5);
        assert_eq!(sled.current_offset, 5);
        let pad = sled.align_to_16();
        assert_eq!(pad.len(), 11); // 16 - 5
    }

    #[test]
    fn test_constant_nops_verification() {
        use constant_nops::*;
        // All constant NOPs should validate.
        assert!(validate_nop_sled(&NOP1).is_ok());
        assert!(validate_nop_sled(&NOP2).is_ok());
        assert!(validate_nop_sled(&NOP3).is_ok());
        assert!(validate_nop_sled(&NOP4).is_ok());
        assert!(validate_nop_sled(&NOP5).is_ok());
        assert!(validate_nop_sled(&NOP6).is_ok());
        assert!(validate_nop_sled(&NOP7).is_ok());
        assert!(validate_nop_sled(&NOP8).is_ok());
        assert!(validate_nop_sled(&NOP9).is_ok());
    }

    #[test]
    fn test_intel_vs_amd_nop_10_byte_differs() {
        let intel = intel_nop_sequence(10).unwrap();
        let amd = amd_nop_sequence(10).unwrap();
        // They should differ at the prefix level.
        assert_ne!(intel.bytes, amd.bytes);
        // But both should be valid NOPs.
        assert!(validate_nop_sled(&intel.bytes).is_ok());
        assert!(validate_nop_sled(&amd.bytes).is_ok());
    }
}