llvm-native-core 0.1.9

//! BPF Target Machine
//!
//! Defines the BPF64 target machine description, including register
//! information, calling convention, addressing modes, and target
//! feature flags. This is the top-level entry point for the BPF
//! backend, providing the interface through which the code generator
//! selects instructions and emits BPF bytecode.
//!
//! ## Register convention
//!
//! - r0: return value / exit code
//! - r1–r5: function arguments
//! - r6–r9: callee-saved registers
//! - r10: frame pointer (read-only)
//!
//! ## Target features
//!
//! - `alu32`: Support for 32-bit ALU operations
//! - `dwarfris`: DWARF register numbers for stack unwinding
//!
//! Clean-room implementation from the BPF ISA specification and
//! the Linux kernel documentation. No LLVM C++ source code was consulted.

use super::bpf_instr_info::{self, BpfInstrInfo, BpfOpcode};

/// BPF register class.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BpfRegClass {
    /// General-purpose 64-bit register.
    GPR,
    /// Frame pointer register (r10).
    FramePtr,
}

/// BPF register description.
#[derive(Debug, Clone)]
pub struct BpfRegister {
    pub index: u8,
    pub name: &'static str,
    pub class: BpfRegClass,
    pub is_callee_saved: bool,
}

/// Complete set of BPF registers.
fn bpf_registers() -> Vec<BpfRegister> {
    vec![
        BpfRegister {
            index: 0,
            name: "r0",
            class: BpfRegClass::GPR,
            is_callee_saved: false,
        },
        BpfRegister {
            index: 1,
            name: "r1",
            class: BpfRegClass::GPR,
            is_callee_saved: false,
        },
        BpfRegister {
            index: 2,
            name: "r2",
            class: BpfRegClass::GPR,
            is_callee_saved: false,
        },
        BpfRegister {
            index: 3,
            name: "r3",
            class: BpfRegClass::GPR,
            is_callee_saved: false,
        },
        BpfRegister {
            index: 4,
            name: "r4",
            class: BpfRegClass::GPR,
            is_callee_saved: false,
        },
        BpfRegister {
            index: 5,
            name: "r5",
            class: BpfRegClass::GPR,
            is_callee_saved: false,
        },
        BpfRegister {
            index: 6,
            name: "r6",
            class: BpfRegClass::GPR,
            is_callee_saved: true,
        },
        BpfRegister {
            index: 7,
            name: "r7",
            class: BpfRegClass::GPR,
            is_callee_saved: true,
        },
        BpfRegister {
            index: 8,
            name: "r8",
            class: BpfRegClass::GPR,
            is_callee_saved: true,
        },
        BpfRegister {
            index: 9,
            name: "r9",
            class: BpfRegClass::GPR,
            is_callee_saved: true,
        },
        BpfRegister {
            index: 10,
            name: "r10",
            class: BpfRegClass::FramePtr,
            is_callee_saved: true,
        },
    ]
}

/// BPF target feature flags.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BpfTargetFeatures {
    /// Support 32-bit ALU operations.
    pub has_alu32: bool,
    /// Support DWARF register numbers.
    pub has_dwarfris: bool,
    /// Disable the verifier's speculation barrier.
    pub no_speculation_barrier: bool,
}

impl Default for BpfTargetFeatures {
    fn default() -> Self {
        Self {
            has_alu32: true,
            has_dwarfris: true,
            no_speculation_barrier: false,
        }
    }
}

impl BpfTargetFeatures {
    /// Create features for the "generic" CPU (all features enabled).
    pub fn generic() -> Self {
        Self::default()
    }

    /// Create features for the "v1" CPU (basic BPF, no alu32).
    pub fn v1() -> Self {
        Self {
            has_alu32: false,
            has_dwarfris: false,
            no_speculation_barrier: true,
        }
    }

    /// Create features for the "v2" CPU.
    pub fn v2() -> Self {
        Self::default()
    }

    /// Create features for the "v3" CPU.
    pub fn v3() -> Self {
        Self {
            has_alu32: true,
            has_dwarfris: true,
            no_speculation_barrier: false,
        }
    }
}

// ============================================================================
// BPF target machine
// ============================================================================

/// The BPF target machine — provides the high-level interface for
/// BPF code generation.
pub struct BpfTargetMachine {
    /// Whether the target machine is initialized.
    pub initialized: bool,
    /// Target features.
    pub features: BpfTargetFeatures,
    /// Whether to emit big-endian BPF (default: little-endian).
    pub big_endian: bool,
    /// BPF registers.
    pub registers: Vec<BpfRegister>,
    /// BPF CPU name.
    pub cpu: String,
    /// BPF triple (e.g., "bpf" or "bpfeb").
    pub triple: String,
}

impl Default for BpfTargetMachine {
    fn default() -> Self {
        Self {
            initialized: false,
            features: BpfTargetFeatures::default(),
            big_endian: false,
            registers: bpf_registers(),
            cpu: String::from("generic"),
            triple: String::from("bpf"),
        }
    }
}

impl BpfTargetMachine {
    /// Create a new BPF target machine with default settings.
    pub fn new() -> Self {
        let mut tm = Self::default();
        tm.initialize();
        tm
    }

    /// Create a BPF target machine for a specific CPU.
    pub fn for_cpu(cpu: &str) -> Self {
        let mut tm = Self::default();
        match cpu {
            "v1" => tm.features = BpfTargetFeatures::v1(),
            "v2" => tm.features = BpfTargetFeatures::v2(),
            "v3" => tm.features = BpfTargetFeatures::v3(),
            _ => tm.features = BpfTargetFeatures::generic(),
        }
        tm.cpu = cpu.to_string();
        tm.initialize();
        tm
    }

    /// Create a BPF target machine for big-endian BPF.
    pub fn big_endian() -> Self {
        let mut tm = Self::new();
        tm.big_endian = true;
        tm.triple = String::from("bpfeb");
        tm
    }

    /// Initialize the target machine.
    fn initialize(&mut self) {
        self.initialized = true;
    }

    /// Get the register information by index.
    pub fn get_register(&self, index: u8) -> Option<&BpfRegister> {
        self.registers.get(index as usize)
    }

    /// Get the canonical register name.
    pub fn get_reg_name(&self, index: u8) -> &'static str {
        bpf_instr_info::reg_name(index)
    }

    /// Get the number of general-purpose registers.
    pub fn num_gprs(&self) -> usize {
        10 // r0–r9
    }

    /// Check if a register is callee-saved.
    pub fn is_callee_saved(&self, index: u8) -> bool {
        self.get_register(index)
            .map(|r| r.is_callee_saved)
            .unwrap_or(false)
    }

    /// Get the frame pointer register index.
    pub fn frame_pointer_reg() -> u8 {
        10
    }

    /// Get the stack pointer register index (same as frame pointer in BPF).
    pub fn stack_pointer_reg() -> u8 {
        10
    }

    /// Get the return value register index.
    pub fn return_reg() -> u8 {
        0
    }

    /// Get argument register indices.
    pub fn arg_regs() -> Vec<u8> {
        vec![1, 2, 3, 4, 5]
    }

    /// Check if a feature is enabled.
    pub fn has_feature(&self, feature: &str) -> bool {
        match feature {
            "alu32" => self.features.has_alu32,
            "dwarfris" => self.features.has_dwarfris,
            _ => false,
        }
    }

    /// Get the target triple string.
    pub fn get_triple(&self) -> &str {
        &self.triple
    }

    /// Get the CPU name.
    pub fn get_cpu(&self) -> &str {
        &self.cpu
    }

    /// Get the instruction alignment in bytes.
    pub fn instr_alignment() -> usize {
        8
    }

    /// Check whether this is a little-endian target.
    pub fn is_little_endian(&self) -> bool {
        !self.big_endian
    }

    /// Get the maximum number of instructions for a BPF program.
    /// (Linux kernel default: 1,000,000 instructions).
    pub fn max_instructions() -> usize {
        1_000_000
    }

    /// Get the address space (used for pointer size).
    pub fn pointer_size() -> usize {
        8
    }
}

// ============================================================================
// Calling convention helpers
// ============================================================================

/// BPF calling convention information.
pub struct BpfCallingConvention;

impl BpfCallingConvention {
    /// Get the register used for the nth function argument.
    pub fn arg_reg(n: usize) -> Option<u8> {
        match n {
            0 => Some(1),
            1 => Some(2),
            2 => Some(3),
            3 => Some(4),
            4 => Some(5),
            _ => None,
        }
    }

    /// Get the number of argument registers.
    pub fn num_arg_regs() -> usize {
        5
    }

    /// Get the callee-saved register indices.
    pub fn callee_saved_regs() -> Vec<u8> {
        vec![6, 7, 8, 9]
    }

    /// Generate the prologue for a BPF function.
    /// Stack frame layout:
    /// ```
    /// [local variables]
    /// [callee-saved regs] ← r10 - n*8
    /// ```
    pub fn emit_prologue(instrs: &mut Vec<super::bpf_mc_encoder::BpfInstr>) {
        // In BPF, r10 is always the frame pointer.
        // Prologue typically allocates stack space via r10 subtraction
        // and saves callee-saved registers.
        // For the minimal prologue, nothing is needed if there are no
        // callee-saved registers to save.

        // If stack space is needed: mov rN, r10; sub r10, N
        // This is handled by the instruction selector based on stack usage.
        let _ = instrs;
    }

    /// Generate the epilogue for a BPF function.
    /// Restores callee-saved registers and returns.
    pub fn emit_epilogue(instrs: &mut Vec<super::bpf_mc_encoder::BpfInstr>) {
        // Epilogue: restore callee-saved registers and exit.
        // This is handled by the instruction selector.
        let _ = instrs;
    }
}

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

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

    #[test]
    fn test_new_target_machine() {
        let tm = BpfTargetMachine::new();
        assert!(tm.initialized);
        assert_eq!(tm.triple, "bpf");
        assert!(!tm.big_endian);
    }

    #[test]
    fn test_for_cpu_v1() {
        let tm = BpfTargetMachine::for_cpu("v1");
        assert_eq!(tm.cpu, "v1");
        assert!(!tm.features.has_alu32);
    }

    #[test]
    fn test_for_cpu_v2() {
        let tm = BpfTargetMachine::for_cpu("v2");
        assert_eq!(tm.cpu, "v2");
        assert!(tm.features.has_alu32);
    }

    #[test]
    fn test_for_cpu_unknown() {
        let tm = BpfTargetMachine::for_cpu("unknown_cpu");
        assert!(tm.features.has_alu32); // defaults to generic with alu32
    }

    #[test]
    fn test_big_endian() {
        let tm = BpfTargetMachine::big_endian();
        assert!(tm.big_endian);
        assert_eq!(tm.triple, "bpfeb");
    }

    #[test]
    fn test_get_register() {
        let tm = BpfTargetMachine::new();
        let reg = tm.get_register(0).expect("r0 should exist");
        assert_eq!(reg.name, "r0");
        assert!(!reg.is_callee_saved);

        let r10 = tm.get_register(10).expect("r10 should exist");
        assert_eq!(r10.name, "r10");
        assert!(r10.is_callee_saved);
    }

    #[test]
    fn test_get_register_out_of_bounds() {
        let tm = BpfTargetMachine::new();
        assert!(tm.get_register(255).is_none());
    }

    #[test]
    fn test_is_callee_saved() {
        let tm = BpfTargetMachine::new();
        assert!(!tm.is_callee_saved(0));
        assert!(!tm.is_callee_saved(5));
        assert!(tm.is_callee_saved(6));
        assert!(tm.is_callee_saved(9));
        assert!(tm.is_callee_saved(10));
    }

    #[test]
    fn test_return_reg() {
        assert_eq!(BpfTargetMachine::return_reg(), 0);
    }

    #[test]
    fn test_arg_regs() {
        let regs = BpfTargetMachine::arg_regs();
        assert_eq!(regs, vec![1, 2, 3, 4, 5]);
    }

    #[test]
    fn test_frame_pointer_reg() {
        assert_eq!(BpfTargetMachine::frame_pointer_reg(), 10);
    }

    #[test]
    fn test_stack_pointer_reg() {
        assert_eq!(BpfTargetMachine::stack_pointer_reg(), 10);
    }

    #[test]
    fn test_has_feature() {
        let tm_v1 = BpfTargetMachine::for_cpu("v1");
        assert!(!tm_v1.has_feature("alu32"));

        let tm = BpfTargetMachine::new();
        assert!(tm.has_feature("alu32"));
        assert!(tm.has_feature("dwarfris"));
    }

    #[test]
    fn test_ptr_size() {
        assert_eq!(BpfTargetMachine::pointer_size(), 8);
    }

    #[test]
    fn test_instr_alignment() {
        assert_eq!(BpfTargetMachine::instr_alignment(), 8);
    }

    #[test]
    fn test_max_instructions() {
        assert!(BpfTargetMachine::max_instructions() > 0);
    }

    #[test]
    fn test_calling_conv_arg_reg() {
        assert_eq!(BpfCallingConvention::arg_reg(0), Some(1));
        assert_eq!(BpfCallingConvention::arg_reg(4), Some(5));
        assert_eq!(BpfCallingConvention::arg_reg(5), None);
    }

    #[test]
    fn test_calling_conv_callee_saved() {
        assert_eq!(BpfCallingConvention::callee_saved_regs(), vec![6, 7, 8, 9]);
    }

    #[test]
    fn test_emit_prologue_epilogue_no_panic() {
        let mut instrs: Vec<super::super::bpf_mc_encoder::BpfInstr> = Vec::new();
        BpfCallingConvention::emit_prologue(&mut instrs);
        BpfCallingConvention::emit_epilogue(&mut instrs);
    }

    #[test]
    fn test_target_features_default() {
        let features = BpfTargetFeatures::default();
        assert!(features.has_alu32);
        assert!(features.has_dwarfris);
    }

    #[test]
    fn test_num_gprs() {
        let tm = BpfTargetMachine::new();
        assert_eq!(tm.num_gprs(), 10);
    }

    #[test]
    fn test_triple_is_little_endian() {
        let tm = BpfTargetMachine::new();
        assert!(tm.is_little_endian());
        assert_eq!(tm.get_triple(), "bpf");
    }

    #[test]
    fn test_get_cpu() {
        let tm = BpfTargetMachine::for_cpu("v3");
        assert_eq!(tm.get_cpu(), "v3");
    }
}