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