互換性マトリックス

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

フレームワーク互換性マトリックス（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.MINOR（MAJOR.MINOR-MINOR と同等）

Android 11 以前を搭載したデバイスでは、AIDL HAL で指定することはできません。それより後のバージョンを実行するデバイスでは省略可。指定する場合、形式は次のいずれかです。

VERSION_MIN-VERSION_MAX
VERSION（VERSION-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 ビット整数として解釈され、桁あふれは切り捨てられます。パーサーは -2⁶⁴ + 1 から 2⁶⁴ - 1 までの値を受け入れ、65 番目のビットは切り捨てます。詳しくは、strtoull の man ページをご覧ください。
range。形式は [int]-[int]（例: 10-20）です。0x または 0X で始まる 16 進数を指定できます。2 つの境界値は、符号なし 64 ビット整数でなければなりません。
tristate。有効な値は y、m、n です。

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 の要件が作成されません。