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.
Stay organized with collections
Save and categorize content based on your preferences.
This page covers how to configure a new kernel feature as a GKI module or
configure an existing built-in kernel feature as a GKI module.
Configure a new feature as a GKI module
For the new feature, edit gki_defconfig and set the required kernel
feature's config item from n to m (=m). Set this setting in both
arch/arm64/configs/gki_defconfig and arch/x86/configs/gki_defconfig.
Add the KO (.ko) files generated for the feature
to the COMMON_GKI_MODULES_LIST section of common/modules.bzl. Add the
files in a sorted order. If you're unsure of all the files generated,
the build fails and lists all the necessary KO files to be added to the list.
For Android 14, add the same set of KO files from step 2, sorted in ascending
order for binary search at runtime, to
common/android/gki_{ARCH}_protected_modules to designate the module as a
protected GKI module.
For Android 14 and 15, update the list of exports so that it includes the
newly-added exports in common/android/abi_gki_protected_exports_ARCHITECTURE. For example, to update the list, run
tools/bazel run //common:kernel_aarch64_abi_update_protected_exports for
aarch64.
Make sure newly added KO files from step 2 are copied to the kernel's
out/<androidX-Y.Z>/dist/system_dlkm.img and
out/androidX-Y.Z/dist/system_dlkm_staging_archive.tar.gz.
Modules in the system_dlkm_staging_archive.tar.gz archive can be used as
input to generate the system_dlkm.img in the platform build.
Submit your changes for review. GKI modules are an Android-only kernel
feature, so module conversion patches aren't required to be submitted
upstream. However, you must follow other guidelines to submit
Android Common Kernel (ACK) patches.
Configure a kernel built-in feature as a GKI module
For an existing built-in kernel feature, edit gki_defconfig and set the
required kernel feature's config item from y to m (=m). Set this
setting in both arch/arm64/configs/gki_defconfig and
arch/x86/configs/gki_defconfig.
Add the KO (.ko) files generated for the feature to the
COMMON_GKI_MODULES_LIST section of common/modules.bzl. Add the files
in a sorted order. If you're unsure of all the files generated,
the build fails and lists all the necessary KO files to be added to the list.
For Android 14, add the same set of KO files from step 2, sorted in ascending
order for binary search at runtime, to
common/android/gki_{ARCH}_protected_modules to designate the module as a
protected GKI module.
For Android 14 and 15, update the list of exports that are protected to
include ones from the newly added module in
common/android/abi_gki_protected_exports_{ARCH} using tools/bazel run
//common:kernel_aarch64_abi_update_protected_exports for aarch64.
Make sure newly converted module KO files from step 2 are copied to the
kernel's out/<androidX-Y.Z>/dist/system_dlkm.img and
out/androidX-Y.Z/dist/system_dlkm_staging_archive.tar.gz.
Modules in the system_dlkm_staging_archive.tar.gz archive can be used as
input to generate the system_dlkm.img in the platform build.
Submit your changes for review. GKI modules are an Android-only kernel
feature, so module conversion patches aren't required to be submitted
upstream. However, you must follow the other guidelines to submit
Android Common Kernel (ACK)
patches.
Convert a protected GKI module to unprotected
For Android 15 and higher, add the module being converted from protected to
unprotected to the COMMON_UNPROTECTED_MODULES_LIST list in
common/modules.bzl file.
For Android 14, remove the module being converted from protected to
unprotected from the list of protected modules at
common/android/gki_protected_modules.
For Android 14 and 15, update the list of exports that are protected to
exclude ones from the newly converted unprotected module in the
common/android/abi_gki_protected_exports_{ARCH} using tools/bazel run
//common:kernel_aarch64_abi_update_protected_exports for aarch64.
Submit your changes for review. GKI modules are an Android-only kernel
feature, so module conversion patches aren't required to be submitted
upstream. However, you must follow the other guidelines to submit
Android Common Kernel (ACK)
patches.
GKI modules symbol violation resolution quick guide
When unsigned modules violate the symbol protection in place for GKI modules,
two types of errors may be encountered during module loading, resulting in
failure.
The module.ko file is an unsigned vendor module and attempts to resolve the
GKI module exported symbol some_kernel_function during loading, without
being listed in the vendor symbol list.
Resolution:
If module.ko is not a protected GKI module, updating the symbol list will
resolve the error by including some_kernel_function in the vendor symbol list.
Alternatively, use the GKI version of module.ko.
2. Unsigned module exporting the protected symbol
Error:
module: exports protected symbol some_kernel_function
Cause:
The module exporting the some_kernel_function is a protected GKI module, and
module.ko is likely an unsigned custom version of that module. When
module.ko tries to export some_kernel_function, which can only be exported
by a signed GKI module, loading fails with this message.
Resolution:
This can be corrected by using the GKI version of the module that exports
some_kernel_function, if the unsigned module is a custom version.
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-08-29 UTC.
[null,null,["Last updated 2025-08-29 UTC."],[],[],null,["# Configure kernel features as GKI modules\n\nThis page covers how to configure a new kernel feature as a GKI module or\nconfigure an existing built-in kernel feature as a GKI module.\n| **Note:** Changes that result in a new GKI module or that change the protection status of a GKI module must be approved by Google.\n\nConfigure a new feature as a GKI module\n---------------------------------------\n\n1. For the new feature, edit `gki_defconfig` and set the required kernel\n feature's config item from `n` to `m` (`=m`). Set this setting in both\n `arch/arm64/configs/gki_defconfig` and `arch/x86/configs/gki_defconfig`.\n\n2. Add the KO (`.ko`) files generated for the feature\n to the `COMMON_GKI_MODULES_LIST` section of `common/modules.bzl`. Add the\n files in a sorted order. If you're unsure of all the files generated,\n the build fails and lists all the necessary KO files to be added to the list.\n\n3. For Android 14, add the same set of KO files from step 2, sorted in ascending\n order for binary search at runtime, to\n `common/android/gki_{ARCH}_protected_modules` to designate the module as a\n protected GKI module.\n\n4. For Android 14 and 15, update the list of exports so that it includes the\n newly-added exports in `common/android/abi_gki_protected_exports_`\u003cvar translate=\"no\"\u003eARCHITECTURE\u003c/var\u003e. For example, to update the list, run\n `tools/bazel run //common:kernel_aarch64_abi_update_protected_exports` for\n `aarch64`.\n\n5. Make sure newly added KO files from step 2 are copied to the kernel's\n `out/\u003candroidX-Y.Z\u003e/dist/system_dlkm.img` and\n `out/`\u003cvar translate=\"no\"\u003eandroidX-Y.Z\u003c/var\u003e`/dist/system_dlkm_staging_archive.tar.gz`.\n Modules in the `system_dlkm_staging_archive.tar.gz` archive can be used as\n input to generate the `system_dlkm.img` in the platform build.\n\n6. Submit your changes for review. GKI modules are an Android-only kernel\n feature, so module conversion patches aren't required to be submitted\n upstream. However, you must follow other guidelines to submit\n [Android Common Kernel (ACK) patches](/docs/core/architecture/kernel/kernel-code#ack-patches).\n\nConfigure a kernel built-in feature as a GKI module\n---------------------------------------------------\n\n1. For an existing built-in kernel feature, edit `gki_defconfig` and set the\n required kernel feature's config item from `y` to `m` (`=m`). Set this\n setting in both `arch/arm64/configs/gki_defconfig` and\n `arch/x86/configs/gki_defconfig`.\n\n2. Add the KO (`.ko`) files generated for the feature to the\n `COMMON_GKI_MODULES_LIST` section of `common/modules.bzl`. Add the files\n in a sorted order. If you're unsure of all the files generated,\n the build fails and lists all the necessary KO files to be added to the list.\n\n3. For Android 14, add the same set of KO files from step 2, sorted in ascending\n order for binary search at runtime, to\n `common/android/gki_{ARCH}_protected_modules` to designate the module as a\n protected GKI module.\n\n4. For Android 14 and 15, update the list of exports that are protected to\n include ones from the newly added module in\n `common/android/abi_gki_protected_exports_{ARCH}` using `tools/bazel run\n //common:kernel_aarch64_abi_update_protected_exports` for `aarch64`.\n\n5. Make sure newly converted module KO files from step 2 are copied to the\n kernel's `out/\u003candroidX-Y.Z\u003e/dist/system_dlkm.img` and\n `out/`\u003cvar translate=\"no\"\u003eandroidX-Y.Z\u003c/var\u003e`/dist/system_dlkm_staging_archive.tar.gz`.\n Modules in the `system_dlkm_staging_archive.tar.gz` archive can be used as\n input to generate the `system_dlkm.img` in the platform build.\n\n6. Submit your changes for review. GKI modules are an Android-only kernel\n feature, so module conversion patches aren't required to be submitted\n upstream. However, you must follow the other guidelines to submit\n [Android Common Kernel (ACK)\n patches](/docs/core/architecture/kernel/kernel-code#ack-patches).\n\nConvert a protected GKI module to unprotected\n---------------------------------------------\n\n1. For Android 15 and higher, add the module being converted from protected to\n unprotected to the `COMMON_UNPROTECTED_MODULES_LIST` list in\n `common/modules.bzl` file.\n\n2. For Android 14, remove the module being converted from protected to\n unprotected from the list of protected modules at\n `common/android/gki_protected_modules`.\n\n3. For Android 14 and 15, update the list of exports that are protected to\n exclude ones from the newly converted unprotected module in the\n `common/android/abi_gki_protected_exports_{ARCH}` using `tools/bazel run\n //common:kernel_aarch64_abi_update_protected_exports` for `aarch64`.\n\n4. Submit your changes for review. GKI modules are an Android-only kernel\n feature, so module conversion patches aren't required to be submitted\n upstream. However, you must follow the other guidelines to submit\n [Android Common Kernel (ACK)\n patches](/docs/core/architecture/kernel/kernel-code#ack-patches).\n\nGKI modules symbol violation resolution quick guide\n---------------------------------------------------\n\nWhen unsigned modules violate the symbol protection in place for GKI modules,\ntwo types of errors may be encountered during module loading, resulting in\nfailure.\n\n### 1. Unsigned module using the protected symbol\n\n**Error:**\n\n`module: Protected symbol: some_kernel_function (err -13)`\n\n**Cause:**\n\nThe `module.ko` file is an unsigned vendor module and attempts to resolve the\nGKI module exported symbol `some_kernel_function` during loading, without\nbeing listed in the vendor symbol list.\n\n**Resolution:**\n\nIf `module.ko` is not a protected GKI module, updating the symbol list will\nresolve the error by including `some_kernel_function` in the vendor symbol list.\nAlternatively, use the GKI version of `module.ko`.\n\n### 2. Unsigned module exporting the protected symbol\n\n**Error:**\n\n`module: exports protected symbol some_kernel_function`\n\n**Cause:**\n\nThe module exporting the `some_kernel_function` is a protected GKI module, and\n`module.ko` is likely an unsigned custom version of that module. When\n`module.ko` tries to export `some_kernel_function`, which can only be exported\nby a signed GKI module, loading fails with this message.\n\n**Resolution:**\n\nThis can be corrected by using the GKI version of the module that exports\n`some_kernel_function`, if the unsigned module is a custom version."]]
