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 (named `classloader-namespace`) that is
15associated with the given classloader, and tries to load the requested library
16from the namespace. The actual searching, loading, and linking of the library
17is 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 runtime 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