1 <html><body><pre>Android Native CPU ABI Management 2 3 4 Introduction: 5 ============= 6 7 Every piece of native code generated with the Android NDK matches a given 8 "Application Binary Interface" (ABI) that defines exactly how your 9 application's machine code is expected to interact with the system at 10 runtime. 11 12 A typical ABI describes things in *excruciating* details, and will typically 13 include the following information: 14 15 - the CPU instruction set that the machine code should use 16 17 - the endianness of memory stores and loads at runtime 18 19 - the format of executable binaries (shared libraries, programs, etc...) 20 and what type of content is allowed/supported in them. 21 22 - various conventions used to pass data between your code and 23 the system (e.g. how registers and/or the stack are used when functions 24 are called, alignment constraints, etc...) 25 26 - alignment and size constraints for enum types, structure fields and 27 arrays. 28 29 - the list of function symbols available to your machine code at runtime, 30 generally from a very specific selected set of libraries. 31 32 This document lists the exact ABIs supported by the Android NDK and the 33 official Android platform releases. 34 35 36 I. Supported ABIs: 37 ================== 38 39 Each supported ABI is identified by a unique name. 40 41 42 I.1. 'armeabi' 43 -------------- 44 45 This is the name of an ABI for ARM-based CPUs that support *at* *least* 46 the ARMv5TE instruction set. Please refer to following documentation for 47 more details: 48 49 - ARM Architecture Reference manual (a.k.a ARMARM) 50 - Procedure Call Standard for the ARM Architecture (a.k.a. AAPCS) 51 - ELF for the ARM Architecture (a.k.a. ARMELF) 52 - ABI for the ARM Architecture (a.k.a. BSABI) 53 - Base Platform ABI for the ARM Architecture (a.k.a. BPABI) 54 - C Library ABI for the ARM Architecture (a.k.a. CLIABI) 55 - C++ ABI for the ARM Architecture (a.k.a. CPPABI) 56 - Runtime ABI for the ARM Architecture (a.k.a. RTABI) 57 58 - ELF System V Application Binary Interface 59 (DRAFT - 24 April 2001) 60 61 - Generic C++ ABI (http://mentorembedded.github.com/cxx-abi/abi.html) 62 63 Note that the AAPCS standard defines 'EABI' as a moniker used to specify 64 a _family_ of similar but distinct ABIs. Android follows the little-endian 65 ARM GNU/Linux ABI as documented in the following document: 66 67 http://sourcery.mentor.com/sgpp/lite/arm/portal/kbattach142/arm_gnu_linux_abi.pdf 68 69 With the exception that wchar_t is only one byte. This should not matter 70 in practice since wchar_t is simply *not* really supported by the Android 71 platform anyway. 72 73 This ABI does *not* support hardware-assisted floating point computations. 74 Instead, all FP operations are performed through software helper functions 75 that come from the compiler's libgcc.a static library. 76 77 Thumb (a.k.a. Thumb-1) instructions are supported. Note that the NDK 78 will generate thumb code by default, unless you define LOCAL_ARM_MODE 79 in your Android.mk (see docs/ANDROID-MK.html for all details). 80 81 82 I.2. 'armeabi-v7a' 83 ------------------ 84 85 This is the name of another ARM-based CPU ABI that *extends* 'armeabi' to 86 include a few CPU instruction set extensions as described in the following 87 document: 88 89 - ARM Architecture v7-a Reference Manual 90 91 The instruction extensions supported by this Android-specific ABI are: 92 93 - The Thumb-2 instruction set extension. 94 - The VFP hardware FPU instructions. 95 96 More specifically, VFPv3-D16 is being used, which corresponds to 16 97 dedicated 64-bit floating point registers provided by the CPU. 98 99 Other extensions described by the v7-a ARM like Advanced SIMD (a.k.a. NEON), 100 VFPv3-D32 or ThumbEE are optional to this ABI, which means that developers 101 should check *at* *runtime* whether the extensions are available and provide 102 alternative code paths if this is not the case. 103 104 (Just like one typically does on x86 systems to check/use MMX/SSE2/etc... 105 specialized instructions). 106 107 You can check docs/CPU-FEATURES.html to see how to perform these runtime 108 checks, and docs/CPU-ARM-NEON.html to learn about the NDK's support for 109 building NEON-capable machine code too. 110 111 IMPORTANT NOTE: This ABI enforces that all double values are passed during 112 function calls in 'core' register pairs, instead of dedicated FP ones. 113 However, all internal computations can be performed with the FP registers 114 and will be greatly sped up. 115 116 This little constraint, while resulting in a slight decrease of 117 performance, ensures binary compatibility with all existing 'armeabi' 118 binaries. 119 120 IMPORTANT NOTE: The 'armeabi-v7a' machine code will *not* run on ARMv5 or 121 ARMv6 based devices. 122 123 124 I.3. 'x86' 125 ---------- 126 127 This is the name of an ABI for CPUs supporting the instruction set 128 commonly named 'x86' or 'IA-32'. More specifically, this ABI corresponds 129 to the following: 130 131 - instructions normally generated by GCC with the following compiler 132 flags: 133 134 -march=i686 -mtune=atom -mstackrealign -msse3 -mfpmath=sse -m32 135 136 which targets Pentium Pro instruction set, according to the GCC 137 documentation, plus the MMX, SSE, SSE2 and SSE3 instruction set 138 extensions. Generated code is optimized for Atom CPU. 139 140 IMPORTANT NOTE: Flags above are not optimization guide. Compiler 141 optimization options which are used by default and/or recommended for 142 performance boost on x86 are not included. For performance optimization 143 hints on x86 GCC please refer to the following article: 144 145 http://software.intel.com/blogs/2012/09/26/gcc-x86-performance-hints 146 147 - using the standard Linux x86 32-bit calling convention (e.g. section 6, 148 "Register Usage" of the "Calling conventions..." document below), not 149 the SVR4 one. 150 151 The ABI does *not* include any other optional IA-32 instruction set 152 extension, including, but not limited to: 153 154 - the MOVBE instruction 155 - the SSSE3 "supplemental SSE3" extension 156 - any variant of "SSE4" 157 158 You can still use these, as long as you use runtime feature probing to 159 enable them, and provide fallbacks for devices that do not support them. 160 161 Please refer to the following documents for more details: 162 163 http://gcc.gnu.org/onlinedocs/gcc/i386-and-x86_002d64-Options.html 164 165 Calling conventions for different C++ compilers and operating systems 166 http://www.agner.org/optimize/calling_conventions.pdf 167 168 Intel IA-32 Intel Architecture Software Developer's Manual 169 volume 2: Instruction Set Reference 170 171 Intel IA-32 Intel Architecture Software Developer's Manual 172 volume 3: System Programming 173 174 Amendment to System V Application Binary Interface 175 Intel386 Processor Architecture Supplement 176 177 178 I.4. 'mips' 179 ----------- 180 181 This is the name of an ABI for MIPS-based CPUs that support *at* *least* 182 the MIPS32r1 instruction set. The ABI includes the following features: 183 184 - MIPS32 revision 1 ISA 185 - Little-Endian 186 - O32 187 - Hard-Float 188 - no DSP application specific extensions 189 190 Please refer to following documentation for more details: 191 192 - ELF for the MIPS Architecture (a.k.a. MIPSELF) 193 - FAQ for MIPS Toolchains (a.k.a. MIPSFAQ) 194 - Toolchain Specifics (a.k.a. MIPSTOOL) 195 - SDE Library (a.k.a. MIPSSDE) 196 - Instruction Set Quick Reference (a.k.a. MIPSISA) 197 - Architecture for Programmers (a.k.a. MIPSARCH) 198 199 - ELF System V Application Binary Interface 200 (DRAFT - 24 April 2001) 201 - Generic C++ ABI (http://sourcery.mentor.com/public/cxx-abi/abi.html) 202 203 The MIPS specific documentation is available at: 204 http://www.mips.com/products/product-materials/processor/mips-architecture/ 205 https://sourcery.mentor.com/sgpp/lite/mips/portal/target_arch?@action=faq&target_arch=MIPS 206 207 Note: This ABI assumes a CPU:FPU clock ratio of 2:1 for maximum 208 compatibility. 209 210 Note: that MIPS16 support is not provided, nor is micromips. 211 212 213 II. Generating code for a specific ABI: 214 ======================================= 215 216 By default, the NDK will generate machine code for the 'armeabi' ABI. 217 You can however add the following line to your Application.mk to generate 218 ARMv7-a compatible machine code instead: 219 220 APP_ABI := armeabi-v7a 221 222 It is also possible to build machine code for *two* distinct ABIs by using: 223 224 APP_ABI := armeabi armeabi-v7a 225 226 This will instruct the NDK to build two versions of your machine code: one for 227 each ABI listed on this line. Both libraries will be copied to your application 228 project path and will be ultimately packaged into your .apk. 229 230 Such a package is called a "fat binary" in Android speak since it contains 231 machine code for more than one CPU architecture. At installation time, the 232 package manager will only unpack the most appropriate machine code for the 233 target device. See below for details. 234 235 236 237 III. ABI Management on the Android platform: 238 ============================================ 239 240 This section provides specific details about how the Android platform manages 241 native code in application packages. 242 243 244 III.1. Native code in Application Packages: 245 ------------------------------------------- 246 247 It is expected that shared libraries generated with the NDK are stored in 248 the final application package (.apk) at locations of the form: 249 250 lib/<abi>/lib<name>.so 251 252 Where <abi> is one of the ABI names listed in section II above, and <name> 253 is a name that can be used when loading the shared library from the VM 254 as in: 255 256 System.loadLibrary("<name>"); 257 258 Since .apk files are just zip files, you can trivially list their content 259 with a command like: 260 261 unzip -l <apk> 262 263 to verify that the native shared libraries you want are indeed at the 264 proper location. You can also place native shared libraries at other 265 locations within the .apk, but they will be ignored by the system, or more 266 precisely by the steps described below; you will need to extract/install 267 them manually in your application. 268 269 In the case of a "fat" binary, up to four distinct libraries can be placed 270 in the .apk, for example at: 271 272 lib/armeabi/libfoo.so 273 lib/armeabi-v7a/libfoo.so 274 lib/x86/libfoo.so 275 lib/mips/libfoo.so 276 277 278 III.2. Android Platform ABI support: 279 ------------------------------------ 280 281 The Android system knows at runtime which ABI(s) it supports. More 282 precisely, up to two build-specific system properties are used to 283 indicate: 284 285 - the 'primary' ABI for the device, corresponding to the machine 286 code used in the system image itself. 287 288 - an optional 'secondary' ABI, corresponding to another ABI that 289 is also supported by the system image. 290 291 For example, a typical ARMv5TE-based device would only define 292 the primary ABI as 'armeabi' and not define a secondary one. 293 294 On the other hand, a typical ARMv7-based device would define the 295 primary ABI to 'armeabi-v7a' and the secondary one to 'armeabi' 296 since it can run application native binaries generated for both 297 of them. 298 299 A typical x86-based device only defines a primary abi named 'x86'. 300 301 A typical MIPS-based device only defines a primary abi named 'mips'. 302 303 III.3. Automatic extraction of native code at install time: 304 ----------------------------------------------------------- 305 306 When installing an application, the package manager service will scan 307 the .apk and look for any shared library of the form: 308 309 lib/<primary-abi>/lib<name>.so 310 311 If one is found, then it is copied under $APPDIR/lib/lib<name>.so, 312 where $APPDIR corresponds to the application's specific data directory. 313 314 If none is found, and a secondary ABI is defined, the service will 315 then scan for shared libraries of the form: 316 317 lib/<secondary-abi>/lib<name>.so 318 319 If anything is found, then it is copied under $APPDIR/lib/lib<name>.so 320 321 This mechanism ensures that the best machine code for the target 322 device is automatically extracted from the package at installation 323 time. 324 </pre></body></html> 325
