mod.rs - source
Description: Source of the Rust file `library/core/src/../../stdarch/crates/core_arch/src/mod.rs`.

#
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;