Maintain a stable kernel module interface

It's critical to maintain a stable kernel module interface (KMI) for vendor modules. The GKI kernel is built and shipped in binary form and vendor-loadable modules are built in a separate tree. The resulting GKI kernel and vendor modules must work as though they were built together.

Generally, the Linux community has frowned on the notion of in-kernel ABI stability for the mainline kernel. In the face of different toolchains, configurations, and an ever-evolving Linux mainline kernel, it isn't feasible to maintain a stable KMI in mainline. However, it's possible to maintain a stable KMI in the highly-constrained GKI environment with these constraints:

  • Only a single configuration, gki_defconfig, can be used to build the kernel.

  • The KMI is only stable within the same LTS and Android version of a kernel, such as android13-5.10, android12-5.10 or android13-5.15.

    • No KMI stability is maintained for android-mainline.

  • Only the specific Clang toolchain supplied in AOSP and defined for the corresponding branch is used for building kernel and modules.

  • Only symbols known to be used by modules as specified in a symbol list are monitored for stability and considered KMI symbols.

    • The corollary is that vendor modules must use only KMI symbols. This constraint is enforced by failing module loads if non-KMI-symbols are required.

  • After the KMI branch is frozen, changes are allowed but can't break the KMI. These changes include the following:

    • Config changes
    • Kernel code changes
    • Toolchain changes (including updates)

Use the hermetic build process and LLVM toolchain

The hermetic build process ensures a stable KMI by having repo manifests in kernel/manifest completely describe the build environment. For example, the manifest for android13-5.15 includes the toolchain, build scripts, and everything else required to build the Generic Kernel Image (GKI) kernel. The respective build.config configuration files, such as the GKI build config build.config.gki.aarch64, ensure that the included tools are used correctly to generate consistent build results.

Using a hermetic build process also ensures that the ABI description for the tree is consistent whether generated by Google (for example, abi_gki_aarch64.xml for android13-5.15) or generated in a local tree that includes the vendor modules. The tools to create and compare the ABI description for the Kernel Module Interface (KMI) are also provided as part of the repo described by the manifest.

The toolchain used to build the GKI kernel must be completely compatible with the toolchain used to build vendor modules. As of Android 10, all Android kernels must be built with an LLVM toolchain. With GKI, the LLVM toolchain used to build product kernels and vendor modules must generate the same ABI as the LLVM toolchain from AOSP and partners must ensure that the KMI is compatible with the GKI kernel. Using the provided build tools is strongly encouraged as they provide the best compatibility.

What's next?

  • For instructions on building the kernel using the hermetic build process and LLVM toolchain, refer to refer to Build kernels.

  • For instructions on how to monitor the ABI and fix issues, refer to Android Kernel ABI Monitoring