core/stdarch/crates/core_arch/src/
mod.rs

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