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.
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.
version
elements are concatenated with
OR (see camera example below).<hal>
elements with the same name are
concatenated with AND.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> </interface> </hal>
A vendor must implement ONE of the following HALs:
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 this HAL:
android.hardware.drm@2.z::ICryptoFactory/default //where z >= 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
exactly match 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 exactly equal
30. Otherwise it is not a match.-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