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.sowith SIMD instructions (without adding new functions), then the modifiedlibcrypto.sowill 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.soto access some internal data, then the modifiedlibjpeg.sowill 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, thenlibfoo.sowill be a DX-Lib.
- Example 1. If a vendor adds a helper function to
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.soonly 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.sorelies on another non-AOSP library namedlibjpeg_turbo2.so, then the modifiedlibjpeg.sowill be an UX-Module. - Example 2. If a vendor adds a new function to their modified
libexif.soand their modifiedlibjpeg.souses the newly added function fromlibexif.so, then their modifiedlibjpeg.sowill be an UX-Module.
- Example 1. If a modified
Definitions and usages are independent from each other:
| Used Functionalities | |||
|---|---|---|---|
| Only AOSP (UA) | Extended (UX) | ||
| Defined Functionalities | Only AOSP (DA) | DAUA | DAUX |
| Extended (DX) | DXUA | DXUX | |
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 a 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.