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 | |
18 | features! { |
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 | |