Utiliser les listes de symboles

Pour réduire la surface des symboles et des types qui doivent être maintenus stables, le kernel GKI peut 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 exportation 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 BUILD.bazel de l'appareil avec les options suivantes:

  • name

    Format requis : <kernel_build>_abi.

  • kernel_build

    Doit contenir le nom de la cible kernel_build de l'appareil.

Vous pouvez également utiliser les options suivantes:

  • kernel_modules

    Liste des cibles des modules hors du nœud. Les modules in-tree ne doivent pas être inclus ici. Consultez la section Préparer les modules dans l'arborescence à l'extraction de symboles.

  • kmi_symbol_list_add_only

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

    Cela est également utile lorsque vous utilisez la même liste de symboles pour plusieurs appareils différents. Ainsi, les symboles utilisés par l'appareil A, mais pas par l'appareil B, ne seront pas supprimés.

  • module_grouping

    Si la valeur est True ou non spécifiée, la liste des symboles regroupe les symboles en fonction des modules du noyau qui les référencent. Sinon, la liste de symboles est une liste triée de symboles utilisés par tous les modules du noyau.

Consultez 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 à l'extraction de symboles, listez les modules dans l'arborescence spécifiques au fournisseur dans un attribut module_outs de la cible kernel_build. Pour voir un exemple, consultez _VIRT_COMMON_MODULES et son utilisation. N'incluez pas les modules GKI dans cette liste.

Configurez ces modules pour qu'ils soient non signés, sinon la liste des symboles risque d'être vide. Pour ce faire, ajoutez cette ligne à vos fragments de configuration du kernel:

# CONFIG_MODULE_SIG_ALL is not set

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

Ajouter une liste de symboles d'appareil à la compilation du noyau de l'appareil

Ajoutez l'attribut kmi_symbol_list à la cible kernel_build définie dans l'appareil BUILD.bazel. Le nom de la liste de symboles doit être au format //common:android/abi_gki_<arch>_<device>. Consultez 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 envoyer une liste de symboles initiale

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

touch common/android/abi_gki_aarch64_virtual_device

Ajoutez ce fichier à additional_kmi_symbol_lists du build de base du kernel 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 d'appareils pour remplir la nouvelle liste de symboles, puis envoyez-la au dépôt Android Common Kernel.

Mettre à jour une liste de symboles d'appareil

Tous les symboles de noyau de base 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. Pour ce faire, exécutez 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 des symboles à ACK

Envoyez un correctif avec la modification de la liste des symboles au dépôt Gerrit du kernel commun Android pour intégrer les nouveaux symboles au KMI.

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

Bien que la mise à jour de la représentation ABI de référence avant d'envoyer une mise à jour de la liste de symboles ne soit pas obligatoire, elle peut éliminer des étapes supplémentaires avant l'envoi et permettre de préparer plus rapidement la modification. Dans tous les cas, il est 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 les options de configuration suivantes:

  • vmlinux

    Doit faire partie de la liste FILES. Pour ce faire, incluez build.config.aarch64.

  • KMI_SYMBOL_LIST

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

Après avoir mis à jour la liste des symboles d'appareils, vous devez également refléter ces modifications dans le build GKI (common/build.config.gki.aarch64):