Module scenario 

Scenario definitions and test execution.

Most tests use the declarative ops API from the ops submodule:

• ops::CgroupDef – declarative cgroup definition (name + cpuset + workload)
• ops::Step – a sequence of ops followed by a hold period
• 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)
• ops::CpusetSpec – how to compute a cpuset from topology
• ops::HoldSpec – how long to hold after a step
• backdrop::Backdrop – persistent scenario state shared across every Step
• ops::execute_defs – run cgroup definitions for the full duration
• ops::execute_steps – run a multi-step sequence
• ops::execute_scenario – run a Backdrop + Steps sequence

Types defined in this module:

• Ctx – runtime context passed to scenario functions
• CgroupGroup – RAII guard that removes cgroups on drop

The scenarios submodule provides curated canned scenarios.

Builder method conventions

Every builder type in the scenario API (Setup, Step, Backdrop, WorkloadConfig, …) names its methods by what they do, not by what they return. The three-prefix vocabulary is uniform across the scenario surface so a reader can predict semantics from the prefix alone:

• with_X(arg) -> Self — alternate constructor that returns a fresh value with X already set (e.g. ops::Step::with_defs, ops::Step::with_payload, ops::Setup::with_factory). Distinct from Self::new(...) which is the base ctor; with_X constructors compose without reaching for Default::default() then chaining setters.
• set_X(self, value) -> Self — field REPLACE on an existing builder. Consumes self, writes X, returns the updated value (e.g. ops::Step::set_ops, ops::Step::set_hold). Previous contents of X are discarded.
• push_X(self, value) -> Self / extend_X<I>(self, iter) -> Self — field APPEND. push_X adds one element, extend_X adds many from any IntoIterator (e.g. backdrop::Backdrop::push_cgroup / backdrop::Backdrop::extend_cgroups).

Naming an APPEND method set_X (or a REPLACE method push_X) mis-encodes the semantics and is a defect — flag at review.

See the Scenarios and Writing Tests chapters of the guide.

Re-exports

pub use backdrop::Backdrop;

pub use crate::workload::AffinityIntent;

Modules

affinity

CPU affinity scenario implementations.

backdrop

Persistent scenario state that lives across every Step in a #[ktstr_test] run.

basic

Basic and mixed-workload scenario implementations.

bpf_pin

Guest-side BPF map fd pinning. See crate::scenario::ops::Op::PinBpfMap for the full motivation; in short, the same-binary Op::ReplaceScheduler swap window’s multi-bss case (two <obj>.bss copies coexisting while the dying scheduler’s BPF object is being torn down) only fires when both copies are still alive at freeze time, and the kernel frees the dying instance’s maps as soon as libbpf drops their fds. Holding an extra refcount via this helper keeps the dying scheduler’s map alive long enough for at least one post-swap freeze to observe both copies, which is what the framework’s crate::scenario::snapshot::Snapshot::active plus walker disambiguation chain exists to handle.

cpuset

Cpuset mutation scenario implementations.

dynamic

Dynamic cgroup add/remove scenario implementations.

host_stall

Host-mode worker stall detection via /proc/<pid>/sched polling.

interaction

Cross-cgroup interaction scenario implementations.

nested

Nested cgroup hierarchy scenario implementations.

ops

Composable ops/steps system for dynamic cgroup topology changes.

payload_run

Runtime builder for launching a Payload from a test body.

performance

Performance and benchmarking scenario implementations.

sample

Unified periodic-sample bundle and series projection.

scenarios

Curated canned scenarios for common scheduler test patterns.

snapshot

Diagnostic snapshot capture and traversal.

stress

Stress and edge-case scenario implementations.

Structs

CgroupGroup

RAII guard that removes cgroups on drop.

Ctx

Runtime context passed to scenario functions.

CtxBuilder

Fluent builder for Ctx.

Functions

collect_all

Stop all workers, collect reports, and run assertion checks.

dfl_wl

Default WorkloadConfig with ctx.workers_per_cgroup workers.

resolve_affinity_for_cgroup

Resolve an AffinityIntent to a concrete ResolvedAffinity for workers in a cgroup with the given effective cpuset.

setup_cgroups

Create N cgroups, spawn workers in each, and start them.

spawn_diverse

Spawn diverse workloads across N cgroups: SpinWait, Bursty, IoSyncWrite, Mixed, YieldHeavy. Each cgroup uses ctx.workers_per_cgroup workers except IoSyncWrite cgroups, which always use 2 workers to avoid drowning the scenario in blocking IO.