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 the target device's CPU Family as an enum. For now, the only 47 supported family is ANDROID_CPU_FAMILY_ARM. 48 49 50 uint64_t android_getCpuFeatures(); 51 52 Returns the set of optional features supported by the device's CPU. 53 The result is a set of bit-flags, each corresponding to one CPU 54 Family-specific optional feature. 55 56 Currently, only the following flags are defined, for the ARM CPU Family: 57 58 * `ANDROID_CPU_ARM_FEATURE_VFPv2` 59 > Indicates that the device's CPU supports VFPv2 instruction set. 60 Most ARMv6 CPUs support these. 61 62 * `ANDROID_CPU_ARM_FEATURE_ARMv7` 63 > Indicates that the device's CPU supports the ARMv7-A instruction 64 set as supported by the "armeabi-v7a" abi (see CPU-ARCH-ABIS.html). 65 This corresponds to Thumb-2 and VFPv3-D16 instructions. 66 67 * `ANDROID_CPU_ARM_FEATURE_VFPv3` 68 > Indicates that the device's CPU supports the VFPv3 hardware FPU 69 instruction set extension. Due to the definition of 'armeabi-v7a', 70 this will always be the case if ANDROID_CPU_ARM_FEATURE_ARMv7 is 71 returned. 72 73 Note that this corresponds to the minimum profile VFPv3-D16 that 74 _only_ provides 16 hardware double-precision FP registers. 75 76 * `ANDROID_CPU_ARM_FEATURE_VFP_D32` 77 > Indicates that the device's CPU supports 32 hardware double-precision 78 FP registers instead of 16. Note that there are still only 32 single- 79 precision registers mapped to the same register banks. 80 81 * `ANDROID_CPU_ARM_FEATURE_NEON` 82 > Indicates that the device's CPU supports the ARM Advanced SIMD 83 (a.k.a. NEON) vector instruction set extension. Note that ARM 84 mandates that such CPUs also implement VFPv3-D32, which provides 85 32 hardware FP registers (shared with the NEON unit). 86 87 * `ANDROID_CPU_ARM_FEATURE_VFP_FP16` 88 > Indicates that the device's CPU supports instructions to perform 89 floating-point operations on 16-bit registers. This is part of the 90 VFPv4 specification. 91 92 * `ANDROID_CPU_ARM_FEATURE_VFP_FMA` 93 > Indicates that the device's CPU supports fused multiply-accumulate 94 VFP instructions extension. Also part of the VFPv4 specification. 95 96 * `ANDROID_CPU_ARM_FEATURE_NEON_FMA` 97 > Indicates that the device's CPU supports fused multiply-accumulate 98 NEON instructions extension. Also part of the VFPv4 specification. 99 100 * `ANDROID_CPU_ARM_FEATURE_IDIV_ARM` 101 > Indicates that the device's CPU supports Integer division in ARM mode. 102 Only available on recent CPUs (e.g. Cortex-A15). 103 104 * `ANDROID_CPU_ARM_FEATURE_IDIV_THUMB2` 105 > Indicates that the device's CPU supports Integer division in Thumb-2 106 mode. Only available on recent CPUs (e.g. Cortex-A15). 107 108 * `ANDROID_CPU_ARM_FEATURE_iWMMXt` 109 > Indicates that the device's CPU supports extension that adds MMX 110 registers and instructions. This is only available on a few XScale- 111 based CPU. 112 113 * `ANDROID_CPU_ARM_FEATURE_LDREX_STREX` 114 > Indicates that the device's CPU supports LDREX and STREX instructions 115 available since ARMv6. Together they provide atomic update on memory 116 with the help of exclusive monitor. 117 118 And the following flags for the x86 CPU Family: 119 120 * `ANDROID_CPU_X86_FEATURE_SSSE3` 121 > Indicates that the device's CPU supports the SSSE3 instruction 122 extension set. Note that this is unlike SSE3 which is required 123 by the x86 NDK ABI. 124 125 * `ANDROID_CPU_X86_FEATURE_POPCNT` 126 > Indicates that the device's CPU supports the POPCNT instruction. 127 128 * `ANDROID_CPU_X86_FEATURE_MOVBE` 129 > Indicates that the device's CPU supports the MOVBE instruction. 130 This one is specific to some Intel IA-32 CPUs, like the Atom. 131 132 133 The following function is also defined to return the max number of 134 CPU cores on the target device: 135 136 int android_getCpuCount(void); 137 138 139 Important Note: 140 --------------- 141 142 The cpufeatures library will be updated to support more CPU families and 143 optional features in the future. It is designed to work as-is on all 144 official Android platform versions. 145 146 147 Change History: 148 --------------- 149 150 Please see the comments in `$NDK/sources/android/cpufeatures/cpu-features.c` 151 for the complete change history for this library. 152
