open-standards/sandbox/sandbox-rs/crates/sandbox-meter/tests/rapl_hardware.rs

//! Linux RAPL against the hardware: this host's powercap counters, read by
//! the meter and by an oracle the tests declare here.
//!
//! In a test binary of its own, so the RAPL probe behind `rapl_status()`
//! runs in this process, and the tests take one lock: each burns CPU and
//! reads machine-wide counters. The oracle reads `/sys/class/powercap`
//! itself — every zone's `name`, `energy_uj` and `max_energy_range_uj` — and
//! applies the sustained-advance rule to the top-level `package-<n>` (and
//! `package-<p>-die-<d>`) zones
//! on its own. None of these tests passes without asserting: where the
//! counters cannot be read (no powercap; a CI container, whose
//! `/sys/devices/virtual/powercap` Docker masks), the status must say so and
//! agree with the oracle; where they are live, both must say live, and a
//! span over a CPU burn must be one `Cpu` record, `HwShunt`, whose figure
//! sits inside the oracle's package-only bracket and clearly below
//! package+psys and package+core. A host whose powercap lists no package zone
//! and whose meter reads the energy-status MSRs instead is checked by
//! `tests/rapl_msr_hardware.rs`, against an oracle of the MSRs; here each test
//! asserts only that this is that case.

#![cfg(target_os = "linux")]

use std::path::Path;
use std::sync::{Mutex, MutexGuard};
use std::time::{Duration, Instant};

use sandbox_meter::probe::{rapl_status, CounterStatus, PowerMeter, RaplPackages, TickOutcome};
use sandbox_meter::Provenance;
use sandbox_schema::DeviceClass;

/// One test at a time: each burns CPU and reads machine-wide counters.
static SERIAL: Mutex<()> = Mutex::new(());

fn serial() -> MutexGuard<'static, ()> {
    SERIAL.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
}

/// The tests' own reading of `/sys/class/powercap`: every zone listed, its
/// `name`, `energy_uj` and `max_energy_range_uj`, read here and nowhere else,
/// and the sustained-advance verdict over the package zones by the family's
/// rule. Nothing in it comes from the crate under test.
#[allow(dead_code)]
mod oracle {
    use std::os::raw::{c_int, c_long};
    use std::path::{Path, PathBuf};
    use std::time::{Duration, Instant};

    /// Where the kernel lists its powercap zones.
    pub const POWERCAP: &str = "/sys/class/powercap";

    #[repr(C)]
    struct Timespec {
        tv_sec: c_long,
        tv_nsec: c_long,
    }

    unsafe extern "C" {
        fn clock_gettime(clock_id: c_int, tp: *mut Timespec) -> c_int;
    }

    /// `CLOCK_THREAD_CPUTIME_ID` in Linux `<linux/time.h>`.
    const CLOCK_THREAD_CPUTIME_ID: c_int = 3;

    /// This thread's CPU time.
    pub fn thread_cpu() -> Duration {
        let mut ts = Timespec { tv_sec: 0, tv_nsec: 0 };
        assert_eq!(unsafe { clock_gettime(CLOCK_THREAD_CPUTIME_ID, &mut ts) }, 0, "clock_gettime");
        Duration::new(ts.tv_sec as u64, ts.tv_nsec as u32)
    }

    /// Spin this thread until it has used `d` of its own CPU time, or `wall_cap`
    /// of wall time has passed. Returns the CPU it got.
    pub fn burn(d: Duration, wall_cap: Duration) -> Duration {
        let (started, wall) = (thread_cpu(), Instant::now());
        let mut acc: u64 = 0;
        while thread_cpu() - started < d && wall.elapsed() < wall_cap {
            for _ in 0..1_000 {
                acc = std::hint::black_box(acc.wrapping_add(1));
            }
        }
        thread_cpu() - started
    }

    /// One entry of the powercap directory.
    #[derive(Debug, Clone)]
    pub struct Zone {
        /// The directory entry: `intel-rapl:0`, `intel-rapl:0:0`, `intel-rapl-mmio:0`, ...
        pub dir: String,
        pub name: Option<String>,
        pub energy_uj: Option<u64>,
        pub max_uj: Option<u64>,
    }

    fn text(p: PathBuf) -> Option<String> {
        std::fs::read_to_string(p).ok().map(|s| s.trim().to_string())
    }

    fn number(p: PathBuf) -> Option<u64> {
        text(p)?.parse().ok()
    }

    /// Every entry under `root`, in name order.
    pub fn zones(root: &Path) -> Vec<Zone> {
        let Ok(entries) = std::fs::read_dir(root) else { return Vec::new() };
        let mut zones: Vec<Zone> = entries
            .flatten()
            .map(|e| {
                let dir = e.file_name().to_string_lossy().into_owned();
                let p = e.path();
                Zone { name: text(p.join("name")), energy_uj: number(p.join("energy_uj")), max_uj: number(p.join("max_energy_range_uj")), dir }
            })
            .collect();
        zones.sort_by(|a, b| a.dir.cmp(&b.dir));
        zones
    }

    fn digits(s: &str) -> bool {
        !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit())
    }

    /// A top-level RAPL zone: `intel-rapl:<n>`. Not a sub-zone, not MMIO.
    pub fn top_level(z: &Zone) -> bool {
        z.dir.strip_prefix("intel-rapl:").is_some_and(digits)
    }

    /// A package zone: top-level, named `package-<n>`, or `package-<p>-die-<d>`
    /// (one zone per die of a multi-die Intel package).
    pub fn is_package(z: &Zone) -> bool {
        let named = |n: &str| match n.strip_prefix("package-") {
            Some(rest) => match rest.split_once("-die-") {
                Some((p, d)) => digits(p) && digits(d),
                None => digits(rest),
            },
            None => false,
        };
        top_level(z) && z.name.as_deref().is_some_and(named)
    }

    /// The platform zone.
    pub fn is_psys(z: &Zone) -> bool {
        top_level(z) && z.name.as_deref() == Some("psys")
    }

    /// A package's `core` sub-zone (`intel-rapl:<n>:<m>` named `core`).
    pub fn is_core(z: &Zone) -> bool {
        z.dir.strip_prefix("intel-rapl:").is_some_and(|r| r.contains(':')) && z.name.as_deref() == Some("core")
    }

    /// One zone's energy between two reads, modulo its own range.
    pub fn delta(e0: u64, e1: u64, max: Option<u64>) -> Option<u64> {
        if e1 >= e0 {
            Some(e1 - e0)
        } else {
            max.filter(|&m| m > 0)?.checked_sub(e0)?.checked_add(e1)
        }
    }

    /// `energy_uj` of each of `dirs` under `root`, in order; `None` if any fails.
    pub fn read(root: &Path, dirs: &[&Zone]) -> Option<Vec<u64>> {
        dirs.iter().map(|z| number(root.join(&z.dir).join("energy_uj"))).collect()
    }

    /// The summed energy of `which` of `set` between two reads of `set`.
    pub fn energy(set: &[&Zone], before: &[u64], after: &[u64], which: impl Fn(&Zone) -> bool) -> u64 {
        set.iter()
            .zip(before.iter().zip(after))
            .filter(|(z, _)| which(z))
            .map(|(z, (&b, &a))| delta(b, a, z.max_uj).expect("a zone fell with no readable range"))
            .sum()
    }

    /// What the oracle concluded about the package counters under a root.
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub enum Verdict {
        /// No top-level zone's `energy_uj` reads (no powercap, a masked or
        /// root-only tree).
        Unreadable,
        /// Top-level zones read, but none is a package.
        NoPackage,
        /// Every package read, but not every one kept advancing.
        Frozen,
        /// Every package advanced in at least five intervals, at least 80% of
        /// them, over at least 300 ms.
        Live,
    }

    /// The oracle's sustained-advance run over the package zones under `root`.
    #[derive(Debug)]
    pub struct Watch {
        pub verdict: Verdict,
        pub packages: Vec<String>,
        pub intervals: u32,
        pub advances: Vec<u32>,
        pub window: Duration,
    }

    impl Watch {
        /// The verdict and each package's advances, for the test's log line.
        pub fn summary(&self) -> String {
            let per: Vec<String> =
                self.packages.iter().zip(&self.advances).map(|(p, a)| format!("{p} advanced {a}/{}", self.intervals)).collect();
            format!("{:?} ({} over {} ms)", self.verdict, per.join(", "), self.window.as_millis())
        }
    }

    /// Sample every package's `energy_uj`, burning 25 ms of this thread's CPU
    /// between samples (capped at 500 ms of wall time), until every package
    /// has advanced in at least five intervals, at least 80% of those
    /// observed, over at least 300 ms; or one second has passed with at least
    /// five intervals; or five seconds have.
    pub fn watch(root: &Path) -> Watch {
        let all = zones(root);
        let packages: Vec<&Zone> = all.iter().filter(|z| is_package(z)).collect();
        let names: Vec<String> = packages.iter().map(|z| z.dir.clone()).collect();
        let none = |verdict| Watch { verdict, packages: names.clone(), intervals: 0, advances: Vec::new(), window: Duration::ZERO };
        if packages.is_empty() {
            let readable = all.iter().any(|z| top_level(z) && z.energy_uj.is_some());
            return none(if readable { Verdict::NoPackage } else { Verdict::Unreadable });
        }
        let started = Instant::now();
        let Some(mut prev) = read(root, &packages) else { return none(Verdict::Unreadable) };
        let mut advances = vec![0u32; packages.len()];
        let mut intervals = 0u32;
        let live = |adv: &[u32], n: u32, w: Duration| {
            w >= Duration::from_millis(300) && adv.iter().all(|&a| a >= 5 && u64::from(a) * 5 >= u64::from(n) * 4)
        };
        loop {
            let el = started.elapsed();
            if live(&advances, intervals, el) || el >= Duration::from_secs(5) || (el >= Duration::from_secs(1) && intervals >= 5) {
                break;
            }
            burn(Duration::from_millis(25), Duration::from_millis(500));
            if let Some(now) = read(root, &packages) {
                intervals += 1;
                for ((a, n), p) in advances.iter_mut().zip(&now).zip(&prev) {
                    *a += u32::from(n > p);
                }
                prev = now;
            }
        }
        let window = started.elapsed();
        let verdict = if live(&advances, intervals, window) { Verdict::Live } else { Verdict::Frozen };
        Watch { verdict, packages: names, intervals, advances, window }
    }

    /// The zones under `root`, as one line for the log.
    pub fn listing(root: &Path) -> String {
        zones(root)
            .iter()
            .map(|z| {
                let kind = if is_package(z) {
                    "package"
                } else if is_psys(z) {
                    "psys"
                } else if is_core(z) {
                    "core sub-zone"
                } else if top_level(z) {
                    "top-level"
                } else {
                    "not summed"
                };
                let e = z.energy_uj.map_or("unreadable".to_string(), |e| e.to_string());
                let m = z.max_uj.map_or("-".to_string(), |m| m.to_string());
                format!("{}={} [{kind}] energy_uj={e} max={m}", z.dir, z.name.as_deref().unwrap_or("?"))
            })
            .collect::<Vec<_>>()
            .join("; ")
    }

    /// The CI container's view of the host's powercap directory: the same
    /// entries, each a symlink into `/sys/devices/virtual/powercap`, which
    /// Docker masks with an empty tmpfs, so every target is missing. Built
    /// from this host's own listing; removed when dropped.
    pub struct MaskedView(pub PathBuf);

    impl MaskedView {
        /// Build the masked view of this host's powercap entries in a
        /// temporary directory named by `tag` and this process.
        pub fn of_host(tag: &str) -> MaskedView {
            let root = std::env::temp_dir().join(format!("{tag}-masked-powercap-{}", std::process::id()));
            let _ = std::fs::remove_dir_all(&root);
            std::fs::create_dir_all(&root).expect("create the masked view");
            let masked = root.join("masked-devices-virtual-powercap");
            for z in zones(Path::new(POWERCAP)) {
                std::os::unix::fs::symlink(masked.join(&z.dir), root.join(&z.dir)).expect("symlink");
            }
            MaskedView(root)
        }
    }

    impl Drop for MaskedView {
        fn drop(&mut self) {
            let _ = std::fs::remove_dir_all(&self.0);
        }
    }

    /// A bracket of reads around the meter's two reads: every package, psys
    /// and core zone read at four points, outer and inner on each side.
    pub struct Bracket<'a> {
        pub set: Vec<&'a Zone>,
        pub reads: [Vec<u64>; 4],
    }

    impl Bracket<'_> {
        /// The packages' energy over the outer bracket, in µJ: the most a
        /// package-only figure read inside it can be.
        pub fn package_outer(&self) -> u64 {
            energy(&self.set, &self.reads[0], &self.reads[3], is_package)
        }
        /// The packages' energy over the inner bracket, in µJ: the least a
        /// package-only figure read around it can be.
        pub fn package_inner(&self) -> u64 {
            energy(&self.set, &self.reads[1], &self.reads[2], is_package)
        }
        /// The psys zone's energy over the inner bracket, in µJ.
        pub fn psys_inner(&self) -> u64 {
            energy(&self.set, &self.reads[1], &self.reads[2], is_psys)
        }
        /// The core sub-zones' energy over the inner bracket, in µJ.
        pub fn core_inner(&self) -> u64 {
            energy(&self.set, &self.reads[1], &self.reads[2], is_core)
        }
        /// Whether the bracket read a zone of the kind `which` picks.
        pub fn has(&self, which: impl Fn(&Zone) -> bool) -> bool {
            self.set.iter().any(|z| which(z))
        }
    }

    /// The family's rule on a figure `uj` the meter read between the
    /// bracket's inner and outer reads: no less than the packages' energy
    /// over the inner bracket, no more than over the outer one, and below
    /// package+psys and package+core where those zones exist. A figure that
    /// added a zone reads at least the packages' and that zone's energy over
    /// the inner bracket, so `uj < inner + zone` is the double-count test; it
    /// can only be put where the zone moved more over the burn than the
    /// packages did in the gap between the outer and inner reads (else a
    /// correct figure could reach it too), and the line says when it could
    /// not. Returns the figures, for the log.
    pub fn assert_package_only(b: &Bracket, uj: u64) -> String {
        let (inner, outer, psys, core) = (b.package_inner(), b.package_outer(), b.psys_inner(), b.core_inner());
        let gap = outer - inner;
        let mut line = format!(
            "meter {uj} µJ; oracle package-only inner {inner} outer {outer} µJ (gap {gap}); psys inner {psys} µJ; \
             core inner {core} µJ"
        );
        assert!(inner > 0, "the packages did not advance over the burn: {line}");
        assert!(inner <= uj && uj <= outer, "the figure is outside the package-only bracket: {line}");
        for (zone, present, moved) in [("psys", b.has(is_psys), psys), ("core", b.has(is_core), core)] {
            if !present {
                continue;
            }
            assert!(moved > 0, "{zone} did not advance: {line}");
            if moved > gap {
                assert!(uj < inner + moved, "the figure reaches package+{zone}: {zone} was added: {line}");
                line.push_str(&format!("; below package+{zone}"));
            } else {
                line.push_str(&format!("; {zone} moved less than the gap, so only the outer bound tests it"));
            }
        }
        line
    }

    /// Every package, psys and core zone of `all` whose counter reads.
    pub fn bracket_set(all: &[Zone]) -> Vec<&Zone> {
        all.iter().filter(|z| (is_package(z) || is_psys(z) || is_core(z)) && z.energy_uj.is_some()).collect()
    }

    /// One oracle read of every zone of `set`; panics if one fails.
    pub fn read_all(set: &[&Zone]) -> Vec<u64> {
        read(Path::new(POWERCAP), set).expect("an oracle read of the bracket zones")
    }

    /// Read the bracket around `meter_read` (called twice) and `work`:
    /// outer, meter, inner, work, inner, meter, outer.
    pub fn around<'a, M>(set: Vec<&'a Zone>, mut meter_read: impl FnMut() -> M, work: impl FnOnce()) -> (Bracket<'a>, M, M) {
        let o0 = read_all(&set);
        let m0 = meter_read();
        let o1 = read_all(&set);
        work();
        let o2 = read_all(&set);
        let m1 = meter_read();
        let o3 = read_all(&set);
        (Bracket { set, reads: [o0, o1, o2, o3] }, m0, m1)
    }
}

use oracle::Verdict;

/// Whether this host's RAPL counter is read from the energy-status MSRs:
/// powercap lists no package zone, and the meter's RAPL probe is `rapl-msr`.
/// Such a host's counters are checked against an independent reading of the
/// MSRs in `tests/rapl_msr_hardware.rs`; the powercap oracle here has nothing
/// to read. It never holds where powercap lists a package zone.
fn reads_the_msrs(sources: &[&str]) -> bool {
    let msr = sources.contains(&"rapl-msr");
    let listed = oracle::zones(Path::new(oracle::POWERCAP)).iter().any(oracle::is_package);
    assert!(!(msr && listed), "the meter reads the MSRs although powercap lists a package zone: {sources:?}");
    if msr {
        eprintln!("rapl hardware: powercap lists no package zone and the meter reads the MSRs ({sources:?}); see rapl_msr_hardware");
        assert_eq!(rapl_status(), CounterStatus::Live, "a RAPL probe in the meter, yet RAPL is not live");
    }
    msr
}

/// The status agrees with the oracle's own verdict, and only a live status
/// opens the package counters and puts the RAPL probe in the meter.
#[test]
fn the_rapl_status_agrees_with_the_oracle_and_gates_the_probe() {
    let _one = serial();
    let status = rapl_status();
    let watch = oracle::watch(Path::new(oracle::POWERCAP));
    let opened = RaplPackages::host().map(|p| p.zones().iter().map(|z| z.to_string()).collect::<Vec<_>>());
    let sources = PowerMeter::detect().sources();
    if reads_the_msrs(&sources) {
        return;
    }
    eprintln!(
        "rapl hardware: {}; oracle {}; status={status:?} opened={opened:?} sources={sources:?}",
        oracle::listing(Path::new(oracle::POWERCAP)),
        watch.summary()
    );
    assert_eq!(status == CounterStatus::Live, watch.verdict == Verdict::Live, "the status disagrees with the oracle");
    match watch.verdict {
        Verdict::Unreadable | Verdict::NoPackage => assert_eq!(status, CounterStatus::Unavailable),
        Verdict::Frozen => assert_eq!(status, CounterStatus::Frozen),
        Verdict::Live => {
            let zones = opened.as_ref().expect("live, yet the package counters did not open");
            assert_eq!(*zones, watch.packages, "the probe holds other zones than the oracle's packages");
        }
    }
    assert_eq!(opened.is_ok(), status == CounterStatus::Live, "opening disagrees with the status");
    assert_eq!(sources.contains(&"rapl-powercap"), status == CounterStatus::Live, "selection disagrees with the status");
}

/// Over a 300 ms one-thread CPU burn, a span of a meter whose only CPU source
/// is RAPL is one `Cpu` record, `HwShunt`, its measured figure inside the
/// oracle's package-only bracket and clearly below package+psys and
/// package+core. Where RAPL is not live, no span has a RAPL figure.
#[test]
fn a_cpu_burn_is_one_hwshunt_cpu_record_inside_the_package_only_bracket() {
    let _one = serial();
    let mut meter = PowerMeter::detect();
    if reads_the_msrs(&meter.sources()) {
        return;
    }
    if !meter.sources().contains(&"rapl-powercap") {
        let watch = oracle::watch(Path::new(oracle::POWERCAP));
        eprintln!("rapl burn: no RAPL probe in {:?}; oracle {}", meter.sources(), watch.summary());
        assert_ne!(watch.verdict, Verdict::Live, "the oracle saw live packages, yet the meter has no RAPL probe");
        assert_ne!(rapl_status(), CounterStatus::Live);
        let ((), m) = meter.measure(|| {
            oracle::burn(Duration::from_millis(50), Duration::from_secs(5));
        });
        assert!(
            !m.devices.iter().any(|d| d.class == DeviceClass::Cpu && d.provenance == Provenance::HwShunt),
            "a CPU record was graded HwShunt with RAPL declined: {:?}",
            m.devices
        );
        return;
    }
    let all = oracle::zones(Path::new(oracle::POWERCAP));
    let set = oracle::bracket_set(&all);
    let wall = Instant::now();
    let o0 = oracle::read_all(&set);
    let span = meter.start();
    let o1 = oracle::read_all(&set);
    let cpu = oracle::burn(Duration::from_millis(300), Duration::from_secs(10));
    let o2 = oracle::read_all(&set);
    let m = span.stop(&mut meter);
    let o3 = oracle::read_all(&set);
    let b = oracle::Bracket { set, reads: [o0, o1, o2, o3] };
    let cpu_records: Vec<_> = m.devices.iter().filter(|d| d.class == DeviceClass::Cpu).collect();
    assert_eq!(cpu_records.len(), 1, "not one CPU record: {:?}", m.devices);
    let d = cpu_records[0];
    assert_eq!(d.provenance, Provenance::HwShunt, "a live RAPL span's CPU record: {d:?}");
    let uj = d.measured_uj.expect("an HwShunt record carries its measured figure");
    assert_eq!(d.estimated_uj, uj, "the estimate of a measured figure is the figure");
    assert!(m.reads_cpu(), "a span with a live RAPL CPU record does not read the CPU");
    eprintln!(
        "rapl burn: {cpu:?} of thread CPU in {:?}; sources {:?}; records {:?}; {}",
        wall.elapsed(),
        meter.sources(),
        m.devices,
        oracle::assert_package_only(&b, uj)
    );
    assert!(cpu >= Duration::from_millis(300), "the burn got only {cpu:?} of CPU");
}

/// The package counters, read through `RaplPackages` directly (the S5
/// executor's RAPL meter), read the same packages: over the same burn, the
/// figure sits inside the same bracket.
#[test]
fn the_package_counters_read_inside_the_package_only_bracket() {
    let _one = serial();
    let Ok(mut packages) = RaplPackages::host() else {
        assert_ne!(rapl_status(), CounterStatus::Live, "live, yet the package counters did not open");
        assert_ne!(oracle::watch(Path::new(oracle::POWERCAP)).verdict, Verdict::Live);
        return;
    };
    if reads_the_msrs(&[packages.source()]) {
        return;
    }
    let all = oracle::zones(Path::new(oracle::POWERCAP));
    let mut cpu = Duration::ZERO;
    let (b, m0, m1) = oracle::around(
        oracle::bracket_set(&all),
        || packages.cumulative_uj().expect("live package counters read"),
        || cpu = oracle::burn(Duration::from_millis(300), Duration::from_secs(10)),
    );
    eprintln!("rapl packages: zones {:?}; {}", packages.zones(), oracle::assert_package_only(&b, m1 - m0));
    assert!(cpu >= Duration::from_millis(300), "the burn got only {cpu:?} of CPU");
}

/// What a CI container sees: Docker masks `/sys/devices/virtual/powercap`
/// with an empty tmpfs, so every entry of `/sys/class/powercap` is a symlink
/// to nothing. On that view of this host's own listing, the probe opens no
/// package and says so, and so does the oracle.
#[test]
fn the_ci_containers_masked_view_is_unavailable() {
    let _one = serial();
    let view = oracle::MaskedView::of_host("sandbox-meter");
    let watch = oracle::watch(&view.0);
    let opened = RaplPackages::live_in(&view.0, || {
        // The oracle's own burn, independent of the probe's. The spin count is
        // this test's declaration that a real spin ran, not a reading taken
        // from the probe — the oracle stays independent of what it checks.
        let cpu = oracle::burn(Duration::from_millis(25), Duration::from_millis(500));
        TickOutcome { cpu, spins: 1 }
    });
    eprintln!("rapl masked view: oracle {}; probe {:?}", watch.summary(), opened.as_ref().map(|p| p.zones().len()).map_err(|e| e.to_string()));
    assert!(matches!(watch.verdict, Verdict::Unreadable | Verdict::NoPackage), "{watch:?}");
    assert!(opened.is_err(), "the probe opened package counters on a masked tree");
}