Lavorare con gli elenchi di simboli

Per ridurre la superficie di simboli e tipi che devono essere mantenuti stabili, il kernel GKI ha la possibilità di limitare i simboli esportati solo a quelli necessari per i moduli. Per i moduli compilati esternamente, devi avere un elenco di simboli utilizzati per consentirne l'esportazione dal kernel GKI. Ad esempio, i simboli utilizzati dai moduli per Cuttlefish sono memorizzati in android/abi_gki_aarch64_virtual_device.

Aggiungere un target per la generazione dell'elenco di simboli

Gli elenchi di simboli vengono generati dal target kernel_abi. Aggiungi questo target al dispositivo BUILD.bazel con le seguenti opzioni:

  • name

    Deve essere nel formato <kernel_build>_abi.

  • kernel_build

    Deve contenere il nome del dispositivo kernel_build di destinazione.

Puoi anche utilizzare le seguenti opzioni:

  • kernel_modules

    Elenco dei target per i moduli out-of-tree. I moduli all'interno dell'albero non devono essere inclusi qui. Consulta Preparare i moduli in-tree per l'estrazione dei simboli.

  • kmi_symbol_list_add_only

    Questa opzione impedisce la rimozione dei simboli inutilizzati. La rimozione dei simboli è consentita solo in momenti specifici durante la stabilizzazione del KMI e non è consentita una volta che il KMI è congelato.

    Questa opzione è utile anche quando utilizzi lo stesso elenco di simboli per più dispositivi diversi. In questo modo, non verranno rimossi i simboli utilizzati dal dispositivo A, ma non dal dispositivo B.

  • module_grouping

    Se True o non specificato, l'elenco dei simboli raggruppa i simboli in base ai moduli del kernel che fanno riferimento al simbolo. In caso contrario, l'elenco dei simboli è un elenco ordinato dei simboli utilizzati da tutti i moduli del kernel.

Ad esempio, consulta common-modules/virtual-device/BUILD.bazel.

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,
)

Consulta anche la documentazione di riferimento sul target kernel_abi in Kleaf.

Preparare i moduli in-tree per l'estrazione dei simboli

Per preparare i moduli in-tree per l'estrazione dei simboli, elenca i moduli in-tree specifici del fornitore in un attributo module_outs del target kernel_build. Per un esempio, consulta _VIRT_COMMON_MODULES e il relativo utilizzo. Non includere i moduli GKI in questo elenco.

Configura questi moduli in modo che siano non firmati, altrimenti l'elenco dei simboli potrebbe essere vuoto. Per farlo, aggiungi questa riga ai frammenti di configurazione del kernel:

# CONFIG_MODULE_SIG_ALL is not set

Vedi common-modules/virtual-device/virtual_device_core.fragment per esempio.

Aggiungere un elenco di simboli del dispositivo alla build del kernel del dispositivo

Aggiungi l'attributo kmi_symbol_list al target kernel_build definito nel dispositivo BUILD.bazel. Il nome dell'elenco di simboli deve essere nel formato//common:android/abi_gki_<arch>_<device>. Consulta common-modules/virtual-device/BUILD.bazel, ad esempio:

kernel_build(
    name = "virtual_device_aarch64",
    base_kernel = "//common:kernel_aarch64",
    kmi_symbol_list = "//common:android/abi_gki_aarch64_virtual_device",
    ...
    module_outs = _VIRT_COMMON_MODULES + _VIRT_AARCH64_MODULES,
)

Creare e inviare un elenco iniziale di simboli

Crea un elenco di simboli vuoto in common/android/abi_gki_<arch>_<device>. Per l'esempio riportato sopra, il comando sarà:

touch common/android/abi_gki_aarch64_virtual_device

Aggiungi questo file a additional_kmi_symbol_lists della build del kernel GKI di base. Ad esempio, //common:android/abi_gki_aarch64_virtual_device viene aggiunto al gruppo di file aarch64_additional_kmi_symbol_lists, dichiarato in common/BUILD.bazel.

Aggiorna l'elenco dei simboli del dispositivo per compilare il nuovo elenco di simboli e inviarlo al repository del kernel comune di Android.

Aggiornare un elenco di simboli di dispositivi

Tutti i simboli del kernel di base utilizzati dai moduli in module_outs di kernel_build e kernel_modules di kernel_abi devono essere inclusi nell'elenco dei simboli. Per farlo, puoi eseguire il target kernel_abi con il suffisso _update_symbol_list. Ad esempio, il seguente comando aggiorna l'elenco di simboli per //common-modules/virtual-device:virtual_device_aarch64:

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

Invia un aggiornamento dell'elenco di simboli ad ACK

Invia una patch con la modifica dell'elenco di simboli al gerrit del kernel Android Common per includere i nuovi simboli nel KMI.

Il messaggio del commit deve includere un elenco di simboli aggiunti o rimossi. Puoi scrivere questo elenco manualmente per un piccolo aggiornamento dell'elenco di simboli o utilizzare il report $DIST_DIR/abi.report.short dopo aver aggiornato la rappresentazione dell'ABI di riferimento.

Anche se l'aggiornamento della rappresentazione dell'ABI di riferimento prima di inviare un aggiornamento dell'elenco di simboli non è obbligatorio, potrebbe eliminare i passaggi pre-invio aggiuntivi e rendere la modifica pronta per l'invio più rapidamente. In ogni caso, viene controllato e aggiornato, se necessario, durante la fase di preinvio.

Versioni precedenti (Android 12 e versioni precedenti)

Utilizza lo strumento build_abi.sh come segue:

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

In questo esempio, build.config.device deve includere le seguenti opzioni di configurazione:

  • vmlinux

    Deve essere presente nell'elenco FILES. A questo scopo, puoi includere build.config.aarch64.

  • KMI_SYMBOL_LIST

    Deve essere impostato e indirizzato all'elenco di simboli KMI da aggiornare.

Dopo aver aggiornato l'elenco dei simboli dei dispositivi, devi anche applicare queste modifiche alla compilazione GKI (common/build.config.gki.aarch64):

  • Copia l'elenco dei simboli aggiornato in common/android/abi_gki_aarch64_<device>.

  • Verifica che android/abi_gki_aarch64_<device> sia incluso in ADDITIONAL_KMI_SYMBOL_LISTS in common/build.config.gki.aarch64.

  • Invia l'aggiornamento dell'elenco di simboli ad ACK.