aya_obj/
lib.rs

1//! An eBPF object file parsing library with BTF and relocation support.
2//!
3//! # Status
4//!
5//! This crate includes code that started as internal API used by
6//! the [aya] crate. It has been split out so that it can be used by
7//! other projects that deal with eBPF object files. Unless you're writing
8//! low level eBPF plumbing tools, you should not need to use this crate
9//! but see the [aya] crate instead.
10//!
11//! The API as it is today has a few rough edges and is generally not as
12//! polished nor stable as the main [aya] crate API. As always,
13//! improvements welcome!
14//!
15//! [aya]: https://github.com/aya-rs/aya
16//!
17//! # Overview
18//!
19//! eBPF programs written with [libbpf] or [aya-bpf] are usually compiled
20//! into an ELF object file, using various sections to store information
21//! about the eBPF programs.
22//!
23//! `aya-obj` is a library for parsing such eBPF object files, with BTF and
24//! relocation support.
25//!
26//! [libbpf]: https://github.com/libbpf/libbpf
27//! [aya-bpf]: https://github.com/aya-rs/aya
28//!
29//! # Example
30//!
31//! This example loads a simple eBPF program and runs it with [rbpf].
32//!
33//! ```no_run
34//! use aya_obj::{generated::bpf_insn, Object};
35//!
36//! // Parse the object file
37//! let bytes = std::fs::read("program.o").unwrap();
38//! let mut object = Object::parse(&bytes).unwrap();
39//! // Relocate the programs
40//! #[cfg(feature = "std")]
41//! let text_sections = std::collections::HashSet::new();
42//! #[cfg(not(feature = "std"))]
43//! let text_sections = hashbrown::HashSet::new();
44//! object.relocate_calls(&text_sections).unwrap();
45//! object.relocate_maps(std::iter::empty(), &text_sections).unwrap();
46//!
47//! // Run with rbpf
48//! let function = object.functions.get(&object.programs["prog_name"].function_key()).unwrap();
49//! let instructions = &function.instructions;
50//! let data = unsafe {
51//!     core::slice::from_raw_parts(
52//!         instructions.as_ptr().cast(),
53//!         instructions.len() * core::mem::size_of::<bpf_insn>(),
54//!     )
55//! };
56//! let vm = rbpf::EbpfVmNoData::new(Some(data)).unwrap();
57//! let _return = vm.execute_program().unwrap();
58//! ```
59//!
60//! [rbpf]: https://github.com/qmonnet/rbpf
61
62#![no_std]
63#![doc(
64    html_logo_url = "https://aya-rs.dev/assets/images/crabby.svg",
65    html_favicon_url = "https://aya-rs.dev/assets/images/crabby.svg"
66)]
67#![cfg_attr(docsrs, feature(doc_cfg))]
68#![deny(missing_docs)]
69#![cfg_attr(
70    any(feature = "std", test),
71    expect(unused_crate_dependencies, reason = "used in doctests")
72)]
73
74extern crate alloc;
75#[cfg(feature = "std")]
76extern crate std;
77
78pub mod btf;
79#[expect(
80    clippy::all,
81    clippy::cast_lossless,
82    clippy::ptr_as_ptr,
83    clippy::ref_as_ptr,
84    clippy::use_self,
85    missing_docs,
86    non_camel_case_types,
87    non_snake_case,
88    trivial_numeric_casts,
89    unreachable_pub,
90    unsafe_op_in_unsafe_fn
91)]
92pub mod generated;
93pub mod links;
94pub mod maps;
95pub mod obj;
96pub mod programs;
97pub mod relocation;
98mod util;
99
100pub use maps::Map;
101pub use obj::*;
102
103/// An error returned from the verifier.
104///
105/// Provides a [`Debug`] implementation that doesn't escape newlines.
106pub struct VerifierLog(alloc::string::String);
107
108impl VerifierLog {
109    /// Create a new verifier log.
110    pub fn new(log: alloc::string::String) -> Self {
111        Self(log)
112    }
113}
114
115impl core::fmt::Debug for VerifierLog {
116    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
117        let Self(log) = self;
118        f.write_str(log)
119    }
120}
121
122impl core::fmt::Display for VerifierLog {
123    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
124        <Self as core::fmt::Debug>::fmt(self, f)
125    }
126}
aya_obj/lib.rs

aya_obj/
lib.rs
