Android系统之VINTF(2)FCM Lifecycle

由 adtxl 发布

1. 术语

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

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

术语 描述
Framework Compatibility Matrix (FCM) An XML file that specifies framework requirements on conforming vendor implementations. The compatibility matrix is versioned, and a new version is frozen for each framework release. Each framework release contains multiple FCMs.
Platform FCM Versions (SF) The set of all FCM versions in a framework release. The framework can work with any vendor implementation that satisfies one of these FCMs.
FCM Version (F) The highest version among all FCMs in a framework release.
Target FCM Version (V) The targeted FCM version (from S F), declared explicitly in the device manifest, that a vendor implementation satisfies. A vendor implementation must be generated against a published FCM, although it may declare newer HAL versions in its Device Manifest.
HAL Version A HAL Version has the format foo@x.y, where foo is the HAL name and x.y is the specific version; e.g. nfc@1.0, keymaster@3.0 (the root prefix, e.g. android.hardware, is omitted throughout this document.)
Device Manifest XML files that specify which HAL versions the device side of the vendor interface, including the vendor and ODM images, provides. The contents of a device manifest are constrained by the Target FCM version of the device but can list HALs that are strictly newer relative to the FCM corresponding to V.
Device HALs HALs that are listed (provided) in the device manifest and listed (either required or optional) in the framework compatibility matrix (FCM).
Device Compatibility Matrix (DCM) An XML file that specifies vendor requirements on conforming framework implementations. Each device contains one DCM.
Framework Manifest An XML file that specifies which HAL versions the framework side of the vendor interface, including system, system_ext, and product images, provides. HALs in the framework manifest are dynamically disabled according to the device's Target FCM version.
Framework HALs HALs that are listed as provided in the framework manifest and listed as either required or optional in the device compatibility matrix (DCM).

2. Developing in a new FCM Version

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

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

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

3. 引入新 HAL

在开发期间,为使用当前有效 FCM 版本 F 的 Android 引入新 HAL(WLAN、NFC 等)时,请将相应 HAL 添加到 compatibility_matrix.current.xml,并采用以下 optional 设置:

  • optional="false"(如果搭载 V = F 的设备必须附带此 HAL),

  • optional="true"(如果搭载 V = F 的设备可以不附带此 HAL)。

例如,Android 8.1 引入了 cas@1.0 作为可选 HAL。 搭载 Android 8.1 的设备无需实现此 HAL,因此将以下条目添加到了 compatibility_matrix.current.xml(Android 8.1 发布后已改名为 compatibility_matrix.2.xml)中:

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

4. 升级 HAL

4.1 升级HAL(Minor)

开发期间,在当前 FCM 版本 F 下将 HAL 的 Minor 版本从 x.z 升级到 x.(z+1) 时,如果:

  • 搭载 V = F 的设备必须使用此版本,则 compatibility_matrix.current.xml 必须声明 x.(z+1)optional="false"

  • 搭载 V = F 的设备无需使用此版本,则 compatibility_matrix.current.xml 必须从 compatibility_matrix.<F-1>.xml 复制 x.y-z 和可选性,并将版本更改为 x.w-(z+1)(其中 w >= y)。

  • Required on devices launching with V = F, the compatibility_matrix.current.xml must state x.(z+1)and optional="false".

  • Not required on devices launching with V = F, the compatibility_matrix.current.xml must copy x.y-z and optionality from compatibility_matrix.<F-1>.xml and change the version to x.w-(z+1) (where w >= y).

例如,Android 8.1 引入了 broadcastradio@1.1 作为 1.0 HAL 的 Minor 版本升级。对于搭载 Android 8.0 的设备,较旧版本 broadcastradio@1.0 是选用版本;对于搭载 Android 8.1 的设备,较新版本 broadcastradio@1.1 是选用版本。在 compatibility_matrix.1.xml 中:

<hal format="hidl" optional="true">
    <name>android.hardware.broadcastradio</name>
    <version>1.0</version>
    <interface>
        <name>IBroadcastRadioFactory</name>
        <instance>default</instance>
    </interface>
</hal>

此条目复制到了 compatibility_matrix.current.xml(Android 8.1 发布后已改名为 compatibility_matrix.2.xml),并进行了以下修改:

<hal format="hidl" optional="true">
    <name>android.hardware.broadcastradio</name>
    <version>1.0-1</version>
    <interface>
        <name>IBroadcastRadioFactory</name>
        <instance>default</instance>
    </interface>
</hal>

4.2 升级 HAL (Major)

在开发期间,当 HAL 有在当前 FCM 版本 F 下的 Major 版本升级时,新的 Major 版本 x.0 会添加到 compatibility_matrix.current.xml,并会采用以下 optional 设置:

  • optional="false" 且仅包含版本 x.0(如果搭载 V = F 的设备必须附带 x.0)。
  • optional="false",但与较旧的 Major 版本位于同一个 <hal> 标记中(如果搭载 V = F 的设备必须附带此 HAL,但可以附带较旧的 Major 版本)。
  • optional="true"(如果搭载 V = F 的设备可以不附带此 HAL)。

例如,Android 9 引入了 health@2.0 作为 1.0 HAL 的 Major 版本升级,并弃用了 1.0 HAL。对于搭载 Android 8.0 和 Android 8.1 的设备,较旧版本 health@1.0 是选用版本。搭载 Android 9 的设备不得提供已弃用的 1.0 HAL,必须改为提供新的 2.0 版本。在 compatibility_matrix.legacy.xml、compatibility_matrix.1.xml 和 compatibility_matrix.2.xml 中:

<hal format="hidl" optional="true">
    <name>android.hardware.health</name>
    <version>1.0</version>
    <interface>
        <name>IHealth</name>
        <instance>default</instance>
    </interface>
</hal>

此条目复制到了 compatibility_matrix.current.xml(在 Android 9 版本中已改名为 compatibility_matrix.3.xml),并进行了以下修改:

<hal format="hidl" optional="false">
    <name>android.hardware.health</name>
    <version>2.0</version>
    <interface>
        <name>IHealth</name>
        <instance>default</instance>
    </interface>
</hal>

限制条件:

  • 由于 2.0 HAL 在 compatibility_matrix.3.xml 中且 optional="false",因此搭载 Android 9 的设备必须附带 2.0 HAL。
  • 由于 1.0 HAL 不在 compatibility_matrix.3.xml 中,因此搭载 Android 9 的设备不得提供 1.0 HAL(因为此 HAL 会被视为已弃用)。
  • 由于 1.0 HAL 作为选用 HAL 存在于 legacy/1/2.xml(Android 9 可以支持的较旧 FCM 版本)中,因此 Android 9 框架仍可以支持 1.0 HAL(不会被视为已移除的 HAL 版本)。

5. 新 FCM 版本

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

compatibility_matrix.current.xml 重命名为 compatibility_matrix.F.xml
确保该文件具有属性 level="F"

  1. Rename compatibility_matrix.current.xml to compatibility_matrix.F.xml.
  2. Ensure the file has the attribute level="F".
  3. Edit corresponding build rules to reflect the file name change.
  4. Ensure all devices build and boot.
  5. Update VTS tests to ensure devices launching with the latest framework (based on Shipping API level) have Target FCM Version V >= F.
  6. Publish file to AOSP.

此文件一经改名并发布,便无法更改。例如,在 Android 9 开发期间,针对 hardware/interfaces/compatibility_matrices/ 构建了以下文件:

compatibility_matrix.legacy.xml
compatibility_matrix.1.xml
compatibility_matrix.2.xml
compatibility_matrix.current.xml

Android 9 发布后,compatibility_matrix.current.xml 改名为 compatibility_matrix.3.xml 并针对 hardware/interfaces/compatibility_matrices/构建了以下文件:

compatibility_matrix.legacy.xml
compatibility_matrix.1.xml
compatibility_matrix.2.xml
compatibility_matrix.3.xml

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反映了对device上也要运行目标 FCM 版本 F 。

6. HAL 版本弃用

是否弃用 HAL 版本由开发者决定(例如,是否弃用 AOSP HAL 由 Google 决定)。发布较高版本的 HAL(无论是 Minor 版本还是 Major 版本)时,可能需要做出此类决定。

6.1 Deprecate a device HAL

When a given device HAL foo@x.y is deprecated at FCM Version F, it means that any device launching with Target FCM Version V = F or later must not implement foo at version x.y or any version older than x.y. A deprecated HAL version is still supported by the framework for upgrading devices.

When FCM Version F is released, a HAL Version foo@x.y is considered deprecated if the specific HAL Version is not explicitly stated in the latest FCM for Target FCM Version V = F. For devices launching with V = F, one of the following conditions is true:

  • The framework requires a higher version (major or minor);
  • The framework doesn't require the HAL anymore.

For example, in Android 9, health@2.0 is introduced as a major version upgrade of 1.0 HAL. health@1.0 is removed from compatibility_matrix.3.xml but is present in compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, and compatibility_matrix.2.xml. Hence, health@1.0 is considered deprecated.

6.2 Deprecate a framework HAL

When a given framework HAL foo@x.y is deprecated at FCM Version F, it means that any device launching with Target FCM Version V = F or later must not expect the framework to provide foo at version x.y, or at any version older than x.y. A deprecated HAL version is still provided by the framework for upgrading devices.

When FCM version F is released, a HAL Version foo@x.y is considered deprecated if the framework manifest specifies max-level="F - 1" for foo@x.y. For devices launching with V = F, the framework doesn't provide the HAL foo@x.y. The device compatibility matrix on devices launching with V = F must not list framework HALs with max-level < V.

For example, in Android 12, schedulerservice@1.0 is deprecated. Its max-level attribute is set to 5, the FCM version introduced in Android 11.

7. Removal of support for Target FCM Versions

When active devices of a certain Target FCM Version V drop below a certain threshold, the Target FCM Version is removed from the set SF of the next framework release. This is done by both of the following steps:

  • Removing compatibility_matrix.V.xml from the build rules (so that it isn't installed on the system image), and deleting any code that implemented or depended on the removed functionality.
  • Removing framework HALs with max-level lower than or equal to V from the framework manifest, and deleting any code that implements the removed framework HALs.

Devices with a target FCM Version outside of SF for a given framework release cannot upgrade to that release.

8. HAL 版本状态

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

8.1 未发布(Unreleased)

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

  • 在 Android 9 开发期间(在 compatibiility_matrix.current.xml 改名为 compatibility_matrix.3.xml 之前),health@2.0 HAL 被视为未发布的 HAL。
  • teleportation@1.0 HAL 不在任何已发布的兼容性矩阵中,也被视为未发布的 HAL。

For framework HALs, if a HAL version is only in the framework manifest of an unrelated development branch, it's considered unreleased.

8.2 已发布且当前有效(Released and Current)

For device HALs, if a HAL Version is in any public and frozen compatibility matrix, it is released. For example, after FCM Version 3 is frozen (when compatibiility_matrix.current.xml is renamed to compatibility_matrix.3.xml) and published to AOSP, the health@2.0 HAL is considered a released and current HAL Version.

If a HAL Version is in a public and frozen compatibility matrix that has the highest FCM Version (excluding compatibility_matrix.current.xml), the HAL version is current (i.e. not deprecated). For example, existing HAL Versions (such as nfc@1.0 introduced in compatibility_matrix.legacy.xml) that continue to exist in compatibility_matrix.3.xml are also considered as released and current HAL Versions.

For framework HALs, if a HAL version is in the framework manifest of the latest released branch without the max-level attribute or (unusually) a max-level equal to or higher than the FCM version released in this branch, it is considered a released and current HAL version. For example, the displayservice HAL is released and current in Android 12, as specified by the Android 12framework manifest.

8.3 已发布但已弃用()

当全部满足以下情况时,HAL 版本会被视为已弃用:

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

示例:

health@1.0 HAL 在 compatibility_matrix.legacy.xml、compatibility_matrix.1.xml 和 compatibility_matrix.2.xml 中,但不在 compatibility_matrix.3.xml 中。因此,它在 Android 9 中被视为已弃用。
power HAL 在 Android 9 中有 Minor 版本升级,但 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 为当前有效版本,而不是已弃用版本。

8.4 已移除

当且仅当在以下情况时,HAL 版本会被视为已移除:

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

9. 旧版 FCM

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

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

10. 已发布的 FCM 版本

您可以在 hardware/interfaces/compatibility_matrices 下找到已发布的 FCM 版本的列表。
To find the FCM version released with a specific Android release, see Level.h


暂无评论

发表评论