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 determine which #[target_feature] attributes to emit. #[arcane] reads the token type from the function signature. #[rite] works in three modes: token-based (reads the token parameter), tier-based (#[rite(v3)] — no token needed), or multi-tier (#[rite(v3, v4, neon)] — generates suffixed variants fn_v3, fn_v4, fn_neon).

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] applies #[target_feature] + #[inline] directly to the function, with no wrapper and no boundary. It works in three modes:

• Token-based (#[rite]): reads the token from the function signature
• Tier-based (#[rite(v3)]): specifies features via tier name, no token needed
• Multi-tier (#[rite(v3, v4, neon)]): generates a suffixed copy for each tier

#[rite] should be your default. Use #[arcane] only at entry points (the first call from non-SIMD code). Token-based and tier-based produce identical output — the token form can be easier to remember if you already have the token in scope. Multi-tier generates one function per tier, each compiled with different #[target_feature] attributes.

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
• avx512: AVX-512 token support

Macros (#[arcane], #[rite], incant!, etc.) are always available.

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;Deprecated

pub use tokens::Has256BitSimd;Deprecated

pub use tokens::Has512BitSimd;Deprecated

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;Deprecated

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_variant

Descriptive alias for incant!.

incant

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_route

Legacy alias for incant!.

Attribute Macros

arcane

Mark a function as an arcane SIMD function.

autoversion

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

magetypes

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

rite

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

token_target_features

Descriptive alias for [rite].

token_target_features_boundary

Descriptive alias for [arcane].