이 페이지에서는 새 커널 기능을 GKI 모듈로 구성하거나 기존 내장 커널 기능을 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 14의 경우 런타임 시 바이너리 검색을 위해 오름차순으로 정렬된 2단계의 동일한 KO 파일 집합을 common/android/gki_{ARCH}_protected_modules에 추가하여 모듈을 보호된 GKI 모듈로 지정합니다.
Android 14 및 15의 경우 common/android/abi_gki_protected_exports_ARCHITECTURE에 새로 추가된 내보내기가 포함되도록 내보내기 목록을 업데이트합니다. 예를 들어 목록을 업데이트하려면 aarch64에 대해 tools/bazel run //common:kernel_aarch64_abi_update_protected_exports를 실행합니다.
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를 생성하는 입력으로 사용할 수 있습니다.
검토를 위해 변경사항을 제출합니다. GKI 모듈은 Android 전용 커널 기능이므로 모듈 변환 패치는 업스트림으로 제출하지 않아도 됩니다. 하지만 다른 가이드라인에 따라 Android 일반 커널(ACK) 패치를 제출해야 합니다.
커널 내장 기능을 GKI 모듈로 구성
기존 내장 커널 기능의 경우 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 파일이 모두 나열됩니다.
Android 14의 경우 런타임 시 바이너리 검색을 위해 오름차순으로 정렬된 2단계의 동일한 KO 파일 집합을 common/android/gki_{ARCH}_protected_modules에 추가하여 모듈을 보호된 GKI 모듈로 지정합니다.
Android 14 및 15의 경우 aarch64에 tools/bazel run
//common:kernel_aarch64_abi_update_protected_exports를 사용하여 common/android/abi_gki_protected_exports_{ARCH}에 새로 추가된 모듈의 내보내기를 포함하도록 보호되는 내보내기 목록을 업데이트하세요.
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를 생성하는 입력으로 사용할 수 있습니다.
검토를 위해 변경사항을 제출합니다. GKI 모듈은 Android 전용 커널 기능이므로 모듈 변환 패치는 업스트림으로 제출하지 않아도 됩니다. 하지만 다른 가이드라인에 따라 Android 일반 커널 (ACK) 패치를 제출해야 합니다.
보호되는 GKI 모듈을 비보호 모듈로 변환
Android 15 이상에서는 보호 상태에서 비보호 상태로 변환되는 모듈을 common/modules.bzl 파일의 COMMON_UNPROTECTED_MODULES_LIST 목록에 추가합니다.
Android 14의 경우 common/android/gki_protected_modules의 보호되는 모듈 목록에서 보호 상태에서 비보호 상태로 변환되는 모듈을 삭제합니다.
Android 14 및 15의 경우 tools/bazel run
//common:kernel_aarch64_abi_update_protected_exports를 aarch64에 사용하여 common/android/abi_gki_protected_exports_{ARCH}에 새로 변환된 비보호 모듈을 제외하도록 보호되는 내보내기 목록을 업데이트하세요.
검토를 위해 변경사항을 제출합니다. GKI 모듈은 Android 전용 커널 기능이므로 모듈 변환 패치는 업스트림으로 제출하지 않아도 됩니다. 하지만 다른 가이드라인에 따라 Android 일반 커널 (ACK) 패치를 제출해야 합니다.
GKI 모듈 기호 위반 해결 방법에 관한 빠른 가이드
서명되지 않은 모듈이 GKI 모듈에 적용되는 기호 보호를 위반하면 모듈을 로드하는 중에 두 가지 유형의 오류가 발생하여 실패할 수 있습니다.
module.ko 파일은 서명되지 않은 공급업체 모듈이며 공급업체 기호 목록에 나열되지 않은 채로 로드 중에 GKI 모듈이 내보낸 기호 some_kernel_function을 확인하려고 시도합니다.
해상도
module.ko가 보호되는 GKI 모듈이 아닌 경우 기호 목록을 업데이트하면 공급업체 기호 목록에 some_kernel_function이 포함되어 오류가 해결됩니다.
또는 module.ko의 GKI 버전을 사용하세요.
2. 보호되지 않은 기호를 내보내는 서명되지 않은 모듈
오류:
module: exports protected symbol some_kernel_function
원인:
some_kernel_function을 내보내는 모듈은 보호되는 GKI 모듈이며 module.ko는 이 모듈의 서명되지 않은 맞춤 버전일 가능성이 높습니다. module.ko가 서명된 GKI 모듈만 내보낼 수 있는 some_kernel_function을 내보내려고 하면 이 메시지가 표시되며 로드에 실패합니다.
해상도
서명되지 않은 모듈이 맞춤 버전인 경우 some_kernel_function을 내보내는 모듈의 GKI 버전을 사용하여 수정할 수 있습니다.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-07-27(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-27(UTC)"],[],[],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."]]
