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

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