FCM lifecycle

An Android framework release has multiple Framework Compatibility Matrixes (FCMs), one for each upgradable Target FCM Version, that define what the framework may use and Target FCM version requirements. As part of the FCM lifecycle, Android deprecates and removes HIDL HALs, then modifies FCM files to reflect the status of the HAL version.

To enable framework-only OTAs in their own ecosystems, partners who extend vendor interfaces should also deprecate and remove HIDL HALs using the same methods.

Terminology

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 (S_F): 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 FC 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).

FCM lifecycle in the codebase

This document describes the FCM lifecycle in the abstract. To see the supported manifests, refer to hardware/interfaces/compatibility_matrix.<FCM>.xml where FCM can be found in system/libvintf/include/vintf/Level.h.

A device shipping the corresponding Android release version is expected to have an FCM value greater than or equal to the equivalent level. For example, a device shipping with Android 11 would generally have FCM level 5, but implement FCM level 6 or greater, which comes with various additional requirements specified in the compatibility matrixes. The supported levels are:

FCM	Android Version
4	Android 10/Q
5	Android 11/R
6	Android 12/S
7	Android 13/T
8	Android 14/U
202404	Android 15/V

The FCM level is equal to or newer than the Vendor API Level.

When Android deprecates an FCM level, it's still supported for existing devices. Devices targeting lower FCM levels are implicitly allowed to use HALs listed in newer FCM levels, as long as they are available in the branch.

Develop in a new FCM version

Android increments the FCM version for each framework release (such as Android 8 and 8.1). During development, the new compatibility_matrix.F.xml is created and the existing compatibility_matrix.f.xml (where f < F) is no longer changed.

To start developing in a new FCM Version F:

Copy the latest compatibility_matrix.<F-1>.xml to compatibility_matrix.F.xml.
Update the level attribute in the file to F.
Add corresponding build rules to install this compatibility matrix to the device.

Introduce a new HAL

During development, when introducing a new HAL (Wi-Fi, NFC, etc.) to Android on the current FCM version F, add the HAL to compatibility_matrix.F.xml with the following optional settings:

optional="false" if devices that ship with V = F must launch with this HAL,
optional="true" if devices that ship with V = F can launch without this HAL.

For example, Android 8.1 introduced cas@1.0 as an optional HAL. Devices launching with Android 8.1 are not required to implement this HAL, so the following entry was added to compatibility_matrix.F.xml (which used to be named compatibility_matrix.current.xml temporarily during development of that release):

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

Upgrade a HAL (minor)

During development, when a HAL has a minor-version upgrade from x.z to x.(z+1) at current FCM Version F, if that version is:

Required on devices launching with V = F, compatibility_matrix.F.xml must state x.(z+1) and optional="false".
Not required on devices launching with V = F, compatibility_matrix.F.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).

For example, Android 8.1 introduced broadcastradio@1.1 as a minor version upgrade of 1.0 HAL. The older version, broadcastradio@1.0, is optional for devices launching with Android 8.0 while the newer version, broadcastradio@1.1, is optional for devices launching with Android 8.1. In 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>

This entry was copied to compatibility_matrix.F.xml and modified as follows:

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

Upgrade a HAL (major)

During development, when a HAL has a major-version upgrade at current FCM Version F, the new major version x.0 is added to compatibility_matrix.F.xml with the following optional settings:

optional="false" with only version x.0, if devices that ship with V = F must launch with x.0.
optional="false" but along with older major versions in the same <hal> tag, if devices that ship with V = F must launch with this HAL, but can launch with an older major version.
optional="true" if devices that ship with V = F don't have to launch the HAL.

For example, Android 9 introduces health@2.0 as a major-version upgrade of the 1.0 HAL and deprecates the 1.0 HAL. The older version, health@1.0, is optional for devices launching with Android 8.0 and Android 8.1. Devices launching with Android 9 must provide the new 2.0 version. For example, assume compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, and compatibility_matrix.2.xml contain this entry:

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

Copy this entry to compatibility_matrix.F.xml and modify as follows:

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

Restrictions:

Because the 2.0 HAL is in compatibility_matrix.3.xml with optional="false", devices that launch with Android 9 must ship with 2.0 HAL.`
Because the 1.0 HAL is not in compatibility_matrix.3.xml, devices that launch with Android 9 must not provide the 1.0 HAL (as this HAL is considered deprecated).
Because the 1.0 HAL is present in legacy/1/2.xml (older FCM Versions that Android 9 can work with) as an optional HAL, the Android 9 framework can still work with the 1.0 HAL (which is not considered a removed HAL Version).

New FCM versions

The process of releasing an FCM Version on the system partition is done solely by Google as part of an AOSP release and includes the following steps:

Ensure the compatibility_matrix.F.xml has the attribute level="F".
Ensure all devices build and boot.
Update VTS tests to ensure devices launching with the latest framework (based on Shipping API level) have Target FCM Version V >= F.
Publish file to AOSP.

For example, VTS tests ensure that devices launching with Android 9 have Target FCM Version >= 3.

In addition, the product and system_ext FCMs may also list requirements for each platform FCM versions. Release of FCM versions on the product and system_ext partitions is done by the owner of these images, respectively. FCM version numbers on the product and system_ext partitions must align with those on the system partition. Similar to FCM versions on the system partition, the compatibility matrix at FCM version F in the product and system_ext partitions reflects requirements on a device with target FCM version F.

HAL version deprecation

Deprecating a HAL Version is a developer decision (i.e. for AOSP HALs, Google makes the decision). It could happen when a higher HAL version (whether minor or major) is released.

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.

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. See Android 12 framework manifest.

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 S_F 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 capabilities.
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 S_F for a given framework release cannot upgrade to that release.

HAL version status

The following sections describe (in chronological order) the possible states of a HAL Version.

Unreleased

For device HALs, if a HAL Version is not in any of the public and frozen compatibility matrixes, it is considered unreleased and possibly in development. This includes HAL Versions that are only in compatibility_matrix.F.xml. Examples:

During the development of Android 9 the health@2.0 HAL was considered an unreleased HAL and was only present in compatibility_matrix.3.xml.
The teleportation@1.0 HAL is not in any released compatibility matrixes, and is also considered an unreleased HAL.

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

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 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 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 12 framework manifest.

Released but deprecated

For device HALs, a HAL Version is deprecated if and only if all of the following are met:

It is released.
It is not in the public and frozen compatibility matrix that has the highest FCM Version.
It is in a public and frozen compatibility matrix that the framework still supports.

Examples:

The health@1.0 HAL is in compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, and compatibility_matrix.2.xml, but not in compatibility_matrix.3.xml. Hence it is considered deprecated in Android 9.
The power HAL has a minor version upgrade in Android 9, but power@1.0 is still in compatibility_matrix.3.xml.
power@1.0 compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, and compatibility_matrix.2.xml.
compatibility_matrix.3.xml has power@1.0-1.

Hence power@1.0 is current, but NOT deprecated, in Android 9.

For framework HALs, if a HAL version is in the framework manifest of the latest released branch with a max-level attribute lower than the FCM version release in this branch, it is considered a released but deprecated HAL version. For example, the schedulerservice HAL is released but deprecated in Android 12, as specified by the Android 12 framework manifest.

Removed

For device HALs, a HAL Version is removed if and only if the following are true:

It was previously released.
It is not in any public and frozen compatibility matrix that the framework supports.

Compatibility matrixes that are public, frozen, but not supported by the framework are kept in the codebase to define the removed HAL Versions set so that VTS tests can be written to ensure removed HALs are not on new devices.

For framework HALs, a HAL version is removed if and only if the following are met:

It was previously released.
It is not in any framework manifest of the latest released branch.

Legacy FCMs

Target FCM Version legacy is a special value for all non-Treble devices. The legacy FCM, compatibility_matrix.legacy.xml, lists the requirements of the framework on legacy devices (i.e. devices launched prior to Android 8.0).

If this file exists for an FCM with version F, any non-Treble device can be upgraded to F provided its device manifest is compatible with this file. Its removal follows the same procedure as FCMs for other Target FCM Versions (removed after the number of active pre-8.0 devices drops below a certain threshold).

Released FCM versions

The list of released FCM versions can be found under hardware/interfaces/compatibility_matrices.

To find the FCM version released with a specific Android release, see Level.h.