aya/programs/
fexit.rs

1//! Fexit programs.
2
3use aya_obj::{
4    btf::{Btf, BtfKind},
5    generated::{bpf_attach_type::BPF_TRACE_FEXIT, bpf_prog_type::BPF_PROG_TYPE_TRACING},
6};
7
8use crate::programs::{
9    FdLink, FdLinkId, ProgramData, ProgramError, ProgramType, define_link_wrapper,
10    load_program_with_attach_type, utils::attach_raw_tracepoint,
11};
12
13/// A program that can be attached to the exit point of (almost) any kernel
14/// function.
15///
16/// [`FExit`] programs are similar to [kretprobes](crate::programs::KProbe),
17/// but the difference is that fexit has practically zero overhead to call
18/// after the kernel function returns. Fexit programs can also be attached to
19/// other eBPF programs.
20///
21/// # Minimum kernel version
22///
23/// The minimum kernel version required to use this feature is 5.5.
24///
25/// # Test runs
26///
27/// [`TestRun`](crate::programs::TestRun) support for [`FExit`] programs uses
28/// the kernel's tracing `BPF_PROG_TEST_RUN` handler. That handler does not call
29/// the function passed to [`FExit::load`]. Instead, it runs the kernel's fixed
30/// `bpf_fentry_test*` sequence, so the [`FExit`] program is executed only when
31/// it is attached to one of those built-in test targets.
32/// <https://github.com/torvalds/linux/blob/v7.1-rc4/net/bpf/test_run.c#L702-L715>
33///
34/// A successful test-run syscall means the kernel sequence completed. To check
35/// that an [`FExit`] program ran, record and verify an explicit side effect such
36/// as a map update. `Ok(())` does not mean this [`FExit`] program ran.
37///
38/// # Examples
39///
40/// ```no_run
41/// # #[derive(thiserror::Error, Debug)]
42/// # enum Error {
43/// #     #[error(transparent)]
44/// #     BtfError(#[from] aya::BtfError),
45/// #     #[error(transparent)]
46/// #     Program(#[from] aya::programs::ProgramError),
47/// #     #[error(transparent)]
48/// #     Ebpf(#[from] aya::EbpfError),
49/// # }
50/// # let mut bpf = Ebpf::load_file("ebpf_programs.o")?;
51/// use aya::{Ebpf, programs::FExit, BtfError, Btf};
52///
53/// let btf = Btf::from_sys_fs()?;
54/// let program: &mut FExit = bpf.program_mut("filename_lookup").unwrap().try_into()?;
55/// program.load("filename_lookup", &btf)?;
56/// program.attach()?;
57/// # Ok::<(), Error>(())
58/// ```
59#[derive(Debug)]
60#[doc(alias = "BPF_TRACE_FEXIT")]
61#[doc(alias = "BPF_PROG_TYPE_TRACING")]
62pub struct FExit {
63    pub(crate) data: ProgramData<FExitLink>,
64}
65
66impl FExit {
67    /// The type of the program according to the kernel.
68    pub const PROGRAM_TYPE: ProgramType = ProgramType::Tracing;
69
70    /// Loads the program inside the kernel.
71    ///
72    /// Loads the program so it's executed when the kernel function `fn_name`
73    /// is exited. The `btf` argument must contain the BTF info for the running
74    /// kernel.
75    pub fn load(&mut self, fn_name: &str, btf: &Btf) -> Result<(), ProgramError> {
76        let Self { data } = self;
77        data.attach_btf_id = Some(btf.id_by_type_name_kind(fn_name, BtfKind::Func)?);
78        load_program_with_attach_type(BPF_PROG_TYPE_TRACING, BPF_TRACE_FEXIT, data)
79    }
80
81    /// Attaches the program.
82    ///
83    /// The returned value can be used to detach, see [`FExit::detach`].
84    pub fn attach(&mut self) -> Result<FExitLinkId, ProgramError> {
85        attach_raw_tracepoint(&mut self.data, None)
86    }
87}
88
89define_link_wrapper!(FExitLink, FExitLinkId, FdLink, FdLinkId, FExit);
aya/programs/fexit.rs

aya/programs/
fexit.rs
