ABI モニタリングの実行

このページでは、Android カーネル ABI 表現をビルドして ABI モニタリングを実行する方法について説明します。この方法は、Android 14 以降に適用できます。それより前のバージョンについては、以前のカーネル バージョンをご覧ください。

また、Kleaf のリファレンス ドキュメント: ABI モニタリングのサポート(GKI)および ABI モニタリングのサポート(デバイス)もご覧ください。

カーネルとその ABI 表現をビルドする

GKI ソースをダウンロードしたら、次のコマンドを実行して GKI カーネルと ABI アーティファクトをビルドします。

tools/bazel run //common:kernel_aarch64_abi_dist

このコマンドは、現在の ABI 表現をビルドし、ビルドされたカーネルとモジュールとともに out_abi/kernel_aarch64/dist/abi.stg にコピーします。

コマンドの末尾で -- の後に ABI ツールの追加の引数を指定できます。たとえば、ABI とビルド アーティファクトの保存先を変更するには、--dist_dir オプションを使用します。

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

ビルドと参照表現の間で ABI の違いを分析する

上記のコマンドで実行される //common:kernel_aarch64_abi_dist ターゲットは、ビルドと common/android/abi_gki_aarch64.stgBUILD.bazel で定義)にある参照表現との間で ABI の違いがあるかどうかを分析し、見つかった場合は相違点をレポートします。この相違点はビルドの最後に出力されます。次に例を示します。

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

出力されるレポートは、out_abi/kernel_aarch64/dist/abi_stgdiff/abi.report.short にあるビルド アーティファクトから取得されるもので、他の形式のレポートとともに表示されます。

自動化ではビルドコマンドの終了コードが使用されますが、相違点が見つかった場合、終了コードはゼロ以外の値になります。

なお、開発段階のブランチ(android-mainline など)には参照 ABI 表現がない点に注意してください。参照表現がないと、//common:kernel_aarch64_abi_dist は相違を検出できません。

参照 ABI 表現を更新する

カーネル ABI に影響する変更(シンボルリストの更新など)がある場合は、参照 ABI 表現(BUILD.bazel で定義された common/android/abi_gki_aarch64.stg)に反映しなければなりません。それには、次のコマンドを実行する必要があります。

​​tools/bazel run //common:kernel_aarch64_abi_update

このコマンドは、ABI の違いを分析する手順のすべてを実行し、さらに、ソースの参照表現を更新します。更新された ABI は、その後、変更と同じコミットでアップロードされます。$DIST_DIR/abi.report.short のレポートにある ABI の相違点をコミット メッセージに含めてください。

ABI モニタリングとデバイス ターゲット

ABI モニタリングはコアカーネルのビルド ターゲットに対してのみ構成する必要があります。GKI カーネルで直接コンパイルする混在型のビルド構成(base_kernel を定義するビルド構成)で必要なのは、デバイス シンボルリストのトラッキングのサポートを追加することだけです。この GKI ビルドを使って ABI 定義を更新する必要があります

Kleaf のリファレンス ドキュメント: ABI モニタリングのサポート(デバイス)もご覧ください。

以前のカーネル バージョン

Android 13

ビルド手順は Android 14 とほぼ同じですが、ABI の形式が XML である点と、参照 ABI 表現が common/android/abi_gki_aarch64.xml である点が異なります。

Android 13 以前

Android 13 では、ABI の形式は XML です。

以前のカーネルは Kleaf ではなく build.sh を使用しています。ABI モニタリングには build_abi.sh を使用する必要があります。build_abi.sh はビルドをカスタマイズするために build.sh と同じ環境変数を受け入れます。次に例を示します。

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

このコードはカーネルをビルドし、ABI 表現を OUT_DIR(デフォルトで out_abi)サブディレクトリに抽出します。Kleaf の //common:kernel_aarch64_abi_dist ターゲットに相当します(カーネルと ABI アーティファクトをビルドするを参照)。

参照 ABI 表現は、common/build.config.gki.aarch64ABI_DEFINITION 変数で定義された android/abi_gki_aarch64.xml に保存されます。

カーネルの ABI 表現を更新する必要がある場合は、--update および --print-report オプションを使用するのが最も便利な方法です。

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

--print-report は、現在のファイルと新しく生成される ABI の間の ABI の相違点を出力します。

--update オプションにより、参照 ABI 表現は上書きされます。また、KMI_SYMBOL_LIST が設定されているデバイスの BUILD_CONFIG を使用する場合は、シンボルリストの更新も行われます。