ktstr/vmm/
topology.rs

1/// CPU topology specification with NUMA memory topology.
2///
3/// Models the hierarchy: NUMA nodes → LLCs → cores → threads.
4///
5/// Each NUMA node owns a contiguous range of LLCs and a memory region.
6/// When `nodes` is `None` (the default), memory and LLCs are distributed
7/// uniformly across `numa_nodes` synthetic nodes with 10/20 distances.
8///
9/// Use [`new`](Self::new) for the simple uniform case, or
10/// [`with_nodes`](Self::with_nodes) for explicit per-node configuration.
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
12pub struct Topology {
13    /// Total number of last-level caches across the whole VM; must be
14    /// a multiple of `numa_nodes` when `nodes` is `None`.
15    pub llcs: u32,
16    /// Physical cores grouped into each LLC. When `llc_cores` is `Some`,
17    /// this is the PACKING WIDTH (the max per-LLC core count): the APIC
18    /// ID block reserved for every LLC is sized to `cores_per_llc`, and
19    /// individual LLCs populate only their `llc_cores[i]` cores within
20    /// that block. When `llc_cores` is `None` (the uniform default),
21    /// every LLC has exactly `cores_per_llc` cores.
22    pub cores_per_llc: u32,
23    /// Hardware threads exposed per core (`1` = no SMT, `2` = SMT-2).
24    pub threads_per_core: u32,
25    /// Number of NUMA nodes.
26    pub numa_nodes: u32,
27    /// Per-node configuration. When `None`, LLCs and memory are
28    /// distributed uniformly. When `Some`, the slice length must
29    /// equal `numa_nodes` and the sum of all `NumaNode::llcs` must
30    /// equal `self.llcs`.
31    pub nodes: Option<&'static [NumaNode]>,
32    /// Inter-node distance matrix. When `None`, distances default to
33    /// 10 (local) / 20 (remote). When `Some`, the matrix dimension
34    /// must equal `numa_nodes`.
35    pub distances: Option<&'static NumaDistance>,
36    /// Per-LLC core count for NON-UNIFORM LLC sizing. `None` (the
37    /// default) means every LLC is uniform with `cores_per_llc` cores.
38    /// `Some(slice)` declares an uneven machine: `slice.len()` must
39    /// equal `llcs`, each entry must be in `1..=cores_per_llc`, and LLC
40    /// `i` gets `slice[i]` cores (`slice[i] * threads_per_core` logical
41    /// CPUs). The guest observes the uneven layout because APIC IDs are
42    /// packed into fixed-width per-LLC blocks (width = `cores_per_llc`)
43    /// but populated only up to each LLC's `slice[i]` — the same sparse
44    /// APIC-block mechanism a power-of-two-rounded uniform LLC already
45    /// uses, so no new ACPI/CPUID surface is required. Models chips
46    /// whose LLCs are not all the same size, the case that breaks
47    /// scheduler per-LLC math assuming equal-sized caches.
48    pub llc_cores: Option<&'static [u32]>,
49}
50
51/// Per-NUMA-node configuration.
52///
53/// `llcs = 0` models a CXL memory-only node: the node has RAM but no
54/// CPUs or LLCs. Such nodes appear in the SRAT memory affinity table
55/// and SLIT distance matrix but contribute no CPU affinity entries.
56#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
57pub struct NumaNode {
58    /// Number of LLCs owned by this node. Zero means memory-only (CXL).
59    pub llcs: u32,
60    /// Memory attached to this node in MiB.
61    pub memory_mib: u32,
62    /// HMAT access latency in nanoseconds. `None` uses the default
63    /// (100ns for CPU-bearing, 300ns for memory-only). Emitted as
64    /// an SLLBI access_latency entry in the HMAT table by
65    /// `write_hmat` in `x86_64/acpi/mod.rs`. x86_64 only — aarch64 does
66    /// not expose an HMAT-equivalent to the guest.
67    pub latency_ns: Option<u32>,
68    /// HMAT read bandwidth in MB/s. `None` uses the default
69    /// (51200 MB/s for CPU-bearing, 20480 MB/s for memory-only).
70    /// Emitted as an SLLBI access_bandwidth entry in the HMAT table
71    /// by `write_hmat` in `x86_64/acpi/mod.rs`. x86_64 only.
72    pub bandwidth_mbs: Option<u32>,
73    /// HMAT Type 2 memory-side cache. `None` means no cache entry
74    /// is emitted for this node. x86_64 only.
75    pub mem_side_cache: Option<MemSideCache>,
76}
77
78/// HMAT Type 2 memory-side cache descriptor.
79///
80/// Models a hardware cache between the CPU and memory on this node
81/// (e.g. CXL HDM decoder cache, HBM cache). Emitted as an HMAT
82/// Memory Side Cache Information Structure.
83///
84/// `associativity` and `write_policy` occupy 4-bit nibbles in the
85/// HMAT cache_attributes field. Values above 15 are invalid.
86#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
87pub struct MemSideCache {
88    /// Cache size in bytes.
89    pub size: u64,
90    /// Cache associativity (0=none, 1=direct-mapped, 2=complex).
91    /// Must be <= 15 (4-bit field).
92    pub associativity: u8,
93    /// Write policy (0=none, 1=write-back, 2=write-through).
94    /// Must be <= 15 (4-bit field).
95    pub write_policy: u8,
96    /// Cache line size in bytes.
97    pub line_size: u16,
98}
99
100impl MemSideCache {
101    /// Const constructor with validation.
102    ///
103    /// # Panics
104    ///
105    /// Panics if `associativity > 15` or `write_policy > 15`
106    /// (4-bit HMAT nibble fields).
107    pub const fn new(size: u64, associativity: u8, write_policy: u8, line_size: u16) -> Self {
108        assert!(
109            associativity <= 15,
110            "MemSideCache: associativity must fit in 4 bits (0-15)"
111        );
112        assert!(
113            write_policy <= 15,
114            "MemSideCache: write_policy must fit in 4 bits (0-15)"
115        );
116        Self {
117            size,
118            associativity,
119            write_policy,
120            line_size,
121        }
122    }
123
124    /// Non-panicking validation.
125    pub fn validate(&self) -> Result<(), String> {
126        if self.associativity > 15 {
127            return Err(format!(
128                "associativity {} exceeds 4-bit maximum (15)",
129                self.associativity
130            ));
131        }
132        if self.write_policy > 15 {
133            return Err(format!(
134                "write_policy {} exceeds 4-bit maximum (15)",
135                self.write_policy
136            ));
137        }
138        Ok(())
139    }
140}
141
142impl NumaNode {
143    /// Const constructor.
144    pub const fn new(llcs: u32, memory_mib: u32) -> Self {
145        Self {
146            llcs,
147            memory_mib,
148            latency_ns: None,
149            bandwidth_mbs: None,
150            mem_side_cache: None,
151        }
152    }
153
154    /// Const constructor with HMAT attributes.
155    pub const fn with_hmat(
156        llcs: u32,
157        memory_mib: u32,
158        latency_ns: u32,
159        bandwidth_mbs: u32,
160    ) -> Self {
161        Self {
162            llcs,
163            memory_mib,
164            latency_ns: Some(latency_ns),
165            bandwidth_mbs: Some(bandwidth_mbs),
166            mem_side_cache: None,
167        }
168    }
169
170    /// Attach a memory-side cache descriptor.
171    pub const fn cache(mut self, cache: MemSideCache) -> Self {
172        self.mem_side_cache = Some(cache);
173        self
174    }
175
176    /// Whether this is a memory-only node (CXL: has RAM but no CPUs).
177    pub const fn is_memory_only(&self) -> bool {
178        self.llcs == 0
179    }
180}
181
182/// NxN inter-NUMA-node distance matrix.
183///
184/// Stored as a flat row-major array. ACPI SLIT requires diagonal = 10
185/// and off-diagonal > 10. ktstr additionally enforces symmetry.
186///
187/// Construct via [`NumaDistance::new`] which validates all invariants
188/// at const-eval time.
189#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
190pub struct NumaDistance {
191    /// Number of NUMA nodes (matrix is `n x n`).
192    n: u32,
193    /// Row-major distance values. Length must be `n * n`.
194    entries: &'static [u8],
195}
196
197impl NumaDistance {
198    /// Const constructor with full validation.
199    ///
200    /// # Panics
201    ///
202    /// Panics if:
203    /// - `n == 0`
204    /// - `entries.len() != n * n`
205    /// - any diagonal entry is not 10
206    /// - any off-diagonal entry is not > 10
207    /// - the matrix is not symmetric
208    pub const fn new(n: u32, entries: &'static [u8]) -> Self {
209        assert!(n > 0, "NumaDistance: n must be > 0");
210        let expected = (n as usize) * (n as usize);
211        assert!(
212            entries.len() == expected,
213            "NumaDistance: entries.len() must equal n * n"
214        );
215        Self::validate_entries(n, entries);
216        Self { n, entries }
217    }
218
219    const fn validate_entries(n: u32, entries: &[u8]) {
220        let dim = n as usize;
221        let mut i = 0;
222        while i < dim {
223            let mut j = 0;
224            while j < dim {
225                let idx = i * dim + j;
226                if i == j {
227                    assert!(
228                        entries[idx] == 10,
229                        "NumaDistance: diagonal entry must be 10"
230                    );
231                } else {
232                    assert!(
233                        entries[idx] > 10,
234                        "NumaDistance: off-diagonal entry must be > 10"
235                    );
236                    let sym_idx = j * dim + i;
237                    assert!(
238                        entries[idx] == entries[sym_idx],
239                        "NumaDistance: matrix must be symmetric"
240                    );
241                }
242                j += 1;
243            }
244            i += 1;
245        }
246    }
247
248    /// Non-panicking validation.
249    pub fn validate(&self) -> Result<(), String> {
250        if self.n == 0 {
251            return Err("n must be > 0".into());
252        }
253        let expected = (self.n as usize) * (self.n as usize);
254        if self.entries.len() != expected {
255            return Err(format!(
256                "entries.len() ({}) must equal n * n ({})",
257                self.entries.len(),
258                expected
259            ));
260        }
261        let dim = self.n as usize;
262        for i in 0..dim {
263            for j in 0..dim {
264                let v = self.entries[i * dim + j];
265                if i == j {
266                    if v != 10 {
267                        return Err(format!("diagonal entry [{i}][{j}] is {v}, must be 10"));
268                    }
269                } else {
270                    if v <= 10 {
271                        return Err(format!(
272                            "off-diagonal entry [{i}][{j}] is {v}, must be > 10"
273                        ));
274                    }
275                    let sym = self.entries[j * dim + i];
276                    if v != sym {
277                        return Err(format!("asymmetric: [{i}][{j}]={v} != [{j}][{i}]={sym}"));
278                    }
279                }
280            }
281        }
282        Ok(())
283    }
284
285    /// Matrix dimension (number of NUMA nodes).
286    pub const fn dimension(&self) -> u32 {
287        self.n
288    }
289
290    /// Distance from node `i` to node `j`.
291    pub const fn distance(&self, i: u32, j: u32) -> u8 {
292        self.entries[(i as usize) * (self.n as usize) + (j as usize)]
293    }
294
295    /// Raw row-major entries.
296    pub const fn entries(&self) -> &[u8] {
297        self.entries
298    }
299}
300
301/// Formats as `{numa}n{llcs}l{cores}c{threads}t` — e.g. `1n2l4c2t` =
302/// 1 NUMA node, 2 LLCs, 4 cores/LLC, 2 threads/core.
303impl std::fmt::Display for Topology {
304    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
305        write!(
306            f,
307            "{}n{}l{}c{}t",
308            self.numa_nodes, self.llcs, self.cores_per_llc, self.threads_per_core,
309        )
310    }
311}
312
313/// Error returned by [`Topology`]'s [`std::str::FromStr`] impl when the input does not
314/// match the `{numa}n{llcs}l{cores}c{threads}t` format or violates a
315/// Topology invariant (each component > 0, `llcs % numa_nodes == 0`,
316/// no `u32` overflow on total CPU count).
317#[derive(Debug, Clone, PartialEq, Eq, Hash, thiserror::Error)]
318pub enum TopologyParseError {
319    /// The input did not match `{numa}n{llcs}l{cores}c{threads}t`.
320    /// Carries the offending input for diagnostics.
321    #[error(
322        "topology string {0:?} does not match \
323         {{numa}}n{{llcs}}l{{cores}}c{{threads}}t — e.g. \"1n2l4c2t\""
324    )]
325    BadFormat(String),
326    /// A component (numa, llcs, cores, threads) was not a positive
327    /// integer (parse error, leading sign, zero).
328    #[error("topology component {0:?} must be a positive integer")]
329    BadComponent(String),
330    /// `llcs` is not a positive multiple of `numa_nodes`. Required by
331    /// [`Topology::new`] to evenly partition LLCs across NUMA nodes.
332    #[error("llcs ({llcs}) must be a positive multiple of numa_nodes ({numa_nodes})")]
333    NotMultiple { llcs: u32, numa_nodes: u32 },
334    /// The total CPU count (`llcs * cores_per_llc * threads_per_core`)
335    /// overflows `u32`. Required by [`Topology::new`] to ensure CPU
336    /// IDs fit in `u32`.
337    #[error("topology total CPU count overflows u32")]
338    Overflow,
339}
340
341/// Parse the [`Display`](#impl-Display-for-Topology) format back into a
342/// uniform `Topology` with `nodes = None` and `distances = None`.
343///
344/// # Lossy round-trip
345///
346/// Only topologies built via [`Topology::new`] (uniform layout, no
347/// per-node configuration, default 10/20 distances) round-trip cleanly
348/// through [`Display`](#impl-Display-for-Topology) → `FromStr`. A
349/// `Topology` built via [`Topology::with_nodes`] or chained with
350/// [`Topology::distances`] loses its per-node config + custom distance
351/// matrix through `Display` (which serializes only the 4 primitives);
352/// `FromStr` cannot reconstruct that information and produces a uniform
353/// `Topology` instead. Use the `Topology` value directly when full
354/// fidelity is required.
355impl std::str::FromStr for Topology {
356    type Err = TopologyParseError;
357
358    fn from_str(s: &str) -> Result<Self, Self::Err> {
359        let bad_format = || TopologyParseError::BadFormat(s.to_string());
360        let (numa_str, rest) = s.split_once('n').ok_or_else(bad_format)?;
361        let (llcs_str, rest) = rest.split_once('l').ok_or_else(bad_format)?;
362        let (cores_str, rest) = rest.split_once('c').ok_or_else(bad_format)?;
363        let (threads_str, tail) = rest.split_once('t').ok_or_else(bad_format)?;
364        if !tail.is_empty() {
365            return Err(bad_format());
366        }
367        let parse = |c: &str| -> Result<u32, TopologyParseError> {
368            let v: u32 = c
369                .parse()
370                .map_err(|_| TopologyParseError::BadComponent(c.to_string()))?;
371            if v == 0 {
372                return Err(TopologyParseError::BadComponent(c.to_string()));
373            }
374            Ok(v)
375        };
376        let numa_nodes = parse(numa_str)?;
377        let llcs = parse(llcs_str)?;
378        let cores_per_llc = parse(cores_str)?;
379        let threads_per_core = parse(threads_str)?;
380        if !llcs.is_multiple_of(numa_nodes) {
381            return Err(TopologyParseError::NotMultiple { llcs, numa_nodes });
382        }
383        let cpus_per_llc = cores_per_llc
384            .checked_mul(threads_per_core)
385            .ok_or(TopologyParseError::Overflow)?;
386        llcs.checked_mul(cpus_per_llc)
387            .ok_or(TopologyParseError::Overflow)?;
388        Ok(Topology {
389            llcs,
390            cores_per_llc,
391            threads_per_core,
392            numa_nodes,
393            nodes: None,
394            distances: None,
395            llc_cores: None,
396        })
397    }
398}
399
400impl Topology {
401    /// Fallback topology used by
402    /// [`Payload::topology`](crate::test_support::Payload::topology)
403    /// for binary-kind payloads that have no scheduler-side topology
404    /// opinion. Matches the inline default in
405    /// [`KtstrTestEntry::DEFAULT`](crate::test_support::KtstrTestEntry::DEFAULT):
406    /// 1 NUMA node / 1 LLC / 2 cores / 1 thread (2 CPUs total), the
407    /// smallest VM shape that runs the harness meaningfully.
408    pub const DEFAULT_FOR_PAYLOAD: Topology = Topology {
409        llcs: 1,
410        cores_per_llc: 2,
411        threads_per_core: 1,
412        numa_nodes: 1,
413        nodes: None,
414        distances: None,
415        llc_cores: None,
416    };
417
418    /// Validated const constructor for uniform topologies.
419    ///
420    /// Produces a topology where LLCs and memory are distributed evenly
421    /// across NUMA nodes, with default 10/20 distances.
422    ///
423    /// See [`validate`](Self::validate) for a non-panicking alternative.
424    ///
425    /// # Panics
426    ///
427    /// Panics if any invariant is violated:
428    /// - any of `llcs`, `cores_per_llc`, `threads_per_core`,
429    ///   `numa_nodes` is zero
430    /// - `llcs` is not divisible by `numa_nodes`
431    /// - total CPU count (`llcs * cores_per_llc * threads_per_core`)
432    ///   overflows `u32`
433    pub const fn new(
434        numa_nodes: u32,
435        llcs: u32,
436        cores_per_llc: u32,
437        threads_per_core: u32,
438    ) -> Self {
439        assert!(llcs > 0, "invalid Topology: llcs must be > 0");
440        assert!(
441            cores_per_llc > 0,
442            "invalid Topology: cores_per_llc must be > 0"
443        );
444        assert!(
445            threads_per_core > 0,
446            "invalid Topology: threads_per_core must be > 0"
447        );
448        assert!(numa_nodes > 0, "invalid Topology: numa_nodes must be > 0");
449        assert!(
450            llcs.is_multiple_of(numa_nodes),
451            "invalid Topology: llcs must be divisible by numa_nodes"
452        );
453        let cpus_per_llc = match cores_per_llc.checked_mul(threads_per_core) {
454            Some(v) => v,
455            None => panic!("invalid Topology: total CPU count overflows u32"),
456        };
457        match llcs.checked_mul(cpus_per_llc) {
458            Some(_) => {}
459            None => panic!("invalid Topology: total CPU count overflows u32"),
460        };
461        Topology {
462            llcs,
463            cores_per_llc,
464            threads_per_core,
465            numa_nodes,
466            nodes: None,
467            distances: None,
468            llc_cores: None,
469        }
470    }
471
472    /// Const constructor with explicit per-node configuration.
473    ///
474    /// Total LLC count is computed from the sum of `NumaNode::llcs`
475    /// across all nodes. Memory-only nodes (llcs=0) are permitted.
476    ///
477    /// # Panics
478    ///
479    /// Panics if:
480    /// - `nodes` is empty
481    /// - `cores_per_llc == 0`
482    /// - `threads_per_core == 0`
483    /// - node LLC sum overflows `u32`
484    /// - a CPU-bearing node (`llcs > 0`) has `memory_mib == 0`
485    /// - total CPU count overflows `u32`
486    /// - no node has LLCs (at least one must have `llcs > 0`)
487    pub const fn with_nodes(
488        cores_per_llc: u32,
489        threads_per_core: u32,
490        nodes: &'static [NumaNode],
491    ) -> Self {
492        assert!(
493            !nodes.is_empty(),
494            "invalid Topology: nodes must not be empty"
495        );
496        assert!(
497            cores_per_llc > 0,
498            "invalid Topology: cores_per_llc must be > 0"
499        );
500        assert!(
501            threads_per_core > 0,
502            "invalid Topology: threads_per_core must be > 0"
503        );
504
505        let mut llcs: u32 = 0;
506        let mut i = 0;
507        while i < nodes.len() {
508            llcs = match llcs.checked_add(nodes[i].llcs) {
509                Some(v) => v,
510                None => panic!("invalid Topology: node LLC sum overflows u32"),
511            };
512            assert!(
513                !(nodes[i].llcs > 0 && nodes[i].memory_mib == 0),
514                "invalid Topology: CPU-bearing node has zero memory"
515            );
516            i += 1;
517        }
518        assert!(llcs > 0, "invalid Topology: total LLCs must be > 0");
519
520        let cpus_per_llc = match cores_per_llc.checked_mul(threads_per_core) {
521            Some(v) => v,
522            None => panic!("invalid Topology: total CPU count overflows u32"),
523        };
524        match llcs.checked_mul(cpus_per_llc) {
525            Some(_) => {}
526            None => panic!("invalid Topology: total CPU count overflows u32"),
527        };
528
529        Topology {
530            llcs,
531            cores_per_llc,
532            threads_per_core,
533            numa_nodes: nodes.len() as u32,
534            nodes: Some(nodes),
535            distances: None,
536            llc_cores: None,
537        }
538    }
539
540    /// Attach a distance matrix.
541    ///
542    /// # Panics
543    ///
544    /// Panics if `distances.n != self.numa_nodes` — the matrix
545    /// dimension must equal the topology's NUMA node count.
546    pub const fn distances(mut self, distances: &'static NumaDistance) -> Self {
547        assert!(
548            distances.n == self.numa_nodes,
549            "invalid Topology: NumaDistance dimension must equal numa_nodes"
550        );
551        self.distances = Some(distances);
552        self
553    }
554
555    /// Non-panicking validation.
556    ///
557    /// Returns `Ok(())` if all invariants hold, or `Err` with a
558    /// description of the first violated invariant.
559    pub fn validate(&self) -> Result<(), String> {
560        if self.llcs == 0 {
561            return Err("llcs must be > 0".into());
562        }
563        if self.cores_per_llc == 0 {
564            return Err("cores_per_llc must be > 0".into());
565        }
566        if self.threads_per_core == 0 {
567            return Err("threads_per_core must be > 0".into());
568        }
569        if self.numa_nodes == 0 {
570            return Err("numa_nodes must be > 0".into());
571        }
572        if self
573            .cores_per_llc
574            .checked_mul(self.threads_per_core)
575            .and_then(|x| self.llcs.checked_mul(x))
576            .is_none()
577        {
578            return Err("total CPU count overflows u32".into());
579        }
580        match &self.nodes {
581            None => {
582                if !self.llcs.is_multiple_of(self.numa_nodes) {
583                    return Err(format!(
584                        "llcs ({}) must be divisible by numa_nodes ({})",
585                        self.llcs, self.numa_nodes,
586                    ));
587                }
588            }
589            Some(nodes) => {
590                if nodes.len() != self.numa_nodes as usize {
591                    return Err(format!(
592                        "nodes.len() ({}) must equal numa_nodes ({})",
593                        nodes.len(),
594                        self.numa_nodes,
595                    ));
596                }
597                let llc_sum: u32 = nodes.iter().map(|n| n.llcs).sum();
598                if llc_sum != self.llcs {
599                    return Err(format!(
600                        "sum of node LLCs ({llc_sum}) must equal total llcs ({})",
601                        self.llcs,
602                    ));
603                }
604                for (i, node) in nodes.iter().enumerate() {
605                    if node.llcs > 0 && node.memory_mib == 0 {
606                        return Err(format!("node {i} has {} LLCs but zero memory", node.llcs,));
607                    }
608                }
609            }
610        }
611        if let Some(d) = &self.distances {
612            if d.n != self.numa_nodes {
613                return Err(format!(
614                    "NumaDistance dimension ({}) must equal numa_nodes ({})",
615                    d.n, self.numa_nodes,
616                ));
617            }
618            d.validate()?;
619        }
620        if let Some(llc_cores) = self.llc_cores {
621            // len must equal llcs; each entry in 1..=cores_per_llc so the
622            // per-LLC APIC block (width = cores_per_llc) can hold it. The
623            // packing-width invariant is what keeps guest LLC grouping
624            // (apicid >> core_shift) correct across uneven LLCs.
625            if llc_cores.len() != self.llcs as usize {
626                return Err(format!(
627                    "llc_cores.len() ({}) must equal llcs ({})",
628                    llc_cores.len(),
629                    self.llcs,
630                ));
631            }
632            for (i, &cores) in llc_cores.iter().enumerate() {
633                if cores == 0 {
634                    return Err(format!("llc_cores[{i}] must be > 0"));
635                }
636                if cores > self.cores_per_llc {
637                    return Err(format!(
638                        "llc_cores[{i}] ({cores}) exceeds cores_per_llc packing width ({})",
639                        self.cores_per_llc,
640                    ));
641                }
642            }
643        }
644        Ok(())
645    }
646
647    /// Total vCPU count. Uniform: `llcs * cores_per_llc *
648    /// threads_per_core`. Non-uniform (`llc_cores` set): `(sum of
649    /// per-LLC cores) * threads_per_core`.
650    pub fn total_cpus(&self) -> u32 {
651        match self.llc_cores {
652            None => self.llcs * self.cores_per_llc * self.threads_per_core,
653            Some(cores) => cores.iter().sum::<u32>() * self.threads_per_core,
654        }
655    }
656
657    /// Cores in LLC `i`: `cores_per_llc` uniform, else `llc_cores[i]`.
658    pub fn cores_in_llc(&self, llc: u32) -> u32 {
659        match self.llc_cores {
660            None => self.cores_per_llc,
661            Some(cores) => cores[llc as usize],
662        }
663    }
664
665    /// Number of LLC domains in the topology.
666    pub fn num_llcs(&self) -> u32 {
667        self.llcs
668    }
669
670    /// Number of NUMA nodes in the topology.
671    pub fn num_numa_nodes(&self) -> u32 {
672        self.numa_nodes
673    }
674
675    /// LLCs owned by NUMA node `node_id`.
676    ///
677    /// With explicit nodes, returns `nodes[node_id].llcs`.
678    /// With uniform distribution, returns `llcs / numa_nodes`.
679    pub fn llcs_in_node(&self, node_id: u32) -> u32 {
680        match &self.nodes {
681            Some(nodes) => nodes[node_id as usize].llcs,
682            None => self.llcs / self.numa_nodes,
683        }
684    }
685
686    /// LLCs per NUMA node (uniform distribution only).
687    ///
688    /// # Panics
689    ///
690    /// Panics if the topology uses explicit nodes (use
691    /// [`llcs_in_node`](Self::llcs_in_node) instead), if
692    /// `numa_nodes == 0`, or if `llcs` is not divisible by
693    /// `numa_nodes`.
694    pub fn llcs_per_numa_node(&self) -> u32 {
695        assert!(
696            self.nodes.is_none(),
697            "llcs_per_numa_node() requires uniform topology; use llcs_in_node() instead"
698        );
699        assert!(self.numa_nodes > 0, "numa_nodes must be > 0");
700        assert!(
701            self.llcs.is_multiple_of(self.numa_nodes),
702            "llcs ({}) must be divisible by numa_nodes ({})",
703            self.llcs,
704            self.numa_nodes,
705        );
706        self.llcs / self.numa_nodes
707    }
708
709    /// NUMA node that owns the given LLC index.
710    ///
711    /// With explicit nodes, walks the node list to find the owning node.
712    /// With uniform distribution, computes `llc_id / llcs_per_node`.
713    ///
714    /// Out-of-bounds `llc_id` (>= total LLCs): with explicit nodes,
715    /// saturates to the last node index; with uniform distribution, no
716    /// bounds check — returns `llc_id / llcs_per_node`, which may
717    /// exceed `numa_nodes - 1`.
718    pub fn numa_node_of(&self, llc_id: u32) -> u32 {
719        match &self.nodes {
720            Some(nodes) => {
721                let mut cumulative: u32 = 0;
722                for (i, node) in nodes.iter().enumerate() {
723                    cumulative += node.llcs;
724                    if llc_id < cumulative {
725                        return i as u32;
726                    }
727                }
728                (nodes.len() - 1) as u32
729            }
730            None => {
731                let per_node = self.llcs / self.numa_nodes;
732                llc_id / per_node
733            }
734        }
735    }
736
737    /// First LLC index owned by NUMA node `node_id`.
738    ///
739    /// Uniform topologies do not bounds-check and return
740    /// `node_id * llcs_per_node` for any input.
741    ///
742    /// # Panics
743    ///
744    /// Panics if `node_id > numa_nodes` for explicit-node topologies
745    /// (the walk would index past the end of the node slice).
746    pub fn first_llc_in_node(&self, node_id: u32) -> u32 {
747        match &self.nodes {
748            Some(nodes) => {
749                let mut offset: u32 = 0;
750                for i in 0..node_id as usize {
751                    offset += nodes[i].llcs;
752                }
753                offset
754            }
755            None => {
756                let per_node = self.llcs / self.numa_nodes;
757                node_id * per_node
758            }
759        }
760    }
761
762    /// Memory in MiB for NUMA node `node_id`.
763    ///
764    /// With explicit nodes, returns `nodes[node_id].memory_mib`.
765    /// With uniform distribution, returns `None` (caller must divide
766    /// total memory evenly).
767    pub fn node_memory_mib(&self, node_id: u32) -> Option<u32> {
768        self.nodes.map(|nodes| nodes[node_id as usize].memory_mib)
769    }
770
771    /// Total memory across all explicit nodes, or `None` for uniform.
772    pub fn total_node_memory_mib(&self) -> Option<u32> {
773        self.nodes
774            .map(|nodes| nodes.iter().map(|n| n.memory_mib).sum())
775    }
776
777    /// Distance from node `i` to node `j`.
778    ///
779    /// Returns the explicit distance if a matrix is attached,
780    /// otherwise 10 for local and 20 for remote.
781    pub fn distance(&self, i: u32, j: u32) -> u8 {
782        match &self.distances {
783            Some(d) => d.distance(i, j),
784            None => {
785                if i == j {
786                    10
787                } else {
788                    20
789                }
790            }
791        }
792    }
793
794    /// Whether any node is memory-only (CXL).
795    pub fn has_memory_only_nodes(&self) -> bool {
796        self.nodes
797            .is_some_and(|nodes| nodes.iter().any(|n| n.is_memory_only()))
798    }
799
800    /// Number of nodes that have CPUs (non-memory-only).
801    pub fn cpu_bearing_nodes(&self) -> u32 {
802        match &self.nodes {
803            Some(nodes) => nodes.iter().filter(|n| !n.is_memory_only()).count() as u32,
804            None => self.numa_nodes,
805        }
806    }
807
808    /// Decompose a logical CPU ID into (llc, core, thread).
809    ///
810    /// CPU IDs are dense (`0..total_cpus`) and laid out LLC-major. For
811    /// the uniform layout this is plain division. For a non-uniform
812    /// (`llc_cores`) machine the LLC boundaries fall at the running
813    /// prefix sums of `llc_cores[i] * threads_per_core`, so the LLC is
814    /// found by walking those prefix sums; `core_id` is always in
815    /// `0..cores_in_llc(llc)` and packs into that LLC's fixed-width
816    /// APIC block in the x86_64 `apic_id` synthesis.
817    pub fn decompose(&self, cpu_id: u32) -> (u32, u32, u32) {
818        let threads = self.threads_per_core;
819        let thread_id = cpu_id % threads;
820        match self.llc_cores {
821            None => {
822                let cores = self.cores_per_llc;
823                let core_id = (cpu_id / threads) % cores;
824                let llc_id = cpu_id / (threads * cores);
825                (llc_id, core_id, thread_id)
826            }
827            Some(llc_cores) => {
828                let mut remaining = cpu_id / threads; // core index, LLC-major
829                for (llc, &cores) in llc_cores.iter().enumerate() {
830                    if remaining < cores {
831                        return (llc as u32, remaining, thread_id);
832                    }
833                    remaining -= cores;
834                }
835                // cpu_id >= total_cpus: mirror the uniform path's
836                // wrap-free arithmetic by attributing overflow to the
837                // last LLC. Callers never pass out-of-range IDs (the
838                // vCPU loop is `0..total_cpus`); validate() guarantees
839                // a non-empty llc_cores.
840                let last = llc_cores.len() as u32 - 1;
841                (last, remaining, thread_id)
842            }
843        }
844    }
845}
846
847#[cfg(test)]
848mod tests {
849    use super::*;
850
851    #[test]
852    fn topology_total_cpus() {
853        let t = Topology {
854            llcs: 2,
855            cores_per_llc: 4,
856            threads_per_core: 2,
857            numa_nodes: 1,
858            nodes: None,
859            distances: None,
860            llc_cores: None,
861        };
862        assert_eq!(t.total_cpus(), 16);
863    }
864
865    #[test]
866    fn topology_num_llcs() {
867        let t = Topology {
868            llcs: 3,
869            cores_per_llc: 4,
870            threads_per_core: 2,
871            numa_nodes: 1,
872            nodes: None,
873            distances: None,
874            llc_cores: None,
875        };
876        assert_eq!(t.num_llcs(), 3);
877    }
878
879    #[test]
880    fn decompose_simple() {
881        let t = Topology {
882            llcs: 2,
883            cores_per_llc: 2,
884            threads_per_core: 2,
885            numa_nodes: 1,
886            nodes: None,
887            distances: None,
888            llc_cores: None,
889        };
890        assert_eq!(t.decompose(0), (0, 0, 0));
891        assert_eq!(t.decompose(1), (0, 0, 1));
892        assert_eq!(t.decompose(2), (0, 1, 0));
893        assert_eq!(t.decompose(3), (0, 1, 1));
894        assert_eq!(t.decompose(4), (1, 0, 0));
895        assert_eq!(t.decompose(5), (1, 0, 1));
896        assert_eq!(t.decompose(6), (1, 1, 0));
897        assert_eq!(t.decompose(7), (1, 1, 1));
898    }
899
900    #[test]
901    fn decompose_no_smt() {
902        let t = Topology {
903            llcs: 2,
904            cores_per_llc: 4,
905            threads_per_core: 1,
906            numa_nodes: 1,
907            nodes: None,
908            distances: None,
909            llc_cores: None,
910        };
911        assert_eq!(t.decompose(0), (0, 0, 0));
912        assert_eq!(t.decompose(3), (0, 3, 0));
913        assert_eq!(t.decompose(4), (1, 0, 0));
914        assert_eq!(t.decompose(7), (1, 3, 0));
915    }
916
917    #[test]
918    fn decompose_single_llc() {
919        let t = Topology {
920            llcs: 1,
921            cores_per_llc: 4,
922            threads_per_core: 1,
923            numa_nodes: 1,
924            nodes: None,
925            distances: None,
926            llc_cores: None,
927        };
928        assert_eq!(t.decompose(0), (0, 0, 0));
929        assert_eq!(t.decompose(3), (0, 3, 0));
930    }
931
932    #[test]
933    fn non_uniform_llc_cores_total_and_partition() {
934        // 192cpu-11llc-smt's shape: ten LLCs of 9 cores + one of 6, SMT-2.
935        static CORES: [u32; 11] = [9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 6];
936        let t = Topology {
937            llcs: 11,
938            cores_per_llc: 9, // packing width (max per-LLC core count)
939            threads_per_core: 2,
940            numa_nodes: 1,
941            nodes: None,
942            distances: None,
943            llc_cores: Some(&CORES),
944        };
945        t.validate().expect("uneven topology must validate");
946        assert_eq!(t.total_cpus(), 192); // (9*10 + 6) * 2
947        // decompose partitions the dense 0..192 CPU space into 11 LLCs
948        // sized {18 x10, 12 x1} — the guest-visible uneven layout.
949        let mut sizes = [0u32; 11];
950        let mut prev_llc = 0;
951        for cpu in 0..t.total_cpus() {
952            let (llc, core, thread) = t.decompose(cpu);
953            assert!(llc < 11);
954            assert!(core < t.cores_in_llc(llc));
955            assert!(thread < 2);
956            // LLC index is monotonic non-decreasing over dense cpu_ids.
957            assert!(llc >= prev_llc);
958            prev_llc = llc;
959            sizes[llc as usize] += 1;
960        }
961        assert_eq!(sizes.iter().filter(|&&s| s == 18).count(), 10);
962        assert_eq!(sizes.iter().filter(|&&s| s == 12).count(), 1);
963        assert_eq!(sizes.iter().sum::<u32>(), 192);
964    }
965
966    #[test]
967    fn non_uniform_llc_cores_validate_rejects_bad() {
968        static BAD_LEN: [u32; 3] = [4, 4, 4];
969        let t = Topology {
970            llcs: 4, // len 3 != 4
971            cores_per_llc: 4,
972            threads_per_core: 1,
973            numa_nodes: 1,
974            nodes: None,
975            distances: None,
976            llc_cores: Some(&BAD_LEN),
977        };
978        assert!(t.validate().is_err());
979        static OVER_WIDTH: [u32; 2] = [4, 5]; // 5 > packing width 4
980        let t = Topology {
981            llcs: 2,
982            cores_per_llc: 4,
983            threads_per_core: 1,
984            numa_nodes: 1,
985            nodes: None,
986            distances: None,
987            llc_cores: Some(&OVER_WIDTH),
988        };
989        assert!(t.validate().is_err());
990    }
991
992    #[test]
993    fn numa_node_of_single_node() {
994        let t = Topology {
995            llcs: 4,
996            cores_per_llc: 2,
997            threads_per_core: 1,
998            numa_nodes: 1,
999            nodes: None,
1000            distances: None,
1001            llc_cores: None,
1002        };
1003        for llc in 0..4 {
1004            assert_eq!(t.numa_node_of(llc), 0);
1005        }
1006    }
1007
1008    #[test]
1009    fn numa_node_of_two_nodes() {
1010        let t = Topology {
1011            llcs: 4,
1012            cores_per_llc: 2,
1013            threads_per_core: 1,
1014            numa_nodes: 2,
1015            nodes: None,
1016            distances: None,
1017            llc_cores: None,
1018        };
1019        assert_eq!(t.llcs_per_numa_node(), 2);
1020        assert_eq!(t.numa_node_of(0), 0);
1021        assert_eq!(t.numa_node_of(1), 0);
1022        assert_eq!(t.numa_node_of(2), 1);
1023        assert_eq!(t.numa_node_of(3), 1);
1024    }
1025
1026    #[test]
1027    fn numa_node_of_out_of_bounds_explicit_saturates() {
1028        static TWO: [NumaNode; 2] = [NumaNode::new(2, 512), NumaNode::new(2, 512)];
1029        let t = Topology::with_nodes(2, 1, &TWO);
1030        // Total LLCs = 4. Any llc_id >= 4 must saturate to last node (1).
1031        assert_eq!(t.numa_node_of(4), 1);
1032        assert_eq!(t.numa_node_of(999), 1);
1033    }
1034
1035    #[test]
1036    fn numa_node_of_out_of_bounds_uniform_no_check() {
1037        // Uniform: numa_nodes=2, llcs=4 => llcs_per_node=2.
1038        // Per documented behavior: no bounds check, returns llc_id/2.
1039        let t = Topology::new(2, 4, 2, 1);
1040        assert_eq!(t.numa_node_of(100), 50);
1041        assert!(t.numa_node_of(100) > t.numa_nodes - 1);
1042    }
1043
1044    #[test]
1045    fn num_numa_nodes() {
1046        let t = Topology {
1047            llcs: 6,
1048            cores_per_llc: 4,
1049            threads_per_core: 2,
1050            numa_nodes: 3,
1051            nodes: None,
1052            distances: None,
1053            llc_cores: None,
1054        };
1055        assert_eq!(t.num_numa_nodes(), 3);
1056        assert_eq!(t.llcs_per_numa_node(), 2);
1057    }
1058
1059    #[test]
1060    #[should_panic(expected = "llcs_per_numa_node() requires uniform topology")]
1061    fn topology_llcs_per_numa_node_panics_on_explicit_nodes() {
1062        static EXPLICIT: [NumaNode; 2] = [NumaNode::new(2, 512), NumaNode::new(2, 512)];
1063        let t = Topology::with_nodes(2, 1, &EXPLICIT);
1064        t.llcs_per_numa_node();
1065    }
1066
1067    #[test]
1068    #[should_panic(expected = "numa_nodes must be > 0")]
1069    fn topology_llcs_per_numa_node_panics_on_zero_numa() {
1070        // Direct construction bypasses Topology::new's numa_nodes>0 assert.
1071        let t = Topology {
1072            llcs: 2,
1073            cores_per_llc: 1,
1074            threads_per_core: 1,
1075            numa_nodes: 0,
1076            nodes: None,
1077            distances: None,
1078            llc_cores: None,
1079        };
1080        t.llcs_per_numa_node();
1081    }
1082
1083    #[test]
1084    #[should_panic(expected = "must be divisible by numa_nodes")]
1085    fn topology_llcs_per_numa_node_panics_on_indivisible() {
1086        // 3 LLCs across 2 NUMA nodes — not evenly divisible.
1087        let t = Topology {
1088            llcs: 3,
1089            cores_per_llc: 1,
1090            threads_per_core: 1,
1091            numa_nodes: 2,
1092            nodes: None,
1093            distances: None,
1094            llc_cores: None,
1095        };
1096        t.llcs_per_numa_node();
1097    }
1098
1099    #[test]
1100    fn new_valid() {
1101        let t = Topology::new(2, 4, 2, 2);
1102        assert_eq!(t.numa_nodes, 2);
1103        assert_eq!(t.llcs, 4);
1104        assert_eq!(t.cores_per_llc, 2);
1105        assert_eq!(t.threads_per_core, 2);
1106        assert!(t.nodes.is_none());
1107        assert!(t.distances.is_none());
1108    }
1109
1110    #[test]
1111    fn new_single_everything() {
1112        let t = Topology::new(1, 1, 1, 1);
1113        assert_eq!(t.total_cpus(), 1);
1114    }
1115
1116    #[test]
1117    fn validate_valid() {
1118        let t = Topology {
1119            llcs: 4,
1120            cores_per_llc: 2,
1121            threads_per_core: 2,
1122            numa_nodes: 2,
1123            nodes: None,
1124            distances: None,
1125            llc_cores: None,
1126        };
1127        assert!(t.validate().is_ok());
1128    }
1129
1130    #[test]
1131    fn validate_zero_llcs() {
1132        let t = Topology {
1133            llcs: 0,
1134            cores_per_llc: 2,
1135            threads_per_core: 1,
1136            numa_nodes: 1,
1137            nodes: None,
1138            distances: None,
1139            llc_cores: None,
1140        };
1141        let err = t.validate().unwrap_err();
1142        assert!(err.contains("llcs must be > 0"), "got: {err}");
1143    }
1144
1145    #[test]
1146    fn validate_zero_cores() {
1147        let t = Topology {
1148            llcs: 1,
1149            cores_per_llc: 0,
1150            threads_per_core: 1,
1151            numa_nodes: 1,
1152            nodes: None,
1153            distances: None,
1154            llc_cores: None,
1155        };
1156        let err = t.validate().unwrap_err();
1157        assert!(err.contains("cores_per_llc must be > 0"), "got: {err}");
1158    }
1159
1160    #[test]
1161    fn validate_zero_threads() {
1162        let t = Topology {
1163            llcs: 1,
1164            cores_per_llc: 2,
1165            threads_per_core: 0,
1166            numa_nodes: 1,
1167            nodes: None,
1168            distances: None,
1169            llc_cores: None,
1170        };
1171        let err = t.validate().unwrap_err();
1172        assert!(err.contains("threads_per_core must be > 0"), "got: {err}");
1173    }
1174
1175    #[test]
1176    fn validate_zero_numa_nodes() {
1177        let t = Topology {
1178            llcs: 1,
1179            cores_per_llc: 2,
1180            threads_per_core: 1,
1181            numa_nodes: 0,
1182            nodes: None,
1183            distances: None,
1184            llc_cores: None,
1185        };
1186        let err = t.validate().unwrap_err();
1187        assert!(err.contains("numa_nodes must be > 0"), "got: {err}");
1188    }
1189
1190    #[test]
1191    fn validate_llcs_not_divisible_by_numa() {
1192        let t = Topology {
1193            llcs: 3,
1194            cores_per_llc: 2,
1195            threads_per_core: 1,
1196            numa_nodes: 2,
1197            nodes: None,
1198            distances: None,
1199            llc_cores: None,
1200        };
1201        let err = t.validate().unwrap_err();
1202        assert!(err.contains("divisible"), "got: {err}");
1203    }
1204
1205    #[test]
1206    #[should_panic(expected = "invalid Topology: numa_nodes must be > 0")]
1207    fn topology_new_panics_on_zero_numa() {
1208        Topology::new(0, 2, 1, 1);
1209    }
1210
1211    #[test]
1212    #[should_panic(expected = "invalid Topology: llcs must be > 0")]
1213    fn topology_new_panics_on_zero_llcs() {
1214        Topology::new(1, 0, 2, 1);
1215    }
1216
1217    #[test]
1218    #[should_panic(expected = "invalid Topology: cores_per_llc must be > 0")]
1219    fn topology_new_panics_on_zero_cores() {
1220        Topology::new(1, 1, 0, 1);
1221    }
1222
1223    #[test]
1224    #[should_panic(expected = "invalid Topology: threads_per_core must be > 0")]
1225    fn topology_new_panics_on_zero_threads() {
1226        Topology::new(1, 1, 2, 0);
1227    }
1228
1229    #[test]
1230    #[should_panic(expected = "invalid Topology: llcs must be divisible by numa_nodes")]
1231    fn topology_new_panics_on_indivisible() {
1232        Topology::new(2, 3, 2, 1);
1233    }
1234
1235    #[test]
1236    #[should_panic(expected = "invalid Topology: total CPU count overflows u32")]
1237    fn topology_new_panics_on_llcs_times_cpus_overflow() {
1238        // llcs * cpus_per_llc overflows at L439 (cores*threads = 65536*2 succeeds at L435).
1239        Topology::new(1, 65536, 65536, 2);
1240    }
1241
1242    #[test]
1243    #[should_panic(expected = "invalid Topology: total CPU count overflows u32")]
1244    fn topology_new_panics_on_cores_times_threads_overflow() {
1245        // cores_per_llc * threads_per_core = 65536 * 65536 = 2^32 overflows
1246        // at L435 BEFORE the llcs multiplication at L439.
1247        Topology::new(1, 1, 65_536, 65_536);
1248    }
1249
1250    #[test]
1251    fn validate_overflow() {
1252        let t = Topology {
1253            llcs: 65536,
1254            cores_per_llc: 65536,
1255            threads_per_core: 2,
1256            numa_nodes: 1,
1257            nodes: None,
1258            distances: None,
1259            llc_cores: None,
1260        };
1261        let err = t.validate().unwrap_err();
1262        assert!(err.contains("overflows"), "got: {err}");
1263    }
1264
1265    #[test]
1266    fn display_format() {
1267        let t = Topology {
1268            llcs: 2,
1269            cores_per_llc: 4,
1270            threads_per_core: 2,
1271            numa_nodes: 1,
1272            nodes: None,
1273            distances: None,
1274            llc_cores: None,
1275        };
1276        assert_eq!(t.to_string(), "1n2l4c2t");
1277    }
1278
1279    #[test]
1280    fn display_format_multi_numa() {
1281        let t = Topology {
1282            llcs: 4,
1283            cores_per_llc: 8,
1284            threads_per_core: 2,
1285            numa_nodes: 2,
1286            nodes: None,
1287            distances: None,
1288            llc_cores: None,
1289        };
1290        assert_eq!(t.to_string(), "2n4l8c2t");
1291    }
1292
1293    // -- NumaNode tests --
1294
1295    #[test]
1296    fn numa_node_memory_only() {
1297        let n = NumaNode::new(0, 1024);
1298        assert!(n.is_memory_only());
1299    }
1300
1301    #[test]
1302    fn numa_node_with_cpus() {
1303        let n = NumaNode::new(2, 512);
1304        assert!(!n.is_memory_only());
1305    }
1306
1307    // -- NumaDistance tests --
1308
1309    #[test]
1310    fn numa_distance_single_node() {
1311        static D: NumaDistance = NumaDistance::new(1, &[10]);
1312        assert_eq!(D.dimension(), 1);
1313        assert_eq!(D.distance(0, 0), 10);
1314    }
1315
1316    #[test]
1317    fn numa_distance_two_nodes() {
1318        static D: NumaDistance = NumaDistance::new(2, &[10, 20, 20, 10]);
1319        assert_eq!(D.dimension(), 2);
1320        assert_eq!(D.distance(0, 0), 10);
1321        assert_eq!(D.distance(0, 1), 20);
1322        assert_eq!(D.distance(1, 0), 20);
1323        assert_eq!(D.distance(1, 1), 10);
1324    }
1325
1326    #[test]
1327    fn numa_distance_three_nodes_varied_weights() {
1328        static D: NumaDistance = NumaDistance::new(3, &[10, 20, 30, 20, 10, 40, 30, 40, 10]);
1329        assert_eq!(D.distance(0, 2), 30);
1330        assert_eq!(D.distance(1, 2), 40);
1331    }
1332
1333    #[test]
1334    fn numa_distance_validate_ok() {
1335        let d = NumaDistance {
1336            n: 2,
1337            entries: &[10, 20, 20, 10],
1338        };
1339        assert!(d.validate().is_ok());
1340    }
1341
1342    #[test]
1343    fn numa_distance_validate_bad_diagonal() {
1344        let d = NumaDistance {
1345            n: 2,
1346            entries: &[11, 20, 20, 10],
1347        };
1348        let err = d.validate().unwrap_err();
1349        assert!(err.contains("diagonal"), "got: {err}");
1350    }
1351
1352    #[test]
1353    fn numa_distance_validate_bad_offdiag() {
1354        let d = NumaDistance {
1355            n: 2,
1356            entries: &[10, 10, 10, 10],
1357        };
1358        let err = d.validate().unwrap_err();
1359        assert!(err.contains("off-diagonal"), "got: {err}");
1360    }
1361
1362    #[test]
1363    fn numa_distance_validate_asymmetric() {
1364        let d = NumaDistance {
1365            n: 2,
1366            entries: &[10, 20, 30, 10],
1367        };
1368        let err = d.validate().unwrap_err();
1369        assert!(err.contains("asymmetric"), "got: {err}");
1370    }
1371
1372    #[test]
1373    fn numa_distance_validate_wrong_size() {
1374        let d = NumaDistance {
1375            n: 2,
1376            entries: &[10, 20, 20],
1377        };
1378        let err = d.validate().unwrap_err();
1379        assert!(err.contains("n * n"), "got: {err}");
1380    }
1381
1382    // -- with_nodes tests --
1383
1384    static TWO_NODES: [NumaNode; 2] = [NumaNode::new(2, 512), NumaNode::new(2, 512)];
1385
1386    #[test]
1387    fn with_nodes_basic() {
1388        let t = Topology::with_nodes(4, 2, &TWO_NODES);
1389        assert_eq!(t.numa_nodes, 2);
1390        assert_eq!(t.llcs, 4);
1391        assert_eq!(t.total_cpus(), 32);
1392        assert!(t.nodes.is_some());
1393    }
1394
1395    #[test]
1396    fn with_nodes_numa_node_of() {
1397        let t = Topology::with_nodes(4, 2, &TWO_NODES);
1398        assert_eq!(t.numa_node_of(0), 0);
1399        assert_eq!(t.numa_node_of(1), 0);
1400        assert_eq!(t.numa_node_of(2), 1);
1401        assert_eq!(t.numa_node_of(3), 1);
1402    }
1403
1404    static ASYMMETRIC_NODES: [NumaNode; 2] = [NumaNode::new(1, 256), NumaNode::new(3, 768)];
1405
1406    #[test]
1407    fn with_nodes_asymmetric_llcs() {
1408        let t = Topology::with_nodes(2, 1, &ASYMMETRIC_NODES);
1409        assert_eq!(t.llcs_in_node(0), 1);
1410        assert_eq!(t.llcs_in_node(1), 3);
1411        assert_eq!(t.numa_node_of(0), 0);
1412        assert_eq!(t.numa_node_of(1), 1);
1413        assert_eq!(t.numa_node_of(2), 1);
1414        assert_eq!(t.numa_node_of(3), 1);
1415        assert_eq!(t.first_llc_in_node(0), 0);
1416        assert_eq!(t.first_llc_in_node(1), 1);
1417    }
1418
1419    #[test]
1420    fn with_nodes_memory() {
1421        let t = Topology::with_nodes(2, 1, &ASYMMETRIC_NODES);
1422        assert_eq!(t.node_memory_mib(0), Some(256));
1423        assert_eq!(t.node_memory_mib(1), Some(768));
1424        assert_eq!(t.total_node_memory_mib(), Some(1024));
1425    }
1426
1427    // -- CXL memory-only node tests --
1428
1429    static CXL_NODES: [NumaNode; 3] = [
1430        NumaNode::new(2, 512),
1431        NumaNode::new(2, 512),
1432        NumaNode::new(0, 1024),
1433    ];
1434
1435    #[test]
1436    fn cxl_memory_only_node() {
1437        let t = Topology::with_nodes(4, 1, &CXL_NODES);
1438        assert_eq!(t.numa_nodes, 3);
1439        assert!(t.has_memory_only_nodes());
1440        assert_eq!(t.cpu_bearing_nodes(), 2);
1441        assert_eq!(t.llcs_in_node(2), 0);
1442        assert_eq!(t.node_memory_mib(2), Some(1024));
1443    }
1444
1445    #[test]
1446    fn cxl_first_llc_in_memory_only_node() {
1447        let t = Topology::with_nodes(4, 1, &CXL_NODES);
1448        assert_eq!(t.first_llc_in_node(0), 0);
1449        assert_eq!(t.first_llc_in_node(1), 2);
1450        assert_eq!(t.first_llc_in_node(2), 4);
1451    }
1452
1453    static CXL_MIDDLE: [NumaNode; 3] = [
1454        NumaNode::new(2, 512),
1455        NumaNode::new(0, 256),
1456        NumaNode::new(2, 512),
1457    ];
1458
1459    #[test]
1460    fn numa_node_of_cxl_middle_node() {
1461        let t = Topology::with_nodes(4, 1, &CXL_MIDDLE);
1462        assert_eq!(t.numa_nodes, 3);
1463        assert_eq!(t.numa_node_of(0), 0);
1464        assert_eq!(t.numa_node_of(1), 0);
1465        assert_eq!(t.numa_node_of(2), 2);
1466        assert_eq!(t.numa_node_of(3), 2);
1467        assert!(t.has_memory_only_nodes());
1468        assert_eq!(t.cpu_bearing_nodes(), 2);
1469    }
1470
1471    #[test]
1472    fn first_llc_in_cxl_middle_node() {
1473        let t = Topology::with_nodes(4, 1, &CXL_MIDDLE);
1474        assert_eq!(t.first_llc_in_node(0), 0);
1475        assert_eq!(t.first_llc_in_node(1), 2);
1476        assert_eq!(t.first_llc_in_node(2), 2);
1477        assert_eq!(t.llcs_in_node(1), 0);
1478        assert_eq!(t.llcs_in_node(2), 2);
1479    }
1480
1481    static CXL_FIRST: [NumaNode; 3] = [
1482        NumaNode::new(0, 256),
1483        NumaNode::new(2, 512),
1484        NumaNode::new(2, 512),
1485    ];
1486
1487    #[test]
1488    fn cxl_first_node_numa_node_of() {
1489        let t = Topology::with_nodes(4, 1, &CXL_FIRST);
1490        assert_eq!(t.numa_node_of(0), 1);
1491        assert_eq!(t.numa_node_of(1), 1);
1492        assert_eq!(t.numa_node_of(2), 2);
1493        assert_eq!(t.numa_node_of(3), 2);
1494        assert_eq!(t.first_llc_in_node(0), 0);
1495        assert_eq!(t.first_llc_in_node(1), 0);
1496        assert_eq!(t.first_llc_in_node(2), 2);
1497    }
1498
1499    static MULTI_CXL: [NumaNode; 4] = [
1500        NumaNode::new(2, 512),
1501        NumaNode::new(0, 256),
1502        NumaNode::new(0, 256),
1503        NumaNode::new(2, 512),
1504    ];
1505
1506    #[test]
1507    fn multiple_consecutive_cxl_nodes() {
1508        let t = Topology::with_nodes(4, 1, &MULTI_CXL);
1509        assert_eq!(t.numa_nodes, 4);
1510        assert_eq!(t.cpu_bearing_nodes(), 2);
1511        assert_eq!(t.numa_node_of(0), 0);
1512        assert_eq!(t.numa_node_of(1), 0);
1513        assert_eq!(t.numa_node_of(2), 3);
1514        assert_eq!(t.numa_node_of(3), 3);
1515    }
1516
1517    static ASYMMETRIC_HEAVY: [NumaNode; 2] = [NumaNode::new(1, 256), NumaNode::new(7, 1792)];
1518
1519    #[test]
1520    fn highly_asymmetric_llcs() {
1521        let t = Topology::with_nodes(2, 1, &ASYMMETRIC_HEAVY);
1522        assert_eq!(t.numa_node_of(0), 0);
1523        assert_eq!(t.numa_node_of(1), 1);
1524        assert_eq!(t.numa_node_of(7), 1);
1525        assert_eq!(t.llcs_in_node(0), 1);
1526        assert_eq!(t.llcs_in_node(1), 7);
1527    }
1528
1529    static CXL_DIST: NumaDistance = NumaDistance::new(3, &[10, 20, 30, 20, 10, 25, 30, 25, 10]);
1530
1531    #[test]
1532    fn distance_with_cxl_middle() {
1533        let t = Topology::with_nodes(4, 1, &CXL_MIDDLE).distances(&CXL_DIST);
1534        assert_eq!(t.distance(1, 2), 25);
1535        assert_eq!(t.distance(0, 1), 20);
1536        assert!(t.validate().is_ok());
1537    }
1538
1539    // -- distances tests --
1540
1541    static DIST_2: NumaDistance = NumaDistance::new(2, &[10, 20, 20, 10]);
1542
1543    #[test]
1544    fn distances() {
1545        let t = Topology::new(2, 4, 2, 1).distances(&DIST_2);
1546        assert_eq!(t.distance(0, 0), 10);
1547        assert_eq!(t.distance(0, 1), 20);
1548        assert_eq!(t.distance(1, 0), 20);
1549        assert_eq!(t.distance(1, 1), 10);
1550    }
1551
1552    #[test]
1553    fn default_distances() {
1554        let t = Topology::new(2, 4, 2, 1);
1555        assert_eq!(t.distance(0, 0), 10);
1556        assert_eq!(t.distance(0, 1), 20);
1557    }
1558
1559    static DIST_3: NumaDistance = NumaDistance::new(3, &[10, 20, 30, 20, 10, 25, 30, 25, 10]);
1560
1561    #[test]
1562    fn with_nodes_then_distances() {
1563        let t = Topology::with_nodes(4, 1, &CXL_NODES).distances(&DIST_3);
1564        assert_eq!(t.distance(0, 2), 30);
1565        assert_eq!(t.distance(1, 2), 25);
1566        assert!(t.validate().is_ok());
1567    }
1568
1569    // -- Validation with nodes --
1570
1571    #[test]
1572    fn validate_with_nodes_ok() {
1573        let t = Topology::with_nodes(4, 2, &TWO_NODES);
1574        assert!(t.validate().is_ok());
1575    }
1576
1577    #[test]
1578    fn validate_with_nodes_llc_mismatch() {
1579        static BAD: [NumaNode; 2] = [NumaNode::new(1, 256), NumaNode::new(1, 256)];
1580        let t = Topology {
1581            llcs: 4,
1582            cores_per_llc: 2,
1583            threads_per_core: 1,
1584            numa_nodes: 2,
1585            nodes: Some(&BAD),
1586            distances: None,
1587            llc_cores: None,
1588        };
1589        let err = t.validate().unwrap_err();
1590        assert!(err.contains("sum of node LLCs"), "got: {err}");
1591    }
1592
1593    #[test]
1594    fn validate_with_nodes_count_mismatch() {
1595        let t = Topology {
1596            llcs: 4,
1597            cores_per_llc: 2,
1598            threads_per_core: 1,
1599            numa_nodes: 3,
1600            nodes: Some(&TWO_NODES),
1601            distances: None,
1602            llc_cores: None,
1603        };
1604        let err = t.validate().unwrap_err();
1605        assert!(err.contains("nodes.len()"), "got: {err}");
1606    }
1607
1608    #[test]
1609    fn validate_distance_dimension_mismatch() {
1610        static BAD_DIST: NumaDistance = NumaDistance::new(1, &[10]);
1611        let t = Topology {
1612            llcs: 4,
1613            cores_per_llc: 2,
1614            threads_per_core: 1,
1615            numa_nodes: 2,
1616            nodes: None,
1617            distances: Some(&BAD_DIST),
1618            llc_cores: None,
1619        };
1620        let err = t.validate().unwrap_err();
1621        assert!(err.contains("dimension"), "got: {err}");
1622    }
1623
1624    #[test]
1625    fn validate_cpu_node_zero_memory() {
1626        static BAD: [NumaNode; 2] = [NumaNode::new(2, 0), NumaNode::new(2, 512)];
1627        let t = Topology {
1628            llcs: 4,
1629            cores_per_llc: 2,
1630            threads_per_core: 1,
1631            numa_nodes: 2,
1632            nodes: Some(&BAD),
1633            distances: None,
1634            llc_cores: None,
1635        };
1636        let err = t.validate().unwrap_err();
1637        assert!(err.contains("zero memory"), "got: {err}");
1638    }
1639
1640    #[test]
1641    fn uniform_no_node_memory() {
1642        let t = Topology::new(2, 4, 2, 1);
1643        assert!(t.node_memory_mib(0).is_none());
1644        assert!(t.total_node_memory_mib().is_none());
1645    }
1646
1647    // -- const construction smoke tests --
1648
1649    const _CONST_TOPO: Topology = Topology::new(1, 2, 4, 2);
1650
1651    static _CONST_NODES: [NumaNode; 2] = [NumaNode::new(1, 256), NumaNode::new(1, 256)];
1652    const _CONST_WITH_NODES: Topology = Topology::with_nodes(4, 2, &_CONST_NODES);
1653
1654    static _CONST_DIST: NumaDistance = NumaDistance::new(2, &[10, 20, 20, 10]);
1655    const _CONST_WITH_DISTANCES: Topology = Topology::new(2, 2, 4, 2).distances(&_CONST_DIST);
1656
1657    #[test]
1658    fn const_construction_valid() {
1659        assert!(_CONST_TOPO.validate().is_ok());
1660        assert!(_CONST_WITH_NODES.validate().is_ok());
1661        assert!(_CONST_WITH_DISTANCES.validate().is_ok());
1662    }
1663
1664    // -- single node edge case --
1665
1666    #[test]
1667    fn single_node_topology() {
1668        let t = Topology::new(1, 1, 1, 1);
1669        assert_eq!(t.total_cpus(), 1);
1670        assert_eq!(t.numa_node_of(0), 0);
1671        assert_eq!(t.distance(0, 0), 10);
1672        assert!(!t.has_memory_only_nodes());
1673        assert_eq!(t.cpu_bearing_nodes(), 1);
1674    }
1675
1676    #[test]
1677    fn first_llc_in_node_uniform() {
1678        let t = Topology::new(2, 4, 2, 1);
1679        assert_eq!(t.first_llc_in_node(0), 0);
1680        assert_eq!(t.first_llc_in_node(1), 2);
1681    }
1682
1683    #[test]
1684    fn first_llc_in_node_at_numa_nodes_returns_total() {
1685        // Documented behavior: node_id == numa_nodes does NOT panic for
1686        // explicit nodes; the walk sums all llcs and returns the total.
1687        let t = Topology::with_nodes(2, 1, &TWO_NODES);
1688        assert_eq!(t.first_llc_in_node(2), 4);
1689    }
1690
1691    #[test]
1692    #[should_panic(expected = "index out of bounds")]
1693    fn topology_first_llc_in_node_panics_on_index_above_numa_nodes() {
1694        // Documented behavior: node_id > numa_nodes indexes past the
1695        // end of the node slice on the walk, panicking.
1696        let t = Topology::with_nodes(2, 1, &TWO_NODES);
1697        let _ = t.first_llc_in_node(3);
1698    }
1699
1700    // -- Topology FromStr / Display round-trip (uniform topologies) --
1701
1702    #[test]
1703    fn topology_fromstr_display_roundtrip_uniform() {
1704        let t = Topology::new(2, 4, 8, 2);
1705        let s = t.to_string();
1706        assert_eq!(s, "2n4l8c2t");
1707        let parsed: Topology = s.parse().unwrap();
1708        assert_eq!(parsed, t);
1709    }
1710
1711    #[test]
1712    fn topology_fromstr_minimal() {
1713        let parsed: Topology = "1n1l1c1t".parse().unwrap();
1714        assert_eq!(parsed, Topology::new(1, 1, 1, 1));
1715    }
1716
1717    #[test]
1718    fn topology_fromstr_default_for_payload_roundtrip() {
1719        // Uniform DEFAULT_FOR_PAYLOAD round-trips cleanly.
1720        let s = Topology::DEFAULT_FOR_PAYLOAD.to_string();
1721        let parsed: Topology = s.parse().unwrap();
1722        assert_eq!(parsed, Topology::DEFAULT_FOR_PAYLOAD);
1723    }
1724
1725    #[test]
1726    fn topology_fromstr_rejects_empty() {
1727        let err = "".parse::<Topology>().unwrap_err();
1728        assert!(matches!(err, TopologyParseError::BadFormat(s) if s.is_empty()));
1729    }
1730
1731    #[test]
1732    fn topology_fromstr_rejects_missing_separator() {
1733        assert!(matches!(
1734            "1n2l4c".parse::<Topology>(),
1735            Err(TopologyParseError::BadFormat(_))
1736        ));
1737        assert!(matches!(
1738            "1n2l4c2".parse::<Topology>(),
1739            Err(TopologyParseError::BadFormat(_))
1740        ));
1741    }
1742
1743    #[test]
1744    fn topology_fromstr_rejects_trailing_garbage() {
1745        assert!(matches!(
1746            "1n2l4c2tjunk".parse::<Topology>(),
1747            Err(TopologyParseError::BadFormat(_))
1748        ));
1749    }
1750
1751    #[test]
1752    fn topology_fromstr_rejects_zero_component() {
1753        for s in ["0n1l1c1t", "1n0l1c1t", "1n1l0c1t", "1n1l1c0t"] {
1754            assert!(
1755                matches!(
1756                    s.parse::<Topology>(),
1757                    Err(TopologyParseError::BadComponent(_))
1758                ),
1759                "expected BadComponent for {s}",
1760            );
1761        }
1762    }
1763
1764    #[test]
1765    fn topology_fromstr_rejects_non_numeric() {
1766        assert!(matches!(
1767            "Xn1l1c1t".parse::<Topology>(),
1768            Err(TopologyParseError::BadComponent(_))
1769        ));
1770        assert!(matches!(
1771            "1n-1l1c1t".parse::<Topology>(),
1772            Err(TopologyParseError::BadComponent(_))
1773        ));
1774    }
1775
1776    #[test]
1777    fn topology_fromstr_rejects_llcs_not_multiple_of_numa_nodes() {
1778        // 2 NUMA nodes but 3 LLCs is not divisible.
1779        let err = "2n3l1c1t".parse::<Topology>().unwrap_err();
1780        assert!(matches!(
1781            err,
1782            TopologyParseError::NotMultiple {
1783                llcs: 3,
1784                numa_nodes: 2
1785            }
1786        ));
1787    }
1788
1789    #[test]
1790    fn topology_fromstr_rejects_total_cpu_overflow() {
1791        // 2 * 65536 = 131072 LLCs, * 65536 * 1 threads = overflow u32.
1792        // Pick numbers that overflow: cores_per_llc * threads_per_core overflows u32 first.
1793        let err = "1n1l65536c65537t".parse::<Topology>().unwrap_err();
1794        assert!(matches!(err, TopologyParseError::Overflow));
1795    }
1796
1797    #[test]
1798    fn topology_hash_consistent_with_eq() {
1799        use std::collections::HashSet;
1800        let t1 = Topology::new(2, 4, 8, 2);
1801        let t2 = Topology::new(2, 4, 8, 2);
1802        let mut set: HashSet<Topology> = HashSet::new();
1803        set.insert(t1);
1804        assert!(set.contains(&t2));
1805    }
1806
1807    #[test]
1808    fn numa_node_hash_consistent_with_eq() {
1809        use std::collections::HashSet;
1810        let n1 = NumaNode {
1811            llcs: 2,
1812            memory_mib: 4096,
1813            latency_ns: Some(100),
1814            bandwidth_mbs: Some(51200),
1815            mem_side_cache: None,
1816        };
1817        let n2 = NumaNode {
1818            llcs: 2,
1819            memory_mib: 4096,
1820            latency_ns: Some(100),
1821            bandwidth_mbs: Some(51200),
1822            mem_side_cache: None,
1823        };
1824        let mut set: HashSet<NumaNode> = HashSet::new();
1825        set.insert(n1);
1826        assert!(set.contains(&n2));
1827    }
1828
1829    #[test]
1830    fn topology_fromstr_per_node_topology_is_lossy() {
1831        // A Topology built via with_nodes carries per-node configuration
1832        // that does NOT survive the Display → FromStr round-trip.
1833        // Documented lossy behavior — verify the parsed result has
1834        // nodes = None and distances = None even when the source had
1835        // explicit per-node config.
1836        let original = Topology::with_nodes(2, 1, &TWO_NODES);
1837        let s = original.to_string();
1838        let parsed: Topology = s.parse().unwrap();
1839        assert!(parsed.nodes.is_none(), "FromStr must produce nodes = None");
1840        assert!(
1841            parsed.distances.is_none(),
1842            "FromStr must produce distances = None"
1843        );
1844        // The 4 uniform primitives DO survive.
1845        assert_eq!(parsed.numa_nodes, original.numa_nodes);
1846        assert_eq!(parsed.llcs, original.llcs);
1847        assert_eq!(parsed.cores_per_llc, original.cores_per_llc);
1848        assert_eq!(parsed.threads_per_core, original.threads_per_core);
1849    }
1850
1851    // -- MemSideCache::new should_panic cluster --
1852
1853    #[test]
1854    #[should_panic(expected = "MemSideCache: associativity must fit in 4 bits")]
1855    fn mem_side_cache_new_panics_on_associativity_above_15() {
1856        MemSideCache::new(4096, 16, 1, 64);
1857    }
1858
1859    #[test]
1860    #[should_panic(expected = "MemSideCache: write_policy must fit in 4 bits")]
1861    fn mem_side_cache_new_panics_on_write_policy_above_15() {
1862        MemSideCache::new(4096, 8, 16, 64);
1863    }
1864
1865    // -- NumaDistance::new should_panic cluster (ACPI SLIT invariants) --
1866
1867    #[test]
1868    #[should_panic(expected = "NumaDistance: n must be > 0")]
1869    fn numa_distance_new_panics_on_zero_n() {
1870        static EMPTY: [u8; 0] = [];
1871        NumaDistance::new(0, &EMPTY);
1872    }
1873
1874    #[test]
1875    #[should_panic(expected = "NumaDistance: entries.len() must equal n * n")]
1876    fn numa_distance_new_panics_on_size_mismatch() {
1877        static THREE_ENTRIES: [u8; 3] = [10, 20, 10];
1878        // n=2 expects 4 entries, but only 3 supplied.
1879        NumaDistance::new(2, &THREE_ENTRIES);
1880    }
1881
1882    #[test]
1883    #[should_panic(expected = "NumaDistance: diagonal entry must be 10")]
1884    fn numa_distance_new_panics_on_nonten_diagonal() {
1885        // n=2 with diagonal[0][0] = 9 instead of 10.
1886        static BAD_DIAG: [u8; 4] = [9, 20, 20, 10];
1887        NumaDistance::new(2, &BAD_DIAG);
1888    }
1889
1890    #[test]
1891    #[should_panic(expected = "NumaDistance: off-diagonal entry must be > 10")]
1892    fn numa_distance_new_panics_on_offdiagonal_at_or_below_ten() {
1893        // n=2 with off-diagonal == 10 (must be > 10 per ACPI SLIT).
1894        static OFF_DIAG_TEN: [u8; 4] = [10, 10, 10, 10];
1895        NumaDistance::new(2, &OFF_DIAG_TEN);
1896    }
1897
1898    #[test]
1899    #[should_panic(expected = "NumaDistance: matrix must be symmetric")]
1900    fn numa_distance_new_panics_on_asymmetric_matrix() {
1901        // n=2 with entries[0][1] = 20 but entries[1][0] = 30.
1902        static ASYMMETRIC: [u8; 4] = [10, 20, 30, 10];
1903        NumaDistance::new(2, &ASYMMETRIC);
1904    }
1905
1906    // -- Topology::with_nodes should_panic cluster --
1907
1908    #[test]
1909    #[should_panic(expected = "invalid Topology: nodes must not be empty")]
1910    fn topology_with_nodes_panics_on_empty_nodes() {
1911        static EMPTY: [NumaNode; 0] = [];
1912        Topology::with_nodes(2, 1, &EMPTY);
1913    }
1914
1915    #[test]
1916    #[should_panic(expected = "invalid Topology: cores_per_llc must be > 0")]
1917    fn topology_with_nodes_panics_on_zero_cores() {
1918        static NODES: [NumaNode; 1] = [NumaNode::new(2, 512)];
1919        Topology::with_nodes(0, 1, &NODES);
1920    }
1921
1922    #[test]
1923    #[should_panic(expected = "invalid Topology: threads_per_core must be > 0")]
1924    fn topology_with_nodes_panics_on_zero_threads() {
1925        static NODES: [NumaNode; 1] = [NumaNode::new(2, 512)];
1926        Topology::with_nodes(2, 0, &NODES);
1927    }
1928
1929    #[test]
1930    #[should_panic(expected = "invalid Topology: node LLC sum overflows u32")]
1931    fn topology_with_nodes_panics_on_llc_sum_overflow() {
1932        // iter 0: accumulator = 0 + u32::MAX = u32::MAX (OK; node is
1933        // cpu-bearing with non-zero memory so the L491 check passes).
1934        // iter 1: u32::MAX.checked_add(1) = None → panic at L489.
1935        static NODES: [NumaNode; 2] = [NumaNode::new(u32::MAX, 512), NumaNode::new(1, 512)];
1936        Topology::with_nodes(1, 1, &NODES);
1937    }
1938
1939    #[test]
1940    #[should_panic(expected = "invalid Topology: CPU-bearing node has zero memory")]
1941    fn topology_with_nodes_panics_on_cpu_node_zero_memory() {
1942        // llcs > 0 with memory_mib == 0 is rejected.
1943        static BAD_MEM: [NumaNode; 1] = [NumaNode::new(2, 0)];
1944        Topology::with_nodes(2, 1, &BAD_MEM);
1945    }
1946
1947    #[test]
1948    #[should_panic(expected = "invalid Topology: total LLCs must be > 0")]
1949    fn topology_with_nodes_panics_on_no_llcs() {
1950        // All memory-only nodes (llcs == 0) — total LLCs is 0.
1951        static MEMORY_ONLY: [NumaNode; 1] = [NumaNode::new(0, 512)];
1952        Topology::with_nodes(2, 1, &MEMORY_ONLY);
1953    }
1954
1955    #[test]
1956    #[should_panic(expected = "invalid Topology: total CPU count overflows u32")]
1957    fn topology_with_nodes_panics_on_cpu_count_overflow() {
1958        // cores_per_llc * threads_per_core overflows u32.
1959        static NODES: [NumaNode; 1] = [NumaNode::new(1, 512)];
1960        Topology::with_nodes(65_536, 65_536, &NODES);
1961    }
1962
1963    // -- Topology::distances should_panic test --
1964
1965    #[test]
1966    #[should_panic(expected = "invalid Topology: NumaDistance dimension must equal numa_nodes")]
1967    fn topology_distances_panics_on_dimension_mismatch() {
1968        // Topology has numa_nodes = 2 (uniform); attach a 3x3 distance
1969        // matrix. distances.n = 3 != 2 = numa_nodes → panic.
1970        static D3X3: [u8; 9] = [10, 20, 20, 20, 10, 20, 20, 20, 10];
1971        static DIST: NumaDistance = NumaDistance::new(3, &D3X3);
1972        Topology::new(2, 2, 1, 1).distances(&DIST);
1973    }
1974}