Configure kernel features as GKI modules

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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

  1. 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.

  2. For Android 14, remove the module being converted from protected to unprotected from the list of protected modules at common/android/gki_protected_modules.

  3. 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.

  4. 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.

1. Unsigned module using the protected symbol

Error:

module: Protected symbol: some_kernel_function (err -13)

Cause:

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.