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