Matching Rules | Android Open Source Project

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.

Framework compatibility matrix version matches

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

HAL matches

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.

Multiple <hal> elements have AND relationship.
Multiple <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).
Multiple <instance> and <regex-instance> elements within the same <hal> have AND relationship (see DRM example below).

Example: Successful HAL match for Camera module

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.

Matrix	Matching Manifest
`2.5`	2.5-2.∞. Shorthand for 2.5-5.
`2.5-7`	2.5-2.∞. Indicates the following: 2.5 is the minimum required version, meaning a manifest providing HAL 2.0-2.4 is not compatible. 2.7 is the maximum version that could be requested, meaning the owner of the compatibility matrix (framework or device) will not request versions beyond 2.7. The owner of the matching manifest can still serve version 2.10 (as an example) when 2.7 is requested. The compatibility-matrix owner knows only that the requested service is compatible with API version 2.7. -7 is informational only and does not affect the OTA update process. Thus, a device with a HAL at version 2.10 in its manifest file remains compatible with a framework that states `camera:` `2.5-7` in its compatibility matrix.

2.5-7

2.5-2.∞. Indicates the following:

2.5 is the minimum required version, meaning a manifest providing HAL 2.0-2.4 is not compatible.
2.7 is the maximum version that could be requested, meaning the owner of the compatibility matrix (framework or device) will not request versions beyond 2.7. The owner of the matching manifest can still serve version 2.10 (as an example) when 2.7 is requested. The compatibility-matrix owner knows only that the requested service is compatible with API version 2.7.
-7 is informational only and does not affect the OTA update process.

Thus, a device with a HAL at version 2.10 in its manifest file remains compatible with a framework that states camera: 2.5-7 in its compatibility matrix.

Example: Successful HAL match for DRM module

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 >= 0

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

Kernel matches

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.

Example: Successful kernel match

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:

3.10.73 (no match to matrix unless there is a separate kernel section with <kernel version="3.10.x"> where x <= 73)
3.18.50 (no match to matrix, smaller than version)
3.18.51 (match to matrix)
3.18.52 (match to matrix)
4.1.22 (no match to matrix unless there is a separate kernel section with <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 matches

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.

Example: Successful SE policy match

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:

The value returned by security_policyvers() must be greater than or equal to 30. Otherwise it is not a match. For example:
- If a device returns 29, it is not a match.
- If a device returns 31, it is a match.
SE Policy version must be one of 25.0-∞ or 26.0-∞. Otherwise it is not a match. (The "-3" after "26.0" is purely informational.)

AVB version matches

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 bootloader
ro.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:

sysprop 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
sysprop 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):

Figure 1. AVB version matches (/system is P, all other partitions are O).

Figure 2. AVB version matches (all partitions are P).

Example: Successful AVB version match

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

Matching AVB version during OTA

For devices launched with Android 9 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:

Cherry-pick the following CLs to the Android 9 source tree:
- CL 732261
- CL 732262
Define 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.
Rebuild the OTA package.

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 9) on the device
system_matrix.xml in compatibility.zip in the OTA package

These changes do not affect other framework compatibility matrices, including /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.

VNDK version matches

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.

As a special case, if no libraries are enumerated in the device compatibility matrix, the entry is always considered a match, because empty set is a subset of any set.

Example: Successful VNDK version 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.

System SDK version matches

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.

As a special case, if no System SDK versions are enumerated in the device compatibility matrix, it is always considered a match, because empty set is a subset of any set.

Example: Successful System SDK version match

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.