Compatibility Matrix

The Compatibility Matrix is the strict enforcement mechanism within the VINTF architecture. While the manifest declares what is available, the compatibility matrix declares what is explicitly required. It acts as a gatekeeper, ensuring that mismatched system and vendor images do not attempt to boot together, which would otherwise result in catastrophic system failures.

Framework Compatibility Matrix: Framework Requirements

The Framework Compatibility Matrix (FCM) defines the minimum requirements the Android OS framework (system.img) imposes on the vendor implementation (vendor.img, odm.img).

This matrix is typically located in /system/etc/vintf/ and is assembled at build time. It specifies:

1. Required HAL versions: If the framework requires android.hardware.audio@6.0 or higher, the FCM will state this requirement.
2. Kernel constraints: The framework might rely on specific Linux kernel features (e.g., eBPF for networking). The FCM mandates the kernel version and the exact CONFIG_ flags that must be enabled.
3. SELinux policy versions: The framework requires the vendor SELinux policy to be within a compatible version range.

Example: Framework Requiring an Audio HAL

<compatibility-matrix version="5.0" type="framework">
    <hal format="hidl" optional="false">
        <name>android.hardware.audio</name>
        <version>6.0-7.0</version>
        <interface>
            <name>IDevicesFactory</name>
            <instance>default</instance>
        </interface>
    </hal>
    <!-- ... other requirements ... -->
</compatibility-matrix>

Here, optional="false" indicates a hard requirement. The framework will refuse to boot unless the vendor manifest provides an Audio HAL between versions 6.0 and 7.0 inclusive.

Device Manifest: Vendor Provisions

As a counterpart to the FCM, the Device Manifest outlines exactly what the hardware and vendor BSP provide. The verification equation is straightforward:

Does the Device Manifest provide everything the Framework Compatibility Matrix requires?

If the answer is yes, the images are deemed compatible.

Validation with the vintf_object Library

The logic that performs this crucial matching lives in the libvintf C++ library, specifically through the vintf_object.

This library is used in several critical stages:

• Build System (assemble_vintf): Validates that the built images are compatible before producing a final ROM zip.
• OTA Client (update_engine): Before applying a payload, update_engine downloads the metadata of the new OS and uses libvintf to check if the new framework is compatible with the currently installed vendor partition. If the check fails, the OTA aborts safely.
• Init (init): During early boot, init checks VINTF. If the partitions are mismatched, init will often halt the boot process to prevent data corruption or unpredictable behavior.

You can inspect the vintf_object status programmatically or via shell. To see the matrices on a running device:

adb shell dumpsys media.extractor # Sometimes shows VINTF dependencies
adb shell cat /system/etc/vintf/compatibility_matrix.device.xml

Compatibility Matrix Freeze per Android Release

To guarantee stable update paths, Google freezes the Framework Compatibility Matrix for each major Android release.

Each release is assigned an FCM version (e.g., Android 11 is FCM level 5, Android 12 is FCM level 6). When a new Android version is released, its FCM is finalized and locked. Devices launching with that Android version must meet the requirements of that specific FCM level.

Crucially, an Android 14 Generic System Image (GSI) will contain compatibility matrices for FCM levels going back several years. This is how a single system.img can boot on devices that launched with Android 11, 12, or 13 without requiring the vendor to update their HALs. The framework dynamically downgrades its expectations based on the device's declared Target FCM Level.