1## 3.3\. Native API Compatibility
2
3Native code compatibility is challenging. For this reason,
4device implementers are:
5
6*   [SR] STRONGLY RECOMMENDED to use the implementations of the libraries
7listed below from the upstream Android Open Source Project.
8
9### 3.3.1\. Application Binary Interfaces
10
11Managed Dalvik bytecode can call into native code provided in the application
12`.apk` file as an ELF `.so` file compiled for the appropriate device hardware
13architecture. As native code is highly dependent on the underlying processor
14technology, Android defines a number of Application Binary Interfaces (ABIs) in
15the Android NDK.
16
17Device implementations:
18
19*   [C-0-1] MUST be compatible with one or more defined ABIs and implement
20    compatibility with the Android NDK.
21*   [C-0-2] MUST include support for code running in the managed environment to
22    call into native code, using the standard Java Native Interface (JNI)
23    semantics.
24*   [C-0-3] MUST be source-compatible (i.e. header-compatible) and
25    binary-compatible (for the ABI) with each required library in the list
26    below.
27*   [C-0-4] MUST support the equivalent 32-bit ABI if any 64-bit ABI is
28    supported.
29*   [C-0-5]  MUST accurately report the native Application Binary Interface
30    (ABI) supported by the device, via the `android.os.Build.SUPPORTED_ABIS`,
31    `android.os.Build.SUPPORTED_32_BIT_ABIS`, and
32    `android.os.Build.SUPPORTED_64_BIT_ABIS` parameters, each a comma separated
33    list of ABIs ordered from the most to the least preferred one.
34*   [C-0-6] MUST report, via the above parameters, only those ABIs documented
35    and described in the latest version of the
36    [Android NDK ABI Management documentation](
37    https://developer.android.com/ndk/guides/abis.html), and MUST include
38    support for the [Advanced SIMD](
39    http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0388f/Beijfcja.html)
40    (a.k.a. NEON) extension.
41*   [C-0-7] MUST make all the following libraries, providing native APIs,
42    available to apps that include native code:
43
44    *   libaaudio.so (AAudio native audio support)
45    *   libandroid.so (native Android activity support)
46    *   libc (C library)
47    *   libcamera2ndk.so
48    *   libdl (dynamic linker)
49    *   libEGL.so (native OpenGL surface management)
50    *   libGLESv1\_CM.so (OpenGL ES 1.x)
51    *   libGLESv2.so (OpenGL ES 2.0)
52    *   libGLESv3.so (OpenGL ES 3.x)
53    *   libicui18n.so
54    *   libicuuc.so
55    *   libjnigraphics.so
56    *   liblog (Android logging)
57    *   libmediandk.so (native media APIs support)
58    *   libm (math library)
59    *   libneuralnetworks.so (Neural Networks API)
60    *   libOpenMAXAL.so (OpenMAX AL 1.0.1 support)
61    *   libOpenSLES.so (OpenSL ES 1.0.1 audio support)
62    *   libRS.so
63    *   libstdc++ (Minimal support for C++)
64    *   libvulkan.so (Vulkan)
65    *   libz (Zlib compression)
66    *   JNI interface
67
68*   [C-0-8] MUST NOT add or remove the public functions for the native libraries
69    listed above.
70*   [C-0-9] MUST list additional non-AOSP libraries exposed directly to
71    third-party apps in `/vendor/etc/public.libraries.txt`.
72*   [C-0-10] MUST NOT expose any other native libraries, implemented and
73    provided in AOSP as system libraries, to third-party apps targeting API
74    level 24 or higher as they are reserved.
75*   [C-0-11] MUST export all the OpenGL ES 3.1 and [Android Extension Pack](
76    http://developer.android.com/guide/topics/graphics/opengl.html#aep)
77    function symbols, as defined in the NDK, through the `libGLESv3.so` library.
78    Note that while all the symbols MUST be present, section 7.1.4.1 describes
79    in more detail the requirements for when the full implementation of each
80    corresponding functions are expected.
81*   [C-0-12] MUST export function symbols for the core Vulkan 1.0 function
82    symobls, as well as the `VK_KHR_surface`, `VK_KHR_android_surface`,
83    `VK_KHR_swapchain`, `VK_KHR_maintenance1`, and
84    `VK_KHR_get_physical_device_properties2` extensions through the
85    `libvulkan.so` library.  Note that while all the symbols MUST be present,
86    section 7.1.4.2 describes in more detail the requirements for when the full
87    implementation of each corresponding functions are expected.
88*   SHOULD be built using the source code and header files available in the
89    upstream Android Open Source Project
90
91Note that future releases of the Android NDK may introduce support for
92additional ABIs.
93
94### 3.3.2. 32-bit ARM Native Code Compatibility
95
96If device implementations are 64-bit ARM devices, then:
97
98*    [C-1-1] Although the ARMv8 architecture deprecates several CPU operations,
99     including some operations used in existing native code, the following
100     deprecated operations MUST remain available to 32-bit native ARM code,
101     either through native CPU support or through software emulation:
102
103     *   SWP and SWPB instructions
104     *   SETEND instruction
105     *   CP15ISB, CP15DSB, and CP15DMB barrier operations
106
107If device implementations include a 32-bit ARM ABI, they:
108
109*    [C-2-1] MUST include the following lines in `/proc/cpuinfo` when it is read
110     by 32-bit ARM applications to ensure compatibility with applications built
111     using legacy versions of Android NDK.
112
113     *   `Features: `, followed by a list of any optional ARMv7 CPU features
114     supported by the device.
115     *   `CPU architecture: `, followed by an integer describing the device's
116     highest supported ARM architecture (e.g., "8" for ARMv8 devices).
117
118*    SHOULD not alter `/proc/cpuinfo` when read by 64-bit ARM or non-ARM
119     applications.
120