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, SimdToken, arcane};
use std::arch::x86_64::*;

#[arcane]
fn multiply_add(_token: Desktop64, a: &[f32; 8], b: &[f32; 8]) -> [f32; 8] {
    // safe_unaligned_simd calls are SAFE inside #[arcane] - no unsafe needed!
    let va = safe_unaligned_simd::x86_64::_mm256_loadu_ps(a);
    let vb = safe_unaligned_simd::x86_64::_mm256_loadu_ps(b);

    // Value-based intrinsics are also SAFE inside #[arcane]!
    // FMA is available because Desktop64 = X64V3Token = AVX2+FMA
    let result = _mm256_fmadd_ps(va, vb, va);

    let mut out = [0.0f32; 8];
    safe_unaligned_simd::x86_64::_mm256_storeu_ps(&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]);
    }
}

The Prelude

use archmage::prelude::* gives you tokens, traits, macros, platform intrinsics, and SIMD types in one import. Value-based intrinsics like _mm256_add_ps are already safe inside #[arcane] since Rust 1.85.

For safe memory operations (load/store), import them explicitly from safe_unaligned_simd — the names overlap with core::arch and can’t resolve through a glob re-export:

use archmage::prelude::*;
use safe_unaligned_simd::x86_64::{_mm256_loadu_ps, _mm256_storeu_ps};

#[arcane]
fn load(_token: Desktop64, data: &[f32; 8]) -> __m256 {
    _mm256_loadu_ps(data)  // Safe! Takes &[f32; 8], not *const f32.
}

See the prelude module for full documentation of what’s included.

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.

Use concrete tokens like Desktop64 (AVX2+FMA) or X64V4Token (AVX-512). For generic code, use tier traits like HasX64V2 or HasX64V4.

Feature Flags

• std (default): Enable std library support
• macros (default): Enable #[arcane] attribute macro (alias: #[arcane])
• avx512: AVX-512 token support

Re-exports

pub use tokens::CompileTimeGuaranteedError;

pub use tokens::DisableAllSimdError;

pub use tokens::IntoConcreteToken;

pub use tokens::SimdToken;

pub use tokens::dangerously_disable_tokens_except_wasm;

pub use tokens::Has128BitSimd;

pub use tokens::Has256BitSimd;

pub use tokens::Has512BitSimd;

pub use tokens::HasX64V2;

pub use tokens::HasX64V4;

pub use tokens::HasNeon;

pub use tokens::HasNeonAes;

pub use tokens::HasNeonSha3;

pub use tokens::Arm64;

pub use tokens::Avx2FmaToken;

pub use tokens::Desktop64;

pub use tokens::NeonAesToken;

pub use tokens::NeonCrcToken;

pub use tokens::NeonSha3Token;

pub use tokens::NeonToken;

pub use tokens::ScalarToken;

pub use tokens::Wasm128Token;

pub use tokens::X64V2Token;

pub use tokens::X64V3Token;

pub use tokens::Avx512Fp16Token;

pub use tokens::Avx512ModernToken;

pub use tokens::Avx512Token;

pub use tokens::Server64;

pub use tokens::X64V4Token;

Modules

detectx86-64 or x86 or AArch64

Optimized feature detection macros.

prelude

One import for everything you need to write SIMD with archmage.

testingstd

Test utilities for exhaustive SIMD token permutation testing.

tokens

SIMD capability tokens

Macros

incantmacros

Dispatch to platform-specific SIMD variants.

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.

simd_routemacros

Legacy alias for incant!.

Attribute Macros

arcanemacros

Mark a function as an arcane SIMD function.

magetypesmacros

Generate platform-specific variants from a function by replacing Token.

ritemacros

Annotate inner SIMD helpers called from #[arcane] functions.