Starting March 27, 2025, we recommend using android-latest-release instead of aosp-main to build and contribute to AOSP. For more information, see Changes to AOSP.
Maintain a stable kernel module interface
Stay organized with collections
Save and categorize content based on your preferences.
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 android14-6.1, android15-6.6 or android16-6.12.
- 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 android16-6.12
includes the toolchain, build system, and everything else required to build the
Generic Kernel Image (GKI) kernel. The build configuration, primarily
BUILD.bazel,
ensures 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,
gki/aarch64/abi.stg
for android16-6.12) 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
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-06-12 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-06-12 UTC."],[],[],null,["# Maintain a stable kernel module interface\n\nIt's critical to maintain a stable kernel module interface (KMI) for vendor\nmodules. The GKI kernel is\nbuilt and shipped in binary form and vendor-loadable modules are built in a\nseparate tree. The resulting GKI kernel and vendor modules must work as\nthough they were built together.\n\nGenerally, the Linux community has\n[frowned on the notion of in-kernel ABI\nstability](https://www.kernel.org/doc/Documentation/process/stable-api-nonsense.rst)\nfor the mainline kernel. In the face of different toolchains, configurations,\nand an ever-evolving Linux mainline kernel, it isn't feasible to maintain a\nstable KMI in mainline. However, it's possible to maintain a stable KMI in\nthe highly-constrained GKI environment with these constraints:\n\n- Only a single configuration, `gki_defconfig`, can be used to build the\n kernel.\n\n- The KMI is only stable within the same LTS and Android version of a kernel,\n such as `android14-6.1`, `android15-6.6` or `android16-6.12`.\n\n - No KMI stability is maintained for `android-mainline`.\n- Only the specific *Clang* toolchain supplied in AOSP and defined for the\n corresponding branch is used for building kernel and modules.\n\n- Only symbols known to be used by modules as specified in a symbol list are\n monitored for stability and considered KMI symbols.\n\n - 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.\n- After the KMI branch is frozen, changes are allowed but can't break the KMI.\n These changes include the following:\n\n - Config changes\n - Kernel code changes\n - Toolchain changes (including updates)\n\nUse the hermetic build process and LLVM toolchain\n-------------------------------------------------\n\nThe hermetic build process ensures a stable KMI by having `repo` manifests in\n`kernel/manifest` completely describe the build environment. For example, the\n[manifest for `android16-6.12`](https://android.googlesource.com/kernel/manifest/+/refs/heads/common-android16-6.12/default.xml)\nincludes the toolchain, build system, and everything else required to build the\nGeneric Kernel Image (GKI) kernel. The build configuration, primarily\n[`BUILD.bazel`](https://android.googlesource.com/kernel/common/+/refs/heads/android16-6.12/BUILD.bazel),\nensures that the included tools are used correctly to generate consistent build\nresults.\n\nUsing a hermetic build process also ensures that the ABI description for the\ntree is consistent whether generated by Google (for example,\n[`gki/aarch64/abi.stg`](https://android.googlesource.com/kernel/common/+/refs/heads/android16-6.12/gki/aarch64/abi.stg)\nfor `android16-6.12`) or generated in a local tree that includes the vendor\nmodules. The\n[tools to create and compare the ABI description](https://android.googlesource.com/kernel/build/+/refs/heads/main-kernel/abi/)\nfor the Kernel Module Interface (KMI) are also provided as part of the repo\ndescribed by the manifest.\n\nThe toolchain used to build the GKI kernel must be completely compatible with\nthe toolchain used to build vendor modules. As of Android\n10, all Android kernels must be built\nwith an LLVM toolchain. With GKI, the LLVM toolchain used to build product\nkernels and vendor modules must generate the same ABI as the LLVM toolchain from\nAOSP and partners must ensure that the KMI is compatible with the GKI kernel.\nUsing the provided build tools is strongly encouraged as they provide the\nbest compatibility.\n\nWhat's next?\n------------\n\n- For instructions on building the kernel using the hermetic build process and\n LLVM toolchain, refer to refer to\n [Build kernels](/docs/setup/build/building-kernels).\n\n- For instructions on how to monitor the ABI and fix issues, refer to\n [Android Kernel ABI Monitoring](/docs/core/architecture/kernel/abi-monitor)"]]
