匹配規則

兩對兼容性矩陣和清單旨在進行協調，以驗證框架和供應商實現可以相互配合。框架兼容性矩陣和設備清單之間以及框架清單和設備兼容性矩陣之間匹配時，此驗證成功。

驗證是在構建時， OTA更新包生成時，引導時以及VTS兼容性測試中完成的。

以下各節詳細介紹了各種組件使用的匹配規則。

框架兼容性列表版本匹配

要將設備清單與框架兼容性矩陣相匹配， manifest.target-level指定的Shipping FCM版本必須與compatibility-matrix.level指定的FCM版本compatibility-matrix.level 。否則沒有匹配。

當使用libvintf請求框架兼容性矩陣時，此匹配總是成功的，因為libvintf打開設備清單，檢索Shipping FCM版本，並以該Shipping FCM版本返回框架兼容性矩陣（以及來自較高FCM兼容性矩陣的一些可選HAL）版本）。

HAL比賽

HAL-match規則標識清單文件中的hal元素的版本，這些元素被認為由相應的兼容性矩陣的所有者支持。

• 多個<hal>元素使用單個AND關係進行求值。
• 同一<hal>中的多個<version>元素具有OR關係。如果指定了兩個或多個，則僅需要實現其中一個版本。 （請參閱下面的DRM示例。）
• 使用單個AND關係評估同一<hal>中的多個<instance>和<regex-instance>元素。 （請參閱下面的DRM示例。）

示例：相機模塊的HAL成功匹配

對於2.5版的HAL，匹配規則如下：

示例：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

AND還必須實現所有這些實例：

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內核的框架要求。該信息應與設備的VINTF對象報告的有關內核的信息相匹配。

匹配內核分支

每個內核分支後綴（例如5.4- r ）都映射到唯一的內核FCM版本（例如5）。映射與發行版字母（例如R）和FCM版本（例如5）之間的映射相同。

如果滿足以下條件之一，則VTS測試會強制設備在設備清單/vendor/etc/vintf/manifest.xml明確指定內核FCM版本：

• 內核FCM版本與目標FCM版本不同。例如，上述設備具有目標FCM版本4，並且其內核FCM版本為5（內核分支後綴r ）。
• 內核FCM版本大於或等於5（內核分支後綴r ）。

VTS測試強制執行以下操作：如果指定了內核FCM版本，則內核FCM版本大於或等於設備清單中的目標FCM版本。

示例：確定內核分支

如果設備具有目標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構建的。

匹配內核版本

矩陣可以包含多個<kernel>部分，每個部分使用以下格式具有不同的version屬性：

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

VINTF對象僅考慮FCM中與設備內核相同的${ver}和${major_rev}與之匹配的FCM版本的FCM中的<kernel>部分（即， version="${ver}.${major_rev}.${matrix_minor_rev}") ;其他部分將被忽略。此外，內核的次要修訂版必須是兼容性矩陣中的值（ ${kernel_minor_rev} >= ${matrix_minor_rev} ;）。如果沒有<kernel>部分滿足這些要求，則為不匹配。

示例：選擇匹配條件

考慮以下假設情況，其中/system/etc/vintf聲明以下要求（省略了header和footer標籤）：

<!-- 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中選擇內核要求：

匹配內核配置

如果<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提供了/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的框架兼容性列表具有以下內核信息：

<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，與矩陣不匹配。 VINTF對象改為從FCM版本2的矩陣中讀取內核要求。

然後，匹配內核版本。如果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>為每個主要版本定義一個較小的次要版本範圍。設備報告的分隔版本必須落入這些範圍之一以與框架兼容。匹配規則類似於HAL版本；如果Sepolicy版本高於或等於該範圍的最低版本，則為匹配項。最高版本僅供參考。
• <kernel-sepolicy-version>即policydb版本。必須小於設備報告的security_policyvers() 。

示例：成功的SE策略匹配

框架兼容性矩陣指出以下隔離信息：

<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中的libavb版本（ init/fs_mgr ）

僅當已使用相應的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庫的兩個副本，每個副本都具有用於升級設備和啟動設備的不同MAJOR版本。在這種情況下，可以共享相同的未簽名系統映像，但是最終的已簽名系統映像是不同的（具有不同的avb.vbmeta-version ）：

示例：成功的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版本匹配。如果在OTA期間AVB版本進行了主要版本升級（例如，從0.0升級到1.0），則VINTF檢查OTA中的兼容性不會反映OTA之後的兼容性。

為了緩解此問題，OEM可以在OTA軟件包（ compatibility.zip ）中放置偽造的AVB版本以通過檢查。為此：

1. 將以下CL挑選到Android 9源代碼樹中：
   • CL 732261
   • CL 732262
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不是匹配項。即使框架清單中libjpeg.so VNDK版本27，該快照中的框架也不支持libjpeg.so 。 VNDK版本26被忽略。

系統SDK版本匹配

設備兼容性矩陣在compatibility-matrix.system-sdk.version聲明了一組必需的系統SDK版本。僅當集合是框架清單中manifest.system-sdk.version中聲明的提供的系統SDK版本的子集時，才存在匹配項。

• 作為一種特殊情況，如果設備兼容性列表中未列舉任何System SDK版本，則始終將其視為匹配項，因為空集是任何集的子集。

示例：成功的系統SDK版本匹配

如果設備兼容性列表對System 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>

示例C不匹配，因為未提供System SDK版本27。