ktstr/vmm/result.rs
1//! Public [`VmResult`] returned from [`super::KtstrVm::run`], plus
2//! the internal [`VmRunState`] passed from `run_vm` to
3//! `collect_results` and the [`KvmStatsTotals`] aggregate of per-vCPU
4//! KVM counters.
5//!
6//! The split keeps the result-shaping types independent of the
7//! orchestration code (which still lives in [`super::KtstrVm`]). Test
8//! code outside `vmm/` constructs `VmResult` literals and reads
9//! `KvmStatsTotals` fields, so both types stay public; `VmRunState`
10//! is `pub(crate)`-only because it's an implementation detail of the
11//! run-then-collect handoff.
12
13use std::collections::HashMap;
14use std::sync::Arc;
15use std::sync::atomic::AtomicBool;
16use std::time::{Duration, Instant};
17
18use super::console;
19use super::host_comms::BulkDrainResult;
20use super::kvm;
21use super::pi_mutex::PiMutex;
22use super::vcpu::WatchpointArm;
23use super::virtio_blk::{VirtioBlkCounters, VirtioBlkCountersSnapshot};
24use super::virtio_net::{VirtioNetCounters, VirtioNetCountersSnapshot};
25use super::wire;
26use crate::monitor;
27
28/// Which watchdog rule (if any) killed the VM — the public mirror of
29/// the watchdog-internal `freeze_coord::KillReasonTag`, rendered as
30/// `cause=` in the deadline-expired stderr dump. `None` on
31/// [`VmResult::watchdog_kill_reason`] means no watchdog kill was
32/// recorded (clean exit, crash, or a timeout path that never stamped a
33/// reason).
34///
35/// The variant IS the mechanism assertion e2e fixtures need: a
36/// wedge-injection fixture proves its tier by matching the reason,
37/// which stays correct at ANY host dilation — unlike a wall-time bound,
38/// which conflates detection latency with host CPU share (an observed
39/// arm64 cell proved Tier-1 firing exactly on its 12 s CPU budget while
40/// taking 83 s of wall at ~14% share).
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42pub enum WatchdogKillReason {
43 /// Tier-1: max per-vCPU CPU burned past the phase budget with no
44 /// milestone — a spinning wedge.
45 Tier1CpuBudget,
46 /// Tier-2: wall past the phase backstop with live evidence channels
47 /// and no runnable demand — a silent idle wedge.
48 Tier2IdleWedge,
49 /// Tier-3: the hard deadline expired and the deadman was not deferred
50 /// (monitor dead, cell inert past the grace, or the current phase
51 /// exhausted the effective-deadline busiest-vCPU CPU budget).
52 Tier3Deadman,
53 /// An AP set the kill flag (panic-driven), not a watchdog expiry.
54 ApKill,
55 /// A scheduler attach consumed its host-measured service budget, then
56 /// failed to acknowledge the host's generation-tagged cancellation
57 /// within the fail-closed grace.
58 AttachCancelUnacknowledged,
59 /// The host monitor became terminal or was unavailable while a
60 /// scheduler attach attempt still owned the lifecycle watchdog.
61 AttachMonitorUnavailable,
62 /// The guest published scheduler-attach `Finished` but consumed the
63 /// delivered-service grace without completing the FinishedAck/Settled
64 /// rendezvous.
65 AttachFinishUnsettled,
66 /// A finite guest prerequisite consumed its delivered-service budget,
67 /// or the host sensor needed to account that budget became terminal.
68 ReadinessWaitFailed,
69}
70
71/// Final guest lifecycle stage as tracked by the progress ledger —
72/// the public mirror of `monitor::LifecycleStage` (same forward-only
73/// ordinal order, so `Ord` compares boot progress). Snapshotted at
74/// run teardown onto [`VmResult::final_guest_phase`].
75///
76/// Fixtures use this to distinguish "the guest reached the phase under
77/// test and the watchdog misfired" (a real detection regression) from
78/// "the guest never got there" (an environmental non-verdict: an
79/// observed arm64 cell at 0.3% host CPU share sat in `Boot` for 172 s —
80/// nothing phase-dependent can be asserted about a guest that could
81/// not boot).
82#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
83pub enum GuestLifecyclePhase {
84 /// Booting: init up to SYS_RDY.
85 Boot,
86 /// SYS_RDY seen; scheduler attaching.
87 Attach,
88 /// Guest dispatch entering the workload preamble.
89 Dispatch,
90 /// The test body / workload proper.
91 Body,
92 /// Winding down (`ScenarioEnd` / `Exit` / `TestResult` seen).
93 Teardown,
94}
95
96/// Result of a VM execution.
97///
98/// `Clone` is supported, but two field categories have different
99/// Clone semantics that callers must understand:
100///
101/// 1. **Pure-data fields** (the bulk of the struct): primitives,
102/// `String`, `Vec`, `Option<_>`, plus `MonitorReport` /
103/// `BulkDrainResult` / `ProgVerifierStats` / `StimulusEvent` /
104/// `KvmStatsTotals` / `VirtioBlkCountersSnapshot` /
105/// `VirtioNetCountersSnapshot`. Every clone produces an
106/// independent value — mutations to one do not affect the
107/// other. The `virtio_blk_counters` / `virtio_net_counters`
108/// fields are materialized `*CountersSnapshot` types (atomic
109/// loads done at construction time inside
110/// `super::KtstrVm::collect_results`), so clones cannot alias
111/// live device state.
112///
113/// 2. **Arc-shared handles** (`snapshot_bridge`, `stats_client`):
114/// these wrap `Arc<Mutex<…>>` / `Arc<AtomicUsize>` and clone via
115/// shallow refcount bump. Two `VmResult` clones SHARE the
116/// underlying store — calling `snapshot_bridge.drain()` on one
117/// clone empties the data visible to the other. See each
118/// field's own doc for the precise drain / iteration contract.
119/// If you need an independent snapshot view, drain into a local
120/// `Vec` before cloning the `VmResult`.
121///
122/// 3. **The capture-series cache** (`periodic_series_cache`): a
123/// `OnceLock<SampleSeries>` that memoizes the one destructive drain
124/// of the category-2 `snapshot_bridge` (see
125/// [`Self::captures_series`]). Its clone behavior depends on whether
126/// it is populated at clone time:
127/// - **Populated** (any of [`Self::captures_series`] /
128/// [`Self::periodic_series`] / [`Self::phase_buckets`] was already
129/// called): the clone carries an INDEPENDENT copy of the cached
130/// series — category-1 semantics. Both clones return the same
131/// captures without touching the (now-drained) shared bridge.
132/// - **Empty**: the clone shares the category-2 bridge, so the
133/// FIRST `captures_series()` call on EITHER clone performs the
134/// single drain and the other clone — if it later drains the same
135/// shared bridge — sees nothing. To give each clone its own
136/// buckets, call [`Self::captures_series`] (or any accessor that
137/// routes through it) on the original BEFORE cloning.
138#[derive(Debug, Clone)]
139pub struct VmResult {
140 /// Overall success flag: `true` when the test reported a pass AND
141 /// the VM exited cleanly without crash, timeout, or watchdog.
142 pub success: bool,
143 /// Guest vCPU count for this run (topology llcs*cores*threads),
144 /// carried from `KtstrVm` to the sidecar `(vcpus, cpu_budget)` stamp.
145 pub vcpus: u32,
146 /// Effective host-CPU budget the vCPU threads ran on; stamped to the
147 /// sidecar. Normally `KtstrVm::effective_cpu_budget` (the build-time
148 /// plan's CPU count), but the default-overcommit path (host too small
149 /// for a 1:1 pin) overrides it in `run()` with the actual masked
150 /// host-CPU count, since the build-time value assumes 1:1 pinning.
151 /// Below `vcpus` means host overcommit, which confounds the
152 /// guest-scheduler timing metrics.
153 pub cpu_budget: u32,
154 /// How the userspace scheduler binary was resolved for this run —
155 /// the snake_case `crate::test_support::ResolveSource::as_str` tag
156 /// (`"auto_built"`, `"target_debug"`, `"path"`, ...). Stamped by the
157 /// host eval layer (`run_ktstr_test_inner_impl`) AFTER the run,
158 /// alongside `entry_name` / `variant_hash`, then carried to the
159 /// sidecar `resolve_source` stamp the same way `vcpus` / `cpu_budget`
160 /// are. `None` for VmResults built outside the host eval path (the
161 /// freeze coordinator, test fixtures) — those resolve no scheduler
162 /// binary.
163 pub resolve_source: Option<String>,
164 /// True when the `#[ktstr_test(expect_auto_repro)]` attribute set
165 /// `expect_auto_repro = true` on the entry AND the auto-repro
166 /// path fired with a valid repro artifact during the run — the
167 /// signal that the verdict-flip from fail-with-artifact → PASS
168 /// is satisfied.
169 ///
170 /// The eval-layer derives this field AFTER `evaluate_vm_result`
171 /// returns (preserving the original `success` + error chain for
172 /// diagnostic visibility); the eval layer then wraps any
173 /// failure `Err` with the
174 /// `crate::test_support::eval::ExpectAutoReproSatisfied`
175 /// marker, and the dispatch arm
176 /// (`crate::test_support::dispatch::result_to_exit_code`)
177 /// downcasts the marker and routes the verdict to `EXIT_PASS`
178 /// without mutating the original `success` or stripping the
179 /// error chain. Pattern mirrors the `expect_err` matcher
180 /// inversion.
181 ///
182 /// Default `false`. When `expect_auto_repro = false` (the
183 /// macro-attribute default) the eval layer skips the artifact
184 /// probe entirely and leaves the field at `false`, so the
185 /// dispatch arm is never matched and the original verdict
186 /// stands.
187 pub expect_auto_repro_satisfied: bool,
188 /// Guest exit code as surfaced through the SHM ring
189 /// (`MSG_TYPE_EXIT`) or COM2 sentinel.
190 pub exit_code: i32,
191 /// Wall-clock duration of the VM run.
192 pub duration: Duration,
193 /// True when the host hit its watchdog before the guest exited.
194 pub timed_out: bool,
195 /// Which watchdog rule killed the VM (see [`WatchdogKillReason`]).
196 /// `None` when no watchdog kill was recorded — clean exits, but
197 /// also crash paths where the kill flag was never watchdog-set.
198 /// Loaded from the watchdog thread's kill-reason latch after its
199 /// join, so the value is final.
200 pub watchdog_kill_reason: Option<WatchdogKillReason>,
201 /// Final guest lifecycle stage per the progress ledger (see
202 /// [`GuestLifecyclePhase`]). Snapshotted at run teardown; stays
203 /// `Boot` when the guest never advanced (or no dispatch thread
204 /// consumed lifecycle frames — e.g. host-only paths).
205 pub final_guest_phase: GuestLifecyclePhase,
206 /// Final milestone count from the progress ledger (the dump's
207 /// `progress_epoch=` value): lifecycle-stage advances plus other
208 /// dispatch-recorded milestones. `0` means the guest never
209 /// published a milestone the host consumed.
210 pub final_progress_epoch: u64,
211 /// Whether the entry's host-triggered BPF-map-write injections
212 /// (`KtstrTestEntry::bpf_map_write` — e.g. the neg_* fixtures'
213 /// crash flag) were delivered: `None` when no writes were
214 /// configured, `Some(true)` when every queued write landed and the
215 /// guest was signalled, `Some(false)` when the injection thread
216 /// never completed (killed mid-retry — e.g. the run ended while a
217 /// starved guest was still booting/attaching). Fixtures that
218 /// expect an injected bug consult this to distinguish "the bug
219 /// never fired because the injection never landed" (environmental
220 /// under witnessed contention) from a real detection failure.
221 pub bpf_map_writes_delivered: Option<bool>,
222 /// Run-relative instant the periodic-capture prereqs (KASLR publish
223 /// and the map/prog accessors) became ready; `None` when they never
224 /// did. With [`Self::periodic_window_end`] this is the READINESS-VS-WINDOW
225 /// evidence: readiness at/after the window end (or never) makes zero
226 /// captures structurally inevitable at ANY host dilation — the
227 /// capture-starvation gates skip on it instead of a dilation
228 /// threshold (a ~7 s cold accessor build outruns a 4-5 s window at
229 /// D ≈ 1.2, below any honest contention bar).
230 pub periodic_prereqs_ready: Option<Duration>,
231 /// Run-relative instant the periodic capture window ends (the
232 /// workload-end clamp); `None` when the window never resolved —
233 /// which itself means no boundary could ever fire.
234 pub periodic_window_end: Option<Duration>,
235 /// Captured guest stdout (and any non-dmesg serial console content).
236 pub output: String,
237 /// Captured guest stderr (separated from `output` when the guest
238 /// reported them distinctly).
239 pub stderr: String,
240 /// Host-side monitor report: sampled per-CPU state, stuck
241 /// verdicts, and SCX event deltas. `None` when the monitor did
242 /// not run (host-only tests, early VM failure).
243 pub monitor: Option<monitor::MonitorReport>,
244 /// TLV messages drained from the guest after VM exit. Merges
245 /// mid-flight bytes the freeze coordinator pulled off
246 /// virtio-console port 1 during the run with the final port-1
247 /// `port1_tx_buf` flush.
248 pub guest_messages: Option<BulkDrainResult>,
249 /// BPF verifier stats collected from host-side memory reads.
250 pub verifier_stats: Vec<monitor::bpf_prog::ProgVerifierStats>,
251 /// KVM per-vCPU cumulative stats (requires Linux >= 5.14).
252 pub kvm_stats: Option<KvmStatsTotals>,
253 /// Crash message extracted from COM2 output via
254 /// `crate::test_support::extract_panic_message`. The guest
255 /// panic hook in `rust_init/init.rs` writes `PANIC: <info>\n<bt>\n`
256 /// to `/dev/ttyS1` synchronously inside `KVM_RUN`, so the host
257 /// captures the full backtrace in `output` even when the guest
258 /// is wedged. `None` when no `PANIC:`-prefixed line was seen.
259 pub crash_message: Option<String>,
260 /// Wall-clock time from BSP exit to the moment
261 /// `super::KtstrVm::collect_results` finishes assembling
262 /// [`VmResult`].
263 /// Records the host-side cost of every teardown step that runs
264 /// after the guest has stopped advancing: watchdog join, AP joins,
265 /// monitor join, BPF-writer join, SHM drain, exit/crash-message
266 /// extraction, and BPF verifier-stat read. Always `Some(_)` for
267 /// VMs whose `super::KtstrVm::run_vm` returns normally —
268 /// including the host-watchdog timeout path, because
269 /// `run_bsp_loop` exits cleanly with `timed_out = true` and
270 /// `collect_results` still executes, populating the field.
271 /// `None` only when `run_vm` does not complete (a BSP panic
272 /// propagated through `?`, or any pre-BSP setup error that
273 /// returns an `Err` before `VmRunState` is constructed) and on
274 /// the `test_fixture` / skip-sidecar paths that never boot a VM.
275 /// Persisted via
276 /// [`SidecarResult`](crate::test_support::SidecarResult) so stats
277 /// tooling can flag cleanup regressions across runs.
278 pub cleanup_duration: Option<Duration>,
279 /// The cleanup window's OWN dilation evidence: the join/drain
280 /// performer thread's schedstat delta (on-CPU + runnable-wait)
281 /// across exactly the [`Self::cleanup_duration`] window. The
282 /// cleanup-budget gate judges overruns against THIS — the
283 /// per-phase/whole-run witnesses cannot attest the window (the
284 /// monitor that feeds them is itself joined inside it, and join
285 /// wake-latency is a tail phenomenon a whole-run average
286 /// under-attests). `None` when schedstat was unreadable at either
287 /// edge; a `0` on-CPU delta (CONFIG_SCHEDSTATS off) is treated as
288 /// unattested by consumers.
289 pub cleanup_sched_delta: Option<HostVcpuSchedstat>,
290 /// Host-side virtio-blk device counters, snapshotted after the
291 /// guest has exited. `Some(_)` when the builder attached a disk
292 /// via `super::KtstrVmBuilder::disk`; `None` when no disk was
293 /// configured and `super::KtstrVm::init_virtio_blk` returned
294 /// `None`. The device increments its internal `AtomicU64`
295 /// counters from `drain_bracket_impl` (production cfg: on the
296 /// dedicated `ktstr-vblk` worker thread; cfg(test): inline on
297 /// the test thread); by the time `collect_results` constructs
298 /// the [`VmResult`] every vCPU and the worker have joined and
299 /// no further mutation can occur. The snapshot is taken at that
300 /// point — readers see plain `u64` fields holding the final
301 /// cumulative totals; no atomic load is needed on the consumer
302 /// side.
303 ///
304 /// The counter struct exposes nine `AtomicU64` fields, each
305 /// bumped from `drain_bracket_impl` (in `src/vmm/virtio_blk/drain.rs`)
306 /// via the `VirtioBlkCounters::record_*` helpers (defined in
307 /// `src/vmm/virtio_blk/counters.rs`). Per-request
308 /// cumulative counters, per-event cumulative counters, and
309 /// per-request live gauges are kept distinct per the
310 /// counter-taxonomy doc on `VirtioBlkCounters`:
311 ///
312 /// - `reads_completed` — count of `VIRTIO_BLK_T_IN` requests
313 /// that returned `S_OK` to the guest. Bumped together with
314 /// `bytes_read` per `VirtioBlkCounters::record_read`.
315 /// - `writes_completed` — count of `VIRTIO_BLK_T_OUT` requests
316 /// that returned `S_OK`. Bumped together with `bytes_written`.
317 /// - `flushes_completed` — count of `VIRTIO_BLK_T_FLUSH`
318 /// requests that returned `S_OK` (real `fdatasync` for
319 /// read-write disks, no-op for `read_only`).
320 /// - `bytes_read` — total bytes returned to the guest for
321 /// completed reads.
322 /// - `bytes_written` — total bytes accepted from the guest for
323 /// completed writes.
324 /// - `throttled_count` — cumulative token-bucket **stall events**
325 /// for the device's lifetime. The chain is rolled back and
326 /// the worker arms a retry timerfd; the guest does not see
327 /// `S_IOERR` for a stall (the request is deferred until the
328 /// bucket refills). This counter is separate from `io_errors`
329 /// so operators can distinguish "throttle bucket drained,
330 /// request deferred" from "real IO problem". Per-event (NOT
331 /// per-request): a single chain that stalls twice produces
332 /// two bumps.
333 /// - `io_errors` — every path that reports `S_IOERR`:
334 /// spec violations, backend `pread`/`pwrite` errors,
335 /// malformed chains, `add_used` failures.
336 /// Stalls do not report `S_IOERR`; see `throttled_count`.
337 /// - `currently_throttled_gauge` — **live gauge**: how many
338 /// requests are RIGHT NOW waiting for throttle tokens.
339 /// Increments when a chain transitions into stalled,
340 /// decrements on retry success or reset. Bounded at 0 or 1
341 /// on this single-queue device. NOT cumulative — answers
342 /// "what's stuck now," distinct from `throttled_count`
343 /// which answers "how many stall events happened over
344 /// time."
345 /// - `invalid_avail_idx_count` — cumulative count of
346 /// `Error::InvalidAvailRingIndex` events observed by
347 /// `drain_bracket_impl` (avail.idx more than `queue.size`
348 /// ahead of `next_avail` — a virtio-v1.2 §2.7.13.3
349 /// avail.idx-distance violation by the guest). Per-event
350 /// counter; the `queue_poisoned` flag short-circuits
351 /// subsequent kicks so one guest fault produces exactly
352 /// one bump regardless of how many notifications follow
353 /// before reset.
354 ///
355 /// Counters are cumulative for the device's lifetime. A guest
356 /// driver re-bind (writing `STATUS=0` to `VIRTIO_MMIO_STATUS`
357 /// triggers `VirtioBlk::reset`) does NOT zero them — the
358 /// device's internal `AtomicU64` storage persists across reset
359 /// cycles, and the post-exit snapshot captures the final
360 /// cumulative totals spanning the entire device lifetime, not
361 /// just a post-reset fragment.
362 ///
363 /// Reading example:
364 ///
365 /// ```ignore
366 /// let r: VmResult = builder.run()?;
367 /// let c = r.virtio_blk_counters.expect("disk attached");
368 /// assert!(c.reads_completed > 0);
369 /// ```
370 ///
371 /// `#[allow(dead_code)]`: the field is part of the public API
372 /// surface and read by user test code outside `lib.rs`, but the
373 /// lib build doesn't see any in-tree readers because no lib code
374 /// path calls `.virtio_blk_counters` on a `VmResult`. The in-tree
375 /// readers live in unit tests.
376 #[allow(dead_code)]
377 pub virtio_blk_counters: Option<VirtioBlkCountersSnapshot>,
378 /// Host-side virtio-net device counters, snapshotted after the
379 /// guest has exited — the cross-NIC AGGREGATE (field-wise
380 /// saturating sum via `VirtioNetCountersSnapshot::aggregate`) over
381 /// every attached NIC. `Some(_)` when the builder attached one or
382 /// more networks via `super::KtstrVmBuilder::network`; `None` when
383 /// no network was configured (the aggregate over an empty NIC set).
384 /// Each NIC's device increments its own `AtomicU64` counters on the
385 /// vCPU thread inside `process_tx_loopback`; by the time
386 /// `collect_results` constructs the [`VmResult`] every vCPU has
387 /// joined and no further mutation can occur. The per-NIC snapshots
388 /// are summed at that point — readers see plain `u64` fields holding
389 /// the final cumulative totals across all NICs; no atomic load is
390 /// needed on the consumer side. Per-NIC IRQ-delivery observability
391 /// comes from the per-CPU / per-IRQ metrics axis, not these
392 /// device-internal loopback counters.
393 ///
394 /// The counter struct exposes sixteen `AtomicU64` fields, each
395 /// bumped across the TX-drain path rooted at `process_tx_loopback`
396 /// (several are bumped inside the `pop_and_capture_tx` /
397 /// `try_loopback_to_rx` helpers it calls; the three `ctrl_*`
398 /// counters are bumped on the control-vq path, not the TX-drain
399 /// path):
400 ///
401 /// - `tx_packets` — count of TX chains whose L2 frame was
402 /// captured (`frame_len = Some`) AND whose TX `add_used`
403 /// succeeded. Over-size-dropped and malformed chains are still
404 /// marked used (so the guest doesn't hang) but do NOT advance
405 /// `tx_packets`; a chain whose `add_used` fails advances
406 /// `tx_add_used_failures` instead. So `tx_packets` advances per
407 /// successfully-captured-and-published chain, not per parsed
408 /// chain.
409 /// - `tx_bytes` — bytes of L2 frame data captured from
410 /// successfully parsed TX chains (excludes the 12-byte
411 /// virtio header).
412 /// - `rx_packets` / `rx_bytes` — count + bytes of RX chains
413 /// successfully written and marked used. `rx_packets` and
414 /// `tx_packets` gate INDEPENDENTLY per chain: `rx_packets`
415 /// bumps when the loopback delivers — recorded BEFORE the TX
416 /// `add_used` — while `tx_packets` bumps only when that later
417 /// TX `add_used` succeeds. So the identity
418 /// `rx_packets == tx_packets - tx_dropped_no_rx_buffer
419 /// - tx_dropped_rx_poisoned` holds ONLY when both the RX-side
420 /// failure counters AND `tx_add_used_failures` are zero:
421 /// RX-side failures (`rx_add_used_failures`, `rx_chain_invalid`,
422 /// `rx_write_failed`) make `rx_packets` fall SHORT of
423 /// `tx_packets - drops`, while a `tx_add_used_failures` on a
424 /// chain whose RX already delivered makes `rx_packets` EXCEED
425 /// it. Asymmetric counts surface queue-state breakage on
426 /// either side.
427 /// - `tx_dropped_no_rx_buffer` — successfully-captured TX
428 /// frames the device could not deliver because the RX queue
429 /// was empty (transient back-pressure event).
430 /// - `tx_dropped_rx_poisoned` — successfully-captured TX frames
431 /// dropped because the RX queue was poisoned by a prior guest
432 /// avail-ring violation (wedged until a virtio reset), as
433 /// opposed to the transient empty-queue back-pressure counted
434 /// by `tx_dropped_no_rx_buffer`.
435 /// - `tx_chain_invalid` / `rx_chain_invalid` — chains rejected
436 /// for malformed shape (short header, wrong direction,
437 /// attacker-controlled descriptor address overflow).
438 /// - `tx_oversize_dropped` — TX chains dropped (not truncated)
439 /// because the captured post-header frame data exceeded the
440 /// maximum L2 frame size the guest's `max_mtu` permits.
441 /// - `rx_write_failed` — RX chain whose shape was valid but
442 /// whose guest-memory `write_slice` (header or frame) hit
443 /// an unmapped GPA. Distinct from `rx_chain_invalid` so an
444 /// operator can tell "guest violated the RX descriptor-
445 /// direction rule" from "guest posted a buffer at an
446 /// unmapped GPA"; the two are mutually exclusive per chain.
447 /// - `tx_add_used_failures` / `rx_add_used_failures` —
448 /// `add_used` failures, indicating the queue's used-ring
449 /// address itself is unmapped or otherwise inaccessible.
450 /// Distinct from the `*_chain_invalid` / `rx_write_failed`
451 /// counters so an operator can tell "guest sent malformed
452 /// frame" / "guest's posted buffer GPA was unmapped" from
453 /// "queue itself is broken".
454 /// - `invalid_avail_idx_count` — cumulative count of
455 /// `Error::InvalidAvailRingIndex` events observed by
456 /// `process_tx_loopback` (avail.idx more than `queue.size`
457 /// ahead of `next_avail` — virtio-v1.2 §2.7.13.3 violation
458 /// by the guest). Per-event counter; the per-queue
459 /// `queue_poisoned` flag short-circuits subsequent kicks
460 /// so one guest fault produces exactly one bump regardless
461 /// of how many notifications follow before reset.
462 /// - `ctrl_mq_set` — cumulative count of successful control-vq
463 /// `VIRTIO_NET_CTRL_MQ` / `VQ_PAIRS_SET` commands (the device
464 /// updated `curr_queue_pairs` and wrote `VIRTIO_NET_OK`).
465 /// Per-event counter.
466 /// - `ctrl_chain_invalid` — cumulative count of control-vq
467 /// chains the device could not satisfy: malformed shape (no
468 /// device-writable status descriptor, too few readable command
469 /// bytes), an unknown `(class, cmd)`, or a `virtqueue_pairs`
470 /// outside `[1, queue_pairs]`. Per-event hostile/buggy-guest
471 /// counter; the control-vq analog of `tx_chain_invalid`.
472 /// - `ctrl_add_used_failures` — cumulative count of control-vq
473 /// status-write or `add_used` failures (the status byte's GPA
474 /// or the used-ring address is unmapped). Queue-state breakage
475 /// distinct from `ctrl_chain_invalid`; the control-vq analog
476 /// of `tx_add_used_failures`.
477 ///
478 /// Counters are cumulative for the device's lifetime — a guest
479 /// driver re-bind (writing `STATUS=0`) does NOT zero them.
480 #[allow(dead_code)]
481 pub virtio_net_counters: Option<VirtioNetCountersSnapshot>,
482 /// Snapshot bridge populated by the freeze coordinator over the
483 /// run's lifetime. Every `Op::CaptureSnapshot` and `Op::WatchSnapshot`
484 /// fire stores a `FailureDumpReport` keyed by its tag.
485 ///
486 /// `#[ktstr_test]` test bodies whose scenario fires snapshot
487 /// ops in the guest assert on the captured reports through a
488 /// `post_vm = NAME` attribute. The named callback runs on the
489 /// HOST after `vm.run()` returns (see
490 /// [`crate::test_support::KtstrTestEntry::post_vm`]) and
491 /// receives `&VmResult`; it calls
492 /// [`crate::scenario::snapshot::SnapshotBridge::drain`] on
493 /// this field to take ownership of the stored reports and
494 /// walks them — typically through
495 /// [`crate::scenario::snapshot::Snapshot::new`] for typed
496 /// access to map values, per-CPU entries, and scalar
497 /// variables. Out-of-tree consumers can drain the bridge the
498 /// same way: `VmResult` is in `ktstr::prelude`.
499 ///
500 /// Always present after a successful `run_vm`; `None`-equivalent
501 /// (empty) when the VM crashed before any snapshot fired.
502 ///
503 /// **Drained exactly once, via [`Self::captures_series`]**: the
504 /// bridge yields each capture once, so the host-side consumers
505 /// share a single drain. The first call to
506 /// [`Self::captures_series`] — whether from a `post_vm` callback
507 /// (which runs FIRST, via [`Self::periodic_series`] /
508 /// [`Self::phase_buckets`]) or from the framework's
509 /// `evaluate_vm_result` (which runs AFTER `post_vm` to build
510 /// [`crate::assert::ScenarioStats::phases`]) — drains this bridge
511 /// and memoizes the resulting
512 /// [`crate::scenario::sample::SampleSeries`] on the
513 /// `periodic_series_cache` field; every later call reads the
514 /// cache. That is why a per-phase `post_vm` and the framework's
515 /// `result.stats.phases` build no longer starve each other (a
516 /// `post_vm` that drained the bridge first used to leave
517 /// `stats.phases` empty). Integration tests under `tests/` that
518 /// bypass the series accessors and call
519 /// `result.snapshot_bridge.drain*()` directly (e.g.
520 /// `tests/stats_bridge_e2e.rs`, `tests/temporal_assertions_e2e.rs`)
521 /// are unaffected: the cache is only populated by
522 /// [`Self::captures_series`], which those tests never call, so the
523 /// raw destructive drain still returns the full capture set.
524 pub snapshot_bridge: crate::scenario::snapshot::SnapshotBridge,
525 /// Live scheduler-stats client. `Some(_)` when the run wired the
526 /// virtio-console port-2 stats bridge (the in-tree path always
527 /// does so, but tests that construct a [`VmResult`] manually via
528 /// `Self::test_fixture` leave this `None`). Test code that
529 /// asserts on scheduler-reported metrics calls
530 /// `super::SchedStatsClient::stats` /
531 /// `super::SchedStatsClient::stats_meta` on this handle WHILE
532 /// the guest is alive — calling after VM exit will time out
533 /// because the relay thread has already exited. Cloneable;
534 /// multiple test threads may share the same client.
535 #[allow(dead_code)]
536 pub stats_client: Option<super::SchedStatsClient>,
537 /// Number of periodic snapshot boundaries the freeze
538 /// coordinator actually fired during this run. Includes both
539 /// successful captures and rendezvous-timeout placeholders.
540 /// Tests can assert `result.periodic_fired >= some_lower_bound`
541 /// to guard periodic-capture coverage; mismatches against
542 /// [`Self::periodic_target`] flag missing samples (early VM
543 /// exit, kill-flag stop, abandoned-after-timeouts).
544 pub periodic_fired: u32,
545 /// Periodic captures that landed REAL BPF state — the
546 /// placeholder-excluded subset of [`Self::periodic_fired`]
547 /// (`periodic_fired` counts rendezvous-timeout placeholders as
548 /// fired). Snapshotted from
549 /// [`crate::scenario::snapshot::SnapshotBridge::periodic_real_count`]
550 /// at result-collection time so it is stable regardless of any
551 /// later test-side drain of the bridge. `periodic_real <
552 /// periodic_fired` means the gap is placeholder-only fills (the
553 /// boundary fired but the dump was degraded); the failure-output
554 /// periodic-samples section surfaces this so a "100% fired" run
555 /// whose captures were all placeholders does not read as full
556 /// coverage.
557 pub periodic_real: u32,
558 /// Configured `num_snapshots` count for the entry that drove
559 /// this run (mirrors the `KtstrTestEntry::num_snapshots` field
560 /// the entry was registered with). `0` when periodic capture
561 /// was disabled. Pairs with [`Self::periodic_fired`] so a
562 /// test can compute coverage without re-reading the entry
563 /// table.
564 pub periodic_target: u32,
565 /// Runtime virt-KASLR offset (kernel-image slide). Captured
566 /// from the freeze coordinator's `kern_virt_kaslr` Arc snapshot
567 /// at run-end via `load(Acquire).saturating_sub(1)`. `0` means
568 /// either (a) KASLR was off — test ran with
569 /// `#[ktstr_test(kaslr = false)]` or
570 /// `Scheduler::kargs(&["nokaslr"])`, OR (b) the derivation
571 /// chain (MSR_LSTAR readback in `vmm::x86_64::msr_kaslr` +
572 /// KERN_ADDRS `_text` path in `crate::vmm::freeze_coord::dispatch`) never
573 /// published a non-zero value (early-boot crash, kallsyms masked
574 /// by kptr_restrict, FRED-enabled kernel). E2E test consumers
575 /// distinguish (a) from (b) by reading the test entry's `kaslr`
576 /// attribute alongside this field — see
577 /// [`Self::kaslr_enabled`] for the binary-question companion.
578 pub kern_kaslr_offset: u64,
579 /// Name of the `#[ktstr_test]` fn whose execution produced this
580 /// result. Stamped from
581 /// `crate::test_support::entry::KtstrTestEntry::name` (a
582 /// `&'static str` the macro emits at compile time) in
583 /// `test_support::eval::run_ktstr_test_inner_impl` immediately
584 /// after `super::KtstrVm::run` returns and BEFORE the
585 /// `post_vm` callback dispatch runs.
586 ///
587 /// `Some(_)` for every result that flowed through the real
588 /// `run_ktstr_test_inner_impl` path. `None` for the
589 /// `freeze_coord::collect_results` direct-synthesis path
590 /// (entry-agnostic boundary; entry is not in scope there) and
591 /// for `#[cfg(test)]`-only `Self::test_fixture` callers. The
592 /// path-derivation methods `wprof_pb_path` and
593 /// `repro_wprof_pb_path` (require the `wprof` feature) bail with a loud diagnostic
594 /// on `None` so any `VmResult` reaching the derivation path
595 /// without going through the eval-layer stamping site
596 /// surfaces the misuse rather than producing a garbage-named
597 /// path.
598 ///
599 /// Test authors writing `post_vm` callbacks should derive
600 /// per-test sidecar paths via the helper methods rather than
601 /// hardcoding a `wprof_pb_path("<literal>")` string against
602 /// the fn name — a future rename of the test fn drifts the
603 /// hardcoded literal silently, where the method-form derives
604 /// from this field automatically.
605 pub entry_name: Option<&'static str>,
606 /// The run's variant hash (see `variant_hash_from_parts`),
607 /// stamped alongside [`Self::entry_name`] after `vm.run()` returns.
608 /// The post-VM `failure_dump_path` / `wprof_pb_path` derivations
609 /// embed it as the `-{16-hex}` filename suffix so a gauntlet test's
610 /// per-preset dumps don't clobber and each matches its sidecar's
611 /// variant hash. `0` on a synthesized/fixture result (which has
612 /// `entry_name = None` and thus bails before reading this).
613 pub variant_hash: u64,
614 /// Host-side vCPU scheduling dilation for this run — RAW schedstat
615 /// totals summed over the vCPU host threads (see
616 /// `HostVcpuSchedstat`). Populated by `run_vm` teardown from live
617 /// `/proc/self/task/<tid>/schedstat` entries plus a one-shot self-snapshot
618 /// each AP stores immediately before exit; `None` on hosts without
619 /// `CONFIG_SCHEDSTATS`, on synthesized/fixture results, and whenever no
620 /// vCPU thread was sampled. Consumers call `HostVcpuSchedstat::dilation`
621 /// for the derived `D` ratio. Purely observational — never affects the
622 /// verdict or exit code.
623 pub host_vcpu_schedstat: Option<HostVcpuSchedstat>,
624 /// Per-phase host-contention witness for the "weather witness" latency
625 /// model (see [`ContentionWitness`]): the Body-phase dilation `D` plus
626 /// the Body-phase peak-window CPU-pressure series that bounds `W(L)`.
627 /// Lifecycle events anchor the series and the monitor adds constant-cost
628 /// cgroup-PSI samples on its existing wakes. `None` when neither PSI nor
629 /// vCPU schedstat supplied evidence. Consumed by a LATER seam pass —
630 /// `latency_verdict` — to make latency threshold verdicts tri-state under
631 /// contention; purely observational until then.
632 pub contention_witness: Option<ContentionWitness>,
633 /// Memoized single drain of [`Self::snapshot_bridge`].
634 ///
635 /// The snapshot bridge yields each capture exactly once, but two
636 /// host-side consumers need the captures: a `post_vm` callback
637 /// (which runs first) and the framework's `evaluate_vm_result`
638 /// (which builds [`crate::assert::ScenarioStats::phases`]). Before
639 /// this cache existed, whichever drained first starved the other —
640 /// a per-phase `post_vm` calling [`Self::periodic_series`] left
641 /// `evaluate_vm_result` with an empty bridge, silently emptying
642 /// `result.stats.phases` and the failure-message timeline.
643 ///
644 /// [`Self::captures_series`] performs the one destructive bridge
645 /// drain on first call and stores the resulting full
646 /// [`crate::scenario::sample::SampleSeries`] here; every later call
647 /// — and [`Self::periodic_series`] / [`Self::phase_buckets`] /
648 /// `evaluate_vm_result` — reads the cached series instead of
649 /// re-draining. Lazily populated so a consumer that only touches
650 /// the raw bridge via `snapshot_bridge.drain*()` (e.g. integration
651 /// tests under `tests/`) is unaffected: the cache is never
652 /// initialised on that path.
653 ///
654 /// `pub(crate)` (not `pub`): in-crate constructors
655 /// (`freeze_coord::collect_results`, test fixtures) set it to an
656 /// empty `OnceLock`, but out-of-tree code cannot struct-literal a
657 /// `VmResult` — it flows from `run_vm` — so the cache stays an
658 /// implementation detail behind [`Self::captures_series`].
659 pub(crate) periodic_series_cache: std::sync::OnceLock<crate::scenario::sample::SampleSeries>,
660}
661
662impl VmResult {
663 /// Whether the guest kernel booted with KASLR enabled (= a
664 /// non-zero virt-KASLR offset published into the freeze
665 /// coordinator's `kern_virt_kaslr` Arc). Returns `true` when
666 /// [`Self::kern_kaslr_offset`] is non-zero. The inverse case
667 /// (returns `false`) covers two scenarios: (a) the test
668 /// explicitly opted out via `#[ktstr_test(kaslr = false)]` or
669 /// `Scheduler::kargs(&["nokaslr"])`, OR (b) the derivation
670 /// chain failed to publish a non-zero value (early-boot crash,
671 /// kallsyms masked, kernel built without `CONFIG_RANDOMIZE_BASE`).
672 /// E2E test consumers distinguish (a) from (b) by reading the
673 /// test entry's `kaslr` attribute alongside this method.
674 ///
675 /// Companion to [`Self::kern_kaslr_offset`] — use this when the
676 /// caller cares about the binary "did KASLR happen?" question
677 /// and use the raw field for exact-offset assertions
678 /// (alignment, entropy-range, etc.).
679 pub fn kaslr_enabled(&self) -> bool {
680 self.kern_kaslr_offset != 0
681 }
682
683 /// The full capture series for this run — every snapshot the
684 /// freeze coordinator stored on [`Self::snapshot_bridge`]
685 /// (periodic boundaries AND on-demand `Op::CaptureSnapshot` /
686 /// watchpoint-fire captures), in the order the bridge surfaced.
687 ///
688 /// Performs the bridge's single destructive drain on the first
689 /// call and memoizes the resulting
690 /// [`crate::scenario::sample::SampleSeries`] on the
691 /// `periodic_series_cache` field; every later call — and
692 /// [`Self::periodic_series`] / [`Self::phase_buckets`] and the
693 /// framework's `evaluate_vm_result` — returns the cached series
694 /// without re-draining. This is what lets a `post_vm` callback and
695 /// the framework's [`crate::assert::ScenarioStats::phases`] build
696 /// share one drain instead of starving each other (the bridge
697 /// yields each capture exactly once).
698 ///
699 /// Takes `&self`: the cache uses interior mutability
700 /// ([`std::sync::OnceLock`]) so this composes with the
701 /// `#[ktstr_test(post_vm = ...)]` callback signature
702 /// (`fn(&VmResult) -> Result<()>`).
703 ///
704 /// A consumer that calls `snapshot_bridge.drain*()` directly
705 /// (e.g. integration tests under `tests/`) bypasses this cache. If
706 /// such a raw drain runs BEFORE the first `captures_series()` call
707 /// the cache memoizes an empty series, so prefer this accessor over
708 /// a raw drain on any path that also reaches `evaluate_vm_result`.
709 pub fn captures_series(&self) -> &crate::scenario::sample::SampleSeries {
710 self.periodic_series_cache.get_or_init(|| {
711 crate::scenario::sample::SampleSeries::from_drained_typed(
712 self.snapshot_bridge.drain_ordered_with_stats(),
713 self.monitor.clone(),
714 )
715 })
716 }
717
718 /// The periodic-capture-only view of this run's series: the
719 /// `"periodic_"`-tagged subset of [`Self::captures_series`] — the
720 /// projection the temporal-assertion / per-phase patterns expect
721 /// (on-demand `Op::CaptureSnapshot` and watchpoint-fire captures
722 /// are filtered out as off-cadence outliers, see
723 /// [`crate::scenario::sample::SampleSeries::periodic_only`]).
724 ///
725 /// Reads the shared [`Self::captures_series`] cache (the single
726 /// bridge drain) and returns an owned, periodic-only clone.
727 /// Idempotent: calling it twice — or alongside
728 /// [`Self::phase_buckets`] / `evaluate_vm_result` — no longer
729 /// empties the bridge for the other consumers (the pre-cache
730 /// behavior, which silently starved whichever drained second).
731 ///
732 /// Takes `&self` so it composes with the
733 /// `#[ktstr_test(post_vm = ...)]` callback signature.
734 pub fn periodic_series(&self) -> crate::scenario::sample::SampleSeries {
735 self.captures_series().clone().periodic_only()
736 }
737
738 /// The complete per-phase stimulus timeline for `post_vm`
739 /// callbacks doing per-phase metric assertions: one
740 /// [`crate::timeline::StimulusEvent`] per guest `Stimulus` frame
741 /// (the step-start boundaries, via
742 /// [`crate::timeline::StimulusEvent::from_wire`]) PLUS the
743 /// synthesized terminal scenario-end boundary (from the
744 /// `ScenarioEnd` frame's final cumulative count, via
745 /// [`crate::timeline::StimulusEvent::terminal`]).
746 ///
747 /// Fold THIS through
748 /// [`crate::assert::build_phase_buckets_with_stimulus`] to reproduce the
749 /// same phase windows and boundary telemetry as `evaluate_vm_result`.
750 /// Iteration rates are joined separately from guest CPU-time carriers.
751 ///
752 /// Non-destructive: reads the already-drained `guest_messages` TLV
753 /// log (unlike the bridge-cache accessors [`Self::captures_series`]
754 /// / [`Self::periodic_series`] / [`Self::phase_buckets`], which
755 /// perform the single destructive snapshot-bridge drain), so it may
756 /// be called alongside the bridge drain. CRC-bad / malformed frames
757 /// are skipped.
758 pub fn stimulus_timeline(&self) -> Vec<crate::timeline::StimulusEvent> {
759 let mut out = Vec::new();
760 let Some(bulk) = &self.guest_messages else {
761 return out;
762 };
763 for entry in &bulk.entries {
764 if !entry.crc_ok {
765 continue;
766 }
767 match wire::MsgType::from_wire(entry.msg_type) {
768 Some(wire::MsgType::Stimulus) => {
769 if let Some(ev) = wire::StimulusEvent::from_payload(&entry.payload) {
770 out.push(crate::timeline::StimulusEvent::from_wire(&ev));
771 }
772 }
773 Some(wire::MsgType::StepEnd) => {
774 // Per-step end-of-hold frame (reuses the StimulusPayload
775 // body). Retained as raw boundary telemetry.
776 if let Some(ev) = wire::StimulusEvent::from_payload(&entry.payload) {
777 out.push(crate::timeline::StimulusEvent::from_step_end(&ev));
778 }
779 }
780 Some(wire::MsgType::ScenarioEnd) => {
781 if let Some((elapsed_ms, total_iterations)) =
782 wire::parse_scenario_end(&entry.payload)
783 {
784 out.push(crate::timeline::StimulusEvent::terminal(
785 elapsed_ms,
786 total_iterations,
787 ));
788 }
789 }
790 _ => {}
791 }
792 }
793 out
794 }
795
796 /// Worker-iteration efficiency (iterations per delivered guest CPU-second)
797 /// for one scenario [`Phase`](crate::assert::Phase).
798 ///
799 /// This is an ergonomic alias for the canonical per-phase
800 /// `iteration_rate`; it is not a second wall-throughput calculation.
801 /// Both the iteration numerator and delivered-CPU denominator come from
802 /// the same guest per-cgroup phase carriers, so host preemption does not
803 /// dilute the result.
804 ///
805 /// `None` when the phase has no guest carrier or its workers accumulated
806 /// no measurable CPU time. A measured zero iteration count over positive
807 /// CPU time returns `Some(0.0)`.
808 pub fn step_throughput(&self, phase: crate::assert::Phase) -> Option<f64> {
809 Self::step_throughput_in(&self.phase_buckets(), phase)
810 }
811
812 /// Ratio `step_throughput(a) / step_throughput(b)` — e.g.
813 /// scheduler-vs-EEVDF iteration efficiency when phase `b` runs on the detached
814 /// kernel default ([`crate::scenario::ops::Op::detach_scheduler`]).
815 /// Builds the canonical phase buckets once. `None` when either phase has
816 /// no measurable rate; a `Some(0.0)` denominator yields `inf` so a stalled
817 /// phase `b` surfaces rather than vanishing to `None`.
818 pub fn throughput_ratio(
819 &self,
820 a: crate::assert::Phase,
821 b: crate::assert::Phase,
822 ) -> Option<f64> {
823 let buckets = self.phase_buckets();
824 let ta = Self::step_throughput_in(&buckets, a)?;
825 let tb = Self::step_throughput_in(&buckets, b)?;
826 Some(ta / tb)
827 }
828
829 /// Shared core for [`Self::step_throughput`] / [`Self::throughput_ratio`]
830 /// over already-built canonical phase buckets.
831 fn step_throughput_in(
832 buckets: &[crate::assert::PhaseBucket],
833 phase: crate::assert::Phase,
834 ) -> Option<f64> {
835 buckets
836 .iter()
837 .find(|b| b.step_index == phase.as_u16())
838 .and_then(|b| b.get("iteration_rate"))
839 }
840
841 /// The guest-side [`crate::assert::AssertResult`] decoded from this
842 /// run's `MSG_TYPE_TEST_RESULT` frame — the verdict the in-VM scenario
843 /// body produced, carrying the per-phase per-cgroup raw telemetry
844 /// carriers in `stats.phases[].per_cgroup`
845 /// ([`crate::assert::PhaseCgroupStats`]: `total_migrations`,
846 /// `run_delays_ns`, `cpus_used`, …) and the per-cgroup reductions in
847 /// `stats.cgroups`.
848 ///
849 /// Non-destructive: reads the already-drained `guest_messages` TLV log
850 /// (the last crc-ok `MSG_TYPE_TEST_RESULT` entry), so it composes with
851 /// the snapshot-bridge accessors and may be called repeatedly. Shares
852 /// the exact decode the eval layer uses
853 /// (`crate::test_support::parse_assert_result_from_drain`).
854 ///
855 /// `Err` when there is no guest verdict to decode — a host-only run, a
856 /// crash before the body emitted its result, or a drain with no
857 /// `MSG_TYPE_TEST_RESULT` frame.
858 ///
859 /// This is the GUEST view: the run-level distribution / `ext_metrics`
860 /// re-pools (`worst_*` wake-latency / run-delay aggregates, pooled
861 /// `iteration_rate`) are applied HOST-side in `evaluate_vm_result`
862 /// AFTER the body returns and are NOT on this value — only
863 /// `stats.phases[].per_cgroup` and the per-cgroup `stats.cgroups`
864 /// reductions are guest-authoritative. For the per-phase per-cgroup view
865 /// aligned to the host capture windows use [`Self::phase_buckets`] (which
866 /// folds these carriers in); for one cgroup in one phase use
867 /// [`Self::phase_cgroup`].
868 pub fn guest_assert_result(&self) -> anyhow::Result<crate::assert::AssertResult> {
869 crate::test_support::parse_assert_result_from_drain(self.guest_messages.as_ref())
870 }
871
872 /// The framework-computed per-phase metric buckets for this run — the
873 /// SAME [`crate::assert::PhaseBucket`] vec the framework folds onto
874 /// [`crate::assert::ScenarioStats::phases`] in `evaluate_vm_result`,
875 /// INCLUDING the per-phase per-cgroup carriers in
876 /// [`crate::assert::PhaseBucket::per_cgroup`].
877 ///
878 /// This is the answer to "my `post_vm` callback wants the per-phase
879 /// metrics the framework already built." It folds the same two sources
880 /// `evaluate_vm_result` does:
881 /// 1. the host-rebuilt buckets from [`Self::periodic_series`] (the
882 /// periodic-only projection of the shared single drain — on-demand /
883 /// watchpoint captures are off-cadence outliers excluded from
884 /// per-phase folds) through
885 /// [`crate::assert::build_phase_buckets_with_stimulus`] using
886 /// [`Self::stimulus_timeline`] for the step windows (window + metric
887 /// folds; `per_cgroup` empty by construction); and
888 /// 2. the guest per-cgroup carriers from [`Self::guest_assert_result`]
889 /// (`stats.phases[].per_cgroup`), folded in by
890 /// `crate::assert::fold_guest_per_cgroup_into_host_buckets` keyed by
891 /// `step_index` (the host window + metrics win; each carrier
892 /// contributes only its `per_cgroup`, an unmatched carrier surfacing
893 /// as a `(0,0)`-window orphan bucket).
894 ///
895 /// Production builds `stats.phases` from these same two sources (same
896 /// periodic-only series, same stimulus timeline, same guest carriers) and
897 /// the eval layer's later `populate_run_*` passes write only
898 /// `stats.ext_metrics` / `stats.cgroups`, never `phases[].per_cgroup`, so
899 /// this returns content IDENTICAL to `result.stats.phases` — the
900 /// no-carrier case pinned by
901 /// `phase_buckets_equals_stats_phases_and_post_vm_read_does_not_starve`
902 /// and the with-per-cgroup-carrier case by
903 /// `phase_buckets_equals_stats_phases_with_guest_per_cgroup_carriers`.
904 ///
905 /// Both sources are non-destructive on the snapshot bridge:
906 /// [`Self::periodic_series`] reads the memoized single drain
907 /// ([`Self::captures_series`]) and [`Self::guest_assert_result`] reads the
908 /// already-drained `guest_messages`. A run with no guest verdict
909 /// ([`Self::guest_assert_result`] `Err` — host-only / early crash) folds
910 /// no carriers and returns the host-rebuilt buckets alone (the prior
911 /// behavior).
912 pub fn phase_buckets(&self) -> Vec<crate::assert::PhaseBucket> {
913 let mut buckets = self.phase_buckets_pre_derive();
914 // Derive the per-phase scalars into the now-final (post-fold) buckets so
915 // a per-phase A/B claim reads them via phase_metric / phase_cgroup_metric:
916 // the non-schbench carrier scalars (every cgroup) into each pc.metrics,
917 // and the schbench scalars into pc.metrics + the pooled bucket.metrics.
918 // A no-op only when no phase carries a per-cgroup carrier; must run
919 // post-fold (the merge skips is_derived keys, so an earlier derive would
920 // be dropped).
921 crate::assert::derive_phase_metrics(&mut buckets);
922 buckets
923 }
924
925 /// The pre-`derive_phase_metrics` phase fold: host buckets from
926 /// [`Self::periodic_series`] + [`Self::stimulus_timeline`] with the guest
927 /// per-cgroup carriers folded in, BEFORE the per-phase scalar derivation
928 /// [`Self::phase_buckets`] applies. This is the exact phase state the eval
929 /// layer feeds to [`crate::assert::populate_run_ext_all`].
930 /// [`Self::run_metric`] reuses it, and that helper performs the same
931 /// idempotent phase derivation as the eval path before folding run metrics.
932 /// Non-destructive on the snapshot bridge, like [`Self::phase_buckets`].
933 fn phase_buckets_pre_derive(&self) -> Vec<crate::assert::PhaseBucket> {
934 let host = crate::assert::build_phase_buckets_with_stimulus(
935 &self.periodic_series(),
936 &self.stimulus_timeline(),
937 );
938 match self.guest_assert_result() {
939 Ok(guest) => {
940 crate::assert::fold_guest_per_cgroup_into_host_buckets(host, guest.stats.phases)
941 }
942 Err(_) => host,
943 }
944 }
945
946 /// One phase's per-cgroup telemetry for `cgroup` — the per-phase analog
947 /// of reading `result.stats.cgroups` for a single phase. Reads
948 /// [`Self::phase_buckets`] (which folds the guest per-cgroup carriers
949 /// against the host capture windows) and returns the
950 /// [`crate::assert::PhaseCgroupStats`] keyed by `cgroup` in `phase`.
951 ///
952 /// `None` when `phase` has no bucket (no capture landed in it AND no
953 /// stimulus `StepStart` synthesized one) or the phase carries no carrier
954 /// for `cgroup` (the cgroup ran no workers in that phase, or the run had
955 /// no step-local cgroups). Owned (cloned from the folded bucket) so it
956 /// composes with the `&VmResult` `post_vm` callback signature.
957 pub fn phase_cgroup(
958 &self,
959 phase: crate::assert::Phase,
960 cgroup: &str,
961 ) -> Option<crate::assert::PhaseCgroupStats> {
962 self.phase_buckets()
963 .into_iter()
964 .find(|b| b.step_index == phase.as_u16())
965 .and_then(|b| b.per_cgroup.get(cgroup).cloned())
966 }
967
968 /// One framework-computed per-phase metric for `phase` — the
969 /// general metric-name form of [`Self::step_throughput`] /
970 /// [`Self::throughput_ratio`]. Resolves `metric` (any `impl Into<MetricId>` —
971 /// a typed `BuiltinMetric`, typo-proof, or a dynamic scheduler-runtime
972 /// string) from the folded
973 /// [`Self::phase_buckets`] bucket for `phase`, checking two stores:
974 /// 1. [`crate::assert::PhaseBucket::metrics`] (via
975 /// [`crate::assert::PhaseBucket::get`]) — the host-folded
976 /// per-sample / monitor / guest-carrier metrics: per-phase CPU time
977 /// (`system_time_ns`, `user_time_ns`), scheduling quality
978 /// (`avg_imbalance_ratio`, `avg_dsq_depth`, ...), and
979 /// `iteration_rate`.
980 /// 2. failing that, the cross-cgroup phase sum of a per-cgroup Counter
981 /// ([`crate::assert::PhaseBucket::cgroup_counter_total`]) for the
982 /// keys whose value lives ONLY in the per-cgroup carriers —
983 /// `"total_migrations"`, `"total_iterations"`, and
984 /// `"total_cpu_time_ns"`. These are
985 /// registered `Counter`s with no per-sample source
986 /// (`crate::stats::MetricDef::read_sample` returns `None`), so
987 /// they never reach `metrics`; without this fallback
988 /// `phase_metric(phase, "total_migrations")` returned a silent
989 /// `None` even though the value was present per-cgroup.
990 ///
991 /// The wake-latency / run-delay distributions (`MetricKind::Distribution`)
992 /// have no per-phase `metrics` value and no single per-cgroup Counter
993 /// (they re-pool run-level from the per-cgroup raw sample vectors), so
994 /// they are not readable here — read them per-cgroup via
995 /// [`Self::phase_cgroup`].
996 ///
997 /// Reads the SAME buckets [`Self::phase_buckets`] folds onto
998 /// `result.stats.phases`, so a `post_vm` callback can compare any
999 /// metric across two phases (e.g. scheduler-vs-detached-EEVDF
1000 /// `total_migrations` or `system_time_ns`) without re-deriving the
1001 /// buckets — the general form of the scheduler-vs-EEVDF throughput
1002 /// compare.
1003 ///
1004 /// `None` when `phase` has no bucket — no capture landed in it AND no
1005 /// stimulus `StepStart` synthesized one (e.g. `Phase::BASELINE` when
1006 /// the settle window fired no captures, or a `phase` past the last
1007 /// step) — or the bucket carries no reading for `metric` in either
1008 /// store. Sentinel-free, distinct from a real `Some(0.0)`: a
1009 /// per-cgroup counter returns `Some(0.0)` when carriers exist but
1010 /// counted zero, `None` only when the phase has no carrier at all. A
1011 /// started-but-uncaptured step (a `StepStart` with zero captures) DOES
1012 /// produce a synthesized bucket, and `phase_metric` can still return its
1013 /// guest-carrier-derived `iteration_rate`.
1014 ///
1015 /// ```ignore
1016 /// // Typed (typo-proof) is the primary form; a dynamic scheduler-runtime
1017 /// // string is the escape hatch through the SAME call.
1018 /// let p99 = result.phase_metric(Phase::step(0), BuiltinMetric::WakeupP99LatencyUs);
1019 /// let custom = result.phase_metric(Phase::step(0), "scx_layered_layer0_util");
1020 /// ```
1021 pub fn phase_metric(
1022 &self,
1023 phase: crate::assert::Phase,
1024 metric: impl Into<crate::stats::MetricId>,
1025 ) -> Option<f64> {
1026 let metric = metric.into();
1027 self.phase_buckets()
1028 .into_iter()
1029 .find(|b| b.step_index == phase.as_u16())
1030 .and_then(|b| {
1031 b.get(metric.as_str())
1032 .or_else(|| b.cgroup_counter_total(metric.as_str()))
1033 })
1034 }
1035
1036 /// One run-level extensible ("ext") metric by name — the whole-run analog of
1037 /// [`Self::phase_metric`], for a `post_vm` callback asserting a run-level
1038 /// aggregate (e.g. `avg_irq_util`, `max_cpu_hardirqs`,
1039 /// `worst_p99_wake_latency_us`, `iteration_rate`). SELF-COMPUTES the
1040 /// run-level `ext_metrics` map exactly as the framework's `evaluate_vm_result`
1041 /// does — a [`VmResult`](Self) carries no stored run-level stats (`post_vm`
1042 /// runs BEFORE the host populates them) — by replaying the shared
1043 /// [`crate::assert::populate_run_ext_all`] sequence over
1044 /// [`Self::periodic_series`], the pre-derive phase fold
1045 /// (`phase_buckets_pre_derive`), and the guest per-cgroup `stats.cgroups`.
1046 /// The result is byte-identical to the run-level `ext_metrics` the sidecar
1047 /// records for this run.
1048 ///
1049 /// Resolves the ext-sourced family that
1050 /// [`crate::assert::ScenarioStats::run_metric`] (the post-merge host
1051 /// accessor) resolves — the `read_sample`-wired registry metrics, the
1052 /// phase-only ext metrics (`avg_imbalance_ratio`, `iteration_rate`,
1053 /// `system_time_ns`, `user_time_ns`, the IRQ counters/rates, the per-CPU
1054 /// spatial maxes `max_cpu_hardirqs` / `max_cpu_softirq_net_rx` and their
1055 /// concentrations), the pooled `iteration_rate`, and the run-level
1056 /// `Distribution` / `WorstLowest` / `WakeLatencyTailRatio` / `WorstCrossNodeRatio`
1057 /// re-pools — and for
1058 /// those keys the two accessors return identical values (this one
1059 /// self-computes pre-merge, the other reads the stored post-merge map).
1060 ///
1061 /// ADDITIONALLY resolves the 5 ext-only run-level MONITOR metrics from
1062 /// [`Self::monitor`]'s summary: `avg_nr_running`, `avg_irq_util`,
1063 /// `max_avg_irq_util`, `psi_irq_full_avg10`, `total_irq_pressure_us` (folded
1064 /// via `MonitorSummary::fold_run_level_ext`, shared with the sidecar row).
1065 /// These DIVERGE from [`crate::assert::ScenarioStats::run_metric`], which has
1066 /// no `MonitorReport` to fold and returns `None` for them — the one place the
1067 /// two accessors differ.
1068 ///
1069 /// RESOLVED here None-aware (via the delegated `ScenarioStats::run_metric`
1070 /// typed dispatch): the cross-cgroup metrics `worst_spread`,
1071 /// `worst_migration_ratio`, `worst_gap_ms`, `total_migrations`,
1072 /// `total_iterations`, `worst_page_locality`,
1073 /// `worst_cross_node_migration_ratio`. The dispatch re-derives each from the
1074 /// carriers (the per-cgroup `stats.cgroups` + the per_cgroup-folded
1075 /// `stats.phases` this method builds) — `None` when no carrier measured it,
1076 /// `Some(0.0)` for a measured zero. The 5 non-NUMA metrics are 0.0-sentinel
1077 /// typed struct fields (re-derived because the field cannot carry the
1078 /// measured-vs-unmeasured distinction); the two NUMA roll-ups
1079 /// (`worst_page_locality`, `worst_cross_node_migration_ratio`) have no struct
1080 /// field and re-pool purely from the per-phase NUMA carriers.
1081 ///
1082 /// NOT resolved here:
1083 /// - the typed-backed monitor run-level metrics (`max_imbalance_ratio`,
1084 /// `max_dsq_depth`, `stuck_count`, `total_fallback`, `total_keep_last`) —
1085 /// these have typed `GauntletRow` fields (not ext-only); read them
1086 /// per-phase via [`Self::phase_metric`].
1087 ///
1088 /// Sentinel-free, matching [`Self::phase_metric`]: `None` means the metric is
1089 /// absent from this run (no populator produced it, or a name not in the map);
1090 /// `Some(0.0)` is a real measured zero. Check [`crate::stats::MetricId::def`]
1091 /// on a dynamic key to distinguish an unregistered key from genuinely-absent
1092 /// data (built-in ids always resolve).
1093 ///
1094 /// A host-only run (no guest verdict — [`Self::guest_assert_result`] `Err`)
1095 /// resolves the SampleSeries + phase families but no per-cgroup pooled /
1096 /// distribution keys (no per-cgroup data exists), the same absence
1097 /// [`crate::assert::ScenarioStats::run_metric`] documents.
1098 ///
1099 /// Non-destructive: reads the memoized snapshot-bridge drain
1100 /// ([`Self::periodic_series`] / [`Self::phase_buckets`]) and the
1101 /// already-drained `guest_messages`, so it composes with [`Self::phase_metric`]
1102 /// in one `post_vm` callback.
1103 ///
1104 /// ```ignore
1105 /// let irq = result.run_metric(BuiltinMetric::AvgIrqUtil);
1106 /// let custom = result.run_metric("scx_layered_layer0_util");
1107 /// ```
1108 pub fn run_metric(&self, metric: impl Into<crate::stats::MetricId>) -> Option<f64> {
1109 let metric = metric.into();
1110 let mut stats = crate::assert::ScenarioStats {
1111 phases: self.phase_buckets_pre_derive(),
1112 cgroups: self
1113 .guest_assert_result()
1114 .map(|g| g.stats.cgroups)
1115 .unwrap_or_default(),
1116 ..Default::default()
1117 };
1118 crate::assert::populate_run_ext_all(&mut stats, &self.periodic_series());
1119 // Fold the run-level ext-only monitor metrics (avg_nr_running + the PELT
1120 // IRQ load pair + the PSI-irq pair) from the stored MonitorReport
1121 // summary. populate_run_ext_all can't produce them — they're
1122 // MonitorSummary-sourced, not phase/series-folded — but VmResult holds
1123 // self.monitor, so (unlike ScenarioStats::run_metric, which has no
1124 // monitor) this accessor CAN resolve them. Shared with
1125 // group::sidecar_to_row via fold_run_level_ext.
1126 if let Some(report) = self.monitor.as_ref() {
1127 report.summary.fold_run_level_ext(&mut stats.ext_metrics);
1128 }
1129 // Delegate to ScenarioStats::run_metric: it resolves the typed
1130 // 0.0-sentinel cross-cgroup fields None-aware from the carriers
1131 // (stats.cgroups + the per_cgroup-folded stats.phases, both populated
1132 // above) ahead of the ext lookup — so the typed fields resolve here too,
1133 // matching ScenarioStats::run_metric. The monitor metrics folded into
1134 // stats.ext_metrics above resolve via that method's ext fallback.
1135 stats.run_metric(metric)
1136 }
1137
1138 /// Polarity-aware "is the `candidate` phase better than the `baseline` phase
1139 /// on `metric`?" comparator — the per-phase A/B primitive for "assert
1140 /// scheduler X beats EEVDF across phases" (e.g. an scx Step vs the EEVDF
1141 /// Step after `Op::DetachScheduler`). Resolves both per-phase values via
1142 /// [`Self::phase_metric`] and the metric's polarity via
1143 /// `crate::stats::metric_def`, then returns a
1144 /// [`crate::assert::temporal::BetterThanPhase`] builder whose terminal
1145 /// (`better_than` / `by_at_least`) records the outcome into `verdict`.
1146 /// "Better" is oriented from the registry polarity, so the SAME call works
1147 /// for a LowerBetter latency (`BuiltinMetric::WakeupP99LatencyUs`) and a
1148 /// HigherBetter CPU-normalized throughput
1149 /// (`BuiltinMetric::SchbenchLoopsPerCpuSec`) with no
1150 /// caller-specified direction.
1151 ///
1152 /// A post_vm callback collapses the verdict to its `anyhow::Result` via
1153 /// [`crate::assert::Verdict::into_anyhow_or_log`], which bails on a Fail OR
1154 /// an Inconclusive — so a missing metric (a phase with no schbench carrier),
1155 /// an undirected metric, or a zero-baseline fractional-margin comparison
1156 /// does NOT silently pass.
1157 pub fn better_across_phases<'v>(
1158 &self,
1159 verdict: &'v mut crate::assert::Verdict,
1160 baseline: crate::assert::Phase,
1161 candidate: crate::assert::Phase,
1162 metric: impl Into<crate::stats::MetricId>,
1163 ) -> crate::assert::temporal::BetterThanPhase<'v> {
1164 let metric = metric.into();
1165 crate::assert::temporal::BetterThanPhase::new(
1166 metric.as_str().to_string(),
1167 verdict,
1168 baseline,
1169 candidate,
1170 self.phase_metric(baseline, metric.clone()),
1171 self.phase_metric(candidate, metric.clone()),
1172 metric.def().map(|m| m.polarity),
1173 None, // pooled producer — no per-cgroup scope label
1174 )
1175 }
1176
1177 /// One per-phase, PER-CGROUP derived metric — the per-cgroup analog of
1178 /// [`Self::phase_metric`], answering "metric M of cgroup C in phase P" as
1179 /// readily as the phase aggregate (the N-cgroups-to-N-queryable-sets goal).
1180 /// Resolves `metric` (any `impl Into<MetricId>` — a typed `BuiltinMetric` or
1181 /// a dynamic scheduler-runtime string) from this
1182 /// cgroup's per-phase carrier via [`crate::assert::PhaseCgroupStats::get`] (its
1183 /// derived `metrics` map), falling back to
1184 /// [`crate::assert::PhaseCgroupStats::cgroup_counter`] for the per-cgroup
1185 /// Counters `total_migrations`/`total_iterations`/`total_cpu_time_ns` (carrier
1186 /// fields, not derived) — symmetric with [`Self::phase_metric`]'s
1187 /// `cgroup_counter_total` fallback.
1188 /// `None` when `phase` has no bucket, the bucket has no carrier for `cgroup`, or
1189 /// the carrier carried no finite value for the metric — sentinel-free, distinct
1190 /// from a real `Some(0.0)`.
1191 pub fn phase_cgroup_metric(
1192 &self,
1193 phase: crate::assert::Phase,
1194 cgroup: &str,
1195 metric: impl Into<crate::stats::MetricId>,
1196 ) -> Option<f64> {
1197 let metric = metric.into();
1198 self.phase_cgroup(phase, cgroup).and_then(|pc| {
1199 pc.get(metric.as_str())
1200 .or_else(|| pc.cgroup_counter(metric.as_str()))
1201 })
1202 }
1203
1204 /// Per-cgroup analog of [`Self::better_across_phases`]: "is `metric` of
1205 /// `cgroup` better in the `candidate` phase than the `baseline` phase?",
1206 /// oriented from the registry polarity. Reuses the SAME
1207 /// [`crate::assert::temporal::BetterThanPhase`] comparator/verdict machinery;
1208 /// only value resolution is re-scoped from the pooled aggregate to the named
1209 /// cgroup, so a missing carrier / undirected metric / zero-baseline margin
1210 /// collapses to Inconclusive (not a silent pass), exactly as the pooled form.
1211 pub fn better_across_phases_cgroup<'v>(
1212 &self,
1213 verdict: &'v mut crate::assert::Verdict,
1214 baseline: crate::assert::Phase,
1215 candidate: crate::assert::Phase,
1216 cgroup: &str,
1217 metric: impl Into<crate::stats::MetricId>,
1218 ) -> crate::assert::temporal::BetterThanPhase<'v> {
1219 let metric = metric.into();
1220 crate::assert::temporal::BetterThanPhase::new(
1221 metric.as_str().to_string(),
1222 verdict,
1223 baseline,
1224 candidate,
1225 self.phase_cgroup_metric(baseline, cgroup, metric.clone()),
1226 self.phase_cgroup_metric(candidate, cgroup, metric.clone()),
1227 metric.def().map(|m| m.polarity),
1228 Some(cgroup.to_string()), // per-cgroup scope label for the diagnostics
1229 )
1230 }
1231
1232 /// Minimal "nothing happened" fixture for tests that exercise
1233 /// code consuming a [`VmResult`] without actually booting a VM
1234 /// (the sidecar-write tests in `src/test_support/sidecar.rs`
1235 /// are the primary users). Every field carries the empty /
1236 /// default / `None` value that `run_vm` would produce for a
1237 /// VM that launched, exited cleanly with exit code 0, and
1238 /// produced no telemetry. Tests that need a specific field
1239 /// override it with a struct-update expression:
1240 ///
1241 /// ```ignore
1242 /// let result = VmResult { success: false, ..VmResult::test_fixture() };
1243 /// ```
1244 ///
1245 /// Gated on `#[cfg(test)]` so the symbol does not appear in
1246 /// release builds — production `VmResult` values flow from
1247 /// `run_vm` and never from this fixture. See
1248 /// `sidecar_vm_result_is_test_fixture_boilerplate` in
1249 /// `test_support/sidecar.rs` for the motivating deduplication
1250 /// (7 identical literal constructions collapsed to a single
1251 /// call).
1252 #[cfg(test)]
1253 pub fn test_fixture() -> Self {
1254 Self {
1255 success: true,
1256 vcpus: 1,
1257 cpu_budget: 1,
1258 resolve_source: None,
1259 expect_auto_repro_satisfied: false,
1260 exit_code: 0,
1261 duration: Duration::from_secs(1),
1262 timed_out: false,
1263 watchdog_kill_reason: None,
1264 final_guest_phase: GuestLifecyclePhase::Boot,
1265 final_progress_epoch: 0,
1266 bpf_map_writes_delivered: None,
1267 periodic_prereqs_ready: None,
1268 periodic_window_end: None,
1269 output: String::new(),
1270 stderr: String::new(),
1271 monitor: None,
1272 guest_messages: None,
1273 verifier_stats: Vec::new(),
1274 kvm_stats: None,
1275 crash_message: None,
1276 cleanup_duration: None,
1277 cleanup_sched_delta: None,
1278 virtio_blk_counters: None,
1279 virtio_net_counters: None,
1280 snapshot_bridge: empty_snapshot_bridge_for_tests(),
1281 stats_client: None,
1282 periodic_fired: 0,
1283 periodic_real: 0,
1284 periodic_target: 0,
1285 kern_kaslr_offset: 0,
1286 entry_name: None,
1287 variant_hash: 0,
1288 host_vcpu_schedstat: None,
1289 contention_witness: None,
1290 periodic_series_cache: std::sync::OnceLock::new(),
1291 }
1292 }
1293
1294 /// Per-test sidecar path for the `.wprof.pb` artifact:
1295 /// `{sidecar_dir()}/{entry_name}-{variant_hash:016x}.wprof.pb`.
1296 #[cfg(feature = "wprof")]
1297 pub fn wprof_pb_path(&self) -> anyhow::Result<std::path::PathBuf> {
1298 let name = self.entry_name.ok_or_else(|| {
1299 anyhow::anyhow!(
1300 "VmResult.entry_name is None — wprof_pb_path() requires the \
1301 macro-stamped entry name set by run_ktstr_test_inner_impl \
1302 after vm.run() returns. A `None` here means the VmResult \
1303 was constructed via the freeze_coord::collect_results \
1304 direct-synthesis path and the eval-layer stamping was \
1305 bypassed; route the result through run_ktstr_test_inner_impl \
1306 OR assign entry_name = Some(\"<test-fn-name>\") manually \
1307 before calling .wprof_pb_path()."
1308 )
1309 })?;
1310 Ok(crate::test_support::sidecar_dir()
1311 .join(format!("{name}-{:016x}.wprof.pb", self.variant_hash)))
1312 }
1313
1314 /// Per-test sidecar path for the `.repro.wprof.pb` artifact.
1315 #[cfg(feature = "wprof")]
1316 pub fn repro_wprof_pb_path(&self) -> anyhow::Result<std::path::PathBuf> {
1317 let name = self.entry_name.ok_or_else(|| {
1318 anyhow::anyhow!(
1319 "VmResult.entry_name is None — repro_wprof_pb_path() \
1320 requires the macro-stamped entry name set by \
1321 run_ktstr_test_inner_impl after vm.run() returns. A `None` \
1322 here means the VmResult was constructed via the \
1323 freeze_coord::collect_results direct-synthesis path and \
1324 the eval-layer stamping was bypassed; route the result \
1325 through run_ktstr_test_inner_impl OR assign entry_name \
1326 manually before calling."
1327 )
1328 })?;
1329 Ok(crate::test_support::sidecar_dir()
1330 .join(format!("{name}-{:016x}.repro.wprof.pb", self.variant_hash)))
1331 }
1332
1333 /// Per-test failure-dump sidecar path. Derives
1334 /// `{sidecar_dir()}/{entry_name}-{variant_hash:016x}.failure-dump.json`
1335 /// from the macro-stamped [`Self::entry_name`].
1336 ///
1337 /// # Sibling to
1338 /// [`crate::scenario::Ctx::failure_dump_path`]
1339 ///
1340 /// The pre-VM body context carries its own copy of the
1341 /// macro-stamped entry name (stamped at Ctx construction by
1342 /// the dispatch path) and computes the same path string. A
1343 /// test body invocation `ctx.failure_dump_path()` and a
1344 /// post-VM `result.failure_dump_path()` resolve to identical
1345 /// paths because both stamp from the same
1346 /// `entry.name: &'static str` source — proc-macro emission
1347 /// at the `#[ktstr_test]` site. This pair gives post_vm
1348 /// callbacks a symmetric path-derivation surface to the
1349 /// pre-VM body, so a future post_vm hook that wants to
1350 /// inspect or clean up the failure dump uses the same method
1351 /// shape the body uses to look at it.
1352 ///
1353 /// # Errors
1354 ///
1355 /// Returns `Err` when [`Self::entry_name`] is `None`.
1356 pub fn failure_dump_path(&self) -> anyhow::Result<std::path::PathBuf> {
1357 let name = self.entry_name.ok_or_else(|| {
1358 anyhow::anyhow!(
1359 "VmResult.entry_name is None — failure_dump_path() \
1360 requires the macro-stamped entry name set by \
1361 run_ktstr_test_inner_impl after vm.run() returns. \
1362 A `None` here means the VmResult was constructed via \
1363 the freeze_coord::collect_results direct-synthesis \
1364 path and the eval-layer stamping was bypassed; route \
1365 the result through run_ktstr_test_inner_impl OR \
1366 assign entry_name manually before calling."
1367 )
1368 })?;
1369 Ok(crate::test_support::sidecar_dir().join(format!(
1370 "{name}-{:016x}.failure-dump.json",
1371 self.variant_hash
1372 )))
1373 }
1374
1375 /// Concatenated guest `/dev/kmsg` content forwarded via
1376 /// `crate::send_kmsg`, or empty when no frames arrived (the scenario
1377 /// did not forward, or the VM exited before the forward completed).
1378 /// Lets a post_vm callback read the guest kernel log even at the
1379 /// default `loglevel=0`, where kernel printks never reach the COM1
1380 /// console (and thus not `stderr`). Encapsulates the bulk-port
1381 /// `ShmEntry` + `MsgType::Dmesg` filter inside the crate.
1382 pub fn guest_kmsg(&self) -> String {
1383 let Some(drain) = self.guest_messages.as_ref() else {
1384 return String::new();
1385 };
1386 drain
1387 .entries
1388 .iter()
1389 .filter(|e| {
1390 e.crc_ok
1391 && !e.payload.is_empty()
1392 && matches!(
1393 crate::vmm::wire::MsgType::from_wire(e.msg_type),
1394 Some(crate::vmm::wire::MsgType::Dmesg)
1395 )
1396 })
1397 .map(|e| String::from_utf8_lossy(&e.payload).into_owned())
1398 .collect::<Vec<String>>()
1399 .join("\n")
1400 }
1401
1402 /// The scheduler's captured log — its stderr, including any libbpf /
1403 /// BPF-verifier output — extracted from the bulk-port
1404 /// `MSG_TYPE_SCHED_LOG` frames in [`Self::guest_messages`]. Empty when
1405 /// no scheduler log was captured (no scheduler was spawned, or the
1406 /// framed markers never arrived).
1407 ///
1408 /// Mirrors the extraction [`crate::verifier::collect_verifier_output`]
1409 /// performs: concatenate the `SchedLog` chunks, slice the span from the
1410 /// first `SCHED_OUTPUT_START` to the last `SCHED_OUTPUT_END` (spanning
1411 /// any intervening markers when the guest staged more than one log),
1412 /// and fall back to `output` when the bulk-port drain carried no
1413 /// `SchedLog` frames (a kernel without the bulk port). Lets a post_vm
1414 /// callback assert on what the scheduler logged — e.g. a libbpf
1415 /// verifier-reject — without reaching into the crate-internal wire
1416 /// types.
1417 pub fn scheduler_log(&self) -> String {
1418 let merged = crate::verifier::concat_sched_log_chunks(self.guest_messages.as_ref());
1419 let source = if merged.is_empty() {
1420 &self.output
1421 } else {
1422 &merged
1423 };
1424 crate::verifier::parse_sched_output(source)
1425 .unwrap_or("")
1426 .to_string()
1427 }
1428
1429 /// The host watchdog-override readback (`expected_jiffies` =
1430 /// host-written, `observed_jiffies` = read back from guest memory).
1431 /// `None` when the scheduler never attached (no readback recorded).
1432 /// A post_vm callback asserts the two are equal to prove the override
1433 /// landed; the readback is taken eagerly by the monitor (in-DRAM,
1434 /// microseconds), so it is immune to the watchdog-kworker starvation
1435 /// that inflates the kernel-measured stall duration. Encapsulates the
1436 /// `MonitorReport` access (`WatchdogObservation` is re-exported at the
1437 /// crate root for the return type).
1438 pub fn watchdog_observation(&self) -> Option<crate::monitor::WatchdogObservation> {
1439 self.monitor.as_ref().and_then(|m| m.watchdog_observation)
1440 }
1441
1442 /// Assert the primary-VM `.wprof.pb` landed and is shape-valid.
1443 /// Returns `Ok(())` immediately when `self.success` is false.
1444 #[cfg(feature = "wprof")]
1445 pub fn assert_wprof_pb_landed(&self) -> anyhow::Result<()> {
1446 if !self.success {
1447 return Ok(());
1448 }
1449 // Pre-check `entry_name` with a callable-specific diagnostic
1450 // BEFORE delegating to `self.wprof_pb_path()` (which would
1451 // bail with the wprof_pb_path-perspective message). A
1452 // fixture-constructed VmResult hitting this method should
1453 // see a diagnostic naming `assert_wprof_pb_landed` so the
1454 // caller's mental model lines up with the error text.
1455 anyhow::ensure!(
1456 self.entry_name.is_some(),
1457 "VmResult::assert_wprof_pb_landed requires entry_name set by \
1458 run_ktstr_test_inner_impl after vm.run() returns. This \
1459 VmResult was constructed manually (freeze_coord direct \
1460 synthesis path or a test fixture); either route the result \
1461 through run_ktstr_test_inner_impl OR call \
1462 crate::test_support::wprof::assert_wprof_pb_shape with a \
1463 manually-computed path.",
1464 );
1465 let path = self.wprof_pb_path()?;
1466 crate::test_support::wprof::assert_wprof_pb_shape(&path)
1467 }
1468}
1469
1470/// Build an empty `SnapshotBridge` whose capture callback always
1471/// returns `None`. Used by `VmResult::test_fixture` and the legacy
1472/// `VmResult` literal constructions in unit tests so they still
1473/// compile after the snapshot_bridge field landed. Production
1474/// `run_vm` constructs its own bridge whose callback is
1475/// intentionally unused — the freeze coordinator stores reports
1476/// directly via `bridge.store(name, report)`.
1477#[cfg(test)]
1478pub(crate) fn empty_snapshot_bridge_for_tests() -> crate::scenario::snapshot::SnapshotBridge {
1479 let cb: crate::scenario::snapshot::CaptureCallback = std::sync::Arc::new(|_| None);
1480 crate::scenario::snapshot::SnapshotBridge::new(cb)
1481}
1482
1483/// Host-side vCPU scheduling-dilation sample, summed over the run's
1484/// vCPU host threads.
1485///
1486/// Dilation `D = 1 + Σrun_delay / Σon_cpu`, where the two sums are
1487/// taken over each vCPU host thread's `/proc/self/task/<tid>/schedstat`
1488/// (field 1 = time on-CPU ns, field 2 = time runnable-but-not-running
1489/// ns). `D == 1.0` means the vCPU threads always got the CPU the instant
1490/// they were runnable; `D > 1.0` quantifies host-side scheduling delay
1491/// (e.g. `1.03x` = threads waited 3% on top of their run time).
1492///
1493/// Idle-immune: a halted vCPU is blocked (not runnable), so it accrues
1494/// no `run_delay` — halt time never inflates `D`. Measured HOST-side
1495/// deliberately: the guest run-queue's own `run_delay` would measure the
1496/// scheduler under test, which is the thing being evaluated; the host
1497/// thread's schedstat measures the CPU the vCPU thread was starved of by
1498/// the HOST, orthogonal to the guest scheduler.
1499///
1500/// RAW totals are stored (not the ratio) so future consumers can
1501/// recompute or re-aggregate; [`Self::dilation`] derives the ratio.
1502///
1503/// `total_on_cpu_ns == 0` yields `dilation() == None` — this happens
1504/// BOTH when no vCPU thread ran at all AND on a host built without
1505/// `CONFIG_SCHEDSTATS` (every schedstat line reads `"0 0 0"`). `None` is
1506/// thus graceful and distinguishable from a genuine `D == 1.0`.
1507#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1508pub struct HostVcpuSchedstat {
1509 /// Σ schedstat field 1 (time the vCPU threads spent ON-CPU), ns.
1510 pub total_on_cpu_ns: u64,
1511 /// Σ schedstat field 2 (time the vCPU threads spent runnable but
1512 /// not running — host-side scheduling delay), ns.
1513 pub total_run_delay_ns: u64,
1514 /// Number of vCPU host threads that contributed to the sums (a TID
1515 /// still 0 — an AP that never stamped its TID — and an unreadable
1516 /// schedstat are both skipped).
1517 pub sampled_vcpus: u32,
1518}
1519
1520impl HostVcpuSchedstat {
1521 /// Host dilation `D = 1 + Σrun_delay / Σon_cpu`, or `None` when no
1522 /// on-CPU time was sampled (no vCPU ran, or the host lacks
1523 /// `CONFIG_SCHEDSTATS` and every line read `"0 0 0"`). `None` is
1524 /// deliberately distinguishable from a true `D == 1.0` (which needs
1525 /// nonzero on-CPU time with zero run-delay).
1526 pub fn dilation(&self) -> Option<f64> {
1527 (self.total_on_cpu_ns > 0)
1528 .then(|| 1.0 + self.total_run_delay_ns as f64 / self.total_on_cpu_ns as f64)
1529 }
1530
1531 /// Field-wise saturating delta `self - anchor` over the two schedstat
1532 /// sums — the on-CPU / run-delay accrued BETWEEN two cumulative
1533 /// snapshots of the same vCPU threads. `sampled_vcpus` carries `self`'s
1534 /// count (the reading the delta closes at). Saturating so a schedstat
1535 /// that momentarily regressed (a TID that vanished then reappeared, a
1536 /// torn read) contributes 0 rather than wrapping — conservative: a
1537 /// per-phase `D` can only be UNDER-stated by such a clamp, never
1538 /// fabricated. The result's [`Self::dilation`] is the phase-local `D`.
1539 pub fn delta_from(&self, anchor: &HostVcpuSchedstat) -> HostVcpuSchedstat {
1540 HostVcpuSchedstat {
1541 total_on_cpu_ns: self.total_on_cpu_ns.saturating_sub(anchor.total_on_cpu_ns),
1542 total_run_delay_ns: self
1543 .total_run_delay_ns
1544 .saturating_sub(anchor.total_run_delay_ns),
1545 sampled_vcpus: self.sampled_vcpus,
1546 }
1547 }
1548}
1549
1550/// Number of `LifecycleStage` variants (Boot, Attach,
1551/// Dispatch, Body, Teardown) — the length of the per-phase witness array.
1552/// Kept in lock-step with that enum; [`PerPhaseSchedstat::for_stage`] indexes
1553/// by `stage as usize`, so a new stage variant needs this bumped.
1554pub const NUM_LIFECYCLE_STAGES: usize = 5;
1555
1556/// Array index of the BODY stage (the measurement phase) — pinned to the
1557/// enum discriminant so it can never drift from
1558/// `LifecycleStage::Body`.
1559pub const BODY_STAGE_INDEX: usize = crate::monitor::LifecycleStage::Body as usize;
1560
1561/// Per-lifecycle-phase host-dilation witness: normally one
1562/// [`HostVcpuSchedstat`] DELTA per stage, covering the schedstat accrued
1563/// between lifecycle-event boundary snapshots. If the guest-reported
1564/// scenario duration proves queued lifecycle frames did not bracket Body,
1565/// Body instead carries the complete enclosing vCPU-thread lifetime. That
1566/// conservative fallback can overstate Body contention but cannot hide it.
1567/// Indexed by `LifecycleStage` `as usize`.
1568///
1569/// Distinct from the whole-run [`VmResult::host_vcpu_schedstat`] (which is
1570/// the verdict-line `D` over the entire run): normally each phase gets its OWN
1571/// `D` over its OWN span, so the Body phase's dilation — the only phase whose
1572/// contention actually contaminates the workload measurement — is isolated
1573/// from the Boot / Attach / Teardown INFRA phases. The batched-delivery
1574/// fallback deliberately gives up that localization. `Boot`/`Attach` `D` is
1575/// diagnostic; `Body` is the one the latency verdict consumes.
1576///
1577/// The dispatch path takes each boundary snapshot immediately after accepting
1578/// the CRC-valid lifecycle frame. ScenarioEnd's guest duration detects
1579/// start/end frames accepted together after a starved dispatch loop. A wide-VM
1580/// snapshot is a sequential sweep of the vCPU TIDs rather than an atomic
1581/// kernel operation, so its uncertainty is the duration of that rare sweep,
1582/// not the monitor's sampling period.
1583#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1584pub struct PerPhaseSchedstat {
1585 /// Per-stage schedstat delta, indexed by `LifecycleStage as usize`
1586 /// (Boot=0 .. Teardown=4). A stage never entered stays at the
1587 /// `Default` all-zero value (`dilation() == None`).
1588 pub phases: [HostVcpuSchedstat; NUM_LIFECYCLE_STAGES],
1589}
1590
1591impl PerPhaseSchedstat {
1592 /// The Body (measurement) phase's schedstat delta — the phase whose
1593 /// dilation the latency verdict consumes.
1594 pub fn body(&self) -> &HostVcpuSchedstat {
1595 &self.phases[BODY_STAGE_INDEX]
1596 }
1597
1598 /// The Body phase's host dilation `D`, or `None` when no on-CPU time was
1599 /// sampled in the Body span (schedstats off, or the phase never ran).
1600 pub fn body_dilation(&self) -> Option<f64> {
1601 self.body().dilation()
1602 }
1603
1604 /// The schedstat delta for one lifecycle stage (diagnostic access to the
1605 /// Boot/Attach/Dispatch/Teardown phases). `pub(crate)`: takes the
1606 /// crate-internal `LifecycleStage`. `allow(dead_code)`:
1607 /// the diagnostic Boot/Attach `D` readers land with the LATER seam pass;
1608 /// `body()` is the wired accessor.
1609 #[allow(dead_code)]
1610 pub(crate) fn for_stage(&self, stage: crate::monitor::LifecycleStage) -> &HostVcpuSchedstat {
1611 &self.phases[stage as usize]
1612 }
1613}
1614
1615/// Body-phase peak-window contamination series. New witnesses store deltas of
1616/// the ktstr runner cgroup's CPU PSI `some total` clock: time during which at
1617/// least one runnable task in that cgroup was stalled for CPU. This includes a
1618/// delayed vCPU even when its competitor is outside the cgroup, without
1619/// charging pressure in unrelated host cgroups. Each entry has its real
1620/// observation width in [`Self::tick_widths_ns`], allowing the window
1621/// calculation to remain sound when the monitor is starved and wakes much
1622/// later than its nominal cadence.
1623///
1624/// Legacy/deserialized witnesses may have no width vector; those retain the
1625/// fixed-grid `tick_ns` interpretation. Bounded storage: observations are
1626/// nominally 100 ms apart and Body phases run minutes, so a few thousand
1627/// entries is typical; the series is capped at 36,000 intervals and
1628/// `saturated` is set if the cap is hit. When
1629/// `saturated`, the series is a PREFIX of the phase, so `W` computed from it
1630/// is a LOWER bound — a later verdict pass should treat that as reducing
1631/// confidence in a `FailConfirmed` rather than trusting a possibly-short `W`.
1632///
1633/// COVERAGE SOUNDNESS: new witnesses sample the cumulative PSI counter at
1634/// accepted lifecycle boundaries as well as monitor wakes, so the first and
1635/// last samples explicitly close the entire Body span. A starved monitor may
1636/// produce one coarse interval instead of many fine ones, but charging that
1637/// interval's entire delta remains an upper bound for every window it can
1638/// touch. If either boundary sample fails or storage saturates, `complete` is
1639/// false and the seam cannot use the series to confirm a failure.
1640///
1641/// Legacy witnesses have no explicit completeness bit. For them the seam
1642/// retains the old conservative check that the fixed-grid samples span enough
1643/// of Body; an empty or clustered series can only demote a result, never
1644/// produce a false confirmation.
1645#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1646pub struct BodyContentionWindow {
1647 /// Per-observation CPU-contention delta (ns) over the Body phase, in time
1648 /// order. New witnesses use runner-cgroup CPU PSI `some total`; legacy
1649 /// witnesses contain summed vCPU schedstat run-delay.
1650 pub tick_deltas: Vec<u64>,
1651 /// Real wall width (ns) of each corresponding delta interval. Empty on
1652 /// legacy witnesses. When present, length matches `tick_deltas` and the
1653 /// peak-window calculation uses these widths instead of a nominal grid.
1654 #[serde(default)]
1655 pub tick_widths_ns: Vec<u64>,
1656 /// The nominal monitor tick period (ns) the deltas were sampled at
1657 /// (100 ms in production). Used only by legacy witnesses without real
1658 /// interval widths.
1659 pub tick_ns: u64,
1660 /// True when [`Self::tick_deltas`] hit its cap and later Body ticks were
1661 /// dropped — the series is then a prefix and `W` from it is a lower bound.
1662 pub saturated: bool,
1663 /// True when lifecycle-event samples anchored BOTH ends of Body (the
1664 /// start is conservatively pulled back to the preceding lifecycle
1665 /// boundary to cover virtio dispatch lag), making the cumulative interval
1666 /// series complete even if it contains only one coarse interval. A host
1667 /// acceptance span shorter than ScenarioEnd's guest duration invalidates
1668 /// those edge samples; the complete whole-vCPU-lifetime fallback may then
1669 /// restore completeness as one conservative interval. False on legacy
1670 /// sampled witnesses, whose coverage is inferred from their first/last
1671 /// monitor ticks.
1672 #[serde(default)]
1673 pub complete: bool,
1674 /// Complete summed vCPU schedstat run-delay (ns) over the conservative
1675 /// wall span of this series, or (when the preceding lifecycle snapshot
1676 /// raced vCPU startup) the enclosing whole-thread lifetime. When
1677 /// [`Self::schedstat_cap_complete`] is true, `W(L)` is capped by this
1678 /// value: a request cannot absorb more task-specific scheduling delay in
1679 /// one window than all vCPUs accumulated over the enclosing span. This
1680 /// removes unrelated runner-cgroup PSI without under-bounding the target
1681 /// VM's delay.
1682 #[serde(default)]
1683 pub schedstat_cap_ns: u64,
1684 /// True when the closing snapshot sampled the complete live vCPU set and
1685 /// the cap is therefore a sound upper bound. An exact matching opening
1686 /// snapshot produces the tighter Body delta; otherwise the complete
1687 /// whole-thread-life total is used. False for legacy witnesses and
1688 /// partial/failed closing reads, in which case the cap is ignored.
1689 #[serde(default)]
1690 pub schedstat_cap_complete: bool,
1691 /// The wall span (ns) covered by the Body witness. Normally the start is
1692 /// conservatively pinned to the accepted lifecycle boundary preceding
1693 /// Body, covering any time the guest's Body frame waited in virtio
1694 /// dispatch; the end is the first accepted transition after Body. It may
1695 /// therefore include adjacent-stage time, which makes `W` larger and can
1696 /// only bias the verdict toward indeterminate. If that accepted span is
1697 /// shorter than ScenarioEnd's guest duration, the guest duration widens
1698 /// it for the whole-lifetime fallback. `0` when Body was never observed.
1699 pub body_wall_ns: u64,
1700 /// The wall span (ns) the series actually covered. For event-anchored
1701 /// complete witnesses this equals `body_wall_ns`; for legacy witnesses it
1702 /// is the elapsed between the first and last Body monitor tick.
1703 pub body_covered_ns: u64,
1704}
1705
1706/// The event-anchored host-contention witness: per-phase vCPU schedstat
1707/// dilation plus the Body-phase CPU-pressure interval series. The monitor
1708/// contributes constant-cost samples on its existing timer wakes; lifecycle
1709/// dispatch anchors the stage boundaries. Carried on
1710/// [`VmResult::contention_witness`] so a later seam pass can call
1711/// `latency_verdict` to turn a latency threshold into a tri-state,
1712/// contention-aware verdict.
1713///
1714/// `None` on [`VmResult`] when neither vCPU schedstat nor CPU PSI supplied any
1715/// evidence. A present but incomplete Body series is retained for diagnostics
1716/// but cannot confirm a latency failure.
1717#[derive(Debug, Clone, Default, PartialEq, serde::Serialize, serde::Deserialize)]
1718pub struct ContentionWitness {
1719 /// Per-lifecycle-phase host-dilation deltas (Boot..Teardown).
1720 pub per_phase: PerPhaseSchedstat,
1721 /// Body-phase contention intervals for the `W(L)` bound.
1722 pub body_window: BodyContentionWindow,
1723}
1724
1725impl ContentionWitness {
1726 /// The Body-phase host dilation `D` (annotation for the latency verdict);
1727 /// `None` when no Body on-CPU time was sampled.
1728 pub fn body_dilation(&self) -> Option<f64> {
1729 self.per_phase.body_dilation()
1730 }
1731}
1732
1733/// Per-vCPU KVM stats read after VM exit. Each map holds cumulative
1734/// counter values from the VM's lifetime.
1735#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1736pub struct KvmStatsTotals {
1737 /// Per-vCPU stat maps. Index is vCPU id.
1738 pub per_vcpu: Vec<HashMap<String, u64>>,
1739}
1740
1741/// KVM stat names surfaced in sidecar output for scheduler testing.
1742///
1743/// Covers VM exit rate, halt-polling behavior, preemption notifications,
1744/// signal-driven exits, and hypercall counts; all fields scheduler
1745/// authors typically correlate with scx decisions.
1746///
1747/// Per-arch availability: `halt_exits`, `preemption_reported`, and
1748/// `hypercalls` are published by KVM only on x86. On aarch64 the
1749/// kernel does not expose these stats via `KVM_GET_STATS_FD`; they
1750/// are absent from the per-vCPU map and read as `0` from
1751/// [`KvmStatsTotals::sum`] / [`KvmStatsTotals::avg`]. The remaining
1752/// names (`exits`, `halt_successful_poll`, `halt_attempted_poll`,
1753/// `halt_wait_ns`, `signal_exits`) are published on both arches.
1754#[allow(dead_code)]
1755pub const KVM_INTERESTING_STATS: &[&str] = &[
1756 "exits",
1757 "halt_exits",
1758 "halt_successful_poll",
1759 "halt_attempted_poll",
1760 "halt_wait_ns",
1761 "preemption_reported",
1762 "signal_exits",
1763 "hypercalls",
1764];
1765
1766impl KvmStatsTotals {
1767 /// Sum a stat across all vCPUs. Returns 0 BOTH when no vCPU published
1768 /// the stat and when every vCPU measured zero — use [`Self::try_sum`]
1769 /// to distinguish "unpublished" from "measured zero".
1770 pub fn sum(&self, name: &str) -> u64 {
1771 self.try_sum(name).unwrap_or(0)
1772 }
1773
1774 /// Average a stat across all vCPUs (returns 0 if no vCPUs). Same
1775 /// absent-vs-zero ambiguity as [`Self::sum`]; see [`Self::try_avg`].
1776 pub fn avg(&self, name: &str) -> u64 {
1777 self.try_avg(name).unwrap_or(0)
1778 }
1779
1780 /// Sum a stat across all vCPUs, or `None` when NO per-vCPU map
1781 /// published it. Distinguishes an unpublished stat (`None`) from a
1782 /// genuinely-measured zero (`Some(0)`) — the plain [`Self::sum`]
1783 /// collapses both to `0`, so a test reading a counter that the kernel
1784 /// never emitted on this arch cannot tell it apart from a real zero.
1785 pub fn try_sum(&self, name: &str) -> Option<u64> {
1786 let mut acc: Option<u64> = None;
1787 for m in &self.per_vcpu {
1788 if let Some(&v) = m.get(name) {
1789 acc = Some(acc.unwrap_or(0) + v);
1790 }
1791 }
1792 acc
1793 }
1794
1795 /// Average a stat across all vCPUs, or `None` when there are no vCPUs
1796 /// or NO per-vCPU map published the stat. The absent-aware counterpart
1797 /// of [`Self::avg`].
1798 pub fn try_avg(&self, name: &str) -> Option<u64> {
1799 let n = self.per_vcpu.len() as u64;
1800 if n == 0 {
1801 return None;
1802 }
1803 self.try_sum(name).map(|s| s / n)
1804 }
1805}
1806
1807/// State returned by [`super::KtstrVm::run_vm`] after the BSP exits.
1808/// Passed to [`super::KtstrVm::collect_results`] to produce
1809/// [`VmResult`].
1810pub(crate) struct VmRunState {
1811 pub(crate) exit_code: i32,
1812 pub(crate) timed_out: bool,
1813 /// Raw kill-reason byte loaded from the watchdog thread's latch
1814 /// after its join (`freeze_coord::KillReasonTag` layout; 0 =
1815 /// unset). Decoded into [`VmResult::watchdog_kill_reason`] by
1816 /// `collect_results`, which owns the tag type.
1817 pub(crate) watchdog_kill_reason_raw: u8,
1818 /// Raw final lifecycle-stage byte from the progress ledger
1819 /// (`monitor::LifecycleStage` layout). Decoded into
1820 /// [`VmResult::final_guest_phase`] by `collect_results`.
1821 pub(crate) final_guest_phase_raw: u8,
1822 /// Final ledger milestone count → [`VmResult::final_progress_epoch`].
1823 pub(crate) final_progress_epoch: u64,
1824 /// Raw BPF-map-write injection delivery state (0 = none
1825 /// configured, 1 = pending/never delivered, 2 = delivered) —
1826 /// decoded into [`VmResult::bpf_map_writes_delivered`].
1827 pub(crate) bpf_map_write_delivery_raw: u8,
1828 /// Cleanup-window-open schedstat snapshot of the run_vm caller
1829 /// thread (the join/drain performer) — closed by `collect_results`
1830 /// into [`VmResult::cleanup_sched_delta`].
1831 pub(crate) cleanup_sched_t0: Option<HostVcpuSchedstat>,
1832 /// Run-relative ns when the periodic prereqs (kaslr + accessors)
1833 /// became ready (0 = never) → [`VmResult::periodic_prereqs_ready`].
1834 pub(crate) periodic_prereqs_ready_ns_raw: u64,
1835 /// Run-relative ns of the periodic capture-window end (0 = the
1836 /// window never resolved) → [`VmResult::periodic_window_end`].
1837 pub(crate) periodic_window_end_ns_raw: u64,
1838 /// Framework/infrastructure failure raised after the VM had already
1839 /// started. `collect_results` performs the complete teardown first, then
1840 /// returns this as a marker-typed error which cannot be inverted by
1841 /// `expect_err` or classified as a resource skip.
1842 pub(crate) framework_error: Option<String>,
1843 /// Event-anchored per-phase dilation + Body contention intervals,
1844 /// finalized from live proc entries plus one-shot AP exit snapshots.
1845 pub(crate) contention_witness: Option<ContentionWitness>,
1846 /// Armed owner for every AP, monitor, and BPF-map-writer thread which can
1847 /// retain a raw view of guest memory. It moves directly from `run_vm` into
1848 /// this handoff state without a naked-JoinHandle interval. Its Drop runs
1849 /// before `vm` (field declaration order), so an unwind or an abandoned
1850 /// `VmRunState` still bounded-joins all readers before guest memory unmaps.
1851 pub(crate) run_threads: super::freeze_coord::RunVmThreadGuard,
1852 pub(crate) com1: Arc<PiMutex<console::Serial>>,
1853 pub(crate) com2: Arc<PiMutex<console::Serial>>,
1854 pub(crate) kill: Arc<AtomicBool>,
1855 /// Wake fd paired with `kill`. Setters that flip `kill`
1856 /// (`collect_results`, vCPU shutdown classifier, panic hook)
1857 /// also write to this EventFd so any consumer blocked in
1858 /// `epoll_wait` (notably the freeze coordinator and the
1859 /// monitor sampler) wakes within microseconds of the flip
1860 /// rather than waiting up to one full poll interval. The
1861 /// AtomicBool above remains the source of truth — the EventFd
1862 /// is purely a wake signal. EFD_NONBLOCK so a saturated
1863 /// counter never stalls the writer.
1864 pub(crate) kill_evt: Arc<vmm_sys_util::eventfd::EventFd>,
1865 /// Broadcast freeze flag for the failure-dump coordinator. When the
1866 /// coordinator receives a guest-side error-exit signal it sets this
1867 /// to true, kicks every vCPU, waits for all `parked` flags to flip
1868 /// true, and then reads guest BPF map state. Released to false to
1869 /// resume normal execution. Lives alongside `kill` so the same Arc
1870 /// pattern (broadcast + per-vCPU ACK) covers both shutdown and
1871 /// freeze rendezvous.
1872 pub(crate) freeze: Arc<AtomicBool>,
1873 /// Hardware-watchpoint arming state Arc, forwarded so
1874 /// [`super::KtstrVm::collect_results`] can invalidate the
1875 /// `kind_host_ptr` and `request_kva` slots after every vCPU
1876 /// thread joins but BEFORE `vm` drops.
1877 ///
1878 /// Without the invalidation, the slots' published values
1879 /// continue to address (a) a host pointer into `vm.guest_mem`'s
1880 /// mapping that becomes unmapped when `vm` drops and (b) a
1881 /// guest KVA whose translation goes through the same mapping.
1882 /// The freeze coordinator joins before `vm` drops in
1883 /// `run_vm`, and AP threads join inside `collect_results` —
1884 /// but defense-in-depth says we zero the slots once every
1885 /// reader is gone so any future restructuring (a stray Arc
1886 /// clone surviving past teardown, a follow-up that adds a
1887 /// new reader path) cannot trip a use-after-free.
1888 ///
1889 /// Declared before `vm` so the implicit drop order on
1890 /// `VmRunState` teardown drops `watchpoint` first: any Arc
1891 /// clone outliving the struct can no longer dereference its
1892 /// `kind_host_ptr` after `vm.guest_mem` has unmapped, even if
1893 /// a future caller forgets the explicit pre-drop
1894 /// invalidation in `collect_results`.
1895 pub(crate) watchpoint: Arc<WatchpointArm>,
1896 pub(crate) vm: kvm::KtstrKvm,
1897 /// Captured immediately after the BSP exits its run loop. Subtracted
1898 /// from `Instant::now()` in [`super::KtstrVm::collect_results`]
1899 /// right before the [`VmResult`] is returned to populate
1900 /// [`VmResult::cleanup_duration`]. Records the wall-clock cost of
1901 /// every host-side teardown step that runs after the guest has
1902 /// stopped advancing, in execution order: the watchdog-thread join
1903 /// in [`super::KtstrVm::run_vm`], then the AP-thread joins, the
1904 /// monitor-thread join, the BPF-map-writer join, the SHM-ring
1905 /// drain, the post-exit exit-code/crash-message extraction, and
1906 /// finally the BPF verifier-stat read inside
1907 /// [`super::KtstrVm::collect_results`].
1908 pub(crate) cleanup_start: Instant,
1909 /// Cloned counter handle from `KtstrVm::init_virtio_blk`
1910 /// when a disk was attached, captured before the device-arc is
1911 /// dropped so [`super::KtstrVm::collect_results`] can snapshot
1912 /// it into [`VmResult::virtio_blk_counters`]. The device worker
1913 /// bumps these atomics from `drain_bracket_impl` (production cfg:
1914 /// dedicated `ktstr-vblk` thread; cfg(test): inline on the test
1915 /// thread); by the time `collect_results` reads this field every
1916 /// vCPU thread has joined upstream, the worker can receive no
1917 /// further kicks, and the conversion site
1918 /// (`run.virtio_blk_counters.as_deref().map(|c| c.snapshot())`)
1919 /// loads the final cumulative state into a plain-u64 snapshot
1920 /// before storing on the public `VmResult`.
1921 pub(crate) virtio_blk_counters: Option<Arc<VirtioBlkCounters>>,
1922 /// Cloned per-NIC counter handles from the net device init
1923 /// (`init_virtio_net` on aarch64 / `init_virtio_net_pci` on x86_64, both
1924 /// arch-gated), one per attached NIC, captured before the device arcs are
1925 /// dropped so [`super::KtstrVm::collect_results`] can snapshot and aggregate
1926 /// them into [`VmResult::virtio_net_counters`] via
1927 /// [`VirtioNetCountersSnapshot::aggregate`]. Empty when no NIC is attached.
1928 pub(crate) virtio_net_counters: Vec<Arc<VirtioNetCounters>>,
1929 /// Snapshot bridge owning every report captured during the run.
1930 /// The freeze coordinator clones this bridge into its closure
1931 /// state; on every guest-side
1932 /// [`crate::vmm::wire::MSG_TYPE_SNAPSHOT_REQUEST`] frame the
1933 /// coordinator's TOKEN_TX handler decoded with kind
1934 /// [`crate::vmm::wire::SNAPSHOT_KIND_CAPTURE`], the dispatch runs
1935 /// `freeze_and_dispatch(FreezeMode::Capture { gate_on_exit_kind: false })` and stores the resulting
1936 /// `FailureDumpReport` here keyed by the snapshot name. After
1937 /// VM exit, [`super::KtstrVm::collect_results`] forwards the
1938 /// bridge onto [`VmResult::snapshot_bridge`] so the test code
1939 /// can drain captured snapshots and walk them via the
1940 /// [`crate::scenario::snapshot::Snapshot`] accessor surface.
1941 pub(crate) snapshot_bridge: crate::scenario::snapshot::SnapshotBridge,
1942 /// Cached aarch64 TCR_EL1 register, populated lazily by the BSP
1943 /// once the guest kernel programs the MMU. Always `None` on
1944 /// x86_64 (the register does not exist). Threads that construct
1945 /// a `GuestKernel` for page-table walks (monitor, BPF map writer,
1946 /// freeze coordinator, post-exit verifier-stats collector) read
1947 /// this atomic to feed the granule-agnostic walker (4 KB / 16 KB
1948 /// / 64 KB). A 0 reading on aarch64 means "kernel hasn't reached
1949 /// MMU bring-up yet"; the walker's T1SZ=0 gate rejects walks in
1950 /// that state and the affected lookup returns `None` cleanly.
1951 pub(crate) tcr_el1: Option<Arc<std::sync::atomic::AtomicU64>>,
1952 /// Cached BSP CR3 (x86_64) / TTBR1_EL1 (aarch64), populated lazily
1953 /// by the BSP loop after initial page-table setup. Used by
1954 /// post-exit `GuestKernel` constructions to walk the live page
1955 /// tables for `phys_base` resolution. `0` means the cache wasn't
1956 /// populated (early boot crash); the walk fails and `phys_base`
1957 /// falls back to `0`, which produces correct translations on
1958 /// non-KASLR boots.
1959 pub(crate) cr3: Arc<std::sync::atomic::AtomicU64>,
1960 /// Optional preloaded vmlinux bytes for the exceptional
1961 /// `collect_verifier_stats` fallback. Ordinary VM runs leave this `None`:
1962 /// the live prog accessor consumes the shared derived artifacts, and the
1963 /// fallback loads bytes lazily only when it is genuinely needed.
1964 pub(crate) vmlinux_data: Option<Arc<Vec<u8>>>,
1965 /// Pre-built prog accessor from the accessor-init worker.
1966 /// When present, `collect_verifier_stats` skips the ~4s
1967 /// ELF/BTF parse and uses this directly.
1968 pub(crate) prog_accessor: Option<crate::monitor::bpf_prog::GuestMemProgAccessorOwned>,
1969 /// Guest-reported phys_base (biased +1). Used by
1970 /// `collect_verifier_stats` fallback when the pre-built prog
1971 /// accessor is unavailable.
1972 pub(crate) kern_phys_base: u64,
1973 /// Runtime virt-KASLR offset (kernel-image slide), captured from
1974 /// the freeze coordinator's `kern_virt_kaslr` Arc snapshot at run
1975 /// end via `load(Acquire).saturating_sub(1)`. `0` means either
1976 /// (a) KASLR was off (test ran with `#[ktstr_test(kaslr = false)]`
1977 /// or `Scheduler::kargs(&["nokaslr"])`), or (b) the derivation
1978 /// chain (MSR_LSTAR readback at `vmm::x86_64::msr_kaslr` +
1979 /// KERN_ADDRS `_text` path at `crate::vmm::freeze_coord::dispatch`) never
1980 /// published a non-zero value (early-boot crash, kallsyms masked
1981 /// by kptr_restrict, FRED-enabled kernel). E2E test consumers
1982 /// distinguish (a) from (b) by asserting against the test entry's
1983 /// `kaslr` attribute. The companion [`Self::kern_phys_base`]
1984 /// carries the kernel-image physical-randomization slide; together
1985 /// they identify the KASLR-randomized kernel layout.
1986 pub kern_kaslr_offset: u64,
1987 /// Virtio-console device shared with vCPU threads. Carries the
1988 /// port-1 (`ktstr-bulk`) TLV stream from guest to host;
1989 /// `collect_results` calls `drain_bulk()` after the run to feed
1990 /// `parse_tlv_stream` and produce the `BulkDrainResult` that
1991 /// `VmResult.guest_messages` exposes to test verdicts.
1992 pub(crate) virtio_con: Arc<crate::vmm::PiMutex<crate::vmm::virtio_console::VirtioConsole>>,
1993 /// Bulk TLV entries the freeze coordinator parsed from
1994 /// `port1_tx_buf` mid-run. The coord's TOKEN_TX handler reads
1995 /// the device's accumulated bulk bytes, feeds them through
1996 /// [`crate::vmm::bulk::HostAssembler`], and stashes every parsed
1997 /// frame here so [`super::KtstrVm::collect_results`] can merge
1998 /// them into `VmResult::guest_messages` alongside the post-exit
1999 /// `drain_bulk` and the post-mortem SHM CRASH-ring drain.
2000 /// Without this stash every EXIT / TEST / PAYLOAD_METRICS /
2001 /// PROFRAW frame consumed by the coord
2002 /// would vanish — only the leftover bytes that arrived on
2003 /// `port1_tx_buf` after the coord exited would reach the
2004 /// verdict, and a typical run would surface no metrics.
2005 pub(crate) bulk_messages: Arc<std::sync::Mutex<Vec<crate::vmm::wire::ShmEntry>>>,
2006 /// Scheduler-stats client constructed at the top of `run_vm`,
2007 /// or `None` when the run has no scheduler attached
2008 /// (`scheduler_binary` is `None` on the builder). Forwarded
2009 /// to [`VmResult::stats_client`] so test code can issue
2010 /// `request_raw` / typed `stats` / `stats_meta` calls through
2011 /// the run's lifetime. The drainer thread tears down when the
2012 /// last clone of the client drops; `None` here means no
2013 /// drainer was spawned at all, so the run pays no
2014 /// stats-bridge cost.
2015 pub(crate) stats_client: Option<super::SchedStatsClient>,
2016 /// Periodic captures actually fired by the freeze coordinator
2017 /// during the run (success + timeout-placeholder count).
2018 /// Forwarded to [`VmResult::periodic_fired`] from the run-loop's
2019 /// `next_periodic_idx` final value.
2020 pub(crate) periodic_fired: u32,
2021 /// Configured periodic-snapshot target (mirrors
2022 /// `KtstrVm::num_snapshots`). Forwarded to
2023 /// [`VmResult::periodic_target`] so test code can compute
2024 /// coverage as `fired / target`.
2025 pub(crate) periodic_target: u32,
2026 /// Host-side vCPU scheduling-dilation sample, read at `run_vm`
2027 /// teardown from each vCPU thread's `/proc/self/task/<tid>/schedstat`
2028 /// (see [`HostVcpuSchedstat`]). Forwarded verbatim to
2029 /// [`VmResult::host_vcpu_schedstat`]. `None` on hosts without
2030 /// `CONFIG_SCHEDSTATS` or when no vCPU thread was sampled.
2031 pub(crate) host_vcpu_schedstat: Option<HostVcpuSchedstat>,
2032}
2033#[cfg(test)]
2034mod tests {
2035 use super::*;
2036
2037 /// scheduler_log() concatenates the bulk-port SchedLog frames and
2038 /// slices the `SCHED_OUTPUT_START`/`END`-bracketed content (mirroring
2039 /// collect_verifier_output). A CRC-bad frame is dropped; with no valid
2040 /// SchedLog frames and an empty `output`, the log is empty. CI-runnable
2041 /// (no VM) — pins the accessor the demo_verifier post_vm assertions
2042 /// depend on, so a boot-path capture regression is caught even when the
2043 /// host-gated e2e cells skip under resource contention.
2044 #[test]
2045 fn scheduler_log_extracts_bracketed_content_and_drops_crc_bad() {
2046 use crate::vmm::host_comms::BulkDrainResult;
2047 use crate::vmm::wire::{MSG_TYPE_SCHED_LOG, ShmEntry};
2048
2049 let framed = "===SCHED_OUTPUT_START===\n\
2050 libbpf: prog 'ktstr_dispatch': BPF program load failed: -EACCES\n\
2051 -- BEGIN PROG LOAD LOG --\n0: (b7) r0 = 0\n-- END PROG LOAD LOG --\n\
2052 ===SCHED_OUTPUT_END===\n";
2053 let mut result = VmResult::test_fixture();
2054 result.guest_messages = Some(BulkDrainResult {
2055 entries: vec![ShmEntry {
2056 msg_type: MSG_TYPE_SCHED_LOG,
2057 payload: framed.as_bytes().to_vec(),
2058 crc_ok: true,
2059 }],
2060 });
2061 let log = result.scheduler_log();
2062 assert!(
2063 log.contains("-- BEGIN PROG LOAD LOG --"),
2064 "libbpf verifier-reject marker survives extraction: {log}"
2065 );
2066 assert!(
2067 log.contains("BPF program load failed"),
2068 "scheduler stderr content present: {log}"
2069 );
2070 assert!(
2071 !log.contains("SCHED_OUTPUT_START"),
2072 "wire brackets stripped by parse_sched_output: {log}"
2073 );
2074
2075 // A CRC-bad SchedLog frame is dropped; with no valid frames the
2076 // merged stream is empty and `output` (empty here) is the fallback,
2077 // so scheduler_log() is empty.
2078 let mut bad = VmResult::test_fixture();
2079 bad.guest_messages = Some(BulkDrainResult {
2080 entries: vec![ShmEntry {
2081 msg_type: MSG_TYPE_SCHED_LOG,
2082 payload: framed.as_bytes().to_vec(),
2083 crc_ok: false,
2084 }],
2085 });
2086 assert_eq!(bad.scheduler_log(), "", "crc-bad frame dropped -> empty");
2087 }
2088
2089 /// `HostVcpuSchedstat::dilation` = `1 + run_delay/on_cpu`, `None`
2090 /// when no on-CPU time was sampled (idle/no-vCPU or a
2091 /// CONFIG_SCHEDSTATS-off host reading `0 0 0`). Directional endpoints:
2092 /// zero run-delay -> exactly 1.0; run-delay == on-cpu -> 2.0; zero
2093 /// on-cpu -> None (distinguishable from a genuine 1.0).
2094 #[test]
2095 fn host_vcpu_schedstat_dilation_endpoints() {
2096 // R == 0 -> D == 1.0 (always got the CPU when runnable).
2097 let d = HostVcpuSchedstat {
2098 total_on_cpu_ns: 1_000,
2099 total_run_delay_ns: 0,
2100 sampled_vcpus: 1,
2101 }
2102 .dilation();
2103 assert_eq!(d, Some(1.0), "no run delay -> exactly 1.0");
2104 // R == C -> D == 2.0 (waited as long as it ran).
2105 let d = HostVcpuSchedstat {
2106 total_on_cpu_ns: 1_000,
2107 total_run_delay_ns: 1_000,
2108 sampled_vcpus: 2,
2109 }
2110 .dilation();
2111 assert_eq!(d, Some(2.0), "run delay == on-cpu -> 2.0");
2112 // C == 0 -> None (no on-cpu time: idle, no vCPU, or schedstats off).
2113 let d = HostVcpuSchedstat {
2114 total_on_cpu_ns: 0,
2115 total_run_delay_ns: 500,
2116 sampled_vcpus: 0,
2117 }
2118 .dilation();
2119 assert_eq!(d, None, "zero on-cpu -> None, not a synthetic 1.0");
2120 }
2121
2122 /// `step_throughput_in` reads the canonical CPU-denominated
2123 /// `iteration_rate`; it neither reconstructs nor exposes a wall rate.
2124 #[test]
2125 fn step_throughput_in_reads_canonical_iteration_rate() {
2126 use crate::assert::Phase;
2127 let buckets = vec![
2128 crate::assert::PhaseBucket {
2129 step_index: 1,
2130 metrics: [("iteration_rate".to_string(), 5_000.0)]
2131 .into_iter()
2132 .collect(),
2133 ..Default::default()
2134 },
2135 crate::assert::PhaseBucket {
2136 step_index: 2,
2137 metrics: [("iteration_rate".to_string(), 0.0)].into_iter().collect(),
2138 ..Default::default()
2139 },
2140 crate::assert::PhaseBucket {
2141 step_index: 3,
2142 ..Default::default()
2143 },
2144 ];
2145 assert_eq!(
2146 VmResult::step_throughput_in(&buckets, Phase::step(0)),
2147 Some(5000.0)
2148 );
2149 assert_eq!(
2150 VmResult::step_throughput_in(&buckets, Phase::step(1)),
2151 Some(0.0),
2152 );
2153 assert_eq!(VmResult::step_throughput_in(&buckets, Phase::step(2)), None);
2154 assert_eq!(
2155 VmResult::step_throughput_in(&buckets, Phase::BASELINE),
2156 None
2157 );
2158 assert_eq!(VmResult::step_throughput_in(&buckets, Phase::step(9)), None);
2159 }
2160
2161 #[test]
2162 fn kvm_stats_try_sum_distinguishes_absent_from_zero() {
2163 let totals = KvmStatsTotals {
2164 per_vcpu: vec![
2165 [("exits".to_string(), 0u64)].into_iter().collect(),
2166 [("exits".to_string(), 0u64)].into_iter().collect(),
2167 ],
2168 };
2169 // "exits" is published as 0 on every vCPU -> a measured zero.
2170 assert_eq!(totals.try_sum("exits"), Some(0));
2171 assert_eq!(totals.try_avg("exits"), Some(0));
2172 // "halt_exits" was never published -> absent, not zero.
2173 assert_eq!(totals.try_sum("halt_exits"), None);
2174 assert_eq!(totals.try_avg("halt_exits"), None);
2175 // sum/avg keep the 0-coercing behavior for both cases.
2176 assert_eq!(totals.sum("exits"), 0);
2177 assert_eq!(totals.sum("halt_exits"), 0);
2178 // No vCPUs at all -> try_avg None (no div-by-zero, no false 0).
2179 let empty = KvmStatsTotals { per_vcpu: vec![] };
2180 assert_eq!(empty.try_sum("exits"), None);
2181 assert_eq!(empty.try_avg("exits"), None);
2182 }
2183
2184 #[test]
2185 fn vm_result_fields_carry_values() {
2186 let r = VmResult {
2187 duration: Duration::from_secs(5),
2188 output: "hello world".into(),
2189 stderr: "boot log".into(),
2190 cleanup_duration: Some(Duration::from_millis(50)),
2191 ..VmResult::test_fixture()
2192 };
2193 assert!(r.success);
2194 assert_eq!(r.exit_code, 0);
2195 assert!(!r.timed_out);
2196 assert_eq!(r.duration, Duration::from_secs(5));
2197 assert_eq!(r.output, "hello world");
2198 assert_eq!(r.stderr, "boot log");
2199 assert!(r.monitor.is_none());
2200 assert!(r.guest_messages.is_none());
2201 assert!(r.stimulus_timeline().is_empty());
2202 assert_eq!(r.cleanup_duration, Some(Duration::from_millis(50)));
2203 assert!(r.virtio_blk_counters.is_none());
2204 // Second construction covers the opposite polarity of
2205 // every boolean/numeric field so no field is silently
2206 // dropped by a future refactor that only exercises the
2207 // success path.
2208 let r2 = VmResult {
2209 success: false,
2210 exit_code: 1,
2211 duration: Duration::from_millis(500),
2212 timed_out: true,
2213 virtio_blk_counters: Some(VirtioBlkCountersSnapshot::default()),
2214 periodic_fired: 3,
2215 periodic_real: 2,
2216 periodic_target: 7,
2217 ..VmResult::test_fixture()
2218 };
2219 assert!(!r2.success);
2220 assert_eq!(r2.exit_code, 1);
2221 assert!(r2.timed_out);
2222 assert_eq!(r2.duration, Duration::from_millis(500));
2223 assert!(r2.cleanup_duration.is_none());
2224 assert_eq!(r2.periodic_fired, 3);
2225 assert_eq!(r2.periodic_target, 7);
2226 // Opposite polarity: counters present. Reads must observe
2227 // the default-zero values for every field — a future field
2228 // added to VirtioBlkCountersSnapshot that doesn't initialise
2229 // to 0 would break the "fresh device reports zero activity"
2230 // contract that VmResult readers rely on. The snapshot was
2231 // taken from the device's atomic counters at collect_results
2232 // time, after every vCPU and worker thread joined; readers
2233 // see plain `u64` field reads with no atomic ordering needed.
2234 let counters = r2.virtio_blk_counters.as_ref().unwrap();
2235 assert_eq!(counters.reads_completed, 0);
2236 assert_eq!(counters.writes_completed, 0);
2237 assert_eq!(counters.flushes_completed, 0);
2238 assert_eq!(counters.bytes_read, 0);
2239 assert_eq!(counters.bytes_written, 0);
2240 assert_eq!(counters.throttled_count, 0);
2241 assert_eq!(counters.io_errors, 0);
2242 assert_eq!(counters.currently_throttled_gauge, 0);
2243 assert_eq!(counters.invalid_avail_idx_count, 0);
2244 }
2245
2246 #[test]
2247 fn vm_result_without_monitor_has_no_samples() {
2248 let r = VmResult {
2249 output: "test output".into(),
2250 ..VmResult::test_fixture()
2251 };
2252 assert!(r.monitor.is_none());
2253 // Output and exit_code must still be accessible.
2254 assert_eq!(r.output, "test output");
2255 assert_eq!(r.exit_code, 0);
2256 }
2257
2258 #[test]
2259 fn vm_result_with_monitor_carries_summary() {
2260 let summary = monitor::MonitorSummary {
2261 prog_stats_deltas: None,
2262 total_samples: 5,
2263 max_imbalance_ratio: 3.5,
2264 max_local_dsq_depth: 10,
2265 stuck_count: 1,
2266 event_deltas: None,
2267 schedstat_deltas: None,
2268 ..Default::default()
2269 };
2270 let report = monitor::MonitorReport {
2271 samples: vec![],
2272 summary: summary.clone(),
2273 ..Default::default()
2274 };
2275 let r = VmResult {
2276 success: false,
2277 exit_code: 1,
2278 duration: Duration::from_millis(500),
2279 timed_out: true,
2280 stderr: "kernel panic".into(),
2281 monitor: Some(report),
2282 ..VmResult::test_fixture()
2283 };
2284 let mon = r.monitor.as_ref().unwrap();
2285 assert_eq!(mon.summary.total_samples, 5);
2286 assert!((mon.summary.max_imbalance_ratio - 3.5).abs() < f64::EPSILON);
2287 assert_eq!(mon.summary.max_local_dsq_depth, 10);
2288 assert!(mon.summary.stuck_count > 0);
2289 assert!(r.timed_out);
2290 assert_eq!(r.exit_code, 1);
2291 assert_eq!(r.stderr, "kernel panic");
2292 }
2293
2294 /// Compile-time pin that `VmResult: Clone`. A future field
2295 /// added with a non-Clone type would break the derive at compile
2296 /// time and break this test's `let _: Self = self_clone(r)` call.
2297 /// Cheap insurance that nobody silently strips the Clone derive
2298 /// or adds a non-Clone field.
2299 #[test]
2300 fn vm_result_is_clone() {
2301 fn self_clone<T: Clone>(t: &T) -> T {
2302 t.clone()
2303 }
2304 let r = VmResult::test_fixture();
2305 let _: VmResult = self_clone(&r);
2306 }
2307
2308 /// Pin the documented aliasing semantic on the Arc-shared
2309 /// `snapshot_bridge` field: clones of `VmResult` share the
2310 /// underlying snapshot store. A future refactor that turned
2311 /// `SnapshotBridge` into a deep-copy struct would break this
2312 /// test — at which point the doc paragraph at the head of
2313 /// `VmResult` must be updated to drop the Arc-shared-handle
2314 /// category. Loud failure on contract drift, not a silent
2315 /// behavior change.
2316 #[test]
2317 fn vm_result_clone_snapshot_bridge_aliases_via_arc() {
2318 let r = VmResult::test_fixture();
2319 let c = r.clone();
2320 // Pre-condition: both bridges start empty.
2321 assert_eq!(r.snapshot_bridge.len(), 0);
2322 assert_eq!(c.snapshot_bridge.len(), 0);
2323 // Store a synthetic report through ONE clone's bridge.
2324 r.snapshot_bridge.store(
2325 "regression_pin",
2326 crate::monitor::dump::FailureDumpReport::default(),
2327 );
2328 // The OTHER clone observes the store — proves the Arc<Mutex<…>>
2329 // is shared, not deep-copied. If this assertion ever fires,
2330 // SnapshotBridge's Clone has changed shape and VmResult's
2331 // doc paragraph must be revisited.
2332 assert_eq!(
2333 r.snapshot_bridge.len(),
2334 c.snapshot_bridge.len(),
2335 "snapshot_bridge clones must observe the same store \
2336 per the VmResult Clone contract (Arc-shared handle)"
2337 );
2338 assert_eq!(c.snapshot_bridge.len(), 1);
2339 }
2340
2341 /// Build a `VmResult` whose snapshot bridge holds `n` periodic
2342 /// captures stamped into Step[0] (`step_index = 1`). No stimulus
2343 /// frames are attached, so `stimulus_timeline()` is empty and the
2344 /// bucketer falls back to each capture's stamped `step_index`.
2345 fn vm_result_with_periodic_captures(n: usize) -> VmResult {
2346 let r = VmResult {
2347 periodic_fired: n as u32,
2348 periodic_target: n as u32,
2349 ..VmResult::test_fixture()
2350 };
2351 for i in 0..n {
2352 r.snapshot_bridge.store_with_stats_and_step(
2353 &format!("periodic_{i}"),
2354 crate::monitor::dump::FailureDumpReport::default(),
2355 None,
2356 Some(i as u64 * 100),
2357 None,
2358 1,
2359 );
2360 }
2361 r
2362 }
2363
2364 /// Regression for the drain-once starvation bug: the snapshot
2365 /// bridge is drained EXACTLY once and the resulting series is
2366 /// shared, so a `post_vm`-style consumer reading the series does
2367 /// not starve a later framework-style consumer. Before
2368 /// [`VmResult::captures_series`], `periodic_series()` drained the
2369 /// bridge directly and a second reader saw an empty bridge — the
2370 /// silent-data-drop this task de-conflicts.
2371 #[test]
2372 fn captures_series_shared_across_consumers() {
2373 let r = vm_result_with_periodic_captures(3);
2374 // First consumer = post_vm style (drains the bridge into the cache).
2375 let post_vm_series = r.periodic_series();
2376 assert_eq!(
2377 post_vm_series.len(),
2378 3,
2379 "post_vm consumer must see all captures"
2380 );
2381 // Second consumer = framework style (reads the cache, no re-drain).
2382 let framework_series = r.captures_series();
2383 assert_eq!(
2384 framework_series.len(),
2385 3,
2386 "framework consumer must NOT see an empty bridge — the single \
2387 cached drain is shared, not re-drained (pre-cache this was 0)"
2388 );
2389 // The raw bridge was consumed exactly once: a direct drain now
2390 // yields nothing because captures_series() took ownership of the
2391 // captures into the cache on first read.
2392 assert_eq!(
2393 r.snapshot_bridge.drain_ordered_with_stats().len(),
2394 0,
2395 "captures_series() performs the single destructive drain"
2396 );
2397 }
2398
2399 /// `phase_buckets()` folds the cached captures into per-phase
2400 /// buckets without the caller draining the bridge — the
2401 /// phase-buckets accessor. Idempotent: a second call returns the same vec from
2402 /// the shared cache.
2403 #[test]
2404 fn phase_buckets_from_cached_captures() {
2405 let r = vm_result_with_periodic_captures(2);
2406 let buckets = r.phase_buckets();
2407 assert!(
2408 !buckets.is_empty(),
2409 "phase_buckets must yield buckets from the cached captures"
2410 );
2411 assert!(
2412 buckets.iter().any(|b| b.step_index >= 1),
2413 "captures stamped step_index=1 must produce a Step bucket, got {:?}",
2414 buckets.iter().map(|b| b.step_index).collect::<Vec<_>>(),
2415 );
2416 assert_eq!(
2417 r.phase_buckets(),
2418 buckets,
2419 "phase_buckets() must be idempotent (shared cache)"
2420 );
2421 }
2422
2423 /// Clone semantics, category 3 (the `periodic_series_cache` field):
2424 /// a clone taken AFTER the cache is populated carries an
2425 /// INDEPENDENT copy, so `phase_buckets()` on both the original and
2426 /// the clone returns identical non-empty buckets without
2427 /// re-touching the (already-drained) shared bridge. Pins the
2428 /// documented safe path.
2429 #[test]
2430 fn vm_result_clone_after_cache_populated_carries_buckets() {
2431 let r = vm_result_with_periodic_captures(2);
2432 // Populate the cache BEFORE cloning (the documented safe path).
2433 let original = r.phase_buckets();
2434 assert!(!original.is_empty());
2435 let c = r.clone();
2436 let cloned = c.phase_buckets();
2437 assert!(!cloned.is_empty());
2438 assert_eq!(
2439 cloned, original,
2440 "a clone taken after cache population must carry the same \
2441 buckets (category-3 independent-once-populated semantics)"
2442 );
2443 }
2444
2445 /// `phase_metric` keys by `Phase` (1-indexed wire `step_index`) and
2446 /// delegates to the matching bucket's `get()`: it returns each
2447 /// present metric's value, `None` for an unknown metric on an
2448 /// existing phase, and `None` for a phase with no bucket. (The
2449 /// Some-value read itself is `PhaseBucket::get`, pinned by its own
2450 /// tests; this pins the phase-keying and the None contract.)
2451 #[test]
2452 fn phase_metric_keys_by_phase_and_delegates_to_bucket_get() {
2453 let r = vm_result_with_periodic_captures(2);
2454 // The captures are stamped step_index=1 -> Phase::step(0).
2455 let p0 = crate::assert::Phase::step(0);
2456 let buckets = r.phase_buckets();
2457 let step0 = buckets
2458 .iter()
2459 .find(|b| b.step_index == p0.as_u16())
2460 .expect("a Step[0] bucket from the stamped captures (keys by step_index)");
2461 // Some-path delegation: for every metric the matching bucket
2462 // carries, phase_metric returns that exact value. The
2463 // default-report fixture may fold no metrics, so this loop can be
2464 // empty — the keying + None assertions below pin the rest.
2465 for (name, val) in &step0.metrics {
2466 assert_eq!(
2467 r.phase_metric(p0, name),
2468 Some(*val),
2469 "phase_metric must return the matching bucket's value for present metric '{name}'",
2470 );
2471 }
2472 // A name absent from the bucket -> None (the bucket is still found).
2473 assert_eq!(
2474 r.phase_metric(p0, "definitely_not_a_registry_metric"),
2475 None,
2476 "an unknown metric name yields None even when the phase has a bucket",
2477 );
2478 // A phase with no bucket -> None (not a panic, not a wrong bucket).
2479 assert_eq!(
2480 r.phase_metric(crate::assert::Phase::step(99), "iteration_rate"),
2481 None,
2482 "a phase with no bucket yields None",
2483 );
2484 }
2485
2486 /// Build a guest `AssertResult` carrying ONE per-phase per-cgroup
2487 /// carrier at `step_index` (the merge-neutral `(u64::MAX, 0)` window
2488 /// `fold_guest_per_cgroup_into_host_buckets` requires) and wrap it in
2489 /// the `MSG_TYPE_TEST_RESULT` TLV a real run leaves on
2490 /// `guest_messages`, so `VmResult::guest_assert_result` decodes it.
2491 fn guest_drain_with_per_cgroup(
2492 step_index: u16,
2493 carriers: &[(&str, u64, u64)],
2494 ) -> crate::vmm::host_comms::BulkDrainResult {
2495 let mut per_cgroup = std::collections::BTreeMap::new();
2496 for &(name, migrations, iters) in carriers {
2497 per_cgroup.insert(
2498 name.to_string(),
2499 crate::assert::PhaseCgroupStats {
2500 total_migrations: migrations,
2501 total_iterations: iters,
2502 ..Default::default()
2503 },
2504 );
2505 }
2506 let mut guest = crate::test_support::test_helpers::build_assert_result(true, vec![]);
2507 guest.stats.phases = vec![crate::assert::PhaseBucket {
2508 step_index,
2509 label: crate::assert::Phase::from(step_index).to_string(),
2510 // Merge-neutral window: fold_guest_per_cgroup_into_host_buckets
2511 // debug_asserts guest carriers carry exactly (u64::MAX, 0).
2512 start_ms: u64::MAX,
2513 end_ms: 0,
2514 sample_count: 0,
2515 metrics: std::collections::BTreeMap::new(),
2516 per_cgroup,
2517 }];
2518 crate::vmm::host_comms::BulkDrainResult {
2519 entries: vec![crate::test_support::test_helpers::assert_result_tlv_entry(
2520 &guest,
2521 )],
2522 }
2523 }
2524
2525 /// `phase_buckets()` folds the guest per-cgroup carriers (parsed from
2526 /// `guest_messages`) into the host buckets keyed by `step_index`, so the
2527 /// returned buckets carry `per_cgroup`; `phase_cgroup` reads one cgroup
2528 /// out of the folded bucket. Pins the guest-carrier fold: the host
2529 /// captures stamp step_index=1 == `Phase::step(0)`, the carrier matches
2530 /// it, and the matched arm unions the carrier's `per_cgroup` into that
2531 /// bucket.
2532 #[test]
2533 fn phase_buckets_folds_guest_per_cgroup_carriers() {
2534 let r = VmResult {
2535 guest_messages: Some(guest_drain_with_per_cgroup(1, &[("cellA", 7, 11)])),
2536 ..vm_result_with_periodic_captures(2)
2537 };
2538 let buckets = r.phase_buckets();
2539 let step0 = buckets
2540 .iter()
2541 .find(|b| b.step_index == crate::assert::Phase::step(0).as_u16())
2542 .expect("host bucket at step_index=1 from the stamped captures");
2543 let cg = step0
2544 .per_cgroup
2545 .get("cellA")
2546 .expect("matched-arm fold must carry the guest carrier's per_cgroup");
2547 assert_eq!(cg.total_migrations, 7);
2548 assert_eq!(cg.total_iterations, 11);
2549 // phase_cgroup is the per-(phase, cgroup) accessor over the same fold.
2550 let via_accessor = r
2551 .phase_cgroup(crate::assert::Phase::step(0), "cellA")
2552 .expect("phase_cgroup must reach the folded carrier");
2553 assert_eq!(via_accessor.total_migrations, 7);
2554 // A cgroup the phase never had -> None (not measured).
2555 assert!(
2556 r.phase_cgroup(crate::assert::Phase::step(0), "nope")
2557 .is_none()
2558 );
2559 }
2560
2561 /// `phase_metric("total_migrations")` resolves the per-phase
2562 /// cross-cgroup SUM via the `cgroup_counter_total` fallback — the key
2563 /// lives ONLY in `per_cgroup` (its `read_sample` is `None`, so
2564 /// `build_phase_buckets` never folds it into `bucket.metrics`, so
2565 /// `get()` misses). Two cgroups in the phase sum: 7 + 3 = 10. Without
2566 /// the `cgroup_counter_total` fallback, `phase_metric` returns a silent
2567 /// `None` for these keys.
2568 #[test]
2569 fn phase_metric_resolves_total_migrations_from_per_cgroup() {
2570 let r = VmResult {
2571 guest_messages: Some(guest_drain_with_per_cgroup(
2572 1,
2573 &[("cellA", 7, 5), ("cellB", 3, 6)],
2574 )),
2575 ..vm_result_with_periodic_captures(2)
2576 };
2577 assert_eq!(
2578 r.phase_metric(crate::assert::Phase::step(0), "total_migrations"),
2579 Some(10.0),
2580 "cross-cgroup sum across per_cgroup carriers (7 + 3)",
2581 );
2582 // The total_iterations arm of cgroup_counter_total resolves too (5 + 6).
2583 assert_eq!(
2584 r.phase_metric(crate::assert::Phase::step(0), "total_iterations"),
2585 Some(11.0),
2586 "cross-cgroup sum of the total_iterations per_cgroup counter (5 + 6)",
2587 );
2588 // A carrier-bearing phase that counted zero is a measured Some(0.0),
2589 // distinct from a phase with no carrier (None).
2590 let r0 = VmResult {
2591 guest_messages: Some(guest_drain_with_per_cgroup(1, &[("cellA", 0, 0)])),
2592 ..vm_result_with_periodic_captures(2)
2593 };
2594 assert_eq!(
2595 r0.phase_metric(crate::assert::Phase::step(0), "total_migrations"),
2596 Some(0.0),
2597 "carriers present but counted zero is a measured Some(0.0)",
2598 );
2599 // No carriers at all (guest_messages with no per_cgroup) -> None.
2600 let r_none = vm_result_with_periodic_captures(2);
2601 assert_eq!(
2602 r_none.phase_metric(crate::assert::Phase::step(0), "total_migrations"),
2603 None,
2604 "no per_cgroup carrier in the phase -> None (not measured)",
2605 );
2606 }
2607
2608 /// A guest carrier whose `step_index` has NO matching host bucket takes
2609 /// the fold's ORPHAN arm: it is appended with its merge-neutral
2610 /// `(u64::MAX, 0)` window normalized to `(0, 0)`, and stays reachable
2611 /// through the public accessors. The host captures stamp step_index=1
2612 /// only, so a step_index=2 carrier is an orphan. Pins that
2613 /// `phase_cgroup` reaches the orphan and the window does not underflow
2614 /// duration consumers (`end_ms - start_ms == 0`, not `0 - u64::MAX`).
2615 #[test]
2616 fn phase_buckets_orphan_carrier_reachable_via_phase_cgroup() {
2617 let r = VmResult {
2618 // step_index 2 == Phase::step(1); no host capture stamps step 2.
2619 guest_messages: Some(guest_drain_with_per_cgroup(2, &[("orphanCell", 4, 0)])),
2620 ..vm_result_with_periodic_captures(2)
2621 };
2622 let buckets = r.phase_buckets();
2623 let orphan = buckets
2624 .iter()
2625 .find(|b| b.step_index == crate::assert::Phase::step(1).as_u16())
2626 .expect("orphan carrier must be appended as its own bucket");
2627 assert_eq!(
2628 (orphan.start_ms, orphan.end_ms),
2629 (0, 0),
2630 "orphan arm normalizes the (u64::MAX, 0) sentinel window to (0, 0)",
2631 );
2632 assert_eq!(
2633 r.phase_cgroup(crate::assert::Phase::step(1), "orphanCell")
2634 .map(|c| c.total_migrations),
2635 Some(4),
2636 "phase_cgroup must reach an orphan carrier",
2637 );
2638 }
2639
2640 /// With no guest verdict (guest_messages None — host-only run / early
2641 /// crash), `guest_assert_result()` is Err and `phase_buckets()` returns
2642 /// the host-rebuilt buckets ALONE: non-empty (captures landed) with every
2643 /// `per_cgroup` empty. Pins the Err arm (the prior behavior) carries the
2644 /// host buckets, no panic.
2645 #[test]
2646 fn phase_buckets_without_guest_verdict_is_host_only() {
2647 let r = vm_result_with_periodic_captures(2);
2648 assert!(
2649 r.guest_assert_result().is_err(),
2650 "test_fixture has no guest verdict"
2651 );
2652 let buckets = r.phase_buckets();
2653 assert!(
2654 !buckets.is_empty(),
2655 "host captures must still yield buckets"
2656 );
2657 assert!(
2658 buckets.iter().all(|b| b.per_cgroup.is_empty()),
2659 "no guest carriers -> every per_cgroup stays empty",
2660 );
2661 }
2662
2663 /// A guest per-cgroup carrier carrying NON-EMPTY sample vectors
2664 /// (run_delays_ns / off_cpu_pcts / wake_latencies_ns) survives the
2665 /// guest->host postcard round-trip (assert_result_tlv_entry encode ->
2666 /// guest_assert_result decode) and the fold verbatim, and the
2667 /// PhaseCgroupStats summary methods reduce them post-decode. The
2668 /// guest_drain_with_per_cgroup helper carries only counters (empty
2669 /// vecs), so this pins the sample-vec wire fidelity that helper does not.
2670 #[test]
2671 fn guest_carrier_sample_vecs_survive_postcard_and_fold() {
2672 let mut pc = std::collections::BTreeMap::new();
2673 pc.insert(
2674 "cellA".to_string(),
2675 crate::assert::PhaseCgroupStats {
2676 total_migrations: 2,
2677 run_delays_ns: vec![10, 20, 30],
2678 off_cpu_pcts: vec![1.5, 2.5],
2679 wake_latencies_ns: vec![100, 200],
2680 wake_sample_total: 2,
2681 ..Default::default()
2682 },
2683 );
2684 let mut guest = crate::test_support::test_helpers::build_assert_result(true, vec![]);
2685 guest.stats.phases = vec![crate::assert::PhaseBucket {
2686 step_index: 1,
2687 label: "Step[0]".to_string(),
2688 start_ms: u64::MAX,
2689 end_ms: 0,
2690 sample_count: 0,
2691 metrics: std::collections::BTreeMap::new(),
2692 per_cgroup: pc,
2693 }];
2694 let r = VmResult {
2695 guest_messages: Some(crate::vmm::host_comms::BulkDrainResult {
2696 entries: vec![crate::test_support::test_helpers::assert_result_tlv_entry(
2697 &guest,
2698 )],
2699 }),
2700 ..vm_result_with_periodic_captures(2)
2701 };
2702 let cg = r
2703 .phase_cgroup(crate::assert::Phase::step(0), "cellA")
2704 .expect("carrier survives postcard + fold");
2705 // Sample vectors round-trip byte-for-byte through the wire.
2706 assert_eq!(cg.run_delays_ns, vec![10, 20, 30]);
2707 assert_eq!(cg.off_cpu_pcts, vec![1.5, 2.5]);
2708 assert_eq!(cg.wake_latencies_ns, vec![100, 200]);
2709 // And the summary methods reduce the decoded samples (worst = max(ns)/1000).
2710 let (_, worst_us) = cg
2711 .run_delay_summary()
2712 .expect("non-empty run_delays -> Some");
2713 assert_eq!(worst_us, 30.0 / 1000.0);
2714 }
2715
2716 #[cfg(feature = "wprof")]
2717 #[test]
2718 fn vm_result_wprof_pb_path_bails_when_entry_name_none() {
2719 let r = VmResult::test_fixture();
2720 assert!(r.entry_name.is_none());
2721 let err = r.wprof_pb_path().expect_err("None entry_name must Err");
2722 let msg = format!("{err:#}");
2723 assert!(
2724 msg.contains("entry_name"),
2725 "diagnostic must name the missing field: {msg}",
2726 );
2727 assert!(
2728 msg.contains("run_ktstr_test_inner_impl"),
2729 "diagnostic must name the stamping site so the operator \
2730 can trace the missing-stamp path: {msg}",
2731 );
2732 }
2733
2734 #[cfg(feature = "wprof")]
2735 #[test]
2736 fn vm_result_wprof_pb_path_returns_writer_mirror_path() {
2737 let r = VmResult {
2738 entry_name: Some("vm_result_wprof_pb_path_returns_writer_mirror_path_fixture"),
2739 variant_hash: 0xab,
2740 ..VmResult::test_fixture()
2741 };
2742 let path = r.wprof_pb_path().expect("Some entry_name must Ok");
2743 // The path's file_name must exactly match
2744 // `<entry_name>-<variant_hash:016x>.wprof.pb` — the writer uses
2745 // the same variant-keyed pattern (the wprof writer reads this
2746 // very method). A divergence would mean the method derives a
2747 // different path than the writer wrote to, surfacing as ENOENT in
2748 // the post_vm callback.
2749 let file_name = path.file_name().and_then(|n| n.to_str()).unwrap();
2750 assert_eq!(
2751 file_name,
2752 "vm_result_wprof_pb_path_returns_writer_mirror_path_fixture-00000000000000ab.wprof.pb",
2753 );
2754 }
2755
2756 #[cfg(feature = "wprof")]
2757 #[test]
2758 fn vm_result_repro_wprof_pb_path_bails_when_entry_name_none() {
2759 let r = VmResult::test_fixture();
2760 let err = r
2761 .repro_wprof_pb_path()
2762 .expect_err("None entry_name must Err");
2763 let msg = format!("{err:#}");
2764 assert!(msg.contains("entry_name"));
2765 assert!(msg.contains("run_ktstr_test_inner_impl"));
2766 }
2767
2768 #[cfg(feature = "wprof")]
2769 #[test]
2770 fn vm_result_repro_wprof_pb_path_returns_writer_mirror_path() {
2771 let r = VmResult {
2772 entry_name: Some("vm_result_repro_wprof_pb_path_fixture"),
2773 variant_hash: 0xab,
2774 ..VmResult::test_fixture()
2775 };
2776 let path = r.repro_wprof_pb_path().expect("Some entry_name must Ok");
2777 let file_name = path.file_name().and_then(|n| n.to_str()).unwrap();
2778 assert_eq!(
2779 file_name,
2780 "vm_result_repro_wprof_pb_path_fixture-00000000000000ab.repro.wprof.pb"
2781 );
2782 }
2783
2784 #[cfg(feature = "wprof")]
2785 #[test]
2786 fn vm_result_assert_wprof_pb_landed_skips_when_success_false() {
2787 let r = VmResult {
2788 success: false,
2789 ..VmResult::test_fixture()
2790 };
2791 assert!(r.entry_name.is_none());
2792 let result = r.assert_wprof_pb_landed();
2793 assert!(
2794 result.is_ok(),
2795 "assert_wprof_pb_landed must Ok-skip on !success EVEN when \
2796 entry_name is None — the entry_name pre-check is downstream of \
2797 the success short-circuit. Got: {result:?}",
2798 );
2799 }
2800}