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