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

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

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