From 2d9d7a1a0b8fb944a9843642e85480b16c11bd11 Mon Sep 17 00:00:00 2001 From: Dave Tucker Date: Wed, 28 Feb 2024 11:11:05 +0000 Subject: [PATCH] docs(aya): Document more breaking changes Signed-off-by: Dave Tucker --- aya/BREAKING-CHANGES.md | 69 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/aya/BREAKING-CHANGES.md b/aya/BREAKING-CHANGES.md index e48c6912..bd312da1 100644 --- a/aya/BREAKING-CHANGES.md +++ b/aya/BREAKING-CHANGES.md @@ -10,6 +10,12 @@ history and changelog. We also tag PRs on github with a [breaking change] label. - [v0.12.0](#v0120) - 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 @@ -95,3 +101,66 @@ fn another_name(_ctx: KprobeContext) -> i32 { Note here that changing the exported function name is not supported anymore. [naming convention]: https://docs.kernel.org/bpf/libbpf/program_types.html + +### 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`, 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` 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.