將核心功能設為 GKI 模組

本頁面說明如何將新的核心功能設定為 GKI 模組，或將現有的內建核心功能設定為 GKI 模組。

將新功能設為 GKI 模組

  1. 針對新功能，請編輯 gki_defconfig，並將必要的核心功能設定項目從 n 設為 m (=m)。請在 arch/arm64/configs/gki_defconfig 和 arch/x86/configs/gki_defconfig 中同時設定這項設定。

  2. 將為功能產生的 KO (.ko) 檔案新增至 common/modules.bzl 的 COMMON_GKI_MODULES_LIST 部分。依照排序順序新增檔案。如果您不確定產生的所有檔案，則建構作業會失敗，並列出所有必須新增至清單的 KO 檔案。

  3. 針對 Android 14，請新增步驟 2 中的相同 KO 檔案組合，並以執行階段二元搜尋的遞增順序排序，將模組指定為受保護的 GKI 模組。common/android/gki_{ARCH}_protected_modules

  4. 針對 Android 14 到 16，請更新匯出清單，以便納入 common/android/abi_gki_protected_exports_ARCHITECTURE 中新加入的匯出項目。例如，如要更新清單，請為 aarch64 執行 tools/bazel run //common:kernel_aarch64_abi_update_protected_exports。

  5. 請確認在步驟 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 封存檔中的模組可用做為輸入內容，在平台版本中產生 system_dlkm.img。

  6. 將變更送審。GKI 模組是 Android 專屬的核心功能，因此模組轉換修補程式不需要提交至上游。不過，您必須遵循其他規範才能提交 Android 通用核心 (ACK) 修補程式。

將核心內建功能設定為 GKI 模組

  1. 針對現有的內建核心功能，請編輯 gki_defconfig，並將必要的核心功能設定項目從 y 設為 m (=m)。請在 arch/arm64/configs/gki_defconfig 和 arch/x86/configs/gki_defconfig 中同時設定這項設定。

  2. 將為功能產生的 KO (.ko) 檔案新增至 common/modules.bzl 的 COMMON_GKI_MODULES_LIST 部分。依照排序順序新增檔案。如果您不確定產生的所有檔案，則建構作業會失敗，並列出所有必須新增至清單的 KO 檔案。

  3. 針對 Android 14，請新增步驟 2 中的相同 KO 檔案組合，並以執行階段二元搜尋的遞增順序排序，將模組指定為受保護的 GKI 模組。common/android/gki_{ARCH}_protected_modules

  4. 針對 Android 14 到 16，請使用 tools/bazel run //common:kernel_aarch64_abi_update_protected_exports 為 aarch64 更新受保護的匯出清單，以納入 common/android/abi_gki_protected_exports_{ARCH} 中新加入的模組 (或 Android 16 的 common/gki/{ARCH}/protected_exports)。

  5. 請確認從步驟 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 封存檔中的模組可用做為輸入內容，在平台版本中產生 system_dlkm.img。

  6. 將變更送審。GKI 模組是 Android 專屬的核心功能，因此模組轉換修補程式不需要提交至上游。不過，您必須遵循其他規範才能提交 Android 通用核心 (ACK) 修補程式。

將受保護的 GKI 模組轉換為未受保護的模組

  1. 如果是 Android 15 以上版本，請將從受保護轉換為未受保護的模組，加入 common/modules.bzl 檔案中的 COMMON_UNPROTECTED_MODULES_LIST 清單。

  2. 針對 Android 14，請從 common/android/gki_protected_modules 的受保護模組清單中，移除從受保護轉換為未受保護的模組。

  3. 針對 Android 14 到 16，請使用 tools/bazel run //common:kernel_aarch64_abi_update_protected_exports 為 aarch64 更新受保護的匯出清單，以便排除 common/android/abi_gki_protected_exports_{ARCH} (或 Android 16 的 common/gki/{ARCH}/protected_exports) 中新轉換的未受保護模組。

  4. 將變更送審。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 時，系統會顯示此訊息，因為 some_kernel_function 只能由已簽署的 GKI 模組匯出。

解決方法：

如果未簽署的模組為自訂版本，您可以使用匯出 some_kernel_function 的模組 GKI 版本來修正這個問題。