1page.title=ABI Management 2@jd:body 3 4<div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>On this page</h2> 7 8 <ol> 9 <li><a href="#sa">Supported ABIs</a></li> 10 <li><a href="#gc">Generating Code for a Specific ABI</a></li> 11 <li><a href="#am">ABI Management on the Android Platform</a></li> 12 </ol> 13 </div> 14 </div> 15 16<p>Different Android handsets use different CPUs, which in turn support different instruction sets. 17Each combination of CPU and instruction sets has its own Application Binary Interface, or 18<i>ABI</i>. The ABI defines, with great precision, how an application's machine code is supposed to 19interact with the system at runtime. You must specify an ABI for each CPU architecture you want 20your app to work with.</p> 21 22<p>A typical ABI includes the following information:</p> 23 24<ul> 25<li>The CPU instruction set(s) that the machine code should use.</li> 26<li>The endianness of memory stores and loads at runtime.</li> 27<li>The format of executable binaries, such as programs and shared libraries, and 28the types of content they support.</li> 29<li>Various conventions for passing data between your code and the system. 30These conventions include alignment constraints, as well as how the system uses the stack and 31registers when it calls functions.</li> 32<li>The list of function symbols available to your machine code at runtime, 33generally from very specific sets of libraries.</li> 34</ul> 35 36<p>This page enumerates the ABIs that the NDK supports, and provides information about how each ABI 37works.</p> 38 39<h2 id="sa">Supported ABIs</h2> 40 41<p>Each ABI supports one or more instruction sets. Table 1 provides an at-a-glance overview of 42the instruction sets each ABI supports.</p> 43 44<p class="table-caption" id="abi-table"> 45 <strong>Table 1.</strong> ABIs and supported instruction sets.</p> 46 47<table> 48<tr> 49<th>ABI</th> 50<th>Supported Instruction Set(s)</th> 51<th>Notes</th> 52</tr> 53 54<tr> 55<td><a href="#armeabi">{@code armeabi}</a> </td> 56<td><li>ARMV5TE and later</li> 57<li>Thumb-1</li></td> 58<td>No hard float.</td> 59</tr> 60 61<tr> 62<td><a href="#v7a">{@code armeabi-v7a} ({@code armeabi-v7a-hard)}</a></td> 63<td> 64<li>armeabi</li> 65<li>Thumb-2</li> 66<li>VFPv3-D16</li> 67<li>Other, optional</li></td> 68<td>Hard float when specified as {@code armeabi-v7a-hard}. 69Incompatible with ARMv5, v6 devices.</td> 70</tr> 71 72<tr> 73<td><a href="#arm64-v8a">{@code arm64-v8a}</a></td> 74<td><li>AArch-64</li></td> 75</tr> 76 77<tr> 78<td> 79<a href="#x86">{@code x86}</a></td> 80<td><li>x86 (IA-32)</li> 81<li>MMX</li> 82<li>SSE/2/3</li> 83<li>SSSE3</li></td> 84<td>No support for MOVBE or SSE4.</td> 85</tr> 86 87<tr> 88<td><a href="#86-64">{@code x86_64}</a> </td> 89<td> 90<li>x86-64</li> 91<li>MMX</li> 92<li>SSE/2/3</li> 93<li>SSSE3</li> 94<li>SSE4.1, 4.2</li> 95<li>POPCNT</li></td> 96</tr> 97 98<tr> 99<td><a href="#mips">{@code mips}</a></td> 100<td><li>MIPS32r1 and later</li></td> 101<td>Uses hard-float, and assumes a CPU:FPU clock ratio of 2:1 for maximum 102compatibility. Provides neither micromips nor MIPS16.</td> 103</tr> 104 105<tr> 106<td><a href="#mips64">{@code mips64}</a></td> 107<td><li>MIPS64r6</li></td><td> 108</td> 109</tr> 110</table> 111 112<p>More detailed information about each ABI appears below.</p> 113 114<h3 id="armeabi">armeabi</h3> 115<p>This ABI is for ARM-based CPUs that support at least 116the ARMv5TE instruction set. Please refer to the following documentation for 117more details:</p> 118 119<ul> 120<li><a href="https://www.scss.tcd.ie/~waldroj/3d1/arm_arm.pdf">ARM Architecture 121Reference Manual</a></li> 122<li><a 123href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042e/IHI0042E_aapcs.pdf"> 124Procedure Call Standard for the ARM Architecture</a></li> 125<li><a 126href="http://infocenter.arm.com/help/topic/com.arm.doc.dui0101a/DUI0101A_Elf.pdf"> 127ARM ELF File Format</a></li> 128<li><a 129href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.subset.swdev.abi/index.html">Application Binary Interface (ABI) for the ARM Architecture</a></li> 130<li><a 131href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0037c/IHI0037C_bpabi.pdf"> 132Base Platform ABI for the ARM Architecture</a></li> 133<li><a 134href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0039c/IHI0039C_clibabi.pdf"> 135C Library ABI for the ARM Architecture</a></li> 136<li><a 137href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ihi0041d/index.html"> 138C++ ABI for the ARM Architecture</a></li> 139<li><a 140href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0043d/IHI0043D_rtabi.pdf"> 141Run-time ABI for the ARM Architecture</a></li> 142<li><a href="http://www.sco.com/developers/gabi/2001-04-24/contents.html">ELF 143System V Application Binary Interface</a></li> 144<li><a href="http://mentorembedded.github.com/cxx-abi/abi.html">Generic/Itanium C++ 145ABI</a></li> 146</ul> 147 148<p>The AAPCS standard defines EABI as a family of similar 149but distinct ABIs. Also, Android follows the little-endian 150<a href="http://sourcery.mentor.com/sgpp/lite/arm/portal/kbattach142/arm_gnu_linux_ abi.pdf"> 151ARM GNU/Linux ABI</a>.</p> 152 153<p>This ABI does not support hardware-assisted floating point 154computations. Instead, all floating-point operations use software helper 155functions from the compiler's {@code libgcc.a} static library.</p> 156 157<p>The armeabi ABI supports ARM’s 158<a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0210c/CACBCAAE.html"> 159Thumb (a.k.a. Thumb-1) instruction set</a>. The NDK generates Thumb 160code by default unless you specify different behavior using the 161<code>LOCAL_ARM_MODE</code> variable in your 162<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> 163file.</p> 164 165<h3 id="v7a">armeabi-v7a (armeabi-v7a-hard)</h3> 166<p>This ABI extends armeabi to include several 167<a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0406c/index.html"> 168CPU instruction set extensions</a>. The instruction extensions that this Android-specific 169ABI supports are:</p> 170 171<ul> 172<li>The Thumb-2 instruction set extension, which provides performance comparable to 32-bit ARM 173instructions with similar compactness to Thumb-1.</li> 174<li>The VFP hardware-FPU instructions. More specifically, VFPv3-D16, which 175includes 16 dedicated 64-bit floating point registers, in addition to another 17616 32-bit registers from the ARM core.</li> 177</ul> 178 179<p>Other extensions that the v7-a ARM spec describes, including 180<a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0388f/Beijfcja.html"> 181Advanced SIMD</a> (a.k.a. NEON), VFPv3-D32, and ThumbEE, are optional 182to this ABI. Since their presence is not guaranteed, the system should check at runtime 183whether the extensions are available. If they are not, you must use alternative code paths. This 184check is similar to the one that the system typically performs to check or use 185<a href="http://en.wikipedia.org/wiki/MMX_%28instruction_set%29">MMX</a>, 186<a href="http://en.wikipedia.org/wiki/SSE2">SSE2</a>, and other specialized 187instruction sets on x86 CPUs.</p> 188 189<p>For information about how to perform these runtime checks, refer to 190<a href="{@docRoot}ndk/guides/cpu-features.html">The {@code cpufeatures} Library</a>. 191Also, for information about the NDK's support for building 192machine code for NEON, see 193<a href="{@docRoot}ndk/guides/cpu-arm-neon.html">NEON Support</a>.</p> 194 195<p>The {@code armeabi-v7a} ABI uses the {@code -mfloat-abi=softfp} switch to 196enforce the rule that the compiler must pass all double values in core register pairs during 197function calls, instead of dedicated floating-point ones. The system can perform all internal 198computations using the FP registers. Doing so speeds up the computations greatly.</p> 199 200<p>Although the requirement to use core register pairs produces a modest performance hit, it ensures 201compatibility with all existing armeabi binaries. If you need the additional 202performance, you can specify your ABI as {@code armeabi-v7a-hard} instead. Doing so 203allows you to use hard floats, while still linking with Android native APIs 204that use {@code softfp}. For more information, refer to the comments in 205{@code $NDK/tests/device/hard-float/jni/android.mk}.</p> 206 207<p class="note"><strong>Note:</strong> You cannot specify {@code APP_ABI} as both 208{@code armeabi-v7a} and {@code armeabi-v7a-hard}. In either case, the build system places the 209shared libraries in the {@code armeabi-v7a/} directory.</p> 210 211<h3 id="hard">armeabi-v7a-hard</h3> 212<p>This variant of the {@code armeabi-v7a} ABI is unique to the NDK. The NDK build 213system adds the following flags in addition to those that it uses for the 214{@code armeabi-v7a} ABI:</p> 215 216<pre class="no-pretty-print"> 217TARGET_CFLAGS += -mhard-float -D_NDK_MATH_NO_SOFTFP=1 218TARGET_LDFLAGS += -Wl,--no-warn-mismatch -lm_hard 219</pre> 220 221<p>The compiler compiles all code with hard-float, and links it with {@code libm_hard.a}. 222This math library is the same one as {@code libm.a}, except that it follows hard-float ABI 223conventions. In the APK, the generated shared libraries reside in {@code /lib/armeabi-v7a/}.</p> 224 225<h3 id="arm64-v8a">arm64-v8a</h3> 226<p>This ABI is for ARMv8-based CPUs that support AArch64. It also includes the NEON and 227VFPv4 instruction sets.</p> 228 229<p>For more information, see the 230<a href="http://www.arm.com/files/downloads/ARMv8_Architecture.pdf">ARMv8 231Technology Preview</a>, and contact ARM for further details.</p> 232 233<h3 id="x86">x86</h3> 234<p>This ABI is for CPUs supporting the instruction set commonly 235referred to as "x86" or "IA-32". Characteristics of this ABI include:</p> 236 237<ul> 238<li>Instructions normally generated by GCC with compiler flags such as the following: 239 240<pre class="no-pretty-print"> 241-march=i686 -mtune=intel -mssse3 -mfpmath=sse -m32 242</pre> 243 244<p>These flags target the the Pentium Pro instruction set, along with the 245the <a href="http://en.wikipedia.org/wiki/MMX_%28instruction_set%29">MMX</a>, 246<a href="http://en.wikipedia.org/wiki/Streaming_SIMD_Extensions">SSE</a>, 247<a href="http://en.wikipedia.org/wiki/SSE2">SSE2</a>, 248<a href="http://en.wikipedia.org/wiki/SSE3">SSE3</a>, and 249<a href="http://en.wikipedia.org/wiki/SSSE3">SSSE3</a> instruction set extensions. 250The generated code is an optimization balanced across the top Intel 32-bit 251CPUs.</p> 252<p> For more information on compiler flags, particularly related to performance optimization, 253refer to <a href="http://software.intel.com/blogs/2012/09/26/gcc-x86-performance-hints">GCC 254x86 performance hints</a>.</p> 255</li> 256<li>Use of the standard Linux x86 32-bit calling convention, as opposed to the one for SVR. For 257more information, see section 6, "Register Usage", of 258<a href="http://www.agner.org/optimize/calling_conventions.pdf">Calling conventions for different 259C++ compilers and operating systems</a>.</li> 260</ul> 261 262<p>The ABI does not include any other optional IA-32 instruction set 263extensions, such as:</p> 264<ul> 265<li>MOVBE</li> 266<li>Any variant of SSE4.</li> 267</ul> 268<p>You can still use these extensions, as long as you use runtime feature-probing to 269enable them, and provide fallbacks for devices that do not support them.</p> 270<p>The NDK toolchain assumes 16-byte stack alignment before a function call. The default tools and 271options enforce this rule. If you are writing assembly code, you must make sure to maintain stack 272alignment, and ensure that other compilers also obey this rule.</p> 273 274<p>Refer to the following documents for more details:</p> 275<ul> 276<li> 277<a href="https://gcc.gnu.org/onlinedocs/gcc-4.9.2/gcc/i386-and-x86-64-Options.html"> 278GCC online documentation: Intel 386 and AMD x86-64 Options</a></li> 279<li><a href="http://www.agner.org/optimize/calling_conventions.pdf">Calling 280conventions for different C++ compilers and operating systems</a></li> 281<li><a 282href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-instruction-set-reference-manual-325383.pdf" 283>Intel IA-32 Intel Architecture Software Developer's Manual, Volume 2: 284Instruction Set Reference</a></li> 285<li><a 286href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-system-programming-manual-325384.pdf">Intel 287IA-32 Intel Architecture Software Developer's Manual, Volume 3: System 288Programming Guide</a></li> 289<li><a href="http://www.sco.com/developers/devspecs/abi386-4.pdf">System V Application Binary 290Interface: Intel386 Processor Architecture Supplement</a></li> 291</ul> 292 293<h3 id="86-64">x86_64</h3> 294<p>This ABI is for CPUs supporting the instruction set commonly referred to as 295"x86-64." It supports instructions that GCC typically generates with the following 296compiler flags:</p> 297<pre class="no-pretty-print"> 298-march=x86-64 -msse4.2 -mpopcnt -m64 -mtune=intel 299</pre> 300 301<p>These flags target the x86-64 instruction set, according to the GCC 302documentation. along with the 303<a href="http://en.wikipedia.org/wiki/MMX_%28instruction_set%29">MMX</a>, 304<a href="http://en.wikipedia.org/wiki/Streaming_SIMD_Extensions">SSE</a>, 305<a href="http://en.wikipedia.org/wiki/SSE2">SSE2</a>, 306<a href="http://en.wikipedia.org/wiki/SSE3">SSE3</a>, 307<a href="http://en.wikipedia.org/wiki/SSSE3">SSSE3</a>, 308<a href="http://en.wikipedia.org/wiki/SSE4#SSE4.1">SSE4.1</a>, 309<a href="http://en.wikipedia.org/wiki/SSE4#SSE4.2">SSE4.2</a>, and 310<a href="https://software.intel.com/en-us/node/512035">POPCNT</a> 311instruction-set extensions. The generated code is an optimization balanced 312across the top Intel 64-bit CPUs.</p> 313 314<p> For more information on compiler flags, particularly related to performance optimization, 315refer to <a href="http://software.intel.com/blogs/2012/09/26/gcc-x86-performance-hints">GCC 316x86 Performance</a>.</p> 317 318<p>This ABI does not include any other optional x86-64 instruction set 319extensions, such as:</p> 320 321<ul> 322<li>MOVBE</li> 323<li>SHA</li> 324<li>AVX</li> 325<li>AVX2</li> 326</ul> 327 328<p>You can still use these extensions, as long as you use runtime feature probing to 329enable them, and provide fallbacks for devices that do not support them.</p> 330<p>Refer to the following documents for more details:</p> 331 332<ul> 333<li><a href="http://www.agner.org/optimize/calling_conventions.pdf">Calling conventions for 334different C++ compilers and operating systems</a></li> 335<li> 336<a href="http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html?iid=tech_vt_tech+64-32_manuals"> 337Intel64 and IA-32 Architectures Software Developer's Manual, Volume 2: Instruction Set 338Reference</a></li> 339<li> 340<a href="http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html?iid=tech_vt_tech+64-32_manuals"> 341Intel64 and IA-32 Intel Architecture Software Developer's Manual Volume 3: System Programming</a> 342</li> 343</ul> 344 345<h3 id="mips">mips</h3> 346<p>This ABI is for MIPS-based CPUs that support at least the MIPS32r1 instruction set. It includes 347the following features:</p> 348 349<ul> 350<li>MIPS32 revision 1 ISA</li> 351<li>Little-endian</li> 352<li>O32</li> 353<li>Hard-float</li> 354<li>No DSP application-specific extensions</li> 355</ul> 356 357<p>For more information, please refer to the following documentation:</p> 358 359<ul> 360<li>Architecture for Programmers ("MIPSARCH")</li> 361<li><a href="https://refspecs.linuxbase.org/elf/gabi4+/contents.html">ELF 362System V Application Binary Interface</a></li> 363<li><a href="http://sourcery.mentor.com/public/cxx-abi/abi.html">Itanium/Generic C++ 364ABI</a></li> 365</ul> 366 367<p>The MIPS-specific documentation is available 368<a href="http://www.imgtec.com/mips/architectures/mips32.asp">here</a>, with 369further information 370<a href="https://sourcery.mentor.com/sgpp/lite/mips/portal/target_arch?@action=faq&target_arch=MIPS">here</a>.</p> 371</li> 372</ul> 373 374<h3 id="mips64">mips64</h3> 375<p>This ABI is for MIPS64 R6. For more information, see 376<a href="http://www.imgtec.com/mips/architectures/mips64.asp">MIPS64 Architecture</a>.</p> 377 378<h2 id="gc">Generating Code for a Specific ABI</h2> 379<p>By default, the NDK generates machine code for the armeabi ABI. You can 380generate ARMv7-a-compatible machine code, instead, by adding the following line 381to your <a href="{@docRoot}ndk/guides/application_mk.html">{@code Application.mk}</a> file.</p> 382<pre class="no-pretty-print"> 383APP_ABI := armeabi-v7a 384</pre> 385 386<p>To build machine code for two or more distinct ABIs, using spaces as delimiters. For 387example:</p> 388 389<pre class="no-pretty-print"> 390APP_ABI := armeabi armeabi-v7a 391</pre> 392 393<p>This setting tells the NDK to build two versions of your machine code: one 394for each ABI listed on this line. For more information on the values you can specify for the 395{@code APP_ABI} variable, see <a href="{@docRoot}ndk/guides/android_mk.html">Android.mk</a>. 396</p> 397 398<p>When you build multiple machine-code versions, the build system copies the libraries to your 399application project path, and ultimately packages them into your APK, so creating 400a <a href="http://en.wikipedia.org/wiki/Fat_binary"><i>fat binary</i></a>. A fat binary 401is larger than one containing only the machine code for a single system; the tradeoff is 402gaining wider compatibility, but at the expense of a larger APK.</p> 403 404<p>At installation time, the package manager unpacks only the most appropriate 405machine code for the target device. For details, see <a href="#aen">Automatic 406extraction of native code at install time</a>.</p> 407 408 409<h2 id="am">ABI Management on the Android Platform</h2> 410<p>This section provides details about how the Android platform manages native 411code in APKs.</p> 412 413<h3>Native code in app packages</h3> 414<p>Both the Play Store and Package Manager expect to find NDK-generated 415libraries on filepaths inside the APK matching the following pattern:</p> 416 417<pre class="no-pretty-print"> 418/lib/<abi>/lib<name>.so 419</pre> 420 421<p>Here, {@code <abi>} is one of the ABI names listed under <a href="#sa">Supported ABIs</a>, 422and {@code <name>} is the name of the library as you defined it for the {@code LOCAL_MODULE} 423variable in the <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file. Since 424APK files are just zip files, it is trivial to open them and confirm that the shared native 425libraries are where they belong.</p> 426 427<p>If the system does not find the native shared libraries where it expects them, it cannot use 428them. In such a case, the app itself has to copy the libraries over, and then 429perform <code>dlopen()</code>.</p> 430 431<p>In a fat binary, each library resides under a directory whose name matches a corresponding ABI. 432For example, a fat binary may contain:</p> 433 434<pre class="no-pretty-print"> 435/lib/armeabi/libfoo.so 436/lib/armeabi-v7a/libfoo.so 437/lib/arm64-v8a/libfoo.so 438/lib/x86/libfoo.so 439/lib/x86_64/libfoo.so 440/lib/mips/libfoo.so 441/lib/mips64/libfoo.so 442</pre> 443 444<p class="note"><strong>Note:</strong> ARMv7-based Android devices running 4.0.3 or earlier 445install native libraries from the {@code armeabi} directory instead of the {@code armeabi-v7a} 446directory if both directories exist. This is because {@code /lib/armeabi/} comes after 447{@code /lib/armeabi-v7a/} in the APK. This issue is fixed from 4.0.4.</p> 448 449<h3>Android Platform ABI support</h3> 450<p>The Android system knows at runtime which ABI(s) it supports, because build-specific system 451properties indicate:</p> 452 453<ul> 454<li>The primary ABI for the device, corresponding to the machine code used in 455the system image itself.</li> 456<li>An optional, secondary ABI, corresponding to another ABI that the system image also supports. 457</li> 458</ul> 459 460<p>This mechanism ensures that the system extracts the best machine code from 461the package at installation time.</p> 462 463<p>For best performance, you should compile directly for the primary ABI. For example, a 464typical ARMv5TE-based device would only define the primary ABI: {@code armeabi}. By contrast, a 465typical, ARMv7-based device would define the primary ABI as {@code armeabi-v7a} and the secondary 466one as {@code armeabi}, since it can run application native binaries generated for each of them.</p> 467 468<p>Many x86-based devices can also run {@code armeabi-v7a} and {@code armeabi} NDK binaries. For 469such devices, the primary ABI would be {@code x86}, and the second one, {@code armeabi-v7a}.</p> 470 471<p>A typical MIPS-based device only defines a primary abi: {@code mips}.</p> 472 473<h3 id="aen">Automatic extraction of native code at install time</h3> 474 475<p>When installing an application, the package manager service scans the APK, and looks for any 476shared libraries of the form:</p> 477 478<pre class="no-pretty-print"> 479lib/<primary-abi>/lib<name>.so 480</pre> 481 482<p>If none is found, and you have defined a secondary ABI, the service scans for shared libraries of 483the form:</p> 484 485<pre class="no-pretty-print"> 486lib/<secondary-abi>/lib<name>.so 487</pre> 488 489<p>When it finds the libraries that it's looking for, the package manager 490copies them to <code>/lib/lib<name>.so</code>, under the application's 491{@code data} directory ({@code data/data/<package_name>/lib/}).</p> 492 493<p>If there is no shared-object file at all, the application builds and installs, but crashes at 494runtime.</p> 495