Debian Codegraph @

.cargo/vendor/cpufeatures/src/lib.rs

raw
1 //! This crate provides macros for runtime CPU feature detection. It's intended
2 //! as a stopgap until Rust [RFC 2725] adding first-class target feature detection
3 //! macros to `libcore` is implemented.
4 //!
5 //! # Supported target architectures
6 //!
7 //! *NOTE: target features with an asterisk are unstable (nightly-only) and
8 //! subject to change to match upstream name changes in the Rust standard
9 //! library.
10 //!
11 //! ## `aarch64`
12 //!
13 //! Linux, iOS, and macOS/ARM only (ARM64 does not support OS-independent feature detection)
14 //!
15 //! Target features:
16 //!
17 //! - `aes`*
18 //! - `sha2`*
19 //! - `sha3`*
20 //!
21 //! Linux only
22 //!
23 //! - `sm4`*
24 //!
25 //! ## `loongarch64`
26 //!
27 //! Linux only (LoongArch64 does not support OS-independent feature detection)
28 //!
29 //! Target features:
30 //!
31 //! - `lam`*
32 //! - `ual`*
33 //! - `fpu`*
34 //! - `lsx`*
35 //! - `lasx`*
36 //! - `crc32`*
37 //! - `complex`*
38 //! - `crypto`*
39 //! - `lvz`*
40 //! - `lbt.x86`*
41 //! - `lbt.arm`*
42 //! - `lbt.mips`*
43 //! - `ptw`*
44 //!
45 //! ## `x86`/`x86_64`
46 //!
47 //! OS independent and `no_std`-friendly
48 //!
49 //! Target features:
50 //!
51 //! - `adx`
52 //! - `aes`
53 //! - `avx`
54 //! - `avx2`
55 //! - `avx512bw`*
56 //! - `avx512cd`*
57 //! - `avx512dq`*
58 //! - `avx512er`*
59 //! - `avx512f`*
60 //! - `avx512ifma`*
61 //! - `avx512pf`*
62 //! - `avx512vl`*
63 //! - `bmi1`
64 //! - `bmi2`
65 //! - `fma`,
66 //! - `mmx`
67 //! - `pclmulqdq`
68 //! - `popcnt`
69 //! - `rdrand`
70 //! - `rdseed`
71 //! - `sgx`
72 //! - `sha`
73 //! - `sse`
74 //! - `sse2`
75 //! - `sse3`
76 //! - `sse4.1`
77 //! - `sse4.2`
78 //! - `ssse3`
79 //!
80 //! If you would like detection support for a target feature which is not on
81 //! this list, please [open a GitHub issue][gh].
82 //!
83 //! # Example
84 //! ```
85 //! # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
86 //! # {
87 //! // This macro creates `cpuid_aes_sha` module
88 //! cpufeatures::new!(cpuid_aes_sha, "aes", "sha");
89 //!
90 //! // `token` is a Zero Sized Type (ZST) value, which guarantees
91 //! // that underlying static storage got properly initialized,
92 //! // which allows to omit initialization branch
93 //! let token: cpuid_aes_sha::InitToken = cpuid_aes_sha::init();
94 //!
95 //! if token.get() {
96 //! println!("CPU supports both SHA and AES extensions");
97 //! } else {
98 //! println!("SHA and AES extensions are not supported");
99 //! }
100 //!
101 //! // If stored value needed only once you can get stored value
102 //! // omitting the token
103 //! let val = cpuid_aes_sha::get();
104 //! assert_eq!(val, token.get());
105 //!
106 //! // Additionally you can get both token and value
107 //! let (token, val) = cpuid_aes_sha::init_get();
108 //! assert_eq!(val, token.get());
109 //! # }
110 //! ```
111 //!
112 //! Note that if all tested target features are enabled via compiler options
113 //! (e.g. by using `RUSTFLAGS`), the `get` method will always return `true`
114 //! and `init` will not use CPUID instruction. Such behavior allows
115 //! compiler to completely eliminate fallback code.
116 //!
117 //! After first call macro caches result and returns it in subsequent
118 //! calls, thus runtime overhead for them is minimal.
119 //!
120 //! [RFC 2725]: https://github.com/rust-lang/rfcs/pull/2725
121 //! [gh]: https://github.com/RustCrypto/utils/issues/new?title=cpufeatures:%20requesting%20support%20for%20CHANGEME%20target%20feature
122
123 #![no_std]
124 #![doc(
125 html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
126 html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
127 )]
128
129 #[cfg(not(miri))]
130 #[cfg(target_arch = "aarch64")]
131 #[doc(hidden)]
132 pub mod aarch64;
133
134 #[cfg(not(miri))]
135 #[cfg(target_arch = "loongarch64")]
136 #[doc(hidden)]
137 pub mod loongarch64;
138
139 #[cfg(not(miri))]
140 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
141 mod x86;
142
143 #[cfg(miri)]
144 mod miri;
145
146 #[cfg(not(any(
147 target_arch = "aarch64",
148 target_arch = "loongarch64",
149 target_arch = "x86",
150 target_arch = "x86_64"
151 )))]
152 compile_error!("This crate works only on `aarch64`, `loongarch64`, `x86`, and `x86-64` targets.");
153
154 /// Create module with CPU feature detection code.
155 #[macro_export]
156 macro_rules! new {
157 ($mod_name:ident, $($tf:tt),+ $(,)?) => {
158 mod $mod_name {
159 use core::sync::atomic::{AtomicU8, Ordering::Relaxed};
160
161 const UNINIT: u8 = u8::max_value();
162 static STORAGE: AtomicU8 = AtomicU8::new(UNINIT);
163
164 /// Initialization token
165 #[derive(Copy, Clone, Debug)]
166 pub struct InitToken(());
167
168 impl InitToken {
169 /// Get initialized value
170 #[inline(always)]
171 pub fn get(&self) -> bool {
172 $crate::__unless_target_features! {
173 $($tf),+ => {
174 STORAGE.load(Relaxed) == 1
175 }
176 }
177 }
178 }
179
180 /// Initialize underlying storage if needed and get
181 /// stored value and initialization token.
182 #[inline]
183 pub fn init_get() -> (InitToken, bool) {
184 let res = $crate::__unless_target_features! {
185 $($tf),+ => {
186 // Relaxed ordering is fine, as we only have a single atomic variable.
187 let val = STORAGE.load(Relaxed);
188
189 if val == UNINIT {
190 let res = $crate::__detect_target_features!($($tf),+);
191 STORAGE.store(res as u8, Relaxed);
192 res
193 } else {
194 val == 1
195 }
196 }
197 };
198
199 (InitToken(()), res)
200 }
201
202 /// Initialize underlying storage if needed and get
203 /// initialization token.
204 #[inline]
205 pub fn init() -> InitToken {
206 init_get().0
207 }
208
209 /// Initialize underlying storage if needed and get
210 /// stored value.
211 #[inline]
212 pub fn get() -> bool {
213 init_get().1
214 }
215 }
216 };
217 }