Exécuter la surveillance des ABI

Cette page explique comment créer des représentations ABI du noyau Android et exécuter la surveillance ABI. Elle s'applique à Android 16 et versions ultérieures. Pour les versions antérieures, consultez la section Surveiller l'ABI des versions précédentes du noyau.

Consultez également la documentation de référence pour Kleaf : Surveiller l'ABI (GKI) et Surveiller l'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 $DIST_DIR/abi.stg, ainsi que le noyau et les modules créés. $DIST_DIR est défini par défaut sur out_abi/kernel_aarch64_abi_dist/dist.

Vous pouvez spécifier des arguments supplémentaires pour l'outil ABI à la fin de la commande après --. Par exemple, pour modifier la destination des artefacts ABI et de compilation, vous pouvez utiliser l'option --destdir :

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

Analyser les différences 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 précédente, analyse et signale toutes les différences ABI trouvées entre la compilation et la représentation de référence située dans common/gki/aarch64/abi.stg (définie dans BUILD.bazel). Ces différences sont imprimées à la fin de la compilation, comme illustré dans 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é dans $DIST_DIR/abi_stgdiff/abi.report.short, ainsi que des rapports 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, ne comportent 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 ABI de référence

Toute modification affectant l'ABI du noyau, comme une mise à jour de la liste des symboles, doit être reflétée dans la représentation ABI de référence (common/gki/aarch64/abi.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 toutes les opérations de l'étape Analyser les différences ABI et met également à jour la représentation de référence dans les sources. L'ABI mis à jour peut ensuite être importé dans le même commit que la modification. Incluez les différences ABI du rapport dans $DIST_DIR/abi_stgdiff/abi.report.short dans le message de commit.

Surveillance ABI et cibles d'appareils

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

Consultez également la documentation de référence pour Kleaf: Surveiller l'ABI (appareil).

Surveiller l'ABI des versions précédentes du noyau (Android 15 et versions antérieures)

Pour les versions précédentes du noyau, les instructions de compilation et de surveillance de l'ABI diffèrent comme suit.

Android 15 et 14

Les instructions sont pour la plupart identiques à celles d'Android 16, à l'exception du fait que la représentation ABI de référence est common/android/abi_gki_aarch64.stg et que $DIST_DIR est défini par défaut sur out_abi/kernel_aarch64/dist.

Android 13

Android 13 peut être créé avec Kleaf ou avec des scripts de compilation hérités.

Pour Kleaf, les instructions sont les mêmes que pour Android 14, à l'exception du fait que le format ABI est XML et que la représentation ABI de référence est common/android/abi_gki_aarch64.xml.

Pour les scripts de compilation hérités, les instructions sont les mêmes que pour Android 12.

Android 12 et versions antérieures

Le format ABI est XML et la représentation ABI de référence est common/android/abi_gki_aarch64.xml.

Ces noyaux utilisent build.sh au lieu de Kleaf. Pour la surveillance ABI, vous devez utiliser build_abi.sh, qui accepte les mêmes variables d'environnement pour personnaliser la compilation 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 ABI dans le OUT_DIR (qui est out_abi par défaut) sous-répertoire et équivaut à la //common:kernel_aarch64_abi_dist cible de Kleaf (voir Créer le noyau et les artefacts ABI).

La représentation ABI de référence est stockée dans android/abi_gki_aarch64.xml, comme défini par la variable ABI_DEFINITION dans common/build.config.gki.aarch64.

Si vous devez mettre à jour la représentation ABI du noyau, 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

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

L'option --update remplace la représentation ABI de référence. Elle effectue également la mise à jour de la liste des symboles lorsque BUILD_CONFIG est utilisé pour un appareil avec KMI_SYMBOL_LIST configuré.