兼容性矩阵

本部分介绍框架和设备兼容性矩阵以及兼容性矩阵结构。有关匹配规则,请参见匹配规则一文。

框架兼容性矩阵 (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 生命周期

设备兼容性矩阵 (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 写入。设备上的相应文件中必须有“必需”标记。

?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>,暗含着“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:接受十进制和十六进制值(必须以 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 版本
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 没有要求。