ABI Monitoring Utilities
========================

This directory contains scripts and utilities to compare, track and mitigate
changes to the kernel ABI. The comparison framework used is
[libabigail](https://sourceware.org/libabigail/), but this might change in the
future. Follow the instructions below to set up the current prerequisites.

Set up the prerequisites
------------------------
The script `bootstrap` will ensure the following system prerequisites are
installed. At the moment, only apt based package managers are supported.
 - autoconf
 - elfutils
 - g++
 - libtool
 - libxml2-dev
 - libdw-dev
 - make
 - pkg-config
 - python3

It will then acquire the libabigail sources and build the required binaries.
At the very end the script will print instructions how to add the binaries to
the local `${PATH}` to be used by the remaining utilities.

You can skip this step if your host system provides a suitable version of the
libabigail tooling including the binaries `abidw` and `abidiff`.


Creating ABI dumps from kernel trees
------------------------------------
Provided a linux kernel tree with built vmlinux and kernel modules, the tool
`dump_abi` creates an ABI representation using the selected abi tool. As of now
there is only one option: 'libabigail' (default). A sample invocation looks as
follows:
  $ dump_abi --linux-tree path/to/out --out-file /path/to/abi.xml

To ensure a consistent environment and stable toolchain, a wrapper script is
provided at the topmost directory of this project: `build_abi.sh`. It builds
the kernel using `build.sh` and therefore accepts the same environment
variables to customize the build, such as BUILD_CONFIG, CC and the various
SKIP_* variables to speed up incremental builds. Following a successful build,
`build_abi.sh` will create an ABI dump in the DIST_DIR of the build. A sample
invocation from the top of the repo tree looks as follows:
  $ BUILD_CONFIG=path/to/build.config build/build_abi.sh

Comparing ABI dumps
-------------------
ABI dumps created by `dump_abi` can be compared with `diff_abi`. Ensure to use
the same abi-tool for `dump_abi` and `diff_abi`. A sample invocation looks as
follows:
  $ diff_abi --baseline abi1.xml --new abi2.xml --report report.out

The report created is tool specific, but generally lists ABI changes detected
that affect the Kernel's module interface.

Updating ABI dumps
------------------
To update the ABI dump, `build_abi.sh` can be invoked with the `--update` flag.
It will update the corresponding abi.xml file that is defined via the
build.config. It might be useful to invoke the script also with
`--print-report` to print the differences the update cleans up. That
information is useful in the commit message when updating the abi.xml in the
source control.