Module prelude

Module prelude 

Source
Expand description

Re-exports for writing #[ktstr_test] functions.

use ktstr::prelude::*;

#[ktstr_test(llcs = 1, cores = 2, threads = 1)]
fn my_test(ctx: &Ctx) -> Result<AssertResult> {
    Ok(AssertResult::pass())
}

For curated canned scenarios, see scenario::scenarios.

Re-exports§

pub use crate::assert::AbsoluteThresholds;
pub use crate::assert::Assert;
pub use crate::assert::AssertDetail;
pub use crate::assert::AssertResult;
pub use crate::assert::COMPARATOR_VOCABULARY;
pub use crate::assert::CgroupStats;
pub use crate::assert::CgroupStatsClaim;
pub use crate::assert::ClaimBuilder;
pub use crate::assert::DetailKind;
pub use crate::assert::EachClaim;
pub use crate::assert::FracPair;
pub use crate::assert::InfoNote;
pub use crate::assert::MAX_RECORDED_PASSES;
pub use crate::assert::NoteValue;
pub use crate::assert::Outcome;
pub use crate::assert::OutcomeRef;
pub use crate::assert::PASSES_TRUNCATION_SENTINEL_COMPARATOR;
pub use crate::assert::PASSES_TRUNCATION_SENTINEL_NAME;
pub use crate::assert::PassDetail;
pub use crate::assert::PhaseBucket;
pub use crate::assert::PhaseBucketClaim;
pub use crate::assert::PhaseCgroupStats;
pub use crate::assert::PhaseCgroupStatsClaim;
pub use crate::assert::PhaseMapExt;
pub use crate::assert::ScenarioStats;
pub use crate::assert::ScenarioStatsClaim;
pub use crate::assert::SeqClaim;
pub use crate::assert::SeriesField;
pub use crate::assert::SetClaim;
pub use crate::assert::Verdict;
pub use crate::assert::assert_scx_events_clean;
pub use crate::assert::assert_thresholds;
pub use crate::assert::build_phase_buckets_with_stimulus;
pub use crate::cgroup::CgroupManager;
pub use crate::host_context::HostContext;
pub use crate::host_heap::HostHeapState;
pub use crate::scenario::backdrop::Backdrop;
pub use crate::scenario::ops::CgroupDef;
pub use crate::scenario::ops::CpusetSpec;
pub use crate::scenario::ops::HoldSpec;
pub use crate::scenario::ops::IrqSelector;
pub use crate::scenario::ops::KernelTarget;
pub use crate::scenario::ops::KernelValue;
pub use crate::scenario::ops::KernelValueWidth;
pub use crate::scenario::ops::Op;
pub use crate::scenario::ops::Setup;
pub use crate::scenario::ops::SpawnPlacement;
pub use crate::scenario::ops::Step;
pub use crate::scenario::ops::execute_defs;
pub use crate::scenario::ops::execute_scenario;
pub use crate::scenario::ops::execute_scenario_with;
pub use crate::scenario::ops::execute_steps;
pub use crate::scenario::ops::execute_steps_with;
pub use crate::scenario::payload_run::PayloadHandle;
pub use crate::scenario::payload_run::PayloadRun;
pub use crate::scenario::scenarios;
pub use crate::test_support::capture_starvation_witness;
pub use crate::test_support::periodic_starvation_gate;
pub use crate::test_support::post_vm_skip;
pub use crate::test_support::stall_ejection_skip;
pub use crate::test_support::starved_below_minimum_skip;
pub use crate::timeline::StimulusEvent;
pub use crate::scenario::sample::BpfMapCpuProjector;
pub use crate::scenario::sample::BpfMapProjector;
pub use crate::scenario::sample::Sample;
pub use crate::scenario::sample::SampleSeries;
pub use crate::scenario::sample::StatsPathProjector;
pub use crate::scenario::sample::StatsValue;
pub use crate::scenario::snapshot::BridgeGuard;
pub use crate::scenario::snapshot::CaptureCallback;
pub use crate::scenario::snapshot::CgroupProcsSnapshot;
pub use crate::scenario::snapshot::JsonField;
pub use crate::scenario::snapshot::MAX_WATCH_SNAPSHOTS;
pub use crate::scenario::snapshot::Snapshot;
pub use crate::scenario::snapshot::SnapshotBridge;
pub use crate::scenario::snapshot::SnapshotEntry;
pub use crate::scenario::snapshot::SnapshotError;
pub use crate::scenario::snapshot::SnapshotField;
pub use crate::scenario::snapshot::SnapshotMap;
pub use crate::scenario::snapshot::SnapshotResult;
pub use crate::scenario::snapshot::WatchRegisterCallback;
pub use crate::scenario::snapshot::pickers;
pub use crate::scenario::snapshot::stats_path;
pub use crate::scenario::CgroupGroup;
pub use crate::scenario::Ctx;
pub use crate::scenario::collect_all;
pub use crate::scenario::spawn_diverse;
pub use crate::test_support::BpfMapAgg;
pub use crate::test_support::BpfMapWrite;
pub use crate::test_support::CgroupPath;
pub use crate::test_support::EXIT_FAIL;
pub use crate::test_support::EXIT_INCONCLUSIVE;
pub use crate::test_support::EXIT_PASS;
pub use crate::test_support::KTSTR_SCHEDULERS;
pub use crate::test_support::KTSTR_TESTS;
pub use crate::test_support::KtstrTestEntry;
pub use crate::test_support::MemSideCache;
pub use crate::test_support::Metric;
pub use crate::test_support::MetricCheck;
pub use crate::test_support::MetricHint;
pub use crate::test_support::MetricStream;
pub use crate::test_support::NumaDistance;
pub use crate::test_support::NumaNode;
pub use crate::test_support::OutputFormat;
pub use crate::test_support::Payload;
pub use crate::test_support::PayloadKind;
pub use crate::test_support::PayloadMetrics;
pub use crate::test_support::PerfDeltaAssertion;
pub use crate::test_support::Polarity;
pub use crate::test_support::Scheduler;
pub use crate::test_support::SchedulerSpec;
pub use crate::test_support::SidecarResult;
pub use crate::test_support::Sysctl;
pub use crate::test_support::Topology;
pub use crate::test_support::TopologyConstraints;
pub use crate::test_support::WatchBpfMap;
pub use crate::test_support::extract_metrics;
pub use crate::test_support::find_scheduler;
pub use crate::test_support::find_test;
pub use crate::test_support::sidecar_dir;
pub use crate::topology::LlcInfo;
pub use crate::topology::NodeMemInfo;
pub use crate::topology::TestTopology;
pub use crate::scenario::host_stuck::StuckDiagnostic;
pub use crate::scenario::host_stuck::StuckReport;
pub use crate::workload::AffinityIntent;
pub use crate::workload::AluWidth;
pub use crate::workload::CloneMode;
pub use crate::workload::CustomCfg;
pub use crate::workload::CustomFn;
pub use crate::workload::FutexLockMode;
pub use crate::workload::MemPolicy;
pub use crate::workload::Migration;
pub use crate::workload::MpolFlags;
pub use crate::workload::ReapMode;
pub use crate::workload::ResolvedAffinity;
pub use crate::workload::SchbenchConfig;
pub use crate::workload::SchedClass;
pub use crate::workload::SchedPolicy;
pub use crate::workload::TaobenchConfig;
pub use crate::workload::TaobenchStats;
pub use crate::workload::WakeMechanism;
pub use crate::workload::WorkPhase;
pub use crate::workload::WorkSpec;
pub use crate::workload::WorkType;
pub use crate::workload::WorkTypeValidationError;
pub use crate::workload::WorkerCtx;
pub use crate::workload::WorkerReport;
pub use crate::workload::WorkerReportClaim;
pub use crate::workload::WorkloadConfig;
pub use crate::workload::WorkloadHandle;
pub use crate::assert::Phase;

Macros§

claim
Open a Verdict claim from a local binding or expression. The label is stringify!(<expr-tokens>) so a regression that renames the binding or alters the expression updates the rendered failure message in lock-step.
claim_present
Presence-checked sibling of claim! for a possibly-absent metric.
declare_scheduler
Function-style macro that registers a Scheduler const.

Structs§

ArenaPage
One mapped arena page captured from guest memory.
ArenaSnapshot
Snapshot of one arena map’s mapped pages.
BodyContentionWindow
Body-phase peak-window contamination series. New witnesses store deltas of the ktstr runner cgroup’s CPU PSI some total clock: time during which at least one runnable task in that cgroup was stalled for CPU. This includes a delayed vCPU even when its competitor is outside the cgroup, without charging pressure in unrelated host cgroups. Each entry has its real observation width in Self::tick_widths_ns, allowing the window calculation to remain sound when the monitor is starved and wakes much later than its nominal cadence.
ContentionWitness
The event-anchored host-contention witness: per-phase vCPU schedstat dilation plus the Body-phase CPU-pressure interval series. The monitor contributes constant-cost samples on its existing timer wakes; lifecycle dispatch anchors the stage boundaries. Carried on VmResult::contention_witness so a later seam pass can call latency_verdict to turn a latency threshold into a tri-state, contention-aware verdict.
DegradedFailureDumpReport
Top-level degraded failure-dump report. Emitted by the freeze coordinator when a real error-class trigger fires but the dump path aborts before a full FailureDumpReport can be captured — today only the vCPU rendezvous-timeout path produces this shape.
DiskConfig
Per-disk config. Default is raw 256 MiB device on /dev/vda; formatting and auto-mount are deferred.
DiskThrottle
IO throttle for one disk. Each field caps a separate dimension; None disables that dimension’s throttle. All None = unthrottled (the device runs at host-pread/pwrite speed).
DsqState
Snapshot of one DSQ’s state — built-in (per-CPU local, per-CPU bypass, per-node global) or user-allocated.
DualFailureDumpReport
Pair of failure-dump snapshots captured at two points in a stall.
EventCounterSample
One per-monitor-tick snapshot of the 13 SCX_EV_* event counters summed across every CPU at that tick.
FailureDumpArrayEntry
One entry of a multi-entry BPF_MAP_TYPE_ARRAY map: the array key (u32) and its rendered value. Mirrors FailureDumpPercpuEntry’s typed u32 key (ARRAY keys are kernel-imposed indices, not user-typed bytes) but carries a single value rather than a per-CPU vector.
FailureDumpEntry
One (key, value) pair from a hash map. Both sides are rendered via BTF when key/value type ids are available; a None rendering preserves the raw bytes.
FailureDumpFdArray
Per-FD-array snapshot of populated indices.
FailureDumpMap
Rendering of one BPF map’s contents.
FailureDumpPercpuEntry
One key from a per-CPU array, with one rendered value per CPU (None for CPUs whose per-CPU page was unmapped or out-of-range).
FailureDumpPercpuHashEntry
One key from a PERCPU_HASH / LRU_PERCPU_HASH map, with one rendered value per CPU. Mirrors FailureDumpEntry for the key side (rendered + hex) and FailureDumpPercpuEntry for the per-CPU value vector.
FailureDumpReport
Top-level failure-dump report. One per freeze trigger.
FailureDumpRingbuf
Ringbuf occupancy snapshot read from struct bpf_ringbuf at the freeze instant.
FailureDumpStackTrace
Per-bucket summary of populated stack traces in a STACK_TRACE map.
FailureDumpStackTraceEntry
One populated stack trace from a STACK_TRACE map.
HostVcpuSchedstat
Host-side vCPU scheduling-dilation sample, summed over the run’s vCPU host threads.
KernelOpReplyPayload
Postcard-encoded payload for MsgType::KernelOpReply.
NetConfig
Configuration for the virtio-net device attached to the VM.
PerCpuTimeStats
Per-CPU CPU-time / softirq / IRQ snapshot captured at freeze time. One entry per CPU index visible to the host walker.
PerNodeNumaStats
Per-node NUMA event counters captured from pglist_data->node_zones[]->vm_numa_event[] at freeze time.
PerPhaseSchedstat
Per-lifecycle-phase host-dilation witness: normally one HostVcpuSchedstat DELTA per stage, covering the schedstat accrued between lifecycle-event boundary snapshots. If the guest-reported scenario duration proves queued lifecycle frames did not bracket Body, Body instead carries the complete enclosing vCPU-thread lifetime. That conservative fallback can overstate Body contention but cannot hide it. Indexed by LifecycleStage as usize.
ProbeBssCounters
Cross-CPU sum of every per-CPU diagnostic counter slot in the probe BPF program’s .bss ktstr_pcpu_counters array.
ProgRuntimeStats
Per-program runtime stats summed across all CPUs.
RenderedMember
One member of a RenderedValue::Struct. name is the BTF name; for anonymous union members it is empty. value is the recursive rendering of the member’s bytes.
RqScxState
Snapshot of one CPU’s struct rq.scx state at freeze time.
ScxSchedState
Top-level scheduler state captured from *scx_root.
TaskEnrichment
Per-task enrichment captured at freeze time.
VirtioBlkCountersSnapshot
Plain-u64 snapshot of VirtioBlkCounters taken at VM-result construction time. Mirrors every atomic field by name.
VirtioNetCountersSnapshot
Plain-u64 snapshot of VirtioNetCounters taken at VM-result construction time. Mirrors every atomic field by name.
VmResult
Result of a VM execution.

Enums§

BuiltinMetric
One variant per super::METRICS entry — the discoverable built-in metric vocabulary. Self::wire_name is the stable registry / sidecar / CI string; Self::def resolves the full MetricDef. Pinned 1:1 to METRICS.
DiskThrottleValidationError
Validation failure for DiskThrottle::validate.
FailureDumpReportAny
Either-or wrapper that owns a parsed FailureDumpReport, DualFailureDumpReport, or DegradedFailureDumpReport. Lets a consumer hold and render a failure-dump file without prematurely committing to one schema — the discriminant lives in the JSON’s schema field, not in the type the consumer holds.
Filesystem
Filesystem to format the backing file with.
GuestLifecyclePhase
Final guest lifecycle stage as tracked by the progress ledger — the public mirror of monitor::LifecycleStage (same forward-only ordinal order, so Ord compares boot progress). Snapshotted at run teardown onto VmResult::final_guest_phase.
KernelOpValue
Wire-encoded crate::scenario::ops::KernelValue variant tag. Mirrors the four KernelValue enum variants 1:1.
MetricId
A metric identifier accepted by every metric accessor via impl Into<MetricId>: a typed BuiltinMetric (the common, discoverable, typo-proof case) or a dynamic scheduler-runtime / payload string (the open keyspace). One call shape for both — phase_metric(BuiltinMetric::X) and phase_metric("runtime_key").
RenderedValue
Structured rendering of one BTF-typed value.
ThrottleDimension
Throttle dimension a DiskThrottleValidationError applies to.
WatchdogKillReason
Which watchdog rule (if any) killed the VM — the public mirror of the watchdog-internal freeze_coord::KillReasonTag, rendered as cause= in the deadline-expired stderr dump. None on VmResult::watchdog_kill_reason means no watchdog kill was recorded (clean exit, crash, or a timeout path that never stamped a reason).

Constants§

REASON_DEGRADED_RENDEZVOUS_TIMEOUT
Reason string written into DegradedFailureDumpReport::reason when the freeze coordinator’s vCPU rendezvous timed out before every parked acknowledgement arrived. Wire-format-stable: matches the operator-grep contract used by every other REASON_* constant in this module. The dynamic detail appended at emit time (<timeout_ms> / <parked> / <expected>) lets an operator see which vCPUs stalled without a separate field.
SCHEMA_DEGRADED
Schema discriminant value emitted in DegradedFailureDumpReport.schema.
SCHEMA_DUAL
Schema discriminant value emitted in DualFailureDumpReport.schema. See SCHEMA_SINGLE for the discriminant contract.
SCHEMA_SINGLE
Schema discriminant value emitted in FailureDumpReport.schema.
SNAPSHOT_TAG_EARLY_DEGRADED
Snapshot tag used when the early-snapshot trigger fires but freeze_and_dispatch(FreezeMode::Capture { gate_on_exit_kind: false }) returns Degraded (early-half rendezvous timeout). The freeze coordinator writes the degraded JSON to a sibling path named via super::super::vmm::freeze_coord::snapshot_tagged_path using this tag — main {stem}.failure-dump.json is preserved for the subsequent late-trigger emission. Operator-readable wire-format constant: kebab-case, stable across releases.
SNAPSHOT_TAG_EARLY_ONLY_LATE_NEVER_FIRED
Snapshot tag used when dual-snapshot mode held a Captured early snapshot AND the late-trigger path NEVER FIRED for the run (no err_exit_detected BPF latch flip; the scheduler never reached an error-class late event). Distinct from SNAPSHOT_TAG_EARLY_ONLY_LATE_SUPPRESSED: this tag means the late trigger never ran at all, NOT that it ran and decided clean. Operator triage: scheduler crossed the half-watchdog runnable-age threshold (early-trigger fired) but then either recovered or terminated before reaching the late-trigger path — freeze_state stayed at Idle or TookEarly through coord exit. The end-of-coord drain emits the early observation to the tagged sibling rather than letting it drop with the closure.
SNAPSHOT_TAG_EARLY_ONLY_LATE_SUPPRESSED
Snapshot tag used when dual-snapshot mode held a Captured early snapshot AND the late-trigger path ran AND returned Suppressed (the gate examined *scx_root->exit_kind, found it below SCX_EXIT_ERROR, and decided no failure dump warranted). Distinct from SNAPSHOT_TAG_EARLY_ONLY_LATE_NEVER_FIRED: this tag means the late trigger DID fire and the gate explicitly decided clean exit. Operator triage: scheduler recovered from the early stall and reached a clean shutdown via the SCX_EXIT_NONE / SCX_EXIT_DONE path. The early observation (runnable-age spike) is independently meaningful and reaches disk at the tagged sibling. Symmetric with SNAPSHOT_TAG_EARLY_PRE_LATE_DEGRADED — tagged sibling rather than main path so the main {stem}.failure-dump.json keeps the “scheduler had a failure-class exit” semantic.
SNAPSHOT_TAG_EARLY_PRE_LATE_DEGRADED
Snapshot tag used when dual-snapshot mode held a Captured early snapshot AND the late-trigger path returned Degraded. The early snapshot is written to a sibling path with this tag while the late degraded JSON occupies the main dump path. Distinguishes “early itself degraded” (SNAPSHOT_TAG_EARLY_DEGRADED) from “early captured, late degraded” (this tag) so an operator browsing the dump directory knows which case produced which file. Every captured snapshot reaches disk.

Type Aliases§

Result
Result<T, Error>

Attribute Macros§

distributed_slice
linkme::distributed_slice re-exported as part of ktstr’s public surface. Combined with crate::linkme for the #[linkme(crate = ...)] annotation, this lets a downstream crate register entries into KTSTR_TESTS or KTSTR_SCHEDULERS without adding linkme as a direct Cargo dependency:
ktstr_test
Attribute macro that registers a function as a ktstr integration test.
ktstr_test_entry
Register a manually constructed KtstrTestEntry.

Derive Macros§

Payload
Derive macro that generates a Payload const from an annotated struct for a userspace binary workload (stress-ng, fio, and similar tools test authors compose under a scheduler).