Merge pull request #892 from dave-tucker/breaking-changes-v2

docs(aya): Document more breaking changes

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<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.