1page.title=NEON Support
2@jd:body
3
4<div id="qv-wrapper">
5    <div id="qv">
6      <h2>On this page</h2>
7
8      <ol>
9        <li><a href="#ul">Using {@code LOCAL_ARM_NEON}</a></li>
10        <li><a href="#uns">Using the {@code .neon} Suffix</a></li>
11        <li><a href="#build">Build Requirements</a></li>
12        <li><a href="#rd">Runtime Detection</a></li>
13        <li><a href="#sc">Sample Code</a></li>
14      </ol>
15    </div>
16  </div>
17
18<p>The NDK supports the ARM Advanced SIMD, an optional instruction-set extension of the ARMv7 spec.
19NEON provides a set of scalar/vector instructions and registers (shared with the FPU) comparable to
20MMX/SSE/3DNow! in the x86 world. To function, it requires VFPv3-D32 (32 hardware FPU 64-bit
21registers, instead of the minimum of 16).</p>
22
23<p>The NDK supports the compilation of modules or even specific source files with support for NEON.
24As a result, a specific compiler flag enables the use of GCC ARM NEON intrinsics and VFPv3-D32
25at the same time.</p>
26
27<p>Not all ARMv7-based Android devices support NEON, but devices that do may benefit significantly
28from its support for scalar/vector instructions. For x86 devices, the NDK can also translate NEON
29instructions into SSE, although with several restrictions. For more information, see
30<a href="{@docRoot}ndk/guides/x86.html#an">x86 Support for ARM NEON Intrinsics.</a></p>
31
32<h2 id="ul">Using LOCAL_ARM_NEON</h2>
33<p>To have the NDK build all its source files with NEON support, include the following line in
34your module definition:</p>
35
36<pre class="no-pretty-print">
37LOCAL_ARM_NEON := true
38</pre>
39
40<p>It can be especially useful to build all source files with NEON support if you want to build a
41static or shared library that specifically contains NEON code paths.</p>
42
43<h2 id="uns">Using the .neon Suffix</h2>
44<p>When listing source files for your {@code LOCAL_SRC_FILES} variable, you have the option of
45using the {@code .neon} suffix to indicate that you want to build binaries with NEON support.
46For example, the following example builds one file with {@code .neon} support, and another
47without it:</p>
48
49<pre class="no-pretty-print">
50LOCAL_SRC_FILES := foo.c.neon bar.c
51</pre>
52
53<p>You can combine the {@code .neon} suffix with the {@code .arm} suffix, which specifies the 32-bit
54ARM instruction set for non-NEON instructions. In such a definition, {@code arm} must come before
55{@code neon}. For example: {@code foo.c.arm.neon} works, but {@code foo.c.neon.arm} does not.</p>
56
57<h2 id="build">Build Requirements</h2>
58<p>NEON support only works with the {@code armeabi-v7a} and {@code x86} ABIs. If the NDK build
59scripts encounter other ABIs while attempting to build with NEON support, the NDK build scripts
60exit. x86 provides <a href="x86.html">partial NEON support</a> via translation header. It is
61important to use checks like the following in your <a href="{@docRoot}ndk/guides/android_mk.html">
62{@code Android.mk}</a> file:</p>
63
64<pre class="no-pretty-print">
65# define a static library containing our NEON code
66ifeq ($(TARGET_ARCH_ABI),$(filter $(TARGET_ARCH_ABI), armeabi-v7a x86))
67include $(CLEAR_VARS)
68LOCAL_MODULE    := mylib-neon
69LOCAL_SRC_FILES := mylib-neon.c
70LOCAL_ARM_NEON  := true
71include $(BUILD_STATIC_LIBRARY)
72endif # TARGET_ARCH_ABI == armeabi-v7a || x86
73</pre>
74
75<h2 id="rd">Runtime Detection</h2>
76<p>Your app must perform runtime detection to confirm that NEON-capable machine code can be run on
77the target device. This is because not all ARMv7-based Android devices support NEON. The app can
78perform this check using the
79<a href="{@docRoot}ndk/guides/cpu-features.html">{@code cpufeatures}</a> library that comes with
80this NDK.</p>
81
82<p>You should explicitly check that {@code android_getCpuFamily()} returns {@code
83ANDROID_CPU_FAMILY_ARM}, and that {@code android_getCpuFeatures()} returns a value including the
84{@code ANDROID_CPU_ARM_FEATURE_NEON flag} set. For example: </p>
85
86<pre class="no-pretty-print">
87#include &lt;cpu-features.h&gt;
88...
89...
90if (android_getCpuFamily() == ANDROID_CPU_FAMILY_ARM &amp;&amp;
91    (android_getCpuFeatures() &amp; ANDROID_CPU_ARM_FEATURE_NEON) != 0)
92{
93    // use NEON-optimized routines
94    ...
95}
96else
97{
98    // use non-NEON fallback routines instead
99    ...
100}
101
102...
103</pre>
104
105<h2 id="sc">Sample Code</h2>
106<p>The source code for the NDK's hello-neon sample provides an example of how to use the
107{@code cpufeatures} library and NEON intrinsics at the same time. This sample implements a tiny
108benchmark for a FIR filter loop using a C version, and a NEON-optimized one for devices that
109support it.</p>