libbpf_rs/lib.rs
1//! # libbpf-rs
2//!
3//! `libbpf-rs` is a safe, idiomatic, and opinionated wrapper around
4//! [libbpf](https://github.com/libbpf/libbpf/).
5//!
6//! libbpf-rs, together with `libbpf-cargo` (libbpf cargo plugin) allow you
7//! to write Compile-Once-Run-Everywhere (CO-RE) eBPF programs. Note this document
8//! uses "eBPF" and "BPF" interchangeably.
9//!
10//! More information about CO-RE is [available
11//! here](https://facebookmicrosites.github.io/bpf/blog/2020/02/19/bpf-portability-and-co-re.html).
12//!
13//! ## High level workflow
14//!
15//! 1. Create new rust project (via `cargo new` or similar) at path `$PROJ_PATH`
16//! 2. Create directory `$PROJ_PATH/src/bpf`
17//! 3. Write CO-RE bpf code in `$PROJ_PATH/src/bpf/${MYFILE}.bpf.c`, where `$MYFILE` may be any
18//! valid filename. Note the `.bpf.c` extension is required.
19//! 4. Create a [build script](https://doc.rust-lang.org/cargo/reference/build-scripts.html) that
20//! builds and generates a skeleton module using `libbpf_cargo::SkeletonBuilder`
21//! 5. Write your userspace code by importing and using the generated module. Import the
22//! module by using the [path
23//! attribute](https://doc.rust-lang.org/reference/items/modules.html#the-path-attribute).
24//! Your userspace code goes in `$PROJ_PATH/src/` as it would in a normal rust project.
25//! 6. Continue regular rust workflow (ie `cargo build`, `cargo run`, etc)
26//!
27//! ## Alternate workflow
28//!
29//! While using the skeleton is recommended, it is also possible to directly use libbpf-rs.
30//!
31//! 1. Follow steps 1-3 of "High level workflow"
32//! 2. Generate a BPF object file. Options include manually invoking `clang`, creating a build
33//! script to invoke `clang`, or using `libbpf-cargo` cargo plugins.
34//! 3. Write your userspace code in `$PROJ_PATH/src/` as you would a normal rust project and point
35//! libbpf-rs at your BPF object file
36//! 4. Continue regular rust workflow (ie `cargo build`, `cargo run`, etc)
37//!
38//! ## Design
39//!
40//! libbpf-rs models various "phases":
41//! ```text
42//! from_*() load()
43//! | |
44//! v v
45//! ObjectBuilder -> OpenObject -> Object
46//! ^ ^
47//! | |
48//! <pre-load modifications> |
49//! |
50//! <post-load interactions>
51//! ```
52//!
53//! The entry point into libbpf-rs is [`ObjectBuilder`]. `ObjectBuilder` helps open the BPF object
54//! file. After the object file is opened, you are returned an [`OpenObject`] where you can
55//! perform all your pre-load operations. Pre-load means before any BPF maps are created or BPF
56//! programs are loaded and verified by the kernel. Finally, after the BPF object is loaded, you
57//! are returned an [`Object`] instance where you can read/write to BPF maps, attach BPF programs
58//! to hooks, etc.
59//!
60//! You _must_ keep the [`Object`] alive the entire duration you interact with anything inside the
61//! BPF object it represents. This is further documented in [`Object`] documentation.
62//!
63//! ## Example
64//!
65//! This is probably the best way to understand how libbpf-rs and libbpf-cargo work together.
66//!
67//! [See example here](https://github.com/libbpf/libbpf-rs/tree/master/examples/runqslower).
68//!
69//! ## API coverage
70//!
71//! `libbpf-rs` is a curated, high-level wrapper of `libbpf` rather than
72//! a one-to-one binding: it exposes safe, idiomatic equivalents instead
73//! of every `libbpf` symbol. Here is a rough overview of currently
74//! captured functionality:
75//!
76//! | Capability | Status |
77//! |----------------------------------------------------------------------|---------------------------------|
78//! | Object open/load/close; map & program iteration | ✅ |
79//! | Program attach: kprobe, uprobe, tracepoint, USDT, perf, cgroup, … | ✅ |
80//! | Map access: lookup/update/delete, batched ops, pinning, `struct_ops` | ✅ |
81//! | Links; TC; XDP; netfilter; object/map/program/link query & info | ✅ |
82//! | Ring buffer, user ring buffer, perf buffer | ✅ |
83//! | Feature probing; BPF object linking ([`Linker`]) | ✅ |
84//! | BTF ([`Btf`]) | ◐ introspection only |
85//! | Program attach: `freplace`, `tcx`, `netkit` | ❌ |
86//! | Object-level bulk pin/unpin (per-map/program pinning *is* supported) | ❌ |
87//! | Low-level `bpf()` syscalls (`bpf_prog_load`, `bpf_link_create`, …) | ❌ superseded by the object API |
88//! | BPF token, light-skeleton loader, subskeletons, func/line info | ❌ |
89//!
90//! Refer to [`tests/test_api_coverage.rs`] for the exhaustive list of
91//! wrapped symbols.
92//!
93//! [`tests/test_api_coverage.rs`]: https://github.com/libbpf/libbpf-rs/blob/master/libbpf-rs/tests/test_api_coverage.rs
94
95pub mod btf;
96mod error;
97mod iter;
98mod link;
99mod linker;
100mod map;
101mod netfilter;
102mod object;
103mod perf_buffer;
104mod print;
105mod program;
106pub mod query;
107mod ringbuf;
108mod skeleton;
109mod streams;
110mod tc;
111mod tracepoint;
112mod user_ringbuf;
113mod util;
114mod xdp;
115
116pub use libbpf_sys;
117
118pub use crate::btf::Btf;
119pub use crate::btf::HasSize;
120pub use crate::btf::ReferencesType;
121pub use crate::error::Error;
122pub use crate::error::ErrorExt;
123pub use crate::error::ErrorKind;
124pub use crate::error::Result;
125pub use crate::iter::Iter;
126pub use crate::link::Link;
127pub use crate::linker::Linker;
128pub use crate::map::BatchedMapIter;
129pub use crate::map::Map;
130pub use crate::map::MapCore;
131pub use crate::map::MapFdInfo;
132pub use crate::map::MapFlags;
133pub use crate::map::MapHandle;
134pub use crate::map::MapImpl;
135pub use crate::map::MapInfo;
136pub use crate::map::MapKeyIter;
137pub use crate::map::MapMut;
138pub use crate::map::MapType;
139pub use crate::map::OpenMap;
140pub use crate::map::OpenMapImpl;
141pub use crate::map::OpenMapMut;
142pub use crate::netfilter::NetfilterOpts;
143pub use crate::netfilter::NFPROTO_IPV4;
144pub use crate::netfilter::NFPROTO_IPV6;
145pub use crate::netfilter::NF_INET_FORWARD;
146pub use crate::netfilter::NF_INET_LOCAL_IN;
147pub use crate::netfilter::NF_INET_LOCAL_OUT;
148pub use crate::netfilter::NF_INET_POST_ROUTING;
149pub use crate::netfilter::NF_INET_PRE_ROUTING;
150pub use crate::object::AsRawLibbpf;
151pub use crate::object::MapIter;
152pub use crate::object::Object;
153pub use crate::object::ObjectBuilder;
154pub use crate::object::OpenObject;
155pub use crate::object::ProgIter;
156pub use crate::perf_buffer::PerfBuffer;
157pub use crate::perf_buffer::PerfBufferBuilder;
158pub use crate::print::get_print;
159pub use crate::print::set_print;
160pub use crate::print::PrintCallback;
161pub use crate::print::PrintLevel;
162pub use crate::program::CgroupIterOpts;
163pub use crate::program::CgroupIterOrder;
164pub use crate::program::Input as ProgramInput;
165pub use crate::program::IterOpts;
166pub use crate::program::KprobeMultiOpts;
167pub use crate::program::KprobeOpts;
168pub use crate::program::MapIterOpts;
169pub use crate::program::OpenProgram;
170pub use crate::program::OpenProgramImpl;
171pub use crate::program::OpenProgramMut;
172pub use crate::program::Output as ProgramOutput;
173pub use crate::program::PerfEventOpts;
174pub use crate::program::Program;
175pub use crate::program::ProgramAttachType;
176pub use crate::program::ProgramHandle;
177pub use crate::program::ProgramImpl;
178pub use crate::program::ProgramMut;
179pub use crate::program::ProgramType;
180pub use crate::program::UprobeMultiOpts;
181pub use crate::program::UprobeOpts;
182pub use crate::program::UsdtOpts;
183pub use crate::ringbuf::RingBuffer;
184pub use crate::ringbuf::RingBufferBuilder;
185pub use crate::tc::TcAttachPoint;
186pub use crate::tc::TcHook;
187pub use crate::tc::TcHookBuilder;
188pub use crate::tc::TC_CUSTOM;
189pub use crate::tc::TC_EGRESS;
190pub use crate::tc::TC_H_CLSACT;
191pub use crate::tc::TC_H_INGRESS;
192pub use crate::tc::TC_H_MIN_EGRESS;
193pub use crate::tc::TC_H_MIN_INGRESS;
194pub use crate::tc::TC_INGRESS;
195pub use crate::tracepoint::RawTracepointOpts;
196pub use crate::tracepoint::TracepointCategory;
197pub use crate::tracepoint::TracepointOpts;
198pub use crate::user_ringbuf::UserRingBuffer;
199pub use crate::user_ringbuf::UserRingBufferSample;
200pub use crate::util::num_possible_cpus;
201pub use crate::xdp::Xdp;
202pub use crate::xdp::XdpFlags;
203
204/// An unconstructible dummy type used for tagging mutable type
205/// variants.
206#[doc(hidden)]
207#[derive(Copy, Clone, Debug)]
208pub enum Mut {}
209
210
211/// Used for skeleton -- an end user may not consider this API stable
212#[doc(hidden)]
213pub mod __internal_skel {
214 pub use super::skeleton::*;
215}
216
217/// Skeleton related definitions.
218pub mod skel {
219 pub use super::skeleton::OpenSkel;
220 pub use super::skeleton::Skel;
221 pub use super::skeleton::SkelBuilder;
222}