Module prelude

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::post_vm_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_stall::StallDiagnostic;
pub use crate::scenario::host_stall::StallReport;
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.
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.
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.
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.
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.

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.

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).

Module prelude

Module prelude Copy item path

Re-exports§

Macros§

Structs§

Enums§

Constants§

Type Aliases§

Attribute Macros§

Derive Macros§

Module prelude