1Android NDK CPU Features detection library:
2====
3
4This NDK provides a small library named "`cpufeatures`" that can be used at
5runtime to detect the target device's CPU family and the optional features
6it supports.
7
8Usage:
9------
10
11The 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
25Here 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
39Features:
40---------
41
42Two functions are provided for now:
43
44        AndroidCpuFamily android_getCpuFamily();
45
46Returns a value matching the CPU family/architecture supported by the
47current 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
61Note that when running a 32-bit executable on a 64-bit system, this function
62will return the 32-bit family value only.
63
64Secondly:
65
66        uint64_t android_getCpuFeatures();
67
68Returns the set of optional features supported by the device's CPU.
69The result is a set of bit-flags, each corresponding to one CPU
70Family-specific optional feature.
71
72Currently, only the following flags are defined, for the 32-bit ARM CPU
73Family:
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
135And 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
149Other CPU families do not have extensions listed at the moment, which
150means that android_getCpuFeatures() will return 0 for them.
151
152The following function is also defined to return the max number of
153CPU cores on the target device:
154
155        int  android_getCpuCount(void);
156
157
158Important Note:
159---------------
160
161The cpufeatures library will be updated to support more CPU families and
162optional features in the future. It is designed to work as-is on all
163official Android platform versions.
164
165
166Change History:
167---------------
168
169Please see the comments in `$NDK/sources/android/cpufeatures/cpu-features.c`
170for the complete change history for this library.
171