1 Android NDK CPU Features detection library: 2 ==== 3 4 This NDK provides a small library named "`cpufeatures`" that can be used at 5 runtime to detect the target device's CPU family and the optional features 6 it supports. 7 8 Usage: 9 ------ 10 11 The library is available as an import module. To use it, you must: 12 13 * List '`cpufeatures`' in your list of static library dependencies, as in: 14 15 LOCAL_STATIC_LIBRARIES := cpufeatures 16 17 * At the end of your Android.mk, import the '`android/cpufeatures`' module, 18 as in: 19 20 $(call import-module,android/cpufeatures) 21 22 * In your source code, include the header named `<cpu-features.h>` 23 24 25 Here is a simple example: 26 27 <project-path>/jni/Android.mk: 28 LOCAL_PATH := $(call my-dir) 29 30 include $(CLEAR_VARS) 31 LOCAL_MODULE := <your-module-name> 32 LOCAL_SRC_FILES := <your-source-files> 33 LOCAL_STATIC_LIBRARIES := cpufeatures 34 include $(BUILD_SHARED_LIBRARY) 35 36 $(call import-module,android/cpufeatures) 37 38 39 Features: 40 --------- 41 42 Two functions are provided for now: 43 44 AndroidCpuFamily android_getCpuFamily(); 45 46 Returns a value matching the CPU family/architecture supported by the 47 current process as an enum. Currently, the following families are defined: 48 49 * `ANDROID_CPU_FAMILY_ARM` 50 51 * `ANDROID_CPU_FAMILY_X86` 52 53 * `ANDROID_CPU_FAMILY_MIPS` 54 55 * `ANDROID_CPU_FAMILY_ARM64` 56 57 * `ANDROID_CPU_FAMILY_X86_64` 58 59 * `ANDROID_CPU_FAMILY_MIPS64` 60 61 Note that when running a 32-bit executable on a 64-bit system, this function 62 will return the 32-bit family value only. 63 64 Secondly: 65 66 uint64_t android_getCpuFeatures(); 67 68 Returns the set of optional features supported by the device's CPU. 69 The result is a set of bit-flags, each corresponding to one CPU 70 Family-specific optional feature. 71 72 Currently, only the following flags are defined, for the 32-bit ARM CPU 73 Family: 74 75 * `ANDROID_CPU_ARM_FEATURE_VFPv2` 76 > Indicates that the device's CPU supports VFPv2 instruction set. 77 Most ARMv6 CPUs support these. 78 79 * `ANDROID_CPU_ARM_FEATURE_ARMv7` 80 > Indicates that the device's CPU supports the ARMv7-A instruction 81 set as supported by the "armeabi-v7a" abi (see CPU-ARCH-ABIS.html). 82 This corresponds to Thumb-2 and VFPv3-D16 instructions. 83 84 * `ANDROID_CPU_ARM_FEATURE_VFPv3` 85 > Indicates that the device's CPU supports the VFPv3 hardware FPU 86 instruction set extension. Due to the definition of 'armeabi-v7a', 87 this will always be the case if ANDROID_CPU_ARM_FEATURE_ARMv7 is 88 returned. 89 90 Note that this corresponds to the minimum profile VFPv3-D16 that 91 _only_ provides 16 hardware double-precision FP registers. 92 93 * `ANDROID_CPU_ARM_FEATURE_VFP_D32` 94 > Indicates that the device's CPU supports 32 hardware double-precision 95 FP registers instead of 16. Note that there are still only 32 single- 96 precision registers mapped to the same register banks. 97 98 * `ANDROID_CPU_ARM_FEATURE_NEON` 99 > Indicates that the device's CPU supports the ARM Advanced SIMD 100 (a.k.a. NEON) vector instruction set extension. Note that ARM 101 mandates that such CPUs also implement VFPv3-D32, which provides 102 32 hardware FP registers (shared with the NEON unit). 103 104 * `ANDROID_CPU_ARM_FEATURE_VFP_FP16` 105 > Indicates that the device's CPU supports instructions to perform 106 floating-point operations on 16-bit registers. This is part of the 107 VFPv4 specification. 108 109 * `ANDROID_CPU_ARM_FEATURE_VFP_FMA` 110 > Indicates that the device's CPU supports fused multiply-accumulate 111 VFP instructions extension. Also part of the VFPv4 specification. 112 113 * `ANDROID_CPU_ARM_FEATURE_NEON_FMA` 114 > Indicates that the device's CPU supports fused multiply-accumulate 115 NEON instructions extension. Also part of the VFPv4 specification. 116 117 * `ANDROID_CPU_ARM_FEATURE_IDIV_ARM` 118 > Indicates that the device's CPU supports Integer division in ARM mode. 119 Only available on recent CPUs (e.g. Cortex-A15). 120 121 * `ANDROID_CPU_ARM_FEATURE_IDIV_THUMB2` 122 > Indicates that the device's CPU supports Integer division in Thumb-2 123 mode. Only available on recent CPUs (e.g. Cortex-A15). 124 125 * `ANDROID_CPU_ARM_FEATURE_iWMMXt` 126 > Indicates that the device's CPU supports extension that adds MMX 127 registers and instructions. This is only available on a few XScale- 128 based CPU. 129 130 * `ANDROID_CPU_ARM_FEATURE_LDREX_STREX` 131 > Indicates that the device's CPU supports LDREX and STREX instructions 132 available since ARMv6. Together they provide atomic update on memory 133 with the help of exclusive monitor. 134 135 And the following flags for the 32-bit x86 CPU Family: 136 137 * `ANDROID_CPU_X86_FEATURE_SSSE3` 138 > Indicates that the device's CPU supports the SSSE3 instruction 139 extension set. Note that this is unlike SSE3 which is required 140 by the x86 NDK ABI. 141 142 * `ANDROID_CPU_X86_FEATURE_POPCNT` 143 > Indicates that the device's CPU supports the POPCNT instruction. 144 145 * `ANDROID_CPU_X86_FEATURE_MOVBE` 146 > Indicates that the device's CPU supports the MOVBE instruction. 147 This one is specific to some Intel IA-32 CPUs, like the Atom. 148 149 Other CPU families do not have extensions listed at the moment, which 150 means that android_getCpuFeatures() will return 0 for them. 151 152 The following function is also defined to return the max number of 153 CPU cores on the target device: 154 155 int android_getCpuCount(void); 156 157 158 Important Note: 159 --------------- 160 161 The cpufeatures library will be updated to support more CPU families and 162 optional features in the future. It is designed to work as-is on all 163 official Android platform versions. 164 165 166 Change History: 167 --------------- 168 169 Please see the comments in `$NDK/sources/android/cpufeatures/cpu-features.c` 170 for the complete change history for this library. 171
