Android Native CPU ABI Management


Introduction:
=============

Every piece of native code generated with the Android NDK matches a given
"Application Binary Interface" (ABI) that defines exactly how your
application's machine code is expected to interact with the system at
runtime.

A typical ABI describes things in *excruciating* details, and will typically
include the following information:

  - the CPU instruction set that the machine code should use

  - the endianess of memory stores and loads at runtime

  - the format of executable binaries (shared libraries, programs, etc...)
    and what type of content is allowed/supported in them.

  - various conventions used to pass data between your code and
    the system (e.g. how registers and/or the stack are used when functions
    are called, alignment constraints, etc...)

  - alignment and size constraints for enum types, structure fields and
    arrays.

  - the list of function symbols available to your machine code at runtime,
    generally from a very specific selected set of libraries.

This document lists the exact ABIs supported by the Android NDK and the
official Android platform releases.


I. Supported ABIs:
==================

Only one ABI is supported at the moment:

 I.1. 'armeabi'
 --------------

  This is the name of an ABI for ARM-based CPUs that support *at* *least*
  the ARMv5TE instruction set. Please refer to following documentation for
  more details:

   - ARM Architecture Reference manual                (a.k.a  ARMARM)
   - Procedure Call Standard for the ARM Architecture (a.k.a. AAPCS)
   - ELF for the ARM Architecture                     (a.k.a. ARMELF)
   - ABI for the ARM Architecture                     (a.k.a. BSABI)
   - Base Platform ABI for the ARM Architecture       (a.k.a. BPABI)
   - C Library ABI for the ARM Architecture           (a.k.a. CLIABI)
   - C++ ABI for the ARM Architecture                 (a.k.a. CPPABI)
   - Runtime ABI for the ARM Architecture             (a.k.a. RTABI)

   - ELF System V Application Binary Interface
     (DRAFT - 24 April 2001)

   - Generic C++ ABI  (http://www.codesourcery.com/public/cxx-abi/abi.html)

  Note that the AAPCS standard defines 'EABI' as a moniker used to specify
  a _family_ of similar but distinct ABIs. Android follows the little-endian
  ARM GNU/Linux ABI as documented in the following document:

      http://www.codesourcery.com/gnu_toolchains/arm/arm_gnu_linux_abi.pdf

  With the exception that wchar_t is only one byte. This should not matter
  in practice since wchar_t is simply *not* really supported by the Android
  platform anyway.

  This ABI does *not* support hardware-assisted floating point computations.
  Instead, all FP operations are performed through software helper functions
  that come from the compiler's libgcc.a static library.

  Thumb (a.k.a. Thumb-1) instructions are supported. Note that the NDK
  will generate thumb code by default, unless you define LOCAL_ARM_MODE
  in your Android.mk (see docs/ANDROID-MK.TXT for all details).


III. ABI Management on the Android platform:
============================================

This section provides specific details about how the Android platform manages
native code in application packages.


  III.1. Native code in Application Packages:
  -------------------------------------------

    It is expected that shared libraries generated with the NDK are stored in
    the final application package (.apk) at locations of the form:

       lib/<abi>/lib<name>.so

    Where <abi> is one of the ABI names listed in section II above, and <name>
    is a name that can be used when loading the shared library from the VM
    as in:

        System.loadLibrary("<name>");

    Since .apk files are just zip files, you can trivially list their content
    with a command like:

        unzip -l <apk>

    to verify that the native shared libraries you want are indeed at the
    proper location. You can also place native shared libraries at other
    locations within the .apk, but they will be ignored by the system, or more
    precisely by the steps described below; you will need to extract/install
    them manually in your application.


  III.2. Android Platform ABI support:
  ------------------------------------

    The Android system knows at runtime which ABI it supports. More
    precisely, one build-specific system properties is used:

        ro.product.cpu.abi

    It it set to "armeabi" for the ARMv5TE of the same name.


  III.3. Automatic extraction of native code at install time:
  -----------------------------------------------------------

    When installing an application, the package manager service will scan
    the .apk and look for any shared library of the form:

         lib/<abi>/lib<name>.so

    If one is found, then it is copied under $APPDIR/lib/lib<name>.so,
    where $APPDIR corresponds to the application's specific data directory.
