兼容性矩阵

本部分介绍了框架和设备兼容性矩阵以及兼容性矩阵架构。如需了解匹配规则,请参阅匹配规则

框架兼容性矩阵 (FCM)

框架兼容性矩阵说明了框架对运行它的设备的要求。矩阵文件与 Android 框架映像(位于 system.img 中)相关联。FCM 的要求应通过设备清单来满足(在启动和 OTA 时会强制执行相应要求)。

示例 FCM 文件:

<?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>
    </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 与系统分区中的 FCM 连接起来。

产品 FCM 是对设备专用 FCM(安装在系统分区中)的补充。设备 FCM 应反映系统分区中各模块的要求,而产品 FCM 应反映产品分区中各模块的要求。两者都应与原始设备制造商 (OEM) 对系统分区和产品分区中框架的修改保持一致。

例如,如果安装在产品分区中的应用使用某个 HAL 接口的供应商扩展,则应在产品 FCM 中声明该 HAL 接口的要求。

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

设备兼容性矩阵 (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 标记的含义。某些“必需”的标记可以在构建时由 assemble_vintf 写入,因此不一定要包含在 Android 源代码树中的源文件中。设备上的相应文件中必须有“必需”标记。

?xml
可选。它只向 XML 解析器提供信息。
compatibility-matrix.version
必需。此兼容性矩阵的元版本。描述兼容性矩阵中预期的元素。与 XML 版本无关。
compatibility-matrix.type
必需。此兼容性矩阵的类型:
  • "device":设备兼容性矩阵。
  • "framework":框架兼容性矩阵。
manifest.level
框架兼容性矩阵的必需标记。指定此文件的框架兼容性矩阵版本(FCM 版本)。不应在设备专用的框架兼容性矩阵(即 DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE)中声明。
compatibility-matrix.hal
可选且可重复。列出兼容性矩阵(框架或设备)的所有者要求存在的单个 HAL(HIDL 或本机)。HAL 条目通过 <name> 元素来区分,可以有多个同名的 HAL 条目(暗含着“和”条件)。
compatibility-matrix.hal.format
可选。值可以是以下几项之一:
  • "hidl":HIDL HAL。这是默认值。
  • "native":本机 HAL。
compatibility-matrix.hal.optional
此属性是可选的,默认值为 false。指明此 HAL 对兼容性矩阵(框架或设备)的所有者来说是否为可选。如果将 <hal> 条目标记为可选,表示在存在的情况下,所有者可以使用此 HAL,但并非是必须存在。
compatibility-matrix.hal.name
必需。此 HAL 的完整软件包名称。例如:
  • android.hardware.camera (HIDL HAL)
  • GLES(本机 HAL,只需提供名称)
compatibility-matrix.hal.version
必需,可以在不重名的情况下重复。版本范围的列表(请参阅 HAL 匹配),用于定义兼容性矩阵(框架或设备)的所有者期望的版本。
compatibility-matrix.hal.interface
可选且可重复。该 HAL 的必需接口的列表。
compatibility-matrix.hal.interface.name
必需。接口的名称。
compatibility-matrix.hal.interface.instance
可选且可重复。此接口的必需实例的列表。
compatibility-matrix.hal.interface.regex-instance
可选且可重复。此接口上的必需实例名称模式的列表。使用扩展正则表达式格式。
compatibility-matrix.kernel
可选且可重复。指定框架在每个内核版本上必需的内核配置的列表。
可以存在具有同一 <version> 的多个 <kernel>,暗含着“和”关系。每个 <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 - 接受十进制和十六进制值(必须以 0x0X) 开头)。解释为 64 位整数,溢出部分会被截断。(解析器接受从 -264 + 1 到 264 - 1 的值,第 65 位会被截断;如需了解详情,请参阅 strtoull 手册页。)
  • range - 格式为 [int]-[int],例如 10-20。接受十六进制值,且值必须以 0x0X 开头。两个边界必须是无符号的 64 位整数。
  • tristate - 有效值为 ymn
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
可选且可重复,仅供设备兼容性矩阵使用。声明供应商应用对 System SDK 版本的要求。如果缺失,系统映像对系统 SDK 没有要求。