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 (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 SF), 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). |
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.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
tocompatibility_matrix.F.xml
. - Update the
level
attribute in the file toF
. - 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.F.xml
with the following
optional
settings:
optional="false"
if devices that ship withV = F
must launch with this HAL,
OR
optional="true"
if devices that ship withV = 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>
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
, thecompatibility_matrix.F.xml
must statex.(z+1)
andoptional="false"
. - Not required on devices launching with
V = F
, thecompatibility_matrix.F.xml
must copyx.y-z
and optionality fromcompatibility_matrix.<F-1>.xml
and change the version tox.w-(z+1)
(wherew >= 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>
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.F.xml
with the following
optional
settings:
optional="false"
with only versionx.0
, if devices that ship withV = F
must launch withx.0
.optional="false"
but along with older major versions in the same<hal>
tag, if devices that ship withV = F
must launch with this HAL, but can launch with an older major version.optional="true"
if devices that ship withV = F
do not 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 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.F.xml
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
withoptional="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 attributelevel="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
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 toV
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.
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 incompatibiility_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 12framework 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 incompatibility_matrix.legacy.xml
,compatibility_matrix.1.xml
, andcompatibility_matrix.2.xml
, but not incompatibility_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 incompatibility_matrix.3.xml
.power@1.0
is incompatibility_matrix.legacy.xml
,compatibility_matrix.1.xml
, andcompatibility_matrix.2.xml
.compatibility_matrix.3.xml
haspower@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 released 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 12framework 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 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.
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
.