VNDK snapshot design

VNDK snapshots can be used by a system image to provide the correct VNDK libraries to vendor images even when system and vendor images are built from different versions of Android. Creating a VNDK snapshot requires capturing VNDK libraries as a snapshot and marking them with a version number. The vendor image may link with a specific VNDK version that provides required ABIs for the modules in the vendor image. However, within the same VNDK version, the VNDK libraries must be ABI-stable.

VNDK snapshot design includes methods for generating the pre-builds of a VNDK snapshot from the current system image and installing those pre-built libs to the system partition of a newer Android version.

About VNDK libraries

HIDL-HALs, introduced in Android 8.0, enables separate upgrades for system and vendor partitions. VNDK defines sets of libraries (VNDK-core, VNDK-SP and LL-NDK) that vendor code can link with and blocks the vendors from using libraries that are not in a VNDK set. As a result, the vendor image can be built and run if the proper VNDK sets on the system image are provided to the vendor image.

VNDK-core

The VNDK-core set of libraries is installed in /system/lib[64]/vndk-${VER} and is available only for vendor processes with the API level equal to ${VER}. System processes may not use these libraries and must instead use the libraries installed in /system/lib[64]. Because of the strict namespace restriction for each process, the VNDK-core libraries are safe from dual-loading.

To include a library in VNDK-core, add the following to Android.bp:

vendor_available: true,
vndk: {
    enabled: true,
},

Note: If a system process loads library foo.so from system/lib and loads another foo.so from system/lib/vndk, foo.so is dual-loaded. Normally it is unsafe to load the same library twice in a process.

VNDK-SP

VNDK-SP libraries are installed in /system/lib[64]/vndk-sp-${VER} and are available to vendor processes and system processes (through the SP-HAL libraries installed in vendor partition). VNDK-SP libraries may be dual-loaded.

To include a library in VNDK-SP, add the following to Android.bp:

vendor_available: true,
vndk: {
    enabled: true,
    support_system_process: true,
},

LL-NDK

LL-NDK libraries are installed in /system/lib[64]. Vendor modules can use LL-NDK stub libraries to access pre-selected symbols of LL-NDK libraries. LL-NDK libraries must be backward-compatible and ABI-stable to enable old versions of vendor modules to use new versions of LL-NDK libraries. Because of the ABI-stable characteristics of LL-NDK, the VNDK snapshot does not need to include LL-NDK libraries for old vendor images.

About VNDK snapshots

Android 8.1 included VNDK libraries built from the source code. However, for later versions of Android, each VNDK version must be captured as a snapshot and provided as a pre-build to enabling linking to an older vendor image.

Starting in Android 9, new versions of Android will include at least one snapshot of VNDK-core and VNDK-SP directories for older versions in the Android source code. At build time, required snapshots will be installed to /system/lib[64]/vndk-${VER} and /system/lib[64]/vndk-sp-${VER} (directories that can be used by the vendor partition), where ${VER} is the string variable that represents the version name of the VNDK snapshot.

As the VNDK snapshot libraries may differ for each VNDK version, the VNDK snapshot also includes the linker namespace configurations, installed as etc/ld.config.${VER}.txt, /etc/llndk.libraries.${VER}.txt, and /etc/vndksp.libraries.${VER}.txt.

Example: Upgrade system and vendor images

No snapshot required; build without additional configurations for VNDK snapshots.

Example: Upgrade system image only

Must include the VNDK snapshot and linker namespace configuration files for the vendor image in the system image. The linker namespace configuration files are automatically configured to search for VNDK libraries in /system/lib[64]/vndk-${VER} and /system/lib[64]/vndk-sp-${VER}.

Figure 1. Upgrading system only

Example: Upgrade system image, minor vendor image change

Building a vendor image against a VNDK snapshot is not yet supported, so you must build the vendor image separately with its original source code, then upgrade the system image as described in the previous example.

VNDK snapshot architecture

To make an Android 9 system image compatible with an Android 8.1 vendor image, the VNDK snapshot that matches the Android 8.1 vendor image must be provided with the Android 9 system image, as shown below:

Figure 2. VNDK snapshot architecture

The VNDK snapshot design includes the following methods:

Generating a snapshot for VNDK-core and VNDK-SP libraries. Android 9 includes a script you can use to make a snapshot of the current VNDK build. This script bundles all libraries in /system/lib[64]/vndk-28 and /system/lib[64]/vndk-sp-28 that were built with the current source as a VNDK snapshot, where 28 is the VNDK version of Android 9. The snapshot also includes the linker namespace configuration files /etc/ld.config.28.txt, /etc/llndk.libraries.28.txt, and /etc/vndksp.libraries.28.txt. The generated snapshot will be used with newer Android versions (higher than Android 9).
Installing pre-built VNDK-core and VNDK-SP libraries from a snapshot. In Android 9, a VNDK snapshot has a set of pre-built VNDK-core libraries and a set of VNDK-SP libraries, as well as linker namespace configuration files. When you provide a list of VNDK snapshot versions to be installed, at build time, the system image installs the VNDK snapshot libraries to /system/lib[64]/vndk-${VER} and the /system/lib[64]/vndk-sp-${VER} directories and linker namespace configuration files for those VNDK snapshots to /etc directory.

VNDK versioning

Each Android release has only one VNDK snapshot and the SDK version is used as a VNDK version (which means the VNDK version has an integer number, such as 27 for Android 8.1). The VNDK version is fixed when the Android version is released. The VNDK version used by the vendor partition is stored automatically in the ro.vndk.version property, which can be read on runtime. This version is then used in identifying the vendor VNDK version for some libraries and identifying the VNDK snapshot version for namespace configuration.

Build VNDK libraries

The make vndk command builds libraries that have vndk: { enabled: true, … }, including dependencies and namespace configuration files. If BOARD_VNDK_VERSION := current is set, these libraries are built with the make command.

Because this build does not install the VNDK libraries from the snapshot, the installed VNDK libraries are not ABI-stable. However, when an Android version is released, the ABI for the current VNDK version is fixed. At this point, any ABI breakage is a build error, so patches to the Android version must not change the ABI for VNDK libraries.