シンボルリストの使用方法

安定的に維持する必要のあるシンボルやタイプのサーフェスを減らすために、GKI カーネルには、エクスポートされるシンボルを、モジュールが必要とするものだけに制限する機能があります。外部でコンパイルされたモジュールの場合、GKI カーネルでエクスポートできるようにするためには、使用するシンボルのリストが必要です。たとえば、Cuttlefish のモジュールが使用するシンボルは、android/abi_gki_aarch64_virtual_device に保存されています。

シンボルリスト生成のためのターゲットを追加する

シンボルリストは kernel_abi ターゲットによって生成されます。以下のオプションを使用して、このターゲットをデバイスの BUILD.bazel に追加します。

name

<kernel_build>_abi の形式でなければなりません。
kernel_build

デバイスの kernel_build ターゲットの名前を含める必要があります。

また、以下のオプションも使用できます。

kernel_modules

「ツリー外」モジュールのターゲットのリスト。「ツリー内」モジュールをここに含めることはできません。シンボル抽出用にツリー内モジュールを準備するをご覧ください。
kmi_symbol_list_add_only

このオプションを指定することで、使用されていないシンボルが削除されるのを防ぎます。シンボルの削除は、KMI 安定化中の特定のタイミングにのみ許可され、一度 KMI が固定されると許可されません。

これは複数の異なるデバイスで同じシンボルリストを使用する際にも役立ちます。デバイス B では使用されていないシンボルが、デバイス A で使用されている場合に削除されることがなくなります。
module_grouping

True または指定されていない場合、シンボルリストは、シンボルを参照するカーネルモジュールに基づいてシンボルをグループ化します。それ以外の場合、シンボルリストは、すべてのカーネルモジュールで使用されているシンボルを並べ替えたリストとなります。

たとえば、common-modules/virtual-device/BUILD.bazel を参照してください。

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

また、Kleaf の kernel_abi ターゲットに関するリファレンスドキュメントもご覧ください。

シンボル抽出用にツリー内モジュールを準備する

シンボル抽出用にツリー内モジュールを準備するには、kernel_build ターゲットの module_outs 属性に、ベンダー固有のツリー内モジュールをリストします。例として、_VIRT_COMMON_MODULES とその使用方法をご覧ください。このリストに GKI モジュールは含めないでください。

これらのモジュールは署名なしで構成してください。署名があると、シンボルリストが空になります。署名なしで構成するには、カーネルの構成フラグメントに、次の行を追加します。

# CONFIG_MODULE_SIG_ALL is not set

たとえば、common-modules/virtual-device/virtual_device_core.fragment を参照してください。

デバイスカーネルビルドにデバイスシンボルリストを追加する

デバイスの BUILD.bazel で定義された kernel_build ターゲットに属性 kmi_symbol_list を追加します。シンボルリストの名前は、//common:android/abi_gki_<arch>_<device> の形式でなければなりません。たとえば、common-modules/virtual-device/BUILD.bazel を参照してください。

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

初期シンボルリストを作成して送信する

common/android/abi_gki_<arch>_<device> に空のシンボルリストを作成します。上記の例の場合、コマンドは次のようになります。

touch common/android/abi_gki_aarch64_virtual_device

このファイルをベース GKI カーネルビルドの additional_kmi_symbol_lists に追加します。たとえば、//common:android/abi_gki_aarch64_virtual_device は、common/BUILD.bazel で宣言された aarch64_additional_kmi_symbol_lists ファイルグループに追加されます。

デバイスシンボルリストを更新して新しいシンボルリストを作成し、Android 共通カーネルリポジトリに送信します。

デバイスシンボルリストを更新する

kernel_build の module_outs および kernel_abi の kernel_modules 内のモジュールに使用されるコアカーネルシンボルは、すべてシンボルリストに含める必要があります。これは、_update_symbol_list サフィックスをつけて kernel_abi ターゲットを実行することで可能です。たとえば、次のコマンドで //common-modules/virtual-device:virtual_device_aarch64 のシンボルリストを更新します。

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

シンボルリストの更新を ACK に送信する

シンボルリストの変更を含むパッチを Android 共通カーネル gerrit に送信し、新しいシンボルを KMI に含めます。

コミットメッセージには、追加されたシンボルまたは削除されたシンボルのリストを含める必要があります。シンボルリストの更新内容が少ない場合、手動でリストを作成することも、参照 ABI 表現の更新後に $DIST_DIR/abi.report.short レポートを使用することもできます。

シンボルリストの更新を送信する前に参照 ABI 表現を更新することは必須ではありませんが、余分な presubmit 手順が不要になるため、更新をより迅速に送信できます。いずれの場合にも、必要に応じて presubmit 中にチェックされ、更新されます。

以前のバージョン（Android 12 以前）

次のように build_abi.sh ツールを使用します。

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

この例では、build.config.device に次の構成オプションを含める必要があります。

vmlinux

FILES リストに含める必要があります。これは、build.config.aarch64 を含めることで対応できます。
KMI_SYMBOL_LIST

更新する KMI シンボルリストを指定するように設定する必要があります。

デバイスシンボルリストを更新した後は、これらの変更を GKI ビルド（common/build.config.gki.aarch64）に反映させることも必要です。

更新されたシンボルリストを common/android/abi_gki_aarch64_<device> にコピーします。
android/abi_gki_aarch64_<device> が common/build.config.gki.aarch64 の ADDITIONAL_KMI_SYMBOL_LISTS に含まれていることを確認します。
シンボルリストの更新を ACK に送信します。