Menggunakan daftar simbol

Untuk mengurangi permukaan simbol dan jenis yang perlu dipertahankan agar tetap stabil, kernel GKI memiliki kemampuan untuk membatasi simbol yang diekspor hanya pada simbol yang diperlukan oleh modul. Untuk modul yang dikompilasi secara eksternal, Anda harus memiliki daftar simbol yang digunakan agar dapat diekspor oleh kernel GKI. Misalnya, simbol yang digunakan oleh modul untuk Cuttlefish disimpan di gki/aarch64/symbols/virtual_device.

Menambahkan target untuk pembuatan daftar simbol

Daftar simbol dibuat oleh target kernel_abi. Tambahkan target ini ke BUILD.bazel perangkat dengan opsi berikut:

  • name

    Harus dalam format <kernel_build>_abi.

  • kernel_build

    Harus berisi nama target kernel_build perangkat.

Anda juga dapat menggunakan opsi berikut:

  • kernel_modules

    Daftar target untuk modul di luar pohon. Modul dalam struktur direktori framework tidak boleh disertakan di sini. Lihat Menyiapkan modul dalam struktur hierarki untuk ekstraksi simbol.

  • kmi_symbol_list_add_only

    Opsi ini mencegah penghapusan simbol yang tidak digunakan. Penghapusan simbol hanya diizinkan pada waktu tertentu selama stabilisasi KMI dan tidak diizinkan setelah KMI dibekukan.

    Tindakan ini juga berguna saat Anda menggunakan daftar simbol yang sama untuk beberapa perangkat yang berbeda. Dengan cara ini, simbol yang digunakan oleh perangkat A tetapi tidak oleh perangkat B tidak akan dihapus.

  • module_grouping

    Jika True atau tidak ditentukan, daftar simbol akan mengelompokkan simbol berdasarkan modul kernel yang mereferensikan simbol. Jika tidak, daftar simbol adalah daftar simbol yang diurutkan yang digunakan oleh semua modul kernel.

Lihat common-modules/virtual-device/BUILD.bazel misalnya:

kernel_abi(
    name = "virtual_device_aarch64_abi",
    kernel_build = ":virtual_device_aarch64",
    kernel_modules = [":virtual_device_aarch64_external_modules"],
    kmi_symbol_list_add_only = True,
)

Lihat juga dokumentasi referensi tentang target kernel_abi di Kleaf.

Menyiapkan modul dalam pohon untuk ekstraksi simbol

Untuk menyiapkan modul dalam struktur direktori untuk ekstraksi simbol, cantumkan modul dalam struktur direktori khusus vendor dalam atribut module_outs target kernel_build. Lihat _VIRT_COMMON_MODULES dan penggunaannya untuk melihat contoh. Jangan sertakan modul GKI dalam daftar ini.

Konfigurasi modul ini agar tidak bertanda tangan, jika tidak, daftar simbol mungkin kosong. Untuk melakukannya, tambahkan baris ini ke fragmen konfigurasi kernel Anda:

# CONFIG_MODULE_SIG_ALL is not set

Lihat common-modules/virtual-device/virtual_device_core.fragment misalnya.

Menambahkan daftar simbol perangkat ke build kernel perangkat

Tambahkan atribut kmi_symbol_list ke target kernel_build yang ditentukan di perangkat BUILD.bazel. Nama daftar simbol harus dalam format //common:gki/<arch>/symbols/<device>.

Lihat common-modules/virtual-device/BUILD.bazel, misalnya:

kernel_build(
    name = "virtual_device_aarch64",
    base_kernel = "//common:kernel_aarch64",
    kmi_symbol_list = "//common:gki/aarch64/symbols/virtual_device",
    ...
    module_outs = _VIRT_COMMON_MODULES + _VIRT_AARCH64_MODULES,
)

Membuat dan mengirimkan daftar simbol awal

Buat daftar simbol kosong di common/gki/<arch>/symbols/<device>. Untuk contoh di atas, perintahnya adalah:

touch common/gki/aarch64/symbols/virtual_device

Tambahkan file ini ke additional_kmi_symbol_lists build kernel GKI dasar. Misalnya, //common:gki/aarch64/symbols/virtual_device ditambahkan ke grup file aarch64_additional_kmi_symbol_lists, yang dideklarasikan di common/BUILD.bazel.

Perbarui daftar simbol perangkat untuk mengisi daftar simbol baru dan kirimkan ke repositori Android Common Kernel.

Memperbarui daftar simbol perangkat

Semua simbol kernel inti yang digunakan oleh modul di module_outs kernel_build dan kernel_modules kernel_abi harus disertakan dalam daftar simbol. Hal ini dapat dilakukan dengan menjalankan target kernel_abi dengan akhiran _update_symbol_list. Misalnya, perintah berikut memperbarui daftar simbol untuk //common-modules/virtual-device:virtual_device_aarch64:

tools/bazel run //common-modules/virtual-device:virtual_device_aarch64_abi_update_symbol_list

Mengirim pembaruan daftar simbol ke ACK

Kirim patch dengan perubahan daftar simbol ke Gerrit Android Common Kernel untuk menjadikan simbol baru bagian dari KMI.

Pesan commit harus menyertakan daftar simbol yang ditambahkan atau dihapus. Anda dapat menulis daftar ini secara manual untuk pembaruan daftar simbol kecil atau menggunakan laporan $DIST_DIR/abi_stgdiff/abi.report.short setelah memperbarui representasi ABI referensi.

Meskipun memperbarui representasi ABI rujukan sebelum mengirimkan pembaruan daftar simbol tidak diperlukan, tindakan ini dapat menghilangkan langkah-langkah pra-pengiriman tambahan dan membuat perubahan siap dikirimkan lebih cepat. Bagaimanapun, hal ini diperiksa dan diperbarui jika perlu selama pra-pengiriman.

Menangani daftar simbol (Android 13)

Android 13 mendukung skrip build Kleaf dan lama, sehingga Anda dapat mengelola daftar simbol seperti yang dijelaskan di bagian sebelumnya atau seperti yang dijelaskan di bagian berikut.

Menangani daftar simbol (Android 12 dan yang lebih lama)

Gunakan alat build_abi.sh sebagai berikut:

BUILD_CONFIG=path/to/build.config.device build/build_abi.sh --update-symbol-list

Dalam contoh ini, build.config.device harus menyertakan opsi konfigurasi berikut:

  • vmlinux

    Harus menjadi bagian dari daftar FILES. Hal ini dapat dilakukan dengan menyertakan build.config.aarch64.

  • KMI_SYMBOL_LIST

    Harus ditetapkan dan diarahkan ke daftar simbol KMI yang akan diperbarui.

Setelah memperbarui daftar simbol perangkat, Anda juga perlu mencerminkan perubahan ini dalam build GKI (common/build.config.gki.aarch64):

  • Salin daftar simbol yang diperbarui ke common/android/abi_gki_aarch64_<device>.

  • Pastikan android/abi_gki_aarch64_<device> disertakan dalam ADDITIONAL_KMI_SYMBOL_LISTS di common/build.config.gki.aarch64.

  • Kirim update daftar simbol ke ACK.