veridian_kernel/arch/x86_64/

apic.rs

//! Local APIC and I/O APIC support for x86_64.
//!
//! Provides initialization and control of the Local APIC (interrupt delivery to
//! the local CPU) and I/O APIC (external interrupt routing). This module is
//! additive to the existing PIC (8259) setup -- the PIC remains as a fallback
//! while the APIC handles advanced interrupt routing.
//!
//! The Local APIC is memory-mapped at 0xFEE0_0000 (identity-mapped by the
//! bootloader). The I/O APIC is at 0xFEC0_0000 with indirect register access
//! via IOREGSEL/IOWIN.
//!
//! Register constants and hardware API methods define the complete Local APIC
//! and I/O APIC register set per the Intel SDM. Unused items are retained for
//! hardware reference completeness.
#![allow(dead_code)]

use core::{
    ptr,
    sync::atomic::{AtomicBool, Ordering},
};

use spin::Mutex;

use crate::error::{KernelError, KernelResult};

// ---------------------------------------------------------------------------
// MSR addresses
// ---------------------------------------------------------------------------

/// IA32_APIC_BASE MSR address. Contains the APIC base physical address and
/// enable/BSP flags.
const IA32_APIC_BASE_MSR: u32 = 0x1B;

/// Bit 11 of IA32_APIC_BASE: global APIC enable.
const IA32_APIC_BASE_ENABLE: u64 = 1 << 11;

// ---------------------------------------------------------------------------
// Local APIC register offsets (byte offsets from APIC base)
// ---------------------------------------------------------------------------

/// Local APIC ID register.
const LAPIC_ID: u32 = 0x020;
/// Local APIC Version register.
const LAPIC_VERSION: u32 = 0x030;
/// Task Priority Register -- controls interrupt priority filtering.
const LAPIC_TPR: u32 = 0x080;
/// End-Of-Interrupt register -- write 0 to signal interrupt completion.
const LAPIC_EOI: u32 = 0x0B0;
/// Spurious Interrupt Vector register -- also contains the software enable bit.
const LAPIC_SVR: u32 = 0x0F0;
// Hardware register definitions -- retained for completeness per Intel SDM
const LAPIC_ISR_BASE: u32 = 0x100;
const LAPIC_TMR_BASE: u32 = 0x180;
const LAPIC_IRR_BASE: u32 = 0x200;
const LAPIC_ESR: u32 = 0x280;
/// Interrupt Command Register (low 32 bits).
const LAPIC_ICR_LOW: u32 = 0x300;
/// Interrupt Command Register (high 32 bits -- destination field).
const LAPIC_ICR_HIGH: u32 = 0x310;
/// LVT Timer register.
const LAPIC_LVT_TIMER: u32 = 0x320;
/// LVT LINT0 register.
const LAPIC_LVT_LINT0: u32 = 0x350;
/// LVT LINT1 register.
const LAPIC_LVT_LINT1: u32 = 0x360;
/// LVT Error register.
const LAPIC_LVT_ERROR: u32 = 0x370;
/// Timer Initial Count register.
const LAPIC_TIMER_INIT_COUNT: u32 = 0x380;
/// Timer Current Count register (read-only).
const LAPIC_TIMER_CUR_COUNT: u32 = 0x390;
/// Timer Divide Configuration register.
const LAPIC_TIMER_DIV: u32 = 0x3E0;

/// LVT mask bit (bit 16) -- when set, the interrupt is masked.
const LVT_MASK: u32 = 1 << 16;

/// Spurious Vector Register software enable bit (bit 8).
const SVR_ENABLE: u32 = 1 << 8;

/// Default spurious interrupt vector number (0xFF by convention).
const SPURIOUS_VECTOR: u8 = 0xFF;

/// APIC timer interrupt vector (dedicated, separate from PIC timer at 32).
pub const APIC_TIMER_VECTOR: u8 = 48;

/// TLB shootdown IPI vector -- sent to remote CPUs to flush stale TLB entries.
pub const TLB_SHOOTDOWN_VECTOR: u8 = 49;

/// Scheduler wake IPI vector -- sent to wake a remote CPU from idle to run a
/// task.
pub const SCHED_WAKE_VECTOR: u8 = 50;

// ---------------------------------------------------------------------------
// LVT Timer mode bits
// ---------------------------------------------------------------------------

// Hardware register definitions -- retained for completeness per Intel SDM
const TIMER_MODE_ONESHOT: u32 = 0b00 << 17;
/// Periodic timer mode (bits 18:17 = 01).
const TIMER_MODE_PERIODIC: u32 = 0b01 << 17;

// ---------------------------------------------------------------------------
// I/O APIC
// ---------------------------------------------------------------------------

/// Default I/O APIC MMIO base address (QEMU virt machine).
const IOAPIC_BASE: usize = 0xFEC0_0000;

/// I/O APIC Register Select (write the register index here).
const IOREGSEL: u32 = 0x00;
/// I/O APIC Window (read/write the selected register through here).
const IOWIN: u32 = 0x10;

// Hardware register definition -- retained for completeness per Intel SDM
const IOAPIC_REG_ID: u32 = 0x00;
/// I/O APIC Version register.
const IOAPIC_REG_VER: u32 = 0x01;

/// I/O APIC redirection table entry base (each entry uses two 32-bit
/// registers).
const IOAPIC_REDTBL_BASE: u32 = 0x10;

// ---------------------------------------------------------------------------
// Redirection table entry bitfields
// ---------------------------------------------------------------------------

/// Redirection table entry -- represents a 64-bit I/O APIC routing entry.
///
/// Layout:
/// - Bits  7:0  -- Interrupt vector
/// - Bits 10:8  -- Delivery mode (000=Fixed, 001=LowestPri, 010=SMI, 100=NMI,
///   101=INIT, 111=ExtINT)
/// - Bit  11    -- Destination mode (0=Physical, 1=Logical)
/// - Bit  12    -- Delivery status (read-only: 0=idle, 1=pending)
/// - Bit  13    -- Pin polarity (0=active high, 1=active low)
/// - Bit  14    -- Remote IRR (read-only, level-triggered)
/// - Bit  15    -- Trigger mode (0=edge, 1=level)
/// - Bit  16    -- Mask (1=masked)
/// - Bits 63:56 -- Destination APIC ID (physical mode)
#[derive(Debug, Clone, Copy)]
pub struct RedirectionEntry {
    raw: u64,
}

impl RedirectionEntry {
    /// Create a new masked redirection entry with the given vector.
    pub const fn new(vector: u8) -> Self {
        Self {
            raw: (vector as u64) | ((1u64) << 16), // masked by default
        }
    }

    /// Set the interrupt vector (bits 7:0).
    pub fn set_vector(&mut self, vector: u8) {
        self.raw = (self.raw & !0xFF) | (vector as u64);
    }

    /// Get the interrupt vector.
    pub fn vector(&self) -> u8 {
        (self.raw & 0xFF) as u8
    }

    /// Set delivery mode (bits 10:8).
    /// 0=Fixed, 1=LowestPriority, 2=SMI, 4=NMI, 5=INIT, 7=ExtINT.
    pub fn set_delivery_mode(&mut self, mode: u8) {
        self.raw = (self.raw & !(0b111 << 8)) | (((mode & 0b111) as u64) << 8);
    }

    /// Set destination mode (bit 11). 0=Physical, 1=Logical.
    pub fn set_dest_mode_logical(&mut self, logical: bool) {
        if logical {
            self.raw |= 1 << 11;
        } else {
            self.raw &= !(1 << 11);
        }
    }

    /// Set pin polarity (bit 13). false=active high, true=active low.
    pub fn set_active_low(&mut self, active_low: bool) {
        if active_low {
            self.raw |= 1 << 13;
        } else {
            self.raw &= !(1 << 13);
        }
    }

    /// Set trigger mode (bit 15). false=edge, true=level.
    pub fn set_level_triggered(&mut self, level: bool) {
        if level {
            self.raw |= 1 << 15;
        } else {
            self.raw &= !(1 << 15);
        }
    }

    /// Set mask bit (bit 16). true=masked.
    pub fn set_masked(&mut self, masked: bool) {
        if masked {
            self.raw |= 1 << 16;
        } else {
            self.raw &= !(1 << 16);
        }
    }

    /// Check if the entry is masked.
    pub fn is_masked(&self) -> bool {
        self.raw & (1 << 16) != 0
    }

    /// Set destination APIC ID (bits 63:56).
    pub fn set_destination(&mut self, dest: u8) {
        self.raw = (self.raw & !(0xFFu64 << 56)) | ((dest as u64) << 56);
    }

    /// Get the low 32 bits of the entry.
    pub fn low(&self) -> u32 {
        self.raw as u32
    }

    /// Get the high 32 bits of the entry.
    pub fn high(&self) -> u32 {
        (self.raw >> 32) as u32
    }

    /// Construct from low and high 32-bit halves.
    pub fn from_parts(low: u32, high: u32) -> Self {
        Self {
            raw: (low as u64) | ((high as u64) << 32),
        }
    }
}

// ---------------------------------------------------------------------------
// Local APIC
// ---------------------------------------------------------------------------

/// Local APIC controller.
///
/// Wraps the memory-mapped register file for the per-CPU Local APIC. All
/// register accesses use volatile reads/writes to prevent compiler reordering.
pub struct LocalApic {
    /// Virtual address of the APIC MMIO base (identity-mapped at 0xFEE0_0000).
    base: usize,
}

impl LocalApic {
    /// Create a new `LocalApic` handle with the given MMIO base address.
    fn new(base: usize) -> Self {
        Self { base }
    }

    /// Read a 32-bit Local APIC register at the given byte offset.
    fn read(&self, offset: u32) -> u32 {
        let addr = self.base + offset as usize;
        // SAFETY: The address `self.base + offset` points to a well-known Local
        // APIC MMIO register. The APIC region at 0xFEE0_0000 is identity-mapped
        // by the bootloader and reserved in the frame allocator. Volatile read
        // ensures the compiler does not elide or reorder the access.
        unsafe { ptr::read_volatile(addr as *const u32) }
    }

    /// Write a 32-bit value to a Local APIC register at the given byte offset.
    fn write(&self, offset: u32, value: u32) {
        let addr = self.base + offset as usize;
        // SAFETY: Same as `read` -- the address is a valid APIC MMIO register.
        // Volatile write ensures the hardware sees the store in program order.
        unsafe { ptr::write_volatile(addr as *mut u32, value) }
    }

    /// Read the Local APIC ID (bits 31:24 of the ID register).
    pub fn read_id(&self) -> u8 {
        ((self.read(LAPIC_ID) >> 24) & 0xFF) as u8
    }

    /// Read the Local APIC version register.
    pub fn read_version(&self) -> u32 {
        self.read(LAPIC_VERSION)
    }

    /// Enable the Local APIC by setting the software-enable bit in the
    /// Spurious Interrupt Vector register and configuring the spurious vector.
    fn enable(&self) {
        // Set spurious vector to 0xFF and set the software-enable bit (bit 8).
        self.write(LAPIC_SVR, SVR_ENABLE | SPURIOUS_VECTOR as u32);
    }

    /// Mask all Local Vector Table entries (Timer, LINT0, LINT1, Error) to
    /// prevent unexpected interrupts before they are explicitly configured.
    fn mask_all_lvt(&self) {
        self.write(LAPIC_LVT_TIMER, LVT_MASK);
        self.write(LAPIC_LVT_LINT0, LVT_MASK);
        self.write(LAPIC_LVT_LINT1, LVT_MASK);
        self.write(LAPIC_LVT_ERROR, LVT_MASK);
    }

    /// Send an End-Of-Interrupt signal. Must be called at the end of every
    /// Local APIC interrupt handler.
    pub fn send_eoi(&self) {
        self.write(LAPIC_EOI, 0);
    }

    /// Set the Task Priority Register to allow all interrupts (priority 0).
    fn set_task_priority(&self, priority: u8) {
        self.write(LAPIC_TPR, priority as u32);
    }

    /// Configure the APIC timer for periodic interrupts.
    ///
    /// - `vector`: IDT vector number for the timer interrupt.
    /// - `divide`: Timer divisor encoded as the Divide Configuration Register
    ///   value (e.g., 0x03 = divide by 16, 0x0B = divide by 1).
    /// - `initial_count`: Initial countdown value. The timer fires when it
    ///   reaches zero and reloads automatically in periodic mode.
    pub fn setup_timer(&self, vector: u8, divide: u8, initial_count: u32) {
        // Stop the timer first.
        self.write(LAPIC_TIMER_INIT_COUNT, 0);

        // Set the divide configuration.
        self.write(LAPIC_TIMER_DIV, divide as u32);

        // Configure LVT Timer: periodic mode, unmasked, with the given vector.
        self.write(LAPIC_LVT_TIMER, TIMER_MODE_PERIODIC | vector as u32);

        // Setting the initial count starts the timer.
        self.write(LAPIC_TIMER_INIT_COUNT, initial_count);
    }

    /// Stop the APIC timer by zeroing the initial count and masking the LVT
    /// Timer entry.
    pub fn stop_timer(&self) {
        self.write(LAPIC_TIMER_INIT_COUNT, 0);
        self.write(LAPIC_LVT_TIMER, LVT_MASK);
    }

    /// Read the current timer count (counts down from the initial value).
    pub fn read_timer_count(&self) -> u32 {
        self.read(LAPIC_TIMER_CUR_COUNT)
    }

    /// Write the Interrupt Command Register to send an IPI.
    ///
    /// - `dest`: Destination APIC ID.
    /// - `vector`: Interrupt vector.
    pub fn send_ipi(&self, dest: u8, vector: u8) {
        // Write high dword first (destination in bits 31:24).
        self.write(LAPIC_ICR_HIGH, (dest as u32) << 24);
        // Write low dword (vector + delivery mode Fixed). Writing ICR low
        // triggers the IPI.
        self.write(LAPIC_ICR_LOW, vector as u32);
    }

    /// Send an INIT IPI to a target CPU (used in AP startup sequence).
    pub fn send_init_ipi(&self, dest: u8) {
        self.write(LAPIC_ICR_HIGH, (dest as u32) << 24);
        // INIT: delivery mode = 0b101 (INIT), level assert
        self.write(LAPIC_ICR_LOW, 0x00004500);
    }

    /// Send a Startup IPI (SIPI) to a target CPU.
    ///
    /// `startup_page` is the physical page number (e.g., 0x08 for 0x8000).
    pub fn send_startup_ipi(&self, dest: u8, startup_page: u8) {
        self.write(LAPIC_ICR_HIGH, (dest as u32) << 24);
        // SIPI: delivery mode = 0b110 (StartUp), vector = page number
        self.write(LAPIC_ICR_LOW, 0x00004600 | startup_page as u32);
    }

    /// Broadcast IPI to all CPUs except self.
    pub fn send_ipi_all_excluding_self(&self, vector: u8) {
        // Shorthand = 11 (all excluding self), no destination field needed.
        self.write(
            LAPIC_ICR_LOW,
            0x000C0000 | vector as u32, // shorthand=11, dest_mode=physical, delivery=fixed
        );
    }
}

// ---------------------------------------------------------------------------
// I/O APIC
// ---------------------------------------------------------------------------

/// I/O APIC controller.
///
/// The I/O APIC uses indirect register access: write the register index to
/// IOREGSEL, then read/write the value through IOWIN.
pub struct IoApic {
    /// Virtual address of the I/O APIC MMIO base (identity-mapped at
    /// 0xFEC0_0000).
    base: usize,
}

impl IoApic {
    /// Create a new `IoApic` handle with the given MMIO base address.
    fn new(base: usize) -> Self {
        Self { base }
    }

    /// Read a 32-bit I/O APIC register.
    pub fn read_register(&self, reg: u32) -> u32 {
        // SAFETY: IOREGSEL at base+0x00 and IOWIN at base+0x10 are the I/O
        // APIC's indirect register access ports. The base address 0xFEC0_0000
        // is identity-mapped by the bootloader. Volatile writes ensure the
        // register select is visible to hardware before the window read.
        unsafe {
            ptr::write_volatile((self.base + IOREGSEL as usize) as *mut u32, reg);
            ptr::read_volatile((self.base + IOWIN as usize) as *const u32)
        }
    }

    /// Write a 32-bit value to an I/O APIC register.
    pub fn write_register(&self, reg: u32, value: u32) {
        // SAFETY: Same as `read_register` -- indirect MMIO access through
        // IOREGSEL/IOWIN. The volatile operations guarantee ordering.
        unsafe {
            ptr::write_volatile((self.base + IOREGSEL as usize) as *mut u32, reg);
            ptr::write_volatile((self.base + IOWIN as usize) as *mut u32, value);
        }
    }

    /// Read the maximum number of redirection entries supported by this I/O
    /// APIC (from bits 23:16 of the version register, plus one).
    pub fn max_redirection_entries(&self) -> u8 {
        let ver = self.read_register(IOAPIC_REG_VER);
        (((ver >> 16) & 0xFF) + 1) as u8
    }

    /// Read a full 64-bit redirection table entry for the given IRQ.
    fn read_redirection(&self, irq: u8) -> RedirectionEntry {
        let reg_base = IOAPIC_REDTBL_BASE + (irq as u32) * 2;
        let low = self.read_register(reg_base);
        let high = self.read_register(reg_base + 1);
        RedirectionEntry::from_parts(low, high)
    }

    /// Write a full 64-bit redirection table entry for the given IRQ.
    fn write_redirection(&self, irq: u8, entry: RedirectionEntry) {
        let reg_base = IOAPIC_REDTBL_BASE + (irq as u32) * 2;
        // Write high dword first to avoid a transient unmasked state if the
        // low dword unmasks the entry.
        self.write_register(reg_base + 1, entry.high());
        self.write_register(reg_base, entry.low());
    }

    /// Route an external IRQ to a specific interrupt vector and destination
    /// APIC ID with edge-triggered, active-high, fixed delivery mode.
    pub fn set_irq_route(&self, irq: u8, vector: u8, dest: u8) {
        let mut entry = RedirectionEntry::new(vector);
        entry.set_destination(dest);
        entry.set_masked(false);
        self.write_redirection(irq, entry);
    }

    /// Mask an IRQ in the I/O APIC redirection table.
    pub fn mask_irq(&self, irq: u8) {
        let mut entry = self.read_redirection(irq);
        entry.set_masked(true);
        self.write_redirection(irq, entry);
    }

    /// Unmask an IRQ in the I/O APIC redirection table.
    pub fn unmask_irq(&self, irq: u8) {
        let mut entry = self.read_redirection(irq);
        entry.set_masked(false);
        self.write_redirection(irq, entry);
    }

    /// Mask all redirection entries.
    fn mask_all(&self) {
        let max = self.max_redirection_entries();
        for irq in 0..max {
            self.mask_irq(irq);
        }
    }
}

// ---------------------------------------------------------------------------
// Global APIC state (no static mut -- uses spin::Mutex)
// ---------------------------------------------------------------------------

/// Combined Local APIC + I/O APIC state, protected by a spinlock.
struct ApicState {
    local_apic: LocalApic,
    io_apic: IoApic,
}

// SAFETY: ApicState contains only raw pointer-like fields (usize base
// addresses) and is always accessed under a spinlock, so there are no data
// races.
unsafe impl Send for ApicState {}

/// Global APIC state. Initialized once by `init()`.
static APIC_STATE: Mutex<Option<ApicState>> = Mutex::new(None);

/// Flag indicating whether the APIC subsystem has been initialized.
static APIC_INITIALIZED: AtomicBool = AtomicBool::new(false);

// ---------------------------------------------------------------------------
// MSR helpers (delegated to arch::x86_64::msr module)
// ---------------------------------------------------------------------------

use super::msr::{phys_to_virt, rdmsr, wrmsr};

/// Initialize the Local APIC and I/O APIC.
///
/// This function:
/// 1. Reads the APIC base address from the IA32_APIC_BASE MSR.
/// 2. Ensures the global APIC enable bit is set in the MSR.
/// 3. Translates physical MMIO addresses to virtual using the bootloader's
///    physical memory offset.
/// 4. Initializes the Local APIC (software enable, mask all LVTs, set TPR=0).
/// 5. Initializes the I/O APIC (mask all redirection entries).
///
/// Must be called after GDT/IDT initialization but before interrupts are
/// enabled. Safe to call exactly once; subsequent calls return
/// `AlreadyExists`.
pub fn init() -> KernelResult<()> {
    if APIC_INITIALIZED.load(Ordering::Acquire) {
        return Err(KernelError::AlreadyExists {
            resource: "APIC",
            id: 0,
        });
    }

    // Read APIC base from MSR.
    let apic_base_msr = rdmsr(IA32_APIC_BASE_MSR);
    let apic_base_phys = (apic_base_msr & 0xFFFF_F000) as usize;

    println!(
        "[APIC] IA32_APIC_BASE MSR = {:#x}, physical base = {:#x}",
        apic_base_msr, apic_base_phys
    );

    // Translate physical APIC addresses to virtual addresses.
    // The bootloader maps all physical memory at a dynamic offset; MMIO
    // regions are NOT identity-mapped in a higher-half kernel.
    let lapic_virt = phys_to_virt(apic_base_phys).ok_or(KernelError::NotInitialized {
        subsystem: "physical memory mapping (APIC)",
    })?;
    let ioapic_virt = phys_to_virt(IOAPIC_BASE).ok_or(KernelError::NotInitialized {
        subsystem: "physical memory mapping (I/O APIC)",
    })?;

    println!(
        "[APIC] Virtual addresses: LAPIC={:#x}, IOAPIC={:#x}",
        lapic_virt, ioapic_virt
    );

    // Ensure the global enable bit is set.
    if apic_base_msr & IA32_APIC_BASE_ENABLE == 0 {
        println!("[APIC] Global APIC enable bit not set, enabling...");
        wrmsr(IA32_APIC_BASE_MSR, apic_base_msr | IA32_APIC_BASE_ENABLE);
    }

    // --- Local APIC initialization ---
    let lapic = LocalApic::new(lapic_virt);

    // Mask all LVT entries before enabling to prevent spurious interrupts.
    lapic.mask_all_lvt();

    // Enable the Local APIC via the Spurious Vector Register.
    lapic.enable();

    // Allow all interrupt priorities.
    lapic.set_task_priority(0);

    let apic_id = lapic.read_id();
    println!(
        "[APIC] Local APIC enabled (ID={}, SVR={:#x})",
        apic_id,
        lapic.read(LAPIC_SVR)
    );

    // --- I/O APIC initialization ---
    let ioapic = IoApic::new(ioapic_virt);

    // Mask all I/O APIC redirection entries by default.
    ioapic.mask_all();

    let max_irqs = ioapic.max_redirection_entries();
    println!(
        "[APIC] I/O APIC initialized at {:#x} ({} IRQ lines)",
        ioapic_virt, max_irqs
    );

    // Store global state.
    let mut state = APIC_STATE.lock();
    *state = Some(ApicState {
        local_apic: lapic,
        io_apic: ioapic,
    });
    APIC_INITIALIZED.store(true, Ordering::Release);

    println!("[APIC] APIC subsystem initialized successfully");
    Ok(())
}

/// Check whether the APIC subsystem has been initialized.
pub fn is_initialized() -> bool {
    APIC_INITIALIZED.load(Ordering::Acquire)
}

/// Send an End-Of-Interrupt to the Local APIC.
///
/// Must be called at the end of every APIC-sourced interrupt handler.
pub fn send_eoi() {
    let state = APIC_STATE.lock();
    if let Some(ref s) = *state {
        s.local_apic.send_eoi();
    }
}

/// Read the Local APIC ID of the current CPU.
pub fn read_id() -> Option<u8> {
    let state = APIC_STATE.lock();
    state.as_ref().map(|s| s.local_apic.read_id())
}

/// Configure the Local APIC timer for periodic interrupts.
///
/// - `vector`: IDT vector number (e.g., 32 for the timer).
/// - `divide`: Divide configuration register value:
///   - `0x00` = divide by 2
///   - `0x01` = divide by 4
///   - `0x02` = divide by 8
///   - `0x03` = divide by 16
///   - `0x08` = divide by 32
///   - `0x09` = divide by 64
///   - `0x0A` = divide by 128
///   - `0x0B` = divide by 1
/// - `initial_count`: Initial countdown value.
pub fn setup_timer(vector: u8, divide: u8, initial_count: u32) -> KernelResult<()> {
    let state = APIC_STATE.lock();
    match state.as_ref() {
        Some(s) => {
            s.local_apic.setup_timer(vector, divide, initial_count);
            println!(
                "[APIC] Timer configured: vector={}, divide={:#x}, count={}",
                vector, divide, initial_count
            );
            Ok(())
        }
        None => Err(KernelError::NotInitialized { subsystem: "APIC" }),
    }
}

/// Stop the Local APIC timer.
pub fn stop_timer() -> KernelResult<()> {
    let state = APIC_STATE.lock();
    match state.as_ref() {
        Some(s) => {
            s.local_apic.stop_timer();
            Ok(())
        }
        None => Err(KernelError::NotInitialized { subsystem: "APIC" }),
    }
}

/// Route an external IRQ through the I/O APIC to a specific interrupt vector
/// and destination CPU.
///
/// - `irq`: I/O APIC input pin (0-23 typically).
/// - `vector`: IDT vector number.
/// - `dest`: Destination Local APIC ID.
pub fn set_irq_route(irq: u8, vector: u8, dest: u8) -> KernelResult<()> {
    let state = APIC_STATE.lock();
    match state.as_ref() {
        Some(s) => {
            s.io_apic.set_irq_route(irq, vector, dest);
            Ok(())
        }
        None => Err(KernelError::NotInitialized { subsystem: "APIC" }),
    }
}

/// Mask an IRQ in the I/O APIC.
pub fn mask_irq(irq: u8) -> KernelResult<()> {
    let state = APIC_STATE.lock();
    match state.as_ref() {
        Some(s) => {
            s.io_apic.mask_irq(irq);
            Ok(())
        }
        None => Err(KernelError::NotInitialized { subsystem: "APIC" }),
    }
}

/// Unmask an IRQ in the I/O APIC.
pub fn unmask_irq(irq: u8) -> KernelResult<()> {
    let state = APIC_STATE.lock();
    match state.as_ref() {
        Some(s) => {
            s.io_apic.unmask_irq(irq);
            Ok(())
        }
        None => Err(KernelError::NotInitialized { subsystem: "APIC" }),
    }
}

/// Send an Inter-Processor Interrupt via the Local APIC.
///
/// - `dest`: Destination APIC ID.
/// - `vector`: Interrupt vector.
pub fn send_ipi(dest: u8, vector: u8) -> KernelResult<()> {
    let state = APIC_STATE.lock();
    match state.as_ref() {
        Some(s) => {
            s.local_apic.send_ipi(dest, vector);
            Ok(())
        }
        None => Err(KernelError::NotInitialized { subsystem: "APIC" }),
    }
}

/// Send INIT IPI to a target CPU for AP startup sequence.
pub fn send_init_ipi(dest: u8) -> KernelResult<()> {
    let state = APIC_STATE.lock();
    match state.as_ref() {
        Some(s) => {
            s.local_apic.send_init_ipi(dest);
            Ok(())
        }
        None => Err(KernelError::NotInitialized { subsystem: "APIC" }),
    }
}

/// Send Startup IPI (SIPI) to a target CPU for AP startup sequence.
///
/// `startup_page` is the physical page number where AP trampoline code resides
/// (e.g., 0x08 for physical address 0x8000).
pub fn send_startup_ipi(dest: u8, startup_page: u8) -> KernelResult<()> {
    let state = APIC_STATE.lock();
    match state.as_ref() {
        Some(s) => {
            s.local_apic.send_startup_ipi(dest, startup_page);
            Ok(())
        }
        None => Err(KernelError::NotInitialized { subsystem: "APIC" }),
    }
}

/// Broadcast an IPI to all CPUs except self. Used for TLB shootdown.
pub fn send_ipi_all_excluding_self(vector: u8) -> KernelResult<()> {
    let state = APIC_STATE.lock();
    match state.as_ref() {
        Some(s) => {
            s.local_apic.send_ipi_all_excluding_self(vector);
            Ok(())
        }
        None => Err(KernelError::NotInitialized { subsystem: "APIC" }),
    }
}

// ---------------------------------------------------------------------------
// APIC Timer calibration and start
// ---------------------------------------------------------------------------

/// Calibrated APIC timer ticks per millisecond. Set by `calibrate_timer()`.
static APIC_TICKS_PER_MS: core::sync::atomic::AtomicU32 = core::sync::atomic::AtomicU32::new(0);

/// Whether the APIC timer has been calibrated and started.
static APIC_TIMER_ACTIVE: AtomicBool = AtomicBool::new(false);

/// Check whether the APIC timer is active.
pub fn is_timer_active() -> bool {
    APIC_TIMER_ACTIVE.load(Ordering::Acquire)
}

/// Get calibrated APIC timer ticks per millisecond.
pub fn ticks_per_ms() -> u32 {
    APIC_TICKS_PER_MS.load(core::sync::atomic::Ordering::Relaxed)
}

/// Calibrate the APIC timer frequency using the PIT (8254) as a reference.
///
/// Method: Configure the APIC timer in one-shot mode with a large initial
/// count, then use the PIT to measure how many APIC ticks elapse in a known
/// time period (10ms). From this, compute ticks-per-millisecond.
///
/// Must be called after `init()` and before `start_timer()`.
pub fn calibrate_timer() -> KernelResult<u32> {
    let state = APIC_STATE.lock();
    let s = state
        .as_ref()
        .ok_or(KernelError::NotInitialized { subsystem: "APIC" })?;

    let lapic = &s.local_apic;

    // Use divide-by-16 for calibration (gives good resolution).
    let divide = 0x03u8; // divide by 16
    lapic.write(LAPIC_TIMER_DIV, divide as u32);

    // Set timer to one-shot mode with a very large initial count.
    // Mask the interrupt during calibration.
    lapic.write(LAPIC_LVT_TIMER, LVT_MASK | APIC_TIMER_VECTOR as u32);
    lapic.write(LAPIC_TIMER_INIT_COUNT, 0xFFFF_FFFF);

    // Use PIT channel 2 to measure ~10ms.
    // PIT frequency = 1,193,182 Hz, so 10ms = 11,932 ticks.
    const PIT_FREQ: u32 = 1_193_182;
    const CALIBRATION_MS: u32 = 10;
    let pit_ticks = PIT_FREQ * CALIBRATION_MS / 1000;

    // SAFETY: PIT port I/O for calibration. Port 0x61 controls PIT gate/speaker,
    // 0x43 is command, 0x42 is channel 2 data. These are standard x86 I/O ports.
    unsafe {
        use x86_64::instructions::port::Port;

        // Configure PIT channel 2 for one-shot countdown.
        let mut port_61 = Port::<u8>::new(0x61);
        let mut cmd = Port::<u8>::new(0x43);
        let mut ch2 = Port::<u8>::new(0x42);

        // Disable speaker, enable gate for channel 2.
        let gate = port_61.read();
        port_61.write((gate & 0xFD) | 0x01); // gate=1, speaker=0

        // Channel 2, lobyte/hibyte, one-shot mode.
        cmd.write(0xB0);

        // Load countdown value.
        ch2.write((pit_ticks & 0xFF) as u8);
        ch2.write(((pit_ticks >> 8) & 0xFF) as u8);

        // Reset the gate to start countdown (toggle gate: low then high).
        let g = port_61.read();
        port_61.write(g & 0xFE); // gate low
        port_61.write(g | 0x01); // gate high -- starts countdown

        // Wait for PIT channel 2 output to go high (bit 5 of port 0x61).
        loop {
            let status = port_61.read();
            if status & 0x20 != 0 {
                break;
            }
        }
    }

    // Read how many APIC ticks elapsed during the PIT countdown.
    let remaining = lapic.read(LAPIC_TIMER_CUR_COUNT);
    let elapsed = 0xFFFF_FFFFu32.wrapping_sub(remaining);

    // Stop the timer.
    lapic.write(LAPIC_TIMER_INIT_COUNT, 0);

    // Calculate ticks per millisecond.
    let ticks_per_ms = elapsed / CALIBRATION_MS;

    if ticks_per_ms == 0 {
        println!("[APIC] Timer calibration failed: 0 ticks elapsed");
        return Err(KernelError::HardwareError {
            device: "APIC timer",
            code: 0,
        });
    }

    APIC_TICKS_PER_MS.store(ticks_per_ms, core::sync::atomic::Ordering::Relaxed);

    // Estimate frequency in MHz.
    let freq_mhz = (ticks_per_ms as u64 * 1000 * 16) / 1_000_000; // *16 for divisor
    println!(
        "[APIC] Timer calibrated: {} ticks/ms, ~{}MHz bus (div16)",
        ticks_per_ms, freq_mhz
    );

    Ok(ticks_per_ms)
}

/// Start the APIC timer in periodic mode at approximately `freq_hz` Hz.
///
/// Must be called after `calibrate_timer()`. The timer fires vector
/// `APIC_TIMER_VECTOR` (48) which must be registered in the IDT.
pub fn start_timer(freq_hz: u32) -> KernelResult<()> {
    let tpm = APIC_TICKS_PER_MS.load(core::sync::atomic::Ordering::Relaxed);
    if tpm == 0 {
        return Err(KernelError::NotInitialized {
            subsystem: "APIC timer (not calibrated)",
        });
    }

    // Calculate initial count for the desired frequency.
    // ticks_per_ms * 1000 / freq_hz = ticks per interrupt period.
    let initial_count = (tpm as u64 * 1000) / (freq_hz as u64);
    if initial_count == 0 || initial_count > 0xFFFF_FFFF {
        println!(
            "[APIC] Invalid timer count for {}Hz: {}",
            freq_hz, initial_count
        );
        return Err(KernelError::HardwareError {
            device: "APIC timer",
            code: freq_hz,
        });
    }

    let state = APIC_STATE.lock();
    let s = state
        .as_ref()
        .ok_or(KernelError::NotInitialized { subsystem: "APIC" })?;

    // Configure periodic mode at APIC_TIMER_VECTOR with divide-by-16.
    s.local_apic
        .setup_timer(APIC_TIMER_VECTOR, 0x03, initial_count as u32);

    APIC_TIMER_ACTIVE.store(true, Ordering::Release);

    println!(
        "[APIC] Timer started: {}Hz, initial_count={}, vector={}",
        freq_hz, initial_count, APIC_TIMER_VECTOR
    );

    Ok(())
}