比對規則

這兩組相容性矩陣和資訊清單應進行調和，以便驗證架構和供應商實作項目是否能相互搭配運作。只要架構相容性矩陣與裝置資訊清單相符，以及架構資訊清單與裝置相容性矩陣相符，這項驗證就會成功。

這項驗證會在建構期間、OTA 更新套件產生期間、啟動期間，以及 VTS 相容性測試中完成。

以下各節將詳細說明各種元件使用的比對規則。

架構相容性矩陣版本相符

如要將裝置資訊清單與架構相容性矩陣配對，manifest.target-level 指定的發布 FCM 版本必須與 compatibility-matrix.level 指定的 FCM 版本完全相同。否則就沒有相符項目。

當您使用 libvintf 要求架構相容性矩陣時，這項比對作業一律會成功，因為 libvintf 會開啟裝置資訊清單、擷取發布版 FCM 版本，並傳回該發布版 FCM 版本的架構相容性矩陣 (以及較高 FCM 版本的部分選用 HAL 自相容性矩陣)。

HAL 比對結果

HAL 比對規則會指出資訊清單檔案中 hal 元素的版本，這些版本被視為相應相容性矩陣的擁有者所支援。

HIDL 和原生 HAL

HIDL 和原生 HAL 的比對規則如下：

  • 系統會使用單一「AND」關係評估多個 <hal> 元素。
  • <hal> 元素可使用 <hal optional="true"> 標示為非必要元素。警告：Android 15 之後不再支援這個 optional
  • 同一個 <hal> 中的多個 <version> 元素具有 OR 關係。如果指定兩個以上版本，則只需實作其中一個版本即可。(請參閱下方的DRM 範例)。
  • 在需要 <hal> 的情況下，系統會使用單一 AND 關係來評估同一 <hal> 中的多個 <instance> 和 <regex-instance> 元素。(請參閱下方的 DRM 範例)。</ahref="#drm">

範例：模組的 HAL 比對成功

如果是 2.5 版 HAL，比對規則如下：

格狀模式 相符的資訊清單
2.5 2.5-2.∞。在相容性矩陣中，2.5 是 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 更新程序。
因此，如果裝置的資訊清單檔案中 HAL 的版本為 2.10，則仍可與在相容性矩陣中宣告 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>

供應商必須實作下列任一例項：

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

AIDL HAL

所有 Android 11 以上版本 (不含 Android 11) 都支援 VINTF 中的 AIDL HAL 版本。AIDL HAL 的比對規則與 HIDL 和原生 HAL 的比對規則相似，但沒有主要版本，且每個 HAL 例項只有一個版本 (如果未指定版本，則為 1)。

  • 系統會使用單一「AND」關係評估多個 <hal> 元素。
  • <hal> 元素可使用 <hal optional="true"> 標示為非必要元素。警告：Android 15 之後不再支援這個 optional
  • 在需要 <hal> 的情況下，系統會使用單一 AND 關係來評估同一 <hal> 中的多個 <instance> 和 <regex-instance> 元素。(請參閱下方的 <ahref="#vibrator">震動器範例)</ahref="#vibrator">。

範例：模組的 HAL 比對成功

對於 HAL 5 版，比對規則如下：

格狀模式 相符的資訊清單
5 5-∞。在相容性矩陣中，5 是 5-5 的簡寫。
5-7 5-∞。表示下列項目：
  • 5 是最低版本需求，也就是說，提供 HAL 1 至 4 的資訊清單不相容。
  • 7 是可要求的最高版本，也就是說相容性矩陣 (架構或裝置) 的擁有者不會要求 7 以上的版本。在要求 7 版時，相符資訊清單的擁有者仍可提供 10 版 (例如)。相容性矩陣擁有者只知道要求的服務與 API 7 版相容。
  • -7 僅供參考，不會影響 OTA 更新程序。
因此，如果裝置的資訊清單檔案中 HAL 的版本為 10，則仍可與在相容性矩陣中宣告 5-7 的架構相容。

範例：多個模組的 HAL 比對成功

架構相容性矩陣會說明以下振動器和相機 HAL 的版本資訊：

<hal>
    <name>android.hardware.vibrator
    <version>1-2</version>
    <interface>
        <name>IVibrator</name>
        <instance>default</instance>
        <instance>specific</instance>
    </interface>
</hal>
<hal>
    <name>android.hardware.camera
    <version>5</version>
    <interface>
        <name>ICamera</name>
        <instance>default</instance>
        <regex-instance>[a-z]+/[0-9]+</regex-instance>
    </interface>
</hal>

廠商必須實作下列所有例項：

android.hardware.vibrator.IVibrator/default     // version >= 1
android.hardware.vibrator.IVibrator/specific    // version >= 1
android.hardware.camera.ICamera/default         // version >= 5
android.hardware.camera.ICamera/${INSTANCE}
            // with version >= 5, where ${INSTANCE} matches [a-z]+/[0-9]+
            // e.g. legacy/0

核心相符項目

架構相容性矩陣的 <kernel> 部分會說明架構對裝置上 Linux 核心的要求。這項資訊會與裝置 VINTF 物件回報的核心相關資訊比對。

比對核心分支

每個核心分支後置字元 (例如 5.4-r) 會對應至專屬的核心 FCM 版本 (例如 5)。這與版本代號 (例如 R) 和 FCM 版本 (例如 5) 之間的對應關係相同。

如果下列任一情況為真，VTS 測試會強制裝置在裝置資訊清單 (/vendor/etc/vintf/manifest.xml) 中明確指定核心 Firebase 雲端通訊版本：

  • 核心 Firebase 雲端訊息版本與目標 Firebase 雲端訊息版本不同。舉例來說，上述裝置的目標 FCM 版本為 4，其核心 FCM 版本為 5 (核心分支後置字 r)。
  • 核心 FCM 版本大於或等於 5 (核心分支後綴 r)。

VTS 測試會強制執行，如果指定核心 Firebase 雲端訊息版本，則核心 Firebase 雲端訊息版本必須大於或等於裝置資訊清單中的目標 Firebase 雲端訊息版本。

範例：判斷核心分支

如果裝置指定 FCM 4 版 (在 Android 10 中發布)，但執行 4.19-r 分支的核心，則裝置資訊清單應指定下列項目：

<manifest version="2.0" type="device" target-level="4">
   <kernel target-level="5" />
</manifest>

VINTF 物件會根據 FCM 5 版中指定的 4.19-r 核心分支，檢查核心相容性。這些規定是根據 Android 來源樹狀結構中的 kernel/configs/r/android-4.19 建構而成。

範例：判斷 GKI 的核心分支

如果裝置使用通用核心映像檔 (GKI)，且 /proc/version 的核心版本字串為以下內容：

5.4.42-android12-0-00544-ged21d463f856

接著，VINTF 物件會從核心版本取得 Android 版本，並使用該版本判斷核心 FCM 版本。在本例中，android12 代表核心 FCM 版本 6 (在 Android 12 中發布)。

如要進一步瞭解如何剖析核心版本字串，請參閱「GKI 版本管理」。

比對核心版本

矩陣可包含多個 <kernel> 區段，每個區段都有不同的 version 屬性，格式如下：

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

VINTF 物件只會考量與 FCM 版本相符的 FCM 中的 <kernel> 部分，且該版本與裝置核心的 ${ver} 和 ${major_rev} 相同 (也就是version="${ver}.${major_rev}.${matrix_minor_rev}")；系統會忽略其他部分。此外，核心的次要修訂版本必須是相容性矩陣 (${kernel_minor_rev} >= ${matrix_minor_rev}) 中的值。如果沒有任何 <kernel> 區段符合這些需求，則表示不相符。

範例：選取比對條件

請考慮下列假設情況，假設 /system/etc/vintf 中的 FCM 宣告以下要求 (省略標頭和頁尾標記)：

<!-- compatibility_matrix.3.xml -->
<kernel version="4.4.107" level="3"/>
<!-- See kernel/configs/p/android-4.4/ for 4.4-p requirements -->
<kernel version="4.9.84" level="3"/>
<!-- See kernel/configs/p/android-4.9/ for 4.9-p requirements -->
<kernel version="4.14.42" level="3"/>
<!-- See kernel/configs/p/android-4.14/ for 4.14-p requirements -->

<!-- compatibility_matrix.4.xml -->
<kernel version="4.9.165" level="4"/>
<!-- See kernel/configs/q/android-4.9/ for 4.9-q requirements -->
<kernel version="4.14.105" level="4"/>
<!-- See kernel/configs/q/android-4.14/ for 4.14-q requirements -->
<kernel version="4.19.42" level="4"/>
<!-- See kernel/configs/q/android-4.19/ for 4.19-q requirements -->

<!-- compatibility_matrix.5.xml -->
<kernel version="4.14.180" level="5"/>
<!-- See kernel/configs/r/android-4.14/ for 4.14-r requirements -->
<kernel version="4.19.123" level="5"/>
<!-- See kernel/configs/r/android-4.19/ for 4.19-r requirements -->
<kernel version="5.4.41" level="5"/>
<!-- See kernel/configs/r/android-5.4/ for 5.4-r requirements -->

目標 FCM 版本、核心 FCM 版本和核心版本會共同從 FCM 選取核心需求：

指定的 FCM 版本核心 FCM 版本核心版本比對方式：
3 (P)未指定4.4.106 不相符 (次要版本不相符)
3 (P)未指定4.4.107 4.4-p
3 (P)未指定4.19.42 4.19-q (請參閱下方附註)
3 (P)未指定5.4.41 5.4-r (請參閱下方附註)
3 (P)3 (P) 4.4.107 4.4-p
3 (P)3 (P) 4.19.42 不相符 (沒有 4.19-p 核心分支)
3 (P)4 (Q) 4.19.42 4.19-q
4 (Q)未指定4.4.107 不相符 (沒有 4.4-q 核心分支)
4 (Q)未指定4.9.165 4.9-q
4 (Q)未指定5.4.41 5.4-r (請參閱下方附註)
4 (Q)4 (Q) 4.9.165 4.9-q
4 (Q)4 (Q) 5.4.41 不相符 (沒有 5.4-q 核心分支)
4 (Q)5 (R) 4.14.1054.14-r
4 (Q)5 (R) 5.4.41 5.4-r
5 (R)未指定任何VTS 失敗 (必須指定目標 Firebase 雲端訊息版本 5 的核心 Firebase 雲端訊息版本)
5 (R)4 (Q) 任何VTS 失敗 (核心 FCM 版本 < 目標 FCM 版本)
5 (R)5 (R) 4.14.1804.14-r

比對核心設定

如果 <kernel> 部分相符，系統會繼續嘗試將 config 元素與 /proc/config.gz 相符。針對相容性矩陣中的每個設定元素，會查詢 /proc/config.gz，瞭解是否存在設定。如果相容性矩陣中相符的 <kernel> 部分將設定項目設為 n，則該項目不得出現在 /proc/config.gz 中。最後，不在相容性矩陣中的設定項目，可能會或不會出現在 /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> 表示設定項目不得存在於 /proc/config.gz。
  • <value type="range">1-0x3</value> 與 1、2 或 3 相符，或等同於十六進位。

範例：成功比對核心

以下是含有 FCM 1.0 的架構相容性矩陣，其中包含以下核心資訊：

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

系統會先比對核心分支。核心分支會在 manifest.kernel.target-level 的裝置資訊清單中指定，如果未指定前者，則預設為 manifest.level。如果裝置資訊清單中的核心分支為：

  • 為 1，則繼續執行下一個步驟並檢查核心版本。
  • 是 2，與矩陣不相符。在 FCM 2.0 版中，VINTF 物件會改為從矩陣讀取核心需求。

然後，系統會比對核心版本。如果 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> 區段後，對於 <config> 值為 n 以外的每個 <config> 項目，我們預期 /proc/config.gz 中會有對應的項目；對於 <config> 值為 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

搜尋引擎比對政策

安全搜尋政策規定必須符合下列條件：

  • <sepolicy-version> 會為每個主要版本定義次要版本的封閉範圍。裝置回報的 sepolicy 版本必須落在其中一個範圍內，才能與架構相容。相符規則與 HAL 版本相似；如果 sepolicy 版本高於或等於該範圍的最小版本，則相符。最高版本僅供參考。
  • <kernel-sepolicy-version> 例如 policydb 版本。必須小於裝置回報的 security_policyvers()。

範例：成功比對搜尋引擎政策

架構相容性矩陣會列出以下 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 版本包含主版本和次版本，格式為主版本.次版本 (例如 1.0、2.1)。詳情請參閱「版本管理與相容性」。AVB 版本具有下列系統屬性：

  • ro.boot.vbmeta.avb_version 是系統啟動載入程式中的 libavb 版本
  • ro.boot.avb_version 是 Android 作業系統 (init/fs_mgr) 中的 libavb 版本

只有在使用對應的 libavb 驗證 AVB 中繼資料 (並傳回「OK」) 時，系統屬性才會顯示。如果發生驗證失敗 (或完全沒有驗證)，就不會出現。

相容性比對會比較下列項目：

  • 使用架構相容性矩陣中的 avb.vbmeta-version 設定 sysprop ro.boot.vbmeta.avb_version；
    • ro.boot.vbmeta.avb_version.MAJOR == avb.vbmeta-version.MAJOR
    • ro.boot.vbmeta.avb_version.MINOR >= avb.vbmeta-version.MINOR
  • 使用架構相容性矩陣中的 avb.vbmeta-version 搭配 sysprop ro.boot.avb_version。
    • ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR
    • ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR

引導程式或 Android 作業系統可能包含兩個 libavb 程式庫副本，每個副本都有不同的 MAJOR 版本，分別用於升級裝置和啟動裝置。在這種情況下，可以共用相同的未簽署系統映像檔，但最終已簽署的系統映像檔會不同 (具有不同的 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 或以下版本，更新至 Android 10 時，架構相容性矩陣中的 AVB 版本需求會與裝置上的目前 AVB 版本進行比對。如果 AVB 版本在 OTA 期間進行主要版本升級 (例如從 0.0 升級至 1.0)，則 OTA 中的 VINTF 相容性檢查不會反映 OTA 後的相容性。

為緩解這個問題，原始設備製造商 (OEM) 可以在 OTA 套件 (compatibility.zip) 中放入假的 AVB 版本，以便通過檢查。方法如下：

  1. 將下列 CL 挑選至 Android 9 來源樹狀結構：
  2. 為裝置定義 BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE。其值應等於 OTA 前 AVB 版本，也就是裝置推出時的 AVB 版本。
  3. 重建 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 版本相符

裝置相容性矩陣會在 compatibility-matrix.vendor-ndk.version 中宣告所需的 VNDK 版本。如果裝置相容性矩陣沒有 <vendor-ndk> 標記，就不會強制規定任何條件，因此系統一律會視為相符。

如果裝置相容性矩陣有 <vendor-ndk> 標記，系統會從架構的宣告集中查詢 VNDK 供應商快照集合，找出與 <version> 相符的 <vendor-ndk> 項目。如果沒有這樣的項目，就表示沒有相符項目。

如果確實有這樣的項目，則裝置相容性矩陣中列舉的程式庫集合必須是架構資訊清單中所述程式庫集合的子集合；否則，系統不會將該項目視為相符。

  • 在特殊情況下，如果裝置相容性矩陣中沒有列舉任何程式庫，系統一律會將該項目視為相符，因為空白集合是任何集合的子集合。

範例：成功比對 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>

範例 A 符合條件，因為 VNDK 版本 27 位於架構資訊清單和 {libjpeg.so, libbase.so, libfoo.so} ⊇ {libjpeg.so, libbase.so} 中。

<!-- 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 版本相符

裝置相容性矩陣會在 compatibility-matrix.system-sdk.version 中宣告一組必要的系統 SDK 版本。只有在集合是架構資訊清單中 manifest.system-sdk.version 中宣告的提供的系統 SDK 版本子集時，才會符合條件。

  • 在特殊情況下，如果裝置相容性矩陣中沒有列舉任何系統 SDK 版本，系統一律會將其視為相符，因為空集是任何集合的子集。

範例：系統 SDK 版本成功比對

如果裝置相容性矩陣指出 System SDK 有以下要求：

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

接著，架構必須提供相符的 26 和 27 版系統 SDK。

<!-- 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>

範例 C 不符合條件，因為未提供 System SDK 27 版。