Crate archmage 

archmage

Safely invoke your intrinsic power, using the tokens granted to you by the CPU. Cast primitive magics faster than any mage alive.

archmage provides capability tokens that prove CPU feature availability at runtime, making raw SIMD intrinsics safe to call via the #[arcane] macro.

Quick Example

use archmage::{Desktop64, HasAvx2, SimdToken, arcane};
use archmage::mem::avx;  // Safe load/store (enabled by default)
use std::arch::x86_64::*;

#[arcane]
fn multiply_add(token: impl HasAvx2, a: &[f32; 8], b: &[f32; 8]) -> [f32; 8] {
    // Safe memory operations - references, not raw pointers!
    let va = avx::_mm256_loadu_ps(token, a);
    let vb = avx::_mm256_loadu_ps(token, b);

    // Value-based intrinsics are SAFE inside #[arcane]!
    let result = _mm256_add_ps(va, vb);
    let result = _mm256_mul_ps(result, result);

    let mut out = [0.0f32; 8];
    avx::_mm256_storeu_ps(token, &mut out, result);
    out
}

fn main() {
    // Desktop64: AVX2 + FMA + BMI2 (Haswell 2013+, Zen 1+)
    // CPUID check elided if compiled with -C target-cpu=native
    if let Some(token) = Desktop64::summon() {
        let result = multiply_add(token, &[1.0; 8], &[2.0; 8]);
    }
}

How It Works

Capability Tokens are zero-sized proof types created via summon(), which checks CPUID at runtime (elided if compiled with target features enabled).

The #[arcane] macro generates an inner function with #[target_feature], making intrinsics safe inside. The token parameter proves CPU support was verified.

Generic bounds like impl HasAvx2 let functions accept any token that provides AVX2 (e.g., Avx2Token, Desktop64, Server64).

Feature Flags

• std (default): Enable std library support
• macros (default): Enable #[arcane] attribute macro (alias: #[simd_fn])
• safe_unaligned_simd (default): Safe load/store via references (exposed as mem module)
• __composite: Higher-level ops (transpose, dot product) - unstable API
• __wide: Integration with the wide crate - unstable API

Re-exports

pub use tokens::SimdToken;

pub use tokens::CompositeToken;

pub use tokens::Has128BitSimd;

pub use tokens::Has256BitSimd;

pub use tokens::Has512BitSimd;

pub use tokens::HasFma;

pub use tokens::HasScalableVectors;

pub use tokens::HasAvx;

pub use tokens::HasAvx2;

pub use tokens::HasAvx512bw;

pub use tokens::HasAvx512f;

pub use tokens::HasAvx512vbmi2;

pub use tokens::HasAvx512vl;

pub use tokens::HasSse;

pub use tokens::HasSse2;

pub use tokens::HasSse41;

pub use tokens::HasSse42;

pub use tokens::HasNeon;

pub use tokens::HasSve;

pub use tokens::HasSve2;

pub use tokens::Avx2FmaToken;

pub use tokens::Avx2Token;

pub use tokens::Avx512Vbmi2Token;

pub use tokens::Avx512Vbmi2VlToken;

pub use tokens::Avx512bwToken;

pub use tokens::Avx512bwVlToken;

pub use tokens::Avx512fToken;

pub use tokens::Avx512fVlToken;

pub use tokens::AvxToken;

pub use tokens::Desktop64;

pub use tokens::FmaToken;

pub use tokens::Server64;

pub use tokens::Sse2Token;

pub use tokens::Sse41Token;

pub use tokens::Sse42Token;

pub use tokens::SseToken;

pub use tokens::X64V2Token;

pub use tokens::X64V3Token;

pub use tokens::X64V4Token;

pub use tokens::Arm64;

pub use tokens::NeonToken;

pub use tokens::Sve2Token;

pub use tokens::SveToken;

pub use tokens::Simd128Token;

Modules

composite__composite

Composite SIMD operations

detectx86-64 or x86 or AArch64

Optimized feature detection macros.

integrate__wide or safe_unaligned_simd

Integration layers for external crates

memsafe_unaligned_simd

Safe unaligned SIMD memory operations with token-based safety.

tokens

SIMD capability tokens

Macros

is_aarch64_feature_available

Checks if an AArch64 CPU feature is available, with compile-time optimization.

is_x86_feature_available

Checks if an x86 CPU feature is available, with compile-time optimization.

Attribute Macros

arcanemacros

Mark a function as an arcane SIMD function.

simd_fnmacros

Alias for [arcane] - mark a function as an arcane SIMD function.