FCM Lifecycle

{% include "_versions.html" %}

An Android framework release has multiple Framework Compatibility Matrices (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	An XML file that specifies what HAL versions the vendor image 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.

Developing in a new FCM Version

Android increments the FCM Version for each framework release (such as Android 8, 8.1, etc). During development, the new compatibility_matrix.current.xml is created (F) 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.current.xml.
Update the level attribute in the file to F.
Add corresponding build rules to install this compatibility matrix to the device.

Introducing 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.current.xml with the following optional settings:

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

OR
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.current.xml (renamed to compatibility_matrix.2.xml after Android 8.1 released):

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

Upgrading 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, 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).

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.current.xml (renamed to compatibility_matrix.2.xml after Android 8.1 released) 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>

Upgrading 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.current.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 do not have to launch the HAL.

For example, Android {{ androidPVersionNumber }} 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 {{ androidPVersionNumber }} must not provide the deprecated 1.0 HAL and must instead provide the new 2.0 version. In compatibility_matrix.legacy.xml, compatibility_matrix.1.xml, and 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>

This entry is copied to compatibility_matrix.current.xml (renamed to compatibility_matrix.3.xml with the Android {{ androidPVersionNumber }} release) and modified 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 {{ androidPVersionNumber }} must ship with 2.0 HAL.
Because the 1.0 HAL is not in compatibility_matrix.3.xml, devices that launch with Android {{ androidPVersionNumber }} 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 {{ androidPVersionNumber }} can work with) as an optional HAL, the Android {{ androidPVersionNumber }} 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 is done solely by Google as part of an AOSP release and includes the following steps:

Rename compatibility_matrix.current.xml to compatibility_matrix.F.xml.
Ensure the file has the attribute level="F".
Edit corresponding build rules to reflect the file name change.
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.

This file cannot be changed once renamed and published. For example, during Android {{ androidPVersionNumber }} development the following files are built for hardware/interfaces/compatibility_matrices/:

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

When Android {{ androidPVersionNumber }} is released, compatibility_matrix.current.xml is renamed to compatibility_matrix.3.xml and the following files are built for hardware/interfaces/compatibility_matrices/:

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

VTS tests ensure that devices launching with Android {{ androidPVersionNumber }} have Target FCM Version >= 3.

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. When a given 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, 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 {{ androidPVersionNumber }}, 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.

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 removing compatibility_matrix.V.xml from the build rules (so that it is no longer installed on the system image), and by deleting any code that implemented or depended on the removed functionality. 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

If a HAL Version is not in any of the public and frozen compatibility matrices, it is considered unreleased and possibly in development. This includes HAL Versions that are only in compatibility_matrix.current.xml. Examples:

During the development of Android {{ androidPVersionNumber }} (before compatibiility_matrix.current.xml is renamed to compatibility_matrix.3.xml), the health@2.0 HAL was considered an unreleased HAL.
The teleportation@1.0 HAL is not in any released compatibility matrices, and is also considered an unreleased HAL.

Released and Current

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.

Released but Deprecated

A HAL Version is deprecated if and only if:

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 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 {{ androidPVersionNumber }}.
The power HAL has a minor version upgrade in Android {{ androidPVersionNumber }}, but power@1.0 is still in compatibility_matrix.3.xml.
- power@1.0 is in 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 {{ androidPVersionNumber }}.

Removed

A HAL Version is removed if and only if:

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

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

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).