Lavorare con gli elenchi di simboli

Per ridurre la superficie di simboli e tipi che devono essere mantenuti stabili, il kernel GKI ha funzionalità per limitare i simboli esportati solo a quelli necessari per i moduli. Per i moduli compilati esternamente, devi avere un elenco di simboli utilizzati per consentire la loro esportazione da parte del kernel GKI. Ad esempio, i simboli utilizzati dai moduli per Cuttlefish sono archiviati in gki/aarch64/symbols/virtual_device.

Aggiungere una destinazione per la generazione dell'elenco di simboli

Gli elenchi di simboli vengono generati dalla destinazione kernel_abi. Aggiungi questa destinazione a BUILD.bazel del dispositivo con le seguenti opzioni:

  • name

    Deve essere nel formato <kernel_build>_abi.

  • kernel_build

    Deve contenere il nome della destinazione kernel_build del dispositivo.

Puoi anche utilizzare le seguenti opzioni:

  • kernel_modules

    Elenco delle destinazioni per i moduli out-of-tree. I moduli in-tree 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 di KMI e non è consentita una volta che KMI è bloccato.

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

  • module_grouping

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

Vedi common-modules/virtual-device/BUILD.bazel per esempio:

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 sulla destinazione 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 della destinazione kernel_build. Per un esempio, vedi _VIRT_COMMON_MODULES e il relativo utilizzo. Non includere i moduli GKI in questo elenco.

Configura questi moduli in modo che non siano firmati, altrimenti l'elenco di simboli potrebbe essere vuoto. A questo scopo, 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 alla destinazione kernel_build definita in BUILD.bazel del dispositivo. Il nome dell'elenco di simboli deve essere nel formato di //common:gki/<arch>/symbols/<device>.

Vedi common-modules/virtual-device/BUILD.bazel, per esempio:

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

Creare e inviare un elenco di simboli iniziale

Crea un elenco di simboli vuoto in common/gki/<arch>/symbols/<device>. Per l'esempio precedente, il comando è:

touch common/gki/aarch64/symbols/virtual_device

Aggiungi questo file a additional_kmi_symbol_lists della build del kernel GKI di base. Ad esempio, //common:gki/aarch64/symbols/virtual_device viene aggiunto al aarch64_additional_kmi_symbol_lists filegroup, dichiarato in common/BUILD.bazel.

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

Aggiornare un elenco di simboli del dispositivo

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 di simboli. Per farlo, esegui la destinazione 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

Inviare un aggiornamento dell'elenco di simboli ad ACK

Invia una patch con la modifica dell'elenco di simboli a gerrit del kernel comune di Android per rendere i nuovi simboli parte di KMI.

Il messaggio di 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 $DIST_DIR/abi_stgdiff/abi.report.short report dopo aver aggiornato la rappresentazione ABI di riferimento.

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

Utilizzare gli elenchi di simboli (Android 13)

Android 13 supporta sia Kleaf sia gli script di build precedenti, quindi puoi gestire gli elenchi di simboli come descritto nelle sezioni precedenti o come descritto nella sezione seguente.

Utilizzare gli elenchi di simboli (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 queste opzioni di configurazione:

  • vmlinux

    Deve far parte dell'elenco FILES. Per farlo, includi build.config.aarch64.

  • KMI_SYMBOL_LIST

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

Dopo aver aggiornato l'elenco di simboli del dispositivo, devi anche riflettere queste modifiche nella build GKI (common/build.config.gki.aarch64):

  • Copia l'elenco di 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.