ironmonitor 7.1.0

IronMonitor: hardware monitoring for CPUs, GPUs, NPUs, memory, I/O and network silicon on Linux, Windows and macOS, which reports what it cannot read as well as what it can
Documentation
//! Linux memory monitoring

use crate::core::memory::{EmcInfo, IramInfo, MemoryStats, RamInfo, SwapInfo};
use crate::error::Result;
use crate::platform::common::*;
use std::fs;

/// Read memory statistics
pub fn read_memory_stats() -> Result<MemoryStats> {
    let mut stats = MemoryStats::empty();

    // Read /proc/meminfo
    let meminfo = fs::read_to_string("/proc/meminfo")?;
    stats.ram = parse_ram_info(&meminfo)?;
    stats.swap = parse_swap_info(&meminfo)?;

    // Try to read Jetson-specific memory info
    stats.emc = read_emc_info().ok();
    stats.iram = read_iram_info().ok();

    Ok(stats)
}

/// Parse the RAM figures out of `/proc/meminfo`.
///
/// **Every accumulator here used to start at `0` and every value came through
/// `.unwrap_or(0)`**, so a missing or unparseable line became a measurement.
/// That mattered in two different ways, fixed two different ways:
///
/// - `MemTotal`, `MemFree` and `MemAvailable` land in bare `u64` fields, which
///   cannot express absence. A `/proc/meminfo` without `MemTotal:` is a broken
///   system rather than a machine with no memory, so this now **fails** rather
///   than reporting zero -- matching the macOS and Windows readers, where the
///   syscall failing fails the whole call.
/// - `Buffers`, `Cached`, `SReclaimable` and `Shmem` land in `Option` fields
///   that already exist for exactly this reason. They were being filled with
///   `Some(accumulator)` regardless, so a kernel with no `Buffers:` line
///   reported `Some(0)` -- a measured zero, through a field typed to say
///   "not reported". `RamInfo::buffers`'s own documentation describes that as
///   the defect it was introduced to fix.
fn parse_ram_info(meminfo: &str) -> Result<RamInfo> {
    let mut mem_total = None;
    let mut mem_free = None;
    let mut mem_available = None;
    let mut buffers = None;
    let mut cached = None;
    let mut s_reclaimable = None;
    let mut shmem = None;

    for line in meminfo.lines() {
        let parts: Vec<&str> = line.split_whitespace().collect();
        if parts.len() < 2 {
            continue;
        }

        let key = parts[0].trim_end_matches(':');
        // A line whose value does not parse is a line we did not read.
        let Ok(value) = parts[1].parse::<u64>() else {
            continue;
        };

        match key {
            "MemTotal" => mem_total = Some(value),
            "MemFree" => mem_free = Some(value),
            "MemAvailable" => mem_available = Some(value),
            "Buffers" => buffers = Some(value),
            "Cached" => cached = Some(value),
            "SReclaimable" => s_reclaimable = Some(value),
            "Shmem" => shmem = Some(value),
            _ => {}
        }
    }

    let missing = |field: &str| {
        crate::error::IronError::Parse(format!(
            "/proc/meminfo has no {field} line; refusing to report it as zero"
        ))
    };

    let total = mem_total.ok_or_else(|| missing("MemTotal"))?;
    let free = mem_free.ok_or_else(|| missing("MemFree"))?;
    let available = mem_available.ok_or_else(|| missing("MemAvailable"))?;

    Ok(RamInfo {
        total,
        free: Some(free),
        // Derived from two readings that are both present by this point.
        used: total.saturating_sub(available),
        buffers,
        // `Cached` alone understates it; the kernel's reclaimable slab counts
        // too. Both are needed: one half alone would be reported as the whole.
        cached: match (cached, s_reclaimable) {
            (Some(c), Some(s)) => Some(c + s),
            _ => None,
        },
        // Linux does report this, via Shmem in /proc/meminfo.
        shared: shmem,
        // Try to read LFB (Large Free Blocks) for Jetson
        lfb: read_lfb().ok(),
    })
}

/// Parse the swap figures out of `/proc/meminfo`.
///
/// `SwapInfo`'s fields are plain `u64`, so a total of zero has to mean exactly
/// one thing: this machine has no swap configured. That is what the kernel
/// reports on a swapless host, and it is a reading.
///
/// It must not also mean "the field was missing", which is reachable — a
/// container without swap accounting has no `SwapTotal:` line at all. Starting
/// at zero and filling in whatever is present quietly conflated the two, so an
/// absent field became a confident "no swap".
///
/// A missing or unparseable `SwapTotal` or `SwapFree` leaves its field `None`:
/// the line is skipped, never read as zero.
fn parse_swap_info(meminfo: &str) -> Result<SwapInfo> {
    // Starts as "nothing reported". Each field becomes `Some` only when
    // /proc/meminfo actually carried it, which is what makes a container with no
    // swap accounting distinguishable from a machine with no swap.
    let mut swap = SwapInfo::default();

    for line in meminfo.lines() {
        let parts: Vec<&str> = line.split_whitespace().collect();
        if parts.len() < 2 {
            continue;
        }

        let key = parts[0].trim_end_matches(':');
        // A line whose value does not parse is a line we did not read.
        let Ok(value) = parts[1].parse::<u64>() else {
            continue;
        };

        match key {
            "SwapTotal" => swap.total = Some(value),
            "SwapFree" => {
                // Used is only meaningful once the total is known.
                swap.used = swap.total.map(|t| t.saturating_sub(value));
            }
            "SwapCached" => swap.cached = Some(value),
            _ => {}
        }
    }

    // A missing SwapTotal is no longer an error: `None` says "not reported" in
    // the type, so the whole memory read need not fail to stay honest. That
    // error existed only because `u64` could not express this.
    Ok(swap)
}

fn read_lfb() -> Result<u32> {
    // LFB can be read from various tegrastats outputs; that parser is not
    // written, so there is no reading to report. Absent, not 0.
    Err(crate::error::IronError::FeatureNotAvailable(
        "LFB reading not yet implemented".to_string(),
    ))
}

fn read_emc_info() -> Result<EmcInfo> {
    // EMC (External Memory Controller) info for Jetson
    let emc_path = "/sys/class/devfreq/17000000.mc";

    if !path_exists(emc_path) {
        // Try alternative paths
        let alt_path = "/sys/class/devfreq/13d00000.mc";
        if !path_exists(alt_path) {
            return Err(crate::error::IronError::FeatureNotAvailable(
                "EMC not available".to_string(),
            ));
        }
    }

    let cur = read_file_u32(format!("{}/cur_freq", emc_path))? / 1000;
    let min = read_file_u32(format!("{}/min_freq", emc_path))? / 1000;
    let max = read_file_u32(format!("{}/max_freq", emc_path))? / 1000;

    // Current clock as a percentage of the maximum clock. This is a frequency
    // ratio, not a measured bandwidth. With no maximum the ratio is undefined,
    // so there is no reading. This used to be 0.
    if max == 0 {
        return Err(crate::error::IronError::FeatureNotAvailable(
            "EMC reports no maximum frequency".to_string(),
        ));
    }
    let clock_percent_of_max = ((cur as f32 / max as f32) * 100.0) as u32;

    Ok(EmcInfo {
        online: true,
        clock_percent_of_max,
        current: cur,
        max,
        min,
    })
}

fn read_iram_info() -> Result<IramInfo> {
    // IRAM info for Jetson (if available)
    // This needs to be parsed from tegrastats output
    Err(crate::error::IronError::FeatureNotAvailable(
        "IRAM reading not yet implemented".to_string(),
    ))
}

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

    #[test]
    fn swap_total_that_does_not_parse_is_absent_not_no_swap() {
        let swap = parse_swap_info("SwapTotal: x kB\nSwapFree: 500 kB\n")
            .ok()
            .unwrap();
        assert_eq!(swap.total, None);
        assert_eq!(swap.used, None);
    }

    #[test]
    fn swap_free_that_does_not_parse_leaves_used_absent() {
        let swap = parse_swap_info("SwapTotal: 1000 kB\nSwapFree: ? kB\n")
            .ok()
            .unwrap();
        assert_eq!(swap.total, Some(1000));
        assert_eq!(swap.used, None);
    }

    #[test]
    fn swap_reads_total_and_used() {
        let swap = parse_swap_info("SwapTotal: 1000 kB\nSwapFree: 400 kB\n")
            .ok()
            .unwrap();
        assert_eq!(swap.total, Some(1000));
        assert_eq!(swap.used, Some(600));
    }

    #[test]
    fn cached_needs_both_cached_and_sreclaimable() {
        let base = "MemTotal: 16000 kB\nMemFree: 1000 kB\nMemAvailable: 8000 kB\n";
        let only_cached = parse_ram_info(&format!("{base}Cached: 300 kB\n"))
            .ok()
            .unwrap();
        assert_eq!(only_cached.cached, None);
        let both = parse_ram_info(&format!("{base}Cached: 300 kB\nSReclaimable: 200 kB\n"))
            .ok()
            .unwrap();
        assert_eq!(both.cached, Some(500));
    }

    #[test]
    fn lfb_is_absent_not_zero() {
        let ram = parse_ram_info("MemTotal: 16000 kB\nMemFree: 1000 kB\nMemAvailable: 8000 kB\n")
            .ok()
            .unwrap();
        assert_eq!(ram.lfb, None);
    }
}