自 2025 年 3 月 27 日起，我们建议您使用 android-latest-release 而非 aosp-main 构建 AOSP 并为其做出贡献。如需了解详情，请参阅 AOSP 的变更。

FCM 生命周期

Android 框架版本具有多个框架兼容性矩阵 (FCM)，每个矩阵对应一个可升级的目标 FCM 版本，用于定义框架可以使用哪些内容以及目标 FCM 版本要求。在 FCM 生命周期中，Android 会废弃并移除 HIDL HAL，然后修改 FCM 文件，以反映 HAL 版本的状态。

若要在自己的生态系统中启用仅针对框架的 OTA，扩展供应商接口的合作伙伴还应使用相同的方法弃用并移除 HIDL HAL。

术语

框架兼容性矩阵 (FCM): 一种 XML 文件，用于指定需要满足哪些框架要求才是合规的供应商实现。兼容性矩阵带有版本编号，对于每个框架版本，都会冻结一个新版本的兼容性矩阵。每个框架版本都包含多个 FCM。
平台 FCM 版本 (S_F): 框架版本中所有 FCM 版本的集合。框架适用于所有符合其中一个 FCM 的供应商实现。
FCM 版本 (F): 在框架版本中，所有 FCM 中的最高版本。
目标 FCM 版本 (V): 供应商实现符合的目标 FCM 版本（S_F 中的版本），已在设备清单中明确声明。必须针对已发布的 FCM 生成供应商实现，即使它可能在其设备清单中声明了更高的 HAL 版本，也是如此。
HAL 版本: HAL 版本采用 foo@x.y 格式，其中 foo 是 HAL 名称，x.y 是具体版本；例如 nfc@1.0、keymaster@3.0（本文档中省略了根前缀，例如 android.hardware。）
设备清单: XML 文件，用于指定设备接口的设备端（包括供应商和 ODM 映像）提供的 HAL 版本。设备清单的内容受设备的目标 FCM 版本限制，但可以列出与 V 对应的 FC 相比更新的 HAL。
设备 HAL: 在设备清单中列出（已提供）以及在框架兼容性矩阵 (FCM) 中列出的 HAL。
设备兼容性矩阵 (DCM): 一个 XML 文件，用于指定需要满足哪些供应商要求才是合规的框架实现。每个设备包含一个 DCM。
框架清单: 一种 XML 文件，用于指定供应商接口的框架端（包括 system、system_ext 和 product 映像）提供的 HAL 版本。系统会根据设备的目标 FCM 版本动态停用框架清单中的 HAL。
框架 HAL: 在框架清单中列为“已提供”以及在设备兼容性矩阵 (DCM) 中列出的 HAL。

代码库中的 FCM 生命周期

本文档简要介绍了 FCM 生命周期。如需查看支持的清单，请参阅 hardware/interfaces/compatibility_matrix.<FCM>.xml（其中 FCM 可在 system/libvintf/include/vintf/Level.h 中找到）。

搭载相应 Android 发布版本的设备的 FCM 值应大于或等于相应级别。例如，搭载 Android 11 的设备通常具有 FCM 级别 5，但可实现 FCM 级别 6 或更高级别，这需要满足兼容性矩阵中指定的各种附加要求。Android 15 支持的级别如下：

FCM	Android 版本
5	Android 11/R
6	Android 12/S
7	Android 13/T
8	Android 14/U
202404	Android 15/V

FCM 级别等于或高于供应商 API 级别。

当 Android 废弃某个 FCM 级别时，该级别仍会继续支持现有设备。以较低 FCM 级别为目标的设备隐式允许使用较高 FCM 级别中列出的 HAL，只要这些 HAL 在分支中可用即可。

使用新 FCM 版本进行开发

Android 会针对每个框架版本递增 FCM 版本（如 Android 8 和 8.1）。在开发期间，会创建新的 compatibility_matrix.F.xml，且不再更改现有的 compatibility_matrix.f.xml（其中 f < F）。

如需开始使用新 FCM 版本 F 进行开发，请执行以下操作：

将最新的 compatibility_matrix.<F-1>.xml 复制到 compatibility_matrix.F.xml。
将文件中的 level 属性更新为 F。
添加相应的构建规则，以便将此兼容性矩阵安装到设备。

引入新 HAL

在开发期间，为使用当前有效 FCM 版本 F 的 Android 引入新 HAL（Wi-Fi、NFC 等）时，请将相应 HAL 添加到 compatibility_matrix.F.xml。

例如，Android 8.1 引入了 cas@1.0。搭载 Android 8.1 的设备可以实现此 HAL，因此将以下条目添加到了 compatibility_matrix.F.xml（曾在该版本的开发过程中被临时命名为 compatibility_matrix.current.xml）：

<hal format="hidl">
    <name>android.hardware.cas</name>
    <version>1.0</version>
    <interface>
        <name>IMediaCasService</name>
        <instance>default</instance>
    </interface>
</hal>

升级 HAL（次要版本）

AIDL HAL 版本计为次要 HAL 版本。HIDL 接口版本具有 major.minor 版本，例如 1.2。

在开发期间，当 AIDL HAL 在当前有效 FCM 版本 F 下将版本从 2 升级到 3 时，新版本会添加到 compatibility_matrix.F.xml 中的 HAL 条目。HAL 条目的版本字段接受 2-3 等范围。

例如，Android FCM F 引入了 foo@3 作为 HAL 的次要版本升级。较旧版本 foo@2 用于定位到较旧 FCM 的设备，而较新版本 foo@3 可用于定位到 Android FCM F 的设备。在版本 2 之前的旧版 FCM 中的条目如下所示：

<hal format="aidl">
    <name>foo</name>
    <version>2</version>
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

此条目复制到了 compatibility_matrix.F.xml，并修改为支持版本 3，如下所示：

<hal format="aidl">
    <name>foo</name>
    <version>2-3</version>
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

升级 HAL（主要版本）

在开发期间，当 HAL 有在当前有效 FCM 版本 F 下的主要版本升级时，新的主要版本 x.0 会添加到 compatibility_matrix.F.xml，并会采用以下设置：

仅版本 x.0（如果搭载 V = F 的设备必须附带 x.0）。
与较旧的主要版本位于同一个 <hal> 标记中（如果搭载 V = F 的设备可以附带较旧的主要版本）。

例如，FCM 版本 F 引入了 foo@2.0 作为 1.0 HAL 的主要版本升级，并废弃了 1.0 HAL。旧版本 foo@1.0 用于以以前的 FCM 版本为目标的设备。如果设备提供 HAL，则定位到 FCM 版本 F 的设备必须提供新的 2.0 版本。在此示例中，之前的 FCM 版本包含以下条目：

<hal format="hidl">
    <name>foo</name>
    <version>1.0</version>;
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

将此条目复制到 compatibility_matrix.F.xml，并进行以下修改：

<hal format="hidl">
    <name>foo</name>
    <version>2.0</version>
    <interface>
        <name>IFoo</name>
        <instance>default</instance>
    </interface>
</hal>

限制条件：

由于 1.0 HAL 不在 compatibility_matrix.F.xml 中，因此以 FCM 版本 F 为目标的设备不得提供 1.0 HAL（因为此 HAL 会被视为已废弃）。
由于 1.0 HAL 存在于较旧的 FCM 版本中，因此该框架仍可以支持 1.0 HAL，从而向后兼容以较旧 FCM 版本为目标的旧设备。

新 FCM 版本

在 system 分区上发布 FCM 版本的流程是在 AOSP 发布时由 Google 单独完成的，包含以下步骤：

确保 compatibility_matrix.F.xml 具有 level="F" 属性。
确保所有设备都已构建并启动。
更新 VTS 测试，确保附带最新框架（基于 Shipping API 级别）的设备搭载的目标 FCM 版本 V >= F。
将文件发布到 AOSP。

例如，VTS 测试可确保搭载 Android 9 的设备的目标 FCM 版本 >= 3。

此外，product 和 system_ext FCM 也可能列出每个平台 FCM 版本的相应要求。product 和 system_ext 分区上 FCM 版本的发布分别由这些映像的所有者完成。product 和 system_ext 分区上的 FCM 版本号必须与 system 分区上的 FCM 版本号一致。与 system 分区上的 FCM 版本类似，product 和 system_ext 分区中 FCM 版本 F 的兼容性矩阵反映了搭载目标 FCM 版本 F 的设备需要满足的要求。

HAL 版本废弃

是否废弃 HAL 版本由开发者决定（例如，是否废弃 AOSP HAL 由 Google 决定）。发布较高版本的 HAL（无论是次要版本还是主要版本）时，可能需要做出此类决定。

废弃设备 HAL

如果在 FCM 版本 F 下废弃指定 HAL foo@x.y，则意味着任何搭载目标 FCM 版本 V = F 或更高版本的设备都不得在 x.y 或任何低于 x.y 的版本下实现 foo。框架仍支持已废弃的 HAL 版本，以便升级设备。

FCM 版本 F 发布后，如果在目标 FCM 版本 V = F 对应的最新 FCM 中未明确声明 HAL 版本 foo@x.y，则该版本会被视为已废弃。对于搭载 V = F 的设备，以下条件之一为 true：

框架需要较高版本（主要版本或次要版本）；
框架不再需要该 HAL。

例如，Android 9 中引入了 health@2.0 作为 1.0 HAL 的主要版本升级。health@1.0 已从 compatibility_matrix.3.xml 中移除，但存在于 compatibility_matrix.legacy.xml、compatibility_matrix.1.xml 和 compatibility_matrix.2.xml 中。因此，health@1.0 被视为已废弃。

废弃框架 HAL

在 FCM 版本 F 下废弃指定框架 HAL foo@x.y 后，任何发布时搭载目标 FCM 版本 V = F 或更高版本的设备的该框架都不再在 x.y 或任何低于 x.y 的版本下提供 foo。框架仍提供已废弃的 HAL 版本，以便升级设备。

FCM 版本 F 发布后，如果框架清单为 foo@x.y 指定了 max-level="F - 1"，则 HAL 版本 foo@x.y 会被视为已废弃。对于发布时搭载 V = F 的设备，框架不提供 HAL foo@x.y。发布时搭载 V = F 的设备上的设备兼容性矩阵不得列出符合 max-level < V 的框架 HAL。

例如，Android 12 中已废弃了 schedulerservice@1.0。其 max-level 属性设置为 5（Android 11 中引入的 FCM 版本）。请参阅 Android 12 框架清单。

取消对目标 FCM 版本的支持

当搭载某个目标 FCM 版本 V 的有效设备数量降至特定阈值以下时，应将该目标 FCM 版本从下一个框架版本的 S_F 集中移除。这是通过以下两个步骤完成的：

从构建规则中移除 compatibility_matrix.V.xml（以便它不再安装在系统映像中），并删除用于实现或依赖于已移除功能的所有代码。
从框架清单中移除 max-level 低于或等于 V 的框架 HAL，并删除用于实现已移除的框架 HAL 的所有代码。

如果设备搭载的目标 FCM 版本不在指定框架版本的 S_F 之内，则无法升级到该版本。

HAL 版本状态

下文介绍了 HAL 版本的可能状态（按时间先后顺序）。

未发布

对于设备 HAL，如果 HAL 版本不在任何公开且冻结的兼容性矩阵中，则被视为未发布且可能正在开发中。这包括仅在 compatibility_matrix.F.xml 中的 HAL 版本。示例：

在 Android 9 开发期间，health@2.0 HAL 被视为未发布的 HAL，并且仅存在于 compatibility_matrix.3.xml 中。
teleportation@1.0 HAL 不在任何已发布的兼容性矩阵中，也被视为未发布的 HAL。

对于框架 HAL，如果 HAL 版本仅在无关开发分支的框架清单中，则会被视为未发布版本。

已发布且当前有效

对于设备 HAL，如果 HAL 版本位于任何公开且冻结的兼容性矩阵中，则为已发布版本。例如，FCM 版本 3 冻结并发布到 AOSP 后，health@2.0 HAL 会被视为已发布且当前有效的 HAL 版本。

如果 HAL 版本位于包含最高 FCM 版本的公开且冻结兼容性矩阵中，则 HAL 版本为当前有效版本（即未废弃版本）。例如，如果现有的 HAL 版本（例如，在 compatibility_matrix.legacy.xml 中引入的 nfc@1.0）继续存在于 compatibility_matrix.3.xml 中，则也会被视为已发布且当前有效的 HAL 版本。

对于框架 HAL，如果 HAL 版本在最新发布的分支的框架清单中，但没有 max-level 属性或（通常）max-level 等于或高于此分支中发布的 FCM 版本，则会被视为已发布且当前有效的 HAL 版本。例如，displayservice HAL 在 Android 12 中是已发布且当前有效的版本（由 Android 12 框架清单指定）。

已发布但已废弃

对于设备 HAL，当且仅当满足以下条件时，HAL 版本才会被视为废弃：

已发布；
不在包含最高 FCM 版本的公开且冻结兼容性矩阵中；
在框架仍支持的公开且冻结兼容性矩阵中。

示例：

health@1.0 HAL 在 compatibility_matrix.legacy.xml、compatibility_matrix.1.xml 和 compatibility_matrix.2.xml 中，但不在 compatibility_matrix.3.xml 中。因此，它在 Android 9 中被视为已废弃。
电量 HAL 在 Android 9 中有次要版本升级，但 power@1.0 仍在 compatibility_matrix.3.xml 中。
power@1.0 compatibility_matrix.legacy.xml、compatibility_matrix.1.xml 和 compatibility_matrix.2.xml。
compatibility_matrix.3.xml 包含 power@1.0-1。

因此，在 Android 9 中，power@1.0 为当前有效版本，而不是已废弃版本。

对于框架 HAL，如果 HAL 版本在最新发布的分支的框架清单中，并且 max-level 属性低于此分支中发布的 FCM 版本，则会被视为已发布但已废弃的 HAL 版本。例如，schedulerservice HAL 已发布，但在 Android 12 中已废弃（由 Android 12 框架清单指定）。

已移除

对于设备 HAL，当且仅当满足以下条件时，HAL 版本会被视为已移除：

之前已发布；
不在框架支持的任何公开且冻结兼容性矩阵中。

不受框架支持的公开且冻结兼容性矩阵会保留在代码库中，以便指定已移除的 HAL 版本集，从而可以写入 VTS 测试，确保新设备上没有已移除的 HAL。

对于框架 HAL，当且仅当满足以下条件时，HAL 版本会被视为已移除：

之前已发布；
不在最新发布的分支的任何框架清单中。

旧版 FCM

对于所有不支持 Treble 的设备，旧版目标 FCM 版本是一个特殊值。旧版 FCM compatibility_matrix.legacy.xml 列出了框架对旧版设备（即搭载 Android 8.0 之前版本的设备）的要求。

如果版本为 F 的 FCM 具有此文件，则任何不支持 Treble 的设备均可升级到 F，但前提是其设备清单与此文件兼容。移除旧版 FCM 的程序与移除其他目标 FCM 版本对应的 FCM 的程序相同（在搭载 8.0 之前版本的有效设备数量降至特定阈值以下后移除）。

已发布的 FCM 版本

您可以在 hardware/interfaces/compatibility_matrices 下找到已发布的 FCM 版本的列表。

如需查找针对特定 Android 版本发布的 FCM 版本，请参阅 Level.h。

FCM 生命周期 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

术语