1# cpu_features [](https://travis-ci.org/google/cpu_features) [](https://ci.appveyor.com/project/gchatelet/cpu-features/branch/master) 2 3A cross-platform C library to retrieve CPU features (such as available 4instructions) at runtime. 5 6## Table of Contents 7 8- [Design Rationale](#rationale) 9- [Code samples](#codesample) 10- [Running sample code](#usagesample) 11- [What's supported](#support) 12- [Android NDK's drop in replacement](#ndk) 13- [License](#license) 14- [Build with cmake](#cmake) 15 16<a name="rationale"></a> 17## Design Rationale 18 19- **Simple to use.** See the snippets below for examples. 20- **Extensible.** Easy to add missing features or architectures. 21- **Compatible with old compilers** and available on many architectures so it 22 can be used widely. To ensure that cpu_features works on as many platforms 23 as possible, we implemented it in a highly portable version of C: C99. 24- **Sandbox-compatible.** The library uses a variety of strategies to cope 25 with sandboxed environments or when `cpuid` is unavailable. This is useful 26 when running integration tests in hermetic environments. 27- **Thread safe, no memory allocation, and raises no exceptions.** 28 cpu_features is suitable for implementing fundamental libc functions like 29 `malloc`, `memcpy`, and `memcmp`. 30- **Unit tested.** 31 32<a name="codesample"></a> 33## Code samples 34 35**Note:** For C++ code, the library functions are defined in the `CpuFeatures` namespace. 36 37### Checking features at runtime 38 39Here's a simple example that executes a codepath if the CPU supports both the 40AES and the SSE4.2 instruction sets: 41 42```c 43#include "cpuinfo_x86.h" 44 45// For C++, add `using namespace CpuFeatures;` 46static const X86Features features = GetX86Info().features; 47 48void Compute(void) { 49 if (features.aes && features.sse4_2) { 50 // Run optimized code. 51 } else { 52 // Run standard code. 53 } 54} 55``` 56 57### Caching for faster evaluation of complex checks 58 59If you wish, you can read all the features at once into a global variable, and 60then query for the specific features you care about. Below, we store all the ARM 61features and then check whether AES and NEON are supported. 62 63```c 64#include <stdbool.h> 65#include "cpuinfo_arm.h" 66 67// For C++, add `using namespace CpuFeatures;` 68static const ArmFeatures features = GetArmInfo().features; 69static const bool has_aes_and_neon = features.aes && features.neon; 70 71// use has_aes_and_neon. 72``` 73 74This is a good approach to take if you're checking for combinations of features 75when using a compiler that is slow to extract individual bits from bit-packed 76structures. 77 78### Checking compile time flags 79 80The following code determines whether the compiler was told to use the AVX 81instruction set (e.g., `g++ -mavx`) and sets `has_avx` accordingly. 82 83```c 84#include <stdbool.h> 85#include "cpuinfo_x86.h" 86 87// For C++, add `using namespace CpuFeatures;` 88static const X86Features features = GetX86Info().features; 89static const bool has_avx = CPU_FEATURES_COMPILED_X86_AVX || features.avx; 90 91// use has_avx. 92``` 93 94`CPU_FEATURES_COMPILED_X86_AVX` is set to 1 if the compiler was instructed to 95use AVX and 0 otherwise, combining compile time and runtime knowledge. 96 97### Rejecting poor hardware implementations based on microarchitecture 98 99On x86, the first incarnation of a feature in a microarchitecture might not be 100the most efficient (e.g. AVX on Sandy Bridge). We provide a function to retrieve 101the underlying microarchitecture so you can decide whether to use it. 102 103Below, `has_fast_avx` is set to 1 if the CPU supports the AVX instruction 104set—but only if it's not Sandy Bridge. 105 106```c 107#include <stdbool.h> 108#include "cpuinfo_x86.h" 109 110// For C++, add `using namespace CpuFeatures;` 111static const X86Info info = GetX86Info(); 112static const X86Microarchitecture uarch = GetX86Microarchitecture(&info); 113static const bool has_fast_avx = info.features.avx && uarch != INTEL_SNB; 114 115// use has_fast_avx. 116``` 117 118This feature is currently available only for x86 microarchitectures. 119 120<a name="usagesample"></a> 121### Running sample code 122 123Building `cpu_features` (check [quickstart](#quickstart) below) brings a small executable to test the library. 124 125```shell 126 % ./build/list_cpu_features 127arch : x86 128brand : Intel(R) Xeon(R) CPU E5-1650 0 @ 3.20GHz 129family : 6 (0x06) 130model : 45 (0x2D) 131stepping : 7 (0x07) 132uarch : INTEL_SNB 133flags : aes,avx,cx16,smx,sse4_1,sse4_2,ssse3 134``` 135 136```shell 137% ./build/list_cpu_features --json 138{"arch":"x86","brand":" Intel(R) Xeon(R) CPU E5-1650 0 @ 3.20GHz","family":6,"model":45,"stepping":7,"uarch":"INTEL_SNB","flags":["aes","avx","cx16","smx","sse4_1","sse4_2","ssse3"]} 139``` 140 141<a name="support"></a> 142## What's supported 143 144| | x86³ | ARM | AArch64 | MIPS⁴ | POWER | 145|---------|:----:|:-------:|:-------:|:------:|:-------:| 146| Android | yes² | yes¹ | yes¹ | yes¹ | N/A | 147| iOS | N/A | not yet | not yet | N/A | N/A | 148| Linux | yes² | yes¹ | yes¹ | yes¹ | yes¹ | 149| MacOs | yes² | N/A | not yet | N/A | no | 150| Windows | yes² | not yet | not yet | N/A | N/A | 151 1521. **Features revealed from Linux.** We gather data from several sources 153 depending on availability: 154 + from glibc's 155 [getauxval](https://www.gnu.org/software/libc/manual/html_node/Auxiliary-Vector.html) 156 + by parsing `/proc/self/auxv` 157 + by parsing `/proc/cpuinfo` 1582. **Features revealed from CPU.** features are retrieved by using the `cpuid` 159 instruction. 1603. **Microarchitecture detection.** On x86 some features are not always 161 implemented efficiently in hardware (e.g. AVX on Sandybridge). Exposing the 162 microarchitecture allows the client to reject particular microarchitectures. 1634. All flavors of Mips are supported, little and big endian as well as 32/64 164 bits. 165 166<a name="ndk"></a> 167## Android NDK's drop in replacement 168 169[cpu_features](https://github.com/google/cpu_features) is now officially 170supporting Android and offers a drop in replacement of for the NDK's [cpu-features.h](https://android.googlesource.com/platform/ndk/+/master/sources/android/cpufeatures/cpu-features.h) 171, see [ndk_compat](ndk_compat) folder for details. 172 173<a name="license"></a> 174## License 175 176The cpu_features library is licensed under the terms of the Apache license. 177See [LICENSE](LICENSE) for more information. 178 179<a name="cmake"></a> 180## Build with CMake 181 182Please check the [CMake build instructions](cmake/README.md). 183 184<a name="quickstart"></a> 185### Quickstart with `Ninja` 186 187 - build `list_cpu_features` 188``` 189 cmake -B/tmp/cpu_features -H. -GNinja -DCMAKE_BUILD_TYPE=Release 190 ninja -C/tmp/cpu_features 191 /tmp/cpu_features/list_cpu_features --json 192``` 193 194 - run tests 195``` 196 cmake -B/tmp/cpu_features -H. -GNinja -DBUILD_TESTING=ON 197 ninja -C/tmp/cpu_features 198 ninja -C/tmp/cpu_features test 199``` 200
){kind=link}