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). See token-registry.toml for the complete mapping of tokens to CPU features.

The #[arcane] and #[rite] macros read the token type from your function signature to determine which #[target_feature] attributes to emit. A function taking Desktop64 gets #[target_feature(enable = "avx2,fma,...")]. A function taking X64V4Token gets AVX-512 features. The token type is the feature selector.

Descriptive aliases are available for AI-assisted coding: #[token_target_features_boundary] = #[arcane], #[token_target_features] = #[rite], dispatch_variant! = incant!.

#[arcane] generates a wrapper: an outer function that calls an inner #[target_feature] function via unsafe. This wrapper is how you cross into SIMD code without writing unsafe yourself — but it also creates an LLVM optimization boundary. #[rite] applies #[target_feature] + #[inline] directly to the function, with no wrapper and no boundary, but can only be called from code that already has matching features.

#[rite] should be your default. Use #[arcane] only at entry points (the first call from non-SIMD code), and #[rite] for everything called from within SIMD code. Passing the same token type through your call hierarchy keeps every function compiled with matching features, so LLVM inlines freely.

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

Safety

Since Rust 1.85, value-based SIMD intrinsics (arithmetic, shuffle, compare, bitwise) are safe inside #[target_feature] functions. Only pointer-based memory operations remain unsafe — use safe_unaligned_simd for those.

Downstream crates can use #![forbid(unsafe_code)] when combining archmage tokens + #[arcane]/#[rite] macros + safe_unaligned_simd for memory operations.

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::HasArm64V2;

pub use tokens::HasArm64V3;

pub use tokens::HasNeon;

pub use tokens::HasNeonAes;

pub use tokens::HasNeonSha3;

pub use tokens::Arm64;

pub use tokens::Arm64V2Token;

pub use tokens::Arm64V3Token;

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::Sse2Token;

pub use tokens::Wasm128RelaxedToken;

pub use tokens::Wasm128Token;

pub use tokens::X64CryptoToken;

pub use tokens::X64V1Token;

pub use tokens::X64V2Token;

pub use tokens::X64V3CryptoToken;

pub use tokens::X64V3Token;

pub use tokens::Avx512Fp16Token;

pub use tokens::Avx512Token;

pub use tokens::Server64;

pub use tokens::X64V4Token;

pub use tokens::X64V4xToken;

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

dispatch_variantmacros

Descriptive alias for incant!.

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.

token_target_featuresmacros

Descriptive alias for [rite].

token_target_features_boundarymacros

Descriptive alias for [arcane].