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

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