openentropy-core 0.12.3

//! Dual clock-domain beat-frequency entropy from Apple Silicon private timers.
//!
//! The systematic JIT sweep of `S3_*_c15_*` registers revealed a family of
//! **undocumented 41 MHz timer counters** running in a separate clock domain
//! from the standard 24 MHz ARM generic timer (`CNTVCT_EL0`). These counters
//! are accessible from EL0 via JIT-generated MRS instructions:
//!
//! ```text
//! Register          Rate      Domain
//! ──────────────────────────────────────────
//! CNTVCT_EL0        24 MHz    ARM generic timer
//! S3_1_c15_c0_6    ~41 MHz   Apple SoC timer domain A
//! S3_4_c15_c10_5   ~41 MHz   Apple SoC timer domain B
//! S3_1_c15_c8_6     24 MHz   CNTVCT alias (same domain)
//! ```
//!
//! ## Physics
//!
//! Two oscillators running at slightly different frequencies accumulate a
//! **phase difference** that grows without bound. The lower bits of this
//! phase difference encode the instantaneous phase, which changes at the
//! **beat frequency** (difference between the two oscillator frequencies):
//!
//! ```text
//! f_beat = |f_A − f_B| + δf_thermal
//! ```
//!
//! where δf_thermal is frequency modulation from temperature-dependent
//! dielectric constants in each oscillator's RC timing circuit. Even two
//! nominally identical 41 MHz counters will have ±100 ppm manufacturing
//! spread, creating ~4,100 Hz beat frequencies — far faster than any
//! external observer can track.
//!
//! ## Characterisation (Mac mini M4)
//!
//! ```text
//! Source pairing                    Beat CV    Notes
//! ─────────────────────────────────────────────────────────────────────
//! 24 MHz CNTVCT × 41 MHz S3_1_0_6   704.2%   Cross-domain beat
//! 41 MHz domain A × domain B           —      Same domain (correlated)
//! ```
//!
//! The 24 MHz vs 41 MHz pairing gives **CV=704.2%** — the highest of any
//! source in the OpenEntropy library. The XOR of two timer values at their
//! current phase encodes ~8 bits of phase information per sample.
//!
//! ## Why these timers are unexplored
//!
//! The `S3_1_c15_c0_6` and `S3_4_c15_c10_5` registers are in the ARM64
//! implementation-defined namespace (CRn=c15), only accessible via explicit
//! JIT-generated MRS instructions. They do not correspond to any documented
//! ARM64 system register. They appear to be Apple-specific SoC performance
//! counters or epoch timers that were accidentally left EL0-readable.
//!
//! No existing entropy library (jitterentropy, HAVEGED, or others) uses
//! cross-domain beat between these undocumented Apple timers and CNTVCT_EL0.
//!
//! ## Prior art gap
//!
//! - Two-oscillator beat entropy principle: well established in metrology
//!   (NIST SP 1065, 2006; Allan 1966 "Statistics of atomic frequency standards")
//! - Using *these specific undocumented Apple Silicon timer registers* as the
//!   second oscillator: no prior art found (sweep conducted 2026-02-24)

use crate::source::{EntropySource, Platform, Requirement, SourceCategory, SourceInfo};

static DUAL_CLOCK_DOMAIN_INFO: SourceInfo = SourceInfo {
    name: "dual_clock_domain",
    description: "24 MHz CNTVCT × 41 MHz Apple private timer beat-frequency entropy",
    physics: "JIT-reads undocumented S3_1_c15_c0_6 (41 MHz Apple SoC timer) alongside \
              CNTVCT_EL0 (24 MHz ARM generic timer). Phase difference between the two \
              independent oscillators increments at the beat frequency \
              |41−24| + thermal_noise MHz. XOR of lower 24 bits gives CV=704.2%. \
              The 41 MHz timer domain is accessible only via JIT-generated MRS — it \
              lives in the ARM64 implementation-defined CRn=c15 namespace and has no \
              documented name. Manufacturing spread (±100 ppm) plus thermal noise in \
              each oscillator's RC circuit makes the phase difference unpredictable \
              on sub-microsecond timescales. No prior entropy library exploits this \
              beat because the 41 MHz register requires JIT MRS to access.",
    category: SourceCategory::Microarch,
    platform: Platform::MacOS,
    requirements: &[Requirement::AppleSilicon],
    entropy_rate_estimate: 6.0,
    composite: false,
    is_fast: false,
};

/// Entropy from cross-clock-domain phase beat between CNTVCT and an
/// undocumented Apple Silicon 41 MHz SoC timer.
pub struct DualClockDomainSource;

#[cfg(all(target_os = "macos", target_arch = "aarch64"))]
mod imp {
    use super::*;
    use crate::sources::helpers::{read_cntvct, xor_fold_u64};

    // S3_1_c15_c0_6: op0=3, op1=1, CRn=c15, CRm=c0, op2=6
    // The 41 MHz Apple SoC timer — undocumented, EL0-accessible from c15 range
    #[allow(clippy::identity_op)]
    const APPLE_41MHZ_MRS_X0: u32 = 0xD5380000u32
        | (1u32 << 16)   // op1=1
        | (15u32 << 12)  // CRn=c15
        | (0u32 << 8)    // CRm=c0
        | (6u32 << 5); // op2=6, Rt=X0

    // S3_4_c15_c10_5: second 41 MHz domain — for triple-beat verification
    const APPLE_41MHZ_B_MRS_X0: u32 = 0xD5380000u32
        | (4u32 << 16)   // op1=4
        | (15u32 << 12)  // CRn=c15
        | (10u32 << 8)   // CRm=c10
        | (5u32 << 5); // op2=5, Rt=X0

    const RET: u32 = 0xD65F03C0u32;

    type FnPtr = unsafe extern "C" fn() -> u64;

    struct JitTimer {
        fn_ptr: FnPtr,
        page: *mut libc::c_void,
    }

    unsafe impl Send for JitTimer {}
    unsafe impl Sync for JitTimer {}

    impl Drop for JitTimer {
        fn drop(&mut self) {
            unsafe {
                libc::munmap(self.page, 4096);
            }
        }
    }

    unsafe fn build_timer(instr: u32) -> Option<JitTimer> {
        let page = unsafe {
            libc::mmap(
                std::ptr::null_mut(),
                4096,
                libc::PROT_READ | libc::PROT_WRITE | libc::PROT_EXEC,
                libc::MAP_PRIVATE | libc::MAP_ANONYMOUS | 0x0800,
                -1,
                0,
            )
        };
        if page == libc::MAP_FAILED {
            return None;
        }
        unsafe {
            libc::pthread_jit_write_protect_np(0);
            let code = page as *mut u32;
            code.write(instr);
            code.add(1).write(RET);
            libc::pthread_jit_write_protect_np(1);
            core::arch::asm!("dc cvau, {p}", "ic ivau, {p}", p = in(reg) page, options(nostack));
            core::arch::asm!("dsb ish", "isb", options(nostack));
        }
        let fn_ptr: FnPtr = unsafe { std::mem::transmute(page) };
        Some(JitTimer { fn_ptr, page })
    }

    /// Read the 41 MHz Apple SoC timer via JIT MRS.
    #[inline]
    unsafe fn read_41mhz(timer: &JitTimer) -> u64 {
        unsafe { (timer.fn_ptr)() }
    }

    impl EntropySource for DualClockDomainSource {
        fn info(&self) -> &SourceInfo {
            &DUAL_CLOCK_DOMAIN_INFO
        }

        fn is_available(&self) -> bool {
            static DUAL_CLOCK_AVAILABLE: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
            *DUAL_CLOCK_AVAILABLE.get_or_init(|| {
                // These undocumented registers may not be accessible on all Apple
                // Silicon chips/OS versions. Use a fork-based probe to safely test
                // without risking SIGILL in the main process.
                crate::sources::helpers::probe_jit_instruction_safe(APPLE_41MHZ_MRS_X0)
                    && crate::sources::helpers::probe_jit_instruction_safe(APPLE_41MHZ_B_MRS_X0)
            })
        }

        fn collect(&self, n_samples: usize) -> Vec<u8> {
            unsafe {
                let Some(timer_a) = build_timer(APPLE_41MHZ_MRS_X0) else {
                    return Vec::new();
                };
                let Some(timer_b) = build_timer(APPLE_41MHZ_B_MRS_X0) else {
                    return Vec::new();
                };

                // Warmup: 64 reads to stabilise JIT and cache
                for _ in 0..64 {
                    let _ = read_41mhz(&timer_a);
                    let _ = read_41mhz(&timer_b);
                }

                // Beat values are phase differences, not timing deltas.
                // XOR-fold each directly into one byte — no delta/XOR pipeline needed.
                let raw_count = n_samples + 64;
                let mut out = Vec::with_capacity(n_samples);

                for _ in 0..raw_count {
                    // Read the 24 MHz CNTVCT directly (not mach_absolute_time)
                    let cntvct = read_cntvct();
                    // Read the 41 MHz Apple SoC timer A
                    let soc_a = read_41mhz(&timer_a);
                    // Read the 41 MHz Apple SoC timer B (second domain)
                    let soc_b = read_41mhz(&timer_b);

                    // Phase difference between clock domains:
                    // XOR of counters at different frequencies encodes
                    // the instantaneous phase beat.
                    let beat = cntvct ^ soc_a ^ soc_b;
                    out.push(xor_fold_u64(beat));

                    if out.len() >= n_samples {
                        break;
                    }
                }

                out.truncate(n_samples);
                out
            }
        }
    }
}

#[cfg(not(all(target_os = "macos", target_arch = "aarch64")))]
impl EntropySource for DualClockDomainSource {
    fn info(&self) -> &SourceInfo {
        &DUAL_CLOCK_DOMAIN_INFO
    }
    fn is_available(&self) -> bool {
        false
    }
    fn collect(&self, _n_samples: usize) -> Vec<u8> {
        Vec::new()
    }
}

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

    #[test]
    fn info() {
        let src = DualClockDomainSource;
        assert_eq!(src.info().name, "dual_clock_domain");
        assert!(matches!(src.info().category, SourceCategory::Microarch));
        assert_eq!(src.info().platform, Platform::MacOS);
        assert!(!src.info().composite);
        assert!(src.info().entropy_rate_estimate > 1.0 && src.info().entropy_rate_estimate <= 8.0);
    }

    #[test]
    #[cfg(all(target_os = "macos", target_arch = "aarch64"))]
    fn is_available_on_apple_silicon() {
        let src = DualClockDomainSource;
        let _ = src.is_available();
    }

    #[test]
    #[ignore] // Requires undocumented S3_1_c15_c0_6 register (M4 Mac mini verified)
    fn collects_high_variance_beats() {
        let src = DualClockDomainSource;
        if !src.is_available() {
            return;
        }
        let data = src.collect(64);
        assert!(!data.is_empty());
        // With CV=704%, we expect many distinct values
        let unique: std::collections::HashSet<u8> = data.iter().copied().collect();
        assert!(
            unique.len() > 8,
            "expected high-entropy beat distribution (got {} unique bytes)",
            unique.len()
        );
    }
}