strat9_kernel/arch/x86_64/

timer.rs

//! Timer Implementation
//!
//! Provides timer functionality for the kernel:
//! - PIT (Programmable Interval Timer) for legacy fallback
//! - APIC Timer for modern systems (calibrated via PIT channel 2)

use core::sync::atomic::{AtomicBool, AtomicU32, Ordering};
use x86_64::instructions::port::Port;

/// Kernel timer frequency in Hz.
///
/// All tick-to-time conversions must use this constant.
/// 100 Hz → 10 ms per tick, good balance between latency and overhead.
pub const TIMER_HZ: u64 = 100;

/// Nanoseconds per timer tick (derived from TIMER_HZ).
pub const NS_PER_TICK: u64 = 1_000_000_000 / TIMER_HZ;

/// Programmable Interval Timer (PIT) constants
const PIT_CHANNEL0_PORT: u16 = 0x40;
const PIT_COMMAND_PORT: u16 = 0x43;
const PIT_FREQUENCY: u32 = 1_193_182; // Hz (NTSC crystal / 12)

/// Whether the APIC timer is currently active
static APIC_TIMER_ACTIVE: AtomicBool = AtomicBool::new(false);
/// Cached APIC ticks per 10ms from calibration (used by APs)
static APIC_TICKS_PER_10MS: AtomicU32 = AtomicU32::new(0);

/// Initialize the Programmable Interval Timer (PIT)
///
/// Configures PIT channel 0 to generate interrupts at the specified frequency.
/// Used as a fallback when APIC timer calibration fails.
pub fn init_pit(frequency_hz: u32) {
    log::info!("========================================");
    log::info!("PIT INITIALIZATION (fallback mode)");
    log::info!("========================================");
    log::info!("Target frequency: {} Hz", frequency_hz);
    log::info!("PIT base frequency: {} Hz", PIT_FREQUENCY);

    let divisor = PIT_FREQUENCY / frequency_hz;
    log::info!("Calculated divisor: {} (0x{:04X})", divisor, divisor);

    // Expected actual frequency
    let actual_freq = PIT_FREQUENCY / divisor;
    log::info!(
        "Expected actual frequency: {} Hz (error: {} Hz)",
        actual_freq,
        if actual_freq > frequency_hz {
            actual_freq - frequency_hz
        } else {
            frequency_hz - actual_freq
        }
    );

    // Send command byte to configure PIT channel 0.
    // 0x34 = 0b00_11_010_0:
    //   Bits [7:6] = 00  → Channel 0
    //   Bits [5:4] = 11  → Access mode: lobyte then hibyte
    //   Bits [3:1] = 010 → Mode 2 (Rate Generator): one IRQ per divisor clocks,
    //                      automatic reload, correct for periodic IRQ generation.
    //   Bit  [0]   = 0   → Binary counting
    //
    // Mode 2 (Rate Generator) is preferred over Mode 3 (Square Wave, 0x36):
    // Mode 3 halves the effective frequency when routed through IOAPIC because it
    // triggers on the falling edge of the square wave, not every count cycle.
    let mut cmd_port = Port::new(PIT_COMMAND_PORT);
    unsafe {
        cmd_port.write(0x34u8); // Channel 0, lobyte/hibyte, Mode 2 (Rate Generator)
    }
    log::info!(
        "PIT command port (0x{:X}) wrote: 0x{:02X}",
        PIT_COMMAND_PORT,
        0x34u8
    );
    log::info!("  Channel: 0");
    log::info!("  Access: low byte then high byte");
    log::info!("  Mode: 2 (Rate Generator)");

    // Send divisor (low byte, then high byte)
    let mut ch0_port = Port::new(PIT_CHANNEL0_PORT);
    let low_byte = (divisor & 0xFF) as u8;
    let high_byte = ((divisor >> 8) & 0xFF) as u8;

    unsafe {
        ch0_port.write(low_byte); // Low byte
        ch0_port.write(high_byte); // High byte
    }

    log::info!("PIT channel 0 port (0x{:X}) wrote:", PIT_CHANNEL0_PORT);
    log::info!("  Low byte:  0x{:02X} ({})", low_byte, low_byte);
    log::info!("  High byte: 0x{:02X} ({})", high_byte, high_byte);

    log::info!("========================================");
    log::info!("PIT INITIALIZED SUCCESSFULLY");
    log::info!("  Frequency: {} Hz", frequency_hz);
    log::info!("  Interval: {} ms", 1_000 / frequency_hz);
    log::info!("========================================");
}

/// Check if the APIC timer is active
pub fn is_apic_timer_active() -> bool {
    APIC_TIMER_ACTIVE.load(Ordering::Relaxed)
}

/// Stop PIT channel 0 to prevent phantom interrupts.
///
/// Programs channel 0 in mode 0 (one-shot) with count = 0, which effectively
/// disables further periodic interrupts from the PIT. Should be called after
/// the APIC timer has been started.
pub fn stop_pit() {
    let mut cmd_port = Port::new(PIT_COMMAND_PORT);
    let mut ch0_port = Port::new(PIT_CHANNEL0_PORT);
    unsafe {
        // Channel 0, lobyte/hibyte, mode 0 (one-shot), binary
        cmd_port.write(0x30u8);
        // Count = 0 => immediate terminal count, no further interrupts
        ch0_port.write(0u8);
        ch0_port.write(0u8);
    }
    log::debug!("PIT channel 0 stopped (one-shot mode, count=0)");
}

/// Calibrate the APIC timer using PIT channel 2 as a reference.
///
/// Uses PIT channel 2 in one-shot mode (~10ms) to measure how many
/// APIC timer ticks elapse. Interrupts should be disabled during calibration.
///
/// Returns the number of APIC timer ticks per 10ms, or 0 on failure.
pub fn calibrate_apic_timer() -> u32 {
    use super::{
        apic,
        io::{inb, outb},
    };
    let saved_flags = super::save_flags_and_cli();

    // Try CPUID leaf 0x15 for TSC frequency first (Linux primary method).
    // This avoids relying on PIT channel 2 gate logic which is fragile
    // on some emulators and hardware.
    if let Some(tsc_khz) = super::cpuid::tsc_frequency_khz() {
        log::info!("TSC frequency from CPUID 0x15: {} KHz", tsc_khz);
        super::boot_timestamp::calibrate_khz(tsc_khz);
    }

    // ========================================================================
    // DEBUG: verbose logging for timer calibration
    // ========================================================================
    log::info!("========================================");
    log::info!("APIC TIMER CALIBRATION (verbose debug)");
    log::info!("========================================");

    // PIT channel 2 count for ~10ms: 1193182 / 100 = 11932
    const PIT_10MS_COUNT: u16 = 11932;
    const PIT_WINDOW_NS: u64 = (PIT_10MS_COUNT as u64) * 1_000_000_000 / (PIT_FREQUENCY as u64);
    // Maximum poll iterations to prevent infinite loop
    const MAX_POLL_ITERATIONS: u32 = 10_000_000;

    log::info!("PIT frequency: {} Hz", PIT_FREQUENCY);
    log::info!("PIT 10ms count: {}", PIT_10MS_COUNT);
    log::info!("Target wait time: ~10ms");

    // Set APIC timer to a known state before calibration:
    // - masked one-shot (no interrupts during measurement)
    // - divide by 16
    // SAFETY: APIC is initialized
    unsafe {
        apic::write_reg(apic::REG_LVT_TIMER, apic::LVT_TIMER_MASKED);
        apic::write_reg(apic::REG_TIMER_DIVIDE, 0x03);
        apic::write_reg(apic::REG_TIMER_INIT, 0);
    }
    log::info!("APIC timer divide set to 16 (0x03)");

    // ========================================================================
    // CRITICAL TIMING SECTION : no log messages between gate-up and poll end
    // ========================================================================
    // The PIT channel 2 gate must be LOW while programming the counter.
    // In mode 0, counting starts as soon as the count is loaded AND gate is
    // HIGH. If gate is already HIGH when we load the count, the 10 ms window
    // begins before we can start the APIC timer → measurement is wrong.
    //
    // Correct sequence:
    //   1. Gate LOW  : prevent counting while we program the PIT
    //   2. Program PIT channel 2 (mode 0, one-shot, count = PIT_10MS_COUNT)
    //   3. Set APIC timer initial count to 0xFFFF_FFFF
    //   4. Gate HIGH : PIT starts counting NOW, APIC is already counting
    //   5. Poll bit 5 of port 0x61 until PIT output goes HIGH (10 ms elapsed)
    //   6. Read APIC timer current count
    // ========================================================================

    // Step 1: Disable PIT channel 2 gate (prevent counting during setup)
    // Port 0x61: bit 0 = gate, bit 1 = speaker enable
    unsafe {
        let val = inb(0x61);
        log::info!("Port 0x61 initial value: 0x{:02X}", val);
        outb(0x61, val & 0xFC); // Clear bit 0 (gate) and bit 1 (speaker)
    }
    log::info!("PIT channel 2 gate DISABLED for setup");

    // Step 2: Program PIT channel 2 in mode 0 (one-shot)
    // Command: 0xB0 = channel 2, lobyte/hibyte, mode 0, binary
    // Writing the command sets output LOW. Count is loaded but gate is LOW
    // so counting does NOT start yet.
    unsafe {
        outb(0x43, 0xB0);
        outb(0x42, (PIT_10MS_COUNT & 0xFF) as u8); // Low byte
        outb(0x42, ((PIT_10MS_COUNT >> 8) & 0xFF) as u8); // High byte
    }
    log::info!(
        "PIT channel 2 programmed: mode 0 (one-shot), count={}",
        PIT_10MS_COUNT
    );
    log::info!("  Low byte:  0x{:02X}", (PIT_10MS_COUNT & 0xFF) as u8);
    log::info!(
        "  High byte: 0x{:02X}",
        ((PIT_10MS_COUNT >> 8) & 0xFF) as u8
    );

    // Step 3: Set APIC timer initial count to maximum
    // SAFETY: APIC is initialized
    // NOTE: No log::info! between APIC write and PIT gate : the APIC timer
    // starts counting immediately, so any delay here inflates the calibrated
    // value and skews the resulting periodic frequency.
    unsafe {
        apic::write_reg(apic::REG_TIMER_INIT, 0xFFFF_FFFF);
    }

    // Step 4: Enable PIT channel 2 gate : starts PIT counting
    // APIC timer is already counting from step 3, so the measurement
    // window begins precisely here.  NO LOG MESSAGES until poll completes.
    let tsc_start = super::rdtsc();
    unsafe {
        let val = inb(0x61);
        outb(0x61, (val | 0x01) & 0xFD); // Set bit 0 (gate), clear bit 1 (speaker)
    }

    // Step 5: Poll PIT channel 2 output (bit 5 of port 0x61)
    // When the count reaches 0, bit 5 goes high
    let mut iterations: u32 = 0;
    loop {
        // SAFETY: reading port 0x61 is safe
        let status = unsafe { inb(0x61) };
        if status & 0x20 != 0 {
            break; // PIT output went high : 10ms elapsed
        }
        iterations += 1;
        if iterations >= MAX_POLL_ITERATIONS {
            log::warn!(
                "APIC timer calibration: PIT poll timeout after {} iterations",
                iterations
            );
            log::warn!("  This may indicate a hardware issue or incorrect PIT configuration");
            // SAFETY: APIC is initialized
            unsafe {
                apic::write_reg(apic::REG_TIMER_INIT, 0);
            }
            super::restore_flags(saved_flags);
            return 0;
        }
    }
    let tsc_delta = super::rdtsc().wrapping_sub(tsc_start);

    // Step 6: Read APIC timer current count : end of critical section
    // SAFETY: APIC is initialized
    let current = unsafe { apic::read_reg(apic::REG_TIMER_CURRENT) };
    let elapsed = 0xFFFF_FFFFu32.wrapping_sub(current);

    // Stop and mask the APIC timer
    // SAFETY: APIC is initialized
    unsafe {
        apic::write_reg(apic::REG_LVT_TIMER, apic::LVT_TIMER_MASKED);
        apic::write_reg(apic::REG_TIMER_INIT, 0);
    }

    // ========================================================================
    // END CRITICAL TIMING SECTION : safe to log again
    // ========================================================================
    log::info!("PIT poll completed after {} iterations", iterations);
    log::info!("APIC timer current count: 0x{:08X}", current);
    log::info!("APIC timer elapsed ticks: {} (0x{:08X})", elapsed, elapsed);

    // Validate calibration result
    if elapsed == 0 {
        log::error!("APIC timer calibration: ZERO ticks measured!");
        log::error!("  This indicates a serious problem with the APIC timer");
        super::restore_flags(saved_flags);
        return 0;
    }

    // Check for suspicious values
    // With div=16, ticks_10ms = APIC_bus_freq / 16 / 100.
    // QEMU default APIC frequency is ~1 GHz → ~625,000 ticks/10ms.
    // Real hardware with a 200 MHz bus → ~125,000 ticks/10ms.
    // Use wide bounds to support both real hardware and emulators.
    const MIN_EXPECTED_TICKS: u32 = 1_000; // extremely slow / throttled
    const MAX_EXPECTED_TICKS: u32 = 5_000_000; // very fast host or low divider

    if elapsed < MIN_EXPECTED_TICKS {
        log::warn!(
            "APIC calibration SUSPICIOUS: {} ticks/10ms is TOO LOW",
            elapsed
        );
        log::warn!(
            "  Expected range: {} - {} ticks/10ms",
            MIN_EXPECTED_TICKS,
            MAX_EXPECTED_TICKS
        );
        log::warn!("  Possible causes:");
        log::warn!("    - APIC divide configured incorrectly");
        log::warn!("    - PIT frequency mismatch");
        log::warn!("    - hardware issue");
        log::warn!("  Forcing fallback to PIT timer");
        super::restore_flags(saved_flags);
        return 0;
    }

    if elapsed > MAX_EXPECTED_TICKS {
        log::warn!(
            "APIC calibration SUSPICIOUS: {} ticks/10ms is TOO HIGH",
            elapsed
        );
        log::warn!(
            "  Expected range: {} - {} ticks/10ms",
            MIN_EXPECTED_TICKS,
            MAX_EXPECTED_TICKS
        );
        log::warn!("  Possible causes:");
        log::warn!("    - PIT poll completed too early");
        log::warn!("    - APIC timer running at wrong frequency");
        log::warn!("    - hardware issue");
        log::warn!("  Forcing fallback to PIT timer");
        super::restore_flags(saved_flags);
        return 0;
    }

    // Calculate estimated CPU frequency
    // CPU_freq = elapsed_ticks * div * 100
    let estimated_cpu_freq_mhz = (elapsed as u64) * 16 * 100 / 1_000_000;
    log::info!(
        "Estimated CPU frequency: {} MHz (based on APIC ticks)",
        estimated_cpu_freq_mhz
    );
    super::boot_timestamp::calibrate(PIT_WINDOW_NS, tsc_delta);
    log::info!(
        "Measured TSC frequency: {} KHz (window={} ns, delta={})",
        super::boot_timestamp::tsc_khz(),
        PIT_WINDOW_NS,
        tsc_delta
    );

    // Store calibration result
    APIC_TICKS_PER_10MS.store(elapsed, Ordering::Release);

    log::info!("========================================");
    log::info!("APIC TIMER CALIBRATION COMPLETE");
    log::info!("  Ticks per 10ms: {}", elapsed);
    log::info!("  Expected frequency: ~100Hz");
    log::info!("  Estimated CPU: {} MHz", estimated_cpu_freq_mhz);
    log::info!("========================================");

    super::restore_flags(saved_flags);
    elapsed
}

/// Start the APIC timer in periodic mode.
///
/// `ticks_per_10ms` is the calibrated tick count from `calibrate_apic_timer()`.
/// The timer fires at vector 0x20 (same as PIT timer), 100Hz.
pub fn start_apic_timer(ticks_per_10ms: u32) {
    use super::apic;

    log::info!("========================================");
    log::info!("APIC TIMER START");
    log::info!("========================================");

    if ticks_per_10ms == 0 {
        log::warn!("APIC timer: cannot start with 0 ticks");
        return;
    }

    log::info!("Ticks per 10ms: {}", ticks_per_10ms);
    log::info!("Target frequency: 100Hz (10ms interval)");

    // Ensure the LAPIC timer vector is routed in the IDT before unmasking it.
    super::idt::register_lapic_timer_vector(apic::LVT_TIMER_VECTOR);

    // SAFETY: APIC is initialized
    unsafe {
        // Set divide to 16 (same as calibration)
        let divide_val = apic::read_reg(apic::REG_TIMER_DIVIDE);
        log::info!("APIC timer divide register before: 0x{:08X}", divide_val);
        apic::write_reg(apic::REG_TIMER_DIVIDE, 0x03);
        let divide_val_after = apic::read_reg(apic::REG_TIMER_DIVIDE);
        log::info!(
            "APIC timer divide register after: 0x{:08X}",
            divide_val_after
        );

        // Configure LVT Timer: periodic mode on dedicated LAPIC timer vector
        let lvt_before = apic::read_reg(apic::REG_LVT_TIMER);
        log::info!("LVT Timer register before: 0x{:08X}", lvt_before);

        let lvt_config = apic::LVT_TIMER_PERIODIC | (apic::LVT_TIMER_VECTOR as u32);
        log::info!(
            "LVT Timer config: 0x{:08X} (periodic + vector {:#x})",
            lvt_config,
            apic::LVT_TIMER_VECTOR
        );
        apic::write_reg(apic::REG_LVT_TIMER, lvt_config);

        let lvt_after = apic::read_reg(apic::REG_LVT_TIMER);
        log::info!("LVT Timer register after: 0x{:08X}", lvt_after);

        stop_pit();

        // Set initial count (fires every ~10ms = 100Hz)
        log::info!(
            "Setting timer initial count to: {} (0x{:08X})",
            ticks_per_10ms,
            ticks_per_10ms
        );
        apic::write_reg(apic::REG_TIMER_INIT, ticks_per_10ms);

        let init_verify = apic::read_reg(apic::REG_TIMER_INIT);
        log::info!(
            "Timer initial count verified: {} (0x{:08X})",
            init_verify,
            init_verify
        );
    }

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

    log::info!(
        "APIC timer: started periodic mode, vector={:#x}, count={} ({}Hz)",
        apic::LVT_TIMER_VECTOR,
        ticks_per_10ms,
        TIMER_HZ,
    );
    log::info!("========================================");
}

/// Return the cached calibration value (ticks per 10ms).
pub fn apic_ticks_per_10ms() -> u32 {
    APIC_TICKS_PER_10MS.load(Ordering::Acquire)
}

/// Start the APIC timer using the cached calibration value.
///
/// If calibration failed (ticks=0), falls back to PIT so the system always
/// has a working timer. Prevents freeze when APIC calibration times out.
pub fn start_apic_timer_cached() {
    let ticks = apic_ticks_per_10ms();
    if ticks == 0 {
        log::warn!("APIC timer: cached ticks=0, falling back to PIT");
        init_pit(TIMER_HZ as u32);
        return;
    }
    start_apic_timer(ticks);
}