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}