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//! let text_sections = std::collections::HashSet::new();
41//! object.relocate_calls(&text_sections).unwrap();
42//! object.relocate_maps(std::iter::empty(), &text_sections).unwrap();
43//!
44//! // Run with rbpf
45//! let function = object.functions.get(&object.programs["prog_name"].function_key()).unwrap();
46//! let instructions = &function.instructions;
47//! let data = unsafe {
48//!     core::slice::from_raw_parts(
49//!         instructions.as_ptr().cast(),
50//!         instructions.len() * core::mem::size_of::<bpf_insn>(),
51//!     )
52//! };
53//! let vm = rbpf::EbpfVmNoData::new(Some(data)).unwrap();
54//! let _return = vm.execute_program().unwrap();
55//! ```
56//!
57//! [rbpf]: https://github.com/qmonnet/rbpf
58
59#![doc(
60    html_logo_url = "https://aya-rs.dev/assets/images/crabby.svg",
61    html_favicon_url = "https://aya-rs.dev/assets/images/crabby.svg"
62)]
63#![cfg_attr(docsrs, feature(doc_cfg))]
64#![deny(missing_docs)]
65#![cfg_attr(test, expect(unused_crate_dependencies, reason = "used in doctests"))]
66
67pub mod btf;
68#[expect(
69    clippy::all,
70    clippy::as_pointer_underscore,
71    clippy::cast_lossless,
72    clippy::decimal_literal_representation,
73    clippy::missing_const_for_fn,
74    clippy::ptr_as_ptr,
75    clippy::pub_underscore_fields,
76    clippy::ref_as_ptr,
77    clippy::renamed_function_params,
78    clippy::semicolon_inside_block,
79    clippy::use_self,
80    clippy::used_underscore_binding,
81    missing_docs,
82    non_camel_case_types,
83    non_snake_case,
84    trivial_casts,
85    trivial_numeric_casts,
86    unreachable_pub,
87    unsafe_op_in_unsafe_fn,
88    unused_qualifications,
89    reason = "generated code"
90)]
91pub mod generated;
92pub mod links;
93pub mod maps;
94pub mod obj;
95pub mod programs;
96pub mod relocation;
97mod util;
98
99pub use maps::Map;
100pub use obj::*;
101
102/// An error returned from the verifier.
103///
104/// Provides a [`Debug`] implementation that doesn't escape newlines.
105pub struct VerifierLog(String);
106
107impl VerifierLog {
108    /// Create a new verifier log.
109    pub const fn new(log: String) -> Self {
110        Self(log)
111    }
112}
113
114impl core::fmt::Debug for VerifierLog {
115    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
116        let Self(log) = self;
117        f.write_str(log)
118    }
119}
120
121impl core::fmt::Display for VerifierLog {
122    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
123        <Self as core::fmt::Debug>::fmt(self, f)
124    }
125}
aya_obj/lib.rs

aya_obj/
lib.rs
