自 2025 年 3 月 27 日起,我们建议您使用 android-latest-release
而非 aosp-main
构建 AOSP 并为其做出贡献。如需了解详情,请参阅 AOSP 的变更。
将内核功能配置为 GKI 模块
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本页旨在介绍如何将新的内核功能或现有的内置内核功能配置为 GKI 模块。
对于新功能,请修改 gki_defconfig
并将所需内核功能的配置项从 n
改设为 m
(=m
)。在 arch/arm64/configs/gki_defconfig
和 arch/x86/configs/gki_defconfig
中均配置此设置。
将为该功能生成的 KO (.ko
) 文件添加到 common/modules.bzl
的 COMMON_GKI_MODULES_LIST
部分。依序添加文件。如果您不确定生成的所有文件,构建会失败并会列出应向列表添加的所有必要 KO 文件。
(可选)对于 Android 15 及更高版本,请省略此步骤。
将第 2 步中的同一组 KO 文件(按升序排列以便在运行时进行二进制文件搜索)添加到 common/android/gki_{ARCH}_protected_modules
中,以将该模块指定为受保护的 GKI 模块。
更新导出列表,使其包含 common/android/abi_gki_protected_exports_ARCHITECTURE
中新添加的导出。例如,如需更新列表,请针对 aarch64
运行 tools/bazel run //common:kernel_aarch64_abi_update_protected_exports
。即使已被指定为受保护的 GKI 模块,这些模块仍必须获得 Google 批准,才能成为受官方保护的模块。
确保将第 2 步中新添加的 KO 文件复制到内核的 out/<androidX-Y.Z>/dist/system_dlkm.img
和 out/androidX-Y.Z/dist/system_dlkm_staging_archive.tar.gz
。
system_dlkm_staging_archive.tar.gz
归档中的模块可用作输入内容,以在平台 build 中生成 system_dlkm.img
。
提交您的更改以供审核。GKI 模块是 Android 专用内核功能,因此无需在上游提交模块转换补丁。不过,您必须遵循其他准则,才能提交 Android 通用内核 (ACK) 补丁。
对于现有的内置内核功能,请修改 gki_defconfig
并将所需内核功能的配置项从 y
改设为 m
(=m
)。在 arch/arm64/configs/gki_defconfig
和 arch/x86/configs/gki_defconfig
中均配置此设置。
将为该功能生成的 KO (.ko
) 文件添加到 common/modules.bzl
的 COMMON_GKI_MODULES_LIST
部分。依序添加文件。如果您不确定生成的所有文件,构建会失败并会列出应向列表添加的所有必要 KO 文件。
将第 2 步中的同一组 KO 文件(按升序排列以便在运行时进行二进制文件搜索)添加到 common/android/gki_{ARCH}_protected_modules
中,以将该模块指定为受保护的 GKI 模块。使用适用于 aarch64
的 tools/bazel run //common:kernel_aarch64_abi_update_protected_exports
更新受保护的导出列表,使其包含 common/android/abi_gki_protected_exports_{ARCH}
中新添加的模块中的导出内容。即使已被指定为受保护的 GKI 模块,这些模块仍必须获得 Google 批准,才能成为受官方保护的模块。
确保将第 2 步中新转换的模块 KO 文件复制到内核的 out/<androidX-Y.Z>/dist/system_dlkm.img
和 out/androidX-Y.Z/dist/system_dlkm_staging_archive.tar.gz
。
system_dlkm_staging_archive.tar.gz
归档中的模块可用作输入内容,以在平台 build 中生成 system_dlkm.img
。
提交您的更改以供审核。GKI 模块是 Android 专用内核功能,因此无需在上游提交模块转换补丁。不过,您必须按照其他准则提交 Android 通用内核 (ACK) 补丁。
将受保护的 GKI 模块转换为不受保护的模块
- 对于 Android 14 及更低版本:从位于
common/android/gki_protected_modules
的受保护模块列表中移除从受保护状态转换为不受保护状态的模块。
- 对于 Android 15 及更高版本:将从受保护状态转换为不受保护状态的模块添加到
common/modules.bzl
文件中的 COMMON_UNPROTECTED_MODULES_LIST
列表中。
使用适用于 aarch64
的 tools/bazel run //common:kernel_aarch64_abi_update_protected_exports
更新受保护导出的列表,以排除 common/android/abi_gki_protected_exports_{ARCH}
中新转换的不受保护模块中的导出内容。
提交您的更改以供审核。GKI 模块是 Android 专用内核功能,因此无需在上游提交模块转换补丁。不过,您必须按照其他准则提交 Android 通用内核 (ACK) 补丁。
GKI 模块符号违规行为解决方法快速指南
当未签名模块违反 GKI 模块的符号保护设置时,模块加载期间可能会遇到两种类型的错误,从而导致失败。
1. 使用受保护符号的未签名模块
错误:
module: Protected symbol: some_kernel_function (err -13)
原因:
module.ko
文件是一个未签名的供应商模块,它会尝试在加载期间解析 GKI 模块导出的符号 some_kernel_function
,而不会在供应商符号列表中列出该符号。
解决方法:
如果 module.ko
不是受保护的 GKI 模块,更新符号列表以在供应商符号列表中添加 some_kernel_function
可解决该错误。
或者,也可以使用 GKI 版本的 module.ko
。
2. 导出受保护符号的未签名模块
错误:
module: exports protected symbol some_kernel_function
原因:
导出 some_kernel_function
的模块是受保护的 GKI 模块,module.ko
可能是该模块的未签名自定义版本。当 module.ko
尝试导出 some_kernel_function
(只能由已签名的 GKI 模块导出)时,加载会失败并显示此消息。
解决方法:
如果未签名模块是自定义版本,则可以使用导出 some_kernel_function
的模块的 GKI 版本来修正此问题。
本页面上的内容和代码示例受内容许可部分所述许可的限制。Java 和 OpenJDK 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-03-26。
[null,null,["最后更新时间 (UTC):2025-03-26。"],[],[],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."]]