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;