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;