比對規則

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

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

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

架構相容性矩陣版本相符

為讓裝置資訊清單與架構相容性矩陣相符，manifest.target-level 指定的正式版 Firebase 雲端通訊版本必須與 compatibility-matrix.level 指定的 Firebase 雲端通訊版本完全相同。否則就沒有相符項目。

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

HAL 賽事

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

HIDL 和原生 HAL

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

  • 系統會使用單一「AND」關係評估多個 <hal> 元素。
  • <hal> 元素可使用 <hal optional="true"> 標示為非必要元素。
  • 同一個 <hal> 中的多個 <version> 元素具有 OR 關係。如果指定兩個以上版本，則只需實作其中一個版本即可。(請參閱下方的DRM 範例)。
  • 如果需要 <hal>，系統會使用單一 AND 關係評估同一個 <hal> 中的多個 <instance> 和 <regex-instance> 元素。(請參閱下方的 <ahref="#drm">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
OR 
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"> 標示為非必要元素。
  • 在需要 <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 物件會檢查核心相容性是否符合 4.19-r 核心分支版本的規定 (如 FCM 版本 5 所述)。這些需求是從 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 物件只會考量與裝置核心 (即 ${ver} 和 ${major_rev}) 相同的 ${ver} 和 ${major_rev} 的 FCM 版本，而非 FCM 的 <kernel> 部分。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()。

範例：成功比對 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 (例如 1.0、2.1)。詳情請參閱「版本管理與相容性」。AVB 版本具有以下系統屬性：

  • ro.boot.vbmeta.avb_version 是系統啟動載入程式中的 libavb 版本
  • ro.boot.avb_version 是 Android 作業系統 (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
  • 使用架構相容性矩陣中的 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 OS 可能會包含兩個 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) 可將假的 AVB 版本放入 OTA 套件 (compatibility.zip) 中，以便通過檢查。方法如下：

  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> 標記，則具備 <version> 相符要求的 <vendor-ndk> 項目，是根據架構資訊清單中架構提供的 VNDK 供應商快照組合查詢。如果項目不存在，表示沒有相符項目。

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

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

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

如果裝置相容性矩陣在系統 SDK 上列出下列要求：

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

然後，該架構必須提供 System 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 不相符。