ktstr/
gauntlet.rs

1//! Gauntlet topology presets.
2//!
3//! See the [Gauntlet](https://ktstr.dev/guide/running-tests/gauntlet.html)
4//! chapter of the guide.
5
6use crate::vmm::Topology;
7
8/// A gauntlet topology preset.
9///
10/// Each preset defines a specific CPU topology for matrix testing.
11/// See [`gauntlet_presets()`] for the full set.
12pub struct TopoPreset {
13    pub name: &'static str,
14    /// Human-readable description; read by preset-audit tests only.
15    #[allow(dead_code)]
16    pub description: &'static str,
17    pub topology: Topology,
18    /// Memory budget for this preset's verifier VM.
19    ///
20    /// This caps the topology-derived 64 MiB/vCPU floor; deferred initramfs
21    /// sizing may still raise the actual guest allocation when the test
22    /// binary, kernel, or boot modules require more memory.
23    pub memory_mib: usize,
24    /// Forced no-perf host-CPU budget for cells running this preset.
25    /// `None` (every stock preset) leaves budget resolution to the
26    /// normal path (test's `cpu_budget`, else auto-size to vCPU count plus
27    /// one service CPU, clamped to the allowed cpuset).
28    /// `Some(n)` pins the no-perf CPU mask to `min(n, allowed host CPUs)`,
29    /// so a preset whose vCPU count exceeds `n` ALWAYS time-slices
30    /// (deliberate, continuous overcommit). On a host with fewer than `n`
31    /// allowed CPUs the budget collapses to the allowed set — deeper
32    /// overcommit, never a skip or hard error (a forced budget exists to
33    /// force overcommit; a smaller host just forces more of it). The
34    /// admission preflight and the verifier cell path apply the same
35    /// clamp. Consumed by the
36    /// verifier cell path ([`crate::verifier::collect_verifier_output`]).
37    /// The only preset that sets it (192cpu-11llc-smt) is also non-uniform,
38    /// hence verifier-only (the gauntlet path skips `llc_cores` presets —
39    /// see `for_each_gauntlet_variant`), so the forced budget is realized
40    /// exclusively in the verifier battery. A future uniform forced-budget
41    /// preset would additionally need the gauntlet variant path to honor
42    /// this field.
43    pub forced_cpu_budget: Option<u32>,
44}
45
46/// Topology presets used by gauntlet mode.
47///
48/// Covers topologies from `4cpu-1llc-nosmt` (4 CPUs) up through the
49/// `252cpu-14llc-smt` / `252cpu-14llc-nosmt` presets (252 CPUs,
50/// near the KVM vCPU limit), plus `192cpu-11llc-smt` (192 CPUs across 11
51/// NON-uniform LLCs), spanning SMT, non-SMT (`-nosmt`), and multi-NUMA
52/// (`2numa-*`, `4numa-*`) families. The stock presets are built from
53/// the `defs` / `numa_defs` tuple tables; `192cpu-11llc-smt` is appended
54/// explicitly because it carries per-LLC core counts and a forced CPU
55/// budget the uniform tuple shape cannot express.
56///
57/// `192cpu-11llc-smt` targets schedulers whose per-LLC math assumes
58/// equal-sized caches: ten LLCs of 18 logical CPUs and one of 12
59/// (`llc_cores = [9;10] + [6]`, packing width 9). It is VERIFIER-ONLY —
60/// the gauntlet execution path reconstructs topology from a uniform
61/// `TopoOverride` that cannot express `llc_cores`, so
62/// `for_each_gauntlet_variant` skips non-uniform presets. The verifier
63/// reaches it via
64/// [`crate::test_support::TopologyConstraints::accepts_verifier`], which
65/// ignores default caps and imposes NO host-size bound. Its
66/// `forced_cpu_budget = Some(96)` guarantees continuous overcommit (192
67/// vCPUs time-slicing over <=96 host CPUs) every time the battery runs.
68///
69/// The full set is returned unconditionally; the only filter applied
70/// here is the aarch64 retain below, which drops SMT presets
71/// (`threads_per_core > 1`) because ARM64 CPUs have no SMT (the
72/// non-SMT scale presets keep ARM64's topology scale
73/// coverage). The multi-NUMA presets are *not* filtered here: the
74/// default [`crate::test_support::TopologyConstraints`]
75/// (`max_numa_nodes: Some(1)`) excludes them at test-selection time
76/// (via `accepts` / `accepts_no_perf_mode`) unless a test raises
77/// the bound.
78pub fn gauntlet_presets() -> Vec<TopoPreset> {
79    let defs: &[(&str, &str, u32, u32, u32, usize)] = &[
80        ("4cpu-1llc-nosmt", "4 CPUs, 1 LLC", 1, 4, 1, 2048),
81        ("4cpu-2llc-nosmt", "4 CPUs, 2 LLCs", 2, 2, 1, 2048),
82        ("9cpu-3llc-nosmt", "9 CPUs, 3 LLCs (odd)", 3, 3, 1, 2048),
83        ("15cpu-5llc-nosmt", "15 CPUs, 5 LLCs (prime)", 5, 3, 1, 2048),
84        ("14cpu-7llc-nosmt", "14 CPUs, 7 LLCs (prime)", 7, 2, 1, 2048),
85        ("8cpu-2llc-smt", "8 CPUs, 2 LLCs with SMT", 2, 2, 2, 2048),
86        ("12cpu-3llc-smt", "12 CPUs, 3 LLCs with SMT", 3, 2, 2, 2048),
87        ("32cpu-4llc-smt", "32 CPUs, 4 LLCs", 4, 4, 2, 2048),
88        ("64cpu-8llc-smt", "64 CPUs, 8 LLCs", 8, 4, 2, 2048),
89        ("128cpu-4llc-smt", "128 CPUs, 4 LLCs", 4, 16, 2, 2048),
90        ("128cpu-8llc-smt", "128 CPUs, 8 LLCs", 8, 8, 2, 2048),
91        (
92            "240cpu-15llc-smt",
93            "240 CPUs, 15 LLCs with SMT",
94            15,
95            8,
96            2,
97            2048,
98        ),
99        (
100            "252cpu-14llc-smt",
101            "252 CPUs, 14 LLCs (near KVM vCPU limit)",
102            14,
103            9,
104            2,
105            4096,
106        ),
107        // Non-SMT scale presets for ARM64 coverage.
108        // These also run on x86_64 to test non-SMT topologies at scale.
109        (
110            "32cpu-4llc-nosmt",
111            "32 CPUs, 4 LLCs (no SMT)",
112            4,
113            8,
114            1,
115            2048,
116        ),
117        (
118            "64cpu-8llc-nosmt",
119            "64 CPUs, 8 LLCs (no SMT)",
120            8,
121            8,
122            1,
123            2048,
124        ),
125        (
126            "128cpu-4llc-nosmt",
127            "128 CPUs, 4 LLCs (no SMT)",
128            4,
129            32,
130            1,
131            2048,
132        ),
133        (
134            "128cpu-8llc-nosmt",
135            "128 CPUs, 8 LLCs (no SMT)",
136            8,
137            16,
138            1,
139            2048,
140        ),
141        (
142            "240cpu-15llc-nosmt",
143            "240 CPUs, 15 LLCs (no SMT)",
144            15,
145            16,
146            1,
147            2048,
148        ),
149        (
150            "252cpu-14llc-nosmt",
151            "252 CPUs, 14 LLCs (no SMT, near KVM vCPU limit)",
152            14,
153            18,
154            1,
155            4096,
156        ),
157    ];
158    let numa_defs: &[(&str, &str, u32, u32, u32, u32, usize)] = &[
159        // One LLC per node, SMT. The 2 total LLCs split evenly across
160        // the 2 nodes, so a scheduler that conflates node identity with
161        // LLC identity has nowhere to hide the confusion. Excluded from
162        // the default battery by `max_numa_nodes = Some(1)`; reached by
163        // the verifier under `accepts_verifier` (default numa cap
164        // ignored).
165        (
166            "2numa-32cpu-2llc-smt",
167            "32 CPUs, 2 NUMA nodes, 2 LLCs (one LLC per node, SMT)",
168            2,
169            2,
170            8,
171            2,
172            2048,
173        ),
174        (
175            "2numa-16cpu-4llc-nosmt",
176            "16 CPUs, 2 NUMA nodes, 4 LLCs",
177            2,
178            4,
179            4,
180            1,
181            2048,
182        ),
183        (
184            "2numa-128cpu-8llc-smt",
185            "128 CPUs, 2 NUMA nodes, 8 LLCs",
186            2,
187            8,
188            8,
189            2,
190            2048,
191        ),
192        (
193            "2numa-128cpu-8llc-nosmt",
194            "128 CPUs, 2 NUMA nodes, 8 LLCs (no SMT)",
195            2,
196            8,
197            16,
198            1,
199            2048,
200        ),
201        (
202            "4numa-32cpu-8llc-nosmt",
203            "32 CPUs, 4 NUMA nodes, 8 LLCs",
204            4,
205            8,
206            4,
207            1,
208            2048,
209        ),
210        (
211            "4numa-192cpu-12llc-smt",
212            "192 CPUs, 4 NUMA nodes, 12 LLCs",
213            4,
214            12,
215            8,
216            2,
217            4096,
218        ),
219    ];
220
221    let mut presets: Vec<TopoPreset> = defs
222        .iter()
223        .map(|&(n, d, s, c, t, m)| TopoPreset {
224            name: n,
225            description: d,
226            topology: Topology {
227                llcs: s,
228                cores_per_llc: c,
229                threads_per_core: t,
230                numa_nodes: 1,
231                nodes: None,
232                distances: None,
233                llc_cores: None,
234            },
235            memory_mib: m,
236            forced_cpu_budget: None,
237        })
238        .chain(numa_defs.iter().map(|&(n, d, nn, s, c, t, m)| TopoPreset {
239            name: n,
240            description: d,
241            topology: Topology {
242                llcs: s,
243                cores_per_llc: c,
244                threads_per_core: t,
245                numa_nodes: nn,
246                nodes: None,
247                distances: None,
248                llc_cores: None,
249            },
250            memory_mib: m,
251            forced_cpu_budget: None,
252        }))
253        .collect();
254
255    // 192cpu-11llc-smt: 11 LLCs, ten with 9 cores (18 logical CPUs) and one
256    // with 6 (12 logical CPUs) = 192 CPUs. NON-uniform LLC sizing (the
257    // point): schedulers that assume equal-sized LLCs mis-place work on
258    // the short cache. Packing width `cores_per_llc = 9` reserves a
259    // 9-core (32-APIC-ID) block per LLC; `llc_cores` populates ten fully
260    // and one to 6, so the guest sees the uneven layout via the sparse
261    // APIC-block mechanism. `forced_cpu_budget = Some(96)` pins the
262    // no-perf mask to <=96 host CPUs so its 192 vCPUs ALWAYS overcommit
263    // (>=2x) — continuous exercise of the time-slicing path, modeling a
264    // chip larger than the host. Appended out-of-band (the tuple tables
265    // express only uniform shapes with no forced budget).
266    static UNEVEN_11LLC_CORES: [u32; 11] = [9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 6];
267    presets.push(TopoPreset {
268        name: "192cpu-11llc-smt",
269        description: "192 CPUs, 11 LLCs (uneven: ten 18-CPU + one 12-CPU, SMT)",
270        topology: Topology {
271            llcs: 11,
272            cores_per_llc: 9,
273            threads_per_core: 2,
274            numa_nodes: 1,
275            nodes: None,
276            distances: None,
277            llc_cores: Some(&UNEVEN_11LLC_CORES),
278        },
279        memory_mib: 4096,
280        forced_cpu_budget: Some(96),
281    });
282
283    // ARM64 has no SMT -- exclude presets with threads_per_core > 1.
284    if cfg!(target_arch = "aarch64") {
285        presets.retain(|p| p.topology.threads_per_core <= 1);
286    }
287
288    presets
289}
290
291#[cfg(test)]
292mod tests {
293    use super::*;
294
295    #[test]
296    fn gauntlet_presets_unique_names() {
297        let p = gauntlet_presets();
298        let names: Vec<&str> = p.iter().map(|p| p.name).collect();
299        let unique: std::collections::HashSet<&&str> = names.iter().collect();
300        assert_eq!(names.len(), unique.len());
301    }
302
303    #[test]
304    fn gauntlet_presets_total_cpus_match() {
305        for p in &gauntlet_presets() {
306            let cpus = p.topology.total_cpus();
307            assert!(
308                p.description.contains(&cpus.to_string()),
309                "{}: description '{}' doesn't mention {} CPUs",
310                p.name,
311                p.description,
312                cpus
313            );
314        }
315    }
316
317    #[test]
318    fn gauntlet_presets_memory_sane() {
319        for p in &gauntlet_presets() {
320            assert!(
321                p.memory_mib >= 512,
322                "{} has too little memory: {}MiB",
323                p.name,
324                p.memory_mib
325            );
326            let cpus = p.topology.total_cpus() as usize;
327            assert!(
328                p.memory_mib >= cpus * 8,
329                "{} has {}MiB for {} CPUs",
330                p.name,
331                p.memory_mib,
332                cpus
333            );
334        }
335    }
336
337    #[test]
338    fn gauntlet_presets_topology_pinned() {
339        // (name, expected LLCs, expected total CPUs)
340        let expected: &[(&str, u32, u32)] = &[
341            ("4cpu-1llc-nosmt", 1, 4),
342            ("4cpu-2llc-nosmt", 2, 4),
343            ("9cpu-3llc-nosmt", 3, 9),
344            ("15cpu-5llc-nosmt", 5, 15),
345            ("14cpu-7llc-nosmt", 7, 14),
346            #[cfg(not(target_arch = "aarch64"))]
347            ("8cpu-2llc-smt", 2, 8),
348            #[cfg(not(target_arch = "aarch64"))]
349            ("12cpu-3llc-smt", 3, 12),
350            #[cfg(not(target_arch = "aarch64"))]
351            ("32cpu-4llc-smt", 4, 32),
352            #[cfg(not(target_arch = "aarch64"))]
353            ("64cpu-8llc-smt", 8, 64),
354            #[cfg(not(target_arch = "aarch64"))]
355            ("128cpu-4llc-smt", 4, 128),
356            #[cfg(not(target_arch = "aarch64"))]
357            ("128cpu-8llc-smt", 8, 128),
358            #[cfg(not(target_arch = "aarch64"))]
359            ("240cpu-15llc-smt", 15, 240),
360            #[cfg(not(target_arch = "aarch64"))]
361            ("252cpu-14llc-smt", 14, 252),
362            #[cfg(not(target_arch = "aarch64"))]
363            ("192cpu-11llc-smt", 11, 192),
364            ("32cpu-4llc-nosmt", 4, 32),
365            ("64cpu-8llc-nosmt", 8, 64),
366            ("128cpu-4llc-nosmt", 4, 128),
367            ("128cpu-8llc-nosmt", 8, 128),
368            ("240cpu-15llc-nosmt", 15, 240),
369            ("252cpu-14llc-nosmt", 14, 252),
370            ("2numa-16cpu-4llc-nosmt", 4, 16),
371            #[cfg(not(target_arch = "aarch64"))]
372            ("2numa-32cpu-2llc-smt", 2, 32),
373            #[cfg(not(target_arch = "aarch64"))]
374            ("2numa-128cpu-8llc-smt", 8, 128),
375            ("2numa-128cpu-8llc-nosmt", 8, 128),
376            ("4numa-32cpu-8llc-nosmt", 8, 32),
377            #[cfg(not(target_arch = "aarch64"))]
378            ("4numa-192cpu-12llc-smt", 12, 192),
379        ];
380        let presets = gauntlet_presets();
381        assert_eq!(
382            expected.len(),
383            presets.len(),
384            "pinned list and preset list have different lengths"
385        );
386        for &(name, llcs, cpus) in expected {
387            let p = presets.iter().find(|p| p.name == name).unwrap();
388            assert_eq!(
389                p.topology.num_llcs(),
390                llcs,
391                "{}: expected {} LLCs, got {}",
392                name,
393                llcs,
394                p.topology.num_llcs()
395            );
396            assert_eq!(
397                p.topology.total_cpus(),
398                cpus,
399                "{}: expected {} CPUs, got {}",
400                name,
401                cpus,
402                p.topology.total_cpus()
403            );
404        }
405    }
406
407    #[test]
408    fn gauntlet_presets_topology_valid() {
409        for p in &gauntlet_presets() {
410            p.topology
411                .validate()
412                .unwrap_or_else(|e| panic!("{}: {e}", p.name));
413        }
414    }
415
416    #[test]
417    fn gauntlet_presets_252_cpu_near_limit() {
418        let presets = gauntlet_presets();
419        let max_presets: Vec<_> = presets
420            .iter()
421            .filter(|p| p.name.starts_with("252cpu-14llc-"))
422            .collect();
423        assert!(
424            !max_presets.is_empty(),
425            "at least one 252cpu-14llc preset must exist"
426        );
427        for p in &max_presets {
428            let cpus = p.topology.total_cpus();
429            assert!(
430                cpus <= 255,
431                "{} has {} CPUs, exceeds KVM vCPU limit",
432                p.name,
433                cpus
434            );
435            assert!(
436                cpus >= 200,
437                "{} should be near the limit: {} CPUs",
438                p.name,
439                cpus
440            );
441        }
442    }
443
444    #[test]
445    fn topology_single_cpu() {
446        let t = Topology {
447            llcs: 1,
448            cores_per_llc: 1,
449            threads_per_core: 1,
450            numa_nodes: 1,
451            nodes: None,
452            distances: None,
453            llc_cores: None,
454        };
455        assert_eq!(t.total_cpus(), 1);
456        assert_eq!(t.num_llcs(), 1);
457    }
458
459    #[test]
460    fn gauntlet_preset_names_encode_topology() {
461        for p in &gauntlet_presets() {
462            let smt = if p.topology.threads_per_core > 1 {
463                "smt"
464            } else {
465                "nosmt"
466            };
467            let expected = if p.topology.numa_nodes > 1 {
468                format!(
469                    "{}numa-{}cpu-{}llc-{smt}",
470                    p.topology.numa_nodes,
471                    p.topology.total_cpus(),
472                    p.topology.num_llcs(),
473                )
474            } else {
475                format!(
476                    "{}cpu-{}llc-{smt}",
477                    p.topology.total_cpus(),
478                    p.topology.num_llcs(),
479                )
480            };
481            assert_eq!(p.name, expected, "preset name must encode its topology");
482        }
483    }
484
485    #[test]
486    fn gauntlet_presets_description_non_empty() {
487        for p in &gauntlet_presets() {
488            assert!(
489                !p.description.is_empty(),
490                "{} has empty description",
491                p.name
492            );
493        }
494    }
495
496    #[test]
497    fn gauntlet_presets_forced_budget_only_on_192cpu_11llc_smt() {
498        // Regression pin: the forced-overcommit budget is opt-in per
499        // preset. Exactly `192cpu-11llc-smt` carries it; every stock preset
500        // leaves it `None` so their cell budgets resolve unchanged.
501        for p in &gauntlet_presets() {
502            match p.name {
503                "192cpu-11llc-smt" => assert_eq!(
504                    p.forced_cpu_budget,
505                    Some(96),
506                    "192cpu-11llc-smt must force a 96-CPU budget"
507                ),
508                other => assert_eq!(
509                    p.forced_cpu_budget, None,
510                    "{other} must not carry a forced budget"
511                ),
512            }
513        }
514    }
515
516    #[test]
517    #[cfg(not(target_arch = "aarch64"))]
518    fn gauntlet_presets_192cpu_11llc_smt_is_non_uniform_and_overcommits() {
519        let p = gauntlet_presets()
520            .into_iter()
521            .find(|p| p.name == "192cpu-11llc-smt")
522            .expect("192cpu-11llc-smt present on x86_64");
523        let t = &p.topology;
524        t.validate().expect("192cpu-11llc-smt must validate");
525        assert_eq!(t.num_llcs(), 11);
526        assert_eq!(t.total_cpus(), 192);
527        // Ten 18-CPU LLCs + one 12-CPU LLC: NOT uniform.
528        let sizes: Vec<u32> = (0..t.num_llcs())
529            .map(|l| t.cores_in_llc(l) * t.threads_per_core)
530            .collect();
531        assert_eq!(sizes.iter().filter(|&&s| s == 18).count(), 10);
532        assert_eq!(sizes.iter().filter(|&&s| s == 12).count(), 1);
533        // Forced budget guarantees overcommit: budget < vCPU count.
534        assert!(
535            p.forced_cpu_budget.unwrap() < t.total_cpus(),
536            "forced budget must be below vCPU count to force overcommit"
537        );
538    }
539}