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 [Android NDK ABIs](
20    https://developer.android.com/ndk/guides/abis).
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-5]  MUST accurately report the native Application Binary Interface
28    (ABI) supported by the device, via the `android.os.Build.SUPPORTED_ABIS`,
29    `android.os.Build.SUPPORTED_32_BIT_ABIS`, and
30    `android.os.Build.SUPPORTED_64_BIT_ABIS` parameters, each a comma separated
31    list of ABIs ordered from the most to the least preferred one.
32*   [C-0-6] MUST report, via the above parameters, a subset of the following
33    list of ABIs and MUST NOT report any ABI not on the list.
34
35     *   `armeabi` (no longer supported as a target by the NDK)
36     *   [`armeabi-v7a`](https://developer.android.com/ndk/guides/abis#v7a)
37     *   [`arm64-v8a`](https://developer.android.com/ndk/guides/abis#arm64-v8a)
38     *   [`x86`](https://developer.android.com/ndk/guides/abis#x86)
39     *   [`x86-64`](https://developer.android.com/ndk/guides/abis#86-64)
40*   [C-0-7] MUST make all the following libraries, providing native APIs,
41    available to apps that include native code:
42
43     *   libaaudio.so (AAudio native audio support)
44     *   libamidi.so (native MIDI support, if feature `android.software.midi`
45         is claimed as described in Section 5.9)
46     *   libandroid.so (native Android activity support)
47     *   libc (C library)
48     *   libcamera2ndk.so
49     *   libdl (dynamic linker)
50     *   libEGL.so (native OpenGL surface management)
51     *   libGLESv1\_CM.so (OpenGL ES 1.x)
52     *   libGLESv2.so (OpenGL ES 2.0)
53     *   libGLESv3.so (OpenGL ES 3.x)
54     *   libicui18n.so
55     *   libicuuc.so
56     *   libjnigraphics.so
57     *   liblog (Android logging)
58     *   libmediandk.so (native media APIs support)
59     *   libm (math library)
60     *   libneuralnetworks.so (Neural Networks API)
61     *   libOpenMAXAL.so (OpenMAX AL 1.0.1 support)
62     *   libOpenSLES.so (OpenSL ES 1.0.1 audio support)
63     *   libRS.so
64     *   libstdc++ (Minimal support for C++)
65     *   libvulkan.so (Vulkan)
66     *   libz (Zlib compression)
67     *   JNI interface
68
69*   [C-0-8] MUST NOT add or remove the public functions for the native libraries
70    listed above.
71*   [C-0-9] MUST list additional non-AOSP libraries exposed directly to
72    third-party apps in `/vendor/etc/public.libraries.txt`.
73*   [C-0-10] MUST NOT expose any other native libraries, implemented and
74    provided in AOSP as system libraries, to third-party apps targeting API
75    level 24 or higher as they are reserved.
76*   [C-0-11] MUST export all the OpenGL ES 3.1 and [Android Extension Pack](
77    http://developer.android.com/guide/topics/graphics/opengl.html#aep)
78    function symbols, as defined in the NDK, through the `libGLESv3.so` library.
79    Note that while all the symbols MUST be present, section 7.1.4.1 describes
80    in more detail the requirements for when the full implementation of each
81    corresponding functions are expected.
82*   [C-0-12] MUST export function symbols for the core Vulkan 1.0 function
83    symbols, as well as the `VK_KHR_surface`, `VK_KHR_android_surface`,
84    `VK_KHR_swapchain`, `VK_KHR_maintenance1`, and
85    `VK_KHR_get_physical_device_properties2` extensions through the
86    `libvulkan.so` library.  Note that while all the symbols MUST be present,
87    section 7.1.4.2 describes in more detail the requirements for when the full
88    implementation of each corresponding functions are expected.
89*   SHOULD be built using the source code and header files available in the
90    upstream Android Open Source Project
91
92Note that future releases of Android may introduce support for additional
93ABIs.
94
95### 3.3.2. 32-bit ARM Native Code Compatibility
96
97If device implementations report the support of the `armeabi` ABI, they:
98
99*    [C-3-1] MUST also support `armeabi-v7a` and report its support, as
100     `armeabi` is only for backwards compatibility with older apps.
101
102If device implementations report the support of the `armeabi-v7a` ABI, for apps
103using this ABI, they:
104
105*    [C-2-1] MUST include the following lines in `/proc/cpuinfo`, and SHOULD NOT
106     alter the values on the same device, even when they are read by other ABIs.
107
108     *   `Features: `, followed by a list of any optional ARMv7 CPU features
109         supported by the device.
110     *   `CPU architecture: `, followed by an integer describing the device's
111         highest supported ARM architecture (e.g., "8" for ARMv8 devices).
112
113*    [C-2-2] MUST always keep the following operations available, even in the
114     case where the ABI is implemented on an ARMv8 architecture, either through
115     native CPU support or through software emulation:
116
117     *   SWP and SWPB instructions.
118     *   SETEND instruction.
119     *   CP15ISB, CP15DSB, and CP15DMB barrier operations.
120
121*    [C-2-3] MUST include support for the [Advanced SIMD](
122     http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0388f/Beijfcja.html)
123     (a.k.a. NEON) extension.
124