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

#[arcane]
fn multiply_add(_token: impl Has256BitSimd, 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]!
    let result = _mm256_add_ps(va, vb);
    let result = _mm256_mul_ps(result, result);

    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]);
    }
}

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 Has256BitSimd let functions accept any token that provides 256-bit SIMD (e.g., X64V3Token, Desktop64, X64V4Token).

Feature Flags

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

Re-exports

pub use tokens::SimdToken;

pub use tokens::Has128BitSimd;

pub use tokens::Has256BitSimd;

pub use tokens::Has512BitSimd;

pub use tokens::HasX64V2;

pub use tokens::HasX64V4;avx512

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

pub use tokens::X64V2Token;

pub use tokens::X64V3Token;

pub use tokens::Avx512Fp16Token;avx512

pub use tokens::Avx512ModernToken;avx512

pub use tokens::Avx512Token;avx512

pub use tokens::Server64;avx512

pub use tokens::X64V4Token;avx512

Modules

detectx86-64 or x86 or AArch64

Optimized feature detection macros.

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.

multiwidthmacros

Generate width-specialized SIMD code.

simd_fnmacros

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