1libnativeloader 2=============================================================================== 3 4Overview 5------------------------------------------------------------------------------- 6libnativeloader is responsible for loading native shared libraries (`*.so` 7files) inside the Android Runtime (ART). The native shared libraries could be 8app-provided JNI libraries or public native libraries like `libc.so` provided 9by the platform. 10 11The most typical use case of this library is calling `System.loadLibrary(name)`. 12When the method is called, the ART runtime delegates the call to this library 13along with the reference to the classloader where the call was made. Then this 14library finds the linker namespace (typically with the name `clns-` followed by 15a number to make it unique) that is associated with the given classloader, and 16tries to load the requested library from that namespace. The actual searching, 17loading, and linking of the library is performed by the dynamic linker. 18 19The linker namespace is created when an APK is loaded into the process, and is 20associated with the classloader that loaded the APK. The linker namespace is 21configured so that only the JNI libraries embedded in the APK is accessible 22from the namespace, thus preventing an APK from loading JNI libraries of other 23APKs. 24 25The linker namespace is also configured differently depending on other 26characteristics of the APK such as whether or not the APK is bundled with the 27platform. In case of the unbundled, i.e., downloaded or updated APK, only the 28public native libraries that is listed in `/system/etc/public.libraries.txt` 29are available from the platform, whereas in case of the bundled, all libraries 30under `/system/lib` are available (i.e. shared). In case when the unbundled 31app is from `/vendor` or `/product` partition, the app is additionally provided 32with the [VNDK-SP](https://source.android.com/devices/architecture/vndk#sp-hal) 33libraries. As the platform is getting modularized with 34[APEX](https://android.googlesource.com/platform/system/apex/+/refs/heads/master/docs/README.md), 35some libraries are no longer provided from platform, but from the APEXes which 36have their own linker namespaces. For example, ICU libraries `libicuuc.so` and 37`libicui18n.so` are from the I18n APEX. 38 39The list of public native libraries is not static. The default set of libraries 40are defined in AOSP, but partners can extend it to include their own libraries. 41Currently, following extensions are available: 42 43- `/vendor/etc/public.libraries.txt`: libraries in `/vendor/lib` that are 44specific to the underlying SoC, e.g. GPU, DSP, etc. 45- `/{system|product}/etc/public.libraries-<companyname>.txt`: libraries in 46`/{system|product}/lib` that a device manufacturer has newly added. The 47libraries should be named as `lib<name>.<companyname>.so` as in 48`libFoo.acme.so`. 49 50Note that, due to the naming constraint requiring `.<companyname>.so` suffix, it 51is prohibited for a device manufacturer to expose an AOSP-defined private 52library, e.g. libgui.so, libart.so, etc., to APKs. 53 54Lastly, libnativeloader is responsible for abstracting the two types of the 55dynamic linker interface: `libdl.so` and `libnativebridge.so`. The former is 56for non-translated, e.g. ARM-on-ARM, libraries, while the latter is for 57loading libraries in a translated environment such as ARM-on-x86. 58 59Implementation 60------------------------------------------------------------------------------- 61Implementation wise, libnativeloader consists of four parts: 62 63- `native_loader.cpp` 64- `library_namespaces.cpp` 65- `native_loader_namespace.cpp` 66- `public_libraries.cpp` 67 68`native_loader.cpp` implements the public interface of this library. It is just 69a thin wrapper around `library_namespaces.cpp` and `native_loader_namespace.cpp`. 70 71`library_namespaces.cpp` implements the singleton class `LibraryNamespaces` which 72is a manager-like entity that is responsible for creating and configuring 73linker namespaces and finding an already created linker namespace for a given 74classloader. 75 76`native_loader_namespace.cpp` implements the class `NativeLoaderNamespace` that 77models a linker namespace. Its main job is to abstract the two types of the 78dynamic linker interface so that other parts of this library do not have to know 79the differences of the interfaces. 80 81`public_libraries.cpp` is responsible for reading `*.txt` files for the public 82native libraries from the various partitions. It can be considered as a part of 83`LibraryNamespaces` but is separated from it to hide the details of the parsing 84routines. 85