GKI & kernel builds

Before you start#

Required earlier lessons: Memory and system calls, C/C++ for source readers, Android boot and partitions, and The kernel boundary. You should know that a kernel is privileged code, and that a build produces files but does not make them suitable for a device. No build, device access, bootloader change, or flashing is required for the core lesson.

Learning goals#

You will explain what GKI standardizes and what it does not; distinguish kernel source, configuration, target, artifact, packaged image, and running kernel; understand the scope of KMI; identify why a successful build does not prove bootability; and use the exact source tree's instructions rather than copying a command from another device or branch.

Practice#

Android's kernel is a device-specific combination

Android does not have one kernel binary that can be built and booted on every phone. The kernel must match architecture, configuration, boot format, device description, modules, firmware, bootloader expectations, and vendor integration. ACK (Android Common Kernel) is Google's Linux source with Android-specific changes. Vendors may add SoC/board support and distribute corresponding sources separately. “Android 14” alone does not identify a kernel branch or device target. AOSP: Android Common Kernels

This curriculum uses the Android 14 android14-6.1 ACK snapshot 2f0d864181b9acf801e9b51c345e11b6156b767a, observed 2026-10-26. The commit is a merge of tag android14-6.1.177_r01 into that branch (commit). The commit is fixed evidence; branch names can move. It is not a claim that all Android 14 products use kernel 6.1.

Current-doc difference: the GKI project page now says that, "effective in 2026," source is published to AOSP in Q2 and Q4 and that android-latest-release is the branch to use for building and contributing to AOSP. The android-14.0.0_r1 baseline is unaffected for this lesson.

GKI and KMI

GKI (Generic Kernel Image) provides a common kernel core for a supported architecture and kernel line. Device- and SoC-specific code can be delivered as loadable vendor modules. GKI is not a complete generic phone image: compatible modules, device-tree data, firmware, boot configuration, and vendor integration still matter. A .ko module runs in kernel privilege; it is not isolated like an app.

KMI (Kernel Module Interface) is a controlled set of exported kernel symbols and associated ABI expectations for supported vendor modules in a given GKI line. An ABI is a binary-level agreement (for example, callable symbols, calling conventions, and relevant data layout). KMI is not a promise that all Linux internals remain stable forever. A module can fail due to mismatched symbols/config/signing, and a module that loads can still be functionally wrong. GKI · Stable KMI

Source, config, target, artifact, package, boot

Keep these stages separate:

source + target/config + selected toolchain + build rules
        → kernel/module/DT artifacts
        → device-specific image packaging
        → bootloader verification
        → running kernel + compatible vendor integration

A configuration selects features/drivers as built-in, modules, or absent. A defconfig is a starting point; fragments and product settings may alter the final config. A target names a particular build graph and output contract. The toolchain compiles for the target architecture; use the version selected/documented by that source tree. An artifact is a generated file (for example, Image, a module, or DTB). Packaging combines the correct artifacts and ramdisk/metadata into the product's boot format. Each arrow can fail independently. vermagic or a matching filename is not proof of KMI compatibility, correct hardware description, signing, or successful boot.

Recent ACK branches use Kleaf, a Bazel-based kernel build system. Android's build guide documents a GKI aarch64 distribution target for an ACK branch with Kleaf:

tools/bazel run //common:kernel_aarch64_dist -- --destdir="$DIST_DIR"

This is a documented GKI distribution example, not a command to run in an arbitrary repository and not a device image to flash. The matching branch's README, manifest, host requirements, and build files are authoritative. The legacy build/build.sh is not supported on Android 14 and later. Never infer that a build command for one branch applies to another. AOSP kernel build guide

Preflight and source-pinned build worksheet

The lesson's source snapshot is pinned at ACK commit 2f0d864…. In its root BUILD.bazel, the common-kernel configuration declares kernel_aarch64 with the GKI AArch64 symbol list and GKI build goals (see pinned BUILD.bazel). The source tree and AOSP guide together document the GKI distribution target above. Target labels can be generated by the build macros; confirm the exact label in the pinned checkout before invoking it.

Preflight—safe source/host checks only, no privilege required:

1. Verify git rev-parse HEAD equals the commit in this lesson. If not, stop and use that checkout's documentation instead.
2. Read that checkout's README and build documentation. Confirm the target is the generic GKI aarch64 distribution—not a board target such as db845c_no_kgdb.
3. Confirm host OS/tool prerequisites, free disk space, and expected build duration using branch-local docs. A full source checkout/build can be large; do not start one on a machine without adequate storage/resources or authorization.
4. In the exact checkout, inspect target availability without building, using its bundled tool: tools/bazel query //common:kernel_aarch64_dist. If the checkout's docs name a different label or the query fails, stop and follow its docs; do not guess a replacement target.
5. Only in a disposable, adequately provisioned Linux build environment, and only after those checks, use the documented command. Set DIST_DIR to a new empty directory you control. Do not flash, boot, install modules, or change boot security as part of this exercise.

After a real build, inspect files without executing or installing them:

find "$DIST_DIR" -maxdepth 2 -type f -printf '%P\n' | sort
file "$DIST_DIR"/*

Expected evidence: files are present in the chosen distribution directory, and file reports artifact types. Exact filenames vary by branch/config. A successful build establishes that this source/config/target compiled and emitted artifacts. It does not establish that they match a phone, pass AVB/bootloader policy, have all vendor modules/DT data, or boot safely.

Source-only fallback (no checkout/build performed): open the pinned BUILD.bazel, search for "kernel_aarch64", then inspect the surrounding declaration and the AOSP build guide's kernel_aarch64_dist command. Record the architecture, KMI list, target name, output category, and one reason it is not a universal phone image. Label the result “source inspection only—not built.” This lesson's build commands are documented examples, not commands this environment ran.

GKI target vs board target

The same pinned build file also includes a target called db845c_no_kgdb, with DB845c-specific build config and explicit Qualcomm DTB outputs. That is a useful example of target scope, not a generic Android 14 build. The lesson's old source excerpt may be read as an advanced example: kernel_build(name = "db845c_no_kgdb", ... build_config = "build.config.db845c", kmi_symbol_list = "android/abi_gki_aarch64_db845c", ...). In this C/Starlark excerpt, ... means attributes are omitted; it is not executable build syntax. Do not copy this board target for a different device.

Advanced source deep dive: KMI evidence

In the pinned build declaration, the kernel_aarch64 target references android/abi_gki_aarch64; in this snapshot that symbol list is a short file with a header and only two symbols, module_layout and __put_task_struct. A symbol list is not a header or a complete ABI description. It does not promise every internal function or structure is supported. An ABI check helps assess a binary interface change; it does not test runtime driver behavior, board wiring, boot policy, or hardware. The architecture and target-specific scope matter. This implementation-level detail is optional; the core takeaway is that GKI reduces fragmentation under a limited compatibility contract rather than erasing device-specific integration.

Knowledge check#

Answer before reading the key.

1. A GKI kernel compiles. What further contracts must be checked before it could be used on a named phone?
2. A vendor module has the expected .ko filename but fails to load. Name three compatibility/policy areas to investigate.
3. The build emits an Image. Does that mean the device bootloader can accept it? Why not?
4. A source-only worksheet identifies a target but runs no build. What may it claim, and what must it not claim?

Answers#

1. Matching architecture/kernel line and config; vendor modules/KMI and signing; correct DTB/DTBO, firmware, ramdisk/packaging; bootloader/AVB state and device integration. Exact requirements are product-specific.
2. KMI/symbol ABI, config/vermagic, signing/module-loading policy, module dependencies, and target kernel/version are reasonable checks. Filename alone proves none of them.
3. No. The image may have the wrong format, config, DT/ramdisk/modules or trust/signature for that device; successful compilation is not packaging or boot evidence.
4. It may describe what the pinned build declarations/documentation specify. It must label this source inspection only and cannot claim successful compilation, artifact output, boot, or hardware compatibility.

Checkpoint#

• Ready: you can describe GKI's shared core and name the device integration it does not supply; you separate build success from boot success.
• Revise: you treat a .ko, Image, or db845c target as universally deployable; redraw the source-to-boot chain and identify target scope.
• Not yet evidenced: your build worksheet does not state whether a build actually ran. Add the label “source inspection only” or provide a build log/artifact inventory from an authorized disposable environment—never a flash/boot claim.

Sources#

• Pinned ACK Android 14 6.1 snapshot — exact lesson baseline (merge of android14-6.1.177_r01 into the branch); branch names move.
• Pinned BUILD.bazel — common AArch64 GKI target configuration; DB845c target demonstrates board-specific scope.
• AOSP kernel build guide — Kleaf distribution command and artifact directory guidance; Kleaf docs — build-system details.
• GKI, stable KMI, and kernel modules — compatibility boundaries and module model.