{% include "_versions.html" %}
The two pairs of compatibility matrices and manifests are meant to be reconciled at OTA time to verify the framework and vendor implementation can work with each other. This verification is successful upon a match between the framework compatibility matrix and the device manifest, as well as between the framework manifest and the device compatibility matrix. The following sections detail matching rules used by various components.
To match a device manifest with a framework compatibility matrix,
the Shipping FCM version specified by manifest.target-level
must exactly equal to the FCM version specified by
compatibility-matrix.level
. Otherwise there is no match.
If the framework compatibility matrix is requested with
libvintf
, this match is always successful because
libvintf
opens the device manifest, retrieves the Shipping FCM
Version, and returns the framework compatibility matrix at that Shipping FCM
Version (plus some optional HALs from compatibility matrices at higher FCM
Versions).
The HAL-match rule identifies the versions of hal
elements in a
manifest file that are considered supported by the owner of the corresponding
compatibility matrix.
<hal>
elements have AND
relationship.<version>
elements within the same
<hal>
have
OR relationship. If two or more are specified, only
one of the version needs to be implemented (see DRM example below).<instance>
and
<regex-instance>
elements within the same
<hal>
have
AND relationship (see DRM example below).For a HAL at version 2.5, the match rule is as follows:
Matrix | Matching Manifest |
---|---|
2.5 |
2.5-2.∞. Shorthand for 2.5-5. |
2.5-7 |
2.5-2.∞. Indicates the following:
camera:
2.5-7 in its compatibility matrix. |
The framework compatibility matrix states the following version information for DRM HAL:
<hal> <name>android.hardware.drm <version>1.0</version> <version>3.1-2</version> <interface> <name>IDrmFactory</name> <instance>default</instance> <instance>specific</instance> </interface> </hal> <hal> <name>android.hardware.drm <version>2.0</version> <interface> <name>ICryptoFactory</name> <instance>default</instance> <regex-instance>[a-z]+/[0-9]+</regex-instance> </interface> </hal>
A vendor must implement ONE of the following instances:
android.hardware.drm@1.x::IDrmFactory/default // where x >= 0 android.hardware.drm@1.x::IDrmFactory/specific // where x >= 0OR
android.hardware.drm@3.y::IDrmFactory/default // where y >= 1 android.hardware.drm@3.y::IDrmFactory/specific // where y >= 1
... AND must also implement all of these instances:
android.hardware.drm@2.z::ICryptoFactory/default // where z >= 0 android.hardware.drm@2.z::ICryptoFactory/${INSTANCE} // where z >= 0 and ${INSTANCE} matches [a-z]+/[0-9]+ // e.g. legacy/0
The <kernel>
section of the framework compatibility matrix
describes the framework's requirements of the Linux kernel on the device. This
information is meant to be matched at OTA time against the
information
about the kernel that gets reported by the device's VINTF object.
A matrix can include multiple <kernel>
sections, each with
a different version
attribute using the format:
${ver}.${major_rev}.${kernel_minor_rev}
The OTA considers only the <kernel>
section with the same
${ver}
and ${major_rev}
as the device kernel (i.e.,
version="${ver}.${major_rev}.${matrix_minor_rev}")
; other sections
are ignored. In addition, the minor revision from the kernel must be a value
from the compatibility matrix (${kernel_minor_rev} >=
${matrix_minor_rev}
;). If no <kernel>
section meets
these requirements, it is a non-match.
If the <kernel>
section does match, the process continues
by attempting to match config
elements against
/proc/config.gz
. For each config element in the compatibility
matrix, it looks up /proc/config.gz
to see if the config is
present. When a config item is set to n
in the compatibility
matrix for the matching <kernel>
section, it must be absent
from /proc/config.gz
. Finally, a config item not in the
compatibility matrix may or may not be present in /proc/config.gz
.
Examples of matches:
<value type="string">bar</value>
matches
"bar"
. Quotes are omitted in the compatibility matrix but present
in /proc/config.gz
.<value type="int">4096</value>
matches
4096
or 0x1000
or 0X1000
.<value type="int">0x1000</value>
matches
4096
or 0x1000
or 0X1000
.<value type="int">0X1000</value>
matches
4096
or 0x1000
or 0X1000
.<value type="tristate">y</value>
matches
y
.<value type="tristate">m</value>
matches
m
.<value type="tristate">n</value>
means the config
item must NOT exist in /proc/config.gz
.<value type="range">1-0x3</value>
matches
1
, 2
, or 3
, or hexadecimal equivalent.
A framework compatibility matrix has the following kernel information:
<kernel version="3.18.51"> <config> <key>CONFIG_TRI</key> <value type="tristate">y</value> </config> <config> <key>CONFIG_NOEXIST</key> <value type="tristate">n</value> </config> <config> <key>CONFIG_DEC</key> <value type="int">4096</value> </config> <config> <key>CONFIG_HEX</key> <value type="int">0XDEAD</value> </config> <config> <key>CONFIG_STR</key> <value type="string">str</value> </config> <config> <key>CONFIG_EMPTY</key> <value type="string"></value> </config> </kernel>
The kernel version is matched first. If a device in uname()
reports:
<kernel version="3.10.x">
where x <= 73
)
version
)<kernel version="4.1.x">
where x <= 22
)
After the appropriate <kernel>
section is selected, for
each <config>
item with value other than n
, we
expect the corresponding entry to be present in /proc/config.gz
;
for each <config>
item with value n
, we expect
the corresponding entry to not be present in /proc/config.gz
. We
expect the content of <value>
to exactly match the text after
the equal sign (including quotes), up to the newline character or
#
, with leading and trailing whitespace truncated.
The following kernel configuration is an example of a successful match:
# comments don't matter CONFIG_TRI=y # CONFIG_NOEXIST should not exist CONFIG_DEC = 4096 # trailing comments and whitespaces are fine CONFIG_HEX=57005 # 0XDEAD == 57005 CONFIG_STR="str" CONFIG_EMPTY="" # empty string must have quotes CONFIG_EXTRA="extra config items are fine too"
The following kernel configuration is an example of an unsuccessful match:
CONFIG_TRI="y" # mismatch: quotes CONFIG_NOEXIST=y # mismatch: CONFIG_NOEXIST exists CONFIG_HEX=0x0 # mismatch; value doesn't match CONFIG_DEC="" # mismatch; type mismatch (expect int) CONFIG_EMPTY=1 # mismatch; expects "" # mismatch: CONFIG_STR is missing
SE policy requires the following matches:
<sepolicy-version>
defines a closed range of minor
versions for every major version. The sepolicy version reported by the device
must fall within one of these ranges to be compatible with the framework. Match
rules are similar to HAL versions; it is a match if the sepolicy version is
higher or equal to the minimum version for the range. The maximum version is
purely informational.<kernel-sepolicy-version>
i.e. policydb version. Must
be less than the security_policyvers()
reported by the device.
The framework compatibility matrix states the following sepolicy information:
<sepolicy> <kernel-sepolicy-version>30</kernel-sepolicy-version> <sepolicy-version>25.0</sepolicy-version> <sepolicy-version>26.0-3</sepolicy-version> </sepolicy>
On the device:
security_policyvers()
must be greater
than or equal to 30. Otherwise it is not a match. For example:
-3
" after "26.0
" is purely
informational.)The AVB version contains a MAJOR version and MINOR version, with the format as MAJOR.MINOR (e.g., 1.0, 2.1). For details, refer to Versioning and Compatibility. AVB version has the following system properties:
ro.boot.vbmeta.avb_version
is the libavb
version
in bootloaderro.boot.avb_version
is the libavb
version in
Android OS (init/fs_mgr
)The system property appears only when the corresponding libavb has been used to verify AVB metadata (and returns OK). It is absent if a verification failure occurred (or no verification occurred at all).
A compatibility match compares the following:
ro.boot.vbmeta.avb_version
with
avb.vbmeta-version
from framework compatibility matrix;
ro.boot.vbmeta.avb_version.MAJOR == avb.vbmeta-version.MAJOR
ro.boot.vbmeta.avb_version.MINOR >= avb.vbmeta-version.MINOR
ro.boot.avb_version
with
avb.vbmeta-version
from framework compatibility matrix.
ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR
ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR
The bootloader or Android OS might contain two copies of libavb
libraries, each with a different MAJOR version for upgrade devices and launch
devices. In this case, the same unsigned system image can be shared but
the final signed system images are different (with different
avb.vbmeta-version
):
/system
is P, all other partitions are O).The framework compatibility matrix states the following AVB information:
<avb> <vbmeta-version>2.1</vbmeta-version> </avb>
On the device:
ro.boot.avb_version == 1.0 && ro.boot.vbmeta.avb_version == 2.1 mismatch
ro.boot.avb_version == 2.1 && ro.boot.vbmeta.avb_version == 3.0 mismatch
ro.boot.avb_version == 2.1 && ro.boot.vbmeta.avb_version == 2.3 match
ro.boot.avb_version == 2.3 && ro.boot.vbmeta.avb_version == 2.1 match
For devices launched with Android {{ androidPVersionNumber }} or lower, during OTA, the AVB version requirements in framework compatibility matrix are matched against the current AVB version on the device. If the AVB version has an major version upgrade during an OTA (for example, from 0.0 to 1.0), the check in OTA does not reflect the compatibility after the OTA.
To mitigate the issue, an OEM can place a fake AVB version in the OTA package
(compatibility.zip
) to pass the check. To do so:
BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE
for the device. Its value
should equal the AVB version before the OTA, i.e. the AVB version of the device when it was
launched.These changes automatically place
BOARD_OTA_FRAMEWORK_VBMETA_VERSION_OVERRIDE
as
compatibility-matrix.avb.vbmeta-version
in the following files:
/system/compatibility_matrix.xml
(which is not used in Android {{ androidPVersionNumber }}) on the devicesystem_matrix.xml
in compatibility.zip
in the OTA package/system/etc/vintf/compatibility_matrix.xml
. After the OTA, the new value in
/system/etc/vintf/compatibility_matrix.xml
is used for compatibility checks instead.
The device compatibility matrix declares the required VNDK version in
compatibility-matrix.vendor-ndk.version
. If the device
compatibility matrix does not have a <vendor-ndk>
tag, no
requirements are imposed, and hence it is always considered a match.
If the device compatibility matrix does have a <vendor-ndk>
tag, an <vendor-ndk>
entry with a matching
<version>
is looked up from the set of VNDK vendor snapshots
provided by the framework in the framework manifest. If such an entry does not
exist, there is no match.
If such entry does exist, the set of libraries enumerated in the device compatibility matrix must be a subset of the set of libraries stated in the framework manifest; otherwise, the entry is not considered a match.
If the device compatibility matrix states the following requirement on VNDK:
<!-- Example Device Compatibility Matrix --> <vendor-ndk> <version>27</version> <library>libjpeg.so</library> <library>libbase.so</library> </vendor-ndk>
In the framework manifest, only the entry with version 27 is considered.
<!-- Framework Manifest Example A --> <vendor-ndk> <version>27</version> <library>libjpeg.so</library> <library>libbase.so</library> <library>libfoo.so</library> </vendor-ndk>
Example A is a match, because VNDK version 27 is in the framework manifest,
and {libjpeg.so, libbase.so, libfoo.so} ⊇ {libjpeg.so, libbase.so}
.
<!-- Framework Manifest Example B --> <vendor-ndk> <version>26</version> <library>libjpeg.so</library> <library>libbase.so</library> </vendor-ndk> <vendor-ndk> <version>27</version> <library>libbase.so</library> </vendor-ndk>
Example B is not a match. Even though VNDK version 27 is in the framework
manifest, libjpeg.so
is not supported by the framework in that
snapshot. VNDK version 26 is ignored.
The device compatibility matrix declares a set of required System SDK
version in compatibility-matrix.system-sdk.version
. There is a
match only if the set is a subset of provided System SDK versions as declared
in manifest.system-sdk.version
in the framework manifest.
If the device compatibility matrix states the following requirement on System SDK:
<!-- Example Device Compatibility Matrix --> <system-sdk> <version>26</version> <version>27</version> </system-sdk>
Then, the framework must provide System SDK version 26 and 27 to match.
<!-- Framework Manifest Example A --> <system-sdk> <version>26</version> <version>27</version> </system-sdk>
Example A is a match.
<!-- Framework Manifest Example B --> <system-sdk> <version>26</version> <version>27</version> <version>28</version> </system-sdk>
Example B is a match.
<!-- Framework Manifest Example C --> <system-sdk> <version>26</version> </system-sdk>
Example C is not a match, because System SDK version 27 is not provided.