VNDK Extensions

Android device manufacturers change the source code of AOSP libraries for various reasons. Some vendors reimplement functions in AOSP libraries to boost the performance while other vendors add new hooks, new APIs, or new functionalities to AOSP libraries. This section provides guidelines for extending AOSP libraries in a way that does not break CTS/VTS.

Drop-in replacement

All modified shared libraries must be binary-compatible, drop-in replacements of their AOSP counterpart. All existing AOSP users must be able to use the modified shared library without recompilations. This requirement implies the following:

• AOSP functions must not be removed.
• Structures must not be altered if such structures are exposed to their users.
• Pre-condition of functions must not be strengthened.
• Functions must provide equivalent functionalities.
• Post-condition of functions must not be weakened.

Extended module classifications

Classify modules by the functionalities they define and use.

Note: Functionalities is used here instead of API/ABI because it is possible to add functionality without changing any API/ABI.

Depending on the functionalities defined in a module, modules can be classified into DA-Module and DX-Module:

• Defining-only-AOSP Modules (DA-Module) do not define new functionalities which were not in the AOSP counterpart.
  • Example 1. An intact unmodified AOSP library is a DA-Module.
  • Example 2. If a vendor rewrites the functions in libcrypto.so with SIMD instructions (without adding new functions), then the modified libcrypto.so will be a DA-Module.
• Defining-Extension Modules (DX-Module) either define new functionalities or do not have an AOSP counterpart.
  • Example 1. If a vendor adds a helper function to libjpeg.so to access some internal data, then the modified libjpeg.so will be a DX-Lib and the newly added function will be the extended portion of the library.
  • Example 2. If a vendor defines a non-AOSP library named libfoo.so, then libfoo.so will be a DX-Lib.

Depending on the functionalities used by a module, modules can be classified into UA-Module and UX-Module.

• Using-only-AOSP Modules (UA-Module) only use AOSP functionalities in their implementations. They do not rely on any non-AOSP extensions.
  • Example 1. An intact unmodified AOSP library is an UA-Module.
  • Example 2. If a modified shared library libjpeg.so only relies on other AOSP APIs, then it will be an UA-Module.
• Using-Extension Modules (UX-Module) rely on some non-AOSP functionalities in their implementations.
  • Example 1. If a modified libjpeg.so relies on another non-AOSP library named libjpeg_turbo2.so, then the modified libjpeg.so will be an UX-Module.
  • Example 2. If a vendor adds a new function to their modified libexif.so and their modified libjpeg.so uses the newly added function from libexif.so, then their modified libjpeg.so will be an UX-Module.

Definitions and usages are independent from each other:

VNDK extension mechanism

Vendor modules that rely on extended functionalities won't work because the AOSP library with the same name does not have the extended functionality. If vendor modules directly or indirectly depend on extended functionalities, vendors should copy DAUX, DXUA, and DXUX shared libraries to the vendor partition (vendor processes always look for shared libraries in the vendor partition first). However, LL-NDK libraries must not be copied, so vendor modules must not rely on the extended functionalities defined by the modified LL-NDK libraries.

DAUA shared libraries can remain on the system partition if the corresponding AOSP library can provide the same functionality and vendor modules continue to work when the system partition is overwritten by an Generic System Image (GSI).

Drop-in replacement is important because the unmodified VNDK libraries in the GSI will link with the modified shared libraries on name collision. If the AOSP libraries are modified in an API/ABI incompatible manner, the AOSP libraries in the GSI might fail to link or result in undefined behaviors.