ktstr/
lib.rs

1// ctor 1.0's `#[ctor::ctor(...)]` macro expansion is a deep
2// TT-muncher whose recursion depth on this crate's ctor sites
3// exceeds Rust's default 128-frame macro-expansion budget. 256 is
4// what the rustc lint's own help message recommends; ctor itself
5// declares the same bump at the top of its lib.rs.
6#![recursion_limit = "256"]
7
8//! VM-based test framework for Linux kernel subsystems, with a focus on sched_ext.
9//!
10//! ktstr boots lightweight KVM virtual machines with controlled CPU topologies,
11//! runs scheduler test scenarios inside them, and evaluates results from the
12//! host via guest memory introspection. Each test creates cgroups, spawns
13//! worker processes, and checks that the scheduler handled the workload
14//! correctly. The same scenarios also run under the kernel's default
15//! EEVDF scheduler, so a test can baseline sched_ext behavior against
16//! stock scheduling.
17//!
18//! # Quick start
19//!
20//! Declare cgroups and workloads as data, let the framework handle
21//! lifecycle and checking:
22//!
23//! ```rust
24//! use ktstr::prelude::*;
25//!
26//! #[ktstr_test(llcs = 1, cores = 2, threads = 1)]
27//! fn my_scheduler_test(ctx: &Ctx) -> Result<AssertResult> {
28//!     execute_defs(ctx, vec![
29//!         CgroupDef::named("cg_0").workers(2),
30//!         CgroupDef::named("cg_1").workers(2),
31//!     ])
32//! }
33//! ```
34//!
35//! Requires a kernel image; see [`find_kernel()`] for the resolution chain.
36//!
37//! For multi-phase scenarios with dynamic topology changes:
38//!
39//! ```rust
40//! use ktstr::prelude::*;
41//!
42//! #[ktstr_test(llcs = 1, cores = 2, threads = 1)]
43//! fn my_dynamic_test(ctx: &Ctx) -> Result<AssertResult> {
44//!     let steps = vec![
45//!         Step::with_defs(
46//!             vec![CgroupDef::named("cg_0").workers(4)],
47//!             HoldSpec::frac(0.5),
48//!         ),
49//!         Step::new(
50//!             vec![Op::stop_cgroup("cg_0"), Op::remove_cgroup("cg_0")],
51//!             HoldSpec::frac(0.5),
52//!         ),
53//!     ];
54//!     execute_steps(ctx, steps)
55//! }
56//! ```
57//!
58//! # Scheduler definition
59//!
60//! Tests work with just topology parameters (as above). When multiple
61//! tests share a scheduler, use `declare_scheduler!` to declare it
62//! once with a binary, default topology, and any always-on args. Tests
63//! reference the generated const and inherit its configuration:
64//!
65//! ```rust,no_run
66//! use ktstr::prelude::*;
67//!
68//! declare_scheduler!(MY_SCHED, {
69//!     name = "my_sched",
70//!     binary = "scx_my_sched",
71//! });
72//!
73//! #[ktstr_test(scheduler = MY_SCHED)]
74//! fn basic(ctx: &Ctx) -> Result<AssertResult> {
75//!     execute_defs(ctx, vec![
76//!         CgroupDef::named("cg_0").workers(2),
77//!         CgroupDef::named("cg_1").workers(2),
78//!     ])
79//! }
80//! ```
81//!
82//! For full control over cgroup setup, worker spawning, and assertion
83//! you can use the low-level API directly:
84//!
85//! ```rust
86//! use ktstr::prelude::*;
87//!
88//! #[ktstr_test(llcs = 1, cores = 2, threads = 1)]
89//! fn my_low_level_test(ctx: &Ctx) -> Result<AssertResult> {
90//!     let mut group = CgroupGroup::new(ctx.cgroups);
91//!     group.add_cgroup_no_cpuset("workers")?;
92//!     let cpus = ctx.topo.all_cpuset();
93//!     ctx.cgroups.set_cpuset("workers", &cpus)?;
94//!
95//!     let cfg = WorkloadConfig {
96//!         num_workers: 2,
97//!         work_type: WorkType::SpinWait,
98//!         ..Default::default()
99//!     };
100//!     let mut handle = WorkloadHandle::spawn(&cfg)?;
101//!     ctx.cgroups.move_tasks("workers", &handle.worker_pids_for_cgroup_procs()?)?;
102//!     handle.start();
103//!
104//!     std::thread::sleep(ctx.duration);
105//!     let reports = handle.stop_and_collect();
106//!
107//!     let a = Assert::default_checks();
108//!     Ok(a.assert_cgroup(&reports, None))
109//! }
110//! ```
111//!
112//! For pointwise assertions against captured stats — the most direct
113//! way to express "this counter is at least N", "this rate is between
114//! A and B", "this metric is finite" — use `Verdict` +
115//! `#[derive(Claim)]` accessors and the [`claim!`] macro:
116//!
117//! ```rust
118//! use ktstr::prelude::*;
119//!
120//! // A test author would obtain `cg` and `report` from `ctx`-driven
121//! // execution; the literal here just illustrates the assertion shape.
122//! let cg = CgroupStats {
123//!     num_workers: 2,
124//!     num_cpus: 2,
125//!     max_gap_ms: 50,
126//!     p99_wake_latency_us: 25.0,
127//!     median_wake_latency_us: 10.0,
128//!     total_iterations: 5_000,
129//!     ..Default::default()
130//! };
131//! let work_units = 10_000u64;
132//! let throughput = work_units as f64 / 5.0;
133//!
134//! let mut v = Assert::default_checks().verdict();
135//! cg.claim_max_gap_ms(&mut v).at_most(100);          // typed CgroupStats accessor
136//! cg.claim_p99_wake_latency_us(&mut v).at_most(50.0);
137//! cg.claim_total_iterations(&mut v).at_least(1_000);
138//! claim!(v, work_units).at_least(5_000);             // local-binding label
139//! claim!(v, throughput).is_finite();                  // expression label
140//! claim!(v, cg.wake_latency_tail_ratio()).between(1.0, 5.0);
141//! let r = v.into_result();
142//! assert!(r.is_pass());
143//! ```
144//!
145//! Every claim is labeled by `stringify!` on either a struct field name
146//! (via the derive) or an identifier/expression (via the macro), so a
147//! rename or refactor updates the failure-message label automatically
148//! and a stale call site fails to compile. There is no manual-string
149//! escape hatch — by design, every label is source-text-grounded.
150//!
151//! Run with `cargo nextest run` (requires `/dev/kvm`).
152//!
153//! See the [`prelude`] module for the full set of re-exports.
154//!
155//! # Library usage
156//!
157//! Default install (full feature set — includes the installed
158//! `ktstr` / `cargo-ktstr` bins' deps):
159//!
160//! ```toml
161//! [dev-dependencies]
162//! ktstr = "0.26.0"
163//! ```
164//!
165//! Lean dev-dep (drops the host-tooling crates: tikv-jemallocator,
166//! clap_complete, tree-sitter, tree-sitter-c, base64):
167//!
168//! ```toml
169//! [dev-dependencies]
170//! ktstr = { version = "0.26.0", default-features = false }
171//! ```
172//!
173//! # Feature flags
174//!
175//! - **`cli-bins`** (default) — umbrella for deps used only by the
176//!   four `src/bin/*.rs` entry points and the matching test-binary
177//!   dispatch hooks. Pulls in `tikv-jemallocator`, `clap_complete`,
178//!   `tree-sitter`, `tree-sitter-c`, and the `export` feature.
179//! - **`export`** (pulled in by `cli-bins`) — gates
180//!   [`mod@export`] and the `cargo ktstr export` dispatch path in
181//!   the test binary. Drops `base64` from the manifest when off.
182//! - **`wprof`** — embed the wprof BPF tracer in shell-mode VMs.
183//!   First build clones `github.com/anakryiko/wprof` (requires git,
184//!   make, gcc, clang, elfutils-devel, zlib-devel).
185//! - **`pretty-labels`** — grex-based regex synthesis for
186//!   `ctprof_compare` display labels. With the feature off,
187//!   labels fall back to the deterministic join key.
188//! - **`remote-cache`** — GitHub Actions cache backend for blob
189//!   storage. CI-only; off-by-default. Pulls in `opendal` + minimal
190//!   `tokio` runtime.
191//! - **`integration`** — gates `resolve_func_ip` visibility for
192//!   integration tests.
193//!
194//! # Crate organization
195//!
196//! - [`cache`] -- kernel image cache (XDG directories, metadata, atomic writes)
197//! - [`cgroup`] -- cgroup v2 filesystem operations
198//! - [`cli`] -- shared helpers backing the `ktstr` and `cargo-ktstr` binaries
199//! - [`fetch`] -- kernel tarball and git source acquisition
200//! - [`flock`] -- advisory file-locking primitives used by cache + LLC reservations
201//! - [`kernel_path`] -- kernel ID parsing and filesystem image discovery
202//! - [`remote_cache`] -- GitHub Actions cache integration
203//! - [`scenario`] -- declarative ops API (`CgroupDef`, `Step`, `Op`, `Backdrop`, `execute_defs`, `execute_steps`, `execute_scenario`)
204//! - [`scenario::scenarios`] -- curated canned scenarios for common patterns
205//! - [`mod@assert`] -- pass/fail assertions (worker progress, isolation, fairness)
206//! - [`test_support`] -- `#[ktstr_test]` runtime and registration
207//! - [`topology`] -- CPU topology abstraction (LLCs, NUMA nodes)
208//! - [`verifier`] -- BPF verifier log parsing, cycle detection, and output formatting
209//! - [`worker_ready`] / [`worker_ready_wait`] -- pid-scoped ready-marker the alloc/test worker writes once it is work-ready, polled (`worker_ready_wait`) before the probe is launched against it
210//! - [`workload`] -- worker process types and telemetry collection
211//!
212//! ## ctprof subsystem
213//!
214//! Per-thread + per-process runtime profile, captured via
215//! `ktstr ctprof capture` and compared via
216//! `ktstr ctprof compare`:
217//!
218//! - [`host_context`] -- one-shot host snapshot (kernel, CPU, memory, tunables)
219//! - [`host_heap`] -- jemalloc global heap counters (mallctl)
220//! - [`ctprof`] -- per-thread procfs walk + cumulative scheduling, I/O, page-fault, jemalloc TSD counters
221//! - [`ctprof_compare`] -- two-snapshot diff engine (group-by + delta tables)
222//!
223//! `host_thread_probe` (the ELF/DWARF + ptrace + `process_vm_readv`
224//! engine that pulls per-thread jemalloc TSD counters) is
225//! `pub(crate)`-only and consumed exclusively by `ctprof` plus
226//! the source-shared standalone `ktstr-jemalloc-probe` binary.
227//! Direct probe access from downstream is intentionally not part
228//! of the surface — scheduler authors get the captured counters
229//! through `ctprof::ThreadState`.
230//!
231//! Internal modules (not re-exported): `host_thread_probe` reads
232//! per-thread jemalloc TSD counters via ptrace, `monitor` reads
233//! live guest state, `probe` attaches BPF probes to traced
234//! functions, and `vmm` owns the KVM VM lifecycle.
235//!
236//! [`timeline`] is a public module (its `StimulusEvent` appears in
237//! `assert::build_phase_buckets_with_stimulus`'s signature and is
238//! re-exported in the [`prelude`]); it correlates stimulus events
239//! with monitor samples for phase-aligned reporting.
240
241// `#[derive(Payload)]` expands into `::ktstr::test_support::...`
242// paths so downstream crates can use it without a `use` import.
243// This alias lets the same derive be used inside the ktstr crate
244// itself — for example by doctests and by integration-test modules
245// under `tests/common/` that pull the derive through the same
246// public path downstream authors take. No runtime cost:
247// `extern crate self as ktstr` is a pure name-binding.
248extern crate self as ktstr;
249
250// Keep the library allocator-agnostic for downstream crates and integration
251// test binaries. The latter are also packed as the guest `/init`; forcing
252// jemalloc into them makes an allocator that is irrelevant to the scenario
253// part of the guest's correctness surface. Each shipped binary that needs
254// jemalloc declares it at its own crate root instead.
255
256// Defense-in-depth for the e2e jemalloc-fixture invariant: `integration`
257// pulls `cli-bins` (Cargo.toml), so the jemalloc introspection fixtures
258// (`ktstr-jemalloc-probe` / `-alloc-worker`, gated on cli-bins +
259// integration) build when their e2es do — those e2es
260// `env!(CARGO_BIN_EXE_…)` the fixture bins. If the implication is ever
261// severed the fixtures don't build and their e2es fail to compile. Fail
262// the build loudly with the cause rather than ship the foot-gun.
263#[cfg(all(feature = "integration", not(feature = "cli-bins")))]
264compile_error!(
265    "feature `integration` requires `cli-bins`: the jemalloc \
266     introspection fixtures (ktstr-jemalloc-probe / -alloc-worker) are \
267     gated on cli-bins and their e2es env!(CARGO_BIN_EXE_…) them. Build \
268     with `--features integration` (which pulls cli-bins) or add cli-bins."
269);
270
271#[allow(
272    clippy::all,
273    dead_code,
274    non_camel_case_types,
275    non_snake_case,
276    non_upper_case_globals
277)]
278mod bpf_skel;
279
280#[cfg(test)]
281#[macro_use]
282mod test_macros;
283
284/// Shared guidance for every `#[non_exhaustive]` type in this
285/// crate. Individual types link here instead of repeating the
286/// same migration rules in every doc block.
287///
288/// # `#[non_exhaustive]` conventions in ktstr
289///
290/// Most of ktstr's public structs and enums carry `#[non_exhaustive]`
291/// so that adding a field or variant is not a breaking change for
292/// downstream crates. The attribute has two consequences downstream
293/// consumers must account for:
294///
295/// ## Pattern matching
296///
297/// Matches on a `#[non_exhaustive]` struct or enum from outside this
298/// crate must end with a wildcard `..` (for structs) or `_ =>` arm
299/// (for enums). Without it, a future addition to the type forces
300/// every matcher into a compile break even when the new field or
301/// variant is irrelevant to the caller.
302///
303/// ```ignore
304/// // Good: `..` absorbs future fields.
305/// if let MyStruct { name, .. } = value { /* ... */ }
306/// match my_enum {
307///     MyEnum::A => {}
308///     MyEnum::B => {}
309///     _ => {}          // absorbs future variants
310/// }
311/// ```
312///
313/// ## Construction
314///
315/// Cross-crate consumers **cannot** use any struct-expression form
316/// for a `#[non_exhaustive]` struct — bare literals
317/// (`MyStruct { name: "x", .. }`) and functional-update spreads
318/// (`MyStruct { name: "x", ..Default::default() }`) are both
319/// rejected by the compiler (E0639). Construction must go through
320/// one of:
321///
322/// 1. A dedicated constructor (`MyStruct::new(...)`,
323///    `MyStruct::from_*(...)`) exposed by the defining crate.
324/// 2. A [`Default`] instance followed by field mutation, when the
325///    type derives `Default`.
326/// 3. A named `test_fixture` or equivalent associated function for
327///    types that expose a populated baseline instead of the
328///    all-default minimum.
329///
330/// The per-type doc picks whichever of these the type actually
331/// supports; see [`host_context::HostContext`],
332/// [`host_heap::HostHeapState`], and the Op/CpusetSpec docs in
333/// [`scenario::ops`] for worked examples across the different
334/// shapes.
335///
336/// ## Pattern matching inside this crate
337///
338/// `#[non_exhaustive]` is enforced only across crate boundaries.
339/// In-crate matchers can remain exhaustive (and should, so the
340/// compiler flags forgotten variants at the definition site), and
341/// in-crate struct-literal construction still works for the tests
342/// and fixtures that live alongside the type.
343#[doc(hidden)]
344pub mod non_exhaustive {}
345
346pub mod cache;
347pub mod cgroup;
348pub mod flock;
349
350/// Map a raw errno value to its C constant name.
351///
352/// Returns `None` for unrecognized values. [`nix::errno::Errno`] has
353/// `#[derive(Debug)]`, but `format!("{:?}", e)` allocates a fresh
354/// `String` on every call; the hand-rolled match below returns a
355/// `&'static str` pointing at a literal instead. [`nix::errno::Errno`]
356/// is used here to gate unknown errnos via
357/// `matches!(e, UnknownErrno)`. Adding a new errno means extending
358/// both nix's port-constants table (for the UnknownErrno gate) and
359/// this match; the test suite pins a representative subset so a
360/// stale arm surfaces at build time.
361pub(crate) fn errno_name(errno: i32) -> Option<&'static str> {
362    let e = nix::errno::Errno::from_raw(errno);
363    if matches!(e, nix::errno::Errno::UnknownErrno) {
364        return None;
365    }
366    // Hand-rolled match: returns a `&'static str` pointing at a
367    // literal, avoiding the allocation that `format!("{:?}", e)` would
368    // incur. Callers that compare these against string literals in
369    // error formatting paths rely on the stable symbolic names below.
370    Some(match e {
371        nix::errno::Errno::EPERM => "EPERM",
372        nix::errno::Errno::ENOENT => "ENOENT",
373        nix::errno::Errno::ESRCH => "ESRCH",
374        nix::errno::Errno::EINTR => "EINTR",
375        nix::errno::Errno::EIO => "EIO",
376        nix::errno::Errno::ENXIO => "ENXIO",
377        nix::errno::Errno::E2BIG => "E2BIG",
378        nix::errno::Errno::ENOEXEC => "ENOEXEC",
379        nix::errno::Errno::EBADF => "EBADF",
380        nix::errno::Errno::ECHILD => "ECHILD",
381        nix::errno::Errno::EAGAIN => "EAGAIN",
382        nix::errno::Errno::ENOMEM => "ENOMEM",
383        nix::errno::Errno::EACCES => "EACCES",
384        nix::errno::Errno::EFAULT => "EFAULT",
385        nix::errno::Errno::EBUSY => "EBUSY",
386        nix::errno::Errno::EEXIST => "EEXIST",
387        nix::errno::Errno::ENODEV => "ENODEV",
388        nix::errno::Errno::ENOTDIR => "ENOTDIR",
389        nix::errno::Errno::EISDIR => "EISDIR",
390        nix::errno::Errno::EINVAL => "EINVAL",
391        nix::errno::Errno::ENFILE => "ENFILE",
392        nix::errno::Errno::EMFILE => "EMFILE",
393        nix::errno::Errno::ENOSPC => "ENOSPC",
394        nix::errno::Errno::ESPIPE => "ESPIPE",
395        nix::errno::Errno::EROFS => "EROFS",
396        nix::errno::Errno::EPIPE => "EPIPE",
397        nix::errno::Errno::EDOM => "EDOM",
398        nix::errno::Errno::ERANGE => "ERANGE",
399        nix::errno::Errno::EDEADLK => "EDEADLK",
400        nix::errno::Errno::ENAMETOOLONG => "ENAMETOOLONG",
401        nix::errno::Errno::ENOSYS => "ENOSYS",
402        nix::errno::Errno::ENOTEMPTY => "ENOTEMPTY",
403        nix::errno::Errno::ELOOP => "ELOOP",
404        nix::errno::Errno::ENOTSUP => "ENOTSUP",
405        nix::errno::Errno::EADDRINUSE => "EADDRINUSE",
406        nix::errno::Errno::ECONNREFUSED => "ECONNREFUSED",
407        nix::errno::Errno::ETIMEDOUT => "ETIMEDOUT",
408        // Other well-defined constants exist on nix::errno::Errno
409        // but were not in the previous curated list. Return None for
410        // them to preserve the prior contract — callers that want
411        // more coverage can extend this match explicitly.
412        _ => return None,
413    })
414}
415
416/// Read the kernel ring buffer (equivalent to `dmesg --notime`).
417/// Exposed as `pub` so scenario tests that need to assert on
418/// kernel-log content (e.g. the sched_ext stall duration emitted
419/// by `scx_exit(SCX_EXIT_ERROR_STALL)` in `kernel/sched/ext.c`)
420/// can read the same buffer the framework captures into
421/// `AssertResult::details` on scheduler-died failures.
422pub fn read_kmsg() -> String {
423    match rmesg::log_entries(rmesg::Backend::Default, false) {
424        Ok(entries) => entries
425            .iter()
426            .map(|e| e.message.as_str())
427            .collect::<Vec<_>>()
428            .join("\n"),
429        Err(_) => String::new(),
430    }
431}
432
433/// Forward the guest's `/dev/kmsg` ring buffer to the host over the
434/// bulk port, so a host-side post_vm callback can read it via
435/// `VmResult::guest_kmsg`. Mirrors `read_kmsg`: that reads the ring
436/// buffer in the guest process; this forwards the bytes (typically
437/// `read_kmsg().as_bytes()`) to the host. The scx_exit
438/// SCX_EXIT_ERROR_STALL printk lands in /dev/kmsg but is suppressed
439/// from the COM1 console at the default `loglevel=0`, so it never
440/// reaches `VmResult::stderr`; this forward is the only host-visible
441/// path to it.
442pub fn send_kmsg(buf: &[u8]) {
443    crate::vmm::guest_comms::send_dmesg(buf);
444}
445
446/// The host watchdog-override readback, surfaced via
447/// `VmResult::watchdog_observation`. Hidden from rustdoc at its
448/// definition, so this re-export adds no public doc surface.
449pub use crate::monitor::WatchdogObservation;
450
451pub mod assert;
452pub(crate) mod budget;
453pub(crate) mod cargo_test_mode;
454pub mod cli;
455pub mod cpu_util;
456pub mod ctprof;
457pub mod ctprof_compare;
458pub mod distro;
459pub(crate) mod elf_strip;
460#[cfg(feature = "export")]
461pub mod export;
462pub mod fetch;
463pub mod fun;
464#[doc(hidden)]
465pub mod git_status;
466pub mod host_context;
467pub mod host_heap;
468pub(crate) mod host_thread_probe;
469pub mod kernel_path;
470pub(crate) mod lookup_cache;
471// build_helpers.rs is `include!`d into build.rs at build-script
472// compile time. Mounting it as a `#[cfg(test)]` mod here lets its
473// unit tests run under `cargo nextest` / `cargo ktstr test`
474// without exposing the helper on the public API (the `mod` is
475// test-only; `cargo build` doesn't compile it as a lib module).
476#[cfg(test)]
477mod build_helpers;
478pub mod metric_types;
479pub(crate) mod monitor;
480pub(crate) mod probe;
481pub(crate) mod report;
482pub mod scenario;
483pub(crate) mod stats;
484pub(crate) mod taskstats;
485pub mod test_support;
486// `pub` (not `pub(crate)`): `assert::build_phase_buckets_with_stimulus`
487// takes `timeline::StimulusEvent` in its public signature, and result
488// analyzers (post_vm callbacks folding `VmResult::stimulus_timeline()`
489// through that fn) need to name the type.
490pub mod timeline;
491pub mod topology;
492
493/// Public surface for the live-host introspection pipeline.
494///
495/// Re-exports from the otherwise-internal `monitor` module so the
496/// live-host capture binary, integration tests, and downstream
497/// consumers can invoke the bpf()-syscall data path, kernel
498/// auto-discovery, kallsyms parser, and dmesg-scx parser without the
499/// `monitor` module's frozen-VM internals leaking into the public API.
500///
501/// This module is the entry point for binaries and tests that
502/// consume the live-host capture pipeline.
503pub mod live_host {
504    pub use crate::monitor::bpf_map::{
505        BPF_MAP_TYPE_ARENA, BPF_MAP_TYPE_ARRAY, BPF_MAP_TYPE_HASH, BPF_MAP_TYPE_PERCPU_ARRAY,
506        BpfMapAccessor, BpfMapInfo,
507    };
508    pub use crate::monitor::bpf_syscall::BpfSyscallAccessor;
509    pub use crate::monitor::dmesg_scx::{ScxExitKind, parse_kmsg_window};
510    pub use crate::monitor::live_host_kernel::{KallsymsTable, LiveHostKernelEnv};
511    pub use crate::monitor::timeline::{
512        TimelineCapture, TimelineEvent, TimelineEventRaw, parse_timeline_buf,
513        parse_timeline_record, tl_evt,
514    };
515}
516
517#[cfg(feature = "remote-cache")]
518pub mod remote_cache;
519
520/// No-op stub for the `remote_cache` module when the `remote-cache`
521/// feature is disabled. Exposes the same three entry points consumed
522/// elsewhere in the crate — `is_enabled()`, `remote_lookup()`,
523/// `remote_store()` — so call sites in `cli/resolve.rs` and
524/// `cli/kernel_build/build.rs` compile and behave correctly without
525/// any `#[cfg]` gating at the call site: `is_enabled()` always
526/// returns false, the lookup/store entry points are unreachable in
527/// practice, and the stubs satisfy the trait surface so type-checking
528/// stays uniform across feature configurations.
529#[cfg(not(feature = "remote-cache"))]
530pub mod remote_cache {
531    use crate::cache::{CacheDir, CacheEntry};
532
533    pub fn is_enabled() -> bool {
534        false
535    }
536
537    pub fn remote_lookup(
538        _cache: &CacheDir,
539        _cache_key: &str,
540        _cli_label: &str,
541    ) -> Option<CacheEntry> {
542        None
543    }
544
545    pub fn remote_store(_entry: &CacheEntry, _cli_label: &str) {}
546}
547pub mod gauntlet;
548pub(crate) mod reflink;
549pub mod scheduler_artifact;
550pub(crate) mod sync;
551#[cfg(any(feature = "export", feature = "remote-cache"))]
552pub(crate) mod tar_util;
553pub mod verifier;
554pub(crate) mod vmm;
555pub mod worker_ready;
556
557/// Internal cargo-ktstr target-runner bridge. Kept at the library root because
558/// cargo-ktstr is a separate crate target while the VMM implementation remains
559/// crate-private.
560#[doc(hidden)]
561pub use vmm::{AdmissionExecGuard, pre_admit_test_cell};
562
563#[cfg(feature = "wprof")]
564pub use vmm::wprof::{WPROF_MIN_MEMORY_MIB, apply_wprof_memory_floor};
565
566/// Re-export of the blob extract / install helpers so the `ktstr`
567/// and `cargo-ktstr` binaries (separate crates linking this lib) can
568/// extract their `include_bytes!`-embedded blobs and export the paths
569/// at startup. The bytes live in each binary; the mechanism lives in
570/// the lib (the `vmm::blobs` module). Re-exported here because `vmm`
571/// is `pub(crate)`, mirroring the `wprof` re-export above.
572pub use vmm::blobs::{extract_blob, install_blob_env_if_unset};
573
574/// Re-export of [`test_support::runtime::bypass_llc_locks_active`]
575/// so the bin/cargo_ktstr + bin/ktstr CLI surfaces (separate
576/// crates linking against this lib) can apply the canonical
577/// empty-string-aware bypass check at their parse-time
578/// `--cpu-cap` conflict guards. Mirrors the in-crate readers at
579/// vmm/builder.rs + cli/kernel_build/build.rs.
580pub use test_support::runtime::bypass_llc_locks_active;
581
582/// Pre-populate the on-disk cast analysis cache for a scheduler binary.
583///
584/// Called by cargo-ktstr before spawning nextest so test processes
585/// find a warm cache instead of each independently running the 30s
586/// analysis. Same-content callers across processes elect one builder,
587/// wait for its atomic publication, and then reuse the completed entry.
588pub fn precompute_cast_analysis(path: &std::path::Path) -> anyhow::Result<()> {
589    vmm::cast_analysis_load::precompute_cast_analysis(path)
590}
591pub mod worker_ready_wait;
592pub mod workload;
593
594/// Contents of `ktstr.kconfig` (the kernel-config fragment that
595/// enables sched_ext, BPF, kprobes, cgroups, and the other options
596/// ktstr requires) baked into the binary at build time via
597/// `include_str!`. Consumed by the kernel build pipeline to
598/// `olddefconfig` a kernel source tree, and used to derive the
599/// cache key suffix so a kconfig change produces a fresh cache
600/// entry.
601pub const EMBEDDED_KCONFIG: &str = include_str!("../ktstr.kconfig");
602
603/// CRC32 hash of the embedded kconfig fragment (8 hex chars).
604pub fn kconfig_hash() -> String {
605    format!("{:08x}", crc32fast::hash(EMBEDDED_KCONFIG.as_bytes()))
606}
607
608/// CRC32 hash (8 hex chars) of a user-supplied `--extra-kconfig`
609/// fragment, hashed verbatim.
610///
611/// Hashes raw bytes — no comment stripping, no CRLF
612/// canonicalization. Two semantically-equivalent inputs with
613/// different comments or line endings produce different hashes and
614/// therefore land at distinct cache entries — accept the disk waste
615/// in exchange for byte-deterministic cache discrimination.
616pub fn extra_kconfig_hash(extra: &str) -> String {
617    format!("{:08x}", crc32fast::hash(extra.as_bytes()))
618}
619
620/// Cache key suffix derived from the embedded kconfig fragment.
621/// Used in kernel cache keys so a kconfig change produces a distinct
622/// cache entry. The kernel binary is independent of ktstr userspace
623/// source, so no ktstr or consumer build identity feeds this suffix.
624pub fn cache_key_suffix() -> String {
625    kconfig_hash()
626}
627
628/// Two-segment cache key suffix accounting for an optional
629/// `--extra-kconfig` fragment.
630///
631/// The suffix uses TWO segments instead of folding both inputs into
632/// one hash:
633///
634/// - `extra = None` → `kconfig_hash()` only — byte-identical to
635///   [`cache_key_suffix`], so paths that don't expose
636///   `--extra-kconfig` (test / coverage / shell / verifier) keep
637///   resolving the existing keyspace and pre-1.0 cached kernels are
638///   not orphaned.
639/// - `extra = Some(content)` → `{kconfig_hash()}-xkc{extra_hash}`,
640///   making `kernel list` self-describing: a reader can see at a
641///   glance which entries carry user extras and which are pure
642///   baked-in builds. Different extra content yields different
643///   `xkc{...}` segments, so cache discrimination across distinct
644///   `--extra-kconfig` invocations is structural rather than
645///   collapsed into a single opaque hash.
646pub fn cache_key_suffix_with_extra(extra: Option<&str>) -> String {
647    match extra {
648        None => kconfig_hash(),
649        Some(content) => format!("{}-xkc{}", kconfig_hash(), extra_kconfig_hash(content)),
650    }
651}
652
653/// Merge the user-supplied `--extra-kconfig` fragment on top of
654/// [`EMBEDDED_KCONFIG`] for the configure pass. Returns a
655/// [`std::borrow::Cow`] so the no-extras branch borrows `baked`
656/// without allocating; only the `Some` branch heaps the merged
657/// String.
658///
659/// The user fragment is appended AFTER the baked-in fragment so
660/// kbuild's last-wins rule
661/// (`scripts/kconfig/confdata.c::conf_read_simple` —
662/// "If conflicting CONFIG options are given from an input file,
663/// the last one wins.") makes user values override baked-in ones
664/// on conflict.
665///
666/// A single `\n` separator is interleaved between the two
667/// fragments. EMBEDDED_KCONFIG ends in a newline today, so the
668/// interleaved `\n` produces a blank line between the segments —
669/// kbuild's `.config` parser ignores blank lines (every
670/// `if (!line[0])` short-circuit in `conf_read_simple`), so the
671/// blank line is harmless. The separator is mandatory for the
672/// adversarial case where the operator hand-crafts an
673/// EMBEDDED_KCONFIG without a trailing newline AND a user
674/// fragment that starts with `CONFIG_X` — without the
675/// interleaved `\n`, the two would concatenate into a single
676/// malformed line. Always emit the separator so the merge is
677/// safe regardless of either side's terminator.
678///
679/// The production configure path in
680/// [`crate::cli::kernel_build_pipeline`] calls this helper to build
681/// the bytes handed to `configure_kernel`. Tests that assert
682/// merge-ordering invariants call it directly so the production
683/// byte sequence is what kbuild's last-wins rule operates on.
684/// (Note: [`cache_key_suffix_with_extra`] hashes `extra` ALONE for
685/// its `xkc{...}` segment — it doesn't pass through this helper —
686/// so the cache-key suffix and the merged-fragment content evolve
687/// independently. The cache-key segment exists to discriminate
688/// extras-vs-no-extras at the cache layer; the merge ordering
689/// exists to give kbuild the right final value.)
690pub fn merge_kconfig_fragments<'a>(
691    baked: &'a str,
692    extra: Option<&str>,
693) -> std::borrow::Cow<'a, str> {
694    match extra {
695        None => std::borrow::Cow::Borrowed(baked),
696        Some(content) => std::borrow::Cow::Owned(format!("{baked}\n{content}")),
697    }
698}
699
700// Derive macros. `Payload` here is the `#[derive(Payload)]` proc
701// macro; the same-named `Payload` struct (to which the derive
702// applies) lives at `crate::test_support::Payload`. Rust's
703// macro-vs-type namespace separation lets both coexist under the
704// identifier `Payload` in `use ktstr::prelude::*;` — the derive
705// position resolves to the macro, type position resolves to the
706// struct.
707pub use ktstr_macros::Claim;
708pub use ktstr_macros::Payload;
709pub use ktstr_macros::declare_scheduler;
710pub use ktstr_macros::json;
711pub use ktstr_macros::ktstr_test;
712pub use ktstr_macros::ktstr_test_entry;
713
714/// Internal re-exports for proc-macro-generated code. Not public API.
715///
716/// Grouped into a single hidden module so that `use ktstr::*;` pulls
717/// in one module name instead of two leading-underscore items.
718/// Consumers of `#[ktstr_test]` should not reference anything under
719/// this path — the `#[ktstr_test]` macro registers via
720/// `::ktstr::distributed_slice` / `::ktstr::linkme`; the `ctor` /
721/// `serde_json` re-exports here serve downstream test-author code
722/// (pre-`main()` setup and sidecar parsing) and ktstr's own
723/// declarative-ctor sites, and the set may change without notice.
724/// (`linkme` lives at the public crate root —
725/// [`ktstr::linkme`](crate::linkme) — since the macro now emits the
726/// public path.)
727#[doc(hidden)]
728pub mod __private {
729    pub use ctor;
730    pub use serde_json;
731}
732
733#[cfg(feature = "integration")]
734pub use crate::probe::process::resolve_func_ip;
735
736/// The `linkme` crate, re-exported as part of ktstr's public surface
737/// so downstream code can reference it via [`ktstr::linkme`](crate::linkme)
738/// in the `#[linkme(crate = ...)]` annotation that
739/// [`distributed_slice`] registrations
740/// require — without having to add `linkme` as a direct Cargo
741/// dependency. See [`distributed_slice`]
742/// for the usage pattern.
743pub use ::linkme;
744
745/// `linkme::distributed_slice` re-exported as part of ktstr's public
746/// surface. Combined with [`crate::linkme`] for the
747/// `#[linkme(crate = ...)]` annotation, this lets a downstream crate
748/// register entries into
749/// [`KTSTR_TESTS`](crate::test_support::KTSTR_TESTS) or
750/// [`KTSTR_SCHEDULERS`](crate::test_support::KTSTR_SCHEDULERS)
751/// without adding `linkme` as a direct Cargo dependency:
752///
753/// ```ignore
754/// use ktstr::prelude::*;
755///
756/// fn my_test_fn(_ctx: &Ctx) -> Result<AssertResult> {
757///     Ok(AssertResult::pass())
758/// }
759///
760/// #[distributed_slice(KTSTR_TESTS)]
761/// #[linkme(crate = ktstr::linkme)]
762/// static MY_ENTRY: KtstrTestEntry = KtstrTestEntry {
763///     name: "my_test",
764///     func: my_test_fn,
765///     ..KtstrTestEntry::DEFAULT
766/// };
767/// ```
768///
769/// The `#[linkme(crate = ...)]` annotation is REQUIRED because the
770/// `linkme` proc-macro expansion hardcodes `::linkme::DistributedSlice`
771/// — without the annotation, downstream crates without `linkme` in
772/// their `Cargo.toml` get an unresolved-import error.
773/// The annotation tells the macro to resolve type references through
774/// `ktstr::linkme` instead, which IS reachable from downstream by
775/// transitive dependency.
776///
777/// Downstream crates that already depend on `linkme = "0.3"` directly
778/// can omit the annotation. The `#[ktstr_test]` proc macro emits both
779/// attributes internally so test authors using the standard macro
780/// surface never have to spell either out.
781pub use linkme::distributed_slice;
782
783/// Re-exports for writing `#[ktstr_test]` functions.
784///
785/// ```rust
786/// use ktstr::prelude::*;
787///
788/// #[ktstr_test(llcs = 1, cores = 2, threads = 1)]
789/// fn my_test(ctx: &Ctx) -> Result<AssertResult> {
790///     Ok(AssertResult::pass())
791/// }
792/// ```
793///
794/// For curated canned scenarios, see [`scenario::scenarios`].
795pub mod prelude {
796    pub use anyhow::Result;
797
798    // `Scheduler` is the `test_support::Scheduler` struct — the
799    // scheduler-definition record test authors build via the
800    // `declare_scheduler!` macro.
801    // The `#[derive(Claim)]`-generated `<Type>Claim` extension traits carry the
802    // typed `claim_<field>(&mut verdict)` accessors. Every derive(Claim) stats
803    // type is preluded, so its Claim trait is preluded alongside it and
804    // `use ktstr::prelude::*` makes the accessors callable without a per-type
805    // trait import: the four assert-module traits below, plus `WorkerReportClaim`
806    // in the workload export block.
807    pub use crate::assert::{
808        AbsoluteThresholds, Assert, AssertDetail, AssertResult, COMPARATOR_VOCABULARY, CgroupStats,
809        CgroupStatsClaim, ClaimBuilder, DetailKind, EachClaim, FracPair, InfoNote,
810        MAX_RECORDED_PASSES, NoteValue, Outcome, OutcomeRef, PASSES_TRUNCATION_SENTINEL_COMPARATOR,
811        PASSES_TRUNCATION_SENTINEL_NAME, PassDetail, PhaseBucket, PhaseBucketClaim,
812        PhaseCgroupStats, PhaseCgroupStatsClaim, PhaseMapExt, ScenarioStats, ScenarioStatsClaim,
813        SeqClaim, SeriesField, SetClaim, Verdict, assert_scx_events_clean, assert_thresholds,
814        build_phase_buckets_with_stimulus,
815    };
816    // Per-phase-metric building blocks for `post_vm` callbacks doing
817    // custom per-phase assertions: `StimulusEvent` is the timeline event
818    // type `build_phase_buckets_with_stimulus` consumes, and
819    // `VmResult::stimulus_timeline()` returns a `Vec<StimulusEvent>`
820    // (step frames + scenario-end terminal) ready to fold through it.
821    // The non-stimulus sibling `assert::build_phase_buckets` is
822    // INTENTIONALLY not preluded: it groups by the raw bridge-stamped
823    // step_index, which can collapse under a deferred-fire burst (see
824    // `SampleSeries::by_stamped_phase`); the stimulus-aware variant above
825    // is the collapse-immune common path, so the prelude surfaces only
826    // it. The plain variant remains reachable by full path for the rare
827    // no-stimulus-timeline case.
828    pub use crate::cgroup::CgroupManager;
829    pub use crate::claim;
830    pub use crate::claim_present;
831    pub use crate::declare_scheduler;
832    pub use crate::distributed_slice;
833    pub use crate::host_context::HostContext;
834    pub use crate::host_heap::HostHeapState;
835    pub use crate::ktstr_test;
836    pub use crate::ktstr_test_entry;
837    pub use crate::scenario::backdrop::Backdrop;
838    pub use crate::scenario::ops::{
839        CgroupDef, CpusetSpec, HoldSpec, IrqSelector, KernelTarget, KernelValue, KernelValueWidth,
840        Op, Setup, SpawnPlacement, Step, execute_defs, execute_scenario, execute_scenario_with,
841        execute_steps, execute_steps_with,
842    };
843    pub use crate::scenario::payload_run::{PayloadHandle, PayloadRun};
844    pub use crate::scenario::scenarios;
845    pub use crate::test_support::{
846        capture_starvation_witness, periodic_starvation_gate, post_vm_skip, stall_ejection_skip,
847        starved_below_minimum_skip,
848    };
849    pub use crate::timeline::StimulusEvent;
850    // Snapshot accessor surface and the underlying report shapes
851    // a test author needs to inspect the captured BTF-rendered
852    // bytes. The renderer types come from monitor::btf_render and
853    // monitor::dump (otherwise crate-private modules); re-exported
854    // here so an out-of-crate caller can build synthetic
855    // FailureDumpReports for unit-testing their assertions
856    // against the snapshot accessor without booting a VM.
857    //
858    // Re-export of the `Payload` derive macro from the crate root.
859    // The same identifier names the `Payload` struct re-exported a
860    // few lines below from `crate::test_support`; the two live in
861    // separate Rust namespaces (macro vs type) so they coexist in
862    // `use ktstr::prelude::*;` without conflict.
863    pub use crate::Payload;
864    pub use crate::monitor::arena::{ArenaPage, ArenaSnapshot};
865    pub use crate::monitor::bpf_prog::ProgRuntimeStats;
866    pub use crate::monitor::btf_render::{RenderedMember, RenderedValue};
867    pub use crate::monitor::dump::{
868        DegradedFailureDumpReport, DualFailureDumpReport, EventCounterSample,
869        FailureDumpArrayEntry, FailureDumpEntry, FailureDumpFdArray, FailureDumpMap,
870        FailureDumpPercpuEntry, FailureDumpPercpuHashEntry, FailureDumpReport,
871        FailureDumpReportAny, FailureDumpRingbuf, FailureDumpStackTrace,
872        FailureDumpStackTraceEntry, PerCpuTimeStats, PerNodeNumaStats, ProbeBssCounters,
873        REASON_DEGRADED_RENDEZVOUS_TIMEOUT, SCHEMA_DEGRADED, SCHEMA_DUAL, SCHEMA_SINGLE,
874        SNAPSHOT_TAG_EARLY_DEGRADED, SNAPSHOT_TAG_EARLY_ONLY_LATE_NEVER_FIRED,
875        SNAPSHOT_TAG_EARLY_ONLY_LATE_SUPPRESSED, SNAPSHOT_TAG_EARLY_PRE_LATE_DEGRADED,
876    };
877    pub use crate::monitor::scx_walker::{DsqState, RqScxState, ScxSchedState};
878    pub use crate::monitor::task_enrichment::TaskEnrichment;
879    pub use crate::scenario::sample::{
880        BpfMapCpuProjector, BpfMapProjector, Sample, SampleSeries, StatsPathProjector, StatsValue,
881    };
882    pub use crate::scenario::snapshot::{
883        BridgeGuard, CaptureCallback, CgroupProcsSnapshot, JsonField, MAX_WATCH_SNAPSHOTS,
884        Snapshot, SnapshotBridge, SnapshotEntry, SnapshotError, SnapshotField, SnapshotMap,
885        SnapshotResult, WatchRegisterCallback, pickers, stats_path,
886    };
887    pub use crate::scenario::{CgroupGroup, Ctx, collect_all, spawn_diverse};
888    // `Payload` in this group is the struct on which
889    // `#[derive(Payload)]` is applied; it occupies the type
890    // namespace, distinct from the derive macro re-exported above.
891    pub use crate::test_support::{
892        BpfMapAgg, BpfMapWrite, CgroupPath, EXIT_FAIL, EXIT_INCONCLUSIVE, EXIT_PASS,
893        KTSTR_SCHEDULERS, KTSTR_TESTS, KtstrTestEntry, MemSideCache, Metric, MetricCheck,
894        MetricHint, MetricStream, NumaDistance, NumaNode, OutputFormat, Payload, PayloadKind,
895        PayloadMetrics, PerfDeltaAssertion, Polarity, Scheduler, SchedulerSpec, SidecarResult,
896        Sysctl, Topology, TopologyConstraints, WatchBpfMap, extract_metrics, find_scheduler,
897        find_test, sidecar_dir,
898    };
899    // The following items are intentionally NOT in the prelude. They
900    // are binary-entry helpers (the `ktstr` / `cargo-ktstr` bins) or
901    // macro-generated glue the `#[ktstr_test]` expansion consumes —
902    // audiences distinct from the test-author surface this module
903    // provides. Import directly from `ktstr::test_support::<item>`
904    // when needed:
905    // `newest_run_dir`, `runs_root`, `analyze_sidecars`, `ktstr_main`,
906    // `ktstr_test_early_dispatch`, `run_ktstr_test`,
907    // `resolve_scheduler`, `resolve_test_kernel`.
908    //
909    // `build_nodemask` (the low-level `set_mempolicy(2)` / `mbind(2)`
910    // bitmask builder) is also excluded: test authors express NUMA
911    // placement through the `MemPolicy` enum, not raw nodemask
912    // construction. The helper itself lives in the crate-private
913    // `workload::spawn` submodule with a `pub(crate)` re-export at
914    // `crate::workload::build_nodemask` for `vmm::host_topology`
915    // internal use.
916    pub use crate::topology::{LlcInfo, NodeMemInfo, TestTopology};
917    pub use crate::vmm::{VirtioBlkCountersSnapshot, VirtioNetCountersSnapshot};
918    // `VmResult` is the host-side return value from booting a VM.
919    // Surfaced for `#[ktstr_test(post_vm = ...)]` callbacks: the
920    // hook signature is `fn(&VmResult) -> anyhow::Result<()>`, and
921    // a test author writing the callback needs the type in scope
922    // to declare the parameter. The contention-witness types ride
923    // along: they are the public `VmResult::contention_witness`
924    // payload a callback destructures.
925    pub use crate::vmm::VmResult;
926    pub use crate::vmm::disk_config::{
927        DiskConfig, DiskThrottle, DiskThrottleValidationError, Filesystem, ThrottleDimension,
928    };
929    pub use crate::vmm::net_config::NetConfig;
930    pub use crate::vmm::{
931        BodyContentionWindow, ContentionWitness, GuestLifecyclePhase, HostVcpuSchedstat,
932        PerPhaseSchedstat, WatchdogKillReason,
933    };
934    // Surfaced for `post_vm` callbacks that drain the snapshot
935    // bridge's per-tag kernel-op reply log via
936    // `VmResult::snapshot_bridge::drain_kernel_ops`: the returned
937    // `Vec<(String, KernelOpReplyPayload)>` carries `read_values`
938    // of `KernelOpValue` variants the callback pattern-matches to
939    // assert on a read-back u32 / u64 / Bytes payload from
940    // `Op::ReadKernel{Hot,Cold}`. Mirrors the existing exports for
941    // `VirtioBlkCountersSnapshot` etc. — observability types the
942    // post_vm contract requires in scope.
943    pub use crate::scenario::host_stuck::{StuckDiagnostic, StuckReport};
944    pub use crate::vmm::wire::{KernelOpReplyPayload, KernelOpValue};
945    pub use crate::workload::{
946        AffinityIntent, AluWidth, CloneMode, CustomCfg, CustomFn, FutexLockMode, MemPolicy,
947        Migration, MpolFlags, ReapMode, ResolvedAffinity, SchbenchConfig, SchedClass, SchedPolicy,
948        TaobenchConfig, TaobenchStats, WakeMechanism, WorkPhase, WorkSpec, WorkType,
949        WorkTypeValidationError, WorkerCtx, WorkerReport, WorkerReportClaim, WorkloadConfig,
950        WorkloadHandle,
951    };
952    // Surface `Phase` from the assert module (the scenario-step
953    // bucket) so test authors can write `Phase::step(0)` /
954    // `Phase::baseline()` without disambiguating against the
955    // formerly-named workload variant. The workload's compound-
956    // pattern enum is now `WorkPhase` (above) so `Phase` alone
957    // unambiguously means the scenario-phase bucket type users
958    // reach for in `field.value_at_phase(Phase::step(0))` style.
959    pub use crate::assert::Phase;
960    // Typed built-in metric ids (the discoverable, typo-proof catalog) + the
961    // `MetricId` hybrid that ALSO accepts a scheduler-runtime string — both flow
962    // through every metric accessor via `impl Into<MetricId>`. A misspelled
963    // built-in is a compile error, not a silent `None`.
964    pub use crate::stats::{BuiltinMetric, MetricId};
965}
966
967/// # KTSTR_* env-var empty-string contract
968///
969/// Default policy across `KTSTR_*` env vars: **empty string is
970/// treated as unset** (falls back to the same default the var
971/// would use if absent). This prevents the "stale shell export"
972/// footgun where an operator's previous `KTSTR_FOO=...` export
973/// gets cleared by the new shell (`KTSTR_FOO=`) but the empty
974/// value is still observed by child processes — without the
975/// empty-as-unset rule, child code would see "set" via
976/// `env::var(...).is_ok()` and try to use the empty value as
977/// data, producing confusing failures far from the export site.
978///
979/// Per-const docs flag deviations from this default explicitly:
980/// presence-only markers (e.g. [`KTSTR_ORCHESTRATED_ENV`]) treat
981/// empty as set per documented contract; value-typed vars (e.g.
982/// path overrides like [`KTSTR_HOST_CGROUP_PARENT_ENV`]) follow
983/// the empty-as-unset default and surface the fallback at the
984/// resolver site.
985///
986/// New `KTSTR_*` env vars must pick a policy at the const-decl
987/// doc and the reader site must honor it; mixed empty-treatment
988/// within one var is a footgun.
989///
990/// Name of the environment variable that selects a kernel for every
991/// ktstr entry point (`ktstr run`, `ktstr shell`, `cargo ktstr test`,
992/// in-process tests, post-run analysis). Single source of truth so
993/// the name is not spelled by hand at each reader; if the name ever
994/// changes, the change lands in one place instead of fanning out to
995/// every call site.
996pub const KTSTR_KERNEL_ENV: &str = "KTSTR_KERNEL";
997
998/// Name of the environment variable that carries the multi-kernel
999/// fan-out list across the `cargo ktstr` → `cargo nextest` → test-
1000/// binary boundary. Format: `label1=path1;label2=path2;…` (semicolon
1001/// entry separator, `=` separates label from absolute kernel-dir
1002/// path). Empty / unset means "single-kernel mode" — the test binary
1003/// honours `KTSTR_KERNEL_ENV` directly.
1004///
1005/// Set by `cargo ktstr test --kernel A --kernel B` (or any
1006/// `--kernel` value that expands to ≥ 2 entries — repeated
1007/// `--kernel` flags, or a single `--kernel START..END` range that
1008/// expands to multiple stable releases via
1009/// [`crate::kernel_path::KernelId::Range`]) before the `exec` into
1010/// `cargo nextest`. Read by the test binary's `--list` /
1011/// `--exact` handlers in `crate::test_support::dispatch` to fan
1012/// the gauntlet across kernels: each (test × scenario × topology ×
1013/// kernel) tuple becomes a distinct nextest test case so
1014/// nextest's parallelism, retries, and `-E` filtering work
1015/// natively. Per-variant subprocesses re-export `KTSTR_KERNEL` to
1016/// the kernel directory selected by the test name's `kernel_…`
1017/// suffix.
1018///
1019/// `KTSTR_KERNEL_ENV` is always set in tandem (to the first entry's
1020/// path) so downstream code that reads `KTSTR_KERNEL` directly —
1021/// budget-listing's vmlinux probe in `dispatch.rs` for example —
1022/// still observes a valid kernel even when running under multi-
1023/// kernel mode.
1024///
1025/// Single source of truth so the name is not spelled by hand at
1026/// each reader; if the name ever changes, the change lands in one
1027/// place instead of fanning out to every call site.
1028pub const KTSTR_KERNEL_LIST_ENV: &str = "KTSTR_KERNEL_LIST";
1029
1030/// Name of the environment variable cargo-ktstr sets to a
1031/// `dir=commit;dir=commit;...` map of each resolved SOURCE kernel's
1032/// short commit hash (with a `-dirty` suffix when the tree is dirty),
1033/// keyed by the same directory string exported in [`KTSTR_KERNEL_ENV`]
1034/// / [`KTSTR_KERNEL_LIST_ENV`].
1035///
1036/// cargo-ktstr probes each kernel's git HEAD ONCE in the orchestrator
1037/// and records it here. The sidecar writer reads this map and looks
1038/// itself up (by its own `KTSTR_KERNEL` dir) instead of re-running a
1039/// gix HEAD read + dirty-walk over the kernel tree in every per-test
1040/// nextest process. That walk is memoized per process but NOT across
1041/// processes, so without this map each of N test processes re-pays the
1042/// full dirty-walk (seconds on a large kernel checkout).
1043///
1044/// Optimization only: a missing entry, absent env, or decode failure
1045/// falls back to the in-process resolve-and-walk, which is always
1046/// correct. Kernels with no recoverable source tree (transient
1047/// Range/Git specs, or a Version/CacheKey cache miss) are absent from
1048/// the map, and the fallback yields the same `None` for them.
1049pub const KTSTR_KERNEL_COMMIT_ENV: &str = "KTSTR_KERNEL_COMMIT";
1050
1051/// Name of the environment variable cargo-ktstr's perf-delta sets to the
1052/// PROJECT tree's short commit hash (with a `-dirty` suffix when the tree
1053/// is dirty) that the child's sidecars must record as their
1054/// `project_commit`. Unlike [`KTSTR_KERNEL_COMMIT_ENV`] this is a single
1055/// value, not a `dir=commit` map — a child has exactly one project tree.
1056///
1057/// perf-delta computes the A/B commit labels ONCE in the orchestrator
1058/// (`short_hash`) and both the pool FILTER and the two run children read
1059/// the same value: the filter partitions on it, and each child records it
1060/// verbatim (the sidecar writer's `detect_project_commit` returns this
1061/// value when the env is set), so the recorded `project_commit` and the
1062/// filter can never diverge on the `-dirty` suffix. It also lets the
1063/// baseline run, whose tree is a plain gix checkout with no `.git`, skip a
1064/// `gix::discover` that would otherwise resolve to the wrong repo (or none).
1065///
1066/// Override only: an absent or empty env falls back to the in-process
1067/// `gix::discover` + dirty-walk, which is correct for a normal (non
1068/// perf-delta) test run.
1069pub const KTSTR_PROJECT_COMMIT_ENV: &str = "KTSTR_PROJECT_COMMIT";
1070
1071/// Name of the environment variable cargo-ktstr sets to signal
1072/// "this test process was launched by a cargo-ktstr orchestration
1073/// path, not raw `cargo nextest`". cargo-ktstr's `test` and
1074/// `verifier` subcommands set it to `"1"` before spawning the
1075/// nextest child; the value content does not matter, only the
1076/// presence — `std::env::var(KTSTR_ORCHESTRATED_ENV).is_ok()`.
1077///
1078/// Tests that boot real KVM VMs (`src/vmm/*` integration tests)
1079/// use this signal to skip when an operator runs the test binary
1080/// directly via `cargo nextest run --lib`. Raw nextest fans
1081/// 7000+ tests at full host parallelism, which starves the
1082/// per-VM resource budgets these tests depend on (KVM page
1083/// allocation, vCPU thread scheduling, freeze rendezvous timing).
1084/// Failure shape is `kill set by AP` + watchdog-deadline timeout
1085/// shortly after VM start. cargo-ktstr's orchestrator constrains
1086/// the VM-test concurrency so the budgets hold; raw nextest
1087/// doesn't, so the skip surfaces operator-error (wrong runner)
1088/// rather than dismissing a real bug.
1089///
1090/// `KTSTR_KERNEL_ENV` alone is not sufficient: an operator may
1091/// have it set in their shell from a prior cargo-ktstr session
1092/// and then invoke raw nextest. The dedicated orchestration
1093/// marker discriminates the two cases.
1094pub const KTSTR_ORCHESTRATED_ENV: &str = "KTSTR_ORCHESTRATED";
1095
1096/// Name of the environment variable carrying the `cargo ktstr test`
1097/// SESSION EPOCH: nanoseconds since the Unix epoch, stamped ONCE by
1098/// the orchestrator (`cargo_ktstr::run_cargo`) before it spawns
1099/// nextest, inherited by every per-test child process.
1100///
1101/// `test_support::sidecar::pre_clear_run_dir_once` uses it as an
1102/// opaque per-invocation session token: nextest is process-per-test
1103/// and every test sharing one `{kernel}-{project_commit}` run
1104/// directory would otherwise have a later process's pre-clear delete
1105/// an earlier peer's freshly-written `{test}-{hash}.ktstr.json`
1106/// (silent stats loss). The first process to clear a dir records
1107/// this token in a `.ktstr_run_epoch` sentinel; a later peer whose
1108/// token matches skips its wipe, sparing the peers' sidecars. Unset
1109/// under raw `cargo nextest run` (no orchestrator) — pre-clear then
1110/// falls back to its per-process wipe-everything behavior.
1111pub const KTSTR_RUN_EPOCH_ENV: &str = "KTSTR_RUN_EPOCH";
1112
1113/// Name of the environment variable that pins the sidecar runs-root
1114/// to an ABSOLUTE path, overriding the CWD-relative
1115/// `{CARGO_TARGET_DIR or "target"}/ktstr` default of
1116/// [`test_support::runs_root`].
1117///
1118/// The `cargo ktstr` orchestrator (`cargo-ktstr` main) stamps this
1119/// once at startup to the cargo target dir's `ktstr` subdir (resolved
1120/// via `cargo metadata`), so its post-run footer / `stats` / `replay`
1121/// reads AND the child test processes' sidecar writes resolve the
1122/// SAME directory regardless of CWD. Without it, in a Cargo workspace
1123/// the test binaries (CWD = package dir, set by nextest) write to
1124/// `{package}/target/ktstr` while the orchestrator (CWD = invocation
1125/// dir) scans elsewhere, so the post-run footer finds nothing.
1126///
1127/// Set ONCE by the parent and inherited by every child test process —
1128/// children never re-run `cargo metadata` (it would be one subprocess
1129/// spawn per test process on the hot path). Unset under raw `cargo
1130/// nextest run` (no orchestrator): [`test_support::runs_root`] falls
1131/// back to its CWD-relative default, which is fine because raw nextest
1132/// has no footer to mismatch.
1133pub const KTSTR_RUNS_ROOT_ENV: &str = "KTSTR_RUNS_ROOT";
1134
1135/// Name of the environment variable that overrides the default
1136/// host-mode cgroup parent (where `host_only` tests' workload
1137/// cgroups land). Empty / unset falls back to the canonical
1138/// default; a non-empty value must be rooted under
1139/// `/sys/fs/cgroup` and name a non-root subdirectory.
1140///
1141/// Single source of truth so the name is not spelled by hand at
1142/// each reader. Mirrors the sibling `KTSTR_KERNEL_ENV` /
1143/// `KTSTR_KERNEL_LIST_ENV` / `KTSTR_KERNEL_PARALLELISM_ENV` /
1144/// `KTSTR_VERIFIER_RAW_ENV` / `KTSTR_ORCHESTRATED_ENV`
1145/// constant-defined naming convention; a single grep across
1146/// `KTSTR_*_ENV` consts gives the operator the complete env-var
1147/// inventory.
1148///
1149/// Read by `crate::test_support::dispatch::resolve_host_cgroup_parent`.
1150pub const KTSTR_HOST_CGROUP_PARENT_ENV: &str = "KTSTR_HOST_CGROUP_PARENT";
1151
1152/// Name of the environment variable that overrides the cgroup-fs
1153/// root [`crate::cgroup::CgroupManager::setup`] walks down from when
1154/// enabling controllers in every ancestor's `cgroup.subtree_control`.
1155/// Empty / unset falls back to `/sys/fs/cgroup` (the canonical
1156/// cgroup-v2 mount). Non-empty value must be a prefix of
1157/// [`KTSTR_HOST_CGROUP_PARENT_ENV`]'s configured parent so the walk
1158/// stays inside the directory the operator owns; values that do not
1159/// satisfy the prefix invariant are rejected upfront by
1160/// [`crate::cgroup::CgroupManager::with_walk_root`].
1161///
1162/// Exists for cgroup-v2 user delegation (Mode B/C: systemd
1163/// `Delegate=yes`, container `nsdelegate`): the operator owns
1164/// `subtree_control` writes only inside the delegated subtree, and a
1165/// blind walk from `/sys/fs/cgroup` down would EACCES at the
1166/// `user.slice` / container-root boundary. Setting the walk root to
1167/// the delegation boundary makes the setup-time controller-enable
1168/// walk stop there.
1169///
1170/// # Empty-string contract
1171///
1172/// Empty string is observationally identical to unset: both fall
1173/// back to `/sys/fs/cgroup` (the [`crate::cgroup::CgroupManager::new`]
1174/// default). This mirrors the sibling env vars; a shell that exports
1175/// `KTSTR_CGROUP_WALK_ROOT=` (without a value) explicitly opts back
1176/// into the default rather than passing an empty path down to
1177/// [`crate::cgroup::CgroupManager::with_walk_root`] (which would
1178/// always fail the prefix invariant).
1179///
1180/// Single source of truth so the name is not spelled by hand at each
1181/// reader. Mirrors the sibling [`KTSTR_HOST_CGROUP_PARENT_ENV`]
1182/// constant-defined naming convention; a single grep across
1183/// `KTSTR_*_ENV` consts gives the operator the complete env-var
1184/// inventory.
1185///
1186/// Read by `crate::test_support::dispatch::resolve_host_cgroup_parent`.
1187pub const KTSTR_CGROUP_WALK_ROOT_ENV: &str = "KTSTR_CGROUP_WALK_ROOT";
1188
1189/// Name of the environment variable that overrides the poll cadence
1190/// (in milliseconds) of the host-mode stuck monitor in
1191/// [`crate::scenario::host_stuck`].
1192///
1193/// The monitor runs in a background thread and samples
1194/// `/proc/<pid>/sched` every N ms for every worker pid the scenario
1195/// spawned; W consecutive samples with `Δnr_switches == 0` AND
1196/// `Δsum_exec_runtime == 0` flip the stuck predicate. Default
1197/// cadence is 500 ms × W=4 = 2 s detection latency.
1198///
1199/// # **Empty = unset** (also: `0` / unparseable)
1200///
1201/// Empty / unset / `0` / unparseable falls back to the default
1202/// ([`crate::scenario::host_stuck::DEFAULT_POLL_INTERVAL_MS`]).
1203/// Mirrors the empty-as-unset contract documented on the sibling
1204/// `KTSTR_*_ENV` constants so a shell `KTSTR_STUCK_POLL_MS=` quirk
1205/// silently degrades to default behavior rather than poisoning the
1206/// poller with a zero interval (which would either busy-loop or be
1207/// no-op-rejected).
1208///
1209/// Read once at `crate::scenario::host_stuck::spawn_monitor` when the
1210/// scenario engine spawns the monitor; mid-scenario env mutations
1211/// are NOT observed by the running thread.
1212///
1213/// Single source of truth so the name is not spelled by hand at
1214/// each reader. Mirrors the sibling [`KTSTR_HOST_CGROUP_PARENT_ENV`]
1215/// constant-defined naming convention; a single grep across
1216/// `KTSTR_*_ENV` consts gives the operator the complete env-var
1217/// inventory.
1218pub const KTSTR_STUCK_POLL_MS_ENV: &str = "KTSTR_STUCK_POLL_MS";
1219
1220/// Name of the environment variable that overrides the rayon
1221/// pool width used by `cargo ktstr`'s `resolve_kernel_set` to
1222/// fan out per-spec kernel resolves (download / git-clone /
1223/// build) in parallel. Default cap is `available_parallelism()`
1224/// — the host's logical CPU count — chosen so download streams
1225/// do not outnumber threads the host can drive without
1226/// thrashing a contended local network (kernel.org CDN
1227/// per-IP throttle, developer ISP, CI shared NIC).
1228///
1229/// Operators override when the default is wrong for their
1230/// environment: a fast NIC + slow CPU benefits from raising
1231/// the cap above logical-CPU count to keep more downloads
1232/// in flight; a contended CI runner with concurrent jobs
1233/// benefits from lowering it to 1 or 2 to leave bandwidth
1234/// for siblings; a multi-version `--kernel A..Z` resolve on
1235/// a workstation may want a hand-tuned middle value to
1236/// balance throughput against background load.
1237///
1238/// Parsed as `usize`; 0 and unparseable values fall through
1239/// to the default cap so a typoed export does not silently
1240/// disable parallelism. Leading/trailing whitespace is trimmed
1241/// before parsing so a shell-quoted `=" 8 "` behaves the same
1242/// as the unquoted form. Read by
1243/// [`crate::cli::resolve_kernel_parallelism`] (the helper
1244/// that combines this env value with the
1245/// `available_parallelism()` fallback) so the parsing rules
1246/// live in one place.
1247///
1248/// Single source of truth so the name is not spelled by hand at
1249/// each reader; if the name ever changes, the change lands in one
1250/// place instead of fanning out to every call site.
1251pub const KTSTR_KERNEL_PARALLELISM_ENV: &str = "KTSTR_KERNEL_PARALLELISM";
1252
1253/// Name of the environment variable that switches the `cargo ktstr
1254/// verifier` per-cell handler from the cycle-collapsed default
1255/// rendering to a raw scheduler-log dump. Set to any value (the
1256/// presence of the variable is what matters; the value is ignored)
1257/// by the dispatcher in `src/bin/cargo_ktstr/verifier.rs` when the
1258/// operator passes `--raw`, and read by
1259/// `crate::test_support::dispatch::run_verifier_cell` before
1260/// formatting via [`crate::verifier::format_verifier_output`].
1261///
1262/// Single source of truth so the name is not spelled by hand at
1263/// each reader; if the name ever changes, the change lands in one
1264/// place instead of fanning out to every call site.
1265pub const KTSTR_VERIFIER_RAW_ENV: &str = "KTSTR_VERIFIER_RAW";
1266
1267/// Name of the environment variable carrying the directory that each
1268/// `cargo ktstr verifier` cell writes its per-cell PASS/FAIL record to.
1269/// The `cargo ktstr verifier` dispatcher creates the dir, exports this
1270/// var (inherited by the spawned `cargo nextest run` and thus by every
1271/// cell process), and after nextest returns reads the records back to
1272/// render one PASS/FAIL grid per scheduler (rows = topology, cols =
1273/// kernel). Unset
1274/// when a verifier cell runs outside the dispatcher (a hand-driven
1275/// `--exact verifier/...`): the cell then simply skips the record write.
1276/// Single source of truth so the name is not spelled by hand at the
1277/// writer (cell) and reader (dispatcher) ends.
1278pub const KTSTR_VERIFIER_RESULT_DIR_ENV: &str = "KTSTR_VERIFIER_RESULT_DIR";
1279
1280/// Name of the environment variable carrying the immutable, versioned
1281/// scheduler-artifact manifest written by every nextest-backed `cargo ktstr`
1282/// parent.
1283///
1284/// Every child `Discover` or `Path` resolution performs an exact tagged
1285/// `(binary specification, manifest_dir, profile)` lookup. Verifier cells
1286/// additionally validate the declared scheduler name. When unset,
1287/// direct/manual test-binary invocations retain on-demand resolution. When
1288/// set, any malformed manifest, missing identity, or invalid path is a hard
1289/// error and never falls back to Cargo or a mutable source path.
1290pub const KTSTR_SCHEDULER_MANIFEST_ENV: &str = "KTSTR_SCHEDULER_MANIFEST";
1291
1292/// Name of the environment variable carrying the immutable, versioned
1293/// verifier-cell ownership manifest written by the `cargo ktstr verifier`
1294/// parent.
1295///
1296/// Recursive discovery can find the same exact `declare_scheduler!`
1297/// declaration in multiple linked test binaries. The parent elects one
1298/// canonical executable for each full scheduler identity and records that
1299/// mapping here. Every child consults it both while listing cells and before
1300/// exact-cell dispatch, so one declaration produces one nextest cell and one
1301/// result writer across the whole warmed binary set. When unset, direct/manual
1302/// test-binary invocations retain the legacy behavior. Once set, malformed or
1303/// incomplete ownership data is a hard error and never falls back to every
1304/// binary owning the cell.
1305pub const KTSTR_VERIFIER_CELL_OWNERSHIP_MANIFEST_ENV: &str =
1306    "KTSTR_VERIFIER_CELL_OWNERSHIP_MANIFEST";
1307
1308/// Name of the environment variable carrying the operator's
1309/// `cargo ktstr verifier --scheduler <NAME>` filter. Set by the
1310/// dispatcher in `src/bin/cargo_ktstr/verifier.rs`; read by
1311/// `crate::test_support::dispatch`'s verifier cell emission, which
1312/// skips every declared scheduler whose `name` does not equal the value
1313/// so the sweep runs one scheduler across topologies instead of the
1314/// full declared-scheduler matrix. Unset, every declared scheduler is
1315/// swept. Single source of truth so the writer (dispatcher) and reader
1316/// (emission) do not spell the name by hand.
1317pub const KTSTR_VERIFIER_SCHEDULER_ENV: &str = "KTSTR_VERIFIER_SCHEDULER";
1318
1319/// Name of the environment variable that forces ktstr to skip the
1320/// `perf_event_open` access check + the
1321/// `perf_event_paranoid`-relaxation gate. Read at scenario-engine
1322/// startup ([`crate::test_support::runtime`]) and by the
1323/// `cargo ktstr shell` / verifier dispatch sites that disable
1324/// perf collection when the operator passes `--no-perf-mode`.
1325///
1326/// **Empty = unset** per the default contract — empty value is
1327/// treated as not set. The canonical reader at
1328/// `crate::test_support::runtime::no_perf_mode_active` uses
1329/// `.map(|v| !v.is_empty()).unwrap_or(false)` after a prior
1330/// regression where CI shells exporting `KTSTR_NO_PERF_MODE=`
1331/// silently disabled perf mode for every `performance_mode` test.
1332/// Any non-empty value (`"1"`, `"yes"`, `"0"`, `"true"`) enables
1333/// no-perf-mode. All readers (shell-mode VM builder in
1334/// `lib.rs`, verifier dispatch in `verifier.rs`, dispatch
1335/// gauntlet + eval entry in `test_support/dispatch.rs` and
1336/// `test_support/eval/mod.rs`)
1337/// route through the canonical helper so the empty-string
1338/// contract holds uniformly.
1339pub const KTSTR_NO_PERF_MODE_ENV: &str = "KTSTR_NO_PERF_MODE";
1340
1341/// Name of the environment variable that restricts a run to ONLY
1342/// `performance_mode` tests: when set to a non-empty value, every
1343/// test whose entry does not have `performance_mode` is skipped
1344/// (skip sidecar recorded, libtest sees pass) before any VM boot.
1345/// The mergebase perf-delta subcommand sets this so a regression run
1346/// measures only the tests configured for clean performance numbers;
1347/// an explicit nextest `-E` filter narrows further within the
1348/// perf-mode set.
1349///
1350/// **Empty = unset** per the default contract, matching
1351/// [`KTSTR_NO_PERF_MODE_ENV`]. The canonical reader
1352/// `test_support::runtime::perf_only_active` (pub(crate)) uses
1353/// `.map(|v| !v.is_empty()).unwrap_or(false)` so a stray
1354/// `KTSTR_PERF_ONLY=` pass-through does not silently skip every
1355/// non-perf test. Readers route through the helper (dispatch
1356/// gauntlet + named routes in `test_support/dispatch.rs` and the
1357/// eval entry in `test_support/eval/mod.rs`).
1358pub const KTSTR_PERF_ONLY_ENV: &str = "KTSTR_PERF_ONLY";
1359
1360/// Name of the environment variable that enables the GitHub Actions
1361/// remote-cache backend in [`crate::remote_cache`]. Read at cache-
1362/// init time; value-typed — only the exact string `"1"` enables;
1363/// unset / empty / any other value (including `"true"`, `"yes"`,
1364/// `"0"`, `"false"`) is disabled. Set explicitly by GitHub Actions
1365/// workflows when the runner has cache-API credentials; absent in
1366/// dev environments where local-only caching is the right default.
1367pub const KTSTR_GHA_CACHE_ENV: &str = "KTSTR_GHA_CACHE";
1368
1369/// Name of the environment variable that signals ktstr is running
1370/// in "cargo test" mode (raw test binary launched by cargo's test
1371/// harness, no orchestrator). Distinct from
1372/// [`KTSTR_ORCHESTRATED_ENV`] which marks cargo-ktstr orchestration;
1373/// `KTSTR_CARGO_TEST_MODE` is for narrower cases like in-process
1374/// VMM tests that adapt their resource budgets when run via
1375/// `cargo test` / `cargo nextest`. Read via
1376/// `crate::cargo_test_mode::cargo_test_mode_active`: treats
1377/// unset and empty as disabled; ANY non-empty value enables —
1378/// no trim, no special-case strings (`"0"` and `"false"` ENABLE
1379/// because they're non-empty).
1380pub const KTSTR_CARGO_TEST_MODE_ENV: &str = "KTSTR_CARGO_TEST_MODE";
1381
1382/// Name of the environment variable carrying every immutable-to-writable
1383/// source-root mapping for a reused Cargo/nextest artifact closure.
1384///
1385/// The value is an internal, versioned wire format. It includes the primary
1386/// workspace and every linked local source root, so runtime helpers can map
1387/// compile-time paths such as `env!("CARGO_MANIFEST_DIR")` back onto their
1388/// writable checkout. An absent value disables translation; a malformed value
1389/// is rejected.
1390#[doc(hidden)]
1391pub const KTSTR_SOURCE_ROOT_REMAPS_ENV: &str = "KTSTR_SOURCE_ROOT_REMAPS";
1392
1393/// Name of the environment variable that overrides ktstr's cache
1394/// root directory (kernel-build cache, btf-anchor cache, blob
1395/// cache, etc.). Empty / unset falls back to the per-user default
1396/// (typically `$HOME/.cache/ktstr`). Heavy test usage —
1397/// `crate::test_support::test_helpers::IsolatedCacheDir` sets it
1398/// to a temp dir per-test so cache reads don't leak host state
1399/// into the test, and post-test the original value is restored
1400/// via `crate::test_support::test_helpers::EnvVarGuard`.
1401pub const KTSTR_CACHE_DIR_ENV: &str = "KTSTR_CACHE_DIR";
1402
1403/// Name of the environment variable that overrides ktstr's flock
1404/// directory for inter-process resource locking (cpuset / LLC
1405/// reservation locks). Empty / unset falls back to the hardcoded
1406/// `/tmp` default at `crate::cache::resolve::resolve_lock_dir`
1407/// (the literal string, not `std::env::temp_dir()` / `TMPDIR`
1408/// resolution — historical default kept for stability). Used by
1409/// tests + CI environments that need isolated lock-dirs.
1410pub const KTSTR_LOCK_DIR_ENV: &str = "KTSTR_LOCK_DIR";
1411
1412/// The nextest test-group name for ordinary CPU-bounded host tests,
1413/// as spelled in `.config/nextest.toml`. Resource users (tests that
1414/// enter production host-resource admission) belong in the
1415/// effectively-unbounded `@global` group instead; the fail-closed
1416/// guard in `crate::vmm::host_topology` aborts when a test that takes
1417/// real admission was classified into this group. This literal is the
1418/// group name (matched against nextest's `NEXTEST_TEST_GROUP`), not a
1419/// value read from config; `nextest_host_tests_group_matches_config`
1420/// pins it equal to the checked-in `.config/nextest.toml` spelling.
1421pub const NEXTEST_HOST_TESTS_GROUP: &str = "host-tests";
1422
1423/// Name of the environment variable cargo-ktstr stamps onto every
1424/// nextest run command with the lock/registry directory it resolved
1425/// in the parent process. Test processes (and their children) inherit
1426/// it; the misclassification guard in `crate::vmm::host_topology`
1427/// consumes it as a sealed reference — the "namespace the real
1428/// scheduler is using this run" — so a `host-tests`-classified test is
1429/// aborted only when it resolves THIS exact dir, not when it redirected
1430/// its locks into an isolated temp namespace (which legitimately runs
1431/// in `host-tests`). Absent (e.g. an ad-hoc `cargo nextest run` not
1432/// launched by cargo-ktstr) disarms the guard entirely.
1433pub const KTSTR_PRODUCTION_LOCK_DIR_ENV: &str = "KTSTR_PRODUCTION_LOCK_DIR";
1434
1435/// Resolve the shared lock/registry directory to stamp into
1436/// [`KTSTR_PRODUCTION_LOCK_DIR_ENV`] when cargo-ktstr spawns nextest.
1437/// Identical resolution to every production admission path, so a test
1438/// process resolving the same env/default lands on a byte-equal path.
1439pub fn resolve_production_lock_dir() -> std::path::PathBuf {
1440    crate::cache::resolve_lock_dir()
1441}
1442
1443/// Name of the environment variable that triggers verbose logging
1444/// in the VMM setup phase. Strict `v == "1"` semantics (only the
1445/// literal `"1"` enables; unset / empty / any other value —
1446/// including `"true"`, `"yes"`, `"0"` — is disabled). Read in
1447/// `crate::vmm::setup` at the two cmdline-assembly sites (one per
1448/// arch: x86_64 and aarch64); both readers identical.
1449pub const KTSTR_VERBOSE_ENV: &str = "KTSTR_VERBOSE";
1450
1451/// Name of the environment variable that enables the VMM's verbose
1452/// host-side diagnostics (per-vCPU affinity-mask lines, the BSP
1453/// run-loop trace, and the `CLEANUP:` teardown timings). Value-typed:
1454/// only the exact string `"1"` enables; unset / empty / any other
1455/// value is disabled. Read once via
1456/// `crate::vmm::debug_logging_enabled` (crate-private), which
1457/// OR-combines it with [`RUNNER_DEBUG_ENV`]. Default-off keeps these
1458/// lines out of normal
1459/// CI logs where they otherwise bury the scheduler failure under
1460/// investigation.
1461pub const KTSTR_DEBUG_ENV: &str = "KTSTR_DEBUG";
1462
1463/// Name of the environment variable GitHub Actions exports (set to
1464/// `"1"`) when a job is re-run with "Enable debug logging". Not a
1465/// `KTSTR_*` variable, but honoured alongside [`KTSTR_DEBUG_ENV`] by
1466/// `crate::vmm::debug_logging_enabled` (crate-private) so a failed CI
1467/// job re-run in debug mode gets the full VMM diagnostics without any
1468/// ktstr-specific
1469/// knob. Value-typed: only `"1"` enables.
1470pub const RUNNER_DEBUG_ENV: &str = "RUNNER_DEBUG";
1471
1472/// Name of the environment variable that bypasses LLC resource
1473/// locks at scenario setup (test_support::dispatch / cargo-ktstr
1474/// shell). Set by the `--bypass-llc-locks` CLI flag.
1475///
1476/// Reader sites use the canonical
1477/// [`crate::bypass_llc_locks_active`] helper (re-export of
1478/// [`test_support::runtime::bypass_llc_locks_active`]) which
1479/// applies the empty-string-as-unset contract uniformly across
1480/// all 7 callers (vmm/builder.rs, cli/kernel_build/build.rs ×2,
1481/// bin/ktstr.rs ×2, bin/cargo_ktstr/{kernel/mod, misc/shell}).
1482pub const KTSTR_BYPASS_LLC_LOCKS_ENV: &str = "KTSTR_BYPASS_LLC_LOCKS";
1483
1484/// Name of the environment variable that caps the host CPU count
1485/// the scenario engine sees, for testing scaling logic without a
1486/// real CPU narrowing. Read at
1487/// `crate::vmm::host_topology` and set by the `--cpu-cap` CLI
1488/// flag in the bin entry points. Empty falls back to the
1489/// host's actual CPU count; non-empty numeric value caps the
1490/// observed count.
1491pub const KTSTR_CPU_CAP_ENV: &str = "KTSTR_CPU_CAP";
1492
1493/// Name of the environment variable carrying the orchestrator-resolved
1494/// fallback for `Scheduler` declarations whose `manifest_dir` is the empty
1495/// runtime sentinel. `cargo ktstr` pins its own resolution once in `main`
1496/// and every descendant (nextest children, admission re-execs, verifier
1497/// cells) inherits it, so the parent's ELF-stamp requirements and each
1498/// child's `Scheduler::effective_manifest_dir` resolve to one exact string
1499/// — scheduler-artifact manifest identities match byte-for-byte. Takes
1500/// precedence over `CARGO_MANIFEST_DIR` in
1501/// `test_support::runtime_manifest_dir`; a nested `cargo ktstr` (the
1502/// recursive verifier fixture) re-pins its own value for its own subtree.
1503pub const KTSTR_MANIFEST_DIR_FALLBACK_ENV: &str = "KTSTR_MANIFEST_DIR_FALLBACK";
1504
1505/// Name of the environment variable that bypasses the contention
1506/// guard at scenario setup. Strict `v == "1"` semantics (only
1507/// the literal `"1"` enables; everything else disables). Used
1508/// by tests that need to provoke contention scenarios without
1509/// the production guard kicking in.
1510pub const KTSTR_CONTENTION_BYPASS_ENV: &str = "KTSTR_CONTENTION_BYPASS";
1511
1512/// Name of the environment variable cargo-ktstr's test
1513/// dispatcher sets to disable the skip-on-contention test
1514/// behavior. Presence check via `var_os(...).is_some()` — set
1515/// to "1" by `cargo ktstr test --no-skip-mode`, absent
1516/// otherwise.
1517///
1518/// **Deviates from the contract-default empty-as-unset rule**:
1519/// `var_os` does not distinguish empty from non-empty, so
1520/// `KTSTR_NO_SKIP_MODE=` (empty) ENABLES the bypass. Same
1521/// shape as [`KTSTR_GUEST_INIT_ENV`].
1522pub const KTSTR_NO_SKIP_MODE_ENV: &str = "KTSTR_NO_SKIP_MODE";
1523
1524/// Name of the environment variable that overrides the per-test
1525/// budget in seconds for VM-boot dispatch. Empty / unset falls
1526/// back to the dispatcher's default. Parsed as f64 seconds at
1527/// `crate::test_support::dispatch` (accepts fractional values
1528/// like `2.5`); invalid or non-positive values surface a warn
1529/// and the default applies.
1530pub const KTSTR_BUDGET_SECS_ENV: &str = "KTSTR_BUDGET_SECS";
1531
1532/// Name of the environment variable that overrides the sidecar
1533/// output directory (the per-test `*.ktstr.json` write target).
1534/// Empty / unset falls back to the per-test
1535/// `target/ktstr/<run-id>` location. Read at
1536/// `crate::test_support::sidecar` +
1537/// `crate::cli::stats_cmds::dispatch` (the stats reader).
1538pub const KTSTR_SIDECAR_DIR_ENV: &str = "KTSTR_SIDECAR_DIR";
1539
1540/// Name of the environment variable that overrides the scheduler
1541/// binary path test_support::eval uses for in-process scheduler
1542/// dispatch. Read at `crate::test_support::eval`. This is a COARSE
1543/// (global) override: it applies to EVERY `SchedulerSpec::Discover`
1544/// scheduler regardless of name, so a test declaring multiple distinct
1545/// schedulers points them all at the same binary through it.
1546///
1547/// Resolution precedence: this global var is checked first — before the
1548/// cargo-test-mode `$PATH` lookup and the on-demand workspace build; if
1549/// it does not resolve, resolution falls through to the build.
1550pub const KTSTR_SCHEDULER_ENV: &str = "KTSTR_SCHEDULER";
1551
1552/// Name of the environment variable that overrides the kernel
1553/// path the eval dispatch reads (orthogonal to
1554/// [`KTSTR_KERNEL_ENV`] which the main entry points use). Read
1555/// at `crate::test_support::eval::resolve_test_kernel`: a
1556/// set-but-empty `KTSTR_TEST_KERNEL=` surfaces a
1557/// `KTSTR_TEST_KERNEL not found:` hard error (typo-loud per
1558/// reader comment); ONLY the unset / `Err(NotPresent)` case
1559/// falls through to `crate::find_kernel()` (cache + sysroot
1560/// probes), which themselves fall through to a
1561/// `KernelUnavailable` error hinting at both
1562/// `KTSTR_TEST_KERNEL` and `KTSTR_KERNEL`.
1563pub const KTSTR_TEST_KERNEL_ENV: &str = "KTSTR_TEST_KERNEL";
1564
1565/// Name of the environment variable cargo-ktstr's spawn-pipeline
1566/// sets to "1" inside the guest-side init binary so the binary
1567/// detects it's running as the guest init. Presence check via
1568/// `var_os(...).is_none()` at `crate::workload::spawn` —
1569/// absent in host-side dispatch.
1570///
1571/// **Deviates from the contract-default empty-as-unset rule**:
1572/// `var_os` does not distinguish empty from non-empty, so
1573/// `KTSTR_GUEST_INIT=` (empty) is observed as SET and disables
1574/// the orphan-detection fast-path. Same shape as
1575/// [`KTSTR_NO_SKIP_MODE_ENV`].
1576pub const KTSTR_GUEST_INIT_ENV: &str = "KTSTR_GUEST_INIT";
1577
1578/// Name of the environment variable that points at a probe binary
1579/// for jemalloc-feature detection. Empty / unset leaves the probe
1580/// binary unwired (the [`crate::test_support::runtime`]
1581/// builder-wiring site calls `.jemalloc_probe_binary()` only on
1582/// set+non-empty — there is no `which`-based fallback). Tests
1583/// that need the probe set this var via `#[ctor]` before the
1584/// harness runs (see `tests/jemalloc_probe_tests.rs`).
1585pub const KTSTR_JEMALLOC_PROBE_BINARY_ENV: &str = "KTSTR_JEMALLOC_PROBE_BINARY";
1586
1587/// Name of the environment variable that points at a worker
1588/// binary for jemalloc allocation-probe runs. Empty / unset
1589/// leaves the worker binary unwired — same shape as
1590/// [`KTSTR_JEMALLOC_PROBE_BINARY_ENV`]; the
1591/// [`crate::test_support::runtime`] builder-wiring site calls
1592/// `.jemalloc_alloc_worker_binary()` only on set+non-empty, no
1593/// `which`-based fallback. Set alongside the probe via `#[ctor]`
1594/// in `tests/jemalloc_probe_tests.rs`.
1595pub const KTSTR_JEMALLOC_ALLOC_WORKER_BINARY_ENV: &str = "KTSTR_JEMALLOC_ALLOC_WORKER_BINARY";
1596
1597/// Name of the environment variable that opts into per-assertion
1598/// PASS logging in the verdict pipeline. Read once per call at
1599/// [`crate::assert::claim::Verdict::new`] via the
1600/// `log_passes_default` helper in src/assert/claim.rs:
1601/// the reader is `!(v.is_empty() || v == "0")`, so empty and
1602/// the literal `"0"` disable; any other value (`"1"`, `"true"`,
1603/// `"yes"`, even `"false"` because it isn't `"0"`) enables.
1604/// Unset → disabled. Default-off keeps the PASS path
1605/// unallocated under normal runs.
1606pub const KTSTR_LOG_PASSES_ENV: &str = "KTSTR_LOG_PASSES";
1607
1608/// Name of the environment variable that points at the busybox
1609/// blob on-disk. Exported by `cargo-ktstr`'s startup
1610/// `install_env` (see `bin/cargo_ktstr/blobs.rs`) which extracts
1611/// the embedded `BUSYBOX_BYTES` to a tempfile and sets this var
1612/// to the absolute path; read by
1613/// `crate::vmm::blobs::load_busybox_bytes`. Both unset and
1614/// set-but-empty surface a hard error, BUT the diagnostic
1615/// differs: unset hits the `Err(_)` arm and surfaces the
1616/// "blob is provided by `cargo-ktstr` at startup" install-env
1617/// hint; empty hits the `Ok("")` arm and falls through to a
1618/// generic `fs::read("")` ENOENT — less actionable. Operators
1619/// invoking `cargo ktstr <SUB>` see neither case; raw
1620/// `cargo nextest run` reliably triggers the unset diagnostic.
1621/// Busybox is load-bearing for shell-mode VMs + disk-template
1622/// builds.
1623pub const KTSTR_BUSYBOX_PATH_ENV: &str = "KTSTR_BUSYBOX_PATH";
1624
1625#[cfg(feature = "wprof")]
1626pub const KTSTR_WPROF_PATH_ENV: &str = "KTSTR_WPROF_PATH";
1627
1628/// Shared skip / error hint for call sites that cannot proceed
1629/// without a resolvable kernel. Phrased so the user sees the same
1630/// wording regardless of which layer surfaced the failure — tests,
1631/// CLI, monitor probes, and sidecar writers all point the operator
1632/// at the same remediation. Referenced by the non-VM-boot skip
1633/// paths in `cache.rs`, `probe/btf.rs`, `monitor/mod.rs`,
1634/// `test_support/eval/mod.rs`, and `test_support/mod.rs`.
1635///
1636/// Format: caller prefixes the actionable first clause (e.g.
1637/// "no vmlinux found") and appends this constant as the
1638/// remediation tail. Keeping the prefix per-caller lets each site
1639/// name the specific artifact it needs while the `KTSTR_KERNEL`
1640/// wording stays consistent.
1641// NOTE: the "accepted forms" enumeration here mirrors
1642// [`kernel_path::KERNEL_ID_GRAMMAR`] verbatim — keep in sync when
1643// either changes. (Composition at const time needs `concat!`-of-
1644// literals, and `KERNEL_ID_GRAMMAR` is a `const &str` not a literal.)
1645pub const KTSTR_KERNEL_HINT: &str = "set KTSTR_KERNEL to one of: \
1646    exact version (`6.14`), inclusive range (`6.14..7.0` or \
1647    `6.14..=7.0`), git source (`git+URL#tag=NAME`, \
1648    `git+URL#branch=NAME`, or `git+URL#sha=<40-hex>`), absolute or \
1649    `~`-prefixed path, local kernel package (`*.rpm`, `*.deb`, or \
1650    `*.pkg.tar.zst`), distro kernel (`fedora`/`fedora-44`/`f44`, \
1651    `ubuntu`/`ubuntu-24.04`, `amazonlinux`/`amazonlinux-2023`/`al2023`, \
1652    `steamos`/`steamos-3.8`, `gke`/`gke-129`), or \
1653    cache key. List \
1654    cached keys with `cargo ktstr kernel list`; build new ones with \
1655    `cargo ktstr kernel build`";
1656
1657/// Read [`KTSTR_KERNEL_ENV`] once, normalizing the raw value:
1658/// missing / empty / whitespace-only reads collapse to `None`, and
1659/// a surrounding-whitespace trim is applied so a shell-quoted
1660/// `KTSTR_KERNEL=" ../linux"` behaves the same as the unquoted
1661/// form. Every caller that reads the env var should route through
1662/// this helper so the normalization rules live in one place; a
1663/// future change to the rules (e.g. accepting a trailing slash)
1664/// propagates to every site automatically.
1665///
1666/// Returns the raw string; callers that need a structured
1667/// identifier parse with [`kernel_path::KernelId::parse`].
1668pub fn ktstr_kernel_env() -> Option<String> {
1669    std::env::var(KTSTR_KERNEL_ENV)
1670        .ok()
1671        .map(|v| v.trim().to_string())
1672        .filter(|v| !v.is_empty())
1673}
1674
1675/// Find a bootable kernel image on the host.
1676///
1677/// Resolution chain:
1678/// 1. `KTSTR_KERNEL` env var, parsed via `KernelId`:
1679///    - Path: search that directory for an arch-specific image
1680///    - Version/CacheKey: require cache access (error if cache
1681///      directory cannot be opened); on cache miss, skip the
1682///      general cache scan (step 2) and fall to filesystem
1683/// 2. XDG cache: most recent cached image (newest first)
1684/// 3. Local build trees (`./linux`, `../linux`,
1685///    `/lib/modules/{release}/build`)
1686/// 4. Host paths (`/lib/modules/{release}/vmlinuz`,
1687///    `/boot/vmlinuz-{release}`, `/boot/vmlinuz`)
1688///
1689/// Returns `Err` when `KTSTR_KERNEL` is a path that does not contain
1690/// a kernel image, or when it is a version/cache key and the cache
1691/// directory cannot be opened. Returns `Ok(None)` when no kernel is
1692/// found.
1693pub fn find_kernel() -> anyhow::Result<Option<std::path::PathBuf>> {
1694    use kernel_path::KernelId;
1695
1696    let release = rustix::system::uname()
1697        .release()
1698        .to_str()
1699        .ok()
1700        .map(str::to_owned);
1701    let release_ref = release.as_deref();
1702
1703    // Track whether KTSTR_KERNEL was set with a non-path value.
1704    // When the user explicitly requests a version or cache key that
1705    // misses cache, the general cache scan (step 2) must be skipped
1706    // to avoid silently returning a different kernel.
1707    let mut skip_cache_scan = false;
1708
1709    // 1. KTSTR_KERNEL env var with KernelId parsing. Route through
1710    // `ktstr_kernel_env()` so the empty/whitespace normalization
1711    // matches every other reader in the crate.
1712    if let Some(val) = ktstr_kernel_env() {
1713        match KernelId::parse(&val) {
1714            KernelId::Path(ref p) => {
1715                // `KernelId::parse` already routed `val` through
1716                // `expand_tilde`, producing the resolved `PathBuf`
1717                // here. Pass that — not the raw `val` — into
1718                // `find_image` so a `~/...` env value resolves
1719                // against `$HOME`. Lossy `to_str` would silently
1720                // mishandle non-UTF-8 paths; bail explicitly with
1721                // the same hint shape as the not-found arm.
1722                let Some(s) = p.to_str() else {
1723                    anyhow::bail!(
1724                        "KTSTR_KERNEL={val} expands to a non-UTF-8 path. \
1725                         {KTSTR_KERNEL_HINT}"
1726                    );
1727                };
1728                match kernel_path::find_image(Some(s), release_ref) {
1729                    Some(found) => return Ok(Some(found)),
1730                    None => anyhow::bail!(
1731                        "KTSTR_KERNEL={val} does not contain a kernel image. {KTSTR_KERNEL_HINT}"
1732                    ),
1733                }
1734            }
1735            KernelId::Version(ref ver) => {
1736                // Only tarball keys use the
1737                // {ver}-tarball-{arch}-kc{suffix} pattern. Content-addressed
1738                // git keys begin with git-{kind}-{refhash}-... and local keys
1739                // begin with local-{hash}-...; neither contains the version
1740                // as a prefix, so only tarball lookup is valid here.
1741                let cache = cache::CacheDir::new().map_err(|e| {
1742                    anyhow::anyhow!(
1743                        "KTSTR_KERNEL={val} requires cache access, \
1744                         but cache directory could not be opened: {e}"
1745                    )
1746                })?;
1747                let arch = std::env::consts::ARCH;
1748                let key = format!("{ver}-tarball-{arch}-kc{}", cache_key_suffix());
1749                if let Some(entry) = cache.lookup(&key) {
1750                    return Ok(Some(entry.image_path()));
1751                }
1752                // Version not in cache — skip general cache scan to
1753                // avoid returning a different kernel version.
1754                skip_cache_scan = true;
1755            }
1756            KernelId::CacheKey(ref key) => {
1757                let cache = cache::CacheDir::new().map_err(|e| {
1758                    anyhow::anyhow!(
1759                        "KTSTR_KERNEL={val} requires cache access, \
1760                         but cache directory could not be opened: {e}"
1761                    )
1762                })?;
1763                if let Some(entry) = cache.lookup(key) {
1764                    return Ok(Some(entry.image_path()));
1765                }
1766                // Explicit cache key not found — skip general cache scan.
1767                skip_cache_scan = true;
1768            }
1769            // Multi-kernel specs (`A..B` ranges; git sources like
1770            // `git+URL#branch=main` are single-kernel but share this arm)
1771            // are only meaningful at the test/coverage/verifier
1772            // subcommand entry points where the runner can fan out
1773            // across kernels. The KTSTR_KERNEL env reader resolves a
1774            // single kernel image for in-process use (BTF lookup,
1775            // direct boot path) and has no dispatch loop, so a range
1776            // or git spec here cannot be expanded.
1777            //
1778            // Run `validate()` first so an inverted range surfaces
1779            // the specific "swap the endpoints" diagnostic instead
1780            // of getting masked by the generic "not supported in
1781            // env-var form" bail below — operators with a typo see
1782            // the actionable fix; valid-but-unsupported specs get
1783            // the generic redirect.
1784            id @ (KernelId::Range { .. } | KernelId::Git { .. }) => {
1785                if let Err(e) = id.validate() {
1786                    anyhow::bail!("KTSTR_KERNEL={val}: {e}");
1787                }
1788                anyhow::bail!(
1789                    "KTSTR_KERNEL={val}: multi-kernel specs (ranges, \
1790                     git sources) are not supported in env-var form. \
1791                     Use --kernel on the test/coverage/verifier \
1792                     subcommands, or set KTSTR_KERNEL to a single \
1793                     version, cache key, or path."
1794                );
1795            }
1796            // Local packages and distro kernels acquire into the cache
1797            // (download + extract, or unpack local files) and resolve to
1798            // the boot image inside the resulting entry. Validate first
1799            // so a malformed distro release surfaces its specific
1800            // diagnostic. Note the runner injects a cache DIR into
1801            // KTSTR_KERNEL (a Path, handled above) rather than a
1802            // package/distro spec — this arm serves an operator who sets
1803            // KTSTR_KERNEL=fedora / KTSTR_KERNEL=./kernel.rpm directly.
1804            ref id @ (KernelId::Package { .. } | KernelId::Distro { .. }) => {
1805                if let Err(e) = id.validate() {
1806                    anyhow::bail!("KTSTR_KERNEL={val}: {e}");
1807                }
1808                let cache_dir = match id {
1809                    KernelId::Package { path } => {
1810                        distro::acquire::acquire_package_kernel(std::slice::from_ref(path))
1811                    }
1812                    KernelId::Distro { kind, release } => distro::acquire::acquire_distro_kernel(
1813                        *kind,
1814                        release.as_deref(),
1815                        "ktstr",
1816                        None,
1817                    ),
1818                    _ => unreachable!("arm guarded to Package | Distro"),
1819                }?;
1820                let image = kernel_path::find_image_in_dir(&cache_dir).ok_or_else(|| {
1821                    anyhow::anyhow!("no kernel image found in {}", cache_dir.display())
1822                })?;
1823                return Ok(Some(image));
1824            }
1825        }
1826    }
1827
1828    // 2. XDG cache: most recent cached image.
1829    // Skipped when KTSTR_KERNEL was an explicit version or cache key
1830    // that missed — returning a different kernel would be surprising.
1831    if !skip_cache_scan
1832        && let Ok(cache) = cache::CacheDir::new()
1833        && let Ok(entries) = cache.list()
1834    {
1835        let kc_hash = kconfig_hash();
1836        for listed in &entries {
1837            let cache::ListedEntry::Valid(entry) = listed else {
1838                continue;
1839            };
1840            // Skip entries built with a different kconfig. Untracked
1841            // (pre-kconfig-tracking) entries are reused — their image
1842            // could still boot correctly, and skipping them would
1843            // permanently orphan legacy cache entries.
1844            if entry.kconfig_status(&kc_hash).is_stale() {
1845                continue;
1846            }
1847            // Skip prebuilt distro / local-package entries. Those are
1848            // OPT-IN kernels — requested explicitly via `--kernel fedora`
1849            // / `--kernel ./pkg.rpm` or their cache key — not
1850            // auto-fallback candidates: they are not ktstr-built, carry
1851            // no kconfig hash (so they read as `Untracked`, not stale),
1852            // and may not run scx schedulers. Auto-selecting one here
1853            // would let a cached `kernel build --kernel fedora` silently
1854            // hijack a later kernel-less `cargo ktstr test`.
1855            if matches!(
1856                entry.metadata.source,
1857                cache::KernelSource::DistroPackage { .. }
1858                    | cache::KernelSource::LocalPackage { .. }
1859            ) {
1860                continue;
1861            }
1862            let image = entry.image_path();
1863            // TOCTOU guard: list() guarantees image existence at scan time,
1864            // but a concurrent cache-clean could delete between scan and use.
1865            if !image.exists() {
1866                continue;
1867            }
1868            // Guard: if a cached vmlinux is present but is missing
1869            // the symbols monitor code requires, skip the entry so
1870            // the caller falls through to a source tree. Older
1871            // caches built by a strip pipeline that dropped data
1872            // sections would pass the image-exists check but fail
1873            // downstream when the monitor initializes.
1874            if let Some(vmlinux) = entry.vmlinux_path()
1875                && let Err(e) = monitor::symbols::KernelSymbols::from_vmlinux(&vmlinux)
1876            {
1877                tracing::warn!(
1878                    entry = %entry.path.display(),
1879                    error = %e,
1880                    "skipping cached kernel with unusable vmlinux"
1881                );
1882                continue;
1883            }
1884            return Ok(Some(image));
1885        }
1886    }
1887
1888    // 3-4. Filesystem fallbacks (local build trees, host paths).
1889    Ok(kernel_path::find_image(None, release_ref))
1890}
1891
1892/// Name of the environment variable selecting the cargo build profile
1893/// for a `SchedulerSpec::Discover` scheduler built on demand by
1894/// [`build_and_find_binary`]. Holds a cargo profile NAME; unset / empty
1895/// means the RELEASE default (see `build_and_find_binary` — a debug
1896/// sched_ext scheduler is never the intended thing to test). Set by
1897/// `cargo ktstr <cmd> --profile <NAME>` (on `test` / `coverage` /
1898/// `verifier` / `perf-delta` / `replay`), or exported directly to pick a
1899/// non-default profile. This is INDEPENDENT of the harness `--release`
1900/// (`--cargo-profile release` to nextest), which selects the harness/test
1901/// binary's compile profile and does NOT touch this var — DECOUPLING the
1902/// scheduler-under-test's profile from the harness profile: the scheduler
1903/// runs optimized by default while the harness keeps its dev-profile
1904/// assertion thresholds and `catch_unwind` behavior unless its own build
1905/// profile is set separately.
1906pub const KTSTR_SCHEDULER_PROFILE_ENV: &str = "KTSTR_SCHEDULER_PROFILE";
1907
1908/// The cargo build profile NAME for the scheduler-under-test:
1909/// [`KTSTR_SCHEDULER_PROFILE_ENV`] when set non-empty, else the
1910/// `"release"` default. Consumed by [`build_and_find_binary`] (which
1911/// passes it as `cargo build --profile <name>` and reads the artifact
1912/// path back from cargo's JSON output) and by the `affected` scheduler
1913/// prebuild, so every scheduler build agrees on the profile.
1914pub fn scheduler_profile_name() -> String {
1915    resolve_scheduler_profile(std::env::var(KTSTR_SCHEDULER_PROFILE_ENV).ok())
1916}
1917
1918/// Pure resolution of the scheduler build-profile NAME from the raw
1919/// [`KTSTR_SCHEDULER_PROFILE_ENV`] value: a non-empty value verbatim,
1920/// else the `"release"` default. An empty string is treated as UNSET —
1921/// so a stray `--profile ""` / `KTSTR_SCHEDULER_PROFILE=` can never make
1922/// [`build_and_find_binary`] run `cargo build --profile ""` (which would
1923/// resolve the artifact under an empty-named profile dir). Split from
1924/// [`scheduler_profile_name`] so the empty / unset / named cases are
1925/// unit-testable without mutating process env.
1926fn resolve_scheduler_profile(env_val: Option<String>) -> String {
1927    env_val
1928        .filter(|p| !p.is_empty())
1929        .unwrap_or_else(|| "release".to_string())
1930}
1931
1932#[cfg(test)]
1933mod scheduler_profile_tests {
1934    use super::resolve_scheduler_profile;
1935
1936    /// The scheduler build-profile default: unset AND empty both fall
1937    /// back to `release` (empty is treated as unset so a stray
1938    /// `--profile ""` / `KTSTR_SCHEDULER_PROFILE=` cannot build under an
1939    /// empty-named profile dir); a non-empty name passes through verbatim
1940    /// (`dev`, `release`, or any custom `[profile.<name>]`). Pins the
1941    /// exact regressions [`resolve_scheduler_profile`] guards — dropping
1942    /// the `.filter(!is_empty)` (empty → empty name) or flipping the
1943    /// default flips a case.
1944    #[test]
1945    fn resolve_scheduler_profile_defaults_and_passthrough() {
1946        assert_eq!(
1947            resolve_scheduler_profile(None),
1948            "release",
1949            "unset -> release default"
1950        );
1951        assert_eq!(
1952            resolve_scheduler_profile(Some(String::new())),
1953            "release",
1954            "empty string is treated as unset -> release, never an empty profile name",
1955        );
1956        assert_eq!(
1957            resolve_scheduler_profile(Some("dev".into())),
1958            "dev",
1959            "named profile passes through verbatim"
1960        );
1961        assert_eq!(resolve_scheduler_profile(Some("release".into())), "release");
1962        assert_eq!(
1963            resolve_scheduler_profile(Some("custom".into())),
1964            "custom",
1965            "custom [profile.<name>] passes through unchanged",
1966        );
1967    }
1968}
1969
1970const SOURCE_ROOT_REMAPS_WIRE_VERSION: &str = "ktstr-source-root-remaps-v1";
1971
1972fn normalized_absolute_source_root(path: &std::path::Path) -> bool {
1973    path.is_absolute()
1974        && path.components().all(|component| {
1975            matches!(
1976                component,
1977                std::path::Component::RootDir | std::path::Component::Normal(_)
1978            )
1979        })
1980        && path
1981            .components()
1982            .any(|component| matches!(component, std::path::Component::Normal(_)))
1983}
1984
1985fn validate_source_root_remaps(
1986    remaps: impl IntoIterator<Item = (std::path::PathBuf, std::path::PathBuf)>,
1987) -> Result<Vec<(std::path::PathBuf, std::path::PathBuf)>, String> {
1988    use std::os::unix::ffi::OsStrExt as _;
1989
1990    let mut unique = std::collections::BTreeMap::new();
1991    for (stable, writable) in remaps {
1992        if !normalized_absolute_source_root(&stable) {
1993            return Err(format!(
1994                "stable source root is not a normalized absolute path: {}",
1995                stable.display(),
1996            ));
1997        }
1998        if !normalized_absolute_source_root(&writable) {
1999            return Err(format!(
2000                "writable source root is not a normalized absolute path: {}",
2001                writable.display(),
2002            ));
2003        }
2004        if let Some(existing) = unique.insert(stable.clone(), writable.clone())
2005            && existing != writable
2006        {
2007            return Err(format!(
2008                "stable source root {} ambiguously maps to both {} and {}",
2009                stable.display(),
2010                existing.display(),
2011                writable.display(),
2012            ));
2013        }
2014    }
2015    if unique.is_empty() {
2016        return Err("source-root remap set is empty".to_string());
2017    }
2018    let mut remaps = unique.into_iter().collect::<Vec<_>>();
2019    // A nested local source root must win over its parent repository. The
2020    // bytewise tie-break keeps serialization deterministic across processes.
2021    remaps.sort_by(|left, right| {
2022        right
2023            .0
2024            .components()
2025            .count()
2026            .cmp(&left.0.components().count())
2027            .then_with(|| {
2028                left.0
2029                    .as_os_str()
2030                    .as_bytes()
2031                    .cmp(right.0.as_os_str().as_bytes())
2032            })
2033    });
2034    Ok(remaps)
2035}
2036
2037/// Encode all immutable-to-writable source-root mappings for a reused Cargo
2038/// build. Paths are base64-encoded as raw Unix bytes, preserving non-UTF-8
2039/// checkouts without reserving any pathname characters in the wire format.
2040#[doc(hidden)]
2041pub fn encode_source_root_remaps(
2042    remaps: &[(std::path::PathBuf, std::path::PathBuf)],
2043) -> Result<std::ffi::OsString, String> {
2044    use base64::Engine as _;
2045    use std::os::unix::ffi::OsStrExt as _;
2046
2047    let remaps = validate_source_root_remaps(remaps.iter().cloned())?;
2048    let codec = base64::engine::general_purpose::STANDARD_NO_PAD;
2049    let mut encoded = SOURCE_ROOT_REMAPS_WIRE_VERSION.to_string();
2050    for (stable, writable) in remaps {
2051        encoded.push('\n');
2052        encoded.push_str(&codec.encode(stable.as_os_str().as_bytes()));
2053        encoded.push('\t');
2054        encoded.push_str(&codec.encode(writable.as_os_str().as_bytes()));
2055    }
2056    Ok(encoded.into())
2057}
2058
2059fn decode_source_root_remaps(
2060    encoded: &std::ffi::OsStr,
2061) -> Result<Vec<(std::path::PathBuf, std::path::PathBuf)>, String> {
2062    use base64::Engine as _;
2063    use std::os::unix::ffi::OsStringExt as _;
2064
2065    let encoded = encoded
2066        .to_str()
2067        .ok_or_else(|| "source-root remap environment is not ASCII".to_string())?;
2068    let mut lines = encoded.split('\n');
2069    if lines.next() != Some(SOURCE_ROOT_REMAPS_WIRE_VERSION) {
2070        return Err("source-root remap environment has an unsupported version".to_string());
2071    }
2072    let codec = base64::engine::general_purpose::STANDARD_NO_PAD;
2073    let mut remaps = Vec::new();
2074    for (index, line) in lines.enumerate() {
2075        let (stable, writable) = line.split_once('\t').ok_or_else(|| {
2076            format!(
2077                "source-root remap entry {} has no field separator",
2078                index + 1
2079            )
2080        })?;
2081        if writable.contains('\t') {
2082            return Err(format!(
2083                "source-root remap entry {} has too many fields",
2084                index + 1,
2085            ));
2086        }
2087        let stable = codec
2088            .decode(stable)
2089            .map_err(|error| format!("decode stable source root {}: {error}", index + 1))?;
2090        let writable = codec
2091            .decode(writable)
2092            .map_err(|error| format!("decode writable source root {}: {error}", index + 1))?;
2093        remaps.push((
2094            std::path::PathBuf::from(std::ffi::OsString::from_vec(stable)),
2095            std::path::PathBuf::from(std::ffi::OsString::from_vec(writable)),
2096        ));
2097    }
2098    validate_source_root_remaps(remaps)
2099}
2100
2101fn writable_source_path_with_remaps(
2102    path: &std::path::Path,
2103    remaps: &[(std::path::PathBuf, std::path::PathBuf)],
2104) -> std::path::PathBuf {
2105    remaps
2106        .iter()
2107        .find_map(|(stable, writable)| {
2108            path.strip_prefix(stable)
2109                .ok()
2110                .map(|relative| writable.join(relative))
2111        })
2112        .unwrap_or_else(|| path.to_path_buf())
2113}
2114
2115/// Translate a source pathname embedded by a reusable Cargo build onto the
2116/// corresponding writable source checkout.
2117///
2118/// Outside a reused `cargo-ktstr` run, or when `path` is not below any stable
2119/// source root, this returns `path` unchanged. A malformed internal mapping is
2120/// rejected immediately instead of risking a write into immutable cache data.
2121#[doc(hidden)]
2122pub fn writable_source_path(path: impl AsRef<std::path::Path>) -> std::path::PathBuf {
2123    let Some(encoded) = std::env::var_os(KTSTR_SOURCE_ROOT_REMAPS_ENV) else {
2124        return path.as_ref().to_path_buf();
2125    };
2126    let remaps = decode_source_root_remaps(&encoded)
2127        .unwrap_or_else(|error| panic!("invalid {KTSTR_SOURCE_ROOT_REMAPS_ENV}: {error}"));
2128    writable_source_path_with_remaps(path.as_ref(), &remaps)
2129}
2130
2131#[cfg(test)]
2132mod writable_source_path_tests {
2133    use super::{
2134        decode_source_root_remaps, encode_source_root_remaps, validate_source_root_remaps,
2135        writable_source_path_with_remaps,
2136    };
2137    use std::os::unix::fs::PermissionsExt as _;
2138    use std::path::Path;
2139
2140    #[test]
2141    fn stable_workspace_members_map_to_the_writable_checkout() {
2142        let stable = Path::new("/cache/stable/source/primary");
2143        let writable = Path::new("/work/checkout");
2144        let member = stable.join("member/tests");
2145        let remaps = vec![(stable.to_path_buf(), writable.to_path_buf())];
2146
2147        assert_eq!(
2148            writable_source_path_with_remaps(&member, &remaps),
2149            writable.join("member/tests"),
2150        );
2151        assert_eq!(
2152            writable_source_path_with_remaps(Path::new("/other/workspace"), &remaps),
2153            Path::new("/other/workspace"),
2154            "unrelated source roots retain their own workspace semantics",
2155        );
2156    }
2157
2158    #[test]
2159    fn external_path_dependency_uses_longest_stable_source_prefix() {
2160        let encoded = encode_source_root_remaps(&[
2161            (
2162                "/cache/stable/source/repository".into(),
2163                "/work/repository".into(),
2164            ),
2165            (
2166                "/cache/stable/source/repository/external".into(),
2167                "/work/path-dependencies/scheduler".into(),
2168            ),
2169        ])
2170        .unwrap();
2171        let remaps = decode_source_root_remaps(&encoded).unwrap();
2172
2173        assert_eq!(
2174            writable_source_path_with_remaps(
2175                Path::new("/cache/stable/source/repository/external/tests/scratch"),
2176                &remaps,
2177            ),
2178            Path::new("/work/path-dependencies/scheduler/tests/scratch"),
2179        );
2180        assert_eq!(
2181            writable_source_path_with_remaps(
2182                Path::new("/cache/stable/source/repository/member/src"),
2183                &remaps,
2184            ),
2185            Path::new("/work/repository/member/src"),
2186        );
2187    }
2188
2189    #[test]
2190    fn malformed_relative_and_ambiguous_source_root_mappings_are_rejected() {
2191        assert!(
2192            encode_source_root_remaps(&[("relative/stable".into(), "/work/tree".into())])
2193                .unwrap_err()
2194                .contains("normalized absolute"),
2195        );
2196        assert!(
2197            validate_source_root_remaps([
2198                ("/cache/stable".into(), "/work/one".into()),
2199                ("/cache/stable".into(), "/work/two".into()),
2200            ])
2201            .unwrap_err()
2202            .contains("ambiguously maps"),
2203        );
2204        assert!(
2205            decode_source_root_remaps(std::ffi::OsStr::new(
2206                "ktstr-source-root-remaps-v1\nnot-base64\talso-not-base64",
2207            ))
2208            .unwrap_err()
2209            .contains("decode stable source root"),
2210        );
2211    }
2212
2213    #[test]
2214    fn verifier_fixture_scratch_is_created_in_the_writable_checkout() {
2215        let temp = tempfile::tempdir().unwrap();
2216        let stable = temp.path().join("stable/source/primary");
2217        let writable = temp.path().join("checkout");
2218        std::fs::create_dir_all(&stable).unwrap();
2219        std::fs::create_dir_all(&writable).unwrap();
2220        std::fs::set_permissions(&stable, std::fs::Permissions::from_mode(0o555)).unwrap();
2221
2222        let embedded_scratch = stable.join("target/verifier-discovery-fixtures");
2223        let scratch = writable_source_path_with_remaps(
2224            &embedded_scratch,
2225            &[(stable.clone(), writable.clone())],
2226        );
2227        std::fs::create_dir_all(&scratch).unwrap();
2228
2229        assert_eq!(scratch, writable.join("target/verifier-discovery-fixtures"));
2230        assert!(scratch.is_dir());
2231        assert!(
2232            !stable.join("target").exists(),
2233            "runtime scratch must not mutate the immutable stable source",
2234        );
2235    }
2236}
2237
2238/// Build a cargo binary package and return its output path.
2239///
2240/// Runs `cargo build -p <package>` from `workspace_dir` — the manifest
2241/// directory of the crate that DECLARED the scheduler. Cargo walks up
2242/// from there to that crate's workspace root, so the lockfile, feature
2243/// unification (e.g. vendored libbpf-sys), and target dir all come from
2244/// the scheduler's own workspace, regardless of the calling process's
2245/// working directory. For a `declare_scheduler!` scheduler `workspace_dir`
2246/// is the invoking crate's `CARGO_MANIFEST_DIR`; for ktstr's own in-tree
2247/// builders it is ktstr's crate dir (the workspace root in this repo).
2248/// Reused artifacts may embed an immutable stable-source pathname;
2249/// [`writable_source_path`] maps it back to the caller's checkout before Cargo
2250/// runs.
2251///
2252/// The scheduler-under-test is built with the RELEASE profile by
2253/// DEFAULT: a debug sched_ext scheduler is far slower and its BPF
2254/// verifier instruction counts differ, so it is never the intended thing
2255/// to test. [`KTSTR_SCHEDULER_PROFILE_ENV`] overrides the profile name
2256/// (set by `cargo ktstr <cmd> --profile <NAME>`); an unset / empty value
2257/// keeps the release default. The build passes `cargo build --profile
2258/// <name>` verbatim (`dev` = the default profile, `release` == `--release`,
2259/// any custom `[profile.<name>]`), so the returned artifact path resolves
2260/// under the matching `target/<dir>/`.
2261pub fn build_and_find_binary(
2262    package: &str,
2263    workspace_dir: &str,
2264) -> anyhow::Result<std::path::PathBuf> {
2265    let profile = scheduler_profile_name();
2266    let build_args: Vec<String> = vec![
2267        "build".into(),
2268        "-p".into(),
2269        package.into(),
2270        "--message-format=json".into(),
2271        "--profile".into(),
2272        profile,
2273    ];
2274    let workspace_dir = writable_source_path(workspace_dir);
2275    let output = std::process::Command::new("cargo")
2276        .args(&build_args)
2277        .current_dir(&workspace_dir)
2278        .stdout(std::process::Stdio::piped())
2279        .stderr(std::process::Stdio::piped())
2280        .output()
2281        .map_err(|e| anyhow::anyhow!("cargo build: {e}"))?;
2282
2283    if !output.status.success() {
2284        let stderr = String::from_utf8_lossy(&output.stderr);
2285        anyhow::bail!("cargo build -p {package} failed:\n{stderr}");
2286    }
2287
2288    let stdout = String::from_utf8_lossy(&output.stdout);
2289    for line in stdout.lines() {
2290        if let Ok(msg) = serde_json::from_str::<serde_json::Value>(line)
2291            && msg.get("reason").and_then(|r| r.as_str()) == Some("compiler-artifact")
2292            && msg
2293                .get("profile")
2294                .and_then(|p| p.get("test"))
2295                .and_then(|t| t.as_bool())
2296                == Some(false)
2297            && msg
2298                .get("target")
2299                .and_then(|t| t.get("kind"))
2300                .and_then(|k| k.as_array())
2301                .is_some_and(|kinds| kinds.iter().any(|k| k.as_str() == Some("bin")))
2302            && let Some(filenames) = msg.get("filenames").and_then(|f| f.as_array())
2303            && let Some(path) = filenames.first().and_then(|f| f.as_str())
2304        {
2305            return Ok(std::path::PathBuf::from(path));
2306        }
2307    }
2308    anyhow::bail!(
2309        "no binary artifact found for package '{package}' — cargo build \
2310         succeeded but no compiler-artifact JSON line declared a [[bin]] \
2311         target. Two common causes: (1) the package has no [[bin]] target \
2312         (library-only, or only [[example]] / [[bench]] targets); (2) the \
2313         cargo --message-format=json output shape changed and the \
2314         artifact walker missed the matching line. Run `cargo build -p \
2315         {package} --message-format=json` and check for a `compiler-artifact` \
2316         line with `\"target\":{{\"kind\":[\"bin\"],...}}` to confirm."
2317    )
2318}
2319
2320/// Resolve the current executable path, falling back to `/proc/self/exe`
2321/// when the binary has been deleted (e.g. by `cargo llvm-cov`).
2322///
2323/// On Linux, `std::env::current_exe()` reads `/proc/self/exe`.  When the
2324/// binary is unlinked while running, the kernel appends ` (deleted)` to
2325/// the readlink target, producing a path that does not exist on disk.
2326/// `/proc/self/exe` itself remains usable as a file path because the
2327/// kernel keeps the inode alive, so we fall back to it.
2328pub(crate) fn resolve_current_exe() -> anyhow::Result<std::path::PathBuf> {
2329    use anyhow::Context;
2330    let exe = std::env::current_exe().context("resolve current exe")?;
2331    if exe.exists() {
2332        return Ok(exe);
2333    }
2334    let proc_exe = std::path::PathBuf::from("/proc/self/exe");
2335    anyhow::ensure!(
2336        proc_exe.exists(),
2337        "current exe not found: {}",
2338        exe.display()
2339    );
2340    Ok(proc_exe)
2341}
2342
2343/// Boot a KVM VM in interactive shell mode.
2344///
2345/// Builds an initramfs with busybox and optional include files, then
2346/// launches a VM with bidirectional stdin/stdout forwarding. The guest
2347/// runs a shell via busybox; user-provided files are available at
2348/// `/include-files/<name>`.
2349///
2350/// `kernel`: path to the kernel image (bzImage/Image).
2351/// `numa_nodes`, `llcs`, `cores`, `threads`: guest CPU topology.
2352/// `include_files`: `(archive_path, host_path)` pairs for files to
2353///   include in the guest.
2354/// `memory_mib`: explicit guest memory override in MiB; conversion
2355///   at VM-launch is `value << 20` bytes. When `None`, memory is
2356///   computed from actual initramfs size after build.
2357/// `disk`: optional virtio-blk device backing for `/dev/vda`. When
2358///   `Some`, the framework calls
2359///   `vmm::KtstrVm::builder`'s `.disk(..)` so the guest probes a
2360///   raw block device sized per `disk.capacity_mib`.
2361/// `wprof_args`: requires the `wprof` cargo feature. When the
2362///   feature is enabled and `Some`, replaces `WprofConfig::args`
2363///   with the tokenised value before booting; `None` keeps the
2364///   defaults. Without the feature, this parameter is ignored
2365///   (a warning is emitted to stderr if `Some`).
2366/// `performance_mode`: forwarded to
2367///   `vmm::KtstrVmBuilder::performance_mode`; when `true`, the
2368///   builder pins vCPU threads, applies hugepages, NUMA mbinds, and
2369///   promotes vCPU threads to SCHED_FIFO (host-side optimizations).
2370/// `sched_enable_cmds` / `sched_disable_cmds`: forwarded to
2371///   `vmm::KtstrVmBuilder::sched_enable_cmds` /
2372///   `vmm::KtstrVmBuilder::sched_disable_cmds`. Non-empty when the
2373///   shell is reproducing a test whose scheduler is a
2374///   [`test_support::SchedulerSpec::KernelBuiltin`] variant —
2375///   guest init runs the enable cmds before drop-to-busybox and the
2376///   disable cmds on shell exit, so the operator gets the same
2377///   scheduler-loaded environment the test would see. Empty slices
2378///   mean "no scheduler-lifecycle commands."
2379#[allow(clippy::too_many_arguments)]
2380pub fn run_shell(
2381    kernel: std::path::PathBuf,
2382    numa_nodes: u32,
2383    llcs: u32,
2384    cores: u32,
2385    threads: u32,
2386    include_files: &[(&str, &std::path::Path)],
2387    memory_mib: Option<u32>,
2388    dmesg: bool,
2389    exec: Option<&str>,
2390    exec_timeout: std::time::Duration,
2391    disk: Option<vmm::disk_config::DiskConfig>,
2392    wprof_args: Option<&str>,
2393    performance_mode: bool,
2394    sched_enable_cmds: &[&str],
2395    sched_disable_cmds: &[&str],
2396) -> anyhow::Result<Option<i32>> {
2397    // Re-ignore SIGPIPE for the lifetime of the shell-mode VM. The
2398    // `cargo-ktstr` main installs SIG_DFL on SIGPIPE (so streaming
2399    // subcommands like `ktstr kernel list | head` exit cleanly rather
2400    // than panicking inside `print!`), but shell-mode owns a multi-
2401    // thread VM whose stdout/stderr writers (virtio-console TX
2402    // forwarder, COM1 console dump, banner / cleanup `eprintln!`s)
2403    // each issue blocking writes against the caller's stdio. When a
2404    // caller spawns `cargo ktstr shell --exec ...` via
2405    // `Command::output()` and reads the captured streams only after
2406    // the child exits, intermediate write contention can surface as
2407    // EPIPE on the next byte — under SIG_DFL that races the
2408    // `write_all().is_err()` BrokenPipe-handling branches in the
2409    // forwarder threads and kills the process before they can flip
2410    // `kill` and exit cleanly. SIG_IGN lets every writer observe the
2411    // EPIPE return value and propagate it through normal Rust error
2412    // handling, which is what shell mode already handles.
2413    //
2414    // SAFETY: `libc::signal` is async-signal-safe and only updates a
2415    // process-wide table entry; SIG_IGN is a well-known constant.
2416    // The change is intentionally permanent for the rest of the
2417    // process — the only caller that left SIG_DFL active was the
2418    // streaming-subcommand path, and that path never reaches
2419    // `run_shell`.
2420    unsafe {
2421        libc::signal(libc::SIGPIPE, libc::SIG_IGN);
2422    }
2423
2424    let payload = resolve_current_exe()?;
2425
2426    let owned_includes: Vec<(String, std::path::PathBuf)> = include_files
2427        .iter()
2428        .map(|(a, p)| (a.to_string(), p.to_path_buf()))
2429        .collect();
2430
2431    let mut cmdline = format!("KTSTR_MODE=shell KTSTR_TOPO={numa_nodes},{llcs},{cores},{threads}");
2432    if dmesg {
2433        cmdline.push_str(" loglevel=7");
2434    }
2435    if let Ok(val) = std::env::var("RUST_LOG") {
2436        cmdline.push_str(&format!(" RUST_LOG={val}"));
2437    }
2438
2439    // Pass host terminal environment to guest.
2440    if let Ok(term) = std::env::var("TERM") {
2441        cmdline.push_str(&format!(" KTSTR_TERM={term}"));
2442    }
2443    if let Ok(ct) = std::env::var("COLORTERM") {
2444        cmdline.push_str(&format!(" KTSTR_COLORTERM={ct}"));
2445    }
2446
2447    // Pass host terminal dimensions to guest for correct line wrapping.
2448    unsafe {
2449        let mut ws: libc::winsize = std::mem::zeroed();
2450        if libc::ioctl(libc::STDIN_FILENO, libc::TIOCGWINSZ, &mut ws) == 0
2451            && ws.ws_col > 0
2452            && ws.ws_row > 0
2453        {
2454            cmdline.push_str(&format!(
2455                " KTSTR_COLS={} KTSTR_ROWS={}",
2456                ws.ws_col, ws.ws_row
2457            ));
2458        }
2459    }
2460
2461    let no_perf_mode = crate::test_support::runtime::no_perf_mode_active();
2462    use anyhow::Context;
2463    let busybox_bytes =
2464        vmm::blobs::load_busybox_bytes().context("load busybox blob for shell-mode VM")?;
2465    #[cfg(feature = "wprof")]
2466    let wprof_config = {
2467        // A `wprof`-feature build provisions the blob via cargo-ktstr's
2468        // install_env (KTSTR_WPROF_PATH) UNLESS it was built with
2469        // KTSTR_SKIP_WPROF_BUILD=1 (the documented escape hatch, which
2470        // leaves the blob empty so install_env exports no path). A failed
2471        // resolve here therefore means that hatch is set or install_env
2472        // was bypassed — fail loud either way rather than silently
2473        // shipping a wprof-less shell VM, which surfaces downstream as a
2474        // confusing "/bin/wprof: No such file" inside the guest.
2475        let mut c = vmm::wprof::WprofConfig::from_env()
2476            .context("resolve wprof for shell mode (the `wprof` feature is enabled)")?;
2477        if let Some(args_str) = wprof_args {
2478            c.args = args_str.split_whitespace().map(String::from).collect();
2479        }
2480        Some(c)
2481    };
2482    #[cfg(not(feature = "wprof"))]
2483    if wprof_args.is_some() {
2484        crate::ktstr_status!(
2485            "ktstr: wprof_args ignored — ktstr was built without the \
2486             `wprof` cargo feature; /bin/wprof will not be available \
2487             in the guest"
2488        );
2489    }
2490    let mut builder = vmm::KtstrVm::builder()
2491        .kernel(&kernel)
2492        // Prebuilt distro kernels ship virtio as modules; embed the
2493        // ordered boot-module set from the cache entry beside the image
2494        // (empty for built kernels — a no-op).
2495        .kernel_modules(cache::boot_modules_for_image(&kernel))
2496        // Match the initrd compression to the guest kernel's RD_* set
2497        // (from the config cached beside the image; LZ4 when absent).
2498        .initrd_compression(cache::initrd_compression_for_image(&kernel))
2499        .init_binary(&payload)
2500        .topology(vmm::Topology::new(numa_nodes, llcs, cores, threads))
2501        .cmdline(&cmdline)
2502        .include_files(owned_includes)
2503        .busybox(Some(busybox_bytes))
2504        .dmesg(dmesg)
2505        .no_perf_mode(no_perf_mode)
2506        .performance_mode(performance_mode)
2507        .sched_enable_cmds(sched_enable_cmds)
2508        .sched_disable_cmds(sched_disable_cmds);
2509
2510    #[cfg(feature = "wprof")]
2511    {
2512        builder = builder.wprof(wprof_config);
2513    }
2514
2515    if let Some(cmd) = exec {
2516        // exec_timeout bounds the payload's wall-clock (panic-less hang
2517        // guard); only meaningful in exec mode, so set it alongside.
2518        builder = builder.exec_cmd(cmd).exec_timeout(exec_timeout);
2519    }
2520
2521    if let Some(d) = disk {
2522        builder = builder.disk(d);
2523    }
2524
2525    // Shell-mode initramfs (busybox, operator includes, and wprof
2526    // when the `wprof` feature is enabled) can exceed a test's
2527    // declared `memory_mib`. Treat the caller's value as a FLOOR;
2528    // the deferred path takes the max of it and the actual
2529    // initramfs size.
2530    builder = match memory_mib {
2531        Some(mib) => builder.memory_deferred_min(mib),
2532        None => builder.memory_deferred(),
2533    };
2534
2535    let vm = builder.build()?;
2536
2537    vm.run_interactive()
2538}
2539
2540#[cfg(test)]
2541mod tests;