1 page.title=The cpufeatures Library 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="#usage">Usage</a></li> 10 <li><a href="#functions">Functions</a></li> 11 <li><a href="#ch">Change History</a></li> 12 </ol> 13 </div> 14 </div> 15 16 <p>The NDK provides a small library named {@code cpufeatures} that your app can use at runtime to 17 detect the target device's CPU family and the optional features it supports. It is designed to work 18 as-is on all official Android platform versions.</p> 19 20 <h2 id="usage">Usage</h2> 21 <p>The {@code cpufeatures} library is available as an import module. To use it, follow the procedure 22 below:</p> 23 24 <ol> 25 <li>List {@code cpufeatures} in your list of static library dependencies. For example: 26 27 <pre class="no-pretty-print"> 28 LOCAL_STATIC_LIBRARIES := cpufeatures 29 </pre> 30 </li> 31 32 <li>In your source code, include the {@code <cpu-features.h>} header file.</li> 33 34 <li>At the end of your <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file, 35 insert an instruction to import the {@code android/cpufeatures} module. For example: 36 37 <pre class="no-pretty-print"> 38 $(call import-module,android/cpufeatures) 39 </pre> 40 41 <p>Here is a simple example of an {@code Android.mk} file that imports the {@code cpufeatures} 42 library:</p> 43 44 <pre class="no-pretty-print"> 45 <project-path>/jni/Android.mk: 46 LOCAL_PATH := $(call my-dir) 47 48 include $(CLEAR_VARS) 49 LOCAL_MODULE := <your-module-name> 50 LOCAL_SRC_FILES := <your-source-files> 51 LOCAL_STATIC_LIBRARIES := cpufeatures 52 include $(BUILD_SHARED_LIBRARY) 53 54 $(call import-module,android/cpufeatures) 55 </pre> 56 </li> 57 </ol> 58 59 <h2 id="functions">Functions</h2> 60 <p>The {@code cpufeatures} library provides two functions. The first function returns the family to 61 which the device's CPU belongs. Declare it as follows:</p> 62 63 <pre class="no-pretty-print"> 64 AndroidCpuFamily android_getCpuFamily(); 65 </pre> 66 67 <p>The function returns one of the following enums, representing the CPU family/architecture that 68 the device supports.</p> 69 <ul> 70 <li>{@code ANDROID_CPU_FAMILY_ARM}</li> 71 <li>{@code ANDROID_CPU_FAMILY_X86}</li> 72 <li>{@code ANDROID_CPU_FAMILY_MIPS}</li> 73 <li>{@code ANDROID_CPU_FAMILY_ARM64}</li> 74 <li>{@code ANDROID_CPU_FAMILY_X86_64}</li> 75 <li>{@code ANDROID_CPU_FAMILY_MIPS64}</li> 76 </ul> 77 78 <p>For a 32-bit executable on a 64-bit system, this function returns only the 32-bit value.</p> 79 80 <p>The second function returns the set of optional features that the device's CPU supports. Declare 81 it as follows: 82 83 <pre class="no-pretty-print"> 84 uint64_t android_getCpuFeatures(); 85 </pre> 86 87 <p>The return value takes the form of a set of bit flags, each flag representing one 88 CPU-family-specific feature. The rest of this section provides information on features for 89 the respective families.</p> 90 91 <h4>32-bit ARM CPU family</h4> 92 93 <p>The following flags are available for the 32-bit ARM CPU family:</p> 94 <dl> 95 <dt>{@code ANDROID_CPU_ARM_FEATURE_VFPv2}</dt> 96 <dd>Indicates that the device's CPU supports the VFPv2 instruction set. Most ARMv6 CPUs support 97 this instruction set.</dd> 98 99 <dt>{@code ANDROID_CPU_ARM_FEATURE_ARMv7}</dt> 100 <dd>Indicates that the device's CPU supports the ARMv7-A instruction set as supported by the 101 <a href="{@docRoot}ndk/guides/abis.html#v7a">armeabi-v7a</a> ABI. This instruction set supports both 102 Thumb-2 and VFPv3-D16 instructions. This return value also indicates support for the VFPv3 hardware 103 FPU instruction-set extension.</dd> 104 105 <dt>{@code ANDROID_CPU_ARM_FEATURE_VFPv3}</dt> 106 <dd>Indicates that the device's CPU supports the VFPv3 hardware FPU instruction-set extension. 107 <p>This value is equivalent to the {@code VFPv3-D16} instruction set, which provides provides only 108 16 hardware double-precision FP registers.</p></dd> 109 110 <dt>{@code ANDROID_CPU_ARM_FEATURE_VFP_D32}</dt> 111 <dd> Indicates that the device's CPU supports 32 hardware double-precision FP registers instead of 112 16. Even when there are 32 hardware double-precision FP registers, there are still only 32 113 single-precision registers mapped to the same register banks.</dd> 114 115 <dt>{@code ANDROID_CPU_ARM_FEATURE_NEON}</dt> 116 <dd>Indicates that the device's CPU supports the ARM Advanced SIMD (NEON) vector instruction set 117 extension. Note that ARM mandates that such CPUs also implement VFPv3-D32, which provides 32 118 hardware FP registers (shared with the NEON unit).</dd> 119 120 <dt>{@code ANDROID_CPU_ARM_FEATURE_VFP_FP16}</dt> 121 <dd>Indicates that the device's CPU supports instructions to perform floating-point operations on 122 16-bit registers. This feature is part of the VFPv4 specification.</dd> 123 124 <dt>{@code ANDROID_CPU_ARM_FEATURE_VFP_FMA}</dt> 125 <dd>Indicates that the device's CPU supports the fused multiply-accumulate extension for the VFP 126 instruction set. Also part of the VFPv4 specification.</dd> 127 128 <dt>{@code ANDROID_CPU_ARM_FEATURE_NEON_FMA}</dt> 129 <dd>Indicates that the device's CPU supports the fused multiply-accumulate extension for the NEON 130 instruction set. Also part of the VFPv4 specification.</dd> 131 132 <dt>{@code ANDROID_CPU_ARM_FEATURE_IDIV_ARM}</dt> 133 <dd>Indicates that the device's CPU supports integer division in ARM mode. Only available on later- 134 model CPUs, such as Cortex-A15.</dd> 135 136 <dt>{@code ANDROID_CPU_ARM_FEATURE_IDIV_THUMB2}</dt> 137 <dd>Indicates that the device's CPU supports Integer division in Thumb-2 mode. Only available on 138 later-model CPUs, such as Cortex-A15.</dd> 139 140 <dt>{@code ANDROID_CPU_ARM_FEATURE_iWMMXt}</dt> 141 <dd>Indicates that the device's CPU supports an instruction-set extension that adds MMX registers 142 and instructions. This feature is only available on a few XScale- based CPUs.</dd> 143 144 <dt>{@code ANDROID_CPU_ARM_FEATURE_LDREX_STREX}</dt> 145 <dd>Indicates that the device's CPU supports LDREX and STREX instructions available since ARMv6. 146 Together, these instructions provide atomic updates on memory with the help of exclusive 147 monitor.</dd> 148 </dl> 149 150 <h4>64-bit ARM CPU family</h4> 151 152 <p>The following flags are available for the 64-bit ARM CPU family:</p> 153 <dl> 154 <dt>{@code ANDROID_CPU_ARM64_FEATURE_FP}</dt> 155 <dd>Indicates that the device's CPU has a Floating Point Unit (FPU). All Android ARM64 devices must 156 support this feature.</dd> 157 <dt>{@code ANDROID_CPU_ARM64_FEATURE_ASIMD}</dt> 158 <dd>Indicates that the device's CPU has an Advanced SIMD (ASIMD) unit. All Android ARM64 devices 159 must support this feature.</dd> 160 <dt>{@code ANDROID_CPU_ARM64_FEATURE_AES}</dt> 161 <dd>Indicates that the device's CPU supports {@code AES} instructions.</dd> 162 <dt>{@code ANDROID_CPU_ARM64_FEATURE_CRC32}</dt> 163 <dd>Indicates that the device's CPU supports {@code CRC32} instructions.</dd> 164 <dt>{@code ANDROID_CPU_ARM64_FEATURE_SHA1}</dt> 165 <dd>Indicates that the device's CPU supports {@code SHA1} instructions.</dd> 166 <dt>{@code ANDROID_CPU_ARM64_FEATURE_SHA2}</dt> 167 <dd>Indicates that the device's CPU supports {@code SHA2} instructions.</dd> 168 <dt>{@code ANDROID_CPU_ARM64_FEATURE_PMULL}</dt> 169 <dd>Indicates that the device's CPU supports 64-bit {@code PMULL} and {@code PMULL2} 170 instructions.</dd> 171 </dl> 172 173 <h4>32-bit x86 CPU family</h4> 174 175 <p>The following flags are available for the 32-bit x86 CPU family.<p> 176 <dl> 177 <dt>{@code ANDROID_CPU_X86_FEATURE_SSSE3}</dt> 178 Indicates that the device's CPU supports the SSSE3 instruction extension set.</dd> 179 180 <dt>{@code ANDROID_CPU_X86_FEATURE_POPCNT}</dt> 181 <dd>Indicates that the device's CPU supports the {@code POPCNT} instruction.</dd> 182 183 <dt>{@code ANDROID_CPU_X86_FEATURE_MOVBE}</dt> 184 <dd>Indicates that the device's CPU supports the {@code MOVBE} instruction. This instruction is 185 specific to some Intel IA-32 CPUs, such as Atom.</dd> 186 <dl> 187 188 <p>{@code android_getCpuFeatures()} returns {@code 0} for CPU families for which there are no 189 listed extensions.</p> 190 191 <p>The following function returns the maximum number of CPU cores on the target device: </p> 192 193 <pre class="no-pretty-print"> 194 int android_getCpuCount(void); 195 </pre> 196 197 <h4>MIPS CPU family</h4> 198 199 <dl> 200 <dt>{@code ANDROID_CPU_MIPS_FEATURE_R6}</dt> 201 <dd>Indicates that the CPU executes MIPS Release 6 instructions natively, and supports obsoleted R1..R5 instructions only via kernel traps.</dd> 202 203 <dt>{@code ANDROID_CPU_MIPS_FEATURE_MSA}</dt> 204 <dd>Indicates that the CPU supports MIPS SIMD Architecture instructions.</dd> 205 </dl> 206 207 <h2 id="ch">Change History</h2> 208 <p>For the complete change history of this library, see the comments in 209 {@code $NDK/sources/android/cpufeatures/cpu-features.c}, where {@code $NDK} is the root of your 210 NDK installation.</p>
