archmage

Guide · Intrinsics browser · Archmage API · Magetypes API

Archmage lets you write SIMD code in Rust without unsafe — your crate keeps #![forbid(unsafe_code)] while calling intrinsics directly. It works on x86-64, AArch64, and WASM, is no_std + alloc (with std on by default for runtime CPU detection), and depends only on archmage-macros and safe_unaligned_simd. You pick a CPU tier, prove it's present once with summon(), and the type system keeps every intrinsic call sound.

Use archmage with the magetypes vector crate for portable vector kernels:

[dependencies]
archmage = "0.9.28"
magetypes = "0.9.28"

Process an image plane (exposure) or an audio buffer (gain), including a short scalar tail. The vector type is generic over the token selected by #[magetypes]; incant! chooses the CPU tier once outside the loop. No manual per-tier wrappers or raw pointers are needed.

Adapted from the zenfilters plane-scaling kernel; the complete production call chain and adaptation notes include pinned source links.

#![forbid(unsafe_code)]
use archmage::prelude::*;

#[magetypes(define(f32x8), v3, neon, wasm128, scalar)]
fn gain_impl(token: Token, plane: &mut [f32], gain: f32) {
    let factor = f32x8::splat(token, gain);
    let (chunks, tail) = f32x8::partition_slice_mut(token, plane);
    for chunk in chunks {
        (f32x8::load(token, chunk) * factor).store(chunk);
    }
    for value in tail {
        *value *= gain;
    }
}

pub fn apply_gain(plane: &mut [f32], gain: f32) {
    incant!(gain_impl(plane, gain), [v3, neon, wasm128, scalar])
}

For ISA-specific kernels, use #[arcane(import_intrinsics)] at the entry and #[rite(import_intrinsics)] for helpers. The intrinsics browser lists available reference-based memory operations. See the guide for both approaches, and reusable generic kernels for sharing algorithms across vector backends.

#[magetypes] is an archmage attribute. The magetypes crate supplies vector types such as f32x4<T> and f32x8<T>. define(f32x8) creates a local alias; explicit f32x8::<Token> uses the same implementation. Type and const generics can remain on the generated function, as in zenavif's sample/pixel kernels and zenanalyze's const-mode/input-type kernels.

Read the complete generic specialization example. For reusable backend-generic helpers, keep the generated feature-enabled caller: an inline attribute or token argument alone does not enable that context.

stub has been removed. incant! handles cross-architecture call-site guards. The reference forms with token and without token remain implemented; they respectively select by the held token's exact type and call a tokenless variant in a matching macro-managed context. See dispatch.

When a helper already has target features, from_context() constructs a token without runtime detection. Rust checks that the caller's features cover the token's requirements. It is not a baseline-callable unchecked constructor.

use archmage::prelude::*;
#[rite(v3)]
fn helper() -> bool {
    let _token = X64V3Token::from_context();
    true
}
#[arcane]
fn entry(_token: X64V3Token) -> bool { helper() }
#[cfg(target_arch = "x86_64")]
if let Some(token) = X64V3Token::summon() { assert!(entry(token)); }

This is a repository addition after 0.9.28. See from_context and token extraction. Use .v3() to extract a V3 token from a stronger proof; as_x64v3() instead checks whether the held token is exactly a V3 token.

Rust 1.89 is the minimum supported version. Archmage macros are always included; its macros feature is a compatibility no-op. std is enabled by default. Magetypes also defaults to w512, which supplies logical 512-bit types and polyfills. Optional avx512 adds native AVX-512 support; it does not detect the running CPU. Follow the feature-forwarding example when exposing features from your own crate.

Logical width does not change with the selected ISA: f32x8 stays eight lanes. Use supported backend lists; do not assume every stronger token implements every narrower backend. The ISA quirks and fixups explain NaNs, rounding, saturation, lane ordering, and measured repair costs. Transcendentals have a separate domain and precision discussion.

Compile the complete call chain, test supported tiers and scalar tails, and inspect optimized code under your supported baseline. See testing and production coverage.

MIT OR Apache-2.0

_{¹ pure-Rust, #![forbid(unsafe_code)] codecs, as of 2026}

zenbench · archmage · magetypes · enough · whereat · cargo-copter

Open source · @imazen · @lilith · lib.rs/~lilith