aya/aya/BREAKING-CHANGES.md

Breaking Changes

This document contains a list of breaking changes in each version and some notes to help migrate between versions. It is compiled manually from the commit history and changelog. We also tag PRs on github with a breaking change label.

Summary

• v0.12.0
  • In aya::Bpf::programs, name uses the function name from the ELF file.
  • Maps API has been reworked.
  • aya::ProgramFd trait has been removed.
  • aya::BpfLoader::set_global signature has changed.
  • MSRV has been bumped to 1.66.0.
  • BTF types have moved to the aya-obj crate.
  • aya::PerfEvent::attach and detach signatures have changed.

v0.12.0

In aya::Bpf::programs, name uses the function name from the ELF file

In previous versions, the name parameter of aya::Bpf::programs was derived from the ELF section name. If you were using aya-bpf, this was sensible since our macros took care of appending the function name to the section name, resulting in a section name like kprobe/my_function. However, loading this program using libbpf > 1.0 would fail due the section name not following the newly enforced naming convention.

Likewise, loading eBPF programs written in C using Aya was also problematic. Given the following C program:

SEC("kprobe")
int my_function(struct pt_regs *ctx) {
    return 0;
}

Loading this program using Aya would require the following:

let bpf = Bpf::load(&program)?;
let my_function = bpf.program("kprobe")?;

This was not intuitive and was a frequent source of confusion.

To solve this, Aya was changed to resolve function names from the ELF files symbol table. Therefore, if your function is defined as:

#[kprobe]
fn my_function(_ctx: KprobeContext) -> i32 {
    0
}

Or in C:

SEC("kprobe")
int my_function(struct pt_regs *ctx) {
    return 0;
}

Then you should load it using:

let bpf = Bpf::load(&program)?;
let my_function = bpf.program("my_function")?;

Migration is straightforward. Simply replace the name parameter in Bpf::programs with the function name from the ELF file.

If you are using aya-bpf, you should update to the latest (git) version and recompile your programs. The name argument inside our macros has been deprecated and should therefore be removed.

Given the following:

#[kprobe(name="another_name")]
fn some_name(_ctx: KprobeContext) -> i32 {
    0
}

You would update it to:

#[kprobe]
fn another_name(_ctx: KprobeContext) -> i32 {
    0
}

Note here that changing the exported function name is not supported anymore.

Maps API has been reworked

In v0.11.0 and earlier aya::Bpf::map_mut and aya::Bpf::map were used to access maps. These functions returned a Result that contained a MapRef or MapRefMut respectively.

Since the OwnedFd and BorrowedFd types were added to the Rust standard library, we've been able to better reason around File descriptor ownership and therefore the MapRef and MapRefMut types have been removed.

These APIs now return Option<&Map> or Option<&mut Map> respectively. Additionally a new aya::Bpf::take_map method has been added to take ownership of a map - a common requirement when working with maps using async.

aya::ProgramFd trait has been removed

The ProgramFd trait has been removed. This trait was used to provide a means of retrieving the file descriptor of a program. As with the maps API, the OwnedFd and BorrowedFd types have made this trait redundant.

To migrate, you can remove any imports of the ProgramFd trait from your code since aya::Bpf::program::fd() is available to retrieve the file descriptor. The fd() method returns an Result<ProgramFd, ProgramError>, which differs from the previous API that returned an Option so you will now have the ability to handle errors more effectively.

aya::BpfLoader::set_global signature has changed

The value in set_global was previously required to implement aya::Pod. The constraint has now been changed to be Into<aya::GlobalData> which includes both aya::Pod types and slices of aya::Pod types.

Additionally, a new argument must_exist has been added. If the must_exist argument is true, BpfLoader::load will fail with aya::ParseError::SymbolNotFound if the loaded object code does not contain the variable.

MSRV has been bumped to 1.66.0

The minimum supported Rust version has been bumped to 1.66.0. This is due to the use of the std::os::fd module which was stabilized in this version.

To migrate you will need to ensure that you are using rustc 1.66.0 or later.

BTF types have moved to the aya-obj crate

The BTF types have been moved to the aya-obj crate. This is to allow the BTF and ELF parsing code to be used independently of aya.

To migrate, if you were using aya::Btf::from_sys_fs or aya::Btf::parse_file, you should use aya_obj::Btf::from_sys_fs or aya_obj::Btf::parse_file.

aya::PerfEvent::attach and detach signatures have changed

The attach method has been changed to take an additional boolean argument called inherit. Where the scope argument determines which processes are sampled, if inherit is true, any new processes spawned by those processes will also automatically get sampled.

Also of note is that both attach and detach deal with a new type called PerfEventLinkId where previously they used PerfEventId. This change was required to support the more modern attachment method for perf event programs.