Comment travailler avec des listes de symboles

Pour réduire la surface des symboles et des types qui doivent être maintenus stables, le noyau GKI dispose d'une fonctionnalité permettant de limiter les symboles exportés à ceux qui sont nécessaires aux modules. Pour les modules compilés en externe, vous devez disposer d'une liste de symboles utilisés pour permettre leur export par le noyau GKI. Par exemple, les symboles utilisés par les modules pour Cuttlefish sont stockés dans android/abi_gki_aarch64_virtual_device .

Ajouter une cible pour la génération de la liste de symboles

Les listes de symboles sont générées par la cible kernel_abi . Ajoutez cette cible au périphérique BUILD.bazel avec les options suivantes :

  • name

    Doit être au format <kernel_build>_abi .

  • kernel_build

    Doit contenir le nom du périphérique cible kernel_build .

Vous pouvez également utiliser les options suivantes :

  • kernel_modules

    Liste des cibles des modules hors arborescence . Les modules dans l'arborescence ne devraient pas être inclus ici. Reportez-vous à Préparer les modules dans l'arborescence pour l'extraction de symboles .

  • kmi_symbol_list_add_only

    Cette option empêche la suppression des symboles inutilisés. La suppression des symboles n'est autorisée qu'à des moments précis pendant la stabilisation du KMI et n'est pas autorisée une fois le KMI gelé .

    Ceci est également utile lorsque vous utilisez la même liste de symboles pour plusieurs appareils différents. De cette façon, il ne supprimera pas les symboles utilisés par le périphérique A mais pas par le périphérique B.

  • module_grouping

    Si True ou non spécifié, la liste des symboles regroupera les symboles en fonction des modules du noyau qui font référence au symbole. Sinon, la liste des symboles sera simplement une liste triée de symboles utilisés par tous les modules du noyau.

Voir common-modules/virtual-device/BUILD.bazel par exemple :

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

Consultez également la documentation de référence sur la cible kernel_abi dans Kleaf.

Préparer les modules dans l'arborescence pour l'extraction de symboles

Pour préparer les modules dans l'arborescence pour l'extraction de symboles, répertoriez les modules dans l'arborescence spécifiques au fournisseur dans un attribut module_outs de la cible kernel_build . Voir _VIRT_COMMON_MODULES et son utilisation pour un exemple. N'incluez pas les modules GKI dans cette liste.

Configurez ces modules pour qu'ils soient unsigned , sinon la liste des symboles pourrait être vide. Pour ce faire, ajoutez cette ligne aux fragments de configuration de votre noyau :

# CONFIG_MODULE_SIG_ALL is not set

Voir common-modules/virtual-device/virtual_device_core.fragment par exemple.

Ajouter une liste de symboles de périphérique à la version du noyau du périphérique

Ajoutez l'attribut kmi_symbol_list à la cible kernel_build définie dans le périphérique BUILD.bazel . Le nom de la liste de symboles doit être au format //common:android/abi_gki_<arch>_<device> . Voir common-modules/virtual-device/BUILD.bazel , par exemple :

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

Créer et soumettre une liste initiale de symboles

Créez une liste de symboles vide sur common/android/abi_gki_<arch>_<device> . Pour l'exemple ci-dessus, la commande serait :

touch common/android/abi_gki_aarch64_virtual_device

Ajoutez ce fichier à additional_kmi_symbol_lists de la version de base du noyau GKI. Par exemple, //common:android/abi_gki_aarch64_virtual_device est ajouté au groupe de fichiers aarch64_additional_kmi_symbol_lists , déclaré dans common/BUILD.bazel .

Mettez à jour la liste des symboles de l'appareil pour remplir la nouvelle liste de symboles et envoyez-la au référentiel Android Common Kernel.

Mettre à jour une liste de symboles d'appareil

Tous les symboles du noyau utilisés par les modules dans module_outs de kernel_build et kernel_modules de kernel_abi doivent être inclus dans la liste des symboles. Cela peut être fait en exécutant la cible kernel_abi avec le suffixe _update_symbol_list . Par exemple, la commande suivante met à jour la liste des symboles pour //common-modules/virtual-device:virtual_device_aarch64 :

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

Envoyer une mise à jour de la liste de symboles à ACK

Envoyez un correctif avec la modification de la liste des symboles au gerrit Android Common Kernel pour intégrer les nouveaux symboles au KMI.

Le message de validation doit inclure une liste de symboles ajoutés ou supprimés. Vous pouvez soit écrire cette liste manuellement pour une petite mise à jour de la liste de symboles, soit utiliser le rapport $DIST_DIR/abi.report.short après avoir mis à jour la représentation ABI de référence .

Bien que la mise à jour de la représentation ABI de référence avant l'envoi d'une mise à jour de la liste de symboles ne soit pas requise, cela peut éliminer des étapes supplémentaires de pré-soumission et rendre la modification prête à être soumise plus rapidement. Dans tous les cas, il sera vérifié et mis à jour si nécessaire lors de la présoumission.

Anciennes versions (Android 12 et versions antérieures)

Utilisez l'outil build_abi.sh comme suit :

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

Dans cet exemple, build.config.device doit inclure ces options de configuration :

  • vmlinux

    Doit faire partie de la liste FILES . Cela peut être fait en incluant build.config.aarch64 .

  • KMI_SYMBOL_LIST

    Doit être défini et pointé sur la liste des symboles KMI à mettre à jour.

Après avoir mis à jour la liste des symboles de périphérique, vous devez également refléter ces modifications dans la version GKI ( common/build.config.gki.aarch64 ) :

  • Copiez la liste de symboles mise à jour dans common/android/abi_gki_aarch64_<device> .

  • Vérifiez que android/abi_gki_aarch64_<device> est inclus dans ADDITIONAL_KMI_SYMBOL_LISTS dans common/build.config.gki.aarch64 .

  • Envoyer la mise à jour de la liste de symboles à ACK .