ktstr/test_support/runtime.rs
1//! Runtime configuration primitives shared by `eval` and `probe`.
2//!
3//! `eval` calls `probe::attempt_auto_repro` from its failure path,
4//! so items shared between the two siblings live here to avoid a
5//! circular import chain. All items are `pub(crate)` and remain
6//! internal to `test_support`.
7
8use std::os::unix::fs::PermissionsExt;
9use std::path::{Path, PathBuf};
10use std::sync::OnceLock;
11use std::time::Duration;
12
13use super::entry::KtstrTestEntry;
14
15/// Stable PathBuf for the process-owned config scratch directory.
16///
17/// Populated once by [`scratch_dir`] on first access. Kept in a
18/// separate `OnceLock` from the `TempDir` itself so the `atexit`
19/// cleanup handler can read the path through `extern "C"` without
20/// involving the `tempfile::TempDir` value (whose `Drop` would
21/// otherwise never run — see the "leak bound" note on
22/// [`scratch_dir`]).
23static SCRATCH_PATH: OnceLock<PathBuf> = OnceLock::new();
24
25/// Process-owned scratch directory for all inline-config tempfile
26/// writes — both [`config_content_parts`] (in-VM eval path) and
27/// [`crate::export::export_test`]'s `config_content_addition`
28/// (host-side .run packaging path).
29///
30/// Created lazily on first access via `tempfile::Builder` with
31/// explicit `0o700` mode (overrides the crate default of umask-
32/// restricted `0o777`-via-`mkdir(2)`, which on a standard
33/// `umask=0o022` host yields `0o755` and would expose directory
34/// listings + filename predictability to other uids). The
35/// directory is a random-suffixed subdirectory of
36/// `std::env::temp_dir()`, owned by the current uid.
37///
38/// Both call sites share this single directory because the
39/// security and leak-bound properties are identical for both
40/// purposes, and a single `OnceLock` + single `atexit` handler is
41/// simpler than maintaining parallel scratch dirs that diverge
42/// silently. Filenames are independently prefixed at each call
43/// site (`ktstr-config-{hash:016x}.json` for the eval path,
44/// `ktstr-export-config-{hash:016x}-{basename}` for the export
45/// path) so the two purposes can be visually distinguished inside
46/// the same directory.
47///
48/// Two properties matter:
49///
50/// 1. **Symlink defense.** /tmp is sticky-bit world-writable, so an
51/// attacker can pre-plant a symlink at the predictable content-
52/// addressed path and have us write to wherever it points. A
53/// per-process 0o700 subdirectory blocks every cross-uid access
54/// mode (read, list, write, traverse); only our process can
55/// create or replace files inside it, which eliminates the
56/// symlink-attack surface for the tempfile-write path.
57///
58/// 2. **Leak bound.** Rust does NOT run `Drop` impls on values
59/// stored in `static` slots at process exit — so the
60/// `tempfile::TempDir`'s built-in cleanup would never fire here.
61/// Instead, the path is registered with `libc::atexit`
62/// (POSIX-spec process-exit handler) so a clean exit
63/// (`exit(3)`, fall-off-`main`) triggers
64/// [`std::fs::remove_dir_all`] on the directory. Crash, abort,
65/// SIGKILL, or panic-`abort` skip the atexit handler and leak
66/// the directory; the residual is bounded by the number of
67/// such ungraceful exits and the directory contents are
68/// text-sized config files. The tempdir's random suffix
69/// prevents collisions across runs, so accumulated leak dirs
70/// don't interfere with future runs.
71pub(crate) fn scratch_dir() -> &'static Path {
72 SCRATCH_PATH
73 .get_or_init(|| {
74 let td = tempfile::Builder::new()
75 .prefix("ktstr-config-")
76 .permissions(std::fs::Permissions::from_mode(0o700))
77 .tempdir()
78 .expect("create ktstr config scratch directory");
79 // `keep()` consumes the TempDir without running its
80 // Drop's cleanup (it flips the cleanup flag and returns
81 // the bare PathBuf we own). The atexit registration
82 // below takes over cleanup responsibility.
83 let path = td.keep();
84 // SAFETY: `cleanup_scratch_dir` has the required
85 // `extern "C" fn()` signature that `libc::atexit`
86 // accepts. The `unsafe` block here is required because
87 // `libc::atexit` itself is an `unsafe extern "C"` FFI
88 // call (the callback signature itself is plain
89 // `extern "C" fn()`, not `unsafe`). Registering more
90 // than once is the caller's responsibility;
91 // `OnceLock::get_or_init` guarantees this runs exactly
92 // once per process.
93 let rc = unsafe { libc::atexit(cleanup_scratch_dir) };
94 assert_eq!(
95 rc, 0,
96 "libc::atexit registration for ktstr config scratch dir failed"
97 );
98 path
99 })
100 .as_path()
101}
102
103/// Process-exit handler registered via `libc::atexit` by
104/// [`scratch_dir`] on first init. Removes the scratch directory and
105/// every config file inside it. Errors are ignored — by the time
106/// this runs the process is exiting and there is nowhere to surface
107/// a failure (no `eprintln!` ordering guarantees from inside an
108/// atexit handler, and panicking would be unsound across the C ABI
109/// boundary).
110extern "C" fn cleanup_scratch_dir() {
111 if let Some(path) = SCRATCH_PATH.get() {
112 let _ = std::fs::remove_dir_all(path);
113 }
114}
115
116/// True when `RUST_BACKTRACE` is set to `"1"` or `"full"`.
117///
118/// Controls whether the full guest kernel console is appended to the
119/// `--- diagnostics ---` section of a failed test, and whether
120/// auto-repro forwards the repro VM's COM1/COM2 output to the host
121/// terminal in real time. The scheduler-log and sched_ext-dump
122/// sections of a failure are always emitted regardless of this flag.
123pub(crate) fn verbose() -> bool {
124 std::env::var("RUST_BACKTRACE")
125 .map(|v| v == "1" || v == "full")
126 .unwrap_or(false)
127}
128
129/// True when `KTSTR_NO_PERF_MODE` is set to a NON-EMPTY value.
130///
131/// Centralises the perf-mode-disabled check used by the dispatch
132/// gauntlet routes (`run_named_test`, `run_gauntlet_test`, and the
133/// verifier-cell listing route `list_verifier_cells_all`, all in
134/// `super::dispatch`) and the eval entry path
135/// (`super::eval::run_ktstr_test_inner_impl`). All four sites
136/// previously called `std::env::var("KTSTR_NO_PERF_MODE").is_ok()`
137/// directly, which returned true for `KTSTR_NO_PERF_MODE=` (empty
138/// string set, e.g. via `unset`/`set` interplay in CI shells, or a
139/// `--env KTSTR_NO_PERF_MODE` Docker pass-through with no value) —
140/// silently skipping every `performance_mode` test. Requiring a
141/// non-empty value matches operator intent ("set it to something to
142/// disable perf mode") and rejects the empty-string accident.
143///
144/// `cargo ktstr test --no-perf-mode` exports `KTSTR_NO_PERF_MODE=1`
145/// (a non-empty value), so the existing CLI surface is unaffected.
146pub(crate) fn no_perf_mode_active() -> bool {
147 std::env::var(crate::KTSTR_NO_PERF_MODE_ENV)
148 .map(|v| !v.is_empty())
149 .unwrap_or(false)
150}
151
152/// True when `KTSTR_BYPASS_LLC_LOCKS` is set to a NON-EMPTY value.
153///
154/// Centralises the bypass check used at 7 reader sites:
155/// `vmm/builder.rs:1199`, `cli/kernel_build/build.rs:102` +
156/// `:488` (the latter the inverse `!bypass_llc_locks_active()`
157/// form), `bin/cargo_ktstr/kernel/mod.rs:720`,
158/// `bin/cargo_ktstr/misc/shell.rs:181`, and `bin/ktstr.rs:652` +
159/// `:1267`. All sites previously spelled the same
160/// `.ok().is_some_and(|v| !v.is_empty())` inline; centralising
161/// eliminates the drift hazard and matches the
162/// `no_perf_mode_active` shape so the empty-string contract is
163/// uniformly enforced.
164///
165/// Set via `--bypass-llc-locks` CLI flag or
166/// `KTSTR_BYPASS_LLC_LOCKS=1` direct export. Empty
167/// (`KTSTR_BYPASS_LLC_LOCKS=` from a Docker `--env` pass-through
168/// without value) does NOT activate per the empty-as-unset
169/// contract — preventing a stray export from silently disabling
170/// LLC flock contention enforcement in CI.
171pub fn bypass_llc_locks_active() -> bool {
172 std::env::var(crate::KTSTR_BYPASS_LLC_LOCKS_ENV)
173 .ok()
174 .is_some_and(|v| !v.is_empty())
175}
176
177/// Effective no-perf-mode for a given test entry. The env override
178/// `KTSTR_NO_PERF_MODE` and the per-entry [`KtstrTestEntry::no_perf_mode`]
179/// attribute are OR'd: either source forces the no-perf path
180/// (cpuset/LLC locking still applies, but vCPU pinning, hugepages,
181/// NUMA mbind, RT scheduling, and KVM exit suppression are all
182/// skipped). The env override is the operator-level switch; the
183/// per-entry attribute lets a test author opt the test out
184/// permanently — e.g. tests that exercise wild virtual topologies
185/// the host hardware can't possibly satisfy under perf-mode pinning.
186pub(crate) fn no_perf_mode_for_entry(entry: &KtstrTestEntry) -> bool {
187 no_perf_mode_active() || entry.no_perf_mode
188}
189
190/// True when `KTSTR_PERF_ONLY` is set to a NON-EMPTY value.
191///
192/// Mirrors [`no_perf_mode_active`]'s empty-as-unset contract (see
193/// [`crate::KTSTR_PERF_ONLY_ENV`]): any non-empty value restricts the
194/// run to `performance_mode` tests, an empty value does not.
195/// Consulted at the dispatch named/gauntlet routes and the eval entry
196/// to skip non-perf entries before VM boot. Set by the mergebase
197/// perf-delta subcommand.
198pub(crate) fn perf_only_active() -> bool {
199 std::env::var(crate::KTSTR_PERF_ONLY_ENV)
200 .map(|v| !v.is_empty())
201 .unwrap_or(false)
202}
203
204/// Whether `perf_only_active()` requires SKIPPING this entry: perf-only
205/// mode is on and the entry is not a `performance_mode` test. A
206/// `performance_mode` entry is always kept (it is the selection
207/// target); every other entry is skipped so a perf-delta run measures
208/// only the perf-configured tests.
209pub(crate) fn perf_only_skips_entry(entry: &KtstrTestEntry) -> bool {
210 perf_only_active() && !entry.performance_mode
211}
212
213/// Derive initramfs archive path, host path, and guest path from a
214/// scheduler's static `config_file`. This scheduler-only projection is shared
215/// by ordinary test VMs and generated verifier cells so both launch the same
216/// declaration instead of silently dropping the verifier's config.
217pub(crate) fn scheduler_config_file_parts(
218 scheduler: &super::entry::Scheduler,
219) -> Option<(String, PathBuf, String)> {
220 let config_path = scheduler.config_file?;
221 let file_name = Path::new(config_path)
222 .file_name()
223 .and_then(|n| n.to_str())
224 .expect("config_file must have a valid filename");
225 let archive_path = format!("include-files/{file_name}");
226 let guest_path = format!("/include-files/{file_name}");
227 Some((archive_path, PathBuf::from(config_path), guest_path))
228}
229
230/// Entry-shaped compatibility wrapper for the ordinary test launch paths.
231pub(crate) fn config_file_parts(entry: &KtstrTestEntry) -> Option<(String, PathBuf, String)> {
232 scheduler_config_file_parts(entry.scheduler)
233}
234
235/// Stable u64 hash of arbitrary string content.
236///
237/// Used by the config-content tempfile path code, but suitable for
238/// any content-addressed naming site that needs determinism across
239/// rustc bumps.
240///
241/// Uses `siphasher::sip::SipHasher13::new_with_keys(0, 0)` rather
242/// than `std::collections::hash_map::DefaultHasher` because the std
243/// algorithm is explicitly unspecified across rustc versions (see
244/// workspace `Cargo.toml` for the dep-line rationale). The explicit
245/// `new_with_keys(0, 0)` form matches the project's other
246/// stable-hash sites (`src/test_support/sidecar/mod.rs`, `build.rs`)
247/// so a future audit of zero-keyed SipHasher13 callers finds every
248/// instance via one grep. Same content always produces the same u64
249/// across toolchain upgrades, so cached artifacts stay reproducible
250/// across machines and rustc bumps.
251pub(crate) fn content_hash(content: &str) -> u64 {
252 use std::hash::{Hash, Hasher};
253 let mut hasher = siphasher::sip::SipHasher13::new_with_keys(0, 0);
254 content.hash(&mut hasher);
255 hasher.finish()
256}
257
258/// Resolve inline config content into a temp file on disk, returning
259/// `(archive_path, host_path, guest_path, sched_args)` where
260/// `sched_args` are the CLI args derived from the scheduler's
261/// `config_file_def` arg template. Returns `None` when the entry has
262/// no `config_content`.
263pub(crate) fn config_content_parts(
264 entry: &KtstrTestEntry,
265) -> Option<(String, PathBuf, String, Vec<String>)> {
266 use std::io::Write as _;
267 let content = entry.config_content?;
268 let (arg_template, guest_path) = entry.scheduler.config_file_def?;
269 let archive_path = guest_path.trim_start_matches('/').to_string();
270 let hash = content_hash(content);
271 let dir = scratch_dir();
272 // Write to a uniquely-named scratch file, then atomic-rename to the
273 // canonical content-addressed path:
274 // - Scratch acquisition via `NamedTempFile::new_in` uses
275 // `mkstemp(3)` semantics: random suffix, opened O_EXCL so no
276 // pre-existing file can be subverted as the write target.
277 // - The atomic `persist` rename is the cross-thread / cross-process
278 // race fix. Two writers of the same content race their renames
279 // to the canonical path; the last writer wins, but since `hash`
280 // is content-addressed both wrote byte-identical content, so the
281 // winner's bytes match the loser's. No torn writes are possible
282 // because `rename(2)` is atomic at the inode level — readers
283 // either see the old inode or the new one, never a partial blend.
284 // - On panic between `new_in` and `persist`, NamedTempFile's `Drop`
285 // unlinks the scratch file. No `/tmp` leak from in-process aborts.
286 let canonical = dir.join(format!("ktstr-config-{hash:016x}.json"));
287 let mut scratch =
288 tempfile::NamedTempFile::new_in(dir).expect("create ktstr config scratch file");
289 scratch
290 .as_file_mut()
291 .write_all(content.as_bytes())
292 .expect("write ktstr config content to scratch");
293 scratch
294 .persist(&canonical)
295 .expect("atomic-rename ktstr config scratch to canonical path");
296 let expanded = arg_template.replace("{file}", guest_path);
297 let sched_args: Vec<String> = expanded.split_whitespace().map(|s| s.to_string()).collect();
298 Some((archive_path, canonical, guest_path.to_string(), sched_args))
299}
300
301/// Build the shared `cmdline=` string appended to every ktstr_test
302/// guest boot. Per-scheduler sysctls, per-scheduler kargs,
303/// `RUST_BACKTRACE` / `RUST_LOG` propagation, and the host-resolved
304/// `KTSTR_SIDECAR_DIR` so the guest's `sidecar_dir()` returns the
305/// SAME path the host's freeze coordinator writes to. Without that
306/// propagation, host and guest each compute the run directory
307/// independently — the host walks `gix::discover` from a real
308/// workspace cwd and produces `{kernel}-{commit}` whereas the
309/// guest's cwd is `/` (no git repo, no kernel env), yielding the
310/// `unknown-unknown` fallback. Anything the two VM-launch sites
311/// (`run_ktstr_test_inner` and `attempt_auto_repro`) previously
312/// re-implemented side-by-side lives here.
313/// Ordered guest-kernel cmdline tokens owned by a scheduler declaration.
314///
315/// Keep this projection independent of `KtstrTestEntry`: generated verifier
316/// cells have a scheduler but no test entry, and booting them without these
317/// tokens can change scheduler startup, BPF rodata, and verifier instruction
318/// counts. Sysctls precede raw kargs exactly as on the ordinary test path.
319pub(crate) fn scheduler_cmdline_tokens(scheduler: &super::entry::Scheduler) -> Vec<String> {
320 let mut parts = Vec::new();
321 for s in scheduler.sysctls {
322 parts.push(format!("sysctl.{}={}", s.key(), s.value()));
323 }
324 for &karg in scheduler.kargs {
325 parts.push(karg.to_string());
326 }
327 parts
328}
329
330fn build_cmdline_extra_with_probe_dump_gate(
331 entry: &KtstrTestEntry,
332 include_probe_dump_gate: bool,
333) -> String {
334 let mut parts = scheduler_cmdline_tokens(entry.scheduler);
335 // Framework-owned readiness authority. Scheduler kargs are otherwise
336 // passed through verbatim, but they may neither arm nor disarm this
337 // watchdog-accounting protocol: only the typed test-entry field decides
338 // whether the primary VM emits the exact `=1` token. This also prevents
339 // auto-repro from inheriting a raw scheduler-provided gate.
340 parts.retain(|part| {
341 part != "KTSTR_AWAIT_PROBE_DUMP_READY" && !part.starts_with("KTSTR_AWAIT_PROBE_DUMP_READY=")
342 });
343 // Per-test KASLR opt-out (see `KtstrTestEntry.kaslr` doc). The base
344 // cmdline `base_guest_cmdline` at `src/vmm/setup/mod.rs` does NOT
345 // inject `nokaslr` by default — KASLR is on. A test that needs determinism sets `kaslr = false` in
346 // its `#[ktstr_test]` attribute; that lands the token here, where it
347 // composes with any operator-supplied `Scheduler::kargs(&["nokaslr"])`
348 // above (kernel parses the flag as a bool; duplicates are harmless).
349 // Mirrored guest-side by `vmm::rust_init::create_cgroup_parent_from_sched_args`
350 // and `monitor::symbols::resolve_page_offset`, both of which handle the
351 // `nokaslr` case via the live-publisher fall back to `DEFAULT_PAGE_OFFSET`.
352 if !entry.kaslr {
353 parts.push("nokaslr".to_string());
354 }
355 // Periodic-capture window anchoring: a run that declares periodic
356 // captures gates its FIRST ScenarioStart (which opens the capture
357 // window) on the host's periodic-prereqs-ready signal, so the
358 // window opens over the live workload with the full declared
359 // duration instead of racing the KASLR publish (see
360 // `vmm::rust_init` Phase 5 and `SIGNAL_PERIODIC_READY`). Only
361 // periodic runs pay the wait; non-periodic runs never see the flag.
362 if entry.num_snapshots > 0 {
363 parts.push("KTSTR_AWAIT_PERIODIC_READY=1".to_string());
364 }
365 // Diagnostic scheduler-start gate: only explicitly opted-in tests
366 // pay the host's full probe-counter decode and guest wait. The
367 // host publishes the matching edge only after the exact dump
368 // reader succeeds, so scheduler-relative fault timers start with
369 // the diagnostic substrate already readable.
370 if include_probe_dump_gate && entry.probe_dump_ready_gate {
371 parts.push("KTSTR_AWAIT_PROBE_DUMP_READY=1".to_string());
372 }
373 if let Ok(bt) = std::env::var("RUST_BACKTRACE") {
374 parts.push(format!("RUST_BACKTRACE={bt}"));
375 }
376 if let Ok(log) = std::env::var("RUST_LOG") {
377 parts.push(format!("RUST_LOG={log}"));
378 }
379 // Propagate the host-resolved sidecar dir so the guest scenario
380 // computes the same path the host's freeze coordinator wrote to
381 // (e.g. when a test reads `sidecar_dir().join("foo.json")` from
382 // inside the guest, the path matches the host's writer site).
383 // The host resolves via the OnceLock-cached project commit walk
384 // from the workspace cwd; the guest's cwd is `/` and would
385 // otherwise fall back to `unknown-unknown`. Sidecar dir paths
386 // are filesystem-safe ASCII (kernel version + 7-char hex
387 // commit, optional `-dirty` suffix), so the cmdline-as-token
388 // shape is sound — no escaping needed for whitespace.
389 //
390 // Absolutize via `current_dir().join()` when the resolved path
391 // is relative (the default-branch shape:
392 // `target/ktstr/{kernel}-{commit}` against the host cwd). The
393 // guest's cwd is `/`, so a relative token would resolve there
394 // instead of at the host's workspace root — the propagation
395 // must carry the FULL absolute path so the guest's
396 // `sidecar_dir()` reports the same string the host's writer
397 // site used. Falls back to the raw resolved path when the cwd
398 // probe fails (extremely rare; happens only when the process's
399 // cwd was rmdir'd while alive — a metadata probe has no
400 // recourse, leave the path as-is).
401 let resolved = super::sidecar::sidecar_dir();
402 let absolute = if resolved.is_absolute() {
403 resolved
404 } else {
405 std::env::current_dir()
406 .map(|cwd| cwd.join(&resolved))
407 .unwrap_or(resolved)
408 };
409 if let Some(s) = absolute.to_str() {
410 parts.push(format!("KTSTR_SIDECAR_DIR={s}"));
411 }
412 parts.join(" ")
413}
414
415/// Build the primary VM's cmdline additions.
416///
417/// An explicitly opted-in primary carries the probe-dump readiness gate. Its
418/// guest args also carry the matching minimal probe request; see
419/// `append_primary_probe_dump_arg`.
420pub(crate) fn build_cmdline_extra(entry: &KtstrTestEntry) -> String {
421 build_cmdline_extra_with_probe_dump_gate(entry, true)
422}
423
424/// Build an auto-repro VM's cmdline additions without primary-only launch
425/// gates.
426///
427/// Stall auto-repro intentionally skips probe attachment, so inheriting a
428/// primary cell's probe-dump gate would make guest init wait for an edge the
429/// host can never publish.
430pub(crate) fn build_auto_repro_cmdline_extra(entry: &KtstrTestEntry) -> String {
431 build_cmdline_extra_with_probe_dump_gate(entry, false)
432}
433
434#[cfg(feature = "wprof")]
435pub(crate) fn attach_wprof_if_requested(
436 builder: crate::vmm::KtstrVmBuilder,
437 entry: &KtstrTestEntry,
438 label: &'static str,
439) -> anyhow::Result<crate::vmm::KtstrVmBuilder> {
440 if !entry.wprof {
441 return Ok(builder);
442 }
443 let mut config = crate::vmm::wprof::WprofConfig::from_env().map_err(|e| {
444 anyhow::anyhow!(
445 "ktstr_test: {label}: wprof requested by \
446 #[ktstr_test(wprof)] but WprofConfig::from_env failed: \
447 {e:#}. Ensure cargo-ktstr's install_env exported \
448 KTSTR_WPROF_PATH and the path is readable."
449 )
450 })?;
451 if let Some(custom_args) = entry.wprof_args {
452 config.args = custom_args.split_whitespace().map(String::from).collect();
453 }
454 Ok(builder.wprof(Some(config)))
455}
456
457/// Per-cpu memory-scaling core shared by every VM sizing site.
458///
459/// Returns `(cpus * 64).max(256)` — 64 MiB per vCPU, floored at
460/// 256 MiB. 64 MiB/cpu matches `derive_test_memory_mib`'s established
461/// scaling (it was cut from 256 to 64 MiB/cpu when the compressed
462/// initramfs landed and dropped peak guest memory; commit 5b6063a0);
463/// no per-cpu budget beyond that heuristic is documented.
464///
465/// The returned value is a LOWER BOUND: every call site feeds it to
466/// `.memory_deferred_min(mib)`, which raises the actual allocation to
467/// fit the real initramfs, so the final boot memory may exceed this.
468pub(crate) fn cpu_scaled_memory_mib(cpus: u32) -> u32 {
469 checked_cpu_scaled_memory_mib(cpus)
470 .expect("validated live topology overflows the 64 MiB/vCPU memory floor")
471}
472
473/// Fallible scalar form used when decoding topology dimensions from an ELF.
474pub(crate) fn checked_cpu_scaled_memory_mib(cpus: u32) -> Option<u32> {
475 cpus.checked_mul(64).map(|scaled| scaled.max(256))
476}
477
478/// Memory floor for one verifier topology preset.
479///
480/// Verifier VMs use deferred sizing, so the actual initramfs budget may raise
481/// this floor. The preset budget caps only the topology-derived CPU scaling:
482/// a 252-vCPU synthetic topology must not advertise 16 GiB merely because it
483/// has many vCPUs when the preset explicitly budgets 4 GiB. Small presets keep
484/// the ordinary 64 MiB/vCPU floor.
485pub(crate) fn verifier_preset_memory_min_mib(cpus: u32, preset_memory_mib: usize) -> u32 {
486 checked_verifier_preset_memory_min_mib(cpus, preset_memory_mib)
487 .expect("validated live verifier topology overflows the 64 MiB/vCPU memory floor")
488}
489
490/// Fallible verifier-memory projection for topology data decoded from an ELF.
491pub(crate) fn checked_verifier_preset_memory_min_mib(
492 cpus: u32,
493 preset_memory_mib: usize,
494) -> Option<u32> {
495 let preset_cap = u32::try_from(preset_memory_mib).unwrap_or(u32::MAX);
496 checked_cpu_scaled_memory_mib(cpus).map(|scaled| scaled.min(preset_cap))
497}
498
499/// wprof BPF ringbuf sizing baked into `WprofConfig::default_args`.
500///
501/// wprof allocates `WPROF_DEFAULT_RINGBUF_CNT` BPF ring buffers, each
502/// `--ringbuf-size` KiB rounded up to a power-of-two byte size; the
503/// tracer faults the whole arena in on capture, so guest RAM must
504/// cover it. These two constants are the single source of truth:
505/// `crate::vmm::wprof::WprofConfig::default_args` renders them into
506/// the `--ringbuf-size=`/`--ringbuf-cnt=` flags AND
507/// [`WPROF_MIN_MEMORY_MIB`] derives the guest-memory floor from them,
508/// so changing the sizing here moves the flags and the floor together.
509///
510/// The default is deliberately minimal — a single 16 MiB ring buffer,
511/// which is wprof's own per-buffer default (`DEFAULT_RINGBUF_SZ`) and
512/// comfortably holds the short sched-event captures ktstr's wprof
513/// tests run. ktstr only tests that wprof writes valid data
514/// end-to-end; oversizing merely inflates the per-cell fault-in cost.
515/// Larger captures pass their own `#[ktstr_test(wprof_args = "...")]`
516/// and, if the resulting arena exceeds the guest's normal memory,
517/// their own `memory_mib`.
518pub(crate) const WPROF_DEFAULT_RINGBUF_SIZE_KB: u32 = 16 * 1024;
519pub(crate) const WPROF_DEFAULT_RINGBUF_CNT: u32 = 1;
520
521/// Guest-memory floor (MiB) for a stamped wprof attachment, derived
522/// from the default ringbuf arena above.
523///
524/// Always compiled because the cargo-ktstr admission runner reads a
525/// stamped wprof bit from an ELF built with a different feature set
526/// than its own, so this projection cannot be `wprof`-gated. The
527/// public wprof API remains feature-gated and aliases this value.
528///
529/// At the minimal default the arena (16 MiB) sits below the universal
530/// 256 MiB memory floor from [`cpu_scaled_memory_mib`], so this floor
531/// is subsumed and never bumps a real VM; it re-engages only if the
532/// default ringbuf sizing above ever grows the arena past that floor.
533pub(crate) const WPROF_MIN_MEMORY_MIB: u32 = {
534 let per_rb_bytes = wprof_next_pow2_u64(WPROF_DEFAULT_RINGBUF_SIZE_KB as u64 * 1024);
535 let arena_bytes = per_rb_bytes * WPROF_DEFAULT_RINGBUF_CNT as u64;
536 (arena_bytes / (1024 * 1024)) as u32
537};
538
539/// Round `n` up to the next power of two, mirroring wprof's
540/// `round_pow_of_2` on the ringbuf byte size. `const fn` so the
541/// memory floor is a compile-time constant.
542const fn wprof_next_pow2_u64(n: u64) -> u64 {
543 let mut p: u64 = 1;
544 while p < n {
545 p <<= 1;
546 }
547 p
548}
549
550/// Apply the feature-independent memory floor encoded by a stamped wprof bit.
551pub(crate) fn apply_wprof_memory_floor(raw_mib: u32, wprof: bool) -> u32 {
552 if wprof && raw_mib < WPROF_MIN_MEMORY_MIB {
553 WPROF_MIN_MEMORY_MIB
554 } else {
555 raw_mib
556 }
557}
558
559/// Compute the exact deferred-memory floor from admission-stamp scalars.
560///
561/// This is the process-independent core of [`derive_test_memory_mib`]. The
562/// pre-exec target runner has only the final ELF stamp, not a live
563/// [`KtstrTestEntry`], and must publish the same lower bound before it starts
564/// the heavyweight test process. Keeping the scalar projection here prevents
565/// admission and VM construction from acquiring different memory weights.
566pub(crate) fn derive_test_memory_min_mib(cpus: u32, declared_memory_mib: u32, wprof: bool) -> u32 {
567 checked_derive_test_memory_min_mib(cpus, declared_memory_mib, wprof)
568 .expect("validated live topology overflows the 64 MiB/vCPU memory floor")
569}
570
571/// Fallible admission-memory projection for topology data decoded from an ELF.
572pub(crate) fn checked_derive_test_memory_min_mib(
573 cpus: u32,
574 declared_memory_mib: u32,
575 wprof: bool,
576) -> Option<u32> {
577 let raw = checked_cpu_scaled_memory_mib(cpus)?.max(declared_memory_mib);
578 Some(apply_wprof_memory_floor(raw, wprof))
579}
580
581/// Derive the test VM's memory floor from a CPU count + entry.
582///
583/// Returns `max(cpu_scaled_memory_mib(cpus), entry.memory_mib)`. When
584/// `entry.wprof` is true, bumps to the feature-independent stamped wprof
585/// memory floor if below it. The tracer attachment itself remains gated by
586/// the `wprof` feature.
587///
588/// The returned value is the LOWER BOUND on guest memory; the
589/// VM builder ultimately uses `.memory_deferred_min(mib)` which
590/// also accounts for the initramfs size, so the final boot memory
591/// may exceed this value.
592pub(crate) fn derive_test_memory_mib(cpus: u32, entry: &KtstrTestEntry) -> u32 {
593 let memory_min_mib = derive_test_memory_min_mib(cpus, entry.memory_mib, entry.wprof);
594 #[cfg(feature = "wprof")]
595 {
596 use crate::vmm::wprof::WPROF_MIN_MEMORY_MIB;
597 let raw = cpu_scaled_memory_mib(cpus).max(entry.memory_mib);
598 if memory_min_mib != raw {
599 tracing::info!(
600 test = %entry.name,
601 requested_mib = raw,
602 floored_mib = WPROF_MIN_MEMORY_MIB,
603 "wprof enabled; memory_mib floored to \
604 WPROF_MIN_MEMORY_MIB"
605 );
606 }
607 }
608 memory_min_mib
609}
610
611/// Resolve the VM topology and memory size from an optional
612/// TopoOverride.
613///
614/// Returns `(topology, memory_mib)` where `topology` is the
615/// `vmm::topology::Topology` passed to the VM builder and `memory_mib`
616/// is the LOWER BOUND on guest memory (the builder's
617/// `.memory_deferred_min(mib)` may raise the actual allocation
618/// to fit the initramfs). When `topo` is `Some`, both come from
619/// the override and the memory is honored verbatim (per the
620/// override-is-verbatim contract — see `topo.rs:42-44`). When
621/// `topo` is `None`, the topology comes from `entry.topology` and
622/// memory is derived by [`derive_test_memory_mib`]. Shared with
623/// `attempt_auto_repro` so the repro VM always sizes memory the
624/// same way as the first VM — reproducibility requires identical
625/// topology, including the wprof floor when applicable.
626///
627/// When the `wprof` feature is enabled and `entry.wprof` is true,
628/// a TopoOverride with memory_mib below the wprof floor triggers
629/// a warn-level log but is still honored verbatim.
630pub(crate) fn resolve_vm_topology(
631 entry: &KtstrTestEntry,
632 topo: Option<&super::topo::TopoOverride>,
633) -> (crate::vmm::topology::Topology, u32) {
634 match topo {
635 Some(t) => {
636 #[cfg(feature = "wprof")]
637 if entry.wprof && t.memory_mib < crate::vmm::wprof::WPROF_MIN_MEMORY_MIB {
638 tracing::warn!(
639 test = %entry.name,
640 override_mib = t.memory_mib,
641 wprof_min_mib = crate::vmm::wprof::WPROF_MIN_MEMORY_MIB,
642 "wprof enabled with TopoOverride.memory_mib below \
643 WPROF_MIN_MEMORY_MIB; honoring the override per the \
644 override-is-verbatim contract, but wprof may OOM-kill \
645 mid-run"
646 );
647 }
648 (crate::vmm::topology::Topology::from(t), t.memory_mib)
649 }
650 None => {
651 let cpus = entry.topology.total_cpus();
652 let mem = derive_test_memory_mib(cpus, entry);
653 (entry.topology, mem)
654 }
655 }
656}
657
658/// Append per-scheduler `sched_args` entries shared by both VM-launch
659/// paths: `--config <guest_path>` if the scheduler declared one, the
660/// cgroup-parent switch, the scheduler's own fixed args, and
661/// per-entry extra args. Active-flag dispatch and probe-specific args
662/// remain at the call site because they differ between the paths.
663///
664/// The caller owns the `include_files` binding on the builder;
665/// `config_file_parts` and the guest-path push are returned separately
666/// so the caller decides whether to attach include files (production
667/// does, probe-only repro pipelines that already pass `include_files`
668/// can skip it).
669/// Concrete absolute-path example used by the panic messages that
670/// reject malformed `--cell-parent-cgroup` values — names the
671/// scheduler's declared default when one exists, falls back to a
672/// canonical `/ktstr` literal otherwise. The operator gets a
673/// copy-pasteable shape regardless of whether the scheduler is
674/// cell-aware. Centralised so both rejection arms (Value-invalid and
675/// MissingValue) display the same example.
676fn cgroup_parent_example(entry: &KtstrTestEntry) -> String {
677 entry
678 .scheduler
679 .cgroup_parent
680 .map(|p| p.as_str().to_string())
681 .unwrap_or_else(|| "/ktstr".to_string())
682}
683
684pub(crate) fn append_base_sched_args(entry: &KtstrTestEntry, args: &mut Vec<String>) {
685 // Fail-fast on a malformed user-supplied `--cell-parent-cgroup`
686 // value before the auto-inject branch. The host-side consumer
687 // `resolve_cgroup_root` (defined in `test_support::args`, used by
688 // the probe/setup path at `probe.rs::build_dispatch_ctx_parts`)
689 // interpolates the value into a
690 // `/sys/fs/cgroup{path}` literal and hands the result to
691 // `CgroupManager::new`, which has NO host-root guard — any path
692 // that doesn't start with `/` lands inside the host cgroup root
693 // (e.g. `""` → `/sys/fs/cgroup`, `"my_test"` →
694 // `/sys/fs/cgroupmy_test`) and corrupts unrelated cgroup state
695 // when subsequent `cgroups.setup(...)` calls run. The guest-side
696 // sibling `vmm::rust_init::create_cgroup_parent_from_sched_args`
697 // happens to be safe-by-coincidence for the empty case because
698 // `enable_subtree_controllers_to` early-returns when leaf equals
699 // the cgroup root — but probe.rs has no such gate, so the host
700 // fail-fast is what actually protects against corruption.
701 //
702 // The check is universal — independent of whether the scheduler
703 // declares a default `cgroup_parent` — because both routes
704 // (`extra_sched_args` from the test author, `sched_args` from
705 // the scheduler def) flow through the same parse + chain below,
706 // and the corruption risk is identical regardless of who
707 // supplied the bad value. Operator sees the message at test
708 // setup time, before any cgroup ops run.
709 match super::args::parse_cell_parent_cgroup(
710 entry
711 .scheduler
712 .sched_args
713 .iter()
714 .chain(entry.extra_sched_args.iter())
715 .copied(),
716 ) {
717 super::args::CellParentCgroupArg::Value(path)
718 if !super::args::cell_parent_path_is_valid(path) =>
719 {
720 let example = cgroup_parent_example(entry);
721 let mut fixes = format!(
722 "supply an absolute path under `/` with at least one non-`.`/`..` \
723 segment (e.g. `{example}`) for the per-test cgroup root"
724 );
725 if let Some(default) = entry.scheduler.cgroup_parent {
726 fixes.push_str(&format!(
727 " or omit the flag entirely (the framework will auto-inject \
728 the scheduler's default `cgroup_parent = {default}`)"
729 ));
730 }
731 panic!(
732 "test `{}` supplies `--cell-parent-cgroup` with a value `{:?}` \
733 (via `extra_sched_args` on the test or `sched_args` in the \
734 scheduler def) that does not start with `/`, is `/` alone, or \
735 contains `.`/`..` segments that normalize back to the host \
736 cgroup root; {fixes}. Empty, bare `/`, relative, or paths \
737 like `/.`, `/foo/..`, `/./bar/..` all resolve to a path \
738 equal to or inside `/sys/fs/cgroup` (e.g. empty → \
739 `/sys/fs/cgroup`, `/` → `/sys/fs/cgroup/`, `/.` → \
740 `/sys/fs/cgroup` after canonicalization) and corrupt \
741 unrelated cgroup state when the probe-side `CgroupManager` \
742 operates on the resolved path. This gate mirrors the \
743 const-eval check in `CgroupPath::new` so runtime values \
744 share the validation contract that compile-time \
745 declarations already pass.",
746 entry.name, path,
747 );
748 }
749 super::args::CellParentCgroupArg::MissingValue => {
750 let example = cgroup_parent_example(entry);
751 let mut fixes = format!(
752 "either remove the bare `--cell-parent-cgroup` and let the \
753 framework auto-inject the scheduler's default (when one is \
754 declared), or supply a value (e.g. `--cell-parent-cgroup={example}` \
755 in combined form, or `--cell-parent-cgroup` followed by an \
756 absolute path in two-token form)"
757 );
758 if entry.scheduler.cgroup_parent.is_none() {
759 fixes.push_str(
760 "; the scheduler in this test declares no default \
761 `cgroup_parent`, so an absolute-path value is required",
762 );
763 }
764 panic!(
765 "test `{}` supplies a bare `--cell-parent-cgroup` (via \
766 `extra_sched_args` on the test or `sched_args` in the \
767 scheduler def) with no following value; {fixes}. The \
768 framework intercepts this here because letting it through \
769 would silently combine with the framework's auto-inject \
770 (when a default exists) and trip clap's `cannot be used \
771 multiple times` diagnostic — a confusing error that buries \
772 the actual missing-value mistake.",
773 entry.name,
774 );
775 }
776 super::args::CellParentCgroupArg::Value(_) => {
777 // User-supplied valid path — flows through the
778 // `args.extend(...)` calls below. Skip the auto-inject so
779 // clap doesn't reject the duplicate flag with `cannot be
780 // used multiple times`.
781 }
782 super::args::CellParentCgroupArg::Absent => {
783 // `cgroup_parent` controls the cgroup root where the
784 // framework places test cgroups (`resolve_cgroup_root`
785 // returns `/sys/fs/cgroup{cgroup_parent}` for guest
786 // CgroupManager). It does NOT auto-inject
787 // `--cell-parent-cgroup` into the scheduler's argv —
788 // cell-aware schedulers (scx_mitosis et al.) interpret
789 // that flag by enabling userspace_managed_cell_mode and
790 // starting an inotify-driven CellManager that can
791 // interfere with the host-side periodic-capture
792 // pipeline. If a scheduler genuinely needs
793 // `--cell-parent-cgroup`, the scheduler declaration's
794 // own `sched_args` array (or the per-test
795 // `extra_sched_args`) must include it explicitly. The
796 // guest-side `create_cgroup_parent_from_sched_args`
797 // mkdir + subtree-controller setup still fires when
798 // `--cell-parent-cgroup` is present in `/sched_args` —
799 // it's gated on the flag's presence, not on whether the
800 // framework injected it vs. the user added it manually.
801 }
802 }
803 args.extend(entry.scheduler.sched_args.iter().map(|s| s.to_string()));
804 args.extend(entry.extra_sched_args.iter().map(|s| s.to_string()));
805}
806
807/// Retry budget for the guest's `vmm::rust_init::send_sys_rdy_with_retry`
808/// loop. Boot-to-readiness wall time is a fixed base PLUS per-vCPU
809/// work: the virtio-console multiport handshake (DEVICE_READY →
810/// PORT_ADD → PORT_READY → PORT_OPEN per `drivers/char/virtio_console.c`)
811/// issues per-CPU work whose wall time grows roughly linearly with
812/// topology size, on top of a fixed device-enumeration / first-CPU
813/// cost. The budget is therefore ADDITIVE — `BASE_MS + vcpus *
814/// PER_VCPU_MS` — not `max(BASE, scaled)`.
815///
816/// The earlier `max` form left the per-vCPU term dead below ~67 vCPUs
817/// (since `vcpus * 150` only clears the 10 s floor at 67 vCPUs), so a
818/// 64-vCPU VM got the same 10 s budget as a 1-vCPU VM. Under host
819/// contention a 64-vCPU handshake was observed at ~10 s and timed out
820/// by ~8 ms — the disk-template gauntlet flake. The additive base
821/// gives every topology ~10 s of fixed headroom on top of its linear
822/// per-vCPU term (64 vCPUs → 19.6 s), so a slow handshake under load
823/// no longer races the floor.
824///
825/// Capped at 90 s as a sanity bound on a genuinely-stuck boot's
826/// guest-side retry loop — NOT to protect the host watchdog. The
827/// watchdog deadline IS derived from this budget ([`vm_boot_headroom`]
828/// feeds [`vm_timeout_from_entry`]), so the budget can never "blow" a
829/// deadline it defines; the old 30 s cap's stated rationale was
830/// inverted. That 30 s cap truncated the additive term above
831/// ~133 vCPUs — a 256-vCPU guest wants `10_000 + 256×150 = 48_400` ms
832/// but was clamped to 30_000 ms, starving the widest topologies of
833/// boot budget exactly where overcommit makes the boot slowest (the
834/// wide-SMP boot-timeout class). 90 s admits the full additive budget
835/// up to the 512-vCPU `MAX_VCPUS` (`10_000 + 512×150 = 86_800` ms);
836/// only pathological counts above 533 vCPUs clip.
837///
838/// The const-fn signature lets both the host (`vm_boot_headroom`,
839/// `vm_timeout_from_entry`) and the guest (`vmm::rust_init`) compute
840/// the same budget without trans-VM coordination — the guest reads
841/// its own vCPU count from `/sys/devices/system/cpu/online`. The guest
842/// uses this UN-scaled budget (it cannot read host overcommit); on an
843/// oversubscribed boot its `send_sys_rdy_with_retry` loop may exhaust
844/// and WARN, but that is non-fatal (the host monitor's `data_valid`
845/// gate keeps reads safe). The host's [`vm_timeout_from_entry`] is the
846/// Tier-3 dead-man deadline this budget feeds; it multiplies the
847/// headroom by a flat [`DEADMAN_HEADROOM_MULT`] and no longer scales by
848/// the host overcommit ratio — the progress watchdog's Tier-1/2 rules,
849/// not the wall deadline, now absorb an oversubscribed host.
850pub(crate) const fn sys_rdy_budget_ms(vcpus: u32) -> u64 {
851 const BASE_MS: u64 = 10_000;
852 const CAP_MS: u64 = 90_000;
853 const PER_VCPU_MS: u64 = 150;
854 let scaled = (vcpus as u64).saturating_mul(PER_VCPU_MS);
855 let total = BASE_MS.saturating_add(scaled);
856 if total > CAP_MS { CAP_MS } else { total }
857}
858
859/// Headroom for kernel init, scheduler attach, and BPF verifier time
860/// — the post-sys_rdy phase of guest startup. Distinct from
861/// [`sys_rdy_budget_ms`]'s base + per-vCPU budget (the pre-sys_rdy
862/// virtio-console handshake budget); the two add together to form
863/// the full [`vm_boot_headroom`].
864const KERNEL_INIT_HEADROOM_MS: u64 = 10_000;
865
866/// The authoritative boot allowance in milliseconds. Kept as a const
867/// integer helper so the wall-clock VM deadline and the progress
868/// watchdog's Boot CPU budget consume the same contract instead of
869/// maintaining independently calibrated width formulas.
870pub(crate) const fn vm_boot_headroom_ms(vcpus: u32) -> u64 {
871 KERNEL_INIT_HEADROOM_MS.saturating_add(sys_rdy_budget_ms(vcpus))
872}
873
874/// Total boot headroom: covers kernel init + scheduler attach + BPF
875/// verifier time ([`KERNEL_INIT_HEADROOM_MS`]) plus the guest's scaled
876/// `send_sys_rdy` retry loop ([`sys_rdy_budget_ms`]) before the
877/// workload phase begins. Scales with vCPU count so the host timeout
878/// doesn't fire while the guest is still inside its sys_rdy budget.
879pub(crate) fn vm_boot_headroom(vcpus: u32) -> Duration {
880 Duration::from_millis(vm_boot_headroom_ms(vcpus))
881}
882
883/// Per-phase CPU-time budget (nanoseconds) charged against a single
884/// lifecycle phase before the progress watchdog's Tier-1 rule
885/// (`vmm::freeze_coord::watchdog_step`) treats "CPU burned without
886/// progress" as a wedge. `phase` is the [`crate::monitor::LifecycleStage`]
887/// discriminant (Boot=0, Attach=1, Dispatch=2, Body=3, Teardown=4);
888/// this fn is deliberately phrased over the raw `u8` so it carries no
889/// dependency on that enum and stays testable in isolation.
890///
891/// Tier-1's evidence is the MAX per-vCPU CPU burned in-phase (the monitor's
892/// `max_vcpu_cpu_in_phase_ns`), not the SUM across vCPUs. A spinning wedge
893/// is one (or a few) hot thread(s), so the sound budget is what a SINGLE
894/// vCPU may legitimately burn in the phase — a per-vCPU-linear budget
895/// against a summed evidence was the wide-SMP false-kill bug (256 idle
896/// vCPUs summed ~141 s of diffuse background burn and crossed a 64 s
897/// budget with zero wedge).
898///
899/// Boot is the deliberate exception to otherwise width-independent
900/// per-vCPU budgets. The BSP serially enumerates and initializes every AP,
901/// so the busiest-vCPU signal contains legitimate O(vCPU-count) work even
902/// though the signal itself is a MAX rather than a SUM. Its budget reuses
903/// [`vm_boot_headroom_ms`], the existing semantic allowance that already
904/// governs kernel init, scheduler attach, BPF verification, and the
905/// vCPU-scaled sys-rdy handshake. This keeps one source of truth for a
906/// healthy boot instead of fitting another base-plus-slope formula to
907/// whichever wide distro image happened to fail last. The pthread
908/// currency widening is applied by the watchdog on top.
909///
910/// Every other phase stays flat because its legitimate busiest-vCPU work
911/// does not scale with guest width:
912/// - Attach (35 s): single-threaded BPF load + verifier time dominates
913/// and lands on one vCPU; host-side cold-BTF/vmlinux waits accrue NO
914/// guest CPU (the guest is blocked, not spinning), so even a cold
915/// parse under host-compile contention leaves the max per-vCPU burn
916/// well under this.
917/// - Dispatch (8 s): the probe's first-dispatch warm-up on the busiest
918/// worker vCPU; 8 s is generous for a single vCPU reaching first
919/// dispatch.
920/// - Body (`u64::MAX`): the workload phase has no CPU-time budget — a
921/// body test is *supposed* to burn CPU, so Tier-1 is structurally
922/// disabled here via this sentinel (the watchdog never charges a CPU
923/// budget it can exceed). Body wedges are caught by the existing
924/// deadline logic, not Tier-1.
925/// - Teardown (8 s): unwind / dump / VM-exit on the busiest vCPU.
926///
927/// Unknown phases (>4) return `u64::MAX` — an id this fn does not model
928/// must never be killed on a CPU budget it cannot justify. The pthread
929/// currency's 3/2 widening (`widen_budget_for_currency`) still applies on
930/// top of these in the watchdog.
931pub(crate) const fn phase_cpu_budget_ns(phase: u8, vcpus: u32) -> u64 {
932 const S_TO_NS: u64 = 1_000_000_000;
933 match phase {
934 // Boot: share the authoritative boot-headroom contract.
935 0 => vm_boot_headroom_ms(vcpus).saturating_mul(1_000_000),
936 // Attach
937 1 => 35u64.saturating_mul(S_TO_NS),
938 // Dispatch
939 2 => 8u64.saturating_mul(S_TO_NS),
940 // Body — Tier-1 off (see doc).
941 3 => u64::MAX,
942 // Teardown
943 4 => 8u64.saturating_mul(S_TO_NS),
944 // Unknown phase → never kill.
945 _ => u64::MAX,
946 }
947}
948
949/// Per-phase WALL-time backstop (nanoseconds) for the progress
950/// watchdog's Tier-2 rule (`vmm::freeze_coord::watchdog_step`): the
951/// fully-quiesced idle-wedge case where a phase has made no progress for
952/// this long *and* the guest shows no runnable demand. Distinct from the
953/// CPU budget above — this is wall clock, so it fires when a phase is
954/// stuck making no forward progress regardless of whether CPU is being
955/// burned (a spinning wedge is Tier-1's; a *silent* wedge is Tier-2's).
956///
957/// Each backstop is set STRICTLY ABOVE the existing wall budget that
958/// governs the same phase, so Tier-2 is a last-resort backstop that only
959/// fires after the phase's own in-band deadline has already had its
960/// chance — never a competing, earlier kill:
961/// - Boot: at least 45s and always 5s above
962/// [`vm_boot_headroom_ms`]. A genuinely silent boot (no epochs,
963/// no demand) past this is wedged, not merely slow.
964/// - Attach 40s: above [`COLD_BTF_PHASE1_BUDGET`] (30s) — the host's
965/// own cold-BTF accessor-build deadline — plus slack, so a slow but
966/// live BTF parse is never mistaken for a silent attach wedge.
967/// - Dispatch 35s: above the guest probe's `DISPATCH_DEADLINE_CAP`
968/// (30s, `vmm::rust_init::verifier_workload`), so the probe verdict
969/// — not Tier-2 — decides a live-but-slow dispatch.
970/// - Teardown 15s: a short backstop; teardown that makes no progress
971/// for this long with no demand is stuck unwinding.
972/// - Body (`u64::MAX`): the workload phase has no wall backstop —
973/// Tier-2 is structurally off for Body via this sentinel (a body
974/// test may legitimately sit quiescent; its deadline is the
975/// authoritative bound).
976///
977/// Unknown phases (>4) return `u64::MAX` — never kill on a wall backstop
978/// this fn does not model.
979pub(crate) const fn phase_wall_backstop_ns(phase: u8, vcpus: u32) -> u64 {
980 const S_TO_NS: u64 = 1_000_000_000;
981 const MS_TO_NS: u64 = 1_000_000;
982 let s = match phase {
983 // Boot is width-sensitive. Preserve the historical 45s floor for
984 // small guests while keeping Tier-2 strictly after the authoritative
985 // boot allowance for wide guests.
986 0 => {
987 let scaled_ms = vm_boot_headroom_ms(vcpus).saturating_add(5_000);
988 let backstop_ms = if scaled_ms > 45_000 {
989 scaled_ms
990 } else {
991 45_000
992 };
993 return backstop_ms.saturating_mul(MS_TO_NS);
994 }
995 // Attach — > COLD_BTF_PHASE1_BUDGET (30s).
996 1 => 40u64,
997 // Dispatch — > guest DISPATCH_DEADLINE_CAP (30s).
998 2 => 35u64,
999 // Body — Tier-2 off (see doc).
1000 3 => return u64::MAX,
1001 // Teardown
1002 4 => 15u64,
1003 // Unknown phase → never kill.
1004 _ => return u64::MAX,
1005 };
1006 s.saturating_mul(S_TO_NS)
1007}
1008
1009/// Worst-case host-side latency the guest's `wait_for_map_write` latch
1010/// blocks on before a `bpf_map_write` test's workload runs: the host
1011/// builds the BPF-map accessor (ELF + BTF parse + symbol HashMap, ~4 s
1012/// on a debug vmlinux per the freeze-coord accessor-init comment) in a
1013/// retry loop bounded by a 30 s `phase1_deadline`. Under heavy `-j16`
1014/// host-compile contention the parse scales and a cold vmlinux read adds
1015/// seconds, so the latch can block up to that deadline. Added to the
1016/// workload budget for any entry declaring a `bpf_map_write` — a
1017/// framework cost every such test pays, not a per-test concern the
1018/// author must remember to budget for.
1019const COLD_BTF_PHASE1_BUDGET: Duration = Duration::from_secs(30);
1020
1021/// Oversubscription ratio at or beyond which a default/no-perf (auto)
1022/// overcommit is SKIPPED rather than booted. Above it the host
1023/// time-slices the vCPU threads so heavily the boot cannot make forward
1024/// progress, so the dispatch
1025/// (`run_ktstr_test_inner_impl`) skips with a "host topology
1026/// insufficient" signal instead of hard-failing. Set above the 4× the
1027/// `cpu_budget` overcommit tests deliberately exercise (those carry an
1028/// explicit `cpu_budget`, so they are NOT auto-collapse and never skip
1029/// on this ratio) and far above the ~1.3× a 256-vCPU guest hits on a
1030/// 192-CPU CI runner — which therefore RUNS and validates wide-SMP boot
1031/// rather than skipping, so the boot invariant is never masked.
1032pub(crate) const OVERCOMMIT_SKIP_RATIO: f64 = 6.0;
1033
1034/// Flat multiplier on the vCPU-scaled [`vm_boot_headroom`] term of the
1035/// Tier-3 dead-man deadline ([`vm_timeout_from_entry`] and
1036/// [`verifier_vm_timeout`]). The approved ~2.5x rounded up to an
1037/// integer — integer math, and the extra generosity is free here.
1038///
1039/// This is NOT a timeout bump. The progress watchdog's Tier-1
1040/// (CPU-burned-without-progress) and Tier-2 (silent idle-wedge) rules in
1041/// `vmm::freeze_coord::watchdog_step` are the primary hang
1042/// detectors for INFRA phases: a wedge dies on those tiers inside a bounded
1043/// per-phase budget no matter how loose this deadline is. Tier-3 owns the
1044/// remaining degradation paths: dead monitoring, an inert cell, and an
1045/// active Body livelock after it burns the whole effective-deadline
1046/// busiest-vCPU budget. The CPU backstop, like Tier-1, stretches with host
1047/// starvation; no wall-clock oversub multiplier is needed. A flat generous
1048/// headroom factor therefore suffices for the deadline itself.
1049const DEADMAN_HEADROOM_MULT: u32 = 3;
1050
1051/// Stricter skip ratio for the `expect_auto_repro` chain. That inversion
1052/// boots a SECOND wide-SMP VM which must replay the forced failure and land
1053/// a shape-valid `.repro.wprof.pb` — a far more fragile path under host
1054/// time-slicing than a single boot: the repro VM's system-wide wprof
1055/// capture over hundreds of vCPUs stops reliably producing a transportable
1056/// trace once the host oversubscribes (the boots themselves still finish
1057/// inside the Tier-3 dead-man deadline; the trace transport is what breaks).
1058/// So this chain auto-skips well below the generic [`OVERCOMMIT_SKIP_RATIO`],
1059/// while single-VM wide-SMP BOOT tests keep running (and validating boot) up
1060/// to the generic cap. Tuned to sit between the ~1.3x a 256-vCPU guest hits
1061/// on the 192-CPU wide-SMP design-target runner (which still RUNS the
1062/// auto-repro hop, so it is validated there) and the ~2.7x of a 96-CPU host
1063/// (which skips cleanly instead of hard-failing — the "overcommit OR
1064/// auto-skip, never hard-fail" contract).
1065pub(crate) const EXPECT_AUTO_REPRO_SKIP_RATIO: f64 = 2.0;
1066
1067/// Host overcommit ratio for a `vcpus`-wide guest given the host's
1068/// allowed-CPU count and the test's optional explicit `cpu_budget`:
1069/// vCPUs divided by the host CPUs the vCPU threads actually land on.
1070/// With an explicit `cpu_budget` the threads collapse onto
1071/// `min(cpu_budget, allowed)` (the per-test cap); without one the
1072/// default/no-perf path collapses onto the whole allowed cpuset
1073/// (`no_perf_cpu_budget`'s `(vcpus + 1).min(allowed)` clamp when
1074/// `allowed < vcpus + 1`, else a fitting 1:1 pin). Under
1075/// `KTSTR_CARGO_TEST_MODE` the planner ignores the explicit budget and
1076/// masks to the full allowed cpuset, so with a `cpu_budget` the
1077/// returned ratio is an UPPER bound there (CI runs `cargo ktstr test`
1078/// with that mode OFF, where the budget IS enforced and the ratio is
1079/// exact). Floored at 1.0 (a fitting host is never under-subscribed) and
1080/// divide-by-zero-guarded (an unenumerable cpuset yields 1.0).
1081///
1082/// Feeds only the boot-or-skip gate ([`overcommit_skip_reason`]) and the
1083/// operator overcommit warning — NOT the Tier-3 dead-man deadline, which
1084/// no longer scales with this ratio (the progress watchdog's Tier-1/2
1085/// rules absorb a loaded host). Pure over `(vcpus, allowed_cpus,
1086/// cpu_budget)` so the skip boundary is unit-testable without reading the
1087/// host cpuset.
1088pub(crate) fn overcommit_ratio(vcpus: u32, allowed_cpus: usize, cpu_budget: Option<u32>) -> f64 {
1089 let allowed = allowed_cpus.max(1);
1090 let effective = match cpu_budget {
1091 Some(b) => (b as usize).min(allowed),
1092 None => allowed,
1093 }
1094 .max(1);
1095 (vcpus as f64 / effective as f64).max(1.0)
1096}
1097
1098/// Reason to auto-skip an over-oversubscribed default/no-perf run, or
1099/// `None` to run it. The default/no-perf path collapses the vCPU threads
1100/// onto the allowed cpuset (`build_overcommit_run_locks` /
1101/// `no_perf_cpu_budget`); at or beyond [`OVERCOMMIT_SKIP_RATIO`] the host
1102/// time-slices so hard the boot cannot make forward progress, so the
1103/// dispatch
1104/// (`run_ktstr_test_inner_impl`) skips with this reason — the "overcommit
1105/// OR auto-skip, never hard-fail" contract. Returns `None` (runs) for:
1106/// the fitting / mildly-oversubscribed case (< the ratio, e.g. a 256-vCPU
1107/// guest at ~1.3x on a 192-CPU CI runner, so wide-SMP boot is VALIDATED
1108/// there, never masked); an explicit `cpu_budget` (a deliberate
1109/// oversubscription opt-in for contention testing always runs, its deeper
1110/// ratio being the author's choice); and an empty (unenumerable) cpuset
1111/// (no ratio is computable, so the overcommit warning is the sole
1112/// signal). Pure over `(vcpus, allowed_cpus, cpu_budget)` so the skip
1113/// boundary is unit-testable without booting a VM.
1114pub(crate) fn overcommit_skip_reason(
1115 vcpus: u32,
1116 allowed_cpus: usize,
1117 cpu_budget: Option<u32>,
1118 expect_auto_repro: bool,
1119) -> Option<String> {
1120 if cpu_budget.is_some() || allowed_cpus == 0 {
1121 return None;
1122 }
1123 let oversub = overcommit_ratio(vcpus, allowed_cpus, None);
1124 // The two-VM expect_auto_repro inversion uses a much stricter cap
1125 // ([`EXPECT_AUTO_REPRO_SKIP_RATIO`]) than a single-VM boot test: its
1126 // repro-VM wprof-trace transport is fragile under time-slicing, so it
1127 // skips at an oversubscription a boot-only wide-SMP test still runs at.
1128 let skip_ratio = if expect_auto_repro {
1129 EXPECT_AUTO_REPRO_SKIP_RATIO
1130 } else {
1131 OVERCOMMIT_SKIP_RATIO
1132 };
1133 if oversub < skip_ratio {
1134 return None;
1135 }
1136 let chain = if expect_auto_repro {
1137 " for the expect_auto_repro inversion chain"
1138 } else {
1139 ""
1140 };
1141 Some(format!(
1142 "host topology insufficient: {vcpus} vCPUs auto-collapse onto \
1143 {allowed_cpus} allowed host CPUs = {oversub:.1}x oversubscription \
1144 (>= {skip_ratio:.0}x skip cap{chain}); widen the process cpuset \
1145 or shrink the guest topology"
1146 ))
1147}
1148
1149/// Derive the host-side VM timeout from the test entry's watchdog and
1150/// duration. This is the watchdog's TIER-3 dead-man's switch — the
1151/// generous wall-clock backstop, NOT the primary hang detector. The
1152/// primary detectors are the progress watchdog's Tier-1
1153/// (CPU-burned-without-progress) and Tier-2 (silent idle-wedge) rules in
1154/// `vmm::freeze_coord::watchdog_step`: a wedge dies on those
1155/// tiers inside a bounded per-phase budget. Tier-3 also owns a dead
1156/// monitor, an inert cell, and an active Body livelock after it consumes
1157/// the whole effective-deadline busiest-vCPU CPU budget; that last bound
1158/// remains dilation-immune because a starved cell accrues CPU slowly.
1159///
1160/// Shape: `base + vm_boot_headroom(booted_vcpus) * DEADMAN_HEADROOM_MULT`.
1161/// The vCPU-scaled boot headroom covers a slow boot on a large topology;
1162/// the flat [`DEADMAN_HEADROOM_MULT`] makes it generous. This is NOT a
1163/// timeout bump and does NOT scale with the host overcommit ratio — the
1164/// old oversub multiplier existed to stop wall-clock false-timeouts on a
1165/// loaded host, a job Tier-1/2 now own, so a flat generous factor
1166/// replaces it (and the overcommit-scaling machinery is retired from this
1167/// path). `base` is the guest's own workload/watchdog budget:
1168/// [`COLD_BTF_PHASE1_BUDGET`] is added when the entry declares a
1169/// `bpf_map_write` (the guest blocks on the host's cold-BTF accessor
1170/// build before the workload starts), and
1171/// [`crate::vmm::freeze_coord::WPROF_SHIP_GRACE`] when it declares
1172/// `wprof` (a crashing scheduler's late Phase-5 trace ship is held for
1173/// that window before teardown). The soft (reset) deadline rides this
1174/// Tier-3 value via `max(reset, hard_deadline)`.
1175///
1176/// `booted_vcpus` is the vCPU count of the topology the VM actually
1177/// boots (`resolve_vm_topology(entry, topo).0.total_cpus()`), NOT the
1178/// declared `entry.topology`: under a `TopoOverride` (gauntlet preset /
1179/// `--ktstr-topo`) they diverge, and the vCPU-scaled boot headroom must
1180/// scale to the topology that boots — otherwise the deadline is sized for
1181/// a smaller-than-booted preset.
1182pub(crate) fn vm_timeout_from_entry(
1183 entry: &super::entry::KtstrTestEntry,
1184 booted_vcpus: u32,
1185) -> Duration {
1186 let mut base = entry
1187 .watchdog_timeout
1188 .max(entry.duration)
1189 .max(Duration::from_secs(1));
1190 if !entry.bpf_map_write.is_empty() {
1191 base += COLD_BTF_PHASE1_BUDGET;
1192 }
1193 // A wprof entry's scheduler may crash; on an error-class exit the
1194 // freeze coordinator holds the VM open up to `WPROF_SHIP_GRACE` for
1195 // the guest's late Phase-5 wprof trace ship before killing. Add that
1196 // window to the host budget so a late crash's full ship grace fits
1197 // inside the watchdog deadline (mirrors COLD_BTF_PHASE1_BUDGET).
1198 if entry.wprof {
1199 base += crate::vmm::freeze_coord::WPROF_SHIP_GRACE;
1200 }
1201 base + vm_boot_headroom(booted_vcpus) * DEADMAN_HEADROOM_MULT
1202}
1203
1204/// Base host-side budget for a verifier sweep cell's guest lifecycle
1205/// past boot: scheduler spawn, BPF load/verify, attach gate, the
1206/// dispatch probe, and teardown. The boot phase is budgeted
1207/// separately by the vCPU-scaled dead-man headroom in
1208/// [`verifier_vm_timeout`], mirroring [`vm_timeout_from_entry`]'s
1209/// base-vs-headroom split.
1210pub(crate) const VERIFIER_BASE_TIMEOUT: Duration = Duration::from_secs(120);
1211
1212/// Post-attach budget for a verifier cell, wired into the builder's
1213/// `workload_duration` so the watchdog's scheduler-attach reset arms:
1214/// a cell whose boot ate most of the deadline still gets this much
1215/// wall time AFTER attach for the dispatch probe + teardown (the
1216/// reset is extend-only — `max(reset, hard_deadline)`). Sized above
1217/// the guest probe's `DISPATCH_DEADLINE_CAP` (30s, see
1218/// `vmm::rust_init::verifier_workload`) plus teardown/dump slack.
1219/// Before this, verifier cells passed no `workload_duration` at all,
1220/// which made the attach-reset dead code on the sweep path — the
1221/// watchdog dump always read `reset_armed_by=none`.
1222pub(crate) const VERIFIER_WORKLOAD_BUDGET: Duration = Duration::from_secs(60);
1223
1224/// Host-side VM timeout for a verifier sweep cell: the flat
1225/// [`VERIFIER_BASE_TIMEOUT`] plus the same vCPU-scaled dead-man boot
1226/// headroom the `#[ktstr_test]` path gets from [`vm_timeout_from_entry`]
1227/// — its Tier-3 backstop, not the primary hang detector (Tier-1/2 in
1228/// `vmm::freeze_coord::watchdog_step` own that). The sweep
1229/// previously hard-coded 120s with no headroom at all, so a
1230/// wide-topology cell (128 vCPUs) that boots fine but slowly under CI
1231/// concurrency was killed mid-attach — reported by the scx verifier
1232/// sweep as a VM timeout (now worded "hung with no confirmed scheduler
1233/// attach" for that shape).
1234pub(crate) fn verifier_vm_timeout(booted_vcpus: u32) -> Duration {
1235 VERIFIER_BASE_TIMEOUT + vm_boot_headroom(booted_vcpus) * DEADMAN_HEADROOM_MULT
1236}
1237
1238/// Configure the ktstr_test VM builder prefix shared by the main
1239/// test path ([`super::eval::run_ktstr_test_inner`]) and the
1240/// auto-repro path ([`super::probe::attempt_auto_repro`]).
1241///
1242/// Applies, in order: kernel, init binary, topology, memory floor,
1243/// guest cmdline, SHM size, guest argv, host-side timeout, perf-mode
1244/// disable flag, optional scheduler binary, every queued BPF map
1245/// write, and the scheduler watchdog timeout.
1246///
1247/// The caller owns the divergent tail. `run_ktstr_test_inner`
1248/// additionally wires `performance_mode`,
1249/// `sched_enable_cmds`/`sched_disable_cmds` for kernel-built
1250/// schedulers, and `monitor_thresholds`. `attempt_auto_repro`
1251/// additionally wires `include_files` plus base `sched_args`.
1252#[allow(clippy::too_many_arguments)]
1253pub(crate) fn build_vm_builder_base(
1254 entry: &KtstrTestEntry,
1255 kernel: &Path,
1256 ktstr_bin: &Path,
1257 scheduler: Option<&Path>,
1258 staged_schedulers: &[(String, std::path::PathBuf, Vec<String>)],
1259 vm_topology: crate::vmm::topology::Topology,
1260 memory_mib: u32,
1261 cmdline_extra: &str,
1262 guest_args: &[String],
1263 no_perf_mode: bool,
1264) -> crate::vmm::KtstrVmBuilder {
1265 // The base builder deliberately does NOT set
1266 // `failure_dump_path` — the per-VM target is caller-specific
1267 // (primary vs auto-repro). Stale-file pre-clear lives at the
1268 // dispatch sites (`test_support::eval` for primary;
1269 // `test_support::probe::attempt_auto_repro` for repro), not
1270 // inside the setter or this base call. The setter is pure
1271 // (no FS side effects); placing the pre-clear in the dispatch
1272 // layer prevents the auto-repro path's reuse of this base
1273 // builder from accidentally erasing the primary dump that
1274 // just landed.
1275 let mut builder = crate::vmm::KtstrVm::builder()
1276 .kernel(kernel)
1277 // Prebuilt distro kernels ship virtio as modules; embed the
1278 // ordered boot-module set from the cache entry beside the image
1279 // (empty for built kernels — a no-op).
1280 .kernel_modules(crate::cache::boot_modules_for_image(kernel))
1281 .initrd_compression(crate::cache::initrd_compression_for_image(kernel))
1282 .init_binary(ktstr_bin)
1283 .topology(vm_topology)
1284 .memory_deferred_min(memory_mib)
1285 .cmdline(cmdline_extra)
1286 .run_args(guest_args)
1287 .timeout(vm_timeout_from_entry(entry, vm_topology.total_cpus()))
1288 .workload_duration(entry.duration)
1289 .no_perf_mode(no_perf_mode);
1290
1291 // Per-test no-perf CPU budget override (#[ktstr_test(cpu_budget = N)]).
1292 // None leaves the builder's auto-size (vCPU count plus one service CPU,
1293 // clamped to the allowed cpuset) in place; only the no-perf path consumes it.
1294 if let Some(budget) = entry.cpu_budget {
1295 builder = builder.cpu_budget(budget);
1296 }
1297
1298 if let Some(sched_path) = scheduler {
1299 builder = builder.scheduler_binary(sched_path);
1300 }
1301
1302 // Push each pre-resolved staged scheduler into the builder's
1303 // staging set. Caller is responsible for running each entry
1304 // through resolve_scheduler so this fn stays
1305 // infallible (sibling to the boot-time `scheduler: Option<&Path>`
1306 // shape which is also caller-resolved). KernelBuiltin / Eevdf
1307 // staged entries (no binary to resolve) are skipped at the
1308 // caller side; only resolved (name, host_binary, sched_args)
1309 // tuples reach this loop.
1310 for (name, host_path, sched_args) in staged_schedulers {
1311 builder = builder.staged_scheduler(name.clone(), host_path.clone(), sched_args.clone());
1312 }
1313
1314 // Opt-in jemalloc-probe wiring. An integration test that needs
1315 // the probe (see `tests/jemalloc_probe_tests.rs`) sets
1316 // `KTSTR_JEMALLOC_PROBE_BINARY` to the absolute host path of
1317 // `ktstr-jemalloc-probe` via `#[ctor]` before the test harness
1318 // dispatches. When set, the probe is packed into every VM's
1319 // base initramfs; the init binary stays stripped because the
1320 // paired alloc-worker carries DWARF. Absent env var = existing
1321 // behavior (no probe).
1322 //
1323 // Required ctor shape in a new test file that needs the probe
1324 // in the guest — paste verbatim, adjust the two binary names.
1325 // Either ctor form works (ktstr re-exports both): the proc-macro
1326 // attribute shown below, or the declarative
1327 // `::ktstr::__private::ctor::declarative::ctor! { ... }` block
1328 // form (ktstr's own in-tree sites use the declarative form per
1329 // src/test_support/dispatch.rs).
1330 //
1331 // ```ignore
1332 // #[::ktstr::__private::ctor::ctor(unsafe, crate_path = ::ktstr::__private::ctor)]
1333 // fn set_probe_binary_env_var() {
1334 // // SAFETY: ctor runs before any `#[ktstr_test]` thread or
1335 // // probe thread spawns; glibc's `__environ` mutation is
1336 // // single-threaded here.
1337 // unsafe {
1338 // std::env::set_var(
1339 // ::ktstr::KTSTR_JEMALLOC_PROBE_BINARY_ENV,
1340 // env!("CARGO_BIN_EXE_ktstr-jemalloc-probe"),
1341 // );
1342 // std::env::set_var(
1343 // ::ktstr::KTSTR_JEMALLOC_ALLOC_WORKER_BINARY_ENV,
1344 // env!("CARGO_BIN_EXE_ktstr-jemalloc-alloc-worker"),
1345 // );
1346 // }
1347 // }
1348 // ```
1349 //
1350 // Declarative-form equivalent (no `crate_path = ` plumbing required
1351 // because the macro_rules! expansion resolves paths via `$crate`):
1352 //
1353 // ```ignore
1354 // ::ktstr::__private::ctor::declarative::ctor! {
1355 // #[ctor(unsafe)]
1356 // fn set_probe_binary_env_var() {
1357 // // SAFETY: same as proc-macro form above.
1358 // unsafe {
1359 // std::env::set_var(
1360 // ::ktstr::KTSTR_JEMALLOC_PROBE_BINARY_ENV,
1361 // env!("CARGO_BIN_EXE_ktstr-jemalloc-probe"),
1362 // );
1363 // std::env::set_var(
1364 // ::ktstr::KTSTR_JEMALLOC_ALLOC_WORKER_BINARY_ENV,
1365 // env!("CARGO_BIN_EXE_ktstr-jemalloc-alloc-worker"),
1366 // );
1367 // }
1368 // }
1369 // }
1370 // ```
1371 //
1372 // The `crate_path = ::ktstr::__private::ctor` argument is
1373 // non-negotiable: `#[ctor::ctor(unsafe)]` without the
1374 // re-export path panics at compile time because the `ctor`
1375 // crate is not listed in the test crate's direct deps. ktstr
1376 // re-exports `ctor` under `__private::ctor` exactly so test
1377 // authors do not need to add it themselves. ctor 1.0 also
1378 // mandates the `unsafe` marker as the first attribute
1379 // argument; bare `#[ctor::ctor]` no longer compiles.
1380 if let Ok(probe_path) = std::env::var(crate::KTSTR_JEMALLOC_PROBE_BINARY_ENV)
1381 && !probe_path.is_empty()
1382 {
1383 // Pack the probe binary into the guest initramfs at
1384 // `/bin/ktstr-jemalloc-probe`. Closed-loop probe tests run
1385 // the probe via `--pid <alloc_worker_pid>` against the
1386 // paired `ktstr-jemalloc-alloc-worker` target; DWARF comes
1387 // from the worker's own ELF, not the init's.
1388 builder = builder.jemalloc_probe_binary(std::path::PathBuf::from(probe_path));
1389 }
1390 if let Ok(worker_path) = std::env::var(crate::KTSTR_JEMALLOC_ALLOC_WORKER_BINARY_ENV)
1391 && !worker_path.is_empty()
1392 {
1393 // Pack the jemalloc-alloc-worker binary alongside the
1394 // probe. Only the cross-process closed-loop test sets
1395 // this; scheduler-only tests leave the env var unset and
1396 // skip the wiring.
1397 builder = builder.jemalloc_alloc_worker_binary(std::path::PathBuf::from(worker_path));
1398 }
1399
1400 for bpf_write in entry.bpf_map_write {
1401 builder = builder.bpf_map_write(
1402 bpf_write.map_name_suffix(),
1403 bpf_write.field(),
1404 bpf_write.value(),
1405 );
1406 }
1407
1408 for watch in entry.watch_bpf_maps {
1409 builder = builder.watch_bpf_map(
1410 watch.map_name_suffix(),
1411 watch.field(),
1412 watch.agg(),
1413 watch.label(),
1414 );
1415 }
1416
1417 if let Some(disk_cfg) = entry.disk.clone() {
1418 builder = builder.disk(disk_cfg);
1419 }
1420
1421 for net_cfg in entry.networks {
1422 builder = builder.network(*net_cfg);
1423 }
1424
1425 builder = builder.num_snapshots(entry.num_snapshots);
1426
1427 if let Some(root) = entry.workload_root_cgroup {
1428 builder = builder.workload_root_cgroup(root.as_str().to_string());
1429 }
1430 if let Some(parent) = entry.scheduler.cgroup_parent {
1431 builder = builder.scheduler_cgroup_parent(parent.as_str().to_string());
1432 }
1433
1434 builder.watchdog_timeout(entry.watchdog_timeout)
1435}
1436
1437#[cfg(test)]
1438mod tests {
1439 use super::super::entry::Scheduler;
1440 use super::super::test_helpers::{EnvVarGuard, lock_env};
1441 use super::*;
1442
1443 #[test]
1444 fn vm_timeout_from_entry_adds_cold_btf_budget_for_bpf_map_write() {
1445 use super::super::entry::{BpfMapWrite, KtstrTestEntry};
1446 static W: BpfMapWrite = BpfMapWrite::new(".bss", "crash", 0);
1447 static WS: &[&BpfMapWrite] = &[&W];
1448 let no_write = KtstrTestEntry {
1449 name: "no_write",
1450 ..KtstrTestEntry::DEFAULT
1451 };
1452 let with_write = KtstrTestEntry {
1453 name: "with_write",
1454 bpf_map_write: WS,
1455 ..KtstrTestEntry::DEFAULT
1456 };
1457 // The cold-BTF phase-1 budget is added to the workload base only
1458 // when the entry declares a host-side bpf_map_write; the delta
1459 // between an otherwise-identical pair is exactly that budget.
1460 assert_eq!(
1461 vm_timeout_from_entry(&with_write, with_write.topology.total_cpus()),
1462 vm_timeout_from_entry(&no_write, no_write.topology.total_cpus())
1463 + COLD_BTF_PHASE1_BUDGET,
1464 "bpf_map_write entries get the cold-BTF phase-1 budget added",
1465 );
1466 }
1467
1468 #[test]
1469 fn no_perf_mode_active_true_when_env_set_to_value() {
1470 let _l = lock_env();
1471 let _g = EnvVarGuard::set(crate::KTSTR_NO_PERF_MODE_ENV, "1");
1472 assert!(no_perf_mode_active());
1473 }
1474
1475 #[test]
1476 fn no_perf_mode_active_false_when_env_unset() {
1477 let _l = lock_env();
1478 let _g = EnvVarGuard::remove(crate::KTSTR_NO_PERF_MODE_ENV);
1479 assert!(!no_perf_mode_active());
1480 }
1481
1482 /// Regression pin: empty-string-as-unset contract. Before the
1483 /// env-var-sweep cleanup, the bare `is_ok()` reader returned
1484 /// true on
1485 /// `KTSTR_NO_PERF_MODE=` (set but empty — e.g. Docker
1486 /// `--env KTSTR_NO_PERF_MODE` pass-through fired without a
1487 /// value), silently flipping perf-mode OFF for every
1488 /// `performance_mode` test. The fix at L146 treats
1489 /// empty-as-unset; this test pins that contract for ALL
1490 /// consumer sites (shell-mode VM at lib.rs, verifier at
1491 /// verifier.rs, dispatch + eval) since they all route
1492 /// through this helper.
1493 #[test]
1494 fn no_perf_mode_active_false_when_env_set_to_empty_string() {
1495 let _l = lock_env();
1496 let _g = EnvVarGuard::set(crate::KTSTR_NO_PERF_MODE_ENV, "");
1497 assert!(
1498 !no_perf_mode_active(),
1499 "empty-string env must be treated as UNSET — a regression \
1500 here flips perf-mode for every consumer that routes \
1501 through no_perf_mode_active",
1502 );
1503 }
1504
1505 #[test]
1506 fn perf_only_active_true_when_env_set_to_value() {
1507 let _l = lock_env();
1508 let _g = EnvVarGuard::set(crate::KTSTR_PERF_ONLY_ENV, "1");
1509 assert!(perf_only_active());
1510 }
1511
1512 #[test]
1513 fn perf_only_active_false_when_env_unset() {
1514 let _l = lock_env();
1515 let _g = EnvVarGuard::remove(crate::KTSTR_PERF_ONLY_ENV);
1516 assert!(!perf_only_active());
1517 }
1518
1519 /// Empty-as-unset contract (mirrors `no_perf_mode_active`): a
1520 /// `KTSTR_PERF_ONLY=` pass-through must NOT silently skip every
1521 /// non-perf test.
1522 #[test]
1523 fn perf_only_active_false_when_env_set_to_empty_string() {
1524 let _l = lock_env();
1525 let _g = EnvVarGuard::set(crate::KTSTR_PERF_ONLY_ENV, "");
1526 assert!(
1527 !perf_only_active(),
1528 "empty-string env must be treated as UNSET",
1529 );
1530 }
1531
1532 /// Selection logic: with perf-only active, a non-performance_mode
1533 /// entry is skipped while a performance_mode entry is kept. When
1534 /// perf-only is inactive, neither is skipped.
1535 #[test]
1536 fn perf_only_skips_entry_keeps_perf_skips_others() {
1537 use super::super::entry::KtstrTestEntry;
1538 let perf = KtstrTestEntry {
1539 name: "perf",
1540 performance_mode: true,
1541 ..KtstrTestEntry::DEFAULT
1542 };
1543 let plain = KtstrTestEntry {
1544 name: "plain",
1545 performance_mode: false,
1546 ..KtstrTestEntry::DEFAULT
1547 };
1548
1549 let _l = lock_env();
1550 {
1551 let _g = EnvVarGuard::set(crate::KTSTR_PERF_ONLY_ENV, "1");
1552 assert!(
1553 !perf_only_skips_entry(&perf),
1554 "a performance_mode test is the selection target, never skipped",
1555 );
1556 assert!(
1557 perf_only_skips_entry(&plain),
1558 "a non-performance_mode test must be skipped under perf-only",
1559 );
1560 }
1561 let _g = EnvVarGuard::remove(crate::KTSTR_PERF_ONLY_ENV);
1562 assert!(!perf_only_skips_entry(&perf));
1563 assert!(
1564 !perf_only_skips_entry(&plain),
1565 "perf-only inactive => nothing is skipped on this axis",
1566 );
1567 }
1568
1569 #[test]
1570 fn bypass_llc_locks_active_true_when_env_set_to_value() {
1571 let _l = lock_env();
1572 let _g = EnvVarGuard::set(crate::KTSTR_BYPASS_LLC_LOCKS_ENV, "1");
1573 assert!(bypass_llc_locks_active());
1574 }
1575
1576 #[test]
1577 fn bypass_llc_locks_active_false_when_env_unset() {
1578 let _l = lock_env();
1579 let _g = EnvVarGuard::remove(crate::KTSTR_BYPASS_LLC_LOCKS_ENV);
1580 assert!(!bypass_llc_locks_active());
1581 }
1582
1583 /// Regression pin: empty-string-as-unset contract for
1584 /// KTSTR_BYPASS_LLC_LOCKS. A bare `KTSTR_BYPASS_LLC_LOCKS=`
1585 /// (CI shell / Docker `--env` pass-through without value)
1586 /// must NOT activate the bypass. The helper enforces this
1587 /// uniformly for all 7 reader sites (vmm/builder.rs,
1588 /// cli/kernel_build/build.rs ×2, bin/ktstr.rs ×2,
1589 /// bin/cargo_ktstr/{kernel/mod, misc/shell}) — a regression
1590 /// here flips the contention contract for every caller.
1591 #[test]
1592 fn bypass_llc_locks_active_false_when_env_set_to_empty_string() {
1593 let _l = lock_env();
1594 let _g = EnvVarGuard::set(crate::KTSTR_BYPASS_LLC_LOCKS_ENV, "");
1595 assert!(
1596 !bypass_llc_locks_active(),
1597 "empty-string env must be treated as UNSET per the contract \
1598 shared with no_perf_mode_active — a regression here flips \
1599 LLC flock contention enforcement for every reader",
1600 );
1601 }
1602
1603 #[test]
1604 fn config_file_parts_nested_path() {
1605 static SCHED: Scheduler = Scheduler::named("cfg").config_file("configs/my_sched.toml");
1606 let entry = KtstrTestEntry {
1607 name: "cfg_test",
1608 scheduler: &SCHED,
1609 ..KtstrTestEntry::DEFAULT
1610 };
1611 let (archive, host, guest) = config_file_parts(&entry).unwrap();
1612 assert_eq!(archive, "include-files/my_sched.toml");
1613 assert_eq!(host, PathBuf::from("configs/my_sched.toml"));
1614 assert_eq!(guest, "/include-files/my_sched.toml");
1615 }
1616
1617 #[test]
1618 fn config_file_parts_bare_filename() {
1619 static SCHED: Scheduler = Scheduler::named("cfg").config_file("config.toml");
1620 let entry = KtstrTestEntry {
1621 name: "cfg_bare",
1622 scheduler: &SCHED,
1623 ..KtstrTestEntry::DEFAULT
1624 };
1625 let (archive, host, guest) = config_file_parts(&entry).unwrap();
1626 assert_eq!(archive, "include-files/config.toml");
1627 assert_eq!(host, PathBuf::from("config.toml"));
1628 assert_eq!(guest, "/include-files/config.toml");
1629 }
1630
1631 #[test]
1632 fn config_file_parts_none_when_unset() {
1633 let entry = KtstrTestEntry {
1634 name: "no_cfg",
1635 ..KtstrTestEntry::DEFAULT
1636 };
1637 assert!(config_file_parts(&entry).is_none());
1638 }
1639
1640 // -- build_cmdline_extra --
1641
1642 use super::super::entry::{KtstrTestEntry, Sysctl};
1643
1644 #[test]
1645 fn build_cmdline_extra_default_is_sidecar_only() {
1646 let _lock = lock_env();
1647 // Make sure the env does not inject spurious RUST_BACKTRACE /
1648 // RUST_LOG entries that would break the default assertion.
1649 let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1650 let _env_log = EnvVarGuard::remove("RUST_LOG");
1651 // Pin KTSTR_SIDECAR_DIR so the propagation token shape is
1652 // stable across tests; without the override, the call falls
1653 // through to the `{kernel}-{commit}` resolver whose output
1654 // depends on the test process's git state.
1655 let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1656
1657 let entry = KtstrTestEntry {
1658 name: "cmdline_test",
1659 ..KtstrTestEntry::DEFAULT
1660 };
1661 let out = build_cmdline_extra(&entry);
1662 assert_eq!(out, "KTSTR_SIDECAR_DIR=/tmp/ktstr-test");
1663 }
1664
1665 #[test]
1666 fn build_cmdline_extra_appends_sysctls_kargs() {
1667 let _lock = lock_env();
1668 let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1669 let _env_log = EnvVarGuard::remove("RUST_LOG");
1670 let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1671
1672 static SYSCTLS: &[Sysctl] = &[Sysctl::new("kernel.foo", "1")];
1673 static SCHED: Scheduler = Scheduler::named("s").sysctls(SYSCTLS).kargs(&["quiet"]);
1674 let entry = KtstrTestEntry {
1675 name: "cmd",
1676 scheduler: &SCHED,
1677 ..KtstrTestEntry::DEFAULT
1678 };
1679 let out = build_cmdline_extra(&entry);
1680 assert_eq!(
1681 out,
1682 "sysctl.kernel.foo=1 quiet KTSTR_SIDECAR_DIR=/tmp/ktstr-test"
1683 );
1684 }
1685
1686 #[test]
1687 fn build_cmdline_extra_emits_probe_dump_gate_only_when_opted_in() {
1688 let _lock = lock_env();
1689 let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1690 let _env_log = EnvVarGuard::remove("RUST_LOG");
1691 let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1692
1693 let default = KtstrTestEntry {
1694 name: "probe_dump_gate_default",
1695 ..KtstrTestEntry::DEFAULT
1696 };
1697 assert!(
1698 !build_cmdline_extra(&default).contains("KTSTR_AWAIT_PROBE_DUMP_READY"),
1699 "the default path must not pay the probe-dump readiness gate"
1700 );
1701
1702 let opted_in = KtstrTestEntry {
1703 name: "probe_dump_gate_enabled",
1704 probe_dump_ready_gate: true,
1705 ..KtstrTestEntry::DEFAULT
1706 };
1707 assert_eq!(
1708 build_cmdline_extra(&opted_in),
1709 "KTSTR_AWAIT_PROBE_DUMP_READY=1 KTSTR_SIDECAR_DIR=/tmp/ktstr-test"
1710 );
1711 }
1712
1713 #[test]
1714 fn build_auto_repro_cmdline_extra_omits_primary_probe_dump_gate() {
1715 let _lock = lock_env();
1716 let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1717 let _env_log = EnvVarGuard::remove("RUST_LOG");
1718 let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1719
1720 let opted_in = KtstrTestEntry {
1721 name: "probe_dump_gate_auto_repro",
1722 probe_dump_ready_gate: true,
1723 ..KtstrTestEntry::DEFAULT
1724 };
1725 assert_eq!(
1726 build_auto_repro_cmdline_extra(&opted_in),
1727 "KTSTR_SIDECAR_DIR=/tmp/ktstr-test",
1728 "auto-repro must not inherit the primary-only probe-dump gate"
1729 );
1730 }
1731
1732 #[test]
1733 fn scheduler_kargs_cannot_forge_or_disable_probe_dump_gate() {
1734 let _lock = lock_env();
1735 let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1736 let _env_log = EnvVarGuard::remove("RUST_LOG");
1737 let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1738
1739 static SCHED: Scheduler = Scheduler::named("probe-gate-kargs").kargs(&[
1740 "quiet",
1741 "KTSTR_AWAIT_PROBE_DUMP_READY=0",
1742 "KTSTR_AWAIT_PROBE_DUMP_READY=1",
1743 ]);
1744 let disabled = KtstrTestEntry {
1745 name: "probe_gate_kargs_disabled",
1746 scheduler: &SCHED,
1747 ..KtstrTestEntry::DEFAULT
1748 };
1749 assert_eq!(
1750 build_cmdline_extra(&disabled),
1751 "quiet KTSTR_SIDECAR_DIR=/tmp/ktstr-test"
1752 );
1753
1754 let enabled = KtstrTestEntry {
1755 name: "probe_gate_kargs_enabled",
1756 scheduler: &SCHED,
1757 probe_dump_ready_gate: true,
1758 ..KtstrTestEntry::DEFAULT
1759 };
1760 let primary = build_cmdline_extra(&enabled);
1761 assert_eq!(
1762 primary,
1763 "quiet KTSTR_AWAIT_PROBE_DUMP_READY=1 KTSTR_SIDECAR_DIR=/tmp/ktstr-test"
1764 );
1765 assert_eq!(
1766 primary
1767 .split_ascii_whitespace()
1768 .filter(|token| *token == "KTSTR_AWAIT_PROBE_DUMP_READY=1")
1769 .count(),
1770 1
1771 );
1772 assert_eq!(
1773 build_auto_repro_cmdline_extra(&enabled),
1774 "quiet KTSTR_SIDECAR_DIR=/tmp/ktstr-test"
1775 );
1776 }
1777
1778 #[test]
1779 fn build_cmdline_extra_propagates_rust_env() {
1780 let _lock = lock_env();
1781 let _env_bt = EnvVarGuard::set("RUST_BACKTRACE", "1");
1782 let _env_log = EnvVarGuard::set("RUST_LOG", "debug");
1783 let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/tmp/ktstr-test");
1784
1785 let entry = KtstrTestEntry {
1786 name: "cmd",
1787 ..KtstrTestEntry::DEFAULT
1788 };
1789 let out = build_cmdline_extra(&entry);
1790 assert!(
1791 out.contains("RUST_BACKTRACE=1"),
1792 "expected RUST_BACKTRACE propagation: {out}"
1793 );
1794 assert!(
1795 out.contains("RUST_LOG=debug"),
1796 "expected RUST_LOG propagation: {out}"
1797 );
1798 assert!(
1799 out.contains("KTSTR_SIDECAR_DIR=/tmp/ktstr-test"),
1800 "expected KTSTR_SIDECAR_DIR propagation: {out}"
1801 );
1802 }
1803
1804 #[test]
1805 fn build_cmdline_extra_propagates_sidecar_dir() {
1806 let _lock = lock_env();
1807 let _env_bt = EnvVarGuard::remove("RUST_BACKTRACE");
1808 let _env_log = EnvVarGuard::remove("RUST_LOG");
1809 // Explicit override path proves the token shape is exactly
1810 // `KTSTR_SIDECAR_DIR=<path>` and uses the override verbatim
1811 // (host's `sidecar_dir()` honours the env var as the
1812 // operator-chosen override slot).
1813 let _env_sd = EnvVarGuard::set(crate::KTSTR_SIDECAR_DIR_ENV, "/explicit/sidecar/dir");
1814
1815 let entry = KtstrTestEntry {
1816 name: "cmd",
1817 ..KtstrTestEntry::DEFAULT
1818 };
1819 let out = build_cmdline_extra(&entry);
1820 assert_eq!(out, "KTSTR_SIDECAR_DIR=/explicit/sidecar/dir");
1821 }
1822
1823 // -- resolve_vm_topology --
1824
1825 #[test]
1826 fn resolve_vm_topology_override_is_verbatim() {
1827 let entry = KtstrTestEntry {
1828 name: "topo_test",
1829 ..KtstrTestEntry::DEFAULT
1830 };
1831 let over = super::super::topo::TopoOverride {
1832 numa_nodes: 2,
1833 llcs: 4,
1834 cores: 8,
1835 threads: 2,
1836 memory_mib: 4096,
1837 };
1838 let (topo, mem) = resolve_vm_topology(&entry, Some(&over));
1839 assert_eq!(mem, 4096);
1840 assert_eq!(topo.llcs, 4);
1841 assert_eq!(topo.cores_per_llc, 8);
1842 assert_eq!(topo.threads_per_core, 2);
1843 assert_eq!(topo.numa_nodes, 2);
1844 }
1845
1846 #[test]
1847 fn resolve_vm_topology_default_memory_can_stay_below_two_gib() {
1848 // The default topology has two vCPUs, so cpu scaling yields
1849 // 128 MiB and the framework-wide 256-MiB floor wins. This
1850 // specifically guards against restoring a stale multi-GiB
1851 // entry default that would defeat deferred payload sizing.
1852 let entry = KtstrTestEntry {
1853 name: "tiny",
1854 ..KtstrTestEntry::DEFAULT
1855 };
1856 let (_topo, mem) = resolve_vm_topology(&entry, None);
1857 assert_eq!(mem, 256, "memory floor = 256 MiB, got {mem}");
1858 assert!(mem < 2048, "default memory must not pin every VM at 2 GiB");
1859 }
1860
1861 #[test]
1862 fn resolve_vm_topology_none_honors_entry_memory_mib() {
1863 // Entry with explicit memory_mib above the cpu*64 and 256 floors.
1864 let entry = KtstrTestEntry {
1865 name: "mem",
1866 memory_mib: 1536,
1867 ..KtstrTestEntry::DEFAULT
1868 };
1869 let (_topo, mem) = resolve_vm_topology(&entry, None);
1870 assert_eq!(
1871 mem, 1536,
1872 "a real explicit override must win even when it is not the old 2-GiB default"
1873 );
1874 }
1875
1876 #[cfg(feature = "wprof")]
1877 #[test]
1878 fn resolve_vm_topology_wprof_does_not_oversize_at_minimal_default() {
1879 // wprof=true with the minimal default arena must NOT oversize:
1880 // the derived wprof floor (16 MiB) is below the entry's own
1881 // memory, so the entry-derived path sizes the VM exactly like
1882 // the same non-wprof entry. Guards against restoring a
1883 // multi-GiB wprof floor that pinned every wprof cell high.
1884 let entry = KtstrTestEntry {
1885 name: "wprof_minimal",
1886 memory_mib: 512,
1887 wprof: true,
1888 ..KtstrTestEntry::DEFAULT
1889 };
1890 // Compile-time invariant: at the minimal default the wprof
1891 // floor stays at/under the universal 256 MiB floor, so it is
1892 // subsumed and cannot oversize a VM.
1893 const { assert!(crate::vmm::wprof::WPROF_MIN_MEMORY_MIB <= 256) };
1894 let (_topo, mem) = resolve_vm_topology(&entry, None);
1895 assert_eq!(
1896 mem, 512,
1897 "wprof must not oversize past the entry's own 512 MiB; got {mem}"
1898 );
1899 }
1900
1901 #[cfg(feature = "wprof")]
1902 #[test]
1903 fn resolve_vm_topology_wprof_no_bump_when_already_above_floor() {
1904 // Entry already above the wprof floor — must be honored unchanged.
1905 let entry = KtstrTestEntry {
1906 name: "wprof_high",
1907 memory_mib: 8192,
1908 wprof: true,
1909 ..KtstrTestEntry::DEFAULT
1910 };
1911 let (_topo, mem) = resolve_vm_topology(&entry, None);
1912 assert_eq!(
1913 mem, 8192,
1914 "memory_mib above WPROF_MIN_MEMORY_MIB must be honored \
1915 unchanged, got {mem}"
1916 );
1917 }
1918
1919 #[test]
1920 fn resolve_vm_topology_wprof_disabled_does_not_floor() {
1921 // wprof=false: the wprof floor must NOT apply, even when
1922 // entry.memory_mib falls below WPROF_MIN_MEMORY_MIB. Only
1923 // the universal 256 floor + cpu*64 derivation apply.
1924 let entry = KtstrTestEntry {
1925 name: "no_wprof",
1926 memory_mib: 512,
1927 wprof: false,
1928 ..KtstrTestEntry::DEFAULT
1929 };
1930 let (_topo, mem) = resolve_vm_topology(&entry, None);
1931 assert_eq!(
1932 mem, 512,
1933 "wprof=false must not invoke the WPROF_MIN_MEMORY_MIB \
1934 floor, got {mem}"
1935 );
1936 }
1937
1938 #[test]
1939 fn derive_test_memory_mib_baseline_without_wprof() {
1940 let entry = KtstrTestEntry {
1941 name: "baseline",
1942 ..KtstrTestEntry::DEFAULT
1943 };
1944 let mem = derive_test_memory_mib(2, &entry);
1945 assert_eq!(mem, 256, "2 cpus * 64 = 128, floor 256 wins");
1946 assert_eq!(
1947 derive_test_memory_min_mib(2, entry.memory_mib, entry.wprof),
1948 mem,
1949 "the admission-stamp scalar projection must equal entry-based VM sizing",
1950 );
1951 }
1952
1953 #[test]
1954 fn cpu_scaled_memory_mib_scales_and_floors() {
1955 // Shared scaling core used by both derive_test_memory_mib and
1956 // the verifier cell. Below the crossover (256/64 = 4 cpus) the
1957 // 256 MiB floor wins; at/above it the 64 MiB/cpu term wins.
1958 assert_eq!(cpu_scaled_memory_mib(1), 256, "1 cpu * 64 = 64, floor 256");
1959 assert_eq!(cpu_scaled_memory_mib(4), 256, "4 cpus * 64 = 256, tie");
1960 assert_eq!(cpu_scaled_memory_mib(8), 512, "8 cpus * 64 = 512 wins");
1961 assert_eq!(cpu_scaled_memory_mib(16), 1024, "16 cpus * 64 = 1024 wins");
1962 }
1963
1964 #[test]
1965 fn stamped_wprof_memory_floor_is_feature_independent() {
1966 // The floor is applied by value, not by cfg!(feature = "wprof"):
1967 // a below-floor raw is bumped, an at/above-floor raw passes
1968 // through — identically whether or not the reader binary was
1969 // built with wprof.
1970 assert_eq!(
1971 apply_wprof_memory_floor(WPROF_MIN_MEMORY_MIB - 1, true),
1972 WPROF_MIN_MEMORY_MIB,
1973 "a raw below the derived floor must be bumped up to it",
1974 );
1975 assert_eq!(
1976 apply_wprof_memory_floor(WPROF_MIN_MEMORY_MIB, true),
1977 WPROF_MIN_MEMORY_MIB,
1978 "a raw at the floor passes through (strict-less-than)",
1979 );
1980 assert_eq!(apply_wprof_memory_floor(4096, true), 4096);
1981 assert_eq!(apply_wprof_memory_floor(4096, false), 4096);
1982 // At the minimal default arena the floor (16 MiB) is far below
1983 // the universal 256 MiB floor, so admission sizing is dominated
1984 // by the latter regardless of the wprof bit — the whole point
1985 // of the minimal default is that wprof no longer oversizes.
1986 assert_eq!(derive_test_memory_min_mib(2, 768, true), 768);
1987 assert_eq!(derive_test_memory_min_mib(2, 768, false), 768);
1988 }
1989
1990 #[test]
1991 fn checked_admission_memory_scaling_rejects_overflow() {
1992 assert_eq!(checked_cpu_scaled_memory_mib(u32::MAX), None);
1993 assert_eq!(
1994 checked_derive_test_memory_min_mib(u32::MAX, 256, false),
1995 None
1996 );
1997 assert_eq!(checked_verifier_preset_memory_min_mib(u32::MAX, 4096), None);
1998 }
1999
2000 #[test]
2001 fn verifier_preset_memory_caps_synthetic_cpu_scaling() {
2002 assert_eq!(verifier_preset_memory_min_mib(4, 2048), 256);
2003 assert_eq!(verifier_preset_memory_min_mib(32, 2048), 2048);
2004 assert_eq!(verifier_preset_memory_min_mib(64, 2048), 2048);
2005 assert_eq!(verifier_preset_memory_min_mib(252, 4096), 4096);
2006 }
2007
2008 #[test]
2009 fn cpu_scaled_memory_mib_backs_derive_test_memory_mib() {
2010 // The entry-aware wrapper must reduce to the shared core when no
2011 // per-entry override raises it — the invariant that lets the
2012 // direct verifier API reuse cpu_scaled_memory_mib directly.
2013 let entry = KtstrTestEntry {
2014 name: "shared",
2015 ..KtstrTestEntry::DEFAULT
2016 };
2017 for cpus in [1u32, 4, 8, 32] {
2018 assert_eq!(
2019 derive_test_memory_mib(cpus, &entry),
2020 cpu_scaled_memory_mib(cpus),
2021 "derive_test_memory_mib must equal the shared core for \
2022 {cpus} cpus when the entry uses the framework minimum"
2023 );
2024 }
2025 }
2026
2027 #[cfg(feature = "wprof")]
2028 #[test]
2029 fn resolve_vm_topology_wprof_universal_floor_dominates_tiny_arena() {
2030 // With the minimal default arena the wprof floor is far below
2031 // the universal 256 MiB floor, so the latter dominates even
2032 // when the entry declares exactly WPROF_MIN_MEMORY_MIB. The
2033 // strict-less-than direction of the floor condition itself is
2034 // pinned directly in `stamped_wprof_memory_floor_is_feature_independent`.
2035 let entry = KtstrTestEntry {
2036 name: "wprof_exact",
2037 memory_mib: crate::vmm::wprof::WPROF_MIN_MEMORY_MIB,
2038 wprof: true,
2039 ..KtstrTestEntry::DEFAULT
2040 };
2041 let (_topo, mem) = resolve_vm_topology(&entry, None);
2042 assert_eq!(
2043 mem, 256,
2044 "universal 256 MiB floor dominates the tiny wprof arena; got {mem}"
2045 );
2046 }
2047
2048 #[cfg(feature = "wprof")]
2049 #[test]
2050 fn resolve_vm_topology_wprof_zero_entry_memory_mib_uses_universal_floor() {
2051 // Edge case: entry.memory_mib=0 with wprof=true. The raw
2052 // derivation `max(cpus*64, 256, 0)` resolves to 256 on the
2053 // default 1-CPU topology; the minimal wprof arena is below
2054 // that, so the universal 256 MiB floor is what the VM gets.
2055 let entry = KtstrTestEntry {
2056 name: "wprof_zero_mib",
2057 memory_mib: 0,
2058 wprof: true,
2059 ..KtstrTestEntry::DEFAULT
2060 };
2061 let (_topo, mem) = resolve_vm_topology(&entry, None);
2062 assert_eq!(
2063 mem, 256,
2064 "entry.memory_mib=0 with wprof=true resolves to the \
2065 universal 256 MiB floor; got {mem}"
2066 );
2067 }
2068
2069 #[cfg(feature = "wprof")]
2070 #[test]
2071 fn derive_test_memory_mib_helper_applies_wprof_floor() {
2072 // Direct test of the derivation helper used by BOTH
2073 // resolve_vm_topology AND the dispatch.rs sites that
2074 // construct TopoOverride from CLI / preset topology
2075 // (run_ktstr_test_with_topo_str, run_gauntlet_test).
2076 // Pins that the helper applies the wprof floor — a
2077 // regression that re-inlined the formula at the dispatch
2078 // sites without the wprof check would silently bypass
2079 // the floor when `cargo ktstr test --ktstr-topo` runs
2080 // against a wprof-tagged test.
2081 let entry = KtstrTestEntry {
2082 name: "helper",
2083 memory_mib: 0,
2084 wprof: true,
2085 ..KtstrTestEntry::DEFAULT
2086 };
2087 let mem = derive_test_memory_mib(2, &entry);
2088 assert_eq!(
2089 mem, 256,
2090 "helper applies the wprof floor (16 MiB) but it is subsumed \
2091 by the universal 256 MiB floor for a 2-cpu VM; got {mem}"
2092 );
2093 assert_eq!(
2094 derive_test_memory_min_mib(2, entry.memory_mib, entry.wprof),
2095 mem,
2096 "pre-exec admission must apply the same wprof floor as VM sizing",
2097 );
2098
2099 // wprof=false: derivation returns the raw formula
2100 // without any floor.
2101 let entry_no_wprof = KtstrTestEntry {
2102 wprof: false,
2103 ..entry
2104 };
2105 let mem = derive_test_memory_mib(2, &entry_no_wprof);
2106 assert_eq!(
2107 mem, 256,
2108 "helper with wprof=false must NOT apply the floor; \
2109 expected max(2*64, 256, 0)=256, got {mem}"
2110 );
2111 }
2112
2113 #[cfg(feature = "wprof")]
2114 #[test]
2115 fn resolve_vm_topology_override_with_wprof_honors_override_verbatim() {
2116 // The override-is-verbatim contract: a TopoOverride with
2117 // memory_mib below WPROF_MIN_MEMORY_MIB is honored as the
2118 // operator's explicit choice. A warn-level log fires (not
2119 // verified in this unit test — tracing capture is out of
2120 // scope here) but the boot memory matches the override.
2121 let entry = KtstrTestEntry {
2122 name: "override_wprof",
2123 wprof: true,
2124 ..KtstrTestEntry::DEFAULT
2125 };
2126 let over = super::super::topo::TopoOverride {
2127 numa_nodes: 1,
2128 llcs: 1,
2129 cores: 1,
2130 threads: 1,
2131 memory_mib: 512,
2132 };
2133 let (_topo, mem) = resolve_vm_topology(&entry, Some(&over));
2134 assert_eq!(
2135 mem, 512,
2136 "TopoOverride.memory_mib must be honored verbatim even \
2137 with wprof enabled, got {mem}"
2138 );
2139 }
2140
2141 // -- append_base_sched_args --
2142
2143 #[test]
2144 fn append_base_sched_args_empty_when_none_set() {
2145 let entry = KtstrTestEntry {
2146 name: "nosched",
2147 ..KtstrTestEntry::DEFAULT
2148 };
2149 let mut args = Vec::new();
2150 append_base_sched_args(&entry, &mut args);
2151 assert!(args.is_empty(), "no sched args expected: {args:?}");
2152 }
2153
2154 /// `cgroup_parent` does NOT auto-inject `--cell-parent-cgroup`
2155 /// into the scheduler argv — the two concerns are decoupled.
2156 /// The scheduler-def `sched_args` and the per-test
2157 /// `extra_sched_args` flow through unchanged; the `cgroup_parent`
2158 /// setting controls the framework's cgroup root but never
2159 /// modifies the scheduler's CLI invocation.
2160 #[test]
2161 fn append_base_sched_args_does_not_auto_inject_cell_parent_cgroup() {
2162 static SCHED: Scheduler = Scheduler::named("s")
2163 .cgroup_parent("/sys/fs/cgroup/ktstr")
2164 .sched_args(&["-v", "--flag"]);
2165 let entry = KtstrTestEntry {
2166 name: "sched",
2167 scheduler: &SCHED,
2168 extra_sched_args: &["--extra"],
2169 ..KtstrTestEntry::DEFAULT
2170 };
2171 let mut args = Vec::new();
2172 append_base_sched_args(&entry, &mut args);
2173 assert_eq!(
2174 args,
2175 vec![
2176 "-v".to_string(),
2177 "--flag".to_string(),
2178 "--extra".to_string(),
2179 ],
2180 "cgroup_parent must not auto-inject --cell-parent-cgroup; \
2181 only sched_args + extra_sched_args reach the scheduler"
2182 );
2183 }
2184
2185 /// User-passed `--cell-parent-cgroup /user` via `extra_sched_args`
2186 /// suppresses the auto-inject so clap inside the scheduler binary
2187 /// doesn't reject the duplicate.
2188 #[test]
2189 fn append_base_sched_args_dedupes_extra_split_form() {
2190 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2191 let entry = KtstrTestEntry {
2192 name: "sched",
2193 scheduler: &SCHED,
2194 extra_sched_args: &["--cell-parent-cgroup", "/user"],
2195 ..KtstrTestEntry::DEFAULT
2196 };
2197 let mut args = Vec::new();
2198 append_base_sched_args(&entry, &mut args);
2199 assert_eq!(
2200 args,
2201 vec!["--cell-parent-cgroup".to_string(), "/user".to_string()],
2202 "auto-inject must be skipped when extra_sched_args carries \
2203 --cell-parent-cgroup in two-token form"
2204 );
2205 }
2206
2207 /// Combined form (`--cell-parent-cgroup=/user`) must also suppress
2208 /// the auto-inject.
2209 #[test]
2210 fn append_base_sched_args_dedupes_extra_combined_form() {
2211 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2212 let entry = KtstrTestEntry {
2213 name: "sched",
2214 scheduler: &SCHED,
2215 extra_sched_args: &["--cell-parent-cgroup=/user"],
2216 ..KtstrTestEntry::DEFAULT
2217 };
2218 let mut args = Vec::new();
2219 append_base_sched_args(&entry, &mut args);
2220 assert_eq!(
2221 args,
2222 vec!["--cell-parent-cgroup=/user".to_string()],
2223 "auto-inject must be skipped when extra_sched_args carries \
2224 --cell-parent-cgroup in combined `=` form"
2225 );
2226 }
2227
2228 /// Scheduler-def `sched_args` carrying `--cell-parent-cgroup`
2229 /// also suppresses the auto-inject.
2230 #[test]
2231 fn append_base_sched_args_dedupes_scheduler_sched_args() {
2232 static SCHED: Scheduler = Scheduler::named("s")
2233 .cgroup_parent("/sys/fs/cgroup/ktstr")
2234 .sched_args(&["--cell-parent-cgroup", "/user"]);
2235 let entry = KtstrTestEntry {
2236 name: "sched",
2237 scheduler: &SCHED,
2238 ..KtstrTestEntry::DEFAULT
2239 };
2240 let mut args = Vec::new();
2241 append_base_sched_args(&entry, &mut args);
2242 assert_eq!(
2243 args,
2244 vec!["--cell-parent-cgroup".to_string(), "/user".to_string()],
2245 "auto-inject must be skipped when scheduler.sched_args carries \
2246 --cell-parent-cgroup"
2247 );
2248 }
2249
2250 /// Scheduler-def `sched_args` carrying the combined `=` form also
2251 /// suppresses the auto-inject — completes the {source × form}
2252 /// 2×2 matrix.
2253 #[test]
2254 fn append_base_sched_args_dedupes_scheduler_sched_args_combined_form() {
2255 static SCHED: Scheduler = Scheduler::named("s")
2256 .cgroup_parent("/sys/fs/cgroup/ktstr")
2257 .sched_args(&["--cell-parent-cgroup=/user"]);
2258 let entry = KtstrTestEntry {
2259 name: "sched",
2260 scheduler: &SCHED,
2261 ..KtstrTestEntry::DEFAULT
2262 };
2263 let mut args = Vec::new();
2264 append_base_sched_args(&entry, &mut args);
2265 assert_eq!(
2266 args,
2267 vec!["--cell-parent-cgroup=/user".to_string()],
2268 "auto-inject must be skipped when scheduler.sched_args carries \
2269 --cell-parent-cgroup in combined `=` form"
2270 );
2271 }
2272
2273 /// When BOTH scheduler.sched_args AND extra_sched_args carry
2274 /// `--cell-parent-cgroup`, the framework's auto-inject is
2275 /// suppressed (`.any()` short-circuits on first match) but the
2276 /// user's duplicates flow through unchanged. The framework does
2277 /// not dedupe user-supplied duplicates — clap inside the
2278 /// scheduler binary will reject them with "cannot be used
2279 /// multiple times", as it should. Pin: the framework correctly
2280 /// avoids ADDING a third copy.
2281 #[test]
2282 fn append_base_sched_args_does_not_dedupe_user_dupes() {
2283 static SCHED: Scheduler = Scheduler::named("s")
2284 .cgroup_parent("/sys/fs/cgroup/ktstr")
2285 .sched_args(&["--cell-parent-cgroup", "/sched"]);
2286 let entry = KtstrTestEntry {
2287 name: "sched",
2288 scheduler: &SCHED,
2289 extra_sched_args: &["--cell-parent-cgroup", "/extra"],
2290 ..KtstrTestEntry::DEFAULT
2291 };
2292 let mut args = Vec::new();
2293 append_base_sched_args(&entry, &mut args);
2294 assert_eq!(
2295 args,
2296 vec![
2297 "--cell-parent-cgroup".to_string(),
2298 "/sched".to_string(),
2299 "--cell-parent-cgroup".to_string(),
2300 "/extra".to_string(),
2301 ],
2302 "framework auto-inject is suppressed; both user-supplied \
2303 entries flow through unchanged (user owns the dup)"
2304 );
2305 }
2306
2307 /// Empty combined value (`--cell-parent-cgroup=`) is rejected at
2308 /// the framework gate with an actionable panic that names the
2309 /// offending test and points the operator at the right fix.
2310 /// Empty values would resolve to `/sys/fs/cgroup` (the host
2311 /// cgroup root) downstream — guaranteed to corrupt unrelated
2312 /// cgroup state — so the framework rejects rather than letting
2313 /// clap surface a generic "value required" error after the
2314 /// cgroup hierarchy has already been built.
2315 #[test]
2316 #[should_panic(expected = "that does not start with `/`")]
2317 fn append_base_sched_args_panics_on_empty_combined_value_via_extra() {
2318 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2319 let entry = KtstrTestEntry {
2320 name: "sched",
2321 scheduler: &SCHED,
2322 extra_sched_args: &["--cell-parent-cgroup="],
2323 ..KtstrTestEntry::DEFAULT
2324 };
2325 let mut args = Vec::new();
2326 append_base_sched_args(&entry, &mut args);
2327 }
2328
2329 /// Two-token form with an empty value as the second token
2330 /// (`["--cell-parent-cgroup", ""]`) is rejected by the same gate.
2331 /// Covers the second route into `parse_cell_parent_cgroup` so a
2332 /// future refactor that switches the empty-detection logic on
2333 /// only one form gets caught.
2334 #[test]
2335 #[should_panic(expected = "that does not start with `/`")]
2336 fn append_base_sched_args_panics_on_empty_two_token_value_via_extra() {
2337 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2338 let entry = KtstrTestEntry {
2339 name: "sched_two_token",
2340 scheduler: &SCHED,
2341 extra_sched_args: &["--cell-parent-cgroup", ""],
2342 ..KtstrTestEntry::DEFAULT
2343 };
2344 let mut args = Vec::new();
2345 append_base_sched_args(&entry, &mut args);
2346 }
2347
2348 /// Bad value via the scheduler-def's own `sched_args` rather than
2349 /// the test's `extra_sched_args` — the chain at the parser site
2350 /// covers both sources, so the gate fires regardless of origin.
2351 /// Pins both the combined form and the scheduler origin.
2352 #[test]
2353 #[should_panic(expected = "that does not start with `/`")]
2354 fn append_base_sched_args_panics_on_empty_combined_value_via_scheduler_sched_args() {
2355 static SCHED: Scheduler = Scheduler::named("s")
2356 .cgroup_parent("/sys/fs/cgroup/ktstr")
2357 .sched_args(&["--cell-parent-cgroup="]);
2358 let entry = KtstrTestEntry {
2359 name: "sched_in_def",
2360 scheduler: &SCHED,
2361 ..KtstrTestEntry::DEFAULT
2362 };
2363 let mut args = Vec::new();
2364 append_base_sched_args(&entry, &mut args);
2365 }
2366
2367 /// Two-token form via the scheduler-def origin — completes the
2368 /// 2-source × 2-form matrix together with the three siblings.
2369 #[test]
2370 #[should_panic(expected = "that does not start with `/`")]
2371 fn append_base_sched_args_panics_on_empty_two_token_value_via_scheduler_sched_args() {
2372 static SCHED: Scheduler = Scheduler::named("s")
2373 .cgroup_parent("/sys/fs/cgroup/ktstr")
2374 .sched_args(&["--cell-parent-cgroup", ""]);
2375 let entry = KtstrTestEntry {
2376 name: "sched_in_def_two_token",
2377 scheduler: &SCHED,
2378 ..KtstrTestEntry::DEFAULT
2379 };
2380 let mut args = Vec::new();
2381 append_base_sched_args(&entry, &mut args);
2382 }
2383
2384 /// Empty-value gate fires even when the scheduler-def has no
2385 /// `cgroup_parent` default. Without the universal gate the empty
2386 /// value would slip through and corrupt unrelated host cgroup
2387 /// state at the downstream `resolve_cgroup_root` interpolation.
2388 #[test]
2389 #[should_panic(expected = "that does not start with `/`")]
2390 fn append_base_sched_args_panics_on_empty_combined_value_no_scheduler_cgroup_parent() {
2391 static SCHED: Scheduler = Scheduler::named("s");
2392 let entry = KtstrTestEntry {
2393 name: "no_default_cgroup",
2394 scheduler: &SCHED,
2395 extra_sched_args: &["--cell-parent-cgroup="],
2396 ..KtstrTestEntry::DEFAULT
2397 };
2398 let mut args = Vec::new();
2399 append_base_sched_args(&entry, &mut args);
2400 }
2401
2402 /// Two-token form, no scheduler default — completes the
2403 /// no-default matrix together with the combined-form sibling.
2404 #[test]
2405 #[should_panic(expected = "that does not start with `/`")]
2406 fn append_base_sched_args_panics_on_empty_two_token_value_no_scheduler_cgroup_parent() {
2407 static SCHED: Scheduler = Scheduler::named("s");
2408 let entry = KtstrTestEntry {
2409 name: "no_default_cgroup_two_token",
2410 scheduler: &SCHED,
2411 extra_sched_args: &["--cell-parent-cgroup", ""],
2412 ..KtstrTestEntry::DEFAULT
2413 };
2414 let mut args = Vec::new();
2415 append_base_sched_args(&entry, &mut args);
2416 }
2417
2418 /// Relative path (no leading `/`) is rejected by the same gate.
2419 /// Pins the broader contract (the message explicitly promises
2420 /// "absolute path under `/`"); empty is just one case of
2421 /// non-absolute.
2422 #[test]
2423 #[should_panic(expected = "that does not start with `/`")]
2424 fn append_base_sched_args_panics_on_relative_path_value() {
2425 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2426 let entry = KtstrTestEntry {
2427 name: "relative_path",
2428 scheduler: &SCHED,
2429 extra_sched_args: &["--cell-parent-cgroup=my_test"],
2430 ..KtstrTestEntry::DEFAULT
2431 };
2432 let mut args = Vec::new();
2433 append_base_sched_args(&entry, &mut args);
2434 }
2435
2436 /// Two-token form of the relative-path case. Closes the matrix
2437 /// gap: combined-form was pinned by the sibling above but a
2438 /// future refactor that split path validation between the
2439 /// combined and two-token branches could regress one form
2440 /// without test catching.
2441 #[test]
2442 #[should_panic(expected = "that does not start with `/`")]
2443 fn append_base_sched_args_panics_on_relative_path_value_two_token() {
2444 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2445 let entry = KtstrTestEntry {
2446 name: "relative_path_two_token",
2447 scheduler: &SCHED,
2448 extra_sched_args: &["--cell-parent-cgroup", "my_test"],
2449 ..KtstrTestEntry::DEFAULT
2450 };
2451 let mut args = Vec::new();
2452 append_base_sched_args(&entry, &mut args);
2453 }
2454
2455 /// `/.` is absolute and has more than one character, so a naive
2456 /// `starts_with('/') && len > 1` check passes — but the kernel
2457 /// canonicalizes `/sys/fs/cgroup/.` back to `/sys/fs/cgroup`
2458 /// (host cgroup root), corrupting unrelated cgroup state.
2459 /// `Path::components` strips the trailing `.`, yielding `[RootDir]`
2460 /// — the validator rejects via the "has no Normal component"
2461 /// check, not the CurDir arm (see `cell_parent_path_is_valid`).
2462 #[test]
2463 #[should_panic(expected = "contains `.`/`..` segments")]
2464 fn append_base_sched_args_panics_on_dot_normalizing_to_root() {
2465 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2466 let entry = KtstrTestEntry {
2467 name: "dot_normalize",
2468 scheduler: &SCHED,
2469 extra_sched_args: &["--cell-parent-cgroup=/."],
2470 ..KtstrTestEntry::DEFAULT
2471 };
2472 let mut args = Vec::new();
2473 append_base_sched_args(&entry, &mut args);
2474 }
2475
2476 /// `/foo/..` canonicalizes back to `/` → `/sys/fs/cgroup`. Same
2477 /// host-root corruption risk as the empty/bare-slash cases. The
2478 /// component-based gate rejects any `..` (ParentDir) segment.
2479 #[test]
2480 #[should_panic(expected = "contains `.`/`..` segments")]
2481 fn append_base_sched_args_panics_on_parent_dir_normalizing_to_root() {
2482 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2483 let entry = KtstrTestEntry {
2484 name: "parent_dir_normalize",
2485 scheduler: &SCHED,
2486 extra_sched_args: &["--cell-parent-cgroup=/foo/.."],
2487 ..KtstrTestEntry::DEFAULT
2488 };
2489 let mut args = Vec::new();
2490 append_base_sched_args(&entry, &mut args);
2491 }
2492
2493 /// Mixed `/./bar/..` — both kinds of normalizing segment in one
2494 /// path. `Path::components` strips the leading `/.`, yielding
2495 /// `[RootDir, Normal("bar"), ParentDir]`; the validator reaches
2496 /// the `ParentDir` and rejects via that arm. The `/.` never
2497 /// surfaces as a CurDir component.
2498 #[test]
2499 #[should_panic(expected = "contains `.`/`..` segments")]
2500 fn append_base_sched_args_panics_on_mixed_normalize_segments() {
2501 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2502 let entry = KtstrTestEntry {
2503 name: "mixed_normalize",
2504 scheduler: &SCHED,
2505 extra_sched_args: &["--cell-parent-cgroup=/./bar/.."],
2506 ..KtstrTestEntry::DEFAULT
2507 };
2508 let mut args = Vec::new();
2509 append_base_sched_args(&entry, &mut args);
2510 }
2511
2512 /// `/foo/./bar` is ACCEPTED — `Path::components` normalizes away
2513 /// every `CurDir` segment (see `cell_parent_path_is_valid` for
2514 /// the full per-position behavior); the canonical form
2515 /// `/foo/bar` is a real non-root path. Pin the accept path so a
2516 /// future refactor to a stricter `.contains("/./")` text check
2517 /// is caught. Also assert the user value flows through verbatim
2518 /// — a regression that canonicalized the path before forwarding
2519 /// would silently rewrite `/foo/./bar` to `/foo/bar`.
2520 #[test]
2521 fn append_base_sched_args_accepts_embedded_dot_segment() {
2522 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2523 let entry = KtstrTestEntry {
2524 name: "embedded_dot_ok",
2525 scheduler: &SCHED,
2526 extra_sched_args: &["--cell-parent-cgroup=/foo/./bar"],
2527 ..KtstrTestEntry::DEFAULT
2528 };
2529 let mut args = Vec::new();
2530 append_base_sched_args(&entry, &mut args);
2531 assert!(
2532 args.iter().any(|a| a == "--cell-parent-cgroup=/foo/./bar"),
2533 "user value must pass through verbatim (no canonicalization); args: {args:?}",
2534 );
2535 }
2536
2537 /// Bare `/..` is the most damaging path-normalize edge:
2538 /// downstream interpolation `/sys/fs/cgroup/..` canonicalizes to
2539 /// `/sys/fs` — escapes the cgroup hierarchy entirely. The
2540 /// component walk hits `ParentDir` immediately after `RootDir`
2541 /// (no Normal segment between them) and rejects via the
2542 /// ParentDir arm.
2543 #[test]
2544 #[should_panic(expected = "contains `.`/`..` segments")]
2545 fn append_base_sched_args_panics_on_bare_parent_dir() {
2546 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2547 let entry = KtstrTestEntry {
2548 name: "bare_parent_dir",
2549 scheduler: &SCHED,
2550 extra_sched_args: &["--cell-parent-cgroup=/.."],
2551 ..KtstrTestEntry::DEFAULT
2552 };
2553 let mut args = Vec::new();
2554 append_base_sched_args(&entry, &mut args);
2555 }
2556
2557 /// Mid-path `/foo/../bar` — ParentDir sits BETWEEN Normal
2558 /// segments. Different shape from `/foo/..` (trailing
2559 /// ParentDir): a regression that bailed only on
2560 /// `path.ends_with("/..")` would slip this past. Downstream
2561 /// interpolation `/sys/fs/cgroup/foo/../bar` canonicalizes to
2562 /// `/sys/fs/cgroup/bar` — an unintended sibling directory the
2563 /// test author didn't ask for. Component walk catches ParentDir
2564 /// in any position.
2565 #[test]
2566 #[should_panic(expected = "contains `.`/`..` segments")]
2567 fn append_base_sched_args_panics_on_mid_path_parent_dir() {
2568 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2569 let entry = KtstrTestEntry {
2570 name: "mid_path_parent_dir",
2571 scheduler: &SCHED,
2572 extra_sched_args: &["--cell-parent-cgroup=/foo/../bar"],
2573 ..KtstrTestEntry::DEFAULT
2574 };
2575 let mut args = Vec::new();
2576 append_base_sched_args(&entry, &mut args);
2577 }
2578
2579 /// Bare `/` slips a naive `starts_with('/')` check but resolves
2580 /// downstream to `/sys/fs/cgroup/` — semantically the host cgroup
2581 /// root, same corruption risk as the empty case. The gate mirrors
2582 /// `CgroupPath::new`'s const-eval contract (rejects both
2583 /// no-leading-slash AND `"/"` alone) so runtime values share the
2584 /// same validation as compile-time declarations.
2585 #[test]
2586 #[should_panic(expected = "is `/` alone")]
2587 fn append_base_sched_args_panics_on_bare_slash_value() {
2588 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2589 let entry = KtstrTestEntry {
2590 name: "bare_slash",
2591 scheduler: &SCHED,
2592 extra_sched_args: &["--cell-parent-cgroup=/"],
2593 ..KtstrTestEntry::DEFAULT
2594 };
2595 let mut args = Vec::new();
2596 append_base_sched_args(&entry, &mut args);
2597 }
2598
2599 /// Combined-form empty value via scheduler-def `sched_args`
2600 /// when the scheduler also has NO `cgroup_parent` default. Closes
2601 /// the matrix intersection: a future refactor that gates the
2602 /// scheduler-def-source check on `cgroup_parent.is_some()` would
2603 /// pass the other 6 empty tests but regress this cell.
2604 #[test]
2605 #[should_panic(expected = "that does not start with `/`")]
2606 fn append_base_sched_args_panics_on_empty_combined_value_in_scheduler_sched_args_no_default() {
2607 static SCHED: Scheduler = Scheduler::named("s").sched_args(&["--cell-parent-cgroup="]);
2608 let entry = KtstrTestEntry {
2609 name: "scheduler_def_origin_no_default",
2610 scheduler: &SCHED,
2611 ..KtstrTestEntry::DEFAULT
2612 };
2613 let mut args = Vec::new();
2614 append_base_sched_args(&entry, &mut args);
2615 }
2616
2617 /// Two-token-form sibling of the above — completes the
2618 /// 2-form coverage for the scheduler-def-origin × no-default
2619 /// intersection.
2620 #[test]
2621 #[should_panic(expected = "that does not start with `/`")]
2622 fn append_base_sched_args_panics_on_empty_two_token_value_in_scheduler_sched_args_no_default() {
2623 static SCHED: Scheduler = Scheduler::named("s").sched_args(&["--cell-parent-cgroup", ""]);
2624 let entry = KtstrTestEntry {
2625 name: "scheduler_def_origin_two_token_no_default",
2626 scheduler: &SCHED,
2627 ..KtstrTestEntry::DEFAULT
2628 };
2629 let mut args = Vec::new();
2630 append_base_sched_args(&entry, &mut args);
2631 }
2632
2633 /// Bare `--cell-parent-cgroup` flag with no following token
2634 /// (two-token form, trailing in argv) is rejected at the
2635 /// framework gate via the `CellParentCgroupArg::MissingValue`
2636 /// arm. Previously this shape parsed as "absent", triggered the
2637 /// auto-inject, and produced two copies of the flag in the final
2638 /// argv that clap then rejected with a confused "cannot be used
2639 /// multiple times" diagnostic. The gate intercepts here so the
2640 /// operator gets a "missing value" message anchored to their
2641 /// declaration.
2642 #[test]
2643 #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2644 fn append_base_sched_args_panics_on_missing_value_via_extra() {
2645 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2646 let entry = KtstrTestEntry {
2647 name: "missing_value_extra",
2648 scheduler: &SCHED,
2649 extra_sched_args: &["--cell-parent-cgroup"],
2650 ..KtstrTestEntry::DEFAULT
2651 };
2652 let mut args = Vec::new();
2653 append_base_sched_args(&entry, &mut args);
2654 }
2655
2656 /// Bare flag preceded by an unrelated trailing token still trips
2657 /// the MissingValue arm — the parser walks the chain in order,
2658 /// hits the bare flag, and `iter.next()` returns None at end of
2659 /// stream regardless of which unrelated tokens came before it.
2660 #[test]
2661 #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2662 fn append_base_sched_args_panics_on_missing_value_after_other_flag() {
2663 static SCHED: Scheduler = Scheduler::named("s").cgroup_parent("/sys/fs/cgroup/ktstr");
2664 let entry = KtstrTestEntry {
2665 name: "missing_value_after_other",
2666 scheduler: &SCHED,
2667 extra_sched_args: &["--other-flag", "--cell-parent-cgroup"],
2668 ..KtstrTestEntry::DEFAULT
2669 };
2670 let mut args = Vec::new();
2671 append_base_sched_args(&entry, &mut args);
2672 }
2673
2674 /// Bare flag in the scheduler-def's `sched_args` also trips
2675 /// MissingValue — the parser chains both sources and the
2676 /// universal gate handles them identically.
2677 #[test]
2678 #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2679 fn append_base_sched_args_panics_on_missing_value_in_scheduler_sched_args() {
2680 static SCHED: Scheduler = Scheduler::named("s")
2681 .cgroup_parent("/sys/fs/cgroup/ktstr")
2682 .sched_args(&["--cell-parent-cgroup"]);
2683 let entry = KtstrTestEntry {
2684 name: "missing_value_scheduler_def",
2685 scheduler: &SCHED,
2686 ..KtstrTestEntry::DEFAULT
2687 };
2688 let mut args = Vec::new();
2689 append_base_sched_args(&entry, &mut args);
2690 }
2691
2692 /// Bare flag with no scheduler default `cgroup_parent`. The
2693 /// universal gate must still fire — the panic message in this
2694 /// case omits the "let the framework auto-inject" suggestion
2695 /// (no default to inject) and adds a hint that an absolute path
2696 /// is required for cell-aware schedulers without a declared
2697 /// default.
2698 #[test]
2699 #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2700 fn append_base_sched_args_panics_on_missing_value_no_scheduler_cgroup_parent() {
2701 static SCHED: Scheduler = Scheduler::named("s");
2702 let entry = KtstrTestEntry {
2703 name: "missing_value_no_default",
2704 scheduler: &SCHED,
2705 extra_sched_args: &["--cell-parent-cgroup"],
2706 ..KtstrTestEntry::DEFAULT
2707 };
2708 let mut args = Vec::new();
2709 append_base_sched_args(&entry, &mut args);
2710 }
2711
2712 /// Bare flag via scheduler-def `sched_args` with no default
2713 /// `cgroup_parent`. Closes the matrix intersection: a future
2714 /// refactor that gated the MissingValue check on
2715 /// `cgroup_parent.is_some()` (mirroring an earlier regression
2716 /// fixed for Value-invalid) would pass the other 4 MissingValue
2717 /// tests but regress this cell.
2718 #[test]
2719 #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2720 fn append_base_sched_args_panics_on_missing_value_in_scheduler_sched_args_no_default() {
2721 static SCHED: Scheduler = Scheduler::named("s").sched_args(&["--cell-parent-cgroup"]);
2722 let entry = KtstrTestEntry {
2723 name: "missing_value_scheduler_def_no_default",
2724 scheduler: &SCHED,
2725 ..KtstrTestEntry::DEFAULT
2726 };
2727 let mut args = Vec::new();
2728 append_base_sched_args(&entry, &mut args);
2729 }
2730
2731 /// Bare flag after another flag, with no scheduler default.
2732 /// Completes the after-other-flag × default matrix together with
2733 /// the sibling test that has a default.
2734 #[test]
2735 #[should_panic(expected = "supplies a bare `--cell-parent-cgroup`")]
2736 fn append_base_sched_args_panics_on_missing_value_after_other_flag_no_default() {
2737 static SCHED: Scheduler = Scheduler::named("s");
2738 let entry = KtstrTestEntry {
2739 name: "missing_value_after_other_no_default",
2740 scheduler: &SCHED,
2741 extra_sched_args: &["--other-flag", "--cell-parent-cgroup"],
2742 ..KtstrTestEntry::DEFAULT
2743 };
2744 let mut args = Vec::new();
2745 append_base_sched_args(&entry, &mut args);
2746 }
2747
2748 // -- build_vm_builder_base --
2749
2750 /// Kernel-path surfaces in the builder's "kernel not found" error.
2751 /// Proves the `kernel()` setter is wired through the helper.
2752 #[test]
2753 fn build_vm_builder_base_propagates_kernel_path() {
2754 // build()'s no-perf path reads KTSTR_BYPASS_LLC_LOCKS + KTSTR_CPU_CAP
2755 // before the validation checks. Under the shared env lock, pin
2756 // bypass=1 + cpu_cap unset so build() short-circuits the slot/LLC
2757 // acquire path (no acquire_llc_plan contention; cpu_cap=None avoids
2758 // the bypass+cpu_cap bail), leaving the asserted error the only outcome.
2759 let _l = lock_env();
2760 let _g = EnvVarGuard::set(crate::KTSTR_BYPASS_LLC_LOCKS_ENV, "1");
2761 let _c = EnvVarGuard::remove(crate::KTSTR_CPU_CAP_ENV);
2762 let entry = KtstrTestEntry {
2763 name: "vmb_kernel_path",
2764 ..KtstrTestEntry::DEFAULT
2765 };
2766 let exe = crate::resolve_current_exe().unwrap();
2767 let missing_kernel =
2768 PathBuf::from("/nonexistent/build_vm_builder_base_test_kernel.bzImage");
2769 let result = build_vm_builder_base(
2770 &entry,
2771 &missing_kernel,
2772 &exe,
2773 None,
2774 &[],
2775 crate::vmm::topology::Topology::new(1, 1, 1, 1),
2776 256,
2777 "",
2778 &["run".to_string()],
2779 true,
2780 )
2781 .build();
2782 // `KtstrVm` does not implement Debug, so `.unwrap_err()` is not
2783 // available — collapse Ok into a panic to extract the error by hand.
2784 let err = match result {
2785 Ok(_) => panic!("builder.build() unexpectedly succeeded for missing kernel"),
2786 Err(e) => e,
2787 };
2788 let msg = format!("{err}");
2789 assert!(
2790 msg.contains("kernel not found"),
2791 "expected kernel not found error, got: {msg}",
2792 );
2793 assert!(
2794 msg.contains("build_vm_builder_base_test_kernel"),
2795 "expected the fake kernel path to appear in the error, got: {msg}",
2796 );
2797 }
2798
2799 /// A zero-`llcs` topology is forwarded to the builder and surfaces
2800 /// as a validation error. Proves `topology()` is wired through.
2801 #[test]
2802 fn build_vm_builder_base_propagates_topology_validation() {
2803 // See build_vm_builder_base_propagates_kernel_path: pin bypass=1 +
2804 // cpu_cap unset under the shared env lock so build() short-circuits
2805 // the no-perf slot/LLC path and the asserted error is deterministic.
2806 let _l = lock_env();
2807 let _g = EnvVarGuard::set(crate::KTSTR_BYPASS_LLC_LOCKS_ENV, "1");
2808 let _c = EnvVarGuard::remove(crate::KTSTR_CPU_CAP_ENV);
2809 let entry = KtstrTestEntry {
2810 name: "vmb_topology",
2811 ..KtstrTestEntry::DEFAULT
2812 };
2813 let exe = crate::resolve_current_exe().unwrap();
2814 let bad_topology = crate::vmm::topology::Topology {
2815 llcs: 0,
2816 cores_per_llc: 1,
2817 threads_per_core: 1,
2818 numa_nodes: 1,
2819 nodes: None,
2820 distances: None,
2821 llc_cores: None,
2822 };
2823 let result = build_vm_builder_base(
2824 &entry,
2825 &exe,
2826 &exe,
2827 None,
2828 &[],
2829 bad_topology,
2830 256,
2831 "",
2832 &["run".to_string()],
2833 true,
2834 )
2835 .build();
2836 let err = match result {
2837 Ok(_) => panic!("builder.build() unexpectedly succeeded for zero-llcs topology"),
2838 Err(e) => e,
2839 };
2840 let msg = format!("{err}");
2841 assert!(
2842 msg.contains("llcs must be > 0"),
2843 "expected topology validation error, got: {msg}",
2844 );
2845 }
2846
2847 /// An optional scheduler binary is attached when `Some(path)`
2848 /// is supplied, surfacing as a "scheduler binary not found"
2849 /// error when the path is missing.
2850 #[test]
2851 fn build_vm_builder_base_propagates_scheduler_binary() {
2852 // See build_vm_builder_base_propagates_kernel_path: pin bypass=1 +
2853 // cpu_cap unset under the shared env lock so build() short-circuits
2854 // the no-perf slot/LLC path and the asserted error is deterministic.
2855 let _l = lock_env();
2856 let _g = EnvVarGuard::set(crate::KTSTR_BYPASS_LLC_LOCKS_ENV, "1");
2857 let _c = EnvVarGuard::remove(crate::KTSTR_CPU_CAP_ENV);
2858 let entry = KtstrTestEntry {
2859 name: "vmb_scheduler",
2860 ..KtstrTestEntry::DEFAULT
2861 };
2862 let exe = crate::resolve_current_exe().unwrap();
2863 let missing_scheduler = PathBuf::from("/nonexistent/build_vm_builder_base_test_scheduler");
2864 let result = build_vm_builder_base(
2865 &entry,
2866 &exe,
2867 &exe,
2868 Some(&missing_scheduler),
2869 &[],
2870 crate::vmm::topology::Topology::new(1, 1, 1, 1),
2871 256,
2872 "",
2873 &["run".to_string()],
2874 true,
2875 )
2876 .build();
2877 let err = match result {
2878 Ok(_) => panic!("builder.build() unexpectedly succeeded for missing scheduler"),
2879 Err(e) => e,
2880 };
2881 let msg = format!("{err}");
2882 assert!(
2883 msg.contains("scheduler binary not found"),
2884 "expected scheduler binary error, got: {msg}",
2885 );
2886 assert!(
2887 msg.contains("build_vm_builder_base_test_scheduler"),
2888 "expected the fake scheduler path to appear, got: {msg}",
2889 );
2890 }
2891
2892 // -- vm_timeout_from_entry tests --
2893
2894 // The Tier-3 dead-man deadline is `base + vm_boot_headroom(vcpus) *
2895 // DEADMAN_HEADROOM_MULT`; the headroom no longer scales by the host
2896 // overcommit ratio, so these are host-cpuset-independent (no pin).
2897
2898 #[test]
2899 fn vm_timeout_from_entry_uses_watchdog_when_largest() {
2900 // DEFAULT topology = 2 vCPUs → vm_boot_headroom(2) = 20.3 s ×3 =
2901 // 60.9 s. base = max(60s, 30s, 1s) = 60s → 120.9 s.
2902 let entry = KtstrTestEntry {
2903 name: "wdog",
2904 watchdog_timeout: Duration::from_secs(60),
2905 duration: Duration::from_secs(30),
2906 ..KtstrTestEntry::DEFAULT
2907 };
2908 assert_eq!(
2909 vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
2910 Duration::from_millis(120_900)
2911 );
2912 }
2913
2914 #[test]
2915 fn vm_timeout_from_entry_uses_duration_when_largest() {
2916 let entry = KtstrTestEntry {
2917 name: "dur",
2918 watchdog_timeout: Duration::from_secs(5),
2919 duration: Duration::from_secs(120),
2920 ..KtstrTestEntry::DEFAULT
2921 };
2922 // base = max(5s, 120s, 1s) = 120s; headroom(2)×3 = 60.9 s.
2923 assert_eq!(
2924 vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
2925 Duration::from_millis(180_900)
2926 );
2927 }
2928
2929 #[test]
2930 fn vm_timeout_from_entry_floor_when_both_small() {
2931 // base floors at 1 s; headroom(2)×3 = 60.9 s → 61.9 s.
2932 let entry = KtstrTestEntry {
2933 name: "tiny",
2934 watchdog_timeout: Duration::from_millis(10),
2935 duration: Duration::from_millis(50),
2936 ..KtstrTestEntry::DEFAULT
2937 };
2938 assert_eq!(
2939 vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
2940 Duration::from_millis(61_900)
2941 );
2942 }
2943
2944 #[test]
2945 fn vm_timeout_from_default_entry() {
2946 // DEFAULT watchdog = 5 s, duration = 12 s → base = 12 s.
2947 // headroom(2)×3 = 60.9 s → 72.9 s total.
2948 let entry = KtstrTestEntry {
2949 name: "default",
2950 ..KtstrTestEntry::DEFAULT
2951 };
2952 assert_eq!(
2953 vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
2954 Duration::from_millis(72_900)
2955 );
2956 }
2957
2958 #[test]
2959 fn vm_timeout_from_entry_scales_headroom_with_topology() {
2960 // A reported case: numa=1, llcs=7, cores=9, threads=2 → 126 vCPUs.
2961 // vm_boot_headroom(126) = 38.9 s ×3 = 116.7 s. base = max(5 s
2962 // watchdog, 12 s duration, 1 s) = 12 s → total = 128.7 s.
2963 // Pins the `entry.topology.total_cpus()` → `vm_boot_headroom`
2964 // wiring; the flat ×3 headroom is host-cpuset-independent.
2965 let entry = KtstrTestEntry {
2966 name: "large_topo",
2967 topology: crate::vmm::topology::Topology {
2968 llcs: 7,
2969 cores_per_llc: 9,
2970 threads_per_core: 2,
2971 numa_nodes: 1,
2972 nodes: None,
2973 distances: None,
2974 llc_cores: None,
2975 },
2976 ..KtstrTestEntry::DEFAULT
2977 };
2978 assert_eq!(
2979 vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
2980 Duration::from_millis(128_700)
2981 );
2982 }
2983
2984 #[test]
2985 fn vm_timeout_from_entry_scales_on_booted_not_declared_vcpus() {
2986 // Under a TopoOverride the VM boots a different vCPU count than
2987 // entry.topology declares; the boot-headroom deadline must scale
2988 // to the BOOTED count passed in, not entry.topology. A default
2989 // 2-vCPU entry "booted" at 126 vCPUs must get the 126-vCPU
2990 // headroom (128.7 s, matching the declared-126 case above), not
2991 // the declared 2-vCPU headroom (72.9 s). The declared-vs-booted
2992 // gap is otherwise untested — every other vm_timeout test passes
2993 // entry.topology.total_cpus() (declared == booted).
2994 let entry = KtstrTestEntry {
2995 name: "booted_override",
2996 ..KtstrTestEntry::DEFAULT
2997 };
2998 assert_eq!(
2999 vm_timeout_from_entry(&entry, 126),
3000 Duration::from_millis(128_700),
3001 );
3002 assert_eq!(
3003 vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
3004 Duration::from_millis(72_900),
3005 );
3006 assert_ne!(
3007 vm_timeout_from_entry(&entry, 126),
3008 vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
3009 "the deadline must key on the booted count, not the declared entry.topology",
3010 );
3011 }
3012
3013 // -- overcommit_ratio / oversub-scaled vm_timeout --
3014
3015 #[test]
3016 fn overcommit_ratio_floors_at_one_for_fitting_host() {
3017 // vCPUs <= allowed → not oversubscribed → 1.0 (never < 1).
3018 assert_eq!(overcommit_ratio(8, 192, None), 1.0);
3019 assert_eq!(overcommit_ratio(192, 192, None), 1.0);
3020 }
3021
3022 #[test]
3023 fn overcommit_ratio_auto_collapse_uses_allowed_cpuset() {
3024 // No explicit cpu_budget: the vCPU threads collapse onto the
3025 // whole allowed cpuset. 256 vCPUs on 192 allowed = the CI
3026 // wide-SMP case (~1.33x).
3027 let r = overcommit_ratio(256, 192, None);
3028 assert!((r - 256.0 / 192.0).abs() < 1e-9, "got {r}");
3029 }
3030
3031 #[test]
3032 fn overcommit_ratio_explicit_budget_collapses_onto_min_budget_allowed() {
3033 // Explicit cpu_budget caps the host CPUs the vCPU threads land
3034 // on (the deliberate _overcommit test): 256 / min(64, 192) = 4x.
3035 assert_eq!(overcommit_ratio(256, 192, Some(64)), 4.0);
3036 // A budget wider than the allowed set clamps to allowed.
3037 let r = overcommit_ratio(256, 192, Some(1000));
3038 assert!((r - 256.0 / 192.0).abs() < 1e-9, "got {r}");
3039 }
3040
3041 #[test]
3042 fn overcommit_ratio_guards_empty_cpuset() {
3043 // An unenumerable cpuset (allowed_cpus = 0) must not divide by
3044 // zero — treat it as a 1-CPU host.
3045 assert_eq!(overcommit_ratio(8, 0, None), 8.0);
3046 }
3047
3048 #[test]
3049 fn overcommit_skip_reason_skips_severe_auto_collapse() {
3050 // 256 vCPUs auto-collapse onto 8 host CPUs = 32x ≥ 6x → skip.
3051 // (boot-only path: expect_auto_repro = false.)
3052 let r = overcommit_skip_reason(256, 8, None, false);
3053 assert!(
3054 r.as_deref()
3055 .is_some_and(|m| m.contains("host topology insufficient")),
3056 "32x auto-collapse must skip with the typed reason, got {r:?}",
3057 );
3058 }
3059
3060 #[test]
3061 fn overcommit_skip_reason_runs_ci_wide_smp_ratio() {
3062 // 256 vCPUs on a 192-CPU CI runner = 1.33x < 6x → RUNS (None),
3063 // so wide-SMP boot is validated there, never masked.
3064 assert_eq!(overcommit_skip_reason(256, 192, None, false), None);
3065 }
3066
3067 #[test]
3068 fn overcommit_skip_reason_never_skips_explicit_budget() {
3069 // An explicit cpu_budget is a deliberate oversubscription opt-in
3070 // (contention testing): even 256 vCPUs on 8 host CPUs runs.
3071 assert_eq!(overcommit_skip_reason(256, 8, Some(4), false), None);
3072 }
3073
3074 #[test]
3075 fn overcommit_skip_reason_runs_on_empty_cpuset() {
3076 // An unenumerable cpuset (allowed = 0) cannot compute a ratio →
3077 // does not skip; the overcommit warning is the sole signal there.
3078 assert_eq!(overcommit_skip_reason(256, 0, None, false), None);
3079 }
3080
3081 #[test]
3082 fn overcommit_skip_reason_boundary_is_inclusive_at_cap() {
3083 // ≥ cap skips, just-below runs. 48 vCPUs on 8 = exactly 6.0x → skip;
3084 // 47 on 8 = 5.875x < 6.0 → run. (boot-only path.)
3085 assert!(overcommit_skip_reason(48, 8, None, false).is_some());
3086 assert_eq!(overcommit_skip_reason(47, 8, None, false), None);
3087 }
3088
3089 #[test]
3090 fn overcommit_skip_reason_expect_auto_repro_uses_stricter_cap() {
3091 // The expect_auto_repro inversion chain skips at a much lower
3092 // ratio (EXPECT_AUTO_REPRO_SKIP_RATIO = 2.0x) than a boot-only
3093 // wide test. Pins the failing CI case: 256 vCPUs on a 96-CPU host
3094 // = 2.67x.
3095 // - 2.67x WITH expect_auto_repro -> SKIP (the two-VM wprof chain
3096 // cannot run cleanly under that time-slicing).
3097 let skip = overcommit_skip_reason(256, 96, None, true);
3098 assert!(
3099 skip.as_deref().is_some_and(
3100 |m| m.contains("host topology insufficient") && m.contains("expect_auto_repro")
3101 ),
3102 "2.67x with expect_auto_repro must skip naming the chain, got {skip:?}",
3103 );
3104 // - same 2.67x WITHOUT expect_auto_repro -> RUNS (a single-VM
3105 // wide-SMP boot test still validates boot at 2.67x < 6.0x).
3106 assert_eq!(overcommit_skip_reason(256, 96, None, false), None);
3107 // - the 192-CPU design-target runner (256/192 = 1.33x) RUNS the
3108 // auto-repro hop even with expect_auto_repro (1.33x < 2.0x), so
3109 // the >255 inversion is still validated there.
3110 assert_eq!(overcommit_skip_reason(256, 192, None, true), None);
3111 // - an explicit cpu_budget stays a deliberate opt-in: no skip
3112 // even with expect_auto_repro.
3113 assert_eq!(overcommit_skip_reason(256, 8, Some(4), true), None);
3114 // - boundary: exactly 2.0x with expect_auto_repro skips (>= is
3115 // inclusive); just below runs.
3116 assert!(overcommit_skip_reason(16, 8, None, true).is_some());
3117 assert_eq!(overcommit_skip_reason(15, 8, None, true), None);
3118 }
3119
3120 #[test]
3121 fn vm_timeout_headroom_is_flat_deadman_mult() {
3122 // Tier-3 dead-man: the headroom term is a FLAT
3123 // vm_boot_headroom(vcpus) × DEADMAN_HEADROOM_MULT, with NO host
3124 // overcommit scaling. 256 vCPUs (16 LLCs × 16 cores):
3125 // vm_boot_headroom(256) = 58.4 s ×3 = 175.2 s; base = max(5 s
3126 // watchdog, 12 s duration, 1 s) = 12 s → 187.2 s. The old path
3127 // multiplied this headroom by the host overcommit ratio; it no
3128 // longer does (Tier-1/2 absorb a loaded host), so the value is
3129 // independent of the host cpuset.
3130 let entry = KtstrTestEntry {
3131 name: "flat",
3132 topology: crate::vmm::topology::Topology {
3133 llcs: 16,
3134 cores_per_llc: 16,
3135 threads_per_core: 1,
3136 numa_nodes: 1,
3137 nodes: None,
3138 distances: None,
3139 llc_cores: None,
3140 },
3141 ..KtstrTestEntry::DEFAULT
3142 };
3143 // 12_000 + 58_400 × 3 = 187_200 ms.
3144 assert_eq!(
3145 vm_timeout_from_entry(&entry, entry.topology.total_cpus()),
3146 Duration::from_millis(187_200)
3147 );
3148 }
3149
3150 #[test]
3151 fn vm_timeout_headroom_does_not_scale_with_overcommit() {
3152 // The deadline reads no host cpuset: the headroom above `base` is
3153 // EXACTLY vm_boot_headroom(vcpus) × DEADMAN_HEADROOM_MULT for any
3154 // vcpu count, so an oversubscribed host cannot lengthen it. Pins
3155 // the structural shape (base = 12 s = max(5 s wdog, 12 s dur, 1 s)
3156 // for a DEFAULT entry).
3157 let entry = KtstrTestEntry {
3158 name: "no_oversub",
3159 ..KtstrTestEntry::DEFAULT
3160 };
3161 let base = Duration::from_secs(12);
3162 for vcpus in [2u32, 64, 128, 256] {
3163 assert_eq!(
3164 vm_timeout_from_entry(&entry, vcpus) - base,
3165 vm_boot_headroom(vcpus) * DEADMAN_HEADROOM_MULT,
3166 "headroom must be the flat dead-man term at {vcpus} vCPUs",
3167 );
3168 }
3169 }
3170
3171 #[test]
3172 fn verifier_vm_timeout_is_flat_deadman() {
3173 // Verifier Tier-3 dead-man: VERIFIER_BASE_TIMEOUT (120 s) plus a
3174 // FLAT vm_boot_headroom(vcpus) × DEADMAN_HEADROOM_MULT, no host
3175 // overcommit scaling. 128 vCPUs: vm_boot_headroom(128) = 10 s
3176 // kernel init + (10_000 + 128×150 = 29_200 ms) sys_rdy = 39.2 s
3177 // ×3 = 117.6 s → 237.6 s. The old flat 120 s left ZERO boot
3178 // headroom for exactly this shape — the mid-attach VM-timeout
3179 // class from the scx verifier sweep.
3180 assert_eq!(verifier_vm_timeout(128), Duration::from_millis(237_600));
3181 // Structural: the headroom above the base is exactly the flat
3182 // dead-man term for any vcpu count (no cpuset read).
3183 for vcpus in [2u32, 128, 256] {
3184 assert_eq!(
3185 verifier_vm_timeout(vcpus) - VERIFIER_BASE_TIMEOUT,
3186 vm_boot_headroom(vcpus) * DEADMAN_HEADROOM_MULT,
3187 );
3188 }
3189 // The worst-case verifier deadline (widest realistic 256-vCPU
3190 // preset) plus the extend-only attach-reset extension must still
3191 // fit the 240s x 2 = 480s nextest verifier override.
3192 assert!(
3193 verifier_vm_timeout(256) + VERIFIER_WORKLOAD_BUDGET < Duration::from_secs(480),
3194 "worst-case verifier deadline (incl. attach-reset extension) \
3195 must fit the 240s x 2 nextest override",
3196 );
3197 }
3198
3199 // -- sys_rdy_budget_ms / vm_boot_headroom --
3200
3201 #[test]
3202 fn sys_rdy_budget_ms_base_plus_linear_per_vcpu() {
3203 // Additive: 10_000 ms base + vcpus × 150. Every topology gets
3204 // the base PLUS its per-vCPU term — no dead floor below 67
3205 // vCPUs (the bug that gave a 64-vCPU VM the same 10 s as a
3206 // 1-vCPU VM).
3207 assert_eq!(sys_rdy_budget_ms(1), 10_150);
3208 assert_eq!(sys_rdy_budget_ms(32), 14_800);
3209 assert_eq!(sys_rdy_budget_ms(66), 19_900);
3210 }
3211
3212 #[test]
3213 fn sys_rdy_budget_ms_scales_linearly_in_band() {
3214 // 10_000 ms base + vcpus × 150, in the band below the 90 s cap.
3215 assert_eq!(sys_rdy_budget_ms(67), 20_050);
3216 // The 126-vCPU case lands at 28.9 s.
3217 assert_eq!(sys_rdy_budget_ms(126), 28_900);
3218 // 256-vCPU wide-SMP gets its FULL additive budget (48.4 s) — the
3219 // case the old 30 s cap truncated to 30 s, starving the boot.
3220 assert_eq!(sys_rdy_budget_ms(256), 48_400);
3221 }
3222
3223 #[test]
3224 fn sys_rdy_budget_ms_caps_at_ninety_seconds() {
3225 // The 512-vCPU MAX_VCPUS topology gets its full additive budget
3226 // (10_000 + 512×150 = 86_800 ms), comfortably under the cap.
3227 assert_eq!(sys_rdy_budget_ms(512), 86_800);
3228 // 533 vCPUs is the last under the 90 s cap (10_000 + 533×150 =
3229 // 89_950); 534 is the first clipped (10_000 + 534×150 = 90_100
3230 // → 90_000). Only pathological >533-vCPU counts clip.
3231 assert_eq!(sys_rdy_budget_ms(533), 89_950);
3232 assert_eq!(sys_rdy_budget_ms(534), 90_000);
3233 assert_eq!(sys_rdy_budget_ms(u32::MAX), 90_000);
3234 }
3235
3236 #[test]
3237 fn sys_rdy_budget_ms_zero_returns_base() {
3238 // Guest fallback when /sys/devices/system/cpu/online is missing:
3239 // 0 vCPUs → the bare 10_000 ms base (no per-vCPU term).
3240 assert_eq!(sys_rdy_budget_ms(0), 10_000);
3241 }
3242
3243 #[test]
3244 fn vm_boot_headroom_is_ten_plus_sys_rdy_budget() {
3245 // KERNEL_INIT_HEADROOM (10 s) + sys_rdy_budget_ms(vcpus).
3246 assert_eq!(vm_boot_headroom(1), Duration::from_millis(20_150));
3247 assert_eq!(vm_boot_headroom(126), Duration::from_millis(38_900));
3248 // 256-vCPU wide-SMP: 10 s + 48.4 s = 58.4 s. Host overcommit
3249 // does not change this flat deadman component.
3250 assert_eq!(vm_boot_headroom(256), Duration::from_millis(58_400));
3251 // 512-vCPU MAX_VCPUS budget (86.8 s) → 96.8 s headroom, uncapped
3252 // under the 90 s ceiling.
3253 assert_eq!(vm_boot_headroom(512), Duration::from_millis(96_800));
3254 }
3255
3256 // -- phase_cpu_budget_ns / phase_wall_backstop_ns --
3257
3258 #[test]
3259 fn phase_cpu_budget_ns_boot_reuses_vm_boot_headroom() {
3260 const S: u64 = 1_000_000_000;
3261 // Boot consumes the same allowance as the VM deadline. The
3262 // remaining phases stay flat against max-per-vCPU evidence.
3263 assert_eq!(phase_cpu_budget_ns(0, 1), 20_150_000_000);
3264 assert_eq!(phase_cpu_budget_ns(0, 240), 56 * S);
3265 assert_eq!(
3266 phase_cpu_budget_ns(0, 240),
3267 vm_boot_headroom(240).as_nanos() as u64,
3268 );
3269 assert_eq!(phase_cpu_budget_ns(1, 1), 35 * S);
3270 assert_eq!(phase_cpu_budget_ns(1, 240), 35 * S);
3271 assert_eq!(phase_cpu_budget_ns(2, 1), 8 * S);
3272 assert_eq!(phase_cpu_budget_ns(2, 240), 8 * S);
3273 assert_eq!(phase_cpu_budget_ns(4, 1), 8 * S);
3274 assert_eq!(phase_cpu_budget_ns(4, 240), 8 * S);
3275 }
3276
3277 #[test]
3278 fn phase_cpu_budget_ns_body_and_unknown_are_sentinel() {
3279 // Body (3): Tier-1 structurally off — the sentinel makes any
3280 // `cpu > budget` comparison unsatisfiable.
3281 assert_eq!(phase_cpu_budget_ns(3, 240), u64::MAX);
3282 // Unknown phase ids never carry a killable budget.
3283 assert_eq!(phase_cpu_budget_ns(5, 240), u64::MAX);
3284 assert_eq!(phase_cpu_budget_ns(u8::MAX, 240), u64::MAX);
3285 }
3286
3287 #[test]
3288 fn phase_wall_backstop_ns_values_sit_above_in_band_deadlines() {
3289 const S: u64 = 1_000_000_000;
3290 assert_eq!(phase_wall_backstop_ns(0, 1), 45 * S);
3291 assert_eq!(phase_wall_backstop_ns(0, 240), 61 * S);
3292 assert_eq!(phase_wall_backstop_ns(0, 512), 101_800_000_000);
3293 for vcpus in [1, 240, 512] {
3294 assert!(
3295 phase_wall_backstop_ns(0, vcpus) > vm_boot_headroom(vcpus).as_nanos() as u64,
3296 "Boot Tier-2 must sit after the authoritative allowance at {vcpus} vCPUs",
3297 );
3298 }
3299 // Attach backstop must clear the host cold-BTF phase-1 budget.
3300 assert_eq!(phase_wall_backstop_ns(1, 1), 40 * S);
3301 assert!(phase_wall_backstop_ns(1, 512) > COLD_BTF_PHASE1_BUDGET.as_nanos() as u64);
3302 // Dispatch backstop must clear the guest probe's 30s cap.
3303 assert_eq!(phase_wall_backstop_ns(2, 1), 35 * S);
3304 assert_eq!(phase_wall_backstop_ns(4, 1), 15 * S);
3305 }
3306
3307 #[test]
3308 fn phase_wall_backstop_ns_body_and_unknown_are_sentinel() {
3309 // Body (3) and unknown ids: Tier-2 structurally off.
3310 assert_eq!(phase_wall_backstop_ns(3, 240), u64::MAX);
3311 assert_eq!(phase_wall_backstop_ns(5, 240), u64::MAX);
3312 assert_eq!(phase_wall_backstop_ns(u8::MAX, 240), u64::MAX);
3313 }
3314
3315 /// Two calls to `content_hash` with the same input must return
3316 /// the same u64. Pins the within-process determinism invariant
3317 /// against a future regression that swaps in a per-call-seeded
3318 /// hasher — e.g. `std::hash::RandomState::new().build_hasher()`,
3319 /// which increments its keys per call within a process, or any
3320 /// time/thread-id-seeded scheme. Note: swapping to std's
3321 /// `DefaultHasher::new()` would NOT regress this test —
3322 /// `DefaultHasher` is itself `SipHasher13::new_with_keys(0, 0)`
3323 /// and therefore deterministic; the cross-rustc-version
3324 /// stability regression class is caught by the value-pin
3325 /// follow-up, not this assertion.
3326 #[test]
3327 fn content_hash_is_deterministic_across_calls() {
3328 let input = "scheduler config payload";
3329 assert_eq!(content_hash(input), content_hash(input));
3330 }
3331
3332 /// Distinct inputs must produce distinct hashes. Catches a trivial
3333 /// regression (constant-returning hasher) that the determinism
3334 /// test alone would silently accept.
3335 #[test]
3336 fn content_hash_differs_for_distinct_inputs() {
3337 assert_ne!(content_hash("alpha"), content_hash("beta"));
3338 }
3339
3340 /// Cross-toolchain stability pin: every `content_hash` output must
3341 /// equal the SipHasher13(keys=0,0) value emitted at commit time.
3342 /// Pins the algorithm choice — a future swap to a different
3343 /// stable hasher (e.g. xxhash, fxhash) would silently regenerate
3344 /// every content-addressed cache filename on disk, breaking cache
3345 /// hit rates without surfacing as a failed test. The companion
3346 /// `content_hash_is_deterministic_across_calls` pin guards
3347 /// within-process determinism; this pin guards cross-process /
3348 /// cross-toolchain / cross-machine stability.
3349 #[test]
3350 fn content_hash_value_pin() {
3351 // SipHasher13(keys=0,0) over the four corpora below. If any
3352 // assertion fails, the algorithm or its seeding changed —
3353 // STOP. `content_hash` names the inline-config tempfile in
3354 // `config_content_parts` at src/test_support/runtime.rs and
3355 // the export-config tempfile in `export.rs`; flipping the
3356 // hashes silently regenerates those filenames on every
3357 // process, breaking any future scheme that tries to dedup
3358 // across runs and breaking intra-run reproducibility if a
3359 // caller comes to depend on stable byte equality across
3360 // identical inputs. Update only after intentional algorithm
3361 // migration. The four corpora — empty + two short ASCII +
3362 // one realistic config payload — span the cases the
3363 // algorithm needs to handle correctly.
3364 assert_eq!(content_hash(""), 0x30406ea523c53def);
3365 assert_eq!(content_hash("alpha"), 0x3c87f3c3317bd39a);
3366 assert_eq!(content_hash("beta"), 0xbb8fd2aa1487d7ac);
3367 assert_eq!(content_hash("scheduler config payload"), 0xc678971ba48d5f80);
3368 }
3369
3370 /// Per-content-hash inline-config files MUST land inside the
3371 /// per-process `scratch_dir()` subtree, NOT bare
3372 /// `std::env::temp_dir()`. The 0o700 process-owned subdirectory
3373 /// blocks the cross-uid symlink-replacement attack on
3374 /// predictable content-addressed filenames in shared `/tmp`. A
3375 /// future "simplification" that reverts the path to bare
3376 /// `std::env::temp_dir().join(...)` silently restores the
3377 /// attack surface; this test fails loudly first.
3378 #[test]
3379 fn config_content_parts_writes_inside_process_scratch_dir() {
3380 use crate::assert::Assert;
3381 use crate::scenario::Ctx;
3382 use crate::test_support::entry::{
3383 KtstrTestEntry, Scheduler, SchedulerSpec, TopologyConstraints,
3384 };
3385 use crate::vmm::topology::Topology;
3386
3387 static SCHED: Scheduler = Scheduler {
3388 name: "config_parts_test_sched",
3389 binary: SchedulerSpec::Discover("nope"),
3390 sysctls: &[],
3391 kargs: &[],
3392 assert: Assert::NO_OVERRIDES,
3393 cgroup_parent: None,
3394 sched_args: &[],
3395 topology: Topology {
3396 llcs: 1,
3397 cores_per_llc: 1,
3398 threads_per_core: 1,
3399 numa_nodes: 1,
3400 nodes: None,
3401 distances: None,
3402 llc_cores: None,
3403 },
3404 constraints: TopologyConstraints::DEFAULT,
3405 config_file: None,
3406 config_file_def: Some(("--config={file}", "/include-files/p.json")),
3407 kernels: &[],
3408 verifier_exclude_topologies: &[],
3409 manifest_dir: env!("CARGO_MANIFEST_DIR"),
3410 };
3411 fn func(_: &Ctx) -> anyhow::Result<crate::assert::AssertResult> {
3412 Ok(crate::assert::AssertResult::pass())
3413 }
3414 let entry = KtstrTestEntry {
3415 name: "scratch_dir_path_test",
3416 func,
3417 scheduler: &SCHED,
3418 config_content: Some("{\"sentinel\":42}"),
3419 ..KtstrTestEntry::DEFAULT
3420 };
3421 let (_, host_path, _, _) =
3422 config_content_parts(&entry).expect("config_content_parts returns Some");
3423 assert!(
3424 host_path.starts_with(scratch_dir()),
3425 "config tempfile must live inside the process-owned scratch dir, \
3426 not bare std::env::temp_dir(): got host_path={host_path:?}, \
3427 scratch_dir={:?}",
3428 scratch_dir()
3429 );
3430 }
3431
3432 /// Two same-content calls produce the SAME canonical path
3433 /// (content-addressed naming idempotence). Callers using the
3434 /// returned PathBuf for downstream dedup decisions rely on this
3435 /// — a regression that breaks the content-hash → path mapping
3436 /// would silently spam the scratch dir with per-call distinct
3437 /// names instead of reusing the canonical entry.
3438 #[test]
3439 fn config_content_parts_same_content_same_canonical_path() {
3440 use crate::assert::Assert;
3441 use crate::scenario::Ctx;
3442 use crate::test_support::entry::{
3443 KtstrTestEntry, Scheduler, SchedulerSpec, TopologyConstraints,
3444 };
3445 use crate::vmm::topology::Topology;
3446
3447 static SCHED: Scheduler = Scheduler {
3448 name: "config_parts_idempotent_sched",
3449 binary: SchedulerSpec::Discover("nope"),
3450 sysctls: &[],
3451 kargs: &[],
3452 assert: Assert::NO_OVERRIDES,
3453 cgroup_parent: None,
3454 sched_args: &[],
3455 topology: Topology {
3456 llcs: 1,
3457 cores_per_llc: 1,
3458 threads_per_core: 1,
3459 numa_nodes: 1,
3460 nodes: None,
3461 distances: None,
3462 llc_cores: None,
3463 },
3464 constraints: TopologyConstraints::DEFAULT,
3465 config_file: None,
3466 config_file_def: Some(("--config={file}", "/include-files/p.json")),
3467 kernels: &[],
3468 verifier_exclude_topologies: &[],
3469 manifest_dir: env!("CARGO_MANIFEST_DIR"),
3470 };
3471 fn func(_: &Ctx) -> anyhow::Result<crate::assert::AssertResult> {
3472 Ok(crate::assert::AssertResult::pass())
3473 }
3474 let entry = KtstrTestEntry {
3475 name: "idempotent_path_test",
3476 func,
3477 scheduler: &SCHED,
3478 config_content: Some("{\"idempotent\":true}"),
3479 ..KtstrTestEntry::DEFAULT
3480 };
3481 let (_, p1, _, _) = config_content_parts(&entry).expect("first call returns Some");
3482 let (_, p2, _, _) = config_content_parts(&entry).expect("second call returns Some");
3483 assert_eq!(
3484 p1, p2,
3485 "same content_content -> same canonical path; content-addressed naming \
3486 must be idempotent across calls"
3487 );
3488 // The filename component encodes the content hash via the
3489 // `ktstr-config-{hash:016x}.json` template; verify the prefix
3490 // so a future filename-template change is caught.
3491 let name = p1.file_name().and_then(|n| n.to_str()).unwrap_or("");
3492 assert!(
3493 name.starts_with("ktstr-config-") && name.ends_with(".json"),
3494 "canonical filename must follow `ktstr-config-{{hash}}.json` template, got: {name}"
3495 );
3496 }
3497}