<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer's Guide: CPU Features</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">NDK Programmer's Guide
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_3__key__topics__c_p_u__support__c_p_u-_f_e_a_t_u_r_e_s.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">CPU Features </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This NDK provides a small library named "`cpufeatures`" that can be used at runtime to detect the target device's CPU family and the optional features it supports.</p>
<h2>Usage</h2>
<p>The library is available as an import module. To use it, you must:</p>
<ul>
<li>List '<code>cpufeatures</code>' in your list of static library dependencies, as in: <pre class="fragment">LOCAL_STATIC_LIBRARIES := cpufeatures
</pre></li>
<li>At the end of your Android.mk, import the '<code>android/cpufeatures</code>' module, as in: <pre class="fragment">$(call import-module,android/cpufeatures)
</pre></li>
<li>In your source code, include the header named <code><cpu-features.h></code></li>
</ul>
<p>Here is a simple example: </p>
<pre class="fragment"> <project-path>/jni/Android.mk:
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := <your-module-name>
LOCAL_SRC_FILES := <your-source-files>
LOCAL_STATIC_LIBRARIES := cpufeatures
include $(BUILD_SHARED_LIBRARY)
$(call import-module,android/cpufeatures)
</pre><h2>Features</h2>
<p>Two functions are provided for now: </p>
<pre class="fragment"> AndroidCpuFamily android_getCpuFamily();
</pre><p>Returns a value matching the CPU family/architecture supported by the current process as an enum. Currently, the following families are defined:</p>
<ul>
<li><code>ANDROID_CPU_FAMILY_ARM</code></li>
<li><code>ANDROID_CPU_FAMILY_X86</code></li>
<li><code>ANDROID_CPU_FAMILY_MIPS</code></li>
<li><code>ANDROID_CPU_FAMILY_ARM64</code></li>
<li><code>ANDROID_CPU_FAMILY_X86_64</code></li>
<li><code>ANDROID_CPU_FAMILY_MIPS64</code></li>
</ul>
<p>Note that when running a 32-bit executable on a 64-bit system, this function will return the 32-bit family value only.</p>
<p>Secondly:</p>
<pre class="fragment"> uint64_t android_getCpuFeatures();
</pre><p>Returns the set of optional features supported by the device's CPU. The result is a set of bit-flags, each corresponding to one CPU Family-specific optional feature.</p>
<p>Currently, only the following flags are defined, for the 32-bit ARM CPU Family:</p>
<ul>
<li><code>ANDROID_CPU_ARM_FEATURE_VFPv2</code><br/>
Indicates that the device's CPU supports VFPv2 instruction set. Most ARMv6 CPUs support these.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_ARMv7</code><br/>
Indicates that the device's CPU supports the ARMv7-A instruction set as supported by the "armeabi-v7a" abi (see CPU-ARCH-ABIS.html). This corresponds to Thumb-2 and VFPv3-D16 instructions.</li>
<li><p class="startli"><code>ANDROID_CPU_ARM_FEATURE_VFPv3</code><br/>
Indicates that the device's CPU supports the VFPv3 hardware FPU instruction set extension. Due to the definition of 'armeabi-v7a', this will always be the case if ANDROID_CPU_ARM_FEATURE_ARMv7 is returned.</p>
<p class="startli">Note that this corresponds to the minimum profile VFPv3-D16 that <em>only</em> provides 16 hardware double-precision FP registers.</p>
</li>
<li><code>ANDROID_CPU_ARM_FEATURE_VFP_D32</code><br/>
Indicates that the device's CPU supports 32 hardware double-precision FP registers instead of 16. Note that there are still only 32 single- precision registers mapped to the same register banks.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_NEON</code><br/>
Indicates that the device's CPU supports the ARM Advanced SIMD (a.k.a. NEON) vector instruction set extension. Note that ARM mandates that such CPUs also implement VFPv3-D32, which provides 32 hardware FP registers (shared with the NEON unit).</li>
<li><code>ANDROID_CPU_ARM_FEATURE_VFP_FP16</code><br/>
Indicates that the device's CPU supports instructions to perform floating-point operations on 16-bit registers. This is part of the VFPv4 specification.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_VFP_FMA</code><br/>
Indicates that the device's CPU supports fused multiply-accumulate VFP instructions extension. Also part of the VFPv4 specification.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_NEON_FMA</code><br/>
Indicates that the device's CPU supports fused multiply-accumulate NEON instructions extension. Also part of the VFPv4 specification.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_IDIV_ARM</code><br/>
Indicates that the device's CPU supports Integer division in ARM mode. Only available on recent CPUs (e.g. Cortex-A15).</li>
<li><code>ANDROID_CPU_ARM_FEATURE_IDIV_THUMB2</code><br/>
Indicates that the device's CPU supports Integer division in Thumb-2 mode. Only available on recent CPUs (e.g. Cortex-A15).</li>
<li><code>ANDROID_CPU_ARM_FEATURE_iWMMXt</code><br/>
Indicates that the device's CPU supports extension that adds MMX registers and instructions. This is only available on a few XScale- based CPU.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_LDREX_STREX</code><br/>
Indicates that the device's CPU supports LDREX and STREX instructions available since ARMv6. Together they provide atomic update on memory with the help of exclusive monitor.</li>
</ul>
<p>And the following flags for the 32-bit x86 CPU Family:</p>
<ul>
<li><code>ANDROID_CPU_X86_FEATURE_SSSE3</code><br/>
Indicates that the device's CPU supports the SSSE3 instruction extension set. Note that this is unlike SSE3 which is required by the x86 NDK ABI.</li>
<li><code>ANDROID_CPU_X86_FEATURE_POPCNT</code><br/>
Indicates that the device's CPU supports the POPCNT instruction.</li>
<li><code>ANDROID_CPU_X86_FEATURE_MOVBE</code><br/>
Indicates that the device's CPU supports the MOVBE instruction. This one is specific to some Intel IA-32 CPUs, like the Atom.</li>
</ul>
<p>And the following flags for the 64-bit ARM CPU Family:</p>
<ul>
<li><code>ANDROID_CPU_ARM64_FEATURE_FP</code><br/>
Indicates that the device's CPU has Floating Point (FP) unit. All Android ARM64 devices are required to support this feature.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_ASIMD</code><br/>
Indicates that the device's CPU has Advanced SIMD (ASIMD) unit. All Android ARM64 devices are required to support this feature.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_AES</code><br/>
Indicates that the device's CPU supports AES instructions.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_CRC32</code><br/>
Indicates that the device's CPU supports CRC32 instructions.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_SHA1</code><br/>
Indicates that the device's CPU supports SHA1 instructions.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_SHA2</code><br/>
Indicates that the device's CPU supports SHA2 instructions.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_PMULL</code><br/>
Indicates that the device's CPU supports 64-bit PMULL and PMULL2 instructions.</li>
</ul>
<p>Other CPU families do not have extensions listed at the moment, which means that android_getCpuFeatures() will return 0 for them.</p>
<p>The following function is also defined to return the max number of CPU cores on the target device: </p>
<pre class="fragment"> int android_getCpuCount(void);
</pre><h2>Important Note</h2>
<p>The cpufeatures library will be updated to support more CPU families and optional features in the future. It is designed to work as-is on all official Android platform versions.</p>
<h2>Change History</h2>
<p>Please see the comments in <code>$NDK/sources/android/cpufeatures/cpu-features.c</code> for the complete change history for this library. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK Programmer's Guide by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
</ul>
</div>
</body>
</html>