1//! `core_arch`
2
3#[macro_use]
4mod macros;
5
6#[cfg(any(target_arch = "riscv32", target_arch = "riscv64", doc))]
7mod riscv_shared;
8
9#[cfg(any(target_arch = "arm", target_arch = "aarch64", doc))]
10mod arm_shared;
11
12mod simd;
13
14#[doc = include_str!("core_arch_docs.md")]
15#[stable(feature = "simd_arch", since = "1.27.0")]
16pub mod arch {
17 /// Platform-specific intrinsics for the `x86` platform.
18 ///
19 /// See the [module documentation](../index.html) for more details.
20 #[cfg(any(target_arch = "x86", doc))]
21 #[doc(cfg(target_arch = "x86"))]
22 #[stable(feature = "simd_x86", since = "1.27.0")]
23 pub mod x86 {
24 #[stable(feature = "simd_x86", since = "1.27.0")]
25 pub use crate::core_arch::x86::*;
26 }
27
28 /// Platform-specific intrinsics for the `x86_64` platform.
29 ///
30 /// See the [module documentation](../index.html) for more details.
31 #[cfg(any(target_arch = "x86_64", doc))]
32 #[doc(cfg(target_arch = "x86_64"))]
33 #[stable(feature = "simd_x86", since = "1.27.0")]
34 pub mod x86_64 {
35 #[stable(feature = "simd_x86", since = "1.27.0")]
36 pub use crate::core_arch::x86::*;
37 #[stable(feature = "simd_x86", since = "1.27.0")]
38 pub use crate::core_arch::x86_64::*;
39 }
40
41 /// Platform-specific intrinsics for the `arm` platform.
42 ///
43 /// See the [module documentation](../index.html) for more details.
44 #[cfg(any(target_arch = "arm", doc))]
45 #[doc(cfg(target_arch = "arm"))]
46 #[unstable(feature = "stdsimd", issue = "27731")]
47 pub mod arm {
48 pub use crate::core_arch::arm::*;
49 }
50
51 /// Platform-specific intrinsics for the `aarch64` platform.
52 ///
53 /// See the [module documentation](../index.html) for more details.
54 #[cfg(any(target_arch = "aarch64", doc))]
55 #[doc(cfg(target_arch = "aarch64"))]
56 #[stable(feature = "neon_intrinsics", since = "1.59.0")]
57 pub mod aarch64 {
58 #[stable(feature = "neon_intrinsics", since = "1.59.0")]
59 pub use crate::core_arch::aarch64::*;
60 }
61
62 /// Platform-specific intrinsics for the `riscv32` platform.
63 ///
64 /// See the [module documentation](../index.html) for more details.
65 #[cfg(any(target_arch = "riscv32", doc))]
66 #[doc(cfg(any(target_arch = "riscv32")))]
67 #[unstable(feature = "riscv_ext_intrinsics", issue = "114544")]
68 pub mod riscv32 {
69 pub use crate::core_arch::riscv32::*;
70 pub use crate::core_arch::riscv_shared::*;
71 }
72
73 /// Platform-specific intrinsics for the `riscv64` platform.
74 ///
75 /// See the [module documentation](../index.html) for more details.
76 #[cfg(any(target_arch = "riscv64", doc))]
77 #[doc(cfg(any(target_arch = "riscv64")))]
78 #[unstable(feature = "riscv_ext_intrinsics", issue = "114544")]
79 pub mod riscv64 {
80 pub use crate::core_arch::riscv64::*;
81 // RISC-V RV64 supports all RV32 instructions as well in current specifications (2022-01-05).
82 // Module `riscv_shared` includes instructions available under all RISC-V platforms,
83 // i.e. RISC-V RV32 instructions.
84 pub use crate::core_arch::riscv_shared::*;
85 }
86
87 /// Platform-specific intrinsics for the `wasm32` platform.
88 ///
89 /// This module provides intrinsics specific to the WebAssembly
90 /// architecture. Here you'll find intrinsics specific to WebAssembly that
91 /// aren't otherwise surfaced somewhere in a cross-platform abstraction of
92 /// `std`, and you'll also find functions for leveraging WebAssembly
93 /// proposals such as [atomics] and [simd].
94 ///
95 /// Intrinsics in the `wasm32` module are modeled after the WebAssembly
96 /// instructions that they represent. Most functions are named after the
97 /// instruction they intend to correspond to, and the arguments/results
98 /// correspond to the type signature of the instruction itself. Stable
99 /// WebAssembly instructions are [documented online][instrdoc].
100 ///
101 /// [instrdoc]: https://webassembly.github.io/spec/core/valid/instructions.html
102 ///
103 /// If a proposal is not yet stable in WebAssembly itself then the functions
104 /// within this function may be unstable and require the nightly channel of
105 /// Rust to use. As the proposal itself stabilizes the intrinsics in this
106 /// module should stabilize as well.
107 ///
108 /// [atomics]: https://github.com/webassembly/threads
109 /// [simd]: https://github.com/webassembly/simd
110 ///
111 /// See the [module documentation](../index.html) for general information
112 /// about the `arch` module and platform intrinsics.
113 ///
114 /// ## Atomics
115 ///
116 /// The [threads proposal][atomics] for WebAssembly adds a number of
117 /// instructions for dealing with multithreaded programs. Most instructions
118 /// added in the [atomics] proposal are exposed in Rust through the
119 /// `std::sync::atomic` module. Some instructions, however, don't have
120 /// direct equivalents in Rust so they're exposed here instead.
121 ///
122 /// Note that the instructions added in the [atomics] proposal can work in
123 /// either a context with a shared wasm memory and without. These intrinsics
124 /// are always available in the standard library, but you likely won't be
125 /// able to use them too productively unless you recompile the standard
126 /// library (and all your code) with `-Ctarget-feature=+atomics`.
127 ///
128 /// It's also worth pointing out that multi-threaded WebAssembly and its
129 /// story in Rust is still in a somewhat "early days" phase as of the time
130 /// of this writing. Pieces should mostly work but it generally requires a
131 /// good deal of manual setup. At this time it's not as simple as "just call
132 /// `std::thread::spawn`", but it will hopefully get there one day!
133 ///
134 /// ## SIMD
135 ///
136 /// The [simd proposal][simd] for WebAssembly added a new `v128` type for a
137 /// 128-bit SIMD register. It also added a large array of instructions to
138 /// operate on the `v128` type to perform data processing. Using SIMD on
139 /// wasm is intended to be similar to as you would on `x86_64`, for example.
140 /// You'd write a function such as:
141 ///
142 /// ```rust,ignore
143 /// #[cfg(target_arch = "wasm32")]
144 /// #[target_feature(enable = "simd128")]
145 /// unsafe fn uses_simd() {
146 /// use std::arch::wasm32::*;
147 /// // ...
148 /// }
149 /// ```
150 ///
151 /// Unlike `x86_64`, however, WebAssembly does not currently have dynamic
152 /// detection at runtime as to whether SIMD is supported (this is one of the
153 /// motivators for the [conditional sections][condsections] and [feature
154 /// detection] proposals, but that is still pretty early days). This means
155 /// that your binary will either have SIMD and can only run on engines
156 /// which support SIMD, or it will not have SIMD at all. For compatibility
157 /// the standard library itself does not use any SIMD internally.
158 /// Determining how best to ship your WebAssembly binary with SIMD is
159 /// largely left up to you as it can be pretty nuanced depending on
160 /// your situation.
161 ///
162 /// [condsections]: https://github.com/webassembly/conditional-sections
163 /// [feature detection]: https://github.com/WebAssembly/feature-detection
164 ///
165 /// To enable SIMD support at compile time you need to do one of two things:
166 ///
167 /// * First you can annotate functions with `#[target_feature(enable =
168 /// "simd128")]`. This causes just that one function to have SIMD support
169 /// available to it, and intrinsics will get inlined as usual in this
170 /// situation.
171 ///
172 /// * Second you can compile your program with `-Ctarget-feature=+simd128`.
173 /// This compilation flag blanket enables SIMD support for your entire
174 /// compilation. Note that this does not include the standard library
175 /// unless you [recompile the standard library][buildstd].
176 ///
177 /// [buildstd]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std
178 ///
179 /// If you enable SIMD via either of these routes then you'll have a
180 /// WebAssembly binary that uses SIMD instructions, and you'll need to ship
181 /// that accordingly. Also note that if you call SIMD intrinsics but don't
182 /// enable SIMD via either of these mechanisms, you'll still have SIMD
183 /// generated in your program. This means to generate a binary without SIMD
184 /// you'll need to avoid both options above plus calling into any intrinsics
185 /// in this module.
186 #[cfg(any(target_arch = "wasm32", doc))]
187 #[doc(cfg(target_arch = "wasm32"))]
188 #[stable(feature = "simd_wasm32", since = "1.33.0")]
189 pub mod wasm32 {
190 #[stable(feature = "simd_wasm32", since = "1.33.0")]
191 pub use crate::core_arch::wasm32::*;
192 }
193
194 /// Platform-specific intrinsics for the `wasm64` platform.
195 ///
196 /// See the [module documentation](../index.html) for more details.
197 #[cfg(any(target_arch = "wasm64", doc))]
198 #[doc(cfg(target_arch = "wasm64"))]
199 #[unstable(feature = "simd_wasm64", issue = "90599")]
200 pub mod wasm64 {
201 #[unstable(feature = "simd_wasm64", issue = "90599")]
202 pub use crate::core_arch::wasm32::*;
203 }
204
205 /// Platform-specific intrinsics for the `wasm` target family.
206 ///
207 /// See the [module documentation](../index.html) for more details.
208 #[cfg(any(target_family = "wasm", doc))]
209 #[doc(cfg(target_family = "wasm"))]
210 #[unstable(feature = "simd_wasm64", issue = "90599")]
211 pub mod wasm {
212 #[unstable(feature = "simd_wasm64", issue = "90599")]
213 pub use crate::core_arch::wasm32::*;
214 }
215
216 /// Platform-specific intrinsics for the `mips` platform.
217 ///
218 /// See the [module documentation](../index.html) for more details.
219 #[cfg(any(target_arch = "mips", doc))]
220 #[doc(cfg(target_arch = "mips"))]
221 #[unstable(feature = "stdsimd", issue = "27731")]
222 pub mod mips {
223 pub use crate::core_arch::mips::*;
224 }
225
226 /// Platform-specific intrinsics for the `mips64` platform.
227 ///
228 /// See the [module documentation](../index.html) for more details.
229 #[cfg(any(target_arch = "mips64", doc))]
230 #[doc(cfg(target_arch = "mips64"))]
231 #[unstable(feature = "stdsimd", issue = "27731")]
232 pub mod mips64 {
233 pub use crate::core_arch::mips::*;
234 }
235
236 /// Platform-specific intrinsics for the `PowerPC` platform.
237 ///
238 /// See the [module documentation](../index.html) for more details.
239 #[cfg(any(target_arch = "powerpc", doc))]
240 #[doc(cfg(target_arch = "powerpc"))]
241 #[unstable(feature = "stdsimd", issue = "27731")]
242 pub mod powerpc {
243 pub use crate::core_arch::powerpc::*;
244 }
245
246 /// Platform-specific intrinsics for the `PowerPC64` platform.
247 ///
248 /// See the [module documentation](../index.html) for more details.
249 #[cfg(any(target_arch = "powerpc64", doc))]
250 #[doc(cfg(target_arch = "powerpc64"))]
251 #[unstable(feature = "stdsimd", issue = "27731")]
252 pub mod powerpc64 {
253 pub use crate::core_arch::powerpc64::*;
254 }
255
256 /// Platform-specific intrinsics for the `NVPTX` platform.
257 ///
258 /// See the [module documentation](../index.html) for more details.
259 #[cfg(any(target_arch = "nvptx64", doc))]
260 #[doc(cfg(target_arch = "nvptx64"))]
261 #[unstable(feature = "stdsimd", issue = "27731")]
262 pub mod nvptx {
263 pub use crate::core_arch::nvptx::*;
264 }
265}
266
267mod simd_llvm;
268
269#[cfg(any(target_arch = "x86", target_arch = "x86_64", doc))]
270#[doc(cfg(any(target_arch = "x86", target_arch = "x86_64")))]
271mod x86;
272#[cfg(any(target_arch = "x86_64", doc))]
273#[doc(cfg(target_arch = "x86_64"))]
274mod x86_64;
275
276#[cfg(any(target_arch = "aarch64", doc))]
277#[doc(cfg(target_arch = "aarch64"))]
278mod aarch64;
279#[cfg(any(target_arch = "arm", doc))]
280#[doc(cfg(any(target_arch = "arm")))]
281mod arm;
282
283#[cfg(any(target_arch = "riscv32", doc))]
284#[doc(cfg(any(target_arch = "riscv32")))]
285mod riscv32;
286
287#[cfg(any(target_arch = "riscv64", doc))]
288#[doc(cfg(any(target_arch = "riscv64")))]
289mod riscv64;
290
291#[cfg(any(target_family = "wasm", doc))]
292#[doc(cfg(target_family = "wasm"))]
293mod wasm32;
294
295#[cfg(any(target_arch = "mips", target_arch = "mips64", doc))]
296#[doc(cfg(any(target_arch = "mips", target_arch = "mips64")))]
297mod mips;
298
299#[cfg(any(target_arch = "powerpc", target_arch = "powerpc64", doc))]
300#[doc(cfg(any(target_arch = "powerpc", target_arch = "powerpc64")))]
301mod powerpc;
302
303#[cfg(any(target_arch = "powerpc64", doc))]
304#[doc(cfg(target_arch = "powerpc64"))]
305mod powerpc64;
306
307#[cfg(any(target_arch = "nvptx64", doc))]
308#[doc(cfg(target_arch = "nvptx64"))]
309mod nvptx;
310