自 2025 年 3 月 27 日起，我們建議您使用 android-latest-release 而非 aosp-main 建構及貢獻 AOSP。詳情請參閱「Android 開放原始碼計畫變更」。

本頁面由 Cloud Translation API 翻譯而成。

相容性矩陣

本節將說明架構和裝置相容性矩陣，以及相容性矩陣結構定義。如要瞭解比對規則，請參閱「比對規則」。

架構相容性矩陣 (FCM)

架構相容性矩陣 (FCM) 說明架構在執行裝置上的相關需求。架構相容性矩陣包含系統相容性矩陣、產品相容性矩陣和 system_ext 相容性矩陣。裝置資訊清單必須符合 FCM 的要求 (要求會在建構時間、執行階段和 VTS 中強制執行)。

system_ext FCM 和產品 FCM 是裝置專屬 FCM (安裝在系統分區) 的補充項目。

裝置 FCM 應反映系統分區中的模組需求。
system_ext FCM 應反映 system_ext 分割區中模組的需求。
產品 FCM 應反映產品區隔中的模組需求。

所有 FCM 都應與原始設備製造商 (OEM) 對系統、產品和 system_ext 分區中架構所做的修改一致。舉例來說，如果在產品分區中安裝的應用程式使用 HAL 介面的供應商擴充功能，則應在產品 FCM 中宣告 HAL 介面需求。

系統相容性矩陣檔案範例：

<?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 寫入。裝置上的對應檔案中必須有「Required」標記。

?xml

選用。它只會向 XML 剖析器提供資訊。

compatibility-matrix.version

必填。這個相容性矩陣的元版本。說明相容性矩陣中預期的元素。與 XML 版本無關。

compatibility-matrix.type

必填。這個相容性矩陣的類型：

"device"：裝置相容性矩陣。
"framework"：架構相容性矩陣。

manifest.level

此屬性是架構相容性矩陣的必要條件。在 Android 12 以上版本中，允許在產品和 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 (Android 15 以下版本)

屬性為選用屬性，預設值為 false。指出這個 HAL 是否為相容性矩陣 (架構或裝置) 擁有者的選用項目。如果 <hal> 項目標示為選用，表示擁有者可使用此 HAL (如有)，但不強制要求使用。

警告：此屬性已在 Android 15 之後淘汰，且不再有任何效果。如果需要安裝任何 HAL，則應在測試中強制執行這項規定。

compatibility-matrix.hal.name

必填。此 HAL 的完整套件名稱。示例：

android.hardware.camera (HIDL 或 AIDL HAL)
GLES (原生 HAL，只需要名稱)

compatibility-matrix.hal.version

版本範圍清單 (請參閱「HAL 比對」)，定義相容性矩陣 (架構或裝置) 擁有者預期的版本。

針對 HIDL 和原生 HAL，這是必要項目，可重複使用而不重複。格式為下列其中一種：

MAJOR.MINOR_MIN-MINOR_MAX
MAJOR.MINOR (等同於 MAJOR.MINOR-MINOR)

針對 AIDL HAL，請勿在搭載 Android 11 以下版本的裝置上使用。適用於執行較新版本的裝置 (選用)。如果指定格式，則格式為下列其中一種：

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

選用，可重複。指定架構在各個核心版本上所需的核心設定清單。
<kernel> 可以與多個相同的 <version> 共存，表示「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 項目都是鍵/值組合，設定項目則以鍵來區分。

compatibility-matrix.kernel.config.key

必填。CONFIG 項目的鍵名稱。開頭為 CONFIG_。

compatibility-matrix.kernel.config.value

必填。CONFIG 項目的值。格式取決於類型：

string。引號已省略。
int。系統接受十進制和十六進制 (必須以 0x 或 0X) 開頭) 值。會解讀為 64 位元整數；溢位會導致截斷。(剖析器接受的值介於 -2⁶⁴ + 1 到 2⁶⁴ - 1 之間，第 65 位元會遭到截斷；詳情請參閱 strtoull 手冊頁面)。
range。格式為 [int]-[int]，例如 10-20。系統接受十六進制值，且開頭必須為 0x 或 0X。兩個邊界必須為不帶正負號的 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 需求。