Exécuter la surveillance des ABI

Cette page explique comment créer des représentations ABI du kernel Android et exécuter la surveillance ABI. Il s'applique à Android 14 et plus élevée. Pour les versions antérieures, consultez la section Versions antérieures du kernel.

Consultez également la documentation de référence de Kleaf : Prise en charge de la surveillance des ABI (GKI) et Prise en charge de la surveillance des ABI (appareil).

Créer le noyau et sa représentation ABI

Après avoir téléchargé les sources GKI, exécutez la commande suivante pour créer le noyau GKI et les artefacts ABI :

tools/bazel run //common:kernel_aarch64_abi_dist

Cette commande crée la représentation ABI actuelle et la copie dans out_abi/kernel_aarch64/dist/abi.stg, ainsi que le noyau et les modules compilés.

Vous pouvez spécifier des arguments supplémentaires pour les outils d'ABI à la fin de la commande après le --. Par exemple, pour modifier la destination de l'ABI et compiler des artefacts, vous devez vous pouvez utiliser l'option --dist_dir:

tools/bazel run //common:kernel_aarch64_abi_dist -- --dist_dir=out/dist

Analyser les différences d'ABI entre la compilation et une représentation de référence

La cible //common:kernel_aarch64_abi_dist, exécutée dans la commande ci-dessus, analyse et signale les différences d'ABI détectées entre la compilation et la référence représentation située à l'emplacement common/android/abi_gki_aarch64.stg (définie dans BUILD.bazel). Ces différences sont imprimées à la fin du build, comme indiqué dans le l'exemple suivant:

INFO: From [stg] Comparing Kernel ABI @//common:kernel_aarch64_abi_diff:
INFO: ABI DIFFERENCES HAVE BEEN DETECTED!

Le rapport imprimé provient de l'artefact de compilation situé à l'adresse out_abi/kernel_aarch64/dist/abi_stgdiff/abi.report.short, ainsi que les rapports dans dans d'autres formats.

L'automatisation doit utiliser le code de sortie de la commande de compilation, qui est différent de zéro si des différences sont détectées.

Notez que les branches de la phase de développement, y compris android-mainline, n'ont aucune représentation ABI de référence. Sans cela, //common:kernel_aarch64_abi_dist ne détectera aucune différence.

Mettre à jour la représentation de l'ABI de référence

Tout changement affectant l'ABI du noyau, comme une mise à jour de la liste des symboles, doit être reflété dans la représentation de l'ABI de référence (common/android/abi_gki_aarch64.stg, définie dans BUILD.bazel). Pour ce faire, vous devez exécuter la commande suivante:

​​tools/bazel run //common:kernel_aarch64_abi_update

Cette commande effectue tout ce qui est indiqué dans l'étape Analyser les différences ABI et met également à jour la représentation de référence dans les sources. L'ABI mise à jour peut ensuite être importée dans le même commit que la modification. Incluez les différences ABI du rapport dans $DIST_DIR/abi.report.short dans le message de commit.

Surveillance de l'ABI et cibles d'appareils

La surveillance ABI ne doit être configurée que pour les cibles de compilation du noyau principal. Les configurations de compilation mixtes (celles qui définissent base_kernel) qui compilent directement avec le noyau GKI ne doivent ajouter la prise en charge du suivi de la liste des symboles de l'appareil que. La définition de l'ABI doit être mise à jour à l'aide du build GKI.

Consultez également la documentation de référence de Kleaf : Prise en charge de la surveillance ABI (appareil).

Anciennes versions du noyau

Android 13

Les instructions de compilation sont pour la plupart les mêmes que Android 14, sauf que le format de l'ABI est XML et la représentation de l'ABI de référence est common/android/abi_gki_aarch64.xml.

Android 13 ou version antérieure

Comme dans Android 13, le format ABI est XML.

Les noyaux plus anciens utilisent build.sh au lieu de Kleaf. Pour surveiller les ABI, utilisez build_abi.sh, qui accepte les mêmes variables d'environnement pour personnaliser en tant que build.sh. Exemple :

BUILD_CONFIG=common/build.config.gki.aarch64 build/build_abi.sh

Cela crée le noyau et extrait la représentation de l'ABI dans OUT_DIR. (out_abi par défaut) et qui équivaut au sous-répertoire Cible //common:kernel_aarch64_abi_dist de Kleaf (voir Compiler les artefacts du noyau et de l'ABI).

La représentation de l'ABI de référence est stockée dans android/abi_gki_aarch64.xml en tant que définie par la variable ABI_DEFINITION dans common/build.config.gki.aarch64.

Si vous devez mettre à jour la représentation de l'ABI du kernel, le moyen le plus pratique consiste à utiliser les options --update et --print-report :

BUILD_CONFIG=common/build.config.gki.aarch64 build/build_abi.sh --update --print-report

--print-report affiche les différences d'ABI entre le fichier tel qu'il existe et un ABI nouvellement généré.

L'option --update écrase la représentation ABI de référence. Elle fait également la mise à jour de la liste de symboles lorsque vous utilisez BUILD_CONFIG pour un appareil sur lequel KMI_SYMBOL_LIST est configuré.