ktstr/scenario/sample/bpf.rs
1//! BPF-axis projection for [`SampleSeries`].
2//!
3//! Each [`Sample`](super::Sample) carries a frozen [`Snapshot`] over
4//! BPF program state captured at the freeze rendezvous. This module
5//! exposes the closure-based [`SampleSeries::bpf`] projection (manual
6//! field access via the Snapshot accessor surface) and the auto-
7//! discovering [`SampleSeries::bpf_map`] → [`BpfMapProjector`] pair
8//! that enumerates a map's struct members and projects each as
9//! `SeriesField<u64>` / `SeriesField<i64>` / `SeriesField<f64>`.
10//!
11//! Orthogonal to [`super::stats`]: the BPF axis sources its values
12//! from the kernel-side BPF state (counters, ringbuf items, struct
13//! members); the stats axis sources from the userspace scheduler's
14//! `scx_stats` JSON. Tests typically use both — BPF for low-level
15//! state, stats for scheduler-author-defined metrics.
16
17use crate::assert::temporal::SeriesField;
18use crate::scenario::snapshot::{Snapshot, SnapshotField, SnapshotResult};
19
20use super::{SampleSeries, build_series_field};
21
22impl SampleSeries {
23 /// Project the series along the BPF axis. The closure receives
24 /// each sample's [`Snapshot`] and returns a
25 /// [`SnapshotResult<T>`] — typically a typed value extracted
26 /// via `snap.var(...).as_u64()` or
27 /// `snap.map(...).at(...).get(...).as_u64()`. Errors flow
28 /// through into the resulting [`SeriesField`] as per-sample
29 /// `Err` slots so a temporal-assertion pattern can decide
30 /// whether to fail or skip on a missing field.
31 ///
32 /// `label` is owned (`impl Into<String>`) and lands in
33 /// [`crate::assert::temporal::SeriesField::label`] for failure-
34 /// message rendering. Callers may pass a `&'static str` literal
35 /// or a runtime-built `String` (for auto-discovered struct or
36 /// JSON key names).
37 pub fn bpf<T, F>(&self, label: impl Into<String>, project: F) -> SeriesField<T>
38 where
39 F: Fn(&Snapshot<'_>) -> SnapshotResult<T>,
40 {
41 build_series_field(&self.rows, label, |row| {
42 // Placeholder reports carry no real BPF state — the
43 // freeze rendezvous timed out (or the capture pipeline
44 // otherwise failed). Surface a dedicated PlaceholderSample
45 // error variant BEFORE invoking the projection closure
46 // so the temporal-assertion patterns can branch on
47 // "placeholder, skip" distinctly from "field missing,
48 // skip" when rendering the verdict's skip-Note.
49 if row.report.is_placeholder {
50 return Err(
51 crate::scenario::snapshot::SnapshotError::PlaceholderSample {
52 tag: row.tag.clone(),
53 reason: row
54 .report
55 .scx_walker_unavailable
56 .clone()
57 .unwrap_or_else(|| "placeholder report".to_string()),
58 },
59 );
60 }
61 let snap = Snapshot::new(&row.report);
62 project(&snap)
63 })
64 }
65
66 /// Project the live scheduler's `<obj>.<section>` global
67 /// variable named `name` as `u64`. Per-row equivalent of
68 /// `snap.live_var(name).as_u64()`, but with the placeholder
69 /// short-circuit baked in.
70 ///
71 /// **Why this exists.** Single-binary tests can use
72 /// `series.bpf("label", |s| s.var(name).as_u64())` directly —
73 /// `var()` auto-disambiguates via the active-scheduler walker
74 /// when multiple maps share a global symbol (e.g. post-
75 /// `Op::ReplaceScheduler` with two scheduler instances). The
76 /// `bpf_live_u64` helper saves the closure boilerplate AND
77 /// makes the live-resolution semantics visible in the call
78 /// site's NAME, not buried in a projector body. The label on
79 /// the resulting [`SeriesField`] is the `name` argument
80 /// verbatim.
81 pub fn bpf_live_u64(&self, name: &str) -> SeriesField<u64> {
82 self.bpf_live_phase_stable(name, |f| f.as_u64())
83 }
84
85 /// Sibling of [`Self::bpf_live_u64`] projecting as `i64`.
86 pub fn bpf_live_i64(&self, name: &str) -> SeriesField<i64> {
87 self.bpf_live_phase_stable(name, |f| f.as_i64())
88 }
89
90 /// Sibling of [`Self::bpf_live_u64`] projecting as `f64`.
91 pub fn bpf_live_f64(&self, name: &str) -> SeriesField<f64> {
92 self.bpf_live_phase_stable(name, |f| f.as_f64())
93 }
94
95 /// Shared phase-stable projector for the `bpf_live_*` trio.
96 ///
97 /// Per-snapshot the underlying [`Snapshot::live_var`] correctly
98 /// disambiguates between bss copies via the walker-populated
99 /// [`crate::monitor::dump::FailureDumpReport::active_map_kvas`].
100 /// But across snapshots in the same phase, the walker can
101 /// re-publish (typical cause: post-`Op::ReplaceScheduler` swap
102 /// window) and successive snapshots can correctly pick
103 /// DIFFERENT bss copies — producing a non-monotonic counter
104 /// series that downstream reducers like
105 /// [`crate::assert::temporal::SeriesField::counter_delta_per_phase`]
106 /// can't reason about.
107 ///
108 /// This projector adds a phase-stability gate on top of the
109 /// per-snapshot pick. Two checks fire per phase:
110 ///
111 /// 1. **KVA drift within a walker-resolved set.** For each
112 /// phase, pin to the FIRST sample whose
113 /// `active_map_kvas` is non-empty. Later same-phase
114 /// samples whose `active_map_kvas` matches the pin pass
115 /// through. Later same-phase samples whose `active_map_kvas`
116 /// differs surface as
117 /// [`crate::scenario::snapshot::SnapshotError::WalkerDriftedWithinPhase`]
118 /// (the walker re-published mid-phase, typically because
119 /// an `Op::ReplaceScheduler` swap fired between snapshots).
120 /// 2. **Cross-scheduler leak via walker-absent samples.** If
121 /// a phase contains at least one walker-resolved sample
122 /// (non-empty `active_map_kvas`), every OTHER same-phase
123 /// sample MUST also be walker-resolved. An empty-kvas
124 /// sample in such a phase came from a pre-walker capture
125 /// window OR a different scheduler instance entirely —
126 /// its `Snapshot::live_var` read cannot be proven to come
127 /// from the same bss as the pinned samples, so the value
128 /// is non-comparable. Surface as
129 /// `WalkerDriftedWithinPhase` with `sample_kvas = []`
130 /// (the empty vec signals "this sample had no walker
131 /// output" as distinct from "the walker output disagreed").
132 /// The temporal patterns' standard error-skip semantics
133 /// drop these samples from per-phase reducers like
134 /// `counter_delta_per_phase`.
135 ///
136 /// Samples in a phase with NO walker-resolved siblings pass
137 /// through unchanged — the single-scheduler / pre-walker
138 /// case where the consumer's per-snapshot
139 /// [`Snapshot::active`] resolution is the only signal
140 /// available.
141 fn bpf_live_phase_stable<T, P>(&self, name: &str, project: P) -> SeriesField<T>
142 where
143 P: Fn(&SnapshotField<'_>) -> SnapshotResult<T>,
144 {
145 let label = name.to_string();
146 let name_owned = name.to_string();
147 // Pre-scan: identify phases that ever have a walker-resolved
148 // sample (non-empty active_map_kvas). Walker-absent samples
149 // in those phases are flagged as cross-scheduler-leak risks
150 // by the main loop below.
151 let mut phases_with_walker: std::collections::BTreeSet<crate::assert::Phase> =
152 std::collections::BTreeSet::new();
153 for row in &self.rows {
154 if row.report.is_placeholder {
155 continue;
156 }
157 if !row.report.active_map_kvas.is_empty()
158 && let Some(ph) = row.step_index.map(crate::assert::Phase::from)
159 {
160 phases_with_walker.insert(ph);
161 }
162 }
163 let mut values: Vec<SnapshotResult<T>> = Vec::with_capacity(self.rows.len());
164 let mut tags: Vec<String> = Vec::with_capacity(self.rows.len());
165 let mut elapsed: Vec<Option<u64>> = Vec::with_capacity(self.rows.len());
166 let mut phases: Vec<Option<crate::assert::Phase>> = Vec::with_capacity(self.rows.len());
167 let mut phase_kva_pin: std::collections::BTreeMap<crate::assert::Phase, Vec<u64>> =
168 std::collections::BTreeMap::new();
169 for row in &self.rows {
170 tags.push(row.tag.clone());
171 elapsed.push(row.elapsed_ms);
172 let phase = row.step_index.map(crate::assert::Phase::from);
173 phases.push(phase);
174
175 if row.report.is_placeholder {
176 values.push(Err(
177 crate::scenario::snapshot::SnapshotError::PlaceholderSample {
178 tag: row.tag.clone(),
179 reason: row
180 .report
181 .scx_walker_unavailable
182 .clone()
183 .unwrap_or_else(|| "placeholder report".to_string()),
184 },
185 ));
186 continue;
187 }
188 let snap = Snapshot::new(&row.report);
189 let field = snap.live_var(&name_owned);
190 let value = project(&field);
191 let sample_kvas: &[u64] = row.report.active_map_kvas.as_slice();
192
193 match (value, phase) {
194 (Ok(v), Some(ph)) if !sample_kvas.is_empty() => {
195 let pin = phase_kva_pin
196 .entry(ph)
197 .or_insert_with(|| sample_kvas.to_vec());
198 if pin.as_slice() == sample_kvas {
199 values.push(Ok(v));
200 } else {
201 values.push(Err(
202 crate::scenario::snapshot::SnapshotError::WalkerDriftedWithinPhase {
203 phase: ph,
204 pinned_kvas: pin.clone(),
205 sample_kvas: sample_kvas.to_vec(),
206 requested: name_owned.clone(),
207 },
208 ));
209 }
210 }
211 (Ok(_v), Some(ph))
212 if sample_kvas.is_empty() && phases_with_walker.contains(&ph) =>
213 {
214 // Cross-scheduler leak guard: this sample had
215 // no walker output but a sibling sample in the
216 // same phase did. The Ok value cannot be proven
217 // to come from the same scheduler as the pinned
218 // siblings — surface as drift with empty
219 // sample_kvas to disambiguate from "walker
220 // output disagreed".
221 let pinned = phase_kva_pin.get(&ph).cloned().unwrap_or_default();
222 values.push(Err(
223 crate::scenario::snapshot::SnapshotError::WalkerDriftedWithinPhase {
224 phase: ph,
225 pinned_kvas: pinned,
226 sample_kvas: Vec::new(),
227 requested: name_owned.clone(),
228 },
229 ));
230 }
231 (other, _) => values.push(other),
232 }
233 }
234 SeriesField::from_parts_with_phases_opt(label, tags, elapsed, values, phases)
235 }
236
237 /// Per-snapshot co-picked BPF projection of N counters from the
238 /// SAME global-section map. Lifts [`Snapshot::live_vars_via`] to
239 /// the series level: for each sample, calls the picker ONCE per
240 /// snapshot and projects the resulting `N` `SnapshotField`s as
241 /// `u64` into `N` parallel [`SeriesField`]s.
242 ///
243 /// **Why this exists.** The single-name `Self::bpf` closure shape
244 /// forces tests that need two co-picked counters (e.g.
245 /// `nr_cross_dispatch` + `nr_same_dispatch` from the same
246 /// scheduler bss copy after `Op::ReplaceScheduler`) to call the
247 /// picker TWICE per snapshot — once for each derived
248 /// `SeriesField` — paying picker cost `2N` instead of `N`. The
249 /// per-snapshot dedup happens here: one `live_vars_via` call per
250 /// row, eagerly split into `N` u64 vectors before any
251 /// `SeriesField` materializes.
252 ///
253 /// **Lifetime / coverage gaps surface per field.** If a snapshot
254 /// is a placeholder, every field's slot for that row carries the
255 /// same [`crate::scenario::snapshot::SnapshotError::PlaceholderSample`].
256 /// If `live_vars_via` fails (no candidate map has all `N` names,
257 /// or the picker returns `None`), every field's slot carries the
258 /// same underlying [`crate::scenario::snapshot::SnapshotError`] —
259 /// the failure is shared, not split. Per-field `.as_u64()` casts
260 /// that fail (the picked field doesn't render as a u64) surface
261 /// as per-field
262 /// [`crate::scenario::snapshot::SnapshotError::TypeMismatch`]
263 /// without contaminating sibling fields.
264 ///
265 /// The label routed onto each resulting [`SeriesField`] is the
266 /// caller-supplied name from `names` at the matching position.
267 pub fn live_bpf_vars_via<const N: usize, P>(
268 &self,
269 names: [&str; N],
270 picker: P,
271 ) -> [SeriesField<u64>; N]
272 where
273 P: for<'a> Fn(&[(&'a str, Vec<SnapshotField<'a>>)]) -> Option<usize> + Copy,
274 {
275 let mut per_field: [Vec<crate::scenario::snapshot::SnapshotResult<u64>>; N] =
276 std::array::from_fn(|_| Vec::with_capacity(self.rows.len()));
277 let mut tags: Vec<String> = Vec::with_capacity(self.rows.len());
278 let mut elapsed: Vec<Option<u64>> = Vec::with_capacity(self.rows.len());
279 let mut phases: Vec<Option<crate::assert::Phase>> = Vec::with_capacity(self.rows.len());
280
281 for row in &self.rows {
282 tags.push(row.tag.clone());
283 elapsed.push(row.elapsed_ms);
284 phases.push(row.step_index.map(crate::assert::Phase::from));
285
286 if row.report.is_placeholder {
287 let err = crate::scenario::snapshot::SnapshotError::PlaceholderSample {
288 tag: row.tag.clone(),
289 reason: row
290 .report
291 .scx_walker_unavailable
292 .clone()
293 .unwrap_or_else(|| "placeholder report".to_string()),
294 };
295 for slot in &mut per_field {
296 slot.push(Err(err.clone()));
297 }
298 continue;
299 }
300
301 let snap = Snapshot::new(&row.report);
302 // Slice cast: live_vars_via takes &[&str], we hold [&str; N].
303 match snap.live_vars_via(&names, picker) {
304 Ok(fields) => {
305 debug_assert_eq!(fields.len(), N);
306 for (i, field) in fields.into_iter().enumerate() {
307 per_field[i].push(field.as_u64());
308 }
309 }
310 Err(e) => {
311 for slot in &mut per_field {
312 slot.push(Err(e.clone()));
313 }
314 }
315 }
316 }
317
318 // Build N SeriesFields, each consuming its own per-field
319 // value vector. Tags / elapsed / phases share the same
320 // sample identity across fields — clone for each output.
321 std::array::from_fn(|i| {
322 crate::assert::temporal::SeriesField::from_parts_with_phases_opt(
323 names[i].to_string(),
324 tags.clone(),
325 elapsed.clone(),
326 std::mem::take(&mut per_field[i]),
327 phases.clone(),
328 )
329 })
330 }
331
332 /// Auto-project a top-level BPF map's struct members. The
333 /// returned [`BpfMapProjector`] auto-discovers struct member
334 /// names at sample 0 and exposes them via `.field_u64(name)` /
335 /// `.field_i64(name)` / `.field_f64(name)` — a caller that
336 /// wants every scalar field of a BSS struct without
337 /// enumerating each one by hand calls
338 /// `series.bpf_map("scx_obj.bss").at(0)` and then
339 /// `.field_u64("nr_dispatched")` for the field of interest.
340 ///
341 /// **Top-level scalar fields only.** The auto-projector reads
342 /// directly-named struct members (e.g. `"nr_dispatched"`,
343 /// `"stall"`). Nested struct members (e.g. `"ctx.weight"`) and
344 /// deeper paths are NOT auto-discoverable through the typed
345 /// `field_*` helpers — for those, use the manual closure
346 /// projection [`SampleSeries::bpf`] with
347 /// `|snap| snap.var("ctx").get("weight").as_u64()` (or the
348 /// equivalent map-walking shape). Per-CPU maps are also out
349 /// of scope: they require an explicit `.cpu(N)` narrow on
350 /// the [`Snapshot`] accessor surface, so callers route
351 /// through the manual closure path for those as well.
352 pub fn bpf_map<'a>(&'a self, map_name: &'a str) -> BpfMapProjector<'a> {
353 BpfMapProjector {
354 series: self,
355 map_name,
356 entry_index: 0,
357 }
358 }
359}
360
361/// Auto-projector handle returned by [`SampleSeries::bpf_map`].
362/// Lazily resolves the named map's value at the requested entry
363/// index when `Self::field` is invoked.
364pub struct BpfMapProjector<'a> {
365 series: &'a SampleSeries,
366 map_name: &'a str,
367 entry_index: usize,
368}
369
370impl<'a> BpfMapProjector<'a> {
371 /// Pin the entry index for the projection. Defaults to `0`
372 /// (typical for ARRAY / `.bss` / `.data` / `.rodata` maps,
373 /// which carry a single value at index 0). Use this to walk
374 /// into a HASH map at a specific ordinal.
375 pub fn at(mut self, index: usize) -> Self {
376 self.entry_index = index;
377 self
378 }
379
380 /// Project a single named struct field as `u64` (the most
381 /// common temporal-assertion shape — counters, byte counts).
382 /// The label routed onto the resulting [`SeriesField`] is the
383 /// caller-supplied field name; combined with the map name in
384 /// the diagnostic the failure message reads
385 /// `"<map>.<entry_index>.<field>"`.
386 pub fn field_u64(&self, field: &str) -> SeriesField<u64> {
387 let map_name = self.map_name.to_string();
388 let entry_index = self.entry_index;
389 let field_owned = field.to_string();
390 self.series.bpf(field, move |snap| {
391 let entry = match snap.map(&map_name) {
392 Ok(m) => m.at(entry_index),
393 Err(e) => return Err(e),
394 };
395 entry.get(&field_owned).as_u64()
396 })
397 }
398
399 /// Project a single named struct field as `i64`.
400 pub fn field_i64(&self, field: &str) -> SeriesField<i64> {
401 let map_name = self.map_name.to_string();
402 let entry_index = self.entry_index;
403 let field_owned = field.to_string();
404 self.series.bpf(field, move |snap| {
405 let entry = match snap.map(&map_name) {
406 Ok(m) => m.at(entry_index),
407 Err(e) => return Err(e),
408 };
409 entry.get(&field_owned).as_i64()
410 })
411 }
412
413 /// Project a single named struct field as `f64`.
414 pub fn field_f64(&self, field: &str) -> SeriesField<f64> {
415 let map_name = self.map_name.to_string();
416 let entry_index = self.entry_index;
417 let field_owned = field.to_string();
418 self.series.bpf(field, move |snap| {
419 let entry = match snap.map(&map_name) {
420 Ok(m) => m.at(entry_index),
421 Err(e) => return Err(e),
422 };
423 entry.get(&field_owned).as_f64()
424 })
425 }
426
427 /// Discover the struct member names of the map's rendered value,
428 /// unioned across ALL samples (first-seen order, deduplicated).
429 /// Useful for tests that want to enumerate every scalar field for a
430 /// blanket assertion.
431 ///
432 /// Discovery spans every row rather than `rows.first()` alone: sample
433 /// 0 can be a placeholder (the map missing or not yet captured) while
434 /// later rows carry the struct, and reading only row 0 would silently
435 /// enumerate nothing — blinding a "assert over every scalar field"
436 /// projection. Empty ONLY when NO sample renders the map as a struct
437 /// (the field set is genuinely undiscoverable).
438 pub fn member_names(&self) -> Vec<String> {
439 let mut names: Vec<String> = Vec::new();
440 let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
441 for row in &self.series.rows {
442 let snap = Snapshot::new(&row.report);
443 let map = match snap.map(self.map_name) {
444 Ok(m) => m,
445 Err(_) => continue,
446 };
447 let entry = map.at(self.entry_index);
448 // Walk the entry's value — SnapshotEntry doesn't expose its
449 // struct members directly, but get("") returns the struct value
450 // (walk_dotted_path returns Value(root) for an empty path).
451 if let SnapshotField::Value(crate::monitor::btf_render::RenderedValue::Struct {
452 members,
453 ..
454 }) = entry.get("")
455 {
456 for m in members {
457 if seen.insert(m.name.clone()) {
458 names.push(m.name.clone());
459 }
460 }
461 }
462 }
463 names
464 }
465
466 /// Project every struct member that resolves as `u64` for at
467 /// least one sample. Iterates [`Self::member_names`], calls
468 /// [`Self::field_u64`] for each, and keeps the entries whose
469 /// resulting [`SeriesField`] has at least one `Ok` value —
470 /// non-numeric members (strings, nested structs, floats) drop
471 /// out because their `as_u64()` cast always errors.
472 pub fn u64_fields(&self) -> Vec<(String, SeriesField<u64>)> {
473 self.member_names()
474 .into_iter()
475 .filter_map(|name| {
476 let field = self.field_u64(&name);
477 // Bind the predicate result and drop the
478 // values_iter borrow before moving `field`. A
479 // chained `.values_iter().any(...).then_some(...)`
480 // keeps the iterator alive across the move and
481 // fails the borrow check.
482 let any_ok = field.values_iter().any(|r| r.is_ok());
483 any_ok.then_some((name, field))
484 })
485 .collect()
486 }
487
488 /// Project every struct member that resolves as `f64` for at
489 /// least one sample. Mirrors [`Self::u64_fields`] using
490 /// [`Self::field_f64`].
491 pub fn f64_fields(&self) -> Vec<(String, SeriesField<f64>)> {
492 self.member_names()
493 .into_iter()
494 .filter_map(|name| {
495 let field = self.field_f64(&name);
496 let any_ok = field.values_iter().any(|r| r.is_ok());
497 any_ok.then_some((name, field))
498 })
499 .collect()
500 }
501
502 // -----------------------------------------------------------------
503 // Per-CPU projection. A `BPF_MAP_TYPE_PERCPU_ARRAY` /
504 // `*_PERCPU_HASH` value has one slot per CPU; the scalar
505 // `field_*` helpers above can't read it (`.get()` on a per-CPU
506 // entry returns `PerCpuNotNarrowed`). Two ways in:
507 // - aggregate across CPUs: `field_cpu_sum_u64` etc., delegating
508 // to the [`SnapshotEntry`](crate::scenario::snapshot::SnapshotEntry)
509 // `cpu_*` reductions — None slots (unmapped / unreadable CPUs)
510 // are skipped; the empty set (every slot None) yields
511 // `Err(NoMatch)` for sum, max, and min alike, since a None slot
512 // is unreadable rather than a real zero;
513 // - select one CPU: [`Self::cpu`] → [`BpfMapCpuProjector`].
514 // -----------------------------------------------------------------
515
516 /// Sum a named per-CPU field across all CPUs as `u64`.
517 /// `Err(NoMatch)` when every slot is `None` (unreadable, not a real
518 /// zero); a readable all-zero map sums to `Ok(0)`. Delegates to
519 /// [`SnapshotEntry::cpu_sum_u64`](crate::scenario::snapshot::SnapshotEntry::cpu_sum_u64).
520 pub fn field_cpu_sum_u64(&self, field: &str) -> SeriesField<u64> {
521 let map_name = self.map_name.to_string();
522 let entry_index = self.entry_index;
523 let field_owned = field.to_string();
524 self.series.bpf(field, move |snap| {
525 let entry = match snap.map(&map_name) {
526 Ok(m) => m.at(entry_index),
527 Err(e) => return Err(e),
528 };
529 entry.cpu_sum_u64(&field_owned)
530 })
531 }
532
533 /// Sum a named per-CPU field across all CPUs as `i64`. The sum
534 /// saturates at `i64::MIN` / `i64::MAX` (parity with the `u64`
535 /// variant's `saturating_add`). `Err(NoMatch)` when every slot is
536 /// `None` (unreadable, not a real zero); a readable all-zero map
537 /// sums to `Ok(0)`. Delegates to
538 /// [`SnapshotEntry::cpu_sum_i64`](crate::scenario::snapshot::SnapshotEntry::cpu_sum_i64).
539 pub fn field_cpu_sum_i64(&self, field: &str) -> SeriesField<i64> {
540 let map_name = self.map_name.to_string();
541 let entry_index = self.entry_index;
542 let field_owned = field.to_string();
543 self.series.bpf(field, move |snap| {
544 let entry = match snap.map(&map_name) {
545 Ok(m) => m.at(entry_index),
546 Err(e) => return Err(e),
547 };
548 entry.cpu_sum_i64(&field_owned)
549 })
550 }
551
552 /// Sum a named per-CPU field across all CPUs as `f64`.
553 /// `Err(NoMatch)` when every slot is `None` (unreadable, not a real
554 /// zero); a readable all-zero map sums to `Ok(0.0)`. Delegates to
555 /// [`SnapshotEntry::cpu_sum_f64`](crate::scenario::snapshot::SnapshotEntry::cpu_sum_f64).
556 pub fn field_cpu_sum_f64(&self, field: &str) -> SeriesField<f64> {
557 let map_name = self.map_name.to_string();
558 let entry_index = self.entry_index;
559 let field_owned = field.to_string();
560 self.series.bpf(field, move |snap| {
561 let entry = match snap.map(&map_name) {
562 Ok(m) => m.at(entry_index),
563 Err(e) => return Err(e),
564 };
565 entry.cpu_sum_f64(&field_owned)
566 })
567 }
568
569 /// Maximum of a named per-CPU field across all CPUs as `u64`.
570 /// `Err(NoMatch)` when no CPU slot contributed. Delegates to
571 /// [`SnapshotEntry::cpu_max_u64`](crate::scenario::snapshot::SnapshotEntry::cpu_max_u64).
572 pub fn field_cpu_max_u64(&self, field: &str) -> SeriesField<u64> {
573 let map_name = self.map_name.to_string();
574 let entry_index = self.entry_index;
575 let field_owned = field.to_string();
576 self.series.bpf(field, move |snap| {
577 let entry = match snap.map(&map_name) {
578 Ok(m) => m.at(entry_index),
579 Err(e) => return Err(e),
580 };
581 entry.cpu_max_u64(&field_owned)
582 })
583 }
584
585 /// Maximum of a named per-CPU field across all CPUs as `i64`.
586 /// `Err(NoMatch)` when no CPU slot contributed. Delegates to
587 /// [`SnapshotEntry::cpu_max_i64`](crate::scenario::snapshot::SnapshotEntry::cpu_max_i64).
588 pub fn field_cpu_max_i64(&self, field: &str) -> SeriesField<i64> {
589 let map_name = self.map_name.to_string();
590 let entry_index = self.entry_index;
591 let field_owned = field.to_string();
592 self.series.bpf(field, move |snap| {
593 let entry = match snap.map(&map_name) {
594 Ok(m) => m.at(entry_index),
595 Err(e) => return Err(e),
596 };
597 entry.cpu_max_i64(&field_owned)
598 })
599 }
600
601 /// Maximum of a named per-CPU field across all CPUs as `f64`.
602 /// `Err(NoMatch)` when no CPU slot contributed; an all-NaN run
603 /// yields `Ok(NaN)`. Delegates to
604 /// [`SnapshotEntry::cpu_max_f64`](crate::scenario::snapshot::SnapshotEntry::cpu_max_f64).
605 pub fn field_cpu_max_f64(&self, field: &str) -> SeriesField<f64> {
606 let map_name = self.map_name.to_string();
607 let entry_index = self.entry_index;
608 let field_owned = field.to_string();
609 self.series.bpf(field, move |snap| {
610 let entry = match snap.map(&map_name) {
611 Ok(m) => m.at(entry_index),
612 Err(e) => return Err(e),
613 };
614 entry.cpu_max_f64(&field_owned)
615 })
616 }
617
618 /// Minimum of a named per-CPU field across all CPUs as `u64`.
619 /// `Err(NoMatch)` when no CPU slot contributed. Delegates to
620 /// [`SnapshotEntry::cpu_min_u64`](crate::scenario::snapshot::SnapshotEntry::cpu_min_u64).
621 pub fn field_cpu_min_u64(&self, field: &str) -> SeriesField<u64> {
622 let map_name = self.map_name.to_string();
623 let entry_index = self.entry_index;
624 let field_owned = field.to_string();
625 self.series.bpf(field, move |snap| {
626 let entry = match snap.map(&map_name) {
627 Ok(m) => m.at(entry_index),
628 Err(e) => return Err(e),
629 };
630 entry.cpu_min_u64(&field_owned)
631 })
632 }
633
634 /// Minimum of a named per-CPU field across all CPUs as `i64`.
635 /// `Err(NoMatch)` when no CPU slot contributed. Delegates to
636 /// [`SnapshotEntry::cpu_min_i64`](crate::scenario::snapshot::SnapshotEntry::cpu_min_i64).
637 pub fn field_cpu_min_i64(&self, field: &str) -> SeriesField<i64> {
638 let map_name = self.map_name.to_string();
639 let entry_index = self.entry_index;
640 let field_owned = field.to_string();
641 self.series.bpf(field, move |snap| {
642 let entry = match snap.map(&map_name) {
643 Ok(m) => m.at(entry_index),
644 Err(e) => return Err(e),
645 };
646 entry.cpu_min_i64(&field_owned)
647 })
648 }
649
650 /// Minimum of a named per-CPU field across all CPUs as `f64`.
651 /// `Err(NoMatch)` when no CPU slot contributed; an all-NaN run
652 /// yields `Ok(NaN)`. Delegates to
653 /// [`SnapshotEntry::cpu_min_f64`](crate::scenario::snapshot::SnapshotEntry::cpu_min_f64).
654 pub fn field_cpu_min_f64(&self, field: &str) -> SeriesField<f64> {
655 let map_name = self.map_name.to_string();
656 let entry_index = self.entry_index;
657 let field_owned = field.to_string();
658 self.series.bpf(field, move |snap| {
659 let entry = match snap.map(&map_name) {
660 Ok(m) => m.at(entry_index),
661 Err(e) => return Err(e),
662 };
663 entry.cpu_min_f64(&field_owned)
664 })
665 }
666
667 /// Narrow to a single CPU's slot of a per-CPU map, returning a
668 /// [`BpfMapCpuProjector`] whose `field_*` read CPU `n` (vs the
669 /// cross-CPU [`Self::field_cpu_sum_u64`] reductions). Mirrors
670 /// [`Self::at`] as a builder step; making the per-CPU SELECT a
671 /// distinct handle means `.cpu(n).field_cpu_sum_*` cannot be
672 /// written (aggregate-vs-select can't be mixed up).
673 ///
674 /// On a non-per-CPU map (`.bss` / ARRAY / HASH) `.cpu(n)` is a
675 /// no-op — the underlying [`SnapshotMap::cpu`](crate::scenario::snapshot::SnapshotMap::cpu)
676 /// narrow is recorded but ignored, so the value reads the same as
677 /// without it (it neither errors nor filters).
678 pub fn cpu(self, n: usize) -> BpfMapCpuProjector<'a> {
679 BpfMapCpuProjector {
680 series: self.series,
681 map_name: self.map_name,
682 entry_index: self.entry_index,
683 cpu: n,
684 }
685 }
686}
687
688/// Single-CPU view of a per-CPU BPF map, returned by
689/// [`BpfMapProjector::cpu`]. Its `field_*` read the chosen CPU's slot
690/// of the map's per-CPU value — the per-CPU SELECT counterpart to the
691/// cross-CPU [`BpfMapProjector::field_cpu_sum_u64`] reductions.
692///
693/// On a non-per-CPU map the CPU narrow is a no-op (see
694/// [`BpfMapProjector::cpu`]), so `field_*` read the plain value.
695pub struct BpfMapCpuProjector<'a> {
696 series: &'a SampleSeries,
697 map_name: &'a str,
698 entry_index: usize,
699 cpu: usize,
700}
701
702impl<'a> BpfMapCpuProjector<'a> {
703 /// Project this CPU's slot of a named struct field as `u64`.
704 pub fn field_u64(&self, field: &str) -> SeriesField<u64> {
705 let map_name = self.map_name.to_string();
706 let entry_index = self.entry_index;
707 let cpu = self.cpu;
708 let field_owned = field.to_string();
709 self.series.bpf(field, move |snap| {
710 let entry = match snap.map(&map_name) {
711 Ok(m) => m.cpu(cpu).at(entry_index),
712 Err(e) => return Err(e),
713 };
714 entry.get(&field_owned).as_u64()
715 })
716 }
717
718 /// Project this CPU's slot of a named struct field as `i64`.
719 pub fn field_i64(&self, field: &str) -> SeriesField<i64> {
720 let map_name = self.map_name.to_string();
721 let entry_index = self.entry_index;
722 let cpu = self.cpu;
723 let field_owned = field.to_string();
724 self.series.bpf(field, move |snap| {
725 let entry = match snap.map(&map_name) {
726 Ok(m) => m.cpu(cpu).at(entry_index),
727 Err(e) => return Err(e),
728 };
729 entry.get(&field_owned).as_i64()
730 })
731 }
732
733 /// Project this CPU's slot of a named struct field as `f64`.
734 pub fn field_f64(&self, field: &str) -> SeriesField<f64> {
735 let map_name = self.map_name.to_string();
736 let entry_index = self.entry_index;
737 let cpu = self.cpu;
738 let field_owned = field.to_string();
739 self.series.bpf(field, move |snap| {
740 let entry = match snap.map(&map_name) {
741 Ok(m) => m.cpu(cpu).at(entry_index),
742 Err(e) => return Err(e),
743 };
744 entry.get(&field_owned).as_f64()
745 })
746 }
747}
748
749#[cfg(test)]
750mod tests {
751 use super::*;
752 use crate::monitor::btf_render::{RenderedMember, RenderedValue};
753 use crate::monitor::dump::{FailureDumpMap, FailureDumpReport, SCHEMA_SINGLE};
754
755 fn synthetic_report(value: u64) -> FailureDumpReport {
756 let bss_value = RenderedValue::Struct {
757 type_name: Some(".bss".into()),
758 members: vec![
759 RenderedMember {
760 name: "nr_dispatched".into(),
761 value: RenderedValue::Uint { bits: 64, value },
762 },
763 RenderedMember {
764 name: "stall".into(),
765 value: RenderedValue::Uint { bits: 8, value: 0 },
766 },
767 ],
768 };
769 let bss_map = FailureDumpMap {
770 name: "scx_obj.bss".into(),
771 map_type: 2,
772 value_size: 16,
773 max_entries: 1,
774 value: Some(bss_value),
775 ..Default::default()
776 };
777 FailureDumpReport {
778 schema: SCHEMA_SINGLE.to_string(),
779 active_map_kvas: Vec::new(),
780 maps: vec![bss_map],
781 ..Default::default()
782 }
783 }
784
785 /// Build a synthetic report with mixed-shape members so the
786 /// `u64_fields` / `f64_fields` auto-projectors exercise the
787 /// "at least one Ok" filter:
788 /// - `nr_dispatched`: Uint — projects Ok as u64.
789 /// - `stall`: Uint — projects Ok as u64.
790 /// - `balance`: Float — projects Err as u64 (TypeMismatch),
791 /// Ok as f64.
792 /// - `flag_str`: Bytes — projects Err as both u64 and f64.
793 fn mixed_shape_report(disp: u64, balance: f64) -> FailureDumpReport {
794 let bss_value = RenderedValue::Struct {
795 type_name: Some(".bss".into()),
796 members: vec![
797 RenderedMember {
798 name: "nr_dispatched".into(),
799 value: RenderedValue::Uint {
800 bits: 64,
801 value: disp,
802 },
803 },
804 RenderedMember {
805 name: "stall".into(),
806 value: RenderedValue::Uint { bits: 8, value: 0 },
807 },
808 RenderedMember {
809 name: "balance".into(),
810 value: RenderedValue::Float {
811 bits: 64,
812 value: balance,
813 },
814 },
815 RenderedMember {
816 name: "flag_str".into(),
817 value: RenderedValue::Bytes {
818 hex: "de ad".into(),
819 },
820 },
821 ],
822 };
823 let bss_map = FailureDumpMap {
824 name: "scx_obj.bss".into(),
825 map_type: 2,
826 value_size: 32,
827 max_entries: 1,
828 value: Some(bss_value),
829 ..Default::default()
830 };
831 FailureDumpReport {
832 schema: SCHEMA_SINGLE.to_string(),
833 active_map_kvas: Vec::new(),
834 maps: vec![bss_map],
835 ..Default::default()
836 }
837 }
838
839 #[test]
840 fn bpf_projection_extracts_field_per_sample() {
841 let drained = vec![
842 (
843 "periodic_000".to_string(),
844 synthetic_report(10),
845 None,
846 Some(100),
847 ),
848 (
849 "periodic_001".to_string(),
850 synthetic_report(20),
851 None,
852 Some(200),
853 ),
854 ];
855 let series = SampleSeries::from_drained(drained, None);
856 let field: SeriesField<u64> =
857 series.bpf("nr_dispatched", |snap| snap.var("nr_dispatched").as_u64());
858 let values: Vec<u64> = field
859 .values_iter()
860 .filter_map(|v| v.as_ref().ok().copied())
861 .collect();
862 assert_eq!(values, vec![10, 20]);
863 }
864
865 #[test]
866 fn bpf_map_projector_field_u64_extracts_field() {
867 let drained = vec![
868 (
869 "periodic_000".to_string(),
870 synthetic_report(10),
871 None,
872 Some(100),
873 ),
874 (
875 "periodic_001".to_string(),
876 synthetic_report(20),
877 None,
878 Some(200),
879 ),
880 ];
881 let series = SampleSeries::from_drained(drained, None);
882 let field = series
883 .bpf_map("scx_obj.bss")
884 .at(0)
885 .field_u64("nr_dispatched");
886 let values: Vec<u64> = field
887 .values_iter()
888 .filter_map(|v| v.as_ref().ok().copied())
889 .collect();
890 assert_eq!(values, vec![10, 20]);
891 }
892
893 #[test]
894 fn bpf_map_projector_member_names_lists_struct_fields() {
895 let drained = vec![(
896 "periodic_000".to_string(),
897 synthetic_report(10),
898 None,
899 Some(100),
900 )];
901 let series = SampleSeries::from_drained(drained, None);
902 let names = series.bpf_map("scx_obj.bss").at(0).member_names();
903 assert!(names.contains(&"nr_dispatched".to_string()));
904 assert!(names.contains(&"stall".to_string()));
905 }
906
907 /// `BpfMapProjector::u64_fields` keeps every member that yields
908 /// at least one `Ok` u64 across the series and drops members
909 /// whose every-sample projection errors. The mixed-shape report
910 /// above carries two u64 members (`nr_dispatched`, `stall`),
911 /// one f64-only member (`balance`) that errors on every u64
912 /// projection, and one bytes member (`flag_str`) that also
913 /// errors on every u64 projection. The returned vec must
914 /// surface only the two u64 names. The `SeriesField::label`
915 /// is set to the field name (see `BpfMapProjector::field_u64`),
916 /// so the tuple's first slot matches the struct member name
917 /// exactly.
918 #[test]
919 fn bpf_map_projector_u64_fields_keeps_at_least_one_ok_excludes_all_err() {
920 let drained = vec![
921 (
922 "periodic_000".to_string(),
923 mixed_shape_report(10, 1.5),
924 None,
925 Some(100),
926 ),
927 (
928 "periodic_001".to_string(),
929 mixed_shape_report(20, 2.5),
930 None,
931 Some(200),
932 ),
933 ];
934 let series = SampleSeries::from_drained(drained, None);
935 let fields = series.bpf_map("scx_obj.bss").at(0).u64_fields();
936 let names: Vec<&str> = fields.iter().map(|(n, _)| n.as_str()).collect();
937 assert!(
938 names.contains(&"nr_dispatched"),
939 "u64-shaped member must be kept: {names:?}",
940 );
941 assert!(
942 names.contains(&"stall"),
943 "u64-shaped member must be kept: {names:?}",
944 );
945 assert!(
946 !names.contains(&"balance"),
947 "Float-shaped member must be excluded — every u64 projection errors: {names:?}",
948 );
949 assert!(
950 !names.contains(&"flag_str"),
951 "Bytes-shaped member must be excluded — every u64 projection errors: {names:?}",
952 );
953 // The kept fields must carry the projected u64 values
954 // verbatim — the tuple's SeriesField is the same object
955 // `field_u64(name)` would return.
956 let dispatched = fields
957 .iter()
958 .find(|(n, _)| n == "nr_dispatched")
959 .expect("nr_dispatched kept above");
960 let values: Vec<u64> = dispatched
961 .1
962 .values_iter()
963 .filter_map(|r| r.as_ref().ok().copied())
964 .collect();
965 assert_eq!(
966 values,
967 vec![10, 20],
968 "kept SeriesField must carry the per-sample u64 projection",
969 );
970 }
971
972 /// Mirror of the u64 test for `f64_fields`. Float, Uint, Int,
973 /// and Enum members coerce to f64 (see `SnapshotField::as_f64`),
974 /// so all three numeric members are kept; the Bytes member
975 /// errors and is dropped. This pins the "at least one Ok"
976 /// filter for the f64 axis distinctly from the u64 axis.
977 #[test]
978 fn bpf_map_projector_f64_fields_keeps_at_least_one_ok_excludes_all_err() {
979 let drained = vec![
980 (
981 "periodic_000".to_string(),
982 mixed_shape_report(10, 1.5),
983 None,
984 Some(100),
985 ),
986 (
987 "periodic_001".to_string(),
988 mixed_shape_report(20, 2.5),
989 None,
990 Some(200),
991 ),
992 ];
993 let series = SampleSeries::from_drained(drained, None);
994 let fields = series.bpf_map("scx_obj.bss").at(0).f64_fields();
995 let names: Vec<&str> = fields.iter().map(|(n, _)| n.as_str()).collect();
996 assert!(
997 names.contains(&"nr_dispatched"),
998 "Uint coerces to f64 — must be kept: {names:?}",
999 );
1000 assert!(
1001 names.contains(&"stall"),
1002 "Uint coerces to f64 — must be kept: {names:?}",
1003 );
1004 assert!(
1005 names.contains(&"balance"),
1006 "Float coerces to f64 — must be kept: {names:?}",
1007 );
1008 assert!(
1009 !names.contains(&"flag_str"),
1010 "Bytes does not coerce to f64 — must be excluded: {names:?}",
1011 );
1012 let balance = fields
1013 .iter()
1014 .find(|(n, _)| n == "balance")
1015 .expect("balance kept above");
1016 let values: Vec<f64> = balance
1017 .1
1018 .values_iter()
1019 .filter_map(|r| r.as_ref().ok().copied())
1020 .collect();
1021 assert_eq!(values.len(), 2, "balance must surface one f64 per sample",);
1022 assert!((values[0] - 1.5).abs() < f64::EPSILON);
1023 assert!((values[1] - 2.5).abs() < f64::EPSILON);
1024 }
1025
1026 /// Empty series — no rows to discover member names from, so
1027 /// `member_names()` returns an empty vec and both auto-projectors
1028 /// yield empty results without panicking. Pins the zero-row
1029 /// iteration path in `BpfMapProjector::member_names` (the loop over
1030 /// `self.series.rows` runs zero times and returns an empty vec).
1031 #[test]
1032 fn bpf_map_projector_field_helpers_empty_series_yields_empty_vec() {
1033 let series = SampleSeries::empty();
1034 let u64s = series.bpf_map("scx_obj.bss").at(0).u64_fields();
1035 assert!(
1036 u64s.is_empty(),
1037 "empty series must yield empty u64_fields, got {} entries",
1038 u64s.len(),
1039 );
1040 let f64s = series.bpf_map("scx_obj.bss").at(0).f64_fields();
1041 assert!(
1042 f64s.is_empty(),
1043 "empty series must yield empty f64_fields, got {} entries",
1044 f64s.len(),
1045 );
1046 }
1047
1048 // --- per-CPU projection ---
1049
1050 /// Build a one-sample series with a single PERCPU map `cpu_ctxs`
1051 /// whose key 0 carries a per-CPU `cpu_ctx { dispatched: Uint }`
1052 /// slot per entry — `None` models an unreadable / unmapped CPU
1053 /// slot (the by-slot `None` the host renderer emits).
1054 fn percpu_series(per_cpu: &[Option<u64>]) -> SampleSeries {
1055 let slots: Vec<Option<RenderedValue>> = per_cpu
1056 .iter()
1057 .map(|v| {
1058 v.map(|n| RenderedValue::Struct {
1059 type_name: Some("cpu_ctx".into()),
1060 members: vec![RenderedMember {
1061 name: "dispatched".into(),
1062 value: RenderedValue::Uint { bits: 64, value: n },
1063 }],
1064 })
1065 })
1066 .collect();
1067 let map = FailureDumpMap {
1068 name: "cpu_ctxs".into(),
1069 percpu_entries: vec![crate::monitor::dump::FailureDumpPercpuEntry {
1070 key: 0,
1071 per_cpu: slots,
1072 }],
1073 ..Default::default()
1074 };
1075 let report = FailureDumpReport {
1076 schema: SCHEMA_SINGLE.to_string(),
1077 maps: vec![map],
1078 ..Default::default()
1079 };
1080 SampleSeries::from_drained(
1081 vec![("periodic_000".to_string(), report, None, Some(100))],
1082 None,
1083 )
1084 }
1085
1086 fn oks_u64(f: SeriesField<u64>) -> Vec<u64> {
1087 f.values_iter()
1088 .filter_map(|r| r.as_ref().ok().copied())
1089 .collect()
1090 }
1091 fn oks_i64(f: SeriesField<i64>) -> Vec<i64> {
1092 f.values_iter()
1093 .filter_map(|r| r.as_ref().ok().copied())
1094 .collect()
1095 }
1096 fn oks_f64(f: SeriesField<f64>) -> Vec<f64> {
1097 f.values_iter()
1098 .filter_map(|r| r.as_ref().ok().copied())
1099 .collect()
1100 }
1101
1102 /// `field_cpu_sum_u64` sums the readable per-CPU slots and SKIPS
1103 /// the `None` (unreadable) slot.
1104 #[test]
1105 fn bpf_map_projector_field_cpu_sum_u64_sums_present_skips_none() {
1106 let series = percpu_series(&[Some(11), Some(22), None, Some(44)]);
1107 assert_eq!(
1108 oks_u64(
1109 series
1110 .bpf_map("cpu_ctxs")
1111 .at(0)
1112 .field_cpu_sum_u64("dispatched")
1113 ),
1114 vec![11 + 22 + 44],
1115 );
1116 }
1117
1118 /// `field_cpu_max_u64` / `field_cpu_min_u64` reduce across the
1119 /// readable slots.
1120 #[test]
1121 fn bpf_map_projector_field_cpu_max_min_u64() {
1122 let series = percpu_series(&[Some(11), Some(22), None, Some(44)]);
1123 assert_eq!(
1124 oks_u64(
1125 series
1126 .bpf_map("cpu_ctxs")
1127 .at(0)
1128 .field_cpu_max_u64("dispatched")
1129 ),
1130 vec![44],
1131 );
1132 assert_eq!(
1133 oks_u64(
1134 series
1135 .bpf_map("cpu_ctxs")
1136 .at(0)
1137 .field_cpu_min_u64("dispatched")
1138 ),
1139 vec![11],
1140 );
1141 }
1142
1143 /// The NEW i64 reductions (`field_cpu_sum_i64` etc.) mirror the
1144 /// u64 ones over the same readable slots.
1145 #[test]
1146 fn bpf_map_projector_field_cpu_i64_aggregates() {
1147 let series = percpu_series(&[Some(11), Some(22), None, Some(44)]);
1148 assert_eq!(
1149 oks_i64(
1150 series
1151 .bpf_map("cpu_ctxs")
1152 .at(0)
1153 .field_cpu_sum_i64("dispatched")
1154 ),
1155 vec![77],
1156 );
1157 assert_eq!(
1158 oks_i64(
1159 series
1160 .bpf_map("cpu_ctxs")
1161 .at(0)
1162 .field_cpu_max_i64("dispatched")
1163 ),
1164 vec![44],
1165 );
1166 assert_eq!(
1167 oks_i64(
1168 series
1169 .bpf_map("cpu_ctxs")
1170 .at(0)
1171 .field_cpu_min_i64("dispatched")
1172 ),
1173 vec![11],
1174 );
1175 }
1176
1177 /// `field_cpu_sum_f64` reads the Uint slots as f64 and sums them.
1178 #[test]
1179 fn bpf_map_projector_field_cpu_sum_f64() {
1180 let series = percpu_series(&[Some(10), None, Some(30)]);
1181 assert_eq!(
1182 oks_f64(
1183 series
1184 .bpf_map("cpu_ctxs")
1185 .at(0)
1186 .field_cpu_sum_f64("dispatched")
1187 ),
1188 vec![40.0],
1189 );
1190 }
1191
1192 /// `.cpu(n)` selects ONE CPU's slot; an unmapped (`None`) slot
1193 /// surfaces as an error (distinct from the aggregate skip).
1194 #[test]
1195 fn bpf_map_projector_cpu_select_reads_one_cpu_and_errors_on_none() {
1196 let series = percpu_series(&[Some(11), Some(22), None, Some(44)]);
1197 assert_eq!(
1198 oks_u64(series.bpf_map("cpu_ctxs").cpu(1).field_u64("dispatched")),
1199 vec![22],
1200 );
1201 let none_slot = series.bpf_map("cpu_ctxs").cpu(2).field_u64("dispatched");
1202 assert!(
1203 none_slot.values_iter().all(|r| r.is_err()),
1204 "an unmapped CPU slot must surface as an error on select, not a value",
1205 );
1206 }
1207
1208 /// All-None: `field_cpu_sum_u64` AND `field_cpu_max_u64` both error.
1209 /// A None slot is UNREADABLE (host-read failure), not a real zero,
1210 /// so summing an all-None map to 0 would silently drop the missing
1211 /// data — sum now matches max/min (Err) rather than an empty-sum
1212 /// identity 0. A readable all-zero map still sums to Ok(0).
1213 #[test]
1214 fn bpf_map_projector_field_cpu_all_none_sum_and_max_error() {
1215 let series = percpu_series(&[None, None, None]);
1216 let sum = series
1217 .bpf_map("cpu_ctxs")
1218 .at(0)
1219 .field_cpu_sum_u64("dispatched");
1220 assert!(
1221 sum.values_iter().all(|r| r.is_err()),
1222 "all-None sum must error (None is unreadable, not a real zero), \
1223 not a silent Ok(0)",
1224 );
1225 let max = series
1226 .bpf_map("cpu_ctxs")
1227 .at(0)
1228 .field_cpu_max_u64("dispatched");
1229 assert!(
1230 max.values_iter().all(|r| r.is_err()),
1231 "all-None max must error (max of the empty set is undefined)",
1232 );
1233 }
1234
1235 /// A cross-CPU reduction on a NON-per-CPU map errors (the value is
1236 /// not a per-CPU entry) rather than silently mis-reading it.
1237 #[test]
1238 fn bpf_map_projector_field_cpu_sum_on_non_percpu_errors() {
1239 let series = SampleSeries::from_drained(
1240 vec![(
1241 "periodic_000".to_string(),
1242 synthetic_report(10),
1243 None,
1244 Some(100),
1245 )],
1246 None,
1247 );
1248 let f = series
1249 .bpf_map("scx_obj.bss")
1250 .at(0)
1251 .field_cpu_sum_u64("nr_dispatched");
1252 assert!(
1253 f.values_iter().all(|r| r.is_err()),
1254 "cpu_sum on a non-per-CPU map must error (TypeMismatch)",
1255 );
1256 }
1257
1258 /// A readable per-CPU slot whose value can't decode to the
1259 /// requested scalar makes the aggregate ERR (not a silent skip /
1260 /// partial sum) — only `None` (unreadable) slots are skipped. The
1261 /// aggregator's `?` on `as_u64()` propagates the decode failure and
1262 /// stops the walk, so a malformed slot can never be silently
1263 /// dropped from the sum (the no-silent-drop contract).
1264 #[test]
1265 fn bpf_map_projector_field_cpu_sum_errors_on_non_numeric_slot() {
1266 let bad = RenderedValue::Struct {
1267 type_name: Some("cpu_ctx".into()),
1268 members: vec![RenderedMember {
1269 name: "dispatched".into(),
1270 value: RenderedValue::Bytes {
1271 hex: "de ad".into(),
1272 },
1273 }],
1274 };
1275 let good = RenderedValue::Struct {
1276 type_name: Some("cpu_ctx".into()),
1277 members: vec![RenderedMember {
1278 name: "dispatched".into(),
1279 value: RenderedValue::Uint { bits: 64, value: 7 },
1280 }],
1281 };
1282 let map = FailureDumpMap {
1283 name: "cpu_ctxs".into(),
1284 percpu_entries: vec![crate::monitor::dump::FailureDumpPercpuEntry {
1285 key: 0,
1286 per_cpu: vec![Some(bad), Some(good)],
1287 }],
1288 ..Default::default()
1289 };
1290 let report = FailureDumpReport {
1291 schema: SCHEMA_SINGLE.to_string(),
1292 maps: vec![map],
1293 ..Default::default()
1294 };
1295 let series = SampleSeries::from_drained(
1296 vec![("periodic_000".to_string(), report, None, Some(100))],
1297 None,
1298 );
1299 let f = series
1300 .bpf_map("cpu_ctxs")
1301 .at(0)
1302 .field_cpu_sum_u64("dispatched");
1303 assert!(
1304 f.values_iter().all(|r| r.is_err()),
1305 "a non-numeric readable slot must make field_cpu_sum_u64 ERR \
1306 (no silent skip / partial sum over the numeric slots)",
1307 );
1308 }
1309
1310 /// Build a synthetic two-bss report: `scx_obj.bss` with `cross
1311 /// = a` + `same = b`, and OPTIONALLY a second `scx_other.bss`
1312 /// with `cross = c` + `same = d`. Mirrors the post-
1313 /// `Op::ReplaceScheduler` shape where two scheduler obj bss
1314 /// copies coexist in the same snapshot and `live_vars_via`'s
1315 /// picker resolves which one is live by max-sum.
1316 fn two_bss_report(primary: (u64, u64), secondary: Option<(u64, u64)>) -> FailureDumpReport {
1317 fn make_bss(name: &str, cross: u64, same: u64) -> FailureDumpMap {
1318 FailureDumpMap {
1319 name: name.into(),
1320 map_type: 2,
1321 value_size: 16,
1322 max_entries: 1,
1323 value: Some(RenderedValue::Struct {
1324 type_name: Some(name.into()),
1325 members: vec![
1326 RenderedMember {
1327 name: "cross".into(),
1328 value: RenderedValue::Uint {
1329 bits: 64,
1330 value: cross,
1331 },
1332 },
1333 RenderedMember {
1334 name: "same".into(),
1335 value: RenderedValue::Uint {
1336 bits: 64,
1337 value: same,
1338 },
1339 },
1340 ],
1341 }),
1342 ..Default::default()
1343 }
1344 }
1345 let mut maps = vec![make_bss("scx_obj.bss", primary.0, primary.1)];
1346 if let Some((c, s)) = secondary {
1347 maps.push(make_bss("scx_other.bss", c, s));
1348 }
1349 FailureDumpReport {
1350 schema: SCHEMA_SINGLE.to_string(),
1351 active_map_kvas: Vec::new(),
1352 maps,
1353 ..Default::default()
1354 }
1355 }
1356
1357 /// Single-candidate map: `live_bpf_vars_via` should resolve
1358 /// both names from `scx_obj.bss` per sample and produce two
1359 /// parallel `SeriesField<u64>`s carrying the per-sample
1360 /// `cross` and `same` values.
1361 #[test]
1362 fn live_bpf_vars_via_single_map_co_picks_both_names() {
1363 let drained = vec![
1364 (
1365 "periodic_000".to_string(),
1366 two_bss_report((10, 20), None),
1367 None,
1368 Some(100),
1369 ),
1370 (
1371 "periodic_001".to_string(),
1372 two_bss_report((30, 40), None),
1373 None,
1374 Some(200),
1375 ),
1376 ];
1377 let series = SampleSeries::from_drained(drained, None);
1378 let [cross, same] = series.live_bpf_vars_via(
1379 ["cross", "same"],
1380 crate::scenario::snapshot::pickers::max_by_sum_u64,
1381 );
1382 let cross_values: Vec<u64> = cross
1383 .values_iter()
1384 .filter_map(|r| r.as_ref().ok().copied())
1385 .collect();
1386 let same_values: Vec<u64> = same
1387 .values_iter()
1388 .filter_map(|r| r.as_ref().ok().copied())
1389 .collect();
1390 assert_eq!(cross_values, vec![10, 30]);
1391 assert_eq!(same_values, vec![20, 40]);
1392 }
1393
1394 /// Placeholder-mid-series: when one snapshot's report is a
1395 /// placeholder (freeze rendezvous failed, walker unavailable),
1396 /// EVERY field slot for that row gets the same
1397 /// `PlaceholderSample` error — not just one. Pins that the
1398 /// per-field substitution (`live_bpf_vars_via`'s
1399 /// `if row.report.is_placeholder` `for slot in &mut per_field` push loop)
1400 /// doesn't silently
1401 /// drop a sample from one field while keeping it in another.
1402 #[test]
1403 fn live_bpf_vars_via_placeholder_substitutes_into_all_field_slots() {
1404 // Build a synthetic placeholder report: is_placeholder=true,
1405 // no maps populated. The construction mirrors what
1406 // freeze_coord stores when a rendezvous times out.
1407 let placeholder = FailureDumpReport {
1408 schema: SCHEMA_SINGLE.to_string(),
1409 is_placeholder: true,
1410 scx_walker_unavailable: Some("rendezvous timed out".to_string()),
1411 ..Default::default()
1412 };
1413 let drained = vec![
1414 (
1415 "periodic_000".to_string(),
1416 two_bss_report((10, 20), None),
1417 None,
1418 Some(100),
1419 ),
1420 ("periodic_001".to_string(), placeholder, None, Some(200)),
1421 (
1422 "periodic_002".to_string(),
1423 two_bss_report((30, 40), None),
1424 None,
1425 Some(300),
1426 ),
1427 ];
1428 let series = SampleSeries::from_drained(drained, None);
1429 let [cross, same] = series.live_bpf_vars_via(
1430 ["cross", "same"],
1431 crate::scenario::snapshot::pickers::max_by_sum_u64,
1432 );
1433 let cross_results: Vec<bool> = cross.values_iter().map(|r| r.is_ok()).collect();
1434 let same_results: Vec<bool> = same.values_iter().map(|r| r.is_ok()).collect();
1435 // Sample 0 + 2: ok. Sample 1 (placeholder): err in BOTH
1436 // fields. The two fields' Ok/Err patterns must match —
1437 // otherwise the per-field split lost coherence.
1438 assert_eq!(cross_results, vec![true, false, true]);
1439 assert_eq!(same_results, vec![true, false, true]);
1440 // The placeholder slot's error must carry the
1441 // PlaceholderSample variant (not a generic catch-all).
1442 let cross_err = cross
1443 .values_iter()
1444 .nth(1)
1445 .unwrap()
1446 .as_ref()
1447 .expect_err("placeholder row produces Err");
1448 assert!(
1449 matches!(
1450 cross_err,
1451 crate::scenario::snapshot::SnapshotError::PlaceholderSample { .. }
1452 ),
1453 "placeholder row must surface PlaceholderSample; got {cross_err:?}",
1454 );
1455 }
1456
1457 /// When `live_vars_via` itself fails for a row (no candidate
1458 /// map has all the names, or the picker returned None), the
1459 /// SAME error MUST be substituted into all N field slots for
1460 /// that row — not split or dropped. Pins `live_bpf_vars_via`'s
1461 /// `Err(e) =>` `for slot in &mut per_field` error-substitution loop.
1462 #[test]
1463 fn live_bpf_vars_via_picker_none_substitutes_into_all_field_slots() {
1464 let drained = vec![(
1465 "periodic_000".to_string(),
1466 two_bss_report((10, 20), Some((30, 40))),
1467 None,
1468 Some(100),
1469 )];
1470 let series = SampleSeries::from_drained(drained, None);
1471 // Picker that always returns None — forces live_vars_via
1472 // to surface ProjectionFailed for the row.
1473 let always_none =
1474 |_rows: &[(&str, Vec<crate::scenario::snapshot::SnapshotField<'_>>)]| None;
1475 let [a, b] = series.live_bpf_vars_via(["cross", "same"], always_none);
1476 let a_err = a
1477 .values_iter()
1478 .next()
1479 .unwrap()
1480 .as_ref()
1481 .expect_err("picker-None must surface as Err");
1482 let b_err = b
1483 .values_iter()
1484 .next()
1485 .unwrap()
1486 .as_ref()
1487 .expect_err("picker-None must surface as Err — same row → same Err");
1488 // The two field slots' errors must carry the SAME variant.
1489 assert!(
1490 matches!(
1491 a_err,
1492 crate::scenario::snapshot::SnapshotError::ProjectionFailed { .. }
1493 ),
1494 "field 0 must carry ProjectionFailed; got {a_err:?}",
1495 );
1496 assert!(
1497 matches!(
1498 b_err,
1499 crate::scenario::snapshot::SnapshotError::ProjectionFailed { .. }
1500 ),
1501 "field 1 must carry ProjectionFailed; got {b_err:?}",
1502 );
1503 }
1504
1505 /// When the picker returns an out-of-range index, `live_vars_via`
1506 /// returns `ProjectionFailed` and the SAME error is substituted
1507 /// into every field slot for that row. Sibling of the
1508 /// picker-None case, distinct underlying failure mode.
1509 #[test]
1510 fn live_bpf_vars_via_picker_oor_substitutes_into_all_field_slots() {
1511 let drained = vec![(
1512 "periodic_000".to_string(),
1513 two_bss_report((10, 20), Some((30, 40))),
1514 None,
1515 Some(100),
1516 )];
1517 let series = SampleSeries::from_drained(drained, None);
1518 // Picker that returns an index way past the candidate count.
1519 let always_oor =
1520 |_rows: &[(&str, Vec<crate::scenario::snapshot::SnapshotField<'_>>)]| Some(999_usize);
1521 let [a, b] = series.live_bpf_vars_via(["cross", "same"], always_oor);
1522 let a_err = a.values_iter().next().unwrap().as_ref().err().unwrap();
1523 let b_err = b.values_iter().next().unwrap().as_ref().err().unwrap();
1524 assert!(
1525 matches!(
1526 a_err,
1527 crate::scenario::snapshot::SnapshotError::ProjectionFailed { .. }
1528 ),
1529 "picker-OOR must surface ProjectionFailed in field 0; got {a_err:?}",
1530 );
1531 assert!(
1532 matches!(
1533 b_err,
1534 crate::scenario::snapshot::SnapshotError::ProjectionFailed { .. }
1535 ),
1536 "picker-OOR must surface ProjectionFailed in field 1; got {b_err:?}",
1537 );
1538 }
1539
1540 /// Duplicate names in the request slice: `live_vars_via` pushes
1541 /// one field per name (no dedup), so the resulting per-field
1542 /// SeriesFields each carry the SAME projected values. Both
1543 /// fields are still well-formed (length matches sample count);
1544 /// the only "skew" is the trivial one where dup names produce
1545 /// dup values. Pins that the per-field split honors `names.len()`
1546 /// rather than a deduplicated set.
1547 #[test]
1548 fn live_bpf_vars_via_duplicate_names_yields_parallel_duplicates() {
1549 let drained = vec![(
1550 "periodic_000".to_string(),
1551 two_bss_report((10, 20), None),
1552 None,
1553 Some(100),
1554 )];
1555 let series = SampleSeries::from_drained(drained, None);
1556 let [a, b] = series.live_bpf_vars_via(
1557 ["cross", "cross"],
1558 crate::scenario::snapshot::pickers::max_by_sum_u64,
1559 );
1560 let av: Vec<u64> = a
1561 .values_iter()
1562 .filter_map(|r| r.as_ref().ok().copied())
1563 .collect();
1564 let bv: Vec<u64> = b
1565 .values_iter()
1566 .filter_map(|r| r.as_ref().ok().copied())
1567 .collect();
1568 assert_eq!(av, vec![10], "first slot carries 'cross' = 10");
1569 assert_eq!(bv, vec![10], "second slot (duplicate) carries 'cross' = 10");
1570 // Pin field-count parity with names.len(): no silent drop.
1571 assert_eq!(
1572 av.len(),
1573 bv.len(),
1574 "duplicate-names must not skew per-field length"
1575 );
1576 }
1577
1578 /// Multi-candidate map: `live_bpf_vars_via` must route both
1579 /// names through the SAME picker-selected candidate so the
1580 /// downstream ratio's numerator and denominator can't be
1581 /// split across two different scheduler obj bss copies. The
1582 /// `max_by_sum_u64` picker selects whichever bss has the
1583 /// larger `cross + same` sum.
1584 #[test]
1585 fn live_bpf_vars_via_two_maps_picker_routes_both_through_winner() {
1586 let drained = vec![
1587 // Sample 0: primary sum 30, secondary sum 1100 → secondary wins
1588 (
1589 "periodic_000".to_string(),
1590 two_bss_report((10, 20), Some((500, 600))),
1591 None,
1592 Some(100),
1593 ),
1594 // Sample 1: primary sum 10000, secondary sum 100 → primary wins
1595 (
1596 "periodic_001".to_string(),
1597 two_bss_report((4000, 6000), Some((50, 50))),
1598 None,
1599 Some(200),
1600 ),
1601 ];
1602 let series = SampleSeries::from_drained(drained, None);
1603 let [cross, same] = series.live_bpf_vars_via(
1604 ["cross", "same"],
1605 crate::scenario::snapshot::pickers::max_by_sum_u64,
1606 );
1607 let cross_values: Vec<u64> = cross
1608 .values_iter()
1609 .filter_map(|r| r.as_ref().ok().copied())
1610 .collect();
1611 let same_values: Vec<u64> = same
1612 .values_iter()
1613 .filter_map(|r| r.as_ref().ok().copied())
1614 .collect();
1615 // Sample 0: secondary wins → (500, 600). Sample 1: primary
1616 // wins → (4000, 6000). Both names came from the SAME map
1617 // per sample, never split.
1618 assert_eq!(cross_values, vec![500, 4000]);
1619 assert_eq!(same_values, vec![600, 6000]);
1620 }
1621
1622 /// Build a single-bss report stamped with the given
1623 /// `active_map_kvas` so phase-stability tests can simulate the
1624 /// walker resolving to one specific KVA set per snapshot.
1625 fn single_bss_report_with_kvas(value: u64, active_kvas: Vec<u64>) -> FailureDumpReport {
1626 let bss = FailureDumpMap {
1627 name: "scx_obj.bss".into(),
1628 map_kva: active_kvas.first().copied().unwrap_or(0),
1629 map_type: 2,
1630 value_size: 8,
1631 max_entries: 1,
1632 value: Some(RenderedValue::Struct {
1633 type_name: Some("scx_obj.bss".into()),
1634 members: vec![RenderedMember {
1635 name: "counter".into(),
1636 value: RenderedValue::Uint { bits: 64, value },
1637 }],
1638 }),
1639 ..Default::default()
1640 };
1641 FailureDumpReport {
1642 schema: crate::monitor::dump::SCHEMA_SINGLE.to_string(),
1643 active_obj_name: Some("scx_obj".to_string()),
1644 active_map_kvas: active_kvas,
1645 maps: vec![bss],
1646 ..Default::default()
1647 }
1648 }
1649
1650 fn drained_entry(
1651 tag: &str,
1652 report: FailureDumpReport,
1653 step_index: Option<u16>,
1654 elapsed_ms: u64,
1655 ) -> crate::scenario::snapshot::DrainedSnapshotEntry {
1656 crate::scenario::snapshot::DrainedSnapshotEntry {
1657 tag: tag.to_string(),
1658 report,
1659 stats: Err(crate::scenario::snapshot::MissingStatsReason::NoSchedulerBinary),
1660 elapsed_ms: Some(elapsed_ms),
1661 boundary_offset_ms: None,
1662 step_index,
1663 }
1664 }
1665
1666 /// Walker drift within a phase: sample 0 and sample 1 are in
1667 /// the same phase but their `active_map_kvas` differ (the
1668 /// walker re-published mid-phase, simulating the post-swap
1669 /// settle window). Sample 0 pins the phase to its KVA set;
1670 /// sample 1 must surface `WalkerDriftedWithinPhase` so the
1671 /// downstream counter-delta reducer sees a single-source
1672 /// monotonic series.
1673 #[test]
1674 fn bpf_live_u64_walker_drift_within_phase_surfaces_drift_error() {
1675 let drained = vec![
1676 drained_entry(
1677 "p001",
1678 single_bss_report_with_kvas(100, vec![0x1000]),
1679 Some(1),
1680 100,
1681 ),
1682 drained_entry(
1683 "p002",
1684 single_bss_report_with_kvas(200, vec![0x2000]),
1685 Some(1),
1686 200,
1687 ),
1688 ];
1689 let series = SampleSeries::from_drained_typed(drained, None);
1690 let f = series.bpf_live_u64("counter");
1691 let results: Vec<&SnapshotResult<u64>> = f.values_iter().collect();
1692 assert_eq!(results.len(), 2);
1693 assert!(
1694 matches!(results[0], Ok(100)),
1695 "first sample pins, got {:?}",
1696 results[0]
1697 );
1698 match results[1] {
1699 Err(crate::scenario::snapshot::SnapshotError::WalkerDriftedWithinPhase {
1700 pinned_kvas,
1701 sample_kvas,
1702 requested,
1703 ..
1704 }) => {
1705 assert_eq!(pinned_kvas, &vec![0x1000]);
1706 assert_eq!(sample_kvas, &vec![0x2000]);
1707 assert_eq!(requested, "counter");
1708 }
1709 other => panic!("expected WalkerDriftedWithinPhase, got {other:?}"),
1710 }
1711 }
1712
1713 /// Walker re-publishes the SAME KVA across same-phase
1714 /// samples — no drift. Both samples pass through with Ok
1715 /// values.
1716 #[test]
1717 fn bpf_live_u64_walker_stable_within_phase_passes_through() {
1718 let drained = vec![
1719 drained_entry(
1720 "p001",
1721 single_bss_report_with_kvas(100, vec![0x1000]),
1722 Some(1),
1723 100,
1724 ),
1725 drained_entry(
1726 "p002",
1727 single_bss_report_with_kvas(150, vec![0x1000]),
1728 Some(1),
1729 200,
1730 ),
1731 ];
1732 let series = SampleSeries::from_drained_typed(drained, None);
1733 let f = series.bpf_live_u64("counter");
1734 let results: Vec<&SnapshotResult<u64>> = f.values_iter().collect();
1735 assert!(matches!(results[0], Ok(100)));
1736 assert!(matches!(results[1], Ok(150)));
1737 }
1738
1739 /// Walker output is empty (pre-walker capture) for both
1740 /// samples — no pin established, no drift detection, both
1741 /// pass through unchanged (the per-snapshot AmbiguousVar
1742 /// guard at the Snapshot::var layer covers the
1743 /// multi-bss-with-empty-walker case separately).
1744 #[test]
1745 fn bpf_live_u64_empty_walker_output_passes_through() {
1746 let drained = vec![
1747 drained_entry(
1748 "p001",
1749 single_bss_report_with_kvas(100, vec![]),
1750 Some(1),
1751 100,
1752 ),
1753 drained_entry(
1754 "p002",
1755 single_bss_report_with_kvas(150, vec![]),
1756 Some(1),
1757 200,
1758 ),
1759 ];
1760 let series = SampleSeries::from_drained_typed(drained, None);
1761 let f = series.bpf_live_u64("counter");
1762 let results: Vec<&SnapshotResult<u64>> = f.values_iter().collect();
1763 assert!(matches!(results[0], Ok(100)));
1764 assert!(matches!(results[1], Ok(150)));
1765 }
1766
1767 /// Different phases get independent pins — drift detection
1768 /// resets at phase boundaries. Phase 1 pins to 0x1000;
1769 /// phase 2 pins to 0x2000 fresh.
1770 #[test]
1771 fn bpf_live_u64_pins_reset_at_phase_boundaries() {
1772 let drained = vec![
1773 drained_entry(
1774 "p001",
1775 single_bss_report_with_kvas(100, vec![0x1000]),
1776 Some(1),
1777 100,
1778 ),
1779 drained_entry(
1780 "p002",
1781 single_bss_report_with_kvas(150, vec![0x1000]),
1782 Some(1),
1783 200,
1784 ),
1785 drained_entry(
1786 "p003",
1787 single_bss_report_with_kvas(50, vec![0x2000]),
1788 Some(2),
1789 300,
1790 ),
1791 drained_entry(
1792 "p004",
1793 single_bss_report_with_kvas(75, vec![0x2000]),
1794 Some(2),
1795 400,
1796 ),
1797 ];
1798 let series = SampleSeries::from_drained_typed(drained, None);
1799 let f = series.bpf_live_u64("counter");
1800 let results: Vec<&SnapshotResult<u64>> = f.values_iter().collect();
1801 assert!(matches!(results[0], Ok(100)));
1802 assert!(matches!(results[1], Ok(150)));
1803 assert!(matches!(results[2], Ok(50)));
1804 assert!(matches!(results[3], Ok(75)));
1805 }
1806}