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.
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.)
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.
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:
- 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.
- 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
- LL-NDK includes the following libraries:
- LL-NDK includes the following libraries:
- 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
- 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
- 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:
The following libraries are VNDK-SP libraries that are accessible by SP-HALs:
The following VNDK-SP dependencies (VNDK-SP-Private) are invisible to SP-HALs:
The following are framework-only libraries with RS exceptions (FWK-ONLY-RS):
- 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.
- Framework Executables refer to executables in
- Framework Shared Libraries refer to shared libraries under
- Framework Modules refer to both Framework Shared Libraries and Framework Executables.
- Framework Processes are processes spawned from Framework
- Vendor Executables refer to executables in
- Vendor Shared Libraries refer to shared libraries under
- Vendor Modules refer to both Vendor Executables and Vendor Shared Libraries.
- Vendor Processes are processes spawned from Vendor Executables (e.g.
In Android 9, VNDK shared libraries are versioned:
ro.vndk.versionsystem property is automatically added to
- VNDK shared libraries are installed to
- VNDK-SP shared libraries are installed to
- The dynamic linker configuration file is installed to
The value of
ro.vndk.version is chosen by the algorithm
BOARD_VNDK_VERSIONis not equal to
BOARD_VNDK_VERSIONis equal to
- Otherwise, use
If an Android 8.x device disabled VNDK run-time enforcement (i.e. either
BOARD_VNDK_VERSION or built with
BOARD_VNDK_RUNTIME_DISABLE), it may add
PRODUCT_USE_VNDK_OVERRIDE := false to
while upgrading to Android 9.
ro.vndk.lite property will be automatically added to
/vendor/default.prop and its value will be
Consequently, the dynamic linker will load the linker namespace configuration
/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
PRODUCT_TREBLE_LINKER_NAMESPACES_OVERRIDE := false to
Vendor Test Suite (VTS)
The Android 9 Vendor Test Suite (VTS) mandates a
ro.vndk.version property. Both newly-launched devices
and upgrading devices must define
ro.vndk.version. Some VNDK test
VtsVndkDependencyTest) rely on the
property to load the matching eligible VNDK libraries data sets.
ro.product.first_api_level property is greater than 27,
ro.vndk.lite property must not be defined.
VtsTreblePlatformVersionTest will fail if
ro.vndk.lite is defined in a newly-launched Android
This section tracks changes to VNDK documentation.
Android 9 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.
libft2.soin RS namespace section. It was an error to include
libandroid_net.soto LL-NDK libraries.
libion.soto VNDK-SP libraries.
libstdc++.sofrom LL-NDK libraries. Use
libc++.soinstead. Some versions of standalone toolchains may add
-lstdc++to the default linker flags. To disable the defaults, add
-nodefaultlibs -lc -lm -ldlto
libz.sofrom LL-NDK to VNDK-SP libraries. In some configurations,
libz.somay continue being LL-NDK. However, there should be no observable differences.