マッチングルール

OTA アップデート時には、互換性マトリックスとマニフェストの 2 つのペアが整合性を持ち、フレームワークとベンダー実装が連携して動作できるかを検証する必要があります。この検証は、フレームワーク互換性マトリックスとデバイスマニフェストが一致し、フレームワークマニフェストとデバイス互換性マトリックスが一致していれば成功します。以下のセクションでは、さまざまなコンポーネントで使用されるマッチングルールについて詳しく説明します。

フレームワーク互換性マトリックスのバージョンの一致

デバイスマニフェストとフレームワーク互換性マトリックスが一致するためには、manifest.target-level で指定された Shipping FCM バージョンと、compatibility-matrix.level で指定された FCM バージョンが完全に同じである必要があります。同じでない場合は一致しません。

フレームワーク互換性マトリックスが libvintf を使用して要求された場合、このマッチングは常に成功します。これは、libvintf がデバイスマニフェストを開いて Shipping FCM バージョンを取得し、その Shipping FCM バージョンのフレームワーク互換性マトリックスを返すためです（さらに、上位の FCM バージョンの互換性マトリックスからオプションの HAL もいくつか返します）。

HAL の一致

HAL のマッチングルールは、対応する互換性マトリックスのオーナーによってサポートされていると想定されるマニフェストファイルの hal 要素のバージョンを識別します。

複数の <hal> 要素は単一の AND 関係で評価されます。
同じ <hal> 内の複数の <version> 要素は OR 関係を持ちます。2 つ以上のバージョンが指定されている場合は、いずれか 1 つのみを実装する必要があります（下記の DRM の例をご覧ください）。
同じ <hal> 内の複数の <instance> 要素と <regex-instance> 要素は、単一の AND 関係で評価されます（下記の DRM の例をご覧ください）。

例: カメラモジュールの HAL マッチングが成功する場合

バージョン 2.5 の HAL の場合、マッチングルールは次のようになります。

マトリックス一致するマニフェスト

2.5 2.5～2.∞。2.5～5 の略記。

マトリックス	一致するマニフェスト
`2.5`	2.5～2.∞。2.5～5 の略記。
`2.5-7`	2.5～2.∞。次のことを示します。 2.5 は最低限必要なバージョンです。HAL 2.0～2.4 を提供するマニフェストは互換性がないことを意味します。 2.7 は要求できる最大バージョンです。互換性マトリックス（フレームワークまたはデバイス）のオーナーが 2.7 より上位のバージョンを要求しないことを意味します。2.7 が要求された場合でも、一致させるマニフェストのオーナーは、たとえばバージョン 2.10 を提供することもできます。互換性マトリックスのオーナーは、要求されたサービスが API バージョン 2.7 と互換性があることのみを認識します。 -7 は単なる情報であり、OTA アップデートプロセスには影響しません。したがって、デバイスのマニフェストファイルでバージョン 2.10 の HAL が指定されている場合、そのデバイスでは、互換性マトリックスで `camera:` `2.5-7` を指定しているフレームワークとの互換性が維持されます。

2.5-7

2.5～2.∞。次のことを示します。

2.5 は最低限必要なバージョンです。HAL 2.0～2.4 を提供するマニフェストは互換性がないことを意味します。
2.7 は要求できる最大バージョンです。互換性マトリックス（フレームワークまたはデバイス）のオーナーが 2.7 より上位のバージョンを要求しないことを意味します。2.7 が要求された場合でも、一致させるマニフェストのオーナーは、たとえばバージョン 2.10 を提供することもできます。互換性マトリックスのオーナーは、要求されたサービスが API バージョン 2.7 と互換性があることのみを認識します。
-7 は単なる情報であり、OTA アップデートプロセスには影響しません。

したがって、デバイスのマニフェストファイルでバージョン 2.10 の HAL が指定されている場合、そのデバイスでは、互換性マトリックスで camera: 2.5-7 を指定しているフレームワークとの互換性が維持されます。

例: DRM モジュールの HAL マッチングが成功する場合

フレームワーク互換性マトリックスに、次のような DRM HAL のバージョン情報が記述されているとします。

<hal>
    <name>android.hardware.drm
    <version>1.0</version>
    <version>3.1-2</version>
    <interface>
        <name>IDrmFactory</name>
        <instance>default</instance>
        <instance>specific</instance>
    </interface>
</hal>
<hal>
    <name>android.hardware.drm
    <version>2.0</version>
    <interface>
        <name>ICryptoFactory</name>
        <instance>default</instance>
        <regex-instance>[a-z]+/[0-9]+</regex-instance>
    </interface>
</hal>

この場合、ベンダーは次のインスタンスのいずれか 1 つを実装する必要があります。

android.hardware.drm@1.x::IDrmFactory/default          // where x >= 0
android.hardware.drm@1.x::IDrmFactory/specific         // where x >= 0

または

android.hardware.drm@3.y::IDrmFactory/default          // where y >= 1
android.hardware.drm@3.y::IDrmFactory/specific         // where y >= 1

そして、次のインスタンスをすべて実装する必要もあります。

android.hardware.drm@2.z::ICryptoFactory/default       // where z >= 0
android.hardware.drm@2.z::ICryptoFactory/${INSTANCE}
            // where z >= 0 and ${INSTANCE} matches [a-z]+/[0-9]+
            // e.g. legacy/0

カーネルの一致

フレームワーク互換性マトリックスの <kernel> セクションには、デバイス上の Linux カーネルのフレームワークの要件が記述されています。この情報は、OTA 時に、デバイスの VINTF オブジェクトによって報告されるカーネルの情報と一致する必要があります。

マトリックスには複数の <kernel> セクションがあり、それぞれに異なる version 属性が次の形式で指定されています。

${ver}.${major_rev}.${kernel_minor_rev}

OTA では、デバイスのカーネルと同じ ${ver} と ${major_rev} を含む <kernel> セクション（version="${ver}.${major_rev}.${matrix_minor_rev}")）のみが考慮され、他のセクションは無視されます。さらに、カーネルのマイナーリビジョンは、互換性マトリックスと同じ値である必要があります（${kernel_minor_rev} >= ${matrix_minor_rev}）。これらの要件を満たす <kernel> セクションがない場合は、一致しません。

<kernel> セクションが一致する場合は、処理が続行されて config 要素が /proc/config.gz と照合されます。互換性マトリックスの config 要素ごとに /proc/config.gz がルックアップされ、その config が存在するかどうかが確認されます。一致する <kernel> セクションの互換性マトリックスで config 項目が n に設定されている場合、config 項目は /proc/config.gz に存在しません。最後に、互換性マトリックスに存在しない config 項目は、/proc/config.gz に存在する場合も、存在しない場合もあります。

一致する例:

<value type="string">bar</value> は "bar" と一致します。互換性マトリックスでは引用符が省略されていますが、/proc/config.gz では引用符があります。
<value type="int">4096</value> は 4096、0x1000、0X1000 のいずれかと一致します。
<value type="int">0x1000</value> は 4096、0x1000、0X1000 のいずれかと一致します。
<value type="int">0X1000</value> は 4096、0x1000、0X1000 のいずれかと一致します。
<value type="tristate">y</value> は y と一致します。
<value type="tristate">m</value> は m と一致します。
<value type="tristate">n</value> は、config 項目が /proc/config.gz に存在しないことを意味します。
<value type="range">1-0x3</value> は、1、2、3、または 16 進数の同等の値と一致します。

例: カーネルのマッチングが成功する場合

フレームワーク互換性マトリックスに、次のようなカーネル情報が記述されているとします。

<kernel version="4.14.42">
   <config>
      <key>CONFIG_TRI</key>
      <value type="tristate">y</value>
   </config>
   <config>
      <key>CONFIG_NOEXIST</key>
      <value type="tristate">n</value>
   </config>
   <config>
      <key>CONFIG_DEC</key>
      <value type="int">4096</value>
   </config>
   <config>
      <key>CONFIG_HEX</key>
      <value type="int">0XDEAD</value>
   </config>
   <config>
      <key>CONFIG_STR</key>
      <value type="string">str</value>
   </config>
   <config>
      <key>CONFIG_EMPTY</key>
      <value type="string"></value>
   </config>
</kernel>

カーネルのバージョンの一致が最初に確認されます。デバイスは uname() で次の情報を報告します。

4.9.84（<kernel version="4.9.x">（x <= 84）の別のカーネルセクションがない限り、マトリックスに一致しません）
4.14.41（version より小さいため、マトリックスに一致しません）
4.14.42（マトリックスと一致します）
4.14.43（マトリックスと一致します）
4.1.22（<kernel version="4.1.x">（x <= 22）の別のカーネルセクションがない限り、マトリックスに一致しません）

適切な <kernel> セクションが選択されると、n 以外の値を持つ各 <config> 項目については、対応するエントリが /proc/config.gz に存在することが期待されます。n の値を持つ各 <config> 項目については、対応するエントリが /proc/config.gz に存在しないことが期待されます。<value> の内容については、等号（引用符を含む）の後から、次の行の文字または # までのテキストと完全に一致することが予想されます（先頭と末尾の空白文字は除く）。

次のカーネル構成は、マッチングが成功する例です。

# comments don't matter
CONFIG_TRI=y
# CONFIG_NOEXIST shouldn't exist
CONFIG_DEC = 4096 # trailing comments and whitespaces are fine
CONFIG_HEX=57005  # 0XDEAD == 57005
CONFIG_STR="str"
CONFIG_EMPTY=""   # empty string must have quotes
CONFIG_EXTRA="extra config items are fine too"

次のカーネル構成は、マッチングが成功しない例です。

CONFIG_TRI="y"   # mismatch: quotes
CONFIG_NOEXIST=y # mismatch: CONFIG_NOEXIST exists
CONFIG_HEX=0x0   # mismatch; value doesn't match
CONFIG_DEC=""    # mismatch; type mismatch (expect int)
CONFIG_EMPTY=1   # mismatch; expects ""
# mismatch: CONFIG_STR is missing

SE ポリシーの一致

SE ポリシーでは、次のような一致が求められます。

<sepolicy-version> は、すべてのメジャーバージョンについて、マイナーバージョンの範囲を定義します。デバイスが報告する sepolicy のバージョンは、フレームワークと互換性がある範囲に含まれている必要があります。マッチングルールは HAL バージョンと同様で、sepolicy のバージョンが範囲の最小バージョン以上であれば、一致します。最大バージョンは単なる情報です。
<kernel-sepolicy-version> は policydb のバージョンです。デバイスが報告する security_policyvers() より小さい値でなければなりません。

例: SE ポリシーのマッチングが成功する場合

フレームワーク互換性マトリックスに、次のような sepolicy 情報が記述されているとします。

<sepolicy>
    <kernel-sepolicy-version>30</kernel-sepolicy-version>
    <sepolicy-version>25.0</sepolicy-version>
    <sepolicy-version>26.0-3</sepolicy-version>
</sepolicy>

デバイス側の要件:

security_policyvers() が返す値は 30 以上であることが必要です。それ以外の場合は一致しません。たとえば、次のようになります。
- デバイスが 29 を返す場合は、一致しません。
- デバイスが 31 を返す場合は、一致します。
SE ポリシーのバージョンは、25.0～∞ または 26.0～∞ のいずれかであることが必要です。それ以外の場合は一致しません。「26.0」の後の「-3」は単なる情報です。

AVB バージョンの一致

AVB バージョンには、MAJOR バージョンと MINOR バージョンが MAJOR.MINOR（1.0、2.1 など）という形式で含まれています。詳細については、バージョニングと互換性をご覧ください。AVB バージョンには次のシステムプロパティがあります。

ro.boot.vbmeta.avb_version は、ブートローダー内の libavb バージョンです。
ro.boot.avb_version は、Android OS（init/fs_mgr）内の libavb バージョンです。

システムプロパティが表示されるのは、対応する libavb が AVB メタデータの検証に使用されており、OK を返したときだけです。検証が失敗したとき（または検証がまったく行われなかったとき）は、含まれません。

互換性のマッチングでは、次の比較が行われます。

sysprop の ro.boot.vbmeta.avb_version とフレームワーク互換性マトリックスの avb.vbmeta-version の比較。
- ro.boot.vbmeta.avb_version.MAJOR == avb.vbmeta-version.MAJOR
- ro.boot.vbmeta.avb_version.MINOR >= avb.vbmeta-version.MINOR
sysprop の ro.boot.avb_version とフレームワーク互換性マトリックスの avb.vbmeta-version の比較。
- ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR
- ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR

ブートローダーまたは Android OS には、libavb ライブラリのコピーが 2 つ（アップグレードデバイスとリリースデバイス用の MAJOR バージョンが 1 つずつ）含まれていることがあります。この場合、同じ無署名のシステムイメージを共有できますが、最終の署名済みシステムイメージは別々になります（avb.vbmeta-version が異なります）。

図 1. AVB バージョンのマッチング（/system は P、他のすべてのパーティションは O）

図 2. AVB バージョンのマッチング（すべてのパーティションが P）

例: AVB バージョンのマッチングが成功する場合

フレームワーク互換性マトリックスに、次のような AVB 情報が記述されているとします。

<avb>
    <vbmeta-version>2.1</vbmeta-version>
</avb>

デバイス側の要件:

ro.boot.avb_version              == 1.0 &&
ro.boot.vbmeta.avb_version       == 2.1  mismatch

ro.boot.avb_version              == 2.1 &&
ro.boot.vbmeta.avb_version       == 3.0  mismatch

ro.boot.avb_version              == 2.1 &&
ro.boot.vbmeta.avb_version       == 2.3  match

ro.boot.avb_version              == 2.3 &&
ro.boot.vbmeta.avb_version       == 2.1  match

OTA 時の AVB バージョンのマッチング

Android 9 以下でリリースするデバイスでは、OTA 時に、フレームワーク互換性マトリックスの AVB バージョン要件とデバイスの現行 AVB バージョンの一致が確認されます。OTA 時に AVB バージョンがメジャーバージョンにアップグレードされた場合（たとえば 0.0 から 1.0）、OTA 後の OTA のチェックでは互換性が反映されません。

この問題を軽減するには、OEM で OTA パッケージ（compatibility.zip）に偽の AVB バージョンを設定し、チェックをパスできるようにします。手順は次のとおりです。

Android 9 のソースツリーで以下の CL を選択します。
- CL 732261
- CL 732262
デバイスの BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE を定義します。この値は、OTA 前の AVB バージョン、つまりデバイスがリリースされたときの AVB バージョンと同じにする必要があります。
OTA パッケージを再ビルドします。

上記の変更により、次のファイルで自動的に BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE が compatibility-matrix.avb.vbmeta-version に設定されます。

デバイス上の /system/compatibility_matrix.xml（Android 9 では使用されません）
OTA パッケージの compatibility.zip に含まれる system_matrix.xml

上記の変更は、他のフレームワーク互換性マトリックス（/system/etc/vintf/compatibility_matrix.xml など）には影響しません。OTA 後は、/system/etc/vintf/compatibility_matrix.xml 内の新しい値が互換性チェックに使用されます。

VNDK バージョンの一致

デバイス互換性マトリックスでは、必要な VNDK バージョンを compatibility-matrix.vendor-ndk.version で宣言します。デバイス互換性マトリックスに <vendor-ndk> タグがない場合は、適用される要件がないため、常に一致すると見なされます。

デバイス互換性マトリックスに <vendor-ndk> タグがある場合は、フレームワークマニフェストのフレームワークによって提供される VNDK ベンダースナップショットのセットから、<version> が一致する <vendor-ndk> エントリがルックアップされます。一致するエントリが存在しない場合は、一致しません。

一致するエントリが存在する場合は、デバイス互換性マトリックスで列挙されるライブラリセットが、フレームワークマニフェストに記述されたライブラリセットのサブセットであることが必要です。それ以外の場合、エントリは一致すると見なされません。

特別なケースとして、デバイス互換性マトリックスでライブラリが 1 つも列挙されていない場合、エントリは常に一致すると見なされます。空のセットは任意のセットのサブセットであるためです。

例: VNDK バージョンのマッチングが成功する場合

デバイス互換性マトリックスに、次のような VNDK に関する要件が記述されているとします。

<!-- Example Device Compatibility Matrix -->
<vendor-ndk>
    <version>27</version>
    <library>libjpeg.so</library>
    <library>libbase.so</library>
</vendor-ndk>

フレームワークマニフェストでは、バージョン 27 のエントリのみが考慮されます。

<!-- Framework Manifest Example A -->
<vendor-ndk>
    <version>27</version>
    <library>libjpeg.so</library>
    <library>libbase.so</library>
    <library>libfoo.so</library>
</vendor-ndk>

VNDK バージョン 27 がフレームワークマニフェストに含まれており、{libjpeg.so, libbase.so, libfoo.so} ⊇ {libjpeg.so, libbase.so} であるため、例 A は一致します。

<!-- Framework Manifest Example B -->
<vendor-ndk>
    <version>26</version>
    <library>libjpeg.so</library>
    <library>libbase.so</library>
</vendor-ndk>
<vendor-ndk>
    <version>27</version>
    <library>libbase.so</library>
</vendor-ndk>

例 B は一致しません。VNDK バージョン 27 はフレームワークマニフェストに含まれていますが、そのスナップショットのフレームワークで libjpeg.so がサポートされていないためです。VNDK バージョン 26 は無視されます。

システム SDK バージョンの一致

デバイス互換性マトリックスでは、必要なシステム SDK バージョンのセットを compatibility-matrix.system-sdk.version で宣言します。このシステム SDK バージョンのセットが、フレームワークマニフェストの manifest.system-sdk.version で宣言されているシステム SDK バージョンのサブセットである場合にのみ、一致します。

特別なケースとして、デバイス互換性マトリックスでシステム SDK バージョンが 1 つも列挙されていない場合は、常に一致すると見なされます。空のセットは任意のセットのサブセットであるためです。

例: システム SDK バージョンのマッチングが成功する場合

デバイス互換性マトリックスに、次のようなシステム SDK に関する要件が記述されているとします。

<!-- Example Device Compatibility Matrix -->
<system-sdk>
    <version>26</version>
    <version>27</version>
</system-sdk>

この場合、一致するためには、フレームワークでシステム SDK バージョン 26 と 27 を指定されている必要があります。

<!-- Framework Manifest Example A -->
<system-sdk>
    <version>26</version>
    <version>27</version>
</system-sdk>

例 A は一致します。

<!-- Framework Manifest Example B -->
<system-sdk>
    <version>26</version>
    <version>27</version>
    <version>28</version>
</system-sdk>

例 B は一致します。

<!-- Framework Manifest Example C -->
<system-sdk>
    <version>26</version>
</system-sdk>

システム SDK バージョン 27 が指定されていないため、例 C は一致しません。

マッチング ルール