Run ABI monitoring

This page describes how to build Android kernel ABI representations and run ABI monitoring. It's applicable to Android 14 and higher. For lower versions, 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 are 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 is non-zero if differences are found.

Note that development phase branches, including android-mainline, have no reference ABI representation. Without it, //common:kernel_aarch64_abi_dist won't 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. 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 13 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.