ktstr/test_support/entry_validate.rs
1//! `KtstrTestEntry::validate` and its phase helpers, split out of
2//! `entry.rs` to keep that file under its grandfathered file-size
3//! ceiling while the validator stays decomposed into sub-200-line
4//! phases. These are inherent methods on
5//! [`crate::test_support::KtstrTestEntry`]; its fields are `pub`, so a
6//! sibling-module impl has full access.
7
8impl crate::test_support::KtstrTestEntry {
9 /// Reject values that would boot a broken VM or leave assertions
10 /// vacuously passing. The `#[ktstr_test]` proc macro enforces the
11 /// same constraints at compile time for attribute-built entries;
12 /// this method covers directly-constructed entries (library
13 /// callers building `KtstrTestEntry` values to push into
14 /// [`KTSTR_TESTS`](crate::test_support::KTSTR_TESTS) programmatically).
15 ///
16 /// Rules:
17 /// - `name` must be non-empty (empty names collapse into each
18 /// other in nextest output and in sidecar lookups).
19 /// - `name` must not contain `/` or `\` (path separators embed in
20 /// sidecar filenames and nextest test IDs; a separator would
21 /// create a synthetic subdirectory in sidecar output and
22 /// mangle `cargo nextest run -E 'test(name)'` filtering).
23 /// - `memory_mib` must be `> 0` (a VM with zero memory cannot boot).
24 /// - `duration` must be `> 0` (a zero-duration run never exercises
25 /// the scheduler and produces no telemetry).
26 pub fn validate(&self) -> anyhow::Result<()> {
27 self.validate_basics_and_staging()?;
28 self.validate_mode_flags()?;
29 self.validate_snapshots()?;
30 self.validate_config_and_topology()?;
31 self.validate_perf_delta_assertions()?;
32 Ok(())
33 }
34
35 /// Validate name shape, memory/duration sizing, payload/host_only
36 /// device conflicts, and staged_schedulers name uniqueness.
37 fn validate_basics_and_staging(&self) -> anyhow::Result<()> {
38 if self.name.is_empty() {
39 anyhow::bail!(
40 "KtstrTestEntry.name must be non-empty (empty names \
41 collide in nextest output and sidecar lookups)"
42 );
43 }
44 if self.name.contains('/') || self.name.contains('\\') {
45 anyhow::bail!(
46 "KtstrTestEntry '{}' name must not contain path \
47 separators ('/' or '\\') — they embed in sidecar \
48 filenames and nextest test IDs, creating synthetic \
49 subdirectories in sidecar output and mangling \
50 nextest -E 'test(name)' filtering",
51 self.name,
52 );
53 }
54 if self.memory_mib == 0 {
55 anyhow::bail!(
56 "KtstrTestEntry '{}'.memory_mib must be > 0 (a VM with \
57 zero memory cannot boot)",
58 self.name,
59 );
60 }
61 if self.duration.is_zero() {
62 anyhow::bail!(
63 "KtstrTestEntry '{}'.duration must be > 0 (a zero-duration \
64 run never exercises the scheduler and produces no data \
65 for assertions)",
66 self.name,
67 );
68 }
69 if let Some(p) = self.payload
70 && p.is_scheduler()
71 {
72 anyhow::bail!(
73 "KtstrTestEntry '{}'.payload must be PayloadKind::Binary, \
74 not Scheduler-kind (schedulers belong in the `scheduler` \
75 slot; the `payload` slot is for userspace binaries \
76 composed under the scheduler)",
77 self.name,
78 );
79 }
80 if self.host_only && self.disk.is_some() {
81 anyhow::bail!(
82 "KtstrTestEntry '{}'.host_only=true with disk=Some(..) — \
83 host_only skips the VM boot that owns the virtio-blk \
84 device lifecycle, so the disk would never be attached. \
85 Drop one of host_only or disk.",
86 self.name,
87 );
88 }
89 if self.host_only && !self.networks.is_empty() {
90 anyhow::bail!(
91 "KtstrTestEntry '{}'.host_only=true with networks=[..] — \
92 host_only skips the VM boot that owns the virtio-net \
93 device lifecycle, so the NICs would never be attached. \
94 Drop one of host_only or networks.",
95 self.name,
96 );
97 }
98 // staged_schedulers names must (a) pass the per-name shape
99 // checks (non-empty, no path separators, no NUL bytes, no
100 // leading dot, not a reserved framework slot — see
101 // [`crate::test_support::staged::validate_staged_scheduler_name`])
102 // and (b) be unique within the set AND disjoint from the
103 // boot scheduler's `name`. A collision on either axis would
104 // land two distinct schedulers at the same guest path —
105 // silent overwrite, the second-staged binary clobbering the
106 // first OR shadowing a boot-time framework slot. The
107 // boot-name seed catches the "stage all the schedulers I
108 // might use" misuse (author includes the boot scheduler in
109 // the staged set thinking it's required there too). Bails
110 // here at validate time so the error surfaces ahead of any
111 // VM boot or initramfs construction.
112 let mut seen_names: std::collections::BTreeSet<&'static str> =
113 std::collections::BTreeSet::new();
114 seen_names.insert(self.scheduler.name);
115 let staged_who = format!("KtstrTestEntry '{}'.staged_schedulers", self.name);
116 for staged in self.staged_schedulers {
117 crate::test_support::staged::validate_staged_scheduler_name(&staged_who, staged.name)?;
118 if !seen_names.insert(staged.name) {
119 if staged.name == self.scheduler.name {
120 anyhow::bail!(
121 "KtstrTestEntry '{}'.staged_schedulers cannot include \
122 the boot scheduler '{}' — the boot slot already \
123 stages it. Staged entries are the ADDITIONAL \
124 candidates the test will swap TO via \
125 Op::AttachScheduler / Op::ReplaceScheduler.",
126 self.name,
127 staged.name,
128 );
129 }
130 anyhow::bail!(
131 "KtstrTestEntry '{}'.staged_schedulers has duplicate \
132 Scheduler.name '{}'; each staged scheduler must have \
133 a unique name (the name maps 1:1 to the guest-side \
134 staging path)",
135 self.name,
136 staged.name,
137 );
138 }
139 }
140 Ok(())
141 }
142
143 /// Validate host_only/scheduler, performance/no-perf, and
144 /// cpu_budget mode-flag combinations and the scx_bpf_error matcher
145 /// gate.
146 fn validate_mode_flags(&self) -> anyhow::Result<()> {
147 // Defense-in-depth for the programmatic-construction path
148 // (struct-literal `KtstrTestEntry { .. }` in integration tests,
149 // gauntlet-rewritten entries). The macro at
150 // ktstr-macros/src/lib.rs rejects `host_only = true` paired with
151 // any `scheduler = ...` attribute at compile time, but
152 // programmatic construction bypasses that gate. Match against
153 // `SchedulerSpec::Eevdf` (the value-level marker for the
154 // no-scx-scheduler placeholder) so a struct literal that sets
155 // `scheduler: &SOME_REAL_SCHED` under host_only is caught while
156 // the default `scheduler: &Scheduler::EEVDF` (whose binary is
157 // `SchedulerSpec::Eevdf`) is accepted. The variant-based check
158 // is spec-safe — unlike a pointer-identity check against
159 // `&Scheduler::EEVDF`, which depends on rustc/LLVM's const-
160 // deduplication of `&CONST_EXPR` materializations.
161 if self.host_only
162 && !matches!(
163 self.scheduler.binary,
164 crate::test_support::SchedulerSpec::Eevdf
165 )
166 {
167 anyhow::bail!(
168 "KtstrTestEntry '{}'.host_only=true with scheduler=&{:?} — \
169 host_only skips the VM boot that owns the scheduler \
170 lifecycle, so the declared scheduler would never attach. \
171 Drop one of host_only or scheduler; the host's \
172 currently-active scheduler (default EEVDF when none is \
173 loaded) runs the test under host_only.",
174 self.name,
175 self.scheduler.name,
176 );
177 }
178 if self.performance_mode && self.no_perf_mode {
179 anyhow::bail!(
180 "KtstrTestEntry '{}'.performance_mode=true with \
181 no_perf_mode=true — the two flags are contradictory \
182 (\"I want pinning\" vs. \"I explicitly don't want \
183 pinning\"). Drop one of them.",
184 self.name,
185 );
186 }
187 // `cpu_budget` of zero cannot run a VM. The builder would
188 // otherwise clamp it to 1 (builder.rs effective_cap), silently
189 // running with a budget the author never asked for. Reject
190 // explicitly — mirrors the macro's compile-time reject and the
191 // memory_mib / cleanup_budget_ms zero-rejects in
192 // validate_cross_attr.
193 if self.cpu_budget == Some(0) {
194 anyhow::bail!(
195 "KtstrTestEntry '{}'.cpu_budget=Some(0) — a zero host-CPU \
196 budget cannot run a VM. Use a positive budget, or drop \
197 cpu_budget to auto-size the no-perf mask from the vCPU count \
198 plus service-thread headroom.",
199 self.name,
200 );
201 }
202 // `cpu_budget` is consulted only on the no_perf_mode path
203 // (builder.rs sizes the shared vCPU-thread mask from it). A
204 // budget set without no_perf_mode is a silent no-op — the VM
205 // runs with the default mask and the requested overcommit never
206 // happens, so a contention test would quietly run un-contended.
207 // Reject at validate time (nextest discovery) for the
208 // programmatic-construction path; ktstr-macros enforces the same
209 // gate at compile time for the `#[ktstr_test]` path.
210 if self.cpu_budget.is_some() && !self.no_perf_mode {
211 anyhow::bail!(
212 "KtstrTestEntry '{}'.cpu_budget={:?} with no_perf_mode=false \
213 — cpu_budget sizes the no-perf vCPU-thread mask and is \
214 ignored unless no_perf_mode is set (under performance_mode \
215 vCPUs are pinned 1:1). Set no_perf_mode=true or drop \
216 cpu_budget.",
217 self.name,
218 self.cpu_budget,
219 );
220 }
221 if (self.assert.expect_scx_bpf_error_contains.is_some()
222 || self.assert.expect_scx_bpf_error_matches.is_some())
223 && !self.expect_err
224 {
225 anyhow::bail!(
226 "KtstrTestEntry '{}' sets an scx_bpf_error matcher \
227 (expect_scx_bpf_error_contains or expect_scx_bpf_error_matches) \
228 without expect_err = true — a reproducer matcher narrows \
229 which failure counts as the expected bug and only \
230 applies to expected-error tests. Set expect_err = true \
231 or drop the matcher.",
232 self.name,
233 );
234 }
235 if self.survives_storm && self.expect_err {
236 anyhow::bail!(
237 "KtstrTestEntry '{}' sets both survives_storm and expect_err — \
238 contradictory: survives_storm asserts the run passes with the \
239 scheduler alive, expect_err asserts the run fails. Pick one.",
240 self.name,
241 );
242 }
243 if self.survives_storm && self.expect_auto_repro {
244 anyhow::bail!(
245 "KtstrTestEntry '{}' sets both survives_storm and \
246 expect_auto_repro — contradictory: survives_storm forces a \
247 scheduler-death failure to EXIT_FAIL, expect_auto_repro \
248 inverts a crash-with-repro failure to PASS. Pick one.",
249 self.name,
250 );
251 }
252 if self.survives_storm && !self.scheduler.has_active_scheduling() {
253 anyhow::bail!(
254 "KtstrTestEntry '{}' sets survives_storm with no active scx \
255 scheduler — the kernel default has no scheduler to eject, so \
256 survival is vacuous. Declare a scheduler = ... or drop \
257 survives_storm.",
258 self.name,
259 );
260 }
261 Ok(())
262 }
263
264 /// Validate num_snapshots against the storage cap, host_only, and
265 /// the minimum periodic-capture interval.
266 fn validate_snapshots(&self) -> anyhow::Result<()> {
267 // Periodic snapshots route through SnapshotBridge::store, which
268 // FIFO-evicts at MAX_STORED_SNAPSHOTS. Allowing num_snapshots
269 // past the cap would silently lose the earliest samples — a
270 // periodic run with N=128 today would only retain
271 // periodic_064..periodic_127 in the bridge.
272 let max = crate::scenario::snapshot::MAX_STORED_SNAPSHOTS as u32;
273 if self.num_snapshots > max {
274 anyhow::bail!(
275 "KtstrTestEntry '{}'.num_snapshots={} exceeds \
276 MAX_STORED_SNAPSHOTS={} — the bridge would FIFO-evict \
277 the earliest periodic samples. Lower the count or split \
278 into multiple test entries.",
279 self.name,
280 self.num_snapshots,
281 max,
282 );
283 }
284 if self.num_snapshots > 0 {
285 // host_only skips the VM boot that owns the freeze
286 // coordinator's run-loop. Without that loop there is no
287 // thread to stamp `scenario_start_ns`, no thread to fire
288 // `freeze_and_dispatch(FreezeMode::Capture { gate_on_exit_kind: false })` at each boundary, and no
289 // `SnapshotBridge` plumbed onto a `VmResult` for the
290 // test author to drain post-run. The combination is
291 // unsatisfiable; reject at validate time so a
292 // misconfigured entry surfaces during nextest discovery
293 // rather than as silently-empty bridge results.
294 if self.host_only {
295 anyhow::bail!(
296 "KtstrTestEntry '{}'.host_only=true with \
297 num_snapshots={} > 0 — host_only skips the VM \
298 boot that owns the freeze coordinator's \
299 periodic-capture loop, so no snapshot would \
300 ever fire. Drop one of host_only or \
301 num_snapshots.",
302 self.name,
303 self.num_snapshots,
304 );
305 }
306 // Refuse interval shorter than the minimum useful capture
307 // cadence. Each boundary fire freezes every vCPU, walks
308 // BPF maps, serialises the dump, and writes to the
309 // bridge — under the FREEZE_RENDEZVOUS_TIMEOUT (30 s)
310 // hard ceiling but commonly tens of milliseconds on a
311 // healthy guest. An interval shorter than ~100 ms would
312 // back-to-back the captures with no actual workload
313 // progress between them, defeating the periodic-sampling
314 // purpose. Compute the interval in nanoseconds in u128
315 // to avoid overflow on long durations: the formula
316 // mirrors the run-loop's
317 // `compute_periodic_boundaries_ns` (10 % pre-buffer,
318 // 80 % usable span, divided into N+1 equal intervals).
319 let usable_span_ns = self
320 .duration
321 .as_nanos()
322 .saturating_sub(2u128.saturating_mul(self.duration.as_nanos() / 10));
323 let interval_ns = usable_span_ns / (self.num_snapshots as u128 + 1);
324 const MIN_INTERVAL_NS: u128 = 100 * 1_000_000; // 100 ms
325 if interval_ns < MIN_INTERVAL_NS {
326 anyhow::bail!(
327 "KtstrTestEntry '{}'.num_snapshots={} with \
328 duration={:?} produces a periodic interval of \
329 {} ns ({} ms) — below the 100 ms minimum the \
330 freeze-and-capture path can sustain without \
331 back-to-back firing. Either reduce num_snapshots \
332 or extend duration so 0.8·duration / (N+1) >= 100 ms.",
333 self.name,
334 self.num_snapshots,
335 self.duration,
336 interval_ns,
337 interval_ns / 1_000_000,
338 );
339 }
340 }
341 Ok(())
342 }
343
344 /// Validate scheduler config_file_def/config_content pairing,
345 /// workload-slot payload kinds, and entry/scheduler topology
346 /// constraints.
347 fn validate_config_and_topology(&self) -> anyhow::Result<()> {
348 // Pair `scheduler.config_file_def` with `config_content`. The
349 // `#[ktstr_test]` macro emits a `const _: () = assert!(...)`
350 // block that catches the same mismatch at compile time for
351 // attribute-built entries; this branch covers programmatic
352 // construction (callers building `KtstrTestEntry` values
353 // directly) and surfaces the misconfiguration before VM boot
354 // rather than as a silent missing-`--config` flag.
355 let scheduler_has_def = self.scheduler.config_file_def.is_some();
356 let entry_has_content = self.config_content.is_some();
357 if scheduler_has_def && !entry_has_content {
358 anyhow::bail!(
359 "KtstrTestEntry '{}'.scheduler '{}' declares \
360 `config_file_def` but the entry does not supply \
361 `config_content`; the scheduler binary expects an \
362 inline config and would launch without `--config`. \
363 Set `config = ...` on `#[ktstr_test]` or assign \
364 `config_content` directly.",
365 self.name,
366 self.scheduler.name,
367 );
368 }
369 if !scheduler_has_def && entry_has_content {
370 anyhow::bail!(
371 "KtstrTestEntry '{}'.config_content is set but the \
372 scheduler '{}' does not declare `config_file_def`; \
373 the content would be silently dropped at dispatch. \
374 Remove `config = ...` or add \
375 `config_file_def(arg_template, guest_path)` to the \
376 scheduler.",
377 self.name,
378 self.scheduler.name,
379 );
380 }
381 // Mirror the payload-slot gate for every workload entry. The
382 // `workloads` slot is for userspace binaries composed with
383 // the primary payload under the scheduler; a scheduler-kind
384 // Payload here would be silently ignored at spawn time. The
385 // narrow typo path post-`declare_scheduler!` rollout is
386 // pasting [`Payload::KERNEL_DEFAULT`] (the only Scheduler-kind
387 // Payload still in the prelude) into a `workloads = [...]`
388 // attribute instead of the `scheduler = ...` slot.
389 for (idx, w) in self.workloads.iter().enumerate() {
390 if w.is_scheduler() {
391 anyhow::bail!(
392 "KtstrTestEntry '{}'.workloads[{idx}] (name='{}') must be \
393 PayloadKind::Binary, not Scheduler-kind (schedulers belong \
394 in the `scheduler` slot; the `workloads` slot is for \
395 userspace binaries composed under the scheduler)",
396 self.name,
397 w.name,
398 );
399 }
400 }
401 // Reject inverted topology ranges before they silently filter
402 // every gauntlet preset to zero matches. The per-entry
403 // constraints gate which gauntlet presets the test author wants
404 // to exercise; an inverted bound (e.g. min_numa_nodes=5 with
405 // max_numa_nodes=Some(2)) would yield false on every preset.
406 self.constraints
407 .validate()
408 .map_err(|e| anyhow::anyhow!("KtstrTestEntry '{}'.constraints: {e}", self.name))?;
409 // Same for the scheduler-level constraints, which apply on top
410 // of the per-entry ones. A scheduler whose declared topology
411 // requirements are themselves inverted has the same silent-
412 // filter pathology regardless of what test entries declare.
413 self.scheduler.constraints.validate().map_err(|e| {
414 anyhow::anyhow!(
415 "KtstrTestEntry '{}'.scheduler '{}'.constraints: {e}",
416 self.name,
417 self.scheduler.name
418 )
419 })?;
420 Ok(())
421 }
422
423 /// Validate declared `perf_delta_assertions`. Each assertion is a
424 /// per-test regression gate consulted only under
425 /// `perf-delta --noise-adjust` (the scalar `perf-delta` path warns that
426 /// declared gates were skipped) — inert during a normal `ktstr test` run,
427 /// where the in-VM evaluation never reads it. Two rules:
428 ///
429 /// - Every asserted `metric` must resolve in the metric registry
430 /// (`crate::stats::metric_def`). A typo'd metric name would never
431 /// match a captured field, so the gate would silently never fire:
432 /// the author believes a regression is guarded when nothing is.
433 /// Reject at validate time so the typo surfaces during nextest
434 /// discovery rather than as a phantom-passing perf-delta run.
435 /// - Declaring any assertion requires `performance_mode`. The gate
436 /// tightens the noise threshold on a metric; under no-perf mode the
437 /// vCPU threads share an oversubscribed host-CPU mask, so the
438 /// metric carries scheduling noise the tightened gate would misread
439 /// (false regressions, or a real regression masked by the narrowed
440 /// band). A perf gate is only meaningful on a pinned run. Mirrors
441 /// the `cpu_budget ⇒ no_perf_mode` flag-dependency above.
442 fn validate_perf_delta_assertions(&self) -> anyhow::Result<()> {
443 if self.perf_delta_assertions.is_empty() {
444 return Ok(());
445 }
446 if !self.performance_mode {
447 anyhow::bail!(
448 "KtstrTestEntry '{}' declares perf_delta_assertions but \
449 performance_mode=false — a declared regression gate \
450 tightens the noise threshold on a metric, which is only \
451 meaningful on a pinned (performance_mode) run. Under \
452 no-perf mode the metric carries host-CPU-oversubscription \
453 noise the gate would misread. Set performance_mode=true \
454 or drop the assertions.",
455 self.name,
456 );
457 }
458 let mut seen: std::collections::BTreeSet<(&'static str, Option<u16>)> =
459 std::collections::BTreeSet::new();
460 for a in self.perf_delta_assertions {
461 let metric = a.metric();
462 if crate::stats::metric_def(metric).is_none() {
463 anyhow::bail!(
464 "KtstrTestEntry '{}'.perf_delta_assertions references \
465 unknown metric '{}' — it does not resolve in the \
466 metric registry, so the gate would never match a \
467 captured field and silently never fire. Check the \
468 name against the registry (src/stats/metric.rs \
469 METRICS).",
470 self.name,
471 metric,
472 );
473 }
474 // A render-suppressed rate COMPONENT (the internal numerator/
475 // denominator of a derived rate — e.g. total_cpu_time_sec)
476 // keeps its registry slot for the cross-run re-pool but is never
477 // emitted as a compare finding, so a gate on it can NEVER fire: a
478 // guaranteed-dead gate that would pass this check on name alone.
479 // Reject so the author declares the user-facing rate (e.g.
480 // iteration_rate) rather than its suppressed component.
481 if crate::stats::is_render_suppressed_component(metric) {
482 anyhow::bail!(
483 "KtstrTestEntry '{}'.perf_delta_assertions references \
484 render-suppressed rate component '{}' — it is an internal \
485 numerator/denominator that never surfaces as a compare \
486 finding, so the gate could never fire. Declare the \
487 user-facing rate metric instead.",
488 self.name,
489 metric,
490 );
491 }
492 // A non-finite or negative threshold silently inverts or disables
493 // the gate in classify_noise (abs_gate/rel_gate are compared with
494 // `>=`; NaN makes every comparison false, a negative floor makes
495 // every move material). Reject both overrides.
496 if let Some(pct) = a.max_regression_pct()
497 && (!pct.is_finite() || pct < 0.0)
498 {
499 anyhow::bail!(
500 "KtstrTestEntry '{}'.perf_delta_assertions gate on '{}' has \
501 max_regression_pct={} — must be finite and >= 0 (a negative \
502 or NaN threshold silently disables or inverts the gate).",
503 self.name,
504 metric,
505 pct,
506 );
507 }
508 if let Some(min) = a.min_abs()
509 && (!min.is_finite() || min < 0.0)
510 {
511 anyhow::bail!(
512 "KtstrTestEntry '{}'.perf_delta_assertions gate on '{}' has \
513 min_abs={} — must be finite and >= 0 (a negative or NaN floor \
514 silently disables or inverts the gate).",
515 self.name,
516 metric,
517 min,
518 );
519 }
520 // Duplicate (metric, phase): the compare consults declared gates via
521 // a first-match `.find()`, so a second gate on the same (metric,
522 // phase) is silently dropped. Reject rather than pick-one-silently.
523 if !seen.insert((metric, a.phase())) {
524 let scope = match a.phase() {
525 Some(k) => format!("phase {k}"),
526 None => "the aggregate value".to_string(),
527 };
528 anyhow::bail!(
529 "KtstrTestEntry '{}'.perf_delta_assertions declares more than \
530 one gate on metric '{}' for {} — the compare applies only the \
531 first and silently drops the rest. Merge them into one gate.",
532 self.name,
533 metric,
534 scope,
535 );
536 }
537 }
538 Ok(())
539 }
540}