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

   1 //! `core_arch`
   2
   3 #![cfg_attr(not(bootstrap), allow(automatic_links))]
   4 #[macro_use]
   5 mod macros;
   6
   7 #[cfg(any(target_arch = "arm", target_arch = "aarch64", doc))]
   8 mod acle;
   9
  10 mod simd;
  11
  12 #[doc = include_str!("core_arch_docs.md")]
  13 #[stable(feature = "simd_arch", since = "1.27.0")]
  14 pub mod arch {
  15     /// Platform-specific intrinsics for the `x86` platform.
  16     ///
  17     /// See the [module documentation](../index.html) for more details.
  18     #[cfg(any(target_arch = "x86", doc))]
  19     #[doc(cfg(target_arch = "x86"))]
  20     #[stable(feature = "simd_x86", since = "1.27.0")]
  21     pub mod x86 {
  22         #[stable(feature = "simd_x86", since = "1.27.0")]
  23         pub use crate::core_arch::x86::*;
  24     }
  25
  26     /// Platform-specific intrinsics for the `x86_64` platform.
  27     ///
  28     /// See the [module documentation](../index.html) for more details.
  29     #[cfg(any(target_arch = "x86_64", doc))]
  30     #[doc(cfg(target_arch = "x86_64"))]
  31     #[stable(feature = "simd_x86", since = "1.27.0")]
  32     pub mod x86_64 {
  33         #[stable(feature = "simd_x86", since = "1.27.0")]
  34         pub use crate::core_arch::x86::*;
  35         #[stable(feature = "simd_x86", since = "1.27.0")]
  36         pub use crate::core_arch::x86_64::*;
  37     }
  38
  39     /// Platform-specific intrinsics for the `arm` platform.
  40     ///
  41     /// See the [module documentation](../index.html) for more details.
  42     #[cfg(any(target_arch = "arm", doc))]
  43     #[doc(cfg(target_arch = "arm"))]
  44     #[unstable(feature = "stdsimd", issue = "27731")]
  45     pub mod arm {
  46         pub use crate::core_arch::arm::*;
  47     }
  48
  49     /// Platform-specific intrinsics for the `aarch64` platform.
  50     ///
  51     /// See the [module documentation](../index.html) for more details.
  52     #[cfg(any(target_arch = "aarch64", doc))]
  53     #[doc(cfg(target_arch = "aarch64"))]
  54     #[unstable(feature = "stdsimd", issue = "27731")]
  55     pub mod aarch64 {
  56         pub use crate::core_arch::{aarch64::*, arm::*};
  57     }
  58
  59     /// Platform-specific intrinsics for the `wasm32` platform.
  60     ///
  61     /// This module provides intrinsics specific to the WebAssembly
  62     /// architecture. Here you'll find intrinsics necessary for leveraging
  63     /// WebAssembly proposals such as [atomics] and [simd]. These proposals are
  64     /// evolving over time and as such the support here is unstable and requires
  65     /// the nightly channel. As WebAssembly proposals stabilize these functions
  66     /// will also become stable.
  67     ///
  68     /// [atomics]: https://github.com/webassembly/threads
  69     /// [simd]: https://github.com/webassembly/simd
  70     ///
  71     /// See the [module documentation](../index.html) for general information
  72     /// about the `arch` module and platform intrinsics.
  73     ///
  74     /// ## Atomics
  75     ///
  76     /// The [threads proposal][atomics] for WebAssembly adds a number of
  77     /// instructions for dealing with multithreaded programs. Atomic
  78     /// instructions can all be generated through `std::sync::atomic` types, but
  79     /// some instructions have no equivalent in Rust such as
  80     /// `memory.atomic.notify` so this module will provide these intrinsics.
  81     ///
  82     /// At this time, however, these intrinsics are only available **when the
  83     /// standard library itself is compiled with atomics**. Compiling with
  84     /// atomics is not enabled by default and requires passing
  85     /// `-Ctarget-feature=+atomics` to rustc. The standard library shipped via
  86     /// `rustup` is not compiled with atomics. To get access to these intrinsics
  87     /// you'll need to compile the standard library from source with the
  88     /// requisite compiler flags.
  89     ///
  90     /// ## SIMD
  91     ///
  92     /// The [simd proposal][simd] for WebAssembly adds a new `v128` type for a
  93     /// 128-bit SIMD register. It also adds a large array of instructions to
  94     /// operate on the `v128` type to perform data processing. The SIMD proposal
  95     /// has been in progress for quite some time and many instructions have come
  96     /// and gone. This module attempts to keep up with the proposal, but if you
  97     /// notice anything awry please feel free to [open an
  98     /// issue](https://github.com/rust-lang/stdarch/issues/new).
  99     ///
 100     /// It's important to be aware that the current state of development of SIMD
 101     /// in WebAssembly is still somewhat early days. There's lots of pieces to
 102     /// demo and prototype with, but discussions and support are still in
 103     /// progress. There's a number of pitfalls and gotchas in various places,
 104     /// which will attempt to be documented here, but there may be others
 105     /// lurking!
 106     ///
 107     /// Using SIMD is intended to be similar to as you would on `x86_64`, for
 108     /// example. You'd write a function such as:
 109     ///
 110     /// ```rust,ignore
 111     /// #[cfg(target_arch = "wasm32")]
 112     /// #[target_feature(enable = "simd128")]
 113     /// unsafe fn uses_simd() {
 114     ///     use std::arch::wasm32::*;
 115     ///     // ...
 116     /// }
 117     /// ```
 118     ///
 119     /// Unlike `x86_64`, however, WebAssembly does not currently have dynamic
 120     /// detection at runtime as to whether SIMD is supported (this is one of the
 121     /// motivators for the [conditional sections proposal][condsections], but
 122     /// that is still pretty early days). This means that your binary will
 123     /// either have SIMD and can only run on engines which support SIMD, or it
 124     /// will not have SIMD at all. For compatibility the standard library itself
 125     /// does not use any SIMD internally. Determining how best to ship your
 126     /// WebAssembly binary with SIMD is largely left up to you as it can can be
 127     /// pretty nuanced depending on your situation.
 128     ///
 129     /// [condsections]: https://github.com/webassembly/conditional-sections
 130     ///
 131     /// To enable SIMD support at compile time you need to do one of two things:
 132     ///
 133     /// * First you can annotate functions with `#[target_feature(enable =
 134     ///   "simd128")]`. This causes just that one function to have SIMD support
 135     ///   available to it, and intrinsics will get inlined as usual in this
 136     ///   situation.
 137     ///
 138     /// * Second you can compile your program with `-Ctarget-feature=+simd128`.
 139     ///   This compilation flag blanket enables SIMD support for your entire
 140     ///   compilation. Note that this does not include the standard library
 141     ///   unless you recompile the standard library.
 142     ///
 143     /// If you enable SIMD via either of these routes then you'll have a
 144     /// WebAssembly binary that uses SIMD instructions, and you'll need to ship
 145     /// that accordingly. Also note that if you call SIMD intrinsics but don't
 146     /// enable SIMD via either of these mechanisms, you'll still have SIMD
 147     /// generated in your program. This means to generate a binary without SIMD
 148     /// you'll need to avoid both options above plus calling into any intrinsics
 149     /// in this module.
 150     ///
 151     /// > **Note**: Due to
 152     /// > [rust-lang/rust#74320](https://github.com/rust-lang/rust/issues/74320)
 153     /// > it's recommended to compile your entire program with SIMD support
 154     /// > (using `RUSTFLAGS`) or otherwise functions may not be inlined
 155     /// > correctly.
 156     ///
 157     /// > **Note**: LLVM's SIMD support is actually split into two features:
 158     /// > `simd128` and `unimplemented-simd128`. Rust code can enable `simd128`
 159     /// > with `#[target_feature]` (and test for it with `#[cfg(target_feature =
 160     /// > "simd128")]`, but it cannot enable `unimplemented-simd128`. The only
 161     /// > way to enable this feature is to compile with
 162     /// > `-Ctarget-feature=+simd128,+unimplemented-simd128`. This second
 163     /// > feature enables more recent instructions implemented in LLVM which
 164     /// > haven't always had enough time to make their way to runtimes.
 165     #[cfg(any(target_arch = "wasm32", doc))]
 166     #[doc(cfg(target_arch = "wasm32"))]
 167     #[stable(feature = "simd_wasm32", since = "1.33.0")]
 168     pub mod wasm32 {
 169         #[stable(feature = "simd_wasm32", since = "1.33.0")]
 170         pub use crate::core_arch::wasm32::*;
 171     }
 172
 173     /// Platform-specific intrinsics for the `mips` platform.
 174     ///
 175     /// See the [module documentation](../index.html) for more details.
 176     #[cfg(any(target_arch = "mips", doc))]
 177     #[doc(cfg(target_arch = "mips"))]
 178     #[unstable(feature = "stdsimd", issue = "27731")]
 179     pub mod mips {
 180         pub use crate::core_arch::mips::*;
 181     }
 182
 183     /// Platform-specific intrinsics for the `mips64` platform.
 184     ///
 185     /// See the [module documentation](../index.html) for more details.
 186     #[cfg(any(target_arch = "mips64", doc))]
 187     #[doc(cfg(target_arch = "mips64"))]
 188     #[unstable(feature = "stdsimd", issue = "27731")]
 189     pub mod mips64 {
 190         pub use crate::core_arch::mips::*;
 191     }
 192
 193     /// Platform-specific intrinsics for the `PowerPC` platform.
 194     ///
 195     /// See the [module documentation](../index.html) for more details.
 196     #[cfg(any(target_arch = "powerpc", doc))]
 197     #[doc(cfg(target_arch = "powerpc"))]
 198     #[unstable(feature = "stdsimd", issue = "27731")]
 199     pub mod powerpc {
 200         pub use crate::core_arch::powerpc::*;
 201     }
 202
 203     /// Platform-specific intrinsics for the `PowerPC64` platform.
 204     ///
 205     /// See the [module documentation](../index.html) for more details.
 206     #[cfg(any(target_arch = "powerpc64", doc))]
 207     #[doc(cfg(target_arch = "powerpc64"))]
 208     #[unstable(feature = "stdsimd", issue = "27731")]
 209     pub mod powerpc64 {
 210         pub use crate::core_arch::powerpc64::*;
 211     }
 212
 213     /// Platform-specific intrinsics for the `NVPTX` platform.
 214     ///
 215     /// See the [module documentation](../index.html) for more details.
 216     #[cfg(any(target_arch = "nvptx", target_arch = "nvptx64", doc))]
 217     #[doc(cfg(any(target_arch = "nvptx", target_arch = "nvptx64")))]
 218     #[unstable(feature = "stdsimd", issue = "27731")]
 219     pub mod nvptx {
 220         pub use crate::core_arch::nvptx::*;
 221     }
 222 }
 223
 224 mod simd_llvm;
 225
 226 #[cfg(any(target_arch = "x86", target_arch = "x86_64", doc))]
 227 #[doc(cfg(any(target_arch = "x86", target_arch = "x86_64")))]
 228 mod x86;
 229 #[cfg(any(target_arch = "x86_64", doc))]
 230 #[doc(cfg(target_arch = "x86_64"))]
 231 mod x86_64;
 232
 233 #[cfg(any(target_arch = "aarch64", doc))]
 234 #[doc(cfg(target_arch = "aarch64"))]
 235 mod aarch64;
 236 #[cfg(any(target_arch = "arm", target_arch = "aarch64", doc))]
 237 #[doc(cfg(any(target_arch = "arm", target_arch = "aarch64")))]
 238 mod arm;
 239
 240 #[cfg(any(target_arch = "wasm32", doc))]
 241 #[doc(cfg(target_arch = "wasm32"))]
 242 mod wasm32;
 243
 244 #[cfg(any(target_arch = "mips", target_arch = "mips64", doc))]
 245 #[doc(cfg(any(target_arch = "mips", target_arch = "mips64")))]
 246 mod mips;
 247
 248 #[cfg(any(target_arch = "powerpc", target_arch = "powerpc64", doc))]
 249 #[doc(cfg(any(target_arch = "powerpc", target_arch = "powerpc64")))]
 250 mod powerpc;
 251
 252 #[cfg(any(target_arch = "powerpc64", doc))]
 253 #[doc(cfg(target_arch = "powerpc64"))]
 254 mod powerpc64;
 255
 256 #[cfg(any(target_arch = "nvptx", target_arch = "nvptx64", doc))]
 257 #[doc(cfg(any(target_arch = "nvptx", target_arch = "nvptx64")))]
 258 mod nvptx;