Different Android handsets use different CPUs, which in turn support different instruction sets. Each combination of CPU and instruction sets has its own Application Binary Interface, or ABI. The ABI defines, with great precision, how an application's machine code is supposed to interact with the system at runtime. You must specify an ABI for each CPU architecture you want your app to work with.
A typical ABI includes the following information:
- The CPU instruction set(s) that the machine code should use.
- The endianness of memory stores and loads at runtime.
- The format of executable binaries, such as programs and shared libraries, and the types of content they support.
- Various conventions for passing data between your code and the system. These conventions include alignment constraints, as well as how the system uses the stack and registers when it calls functions.
- The list of function symbols available to your machine code at runtime, generally from very specific sets of libraries.
This page enumerates the ABIs that the NDK supports, and provides information about how each ABI works. For a list of ABI issues for 32-bit systems, see 32-bit ABI bugs
Supported ABIs
Each ABI supports one or more instruction sets. Table 1 provides an at-a-glance overview of the instruction sets each ABI supports.
ABI | Supported Instruction Set(s) | Notes |
---|---|---|
armeabi |
Deprecated in r16. Removed in r17. No hard float. | |
armeabi-v7a |
|
Incompatible with ARMv5, v6 devices. |
arm64-v8a |
||
x86 |
No support for MOVBE or SSE4. | |
x86_64 |
|
Note: Historically the NDK supported 32-bit and 64-bit MIPS, but support was removed in NDK r17.
More detailed information about each ABI appears below.
armeabi
Note: This ABI was removed in NDK r17.
This ABI is for ARM-based CPUs that support at least the ARMv5TE instruction set. Please refer to the following documentation for more details:
- ARM Architecture Reference Manual
- Procedure Call Standard for the ARM Architecture
- ARM ELF File Format
- Application Binary Interface (ABI) for the ARM Architecture
- Base Platform ABI for the ARM Architecture
- C Library ABI for the ARM Architecture
- C++ ABI for the ARM Architecture
- Run-time ABI for the ARM Architecture
- ELF System V Application Binary Interface
- Generic/Itanium C++ ABI
The AAPCS standard defines EABI as a family of similar but distinct ABIs. Also, Android follows the little-endian ARM GNU/Linux ABI.
This ABI does not support hardware-assisted floating point
computations. Instead, all floating-point operations use software helper
functions from the compiler's libgcc.a
static library.
The armeabi ABI supports ARM’s
Thumb (a.k.a. Thumb-1) instruction set. The NDK generates Thumb
code by default unless you specify different behavior using the
LOCAL_ARM_MODE
variable in your
Android.mk
file.
armeabi-v7a
This ABI extends armeabi to include several CPU instruction set extensions. The instruction extensions that this Android-specific ABI supports are:
- The Thumb-2 instruction set extension, which provides performance comparable to 32-bit ARM instructions with similar compactness to Thumb-1.
- The VFP hardware-FPU instructions. More specifically, VFPv3-D16, which includes 16 dedicated 64-bit floating point registers, in addition to another 16 32-bit registers from the ARM core.
Other extensions that the v7-a ARM spec describes, including Advanced SIMD (a.k.a. NEON), VFPv3-D32, and ThumbEE, are optional to this ABI. Since their presence is not guaranteed, the system should check at runtime whether the extensions are available. If they are not, you must use alternative code paths. This check is similar to the one that the system typically performs to check or use MMX, SSE2, and other specialized instruction sets on x86 CPUs.
For information about how to perform these runtime checks, refer to
The cpufeatures
Library.
Also, for information about the NDK's support for building
machine code for NEON, see
NEON Support.
The armeabi-v7a
ABI uses the -mfloat-abi=softfp
switch to
enforce the rule that the compiler must pass all double values in core register pairs during
function calls, instead of dedicated floating-point ones. The system can perform all internal
computations using the FP registers. Doing so speeds up the computations greatly.
arm64-v8a
This ABI is for ARMv8-based CPUs that support AArch64. It also includes the NEON and VFPv4 instruction sets.
For more information, see the ARMv8 Technology Preview, and contact ARM for further details.
x86
This ABI is for CPUs supporting the instruction set commonly referred to as "x86" or "IA-32". Characteristics of this ABI include:
- Instructions normally generated by GCC with compiler flags such as the following:
-march=i686 -mtune=intel -mssse3 -mfpmath=sse -m32
These flags target the Pentium Pro instruction set, along with the the MMX, SSE, SSE2, SSE3, and SSSE3 instruction set extensions. The generated code is an optimization balanced across the top Intel 32-bit CPUs.
For more information on compiler flags, particularly related to performance optimization, refer to GCC x86 performance hints.
- Use of the standard Linux x86 32-bit calling convention, as opposed to the one for SVR. For more information, see section 6, "Register Usage", of Calling conventions for different C++ compilers and operating systems.
The ABI does not include any other optional IA-32 instruction set extensions, such as:
- MOVBE
- Any variant of SSE4.
You can still use these extensions, as long as you use runtime feature-probing to enable them, and provide fallbacks for devices that do not support them.
The NDK toolchain assumes 16-byte stack alignment before a function call. The default tools and options enforce this rule. If you are writing assembly code, you must make sure to maintain stack alignment, and ensure that other compilers also obey this rule.
Refer to the following documents for more details:
- GCC online documentation: Intel 386 and AMD x86-64 Options
- Calling conventions for different C++ compilers and operating systems
- Intel IA-32 Intel Architecture Software Developer's Manual, Volume 2: Instruction Set Reference
- Intel IA-32 Intel Architecture Software Developer's Manual, Volume 3: System Programming Guide
- System V Application Binary Interface: Intel386 Processor Architecture Supplement
x86_64
This ABI is for CPUs supporting the instruction set commonly referred to as "x86-64." It supports instructions that GCC typically generates with the following compiler flags:
-march=x86-64 -msse4.2 -mpopcnt -m64 -mtune=intel
These flags target the x86-64 instruction set, according to the GCC documentation. along with the MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, and POPCNT instruction-set extensions. The generated code is an optimization balanced across the top Intel 64-bit CPUs.
For more information on compiler flags, particularly related to performance optimization, refer to GCC x86 Performance.
This ABI does not include any other optional x86-64 instruction set extensions, such as:
- MOVBE
- SHA
- AVX
- AVX2
You can still use these extensions, as long as you use runtime feature probing to enable them, and provide fallbacks for devices that do not support them.
Refer to the following documents for more details:
- Calling conventions for different C++ compilers and operating systems
- Intel64 and IA-32 Architectures Software Developer's Manual, Volume 2: Instruction Set Reference
- Intel64 and IA-32 Intel Architecture Software Developer's Manual Volume 3: System Programming
Generating Code for a Specific ABI
By default, the NDK targets for all non-deprecated ABIs. You can target a
single ABI by setting APP_ABI
in your Application.mk
file. The
following snippet shows a few examples of using APP_ABI
APP_ABI := arm64-v8a # Target only arm64-v8a APP_ABI := all # Target all ABIs, including those that are deprecated. APP_ABI := armeabi-v7a x86_64 # Target only armeabi-v7a and x86_64.
For more information on the values you can specify for APP_ABI
,
see Application.mk.
The default behavior of the build system is to include the binaries for each ABI in a single APK, also known as a fat APK. A fat APK is much larger than one containing only the binaries for a single ABI; the tradeoff is gaining wider compatibility, but at the expense of a larger APK. It is strongly recommended that you take advantage of split APKs to reduce the size of your APKs while still maintaining maximum device compatibility.
At installation time, the package manager unpacks only the most appropriate machine code for the target device. For details, see Automatic extraction of native code at install time.
ABI Management on the Android Platform
This section provides details about how the Android platform manages native code in APKs.
Native code in app packages
Both the Play Store and Package Manager expect to find NDK-generated libraries on filepaths inside the APK matching the following pattern:
/lib/<abi>/lib<name>.so
Here, <abi>
is one of the ABI names listed under Supported ABIs,
and <name>
is the name of the library as you defined it for the LOCAL_MODULE
variable in the Android.mk
file. Since
APK files are just zip files, it is trivial to open them and confirm that the shared native
libraries are where they belong.
If the system does not find the native shared libraries where it expects them, it cannot use
them. In such a case, the app itself has to copy the libraries over, and then
perform dlopen()
.
In a fat APK, each library resides under a directory whose name matches a corresponding ABI. For example, a fat APK may contain:
/lib/armeabi/libfoo.so /lib/armeabi-v7a/libfoo.so /lib/arm64-v8a/libfoo.so /lib/x86/libfoo.so /lib/x86_64/libfoo.so
Note: ARMv7-based Android devices running 4.0.3 or earlier
install native libraries from the armeabi
directory instead of the armeabi-v7a
directory if both directories exist. This is because /lib/armeabi/
comes after
/lib/armeabi-v7a/
in the APK. This issue is fixed from 4.0.4.
Android Platform ABI support
The Android system knows at runtime which ABI(s) it supports, because build-specific system properties indicate:
- The primary ABI for the device, corresponding to the machine code used in the system image itself.
- Optionally, secondary ABIs, corresponding to other ABI that the system image also supports.
This mechanism ensures that the system extracts the best machine code from the package at installation time.
For best performance, you should compile directly for the primary ABI. For example, a
typical ARMv5TE-based device would only define the primary ABI: armeabi
. By contrast, a
typical, ARMv7-based device would define the primary ABI as armeabi-v7a
and the secondary
one as armeabi
, since it can run application native binaries generated for each of them.
64-bit devices also support their 32-bit variants. Using arm64-v8a devices as an example, the device can also run armeabi and armeabi-v7a code. Note, however, that you application will perform much better on 64-bit devices if it targets arm64-v8a rather than relying on the device running the armeabi-v7a version of your application.
Many x86-based devices can also run armeabi-v7a
and armeabi
NDK binaries. For
such devices, the primary ABI would be x86
, and the second one, armeabi-v7a
.
Automatic extraction of native code at install time
When installing an application, the package manager service scans the APK, and looks for any shared libraries of the form:
lib/<primary-abi>/lib<name>.so
If none is found, and you have defined a secondary ABI, the service scans for shared libraries of the form:
lib/<secondary-abi>/lib<name>.so
When it finds the libraries that it's looking for, the package manager
copies them to /lib/lib<name>.so
, under the application's
data
directory (data/data/<package_name>/lib/
).
If there is no shared-object file at all, the application builds and installs, but crashes at runtime.