ktstr/
topology.rs

1//! CPU topology abstraction.
2//!
3//! [`TestTopology`] reads sysfs to discover CPUs, LLCs, and NUMA nodes.
4//! Provides cpuset generation methods used by
5//! [`CpusetSpec`](crate::scenario::ops::CpusetSpec).
6//!
7//! See the [Scenarios](https://ktstr.dev/guide/concepts/scenarios.html)
8//! chapter for how topology drives cpuset partitioning.
9
10use anyhow::{Context, Result, bail};
11use std::collections::{BTreeMap, BTreeSet};
12use std::fs;
13use std::path::Path;
14
15/// Information about a last-level cache domain.
16#[derive(Debug, Clone, PartialEq, Eq)]
17pub struct LlcInfo {
18    cpus: Vec<usize>,
19    numa_node: usize,
20    cache_size_kib: Option<u64>,
21    /// core_id -> sorted list of CPU IDs (SMT siblings).
22    cores: BTreeMap<usize, Vec<usize>>,
23}
24
25impl LlcInfo {
26    /// Sorted list of CPU IDs in this LLC domain.
27    pub fn cpus(&self) -> &[usize] {
28        &self.cpus
29    }
30    /// NUMA node containing this LLC.
31    pub fn numa_node(&self) -> usize {
32        self.numa_node
33    }
34    /// LLC cache size in KiB when sysfs reported it, else `None`.
35    pub fn cache_size_kib(&self) -> Option<u64> {
36        self.cache_size_kib
37    }
38    /// Per-core sibling map: `core_id -> sorted list of CPU IDs that
39    /// are SMT siblings of that core`.
40    pub fn cores(&self) -> &BTreeMap<usize, Vec<usize>> {
41        &self.cores
42    }
43    /// Number of physical cores in the LLC; falls back to the CPU
44    /// count when core-group data is unavailable.
45    pub fn num_cores(&self) -> usize {
46        if self.cores.is_empty() {
47            self.cpus.len()
48        } else {
49            self.cores.len()
50        }
51    }
52}
53
54/// Per-node memory information (total and free KiB).
55#[derive(Debug, Clone, Copy, PartialEq, Eq)]
56pub struct NodeMemInfo {
57    /// Total memory in KiB.
58    pub total_kib: u64,
59    /// Free memory in KiB.
60    pub free_kib: u64,
61}
62
63impl NodeMemInfo {
64    /// Used memory in KiB (`total_kib - free_kib`).
65    pub fn used_kib(&self) -> u64 {
66        self.total_kib.saturating_sub(self.free_kib)
67    }
68}
69
70/// CPU topology abstraction for test configuration.
71///
72/// Provides LLC-aware CPU partitioning, cpuset generation, NUMA
73/// distance queries, and per-node memory introspection. Built from
74/// sysfs ([`from_system`](Self::from_system)), a VM spec
75/// ([`from_vm_topology`](Self::from_vm_topology) — takes a
76/// [`crate::vmm::topology::Topology`] built via
77/// `Topology::new(numa, llcs, cores, threads)`), or synthetic
78/// parameters (`synthetic`, test-only).
79#[derive(Debug, Clone, PartialEq, Eq)]
80pub struct TestTopology {
81    cpus: Vec<usize>,
82    llcs: Vec<LlcInfo>,
83    numa_nodes: BTreeSet<usize>,
84    /// Flat row-major NxN distance matrix. Dimension equals
85    /// `numa_nodes.len()`, rows ordered by ascending node ID.
86    /// Default 10/20 when sysfs distances are unavailable.
87    numa_distances: Vec<u8>,
88    /// Per-node memory info, keyed by NUMA node ID.
89    node_mem: BTreeMap<usize, NodeMemInfo>,
90    /// NUMA nodes that have memory but no CPUs (CXL memory-only).
91    memory_only_nodes: BTreeSet<usize>,
92}
93
94/// Parse a CPU list string (e.g., "0-3,5,7-9") into a sorted vec of CPU IDs.
95///
96/// Returns an error if any element is not a valid integer or range.
97/// For lenient parsing that skips invalid entries, use
98/// [`parse_cpu_list_lenient`].
99///
100/// # Why this is NOT [`crate::cpu_util::parse_cpu_list`]
101///
102/// `cpu_util` carries an `Option<Vec<u32>>`-returning variant
103/// with a range-expansion cap and dedup, intended for the
104/// per-task `/proc/<tid>/status:Cpus_allowed_list` capture path
105/// where the input is untrusted and a hostile range like
106/// `0-4294967295` would OOM the process. This parser ingests
107/// operator-supplied VM topology config (`anyhow::Error`
108/// propagation, `usize` interop with sysfs APIs, no DoS cap
109/// needed). See the module doc on [`crate::cpu_util`] for the
110/// full split rationale.
111pub fn parse_cpu_list(s: &str) -> Result<Vec<usize>> {
112    let mut cpus = Vec::new();
113    for part in s.trim().split(',') {
114        let part = part.trim();
115        if part.is_empty() {
116            continue;
117        }
118        if let Some((lo, hi)) = part.split_once('-') {
119            let lo: usize = lo.parse()?;
120            let hi: usize = hi.parse()?;
121            cpus.extend(lo..=hi);
122        } else {
123            cpus.push(part.parse()?);
124        }
125    }
126    cpus.sort();
127    Ok(cpus)
128}
129
130/// Parse a CPU list string, silently skipping invalid entries.
131///
132/// Unlike [`parse_cpu_list`], this never fails — non-numeric elements
133/// and reversed ranges are ignored. Returns a sorted ascending
134/// `Vec<usize>`, matching `parse_cpu_list`'s contract so callers that
135/// do `iter().min()` / binary search / fold-into-BTreeSet see
136/// identical ordering whichever parser they used.
137pub fn parse_cpu_list_lenient(s: &str) -> Vec<usize> {
138    let mut cpus = Vec::new();
139    for part in s.trim().split(',') {
140        let part = part.trim();
141        if part.is_empty() {
142            continue;
143        }
144        if let Some((lo, hi)) = part.split_once('-') {
145            if let (Ok(lo), Ok(hi)) = (lo.parse::<usize>(), hi.parse::<usize>()) {
146                cpus.extend(lo..=hi);
147            }
148        } else if let Ok(cpu) = part.parse::<usize>() {
149            cpus.push(cpu);
150        }
151    }
152    cpus.sort();
153    cpus
154}
155
156/// Find the sysfs index of the highest-level (last-level) cache for a CPU.
157///
158/// Iterates `/sys/devices/system/cpu/cpuN/cache/indexM/level` entries and
159/// returns the index with the largest level value.
160fn find_llc_index(cpu: usize) -> Result<usize> {
161    let cache_dir = format!("/sys/devices/system/cpu/cpu{cpu}/cache");
162    let mut max_level = 0usize;
163    let mut llc_index = 0usize;
164    for entry in fs::read_dir(&cache_dir).context("read cache dir")? {
165        let entry = entry?;
166        let name = entry.file_name();
167        let name = name.to_string_lossy();
168        if !name.starts_with("index") {
169            continue;
170        }
171        let level_path = entry.path().join("level");
172        if let Ok(level_str) = fs::read_to_string(&level_path)
173            && let Ok(level) = level_str.trim().parse::<usize>()
174            && level > max_level
175        {
176            let idx_str = name
177                .strip_prefix("index")
178                .expect("filtered by starts_with(\"index\") above");
179            match idx_str.parse::<usize>() {
180                Ok(idx) => {
181                    max_level = level;
182                    llc_index = idx;
183                }
184                Err(e) => {
185                    tracing::warn!(
186                        cache_dir = %cache_dir,
187                        entry = %name,
188                        err = %e,
189                        "malformed sysfs cache index name; skipping entry",
190                    );
191                }
192            }
193        }
194    }
195    Ok(llc_index)
196}
197
198/// Read the LLC cache ID for a CPU from sysfs.
199///
200/// Prefers the `id` file when available (x86_64 always has it).
201/// Falls back to the lowest CPU in the LLC's `shared_cpu_list`,
202/// which is unique per LLC group. The previous fallback used the
203/// cache index number, which is the same for every CPU and
204/// collapsed all LLCs into one group.
205fn read_llc_id(cpu: usize) -> Result<usize> {
206    let llc_index = find_llc_index(cpu)?;
207    let id_path = format!("/sys/devices/system/cpu/cpu{cpu}/cache/index{llc_index}/id");
208    if let Ok(id_str) = fs::read_to_string(&id_path)
209        && let Ok(id) = id_str.trim().parse::<usize>()
210    {
211        return Ok(id);
212    }
213    // Fallback: use the lowest CPU in shared_cpu_list as a stable
214    // group identifier. Each LLC group has a unique minimum CPU.
215    let shared_path =
216        format!("/sys/devices/system/cpu/cpu{cpu}/cache/index{llc_index}/shared_cpu_list");
217    if let Ok(shared_str) = fs::read_to_string(&shared_path) {
218        let siblings = parse_cpu_list_lenient(shared_str.trim());
219        if let Some(&min_cpu) = siblings.iter().min() {
220            return Ok(min_cpu);
221        }
222    }
223    Ok(0)
224}
225
226/// Read the NUMA node ID for a CPU from sysfs.
227fn read_numa_node(cpu: usize) -> Result<usize> {
228    let node_dir = format!("/sys/devices/system/cpu/cpu{cpu}");
229    for entry in fs::read_dir(&node_dir)? {
230        let entry = entry?;
231        let name = entry.file_name();
232        let name = name.to_string_lossy();
233        if name.starts_with("node")
234            && let Some(id_str) = name.strip_prefix("node")
235            && let Ok(id) = id_str.parse::<usize>()
236        {
237            return Ok(id);
238        }
239    }
240    Ok(0)
241}
242
243/// Read the LLC cache size in KiB for a CPU from sysfs.
244fn read_llc_cache_size(cpu: usize) -> Option<u64> {
245    let llc_index = find_llc_index(cpu).ok()?;
246    let size_path = format!("/sys/devices/system/cpu/cpu{cpu}/cache/index{llc_index}/size");
247    let size_str = fs::read_to_string(&size_path).ok()?;
248    parse_cache_size(size_str.trim())
249}
250
251/// Parse a cache size string like "32768K" or "32M" into KiB.
252///
253/// The sysfs `cache/index*/size` files use binary multiples (K=KiB,
254/// M=MiB) per Linux convention for cache sizes. Bare numeric input
255/// is interpreted as bytes and converted to KiB via ceiling division
256/// — a non-zero byte count smaller than 1 KiB still rounds up to 1
257/// KiB rather than silently becoming 0 KiB (which a consumer would
258/// read as "no cache"). Integer division on `500 / 1024 = 0` is the
259/// failure mode being avoided. Zero bytes still maps to 0 KiB.
260fn parse_cache_size(s: &str) -> Option<u64> {
261    let s = s.trim();
262    if let Some(kib) = s.strip_suffix('K') {
263        kib.parse().ok()
264    } else if let Some(mib) = s.strip_suffix('M') {
265        mib.parse::<u64>().ok().map(|v| v * 1024)
266    } else {
267        // Bare number: assume bytes, ceil-convert to KiB so sub-KiB
268        // values don't collapse to 0.
269        s.parse::<u64>().ok().map(|v| v.div_ceil(1024))
270    }
271}
272
273/// Read the core_id for a CPU from sysfs.
274fn read_core_id(cpu: usize) -> Option<usize> {
275    let path = format!("/sys/devices/system/cpu/cpu{cpu}/topology/core_id");
276    fs::read_to_string(&path)
277        .ok()
278        .and_then(|s| s.trim().parse().ok())
279}
280
281/// Read per-node memory info from `/sys/devices/system/node/nodeN/meminfo`.
282///
283/// Parses `MemTotal` and `MemFree` lines; returns `None` if the file
284/// is missing or unparseable.
285fn read_node_meminfo(node: usize) -> Option<NodeMemInfo> {
286    let path = format!("/sys/devices/system/node/node{node}/meminfo");
287    let content = fs::read_to_string(path).ok()?;
288    let mut total_kib = None;
289    let mut free_kib = None;
290    for line in content.lines() {
291        if let Some(rest) = line.strip_suffix("kB").map(str::trim_end) {
292            if rest.contains("MemTotal") {
293                total_kib = rest
294                    .rsplit_once(char::is_whitespace)
295                    .and_then(|(_, v)| v.parse().ok());
296            } else if rest.contains("MemFree") {
297                free_kib = rest
298                    .rsplit_once(char::is_whitespace)
299                    .and_then(|(_, v)| v.parse().ok());
300            }
301        }
302    }
303    Some(NodeMemInfo {
304        total_kib: total_kib?,
305        free_kib: free_kib?,
306    })
307}
308
309/// Read NUMA distance row from `/sys/devices/system/node/nodeN/distance`.
310///
311/// Returns the space-separated distance values as a `Vec<u8>`. Returns
312/// `None` when the file is missing, any token fails to parse, or the
313/// file is whitespace-only — `split_whitespace` on an empty/whitespace
314/// file yields zero tokens so `collect` succeeds with an empty vec,
315/// which the caller would otherwise accept as a valid distance row
316/// for a zero-node topology.
317fn read_node_distances(node: usize) -> Option<Vec<u8>> {
318    let path = format!("/sys/devices/system/node/node{node}/distance");
319    let content = fs::read_to_string(path).ok()?;
320    let values: Option<Vec<u8>> = content.split_whitespace().map(|s| s.parse().ok()).collect();
321    match values {
322        Some(v) if v.is_empty() => None,
323        other => other,
324    }
325}
326
327/// Read the cpulist for a NUMA node. Returns `true` if the node has
328/// no CPUs (memory-only / CXL).
329fn is_node_memory_only(node: usize) -> bool {
330    let path = format!("/sys/devices/system/node/node{node}/cpulist");
331    match fs::read_to_string(path) {
332        Ok(s) => s.trim().is_empty(),
333        Err(_) => false,
334    }
335}
336
337/// Build a synthetic single-LLC [`LlcInfo`] covering every online
338/// CPU. Used by [`TestTopology::from_system`] when sysfs reports
339/// online CPUs but no cache topology — the fallback path keeps
340/// downstream LLC-aware accessors non-empty.
341///
342/// Each CPU becomes its own core (no SMT sibling data available),
343/// so `num_cores()` equals the CPU count and the per-core sibling
344/// map is non-empty.
345fn synthesize_fallback_llc(cpus: &[usize], numa_node: usize) -> LlcInfo {
346    // Core map: with sysfs unavailable we can't reconstruct SMT
347    // sibling groupings, so assume no SMT — treat each CPU as its
348    // own core. Keeps `num_cores()` equal to the physical CPU count
349    // and `cores()` non-empty so consumers iterating sibling groups
350    // always see at least one entry per CPU.
351    let cores: BTreeMap<usize, Vec<usize>> = cpus.iter().map(|&c| (c, vec![c])).collect();
352    LlcInfo {
353        cpus: cpus.to_vec(),
354        numa_node,
355        cache_size_kib: None,
356        cores,
357    }
358}
359
360/// Intersect a sysfs-online CPU list with an optional
361/// `sched_getaffinity` result. Pure-fn carve-out of
362/// `TestTopology::from_system`'s cross-check so the 3 paths
363/// (narrowed + warn, disjoint + bail, no-affinity-fallback) are
364/// unit-testable without syscall mocking.
365///
366/// - `online_sysfs` — sorted, non-empty CPU list from
367///   `/sys/devices/system/cpu/online`.
368/// - `allowed` — `Some(set)` when [`crate::cpu_util::read_affinity`]
369///   succeeded; `None` on EPERM / ESRCH / syscall failure OR when
370///   the host's CPU count exceeded `AFFINITY_MAX_BITS = 262144`
371///   (cpu_util's ceiling). All None cases fall back to the full
372///   sysfs set (status quo) so a permission failure doesn't drop
373///   real CPUs.
374///
375/// Returns:
376/// - `Ok(intersect)` when the cross-check produced at least one
377///   usable CPU. Emits a `tracing::warn!` when the intersection
378///   was a strict subset (operator running inside a
379///   cgroup-cpuset-namespaced container or under a taskset-
380///   narrowed parent).
381/// - `Err(_)` when `allowed` is `Some` and disjoint from
382///   `online_sysfs` — no CPU is both kernel-online AND
383///   affinity-allowed, so no topology can be built. The
384///   diagnostic includes both the sysfs set and the disjoint
385///   allowed set so the operator can correlate against their
386///   container / taskset config.
387fn intersect_online_with_affinity(
388    online_sysfs: &[usize],
389    allowed: Option<BTreeSet<usize>>,
390) -> Result<Vec<usize>> {
391    let Some(allowed_set) = allowed else {
392        return Ok(online_sysfs.to_vec());
393    };
394    let intersect: Vec<usize> = online_sysfs
395        .iter()
396        .copied()
397        .filter(|c| allowed_set.contains(c))
398        .collect();
399    if intersect.is_empty() {
400        bail!(
401            "sched_getaffinity(0) cpuset is disjoint from \
402             /sys/devices/system/cpu/online (sysfs={online_sysfs:?}, \
403             allowed={allowed_set:?}); no usable CPUs to build a topology \
404             against — operator likely running inside a cpuset cgroup \
405             whose `cpuset.cpus` names CPUs not on this host"
406        );
407    }
408    if intersect.len() < online_sysfs.len() {
409        let dropped: Vec<usize> = online_sysfs
410            .iter()
411            .copied()
412            .filter(|c| !allowed_set.contains(c))
413            .collect();
414        tracing::warn!(
415            sysfs_online_count = online_sysfs.len(),
416            allowed_count = intersect.len(),
417            dropped_cpus = ?dropped,
418            "TestTopology::from_system: sched_getaffinity(0) is \
419             narrower than /sys/devices/system/cpu/online — running \
420             inside a cgroup-cpuset-namespaced container or with a \
421             taskset-restricted parent. Dropped CPUs would EPERM at \
422             sched_setaffinity time; topology now reflects only the \
423             actually-usable CPUs."
424        );
425    }
426    Ok(intersect)
427}
428
429/// First pass over the usable online CPUs: build the CPU set, the
430/// per-LLC [`LlcInfo`] map, and the NUMA node set. Carve-out of
431/// [`TestTopology::from_system`]'s per-CPU scan so the loop stays
432/// under the source-function size guard.
433///
434/// `online_cpus` — the sorted sysfs-online set, optionally already
435/// intersected with the calling task's `sched_getaffinity(0)` cpuset by the
436/// caller.
437///
438/// Returns `(cpus, llc_map, numa_nodes)`:
439/// - `cpus` — CPUs whose `/sys/devices/system/cpu/cpuN/` directory
440///   exists; CPUs listed in `online` but missing the per-CPU dir are
441///   warned and skipped.
442/// - `llc_map` — `llc_id -> LlcInfo`, each `info.cpus` and per-core
443///   sibling list sorted ascending.
444/// - `numa_nodes` — node IDs seen on the scanned CPUs (memory-only
445///   nodes are added later by the caller).
446fn scan_online_cpus(
447    online_cpus: &[usize],
448) -> (BTreeSet<usize>, BTreeMap<usize, LlcInfo>, BTreeSet<usize>) {
449    let mut cpus = BTreeSet::new();
450    let mut llc_map: BTreeMap<usize, LlcInfo> = BTreeMap::new();
451    let mut numa_nodes = BTreeSet::new();
452
453    // First pass: collect cache size per LLC (read once per LLC, not per CPU).
454    let mut llc_cache_sizes: BTreeMap<usize, Option<u64>> = BTreeMap::new();
455
456    for &cpu_id in online_cpus {
457        let cpu_path = format!("/sys/devices/system/cpu/cpu{cpu_id}");
458        if !Path::new(&cpu_path).exists() {
459            tracing::warn!(
460                cpu = cpu_id,
461                path = %cpu_path,
462                "/sys/devices/system/cpu/online listed this CPU but \
463                 /sys/devices/system/cpu/cpuN/ is absent; skipping — \
464                 the CPU will not appear in TestTopology.all_cpus()"
465            );
466            continue;
467        }
468        cpus.insert(cpu_id);
469        let llc_id = match read_llc_id(cpu_id) {
470            Ok(id) => id,
471            Err(e) => {
472                tracing::warn!(
473                    cpu = cpu_id,
474                    error = %e,
475                    "LLC id unreadable from sysfs; bucketing CPU into fallback LLC 0 — \
476                     LlcAligned affinity will merge this CPU with any other unreadable CPUs"
477                );
478                0
479            }
480        };
481        let node_id = match read_numa_node(cpu_id) {
482            Ok(id) => id,
483            Err(e) => {
484                tracing::warn!(
485                    cpu = cpu_id,
486                    error = %e,
487                    "NUMA node unreadable from sysfs; bucketing CPU into fallback node 0 — \
488                     NUMA-aware placement may be incorrect for this CPU"
489                );
490                0
491            }
492        };
493        // core_id unreadable = synthesize a singleton core using the
494        // CPU id. Without this, CPUs with missing core_id are added
495        // to `info.cpus` but excluded from `info.cores`, so per-core
496        // iterators silently drop them. Using cpu_id as the core id
497        // guarantees uniqueness; a degenerate topology (no SMT
498        // sibling info) is better than a CPU invisible to core-aware
499        // consumers.
500        let core_id = read_core_id(cpu_id).unwrap_or_else(|| {
501            tracing::warn!(
502                cpu = cpu_id,
503                "core_id unreadable from sysfs; synthesizing singleton core entry \
504                 using cpu_id as the core id — SMT sibling grouping unavailable for this CPU"
505            );
506            cpu_id
507        });
508        numa_nodes.insert(node_id);
509        llc_cache_sizes
510            .entry(llc_id)
511            .or_insert_with(|| read_llc_cache_size(cpu_id));
512        llc_map
513            .entry(llc_id)
514            .and_modify(|info| {
515                info.cpus.push(cpu_id);
516                info.cores.entry(core_id).or_default().push(cpu_id);
517            })
518            .or_insert_with(|| {
519                let mut cores = BTreeMap::new();
520                cores.insert(core_id, vec![cpu_id]);
521                LlcInfo {
522                    cpus: vec![cpu_id],
523                    numa_node: node_id,
524                    cache_size_kib: llc_cache_sizes.get(&llc_id).copied().flatten(),
525                    cores,
526                }
527            });
528    }
529    for info in llc_map.values_mut() {
530        info.cpus.sort();
531        for siblings in info.cores.values_mut() {
532            siblings.sort();
533        }
534    }
535    (cpus, llc_map, numa_nodes)
536}
537
538/// Build the flat row-major NxN NUMA distance matrix from sysfs.
539/// Carve-out of [`TestTopology::from_system`]'s distance block so
540/// the source function stays under the size guard.
541///
542/// `node_ids` — sorted NUMA node IDs; `n = node_ids.len()` is the
543/// matrix dimension. Reads `/sys/devices/system/node/nodeN/distance`
544/// for each node in order. Falls back to a uniform 10 (intra-node) /
545/// 20 (inter-node) matrix and warns when any row is missing,
546/// unparseable, the wrong length, or the assembled matrix is not
547/// exactly `n * n`.
548fn build_distance_matrix(node_ids: &[usize]) -> Vec<u8> {
549    let n = node_ids.len();
550    let mut matrix = Vec::with_capacity(n * n);
551    let mut fallback_reason: Option<String> = None;
552    for &nid in node_ids {
553        match read_node_distances(nid) {
554            Some(row) if row.len() == n => matrix.extend_from_slice(&row),
555            Some(row) => {
556                fallback_reason = Some(format!(
557                    "node{nid}/distance has {} entries, expected {n}",
558                    row.len()
559                ));
560                break;
561            }
562            None => {
563                fallback_reason = Some(format!("node{nid}/distance missing or unparseable"));
564                break;
565            }
566        }
567    }
568    if fallback_reason.is_some() || matrix.len() != n * n {
569        let reason = fallback_reason
570            .unwrap_or_else(|| format!("distance matrix length {} != {}", matrix.len(), n * n));
571        tracing::warn!(
572            reason = %reason,
573            numa_nodes = n,
574            "NUMA distance matrix unavailable from /sys/devices/system/node/*/distance; \
575             falling back to 10 (intra-node) / 20 (inter-node) — \
576             NUMA-aware placement decisions will use uniform distances"
577        );
578        matrix.clear();
579        matrix.resize(n * n, 0);
580        for i in 0..n {
581            for j in 0..n {
582                matrix[i * n + j] = if i == j { 10 } else { 20 };
583            }
584        }
585    }
586    matrix
587}
588
589impl TestTopology {
590    /// Discover topology from sysfs (reads `/sys/devices/system/cpu/`).
591    ///
592    /// Intersects sysfs's online-CPU set with the calling task's
593    /// `sched_getaffinity(0)` cpuset so the resulting `TestTopology`
594    /// only enumerates CPUs the process can actually run on. In a
595    /// cgroup-cpuset-namespaced container `/sys/devices/system/cpu`
596    /// reports the full host CPU set (not cgroup-filtered per the
597    /// kernel's `drivers/base/cpu.c` registration model), but
598    /// `sched_setaffinity` to CPUs outside the cgroup-allowed set
599    /// later fails with `EPERM`. Without this intersection an operator
600    /// running ktstr inside such a container sees confusing
601    /// affinity-EPERM errors far from the topology read; with it the
602    /// restriction surfaces at construction with a warn that names
603    /// the dropped CPUs.
604    pub fn from_system() -> Result<Self> {
605        Self::from_system_impl(true)
606    }
607
608    /// Discover the host-global physical topology without intersecting the
609    /// calling task's affinity mask.
610    ///
611    /// Host resource admission uses this view so LLC ordinals and complete
612    /// cache-domain CPU membership remain identical across processes running
613    /// under different cpusets. Workload placement applies its allowed mask
614    /// separately.
615    pub(crate) fn from_system_unfiltered() -> Result<Self> {
616        Self::from_system_impl(false)
617    }
618
619    fn from_system_impl(filter_affinity: bool) -> Result<Self> {
620        let online_str =
621            fs::read_to_string("/sys/devices/system/cpu/online").context("read online cpus")?;
622        let online_cpus_sysfs = parse_cpu_list(&online_str)?;
623        if online_cpus_sysfs.is_empty() {
624            bail!("no online CPUs found");
625        }
626
627        // Cross-check against sched_getaffinity. read_affinity returns
628        // None on EPERM / ESRCH / syscall failure OR when the host's
629        // CPU count exceeds cpu_util's AFFINITY_MAX_BITS = 262144
630        // ceiling — both cases fall back to the full sysfs set
631        // (status quo). Returns u32 ids; widen to usize for the
632        // intersection.
633        let online_cpus = if filter_affinity {
634            let allowed: Option<BTreeSet<usize>> = crate::cpu_util::read_affinity(0)
635                .map(|v| v.into_iter().map(|c| c as usize).collect());
636            intersect_online_with_affinity(&online_cpus_sysfs, allowed)?
637        } else {
638            online_cpus_sysfs
639        };
640
641        let (cpus, llc_map, mut numa_nodes) = scan_online_cpus(&online_cpus);
642
643        // Discover additional NUMA nodes from /sys/devices/system/node/
644        // (catches memory-only nodes that have no CPUs).
645        if let Ok(entries) = fs::read_dir("/sys/devices/system/node") {
646            for entry in entries.flatten() {
647                let name = entry.file_name();
648                let name = name.to_string_lossy();
649                if let Some(id_str) = name.strip_prefix("node")
650                    && let Ok(id) = id_str.parse::<usize>()
651                {
652                    numa_nodes.insert(id);
653                }
654            }
655        }
656
657        let node_ids: Vec<usize> = numa_nodes.iter().copied().collect();
658
659        // Read per-node memory info.
660        let mut node_mem = BTreeMap::new();
661        for &nid in &node_ids {
662            if let Some(mi) = read_node_meminfo(nid) {
663                node_mem.insert(nid, mi);
664            }
665        }
666
667        // Identify memory-only nodes.
668        let mut memory_only_nodes = BTreeSet::new();
669        for &nid in &node_ids {
670            if is_node_memory_only(nid) {
671                memory_only_nodes.insert(nid);
672            }
673        }
674
675        // Build distance matrix. Try sysfs first, fall back to 10/20.
676        let numa_distances = build_distance_matrix(&node_ids);
677
678        let llcs: Vec<LlcInfo> = llc_map.into_values().collect();
679        // Construction-time invariant: every TestTopology has at
680        // least one LLC. If sysfs reports online CPUs but no LLC
681        // info (pathological kernel — missing
682        // `/sys/devices/system/cpu/*/cache/` entries, unreadable
683        // `shared_cpu_list`, or a cgroup-restricted view that hides
684        // the per-cpu cache topology), synthesize a single LLC
685        // covering all online CPUs so downstream accessors
686        // (`llc_aligned_cpuset`, `cpus_in_llc`, LlcAligned affinity
687        // resolution) always have something to return.
688        let llcs = if llcs.is_empty() {
689            let fallback_cpus: Vec<usize> = cpus.iter().copied().collect();
690            let fallback_node = *numa_nodes.iter().next().unwrap_or(&0);
691            tracing::warn!(
692                cpu_count = fallback_cpus.len(),
693                fallback_numa_node = fallback_node,
694                "LLC discovery empty from /sys/devices/system/cpu/*/cache/; \
695                 synthesizing a single fallback LLC covering all online CPUs — \
696                 LlcAligned affinity will pin to the entire machine"
697            );
698            vec![synthesize_fallback_llc(&fallback_cpus, fallback_node)]
699        } else {
700            llcs
701        };
702        // NUMA node set must be non-empty too (every online CPU has
703        // a NUMA node, so this is a belt-and-suspenders guard).
704        let numa_nodes = if numa_nodes.is_empty() {
705            tracing::warn!(
706                "NUMA node set empty after sysfs discovery (no nodeN entries and \
707                 no per-CPU node ids); synthesizing a fallback {{0}} — \
708                 NUMA-aware placement will treat the machine as single-node"
709            );
710            let mut s = BTreeSet::new();
711            s.insert(0);
712            s
713        } else {
714            numa_nodes
715        };
716        Ok(Self {
717            cpus: cpus.into_iter().collect(),
718            llcs,
719            numa_nodes,
720            numa_distances,
721            node_mem,
722            memory_only_nodes,
723        })
724    }
725
726    /// Total number of CPUs.
727    pub fn total_cpus(&self) -> usize {
728        self.cpus.len()
729    }
730    /// Number of last-level caches.
731    pub fn num_llcs(&self) -> usize {
732        self.llcs.len()
733    }
734    /// Number of NUMA nodes.
735    pub fn num_numa_nodes(&self) -> usize {
736        self.numa_nodes.len()
737    }
738    /// NUMA node IDs as a `BTreeSet`.
739    pub fn numa_node_ids(&self) -> &BTreeSet<usize> {
740        &self.numa_nodes
741    }
742    /// All LLC domains.
743    ///
744    /// # Ordering
745    ///
746    /// Returned slice is ordered by **LLC id** (ascending), not by
747    /// first-CPU. Both [`from_system`](Self::from_system) and
748    /// [`from_vm_topology`](Self::from_vm_topology) build the LLC
749    /// list by iterating a `BTreeMap<llc_id, LlcInfo>::into_values()`,
750    /// so the result is deterministic and stable across runs. When
751    /// sysfs assigns non-contiguous LLC ids (cache `id` file, or
752    /// `shared_cpu_list.min()` fallback), the slice order can differ
753    /// from CPU order — callers that need CPU-sorted LLCs must
754    /// sort by `llc.cpus()[0]` themselves.
755    pub fn llcs(&self) -> &[LlcInfo] {
756        &self.llcs
757    }
758    /// All CPU IDs, sorted.
759    pub fn all_cpus(&self) -> &[usize] {
760        &self.cpus
761    }
762    /// All CPU IDs as a `BTreeSet`.
763    pub fn all_cpuset(&self) -> BTreeSet<usize> {
764        self.cpus.iter().copied().collect()
765    }
766
767    /// CPUs available for workload placement. When the topology has
768    /// more than 2 CPUs, the last CPU is reserved for the root cgroup
769    /// (cgroup 0); with 2 or fewer CPUs, every CPU is returned.
770    pub fn usable_cpus(&self) -> &[usize] {
771        if self.cpus.len() > 2 {
772            &self.cpus[..self.cpus.len() - 1]
773        } else {
774            &self.cpus
775        }
776    }
777    /// Usable CPUs as a `BTreeSet`.
778    pub fn usable_cpuset(&self) -> BTreeSet<usize> {
779        self.usable_cpus().iter().copied().collect()
780    }
781    /// CPUs belonging to LLC at index `idx`.
782    ///
783    /// Out-of-range indices return an empty slice rather than
784    /// panicking. Construction guarantees at least one LLC (see
785    /// [`TestTopology::from_vm_topology_with_memory`]), so the only
786    /// way to hit the out-of-range branch is passing an index larger
787    /// than [`num_llcs`](Self::num_llcs) — a caller bug that used to
788    /// crash the whole scheduler test run.
789    pub fn cpus_in_llc(&self, idx: usize) -> &[usize] {
790        match self.llcs.get(idx) {
791            Some(llc) => &llc.cpus,
792            None => &[],
793        }
794    }
795    /// CPUs in LLC `idx` as a `BTreeSet`. See [`cpus_in_llc`](Self::cpus_in_llc)
796    /// for the out-of-range behavior (returns an empty set).
797    pub fn llc_aligned_cpuset(&self, idx: usize) -> BTreeSet<usize> {
798        match self.llcs.get(idx) {
799            Some(llc) => llc.cpus.iter().copied().collect(),
800            None => BTreeSet::new(),
801        }
802    }
803    /// CPUs in all LLCs belonging to NUMA node `node` as a `BTreeSet`.
804    pub fn numa_aligned_cpuset(&self, node: usize) -> BTreeSet<usize> {
805        self.llcs
806            .iter()
807            .filter(|llc| llc.numa_node() == node)
808            .flat_map(|llc| llc.cpus())
809            .copied()
810            .collect()
811    }
812
813    /// NUMA nodes covered by the given CPU set.
814    pub fn numa_nodes_for_cpuset(&self, cpus: &BTreeSet<usize>) -> BTreeSet<usize> {
815        self.llcs
816            .iter()
817            .filter(|llc| llc.cpus.iter().any(|c| cpus.contains(c)))
818            .map(|llc| llc.numa_node)
819            .collect()
820    }
821
822    /// Per-node memory info. Returns `None` when the node ID is not
823    /// present or meminfo is unavailable.
824    pub fn node_meminfo(&self, node_id: usize) -> Option<&NodeMemInfo> {
825        self.node_mem.get(&node_id)
826    }
827
828    /// Inter-node NUMA distance. Returns 255 when either node ID is
829    /// not present, matching the kernel's unreachable distance.
830    pub fn numa_distance(&self, from: usize, to: usize) -> u8 {
831        let n = self.numa_nodes.len();
832        let Some(from_idx) = self.numa_nodes.iter().position(|&id| id == from) else {
833            return 255;
834        };
835        let Some(to_idx) = self.numa_nodes.iter().position(|&id| id == to) else {
836            return 255;
837        };
838        self.numa_distances[from_idx * n + to_idx]
839    }
840
841    /// Whether the node is memory-only (has RAM but no CPUs). Typical
842    /// for CXL-attached memory tiers.
843    pub fn is_memory_only(&self, node_id: usize) -> bool {
844        self.memory_only_nodes.contains(&node_id)
845    }
846
847    /// One `BTreeSet` of CPUs per LLC.
848    pub fn split_by_llc(&self) -> Vec<BTreeSet<usize>> {
849        self.llcs
850            .iter()
851            .map(|l| l.cpus.iter().copied().collect())
852            .collect()
853    }
854
855    /// Generate `n` cpusets with `overlap_frac` overlap between adjacent sets.
856    pub fn overlapping_cpusets(&self, n: usize, overlap_frac: f64) -> Vec<BTreeSet<usize>> {
857        let total = self.cpus.len();
858        if n == 0 || total == 0 {
859            return vec![];
860        }
861        let base = total / n;
862        let overlap = ((base as f64) * overlap_frac).ceil() as usize;
863        let stride = if base > overlap { base - overlap } else { 1 };
864        (0..n)
865            .map(|i| {
866                let start = (i * stride) % total;
867                (0..base.max(1))
868                    .map(|j| self.cpus[(start + j) % total])
869                    .collect()
870            })
871            .collect()
872    }
873
874    /// Format a CPU set as a compact range string (e.g. `"0-3,5,7-9"`).
875    pub fn cpuset_string(cpus: &BTreeSet<usize>) -> String {
876        if cpus.is_empty() {
877            return String::new();
878        }
879        let sorted: Vec<usize> = cpus.iter().copied().collect();
880        let mut ranges = Vec::new();
881        let (mut start, mut end) = (sorted[0], sorted[0]);
882        for &cpu in &sorted[1..] {
883            if cpu == end + 1 {
884                end = cpu;
885            } else {
886                ranges.push(if start == end {
887                    format!("{start}")
888                } else {
889                    format!("{start}-{end}")
890                });
891                start = cpu;
892                end = cpu;
893            }
894        }
895        ranges.push(if start == end {
896            format!("{start}")
897        } else {
898            format!("{start}-{end}")
899        });
900        ranges.join(",")
901    }
902
903    /// Build a [`TestTopology`] from a [`Topology`](crate::vmm::topology::Topology).
904    ///
905    /// Populates LLCs, NUMA nodes, distances, per-node memory info,
906    /// and memory-only node flags from the VM spec. Handles both
907    /// uniform and explicit-node topologies. For uniform topologies,
908    /// pass `total_memory_mib` to populate per-node memory info; when
909    /// `None`, memory info is omitted.
910    ///
911    /// # Signature asymmetry with [`from_system`](Self::from_system)
912    ///
913    /// `from_system` returns `Result` because sysfs I/O is a
914    /// runtime-failable operation (unreadable files, cgroup-restricted
915    /// views, non-Linux hosts). `from_vm_topology` infallibly returns
916    /// `Self` because its input is already validated: every
917    /// [`Topology`](crate::vmm::topology::Topology) reaches this
918    /// function via `Topology::new`, which asserts `llcs > 0`,
919    /// `cores_per_llc > 0`, `threads_per_core > 0`, and
920    /// `numa_nodes > 0` at construction time. The remaining asserts
921    /// inside this function guard against hand-constructed `Topology`
922    /// struct literals that bypass `Topology::new`; they never fire
923    /// for any `Topology` obtained through the normal constructor.
924    ///
925    /// # Panics
926    ///
927    /// Panics if `topo` was constructed via struct literal
928    /// (bypassing `Topology::new`) with `llcs == 0`,
929    /// `cores_per_llc == 0`, `threads_per_core == 0`, or
930    /// `numa_nodes == 0`. Inputs obtained through `Topology::new`
931    /// satisfy the invariants and cannot trigger these asserts.
932    pub fn from_vm_topology(topo: &crate::vmm::topology::Topology) -> Self {
933        Self::from_vm_topology_with_memory(topo, None)
934    }
935
936    /// Build a [`TestTopology`] with optional total memory for uniform topologies.
937    ///
938    /// # Panics
939    ///
940    /// Panics if `topo` was constructed via struct literal
941    /// (bypassing `Topology::new`) with `llcs == 0`,
942    /// `cores_per_llc == 0`, `threads_per_core == 0`, or
943    /// `numa_nodes == 0`. Inputs obtained through `Topology::new`
944    /// satisfy the invariants and cannot trigger these asserts.
945    pub fn from_vm_topology_with_memory(
946        topo: &crate::vmm::topology::Topology,
947        total_memory_mib: Option<u32>,
948    ) -> Self {
949        // Construction-time invariant: every TestTopology has at
950        // least one LLC, core, and thread. Downstream code
951        // (`llc_aligned_cpuset`, `resolve_affinity_for_cgroup`'s
952        // LlcAligned branch, cpuset resolution) assumes this.
953        assert!(
954            topo.llcs > 0 && topo.cores_per_llc > 0 && topo.threads_per_core > 0,
955            "TestTopology requires non-zero llcs/cores/threads; got llcs={}, cores={}, threads={}",
956            topo.llcs,
957            topo.cores_per_llc,
958            topo.threads_per_core,
959        );
960        assert!(
961            topo.numa_nodes > 0,
962            "TestTopology requires at least one NUMA node; got {}",
963            topo.numa_nodes,
964        );
965        let llcs = topo.llcs;
966        let cores = topo.cores_per_llc;
967        let threads = topo.threads_per_core;
968        let numa_nodes = topo.numa_nodes;
969
970        let total = (llcs * cores * threads) as usize;
971        let cpus_per_llc = (cores * threads) as usize;
972        let cpus: Vec<usize> = (0..total).collect();
973
974        let llc_infos: Vec<LlcInfo> = (0..llcs as usize)
975            .map(|l| {
976                let start = l * cpus_per_llc;
977                let end = start + cpus_per_llc;
978                let mut core_map = BTreeMap::new();
979                for c in 0..cores as usize {
980                    let base = start + c * threads as usize;
981                    let siblings: Vec<usize> = (base..base + threads as usize).collect();
982                    core_map.insert(c, siblings);
983                }
984                LlcInfo {
985                    cpus: (start..end).collect(),
986                    numa_node: topo.numa_node_of(l as u32) as usize,
987                    cache_size_kib: None,
988                    cores: core_map,
989                }
990            })
991            .collect();
992
993        let n = numa_nodes as usize;
994        let numa_node_set: BTreeSet<usize> = (0..n).collect();
995
996        let mut distances = vec![0u8; n * n];
997        for i in 0..n {
998            for j in 0..n {
999                distances[i * n + j] = topo.distance(i as u32, j as u32);
1000            }
1001        }
1002
1003        let mut node_mem = BTreeMap::new();
1004        let mut memory_only_nodes = BTreeSet::new();
1005        match topo.nodes {
1006            Some(nodes) => {
1007                for (i, node) in nodes.iter().enumerate() {
1008                    if node.memory_mib > 0 {
1009                        node_mem.insert(
1010                            i,
1011                            NodeMemInfo {
1012                                total_kib: (node.memory_mib as u64) * 1024,
1013                                free_kib: (node.memory_mib as u64) * 1024,
1014                            },
1015                        );
1016                    }
1017                    if node.is_memory_only() {
1018                        memory_only_nodes.insert(i);
1019                    }
1020                }
1021            }
1022            None => {
1023                if let Some(total_mib) = total_memory_mib {
1024                    let per_node_mib = total_mib / numa_nodes;
1025                    for i in 0..n {
1026                        let mib = if i == n - 1 {
1027                            total_mib - per_node_mib * (numa_nodes - 1)
1028                        } else {
1029                            per_node_mib
1030                        };
1031                        node_mem.insert(
1032                            i,
1033                            NodeMemInfo {
1034                                total_kib: (mib as u64) * 1024,
1035                                free_kib: (mib as u64) * 1024,
1036                            },
1037                        );
1038                    }
1039                }
1040            }
1041        }
1042
1043        Self {
1044            cpus,
1045            llcs: llc_infos,
1046            numa_nodes: numa_node_set,
1047            numa_distances: distances,
1048            node_mem,
1049            memory_only_nodes,
1050        }
1051    }
1052
1053    #[cfg(test)]
1054    pub fn synthetic(num_cpus: usize, num_llcs: usize) -> Self {
1055        // Construction-time invariant: every TestTopology has at
1056        // least one LLC and at least one CPU. `llc_aligned_cpuset`,
1057        // `cpus_in_llc`, and affinity resolution all assume this.
1058        assert!(
1059            num_llcs > 0,
1060            "TestTopology::synthetic requires num_llcs > 0; got 0"
1061        );
1062        assert!(
1063            num_cpus > 0,
1064            "TestTopology::synthetic requires num_cpus > 0; got 0"
1065        );
1066        assert!(
1067            num_cpus >= num_llcs,
1068            "TestTopology::synthetic requires num_cpus ({num_cpus}) >= num_llcs ({num_llcs})",
1069        );
1070        let cpus: Vec<usize> = (0..num_cpus).collect();
1071        let per_llc = num_cpus / num_llcs;
1072        let llcs: Vec<LlcInfo> = (0..num_llcs)
1073            .map(|i| {
1074                let start = i * per_llc;
1075                let end = if i == num_llcs - 1 {
1076                    num_cpus
1077                } else {
1078                    (i + 1) * per_llc
1079                };
1080                LlcInfo {
1081                    cpus: (start..end).collect(),
1082                    numa_node: i,
1083                    cache_size_kib: None,
1084                    cores: BTreeMap::new(),
1085                }
1086            })
1087            .collect();
1088        let n = num_llcs;
1089        let numa_nodes: BTreeSet<usize> = (0..n).collect();
1090        let mut distances = vec![0u8; n * n];
1091        for i in 0..n {
1092            for j in 0..n {
1093                distances[i * n + j] = if i == j { 10 } else { 20 };
1094            }
1095        }
1096        Self {
1097            cpus,
1098            llcs,
1099            numa_nodes,
1100            numa_distances: distances,
1101            node_mem: BTreeMap::new(),
1102            memory_only_nodes: BTreeSet::new(),
1103        }
1104    }
1105}
1106
1107#[cfg(test)]
1108mod tests {
1109    use super::*;
1110
1111    /// `intersect_online_with_affinity` drops CPUs outside the
1112    /// allowed set and preserves sysfs ordering. Pins the
1113    /// narrowing-path (Some-allowed) return value separately from
1114    /// the tracing::warn side effect, which the surrounding
1115    /// production integration paths already exercise.
1116    #[test]
1117    fn intersect_drops_cpus_outside_allowed_set() {
1118        let online = vec![0, 1, 2, 3, 4];
1119        let allowed: BTreeSet<usize> = [0, 2, 4].into_iter().collect();
1120        let out =
1121            intersect_online_with_affinity(&online, Some(allowed)).expect("non-disjoint must Ok");
1122        assert_eq!(
1123            out,
1124            vec![0, 2, 4],
1125            "intersection must preserve sysfs order and drop forbidden CPUs"
1126        );
1127    }
1128
1129    /// Disjoint allowed-set bails with a diagnostic that includes
1130    /// BOTH the sysfs set AND the disjoint allowed set so the
1131    /// operator can correlate against the container / taskset
1132    /// config that imposed the restriction.
1133    #[test]
1134    fn intersect_disjoint_allowed_set_bails_with_both_sets() {
1135        let online = vec![0, 1, 2, 3];
1136        let allowed: BTreeSet<usize> = [4, 5, 6].into_iter().collect();
1137        let err =
1138            intersect_online_with_affinity(&online, Some(allowed)).expect_err("disjoint must Err");
1139        let msg = format!("{err:#}");
1140        assert!(
1141            msg.contains("disjoint from"),
1142            "bail must use the 'disjoint from' phrasing: {msg}"
1143        );
1144        assert!(
1145            msg.contains("/sys/devices/system/cpu/online"),
1146            "bail must cite the sysfs source: {msg}"
1147        );
1148        assert!(
1149            msg.contains("[0, 1, 2, 3]") || msg.contains("sysfs=[0, 1, 2, 3]"),
1150            "bail must include the sysfs CPU set verbatim: {msg}"
1151        );
1152        assert!(
1153            msg.contains("4") && msg.contains("5") && msg.contains("6"),
1154            "bail must include the disjoint allowed-set CPUs per FAF1: {msg}"
1155        );
1156    }
1157
1158    /// None-affinity (EPERM / ESRCH / syscall failure / >262144-CPU
1159    /// ceiling) returns the full sysfs set verbatim — fallback
1160    /// preserves the pre-sched_getaffinity-cross-check status quo so
1161    /// a permission failure doesn't accidentally drop real CPUs.
1162    #[test]
1163    fn intersect_none_affinity_returns_full_sysfs_set() {
1164        let online = vec![0, 1, 2, 3];
1165        let out =
1166            intersect_online_with_affinity(&online, None).expect("None-affinity must Ok-fallback");
1167        assert_eq!(
1168            out, online,
1169            "None-affinity must return sysfs set verbatim, not narrow"
1170        );
1171    }
1172
1173    #[test]
1174    fn cpuset_string_empty() {
1175        assert_eq!(TestTopology::cpuset_string(&BTreeSet::new()), "");
1176    }
1177
1178    #[test]
1179    fn cpuset_string_single() {
1180        assert_eq!(TestTopology::cpuset_string(&[3].into_iter().collect()), "3");
1181    }
1182
1183    #[test]
1184    fn cpuset_string_range() {
1185        assert_eq!(
1186            TestTopology::cpuset_string(&[0, 1, 2, 3].into_iter().collect()),
1187            "0-3"
1188        );
1189    }
1190
1191    #[test]
1192    fn cpuset_string_gaps() {
1193        assert_eq!(
1194            TestTopology::cpuset_string(&[0, 1, 3, 5, 6, 7].into_iter().collect()),
1195            "0-1,3,5-7"
1196        );
1197    }
1198
1199    #[test]
1200    fn synthetic_topology() {
1201        let t = TestTopology::synthetic(8, 2);
1202        assert_eq!(t.total_cpus(), 8);
1203        assert_eq!(t.num_llcs(), 2);
1204        assert_eq!(t.cpus_in_llc(0), &[0, 1, 2, 3]);
1205        assert_eq!(t.cpus_in_llc(1), &[4, 5, 6, 7]);
1206    }
1207
1208    #[test]
1209    fn overlapping_cpusets_basic() {
1210        let t = TestTopology::synthetic(8, 1);
1211        let sets = t.overlapping_cpusets(2, 0.5);
1212        assert_eq!(sets.len(), 2);
1213        for s in &sets {
1214            assert_eq!(s.len(), 4);
1215        }
1216        let overlap: BTreeSet<usize> = sets[0].intersection(&sets[1]).copied().collect();
1217        assert!(!overlap.is_empty());
1218    }
1219
1220    #[test]
1221    fn overlapping_cpusets_no_overlap() {
1222        let t = TestTopology::synthetic(8, 1);
1223        let sets = t.overlapping_cpusets(2, 0.0);
1224        assert_eq!(sets.len(), 2);
1225        let overlap: BTreeSet<usize> = sets[0].intersection(&sets[1]).copied().collect();
1226        assert!(overlap.is_empty());
1227    }
1228
1229    #[test]
1230    fn split_by_llc() {
1231        let t = TestTopology::synthetic(8, 2);
1232        let splits = t.split_by_llc();
1233        assert_eq!(splits.len(), 2);
1234        assert_eq!(splits[0], [0, 1, 2, 3].into_iter().collect());
1235        assert_eq!(splits[1], [4, 5, 6, 7].into_iter().collect());
1236    }
1237
1238    #[test]
1239    fn llc_aligned_cpuset() {
1240        let t = TestTopology::synthetic(8, 2);
1241        assert_eq!(t.llc_aligned_cpuset(0), [0, 1, 2, 3].into_iter().collect());
1242        assert_eq!(t.llc_aligned_cpuset(1), [4, 5, 6, 7].into_iter().collect());
1243    }
1244
1245    #[test]
1246    fn from_vm_topology_single_llc() {
1247        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 1, 4, 2));
1248        assert_eq!(t.total_cpus(), 8);
1249        assert_eq!(t.num_llcs(), 1);
1250        assert_eq!(t.num_numa_nodes(), 1);
1251        assert_eq!(t.all_cpus(), &[0, 1, 2, 3, 4, 5, 6, 7]);
1252        assert_eq!(t.cpus_in_llc(0), &[0, 1, 2, 3, 4, 5, 6, 7]);
1253    }
1254
1255    #[test]
1256    fn from_vm_topology_multi_llc() {
1257        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 2, 4, 2));
1258        assert_eq!(t.total_cpus(), 16);
1259        assert_eq!(t.num_llcs(), 2);
1260        assert_eq!(t.num_numa_nodes(), 1);
1261        assert_eq!(t.cpus_in_llc(0), &[0, 1, 2, 3, 4, 5, 6, 7]);
1262        assert_eq!(t.cpus_in_llc(1), &[8, 9, 10, 11, 12, 13, 14, 15]);
1263    }
1264
1265    #[test]
1266    fn from_vm_topology_no_smt() {
1267        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 2, 2, 1));
1268        assert_eq!(t.total_cpus(), 4);
1269        assert_eq!(t.num_llcs(), 2);
1270        assert_eq!(t.cpus_in_llc(0), &[0, 1]);
1271        assert_eq!(t.cpus_in_llc(1), &[2, 3]);
1272    }
1273
1274    #[test]
1275    fn from_vm_topology_minimal() {
1276        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 1, 1, 1));
1277        assert_eq!(t.total_cpus(), 1);
1278        assert_eq!(t.num_llcs(), 1);
1279        assert_eq!(t.all_cpus(), &[0]);
1280    }
1281
1282    #[test]
1283    fn from_vm_topology_multi_numa() {
1284        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 2));
1285        assert_eq!(t.total_cpus(), 32);
1286        assert_eq!(t.num_llcs(), 4);
1287        assert_eq!(t.num_numa_nodes(), 2);
1288        // LLCs 0,1 -> NUMA node 0; LLCs 2,3 -> NUMA node 1
1289        assert_eq!(t.llcs()[0].numa_node(), 0);
1290        assert_eq!(t.llcs()[1].numa_node(), 0);
1291        assert_eq!(t.llcs()[2].numa_node(), 1);
1292        assert_eq!(t.llcs()[3].numa_node(), 1);
1293    }
1294
1295    #[test]
1296    fn overlapping_cpusets_zero_n() {
1297        let t = TestTopology::synthetic(8, 1);
1298        assert!(t.overlapping_cpusets(0, 0.5).is_empty());
1299    }
1300
1301    #[test]
1302    fn synthetic_single_llc() {
1303        let t = TestTopology::synthetic(4, 1);
1304        assert_eq!(t.num_llcs(), 1);
1305        assert_eq!(t.total_cpus(), 4);
1306        assert_eq!(t.num_numa_nodes(), 1);
1307        assert_eq!(t.all_cpus(), &[0, 1, 2, 3]);
1308    }
1309
1310    #[test]
1311    fn synthetic_many_llcs() {
1312        let t = TestTopology::synthetic(16, 4);
1313        assert_eq!(t.num_llcs(), 4);
1314        for i in 0..4 {
1315            assert_eq!(t.cpus_in_llc(i).len(), 4);
1316        }
1317    }
1318
1319    #[test]
1320    fn cpuset_string_two_ranges() {
1321        assert_eq!(
1322            TestTopology::cpuset_string(&[0, 1, 2, 5, 6, 7].into_iter().collect()),
1323            "0-2,5-7"
1324        );
1325    }
1326
1327    #[test]
1328    fn cpuset_string_all_isolated() {
1329        assert_eq!(
1330            TestTopology::cpuset_string(&[1, 3, 5].into_iter().collect()),
1331            "1,3,5"
1332        );
1333    }
1334
1335    #[test]
1336    fn cpuset_string_large_range() {
1337        let cpus: BTreeSet<usize> = (0..128).collect();
1338        assert_eq!(TestTopology::cpuset_string(&cpus), "0-127");
1339    }
1340
1341    #[test]
1342    fn overlapping_cpusets_single_set() {
1343        let t = TestTopology::synthetic(8, 1);
1344        let sets = t.overlapping_cpusets(1, 0.5);
1345        assert_eq!(sets.len(), 1);
1346        assert_eq!(sets[0].len(), 8);
1347    }
1348
1349    #[test]
1350    fn split_by_llc_single() {
1351        let t = TestTopology::synthetic(4, 1);
1352        let splits = t.split_by_llc();
1353        assert_eq!(splits.len(), 1);
1354        assert_eq!(splits[0].len(), 4);
1355    }
1356
1357    /// Regression test for the split_by_llc bug: topology(2,4,1) must
1358    /// produce 2 disjoint LLC sets covering all 8 CPUs. Before the fix,
1359    /// from_system() on AMD hosts returned 1 LLC because CPUID leaf
1360    /// 0x8000001D was not patched, and the test panicked indexing
1361    /// llc_sets[1].
1362    #[test]
1363    fn split_by_llc_two_llc_regression() {
1364        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 2, 4, 1));
1365        assert_eq!(t.total_cpus(), 8);
1366        assert_eq!(t.num_llcs(), 2);
1367
1368        let splits = t.split_by_llc();
1369        assert_eq!(splits.len(), 2, "2-LLC topology must produce 2 LLC sets");
1370
1371        // Sets must be disjoint
1372        let overlap: BTreeSet<usize> = splits[0].intersection(&splits[1]).copied().collect();
1373        assert!(
1374            overlap.is_empty(),
1375            "LLC sets must be disjoint: overlap={overlap:?}"
1376        );
1377
1378        // Union must cover all CPUs
1379        let union: BTreeSet<usize> = splits[0].union(&splits[1]).copied().collect();
1380        assert_eq!(union, t.all_cpuset(), "LLC sets must cover all CPUs");
1381
1382        // Each set has 4 CPUs (4 cores per LLC, 1 thread)
1383        assert_eq!(splits[0].len(), 4);
1384        assert_eq!(splits[1].len(), 4);
1385
1386        // Verify exact contents
1387        assert_eq!(splits[0], [0, 1, 2, 3].into_iter().collect());
1388        assert_eq!(splits[1], [4, 5, 6, 7].into_iter().collect());
1389    }
1390
1391    #[test]
1392    fn usable_cpus_reserves_last() {
1393        let t = TestTopology::synthetic(8, 2);
1394        assert_eq!(t.usable_cpus().len(), 7);
1395        assert!(!t.usable_cpus().contains(&7));
1396    }
1397
1398    #[test]
1399    fn usable_cpus_small_no_reserve() {
1400        let t = TestTopology::synthetic(2, 1);
1401        assert_eq!(t.usable_cpus().len(), 2);
1402    }
1403
1404    #[test]
1405    fn usable_cpus_single_cpu() {
1406        let t = TestTopology::synthetic(1, 1);
1407        assert_eq!(t.usable_cpus().len(), 1);
1408    }
1409
1410    #[test]
1411    fn parse_cpu_list_simple() {
1412        assert_eq!(parse_cpu_list("0,1,2,3").unwrap(), vec![0, 1, 2, 3]);
1413    }
1414
1415    #[test]
1416    fn parse_cpu_list_range() {
1417        assert_eq!(parse_cpu_list("0-3").unwrap(), vec![0, 1, 2, 3]);
1418    }
1419
1420    #[test]
1421    fn parse_cpu_list_mixed() {
1422        assert_eq!(
1423            parse_cpu_list("0-2,5,7-9").unwrap(),
1424            vec![0, 1, 2, 5, 7, 8, 9]
1425        );
1426    }
1427
1428    #[test]
1429    fn parse_cpu_list_empty() {
1430        assert!(parse_cpu_list("").unwrap().is_empty());
1431    }
1432
1433    #[test]
1434    fn parse_cpu_list_whitespace() {
1435        assert_eq!(parse_cpu_list("  0 , 1 , 2  ").unwrap(), vec![0, 1, 2]);
1436    }
1437
1438    #[test]
1439    fn from_vm_topology_large() {
1440        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 4, 8, 2));
1441        assert_eq!(t.total_cpus(), 64);
1442        assert_eq!(t.num_llcs(), 4);
1443        assert_eq!(t.num_numa_nodes(), 1);
1444    }
1445
1446    #[test]
1447    fn llc_info_accessors() {
1448        let t = TestTopology::synthetic(8, 2);
1449        let llcs = t.llcs();
1450        assert_eq!(llcs.len(), 2);
1451        assert_eq!(llcs[0].cpus(), &[0, 1, 2, 3]);
1452        assert_eq!(llcs[0].numa_node(), 0);
1453        assert_eq!(llcs[1].cpus(), &[4, 5, 6, 7]);
1454        assert_eq!(llcs[1].numa_node(), 1);
1455    }
1456
1457    #[test]
1458    fn from_vm_topology_cores_populated() {
1459        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 2, 4, 2));
1460        let llc0 = &t.llcs()[0];
1461        assert_eq!(llc0.num_cores(), 4);
1462        assert_eq!(llc0.cores().len(), 4);
1463        assert_eq!(llc0.cores()[&0], vec![0, 1]);
1464        assert_eq!(llc0.cores()[&1], vec![2, 3]);
1465        assert_eq!(llc0.cores()[&2], vec![4, 5]);
1466        assert_eq!(llc0.cores()[&3], vec![6, 7]);
1467        let llc1 = &t.llcs()[1];
1468        assert_eq!(llc1.cores()[&0], vec![8, 9]);
1469    }
1470
1471    #[test]
1472    fn from_vm_topology_no_smt_cores() {
1473        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 1, 4, 1));
1474        let llc = &t.llcs()[0];
1475        assert_eq!(llc.num_cores(), 4);
1476        assert_eq!(llc.cores()[&0], vec![0]);
1477        assert_eq!(llc.cores()[&3], vec![3]);
1478    }
1479
1480    #[test]
1481    fn parse_cache_size_formats() {
1482        assert_eq!(parse_cache_size("32768K"), Some(32768));
1483        assert_eq!(parse_cache_size("32M"), Some(32768));
1484        // 65536 bytes = 64 KiB exactly.
1485        assert_eq!(parse_cache_size("65536"), Some(64));
1486        // Sub-KiB bare-byte values round up to 1 KiB instead of 0 KiB.
1487        // Consumers treat 0 as "no cache"; a 500-byte cache is not
1488        // "no cache", it's "small cache."
1489        assert_eq!(parse_cache_size("500"), Some(1));
1490        assert_eq!(parse_cache_size("1"), Some(1));
1491        assert_eq!(parse_cache_size("1023"), Some(1));
1492        // Just over 1 KiB still ceils to 2 KiB.
1493        assert_eq!(parse_cache_size("1025"), Some(2));
1494        // Exact zero bytes maps to zero KiB.
1495        assert_eq!(parse_cache_size("0"), Some(0));
1496    }
1497
1498    #[test]
1499    fn num_cores_from_cores_map() {
1500        let llc = LlcInfo {
1501            cpus: vec![0, 1, 2, 3],
1502            numa_node: 0,
1503            cache_size_kib: None,
1504            cores: BTreeMap::from([(0, vec![0, 1]), (1, vec![2, 3])]),
1505        };
1506        assert_eq!(llc.num_cores(), 2);
1507    }
1508
1509    #[test]
1510    fn num_cores_fallback_to_cpus() {
1511        let llc = LlcInfo {
1512            cpus: vec![0, 1, 2, 3],
1513            numa_node: 0,
1514            cache_size_kib: None,
1515            cores: BTreeMap::new(),
1516        };
1517        assert_eq!(llc.num_cores(), 4);
1518    }
1519
1520    #[test]
1521    fn parse_cpu_list_lenient_simple() {
1522        assert_eq!(parse_cpu_list_lenient("0,1,2,3"), vec![0, 1, 2, 3]);
1523    }
1524
1525    #[test]
1526    fn parse_cpu_list_lenient_range() {
1527        assert_eq!(parse_cpu_list_lenient("0-3"), vec![0, 1, 2, 3]);
1528    }
1529
1530    #[test]
1531    fn parse_cpu_list_lenient_mixed() {
1532        assert_eq!(
1533            parse_cpu_list_lenient("0-2,5,7-9"),
1534            vec![0, 1, 2, 5, 7, 8, 9]
1535        );
1536    }
1537
1538    #[test]
1539    fn parse_cpu_list_lenient_empty() {
1540        assert!(parse_cpu_list_lenient("").is_empty());
1541    }
1542
1543    #[test]
1544    fn parse_cpu_list_lenient_skips_garbage() {
1545        assert_eq!(parse_cpu_list_lenient("0,abc,2,xyz-3,4"), vec![0, 2, 4]);
1546    }
1547
1548    #[test]
1549    fn parse_cpu_list_lenient_whitespace() {
1550        assert_eq!(parse_cpu_list_lenient("  0 , 1 , 2  "), vec![0, 1, 2]);
1551    }
1552
1553    #[test]
1554    fn cache_size_bare_number() {
1555        // Bare number without suffix is treated as bytes, converted to KiB.
1556        assert_eq!(parse_cache_size("1024"), Some(1));
1557    }
1558
1559    #[test]
1560    fn cache_size_empty_string() {
1561        assert_eq!(parse_cache_size(""), None);
1562    }
1563
1564    #[test]
1565    fn cache_size_whitespace_only() {
1566        assert_eq!(parse_cache_size("   "), None);
1567    }
1568
1569    #[test]
1570    fn numa_aligned_cpuset_two_nodes() {
1571        // 2 NUMA nodes, 4 LLCs (2 per NUMA), 4 cores, 1 thread
1572        // LLCs 0,1 -> NUMA 0 (CPUs 0-7), LLCs 2,3 -> NUMA 1 (CPUs 8-15)
1573        // Total = 4 * 4 * 1 = 16 CPUs per NUMA pair = each LLC has 4 CPUs
1574        // NUMA 0: LLCs 0,1 → CPUs 0-3, 4-7 = 0-7
1575        // NUMA 1: LLCs 2,3 → CPUs 8-11, 12-15 = 8-15 (but only 16 CPUs)
1576        //
1577        // Topology::new(2, 4, 4, 1) → 4 LLCs × 4 cores × 1 thread = 16 CPUs
1578        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 1));
1579        assert_eq!(t.total_cpus(), 16);
1580        assert_eq!(t.num_numa_nodes(), 2);
1581        assert_eq!(t.num_llcs(), 4);
1582
1583        let node0: BTreeSet<usize> = t.numa_aligned_cpuset(0);
1584        let node1: BTreeSet<usize> = t.numa_aligned_cpuset(1);
1585
1586        // NUMA 0: LLCs 0,1 each with 4 CPUs → CPUs 0-7
1587        let expected0: BTreeSet<usize> = (0..8).collect();
1588        assert_eq!(node0, expected0);
1589
1590        // NUMA 1: LLCs 2,3 each with 4 CPUs → CPUs 8-15
1591        let expected1: BTreeSet<usize> = (8..16).collect();
1592        assert_eq!(node1, expected1);
1593    }
1594
1595    // -- proptest --
1596
1597    use proptest::prop_assert;
1598
1599    proptest::proptest! {
1600        /// Any arbitrary input must either succeed and return a
1601        /// sorted Vec whose elements all came from the input, or
1602        /// fail without panicking. Broadened from 30 to 120
1603        /// characters to exercise long lists and pathological
1604        /// range/comma mixes.
1605        #[test]
1606        fn prop_parse_cpu_list_never_panics(s in "\\PC{0,120}") {
1607            if let Ok(cpus) = parse_cpu_list(&s) {
1608                for w in cpus.windows(2) {
1609                    prop_assert!(w[0] <= w[1], "parse_cpu_list not sorted: {cpus:?}");
1610                }
1611            }
1612        }
1613
1614        #[test]
1615        fn prop_parse_cpu_list_single_cpu(cpu in 0usize..256) {
1616            let result = parse_cpu_list(&cpu.to_string()).unwrap();
1617            assert_eq!(result, vec![cpu]);
1618        }
1619
1620        #[test]
1621        fn prop_parse_cpu_list_range_sorted(lo in 0usize..128, span in 1usize..64) {
1622            let hi = lo + span;
1623            let result = parse_cpu_list(&format!("{lo}-{hi}")).unwrap();
1624            assert_eq!(result.len(), span + 1);
1625            assert_eq!(*result.first().unwrap(), lo);
1626            assert_eq!(*result.last().unwrap(), hi);
1627            // Must be sorted.
1628            for w in result.windows(2) {
1629                assert!(w[0] <= w[1]);
1630            }
1631        }
1632
1633        /// Lenient parser must never panic AND its output must stay
1634        /// sorted — the strict parser's contract carries over.
1635        /// Broadened range from 30 to 120 characters.
1636        #[test]
1637        fn prop_parse_cpu_list_lenient_never_panics(s in "\\PC{0,120}") {
1638            let cpus = parse_cpu_list_lenient(&s);
1639            for w in cpus.windows(2) {
1640                prop_assert!(w[0] <= w[1], "parse_cpu_list_lenient not sorted: {cpus:?}");
1641            }
1642        }
1643
1644        #[test]
1645        fn prop_parse_cpu_list_lenient_superset_of_strict(
1646            lo in 0usize..64,
1647            hi in 64usize..128,
1648        ) {
1649            let s = format!("{lo}-{hi}");
1650            let strict = parse_cpu_list(&s).unwrap();
1651            let lenient = parse_cpu_list_lenient(&s);
1652            assert_eq!(strict, lenient);
1653        }
1654
1655        #[test]
1656        fn prop_parse_cpu_list_roundtrip(
1657            cpus in proptest::collection::btree_set(0usize..256, 1..16),
1658        ) {
1659            // Format as comma-separated list, parse back, compare.
1660            let s: String = cpus.iter().map(|c| c.to_string()).collect::<Vec<_>>().join(",");
1661            let parsed = parse_cpu_list(&s).unwrap();
1662            let roundtrip: std::collections::BTreeSet<usize> = parsed.into_iter().collect();
1663            assert_eq!(cpus, roundtrip);
1664        }
1665    }
1666
1667    #[test]
1668    fn numa_node_ids_synthetic() {
1669        let t = TestTopology::synthetic(8, 2);
1670        assert_eq!(*t.numa_node_ids(), [0, 1].into_iter().collect());
1671    }
1672
1673    #[test]
1674    fn numa_nodes_for_cpuset_single_node() {
1675        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 1));
1676        let cpuset: BTreeSet<usize> = (0..4).collect(); // LLC 0, NUMA 0
1677        assert_eq!(t.numa_nodes_for_cpuset(&cpuset), [0].into_iter().collect());
1678    }
1679
1680    #[test]
1681    fn numa_nodes_for_cpuset_both_nodes() {
1682        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 1));
1683        let cpuset: BTreeSet<usize> = [0, 8].into_iter().collect(); // NUMA 0 + NUMA 1
1684        assert_eq!(
1685            t.numa_nodes_for_cpuset(&cpuset),
1686            [0, 1].into_iter().collect()
1687        );
1688    }
1689
1690    #[test]
1691    fn numa_nodes_for_cpuset_empty() {
1692        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 1));
1693        assert!(t.numa_nodes_for_cpuset(&BTreeSet::new()).is_empty());
1694    }
1695
1696    // -- NUMA distance tests --
1697
1698    #[test]
1699    fn from_vm_topology_numa_distance_local() {
1700        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 1));
1701        assert_eq!(t.numa_distance(0, 0), 10);
1702        assert_eq!(t.numa_distance(1, 1), 10);
1703    }
1704
1705    #[test]
1706    fn from_vm_topology_numa_distance_remote() {
1707        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 1));
1708        assert_eq!(t.numa_distance(0, 1), 20);
1709        assert_eq!(t.numa_distance(1, 0), 20);
1710    }
1711
1712    #[test]
1713    fn from_vm_topology_numa_distance_single_node() {
1714        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 2, 4, 1));
1715        assert_eq!(t.numa_distance(0, 0), 10);
1716    }
1717
1718    #[test]
1719    fn numa_distance_invalid_node() {
1720        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 1));
1721        assert_eq!(t.numa_distance(0, 99), 255);
1722        assert_eq!(t.numa_distance(99, 0), 255);
1723    }
1724
1725    #[test]
1726    fn synthetic_distances_default() {
1727        let t = TestTopology::synthetic(8, 2);
1728        assert_eq!(t.numa_distance(0, 0), 10);
1729        assert_eq!(t.numa_distance(0, 1), 20);
1730        assert_eq!(t.numa_distance(1, 0), 20);
1731    }
1732
1733    // -- node_meminfo tests --
1734
1735    #[test]
1736    fn node_meminfo_used_kib() {
1737        let mi = NodeMemInfo {
1738            total_kib: 1024,
1739            free_kib: 256,
1740        };
1741        assert_eq!(mi.used_kib(), 768);
1742    }
1743
1744    #[test]
1745    fn node_meminfo_used_kib_saturates() {
1746        let mi = NodeMemInfo {
1747            total_kib: 0,
1748            free_kib: 100,
1749        };
1750        assert_eq!(mi.used_kib(), 0);
1751    }
1752
1753    #[test]
1754    fn from_vm_topology_no_meminfo() {
1755        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 1));
1756        assert!(t.node_meminfo(0).is_none());
1757        assert!(t.node_meminfo(1).is_none());
1758    }
1759
1760    #[test]
1761    fn synthetic_no_meminfo() {
1762        let t = TestTopology::synthetic(8, 2);
1763        assert!(t.node_meminfo(0).is_none());
1764    }
1765
1766    // -- is_memory_only tests --
1767
1768    #[test]
1769    fn from_vm_topology_not_memory_only() {
1770        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 1));
1771        assert!(!t.is_memory_only(0));
1772        assert!(!t.is_memory_only(1));
1773    }
1774
1775    #[test]
1776    fn is_memory_only_nonexistent_node() {
1777        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(2, 4, 4, 1));
1778        assert!(!t.is_memory_only(99));
1779    }
1780
1781    /// Regression for the unchecked-index panic in `llc_aligned_cpuset`:
1782    /// an out-of-range index used to panic at `self.llcs[idx]`. Now
1783    /// it returns an empty BTreeSet so a caller bug degrades rather
1784    /// than crashing the test run.
1785    #[test]
1786    fn llc_aligned_cpuset_out_of_range_returns_empty() {
1787        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 2, 4, 1));
1788        assert_eq!(t.num_llcs(), 2);
1789        let empty = t.llc_aligned_cpuset(99);
1790        assert!(
1791            empty.is_empty(),
1792            "out-of-range LLC idx must return empty, got {empty:?}"
1793        );
1794    }
1795
1796    /// Companion for `cpus_in_llc` — same out-of-range handling.
1797    #[test]
1798    fn cpus_in_llc_out_of_range_returns_empty_slice() {
1799        let t = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 2, 4, 1));
1800        assert_eq!(t.cpus_in_llc(99), &[] as &[usize]);
1801    }
1802
1803    /// Regression for `AffinityIntent::LlcAligned` panic when the
1804    /// topology has zero LLCs: construction now asserts non-zero,
1805    /// so the path that used to hit `self.llcs[0]` on empty is
1806    /// unreachable.
1807    #[test]
1808    #[should_panic(expected = "non-zero llcs")]
1809    fn from_vm_topology_rejects_zero_llcs() {
1810        let bad = crate::vmm::topology::Topology {
1811            llcs: 0,
1812            cores_per_llc: 2,
1813            threads_per_core: 1,
1814            numa_nodes: 1,
1815            nodes: None,
1816            distances: None,
1817            llc_cores: None,
1818        };
1819        let _ = TestTopology::from_vm_topology(&bad);
1820    }
1821
1822    #[test]
1823    #[should_panic(expected = "num_llcs > 0")]
1824    fn synthetic_rejects_zero_llcs() {
1825        let _ = TestTopology::synthetic(4, 0);
1826    }
1827
1828    #[test]
1829    #[should_panic(expected = "num_cpus > 0")]
1830    fn synthetic_rejects_zero_cpus() {
1831        let _ = TestTopology::synthetic(0, 1);
1832    }
1833
1834    #[test]
1835    #[should_panic(expected = ">= num_llcs")]
1836    fn synthetic_rejects_more_llcs_than_cpus() {
1837        let _ = TestTopology::synthetic(2, 4);
1838    }
1839
1840    /// Every constructor must land a topology with at least one LLC
1841    /// so `llc_aligned_cpuset(0)` always returns a non-empty set.
1842    #[test]
1843    fn every_constructor_produces_nonzero_llcs() {
1844        let a = TestTopology::synthetic(8, 2);
1845        assert!(a.num_llcs() >= 1);
1846        let b = TestTopology::from_vm_topology(&crate::vmm::topology::Topology::new(1, 2, 4, 1));
1847        assert!(b.num_llcs() >= 1);
1848        // `from_system` depends on /sys; skip when unavailable.
1849        if let Ok(c) = TestTopology::from_system() {
1850            assert!(
1851                c.num_llcs() >= 1,
1852                "from_system must always yield at least one LLC",
1853            );
1854        }
1855    }
1856
1857    /// Direct test of the fallback-LLC synthesis path. The only way
1858    /// `from_system` itself can reach the fallback is a pathological
1859    /// sysfs (online CPUs present, cache topology empty), which is
1860    /// impossible to inject reliably from a unit test. Extracting
1861    /// `synthesize_fallback_llc` to an independent helper lets us
1862    /// exercise the shape contract the fallback must satisfy
1863    /// downstream.
1864    #[test]
1865    fn synthesize_fallback_llc_populates_cpus_node_and_cores() {
1866        let cpus = [0, 1, 3, 7];
1867        let llc = synthesize_fallback_llc(&cpus, 2);
1868
1869        // Covers every input CPU.
1870        assert_eq!(llc.cpus(), &cpus);
1871
1872        // NUMA node faithfully carried through.
1873        assert_eq!(llc.numa_node(), 2);
1874
1875        // Cache size unknown (we had no sysfs entries to read).
1876        assert!(llc.cache_size_kib().is_none());
1877
1878        // One core per CPU (no SMT sibling reconstruction possible).
1879        assert_eq!(llc.cores().len(), cpus.len());
1880        for &c in &cpus {
1881            assert_eq!(
1882                llc.cores().get(&c).map(|v| v.as_slice()),
1883                Some(&[c][..]),
1884                "each CPU must appear as its own single-sibling core",
1885            );
1886        }
1887        assert_eq!(llc.num_cores(), cpus.len());
1888    }
1889
1890    /// Zero CPUs is legal input (`from_system` would bail earlier
1891    /// with "no online CPUs found", but the helper itself must not
1892    /// panic): an empty LlcInfo with empty cores map.
1893    #[test]
1894    fn synthesize_fallback_llc_empty_cpus_returns_empty_llc() {
1895        let llc = synthesize_fallback_llc(&[], 0);
1896        assert!(llc.cpus().is_empty());
1897        assert_eq!(llc.numa_node(), 0);
1898        assert!(llc.cores().is_empty());
1899        // With empty cores map, num_cores falls back to cpus.len() == 0.
1900        assert_eq!(llc.num_cores(), 0);
1901    }
1902
1903    // -- TestTopology + LlcInfo PartialEq + Eq --
1904
1905    #[test]
1906    fn test_topology_partial_eq_equal_for_same_spec() {
1907        let spec = crate::vmm::topology::Topology::new(1, 2, 4, 2);
1908        let a = TestTopology::from_vm_topology(&spec);
1909        let b = TestTopology::from_vm_topology(&spec);
1910        assert_eq!(a, b);
1911    }
1912
1913    #[test]
1914    fn test_topology_partial_eq_differs_for_different_spec() {
1915        let spec_a = crate::vmm::topology::Topology::new(1, 2, 4, 2);
1916        let spec_b = crate::vmm::topology::Topology::new(2, 4, 4, 2);
1917        let a = TestTopology::from_vm_topology(&spec_a);
1918        let b = TestTopology::from_vm_topology(&spec_b);
1919        assert_ne!(a, b);
1920    }
1921
1922    #[test]
1923    fn llc_info_partial_eq_equal_for_same_fields() {
1924        let a = synthesize_fallback_llc(&[0, 1], 0);
1925        let b = synthesize_fallback_llc(&[0, 1], 0);
1926        assert_eq!(a, b);
1927    }
1928
1929    #[test]
1930    fn llc_info_partial_eq_differs_for_different_cpus() {
1931        let a = synthesize_fallback_llc(&[0, 1], 0);
1932        let b = synthesize_fallback_llc(&[2, 3], 0);
1933        assert_ne!(a, b);
1934    }
1935
1936    #[test]
1937    fn mem_policy_partial_eq_default_equals_default() {
1938        use crate::workload::MemPolicy;
1939        assert_eq!(MemPolicy::default(), MemPolicy::Default);
1940        assert_ne!(MemPolicy::default(), MemPolicy::Local);
1941    }
1942}