So arbeiten Sie mit Symbollisten

Um die Oberfläche von Symbolen und Typen zu reduzieren, die stabil gehalten werden müssen, verfügt der GKI-Kernel über eine Funktion, um exportierte Symbole auf nur diejenigen zu beschränken, die von Modulen benötigt werden. Für extern kompilierte Module benötigen Sie eine Liste der verwendeten Symbole, damit sie vom GKI-Kernel exportiert werden können. Beispielsweise werden Symbole, die von Modulen für Cuttlefish verwendet werden, in android/abi_gki_aarch64_virtual_device gespeichert.

Fügen Sie ein Ziel für die Symbollistengenerierung hinzu

Symbollisten werden vom Ziel kernel_abi generiert. Fügen Sie dieses Ziel mit den folgenden Optionen zum Gerät BUILD.bazel hinzu:

  • name

    Sollte das Format <kernel_build>_abi haben.

  • kernel_build

    Sollte den Namen des Geräts kernel_build target enthalten.

Sie können auch die folgenden Optionen nutzen:

  • kernel_modules

    Liste der Ziele für Out-of-Tree- Module. In-Tree- Module sollten hier nicht enthalten sein. Weitere Informationen finden Sie unter Vorbereiten von In-Tree-Modulen für die Symbolextraktion .

  • kmi_symbol_list_add_only

    Diese Option verhindert das Entfernen nicht verwendeter Symbole. Das Entfernen von Symbolen ist nur zu bestimmten Zeiten während der KMI- Stabilisierung zulässig und nicht zulässig, sobald der KMI eingefroren ist.

    Dies ist auch nützlich, wenn Sie dieselbe Symbolliste für mehrere verschiedene Geräte verwenden. Auf diese Weise werden keine Symbole entfernt, die von Gerät A, aber nicht von Gerät B verwendet werden.

  • module_grouping

    Wenn True oder nicht angegeben, gruppiert die Symbolliste Symbole basierend auf den Kernelmodulen, die auf das Symbol verweisen. Andernfalls ist die Symbolliste einfach eine sortierte Liste von Symbolen, die von allen Kernelmodulen verwendet werden.

Siehe common-modules/virtual-device/BUILD.bazel zum Beispiel:

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

Siehe auch Referenzdokumentation zum kernel_abi -Ziel in Kleaf.

Bereiten Sie In-Tree-Module für die Symbolextraktion vor

Um In-Tree-Module für die Symbolextraktion vorzubereiten, listen Sie herstellerspezifische In-Tree-Module in einem module_outs Attribut des kernel_build Ziels auf. Ein Beispiel finden Sie unter _VIRT_COMMON_MODULES und seine Verwendung . Nehmen Sie keine GKI-Module in diese Liste auf.

Konfigurieren Sie diese Module als unsigned , andernfalls ist die Symbolliste möglicherweise leer. Fügen Sie dazu diese Zeile zu Ihren Kernel-Konfigurationsfragmenten hinzu:

# CONFIG_MODULE_SIG_ALL is not set

Siehe zum Beispiel common-modules/virtual-device/virtual_device_core.fragment .

Fügen Sie dem Gerätekernel-Build eine Gerätesymbolliste hinzu

Fügen Sie das Attribut kmi_symbol_list zum Ziel kernel_build hinzu, das im Gerät BUILD.bazel definiert ist. Der Name der Symbolliste sollte das Format //common:android/abi_gki_<arch>_<device> haben. Siehe common-modules/virtual-device/BUILD.bazel , zum Beispiel:

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

Erstellen und übermitteln Sie eine erste Symbolliste

Erstellen Sie eine leere Symbolliste unter common/android/abi_gki_<arch>_<device> . Für das obige Beispiel wäre der Befehl:

touch common/android/abi_gki_aarch64_virtual_device

Fügen Sie diese Datei zu additional_kmi_symbol_lists des Basis-GKI-Kernel-Builds hinzu. Beispielsweise wird //common:android/abi_gki_aarch64_virtual_device zur Dateigruppe aarch64_additional_kmi_symbol_lists hinzugefügt, die in common/BUILD.bazel deklariert ist.

Aktualisieren Sie die Gerätesymbolliste, um die neue Symbolliste zu füllen, und senden Sie sie an das Android Common Kernel-Repository.

Aktualisieren Sie eine Gerätesymbolliste

Alle Kernel-Symbole, die von Modulen in module_outs von kernel_build und kernel_modules von kernel_abi verwendet werden, sollten in der Symbolliste enthalten sein. Dies kann durch Ausführen des kernel_abi -Ziels mit dem Suffix _update_symbol_list erfolgen. Der folgende Befehl aktualisiert beispielsweise die Symbolliste für //common-modules/virtual-device:virtual_device_aarch64 :

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

Senden Sie eine Aktualisierung der Symbolliste an ACK

Senden Sie einen Patch mit der Änderung der Symbolliste an den Android Common Kernel- Gerrit, um die neuen Symbole in das KMI aufzunehmen.

Die Commit-Nachricht sollte eine Liste der hinzugefügten oder entfernten Symbole enthalten. Sie können diese Liste entweder manuell für eine kleine Aktualisierung der Symbolliste schreiben oder den Bericht $DIST_DIR/abi.report.short verwenden, nachdem Sie die Referenz-ABI-Darstellung aktualisiert haben .

Während die Aktualisierung der Referenz-ABI-Darstellung vor dem Senden einer Symbollistenaktualisierung nicht erforderlich ist, können dadurch zusätzliche Schritte vor der Übermittlung entfallen und die Änderung schneller zur Übermittlung bereit sein. In jedem Fall wird es im Vorfeld der Einreichung überprüft und ggf. aktualisiert.

Ältere Versionen (Android 12 und niedriger)

Verwenden Sie das Tool build_abi.sh wie folgt:

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

In diesem Beispiel muss build.config.device diese Konfigurationsoptionen enthalten:

  • vmlinux

    Muss Teil der FILES Liste sein. Dies kann durch Einbinden von build.config.aarch64 erfolgen.

  • KMI_SYMBOL_LIST

    Muss zum Aktualisieren festgelegt und auf die KMI-Symbolliste verwiesen werden.

Nach der Aktualisierung der Gerätesymbolliste müssen Sie diese Änderungen auch im GKI-Build ( common/build.config.gki.aarch64 ) widerspiegeln:

  • Kopieren Sie die aktualisierte Symbolliste nach common/android/abi_gki_aarch64_<device> .

  • Überprüfen Sie, ob android/abi_gki_aarch64_<device> in ADDITIONAL_KMI_SYMBOL_LISTS in common/build.config.gki.aarch64 enthalten ist.

  • Aktualisierung der Symbolliste an ACK senden .