The Vendor Native Development Kit (VNDK) is a set of libraries exclusively for vendors to implement their HALs. The VNDK ships in system.img and is dynamically linked to vendor code at runtime.

Why VNDK?

Android 8.0 and higher enables framework-only updates in which the system partition can be upgraded to the latest version while vendor partitions are left unchanged. This implies that binaries built at different times must be able to work with each other; VNDK covers API/ABI changes across Android releases.

Framework-only updates include the following challenges:

• Dependency between framework modules and vendor modules. Before Android 8.0, modules from both sides could link with modules from the other side. However, dependencies from vendor modules imposed undesired restrictions to framework modules development.
• Extensions to AOSP libraries. Android 8.0 and higher 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 8.0 introduces several techniques such as VNDK (described in this section), HIDL, hwbinder, device tree overlay, and sepolicy overlay.

VNDK resources

This section includes the following VNDK resources:

• VNDK concepts (below) describes framework shared libraries, same-process HALs (SP-HALs), and VNDK terminology.
• VNDK extensions classifies vendor-specific changes into categories. For example, libraries with extended functionalities on which vendor modules rely must be copied into the vendor partition, but ABI-incompatible changes are prohibited.
• VNDK Build System Support describes the build system configurations and module definition syntaxes that are related to VNDK.
• The VNDK Definition Tool helps migrate your source tree to Android 8.0 and higher.
• Linker Namespace provides fine-grained control over shared library linkages.
• Directories, Rules, and sepolicy defines the directory structure for devices running Android 8.0 and higher, VNDK rules, and associated sepolicy.
• The VNDK Design presentation illustrates fundamental VDNK concepts used in Android 8.0 and higher.

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

The following libraries are VNDK-SP libraries that are accessible by SP-HALs:

• android.hardware.graphics.common@1.0.so
• android.hardware.graphics.mapper@2.0.so
• android.hardware.renderscript@1.0.so (Renderscript)
• libRS_internal.so (Renderscript)
• libbase.so
• libc++.so
• libcutils.so
• libhardware.so
• libhidlbase.so
• libhidltransport.so
• libhwbinder.so
• libion.so
• libutils.so
• libz.so

The following VNDK-SP dependencies (VNDK-SP-Private) are invisible to SP-HALs:

• libRSCpuRef.so (Renderscript)
• libRSDriver.so (Renderscript)
• libbacktrace.so
• libblas.so (Renderscript)
• libbcinfo.so (Renderscript)
• liblzma.so
• libunwind.so

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

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

VNDK terminology

• Modules refer to either Shared Libraries or Executables.
• Processes are operating system tasks spawned from Executables.
• Framework-qualified terms refer to the concepts related to the system partition.
• Vendor-qualified terms refer to the concepts related to vendor partitions.

For example:

• 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 (e.g. /system/bin/app_process).
• 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 (e.g.
/vendor/bin/android.hardware.camera.provider@2.4-service).

VNDK versioning

In Android {{ androidPVersionNumber }}, VNDK shared libraries are versioned:

• The ro.vndk.version system property is automatically added to /vendor/default.prop.
• VNDK shared libraries are installed to /system/lib[64]/vndk-${ro.vndk.version}.
• VNDK-SP shared libraries are installed to /system/lib[64]/vndk-sp-${ro.vndk.version}.
• The dynamic linker configuration file is installed to /system/etc/ld.config.${ro.vndk.version}.txt.

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

Upgrading devices

If an Android 8.x device disabled VNDK run-time enforcement (i.e. either built without BOARD_VNDK_VERSION or built with BOARD_VNDK_RUNTIME_DISABLE), it may add PRODUCT_USE_VNDK_OVERRIDE := false to BoardConfig.mk while upgrading to Android {{ androidPVersionNumber }}.

If PRODUCT_USE_VNDK_OVERRIDE is false, the ro.vndk.lite property will be automatically added to /vendor/default.prop and its value will be true. Consequently, the dynamic linker will load the linker namespace configuration from /system/etc/ld.config.vndk_lite.txt, which isolates only SP-HAL and VNDK-SP.

To upgrade an Android 7.0 or lower device to Android {{ androidPVersionNumber }}, add PRODUCT_TREBLE_LINKER_NAMESPACES_OVERRIDE := false to BoardConfig.mk.

Vendor Test Suite (VTS)

The Android {{ androidPVersionNumber }} 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.

If the ro.product.first_api_level property is greater than 27, the ro.vndk.lite property must not be defined. VtsTreblePlatformVersionTest will fail if ro.vndk.lite is defined in a newly-launched Android {{ androidPVersionNumber }} device.

Document history

This section tracks changes to VNDK documentation.

Android {{ androidPVersionNumber }} changes

• Add VNDK versioning section.
• Add VTS section.
• Some VNDK categories have been renamed:
• LL-NDK-Indirect has been renamed to LL-NDK-Private.
• VNDK-Indirect has been renamed to VNDK-Private.
• VNDK-SP-Indirect-Private has been renamed to VNDK-SP-Private.
• VNDK-SP-Indirect has been removed.

Android 8.1 changes

• SP-NDK libraries have been merged into LL-NDK libraries.
• Replace libui.so with libft2.so in RS namespace section. It was an error to include libui.so.
• Add libGLESv3.so and libandroid_net.so to LL-NDK libraries.
• Add libion.so to VNDK-SP libraries.
• Remove libstdc++.so from LL-NDK libraries. Use libc++.so instead. Some versions of standalone toolchains may add -lstdc++ to the default linker flags. To disable the defaults, add -nodefaultlibs -lc -lm -ldl to LDFLAGS.
• Move libz.so from LL-NDK to VNDK-SP libraries. In some configurations, libz.so may continue being LL-NDK. However, there should be no observable differences.