ndk/docs/CPU-ARCH-ABIS.html

   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://www.codesourcery.com/public/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://www.codesourcery.com/gnu_toolchains/arm/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 targets the
 129   instruction set commonly referenced as 'i686' or 'Pentium Pro' in
 130   documents such as:
 131
 132     Intel IA-32 Intel Architecture Software Developer's Manual
 133       volume 2: Instruction Set Reference
 134
 135
 136   IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT:
 137
 138       THE 'x86' ABI IS AN EXPERIMENTAL FEATURE THAT IS NOT FULLY
 139       SUPPORTED YET BY THIS NDK RELEASE. TRYING TO USE IT WILL RESULT
 140       IN AN ERROR DURING THE BUILD PROCESS.
 141
 142   Note that optional features like MMX/SSE2/SSE3/3DNow!/KVM must be
 143   explicitly tested at runtime by the generated machine code and
 144   cannot be assumed to be everywhere.
 145
 146
 147 II. Generating code for a specific ABI:
 148 =======================================
 149
 150 By default, the NDK will generate machine code for the 'armeabi' ABI.
 151 You can however add the following line to your Application.mk to generate
 152 ARMv7-a compatible machine code instead:
 153
 154    APP_ABI := armeabi-v7a
 155
 156 It is also possible to build machine code for *two* distinct ABIs by using:
 157
 158    APP_ABI := armeabi armeabi-v7a
 159
 160 This will instruct the NDK to build two versions of your machine code: one for
 161 each ABI listed on this line. Both libraries will be copied to your application
 162 project path and will be ultimately packaged into your .apk.
 163
 164 Such a package is called a "fat binary" in Android speak since it contains
 165 machine code for more than one CPU architecture. At installation time, the
 166 package manager will only unpack the most appropriate machine code for the
 167 target device. See below for details.
 168
 169
 170
 171 III. ABI Management on the Android platform:
 172 ============================================
 173
 174 This section provides specific details about how the Android platform manages
 175 native code in application packages.
 176
 177
 178   III.1. Native code in Application Packages:
 179   -------------------------------------------
 180
 181     It is expected that shared libraries generated with the NDK are stored in
 182     the final application package (.apk) at locations of the form:
 183
 184        lib/&lt;abi&gt;/lib&lt;name&gt;.so
 185
 186     Where &lt;abi&gt; is one of the ABI names listed in section II above, and &lt;name&gt;
 187     is a name that can be used when loading the shared library from the VM
 188     as in:
 189
 190         System.loadLibrary("&lt;name&gt;");
 191
 192     Since .apk files are just zip files, you can trivially list their content
 193     with a command like:
 194
 195         unzip -l &lt;apk&gt;
 196
 197     to verify that the native shared libraries you want are indeed at the
 198     proper location. You can also place native shared libraries at other
 199     locations within the .apk, but they will be ignored by the system, or more
 200     precisely by the steps described below; you will need to extract/install
 201     them manually in your application.
 202
 203     In the case of a "fat" binary, two distinct libraries are thus placed in
 204     the  .apk, for example at:
 205
 206         lib/armeabi/libfoo.so
 207         lib/armeabi-v7a/libfoo.so
 208
 209
 210   III.2. Android Platform ABI support:
 211   ------------------------------------
 212
 213     The Android system knows at runtime which ABI(s) it supports. More
 214     precisely, up to two build-specific system properties are used to
 215     indicate:
 216
 217     - the 'primary' ABI for the device, corresponding to the machine
 218       code used in the system image itself.
 219
 220     - an optional 'secondary' ABI, corresponding to another ABI that
 221       is also supported by the system image.
 222
 223     For example, a typical ARMv5TE-based device would only define
 224     the primary ABI as 'armeabi' and not define a secondary one.
 225
 226     On the other hand, a typical ARMv7-based device would define the
 227     primary ABI to 'armeabi-v7a' and the secondary one to 'armeabi'
 228     since it can run application native binaries generated for both
 229     of them.
 230
 231
 232   III.3. Automatic extraction of native code at install time:
 233   -----------------------------------------------------------
 234
 235     When installing an application, the package manager service will scan
 236     the .apk and look for any shared library of the form:
 237
 238          lib/&lt;primary-abi&gt;/lib&lt;name&gt;.so
 239
 240     If one is found, then it is copied under $APPDIR/lib/lib&lt;name&gt;.so,
 241     where $APPDIR corresponds to the application's specific data directory.
 242
 243     If none is found, and a secondary ABI is defined, the service will
 244     then scan for shared libraries of the form:
 245
 246         lib/&lt;secondary-abi&gt;/lib&lt;name&gt;.so
 247
 248     If anything is found, then it is copied under $APPDIR/lib/lib&lt;name&gt;.so
 249
 250     This mechanism ensures that the best machine code for the target
 251     device is automatically extracted from the package at installation
 252     time.
 253 </pre></body></html>