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() as *const u8,
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(clippy::all, missing_docs)]
69#![allow(clippy::missing_safety_doc, clippy::len_without_is_empty)]
70
71extern crate alloc;
72#[cfg(feature = "std")]
73extern crate std;
74#[cfg(not(feature = "std"))]
75mod std {
76    pub mod error {
77        pub use core_error::Error;
78    }
79    pub use core::*;
80
81    pub mod os {
82        pub mod fd {
83            pub type RawFd = core::ffi::c_int;
84        }
85    }
86}
87
88pub mod btf;
89pub mod generated;
90pub mod links;
91pub mod maps;
92pub mod obj;
93pub mod programs;
94pub mod relocation;
95mod util;
96
97pub use maps::Map;
98pub use obj::*;
99
100/// An error returned from the verifier.
101///
102/// Provides a [`Debug`] implementation that doesn't escape newlines.
103pub struct VerifierLog(alloc::string::String);
104
105impl VerifierLog {
106    /// Create a new verifier log.
107    pub fn new(log: alloc::string::String) -> Self {
108        Self(log)
109    }
110}
111
112impl std::fmt::Debug for VerifierLog {
113    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
114        let Self(log) = self;
115        f.write_str(log)
116    }
117}
118
119impl std::fmt::Display for VerifierLog {
120    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
121        <Self as std::fmt::Debug>::fmt(self, f)
122    }
123}
aya_obj/lib.rs

aya_obj/
lib.rs
