Understanding VINTF and Compatibility Matrices in Android Project Treble

Project Treble, introduced in Android 8.0, separates the vendor implementation (Vendor) from the Android OS framework, allowing vendors to update devices to newer Android versions with lower cost and effort. It applies to all new devices running Android 8.0 and later.

The VINTF (Vendor Interface) object is a core mechanism of the Treble architecture that aggregates device information and exposes it through queryable APIs. It contains two main types of data: the compatibility matrix and the manifest.

Key Terminology

• Framework Compatibility Matrix (FCM) : an XML file that specifies the framework requirements a vendor implementation must satisfy. Each Android framework version has its own set of FCMs.

• Platform FCM version (S) : the collection of all FCM versions for a given framework version.

• FCM version (F) : a specific version within a framework version.

• Target FCM version (V) : the FCM version declared by the device manifest; the vendor implementation must match this version.

• HAL version : expressed as foo@x where foo is the HAL name and x the version number.

• Device Manifest (DM) : an XML file that lists the HAL versions provided by the device (vendor and ODM images). Its content is limited by the target FCM version but may list newer HALs.

• Device Compatibility Matrix (DCM) : an XML file that defines the vendor requirements a framework implementation must satisfy.

• Framework Manifest (FM) : an XML file that lists the HAL versions the framework provides. The framework may disable HALs that exceed the target FCM version.

Important Files

1. Device Manifest (DM) – describes static components the device can provide to the framework. 2. Framework Compatibility Matrix (FCM) – describes the framework’s expectations from a device. 3. Framework Manifest (FM) – describes the high‑level services the framework offers. 4. Device Compatibility Matrix (DCM) – describes the vendor requirements for the framework.

Overall, the manifest is the provider side, while the compatibility matrix is the consumer side. Both are checked during build, OTA generation, boot, and VTS testing.

HAL Interface VINTF Object

When developing or iterating HAL interfaces, developers must update the FCM/DM accordingly. Missing or malformed VINTF objects cause compilation errors, runtime issues, or VTS failures.

Compatibility‑Matrix Architecture

The compatibility matrix includes fields such as:

compatibility-matrix.type : "framework" or "device". compatibility-matrix.level : the FCM version (e.g., 202404 for Android V). compatibility-matrix.hal.format : "hidl" or "aidl" (default "hidl"). compatibility-matrix.hal.optional : true if the HAL is optional, false if mandatory.

Additional information such as sepolicy and kernel versions is also inserted into the FCM for later compatibility checks.

Manifest Architecture

In Android.mk or Android.bp the VINTF fragments are declared, for example:

Android.mk: LOCAL_VINTF_FRAGMENTS := .xml

Android.bp: vintf_fragments: [".xml"]

Key manifest attributes include:

manifest.target-level : the Shipping FCM version the device manifest targets. manifest.hal.max-level : the highest HAL version the framework manifest will accept. manifest.hal.max-level.version : optional HAL version (default 1). manifest.hal.max-level.fqname : optional fully‑qualified name for a HAL instance.

VINTF Check Tool (libvintf)

libvintf is the AOSP tool that validates the compatibility between the framework and vendor side using the VINTF XML files. It is packaged as a host‑side binary checkvintf and is invoked during the build.

The checking process consists of three main parts:

1. Compatibility verification : parses VINTF files to obtain HAL, SDK, and sepolicy versions, then checks DM ↔ FCM (HAL & sepolicy), FM ↔ DCM (HAL & SDK), and RuntimeInfo ↔ FCM (runtime). Optional HALs are skipped; mandatory HALs must be present and meet version requirements.

2. Interface deprecation check : splits FCMs into the target level and other levels, then walks through interfaces in the other FCMs to see if they are missing or have lower versions in the target FCM, reporting them as deprecated.

3. Unused‑interface check : iterates over HALs declared in the device manifest; if a HAL cannot be found in the framework compatibility matrix, an error is reported.

These checks are also performed during OTA updates and at boot time to ensure ongoing compatibility.

Source code snippets referenced in the article (e.g., check_vintf.cpp , VintfObject.cpp ) illustrate how the tool extracts information and performs the three verification steps.

Conclusion

The article provides a practical overview of VINTF, its associated XML artifacts, and the libvintf checking workflow, which is essential for Android platform developers working on vendor‑framework integration.