blob: 967eb2acdf9dafb574992a0f215be019449ff739 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
|
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.
|
