Vendor Native Development Kit (VNDK) overview

The Vendor Native Development Kit (VNDK) is a set of libraries used by other libraries or binaries, in the vendor or product partition, on runtime for dlopen.

Deprecation

Vendor NDK was introduced in Android 8.0 to provide APIs between the framework and vendor code. While VNDK has been successfully used for many years, it has some drawbacks:
  • Storage
    • A single VNDK APEX packages all VNDK libraries, whether they're used from the device or not.
    • GSI contains multiple versions of VNDK APEXes to support multiple versions of vendor images.
  • Updatability
    • It's difficult to update VNDK APEXes separately from the platform update.
    • Vendor images are frequently updated over the air (OTA), reducing the benefits of having VNDK packaged within the system image.
Based on these issues, we decided to deprecate VNDK starting with Android 15.

Details on VNDK deprecation

All VNDK libraries are packaged into the VNDK APEX, and installed in the system (-ext) image. With VNDK deprecation, former VNDK libraries are installed in the vendor (or product) image, same as other vendor-available libraries. These features are removed along with VNDK deprecation:
  • VNDK APEX for Android 15
  • System properties that indicate the version of the target VNDK are removed if the vendor or product partitions are built for Android 15:
    • ro.vndk.version
    • ro.product.vndk.version
  • VNDK optimizations won't be available as there is no VNDK:
    • TARGET_VNDK_USING_CORE_VARIANT for Android Go devices
    • use_vndk_as_stable for Vendor APEXes
  • Vendor snapshot, which is highly dependent on the VNDK

Exceptions from the deprecation

These features won't change with the VNDK deprecation:
  • VNDK APEXes with VNDK version 14 or lower, which are required to support existing vendor images.
  • LL-NDK isn't part of the VNDK.

Why VNDK?

AOSP allows framework-only updates in which the system partition can be upgraded to the latest framework version while vendor partition is left unchanged. Despite being built at different times, binaries in each partition must be able to work with each other.

Framework-only updates include the following challenges:

  • Dependency between framework modules and vendor modules. Before Android 8.0, modules in the vendor and system partition could link with each other. However, dependencies from vendor modules imposed undesired restrictions to framework modules development.
  • Extensions to AOSP libraries. Android requires all Android devices to pass CTS when the system partition is replaced with a standard Generic System Image (GSI). However, as vendors extend AOSP libraries to boost performance or to add extra functionalities for their HIDL implementations, flashing the system partition with a standard GSI might break a vendor's HIDL implementation. For guidelines on preventing such breakages, see VNDK extensions.

To address these challenges, Android contains several features such as VNDK (described in this section), HIDL, hwbinder, device tree overlay, and sepolicy overlay.

VNDK-specific terms

VNDK-related documents use the following terminology:
  • Modules refer to either shared libraries or executables. Modules make build-time dependencies.
  • Processes are operating system tasks spawned from executables. Processes make run-time dependencies.
  • Framework-qualified terms are related to the system partition:
    • Framework executables refer to executables in /system/bin or /system/xbin.
    • Framework shared libraries refer to shared libraries under /system/lib[64].
    • Framework modules refer to both framework shared libraries and framework executables.
    • Framework processes are processes spawned from framework executables, such as /system/bin/app_process.
  • Vendor-qualified terms are related to vendor partitions:
    • Vendor executables refer to executables in /vendor/bin
    • Vendor shared libraries refer to shared libraries under /vendor/lib[64].
    • Vendor modules refer to both vendor executables and vendor shared libraries.
    • Vendor processes are processes spawned from Vendor Executables, such as /vendor/bin/android.hardware.camera.provider@2.4-service.

VNDK concepts

In an ideal Android 8.0 and higher world, framework processes do not load vendor shared libraries, all vendor processes load only vendor shared libraries (and a portion of framework shared libraries), and communications between framework processes and vendor processes are governed by HIDL and hardware binder.

Such a world includes the possibility that stable, public APIs from framework shared libraries might not be sufficient for vendor module developers (although APIs can change between Android releases), requiring that some portion of framework shared libraries be accessible to vendor processes. In addition, as performance requirements can lead to compromises, some response-time-critical HALs must be treated differently.

The following sections detail how VNDK handles framework shared libraries for vendors and Same-Process HALs (SP-HALs).

Framework shared libraries for vendor

This section describes the criteria for classifying shared libraries that are accessible to vendor processes. There are two approaches to support vendor modules across multiple Android releases:

  1. Stabilize the ABIs/APIs of the framework shared libraries. New framework modules and old vendor modules can use the same shared library to reduce memory footprint and storage size. A unique shared library also avoids several double-loading issues. However, the development cost to maintain stable ABIs/APIs is high and it is unrealistic to stabilize all ABIs/APIs exported by every framework shared library.
  2. Copy old framework shared libraries. Comes with the strong restriction against side channels, defined as all mechanisms to communicate among framework modules and vendor modules, including (but not limited to) binder, socket, pipe, shared memory, shared file, and system properties. There must be no communication unless the communication protocol is frozen and stable (e.g. HIDL through hwbinder). Double-loading shared libraries might cause problems as well; for example, if an object created by the new library is passed into the functions from the old library, an error may occur as these libraries may interpret the object differently.

Different approaches are used depending on the characteristics of the shared libraries. As a result, framework shared libraries are classified into three sub-categories:

  • LL-NDK Libraries are Framework Shared Libraries that are known to be stable. Their developers are committed to maintain their API/ABI stabilities.
    • LL-NDK includes the following libraries: libEGL.so, libGLESv1_CM.so, libGLESv2.so, libGLESv3.so, libandroid_net.so, libc.so, libdl.so, liblog.so, libm.so, libnativewindow.so, libneuralnetworks.so, libsync.so, libvndksupport.so, and libvulkan.so,
  • Eligible VNDK Libraries (VNDK) are Framework Shared Libraries that are safe to be copied twice. Framework Modules and Vendor Modules can link with their own copies. A framework shared library can become an eligible VNDK library only if it satisfies the following criteria:
    • It does not send/receive IPCs to/from the framework.
    • It is not related to ART virtual machine.
    • It does not read/write files/partitions with unstable file formats.
    • It does not have special software license which requires legal reviews.
    • Its code owner does not have objections to vendor usages.
  • Framework-Only Libraries (FWK-ONLY) are Framework Shared Libraries that do not belong to the categories mentioned above. These libraries:
    • Are considered framework internal implementation details.
    • Must not be accessed by vendor modules.
    • Have unstable ABIs/APIs and no API/ABI compatibility guarantees.
    • Are not copied.

Same-Process HAL (SP-HAL)

Same-Process HAL (SP-HAL) is a set of predetermined HALs implemented as Vendor Shared Libraries and loaded into Framework Processes. SP-HALs are isolated by a linker namespace (controls the libraries and symbols that are visible to the shared libraries). SP-HALs must depend only on LL-NDK and VNDK-SP.

VNDK-SP is a predefined subset of eligible VNDK libraries. VNDK-SP libraries are carefully reviewed to ensure double-loading VNDK-SP libraries into framework processes does not cause problems. Both SP-HALs and VNDK-SPs are defined by Google.

The following libraries are approved SP-HALs:

  • libGLESv1_CM_${driver}.so
  • libGLESv2_${driver}.so
  • libGLESv3_${driver}.so
  • libEGL_${driver}.so
  • vulkan.${driver}.so
  • android.hardware.renderscript@1.0-impl.so
  • android.hardware.graphics.mapper@2.0-impl.so

VNDK-SP libraries specify vndk: { support_system_process: true } in their Android.bp files. If vndk: {private:true} is also specified, then these libraries are called VNDK-SP-Private and they are invisible to SP-HALS.

The following are framework-only libraries with RS exceptions (FWK-ONLY-RS):

  • libft2.so (Renderscript)
  • libmediandk.so (Renderscript)

VNDK versioning

VNDK shared libraries are versioned:

  • The ro.vndk.version system property is automatically added to /vendor/default.prop.
  • VNDK and VNDK-SP shared libraries are installed as a VNDK apex com.android.vndk.v${ro.vndk.version} and mounted to /apex/com.android.vndk.v${ro.vndk.version}.

The value of ro.vndk.version is chosen by the algorithm below:

  • If BOARD_VNDK_VERSION is not equal to current, use BOARD_VNDK_VERSION.
  • If BOARD_VNDK_VERSION is equal to current:
    • If PLATFORM_VERSION_CODENAME is REL, use PLATFORM_SDK_VERSION (e.g. 28).
    • Otherwise, use PLATFORM_VERSION_CODENAME (e.g. P).

Vendor Test Suite (VTS)

The Android Vendor Test Suite (VTS) mandates a non-empty ro.vndk.version property. Both newly launched devices and upgrading devices must define ro.vndk.version. Some VNDK test cases (e.g. VtsVndkFilesTest and VtsVndkDependencyTest) rely on the ro.vndk.version property to load the matching eligible VNDK libraries data sets.