互換性マトリックス

このセクションでは、フレームワーク互換性マトリックスおよびデバイス互換性マトリックスと、互換性マトリックスのスキーマについて説明します。一致のルールについては、マッチング ルールをご覧ください。

フレームワーク互換性マトリックス(FCM)

フレームワーク互換性マトリックス(FCM)には、フレームワークが実行されるデバイス上のフレームワークの要件が記述されます。フレームワーク互換性マトリックスは、システム互換性マトリックス、プロダクト互換性マトリックスsystem_ext 互換性マトリックスから構成されます。FCM の要件は、デバイス マニフェスト(ビルド時間、ランタイム、VTS で適用される要件)によって満たされている必要があります。

system_ext FCM とプロダクト FCM は、デバイス固有の FCM(システム パーティションにインストール)を補完します。

  • デバイス FCM は、システム パーティション内のモジュールの要件を反映する必要があります。
  • system_ext FCM は、system_ext パーティション内のモジュールの要件を反映する必要があります。
  • プロダクト FCM は、プロダクト パーティション内のモジュールの要件を反映する必要があります。

すべての FCM は、システム、プロダクト、system_ext パーティションのフレームワークに対する OEM の変更に合わせて調整する必要があります。たとえば、プロダクト パーティションにインストールされたアプリが HAL インターフェースのベンダー拡張を使用する場合、HAL インターフェースの要件をプロダクト FCM で宣言する必要があります。

システム互換性マトリックス ファイルの例:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="framework" level="3">
    <hal>
        <name>android.hardware.camera</name>
        <version>1.0</version>
        <version>3.1-4</version>
        <interface>
            <name>ICameraProvider</name>
            <instance>default</instance>
            <regex-instance>[a-z_]+/[0-9]+</regex-instance>
        </interface>
    </hal>
    <hal>
        <name>android.hardware.nfc</name>
        <version>1.0</version>
        <interface>
            <name>INfc</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal optional="true">
        <name>android.hardware.graphics.composer</name>
        <version>2.1</version>
        <interface>
            <name>IComposer</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal format="aidl" optional="true">
        <name>android.hardware.light</name>
        <version>1-2</version>
        <interface>
            <name>ILights</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal format="native">
        <name>GL</name>
        <version>1.1</version>
        <version>3.0</version>
    </hal>
    <hal format="native">
        <name>EGL</name>
        <version>1.1</version>
    </hal>
    <kernel version="3.18.51">
        <!-- common configs -->
    </kernel>
    <kernel version="3.18.51">
        <!-- arm specific configs -->
        <condition>
            <config>
                <key>CONFIG_ARM</key>
                <value type="tristate">y</value>
            </config>
        <condition>
        <config>
            <key>CONFIG_A</key>
            <value type="string"></value>
        </config>
        <config>
            <key>CONFIG_B</key>
            <value type="tristate">y</value>
        </config>
    </kernel>
    <kernel version="4.1.22">
        <!-- common configs -->
        <config>
            <key>CONFIG_A</key>
            <value type="string">foo</value>
        </config>
        <config>
            <key>CONFIG_B2</key>
            <value type="int">1024</value>
        </config>
    </kernel>
    <sepolicy>
        <kernel-sepolicy-version>30</kernel-sepolicy-version>
        <sepolicy-version>25.0</sepolicy-version>
        <sepolicy-version>26.0-3</sepolicy-version>
    </sepolicy>
    <avb>
        <vbmeta-version>2.1</vbmeta-version>
    </avb>
    <xmlfile format="dtd">
        <name>media_profile</name>
        <version>1.0</version>
        <path>/system/etc/media_profile_V1_0.dtd</path>
    </xmlfile>
</compatibility-matrix>

詳しくは、FCM ライフサイクルをご覧ください。

プロダクト互換性マトリックス

プロダクト FCM は、プロダクト パーティション内のフレームワーク互換性マトリックス ファイルです。VINTF オブジェクトは、プロダクト FCM と、システム パーティションおよび system_ext パーティション内の FCM をランタイム時に結合します。

プロダクト FCM ファイルの例:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="framework">
    <hal>
        <name>vendor.foo.camera</name>
        <version>1.0</version>
        <interface>
            <name>IBetterCamera</name>
            <instance>default</instance>
        </interface>
    </hal>
</compatibility-matrix>

system_ext 互換性マトリックス

system_ext FCM は、system_ext パーティション内のフレームワーク互換性マトリックス ファイルです。VINTF オブジェクトは、system_ext FCM と、システム パーティションおよびプロダクト パーティション内の FCM をランタイム時に結合します。system_ext FCM ファイルの例については、プロダクト互換性マトリックスをご覧ください。

デバイス互換性マトリックス(DCM)

デバイス互換性マトリックスには、デバイスがフレームワークに求める要件のセット(リリース時と OTA 時に適用される要件)が記述されます。

DCM ファイルの例:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<compatibility-matrix version="1.0" type="device">
    <hal>
        <name>android.hidl.manager</name>
        <version>1.0</version>
        <interface>
            <name>IServiceManager</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hidl.memory</name>
        <version>1.0</version>
        <interface>
            <name>IMemory</name>
            <instance>ashmem</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hidl.allocator</name>
        <version>1.0</version>
        <interface>
            <name>IAllocator</name>
            <instance>ashmem</instance>
        </interface>
    </hal>
    <hal>
        <name>android.framework.sensor</name>
        <version>1.0</version>
        <interface>
            <name>ISensorManager</name>
            <instance>default</instance>
        </interface>
    </hal>
    <vendor-ndk>
        <version>27</version>
    </vendor-ndk>
    <system-sdk>
        <version>27</version>
    </system-sdk>
</compatibility-matrix>

互換性マトリックスのスキーマ

このセクションでは、下記の XML タグの意味について説明します。「必須」タグの一部は Android ソースツリーのソースファイルに存在せず、ビルド時に assemble_vintf によって書き込まれる場合があります。「必須」タグは、デバイス上の対応するファイル内に存在する必要があります。

?xml
省略可。単に XML パーサーに情報を提供します。
compatibility-matrix.version
必須。この互換性マトリックスのメタバージョン。マニフェストに存在することが期待される要素を記述します。XML バージョンとは無関係です。
compatibility-matrix.type
必須。この互換性マトリックスのタイプ。次のいずれかです。
  • "device": デバイス互換性マトリックス。
  • "framework": フレームワーク互換性マトリックス。
manifest.level
フレームワーク互換性マトリックスでは必須。Android 12 以降では、product パーティションと system_ext パーティションのフレームワーク互換性マトリックス ファイルで許可されています。このファイルのフレームワーク互換性マトリックス バージョン(FCM バージョン)を指定します。デバイス固有のフレームワーク互換性マトリックス(つまり DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE)でこれを宣言しないでください。
compatibility-matrix.hal
省略可。繰り返し指定できます。互換性マトリックス(フレームワークまたはデバイス)のオーナーが要求する単一の HAL(HIDL またはネイティブ)のリストを指定します。HAL エントリは <name> 要素で区別します。同じ名前の HAL エントリを複数指定でき、その場合は「AND」条件が適用されることを意味します。
compatibility-matrix.hal.format
省略可。次のいずれかの値を指定できます。
  • "hidl": HIDL HAL。これがデフォルトです。
  • "aidl": AIDL HAL。互換性マトリックスのメタバージョン 2.0 でのみ有効です。
  • "native": ネイティブ HAL。
compatibility-matrix.hal.optional
属性は省略可で、デフォルトは false です。この HAL が互換性マトリックス(フレームワークまたはデバイス)のオーナーにとってオプションかどうかを示します。<hal> エントリが optional とマークされている場合、オーナーはこの HAL が存在すればそれを利用できますが、この HAL の存在を要求することはありません。
compatibility-matrix.hal.name
必須。この HAL の完全なパッケージ名。例:
  • android.hardware.camera(HIDL または AIDL HAL)
  • GLES(ネイティブ HAL、名前のみ必要)
compatibility-matrix.hal.version
互換性マトリックス(フレームワークまたはデバイス)のオーナーが期待するバージョンを定義した、バージョン範囲のリスト(HAL の一致を参照)。

HIDL HAL とネイティブ HAL で必須。重複なしで繰り返し指定できます。形式は次のいずれかです。
  • MAJOR.MINOR_MIN-MINOR_MAX
  • MAJOR.MINORMAJOR.MINOR-MINOR と同等)

Android 11 以前を搭載したデバイスでは、AIDL HAL で指定することはできません。それより後のバージョンを実行するデバイスでは省略可。指定する場合、形式は次のいずれかです。
  • VERSION_MIN-VERSION_MAX
  • VERSIONVERSION-VERSION と同等)
指定しない場合、その値はデフォルトの 1 になります。
compatibility-matrix.hal.interface
省略可。繰り返し指定できます。この HAL の必須インターフェースのリスト。
compatibility-matrix.hal.interface.name
必須。インターフェースの名前。
compatibility-matrix.hal.interface.instance
省略可。繰り返し指定できます。このインターフェースの必須インスタンスのリスト。
compatibility-matrix.hal.interface.regex-instance
省略可。繰り返し指定できます。このインターフェースの必須インスタンス名パターンのリスト。拡張正規表現形式を使用します。
compatibility-matrix.kernel
省略可。繰り返し指定できます。フレームワークが各カーネル バージョンで必要とするカーネル構成のリストを指定します。
同じ <version><kernel> を複数指定でき、その場合は「And」の関係で結ばれることを意味します。各 <kernel> は、<conditions> が満たされた場合にのみ有効になる要件の「フラグメント」です。
compatibility-matrix.kernel.version
必須。カーネル バージョン。形式は VERSION.MAJOR_REVISION.MINOR_REVISION です。 バージョンとメジャー リビジョンは正確に一致する必要があります。マイナー リビジョンは、フレームワークが期待するカーネルの最小 LTS バージョンを定義します。
compatibility-matrix.kernel.condition
省略可。各バージョンの最初の <kernel> では指定できません。条件のリストを指定します。条件が満たされた場合、この <kernel> フラグメントに記述されている要件が有効になります。
compatibility-matrix.kernel.config
省略可。繰り返し指定できます。このカーネル バージョンと一致する必要がある CONFIG 項目のリストを指定します。各 CONFIG 項目は Key-Value ペアです。config 項目はキーで区別されます。
compatibility-matrix.kernel.config.key
必須。CONFIG 項目のキー名。CONFIG_ で始まります。
compatibility-matrix.kernel.config.value
必須。CONFIG 項目の値。形式は、次のように型によって異なります。
  • string。引用符は省略されます。
  • int。10 進数と 16 進数(先頭が 0x または 0X))の値を指定できます。64 ビット整数として解釈され、桁あふれは切り捨てられます。パーサーは -264 + 1 から 264 - 1 までの値を受け入れ、65 番目のビットは切り捨てます。詳しくは、strtoull の man ページをご覧ください。
  • range。形式は [int]-[int](例: 10-20)です。0x または 0X で始まる 16 進数を指定できます。2 つの境界値は、符号なし 64 ビット整数でなければなりません。
  • tristate。有効な値は ymn です。
compatibility-matrix.kernel.config.value.type
必須。CONFIG 項目の値の型。次のいずれかを指定できます。
  • string
  • int
  • range
  • tristate
compatibility-matrix.sepolicy
必須。sepolicy 関連のすべてのエントリを含みます。フレームワーク互換性マトリックスでのみ使用されます。
compatibility-matrix.sepolicy.sepolicy-version
必須。繰り返し指定できます。sepolicy バージョンの要件を記述します。 manifest.sepolicy.version に対応しています。要素の各インスタンスは、sepolicy バージョンの範囲を定義します。
compatibility-matrix.sepolicy.kernel-sepolicy-version
必須。フレームワークが機能する policydb バージョンを宣言します。
compatibility-matrix.avb.vbmeta-version
省略可。フレームワーク互換性マトリックスでのみ使用されます。system.img の署名に使用される AVB バージョンを宣言します。Android 10 でサポートが終了しました。
compatibility-matrix.vendor-ndk
省略可。デバイス互換性マトリックスでのみ使用されます。VNDK ベンダー スナップショットの要件を宣言します。このタグがない場合、システム イメージで VNDK の要件が作成されません。
compatibility-matrix.vendor-ndk.version
必須。ベンダー イメージが必要とする VNDK バージョンを宣言する正の整数。
compatibility-matrix.vendor-ndk.library
省略可。繰り返し指定できます。ベンダー イメージが必要とする VNDK ライブラリのセットを宣言します。セマンティクスは manifest.vendor-ndk.library と同じです。
compatibility-matrix.system-sdk.version
省略可。繰り返し指定できます。デバイス互換性マトリックスでのみ使用されます。システム SDK バージョンに関するベンダーアプリの要件を宣言します。省略すると、システム イメージにシステム SDK の要件が作成されません。