Skip to main content

ntpsec_rs_xdp/
lib.rs

1// ──── lib.rs ──────────────────────────────────────────────────────────────────
2// Userspace loader for the ntpsec-rs XDP timestamp program.
3//
4// Provides:
5// - `NtpXdpTimestamp`: loads, attaches, and detaches the XDP program
6// - `NtpTimestampEvent`: parsed event data from the perf event buffer
7// - `XdpCollector`: high-level interface for the daemon event loop
8// =============================================================================
9
10#![doc = include_str!("../README.md")]
11
12use std::time::Duration;
13
14use aya::maps::PerfEventArray;
15use aya::programs::xdp::XdpLinkId;
16use aya::programs::{Xdp, XdpFlags};
17use aya::util::online_cpus;
18use aya::Bpf;
19use bytes::BytesMut;
20use ntpsec_rs_core::ntp_types::NtpTs64;
21use thiserror::Error;
22
23/// Error type for XDP operations.
24#[derive(Error, Debug)]
25pub enum XdpError {
26    /// Failed to load the BPF object file.
27    #[error("BPF load error: {0}")]
28    BpfLoad(#[from] aya::BpfError),
29
30    /// Failed to attach the XDP program to an interface.
31    #[error("XDP attach error: {0}")]
32    XdpAttach(String),
33
34    /// Failed to detach the XDP program.
35    #[error("XDP detach error: {0}")]
36    XdpDetach(String),
37
38    /// Error reading from the perf event buffer.
39    #[error("Perf event error: {0}")]
40    PerfEvent(String),
41
42    /// Interface not found or not available.
43    #[error("Interface error: {0}")]
44    Interface(String),
45
46    /// The BPF object does not contain the expected XDP program.
47    #[error("XDP program 'ntp_timestamp' not found in BPF object")]
48    ProgramNotFound,
49
50    /// Map error.
51    #[error("Map error: {0}")]
52    Map(#[from] aya::maps::MapError),
53}
54
55/// A single NTP timestamp event captured by the XDP/BPF program.
56///
57/// Fields are kept in sync with `NtpXdpEvent` in `xdp/src/ntp_timestamp.rs`.
58#[repr(C)]
59#[derive(Debug, Clone, Copy)]
60pub struct NtpTimestampEvent {
61    /// Source IPv4 address in network byte order.
62    pub source_ip: [u8; 4],
63    /// Destination IPv4 address in network byte order.
64    pub dest_ip: [u8; 4],
65    /// Kernel timestamp in nanoseconds (CLOCK_MONOTONIC / bpf_ktime_get_ns).
66    pub timestamp_ns: u64,
67    /// UDP source port.
68    pub src_port: u16,
69    /// UDP destination port.
70    pub dst_port: u16,
71    /// Packet length in bytes.
72    pub pkt_len: u16,
73    /// Padding to match the BPF struct layout.
74    _padding: [u8; 4],
75}
76
77impl NtpTimestampEvent {
78    /// Convert source IP to a standard IPv4 address.
79    pub fn source_addr(&self) -> std::net::Ipv4Addr {
80        std::net::Ipv4Addr::from(self.source_ip)
81    }
82
83    /// Convert destination IP to a standard IPv4 address.
84    pub fn dest_addr(&self) -> std::net::Ipv4Addr {
85        std::net::Ipv4Addr::from(self.dest_ip)
86    }
87
88    /// Timestamp as a `std::time::Duration` since boot (CLOCK_MONOTONIC).
89    pub fn duration_since_boot(&self) -> Duration {
90        Duration::from_nanos(self.timestamp_ns)
91    }
92}
93
94/// XDP timestamp collector.
95///
96/// Manages the lifecycle of the XDP program and provides access to captured
97/// NTP packet timestamps via synchronous polling.
98///
99/// ## Ownership model
100///
101/// The `Bpf` object owns the loaded programs and maps. We keep it alive for
102/// the duration of the attachment. The XDP program is accessed via mutable
103/// references obtained from `Bpf::program_mut()` as needed (detach),
104/// rather than storing a long-lived reference.
105pub struct NtpXdpTimestamp {
106    /// The loaded BPF object — must stay alive while the XDP program is loaded.
107    bpf: Option<Bpf>,
108    /// The link ID returned by attach, needed for detach.
109    link_id: Option<XdpLinkId>,
110    /// The network interface the program is attached to.
111    interface: String,
112}
113
114impl NtpXdpTimestamp {
115    /// Load and attach the XDP program to a network interface.
116    pub fn attach(interface: &str) -> Result<Self, XdpError> {
117        let bpf_elf_path = env!("XDP_BPF_ELF");
118
119        let mut bpf = Bpf::load_file(bpf_elf_path).map_err(XdpError::BpfLoad)?;
120
121        let xdp_prog: &mut Xdp = bpf
122            .program_mut("ntp_timestamp")
123            .ok_or(XdpError::ProgramNotFound)?
124            .try_into()
125            .map_err(|e| XdpError::XdpAttach(format!("Failed to get XDP program: {}", e)))?;
126
127        xdp_prog
128            .load()
129            .map_err(|e| XdpError::XdpAttach(format!("Failed to load XDP program: {}", e)))?;
130
131        let link_id = xdp_prog
132            .attach(interface, XdpFlags::default())
133            .map_err(|e| {
134                XdpError::XdpAttach(format!(
135                    "Failed to attach XDP to '{}': {}. \
136                     Try SKB mode (generic) or ensure the interface supports native XDP.",
137                    interface, e
138                ))
139            })?;
140
141        tracing::info!("XDP program 'ntp_timestamp' attached to '{}'", interface);
142
143        Ok(Self {
144            bpf: Some(bpf),
145            link_id: Some(link_id),
146            interface: interface.to_string(),
147        })
148    }
149
150    /// Detach the XDP program from the interface.
151    pub fn detach(&mut self) -> Result<(), XdpError> {
152        if let Some(link_id) = self.link_id.take() {
153            if let Some(ref mut bpf) = self.bpf {
154                if let Some(prog) = bpf.program_mut("ntp_timestamp") {
155                    let xdp_prog: Result<&mut Xdp, _> = prog.try_into();
156                    if let Ok(xdp) = xdp_prog {
157                        xdp.detach(link_id).map_err(|e| {
158                            XdpError::XdpDetach(format!(
159                                "Failed to detach XDP from '{}': {}",
160                                self.interface, e
161                            ))
162                        })?;
163                    }
164                }
165            }
166            tracing::info!("XDP program detached from '{}'", self.interface);
167        }
168
169        // Drop the BPF object to unload the program from the kernel.
170        self.bpf.take();
171
172        Ok(())
173    }
174
175    /// Return the interface name this XDP program is attached to.
176    pub fn interface(&self) -> &str {
177        &self.interface
178    }
179
180    /// Whether the XDP program is currently attached.
181    pub fn is_attached(&self) -> bool {
182        self.link_id.is_some()
183    }
184
185    /// Read all available timestamp events from the perf event buffers.
186    ///
187    /// This performs a synchronous, non-blocking poll of all per-CPU perf
188    /// event buffers. Opens buffers fresh each time to avoid storing
189    /// complex generic types on the struct.
190    pub fn read_timestamps(&mut self) -> Vec<NtpTimestampEvent> {
191        let bpf = match self.bpf.as_mut() {
192            Some(b) => b,
193            None => return Vec::new(),
194        };
195
196        let map = match bpf.map_mut("NTP_TIMESTAMPS") {
197            Some(m) => m,
198            None => {
199                tracing::warn!("Map 'NTP_TIMESTAMPS' not found");
200                return Vec::new();
201            }
202        };
203
204        let mut perf_array = match PerfEventArray::try_from(map) {
205            Ok(a) => a,
206            Err(e) => {
207                tracing::warn!("Failed to create PerfEventArray: {}", e);
208                return Vec::new();
209            }
210        };
211
212        let cpus = match online_cpus() {
213            Ok(c) => c,
214            Err(e) => {
215                tracing::warn!("Failed to get online CPUs: {}", e);
216                return Vec::new();
217            }
218        };
219
220        let mut events = Vec::with_capacity(64);
221        let event_size = std::mem::size_of::<NtpTimestampEvent>();
222
223        for cpu_id in &cpus {
224            let mut buffer = match perf_array.open(*cpu_id, None) {
225                Ok(buf) => buf,
226                Err(e) => {
227                    tracing::debug!("Failed to open perf buffer for CPU {}: {}", cpu_id, e);
228                    continue;
229                }
230            };
231
232            if !buffer.readable() {
233                continue;
234            }
235
236            let mut out_bufs = [BytesMut::with_capacity(4096)];
237
238            match buffer.read_events(&mut out_bufs) {
239                Ok(result) => {
240                    for buf in &out_bufs {
241                        for chunk in buf.chunks(event_size) {
242                            if chunk.len() >= event_size {
243                                let event: NtpTimestampEvent = unsafe {
244                                    core::ptr::read(chunk.as_ptr() as *const NtpTimestampEvent)
245                                };
246                                events.push(event);
247                            }
248                        }
249                    }
250                    if result.lost > 0 {
251                        tracing::warn!(
252                            "XDP perf buffer on CPU {}: {} events lost (overflow)",
253                            cpu_id,
254                            result.lost
255                        );
256                    }
257                }
258                Err(e) => {
259                    tracing::warn!("XDP perf event read error on CPU {}: {}", cpu_id, e);
260                }
261            }
262        }
263
264        events
265    }
266}
267
268impl Drop for NtpXdpTimestamp {
269    fn drop(&mut self) {
270        let _ = self.detach();
271    }
272}
273
274// ──── Integration Helpers ───────────────────────────────────────────────────
275
276/// Convert an XDP timestamp (CLOCK_MONOTONIC nanoseconds) to an NTP timestamp.
277pub fn xdp_timestamp_to_ntp(
278    xdp_ns: u64,
279    _realtime_ntp_ts: NtpTs64,
280    monotonic_ns_at_reference: u64,
281) -> NtpTs64 {
282    let elapsed_ns = xdp_ns.saturating_sub(monotonic_ns_at_reference);
283    let elapsed_secs = (elapsed_ns as f64) / 1_000_000_000.0;
284    ntpsec_rs_core::ntp_fp::ts_to_ntp(
285        elapsed_secs as i64,
286        ((elapsed_secs.fract() * 1_000_000_000.0) as i64).abs(),
287    )
288}
289
290/// Snapshot the offset between CLOCK_MONOTONIC and CLOCK_REALTIME.
291pub fn clock_offset_snapshot() -> Result<(u64, u64), XdpError> {
292    let mut mono_ts = libc::timespec {
293        tv_sec: 0,
294        tv_nsec: 0,
295    };
296    let mut real_ts = libc::timespec {
297        tv_sec: 0,
298        tv_nsec: 0,
299    };
300
301    let ret = unsafe { libc::clock_gettime(libc::CLOCK_MONOTONIC, &mut mono_ts) };
302    if ret != 0 {
303        return Err(XdpError::PerfEvent(
304            "clock_gettime(CLOCK_MONOTONIC) failed".to_string(),
305        ));
306    }
307
308    let ret = unsafe { libc::clock_gettime(libc::CLOCK_REALTIME, &mut real_ts) };
309    if ret != 0 {
310        return Err(XdpError::PerfEvent(
311            "clock_gettime(CLOCK_REALTIME) failed".to_string(),
312        ));
313    }
314
315    let mono_ns = (mono_ts.tv_sec as u64) * 1_000_000_000 + (mono_ts.tv_nsec as u64);
316    let real_ns = (real_ts.tv_sec as u64) * 1_000_000_000 + (real_ts.tv_nsec as u64);
317
318    Ok((mono_ns, real_ns))
319}
320
321/// A running XDP timestamp collector, ready for daemon integration.
322pub struct XdpCollector {
323    inner: NtpXdpTimestamp,
324    mono_ns_at_ref: u64,
325    real_ns_at_ref: u64,
326}
327
328impl XdpCollector {
329    /// Create and start a new XDP collector on the given interface.
330    pub fn start(interface: &str) -> Result<Self, XdpError> {
331        let inner = NtpXdpTimestamp::attach(interface)?;
332        let (mono_ns_at_ref, real_ns_at_ref) = clock_offset_snapshot()?;
333
334        Ok(Self {
335            inner,
336            mono_ns_at_ref,
337            real_ns_at_ref,
338        })
339    }
340
341    /// Poll for the next batch of timestamp events.
342    pub fn poll(&mut self) -> Vec<NtpTimestampEvent> {
343        self.inner.read_timestamps()
344    }
345
346    /// Stop the collector and detach the XDP program.
347    pub fn stop(&mut self) -> Result<(), XdpError> {
348        self.inner.detach()
349    }
350
351    /// Get the interface name.
352    pub fn interface(&self) -> &str {
353        self.inner.interface()
354    }
355
356    /// Whether the collector is active.
357    pub fn is_active(&self) -> bool {
358        self.inner.is_attached()
359    }
360
361    /// Reference CLOCK_MONOTONIC nanosecond timestamp (taken at attach time).
362    pub fn mono_ns_at_ref(&self) -> u64 {
363        self.mono_ns_at_ref
364    }
365
366    /// Reference CLOCK_REALTIME nanosecond timestamp (taken at attach time).
367    pub fn real_ns_at_ref(&self) -> u64 {
368        self.real_ns_at_ref
369    }
370}
371
372// ──── Tests ─────────────────────────────────────────────────────────────────
373
374#[cfg(test)]
375mod tests {
376    use super::*;
377
378    #[test]
379    fn test_ntp_timestamp_event_size() {
380        assert_eq!(
381            std::mem::size_of::<NtpTimestampEvent>(),
382            32,
383            "NtpTimestampEvent must be 32 bytes"
384        );
385    }
386
387    #[test]
388    fn test_ntp_timestamp_event_addr_conversion() {
389        let event = NtpTimestampEvent {
390            source_ip: [192, 168, 1, 1],
391            dest_ip: [10, 0, 0, 1],
392            timestamp_ns: 1_000_000_000,
393            src_port: 123,
394            dst_port: 45678,
395            pkt_len: 48,
396            _padding: [0u8; 4],
397        };
398
399        assert_eq!(event.source_addr(), std::net::Ipv4Addr::new(192, 168, 1, 1));
400        assert_eq!(event.dest_addr(), std::net::Ipv4Addr::new(10, 0, 0, 1));
401        assert_eq!(event.duration_since_boot(), Duration::from_secs(1));
402    }
403
404    #[test]
405    fn test_xdp_error_display() {
406        let err = XdpError::Interface("eth0 not found".to_string());
407        assert!(err.to_string().contains("eth0"));
408    }
409
410    #[test]
411    fn test_xdp_timestamp_to_ntp() {
412        let xdp_ns = 5_000_000_000;
413        let ref_ns = 1_000_000_000;
414        let result = xdp_timestamp_to_ntp(
415            xdp_ns,
416            NtpTs64 {
417                seconds: 0,
418                fraction: 0,
419            },
420            ref_ns,
421        );
422        // 5 seconds XDP - 1 second ref = 4 seconds offset, plus NTP epoch (2208988800)
423        assert!(result.seconds >= 2208988800);
424        assert_eq!(result.seconds, 2208988804);
425    }
426}