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