page.title=The cpufeatures Library @jd:body

On this page

  1. Usage
  2. Functions
  3. Change History

The NDK provides a small library named {@code cpufeatures} that your app can use at runtime to detect the target device's CPU family and the optional features it supports. It is designed to work as-is on all official Android platform versions.

Usage

The {@code cpufeatures} library is available as an import module. To use it, follow the procedure below:

  1. List {@code cpufeatures} in your list of static library dependencies. For example: 
    LOCAL_STATIC_LIBRARIES := cpufeatures
  2. In your source code, include the {@code <cpu-features.h>} header file.
  3. At the end of your {@code Android.mk} file, insert an instruction to import the {@code android/cpufeatures} module. For example: 
    $(call import-module,android/cpufeatures)

    Here is a simple example of an {@code Android.mk} file that imports the {@code cpufeatures} library:

    <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)

Functions

The {@code cpufeatures} library provides two functions. The first function returns the family to which the device's CPU belongs. Declare it as follows:

AndroidCpuFamily android_getCpuFamily();

The function returns one of the following enums, representing the CPU family/architecture that the device supports.

For a 32-bit executable on a 64-bit system, this function returns only the 32-bit value.

The second function returns the set of optional features that the device's CPU supports. Declare it as follows: 

uint64_t android_getCpuFeatures();

The return value takes the form of a set of bit flags, each flag representing one CPU-family-specific feature. The rest of this section provides information on features for the respective families.

32-bit ARM CPU family

The following flags are available for the 32-bit ARM CPU family:

{@code ANDROID_CPU_ARM_FEATURE_VFPv2}
Indicates that the device's CPU supports the VFPv2 instruction set. Most ARMv6 CPUs support this instruction set.
{@code ANDROID_CPU_ARM_FEATURE_ARMv7}
Indicates that the device's CPU supports the ARMv7-A instruction set as supported by the armeabi-v7a ABI. This instruction set supports both Thumb-2 and VFPv3-D16 instructions. This return value also indicates support for the VFPv3 hardware FPU instruction-set extension.
{@code ANDROID_CPU_ARM_FEATURE_VFPv3}
Indicates that the device's CPU supports the VFPv3 hardware FPU instruction-set extension.

This value is equivalent to the {@code VFPv3-D16} instruction set, which provides provides only 16 hardware double-precision FP registers.

{@code ANDROID_CPU_ARM_FEATURE_VFP_D32}
Indicates that the device's CPU supports 32 hardware double-precision FP registers instead of 16. Even when there are 32 hardware double-precision FP registers, there are still only 32 single-precision registers mapped to the same register banks.
{@code ANDROID_CPU_ARM_FEATURE_NEON}
Indicates that the device's CPU supports the ARM Advanced SIMD (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).
{@code ANDROID_CPU_ARM_FEATURE_VFP_FP16}
Indicates that the device's CPU supports instructions to perform floating-point operations on 16-bit registers. This feature is part of the VFPv4 specification.
{@code ANDROID_CPU_ARM_FEATURE_VFP_FMA}
Indicates that the device's CPU supports the fused multiply-accumulate extension for the VFP instruction set. Also part of the VFPv4 specification.
{@code ANDROID_CPU_ARM_FEATURE_NEON_FMA}
Indicates that the device's CPU supports the fused multiply-accumulate extension for the NEON instruction set. Also part of the VFPv4 specification.
{@code ANDROID_CPU_ARM_FEATURE_IDIV_ARM}
Indicates that the device's CPU supports integer division in ARM mode. Only available on later- model CPUs, such as Cortex-A15.
{@code ANDROID_CPU_ARM_FEATURE_IDIV_THUMB2}
Indicates that the device's CPU supports Integer division in Thumb-2 mode. Only available on later-model CPUs, such as Cortex-A15.
{@code ANDROID_CPU_ARM_FEATURE_iWMMXt}
Indicates that the device's CPU supports an instruction-set extension that adds MMX registers and instructions. This feature is only available on a few XScale- based CPUs.
{@code ANDROID_CPU_ARM_FEATURE_LDREX_STREX}
Indicates that the device's CPU supports LDREX and STREX instructions available since ARMv6. Together, these instructions provide atomic updates on memory with the help of exclusive monitor.

64-bit ARM CPU family

The following flags are available for the 64-bit ARM CPU family:

{@code ANDROID_CPU_ARM64_FEATURE_FP}
Indicates that the device's CPU has a Floating Point Unit (FPU). All Android ARM64 devices must support this feature.
{@code ANDROID_CPU_ARM64_FEATURE_ASIMD}
Indicates that the device's CPU has an Advanced SIMD (ASIMD) unit. All Android ARM64 devices must support this feature.
{@code ANDROID_CPU_ARM64_FEATURE_AES}
Indicates that the device's CPU supports {@code AES} instructions.
{@code ANDROID_CPU_ARM64_FEATURE_CRC32}
Indicates that the device's CPU supports {@code CRC32} instructions.
{@code ANDROID_CPU_ARM64_FEATURE_SHA1}
Indicates that the device's CPU supports {@code SHA1} instructions.
{@code ANDROID_CPU_ARM64_FEATURE_SHA2}
Indicates that the device's CPU supports {@code SHA2} instructions.
{@code ANDROID_CPU_ARM64_FEATURE_PMULL}
Indicates that the device's CPU supports 64-bit {@code PMULL} and {@code PMULL2} instructions.

32-bit x86 CPU family

The following flags are available for the 32-bit x86 CPU family.

{@code ANDROID_CPU_X86_FEATURE_SSSE3}
Indicates that the device's CPU supports the SSSE3 instruction extension set.
{@code ANDROID_CPU_X86_FEATURE_POPCNT}
Indicates that the device's CPU supports the {@code POPCNT} instruction.
{@code ANDROID_CPU_X86_FEATURE_MOVBE}
Indicates that the device's CPU supports the {@code MOVBE} instruction. This instruction is specific to some Intel IA-32 CPUs, such as Atom.

{@code android_getCpuFeatures()} returns {@code 0} for CPU families for which there are no listed extensions.

The following function returns the maximum number of CPU cores on the target device: 

int  android_getCpuCount(void);

MIPS CPU family

{@code ANDROID_CPU_MIPS_FEATURE_R6}
Indicates that the CPU executes MIPS Release 6 instructions natively, and supports obsoleted R1..R5 instructions only via kernel traps.
{@code ANDROID_CPU_MIPS_FEATURE_MSA}
Indicates that the CPU supports MIPS SIMD Architecture instructions.

Change History

For the complete change history of this library, see the comments in {@code $NDK/sources/android/cpufeatures/cpu-features.c}, where {@code $NDK} is the root of your NDK installation.