# x86-64 Tokens

## X64V2Token

**LLVM Level:** x86-64-v2
**Features:** SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT
**CPUs:** Intel Nehalem (2008)+, AMD Bulldozer (2011)+
**Register width:** 128-bit (XMM)

```rust
use archmage::{X64V2Token, SimdToken, arcane};

if let Some(token) = X64V2Token::summon() {
    process_sse(token, &data);
}
```

The V2 level adds the most commonly useful SSE extensions beyond baseline. If you only need 128-bit operations with SSE4.2, this is the token.

## X64V3Token / Desktop64

**LLVM Level:** x86-64-v3
**Features:** All V2 + AVX, AVX2, FMA, BMI1, BMI2, F16C, MOVBE
**CPUs:** Intel Haswell (2013)+, AMD Zen 1 (2017)+
**Register width:** 256-bit (YMM)

```rust
use archmage::{Desktop64, SimdToken, arcane};

// Desktop64 is the recommended baseline for most SIMD work
if let Some(token) = Desktop64::summon() {
    process_avx2(token, &data);
}
```

**Aliases:** `Desktop64` (preferred), `Avx2FmaToken` (legacy)

This is the sweet spot for most applications. AVX2 doubles throughput over SSE, FMA provides fused multiply-add, and virtually all desktop/laptop CPUs from the last decade support it. Use `Desktop64` as the name — it communicates intent better than `X64V3Token`.

### Key capabilities at this tier

- 256-bit integer operations (AVX2)
- Fused multiply-add (FMA3) — `a * b + c` in one instruction
- Bit manipulation (BMI1/BMI2) — `pdep`, `pext`, `tzcnt`, `lzcnt`
- Half-float conversion (F16C) — `f16 ↔ f32`

## X64V4Token / Server64 / Avx512Token

**LLVM Level:** x86-64-v4
**Features:** All V3 + AVX-512F, AVX-512BW, AVX-512CD, AVX-512DQ, AVX-512VL
**CPUs:** Intel Skylake-X (2017)+, AMD Zen 4 (2022)+
**Register width:** 512-bit (ZMM)
**Requires:** `avx512` cargo feature

```rust
#[cfg(feature = "avx512")]
use archmage::{Server64, SimdToken, arcane};

if let Some(token) = Server64::summon() {
    process_avx512(token, &data);
}
```

**Aliases:** `Server64` (preferred), `Avx512Token`

AVX-512 doubles width again to 512-bit and adds mask registers for predicated operations. The "VL" subset means these new instructions also work on 128/256-bit registers, so you get better codegen even at smaller widths.

### Frequency throttling

**Intel:** Heavy 512-bit usage can downclock the CPU by 100-200 MHz on some models. For sustained workloads, 256-bit may actually be faster due to higher clock speeds. Profile your workload.

**AMD Zen 4+:** AVX-512 is implemented as 2×256-bit internally. No significant throttling.

## X64V4xToken

**Features:** All V4 + VPOPCNTDQ, IFMA, VBMI, VNNI, BF16, VBMI2, BITALG, VPCLMULQDQ, GFNI, VAES
**CPUs:** Intel Ice Lake (2019)+, AMD Zen 4 (2022)+
**Requires:** `avx512` cargo feature

```rust
#[cfg(feature = "avx512")]
use archmage::{X64V4xToken, SimdToken};

if let Some(token) = X64V4xToken::summon() {
    // Modern extensions: VNNI for ML inference, VAES for crypto, etc.
}
```

Adds specialized instructions for ML inference (VNNI, BF16), cryptography (VAES, VPCLMULQDQ, GFNI), and bit manipulation (VBMI, BITALG). Only use if you specifically need these extensions.

## Avx512Fp16Token

**Features:** AVX-512 FP16
**CPUs:** Intel Sapphire Rapids (2023)+
**Requires:** `avx512` cargo feature

```rust
#[cfg(feature = "avx512")]
if let Some(token) = Avx512Fp16Token::summon() {
    // Native FP16 arithmetic (not just conversion)
}
```

Native half-precision float arithmetic. Distinct from F16C (which only converts between f16 and f32) — this does actual `f16` math in hardware.

## Downcasting

Higher tokens can be passed to functions expecting lower tokens. This is free — no runtime cost:

```rust
#[arcane]
fn needs_v3(token: Desktop64, data: &[f32; 8]) -> f32 { ... }

#[arcane]
fn has_v4(token: Server64, data: &[f32; 8]) -> f32 {
    // V4 is a superset of V3 — this just works
    needs_v3(token, data)
}
```
