xdp_socket/lib.rs
1//!
2//! # xdp-socket
3//!
4//! A minimal and efficient Rust implementation of AF_XDP sockets for high-performance
5//! packet processing. This crate provides a low-level, transparent API to interact with
6//! XDP sockets, enabling direct, zero-copy access to network interfaces for both transmit
7//! and receive operations.
8//!
9//! ## Features
10//!
11//! - Simple and flexible API for AF_XDP sockets
12//! - Support for both TX and RX directions
13//! - UMEM management and ring buffer handling
14//! - Utilities for polling, sending, and kernel wakeup
15//! - Designed for integration with async runtimes or custom event loops
16//!
17//! This crate is intended for developers building fast packet processing applications or
18//! custom networking stacks in Rust.
19//!
20//! ## Main Components
21//!
22//! - [`Socket`]: The main type representing an AF_XDP socket, parameterized by direction
23//! (TX or RX). Provides methods for sending, receiving, and managing descriptors.
24//! - [`UMEM`]: User memory region for zero-copy packet buffers, shared with the kernel.
25//! - Ring Buffers: Fill, Completion, TX, and RX rings for packet flow control and
26//! synchronization with the kernel.
27//! - [`PollWaitExt`]: Trait for blocking until the socket is ready for I/O.
28//! - [`SendExt`]: Trait for high-level, ergonomic packet sending on transmit sockets.
29//!
30//! ## Descriptor Flow: seek → peek → commit → kick
31//!
32//! The typical workflow for both sending and receiving packets involves the following steps:
33//!
34//! 1. **seek**: Reserve one or more descriptors in the ring buffer, ensuring space for
35//! packet data.
36//! 2. **peek**: Access the reserved UMEM region for reading (RX) or writing (TX) packet data.
37//! 3. **commit**: Mark the descriptor as ready for the kernel (TX) or for user processing (RX).
38//! 4. **kick**: Notify the kernel to process the descriptors if the ring requires wakeup.
39//!
40//! This flow enables efficient, lock-free packet exchange between user space and the kernel,
41//! minimizing syscalls and maximizing throughput. For TX, you write data after seek/peek,
42//! then commit and kick. For RX, you seek/peek to fetch data, then commit to release the
43//! descriptor back to the kernel.
44//!
45
46// Public modules and re-exports
47pub mod create;
48pub mod mmap;
49pub mod ring;
50pub mod socket;
51
52pub use create::{
53 Direction, XdpConfig, create_bi_socket, create_rx_socket, create_socket, create_tx_socket,
54};
55pub use socket::Socket;
56
57// Internal modules, hidden from documentation
58#[doc(hidden)]
59pub mod commit;
60#[doc(hidden)]
61pub mod kick;
62pub mod peek;
63pub mod poll;
64#[doc(hidden)]
65pub mod seek;
66#[doc(hidden)]
67pub mod send;
68
69pub use {poll::PollWaitExt, send::SendExt};