safe_unaligned_simd 0.2.4

Safe SIMD wrappers for unaligned load and store operations.
Documentation

safe_unaligned_simd

Build Status Crates.io Docs.rs

Safe wrappers for unaligned SIMD load and store operations.

The goal of this crate is to remove the need for "unnecessary unsafe" code when using vector intrinsics to access memory, with no alignment requirements.

Platform-intrinsics that take raw pointers have been wrapped in functions that receive Rust reference types as arguments.

MSRV: 1.88

Why use this crate?

This crate is compatible with runtime feature detection.

Unlike some other safe architecture intrinsic wrappers, this crate does not lock the user into #[cfg()]-gating SIMD code behind compile-time CPU target feature declaration.

[!NOTE]
To safely use platform intrinsics, users are responsible for ensuring that the CPU supports the intended target feature.

Feature detection can be done at compile-time by using #[cfg] attributes on functions or at runtime using an is_[arch]_feature_detected! macro from std::arch.

unsafe is needed to call into functions annotated with #[target_feature], but it's safe to call other functions with the same target features.

See the std::arch module documentation for a full explanation and the rustc 1.87 release notes for a simple example of runtime feature detection with fallback.

Supported target architectures

x86 / x86_64

  • sse, sse2, avx, avx512f, avx512vl, avx512bw, avx512vbmi2

Some functions have variants that are generic over Cell array types, which allow for mutation of shared references. See the cell module for an example.

Example function signatures:

#[target_feature(enable = "sse")]
fn _mm_storeu_ps(mem_addr: &mut [f32; 4], a: __m128);
#[target_feature(enable = "sse2")]
fn _mm_store_sd(mem_addr: &mut f64, a: __m128d);
#[target_feature(enable = "avx")]
fn _mm256_loadu2_m128(hiaddr: &[f32; 4], loaddr: &[f32; 4]) -> __m256;

Currently, there is no plan to implement gather/scatter or avx2 masked load/store intrinsics for this platform.

avx512 - AVX-512 intrinsics require rustc 1.89 or later.

aarch64 / arm64ec

  • neon

Example function signatures:

#[target_feature(enable = "neon")]
fn vld2_dup_s8(from: &[i8; 2]) -> int8x8x2_t;
#[target_feature(enable = "neon")]
fn vst1q_f64(into: &mut [f64; 2], val: float64x2_t);

wasm32

  • simd128

Example function signatures:

#[target_feature(enable = "simd128")]
pub fn v128_load8_splat<T: Is1ByteUnaligned>(t: &T) -> v128;
#[target_feature(enable = "simd128")]
pub fn v128_store<T: Is16BytesUnaligned>(t: &mut T, v: v128);

A note on creating mutable array references from slices

tl;dr: Use as_mut_array to avoid this bug, stable since 1.93.

Beware of accidentally creating mutable references to temporary arrays.

Rust will implicitly clone an array from a slice and return a mutable reference to that clone if not wrapped properly in parentheses.

// Valid mutable array reference creation
let out_data: &mut [u8; 4] = chunk[..4].as_mut_array().unwrap(); // since 1.93
let out_data: &mut [u8; 4] = (&mut chunk[..4]).try_into().unwrap();
let out_data = TryInto::<&mut [u8; 4]>::try_into(&mut chunk[..4]).unwrap();

// Incorrect creation of a mutable reference: this clones the chunk and returns
// a mutable reference to the copy. If we modify `out_data` after this point,
// the changes will not reflect back in our original `chunk` slice.
// 🚫🈲⛔❌ - Do not use the following line
let out_data = &mut chunk[..4].try_into().unwrap();

The now-stable as_mut_array sidesteps this issue entirely.

License

This crate is licensed under either

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.