llvm-native-core 0.1.15

//! Call Frame Information generation — .debug_frame and .eh_frame sections.
//!
//! This module provides structures and builders for DWARF Call Frame
//! Information (CFI), including Common Information Entries (CIEs),
//! Frame Description Entries (FDEs), and a high-level `CFIBuilder` for
//! constructing CFI instruction streams.
//!
//! Supports both .debug_frame (DWARF-standard) and .eh_frame (ELF
//! exception-handling) formats.

#![allow(dead_code)]

use super::{encode_sleb128, encode_uleb128};

/// Stub type for DWARF frame handling; see CFIBuilder, CIE, FDE for full implementations.
pub struct DwarfFrame;

// ============================================================================
// CFI Opcodes — DW_CFA_*
// ============================================================================

/// DWARF Call Frame Instruction opcodes.
///
/// These constants define the byte values for each CFA operation.
/// The high 2 bits of certain opcodes encode the operand inline:
/// - `DW_CFA_advance_loc` (0x40): bits 0-5 encode the delta
/// - `DW_CFA_offset` (0x80): bits 0-5 encode the register
/// - `DW_CFA_restore` (0xC0): bits 0-5 encode the register
pub mod cfa_ops {
    /// Advance location by delta (high 2 bits = 01, delta in low 6 bits).
    pub const DW_CFA_advance_loc: u8 = 0x40;
    /// Register saved at CFA offset (high 2 bits = 10, register in low 6 bits).
    pub const DW_CFA_offset: u8 = 0x80;
    /// Restore register to initial rule (high 2 bits = 11, register in low 6 bits).
    pub const DW_CFA_restore: u8 = 0xC0;
    /// No operation.
    pub const DW_CFA_nop: u8 = 0x00;
    /// Set absolute location.
    pub const DW_CFA_set_loc: u8 = 0x01;
    /// Advance location by 1-byte unsigned delta.
    pub const DW_CFA_advance_loc1: u8 = 0x02;
    /// Advance location by 2-byte unsigned delta.
    pub const DW_CFA_advance_loc2: u8 = 0x03;
    /// Advance location by 4-byte unsigned delta.
    pub const DW_CFA_advance_loc4: u8 = 0x04;
    /// Register saved at CFA offset (ULEB128 register, ULEB128 offset).
    pub const DW_CFA_offset_extended: u8 = 0x05;
    /// Restore extended register.
    pub const DW_CFA_restore_extended: u8 = 0x06;
    /// Register has no recoverable value.
    pub const DW_CFA_undefined: u8 = 0x07;
    /// Register has same value as in caller.
    pub const DW_CFA_same_value: u8 = 0x08;
    /// Register saved in another register.
    pub const DW_CFA_register: u8 = 0x09;
    /// Remember current state on the CFI stack.
    pub const DW_CFA_remember_state: u8 = 0x0A;
    /// Restore previously remembered state.
    pub const DW_CFA_restore_state: u8 = 0x0B;
    /// Define CFA: register + offset.
    pub const DW_CFA_def_cfa: u8 = 0x0C;
    /// Change CFA register, keep offset.
    pub const DW_CFA_def_cfa_register: u8 = 0x0D;
    /// Change CFA offset, keep register.
    pub const DW_CFA_def_cfa_offset: u8 = 0x0E;
    /// Define CFA via DWARF expression.
    pub const DW_CFA_def_cfa_expression: u8 = 0x0F;
    /// Register saved via DWARF expression.
    pub const DW_CFA_expression: u8 = 0x10;
    /// Register saved at CFA signed offset (SLEB128 offset).
    pub const DW_CFA_offset_extended_sf: u8 = 0x11;
    /// Define CFA: register + signed offset (SLEB128).
    pub const DW_CFA_def_cfa_sf: u8 = 0x12;
    /// Change CFA signed offset (SLEB128).
    pub const DW_CFA_def_cfa_offset_sf: u8 = 0x13;
    /// Register has value at CFA offset (not indirect).
    pub const DW_CFA_val_offset: u8 = 0x14;
    /// Register has value at CFA signed offset.
    pub const DW_CFA_val_offset_sf: u8 = 0x15;
    /// Register has value via expression.
    pub const DW_CFA_val_expression: u8 = 0x16;
    /// Lowest user-defined opcode.
    pub const DW_CFA_lo_user: u8 = 0x1C;
    /// Highest user-defined opcode.
    pub const DW_CFA_hi_user: u8 = 0x3F;

    /// GNU extension: argument size for call sites.
    pub const DW_CFA_GNU_args_size: u8 = 0x2E;
    /// GNU extension: negative offset extended.
    pub const DW_CFA_GNU_negative_offset_extended: u8 = 0x2F;
    /// AArch64: negate RA state (for PAuth).
    pub const DW_CFA_AARCH64_negate_ra_state: u8 = 0x2D;
    /// MIPS: 8-byte advance location.
    pub const DW_CFA_MIPS_advance_loc8: u8 = 0x1D;
    /// GNU: window save (SPARC).
    pub const DW_CFA_GNU_window_save: u8 = 0x2D;
}

// ============================================================================
// Pointer Encoding Constants (for .eh_frame augmentation)
// ============================================================================

/// DWARF Exception Header pointer encoding constants used in .eh_frame
/// augmentation strings (e.g., "zR", "zPLR").
pub mod ptr_encoding {
    /// Encoding is relative to the current position.
    pub const DW_EH_PE_pcrel: u8 = 0x10;
    /// Encoding is relative to the start of the text segment.
    pub const DW_EH_PE_textrel: u8 = 0x20;
    /// Encoding is relative to the start of the data segment.
    pub const DW_EH_PE_datarel: u8 = 0x30;
    /// Encoding is relative to the start of the function.
    pub const DW_EH_PE_funcrel: u8 = 0x40;
    /// Encoding is absolute (no relocation).
    pub const DW_EH_PE_absptr: u8 = 0x00;
    /// Value is omitted entirely.
    pub const DW_EH_PE_omit: u8 = 0xFF;

    /// Value is unsigned (ULEB128).
    pub const DW_EH_PE_uleb128: u8 = 0x01;
    /// Value is unsigned 2-byte.
    pub const DW_EH_PE_udata2: u8 = 0x02;
    /// Value is unsigned 4-byte.
    pub const DW_EH_PE_udata4: u8 = 0x03;
    /// Value is unsigned 8-byte.
    pub const DW_EH_PE_udata8: u8 = 0x04;
    /// Value is signed (SLEB128).
    pub const DW_EH_PE_sleb128: u8 = 0x09;
    /// Value is signed 2-byte.
    pub const DW_EH_PE_sdata2: u8 = 0x0A;
    /// Value is signed 4-byte.
    pub const DW_EH_PE_sdata4: u8 = 0x0B;
    /// Value is signed 8-byte.
    pub const DW_EH_PE_sdata8: u8 = 0x0C;

    /// Indirect reference: value is a pointer to the actual value.
    pub const DW_EH_PE_indirect: u8 = 0x80;
}

// ============================================================================
// Common Information Entry (CIE)
// ============================================================================

/// A Common Information Entry — shared CFI state applied to one or more FDEs.
///
/// The CIE defines:
/// - The version of CFI information (1 for .eh_frame, 3 for DWARF3, 4 for DWARF4)
/// - An augmentation string describing optional data
/// - Code/data alignment factors
/// - The return address register
/// - Initial CFI instructions executed before the FDE's instructions
#[derive(Debug, Clone)]
pub struct CIE {
    /// CFI version: 1 (eh_frame), 3 (DWARF3), 4 (DWARF4).
    pub version: u8,
    /// Augmentation string (e.g., "zR", "zPLR", "").
    pub augmentation: String,
    /// Code alignment factor (ULEB128): all location advances are multiplied by this.
    pub code_alignment_factor: u64,
    /// Data alignment factor (SLEB128): all offset values are multiplied by this.
    pub data_alignment_factor: i64,
    /// Return address register number.
    pub return_address_register: u64,
    /// Optional personality routine address (for .eh_frame).
    pub personality: Option<u64>,
    /// LSDA (Language-Specific Data Area) encoding (for .eh_frame).
    pub lsda_encoding: u8,
    /// FDE pointer encoding (for .eh_frame, how initial_location is encoded).
    pub fde_pointer_encoding: u8,
    /// Initial CFI instructions (raw byte sequence).
    pub initial_instructions: Vec<u8>,
}

impl CIE {
    /// Create a new CIE with default values.
    pub fn new(version: u8, augmentation: &str) -> Self {
        Self {
            version,
            augmentation: augmentation.to_string(),
            code_alignment_factor: 1,
            data_alignment_factor: -8,
            return_address_register: 16,
            personality: None,
            lsda_encoding: ptr_encoding::DW_EH_PE_omit,
            fde_pointer_encoding: ptr_encoding::DW_EH_PE_absptr,
            initial_instructions: Vec::new(),
        }
    }

    /// Create a standard CIE for AArch64.
    ///
    /// AArch64 properties:
    /// - Code alignment: 1 (all instructions are 4 bytes, CFI advance by 1 per instruction)
    /// - Data alignment: -8 (stack grows down, 8-byte aligned on AArch64)
    /// - Return address register: x30 (link register)
    /// - Initial instructions: `DW_CFA_def_cfa r31(sp), 0`
    pub fn aarch64() -> Self {
        let mut cie = CIE::new(4, "");
        cie.code_alignment_factor = 1;
        cie.data_alignment_factor = -8;
        cie.return_address_register = 30; // x30 = LR
                                          // Start with CFA = sp (r31) + 0
        let mut instrs = Vec::new();
        instrs.push(cfa_ops::DW_CFA_def_cfa);
        encode_uleb128(&mut instrs, 31); // SP
        encode_uleb128(&mut instrs, 0); // offset 0
        cie.initial_instructions = instrs;
        cie
    }

    /// Create a standard CIE for x86-64.
    ///
    /// x86-64 properties:
    /// - Code alignment: 1 (x86 instructions are variable-length, CFA advance by bytes)
    /// - Data alignment: -8 (stack grows down, 8-byte aligned on x86-64)
    /// - Return address register: 16 (RIP in DWARF register numbering)
    /// - Initial instructions:
    ///   - `DW_CFA_def_cfa r7(rsp), 8` (CFA = rsp + 8 after call pushes return address)
    ///   - `DW_CFA_offset r16(rip), -8` (return address saved at CFA - 8)
    pub fn x86_64() -> Self {
        let mut cie = CIE::new(4, "");
        cie.code_alignment_factor = 1;
        cie.data_alignment_factor = -8;
        cie.return_address_register = 16; // RIP
        let mut instrs = Vec::new();
        // CFA = rsp(7) + 8 (after call pushes return address)
        instrs.push(cfa_ops::DW_CFA_def_cfa);
        encode_uleb128(&mut instrs, 7); // RSP
        encode_uleb128(&mut instrs, 8); // offset 8
                                        // Return address (reg 16) saved at CFA - 8
        instrs.push(cfa_ops::DW_CFA_offset | 16); // high 2 bits = 10, reg in low 6
        encode_uleb128(&mut instrs, 1); // 1 * data_alignment_factor = -8
        cie.initial_instructions = instrs;
        cie
    }

    /// Create a standard CIE for .eh_frame on AArch64.
    ///
    /// Uses augmentation "zR" (augmentation data with PC-relative FDE encoding).
    pub fn eh_frame_aarch64() -> Self {
        let mut cie = CIE::aarch64();
        cie.version = 1;
        cie.augmentation = "zR".to_string();
        cie.fde_pointer_encoding = ptr_encoding::DW_EH_PE_pcrel | ptr_encoding::DW_EH_PE_sdata4;
        cie
    }

    /// Create a standard CIE for .eh_frame on x86-64.
    ///
    /// Uses augmentation "zR" (augmentation data with PC-relative FDE encoding).
    pub fn eh_frame_x86_64() -> Self {
        let mut cie = CIE::x86_64();
        cie.version = 1;
        cie.augmentation = "zR".to_string();
        cie.fde_pointer_encoding = ptr_encoding::DW_EH_PE_pcrel | ptr_encoding::DW_EH_PE_sdata4;
        cie
    }

    /// Check whether the augmentation string contains the given character.
    pub fn has_augmentation(&self, ch: char) -> bool {
        self.augmentation.contains(ch)
    }
}

impl Default for CIE {
    fn default() -> Self {
        CIE::x86_64()
    }
}

// ============================================================================
// Frame Description Entry (FDE)
// ============================================================================

/// A Frame Description Entry — CFI rules for a specific code range.
///
/// Each FDE references a CIE (via `cie_pointer`: offset back to the CIE)
/// and provides:
/// - An initial location (start address)
/// - An address range (length of the covered code)
/// - Optional augmentation data
/// - A sequence of CFI instructions that describe how to unwind the frame
#[derive(Debug, Clone)]
pub struct FDE {
    /// Offset from this field back to the start of the associated CIE.
    /// For .debug_frame this is a section offset.
    /// For .eh_frame this is a negative offset from the CIE pointer field.
    pub cie_pointer: u32,
    /// Initial location (start PC) of the covered code range.
    pub initial_location: u64,
    /// Length of the covered code range (in bytes for .debug_frame;
    /// in units of code_alignment_factor for .eh_frame with certain encodings).
    pub address_range: u64,
    /// Augmentation data (only present if CIE augmentation includes 'z').
    pub augmentation_data: Vec<u8>,
    /// CFI instructions for this FDE.
    pub instructions: Vec<u8>,
}

impl FDE {
    /// Create a new FDE referencing the given CIE pointer offset.
    pub fn new(cie_pointer: u32) -> Self {
        Self {
            cie_pointer,
            initial_location: 0,
            address_range: 0,
            augmentation_data: Vec::new(),
            instructions: Vec::new(),
        }
    }

    /// Create an FDE for a specific function at `start` spanning `size` bytes.
    pub fn for_function(cie_pointer: u32, start: u64, size: u64) -> Self {
        Self {
            cie_pointer,
            initial_location: start,
            address_range: size,
            augmentation_data: Vec::new(),
            instructions: Vec::new(),
        }
    }
}

// ============================================================================
// CFI Builder — incremental construction of CFI instruction streams
// ============================================================================

/// Incremental builder for CFI instruction sequences.
///
/// `CFIBuilder` accumulates CFA instructions and provides convenience
/// methods for the most common operations. It can be used to build
/// both CIE initial instructions and FDE instruction streams.
///
/// # Example
///
/// ```ignore
/// let mut builder = CFIBuilder::new(false);
/// builder.def_cfa(31, 0);       // CFA = sp + 0
/// builder.offset(30, 1);        // LR saved at CFA - 8
/// builder.advance_loc(4);       // advance 4 bytes
/// builder.def_cfa_offset(32);   // CFA = sp + 32
/// let fde = builder.finish_fde(start, range);
/// ```
pub struct CFIBuilder {
    /// Accumulated CFI instruction bytes.
    pub instructions: Vec<u8>,
    /// The CIE associated with this builder (provides alignment factors).
    pub cie: Option<CIE>,
    /// Whether this is for .eh_frame (vs .debug_frame).
    pub is_eh_frame: bool,
}

impl CFIBuilder {
    /// Create a new empty CFI builder.
    ///
    /// `is_eh_frame`: true for .eh_frame (version 1, CIE_id=0),
    /// false for .debug_frame (version 4, CIE_id=0xFFFFFFFF).
    pub fn new(is_eh_frame: bool) -> Self {
        Self {
            instructions: Vec::new(),
            cie: None,
            is_eh_frame,
        }
    }

    /// Create a new CFI builder with an associated CIE.
    pub fn with_cie(is_eh_frame: bool, cie: CIE) -> Self {
        Self {
            instructions: Vec::new(),
            cie: Some(cie),
            is_eh_frame,
        }
    }

    // ── Convenience constructors ──────────────────────────────────────

    /// Create a standard AArch64 CIE.
    pub fn create_cie_aarch64() -> CIE {
        if cfg!(target_arch = "aarch64") {
            CIE::aarch64()
        } else {
            // Return AArch64 CIE regardless — caller knows the target
            CIE::aarch64()
        }
    }

    /// Create a standard x86-64 CIE.
    pub fn create_cie_x86_64() -> CIE {
        CIE::x86_64()
    }

    // ── CFA definition ────────────────────────────────────────────────

    /// Define the CFA as register + offset.
    ///
    /// Uses `DW_CFA_def_cfa` for unsigned offsets and `DW_CFA_def_cfa_sf`
    /// for signed offsets (when `offset` is negative).
    pub fn def_cfa(&mut self, register: u64, offset: i64) {
        if offset >= 0 {
            self.instructions.push(cfa_ops::DW_CFA_def_cfa);
            encode_uleb128(&mut self.instructions, register);
            encode_uleb128(&mut self.instructions, offset as u64);
        } else {
            self.instructions.push(cfa_ops::DW_CFA_def_cfa_sf);
            encode_uleb128(&mut self.instructions, register);
            encode_sleb128(&mut self.instructions, offset);
        }
    }

    /// Change the CFA register, keeping the current offset.
    pub fn def_cfa_register(&mut self, register: u64) {
        self.instructions.push(cfa_ops::DW_CFA_def_cfa_register);
        encode_uleb128(&mut self.instructions, register);
    }

    /// Change the CFA offset (unsigned), keeping the current register.
    pub fn def_cfa_offset(&mut self, offset: u64) {
        self.instructions.push(cfa_ops::DW_CFA_def_cfa_offset);
        encode_uleb128(&mut self.instructions, offset);
    }

    /// Change the CFA offset (signed).
    pub fn def_cfa_offset_sf(&mut self, offset: i64) {
        self.instructions.push(cfa_ops::DW_CFA_def_cfa_offset_sf);
        encode_sleb128(&mut self.instructions, offset);
    }

    /// Define the CFA via a DWARF expression.
    pub fn def_cfa_expression(&mut self, expr: &[u8]) {
        self.instructions.push(cfa_ops::DW_CFA_def_cfa_expression);
        encode_uleb128(&mut self.instructions, expr.len() as u64);
        self.instructions.extend_from_slice(expr);
    }

    // ── Register rules ────────────────────────────────────────────────

    /// Register is saved at `offset * data_alignment_factor` from the CFA.
    ///
    /// Uses the compact form (`DW_CFA_offset` high bits) when possible
    /// (register < 64 and offset fits in ULEB128), otherwise uses
    /// `DW_CFA_offset_extended`.
    pub fn offset(&mut self, register: u64, offset: u64) {
        if register < 64 {
            // Compact form: high 2 bits = 10, register in low 6
            self.instructions
                .push(cfa_ops::DW_CFA_offset | (register as u8 & 0x3F));
            encode_uleb128(&mut self.instructions, offset);
        } else {
            self.instructions.push(cfa_ops::DW_CFA_offset_extended);
            encode_uleb128(&mut self.instructions, register);
            encode_uleb128(&mut self.instructions, offset);
        }
    }

    /// Register is saved at a signed offset from the CFA.
    pub fn offset_extended_sf(&mut self, register: u64, offset: i64) {
        self.instructions.push(cfa_ops::DW_CFA_offset_extended_sf);
        encode_uleb128(&mut self.instructions, register);
        encode_sleb128(&mut self.instructions, offset);
    }

    /// Restore register to the rule defined in the CIE.
    ///
    /// Uses compact form when register < 64.
    pub fn restore(&mut self, register: u64) {
        if register < 64 {
            self.instructions
                .push(cfa_ops::DW_CFA_restore | (register as u8 & 0x3F));
        } else {
            self.instructions.push(cfa_ops::DW_CFA_restore_extended);
            encode_uleb128(&mut self.instructions, register);
        }
    }

    /// Register `reg1` is saved in register `reg2` (same value).
    pub fn save_register(&mut self, reg1: u64, reg2: u64) {
        self.instructions.push(cfa_ops::DW_CFA_register);
        encode_uleb128(&mut self.instructions, reg1);
        encode_uleb128(&mut self.instructions, reg2);
    }

    /// Register has the same value as in the caller (not modified).
    pub fn same_value(&mut self, register: u64) {
        self.instructions.push(cfa_ops::DW_CFA_same_value);
        encode_uleb128(&mut self.instructions, register);
    }

    /// Register has no recoverable value.
    pub fn undefined(&mut self, register: u64) {
        self.instructions.push(cfa_ops::DW_CFA_undefined);
        encode_uleb128(&mut self.instructions, register);
    }

    /// Register is saved via a DWARF expression.
    pub fn expression(&mut self, register: u64, expr: &[u8]) {
        self.instructions.push(cfa_ops::DW_CFA_expression);
        encode_uleb128(&mut self.instructions, register);
        encode_uleb128(&mut self.instructions, expr.len() as u64);
        self.instructions.extend_from_slice(expr);
    }

    /// Register has the given value (not indirect) at a CFA offset.
    pub fn val_offset(&mut self, register: u64, offset: u64) {
        self.instructions.push(cfa_ops::DW_CFA_val_offset);
        encode_uleb128(&mut self.instructions, register);
        encode_uleb128(&mut self.instructions, offset);
    }

    /// Register has the given value at a signed CFA offset.
    pub fn val_offset_sf(&mut self, register: u64, offset: i64) {
        self.instructions.push(cfa_ops::DW_CFA_val_offset_sf);
        encode_uleb128(&mut self.instructions, register);
        encode_sleb128(&mut self.instructions, offset);
    }

    /// Register has the given value computed by a DWARF expression.
    pub fn val_expression(&mut self, register: u64, expr: &[u8]) {
        self.instructions.push(cfa_ops::DW_CFA_val_expression);
        encode_uleb128(&mut self.instructions, register);
        encode_uleb128(&mut self.instructions, expr.len() as u64);
        self.instructions.extend_from_slice(expr);
    }

    // ── State management ──────────────────────────────────────────────

    /// Push the current CFI state onto the internal stack.
    ///
    /// Use `restore_state` to pop back to this saved state.
    pub fn remember_state(&mut self) {
        self.instructions.push(cfa_ops::DW_CFA_remember_state);
    }

    /// Pop the most recently saved CFI state from the internal stack.
    pub fn restore_state(&mut self) {
        self.instructions.push(cfa_ops::DW_CFA_restore_state);
    }

    // ── Location control ──────────────────────────────────────────────

    /// Advance the current location by `delta` bytes.
    ///
    /// Uses compact form when delta < 64, otherwise uses
    /// `DW_CFA_advance_loc1`, `advance_loc2`, or `advance_loc4` as needed.
    pub fn advance_loc(&mut self, delta: u64) {
        if delta < 64 {
            self.instructions
                .push(cfa_ops::DW_CFA_advance_loc | (delta as u8 & 0x3F));
        } else if delta <= 0xFF {
            self.instructions.push(cfa_ops::DW_CFA_advance_loc1);
            self.instructions.push(delta as u8);
        } else if delta <= 0xFFFF {
            self.instructions.push(cfa_ops::DW_CFA_advance_loc2);
            self.instructions
                .extend_from_slice(&(delta as u16).to_le_bytes());
        } else {
            self.instructions.push(cfa_ops::DW_CFA_advance_loc4);
            self.instructions
                .extend_from_slice(&(delta as u32).to_le_bytes());
        }
    }

    /// Set the absolute current location.
    ///
    /// Uses `DW_CFA_set_loc` with an address-sized value.
    pub fn set_loc(&mut self, address: u64, addr_size: u8) {
        self.instructions.push(cfa_ops::DW_CFA_set_loc);
        match addr_size {
            4 => self
                .instructions
                .extend_from_slice(&(address as u32).to_le_bytes()),
            _ => self.instructions.extend_from_slice(&address.to_le_bytes()),
        }
    }

    // ── Misc ──────────────────────────────────────────────────────────

    /// Emit a no-operation.
    pub fn nop(&mut self) {
        self.instructions.push(cfa_ops::DW_CFA_nop);
    }

    /// Emit multiple NOP instructions for alignment padding.
    pub fn pad_to_alignment(&mut self, alignment: usize) {
        let rem = (self.instructions.len() + 1) % alignment; // +1 for CIE length
        let padding = (alignment - rem) % alignment;
        for _ in 0..padding {
            self.nop();
        }
    }

    // ── Encoding helpers ──────────────────────────────────────────────

    /// Encode a CIE into raw bytes.
    ///
    /// Produces a valid CIE record for either .debug_frame or .eh_frame
    /// depending on the builder's `is_eh_frame` flag.
    ///
    /// # .debug_frame layout
    ///
    /// ```text
    /// length (4 bytes)         — excluding this length field
    /// CIE_id (4 bytes)         — 0xFFFFFFFF
    /// version (1 byte)         — 4 (DWARF4)
    /// augmentation (string)    — null-terminated UTF-8
    /// address_size (1 byte)    — 4 or 8
    /// segment_selector_size (1 byte) — 0
    /// code_alignment_factor (ULEB128)
    /// data_alignment_factor (SLEB128)
    /// return_address_register (ULEB128)
    /// augmentation_data_length (ULEB128)
    /// augmentation_data
    /// initial_instructions
    /// ```
    ///
    /// # .eh_frame layout
    ///
    /// ```text
    /// length (4 bytes)
    /// CIE_id (4 bytes)         — 0
    /// version (1 byte)         — 1 or 3
    /// augmentation (string)    — null-terminated
    /// code_alignment_factor (ULEB128)
    /// data_alignment_factor (SLEB128)
    /// return_address_register (ULEB128 for version 3, 1 byte for version 1)
    /// [if 'z'] augmentation_data_length (ULEB128)
    /// [if 'z'] augmentation_data
    /// initial_instructions
    /// ```
    pub fn emit_cie(&self, cie: &CIE, addr_size: u8) -> Vec<u8> {
        let mut out = Vec::new();

        if self.is_eh_frame {
            self.encode_eh_frame_cie(&mut out, cie, addr_size);
        } else {
            self.encode_debug_frame_cie(&mut out, cie, addr_size);
        }

        // Fix up the length field
        let total_len = out.len() as u32;
        let unit_len = total_len - 4;
        out[0..4].copy_from_slice(&unit_len.to_le_bytes());

        out
    }

    /// Encode .debug_frame CIE format.
    fn encode_debug_frame_cie(&self, out: &mut Vec<u8>, cie: &CIE, addr_size: u8) {
        // length placeholder
        let len_pos = out.len();
        out.extend_from_slice(&[0u8; 4]);

        // CIE_id = 0xFFFFFFFF for .debug_frame
        out.extend_from_slice(&0xFFFFFFFFu32.to_le_bytes());

        // version (DWARF4 = 4)
        out.push(cie.version);

        // augmentation
        out.extend_from_slice(cie.augmentation.as_bytes());
        out.push(0);

        // address_size (only in .debug_frame)
        out.push(addr_size);

        // segment_selector_size (0 for flat address space)
        out.push(0);

        // code_alignment_factor
        encode_uleb128(out, cie.code_alignment_factor);

        // data_alignment_factor
        encode_sleb128(out, cie.data_alignment_factor);

        // return_address_register
        encode_uleb128(out, cie.return_address_register);

        // augmentation data
        if cie.has_augmentation('z') {
            // Build augmentation data
            let mut aug_data = Vec::new();
            // FDE pointer encoding (for 'R')
            if cie.has_augmentation('R') {
                aug_data.push(cie.fde_pointer_encoding);
            }
            // LSDA encoding (for 'L')
            if cie.has_augmentation('L') {
                aug_data.push(cie.lsda_encoding);
            }
            // Personality routine (for 'P')
            if cie.has_augmentation('P') {
                if let Some(pers) = cie.personality {
                    aug_data.push(cie.fde_pointer_encoding);
                    match addr_size {
                        4 => aug_data.extend_from_slice(&(pers as u32).to_le_bytes()),
                        _ => aug_data.extend_from_slice(&pers.to_le_bytes()),
                    }
                }
            }
            encode_uleb128(out, aug_data.len() as u64);
            out.extend_from_slice(&aug_data);
        }

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

        let _ = len_pos;
    }

    /// Encode .eh_frame CIE format.
    fn encode_eh_frame_cie(&self, out: &mut Vec<u8>, cie: &CIE, addr_size: u8) {
        // length placeholder
        let len_pos = out.len();
        out.extend_from_slice(&[0u8; 4]);

        // CIE_id = 0 for .eh_frame
        out.extend_from_slice(&0u32.to_le_bytes());

        // version
        out.push(cie.version);

        // augmentation
        out.extend_from_slice(cie.augmentation.as_bytes());
        out.push(0);

        // code_alignment_factor
        encode_uleb128(out, cie.code_alignment_factor);

        // data_alignment_factor
        encode_sleb128(out, cie.data_alignment_factor);

        // return_address_register (1 byte for version 1, ULEB128 for version 3+)
        if cie.version >= 3 {
            encode_uleb128(out, cie.return_address_register);
        } else {
            out.push(cie.return_address_register as u8);
        }

        // Augmentation data
        if cie.has_augmentation('z') {
            let aug_start = out.len();
            out.push(0); // placeholder for augmentation length

            // 'R': FDE pointer encoding
            if cie.has_augmentation('R') {
                out.push(cie.fde_pointer_encoding);
            }

            // 'L': LSDA encoding
            if cie.has_augmentation('L') {
                out.push(cie.lsda_encoding);
            }

            // 'P': personality routine
            if cie.has_augmentation('P') {
                if let Some(pers) = cie.personality {
                    out.push(cie.fde_pointer_encoding);
                    match addr_size {
                        4 => out.extend_from_slice(&(pers as u32).to_le_bytes()),
                        _ => out.extend_from_slice(&pers.to_le_bytes()),
                    }
                } else {
                    out.push(ptr_encoding::DW_EH_PE_omit);
                }
            }

            // Fix up augmentation data length
            let aug_len = (out.len() - aug_start - 1) as u8;
            out[aug_start] = aug_len;
        }

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

        let _ = len_pos;
    }

    /// Encode an FDE into raw bytes.
    ///
    /// The FDE references a CIE and contains location information
    /// and CFI instructions.
    pub fn emit_fde(&self, fde: &FDE, cie: &CIE, addr_size: u8) -> Vec<u8> {
        let mut out = Vec::new();

        // length placeholder
        let len_pos = out.len();
        out.extend_from_slice(&[0u8; 4]);

        if self.is_eh_frame {
            // CIE_pointer: offset back to CIE from this field
            // For .eh_frame, this is a signed offset to the CIE
            let cie_offset = fde.cie_pointer;
            out.extend_from_slice(&cie_offset.to_le_bytes());

            // Initial location (encoded per pointer encoding)
            if cie.has_augmentation('R') {
                // PC-relative encoding
                let encoding = cie.fde_pointer_encoding & 0x0F;
                match encoding {
                    ptr_encoding::DW_EH_PE_sdata4 | ptr_encoding::DW_EH_PE_udata4 => {
                        out.extend_from_slice(&(fde.initial_location as u32).to_le_bytes());
                    }
                    ptr_encoding::DW_EH_PE_sdata8 | ptr_encoding::DW_EH_PE_udata8 => {
                        out.extend_from_slice(&fde.initial_location.to_le_bytes());
                    }
                    _ => {
                        // Default: address-sized
                        match addr_size {
                            4 => {
                                out.extend_from_slice(&(fde.initial_location as u32).to_le_bytes())
                            }
                            _ => out.extend_from_slice(&fde.initial_location.to_le_bytes()),
                        }
                    }
                }
            } else {
                match addr_size {
                    4 => out.extend_from_slice(&(fde.initial_location as u32).to_le_bytes()),
                    _ => out.extend_from_slice(&fde.initial_location.to_le_bytes()),
                }
            }

            // Address range
            match addr_size {
                4 => out.extend_from_slice(&(fde.address_range as u32).to_le_bytes()),
                _ => out.extend_from_slice(&fde.address_range.to_le_bytes()),
            }

            // Augmentation data
            if cie.has_augmentation('z') {
                encode_uleb128(&mut out, fde.augmentation_data.len() as u64);
                out.extend_from_slice(&fde.augmentation_data);
            }
        } else {
            // .debug_frame format
            // CIE_pointer: offset to CIE in the .debug_frame section
            out.extend_from_slice(&fde.cie_pointer.to_le_bytes());

            // Initial location (address-sized)
            match addr_size {
                4 => out.extend_from_slice(&(fde.initial_location as u32).to_le_bytes()),
                _ => out.extend_from_slice(&fde.initial_location.to_le_bytes()),
            }

            // Address range (address-sized)
            match addr_size {
                4 => out.extend_from_slice(&(fde.address_range as u32).to_le_bytes()),
                _ => out.extend_from_slice(&fde.address_range.to_le_bytes()),
            }

            // Augmentation data
            if cie.has_augmentation('z') {
                encode_uleb128(&mut out, fde.augmentation_data.len() as u64);
                out.extend_from_slice(&fde.augmentation_data);
            }
        }

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

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

        out
    }

    // ── Prologue CFI helpers ──────────────────────────────────────────

    /// Emit CFI instructions for a standard AArch64 prologue:
    ///
    /// ```asm
    /// stp x29, x30, [sp, #-32]!   ; save FP and LR, allocate 32 bytes
    /// mov x29, sp                  ; set FP = SP
    /// ```
    pub fn emit_aarch64_prologue_cfi(&mut self) {
        // After stp, FP(x29) and LR(x30) are saved at CFA offset
        // CFA is now sp + 32 (due to pre-decrement)
        self.def_cfa_offset(32);
        self.offset(29, 2); // FP at CFA + 2 * (-8) = CFA - 16... wait.

        // Actually, in standard AArch64:
        // stp x29, x30, [sp, #-32]! → sp -= 32, save x29@[sp], x30@[sp+8]
        // CFA = sp + 32 (since sp is now 32 less)
        // x29 saved at CFA - 32 + 0 = CFA - 32, normalized: offset = 32/8 = 4
        // x30 saved at CFA - 32 + 8 = CFA - 24, normalized: offset = 24/8 = 3
        self.offset(29, 4); // FP at CFA - 32 (i.e., offset=4 * -8 = -32)
        self.offset(30, 3); // LR at CFA - 24 (i.e., offset=3 * -8 = -24)
    }

    /// Emit CFI instructions for a standard x86-64 prologue:
    ///
    /// ```asm
    /// push rbp          ; save old frame pointer
    /// mov rbp, rsp      ; set new frame pointer
    /// ```
    ///
    /// After `push rbp`, the stack pointer is decremented by 8
    /// and the old RBP is stored at [RSP].
    ///
    /// CFA is now RSP + 16 (8 for return address + 8 for pushed RBP).
    /// RBP is saved at CFA - 16 (i.e. CFI offset 2 * -8 = -16).
    pub fn emit_x86_64_prologue_cfi(&mut self) {
        // push rbp: RSP -= 8, [RSP] = old RBP
        self.def_cfa_offset(16); // CFA = RSP + 8 (ret addr) + 8 (rbp) = RSP + 16
        self.offset(6, 2); // RBP at CFA + 2 * (-8) = CFA - 16

        // mov rbp, rsp would follow, but CFI-wise we might set RBP = CFA
        // This is often encoded as: def_cfa_register(rbp) after setting it
    }
}

// ============================================================================
// Frame Emitter — high-level section builder
// ============================================================================

/// High-level emitter for .debug_frame or .eh_frame sections.
///
/// `FrameEmitter` collects CIEs and FDEs and produces the complete
/// section contents in a single `emit()` call.
///
/// # Example
///
/// ```ignore
/// let mut emitter = FrameEmitter::new(false, 8);
/// emitter.add_cie(CFIBuilder::create_cie_aarch64());
/// emitter.add_fde(FDE::for_function(0, 0x1000, 0x40));
/// let section_bytes = emitter.emit().unwrap();
/// ```
pub struct FrameEmitter {
    /// All CIEs in this frame section.
    pub cies: Vec<CIE>,
    /// All FDEs in this frame section.
    pub fdes: Vec<FDE>,
    /// Whether this is an .eh_frame section.
    pub is_eh_frame: bool,
    /// Address size in bytes (4 or 8).
    pub address_size: u8,
    /// Internally tracked offset of each CIE for FDE `cie_pointer` calculation.
    cie_offsets: Vec<u64>,
}

impl FrameEmitter {
    /// Create a new frame emitter.
    ///
    /// - `is_eh_frame`: true for .eh_frame, false for .debug_frame.
    /// - `address_size`: 4 for 32-bit, 8 for 64-bit.
    pub fn new(is_eh_frame: bool, address_size: u8) -> Self {
        Self {
            cies: Vec::new(),
            fdes: Vec::new(),
            is_eh_frame,
            address_size,
            cie_offsets: Vec::new(),
        }
    }

    /// Add a CIE and return its index.
    pub fn add_cie(&mut self, cie: CIE) -> usize {
        let idx = self.cies.len();
        self.cies.push(cie);
        idx
    }

    /// Add an FDE. The FDE's `cie_pointer` should reference the CIE.
    pub fn add_fde(&mut self, fde: FDE) {
        self.fdes.push(fde);
    }

    /// Add an FDE for a function that references the first CIE.
    pub fn add_function_fde(
        &mut self,
        cie_index: usize,
        start: u64,
        size: u64,
        instructions: &[u8],
    ) {
        let fde = FDE {
            cie_pointer: 0, // will be fixed up during emit
            initial_location: start,
            address_range: size,
            augmentation_data: Vec::new(),
            instructions: instructions.to_vec(),
        };
        self.fdes.push(fde);
        let _ = cie_index;
    }

    /// Emit the complete .debug_frame or .eh_frame section.
    ///
    /// Returns `None` if there are no CIEs.
    pub fn emit(&mut self) -> Option<Vec<u8>> {
        if self.cies.is_empty() {
            return None;
        }

        let mut out = Vec::new();
        let builder = CFIBuilder::new(self.is_eh_frame);

        // Emit CIEs and track offsets for FDE fixup
        self.cie_offsets.clear();
        for cie in &self.cies {
            self.cie_offsets.push(out.len() as u64);
            let cie_bytes = builder.emit_cie(cie, self.address_size);
            out.extend_from_slice(&cie_bytes);
        }

        // Emit FDEs with correct CIE pointers
        let mut current_offset = out.len() as u64;
        for fde in &self.fdes {
            // Calculate CIE pointer
            let mut fde_bytes = Vec::new();
            let len_pos = fde_bytes.len();
            fde_bytes.extend_from_slice(&[0u8; 4]);

            // CIE pointer: for .debug_frame, it's the absolute offset of the CIE.
            // For .eh_frame, it's a signed offset from this field back to the CIE.
            let cie_offset = if self.is_eh_frame {
                // The CIE pointer field is at `current_offset + len_pos + 4` (after length)
                // CIE is at `self.cie_offsets[fde.cie_pointer as usize]`
                // Offset = cie_offset - current_offset_field_position
                let cie_pos = self
                    .cie_offsets
                    .get(fde.cie_pointer as usize)
                    .copied()
                    .unwrap_or(0);
                let field_pos = current_offset + len_pos as u64 + 4;
                // For .eh_frame, CIE pointer is a signed offset back to the CIE
                // from the current position (the CIE pointer field itself)
                (cie_pos as i64 - field_pos as i64) as u32
            } else {
                // .debug_frame: CIE pointer is absolute offset within section
                self.cie_offsets
                    .get(fde.cie_pointer as usize)
                    .copied()
                    .unwrap_or(0) as u32
            };

            fde_bytes.extend_from_slice(&cie_offset.to_le_bytes());

            // Initial location
            match self.address_size {
                4 => fde_bytes.extend_from_slice(&(fde.initial_location as u32).to_le_bytes()),
                _ => fde_bytes.extend_from_slice(&fde.initial_location.to_le_bytes()),
            }

            // Address range
            match self.address_size {
                4 => fde_bytes.extend_from_slice(&(fde.address_range as u32).to_le_bytes()),
                _ => fde_bytes.extend_from_slice(&fde.address_range.to_le_bytes()),
            }

            // Augmentation data
            if let Some(cie) = self.cies.get(fde.cie_pointer as usize) {
                if cie.has_augmentation('z') {
                    encode_uleb128(&mut fde_bytes, fde.augmentation_data.len() as u64);
                    fde_bytes.extend_from_slice(&fde.augmentation_data);
                }
            }

            // Instructions
            fde_bytes.extend_from_slice(&fde.instructions);

            // Fix up FDE length
            let fde_len = fde_bytes.len() as u32 - 4;
            fde_bytes[0..4].copy_from_slice(&fde_len.to_le_bytes());

            current_offset += fde_bytes.len() as u64;
            out.extend_from_slice(&fde_bytes);
        }

        Some(out)
    }
}

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

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

    // ── CIE tests ─────────────────────────────────────────────────────

    #[test]
    fn test_cie_new_defaults() {
        let cie = CIE::new(4, "zR");
        assert_eq!(cie.version, 4);
        assert_eq!(cie.augmentation, "zR");
        assert_eq!(cie.code_alignment_factor, 1);
        assert_eq!(cie.data_alignment_factor, -8);
        assert_eq!(cie.return_address_register, 16);
        assert!(cie.personality.is_none());
        assert!(cie.initial_instructions.is_empty());
    }

    #[test]
    fn test_cie_aarch64() {
        let cie = CIE::aarch64();
        assert_eq!(cie.version, 4);
        assert_eq!(cie.code_alignment_factor, 1);
        assert_eq!(cie.data_alignment_factor, -8);
        assert_eq!(cie.return_address_register, 30); // x30 = LR
        assert!(!cie.initial_instructions.is_empty());
        // Should start with DW_CFA_def_cfa
        assert_eq!(cie.initial_instructions[0], cfa_ops::DW_CFA_def_cfa);
    }

    #[test]
    fn test_cie_x86_64() {
        let cie = CIE::x86_64();
        assert_eq!(cie.version, 4);
        assert_eq!(cie.code_alignment_factor, 1);
        assert_eq!(cie.data_alignment_factor, -8);
        assert_eq!(cie.return_address_register, 16); // RIP
        assert!(!cie.initial_instructions.is_empty());
        assert_eq!(cie.initial_instructions[0], cfa_ops::DW_CFA_def_cfa);
    }

    #[test]
    fn test_cie_eh_frame_aarch64() {
        let cie = CIE::eh_frame_aarch64();
        assert_eq!(cie.version, 1);
        assert!(cie.augmentation.contains('z'));
        assert!(cie.augmentation.contains('R'));
        assert_eq!(
            cie.fde_pointer_encoding,
            ptr_encoding::DW_EH_PE_pcrel | ptr_encoding::DW_EH_PE_sdata4
        );
    }

    #[test]
    fn test_cie_eh_frame_x86_64() {
        let cie = CIE::eh_frame_x86_64();
        assert_eq!(cie.version, 1);
        assert!(cie.augmentation.contains('z'));
        assert!(cie.augmentation.contains('R'));
    }

    #[test]
    fn test_cie_has_augmentation() {
        let cie = CIE::new(1, "zPLR");
        assert!(cie.has_augmentation('z'));
        assert!(cie.has_augmentation('P'));
        assert!(cie.has_augmentation('L'));
        assert!(cie.has_augmentation('R'));
        assert!(!cie.has_augmentation('X'));
    }

    #[test]
    fn test_cie_default() {
        let cie = CIE::default();
        assert_eq!(cie.code_alignment_factor, 1);
        assert_eq!(cie.return_address_register, 16);
    }

    // ── FDE tests ─────────────────────────────────────────────────────

    #[test]
    fn test_fde_new() {
        let fde = FDE::new(0x20);
        assert_eq!(fde.cie_pointer, 0x20);
        assert_eq!(fde.initial_location, 0);
        assert_eq!(fde.address_range, 0);
        assert!(fde.instructions.is_empty());
    }

    #[test]
    fn test_fde_for_function() {
        let fde = FDE::for_function(0x10, 0x4000, 0x80);
        assert_eq!(fde.cie_pointer, 0x10);
        assert_eq!(fde.initial_location, 0x4000);
        assert_eq!(fde.address_range, 0x80);
    }

    // ── CFIBuilder tests ──────────────────────────────────────────────

    #[test]
    fn test_cfi_builder_new() {
        let b = CFIBuilder::new(false);
        assert!(!b.is_eh_frame);
        assert!(b.instructions.is_empty());
        assert!(b.cie.is_none());

        let b = CFIBuilder::new(true);
        assert!(b.is_eh_frame);
    }

    #[test]
    fn test_cfi_builder_with_cie() {
        let cie = CIE::aarch64();
        let b = CFIBuilder::with_cie(false, cie.clone());
        assert!(b.cie.is_some());
        assert_eq!(b.cie.as_ref().unwrap().version, 4);
    }

    #[test]
    fn test_create_cie_aarch64() {
        let cie = CFIBuilder::create_cie_aarch64();
        assert_eq!(cie.return_address_register, 30);
    }

    #[test]
    fn test_create_cie_x86_64() {
        let cie = CFIBuilder::create_cie_x86_64();
        assert_eq!(cie.return_address_register, 16);
    }

    #[test]
    fn test_def_cfa_positive_offset() {
        let mut b = CFIBuilder::new(false);
        b.def_cfa(31, 0);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_def_cfa);
    }

    #[test]
    fn test_def_cfa_negative_offset() {
        let mut b = CFIBuilder::new(false);
        b.def_cfa(7, -8);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_def_cfa_sf);
    }

    #[test]
    fn test_def_cfa_register() {
        let mut b = CFIBuilder::new(false);
        b.def_cfa_register(29);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_def_cfa_register);
    }

    #[test]
    fn test_def_cfa_offset() {
        let mut b = CFIBuilder::new(false);
        b.def_cfa_offset(16);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_def_cfa_offset);
    }

    #[test]
    fn test_def_cfa_offset_sf() {
        let mut b = CFIBuilder::new(false);
        b.def_cfa_offset_sf(-16);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_def_cfa_offset_sf);
    }

    #[test]
    fn test_offset_compact() {
        let mut b = CFIBuilder::new(false);
        b.offset(30, 2); // register 30 < 64 → compact form
                         // DW_CFA_offset | (30 & 0x3F) = 0x80 | 0x1E = 0x9E
        assert_eq!(b.instructions[0], 0x80 | 0x1E);
    }

    #[test]
    fn test_offset_extended() {
        let mut b = CFIBuilder::new(false);
        b.offset(64, 3); // register 64 >= 64 → extended form
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_offset_extended);
    }

    #[test]
    fn test_restore_compact() {
        let mut b = CFIBuilder::new(false);
        b.restore(29);
        // DW_CFA_restore | 29 = 0xC0 | 0x1D = 0xDD
        assert_eq!(b.instructions[0], 0xC0 | 0x1D);
    }

    #[test]
    fn test_restore_extended() {
        let mut b = CFIBuilder::new(false);
        b.restore(100);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_restore_extended);
    }

    #[test]
    fn test_save_register() {
        let mut b = CFIBuilder::new(false);
        b.save_register(16, 6);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_register);
    }

    #[test]
    fn test_same_value() {
        let mut b = CFIBuilder::new(false);
        b.same_value(3);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_same_value);
    }

    #[test]
    fn test_undefined() {
        let mut b = CFIBuilder::new(false);
        b.undefined(5);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_undefined);
    }

    #[test]
    fn test_remember_restore_state() {
        let mut b = CFIBuilder::new(false);
        b.remember_state();
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_remember_state);
        b.restore_state();
        assert_eq!(b.instructions[1], cfa_ops::DW_CFA_restore_state);
    }

    #[test]
    fn test_advance_loc_small() {
        let mut b = CFIBuilder::new(false);
        b.advance_loc(10);
        // DW_CFA_advance_loc | 10 = 0x40 | 0x0A = 0x4A
        assert_eq!(b.instructions[0], 0x40 | 0x0A);
    }

    #[test]
    fn test_advance_loc_medium() {
        let mut b = CFIBuilder::new(false);
        b.advance_loc(200);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_advance_loc1);
        assert_eq!(b.instructions[1], 200);
    }

    #[test]
    fn test_advance_loc_large() {
        let mut b = CFIBuilder::new(false);
        b.advance_loc(70000);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_advance_loc4);
    }

    #[test]
    fn test_set_loc_64() {
        let mut b = CFIBuilder::new(false);
        b.set_loc(0x400000, 8);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_set_loc);
        // 8 bytes of address follow
        assert_eq!(b.instructions.len(), 9);
    }

    #[test]
    fn test_set_loc_32() {
        let mut b = CFIBuilder::new(false);
        b.set_loc(0x400000, 4);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_set_loc);
        // 4 bytes of address follow
        assert_eq!(b.instructions.len(), 5);
    }

    #[test]
    fn test_nop() {
        let mut b = CFIBuilder::new(false);
        b.nop();
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_nop);
    }

    #[test]
    fn test_pad_to_alignment() {
        let mut b = CFIBuilder::new(false);
        let expected_padding = (8 - (b.instructions.len() + 1) % 8) % 8;
        b.pad_to_alignment(8);
        assert_eq!(b.instructions.len(), expected_padding);
        for &byte in &b.instructions {
            assert_eq!(byte, cfa_ops::DW_CFA_nop);
        }
    }

    #[test]
    fn test_emit_cie_debug_frame_aarch64() {
        let cie = CIE::aarch64();
        let b = CFIBuilder::new(false);
        let bytes = b.emit_cie(&cie, 8);
        assert!(!bytes.is_empty());
        // CIE_id should be 0xFFFFFFFF for .debug_frame
        let cie_id = u32::from_le_bytes(bytes[4..8].try_into().unwrap());
        assert_eq!(cie_id, 0xFFFFFFFF);
        // Version should be 4
        assert_eq!(bytes[8], 4);
    }

    #[test]
    fn test_emit_cie_eh_frame() {
        let cie = CIE::eh_frame_x86_64();
        let b = CFIBuilder::new(true);
        let bytes = b.emit_cie(&cie, 8);
        assert!(!bytes.is_empty());
        // CIE_id should be 0 for .eh_frame
        let cie_id = u32::from_le_bytes(bytes[4..8].try_into().unwrap());
        assert_eq!(cie_id, 0);
        // Version should be 1
        assert_eq!(bytes[8], 1);
        // The augmentation string should be present somewhere in the CIE
        let all_bytes = String::from_utf8_lossy(&bytes);
        assert!(
            all_bytes.contains("zR"),
            "Expected augmentation 'zR' in: {:?}",
            all_bytes
        );
    }

    #[test]
    fn test_emit_fde_debug_frame() {
        let cie = CIE::x86_64();
        let b = CFIBuilder::new(false);
        let fde = FDE::for_function(0x20, 0x1000, 0x50);
        let bytes = b.emit_fde(&fde, &cie, 8);
        assert!(!bytes.is_empty());
        // Check that address is encoded (8 bytes for 64-bit)
        // After length (4) + cie_pointer (4) = 8 bytes, we have initial_location
        let loc = u64::from_le_bytes(bytes[8..16].try_into().unwrap());
        assert_eq!(loc, 0x1000);
    }

    #[test]
    fn test_emit_fde_debug_frame32() {
        let cie = CIE::x86_64();
        let b = CFIBuilder::new(false);
        let fde = FDE::for_function(0x10, 0x4000, 0x30);
        let bytes = b.emit_fde(&fde, &cie, 4);
        assert!(!bytes.is_empty());
        // 32-bit addresses → 4 bytes each
        let loc = u32::from_le_bytes(bytes[8..12].try_into().unwrap());
        assert_eq!(loc, 0x4000);
    }

    #[test]
    fn test_cfa_ops_constants() {
        // Verify the high-bit encoding schemes
        assert_eq!(cfa_ops::DW_CFA_advance_loc, 0x40); // high 2 bits = 01
        assert_eq!(cfa_ops::DW_CFA_offset, 0x80); // high 2 bits = 10
        assert_eq!(cfa_ops::DW_CFA_restore, 0xC0); // high 2 bits = 11
        assert_eq!(cfa_ops::DW_CFA_nop, 0x00);
        assert_eq!(cfa_ops::DW_CFA_set_loc, 0x01);
        assert_eq!(cfa_ops::DW_CFA_advance_loc1, 0x02);
        assert_eq!(cfa_ops::DW_CFA_advance_loc2, 0x03);
        assert_eq!(cfa_ops::DW_CFA_advance_loc4, 0x04);
        assert_eq!(cfa_ops::DW_CFA_def_cfa, 0x0C);
        assert_eq!(cfa_ops::DW_CFA_def_cfa_offset, 0x0E);
        assert_eq!(cfa_ops::DW_CFA_lo_user, 0x1C);
        assert_eq!(cfa_ops::DW_CFA_hi_user, 0x3F);
    }

    // ── FrameEmitter tests ────────────────────────────────────────────

    #[test]
    fn test_frame_emitter_new() {
        let emitter = FrameEmitter::new(false, 8);
        assert!(!emitter.is_eh_frame);
        assert_eq!(emitter.address_size, 8);
        assert!(emitter.cies.is_empty());
        assert!(emitter.fdes.is_empty());

        let emitter = FrameEmitter::new(true, 4);
        assert!(emitter.is_eh_frame);
        assert_eq!(emitter.address_size, 4);
    }

    #[test]
    fn test_frame_emitter_add_cie() {
        let mut emitter = FrameEmitter::new(false, 8);
        let idx = emitter.add_cie(CIE::aarch64());
        assert_eq!(idx, 0);
        assert_eq!(emitter.cies.len(), 1);
    }

    #[test]
    fn test_frame_emitter_add_fde() {
        let mut emitter = FrameEmitter::new(false, 8);
        emitter.add_cie(CIE::x86_64());
        emitter.add_fde(FDE::for_function(0, 0x1000, 0x40));
        assert_eq!(emitter.fdes.len(), 1);
    }

    #[test]
    fn test_frame_emitter_emit_empty() {
        let mut emitter = FrameEmitter::new(false, 8);
        assert!(emitter.emit().is_none());
    }

    #[test]
    fn test_frame_emitter_emit_debug_frame() {
        let mut emitter = FrameEmitter::new(false, 8);
        emitter.add_cie(CIE::x86_64());
        emitter.add_fde(FDE::for_function(0, 0x4000, 0x80));
        let output = emitter.emit().unwrap();
        assert!(output.len() > 30);
        // Should start with CIE length > 0
        let cie_len = u32::from_le_bytes(output[0..4].try_into().unwrap());
        assert!(cie_len > 0);
        // CIE_id = 0xFFFFFFFF
        let cie_id = u32::from_le_bytes(output[4..8].try_into().unwrap());
        assert_eq!(cie_id, 0xFFFFFFFF);
    }

    #[test]
    fn test_frame_emitter_emit_eh_frame() {
        let mut emitter = FrameEmitter::new(true, 8);
        emitter.add_cie(CIE::eh_frame_x86_64());
        emitter.add_fde(FDE::for_function(0, 0x2000, 0x100));
        let output = emitter.emit().unwrap();
        assert!(output.len() > 20);
        // CIE_id = 0
        let cie_id = u32::from_le_bytes(output[4..8].try_into().unwrap());
        assert_eq!(cie_id, 0);
    }

    #[test]
    fn test_frame_emitter_multiple_cies() {
        let mut emitter = FrameEmitter::new(false, 8);
        emitter.add_cie(CIE::aarch64());
        emitter.add_cie(CIE::x86_64());
        emitter.add_fde(FDE::for_function(0, 0x1000, 0x30));
        emitter.add_fde(FDE::for_function(1, 0x2000, 0x40));
        let output = emitter.emit().unwrap();
        assert!(output.len() > 60);
    }

    #[test]
    fn test_prologue_aarch64() {
        let mut b = CFIBuilder::new(false);
        b.emit_aarch64_prologue_cfi();
        assert!(!b.instructions.is_empty());
        // Should contain offset instructions for FP(x29) and LR(x30)
        // DW_CFA_def_cfa_offset (0x0E)
        assert!(b.instructions.contains(&cfa_ops::DW_CFA_def_cfa_offset));
    }

    #[test]
    fn test_prologue_x86_64() {
        let mut b = CFIBuilder::new(false);
        b.emit_x86_64_prologue_cfi();
        assert!(!b.instructions.is_empty());
        // Should contain offset instruction for RBP(6)
        assert!(b.instructions.contains(&cfa_ops::DW_CFA_def_cfa_offset));
    }

    #[test]
    fn test_val_offset() {
        let mut b = CFIBuilder::new(false);
        b.val_offset(16, 2);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_val_offset);
    }

    #[test]
    fn test_val_offset_sf() {
        let mut b = CFIBuilder::new(false);
        b.val_offset_sf(16, -16);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_val_offset_sf);
    }

    #[test]
    fn test_val_expression() {
        let mut b = CFIBuilder::new(false);
        b.val_expression(16, &[0x50, 0x30]); // DW_OP_reg0, DW_OP_lit0
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_val_expression);
    }

    #[test]
    fn test_expression() {
        let mut b = CFIBuilder::new(false);
        b.expression(7, &[0x50]);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_expression);
    }

    #[test]
    fn test_offset_extended_sf() {
        let mut b = CFIBuilder::new(false);
        b.offset_extended_sf(30, -2);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_offset_extended_sf);
    }

    #[test]
    fn test_ptr_encoding_constants() {
        assert_eq!(ptr_encoding::DW_EH_PE_pcrel, 0x10);
        assert_eq!(ptr_encoding::DW_EH_PE_sdata4, 0x0B);
        assert_eq!(ptr_encoding::DW_EH_PE_absptr, 0x00);
        assert_eq!(ptr_encoding::DW_EH_PE_omit, 0xFF);
        assert_eq!(ptr_encoding::DW_EH_PE_indirect, 0x80);
    }

    #[test]
    fn test_emit_fde_with_instructions() {
        let cie = CIE::x86_64();
        let b = CFIBuilder::new(false);
        let mut fde = FDE::for_function(0, 0x1000, 0x50);
        let mut instr_builder = CFIBuilder::new(false);
        instr_builder.advance_loc(4);
        instr_builder.def_cfa_offset(32);
        fde.instructions = instr_builder.instructions;
        let bytes = b.emit_fde(&fde, &cie, 8);
        assert!(bytes.len() > 20);
        // Instructions should be at the end
        assert!(bytes.contains(&cfa_ops::DW_CFA_def_cfa_offset));
    }

    #[test]
    fn test_def_cfa_expression() {
        let mut b = CFIBuilder::new(false);
        b.def_cfa_expression(&[0x12, 0x34]);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_def_cfa_expression);
    }

    #[test]
    fn test_eh_frame_roundtrip_single_cie_fde() {
        let mut emitter = FrameEmitter::new(true, 8);
        let cie = CIE::eh_frame_x86_64();
        emitter.add_cie(cie.clone());
        emitter.add_fde(FDE::for_function(0, 0x400000, 0x200));
        let output = emitter.emit().unwrap();

        // Verify CIE section
        let cie_len = u32::from_le_bytes(output[0..4].try_into().unwrap());
        assert!(cie_len >= 16);
        let cie_end = 4 + cie_len as usize;

        // Verify FDE follows
        assert!(output.len() > cie_end + 4);

        // FDE length should be > 0
        let fde_len = u32::from_le_bytes(output[cie_end..cie_end + 4].try_into().unwrap());
        assert!(fde_len > 0);
    }

    #[test]
    fn test_debug_frame_roundtrip_single_cie_fde() {
        let mut emitter = FrameEmitter::new(false, 8);
        let cie = CIE::aarch64();
        emitter.add_cie(cie.clone());
        emitter.add_fde(FDE::for_function(0, 0x400000, 0x100));
        let output = emitter.emit().unwrap();

        // CIE_id must be 0xFFFFFFFF
        let cie_id = u32::from_le_bytes(output[4..8].try_into().unwrap());
        assert_eq!(cie_id, 0xFFFFFFFF);

        // Parse CIE length
        let cie_len = u32::from_le_bytes(output[0..4].try_into().unwrap());
        let cie_end = 4 + cie_len as usize;
        assert!(output.len() > cie_end);
    }

    #[test]
    fn test_advance_loc_boundary() {
        let mut b = CFIBuilder::new(false);
        // Exactly 63: should use compact form
        b.advance_loc(63);
        assert_eq!(b.instructions[0], 0x40 | 63);
        assert_eq!(b.instructions.len(), 1);

        let mut b = CFIBuilder::new(false);
        // 64: should use advance_loc1
        b.advance_loc(64);
        assert_eq!(b.instructions[0], cfa_ops::DW_CFA_advance_loc1);
        assert_eq!(b.instructions[1], 64);
    }
}