ベンダー APEX

APEX ファイル形式を使用すると、低レベルの Android OS モジュールをパッケージ化してインストールできます。ネイティブサービスやライブラリ、HAL 実装、ファームウェア、構成ファイルなどのコンポーネントを独立してビルドでき、インストールできます。

ベンダー APEX は、ビルドシステムによって自動的に /vendor パーティションにインストールされます。他のパーティションの APEX と同様、実行時に apexd によって有効化されます。

ユースケース

ベンダーイメージのモジュール化

APEX により、ベンダーイメージの機能実装の自然なバンドルとモジュール化が容易になります。

ベンダーイメージが、個別にビルドされたベンダー APEX の組み合わせとしてビルドされている場合、デバイスメーカーは、デバイスで必要な特定のベンダー実装を簡単に選択できます。メーカーは、提供された APEX がいずれもニーズを満たさない場合や、新しいカスタムハードウェアがある場合、新しいベンダー APEX を作成することもできます。

たとえば OEM は、AOSP Wi-Fi 実装 APEX、SoC Bluetooth 実装 APEX、カスタム OEM テレフォニー実装 APEX でデバイスを構成できます。

ベンダー APEX がない場合、ベンダーコンポーネント間の依存関係が多い実装では、調整とトラッキングを慎重に行う必要があります。機能間通信の任意の点で、明確に定義されたインターフェースによってすべてのコンポーネント（構成ファイルと追加ライブラリを含む）を APEX にラップすることで、さまざまなコンポーネントの互換性が確保されます。

デベロッパーの反復処理

ベンダー APEX は、Wi-Fi HAL のような機能実装全体をベンダー APEX 内にバンドルすることで、ベンダーモジュールの開発時に、デベロッパーによる反復処理を高速化します。デベロッパーは、ベンダーイメージ全体を再ビルドする代わりに、ベンダー APEX をビルドして個別に push し、変更をテストできます。

これにより、主に 1 つの機能領域で作業し、その機能領域のみを反復する場合に、デベロッパーの反復サイクルが簡素化されてスピードアップします。

機能領域が APEX に自然にバンドルされると、その機能領域に対する変更のビルド、push、テストのプロセスが簡素化されます。たとえば APEX を再インストールすると、APEX に含まれるバンドルライブラリまたは構成ファイルが自動的に更新されます。

機能領域を APEX にバンドルすると、デバイスの動作不良があった場合のデバッグや復元も簡素化します。たとえば、新しいビルドでテレフォニーがうまく機能していない場合、デベロッパーは（フルビルドをフラッシュせずに）古いテレフォニー実装 APEX をデバイスにインストールし、正常な動作が復元するかどうかを確認できます。

ワークフローの例:

# Build the entire device and flash. OR, obtain an already-flashed device.
source build/envsetup.sh && lunch oem_device-userdebug
m
fastboot flashall -w

# Test the device.
... testing ...

# Check previous behavior using a vendor APEX from one week ago, downloaded from
# your continuous integration build.
... download command ...
adb install <path to downloaded APEX>
adb reboot
... testing ...

# Edit and rebuild just the APEX to change and test behavior.
... edit APEX source contents ...
m <apex module name>
adb install out/<path to built APEX>
adb reboot
... testing ...

例

基本情報

デバイスの要件、ファイル形式の詳細、インストール手順など、APEX の一般的な情報については、APEX ファイル形式のメインページをご覧ください。

Android.bp で vendor: true プロパティを設定すると、APEX モジュールはベンダー APEX になります。

apex {
  ..
  vendor: true,
  ..
}

バイナリと共有ライブラリ

APEX には、安定したインターフェースがある場合を除き、APEX ペイロード内に推移的依存関係が含まれます。

ベンダー APEX の依存関係の安定版ネイティブインターフェースには、stubs、ndk_library、または llndk_library を持つ cc_library があります。これらの依存関係はパッケージ化から除外され、依存関係は APEX マニフェストに記録されます。マニフェストは linkerconfig によって処理されるため、実行時に外部のネイティブ依存関係を利用できます。

/system パーティション内の APEX とは異なり、ベンダー APEX は通常、特定の VNDK バージョンに関連付けられます。VNDK ライブラリはリリース内の ABI の安定性を保証しているため、VNDK ライブラリを安定版として扱い、use_vndk_as_stable プロパティを使用して APEX から除外することでベンダー APEX のサイズを縮小できます。

以下のスニペットで、APEX にはバイナリ（my_service）と安定版でない依存関係（*.so ファイル）の両方が含まれます。my_service が libbase などの VNDK ライブラリでビルドされている場合でも、VNDK ライブラリは含まれません。その代わり、実行時に my_service はシステムが提供する VNDK ライブラリの libbase を使用します。

apex {
  ..
  vendor: true,
  use_vndk_as_stable: true,
  binaries: ["my_service"],
  ..
}

以下のスニペットの APEX には、前述のとおり、共有ライブラリ my_standalone_lib と安定版でない依存関係が含まれます。

apex {
  ..
  vendor: true,
  use_vndk_as_stable: true,
  native_shared_libs: ["my_standalone_lib"],
  ..
}

HAL 実装

HAL 実装を定義するには、次の例のように、ベンダー APEX 内で対応するバイナリとライブラリを提供します。

HAL 実装を完全にカプセル化するために、APEX は関連する VINTF フラグメントと init スクリプトも指定する必要があります。

VINTF フラグメント

VINTF フラグメントは、APEX 内に含まれるのではなく /vendor/etc/vintf にインストールされます。

標準の vintf_fragments プロパティを使用します。

apex {
  ..
  vendor: true,
  vintf_fragments: ["fragment.xml"],
  ..
}

init スクリプト

APEX には、（A）APEX ペイロード内のビルド済みテキストファイル、または（B）/vendor/etc の通常の init スクリプトという 2 つの方法で init スクリプトを含めることができます。同じ APEX に対して両方を設定できます。

APEX 内の init スクリプト:

prebuilt_etc {
  name: "myinit.rc",
  src: "myinit.rc"
}

apex {
  ..
  vendor: true,
  prebuilts: ["myinit.rc"],
  ..
}

APEX 内の init スクリプトには、service 定義のみを含めることができます。on <property> ディレクティブを含めることはできません。サービスがなんらかの条件に依存する必要がある場合は、init スクリプトを /vendor にインストールする必要があります。

/vendor の init スクリプト:

apex {
  ..
  vendor: true,
  init_rc: ["myinit.in.vendor.rc"],
  ..
}

init スクリプト内でのバイナリパスの参照には、APEX 内のパスを反映させる必要があります。init スクリプトのソースファイルでパスをハードコードするか、genrule を使用して既存のソースファイルから置き換えることができます。

ファームウェア

例:

バイブレーターサービスのファームウェア

次のように、prebuilt_firmware モジュールタイプでベンダー APEX にファームウェアを埋め込みます。

prebuilt_firmware {
  name: "my.bin",
  src: "path_to_prebuilt_firmware",
  vendor: true,
}

apex {
  ..
  vendor: true,
  prebuilts: ["my.bin"],  // installed inside APEX as /etc/firmware/my.bin
  ..
}

prebuilt_firmware モジュールは、APEX の <apex name>/etc/firmware ディレクトリにインストールされます。ueventd は /apex/*/etc/firmware ディレクトリをスキャンしてファームウェアモジュールを見つけます。

APEX の file_contexts は、実行時に ueventd がそれらのファイルにアクセスできるようにするために、ファームウェアペイロードエントリに適切なラベルを付ける必要があります。通常は、vendor_file ラベルで十分です。次に例を示します。

(/.*)? u:object_r:vendor_file:s0

カーネルモジュール

次のように、カーネルモジュールをベンダー APEX にビルド済みモジュールとして埋め込みます。

prebuilt_etc {
  name: "my.ko",
  src: "my.ko",
  vendor: true,
  sub_dir: "modules"
}

apex {
  ..
  vendor: true,
  prebuilts: ["my.ko"],  // installed inside APEX as /etc/modules/my.ko
  ..
}

APEX の file_contexts は、カーネルモジュールのペイロードエントリに適切なラベルを付ける必要があります。次に例を示します。

/etc/modules(/.*)? u:object_r:vendor_kernel_modules:s0

カーネルモジュールは明示的にインストールする必要があります。ベンダーパーティションにおける次の init スクリプトの例は、insmod を介したインストールを示しています。

my_init.rc:

on early-boot
  insmod /apex/myapex/etc/modules/my.ko
  ..

ランタイムリソースオーバーレイ

例:

Cuttlefish RRO

rros プロパティを使用して、ベンダー APEX にランタイムリソースオーバーレイを埋め込みます。

runtime_resource_overlay {
    name: "my_rro",
    soc_specific: true,
}

apex {
  ..
  vendor: true,
  rros: ["my_rro"],  // installed inside APEX as /overlay/my_rro.apk
  ..
}

その他の構成ファイル

ベンダー APEX は、ベンダー APEX でのビルド済みとしてベンダーパーティションに通常存在するその他のさまざまな構成ファイルをサポートしており、今後さらに追加される予定です。

例:

機能宣言の XML
- センサー HAL ベンダー APEX でのビルド済みとしてのセンサー機能 XML
入力構成ファイル
- 構成のみのベンダー APEX でのビルド済みとしてのタッチスクリーン構成

追加の開発機能

起動時の APEX 選択

例:

Cuttlefish Emulated Camera HAL APEX

デベロッパーは、同じ APEX 名とキーを共有する複数のバージョンのベンダー APEX をインストールし、永続 sysprop を使用して起動ごとに有効にするバージョンを選択することもできます。デベロッパーのユースケースによっては、adb install を使用して APEX の新しいコピーをインストールするよりも、こちらの方が簡単な場合があります。

ユースケースの例:

3 つのバージョンの Wi-Fi HAL ベンダー APEX をインストールする: QA チームは、あるバージョンを使用して手動テストまたは自動テストを行い、次に別のバージョンで再起動してテストをもう一度行い、最終結果を比較できます。
2 つのバージョンのカメラ HAL ベンダー APEX（現行と試験運用版）をインストールする: dogfood ユーザーは、追加のファイルのダウンロードやインストールをすることなく試験運用版を使用できるため、簡単に入れ替えられます。

apexd は起動中に特定の形式に従った sysprop を探し、適切な APEX バージョンを有効にします。

プロパティキーに期待される形式は次のとおりです。

bootconfig
- BoardConfig.mk で、デフォルト値を設定するために使用します。
- androidboot.vendor.apex.<apex name>
永続 sysprop
- すでに起動しているデバイスに設定されているデフォルト値を変更するために使用します。
- bootconfig 値が存在する場合はオーバーライドします。
- persist.vendor.apex.<apex name>

プロパティの値は、有効にする必要がある APEX のファイル名にする必要があります。

APEX Android.bp 定義に対する変更は、multi_install_skip_symbol_files フィールドのみです。デフォルトでないすべてのマルチインストール APEX 定義について、true にする必要があります。

// Default version.
apex {
  name: "com.oem.camera.hal.my_apex_default",
  apex_name: "com.oem.camera.hal",
  vendor: true,
  ..
}

// Non-default version.
apex {
  name: "com.oem.camera.hal.my_apex_experimental",
  apex_name: "com.oem.camera.hal",
  vendor: true,
  multi_install_skip_symbol_files: true,
  ..
}

また、デフォルトバージョンは、BoardConfig.mk で bootconfig を使用して構成する必要があります。

# Example for APEX "com.oem.camera.hal" with the default above:
BOARD_BOOTCONFIG += \
    androidboot.vendor.apex.com.oem.camera.hal=com.oem.camera.hal.my_apex_default

デバイスが起動したら、永続 sysprop を設定して有効なバージョンを変更します。

$ adb root;
$ adb shell setprop \
    persist.vendor.apex.com.oem.camera.hal \
    com.oem.camera.hal.my_apex_experimental;
$ adb reboot;

デバイスがフラッシュ後の bootconfig の更新をサポートしている場合（fastboot oem コマンドを使用するなど）、マルチインストールされた APEX の bootconfig プロパティを変更すると、起動時に有効になるバージョンも変更されます。

Cuttlefish ベースの仮想リファレンスデバイスの場合、--extra_bootconfig_args コマンドを使用して起動時に bootconfig プロパティを直接設定できます。次に例を示します。

launch_cvd --noresume \
  --extra_bootconfig_args "androidboot.vendor.apex.com.oem.camera.hal:=com.oem.camera.hal.my_apex_experimental";