This section describes how to build Android kernel ABI representations and run
ABI monitoring. It is applicable to Android 14 and
higher. For older versions, please refer to
Older kernel versions
.
Also see the reference documentation for Kleaf:
Support ABI monitoring (GKI)
and
Support ABI monitoring (Device)
.
Build the kernel and its ABI representation
After
downloading GKI sources
run the following command to build the GKI kernel and ABI artifacts:
tools/bazel run //common:kernel_aarch64_abi_dist
This command builds current ABI representation and copies it to
out_abi/kernel_aarch64/dist/abi.stg
along with the built kernel and modules.
You can specify extra arguments for the ABI tooling at the end of the command
after
--
. For example to change destination for ABI and build artifacts, you
can use
--dist_dir
option:
tools/bazel run //common:kernel_aarch64_abi_dist -- --dist_dir=out/dist
Analyze the ABI differences between the build and a reference representation
The
//common:kernel_aarch64_abi_dist
target, executed in the command above,
analyzes and reports any ABI differences found between the build and reference
representation located at
common/android/abi_gki_aarch64.stg
(defined in
BUILD.bazel
).
These differences will be printed out at the end of the build, as shown in the
following example:
INFO: From [stg] Comparing Kernel ABI @//common:kernel_aarch64_abi_diff:
INFO: ABI DIFFERENCES HAVE BEEN DETECTED!
The printed report comes from the build artifact located at
out_abi/kernel_aarch64/dist/abi_stgdiff/abi.report.short
along with reports in
other formats.
Automation should use the build command's exit code, which will be non-zero if
differences are found.
Please note that
development phase
branches, including
android-mainline
, have no reference ABI representation.
Without it,
//common:kernel_aarch64_abi_dist
will not detect any differences.
Update the reference ABI representation
Any change that affects the kernel ABI, such as a
symbol list update
,
needs to be reflected in the reference ABI representation
(
common/android/abi_gki_aarch64.stg
, defined in
BUILD.bazel
).
To do so you need to run the following command:
??tools/bazel run //common:kernel_aarch64_abi_update
This command performs everything in the step
Analyze the ABI differences
and additionally updates the
reference representation in the sources. The updated ABI can then be uploaded in
the same commit as the change. Please include the ABI differences from the
report in
$DIST_DIR/abi.report.short
in the commit message.
ABI monitoring and device targets
ABI monitoring only needs to be configured for core kernel build targets. Mixed
build configurations (ones that define
base_kernel
) that compile directly with
the GKI kernel
only need to
add support for tracking the device symbol list
.
The ABI definition
should
be updated using the GKI build.
Also see reference documentation for Kleaf:
Support ABI monitoring (Device)
.
Older kernel versions
Android?13
The build instructions are mostly the same as
Android 14 except that the ABI format is XML and
the reference ABI representation is
common/android/abi_gki_aarch64.xml
.
Android?12 and lower
As in Android 13, the ABI format is XML.
Older kernels use
build.sh
instead of Kleaf. For ABI monitoring you should use
build_abi.sh
, which accepts the same environment variables to customize the
build as
build.sh
. For example:
BUILD_CONFIG=common/build.config.gki.aarch64 build/build_abi.sh
This builds the kernel and extracts the ABI representation into the
OUT_DIR
(which is
out_abi
by default) subdirectory and is equivalent to the
//common:kernel_aarch64_abi_dist
target of Kleaf (see
Build kernel and ABI artifacts
).
The reference ABI representation is stored in
android/abi_gki_aarch64.xml
as
defined by the
ABI_DEFINITION
variable in
common/build.config.gki.aarch64
.
If you need to update the kernel ABI representation, the most convenient way is
to use
--update
and
--print-report
options:
BUILD_CONFIG=common/build.config.gki.aarch64 build/build_abi.sh --update --print-report
The
--print-report
prints the ABI differences between the file as it exists
and a newly-generated ABI.
The
--update
option overwrites the reference ABI representation. It also does
the
symbol list update
when using
BUILD_CONFIG
for a device with
KMI_SYMBOL_LIST
configured.