README.md
1# CPU INFOrmation library
2
3[](https://github.com/pytorch/cpuinfo/blob/master/LICENSE)
4[](https://travis-ci.org/pytorch/cpuinfo)
5[](https://ci.appveyor.com/project/MaratDukhan/cpuinfo/branch/master)
6
7cpuinfo is a library to detect essential for performance optimization information about host CPU.
8
9## Features
10
11- **Cross-platform** availability:
12 - Linux, Windows, macOS, Android, and iOS operating systems
13 - x86, x86-64, ARM, and ARM64 architectures
14- Modern **C/C++ interface**
15 - Thread-safe
16 - No memory allocation after initialization
17 - No exceptions thrown
18- Detection of **supported instruction sets**, up to AVX512 (x86) and ARMv8.3 extensions
19- Detection of SoC and core information:
20 - **Processor (SoC) name**
21 - Vendor and **microarchitecture** for each CPU core
22 - ID (**MIDR** on ARM, **CPUID** leaf 1 EAX value on x86) for each CPU core
23- Detection of **cache information**:
24 - Cache type (instruction/data/unified), size and line size
25 - Cache associativity
26 - Cores and logical processors (hyper-threads) sharing the cache
27- Detection of **topology information** (relative between logical processors, cores, and processor packages)
28- Well-tested **production-quality** code:
29 - 60+ mock tests based on data from real devices
30 - Includes work-arounds for common bugs in hardware and OS kernels
31 - Supports systems with heterogenous cores, such as **big.LITTLE** and Max.Med.Min
32- Permissive **open-source** license (Simplified BSD)
33
34## Examples
35
36Log processor name:
37
38```c
39cpuinfo_initialize();
40printf("Running on %s CPU\n", cpuinfo_get_package(0)->name);
41```
42
43Detect if target is a 32-bit or 64-bit ARM system:
44
45```c
46#if CPUINFO_ARCH_ARM || CPUINFO_ARCH_ARM64
47 /* 32-bit ARM-specific code here */
48#endif
49```
50
51Check if the host CPU support ARM NEON
52```c
53cpuinfo_initialize();
54if (cpuinfo_has_arm_neon()) {
55 neon_implementation(arguments);
56}
57```
58
59Check if the host CPU supports x86 AVX
60```c
61cpuinfo_initialize();
62if (cpuinfo_has_x86_avx()) {
63 avx_implementation(arguments);
64}
65```
66
67Check if the thread runs on a Cortex-A53 core
68```c
69cpuinfo_initialize();
70switch (cpuinfo_get_current_core()->uarch) {
71 case cpuinfo_uarch_cortex_a53:
72 cortex_a53_implementation(arguments);
73 break;
74 default:
75 generic_implementation(arguments);
76 break;
77}
78```
79
80Get the size of level 1 data cache on the fastest core in the processor (e.g. big core in big.LITTLE ARM systems):
81```c
82cpuinfo_initialize();
83const size_t l1_size = cpuinfo_get_processor(0)->cache.l1d->size;
84```
85
86Pin thread to cores sharing L2 cache with the current core (Linux or Android)
87```c
88cpuinfo_initialize();
89cpu_set_t cpu_set;
90CPU_ZERO(&cpu_set);
91const struct cpuinfo_cache* current_l2 = cpuinfo_get_current_processor()->cache.l2;
92for (uint32_t i = 0; i < current_l2->processor_count; i++) {
93 CPU_SET(cpuinfo_get_processor(current_l2->processor_start + i)->linux_id, &cpu_set);
94}
95pthread_setaffinity_np(pthread_self(), sizeof(cpu_set_t), &cpu_set);
96```
97
98## Exposed information
99- [x] Processor (SoC) name
100- [x] Microarchitecture
101- [x] Usable instruction sets
102- [ ] CPU frequency
103- [x] Cache
104 - [x] Size
105 - [x] Associativity
106 - [x] Line size
107 - [x] Number of partitions
108 - [x] Flags (unified, inclusive, complex hash function)
109 - [x] Topology (logical processors that share this cache level)
110- [ ] TLB
111 - [ ] Number of entries
112 - [ ] Associativity
113 - [ ] Covered page types (instruction, data)
114 - [ ] Covered page sizes
115- [x] Topology information
116 - [x] Logical processors
117 - [x] Cores
118 - [x] Packages (sockets)
119
120## Supported environments:
121- [x] Android
122 - [x] x86 ABI
123 - [x] x86_64 ABI
124 - [x] armeabi ABI
125 - [x] armeabiv7-a ABI
126 - [x] arm64-v8a ABI
127 - [ ] ~~mips ABI~~
128 - [ ] ~~mips64 ABI~~
129- [x] Linux
130 - [x] x86
131 - [x] x86-64
132 - [x] 32-bit ARM (ARMv5T and later)
133 - [x] ARM64
134 - [ ] PowerPC64
135- [x] iOS
136 - [x] x86 (iPhone simulator)
137 - [x] x86-64 (iPhone simulator)
138 - [x] ARMv7
139 - [x] ARM64
140- [x] OS X
141 - [x] x86
142 - [x] x86-64
143- [x] Windows
144 - [x] x86
145 - [x] x86-64
146
147## Methods
148
149- Processor (SoC) name detection
150 - [x] Using CPUID leaves 0x80000002–0x80000004 on x86/x86-64
151 - [x] Using `/proc/cpuinfo` on ARM
152 - [x] Using `ro.chipname`, `ro.board.platform`, `ro.product.board`, `ro.mediatek.platform`, `ro.arch` properties (Android)
153 - [ ] Using kernel log (`dmesg`) on ARM Linux
154- Vendor and microarchitecture detection
155 - [x] Intel-designed x86/x86-64 cores (up to Kaby Lake, Airmont, and Knights Mill)
156 - [x] AMD-designed x86/x86-64 cores (up to Puma/Jaguar and Zen)
157 - [ ] VIA-designed x86/x86-64 cores
158 - [ ] Other x86 cores (DM&P, RDC, Transmeta, Cyrix, Rise)
159 - [x] ARM-designed ARM cores (up to Cortex-A55 and Cortex-A75)
160 - [x] Qualcomm-designed ARM cores (up to Kryo, Kryo-280, and Kryo-385)
161 - [x] Nvidia-designed ARM cores (Denver)
162 - [x] Samsung-designed ARM cores (Mongoose and Meerkat)
163 - [x] Intel-designed ARM cores (XScale up to 3rd-gen)
164 - [x] Apple-designed ARM cores (up to Hurricane)
165 - [x] Cavium-designed ARM cores (ThunderX)
166 - [x] AppliedMicro-designed ARM cores (X-Gene)
167- Instruction set detection
168 - [x] Using CPUID (x86/x86-64)
169 - [x] Using dynamic code generation validator (Native Client/x86-64)
170 - [x] Using `/proc/cpuinfo` on 32-bit ARM EABI (Linux)
171 - [x] Using microarchitecture heuristics on (32-bit ARM)
172 - [x] Using `FPSID` and `WCID` registers (32-bit ARM)
173 - [x] Using `getauxval` (Linux/ARM)
174 - [x] Using `/proc/self/auxv` (Android/ARM)
175 - [ ] Using instruction probing on ARM (Linux)
176 - [ ] Using CPUID registers on ARM64 (Linux)
177- Cache detection
178 - [x] Using CPUID leaf 0x00000002 (x86/x86-64)
179 - [x] Using CPUID leaf 0x00000004 (non-AMD x86/x86-64)
180 - [ ] Using CPUID leaves 0x80000005-0x80000006 (AMD x86/x86-64)
181 - [x] Using CPUID leaf 0x8000001D (AMD x86/x86-64)
182 - [x] Using `/proc/cpuinfo` (Linux/pre-ARMv7)
183 - [x] Using microarchitecture heuristics (ARM)
184 - [x] Using chipset name (ARM)
185 - [x] Using `sysctlbyname` (Mach)
186 - [x] Using sysfs `typology` directories (ARM/Linux)
187 - [ ] Using sysfs `cache` directories (Linux)
188- TLB detection
189 - [x] Using CPUID leaf 0x00000002 (x86/x86-64)
190 - [ ] Using CPUID leaves 0x80000005-0x80000006 and 0x80000019 (AMD x86/x86-64)
191 - [x] Using microarchitecture heuristics (ARM)
192- Topology detection
193 - [x] Using CPUID leaf 0x00000001 on x86/x86-64 (legacy APIC ID)
194 - [x] Using CPUID leaf 0x0000000B on x86/x86-64 (Intel APIC ID)
195 - [ ] Using CPUID leaf 0x8000001E on x86/x86-64 (AMD APIC ID)
196 - [x] Using `/proc/cpuinfo` (Linux)
197 - [x] Using `host_info` (Mach)
198 - [x] Using `GetLogicalProcessorInformationEx` (Windows)
199 - [x] Using sysfs (Linux)
200 - [x] Using chipset name (ARM/Linux)
201
){kind=link}
){kind=link}