{% 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.
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 | 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. |
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
:
compatibility_matrix.<F-1>.xml
to
compatibility_matrix.current.xml
.level
attribute in the file to F
.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,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>
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:
V = F
, the
compatibility_matrix.current.xml
must state x.(z+1)
and
optional="false"
.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>
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:
compatibility_matrix.3.xml
with
optional="false"
, devices that launch with Android
{{ androidPVersionNumber }} must ship with 2.0 HAL.compatibility_matrix.3.xml
,
devices that launch with Android {{ androidPVersionNumber }} must not provide
the 1.0 HAL (as this HAL is considered deprecated).The process of releasing an FCM Version is done solely by Google as part of an AOSP release and includes the following steps:
compatibility_matrix.current.xml
to
compatibility_matrix.F.xml
.level="F"
.V >= F
.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.
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:
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.
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 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 SF for a given framework release cannot upgrade to that
release.
The following sections describe (in chronological order) the possible states of a HAL Version.
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:
compatibiility_matrix.current.xml
is renamed to
compatibility_matrix.3.xml
), the health@2.0
HAL was
considered an unreleased HAL.teleportation@1.0
HAL is not in any released compatibility
matrices, and is also considered an unreleased HAL.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.
A HAL Version is deprecated if and only if:
Examples:
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 }}.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 }}.
A HAL Version is removed if and only if:
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.
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).