library/portable-simd/crates/core_simd/src/intrinsics.rs

   1 //! This module contains the LLVM intrinsics bindings that provide the functionality for this
   2 //! crate.
   3 //!
   4 //! The LLVM assembly language is documented here: <https://llvm.org/docs/LangRef.html>
   5 //!
   6 //! A quick glossary of jargon that may appear in this module, mostly paraphrasing LLVM's LangRef:
   7 //! - poison: "undefined behavior as a value". specifically, it is like uninit memory (such as padding bytes). it is "safe" to create poison, BUT
   8 //!   poison MUST NOT be observed from safe code, as operations on poison return poison, like NaN. unlike NaN, which has defined comparisons,
   9 //!   poison is neither true nor false, and LLVM may also convert it to undef (at which point it is both). so, it can't be conditioned on, either.
  10 //! - undef: "a value that is every value". functionally like poison, insofar as Rust is concerned. poison may become this. note:
  11 //!   this means that division by poison or undef is like division by zero, which means it inflicts...
  12 //! - "UB": poison and undef cover most of what people call "UB". "UB" means this operation immediately invalidates the program:
  13 //!   LLVM is allowed to lower it to `ud2` or other opcodes that may cause an illegal instruction exception, and this is the "good end".
  14 //!   The "bad end" is that LLVM may reverse time to the moment control flow diverged on a path towards undefined behavior,
  15 //!   and destroy the other branch, potentially deleting safe code and violating Rust's `unsafe` contract.
  16 //!
  17 //! Note that according to LLVM, vectors are not arrays, but they are equivalent when stored to and loaded from memory.
  18 //!
  19 //! Unless stated otherwise, all intrinsics for binary operations require SIMD vectors of equal types and lengths.
  20
  21 // These intrinsics aren't linked directly from LLVM and are mostly undocumented, however they are
  22 // mostly lowered to the matching LLVM instructions by the compiler in a fairly straightforward manner.
  23 // The associated LLVM instruction or intrinsic is documented alongside each Rust intrinsic function.
  24 extern "platform-intrinsic" {
  25     /// add/fadd
  26     pub(crate) fn simd_add<T>(x: T, y: T) -> T;
  27
  28     /// sub/fsub
  29     pub(crate) fn simd_sub<T>(lhs: T, rhs: T) -> T;
  30
  31     /// mul/fmul
  32     pub(crate) fn simd_mul<T>(x: T, y: T) -> T;
  33
  34     /// udiv/sdiv/fdiv
  35     /// ints and uints: {s,u}div incur UB if division by zero occurs.
  36     /// ints: sdiv is UB for int::MIN / -1.
  37     /// floats: fdiv is never UB, but may create NaNs or infinities.
  38     pub(crate) fn simd_div<T>(lhs: T, rhs: T) -> T;
  39
  40     /// urem/srem/frem
  41     /// ints and uints: {s,u}rem incur UB if division by zero occurs.
  42     /// ints: srem is UB for int::MIN / -1.
  43     /// floats: frem is equivalent to libm::fmod in the "default" floating point environment, sans errno.
  44     pub(crate) fn simd_rem<T>(lhs: T, rhs: T) -> T;
  45
  46     /// shl
  47     /// for (u)ints. poison if rhs >= lhs::BITS
  48     pub(crate) fn simd_shl<T>(lhs: T, rhs: T) -> T;
  49
  50     /// ints: ashr
  51     /// uints: lshr
  52     /// poison if rhs >= lhs::BITS
  53     pub(crate) fn simd_shr<T>(lhs: T, rhs: T) -> T;
  54
  55     /// and
  56     pub(crate) fn simd_and<T>(x: T, y: T) -> T;
  57
  58     /// or
  59     pub(crate) fn simd_or<T>(x: T, y: T) -> T;
  60
  61     /// xor
  62     pub(crate) fn simd_xor<T>(x: T, y: T) -> T;
  63
  64     /// getelementptr (without inbounds)
  65     pub(crate) fn simd_arith_offset<T, U>(ptrs: T, offsets: U) -> T;
  66
  67     /// fptoui/fptosi/uitofp/sitofp
  68     /// casting floats to integers is truncating, so it is safe to convert values like e.g. 1.5
  69     /// but the truncated value must fit in the target type or the result is poison.
  70     /// use `simd_as` instead for a cast that performs a saturating conversion.
  71     pub(crate) fn simd_cast<T, U>(x: T) -> U;
  72     /// follows Rust's `T as U` semantics, including saturating float casts
  73     /// which amounts to the same as `simd_cast` for many cases
  74     pub(crate) fn simd_as<T, U>(x: T) -> U;
  75
  76     /// neg/fneg
  77     /// ints: ultimately becomes a call to cg_ssa's BuilderMethods::neg. cg_llvm equates this to `simd_sub(Simd::splat(0), x)`.
  78     /// floats: LLVM's fneg, which changes the floating point sign bit. Some arches have instructions for it.
  79     /// Rust panics for Neg::neg(int::MIN) due to overflow, but it is not UB in LLVM without `nsw`.
  80     pub(crate) fn simd_neg<T>(x: T) -> T;
  81
  82     /// fabs
  83     pub(crate) fn simd_fabs<T>(x: T) -> T;
  84
  85     // minnum/maxnum
  86     pub(crate) fn simd_fmin<T>(x: T, y: T) -> T;
  87     pub(crate) fn simd_fmax<T>(x: T, y: T) -> T;
  88
  89     // these return Simd<int, N> with the same BITS size as the inputs
  90     pub(crate) fn simd_eq<T, U>(x: T, y: T) -> U;
  91     pub(crate) fn simd_ne<T, U>(x: T, y: T) -> U;
  92     pub(crate) fn simd_lt<T, U>(x: T, y: T) -> U;
  93     pub(crate) fn simd_le<T, U>(x: T, y: T) -> U;
  94     pub(crate) fn simd_gt<T, U>(x: T, y: T) -> U;
  95     pub(crate) fn simd_ge<T, U>(x: T, y: T) -> U;
  96
  97     // shufflevector
  98     // idx: LLVM calls it a "shuffle mask vector constant", a vector of i32s
  99     pub(crate) fn simd_shuffle<T, U, V>(x: T, y: T, idx: U) -> V;
 100
 101     /// llvm.masked.gather
 102     /// like a loop of pointer reads
 103     /// val: vector of values to select if a lane is masked
 104     /// ptr: vector of pointers to read from
 105     /// mask: a "wide" mask of integers, selects as if simd_select(mask, read(ptr), val)
 106     /// note, the LLVM intrinsic accepts a mask vector of `<N x i1>`
 107     /// FIXME: review this if/when we fix up our mask story in general?
 108     pub(crate) fn simd_gather<T, U, V>(val: T, ptr: U, mask: V) -> T;
 109     /// llvm.masked.scatter
 110     /// like gather, but more spicy, as it writes instead of reads
 111     pub(crate) fn simd_scatter<T, U, V>(val: T, ptr: U, mask: V);
 112
 113     // {s,u}add.sat
 114     pub(crate) fn simd_saturating_add<T>(x: T, y: T) -> T;
 115
 116     // {s,u}sub.sat
 117     pub(crate) fn simd_saturating_sub<T>(lhs: T, rhs: T) -> T;
 118
 119     // reductions
 120     // llvm.vector.reduce.{add,fadd}
 121     pub(crate) fn simd_reduce_add_ordered<T, U>(x: T, y: U) -> U;
 122     // llvm.vector.reduce.{mul,fmul}
 123     pub(crate) fn simd_reduce_mul_ordered<T, U>(x: T, y: U) -> U;
 124     #[allow(unused)]
 125     pub(crate) fn simd_reduce_all<T>(x: T) -> bool;
 126     #[allow(unused)]
 127     pub(crate) fn simd_reduce_any<T>(x: T) -> bool;
 128     pub(crate) fn simd_reduce_max<T, U>(x: T) -> U;
 129     pub(crate) fn simd_reduce_min<T, U>(x: T) -> U;
 130     pub(crate) fn simd_reduce_and<T, U>(x: T) -> U;
 131     pub(crate) fn simd_reduce_or<T, U>(x: T) -> U;
 132     pub(crate) fn simd_reduce_xor<T, U>(x: T) -> U;
 133
 134     // truncate integer vector to bitmask
 135     // `fn simd_bitmask(vector) -> unsigned integer` takes a vector of integers and
 136     // returns either an unsigned integer or array of `u8`.
 137     // Every element in the vector becomes a single bit in the returned bitmask.
 138     // If the vector has less than 8 lanes, a u8 is returned with zeroed trailing bits.
 139     // The bit order of the result depends on the byte endianness. LSB-first for little
 140     // endian and MSB-first for big endian.
 141     //
 142     // UB if called on a vector with values other than 0 and -1.
 143     #[allow(unused)]
 144     pub(crate) fn simd_bitmask<T, U>(x: T) -> U;
 145
 146     // select
 147     // first argument is a vector of integers, -1 (all bits 1) is "true"
 148     // logically equivalent to (yes & m) | (no & (m^-1),
 149     // but you can use it on floats.
 150     pub(crate) fn simd_select<M, T>(m: M, yes: T, no: T) -> T;
 151     #[allow(unused)]
 152     pub(crate) fn simd_select_bitmask<M, T>(m: M, yes: T, no: T) -> T;
 153 }