1//! This module implements minimal run-time feature detection for x86.
2//!
3//! The features are detected using the `detect_features` function below.
4//! This function uses the CPUID instruction to read the feature flags from the
5//! CPU and encodes them in a `usize` where each bit position represents
6//! whether a feature is available (bit is set) or unavailable (bit is cleared).
7//!
8//! The enum `Feature` is used to map bit positions to feature names, and the
9//! the `__crate::detect::check_for!` macro is used to map string literals (e.g.,
10//! "avx") to these bit positions (e.g., `Feature::avx`).
11//!
12//! The run-time feature detection is performed by the
13//! `__crate::detect::check_for(Feature) -> bool` function. On its first call,
14//! this functions queries the CPU for the available features and stores them
15//! in a global `AtomicUsize` variable. The query is performed by just checking
16//! whether the feature bit in this global variable is set or cleared.
17
18features! {
19 @TARGET: x86;
20 @CFG: any(target_arch = "x86", target_arch = "x86_64");
21 @MACRO_NAME: is_x86_feature_detected;
22 @MACRO_ATTRS:
23 /// A macro to test at *runtime* whether a CPU feature is available on
24 /// x86/x86-64 platforms.
25 ///
26 /// This macro is provided in the standard library and will detect at runtime
27 /// whether the specified CPU feature is detected. This does **not** resolve at
28 /// compile time unless the specified feature is already enabled for the entire
29 /// crate. Runtime detection currently relies mostly on the `cpuid` instruction.
30 ///
31 /// This macro only takes one argument which is a string literal of the feature
32 /// being tested for. The feature names supported are the lowercase versions of
33 /// the ones defined by Intel in [their documentation][docs].
34 ///
35 /// ## Supported arguments
36 ///
37 /// This macro supports the same names that `#[target_feature]` supports. Unlike
38 /// `#[target_feature]`, however, this macro does not support names separated
39 /// with a comma. Instead testing for multiple features must be done through
40 /// separate macro invocations for now.
41 ///
42 /// Supported arguments are:
43 ///
44 /// * `"aes"`
45 /// * `"pclmulqdq"`
46 /// * `"rdrand"`
47 /// * `"rdseed"`
48 /// * `"tsc"`
49 /// * `"mmx"`
50 /// * `"sse"`
51 /// * `"sse2"`
52 /// * `"sse3"`
53 /// * `"ssse3"`
54 /// * `"sse4.1"`
55 /// * `"sse4.2"`
56 /// * `"sse4a"`
57 /// * `"sha"`
58 /// * `"avx"`
59 /// * `"avx2"`
60 /// * `"avx512f"`
61 /// * `"avx512cd"`
62 /// * `"avx512er"`
63 /// * `"avx512pf"`
64 /// * `"avx512bw"`
65 /// * `"avx512dq"`
66 /// * `"avx512vl"`
67 /// * `"avx512ifma"`
68 /// * `"avx512vbmi"`
69 /// * `"avx512vpopcntdq"`
70 /// * `"avx512vbmi2"`
71 /// * `"gfni"`
72 /// * `"vaes"`
73 /// * `"vpclmulqdq"`
74 /// * `"avx512vnni"`
75 /// * `"avx512bitalg"`
76 /// * `"avx512bf16"`
77 /// * `"avx512vp2intersect"`
78 /// * `"avx512fp16"`
79 /// * `"f16c"`
80 /// * `"fma"`
81 /// * `"bmi1"`
82 /// * `"bmi2"`
83 /// * `"abm"`
84 /// * `"lzcnt"`
85 /// * `"tbm"`
86 /// * `"popcnt"`
87 /// * `"fxsr"`
88 /// * `"xsave"`
89 /// * `"xsaveopt"`
90 /// * `"xsaves"`
91 /// * `"xsavec"`
92 /// * `"cmpxchg16b"`
93 /// * `"adx"`
94 /// * `"rtm"`
95 /// * `"movbe"`
96 /// * `"ermsb"`
97 ///
98 /// [docs]: https://software.intel.com/sites/landingpage/IntrinsicsGuide
99 #[stable(feature = "simd_x86", since = "1.27.0")]
100 @BIND_FEATURE_NAME: "abm"; "lzcnt"; // abm is a synonym for lzcnt
101 @BIND_FEATURE_NAME: "avx512gfni"; "gfni"; #[deprecated(since = "1.67.0", note = "the `avx512gfni` feature has been renamed to `gfni`")];
102 @BIND_FEATURE_NAME: "avx512vaes"; "vaes"; #[deprecated(since = "1.67.0", note = "the `avx512vaes` feature has been renamed to `vaes`")];
103 @BIND_FEATURE_NAME: "avx512vpclmulqdq"; "vpclmulqdq"; #[deprecated(since = "1.67.0", note = "the `avx512vpclmulqdq` feature has been renamed to `vpclmulqdq`")];
104 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] aes: "aes";
105 /// AES (Advanced Encryption Standard New Instructions AES-NI)
106 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] pclmulqdq: "pclmulqdq";
107 /// CLMUL (Carry-less Multiplication)
108 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] rdrand: "rdrand";
109 /// RDRAND
110 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] rdseed: "rdseed";
111 /// RDSEED
112 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] tsc: "tsc";
113 /// TSC (Time Stamp Counter)
114 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] mmx: "mmx";
115 /// MMX (MultiMedia eXtensions)
116 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] sse: "sse";
117 /// SSE (Streaming SIMD Extensions)
118 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] sse2: "sse2";
119 /// SSE2 (Streaming SIMD Extensions 2)
120 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] sse3: "sse3";
121 /// SSE3 (Streaming SIMD Extensions 3)
122 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] ssse3: "ssse3";
123 /// SSSE3 (Supplemental Streaming SIMD Extensions 3)
124 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] sse4_1: "sse4.1";
125 /// SSE4.1 (Streaming SIMD Extensions 4.1)
126 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] sse4_2: "sse4.2";
127 /// SSE4.2 (Streaming SIMD Extensions 4.2)
128 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] sse4a: "sse4a";
129 /// SSE4a (Streaming SIMD Extensions 4a)
130 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] sha: "sha";
131 /// SHA
132 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx: "avx";
133 /// AVX (Advanced Vector Extensions)
134 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx2: "avx2";
135 /// AVX2 (Advanced Vector Extensions 2)
136 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512f: "avx512f" ;
137 /// AVX-512 F (Foundation)
138 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512cd: "avx512cd" ;
139 /// AVX-512 CD (Conflict Detection Instructions)
140 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512er: "avx512er";
141 /// AVX-512 ER (Expo nential and Reciprocal Instructions)
142 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512pf: "avx512pf";
143 /// AVX-512 PF (Prefetch Instructions)
144 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512bw: "avx512bw";
145 /// AVX-512 BW (Byte and Word Instructions)
146 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512dq: "avx512dq";
147 /// AVX-512 DQ (Doubleword and Quadword)
148 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512vl: "avx512vl";
149 /// AVX-512 VL (Vector Length Extensions)
150 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512ifma: "avx512ifma";
151 /// AVX-512 IFMA (Integer Fused Multiply Add)
152 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512vbmi: "avx512vbmi";
153 /// AVX-512 VBMI (Vector Byte Manipulation Instructions)
154 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512vpopcntdq: "avx512vpopcntdq";
155 /// AVX-512 VPOPCNTDQ (Vector Population Count Doubleword and
156 /// Quadword)
157 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512vbmi2: "avx512vbmi2";
158 /// AVX-512 VBMI2 (Additional byte, word, dword and qword capabilities)
159 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] gfni: "gfni";
160 /// AVX-512 GFNI (Galois Field New Instruction)
161 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] vaes: "vaes";
162 /// AVX-512 VAES (Vector AES instruction)
163 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] vpclmulqdq: "vpclmulqdq";
164 /// AVX-512 VPCLMULQDQ (Vector PCLMULQDQ instructions)
165 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512vnni: "avx512vnni";
166 /// AVX-512 VNNI (Vector Neural Network Instructions)
167 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512bitalg: "avx512bitalg";
168 /// AVX-512 BITALG (Support for VPOPCNT\[B,W\] and VPSHUFBITQMB)
169 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512bf16: "avx512bf16";
170 /// AVX-512 BF16 (BFLOAT16 instructions)
171 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512vp2intersect: "avx512vp2intersect";
172 /// AVX-512 P2INTERSECT
173 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] avx512fp16: "avx512fp16";
174 /// AVX-512 FP16 (FLOAT16 instructions)
175 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] f16c: "f16c";
176 /// F16C (Conversions between IEEE-754 `binary16` and `binary32` formats)
177 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] fma: "fma";
178 /// FMA (Fused Multiply Add)
179 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] bmi1: "bmi1" ;
180 /// BMI1 (Bit Manipulation Instructions 1)
181 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] bmi2: "bmi2" ;
182 /// BMI2 (Bit Manipulation Instructions 2)
183 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] lzcnt: "lzcnt";
184 /// ABM (Advanced Bit Manipulation) / LZCNT (Leading Zero Count)
185 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] tbm: "tbm";
186 /// TBM (Trailing Bit Manipulation)
187 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] popcnt: "popcnt";
188 /// POPCNT (Population Count)
189 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] fxsr: "fxsr";
190 /// FXSR (Floating-point context fast save and restore)
191 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] xsave: "xsave";
192 /// XSAVE (Save Processor Extended States)
193 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] xsaveopt: "xsaveopt";
194 /// XSAVEOPT (Save Processor Extended States Optimized)
195 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] xsaves: "xsaves";
196 /// XSAVES (Save Processor Extended States Supervisor)
197 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] xsavec: "xsavec";
198 /// XSAVEC (Save Processor Extended States Compacted)
199 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] cmpxchg16b: "cmpxchg16b";
200 /// CMPXCH16B (16-byte compare-and-swap instruction)
201 @FEATURE: #[stable(feature = "simd_x86_adx", since = "1.33.0")] adx: "adx";
202 /// ADX, Intel ADX (Multi-Precision Add-Carry Instruction Extensions)
203 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] rtm: "rtm";
204 /// RTM, Intel (Restricted Transactional Memory)
205 @FEATURE: #[stable(feature = "movbe_target_feature", since = "1.67.0")] movbe: "movbe";
206 /// MOVBE (Move Data After Swapping Bytes)
207 @FEATURE: #[stable(feature = "simd_x86", since = "1.27.0")] ermsb: "ermsb";
208 /// ERMSB, Enhanced REP MOVSB and STOSB
209}
210