Merge "Changing x86 and x86_64 ABI docs."

4 files changed, 131 insertions, 5 deletions

diff --git a/docs/text/ANDROID-MK.text b/docs/text/ANDROID-MK.text
index ffe8247d2..cb2168fc1 100644
--- a/docs/text/ANDROID-MK.text
+++ b/docs/text/ANDROID-MK.text
@@ -252,6 +252,9 @@ TARGET_ARCH_ABI
        x86
             For i686
 
+       x86_64
+            For x86-64
+
        mips
             For mips32 (r1)
 
diff --git a/docs/text/APPLICATION-MK.text b/docs/text/APPLICATION-MK.text
index 61c144f5b..367e95e5c 100644
--- a/docs/text/APPLICATION-MK.text
+++ b/docs/text/APPLICATION-MK.text
@@ -171,13 +171,17 @@ APP_ABI
 
               APP_ABI := x86
 
+>    Or to support the Intel64 instruction set, use:
+
+              APP_ABI := x86-64
+
 >    Or to support the MIPS instruction set, use:
 
               APP_ABI := mips
 
 >    Or to support all at the same time, use:
 
-              APP_ABI := armeabi armeabi-v7a x86 mips
+              APP_ABI := armeabi armeabi-v7a x86 mips x86-64
 
 >    Or even better, since NDK r7, you can also use the special value
 >    '`all`' which means "all ABIs supported by this NDK release":
diff --git a/docs/text/CPU-ARCH-ABIS.text b/docs/text/CPU-ARCH-ABIS.text
index 3b7d9a0aa..353e37645 100644
--- a/docs/text/CPU-ARCH-ABIS.text
+++ b/docs/text/CPU-ARCH-ABIS.text
@@ -136,11 +136,12 @@ I.3. 'x86'
   - instructions normally generated by GCC with the following compiler
     flags:
 
-          -march=i686 -mtune=atom -mstackrealign -msse3 -mfpmath=sse -m32
+          -march=i686 -mtune=intel -mstackrealign -mssse3 -mfpmath=sse -m32
 
     which targets Pentium Pro instruction set, according to the GCC
-    documentation, plus the MMX, SSE, SSE2 and SSE3 instruction set
-    extensions. Generated code is optimized for Atom CPU.
+    documentation, plus the MMX, SSE, SSE2, SSE3, SSSE3 instruction set
+    extensions. Generated code is a balanced optimization across top Intel
+    32-bit CPUs.
 
     IMPORTANT NOTE: Flags above are not optimization guide. Compiler
     optimization options which are used by default and/or recommended for
@@ -157,7 +158,6 @@ I.3. 'x86'
   extension, including, but not limited to:
 
   - the MOVBE instruction
-  - the SSSE3 "supplemental SSE3" extension
   - any variant of "SSE4"
 
   You can still use these, as long as you use runtime feature probing to
@@ -215,6 +215,58 @@ I.4. 'mips'
   Note: that MIPS16 support is not provided, nor is micromips.
 
 
+I.5. 'x86-64'
+----------
+
+  This is the name of an ABI for CPUs supporting the instruction set
+  commonly named 'x86-64'. More specifically, this ABI corresponds
+  to the following:
+
+  - instructions normally generated by GCC with the following compiler
+    flags:
+
+          -march=x86-64 -msse4.2 -mpopcnt -m64 -mtune=intel
+
+    which targets x86-64 instruction set, according to the GCC
+    documentation, plus the MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1,
+    SSE4.2 and POPCNT instruction set extensions. Generated code is a balanced
+    optimization across top Intel 64-bit CPUs.
+
+    IMPORTANT NOTE: Flags above are not optimization guide. Compiler
+    optimization options which are used by default and/or recommended for
+    performance boost on x86-64 are not included. For performance
+    optimization hints on x86-64 GCC please refer to the following
+    article:
+
+> http://software.intel.com/blogs/2012/09/26/gcc-x86-performance-hints
+
+  The ABI does *not* include any other optional x86-64 instruction set
+  extension, including, but not limited to:
+
+  - the MOVBE instruction
+  - the SHA instruction
+  - the AVX extension
+  - the AVX2 extension
+
+  You can still use these, as long as you use runtime feature probing to
+  enable them, and provide fallbacks for devices that do not support them.
+
+  Please refer to the following documents for more details:
+
+  * http://gcc.gnu.org/onlinedocs/gcc/i386-and-x86_002d64-Options.html
+
+  * Calling conventions for different C++ compilers and operating systems:
+>    http://www.agner.org/optimize/calling_conventions.pdf
+
+  * Intel64 and IA-32 Intel Architecture Software Developer's Manual
+    volume 2: Instruction Set Reference
+
+  * Intel64 and IA-32 Intel Architecture Software Developer's Manual
+    volume 3: System Programming
+
+  * Amendment to System V Application Binary Interface
+    AMD64 Processor Architecture Supplement
+
 - - - -
 II. Generating code for a specific ABI:
 =======================================
@@ -288,6 +340,7 @@ in the  .apk, for example at:
         lib/armeabi/libfoo.so
         lib/armeabi-v7a/libfoo.so
         lib/x86/libfoo.so
+        lib/x86-64/libfoo.so
         lib/mips/libfoo.so
 
 IMPORTANT NOTE: ARMv7-based Android device running 4.0.3 or before installs native
diff --git a/docs/text/CPU-X86-64.text b/docs/text/CPU-X86-64.text
new file mode 100644
index 000000000..d40522600
--- /dev/null
+++ b/docs/text/CPU-X86-64.text
@@ -0,0 +1,66 @@
+Android NDK x86-64 instruction set support
+===
+
+Introduction:
+-------------
+
+Android NDK r[TBD] added support for the '`x86-64`' ABI, that allows native code to
+run on Android-based devices running on CPUs supporting the x86-64 instruction
+set.
+
+The Android x86-64 ABI itself is fully specified in docs/CPU-ARCH-ABIS.html.
+
+Overview:
+---------
+
+Generating machine code is simple: just add 'x86-64' to your APP_ABI
+definition in your Application.mk file, for example:
+
+        APP_ABI := armeabi armeabi-v7a x86 x86-64
+
+Alternatively, you can use:
+
+        APP_ABI := all
+
+will generate machine code for all supported ABIs with this NDK. Doing so
+will ensure that your application package contains libraries for all target
+ABIs. Note that this has an impact on package size, since each ABI will
+correspond to its own set of native libraries built from the same sources.
+
+The default ABI is still '`armeabi`', if unspecified in your project.
+
+As you would expect, generated libraries will go into `$PROJECT/libs/x86-64/`,
+and will be embedded into your .apk under `/lib/x86-64/`.
+
+And just like other ABIs, the Android package manager will extract these
+libraries on a *compatible* x86-64 based device automatically at install
+time, to put them under <dataPath>/lib, where <dataPath> is the
+application's private data directory.
+
+Similarly, the Google Play server is capable of filtering applications
+based on the native libraries they embed and your device's target CPU.
+
+Debugging with ndk-gdb should work exactly as described under docs/NDK-GDB.html.
+
+Standalone-toolchain:
+---------------------
+
+It is possible to use the x86-64 toolchain with NDK in stand-alone mode.
+See docs/STANDALONE-TOOLCHAIN.html for more details. Briefly speaking,
+it is now possible to run:
+
+      $NDK/build/tools/make-standalone-toolchain.sh --arch=x86_64 --install-dir=<path>
+
+The toolchain binaries have the `x86_64-linux-android- prefix`.
+
+
+Compatibility:
+--------------
+
+The minimal native API level provided by official Android x86-64 platform
+builds is [TBD], which corresponds to all the native APIs provided by
+Android [TBD], i.e. [TBD]-desert.
+
+You won't have to change anything to your project files if you target an older
+API level: the NDK build script will automatically select the right set of
+native platform headers/libraries for you.