ktstr/scenario/
mod.rs

1//! Scenario definitions and test execution.
2//!
3//! Most tests use the declarative ops API from the [`ops`] submodule:
4//! - [`ops::CgroupDef`] -- declarative cgroup definition (name + cpuset + workload)
5//! - [`ops::Step`] -- a sequence of ops followed by a hold period
6//! - [`ops::Op`] -- an atomic scenario operation (cgroup/worker topology, payload run/wait/kill, freeze, snapshot, kernel read/write, scheduler attach/detach/restart/replace, BPF map pin)
7//! - [`ops::CpusetSpec`] -- how to compute a cpuset from topology
8//! - [`ops::HoldSpec`] -- how long to hold after a step
9//! - [`backdrop::Backdrop`] -- persistent scenario state shared across every Step
10//! - [`ops::execute_defs`] -- run cgroup definitions for the full duration
11//! - [`ops::execute_steps`] -- run a multi-step sequence
12//! - [`ops::execute_scenario`] -- run a Backdrop + Steps sequence
13//!
14//! Types defined in this module:
15//! - [`Ctx`] -- runtime context passed to scenario functions
16//! - [`CgroupGroup`] -- RAII guard that removes cgroups on drop
17//!
18//! The [`scenarios`] submodule provides curated canned scenarios.
19//!
20//! ## Builder method conventions
21//!
22//! Every builder type in the scenario API (Setup, Step, Backdrop,
23//! WorkloadConfig, …) names its methods by what they do, not by
24//! what they return. The three-prefix vocabulary is uniform across
25//! the scenario surface so a reader can predict semantics from
26//! the prefix alone:
27//!
28//! - **`with_X(arg) -> Self`** — alternate constructor that returns
29//!   a fresh value with `X` already set (e.g.
30//!   [`ops::Step::with_defs`], [`ops::Step::with_payload`],
31//!   [`ops::Setup::with_factory`]). Distinct from `Self::new(...)`
32//!   which is the base ctor; `with_X` constructors compose without
33//!   reaching for `Default::default()` then chaining setters.
34//! - **`set_X(self, value) -> Self`** — field REPLACE on an
35//!   existing builder. Consumes `self`, writes `X`, returns the
36//!   updated value (e.g. [`ops::Step::set_ops`],
37//!   [`ops::Step::set_hold`]). Previous contents of `X` are
38//!   discarded.
39//! - **`push_X(self, value) -> Self`** / **`extend_X<I>(self, iter)
40//!   -> Self`** — field APPEND. `push_X` adds one element,
41//!   `extend_X` adds many from any `IntoIterator` (e.g.
42//!   [`backdrop::Backdrop::push_cgroup`] /
43//!   [`backdrop::Backdrop::extend_cgroups`]).
44//!
45//! Naming an APPEND method `set_X` (or a REPLACE method `push_X`)
46//! mis-encodes the semantics and is a defect — flag at review.
47//!
48//! See the [Scenarios](https://ktstr.dev/guide/concepts/scenarios.html)
49//! and [Writing Tests](https://ktstr.dev/guide/writing-tests.html)
50//! chapters of the guide.
51
52pub mod affinity;
53pub mod backdrop;
54pub mod basic;
55pub mod bpf_pin;
56pub mod cpuset;
57pub mod dynamic;
58pub mod host_stuck;
59pub mod interaction;
60pub mod nested;
61pub mod ops;
62pub mod payload_run;
63pub mod performance;
64pub mod sample;
65pub mod scenarios;
66pub mod snapshot;
67pub mod stress;
68
69pub use backdrop::Backdrop;
70
71use std::collections::BTreeSet;
72use std::sync::Arc;
73use std::sync::atomic::AtomicU16;
74use std::thread;
75use std::time::Duration;
76
77use anyhow::Result;
78
79#[cfg(test)]
80use nix::sys::signal::kill;
81#[cfg(test)]
82use nix::unistd::Pid;
83
84use crate::assert::AssertResult;
85use crate::topology::TestTopology;
86use crate::workload::*;
87
88/// Test-only synthetic-PID liveness seam.
89///
90/// Production scheduler liveness is derived from the exact pidfd retained by
91/// `CurrentSchedulerProcess`; host unit tests cannot install that guest owner
92/// and use this numeric helper only for injected fixtures.
93///
94/// Returns `false` for pid 0: `kill(0, ...)` targets the caller's
95/// process group rather than a single process, so the syscall would
96/// always report success and falsely mark "no process" as alive.
97///
98/// Returns `false` for `pid <= 0`. Non-positive pid_t values are
99/// invalid targets — `kill(0, ...)` signals the caller's process
100/// group and `kill(-1, ...)` signals every process the caller is
101/// permitted to signal. Neither matches "is this specific process
102/// alive?", so we refuse rather than probe.
103///
104/// # EPERM: foreign-UID processes report as dead
105///
106/// `kill(pid, 0)` returns one of three things for `pid > 0`:
107///
108/// 1. `Ok(())` — pid exists and the caller is permitted to signal it
109///    (same UID, or the caller has `CAP_KILL`). This maps to `true`.
110/// 2. `Err(ESRCH)` — no process with that pid. Maps to `false`.
111/// 3. `Err(EPERM)` — the pid exists but belongs to a different UID
112///    (or is otherwise unsignalable by the caller). Per `kill(2)`,
113///    "EPERM implies the process exists" — a live process. This
114///    implementation treats EPERM as `false` (via `.is_ok()`) because
115///    ktstr's callers use `process_alive` to ask "is the scheduler /
116///    payload *I launched* still running?", not "does any process
117///    with this pid exist?". A foreign-UID process sharing the pid is
118///    not the one the caller is tracking and is correctly classified
119///    as "no, not *my* process."
120///
121/// If a future caller needs to distinguish "dead" from "alive but
122/// unsignalable," switch to `Errno::ESRCH` discrimination on the
123/// `kill` result instead of `.is_ok()` — do NOT change this function
124/// silently, because existing callers rely on the EPERM-as-false
125/// behavior when walking /proc on heavily-forking hosts where pid
126/// reuse can land a foreign-UID process on the old slot.
127#[cfg(test)]
128fn process_alive(pid: libc::pid_t) -> bool {
129    if pid <= 0 {
130        return false;
131    }
132    kill(Pid::from_raw(pid), None).is_ok()
133}
134
135#[cfg(not(test))]
136fn configured_scheduler_alive(_snapshot_pid: libc::pid_t) -> Result<bool> {
137    crate::vmm::rust_init::current_scheduler_liveness()
138        .map(|alive| alive.unwrap_or(false))
139        .map_err(anyhow::Error::msg)
140}
141
142#[cfg(test)]
143fn configured_scheduler_alive(snapshot_pid: libc::pid_t) -> Result<bool> {
144    Ok(process_alive(snapshot_pid))
145}
146
147// Re-export AffinityIntent from workload so existing `use super::*` in
148// submodules (affinity.rs, etc.) can find it.
149pub use crate::workload::AffinityIntent;
150
151// ---------------------------------------------------------------------------
152// RAII cgroup group
153// ---------------------------------------------------------------------------
154
155/// RAII guard that removes cgroups on drop.
156///
157/// Prevents cgroup leaks when workload spawning or other operations fail
158/// between cgroup creation and cleanup.
159#[must_use = "dropping a CgroupGroup immediately destroys the cgroups it manages"]
160pub struct CgroupGroup<'a> {
161    cgroups: &'a dyn crate::cgroup::CgroupOps,
162    names: Vec<String>,
163}
164
165impl std::fmt::Debug for CgroupGroup<'_> {
166    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
167        f.debug_struct("CgroupGroup")
168            .field("cgroups", &self.cgroups.parent_path())
169            .field("names", &self.names)
170            .finish()
171    }
172}
173
174impl<'a> CgroupGroup<'a> {
175    /// Create an empty group. Cgroups added via `add_cgroup` or
176    /// `add_cgroup_no_cpuset` are removed when the group is dropped.
177    pub fn new(cgroups: &'a dyn crate::cgroup::CgroupOps) -> Self {
178        Self {
179            cgroups,
180            names: Vec::new(),
181        }
182    }
183
184    /// Create a cgroup and set its cpuset. The cgroup is tracked for cleanup on drop.
185    ///
186    /// Auto-enables [`Controller::Cpuset`](crate::cgroup::Controller::Cpuset)
187    /// on the parent's `cgroup.subtree_control` before creating the
188    /// child so the child's `cpuset.cpus` file is exposed and the
189    /// subsequent [`set_cpuset`](crate::cgroup::CgroupOps::set_cpuset)
190    /// write lands. Direct CgroupGroup users (the `custom_*` scenarios
191    /// in [`crate::scenario::nested`] / [`crate::scenario::stress`])
192    /// don't go through `run_scenario`'s
193    /// controller-resolution hook, so the controller enable has to
194    /// happen here. The setup call is idempotent on real cgroupfs (a
195    /// `+cpuset` write into `cgroup.subtree_control` that already
196    /// contains `cpuset` is a no-op at the kernel level per
197    /// `cgroup_subtree_control_write` in kernel/cgroup/cgroup.c).
198    pub fn add_cgroup(&mut self, name: &str, cpuset: &BTreeSet<usize>) -> Result<()> {
199        let mut required = BTreeSet::new();
200        required.insert(crate::cgroup::Controller::Cpuset);
201        self.cgroups.setup(&required)?;
202        self.cgroups.create_cgroup(name)?;
203        self.cgroups.set_cpuset(name, cpuset)?;
204        self.names.push(name.to_string());
205        Ok(())
206    }
207
208    /// Create a cgroup without a cpuset. The cgroup is tracked for cleanup on drop.
209    ///
210    /// No controller enablement: callers explicitly opting out of a
211    /// cpuset signal that they don't need any cgroup v2 controller
212    /// surface beyond the cgroup-core knobs (`cgroup.procs`,
213    /// `cgroup.freeze`) which are ungated. If a future caller needs
214    /// e.g. memory limits on a no-cpuset cgroup, add a
215    /// `with_controllers` overload rather than auto-enabling — the
216    /// "no-cpuset" name is load-bearing for the absent-controller
217    /// behavior pinned by tests in
218    /// [`crate::scenario::nested::custom_nested_cgroup_no_ctrl`].
219    pub fn add_cgroup_no_cpuset(&mut self, name: &str) -> Result<()> {
220        self.cgroups.create_cgroup(name)?;
221        self.names.push(name.to_string());
222        Ok(())
223    }
224
225    /// Names of all tracked cgroups.
226    pub fn names(&self) -> &[String] {
227        &self.names
228    }
229
230    /// Forget a tracked cgroup name without touching cgroupfs. Used
231    /// by `Op::RemoveCgroup` immediately BEFORE invoking the kernel
232    /// rmdir, so a later `Op::AddCgroup` with the same name can
233    /// re-create the cgroup instead of colliding against the stale
234    /// tracking entry, and the teardown-on-drop path skips a
235    /// now-redundant rmdir of a dir that the in-progress (or
236    /// already-completed) kernel call is removing.
237    pub(crate) fn forget(&mut self, name: &str) {
238        self.names.retain(|n| n != name);
239    }
240}
241
242/// True when `err`'s root cause is an `io::Error` with kind
243/// `NotFound` (ENOENT). Used by `CgroupGroup::drop` and
244/// `Op::RemoveCgroup` to classify a TOCTOU ENOENT as benign
245/// (post-condition "no dir" already holds) so it is filtered
246/// from warn output. Extracting the predicate keeps the two
247/// sites in lock-step — a classification change only edits
248/// this function, not both call sites.
249pub(crate) fn is_io_not_found(err: &anyhow::Error) -> bool {
250    err.root_cause()
251        .downcast_ref::<std::io::Error>()
252        .is_some_and(|io| io.kind() == std::io::ErrorKind::NotFound)
253}
254
255/// Map a cgroup `remove_cgroup` error's root-cause errno to a
256/// short remediation hint appended to warn messages. Only
257/// EBUSY and EACCES — the two errnos callers can act on — get
258/// specific hints; every other errno yields `None` so the warn
259/// stays terse with just the underlying error chain. Extracted
260/// so both `CgroupGroup::drop` and `Op::RemoveCgroup` stay
261/// synchronized; a new hint (e.g. ENOTEMPTY for un-cleaned
262/// children) only needs to be wired here.
263pub(crate) fn remove_cgroup_errno_hint(err: &anyhow::Error) -> Option<&'static str> {
264    let raw = err
265        .root_cause()
266        .downcast_ref::<std::io::Error>()?
267        .raw_os_error()?;
268    match raw {
269        libc::EBUSY => {
270            Some("EBUSY: cgroup still has live tasks — workloads were not drained before teardown")
271        }
272        libc::EACCES => {
273            Some("EACCES: permission denied — check cgroup owner / `user.slice` delegation")
274        }
275        _ => None,
276    }
277}
278
279impl Drop for CgroupGroup<'_> {
280    fn drop(&mut self) {
281        // Reverse-iterate so nested cgroups (children created AFTER
282        // their parents) are removed before their parents. Removing a
283        // cgroup directory that still has child cgroup directories
284        // under it fails with ENOTEMPTY.
285        //
286        // ENOENT is expected: `CgroupManager::remove_cgroup` returns
287        // Ok when the dir is already gone, so the only way ENOENT
288        // reaches here is the narrow TOCTOU race where another process
289        // unlinks between `exists()` and `remove_dir` — the post-
290        // condition (no dir) still holds and no cleanup is owed. Every
291        // other error (EBUSY from a surviving task, EACCES, broken
292        // cgroupfs mount) surfaces via `tracing::warn!` so a teardown
293        // failure is visible instead of silently swallowed; mirrors
294        // the same handling in `Op::RemoveCgroup` so the two paths
295        // stay consistent.
296        for name in self.names.iter().rev() {
297            if let Err(err) = self.cgroups.remove_cgroup(name) {
298                if is_io_not_found(&err) {
299                    continue;
300                }
301                let hint = remove_cgroup_errno_hint(&err).unwrap_or("");
302                tracing::warn!(
303                    cgroup = %name,
304                    err = %format!("{err:#}"),
305                    hint,
306                    "CgroupGroup::drop: remove_cgroup returned non-ENOENT error",
307                );
308            }
309        }
310    }
311}
312
313// ---------------------------------------------------------------------------
314// Runtime context and interpreter
315// ---------------------------------------------------------------------------
316
317/// Runtime context passed to scenario functions.
318///
319/// Provides access to cgroup management, topology information, and
320/// test configuration. Custom scenarios are functions receiving this
321/// `Ctx` as their sole parameter (e.g. the `custom_*` fns in
322/// [`crate::scenario::nested`] / [`crate::scenario::stress`]).
323///
324/// # Method groups
325///
326/// ## Time helpers
327///
328/// - [`Self::settled_hold`] — `HoldSpec::fixed(settle + duration * f)`
329///   sugar for the dominant Step hold-time pattern.
330///
331/// ## Cgroup construction
332///
333/// - [`Self::cgroup_def`] — `CgroupDef::named(name).workers(workers_per_cgroup)`
334///   sugar that pins the default-worker-count shape across 40+ call
335///   sites.
336///
337/// ## Topology accessors
338///
339/// - [`Self::cpuset_cpus`] — resolve a
340///   [`CpusetSpec`](crate::scenario::ops::CpusetSpec) against this
341///   context's topology and return the CPU count.
342///
343/// ## Constructors
344///
345/// - [`Self::builder`] — start a [`CtxBuilder`] with sane defaults for
346///   unit-test scenarios.
347/// - [`Self::payload`] — start a
348///   [`PayloadRun`](crate::scenario::payload_run::PayloadRun) for a
349///   given [`Payload`](crate::test_support::Payload).
350///
351/// # Field groups
352///
353/// Each pub field's doc is prefixed with its sub-concern label so the
354/// rustdoc table groups visibly. The six groups are:
355///
356/// - **VM environment** — `cgroups`, `topo`. The host-side
357///   filesystem + topology handles the scenario interacts with.
358/// - **Test timing** — `duration`, `settle`. The wall-clock
359///   budgets that shape every Step's hold-time math.
360/// - **Cgroup defaults** — `workers_per_cgroup`, `work_type_override`.
361///   The merge-time defaults `CgroupDef::merged_works` applies when a
362///   `WorkSpec` leaves them unset.
363/// - **Scheduler state** — `sched_pid`. Liveness-probe target for
364///   inter-step scheduler-death detection.
365/// - **Assertion policy** — `assert`. The merged
366///   default+scheduler+per-test verdict checks
367///   `run_scenario` / `execute_steps` apply.
368/// - **Runtime coordination** — `wait_for_map_write`. Framework-set
369///   gate that custom scenarios typically do not flip.
370#[non_exhaustive]
371pub struct Ctx<'a> {
372    /// **VM environment.** Cgroup filesystem operations. `&dyn CgroupOps`
373    /// (not `&CgroupManager`) so scenario code can be driven by an
374    /// in-memory test double without touching `/sys/fs/cgroup`.
375    /// Production callers pass `&CgroupManager` and the auto-coercion
376    /// is transparent at the call site — `ctx.cgroups.set_cpuset(...)`
377    /// works unchanged.
378    pub cgroups: &'a dyn crate::cgroup::CgroupOps,
379    /// **VM environment.** VM CPU topology.
380    pub topo: &'a TestTopology,
381    /// **Test timing.** How long to run the workload.
382    pub duration: Duration,
383    /// **Cgroup defaults.** Default number of workers per cgroup.
384    pub workers_per_cgroup: usize,
385    /// **Scheduler state.** PID of the running scheduler (for liveness
386    /// checks), or `None` when no scheduler is attached. Stored as
387    /// `Option<pid_t>` so the "no scheduler" state is a distinct
388    /// variant rather than a 0-sentinel — `run_scenario` and
389    /// step-level liveness probes destructure via `if let Some(pid)`
390    /// instead of `!= 0` guards.
391    pub sched_pid: Option<libc::pid_t>,
392    /// **Test timing.** Time to wait after cgroup creation for
393    /// scheduler stabilization.
394    pub settle: Duration,
395    /// **Cgroup defaults.** Override work type for scenarios that use
396    /// `SpinWait` by default.
397    pub work_type_override: Option<WorkType>,
398    /// **Assertion policy.** Merged assertion config (default_checks +
399    /// scheduler + per-test). Used by `run_scenario` for data-driven
400    /// scenarios and by `execute_steps` as the default when no explicit
401    /// checks are passed to `execute_steps_with`.
402    pub assert: crate::assert::Assert,
403    /// **Runtime coordination.** When true, `execute_steps` blocks after
404    /// writing the scenario start marker until the host confirms its BPF
405    /// map write is complete — waiting on the `bpf_map_write_done` latch
406    /// that `hvc0_poll_loop` sets when the host pushes
407    /// `SIGNAL_BPF_WRITE_DONE` over the virtio-console RX queue. Set
408    /// automatically by the framework when a `KtstrTestEntry` declares
409    /// `bpf_map_write`; custom scenarios typically do not flip this
410    /// manually.
411    pub wait_for_map_write: bool,
412    /// **Phase coordination.** Per-VM atomic publishing the current
413    /// scenario step index. Written by the scenario driver immediately
414    /// before each `run_step` call and read by three stamping sites
415    /// so each captured sample carries the step it belongs to:
416    /// (1) the host-side freeze-coordinator periodic-capture path
417    /// stamps at periodic-fire time;
418    /// (2) the on-demand `Op::CaptureSnapshot` apply arm stamps at
419    /// apply time (the apply happens in the same phase as the
420    /// capture);
421    /// (3) the host-side user-watchpoint trip handler stamps at
422    /// TRIP time, not at registration — the user issues
423    /// `Op::WatchSnapshot` from some Step k, but the actual write
424    /// that fires the watchpoint and triggers the snapshot can
425    /// happen at any later phase, so the trip-time stamp pins the
426    /// sample to the bucket matching when the observation actually
427    /// occurred.
428    ///
429    /// Encoded per the framework's 1-indexed phase convention: `0` is
430    /// the BASELINE settle window (the initial value), `1..=N` align
431    /// with scenario Step ordinals (`step_idx + 1`). This matches
432    /// [`crate::assert::PhaseBucket::step_index`] so a phase-aware
433    /// sample drops directly into the correct bucket without a
434    /// reindex.
435    ///
436    /// Stored as `AtomicU16` because the wire `StimulusPayload`
437    /// step-index field is also `u16`, so a single shared width
438    /// keeps the host-side bridge map and the guest-published wire
439    /// value type-compatible without narrowing.
440    ///
441    /// Wrapped in `Arc` so the same per-VM publisher can be cloned
442    /// into every consumer thread (scenario driver, freeze-coord,
443    /// on-demand-capture apply arms) without a process-global
444    /// static — multiple in-process VMs (e.g. parallel gauntlet
445    /// variants) each get an independent atomic instead of racing
446    /// on shared global state.
447    pub current_step: Arc<AtomicU16>,
448    /// **Drift-safe path derivation.** The `&'static str` name of
449    /// the [`KtstrTestEntry`](crate::test_support::KtstrTestEntry)
450    /// the running test body was dispatched as, stamped by the
451    /// guest-side `maybe_dispatch_vm_test_with_args` and the
452    /// host-only dispatch path before the test body runs. Drives
453    /// the body-side path-derivation methods
454    /// [`failure_dump_path`](Self::failure_dump_path)
455    /// (and `wprof_pb_path` / `repro_wprof_pb_path` when the
456    /// `wprof` feature is enabled) — the
457    /// drift-safe replacement for the legacy pattern of
458    /// hardcoding the test fn name as a string literal at the
459    /// callsite. When `Some(name)`, those methods derive the
460    /// sidecar paths from the macro-stamped value at call time,
461    /// so a future test rename surfaces the resulting
462    /// `Result<PathBuf>` bail at compile-time-equivalent-failure
463    /// (a deterministic Err) rather than as a runtime ENOENT
464    /// against a stale literal.
465    ///
466    /// `None` is the manually-constructed-Ctx escape hatch — ad-hoc
467    /// scenario tests that build `Ctx` via
468    /// [`CtxBuilder::build`](CtxBuilder::build) without calling
469    /// [`CtxBuilder::entry_name`](CtxBuilder::entry_name) get
470    /// `None` and a path-derivation method invocation bails with an
471    /// actionable diagnostic naming the missing-stamp scenario.
472    /// Sibling to [`crate::vmm::VmResult::entry_name`] which carries
473    /// the same `&'static str` on the post-VM result struct (the
474    /// two ends of the test-name chain — pre-VM body context vs
475    /// post-VM result — store the same shape so the body-side
476    /// `ctx.failure_dump_path()` and the host-side
477    /// `result.failure_dump_path()` resolve to identical paths).
478    pub entry_name: Option<&'static str>,
479    /// The run's variant hash (see `variant_hash_from_parts`),
480    /// stamped at the macro dispatch site alongside [`Self::entry_name`].
481    /// The body-side `failure_dump_path` / `wprof_pb_path` derivations
482    /// embed it as the `-{16-hex}` filename suffix so a gauntlet test's
483    /// per-preset dumps don't clobber and each matches its sidecar's
484    /// variant hash. `0` on a manually-built fixture (which has
485    /// `entry_name = None` and thus bails before reading this).
486    pub variant_hash: u64,
487}
488
489impl std::fmt::Debug for Ctx<'_> {
490    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
491        // `&dyn CgroupOps` is not Debug (dropped the supertrait to
492        // avoid bloating the test-double surface); render the parent
493        // path instead so debug prints are still informative.
494        f.debug_struct("Ctx")
495            .field("cgroups", &self.cgroups.parent_path())
496            .field("topo", &self.topo)
497            .field("duration", &self.duration)
498            .field("workers_per_cgroup", &self.workers_per_cgroup)
499            .field("sched_pid", &self.sched_pid)
500            .field("settle", &self.settle)
501            .field("work_type_override", &self.work_type_override)
502            .field("assert", &self.assert)
503            .field("wait_for_map_write", &self.wait_for_map_write)
504            .field(
505                "current_step",
506                &self.current_step.load(std::sync::atomic::Ordering::Relaxed),
507            )
508            .field("entry_name", &self.entry_name)
509            .field("variant_hash", &self.variant_hash)
510            .finish()
511    }
512}
513
514impl Ctx<'_> {
515    /// Read the live scheduler identity published by the
516    /// `Op::AttachScheduler` / `Op::ReplaceScheduler` /
517    /// `Op::DetachScheduler` dispatch arms. Returns `None` when no
518    /// scheduler is currently attached (the pre-attach state at
519    /// process start and the post-`Op::DetachScheduler` state).
520    ///
521    /// Distinct from `entry.scheduler` (the boot-time descriptor
522    /// from the `#[ktstr_test]` macro): `entry.scheduler` stays
523    /// the same across `Op::ReplaceScheduler` swaps, while
524    /// `ctx.current_scheduler()` reflects the LIVE identity after
525    /// any runtime swap. Consumer sites that care about the
526    /// currently-attached BPF binary (verifier_stats wiring,
527    /// monitor thresholds, auto-repro probe gates) want this
528    /// method; sites that care about the test's declared
529    /// scheduler (test-runner skip/include filtering, sidecar
530    /// `scheduler_name` metadata) want `entry.scheduler`.
531    ///
532    /// v0 limitation: the boot path does not publish the boot
533    /// scheduler into the side channel, so the first observable
534    /// `Some` arrives after the first `Op::AttachScheduler` /
535    /// `Op::ReplaceScheduler` runs. Consumer sites that want a
536    /// fallback should call `.unwrap_or(&entry.scheduler.binary)`
537    /// to combine the live view with the boot descriptor.
538    pub fn current_scheduler(&self) -> Option<&'static crate::test_support::SchedulerSpec> {
539        crate::vmm::rust_init::current_scheduler()
540    }
541
542    /// Scheduler pid, filtered to the `> 0` range that
543    /// `process_alive` treats as signalable.
544    ///
545    /// `Ctx::sched_pid` documents `None` as the "no scheduler
546    /// configured" state, and the liveness sites destructure with
547    /// `if let Some(pid)`. Nothing in the builder, however, prevents
548    /// a caller from passing `Some(0)` or a negative pid — an easy
549    /// mistake for callers used to the workload module's internal
550    /// 0-sentinel pid slot (see the note on `sched_pid` above — the
551    /// sentinel lives on a module-private `AtomicI32` in
552    /// `src/workload/`, not on this `Option<pid_t>`). A bare
553    /// `Some(0)` would reach
554    /// `process_alive`, which returns `false` for any pid `<= 0`,
555    /// and the liveness sites would then bail with `scheduler died`
556    /// even though no scheduler was ever running — a false
557    /// positive that turns a misconfiguration into a misleading
558    /// scheduler-death diagnostic.
559    ///
560    /// Centralising the filter here keeps the sole production
561    /// caller — `setup_cgroups`'s post-settle bail — on a single
562    /// predicate: only a positive pid is "configured". The
563    /// `run_scenario` post-settle bail and workload-phase polling
564    /// take a live `crate::vmm::rust_init::sched_pid()` read
565    /// instead of this snapshot accessor.
566    ///
567    /// A `Some(n)` where `n <= 0` is a caller bug — the builder
568    /// documents `None` as the unconfigured shape, and every
569    /// positive value flows through unchanged. When the accessor
570    /// squashes such a value to `None`, it emits a `tracing::warn!`
571    /// naming the offending pid so the misuse surfaces in
572    /// structured logs instead of manifesting downstream as a
573    /// silent "scheduler died" verdict or, worse, a `kill(0, …)`
574    /// reaching the caller's own process group. The warn is
575    /// bounded: the sole production caller is `setup_cgroups`'s
576    /// post-settle bail, so the volume is O(1) per scenario run
577    /// even for a sustained misconfiguration — tight enough to
578    /// leave in place without a rate limiter.
579    pub(crate) fn active_sched_pid(&self) -> Option<libc::pid_t> {
580        match self.sched_pid {
581            Some(p) if p > 0 => Some(p),
582            Some(p) => {
583                tracing::warn!(
584                    pid = p,
585                    "Ctx::active_sched_pid: sched_pid=Some({p}) squashed to None; \
586                     only positive pids are configured-scheduler values — use \
587                     None for the unconfigured shape instead of a 0-sentinel or \
588                     negative pid"
589                );
590                None
591            }
592            None => None,
593        }
594    }
595
596    /// Resolve a `CpusetSpec` against this context's topology and
597    /// return the CPU count. Convenience accessor for tests that need
598    /// to size work counts proportional to a cpuset without computing
599    /// the topology denominator by hand. Mirrors the framework's own
600    /// resolution: the count is exactly the size of the BTreeSet
601    /// `spec.resolve(self)` returns, so any
602    /// `CpusetSpec`-aware code path (cgroup cpuset assignment,
603    /// affinity intent resolution, [`WorkSpec::workers_pct`]) sees the
604    /// same denominator. Uses the TOPOLOGY-level cpuset, not the
605    /// currently-effective cgroup cpuset — narrowing via mid-scenario
606    /// `Op::SetCpuset` does not change the value this returns.
607    pub fn cpuset_cpus(&self, spec: &crate::scenario::ops::CpusetSpec) -> usize {
608        spec.resolve(self).len()
609    }
610
611    /// `HoldSpec::fixed(settle + duration * fraction_of_duration)` —
612    /// the dominant Step hold-time pattern across scenarios. A Step
613    /// typically holds for the settle window (so the scheduler can
614    /// reach steady state) plus some fraction of the workload
615    /// duration (often `1.0` for whole-test Steps, or `0.5`/`1.0/3.0`
616    /// for multi-Step scenarios that subdivide the duration budget).
617    ///
618    /// The multiplication routes through [`Duration::mul_f64`], so a
619    /// fraction like `1.0 / 3.0` may yield a Duration that differs
620    /// from an integer-division formulation by ≤1 nanosecond — below
621    /// Linux thread sleep granularity and so unobservable at the
622    /// hold-evaluation boundary, but worth noting if a test ever
623    /// byte-pins a Duration value.
624    ///
625    /// # Panics
626    /// When `fraction_of_duration` is NaN, infinite, or negative
627    /// (per the `Duration::mul_f64` contract).
628    ///
629    /// # Examples
630    ///
631    /// ```ignore
632    /// Step::new(vec![], ctx.settled_hold(0.5));  // settle + half duration
633    /// Step::new(vec![], ctx.settled_hold(1.0));  // settle + full duration
634    /// ```
635    pub fn settled_hold(&self, fraction_of_duration: f64) -> crate::scenario::ops::HoldSpec {
636        crate::scenario::ops::HoldSpec::fixed(
637            self.settle + self.duration.mul_f64(fraction_of_duration),
638        )
639    }
640
641    /// Construct a [`CgroupDef`](crate::scenario::ops::CgroupDef) with `self.workers_per_cgroup`
642    /// workers — the most common scenario shape, dedupe of 40+
643    /// `CgroupDef::named(name).workers(ctx.workers_per_cgroup)` call
644    /// sites across `src/scenario/` and `tests/`.
645    ///
646    /// Equivalent to:
647    ///
648    /// ```ignore
649    /// CgroupDef::named(name).workers(ctx.workers_per_cgroup)
650    /// ```
651    ///
652    /// Returns a fresh [`CgroupDef`](crate::scenario::ops::CgroupDef) so the test author can chain
653    /// further builders (`.cpuset`, `.work`, etc.) on the
654    /// result. For non-default worker counts call
655    /// `CgroupDef::named(name).workers(N)` directly — the helper
656    /// pins ONLY the `ctx.workers_per_cgroup` default path.
657    ///
658    /// # Examples
659    ///
660    /// ```ignore
661    /// // Before (42+ sites):
662    /// vec![CgroupDef::named("cg_0").workers(ctx.workers_per_cgroup)].into()
663    /// // After:
664    /// vec![ctx.cgroup_def("cg_0")].into()
665    ///
666    /// // With additional builders:
667    /// ctx.cgroup_def("cg_0").cpuset(...)
668    /// ```
669    pub fn cgroup_def(
670        &self,
671        name: impl Into<std::borrow::Cow<'static, str>>,
672    ) -> crate::scenario::ops::CgroupDef {
673        crate::scenario::ops::CgroupDef::named(name).workers(self.workers_per_cgroup)
674    }
675
676    /// Per-test failure-dump sidecar path. Derives
677    /// `{sidecar_dir()}/{entry_name}-{variant_hash:016x}.failure-dump.json`
678    /// from the macro-stamped [`Self::entry_name`] — the drift-safe
679    /// replacement for the legacy pattern of hardcoding the test
680    /// fn name as a string literal at the callsite.
681    ///
682    /// # Sibling to [`crate::vmm::VmResult::failure_dump_path`]
683    ///
684    /// The post-VM result struct carries its own copy of the
685    /// macro-stamped entry name + computes the same path string.
686    /// A test body invocation `ctx.failure_dump_path()` and a
687    /// post-VM `result.failure_dump_path()` resolve to identical
688    /// paths because both stamp from the same
689    /// `entry.name: &'static str` source — proc-macro emission at
690    /// the `#[ktstr_test]` site.
691    ///
692    /// # Errors
693    ///
694    /// Bails when `self.entry_name` is `None`. The `None` shape is
695    /// the manually-constructed-Ctx escape hatch — ad-hoc scenario
696    /// unit tests build [`Ctx`] via [`CtxBuilder::build`] without
697    /// calling [`CtxBuilder::entry_name`]; such a context cannot
698    /// compute a drift-safe path. The bail diagnostic names the
699    /// missing-stamp scenario explicitly so test authors who hit it
700    /// know exactly which builder method to call.
701    pub fn failure_dump_path(&self) -> anyhow::Result<std::path::PathBuf> {
702        let name = self.entry_name.ok_or_else(|| {
703            anyhow::anyhow!(
704                "Ctx::failure_dump_path requires entry_name set by the \
705                 macro-stamped dispatch path \
706                 (`maybe_dispatch_vm_test_with_args`); reached with \
707                 entry_name = None, which means the Ctx was \
708                 constructed via CtxBuilder::build without calling \
709                 .entry_name(...). Call ctx_builder.entry_name(name) \
710                 explicitly, OR if this is a scenario unit-test fixture \
711                 that has no test-entry context, derive the path inline \
712                 (sidecar_dir().join(format!(\"{{name}}-{{variant_hash:016x}}.failure-dump.json\"))) \
713                 — the method form is for tests dispatched via \
714                 #[ktstr_test], not for builder-driven fixtures."
715            )
716        })?;
717        Ok(crate::test_support::sidecar_dir().join(format!(
718            "{name}-{:016x}.failure-dump.json",
719            self.variant_hash
720        )))
721    }
722
723    /// Per-test wprof Perfetto-trace sidecar path. Mirror of
724    /// [`Self::failure_dump_path`] for the wprof artifact —
725    /// derives `{sidecar_dir()}/{entry_name}-{variant_hash:016x}.wprof.pb`
726    /// from the macro-stamped [`Self::entry_name`].
727    ///
728    /// Sibling to [`crate::vmm::VmResult::wprof_pb_path`] —
729    /// the post-VM and pre-VM derivations produce identical paths.
730    /// See [`Self::failure_dump_path`] for the broader contract +
731    /// the manually-constructed-Ctx None-bail diagnostic.
732    ///
733    /// # Errors
734    ///
735    /// Bails when `self.entry_name` is `None` per the same shape
736    /// as [`Self::failure_dump_path`].
737    #[cfg(feature = "wprof")]
738    pub fn wprof_pb_path(&self) -> anyhow::Result<std::path::PathBuf> {
739        let name = self.entry_name.ok_or_else(|| {
740            anyhow::anyhow!(
741                "Ctx::wprof_pb_path requires entry_name set by the \
742                 macro-stamped dispatch path; reached with \
743                 entry_name = None — see Ctx::failure_dump_path \
744                 for the manually-constructed-Ctx workaround."
745            )
746        })?;
747        Ok(crate::test_support::sidecar_dir()
748            .join(format!("{name}-{:016x}.wprof.pb", self.variant_hash)))
749    }
750
751    #[cfg(feature = "wprof")]
752    pub fn repro_wprof_pb_path(&self) -> anyhow::Result<std::path::PathBuf> {
753        let name = self.entry_name.ok_or_else(|| {
754            anyhow::anyhow!(
755                "Ctx::repro_wprof_pb_path requires entry_name set by \
756                 the macro-stamped dispatch path; reached with \
757                 entry_name = None — see Ctx::failure_dump_path for \
758                 the manually-constructed-Ctx workaround."
759            )
760        })?;
761        Ok(crate::test_support::sidecar_dir()
762            .join(format!("{name}-{:016x}.repro.wprof.pb", self.variant_hash)))
763    }
764}
765
766/// Fluent builder for [`Ctx`].
767///
768/// Scenario unit tests reach for a [`Ctx`] with sane defaults so they
769/// can exercise scenario logic without booting a VM. The direct
770/// struct-literal construction at ~14 call sites forces every test to
771/// repeat the full 12-field init and keeps diverging defaults in sync
772/// by hand; this builder centralises those defaults and keeps required
773/// fields (borrowed `cgroups`/`topo`) in their types.
774///
775/// Defaults:
776/// - `duration`: 1 s — matches the `scenario::basic` test helper
777///   (`scenario::stress` uses 2 s and sets it explicitly)
778/// - `workers_per_cgroup`: 1
779/// - `sched_pid`: `None` — `run_scenario` short-circuits the
780///   liveness checks when `sched_pid.is_none()`.
781/// - `settle`: 0 ms — tests do not need to wait for scheduler stabilisation
782/// - `work_type_override`: `None`
783/// - `assert`: [`crate::assert::Assert::default_checks()`] —
784///   the same policy production paths merge through
785/// - `wait_for_map_write`: `false`
786///
787/// Override any default via the corresponding method, then materialise
788/// the context with [`CtxBuilder::build`].
789///
790/// # Example
791/// ```ignore
792/// let cgroups = CgroupManager::new("/nonexistent");
793/// let topo = TestTopology::synthetic(4, 1);
794/// let ctx = Ctx::builder(&cgroups, &topo)
795///     .workers_per_cgroup(3)
796///     .duration(Duration::from_secs(2))
797///     .build();
798/// ```
799pub struct CtxBuilder<'a> {
800    cgroups: &'a dyn crate::cgroup::CgroupOps,
801    topo: &'a TestTopology,
802    duration: Duration,
803    workers_per_cgroup: usize,
804    sched_pid: Option<libc::pid_t>,
805    settle: Duration,
806    work_type_override: Option<WorkType>,
807    assert: crate::assert::Assert,
808    wait_for_map_write: bool,
809    current_step: Arc<AtomicU16>,
810    entry_name: Option<&'static str>,
811    variant_hash: u64,
812}
813
814impl<'a> CtxBuilder<'a> {
815    /// Wall-clock budget for the workload phase of the scenario.
816    #[must_use = "builder methods consume self; bind the result"]
817    pub fn duration(mut self, d: Duration) -> Self {
818        self.duration = d;
819        self
820    }
821
822    /// Number of worker threads started per cgroup by the default workload.
823    #[must_use = "builder methods consume self; bind the result"]
824    pub fn workers_per_cgroup(mut self, n: usize) -> Self {
825        self.workers_per_cgroup = n;
826        self
827    }
828
829    /// PID of the scheduler process; `None` disables the liveness
830    /// checks in `run_scenario`.
831    #[must_use = "builder methods consume self; bind the result"]
832    pub fn sched_pid(mut self, pid: Option<libc::pid_t>) -> Self {
833        self.sched_pid = pid;
834        self
835    }
836
837    /// Time to wait after cgroup creation for scheduler stabilisation.
838    #[must_use = "builder methods consume self; bind the result"]
839    pub fn settle(mut self, s: Duration) -> Self {
840        self.settle = s;
841        self
842    }
843
844    /// Override the default work type for scenarios that would
845    /// otherwise use `SpinWait`.
846    #[must_use = "builder methods consume self; bind the result"]
847    pub fn work_type_override(mut self, wt: Option<WorkType>) -> Self {
848        self.work_type_override = wt;
849        self
850    }
851
852    /// Merged assertion config. Callers that want the production
853    /// layering should pass `Assert::default_checks().merge(&...)`;
854    /// tests that pin a specific policy can pass
855    /// [`crate::assert::Assert::NO_OVERRIDES`] directly.
856    #[must_use = "builder methods consume self; bind the result"]
857    pub fn assert(mut self, a: crate::assert::Assert) -> Self {
858        self.assert = a;
859        self
860    }
861
862    /// When true, `execute_steps` blocks on the `bpf_map_write_done`
863    /// latch (set on the host's `SIGNAL_BPF_WRITE_DONE` over
864    /// virtio-console RX) after writing the scenario start marker. See
865    /// the field doc on [`Ctx::wait_for_map_write`].
866    #[must_use = "builder methods consume self; bind the result"]
867    pub fn wait_for_map_write(mut self, v: bool) -> Self {
868        self.wait_for_map_write = v;
869        self
870    }
871
872    /// Inject a caller-owned per-VM step-index publisher. The
873    /// default `Ctx::builder` already constructs a fresh
874    /// `Arc<AtomicU16>` initialised to `0`, so most callers do
875    /// not need this setter; it exists so the host-side VM runner
876    /// can hand the same Arc to both the scenario driver `Ctx` and
877    /// the freeze-coordinator thread, giving both halves a single
878    /// per-VM source of truth for the current phase.
879    #[must_use = "builder methods consume self; bind the result"]
880    pub fn current_step(mut self, cs: Arc<AtomicU16>) -> Self {
881        self.current_step = cs;
882        self
883    }
884
885    /// **Drift-safe path derivation.** Stamp the
886    /// `&'static str` name of the
887    /// [`KtstrTestEntry`](crate::test_support::KtstrTestEntry)
888    /// the dispatched test body was registered as. Drives the
889    /// body-side path-derivation methods on [`Ctx`]
890    /// (`failure_dump_path`, `wprof_pb_path`,
891    /// `repro_wprof_pb_path`) so test
892    /// authors get the drift-safe per-test sidecar path without
893    /// re-hardcoding the test fn name in the body — a future test
894    /// rename surfaces a deterministic `Result<PathBuf>` bail
895    /// rather than a runtime ENOENT against a stale literal.
896    ///
897    /// The framework's macro-stamped dispatch path
898    /// (`maybe_dispatch_vm_test_with_args` + the host-only
899    /// dispatcher) calls this with the entry name at Ctx
900    /// construction time, before the test body runs. Ad-hoc
901    /// scenario unit tests that build [`Ctx`] without the dispatch
902    /// path skip this setter, and the path-derivation methods bail
903    /// with an actionable diagnostic — see
904    /// [`Ctx::failure_dump_path`] for the None-case bail shape.
905    #[must_use = "builder methods consume self; bind the result"]
906    pub fn entry_name(mut self, name: &'static str) -> Self {
907        self.entry_name = Some(name);
908        self
909    }
910
911    /// Stamp the run's variant hash (see `variant_hash_from_parts`) so the
912    /// body-side `failure_dump_path` / `wprof_pb_path` derivations embed
913    /// it as the `-{16-hex}` filename suffix. Set at the macro dispatch
914    /// site alongside [`Self::entry_name`]; ad-hoc fixtures leave it `0`.
915    #[must_use = "builder methods consume self; bind the result"]
916    pub fn variant_hash(mut self, hash: u64) -> Self {
917        self.variant_hash = hash;
918        self
919    }
920
921    /// Materialise the configured [`Ctx`].
922    #[must_use = "dropping a Ctx without running the scenario discards the test setup"]
923    pub fn build(self) -> Ctx<'a> {
924        Ctx {
925            cgroups: self.cgroups,
926            topo: self.topo,
927            duration: self.duration,
928            workers_per_cgroup: self.workers_per_cgroup,
929            sched_pid: self.sched_pid,
930            settle: self.settle,
931            work_type_override: self.work_type_override,
932            assert: self.assert,
933            wait_for_map_write: self.wait_for_map_write,
934            current_step: self.current_step,
935            entry_name: self.entry_name,
936            variant_hash: self.variant_hash,
937        }
938    }
939}
940
941impl<'a> Ctx<'a> {
942    /// Start a new [`CtxBuilder`] with required `cgroups` and `topo`
943    /// borrows and sane defaults for every other field. See
944    /// [`CtxBuilder`] for the full default set.
945    #[must_use = "discarding a CtxBuilder drops the scenario context defaults; chain setters and call .build()"]
946    pub fn builder(
947        cgroups: &'a dyn crate::cgroup::CgroupOps,
948        topo: &'a TestTopology,
949    ) -> CtxBuilder<'a> {
950        CtxBuilder {
951            cgroups,
952            topo,
953            duration: Duration::from_secs(1),
954            workers_per_cgroup: 1,
955            sched_pid: None,
956            settle: Duration::from_millis(0),
957            work_type_override: None,
958            assert: crate::assert::Assert::default_checks(),
959            wait_for_map_write: false,
960            current_step: Arc::new(AtomicU16::new(0)),
961            entry_name: None,
962            variant_hash: 0,
963        }
964    }
965
966    /// Start a [`PayloadRun`](crate::scenario::payload_run::PayloadRun)
967    /// builder for the given [`Payload`](crate::test_support::Payload).
968    ///
969    /// The builder inherits `payload.default_args` and
970    /// `payload.default_checks`; chained `.arg(...)` / `.check(...)`
971    /// calls extend them; `.clear_args()` / `.clear_checks()` wipe
972    /// both defaults and prior appends. Terminal `.run()` blocks and
973    /// returns `Result<(AssertResult, PayloadMetrics)>`.
974    ///
975    /// Only `PayloadKind::Binary` payloads are runnable here;
976    /// `.run()` on a `PayloadKind::Scheduler` payload returns `Err`.
977    #[must_use = "dropping a PayloadRun discards the payload configuration; chain setters and call .run()"]
978    pub fn payload(
979        &'a self,
980        p: &'static crate::test_support::Payload,
981    ) -> crate::scenario::payload_run::PayloadRun<'a> {
982        crate::scenario::payload_run::PayloadRun::new(self, p)
983    }
984}
985
986/// Spawn workers per cgroup, move each handle's worker pids into
987/// its cgroup, then start all handles in a second pass.
988///
989/// Shared scaffolding for `run_scenario` and `setup_cgroups` —
990/// both defer `.start()` until every handle has been spawned and
991/// every worker pid moved, so workers see a stable cgroup
992/// membership at first run. [`spawn_diverse`] does NOT use this
993/// helper because it starts each handle inline (eager-start
994/// semantics required for its IoSyncWrite/SpinWait mix — workload
995/// ordering matters when the mix includes I/O-bound and CPU-bound
996/// cgroups).
997///
998/// `cfg_fn` builds the per-cgroup [`WorkloadConfig`] from its
999/// index + name; callers own the per-cgroup customization logic.
1000///
1001/// `move_tasks` is ESRCH-tolerant — a worker that exits between
1002/// fork and cgroup placement is warned and skipped, unlike the
1003/// original per-pid `move_task` which propagated ESRCH.
1004fn spawn_and_move<F>(ctx: &Ctx, names: &[String], mut cfg_fn: F) -> Result<Vec<WorkloadHandle>>
1005where
1006    F: FnMut(usize, &str) -> Result<WorkloadConfig>,
1007{
1008    let mut handles = Vec::with_capacity(names.len());
1009    for (i, name) in names.iter().enumerate() {
1010        let wl = cfg_fn(i, name.as_str())?;
1011        let h = WorkloadHandle::spawn(&wl)?;
1012        tracing::debug!(
1013            cgroup = %name,
1014            workers = wl.num_workers,
1015            pids = h.worker_pids().len(),
1016            "spawned workers",
1017        );
1018        ctx.cgroups
1019            .move_tasks(name.as_str(), &h.worker_pids_for_cgroup_procs()?)?;
1020        handles.push(h);
1021    }
1022    for h in &mut handles {
1023        h.start();
1024    }
1025    Ok(handles)
1026}
1027
1028/// Resolve a [`WorkSpec`]'s `num_workers`, falling back to `default_n` when unset,
1029/// and reject `num_workers=0`.
1030///
1031/// A cgroup with no workers emits no [`crate::workload::WorkerReport`]s, so every downstream
1032/// assertion vacuously passes. Callers that want "no load" on a cgroup
1033/// should either drop the [`crate::workload::WorkSpec`] entry entirely (letting the default apply)
1034/// or use a single sentinel worker so assertions have something to check.
1035pub(crate) fn resolve_num_workers(work: &WorkSpec, default_n: usize, label: &str) -> Result<usize> {
1036    let n = work.num_workers.unwrap_or(default_n);
1037    if n == 0 {
1038        anyhow::bail!(
1039            "cgroup '{}': num_workers=0 is not allowed — assertions would \
1040             vacuously pass with no WorkerReports; use at least 1 worker or \
1041             drop this WorkSpec entry",
1042            label,
1043        );
1044    }
1045    Ok(n)
1046}
1047
1048/// Resolve an [`AffinityIntent`] to a concrete [`ResolvedAffinity`]
1049/// for workers in a cgroup with the given effective cpuset.
1050///
1051/// # Errors
1052///
1053/// Returns `Err` when the test author's affinity intent cannot be
1054/// satisfied against the cgroup's effective cpuset. Per the
1055/// project-wide no-silent-drops invariant, an unsatisfiable
1056/// intent must surface as a returnable error rather than silently
1057/// degrading to "no affinity applied" — silent degradation lets
1058/// the workload run with the wrong placement while the test
1059/// reports success (vacuously-passing assertions).
1060///
1061/// The unsatisfiable cases by variant:
1062/// - [`AffinityIntent::RandomSubset`]: `from` pool empty after
1063///   cpuset intersection, or `count == 0`.
1064/// - [`AffinityIntent::LlcAligned`]: every LLC's CPUs disjoint
1065///   from the cpuset (no LLC has any CPU inside the cpuset).
1066/// - [`AffinityIntent::SingleCpu`]: cpuset is empty.
1067/// - [`AffinityIntent::Exact`]: requested CPU set is empty
1068///   (`Exact(BTreeSet::new())` is intent-only unsatisfiable),
1069///   or requested CPU set disjoint from the cpuset
1070///   (intersection empty).
1071/// - [`AffinityIntent::SmtSiblingPair`]: no physical core with
1072///   ≥2 SMT siblings inside the cpuset.
1073/// - [`AffinityIntent::CrossCgroup`]: topology exposes zero CPUs.
1074///   The public [`crate::topology::TestTopology`] constructors all
1075///   reject this at construction; reaching this case requires a
1076///   private-field construction or a future API addition.
1077///
1078/// Every error diagnostic names the offending intent and a
1079/// remediation hint. Diagnostics for cpuset-narrowed pools
1080/// (`RandomSubset` empty intersection, `LlcAligned`, `SingleCpu`,
1081/// `Exact` disjoint-intersection, `SmtSiblingPair`) also render the
1082/// cpuset that narrowed the pool. The intent-only errors —
1083/// `RandomSubset { count: 0 }` and `Exact(BTreeSet::new())` — omit
1084/// the cpuset because the cpuset is irrelevant to the failure (the
1085/// intent itself names zero CPUs). Remediation hints include
1086/// switching to [`AffinityIntent::Inherit`] to deliberately inherit
1087/// the cpuset, widening the cgroup's cpuset, or picking CPUs inside
1088/// the cpuset.
1089pub fn resolve_affinity_for_cgroup(
1090    kind: &AffinityIntent,
1091    cpuset: Option<&BTreeSet<usize>>,
1092    topo: &TestTopology,
1093) -> Result<ResolvedAffinity> {
1094    match kind {
1095        AffinityIntent::Inherit => Ok(ResolvedAffinity::None),
1096        AffinityIntent::RandomSubset { from, count } => {
1097            // Validate the intent itself (count > 0) before doing any
1098            // resource work — an intent-only bug (count==0) doesn't
1099            // need an allocation to diagnose.
1100            if *count == 0 {
1101                anyhow::bail!(
1102                    "AffinityIntent::RandomSubset count=0 cannot satisfy any sample. \
1103                     Switch to `AffinityIntent::Inherit` to deliberately inherit the \
1104                     cgroup cpuset, or pass `count >= 1`.",
1105                );
1106            }
1107            // The pool is already resolved by the caller (typed
1108            // `from`). Intersect with the cgroup's cpuset if one is
1109            // active so the resolved pool stays within the
1110            // scenario's CPU budget — same intersection semantic
1111            // applied to `Exact` below.
1112            let pool = if let Some(cs) = cpuset {
1113                from.intersection(cs).copied().collect::<BTreeSet<usize>>()
1114            } else {
1115                from.clone()
1116            };
1117            if pool.is_empty() {
1118                if cpuset.is_some() {
1119                    let cpuset_repr = format_cpuset_for_diag(cpuset);
1120                    anyhow::bail!(
1121                        "AffinityIntent::RandomSubset has no CPUs after intersecting \
1122                         `from={from:?}` with the cgroup cpuset ({cpuset_repr}). \
1123                         Switch to `AffinityIntent::Inherit` to deliberately inherit \
1124                         the cgroup cpuset, widen the cgroup's cpuset, or pick a \
1125                         `from` set that overlaps the cpuset.",
1126                    );
1127                } else {
1128                    anyhow::bail!(
1129                        "AffinityIntent::RandomSubset has an empty `from` pool with \
1130                         no cgroup cpuset to narrow it — there is no CPU to sample. \
1131                         Switch to `AffinityIntent::Inherit` to deliberately inherit \
1132                         the scenario's CPU budget, or pass a non-empty `from` set.",
1133                    );
1134                }
1135            }
1136            Ok(ResolvedAffinity::Random {
1137                from: pool,
1138                count: *count,
1139            })
1140        }
1141        AffinityIntent::LlcAligned => {
1142            let pool = cpuset.cloned().unwrap_or_else(|| topo.all_cpuset());
1143            // Find the LLC that has the most overlap with the cpuset.
1144            let mut best_llc = topo.llc_aligned_cpuset(0);
1145            let mut best_overlap = best_llc.intersection(&pool).count();
1146            for idx in 1..topo.num_llcs() {
1147                let llc = topo.llc_aligned_cpuset(idx);
1148                let overlap = llc.intersection(&pool).count();
1149                if overlap > best_overlap {
1150                    best_llc = llc;
1151                    best_overlap = overlap;
1152                }
1153            }
1154            // Intersect with cpuset so effective affinity matches kernel behavior.
1155            let effective: BTreeSet<usize> = best_llc.intersection(&pool).copied().collect();
1156            if effective.is_empty() {
1157                let cpuset_repr = format_cpuset_for_diag(cpuset);
1158                anyhow::bail!(
1159                    "AffinityIntent::LlcAligned has no CPUs after intersecting every \
1160                     LLC with the cgroup cpuset ({cpuset_repr}). No LLC has any CPU \
1161                     inside the cpuset. Switch to `AffinityIntent::Inherit` to \
1162                     deliberately inherit the cpuset, widen the cgroup's cpuset to \
1163                     include CPUs from at least one LLC, or pick a different \
1164                     affinity intent that doesn't require LLC alignment.",
1165                );
1166            }
1167            Ok(ResolvedAffinity::Fixed(effective))
1168        }
1169        AffinityIntent::CrossCgroup => {
1170            // When a cpuset is active, crossing cgroup boundaries is the intent,
1171            // but the kernel will intersect. Use all CPUs -- the kernel enforces
1172            // the cpuset constraint.
1173            let all = topo.all_cpuset();
1174            if all.is_empty() {
1175                // Defense-in-depth against zero-CPU topologies. The two
1176                // public TestTopology constructors (`synthetic` +
1177                // `from_vm_topology`) both reject `num_cpus == 0` at
1178                // construction, so reaching this branch requires a
1179                // private-field construction or a future API addition
1180                // that produces a zero-CPU topology. Without this bail
1181                // an empty `Fixed` would either trip the
1182                // `flatten_for_spawn` unreachable!() OR (if reached via
1183                // a path that bypassed flatten) silently produce an
1184                // empty `sched_setaffinity` mask the kernel rejects
1185                // with EINVAL after the cgroup intersection.
1186                anyhow::bail!(
1187                    "AffinityIntent::CrossCgroup cannot satisfy any worker — \
1188                     the topology exposes zero CPUs. The public \
1189                     TestTopology constructors (`synthetic` + \
1190                     `from_vm_topology`) reject this at construction; \
1191                     reaching this bail means a direct private-field \
1192                     construction or a future API addition produced a \
1193                     zero-CPU topology. Build the test against a \
1194                     topology with at least one CPU, or switch to \
1195                     `AffinityIntent::Inherit` to defer to the cgroup \
1196                     cpuset.",
1197                );
1198            }
1199            Ok(ResolvedAffinity::Fixed(all))
1200        }
1201        AffinityIntent::SingleCpu => {
1202            let pool = cpuset.cloned().unwrap_or_else(|| topo.all_cpuset());
1203            if let Some(&cpu) = pool.iter().next() {
1204                Ok(ResolvedAffinity::SingleCpu(cpu))
1205            } else {
1206                // Pool is empty only when cpuset is Some(empty) — `all_cpuset()`
1207                // returns at least the boot CPU for any non-degenerate topology.
1208                anyhow::bail!(
1209                    "AffinityIntent::SingleCpu cannot pick a CPU from an empty \
1210                     cgroup cpuset. Switch to `AffinityIntent::Inherit` to \
1211                     deliberately inherit (the empty cpuset is itself the \
1212                     problem), or assign a non-empty cpuset to the cgroup.",
1213                );
1214            }
1215        }
1216        AffinityIntent::Exact(cpus) => {
1217            if cpus.is_empty() {
1218                // Empty Exact is the most-explicit way a user can say
1219                // "I made a mistake" — silently degrading it to
1220                // Inherit is the same no-silent-drop violation as the
1221                // disjoint-intersection case below.
1222                anyhow::bail!(
1223                    "AffinityIntent::Exact(BTreeSet::new()) is unsatisfiable — an \
1224                     empty CPU set pins workers to nothing. Switch to \
1225                     `AffinityIntent::Inherit` to deliberately inherit the cgroup \
1226                     cpuset (or the full topology when no cpuset is active), or \
1227                     pass at least one CPU ID.",
1228                );
1229            }
1230            if let Some(cs) = cpuset {
1231                let effective: BTreeSet<usize> = cpus.intersection(cs).copied().collect();
1232                if effective.is_empty() {
1233                    let cpuset_repr = format_cpuset_for_diag(cpuset);
1234                    anyhow::bail!(
1235                        "AffinityIntent::Exact({cpus:?}) is disjoint from the cgroup \
1236                         cpuset ({cpuset_repr}); intersection is empty. Switch to \
1237                         `AffinityIntent::Inherit` to deliberately inherit the cpuset, \
1238                         widen the cgroup's cpuset to include the requested CPUs, or \
1239                         narrow the `Exact` set to CPUs inside the cpuset.",
1240                    );
1241                }
1242                Ok(ResolvedAffinity::Fixed(effective))
1243            } else {
1244                Ok(ResolvedAffinity::Fixed(cpus.clone()))
1245            }
1246        }
1247        AffinityIntent::SmtSiblingPair => resolve_smt_sibling_pair(cpuset, topo),
1248    }
1249}
1250
1251/// Render a cgroup cpuset for the bail diagnostics on
1252/// [`resolve_affinity_for_cgroup`]'s unsatisfiable arms. `None`
1253/// renders as `<no cpuset>` so the operator can distinguish
1254/// "cpuset is empty" from "no cpuset is active" — both can produce
1255/// an empty intersection on different intents.
1256fn format_cpuset_for_diag(cpuset: Option<&BTreeSet<usize>>) -> String {
1257    match cpuset {
1258        Some(cs) if cs.is_empty() => "empty cpuset {}".to_string(),
1259        Some(cs) => format!("cpuset {cs:?}"),
1260        None => "<no cpuset>".to_string(),
1261    }
1262}
1263
1264/// Resolve [`AffinityIntent::SmtSiblingPair`] against the cgroup's
1265/// effective cpuset.
1266///
1267/// Walks every LLC's per-core sibling map looking for a physical
1268/// core whose SMT siblings are all present in the pool (cgroup's
1269/// cpuset, or the full topology when no cpuset is active). Returns
1270/// the first matching pair as [`ResolvedAffinity::Fixed`] containing
1271/// the two sibling CPU IDs.
1272///
1273/// Returns `Err` when no core has 2+ siblings in the pool —
1274/// `threads_per_core == 1` (SMT disabled or non-SMT host), the
1275/// cpuset isolates each sibling onto a different cgroup, or the
1276/// topology was constructed without per-core sibling data
1277/// (`LlcInfo::cores` empty — see `crate::topology::TestTopology::synthetic`). The
1278/// error path is explicit, not a silent fallback, because
1279/// [`WorkType::SmtSiblingSpin`] and other paired-on-siblings
1280/// workloads produce meaningless results without true SMT
1281/// contention.
1282///
1283/// All workers in the group resolve to the same 2-CPU set; for
1284/// `num_workers == 2` the kernel runs one worker on each sibling,
1285/// which is the contention pattern this intent targets. For
1286/// `num_workers > 2` (multiple pairs in one group) every worker
1287/// shares the same pair — the kernel time-slices them, which
1288/// approximates pair contention but does not place each pair on
1289/// distinct cores. Strict per-pair distribution across cores
1290/// requires per-worker affinity that the current
1291/// [`ResolvedAffinity`] model does not express; track via a
1292/// follow-up if a test author needs it.
1293///
1294/// [`WorkType::SmtSiblingSpin`]: crate::workload::WorkType::SmtSiblingSpin
1295/// [`AffinityIntent::SmtSiblingPair`]: crate::workload::AffinityIntent::SmtSiblingPair
1296fn resolve_smt_sibling_pair(
1297    cpuset: Option<&BTreeSet<usize>>,
1298    topo: &TestTopology,
1299) -> Result<ResolvedAffinity> {
1300    let pool = cpuset.cloned().unwrap_or_else(|| topo.all_cpuset());
1301    for llc in topo.llcs() {
1302        for siblings in llc.cores().values() {
1303            // Take the first two sibling CPUs that are both in the
1304            // pool. `cores()` is sorted; pairing the lowest two
1305            // present siblings gives a deterministic choice for a
1306            // given (topology, cpuset) input.
1307            let mut iter = siblings.iter().copied().filter(|cpu| pool.contains(cpu));
1308            if let (Some(a), Some(b)) = (iter.next(), iter.next()) {
1309                let pair: BTreeSet<usize> = [a, b].into_iter().collect();
1310                return Ok(ResolvedAffinity::Fixed(pair));
1311            }
1312        }
1313    }
1314    // Render the search scope: when a cpuset narrowed the pool, name
1315    // it (operator can widen / pick siblings inside it); when no
1316    // cpuset is active, the scope IS the full topology (operator must
1317    // adjust topology or switch intents — naming "<no cpuset>" would
1318    // mislead by implying cpuset config is relevant).
1319    let scope = if cpuset.is_some() {
1320        format!("the effective cpuset ({})", format_cpuset_for_diag(cpuset))
1321    } else {
1322        "the full topology (no cgroup cpuset is active)".to_string()
1323    };
1324    anyhow::bail!(
1325        "AffinityIntent::SmtSiblingPair requires a physical core with at \
1326         least two SMT siblings present in {scope}. The current topology \
1327         and cpuset expose no such pair — threads_per_core may be 1 (SMT \
1328         disabled or non-SMT host), the cpuset may have isolated each \
1329         sibling onto a different cgroup, or the topology was built \
1330         without per-core sibling data. Switch to a different \
1331         AffinityIntent for non-SMT scheduling tests, or run on a host \
1332         whose VM topology has threads_per_core >= 2.",
1333    );
1334}
1335
1336/// Resolve an [`AffinityIntent`] for direct storage in
1337/// [`crate::workload::WorkloadConfig::affinity`].
1338///
1339/// [`crate::workload::WorkloadConfig::affinity`] is an
1340/// [`AffinityIntent`] (type-unified with [`crate::workload::WorkSpec::affinity`])
1341/// and its spawn-time gate (see
1342/// [`crate::workload::WorkloadHandle::spawn`]) accepts
1343/// [`AffinityIntent::Inherit`], [`AffinityIntent::Exact`], and
1344/// [`AffinityIntent::RandomSubset`]. The scenario engine holds the
1345/// topology and cpuset that the spawn-time gate lacks, so it
1346/// pre-resolves topology-aware variants here:
1347///
1348/// - [`ResolvedAffinity::None`] → [`AffinityIntent::Inherit`]
1349/// - [`ResolvedAffinity::Fixed(set)`](ResolvedAffinity::Fixed) →
1350///   [`AffinityIntent::Exact(set)`](AffinityIntent::Exact)
1351/// - [`ResolvedAffinity::SingleCpu(cpu)`](ResolvedAffinity::SingleCpu) →
1352///   [`AffinityIntent::Exact`] containing `cpu`
1353/// - [`ResolvedAffinity::Random { from, count }`](ResolvedAffinity::Random) →
1354///   [`AffinityIntent::RandomSubset { from, count }`](AffinityIntent::RandomSubset)
1355///   — the resolved pool is forwarded verbatim and per-worker
1356///   sampling stays deferred to spawn time (each worker gets an
1357///   independent draw from `from`).
1358///
1359/// # Errors
1360///
1361/// Forwards every `Err` from the inner [`resolve_affinity_for_cgroup`]
1362/// — see that function's `# Errors` section for the full list of
1363/// unsatisfiable cases (RandomSubset empty pool / count=0,
1364/// LlcAligned no-overlap, SingleCpu empty cpuset, Exact empty or
1365/// disjoint, SmtSiblingPair no-pair-in-cpuset, CrossCgroup on
1366/// zero-CPU topology). The empty-pool "silent degrade to Inherit"
1367/// policy that previously lived here was removed — empty pools are
1368/// operator bugs, not "soft" fallbacks.
1369pub(crate) fn intent_for_spawn(
1370    kind: &AffinityIntent,
1371    cpuset: Option<&BTreeSet<usize>>,
1372    topo: &TestTopology,
1373) -> Result<AffinityIntent> {
1374    Ok(flatten_for_spawn(resolve_affinity_for_cgroup(
1375        kind, cpuset, topo,
1376    )?))
1377}
1378
1379fn flatten_for_spawn(resolved: ResolvedAffinity) -> AffinityIntent {
1380    match resolved {
1381        ResolvedAffinity::None => AffinityIntent::Inherit,
1382        ResolvedAffinity::Fixed(set) => {
1383            if set.is_empty() {
1384                // Invariant: resolve_affinity_for_cgroup bails before
1385                // constructing an empty Fixed (LlcAligned
1386                // empty-effective bail, Exact empty-input bail, Exact
1387                // disjoint-intersection bail, CrossCgroup zero-CPU
1388                // topology bail). Reaching here means a future
1389                // constructor of ResolvedAffinity::Fixed bypassed
1390                // those checks — panic loudly so the regression
1391                // surfaces at the construction site, not as a silent
1392                // inheritance downstream.
1393                unreachable!(
1394                    "ResolvedAffinity::Fixed(empty) reached flatten_for_spawn — \
1395                     resolve_affinity_for_cgroup is supposed to bail on every \
1396                     path that produces an empty Fixed (no-silent-drops \
1397                     invariant). Audit the new caller that constructed it.",
1398                )
1399            } else {
1400                AffinityIntent::Exact(set)
1401            }
1402        }
1403        ResolvedAffinity::SingleCpu(cpu) => AffinityIntent::Exact([cpu].into_iter().collect()),
1404        ResolvedAffinity::Random { from, count } => {
1405            // Round-trip the resolved pool through
1406            // [`AffinityIntent::RandomSubset`] so per-worker
1407            // sampling stays deferred to spawn time
1408            // (`workload::resolve_affinity` samples each worker
1409            // independently).
1410            if count == 0 || from.is_empty() {
1411                // Invariant: resolve_affinity_for_cgroup bails on
1412                // RandomSubset { count: 0 } and on empty intersected
1413                // pools. Same regression-surface contract as the
1414                // Fixed arm above.
1415                unreachable!(
1416                    "ResolvedAffinity::Random {{ count={count}, from={from:?} }} \
1417                     reached flatten_for_spawn with count==0 or empty pool — \
1418                     resolve_affinity_for_cgroup is supposed to bail on those \
1419                     cases (no-silent-drops invariant). Audit the new caller \
1420                     that constructed it.",
1421                )
1422            } else {
1423                AffinityIntent::RandomSubset { from, count }
1424            }
1425        }
1426    }
1427}
1428
1429// ---------------------------------------------------------------------------
1430// Custom scenario helpers
1431// ---------------------------------------------------------------------------
1432
1433/// Create N cgroups, spawn workers in each, and start them.
1434///
1435/// Returns the worker handles and an RAII [`CgroupGroup`] that removes
1436/// the cgroups on drop. Workers are moved into their target cgroups
1437/// before being signaled to start.
1438pub fn setup_cgroups<'a>(
1439    ctx: &'a Ctx,
1440    n: usize,
1441    wl: &WorkloadConfig,
1442) -> Result<(Vec<WorkloadHandle>, CgroupGroup<'a>)> {
1443    let mut guard = CgroupGroup::new(ctx.cgroups);
1444    for i in 0..n {
1445        guard.add_cgroup_no_cpuset(&format!("cg_{i}"))?;
1446    }
1447    thread::sleep(ctx.settle);
1448    // `active_sched_pid()` returns `None` when no scheduler was
1449    // configured (kernel-default path) OR when the caller planted a
1450    // `<= 0` sentinel; both cases skip the liveness-based bail.
1451    if let Some(pid) = ctx.active_sched_pid() {
1452        let alive = configured_scheduler_alive(pid).map_err(|error| {
1453            anyhow::anyhow!(
1454                "{} after cgroup creation: retained scheduler pidfd liveness \
1455                 failed (snapshot pid={}): {}",
1456                crate::assert::SCHED_DIED_PREFIX,
1457                pid,
1458                error,
1459            )
1460        })?;
1461        if !alive {
1462            anyhow::bail!(
1463                "{} after cgroup creation (snapshot pid={})",
1464                crate::assert::SCHED_DIED_PREFIX,
1465                pid,
1466            );
1467        }
1468    }
1469    let names: Vec<String> = (0..n).map(|i| format!("cg_{i}")).collect();
1470    let handles = spawn_and_move(ctx, &names, |_, _| Ok(wl.clone()))?;
1471    Ok((handles, guard))
1472}
1473
1474/// Stop workers, collect reports, and merge per-cgroup telemetry +
1475/// assertion results.
1476///
1477/// Each item is a `(WorkloadHandle, Option<&BTreeSet<usize>>)` pair
1478/// where the optional cpuset is passed through to
1479/// [`Assert::assert_cgroup`](crate::assert::Assert::assert_cgroup)
1480/// for isolation checks. Per-cgroup telemetry ([`crate::assert::CgroupStats`])
1481/// is produced for EVERY handle — one entry per declared cgroup,
1482/// including a `num_workers == 0` entry for a handle that collected no
1483/// reports — independent of whether any worker-level check is configured.
1484/// Worker-check assertion outcomes are recorded only for the checks the
1485/// caller set. (Telemetry was previously gated behind
1486/// `checks.has_worker_checks()`, which silently left
1487/// `ScenarioStats.cgroups` empty for tests that read the telemetry
1488/// without configuring a check.)
1489pub(crate) fn collect_handles<'a>(
1490    handles: impl IntoIterator<Item = (String, WorkloadHandle, Option<&'a BTreeSet<usize>>)>,
1491    checks: &crate::assert::Assert,
1492    topo: Option<&crate::topology::TestTopology>,
1493    step_index: Option<u16>,
1494) -> AssertResult {
1495    let mut r = AssertResult::pass();
1496    for (name, h, cpuset) in handles {
1497        // Bind the cgroup name before it is moved into cg.cgroup_name below,
1498        // so the per-phase per_cgroup carrier can key on it.
1499        let key = name.clone();
1500        let reports = h.stop_and_collect();
1501        let numa_nodes = cpuset.and_then(|cs| topo.map(|t| t.numa_nodes_for_cpuset(cs)));
1502        let mut one = checks.assert_cgroup_with_numa(&reports, cpuset, numa_nodes.as_ref());
1503        // `assert_cgroup_with_numa` produces exactly one CgroupStats entry
1504        // (scenario_stats_for_cgroup); no sub-check populates stats.cgroups,
1505        // so last_mut() is that entry. Label it with the cgroup name here —
1506        // the name is in scope only at the collection layer; cgroup_stats
1507        // sees only the reports. merge() extends cgroups, so the label
1508        // survives the roll-up and surfaces per-cgroup on a passing run.
1509        // The debug_assert trips immediately (in any debug-build test path)
1510        // if a future sub-assert ever adds a second cgroups entry, which
1511        // would make last_mut() mislabel the wrong one.
1512        debug_assert_eq!(
1513            one.stats.cgroups.len(),
1514            1,
1515            "assert_cgroup_with_numa must yield exactly one cgroup entry for \
1516             collect_handles to label correctly; got {}",
1517            one.stats.cgroups.len(),
1518        );
1519        if let Some(cg) = one.stats.cgroups.last_mut() {
1520            cg.cgroup_name = name;
1521        }
1522        // For a step-local cgroup (step_index Some), attach the per-phase
1523        // RAW per-cgroup components as a single-bucket phases entry keyed by the
1524        // step's 1-indexed step_index. AssertResult::merge unions per_cgroup by
1525        // name, so multiple cgroups in one step accumulate into the one bucket;
1526        // the host eval fold then unions these into the host-rebuilt buckets.
1527        // None: a backdrop handle expands each worker's PhaseSlices into
1528        // per-epoch buckets (expand_backdrop_phase_buckets); collect_all and
1529        // the non-step staging collect carry no PhaseSlices, so the
1530        // expansion yields an empty Vec (effectively nothing).
1531        match step_index {
1532            Some(idx) => {
1533                one.stats.phases = vec![crate::assert::step_per_cgroup_bucket(
1534                    &key,
1535                    &reports,
1536                    numa_nodes.as_ref(),
1537                    idx,
1538                )];
1539            }
1540            None => {
1541                // Backdrop (collected with no step_index): expand each
1542                // worker's per-phase PhaseSlices into one PhaseBucket per
1543                // epoch (BASELINE / inter-step-gap epochs skipped). The
1544                // host's fold_guest_per_cgroup_into_host_buckets then
1545                // unions these into the host-rebuilt buckets (matched
1546                // epochs) or surfaces them as orphan not-measured windows.
1547                one.stats.phases = crate::assert::expand_backdrop_phase_buckets(
1548                    &key,
1549                    &reports,
1550                    numa_nodes.as_ref(),
1551                );
1552            }
1553        }
1554        // Handle iteration order IS the per_cgroup fold order: AssertResult::merge
1555        // folds same-name carriers (a multi-WorkSpec cgroup's per-handle carriers)
1556        // in this order, and PhaseCgroupStats::merge's coupled-gap last-wins
1557        // tie-break depends on it matching the order cgroup_stats pools the reports
1558        // (also handle order) for gap-CPU parity. A reorder here would desync them.
1559        r.merge(one);
1560    }
1561    r
1562}
1563
1564/// Stop all workers, collect reports, and run assertion checks.
1565///
1566/// Uses `checks` for worker evaluation. Returns a merged
1567/// [`AssertResult`] across all workers.
1568pub fn collect_all(handles: Vec<WorkloadHandle>, checks: &crate::assert::Assert) -> AssertResult {
1569    collect_handles(
1570        handles.into_iter().map(|h| (String::new(), h, None)),
1571        checks,
1572        None,
1573        // No step concept for the bare collect_all path -> no phase attribution.
1574        None,
1575    )
1576}
1577
1578/// Default [`WorkloadConfig`] with `ctx.workers_per_cgroup` workers.
1579pub fn dfl_wl(ctx: &Ctx) -> WorkloadConfig {
1580    WorkloadConfig {
1581        num_workers: ctx.workers_per_cgroup,
1582        ..Default::default()
1583    }
1584}
1585
1586#[cfg(test)]
1587pub fn split_half(ctx: &Ctx) -> (BTreeSet<usize>, BTreeSet<usize>) {
1588    let usable = ctx.topo.usable_cpus();
1589    let mid = usable.len() / 2;
1590    (
1591        usable[..mid].iter().copied().collect(),
1592        usable[mid..].iter().copied().collect(),
1593    )
1594}
1595
1596/// Spawn diverse workloads across N cgroups: SpinWait, Bursty,
1597/// IoSyncWrite, Mixed, YieldHeavy. Each cgroup uses
1598/// `ctx.workers_per_cgroup` workers except IoSyncWrite cgroups,
1599/// which always use 2 workers to avoid drowning the scenario in
1600/// blocking IO.
1601pub fn spawn_diverse(ctx: &Ctx, cgroup_names: &[&str]) -> Result<Vec<WorkloadHandle>> {
1602    let types = [
1603        WorkType::SpinWait,
1604        WorkType::bursty(Duration::from_millis(50), Duration::from_millis(100)),
1605        WorkType::IoSyncWrite,
1606        WorkType::Mixed,
1607        WorkType::YieldHeavy,
1608    ];
1609    let mut handles = Vec::new();
1610    for (i, name) in cgroup_names.iter().enumerate() {
1611        let wt = types[i % types.len()].clone();
1612        let n = if matches!(wt, WorkType::IoSyncWrite) {
1613            2
1614        } else {
1615            ctx.workers_per_cgroup
1616        };
1617        let mut h = WorkloadHandle::spawn(&WorkloadConfig {
1618            num_workers: n,
1619            work_type: wt,
1620            ..Default::default()
1621        })?;
1622        ctx.cgroups
1623            .move_tasks(name, &h.worker_pids_for_cgroup_procs()?)?;
1624        h.start();
1625        handles.push(h);
1626    }
1627    Ok(handles)
1628}
1629
1630#[cfg(test)]
1631mod tests;