laminar_core/xdp/
mod.rs

1//! # XDP/eBPF Network Optimization (F072)
2//!
3//! Implements XDP (eXpress Data Path) integration for wire-speed packet filtering
4//! and CPU steering. XDP processes packets at the NIC driver level before kernel
5//! networking stack allocation.
6//!
7//! ## Performance
8//!
9//! | Processing Level | Packets/sec/core | Latency |
10//! |------------------|------------------|---------|
11//! | Application (userspace) | ~1M | ~50μs |
12//! | Kernel network stack | ~5M | ~10μs |
13//! | **XDP (driver level)** | **26M** | **<1μs** |
14//!
15//! ## Use Cases
16//!
17//! - Invalid packet filtering (`XDP_DROP`)
18//! - Protocol validation (`XDP_DROP`/`XDP_PASS`)
19//! - Core routing by partition key (`XDP_REDIRECT`)
20//! - Denial-of-service mitigation (wire-speed filtering)
21//!
22//! ## Platform Support
23//!
24//! - Linux 4.15+: XDP generic (SKB mode)
25//! - Linux 5.3+: XDP native (driver mode)
26//! - Windows/macOS: Not supported (graceful fallback)
27//!
28//! ## Example
29//!
30//! ```rust,ignore
31//! use laminar_core::xdp::{XdpConfig, XdpLoader, XdpStats};
32//!
33//! // Configure XDP (Linux only)
34//! let config = XdpConfig {
35//!     enabled: true,
36//!     bpf_object_path: PathBuf::from("/usr/share/laminardb/laminar_xdp.o"),
37//!     interface: "eth0".to_string(),
38//!     port: 9999,
39//! };
40//!
41//! // Load and attach (returns fallback stub on non-Linux)
42//! let loader = XdpLoader::load_and_attach(&config, 4)?;
43//!
44//! // Get statistics
45//! let stats = loader.stats()?;
46//! println!("Redirected: {}", stats.redirected);
47//! ```
48
49mod config;
50mod error;
51mod header;
52#[cfg(target_os = "linux")]
53mod loader_linux;
54#[cfg(not(target_os = "linux"))]
55mod loader_stub;
56mod stats;
57
58pub use config::XdpConfig;
59pub use error::XdpError;
60pub use header::LaminarHeader;
61pub use stats::XdpStats;
62
63#[cfg(target_os = "linux")]
64pub use loader_linux::XdpLoader;
65
66#[cfg(not(target_os = "linux"))]
67pub use loader_stub::XdpLoader;
68
69/// XDP action types (mirrors kernel definitions).
70#[derive(Debug, Clone, Copy, PartialEq, Eq)]
71#[repr(u32)]
72pub enum XdpAction {
73    /// Abort processing (kernel error path)
74    Aborted = 0,
75    /// Drop the packet
76    Drop = 1,
77    /// Pass to kernel network stack
78    Pass = 2,
79    /// Send back out the same interface
80    Tx = 3,
81    /// Redirect to another interface/CPU
82    Redirect = 4,
83}
84
85impl From<u32> for XdpAction {
86    fn from(value: u32) -> Self {
87        match value {
88            1 => XdpAction::Drop,
89            2 => XdpAction::Pass,
90            3 => XdpAction::Tx,
91            4 => XdpAction::Redirect,
92            // 0 and any unknown value map to Aborted
93            _ => XdpAction::Aborted,
94        }
95    }
96}
97
98/// XDP attach mode.
99#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
100pub enum XdpAttachMode {
101    /// Auto-detect best mode
102    #[default]
103    Auto,
104    /// Generic mode (SKB, works on all interfaces)
105    Generic,
106    /// Native mode (driver support required, best performance)
107    Native,
108    /// Offload mode (NIC hardware, requires specific NICs)
109    Offload,
110}
111
112#[cfg(test)]
113mod tests {
114    use super::*;
115
116    #[test]
117    fn test_xdp_action_from_u32() {
118        assert_eq!(XdpAction::from(0), XdpAction::Aborted); // 0 maps to Aborted
119        assert_eq!(XdpAction::from(1), XdpAction::Drop);
120        assert_eq!(XdpAction::from(2), XdpAction::Pass);
121        assert_eq!(XdpAction::from(3), XdpAction::Tx);
122        assert_eq!(XdpAction::from(4), XdpAction::Redirect);
123        assert_eq!(XdpAction::from(99), XdpAction::Aborted); // Unknown maps to Aborted
124    }
125
126    #[test]
127    fn test_attach_mode_default() {
128        assert_eq!(XdpAttachMode::default(), XdpAttachMode::Auto);
129    }
130}
laminar_core/xdp/mod.rs

laminar_core/xdp/
mod.rs
