Android kernel frequently asked questions

This document contains frequently asked questions about the Android kernel, known also as the Generic Kernel Image (GKI) kernel. If you are unfamiliar with GKI and GKI kernel terminology, refer to the Kernel overview.

Can Kernel Module Interface (KMI) symbol lists be changed in a stable kernel?

Changes that don't affect the existing KMI can be added to kernels that are frozen. These changes include new exported functions and symbol list entries. For details, see Manage symbol lists.

Can I change structures used by vendor modules in a stable kernel?

Structures that are part of a KMI interface can't be changed in kernels with a frozen KMI. Prior to KMI freeze, these structures can be changed.

Can I change the kernel as long as I don't break binary or source compatibility?

Changes that don't affect the KMI can be made as described in Android-specific patches.

How does GKI handle kernel configuration?

For information on kernel configuration, refer to the Changes to gki_defconfig.

How do I handle upstream bug fixes for overwrites to existing GKI modules?

If you create a vendor module based on a driver in Android Common Kernel (ACK), it's up to you to ensure that bug fixes from upstream and ACK are propagated to your module. Generally, it's in your best interest to use the GKI kernel and GKI modules without modification so these updates are provided consistently by Google.

Are there GKI specific tests?

There are Vendor Test Suite (VTS) tests that verify that a certified GKI build is installed and also to enforce per-release GKI requirements. For example, there are Android 12 VTS tests for boot header v3 and to verify the existence of required partitions in a device running a 5.10 kernel.

How do I create the project defconfig fragment file for device builds?

Many GKI-compliant devices use a config fragment to describe the configuration options needed, in addition to gki_defconfig, to build the vendor modules. Examples that are part of the ACK codebase include Cuttlefish and DB845c. There's no way to avoid some manual examination of configuration options to optimize the fragment, but scripts/diffconfig from the kernel sources is useful for comparing the results of gki_defconfig and gki_defconfig+device.fragment.

Is there a workaround for modprobe treating - and _ as equivalent?

The modprobe man page contains this description: "modprobe intelligently adds or removes a module from the Linux kernel: note that for convenience, there is no difference between _ and - in module names (automatic underscore conversion is performed)." The GKI team adheres to the standard upstream convention, so vendor tools or module naming conventions must take this adherence into account.

How do I enable debugfs for internal use?

For details on enabling debugfs, see intrusive downstream debug features.

How can I resolve mismatched ABIs between the GKI kernel with a specific module configuration enabled?

Mismatched ABIs between the GKI kernel and module configuration represents an implicit module config dependency, where enabling a module causes a binary config to be built into the resulting kernel image. Reach out to the Android kernel team (kernel-team@android.com) to determine a path forward. After the list of symbols is determined, create a bug in the Issue Tracker and upload a change to the symbol list.

I have GKI 1.0 compliant devices in the field running the 5.4 kernel that launched with Android 11 and 12. What kernel upgrade options are available, and how can I test these devices when upgrading to Android 12 and 13?

Refer to the compatibility matrix for a list of supported kernel versions for launch and upgrade versions. Here are two upgrade examples:

Example 1: A user with a device that launches with Android 11 with the android11-5.4 kernel (GKI 1.0) can choose any of these options when upgrading to Android 12:

  • Upgrade to the android12-5.10 GKI 2.0 kernel (strongly recommended).

  • Keep the android11-5.4 kernel.

  • Upgrade to the android12-5.4 kernel.

Example 2: A user with a device that launches with Android 12 with either the android12-5.4 or android12-5.10 kernel can choose any of these options when upgrading to Android 13:

  • Upgrade to the android13-5.10 or android13-5.15 GKI 2.0 kernel (strongly recommended).

  • Keep the android12-5.4 GKI 1.0 kernel.

  • Keep the android12-5.10 GKI 2.0 kernel.

Specifically for Treble compliance testing, we recommend you do one of the following:

  • Replace the partner kernel with the certified GKI 1.0 kernel (android11-5.4 or android12-5.4).

  • Ship with the certified GKI 2.0 kernel (android12-5.10, android13-5.10, or android13-5.15) depending on your selection.

You can download GKI 2.0 builds from Generic Kernel Image (GKI) release builds.