Crate cpufeatures
source · [−]Expand description
This crate provides macros for runtime CPU feature detection. It’s intended
as a stopgap until Rust RFC 2725 adding first-class target feature detection
macros to libcore
is implemented.
Supported target architectures:
aarch64
: Linux and macOS/M4 only (ARM64 does not support OS-independent feature detection)- Target features:
aes
,sha2
,sha3
- Target features:
x86
/x86_64
: OS independent andno_std
-friendly- Target features:
adx
,aes
,avx
,avx2
,bmi1
,bmi2
,fma
,mmx
,pclmulqdq
,popcnt
,rdrand
,rdseed
,sgx
,sha
,sse
,sse2
,sse3
,sse4.1
,sse4.2
,ssse3
- Target features:
If you would like detection support for a target feature which is not on this list, please open a GitHub issue.
Example
// This macro creates `cpuid_aes_sha` module
cpufeatures::new!(cpuid_aes_sha, "aes", "sha");
// `token` is a Zero Sized Type (ZST) value, which guarantees
// that underlying static storage got properly initialized,
// which allows to omit initialization branch
let token: cpuid_aes_sha::InitToken = cpuid_aes_sha::init();
if token.get() {
println!("CPU supports both SHA and AES extensions");
} else {
println!("SHA and AES extensions are not supported");
}
// If stored value needed only once you can get stored value
// omitting the token
let val = cpuid_aes_sha::get();
assert_eq!(val, token.get());
// Additionally you can get both token and value
let (token, val) = cpuid_aes_sha::init_get();
assert_eq!(val, token.get());
Note that if all tested target features are enabled via compiler options
(e.g. by using RUSTFLAGS
), the get
method will always return true
and init
will not use CPUID instruction. Such behavior allows
compiler to completely eliminate fallback code.
After first call macro caches result and returns it in subsequent calls, thus runtime overhead for them is minimal.
Macros
Create module with CPU feature detection code.