docs/CPU-FEATURES.TXT

   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 from sources/cpufeatures. It provides an Android.mk
  12 build script that can be used to build it as a static library.
  13
  14 To use it, you must:
  15
  16   * add 'cpufeatures' to your APP_MODULES list in your Application.mk
  17
  18   * include 'sources/cpufeatures/Android.mk' at the start or end of your
  19     Android.mk file.
  20
  21   * add 'sources/cpufeatures' to your LOCAL_C_INCLUDES definition.
  22
  23   * add 'cpufeatures' to your LOCAL_STATIC_LIBRARIES definition when building
  24     your final shared library.
  25
  26   your source code can then #include <cpu-features.h> to compile against it.
  27
  28 Here is a simple example:
  29
  30 <NDK>/apps/<appname>/Application.mk:
  31     APP_PROJECT_PATH := <project-path>
  32     APP_MODULES      := <your-modules> cpufeatures
  33
  34 <project-path>/jni/Android.mk:
  35     LOCAL_PATH := $(call my-dir)
  36
  37     include $(CLEAR_VARS)
  38     LOCAL_MODULE := <your-module-name>
  39     LOCAL_C_INCLUDES += sources/cpufeatures
  40     LOCAL_SRC_FILES := <your-source-files>
  41     LOCAL_STATIC_LIBRARIES += cpufeatures
  42     include $(BUILD_SHARED_LIBRARY)
  43
  44     include sources/cpufeature/Android.mk
  45
  46
  47 Features:
  48 ---------
  49
  50 Two functions are provided for now:
  51
  52    AndroidCpuFamily   android_getCpuFamily();
  53
  54 Returns the target device's CPU Family as an enum. For now, the only
  55 supported family is ANDROID_CPU_FAMILY_ARM.
  56
  57
  58    uint64_t   android_getCpuFeatures();
  59
  60 Returns the set of optional features supported by the device's CPU.
  61 The result is a set of bit-flags, each corresponding to one CPU
  62 Family-specific optional feature.
  63
  64 Currently, only the following flags are defined, for the ARM CPU Family:
  65
  66    ANDROID_CPU_ARM_FEATURE_ARMv7
  67       Indicates that the device's CPU supports the ARMv7-A instruction
  68       set as supported by the "armeabi-v7a" abi (see CPU-ARCH-ABIS.TXT).
  69       This corresponds to Thumb-2 and VFPv3-D16 instructions.
  70
  71    ANDROID_CPU_ARM_FEATURE_VFPv3
  72       Indicates that the device's CPU supports the VFPv3 hardware FPU
  73       instruction set extension. Due to the definition of 'armeabi-v7a',
  74       this will always be the case if ANDROID_CPU_ARM_FEATURE_ARMv7 is
  75       returned.
  76
  77       Note that this corresponds to the minimum profile VFPv3-D16 that
  78       only provides 16 hardware FP registers.
  79
  80    ANDROID_CPU_ARM_FEATURE_NEON
  81       Indicates that the device's CPU supports the ARM Advanced SIMD
  82       (a.k.a. NEON) vector instruction set extension. Note that ARM
  83       mandates that such CPUs also implement VFPv3-D32, which provides
  84       32 hardware FP registers (shared with the NEON unit).
  85
  86
  87 Important Note:
  88 ---------------
  89
  90 The cpufeatures library will be updated to support more CPU families and
  91 optional features in the future. It is designed to work as-is on all
  92 official Android platform versions.