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::{X64V3Token, SimdToken, arcane};

#[arcane(import_intrinsics)]
fn multiply_add(_token: X64V3Token, a: &[f32; 8], b: &[f32; 8]) -> [f32; 8] {
    // import_intrinsics brings all intrinsics + safe memory ops into scope
    let va = _mm256_loadu_ps(a);  // Takes &[f32; 8], not *const f32
    let vb = _mm256_loadu_ps(b);

    // Value-based intrinsics are SAFE inside #[arcane]! (Rust 1.85+)
    let result = _mm256_fmadd_ps(va, vb, va);

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

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

Auto-Imports

import_intrinsics is the recommended default — it injects archmage::intrinsics::{arch}::* into the function body, giving you all platform types, value intrinsics, and safe memory ops in one import:

use archmage::{X64V3Token, SimdToken, arcane};

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

The prelude (use archmage::prelude::*) is still available for module-level imports. See the prelude module for full documentation.

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 X64V3Token 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 sibling #[target_feature] function at the same scope, plus a safe wrapper that calls it. Since both live in the same scope, self and Self work naturally in methods. For trait impls, use #[arcane(_self = Type)] (nested mode). On wrong architectures, functions are cfg’d out by default; use #[arcane(stub)] for unreachable stubs.

#[rite(import_intrinsics)] 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(import_intrinsics)] should be your default. Use #[arcane(import_intrinsics)] only at entry points (the first call from non-SIMD code), and #[rite(import_intrinsics)] 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 X64V3Token (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 — import_intrinsics handles this by providing safe reference-based memory ops that shadow the pointer-based ones.

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

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.

intrinsics

Combined intrinsics: core::arch + safe_unaligned_simd in one namespace.

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.

autoversionmacros

Let the compiler auto-vectorize scalar code for each architecture.

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].