ktstr/monitor/timeline.rs
1//! Failure-dump timeline support.
2//!
3//! Host-side consumer for the `timeline_events` BPF ringbuf
4//! populated by the `ktstr_tl_*` handlers in
5//! `src/bpf/probe.bpf.c`: [`parse_timeline_buf`] parses drained
6//! records into [`TimelineEvent`] values for the failure dump.
7//!
8//! The parser and [`TimelineCapture`] are re-exported from
9//! [`crate::live_host`] but no host-side drain consumes them yet —
10//! the BPF producer is live (its per-CPU counters surface as
11//! `bpf_timeline_count` / `bpf_timeline_drops` in the probe diag),
12//! the dump-pipeline consumer is the follow-up, which is why the
13//! parse path carries `#[allow(dead_code)]`.
14//!
15//! # Layout pinning
16//!
17//! [`TimelineEvent`] mirrors the on-the-wire `struct timeline_event`
18//! defined in `src/bpf/intf.h`. Field order, sizes, and the type
19//! constants must stay in lockstep — a unit test
20//! (`tests::timeline_event_layout_pinned`) verifies the 40-byte
21//! footprint and field offsets against the BPF-side layout.
22
23use serde::{Deserialize, Serialize};
24
25/// Type-byte values from `src/bpf/intf.h::TL_EVT_*`. Pinned here as
26/// the userspace-facing identifier for each variant; the parser
27/// uses these to discriminate the [`TimelineEvent`] variant.
28pub mod tl_evt {
29 /// `tp_btf/sched_switch` record. `prev_pid`/`next_pid`/`a` (prev_state)/`b` (preempt).
30 pub const SWITCH: u32 = 1;
31 /// `tp_btf/sched_migrate_task` record. `prev_pid`/`a` (dest_cpu)/`b` (orig_cpu).
32 pub const MIGRATE: u32 = 2;
33 /// `tp_btf/sched_wakeup` record. `prev_pid`/`a` (target_cpu).
34 pub const WAKEUP: u32 = 3;
35 /// `fentry/fexit` rt_mutex_setprio. PI boost record.
36 pub const PI_BOOST: u32 = 4;
37 /// `tp_btf/lock:contention_begin` record.
38 pub const LOCK_CONTEND: u32 = 5;
39}
40
41/// Wire-format mirror of `struct timeline_event` from
42/// `src/bpf/intf.h`.
43///
44/// Layout pinning: 40 bytes total (4 type + 4 cpu + 8 ts +
45/// 4 prev_pid + 4 next_pid + 8 a + 8 b). Order matches the BPF
46/// emit sites in `probe.bpf.c::ktstr_tl_switch/migrate/wakeup`.
47#[repr(C)]
48#[derive(Debug, Clone, Copy, PartialEq, Eq)]
49pub struct TimelineEventRaw {
50 pub type_: u32,
51 pub cpu: u32,
52 pub ts: u64,
53 pub prev_pid: u32,
54 pub next_pid: u32,
55 pub a: u64,
56 pub b: u64,
57}
58
59/// Parsed timeline event with variant-aware field naming.
60///
61/// `non_exhaustive` so future BPF event types added in `intf.h`
62/// (per the TL_EVT_PI_BOOST / TL_EVT_LOCK_CONTEND sites) can land
63/// without breaking existing on-disk dumps.
64#[derive(Debug, Clone, Serialize, Deserialize)]
65#[non_exhaustive]
66#[serde(tag = "kind")]
67#[allow(dead_code)] // re-exported for consumers; not yet wired into
68// the dump pipeline.
69pub enum TimelineEvent {
70 /// `tp_btf/sched_switch`. The kernel switched from `prev_pid`
71 /// to `next_pid` on `cpu` at `ts` (boot-time ns).
72 Switch {
73 ts: u64,
74 cpu: u32,
75 prev_pid: u32,
76 next_pid: u32,
77 /// Raw `prev_state` bitfield (TASK_RUNNING / TASK_INTERRUPTIBLE
78 /// / etc., from `include/linux/sched.h`).
79 prev_state: u64,
80 /// True when the switch was a preemption (vs voluntary
81 /// dequeue).
82 preempt: bool,
83 },
84 /// `tp_btf/sched_migrate_task`. Task `pid` migrated from
85 /// `orig_cpu` to `dest_cpu`.
86 Migrate {
87 ts: u64,
88 cpu: u32,
89 pid: u32,
90 orig_cpu: u32,
91 dest_cpu: u32,
92 },
93 /// `tp_btf/sched_wakeup`. Task `pid` woken up; scheduler
94 /// chose `target_cpu` for placement.
95 Wakeup {
96 ts: u64,
97 cpu: u32,
98 pid: u32,
99 target_cpu: u32,
100 },
101 /// PI boost. Probe-context tid `prober_tid`; boosted task
102 /// `pid`. `old_prio`/`new_prio` are the boosted task's effective
103 /// kernel priority (signed `int`) before and after the boost.
104 /// Scheduling-class transitions are counted separately via the
105 /// `pi_class_changes` counter, not carried in this record. Field
106 /// layout per `src/bpf/intf.h::TL_EVT_PI_BOOST`.
107 PiBoost {
108 ts: u64,
109 cpu: u32,
110 prober_tid: u32,
111 pid: u32,
112 old_prio: i32,
113 new_prio: i32,
114 },
115 /// Lock contention begin. `tid` is the waiter; `lock_kva` is
116 /// the lock's kernel virtual address; `flags` carries the
117 /// LCB_* class bits (F_SPIN, F_READ, F_WRITE, F_RT — see
118 /// `include/trace/events/lock.h`).
119 LockContend {
120 ts: u64,
121 cpu: u32,
122 tid: u32,
123 lock_kva: u64,
124 flags: u32,
125 },
126 /// Unrecognized type byte. Library doesn't drop unknown
127 /// records — surfacing them as `Unknown` lets the failure
128 /// dump preserve forward-compat data the consumer can opt
129 /// into rendering later.
130 Unknown {
131 ts: u64,
132 cpu: u32,
133 type_: u32,
134 prev_pid: u32,
135 next_pid: u32,
136 a: u64,
137 b: u64,
138 },
139}
140
141/// Parse a single 40-byte ringbuf record.
142///
143/// Returns `None` when the input is shorter than the on-the-wire
144/// size — the caller has truncated buffer / partial read and should
145/// stop draining at this slot.
146#[allow(dead_code)]
147pub fn parse_timeline_record(bytes: &[u8]) -> Option<TimelineEvent> {
148 if bytes.len() < std::mem::size_of::<TimelineEventRaw>() {
149 return None;
150 }
151 // SAFETY: TimelineEventRaw is repr(C) plain-data, all fields
152 // are integer types so any byte pattern is a valid value.
153 // The size check above guarantees we have enough bytes.
154 let raw = unsafe { std::ptr::read_unaligned(bytes.as_ptr() as *const TimelineEventRaw) };
155 Some(decode_raw(&raw))
156}
157
158/// Parse a contiguous buffer of timeline records into a vec of
159/// [`TimelineEvent`] values, in encounter order.
160///
161/// `bytes` is the concatenation of N timeline_event records.
162/// Trailing bytes that don't form a full record are silently
163/// dropped (a torn final record at ringbuf wrap is the typical
164/// case; the consumer's next drain picks up the remainder).
165#[allow(dead_code)]
166pub fn parse_timeline_buf(bytes: &[u8]) -> Vec<TimelineEvent> {
167 let stride = std::mem::size_of::<TimelineEventRaw>();
168 let mut out = Vec::with_capacity(bytes.len() / stride);
169 let mut off = 0;
170 while off + stride <= bytes.len() {
171 if let Some(ev) = parse_timeline_record(&bytes[off..off + stride]) {
172 out.push(ev);
173 }
174 off += stride;
175 }
176 out
177}
178
179fn decode_raw(raw: &TimelineEventRaw) -> TimelineEvent {
180 match raw.type_ {
181 tl_evt::SWITCH => TimelineEvent::Switch {
182 ts: raw.ts,
183 cpu: raw.cpu,
184 prev_pid: raw.prev_pid,
185 next_pid: raw.next_pid,
186 prev_state: raw.a,
187 preempt: raw.b != 0,
188 },
189 tl_evt::MIGRATE => TimelineEvent::Migrate {
190 ts: raw.ts,
191 cpu: raw.cpu,
192 pid: raw.prev_pid,
193 orig_cpu: raw.b as u32,
194 dest_cpu: raw.a as u32,
195 },
196 tl_evt::WAKEUP => TimelineEvent::Wakeup {
197 ts: raw.ts,
198 cpu: raw.cpu,
199 pid: raw.prev_pid,
200 target_cpu: raw.a as u32,
201 },
202 tl_evt::PI_BOOST => {
203 // The producer widens the signed kernel prio to u64 via
204 // (u64)(s64)prio; truncating back to i32 recovers the
205 // original signed value. No class id is packed in the high
206 // bits — class transitions surface via the pi_class_changes
207 // counter, not this record.
208 let old_prio = raw.a as i32;
209 let new_prio = raw.b as i32;
210 TimelineEvent::PiBoost {
211 ts: raw.ts,
212 cpu: raw.cpu,
213 prober_tid: raw.prev_pid,
214 pid: raw.next_pid,
215 old_prio,
216 new_prio,
217 }
218 }
219 tl_evt::LOCK_CONTEND => TimelineEvent::LockContend {
220 ts: raw.ts,
221 cpu: raw.cpu,
222 tid: raw.prev_pid,
223 lock_kva: raw.a,
224 flags: raw.b as u32,
225 },
226 _ => TimelineEvent::Unknown {
227 ts: raw.ts,
228 cpu: raw.cpu,
229 type_: raw.type_,
230 prev_pid: raw.prev_pid,
231 next_pid: raw.next_pid,
232 a: raw.a,
233 b: raw.b,
234 },
235 }
236}
237
238/// Capture handle for the freeze coordinator's drain of the
239/// `timeline_events` BPF ringbuf.
240///
241/// At dump time the coordinator constructs this with the drained
242/// raw bytes (concatenated 40-byte records, in ringbuf order) plus
243/// the BSS-side drop count. The dump consumer parses the buffer
244/// into [`TimelineEvent`] values. This capture is not yet consumed
245/// by the dump pipeline; the BSS-side drop count is surfaced today
246/// via [`super::dump::ProbeBssCounters::timeline_drops`] (reached
247/// through `super::dump::FailureDumpReport::probe_counters`).
248#[derive(Debug, Clone, Default)]
249#[allow(dead_code)]
250pub struct TimelineCapture<'a> {
251 /// Raw concatenated record bytes drained from the
252 /// `timeline_events` ringbuf. Length must be a multiple of
253 /// `size_of::<TimelineEventRaw>()` (40); trailing partial
254 /// records are silently dropped at parse time.
255 pub records: &'a [u8],
256 /// `KTSTR_PCPU_TIMELINE_DROPS` per-CPU slot (summed across
257 /// CPUs) at drain time. Non-zero indicates the BPF producer
258 /// hit a full ringbuf and dropped the newest event(s) on
259 /// submit.
260 pub drops: u64,
261}
262
263#[cfg(test)]
264mod tests {
265 use super::*;
266
267 /// `TimelineEventRaw` matches the BPF-side struct timeline_event
268 /// in size and field offsets. Drift here is a wire-protocol
269 /// break; the test catches it at compile + run time.
270 ///
271 /// Verdict-routed so a multi-field layout regression (e.g.
272 /// somebody re-orders the struct) surfaces every drift in one
273 /// run rather than failing on the first mismatch.
274 #[test]
275 fn timeline_event_layout_pinned() {
276 use crate::assert::Verdict;
277
278 let total_size = std::mem::size_of::<TimelineEventRaw>();
279 let off_type = std::mem::offset_of!(TimelineEventRaw, type_);
280 let off_cpu = std::mem::offset_of!(TimelineEventRaw, cpu);
281 let off_ts = std::mem::offset_of!(TimelineEventRaw, ts);
282 let off_prev_pid = std::mem::offset_of!(TimelineEventRaw, prev_pid);
283 let off_next_pid = std::mem::offset_of!(TimelineEventRaw, next_pid);
284 let off_a = std::mem::offset_of!(TimelineEventRaw, a);
285 let off_b = std::mem::offset_of!(TimelineEventRaw, b);
286
287 let mut v = Verdict::new();
288 // Total: 4 + 4 + 8 + 4 + 4 + 8 + 8 = 40 bytes.
289 crate::claim!(v, total_size).eq(40usize);
290 // Field offsets matching src/bpf/intf.h::struct timeline_event.
291 crate::claim!(v, off_type).eq(0usize);
292 crate::claim!(v, off_cpu).eq(4usize);
293 crate::claim!(v, off_ts).eq(8usize);
294 crate::claim!(v, off_prev_pid).eq(16usize);
295 crate::claim!(v, off_next_pid).eq(20usize);
296 crate::claim!(v, off_a).eq(24usize);
297 crate::claim!(v, off_b).eq(32usize);
298 let r = v.into_result();
299 assert!(
300 r.is_pass(),
301 "timeline_event layout drift detected: {:?}",
302 r.outcomes,
303 );
304 }
305
306 fn raw(type_: u32, cpu: u32, ts: u64, p: u32, n: u32, a: u64, b: u64) -> Vec<u8> {
307 let r = TimelineEventRaw {
308 type_,
309 cpu,
310 ts,
311 prev_pid: p,
312 next_pid: n,
313 a,
314 b,
315 };
316 // Safety: r is plain-data; reading its bytes is well-defined.
317 let bytes = unsafe {
318 std::slice::from_raw_parts(
319 &r as *const TimelineEventRaw as *const u8,
320 std::mem::size_of::<TimelineEventRaw>(),
321 )
322 };
323 bytes.to_vec()
324 }
325
326 /// Switch record decodes with prev/next pids + prev_state +
327 /// preempt bool. Verdict-routed so every field surfaces its own
328 /// labeled detail on regression.
329 #[test]
330 fn parse_switch_record() {
331 use crate::assert::Verdict;
332
333 let bytes = raw(tl_evt::SWITCH, 3, 1_000_000, 100, 200, 0x402, 1);
334 let ev = parse_timeline_record(&bytes).unwrap();
335 match ev {
336 TimelineEvent::Switch {
337 ts,
338 cpu,
339 prev_pid,
340 next_pid,
341 prev_state,
342 preempt,
343 } => {
344 let mut v = Verdict::new();
345 crate::claim!(v, ts).eq(1_000_000u64);
346 crate::claim!(v, cpu).eq(3u32);
347 crate::claim!(v, prev_pid).eq(100u32);
348 crate::claim!(v, next_pid).eq(200u32);
349 crate::claim!(v, prev_state).eq(0x402u64);
350 crate::claim!(v, preempt).eq(true);
351 let r = v.into_result();
352 assert!(r.is_pass(), "Switch record decode drift: {:?}", r.outcomes,);
353 }
354 other => panic!("expected Switch, got {other:?}"),
355 }
356 }
357
358 /// Migrate record decodes with pid + orig_cpu + dest_cpu.
359 /// Per intf.h: a = dest_cpu, b = orig_cpu.
360 #[test]
361 fn parse_migrate_record() {
362 let bytes = raw(tl_evt::MIGRATE, 1, 2_000_000, 555, 0, 7, 2);
363 let ev = parse_timeline_record(&bytes).unwrap();
364 match ev {
365 TimelineEvent::Migrate {
366 pid,
367 orig_cpu,
368 dest_cpu,
369 ..
370 } => {
371 assert_eq!(pid, 555);
372 assert_eq!(dest_cpu, 7);
373 assert_eq!(orig_cpu, 2);
374 }
375 other => panic!("expected Migrate, got {other:?}"),
376 }
377 }
378
379 /// Wakeup record decodes with pid + target_cpu.
380 #[test]
381 fn parse_wakeup_record() {
382 let bytes = raw(tl_evt::WAKEUP, 0, 3_000_000, 777, 0, 4, 0);
383 let ev = parse_timeline_record(&bytes).unwrap();
384 match ev {
385 TimelineEvent::Wakeup {
386 pid, target_cpu, ..
387 } => {
388 assert_eq!(pid, 777);
389 assert_eq!(target_cpu, 4);
390 }
391 other => panic!("expected Wakeup, got {other:?}"),
392 }
393 }
394
395 /// PiBoost carries the signed kernel prio in a/b, widened to u64
396 /// by the producer via `(u64)(s64)prio`. The decoder truncates
397 /// back to i32 — a negative prio (task boosted into the RT band)
398 /// must round-trip, which the old `(prio | class_id<<32)` split
399 /// corrupted by reading the sign-extension bits as a class id.
400 #[test]
401 fn parse_pi_boost_record() {
402 let old_a = (120i32 as i64) as u64; // prio=120 (normal band)
403 let new_b = (-1i32 as i64) as u64; // prio=-1 (sign-extended)
404 let bytes = raw(tl_evt::PI_BOOST, 2, 4_000_000, 10, 11, old_a, new_b);
405 let ev = parse_timeline_record(&bytes).unwrap();
406 match ev {
407 TimelineEvent::PiBoost {
408 prober_tid,
409 pid,
410 old_prio,
411 new_prio,
412 ..
413 } => {
414 assert_eq!(prober_tid, 10);
415 assert_eq!(pid, 11);
416 assert_eq!(old_prio, 120);
417 assert_eq!(new_prio, -1);
418 }
419 other => panic!("expected PiBoost, got {other:?}"),
420 }
421 }
422
423 /// LockContend record carries lock_kva + flags.
424 #[test]
425 fn parse_lock_contend_record() {
426 let lock_kva = 0xffff_ffff_8000_1000u64;
427 let flags = 0x4u64;
428 let bytes = raw(tl_evt::LOCK_CONTEND, 5, 5_000_000, 99, 0, lock_kva, flags);
429 let ev = parse_timeline_record(&bytes).unwrap();
430 match ev {
431 TimelineEvent::LockContend {
432 tid,
433 lock_kva: kva,
434 flags: f,
435 ..
436 } => {
437 assert_eq!(tid, 99);
438 assert_eq!(kva, lock_kva);
439 assert_eq!(f, 0x4);
440 }
441 other => panic!("expected LockContend, got {other:?}"),
442 }
443 }
444
445 /// Unknown type byte surfaces as Unknown variant — preserves
446 /// forward-compat data for newer kernels with TL_EVT_* values
447 /// the consumer doesn't yet decode.
448 #[test]
449 fn parse_unknown_type_preserves_fields() {
450 let bytes = raw(99, 7, 6_000_000, 1, 2, 3, 4);
451 let ev = parse_timeline_record(&bytes).unwrap();
452 match ev {
453 TimelineEvent::Unknown {
454 type_,
455 prev_pid,
456 a,
457 b,
458 ..
459 } => {
460 assert_eq!(type_, 99);
461 assert_eq!(prev_pid, 1);
462 assert_eq!(a, 3);
463 assert_eq!(b, 4);
464 }
465 other => panic!("expected Unknown, got {other:?}"),
466 }
467 }
468
469 /// Truncated record returns None — the drain loop stops
470 /// parsing rather than reading past end-of-buffer.
471 #[test]
472 fn parse_truncated_record_returns_none() {
473 let bytes = vec![0u8; 39]; // 1 byte short of 40
474 assert!(parse_timeline_record(&bytes).is_none());
475 }
476
477 /// `parse_timeline_buf` parses every full record in a multi-
478 /// record buffer and silently drops a partial trailing record.
479 #[test]
480 fn parse_timeline_buf_multi_record_with_partial_tail() {
481 let mut buf: Vec<u8> = Vec::new();
482 buf.extend(raw(tl_evt::SWITCH, 0, 1, 1, 2, 0, 0));
483 buf.extend(raw(tl_evt::WAKEUP, 1, 2, 3, 0, 4, 0));
484 // Append 20 bytes of partial record — must not parse.
485 buf.extend(vec![0u8; 20]);
486 let evs = parse_timeline_buf(&buf);
487 assert_eq!(evs.len(), 2);
488 assert!(matches!(evs[0], TimelineEvent::Switch { .. }));
489 assert!(matches!(evs[1], TimelineEvent::Wakeup { .. }));
490 }
491
492 /// `TimelineEvent` round-trips through serde — every variant
493 /// survives the json string.
494 #[test]
495 fn timeline_event_serde_roundtrip_all_variants() {
496 let cases = vec![
497 TimelineEvent::Switch {
498 ts: 1,
499 cpu: 0,
500 prev_pid: 10,
501 next_pid: 20,
502 prev_state: 1,
503 preempt: false,
504 },
505 TimelineEvent::Migrate {
506 ts: 2,
507 cpu: 1,
508 pid: 30,
509 orig_cpu: 1,
510 dest_cpu: 2,
511 },
512 TimelineEvent::Wakeup {
513 ts: 3,
514 cpu: 2,
515 pid: 40,
516 target_cpu: 5,
517 },
518 TimelineEvent::PiBoost {
519 ts: 4,
520 cpu: 3,
521 prober_tid: 1,
522 pid: 2,
523 old_prio: 120,
524 new_prio: 100,
525 },
526 TimelineEvent::LockContend {
527 ts: 5,
528 cpu: 4,
529 tid: 99,
530 lock_kva: 0xffff_ffff,
531 flags: 0x4,
532 },
533 ];
534 for ev in cases {
535 let json = serde_json::to_string(&ev).expect("serialize");
536 let _: TimelineEvent = serde_json::from_str(&json).expect("deserialize");
537 }
538 }
539}