scx_utils: Add EnergyModel (energy_model.rs).

Schedulers need to know the energy model of a system to make energy-aware
scheduling decisions. The EnergyModel (energy_model.rs) represents the energy
model of a system. It loads the energy model data from debugfs (typically at
/sys/kernel/debug/energy_model), so the kernel should support not only the
energy model (CONFIG_ENERGY_MODEL) but also debugfs.

A system's energy model (EnergyModel) consists of one or more performance
domains (PerfDomain). A group of CPUs belonging to the same performance domain
is frequency-scaled altogether (i.e., the same frequency domain), so it has
the same performance-power characteristics. The performance-power attributes
of a performance domain are represented by a collection of performance states
(PerfState). Each performance state includes
  1) CPU frequency (kHz),
  2) the cost of the transition,
  3) performance scaled by 1024 against the highest performance of
     the fastest CPU,
  4) power consumption (mW), and
  5) whether this state is power-inefficient or not.

Signed-off-by: Changwoo Min <[email protected]>

Author: Changwoo Min

rust/scx_utils/src/cpumask.rs

@@ -60,6 +60,7 @@ use anyhow::bail;
 use anyhow::Context;
 use anyhow::Result;
 use bitvec::prelude::*;
+use sscanf::sscanf;
 use std::fmt;
 use std::ops::BitAndAssign;
 use std::ops::BitOrAssign;
@@ -137,6 +138,15 @@ impl Cpumask {
         Ok(Self { mask })
     }
 
+    pub fn from_cpulist(cpulist: &str) -> Result<Cpumask> {
+        let mut mask = Cpumask::new();
+        for cpu_id in read_cpulist(cpulist).unwrap() {
+            mask.set_cpu(cpu_id);
+        }
+
+        Ok(mask)
+    }
+
     pub fn from_vec(vec: Vec<u64>) -> Self {
         Self {
             mask: BitVec::from_vec(vec),
@@ -322,6 +332,27 @@ impl Cpumask {
     }
 }
 
+pub fn read_cpulist(cpulist: &str) -> Result<Vec<usize>> {
+    let cpu_groups: Vec<&str> = cpulist.split(',').collect();
+    let mut cpu_ids = vec![];
+    for group in cpu_groups.iter() {
+        let (min, max) = match sscanf!(group.trim(), "{usize}-{usize}") {
+            Ok((x, y)) => (x, y),
+            Err(_) => match sscanf!(group.trim(), "{usize}") {
+                Ok(x) => (x, x),
+                Err(_) => {
+                    bail!("Failed to parse cpulist {}", group.trim());
+                }
+            },
+        };
+        for i in min..(max + 1) {
+            cpu_ids.push(i);
+        }
+    }
+
+    Ok(cpu_ids)
+}
+
 pub struct CpumaskIterator<'a> {
     mask: &'a Cpumask,
     index: usize,

rust/scx_utils/src/energy_model.rs

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: GPL-2.0
+//
+// Copyright (c) 2025 Valve Corporation.
+// Author: Changwoo Min <[email protected]>
+
+// This software may be used and distributed according to the terms of the
+// GNU General Public License version 2.
+
+//! # SCX Energy Model
+//!
+//! A crate that allows schedulers to inspect and model the host's energy model,
+//! which is loaded from debugfs.
+
+use crate::compat;
+use crate::misc::read_from_file;
+use crate::Cpumask;
+use anyhow::bail;
+use anyhow::Result;
+use glob::glob;
+use std::collections::BTreeMap;
+use std::fmt;
+use std::path::Path;
+use std::sync::Arc;
+
+#[derive(Debug)]
+pub struct PerfState {
+    pub cost: usize,
+    pub frequency: usize,
+    pub inefficient: usize,
+    pub performance: usize,
+    pub power: usize,
+}
+
+#[derive(Debug)]
+pub struct PerfDomain {
+    /// Monotonically increasing unique id.
+    pub id: usize,
+    /// Cpumask of all CPUs in this performance domain.
+    pub span: Cpumask,
+    /// Table of performance states indexed by performance.
+    pub perf_table: BTreeMap<usize, Arc<PerfState>>,
+}
+
+#[derive(Debug)]
+pub struct EnergyModel {
+    /// Performance domains indexed by domain id
+    pub perf_doms: BTreeMap<usize, Arc<PerfDomain>>,
+}
+
+impl EnergyModel {
+    /// Build a complete EnergyModel
+    pub fn new() -> Result<EnergyModel> {
+        let mut perf_doms = BTreeMap::new();
+        let pd_paths = match get_pd_paths() {
+            Ok(pd_paths) => pd_paths,
+            Err(_) => {
+                bail!("Fail to locate the energy model directory");
+            }
+        };
+
+        for (pd_id, pd_path) in pd_paths {
+            let pd = PerfDomain::new(pd_id, pd_path).unwrap();
+            perf_doms.insert(pd.id, pd.into());
+        }
+
+        Ok(EnergyModel { perf_doms })
+    }
+}
+
+impl PerfDomain {
+    /// Build a PerfDomain
+    pub fn new(id: usize, root: String) -> Result<PerfDomain> {
+        let mut perf_table = BTreeMap::new();
+        let cpulist = std::fs::read_to_string(root.clone() + "/cpus")?;
+        let span = Cpumask::from_cpulist(&cpulist)?;
+
+        for ps_path in get_ps_paths(root).unwrap() {
+            let ps = PerfState::new(ps_path).unwrap();
+            perf_table.insert(ps.performance, ps.into());
+        }
+
+        Ok(PerfDomain {
+            id,
+            span,
+            perf_table,
+        })
+    }
+}
+
+impl PerfState {
+    /// Build a PerfState
+    pub fn new(root: String) -> Result<PerfState> {
+        let cost = read_from_file(Path::new(&(root.clone() + "/cost")))?;
+        let frequency = read_from_file(Path::new(&(root.clone() + "/frequency")))?;
+        let inefficient = read_from_file(Path::new(&(root.clone() + "/inefficient")))?;
+        let performance = read_from_file(Path::new(&(root.clone() + "/performance")))?;
+        let power = read_from_file(Path::new(&(root.clone() + "/power")))?;
+
+        Ok(PerfState {
+            cost,
+            frequency,
+            inefficient,
+            performance,
+            power,
+        })
+    }
+}
+
+impl fmt::Display for EnergyModel {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        for (_, pd) in self.perf_doms.iter() {
+            write!(f, "{:#}\n", pd)?;
+        }
+        Ok(())
+    }
+}
+
+impl fmt::Display for PerfDomain {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "# perf domain: {:#}, cpus: {:#}\n", self.id, self.span)?;
+        write!(f, "cost, frequency, inefficient, performance, power\n")?;
+        for (_, ps) in self.perf_table.iter() {
+            write!(f, "{:#}\n", ps)?;
+        }
+        Ok(())
+    }
+}
+
+impl fmt::Display for PerfState {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(
+            f,
+            "{}, {}, {}, {}, {}",
+            self.cost, self.frequency, self.inefficient, self.performance, self.power
+        )?;
+        Ok(())
+    }
+}
+
+/*********************************************************
+ * Helper structs/functions for creating the EnergyModel *
+ *********************************************************/
+fn get_ps_paths(root: String) -> Result<Vec<String>> {
+    let ps_paths = glob(&(root.clone() + "/ps:[0-9]*"))?;
+    let mut ps_vec = vec![];
+    for ps_path in ps_paths.filter_map(Result::ok) {
+        let ps_str = ps_path.into_os_string().into_string().unwrap();
+        ps_vec.push(ps_str);
+    }
+
+    Ok(ps_vec)
+}
+
+fn get_pd_paths() -> Result<Vec<(usize, String)>> {
+    let prefix = get_em_root().unwrap() + "/cpu";
+    let pd_paths = glob(&(prefix.clone() + "[0-9]*"))?;
+
+    let mut pd_vec = vec![];
+    for pd_path in pd_paths.filter_map(Result::ok) {
+        let pd_str = pd_path.into_os_string().into_string().unwrap();
+        let pd_id: usize = pd_str[prefix.len()..].parse().unwrap();
+        pd_vec.push((pd_id, pd_str));
+    }
+    if pd_vec.len() == 0 {
+        bail!("There is no performance domain.");
+    }
+    pd_vec.sort();
+
+    let mut pd_vec2 = vec![];
+    for (id, (_, pd_str)) in pd_vec.into_iter().enumerate() {
+        pd_vec2.push((id, pd_str));
+    }
+
+    Ok(pd_vec2)
+}
+
+fn get_em_root() -> Result<String> {
+    let root = compat::debugfs_mount().unwrap().join("energy_model");
+    Ok(root.display().to_string())
+}

rust/scx_utils/src/lib.rs

@@ -70,6 +70,11 @@ pub use topology::Topology;
 pub use topology::NR_CPUS_POSSIBLE;
 pub use topology::NR_CPU_IDS;
 
+mod energy_model;
+pub use energy_model::EnergyModel;
+pub use energy_model::PerfDomain;
+pub use energy_model::PerfState;
+
 mod cpumask;
 pub use cpumask::Cpumask;
 

rust/scx_utils/src/topology.rs

@@ -353,24 +353,7 @@ impl TopoCtx {
 fn cpus_online() -> Result<Cpumask> {
     let path = "/sys/devices/system/cpu/online";
     let online = std::fs::read_to_string(path)?;
-    let online_groups: Vec<&str> = online.split(',').collect();
-    let mut mask = Cpumask::new();
-    for group in online_groups.iter() {
-        let (min, max) = match sscanf!(group.trim(), "{usize}-{usize}") {
-            Ok((x, y)) => (x, y),
-            Err(_) => match sscanf!(group.trim(), "{usize}") {
-                Ok(x) => (x, x),
-                Err(_) => {
-                    bail!("Failed to parse online cpus {}", group.trim());
-                }
-            },
-        };
-        for i in min..(max + 1) {
-            mask.set_cpu(i)?;
-        }
-    }
-
-    Ok(mask)
+    Cpumask::from_cpulist(&online)
 }
 
 fn get_cache_id(topo_ctx: &mut TopoCtx, cache_level_path: &PathBuf, cache_level: usize) -> usize {