From cc049d5a779a6d64ba1dcd29a1ff031ad4891d47 Mon Sep 17 00:00:00 2001 From: David 'Digit' Turner Date: Wed, 18 Nov 2009 18:05:55 -0800 Subject: [PATCH] Add support for armeabi-v7a to the NDK. This patch modifies the NDK build scripts to support the 'armeabi-v7a' ABI. (For the record, it corresponds to Thumb-2 + FPU support, to speed up native code on certain devices like the Droid). To build for this ABI, the Application.mk file should use a line like: APP_ABI := armeabi-v7a It is also possible to build for both 'armeabi' and 'armeabi-v7a' by using: APP_ABI := armeabi armeabi-v7a This will result in the generation of two distinct shared libraries that both will be copied to the final application package. This is dependent on having GCC 4.4.0 prebuilt binaries under build/prebuilt//arm-eabi-4.4.0, since gcc 4.2.1 does not support this new ABI. Note that this also changes the NDK to use gcc 4.4.0 by default, unless the user defines NDK_TOOLCHAIN to 'arm-eabi-4.2.1' in its environment to switch back to the previous one. --- build/core/definitions.mk | 2 +- build/core/main.mk | 26 +++- build/core/setup-abi.mk | 28 ++++ build/core/setup-app.mk | 46 +++--- build/core/setup-toolchain.mk | 14 +- build/toolchains/arm-eabi-4.2.1/config.mk | 2 +- build/toolchains/arm-eabi-4.4.0/config.mk | 19 +++ build/toolchains/arm-eabi-4.4.0/setup.mk | 139 ++++++++++++++++++ docs/ANDROID-MK.TXT | 22 ++- docs/APPLICATION-MK.TXT | 19 +++ docs/CHANGES.TXT | 61 +++++++- docs/CPU-ARCH-ABIS.TXT | 225 ++++++++++++++++++++++++++++++ docs/STABLE-APIS.TXT | 2 +- 13 files changed, 567 insertions(+), 38 deletions(-) create mode 100644 build/core/setup-abi.mk create mode 100644 build/toolchains/arm-eabi-4.4.0/config.mk create mode 100644 build/toolchains/arm-eabi-4.4.0/setup.mk create mode 100644 docs/CPU-ARCH-ABIS.TXT diff --git a/build/core/definitions.mk b/build/core/definitions.mk index 95bab67..ae9b540 100644 --- a/build/core/definitions.mk +++ b/build/core/definitions.mk @@ -262,7 +262,7 @@ NDK_APP_VARS_REQUIRED := APP_MODULES APP_PROJECT_PATH # the list of variables that *may* be defined in Application.mk files NDK_APP_VARS_OPTIONAL := APP_OPTIM APP_CPPFLAGS APP_CFLAGS APP_CXXFLAGS \ - APP_PLATFORM APP_BUILD_SCRIPT + APP_PLATFORM APP_BUILD_SCRIPT APP_ABI # the list of all variables that may appear in an Application.mk file NDK_APP_VARS := $(NDK_APP_VARS_REQUIRED) $(NDK_APP_VARS_OPTIONAL) diff --git a/build/core/main.mk b/build/core/main.mk index 91ffb71..1c3442a 100644 --- a/build/core/main.mk +++ b/build/core/main.mk @@ -83,13 +83,31 @@ $(foreach _config_mk,$(TOOLCHAIN_CONFIGS),\ $(eval include $(BUILD_SYSTEM)/add-toolchain.mk)\ ) -#$(info ALL_TOOLCHAINS=$(ALL_TOOLCHAINS)) -NDK_TARGET_TOOLCHAIN := $(firstword $(NDK_ALL_TOOLCHAINS)) -$(call ndk_log, Default toolchain is $(NDK_TARGET_TOOLCHAIN)) - NDK_ALL_TOOLCHAINS := $(call uniq,$(NDK_ALL_TOOLCHAINS)) NDK_ALL_ABIS := $(call uniq,$(NDK_ALL_ABIS)) +# The default toolchain is now arm-eabi-4.4.0, however its +# C++ compiler is a tad bit more pedantic with certain +# constructs (e.g. templates) so allow users to switch back +# to the old 4.2.1 instead if they really want to. +# +# NOTE: you won't get armeabi-v7a support though ! +# +NDK_TOOLCHAIN := $(strip $(NDK_TOOLCHAIN)) +ifndef NDK_TOOLCHAIN + NDK_TARGET_TOOLCHAIN := arm-eabi-4.4.0 + $(call ndk_log, Default toolchain is $(NDK_TARGET_TOOLCHAIN)) +else + # check that the toolchain name is supported + $(if $(filter-out $(NDK_ALL_TOOLCHAINS),$(NDK_TOOLCHAIN)),\ + $(call __ndk_info,NDK_TOOLCHAIN is defined to the unsupported value $(NDK_TOOLCHAIN)) \ + $(call __ndk_info,Please use one of the following values: $(NDK_ALL_TOOLCHAINS))\ + $(call __ndk_error,Aborting)\ + ,) + NDK_TARGET_TOOLCHAIN=$(NDK_TOOLCHAIN) + $(call ndk_log, Using specific toolchain $(NDK_TARGET_TOOLCHAIN)) +endif + $(call ndk_log, This NDK supports the following toolchains and target ABIs:) $(foreach tc,$(NDK_ALL_TOOLCHAINS),\ $(call ndk_log, $(space)$(space)$(tc): $(NDK_TOOLCHAIN.$(tc).abis))\ diff --git a/build/core/setup-abi.mk b/build/core/setup-abi.mk new file mode 100644 index 0000000..f548823 --- /dev/null +++ b/build/core/setup-abi.mk @@ -0,0 +1,28 @@ +# Copyright (C) 2009 The Android Open Source Project +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +# this file is included multiple times by build/core/setup-app.mk +# + +$(call ndk_log,Building application '$(NDK_APP_NAME)' for ABI '$(TARGET_ARCH_ABI)') + +TARGET_ARCH := arm + +TARGET_OUT := $(NDK_APP_OUT)/$(_app)/$(TARGET_ARCH_ABI) +TARGET_OBJS := $(TARGET_OUT)/objs + +TARGET_GDB_SETUP := $(TARGET_OUT)/setup.gdb + +include $(BUILD_SYSTEM)/setup-toolchain.mk diff --git a/build/core/setup-app.mk b/build/core/setup-app.mk index 8513482..d835e6f 100644 --- a/build/core/setup-app.mk +++ b/build/core/setup-app.mk @@ -21,21 +21,6 @@ $(call assert-defined,_app) _map := NDK_APP.$(_app) -# which platform/abi/toolchain are we going to use? -TARGET_PLATFORM := $(call get,$(_map),APP_PLATFORM) -TARGET_ARCH_ABI := arm -TARGET_ARCH := arm -TARGET_TOOLCHAIN := $(NDK_TARGET_TOOLCHAIN) - -# the location of generated files for this app -HOST_OUT := $(NDK_APP_OUT)/$(_app)/$(HOST_TAG) -HOST_OBJS := $(HOST_OUT)/objs - -TARGET_OUT := $(NDK_APP_OUT)/$(_app)/$(TARGET_ABI) -TARGET_OBJS := $(TARGET_OUT)/objs - -TARGET_GDB_SETUP := $(TARGET_OUT)/setup.gdb - # ok, let's parse all Android.mk source files in order to build # the modules for this app. # @@ -62,4 +47,33 @@ endif ndk-app-$(_app): $(NDK_APP_MODULES) all: ndk-app-$(_app) -include $(BUILD_SYSTEM)/setup-toolchain.mk +# which platform/abi/toolchain are we going to use? +TARGET_PLATFORM := $(call get,$(_map),APP_PLATFORM) + +# the location of generated files for this app +HOST_OUT := $(NDK_APP_OUT)/$(_app)/$(HOST_TAG) +HOST_OBJS := $(HOST_OUT)/objs + +# the target to use +TARGET_TOOLCHAIN := $(NDK_TARGET_TOOLCHAIN) + +APP_ABI := $(strip $(APP_ABI)) +ifndef APP_ABI + # the default ABI for now is armeabi + APP_ABI := armeabi +endif + +# check the target ABIs for this application +_bad_abis = $(strip $(filter-out $(NDK_ALL_ABIS),$(APP_ABI))) +ifneq ($(_bad_abis),) + $(info _bad_abis = '$(_bad_abis)') + $(call __ndk_info,NDK Application '$(_app)' targets unknown ABI(s): $(_bad_abis)) + $(call __ndk_info,Please fix the APP_ABI definition in $(NDK_APP_APPLICATION_MK)) + $(call __ndk_error,Aborting) +endif + +$(foreach _abi,$(APP_ABI),\ + $(eval TARGET_ARCH_ABI := $(_abi))\ + $(eval include $(BUILD_SYSTEM)/setup-abi.mk) \ +) + diff --git a/build/core/setup-toolchain.mk b/build/core/setup-toolchain.mk index 352585e..e5d4e82 100644 --- a/build/core/setup-toolchain.mk +++ b/build/core/setup-toolchain.mk @@ -13,13 +13,21 @@ # limitations under the License. # -# this file is included repeatedly from build/core/main.mk and is used +# this file is included repeatedly from build/core/setup-abi.mk and is used # to setup the target toolchain for a given platform/abi combination. # $(call assert-defined,TARGET_TOOLCHAIN TARGET_PLATFORM TARGET_ARCH TARGET_ARCH_ABI) $(call assert-defined,NDK_APPS) +# Check that the toolchain supports the current ABI +$(if $(filter-out $(NDK_TOOLCHAIN.$(NDK_TARGET_TOOLCHAIN).abis),$(TARGET_ARCH_ABI)),\ + $(call __ndk_info,The $(NDK_TARGET_TOOLCHAIN) toolchain does not support the $(TARGET_ARCH_ABI) ABI.)\ + $(call __ndk_info,Please modify the APP_ABI definition in $(NDK_APP_APPLICATION_MK) to fix this)\ + $(call __ndk_info,Valid ABIs values for $(NDK_TARGET_TOOLCHAIN) are: $(NDK_TARGET_TOOLCHAIN.$(NDK_TOOLCHAIN).abis))\ + $(call __ndk_error,Aborting)\ +,) + TARGET_ABI := $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI) # setup sysroot-related variables. The SYSROOT point to a directory @@ -27,7 +35,7 @@ TARGET_ABI := $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI) # some libraries and object files used for linking the generated # target files properly. # -SYSROOT := build/platforms/$(TARGET_PLATFORM)/arch-$(TARGET_ARCH_ABI) +SYSROOT := build/platforms/$(TARGET_PLATFORM)/arch-$(TARGET_ARCH) TARGET_CRTBEGIN_STATIC_O := $(SYSROOT)/usr/lib/crtbegin_static.o TARGET_CRTBEGIN_DYNAMIC_O := $(SYSROOT)/usr/lib/crtbegin_dynamic.o @@ -40,7 +48,7 @@ TARGET_PREBUILT_SHARED_LIBRARIES := $(TARGET_PREBUILT_SHARED_LIBRARIES:%=$(SYSRO include $(NDK_TOOLCHAIN.$(TARGET_TOOLCHAIN).setup) # compute NDK_APP_DEST as the destination directory for the generated files -NDK_APP_DEST := $(NDK_APP_PROJECT_PATH)/libs/$(TARGET_ABI_SUBDIR) +NDK_APP_DEST := $(NDK_APP_PROJECT_PATH)/libs/$(TARGET_ARCH_ABI) # free the dictionary of LOCAL_MODULE definitions $(call modules-clear) diff --git a/build/toolchains/arm-eabi-4.2.1/config.mk b/build/toolchains/arm-eabi-4.2.1/config.mk index 1b5cf02..c6297c2 100644 --- a/build/toolchains/arm-eabi-4.2.1/config.mk +++ b/build/toolchains/arm-eabi-4.2.1/config.mk @@ -16,4 +16,4 @@ # config file for the arm-eabi-4.2.1 toolchain for the Android NDK # the real meat is in the setup.mk file adjacent to this one # -TOOLCHAIN_ABIS := arm +TOOLCHAIN_ABIS := armeabi diff --git a/build/toolchains/arm-eabi-4.4.0/config.mk b/build/toolchains/arm-eabi-4.4.0/config.mk new file mode 100644 index 0000000..43a28fa --- /dev/null +++ b/build/toolchains/arm-eabi-4.4.0/config.mk @@ -0,0 +1,19 @@ +# Copyright (C) 2009 The Android Open Source Project +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +# config file for the arm-eabi-4.4.0 toolchain for the Android NDK +# the real meat is in the setup.mk file adjacent to this one +# +TOOLCHAIN_ABIS := armeabi armeabi-v7a diff --git a/build/toolchains/arm-eabi-4.4.0/setup.mk b/build/toolchains/arm-eabi-4.4.0/setup.mk new file mode 100644 index 0000000..cbdeed5 --- /dev/null +++ b/build/toolchains/arm-eabi-4.4.0/setup.mk @@ -0,0 +1,139 @@ +# Copyright (C) 2009 The Android Open Source Project +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +# this file is used to prepare the NDK to build with the arm-eabi-4.4.0 +# toolchain any number of source files +# +# its purpose is to define (or re-define) templates used to build +# various sources into target object files, libraries or executables. +# +# Note that this file may end up being parsed several times in future +# revisions of the NDK. +# + +TOOLCHAIN_NAME := arm-eabi-4.4.0 +TOOLCHAIN_PREFIX := $(HOST_PREBUILT)/$(TOOLCHAIN_NAME)/bin/arm-eabi- + +TARGET_CFLAGS.common := \ + -I$(SYSROOT)/usr/include \ + -fpic \ + -mthumb-interwork \ + -ffunction-sections \ + -funwind-tables \ + -fstack-protector \ + -fno-short-enums \ + -D__ARM_ARCH_5__ -D__ARM_ARCH_5T__ \ + -D__ARM_ARCH_5E__ -D__ARM_ARCH_5TE__ \ + +ifeq ($(TARGET_ARCH_ABI),armeabi-v7a) + TARGET_ARCH_CFLAGS := -march=armv7-a \ + -mfloat-abi=softfp \ + -mfpu=neon + TARGET_ARCH_LDFLAGS := -Wl,--fix-cortex-a8 +else + TARGET_ARCH_CFLAGS := -march=armv5te \ + -mtune=xscale \ + -msoft-float + TARGET_ARCH_LDFLAGS := +endif + +TARGET_arm_release_CFLAGS := -O2 \ + -fomit-frame-pointer \ + -fstrict-aliasing \ + -funswitch-loops \ + -finline-limit=300 + +TARGET_thumb_release_CFLAGS := -mthumb \ + -Os \ + -fomit-frame-pointer \ + -fno-strict-aliasing \ + -finline-limit=64 + +# When building for debug, compile everything as arm. +TARGET_arm_debug_CFLAGS := $(TARGET_arm_release_CFLAGS) \ + -fno-omit-frame-pointer \ + -fno-strict-aliasing + +TARGET_thumb_debug_CFLAGS := $(TARGET_thumb_release_CFLAGS) \ + -marm \ + -fno-omit-frame-pointer + +TARGET_CC := $(TOOLCHAIN_PREFIX)gcc +TARGET_CFLAGS := $(TARGET_CFLAGS.common) $(TARGET_ARCH_CFLAGS) + + +TARGET_CXX := $(TOOLCHAIN_PREFIX)g++ +TARGET_CXXFLAGS := $(TARGET_CFLAGS.common) $(TARGET_ARCH_CFLAGS) -fno-exceptions -fno-rtti + +TARGET_LD := $(TOOLCHAIN_PREFIX)ld +TARGET_LDFLAGS := $(TARGET_ARCH_LDFLAGS) + +TARGET_AR := $(TOOLCHAIN_PREFIX)ar +TARGET_ARFLAGS := crs + +TARGET_LIBGCC := $(shell $(TARGET_CC) -mthumb-interwork -print-libgcc-file-name) +TARGET_LDLIBS := -Wl,-rpath-link=$(SYSROOT)/usr/lib + +# These flags are used to ensure that a binary doesn't reference undefined +# flags. +TARGET_NO_UNDEFINED_LDFLAGS := -Wl,--no-undefined + +# NOTE: Ensure that TARGET_LIBGCC is placed after all private objects +# and static libraries, but before any other library in the link +# command line when generating shared libraries and executables. +# +# This ensures that all libgcc.a functions required by the target +# will be included into it, instead of relying on what's available +# on other libraries like libc.so, which may change between system +# releases due to toolchain or library changes. +# +define cmd-build-shared-library +$(TARGET_CC) \ + -nostdlib -Wl,-soname,$(notdir $@) \ + -Wl,-shared,-Bsymbolic \ + $(PRIVATE_OBJECTS) \ + -Wl,--whole-archive \ + $(PRIVATE_WHOLE_STATIC_LIBRARIES) \ + -Wl,--no-whole-archive \ + $(PRIVATE_STATIC_LIBRARIES) \ + $(TARGET_LIBGCC) \ + $(PRIVATE_SHARED_LIBRARIES) \ + $(PRIVATE_LDFLAGS) \ + $(PRIVATE_LDLIBS) \ + -o $@ +endef + +define cmd-build-executable +$(TARGET_CC) \ + -nostdlib -Bdynamic \ + -Wl,-dynamic-linker,/system/bin/linker \ + -Wl,--gc-sections \ + -Wl,-z,nocopyreloc \ + $(TARGET_CRTBEGIN_DYNAMIC_O) \ + $(PRIVATE_OBJECTS) \ + $(PRIVATE_STATIC_LIBRARIES) \ + $(TARGET_LIBGCC) \ + $(PRIVATE_SHARED_LIBRARIES) \ + $(PRIVATE_LDFLAGS) \ + $(PRIVATE_LDLIBS) \ + $(TARGET_CRTEND_O) \ + -o $@ +endef + +define cmd-build-static-library +$(TARGET_AR) $(TARGET_ARFLAGS) $@ $(PRIVATE_OBJECTS) +endef + +cmd-strip = $(TOOLCHAIN_PREFIX)strip --strip-debug $1 diff --git a/docs/ANDROID-MK.TXT b/docs/ANDROID-MK.TXT index babcd95..622806a 100644 --- a/docs/ANDROID-MK.TXT +++ b/docs/ANDROID-MK.TXT @@ -209,14 +209,25 @@ TARGET_ARCH TARGET_PLATFORM Name of the target Android platform when this Android.mk is parsed. - For now, only 'android-3' is supported, which corresponds to the - Android 1.5 platform. + For example, 'android-3' correspond to Android 1.5 system images. For + a complete list of platform names and corresponding Android system + images, read docs/STABLE-APIS.TXT. TARGET_ARCH_ABI Name of the target CPU+ABI when this Android.mk is parsed. - For now, only 'arm' is supported, which really means the following: + Two values are supported at the moment: - ARMv5TE or higher CPU, with 'softfloat' floating point support + armeabi + For Armv5TE + + armeabi-v7a + + NOTE: Up to Android NDK 1.6_r1, this variable was simply defined + as 'arm'. However, the value has been redefined to better + match what is used internally by the Android platform. + + For more details about architecture ABIs and corresponding + compatibility issues, please read docs/CPU-ARCH-ABIS.TXT Other target ABIs will be introduced in future releases of the NDK and will have a different name. Note that all ARM-based ABIs will @@ -228,8 +239,9 @@ TARGET_ABI as $(TARGET_PLATFORM)-$(TARGET_ARCH_ABI) and is useful when you want to test against a specific target system image for a real device. - By default, this will be 'android-3-arm' + By default, this will be 'android-3-armeabi' + (Up to Android NDK 1.6_r1, this used to be 'android-3-arm' by default) NDK-provided function macros: - - - - - - - - - - - - - - - diff --git a/docs/APPLICATION-MK.TXT b/docs/APPLICATION-MK.TXT index b790ac6..0a11cca 100644 --- a/docs/APPLICATION-MK.TXT +++ b/docs/APPLICATION-MK.TXT @@ -114,6 +114,25 @@ APP_BUILD_SCRIPT to point to an alternate build script. A non-absolute path will always be interpreated as relative to the NDK's top-level directory. +APP_ABI + By default, the NDK build system will generate machine code for the + 'armeabi' ABI. This corresponds to an ARMv5TE based CPU with software + floating point operations. You can use APP_ABI to select a different + ABI. + + For example, to support hardware FPU instructions on ARMv7 based devices, + use: + + APP_ABI := armeabi-v7a + + Or to support both ARMv5TE and ARMv7 based devices, use: + + APP_ABI := armeabi armeabi-v7a + + For the list of all supported ABIs and details about their usage / limitations + please read docs/CPU-ARCH-ABIS.TXT + + A trivial Application.mk file would be: -------------- cut here ------------------------- diff --git a/docs/CHANGES.TXT b/docs/CHANGES.TXT index c162886..656b1b4 100644 --- a/docs/CHANGES.TXT +++ b/docs/CHANGES.TXT @@ -7,24 +7,60 @@ IMPORTANT BUG FIXES: - Fix build/host-setup.sh to execute as a Bourne shell script (again) -- Make target shared libraries portable to systems that don't use the exact same - toolchain (GCC 4.2.1) . - -- Actually use the awk version detected by host-setup.sh during the build. +- Make target shared libraries portable to systems that don't use the exact + same toolchain. This is needed due to differences in libgcc.a implementations + between gcc 4.2.1 and 4.4.0. This change ensures that generated machine + code doesn't depend on helper functions provided by the Android platform + runtime. IMPORTANT CHANGES: -- Added platform eclair-5 to reflect the Eclair branch. This is merely a copy +- Support for hardware FPU. This is through the new 'armeabi-v7a' ABI + corresponding to ARMv7-a class devices. + + Note that by default, the NDK will still generate machine code for the old + 'armeabi' ABI (ARMv5TE based) which is supported by all official Android + system images to date. + + You will need to define APP_ABI in your Application.mk file to change this. + See docs/APPLICATION-MK.TXT + + More details about ABIs is now available in docs/CPU-ARCH-ABIS.TXT + +- GCC 4.4.0 is now used by default by the NDK. It generates better code than + GCC 4.2.1, which was used in previous releases. However, the compiler's C++ + frontend is also a lot more pedantic regarding certain template constructs + and will even refuse to build some of them. + + For this reason, the NDK also comes with GCC 4.2.1 prebuilt binaries, and + you can force its usage by defining NDK_TOOLCHAIN in your environment to + the value 'arm-eabi-4.2.1'. For example: + + export NDK_TOOLCHAIN=arm-eabi-4.2.1 + make APP=hello-jni + + Note that only the 'armeabi' ABI is supported by the 4.2.1 toolchain. We + recommend switching to 4.2.1 *only* if you encounter compilation problems + with 4.4.0. + + The 4.2.1 prebuilt binaries will probably be removed from a future release + of the Android NDK, we thus *strongly* invite you to fix your code if such + problems happen. + +- Support for OpenGL ES 2.0. This is through the new 'android-5' platform to + reflect Android 2.0 (previously the Eclair branch). This is merely a copy of android-4 that also includes headers and libraries for OpenGL ES 2.0. See the sample named "hello-gl2" for a *very* basic demonstration. Note that - OpenGL ES 2.0 is currently *not* available from Java, and must be used through - native code exclusively. + OpenGL ES 2.0 is currently *not* available from Java, and must be used + through native code exclusively. OTHER FIXES & CHANGES: +- Actually use the awk version detected by host-setup.sh during the build. + - Added --prebuilt-ndk=FILE option to build/tools/make-release.sh script to package a new experimental NDK package archive from the current source tree plus the toolchain binaries of an existing NDK release package. E.g.: @@ -58,6 +94,17 @@ OTHER FIXES & CHANGES: st_ctimensec) to - add missing declaration for tzset() in +- Added build/tools/download-toolchain-sources.sh, a script that allows you + to download the toolchain sources from the official open-source repository + at android.git.kernel.org and nicely package them into a tarball that can + later be used by build/tools/build-toolchain.sh to rebuild the prebuilt + binaries for your system. + +- Updated build/tools/build-toolchain.sh to support the tarballs generated + by download-toolchain-sources.sh with the --package= option. This + also builds both gcc 4.2.1 and 4.4.0, adding support for armeabi-v7a to + gcc 4.4.0. + ------------------------------------------------------------------------------- android-ndk-1.6_r1 diff --git a/docs/CPU-ARCH-ABIS.TXT b/docs/CPU-ARCH-ABIS.TXT new file mode 100644 index 0000000..d142db4 --- /dev/null +++ b/docs/CPU-ARCH-ABIS.TXT @@ -0,0 +1,225 @@ +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: +================== + +Each supported ABI is identified by a unique name. + + + 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). + + + I.2. 'armeabi-v7a' + ------------------ + + This is the name of another ARM-based CPU ABI that *extends* 'armeabi' to + include a few CPU instruction set extensions as described in the following + document: + + - ARM Architecture v7-a Reference Manual + + The instruction extensions supported by this Android-specific ABI are: + + - The Thumb-2 instruction set extension. + - The VFP hardware FPU instructions. + + More specifically, VFPv3-D32 is being used, which corresponds to 32 + dedicated 64-bit floating point registers provided by the CPU. + + Other extensions described by the v7-a ARM like Advanced SIMD (a.k.a. NEON) + or ThumbEE are optional to this ABI, which means that developers should + check *at* *runtime* whether the extensions are available and provide + alternative code paths if this is not the case. + + (Just like one typically does on x86 systems to check/use MMX/SSE2/etc... + specialized instructions). + + IMPORTANT NOTE: This ABI enforces that all double values are passed during + function calls in 'core' register pairs, instead of dedicated FP ones. + However, all internal computations can be performed with the FP registers + and will be greatly sped up. + + This little constraint, while resulting in a slight decrease of + performance, ensures binary compatibility with all existing 'armeabi' + binaries. + + IMPORTANT NOTE: The 'armeabi-v7a' machine code will *not* run on ARMv5 or + ARMv6 based devices. + + +II. Generating code for a specific ABI: +======================================= + +By default, the NDK will generate machine code for the 'armeabi' ABI. +You can however add the following line to your Application.mk to generate +ARMv7-a compatible machine code instead: + + APP_ABI := armeabi-v7a + +It is also possible to build machine code for *two* distinct ABIs by using: + + APP_ABI := armeabi armeabi-v7a + +This will instruct the NDK to build two versions of your machine code: one for +each ABI listed on this line. Both libraries will be copied to your application +project path and will be ultimately packaged into your .apk. + +Such a package is called a "fat binary" in Android speak since it contains +machine code for more than one CPU architecture. At installation time, the +package manager will only unpack the most appropriate machine code for the +target device. See below for 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//lib.so + + Where is one of the ABI names listed in section II above, and + is a name that can be used when loading the shared library from the VM + as in: + + System.loadLibrary(""); + + Since .apk files are just zip files, you can trivially list their content + with a command like: + + unzip -l + + 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. + + In the case of a "fat" binary, two distinct libraries are thus placed in + the .apk, for example at: + + lib/armeabi/libfoo.so + lib/armeabi-v7a/libfoo.so + + + III.2. Android Platform ABI support: + ------------------------------------ + + The Android system knows at runtime which ABI(s) it supports. More + precisely, up to two build-specific system properties are used to + indicate: + + - the 'primary' ABI for the device, corresponding to the machine + code used in the system image itself. + + - an optional 'secondary' ABI, corresponding to another ABI that + is also supported by the system image. + + For example, a typical ARMv5TE-based device would only define + the primary ABI as 'armeabi' and not define a secondary one. + + On the other hand, a typical ARMv7-based device would define the + primary ABI to 'armeabi-v7a' and the secondary one to 'armeabi' + since it can run application native binaries generated for both + of them. + + + 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//lib.so + + If one is found, then it is copied under $APPDIR/lib/lib.so, + where $APPDIR corresponds to the application's specific data directory. + + If none is found, and a secondary ABI is defined, the service will + then scan for shared libraries of the form: + + lib//lib.so + + If anything is found, then it is copied under $APPDIR/lib/lib.so + + This mechanism ensures that the best machine code for the target + device is automatically extracted from the package at installation + time. diff --git a/docs/STABLE-APIS.TXT b/docs/STABLE-APIS.TXT index 7d5d175..700bb88 100644 --- a/docs/STABLE-APIS.TXT +++ b/docs/STABLE-APIS.TXT @@ -27,7 +27,7 @@ currently supported: android-3 -> Official Android 1.5 system images android-4 -> Official Android 1.6 system images - android-5 -> Experimental Eclair system images + android-5 -> Official Android 2.0 system images II. Android-3 Stable Native APIs: --------------------------------- -- 2.11.0