acpu — API specification

pure Rust driver for Apple Silicon CPU compute. direct access to every useful compute unit in M1–M4: matrix coprocessor, vector engine, numeric extensions, atomics, memory system, performance counters. zero external dependencies — only inline assembly and system calls.

organs

six groups. each maps to a compute unit or system resource in silicon.

concepts

probe — chip detection

runtime identification of Apple Silicon chip and its capabilities. all detection is zero-cost after first call (cached in static).

chip

features

system mapping

matrix — AMX coprocessor

Apple Matrix coprocessor. undocumented. three register banks: X (8 × 512-bit), Y (8 × 512-bit), Z (8 × 512-bit). total: 4608 bytes of matrix register state.

AMX instructions live in reserved ARM encoding space at 0x201000 + (opcode << 5) + operand. emitted via .word in inline assembly.

context lifecycle

AMX_SET/AMX_CLR are bracketing instructions. all AMX operations must occur between set and clr. context is per-thread.

encoding

AMX_SET: NOP; NOP; NOP; .word (0x201000 + (17 << 5) + 0)
AMX_CLR: NOP; NOP; NOP; .word (0x201000 + (17 << 5) + 1)

register model

registers are typed wrappers: XRow(0) .. XRow(7).

Z rows are accumulators — fma/mac results land here.

load / store

encoding

operand GPR holds: ptr | (row_index << 56) for load/store.

compute

encoding (compute)

operand GPR holds bit-packed config:

fma32:  bits[4:0]  = x_offset
        bits[8:6]  = y_row_select (0–7)
        bits[19:10] = z_row
        bit[27]    = accumulate mode (1 = +=, 0 = =)
opcode: 10 (fma32), 11 (fma16), 12 (fmabf16), 13 (mac16)
M3+:    14 (matint)
M4+:    15 (vecfp), 16 (vecint), 8 (extrh), 9 (extrv)

exact bit layout per opcode documented in corsix/amx Instructions.md.

fma geometry

X row:  64 bytes = 16 × fp32  or  32 × fp16
Y row:  64 bytes = 16 × fp32  or  32 × fp16
Z row:  64 bytes = 16 × fp32

fma32:  Z[16×16] += outer_product(X[16], Y[16])
fma16:  Z[16×16] += outer_product(X[32→16], Y[32→16])  (fp16 in, fp32 accum)

one fma32 = 256 fp32 multiply-accumulates per instruction.

vector — NEON (AdvSIMD)

ARM Advanced SIMD. 32 registers × 128 bits. documented, stable, available on all AArch64. accessed via core::arch::aarch64 intrinsics or inline assembly.

acpu exposes NEON through typed kernel functions, not raw intrinsics. the user calls acpu::exp(slice), not vfmaq_f32(a, b, c).

register file

v0–v31:  128-bit SIMD registers
  as f32:  4 lanes  (float32x4_t)
  as f16:  8 lanes  (float16x8_t)
  as f64:  2 lanes  (float64x2_t)
  as i32:  4 lanes  (int32x4_t)
  as i16:  8 lanes  (int16x8_t)
  as i8:  16 lanes  (int8x16_t)
  as u8:  16 lanes  (uint8x16_t)

operations used

not a full NEON reference — only the instruction classes acpu uses.

numeric — precision and format extensions

extensions that operate within the NEON register file but add specialized data formats. each gated by a feature flag in caps.

fp16 (FEAT_FP16) — M1+

native half-precision arithmetic in NEON. not just conversion — actual compute in 16-bit.

bulk conversion (NEON vectorized)

bf16 (FEAT_BF16) — M2+

brain float: 8-bit exponent, 7-bit mantissa. same range as fp32, less precision. preferred for training.

bulk conversion

dotprod (FEAT_DotProd) — M1+

INT8 dot product. four int8 × int8 multiplies accumulated into one int32. the foundation of quantized inference.

i8mm (FEAT_I8MM) — M2+

INT8 matrix multiply. 2×8 × 8×2 → 2×2 int32. eight times the throughput of scalar int8 multiply.

fcma (FEAT_FCMA) — M1+

complex number arithmetic in NEON registers. pairs of floats treated as (real, imag).

used for: FFT, complex-valued attention, signal processing.

rdm (FEAT_RDM) — M1+

rounding doubling multiply. fixed-point DSP without overflow.

used for: fixed-point quantization, audio DSP.

sync — atomics, ordering, affinity

concurrency primitives for parallel compute across P-cores and E-cores. not for general concurrent programming — specifically for multi-threaded GEMM, producer-consumer pipelines, and work-stealing.

lse atomics (FEAT_LSE) — M1+

hardware atomic operations. single instruction, no LL/SC loop. essential for lock-free thread pool in parallel GEMM.

Rust mapping

LSE atomics are used automatically by LLVM on AArch64 when -Ctarget-feature=+lse is set (default on macOS). std::sync::atomic operations compile to single LSE instructions. acpu does not wrap these — Rust already does the right thing.

acpu exposes LSE through the sync module only where the standard library is insufficient (e.g. custom fence patterns, spin-wait with WFE).

lrcpc (FEAT_LRCPC) — M1+

load-acquire with weaker ordering. faster than full acquire barrier for producer-consumer patterns.

used between pack-thread and compute-thread in parallel GEMM.

memory barriers

wait/wake pair: spin-waiting threads use WFE to sleep until producer calls SEV. saves power and thermal headroom during parallel GEMM synchronization.

core affinity

pin threads to performance or efficiency cores.

system mapping

note: macOS QoS classes influence core scheduling but do not guarantee hard affinity. USER_INTERACTIVE strongly prefers P-cores. BACKGROUND strongly prefers E-cores. for inference, pin all compute threads to P-cores.

prefetch

used in GEMM packing loops to hide memory latency.

pulse — performance counters

Apple Performance Monitoring Unit. undocumented kpc_* API in /usr/lib/libkperf.dylib. gives cycle-accurate measurements without Instruments or dtrace.

accessed via dlopen at runtime (same pattern as rane uses for AppleNeuralEngine.framework).

counters

context

system mapping

usage pattern

let mut pulse = Counters::new(&[Counter::Cycles, Counter::L1dMisses])?;
pulse.start();
let a = pulse.read();
// ... compute ...
let b = pulse.read();
let counts = pulse.elapsed(&a, &b);
println!("cycles: {}, L1 misses: {}", counts.cycles, counts.l1d_misses);
pulse.stop();

kernels — high-level compute operations

safe, auto-dispatching operations. each kernel picks the fastest available path based on caps:

AMX  →  NEON+extension  →  NEON scalar  →  fallback

dispatch is resolved at first call and cached.

gemm

dispatch:

• matmul_f32: AMX fma32 → NEON fmla
• matmul_f16: AMX fma16 → NEON FP16 fmla
• matmul_bf16: AMX fmabf16 → NEON bfmmla → NEON bfdot
• matmul_i8: NEON I8MM smmla → NEON DotProd sdot → scalar

math (elementwise, vectorized)

all operate in-place on fp32 slices. NEON vectorized, 4-wide minimum, tail-masked.

convert (bulk, vectorized)

reduce

errors

ChipNotSupported         not Apple Silicon
AmxSetFailed             AMX_SET instruction failed
AmxOpFailed(String)      AMX operation error
PmuNotAvailable          libkperf.dylib not found or kpc denied
PmuConfigFailed(String)  counter configuration rejected
FeatureNotAvailable(Feature)  required extension absent on this chip
AffinityFailed(String)   QoS class change failed

execution model

• AMX is per-thread. each thread needs its own Matrix
• AMX set/clr are cheap (~1 cycle). open a context per GEMM call, not per thread lifetime
• NEON registers are callee-saved (v8–v15). inline asm must respect this
• all kernels are synchronous. no async dispatch model (this is CPU, not GPU)
• parallel GEMM: partition M dimension across threads, each thread gets own Matrix
• sync between threads: WFE/SEV + LSE atomics (no mutexes in hot path)
• memory: all buffers are caller-owned slices. acpu allocates nothing on heap
• all public functions are #[inline] or dispatch through cached function pointers

driver stack

acpu crate
  → inline asm (.word for AMX, intrinsics for NEON)
  → sysctl (chip detection)
  → libkperf.dylib dlopen (PMU counters)
  → pthread (core affinity)
  → no frameworks, no ObjC, no C compiler

module map

src/
  lib.rs              pub API re-exports, CpuError
  probe.rs            Chip, Features, Feature, scan()
  matrix/
    mod.rs            Matrix lifecycle (set/clr)
    ops.rs            load/store, fma32/fma16/fmabf16/mac16
    regs.rs           XRow, YRow, ZRow typed wrappers
    asm.rs            raw .word encoding macros
  vector/
    mod.rs            NEON kernel dispatch
    math.rs           exp, log, tanh, sigmoid, gelu, silu
    reduce.rs         sum, max, min, dot, length
    softmax.rs        softmax, normalize
    rope.rs           rotary positional embedding
  numeric/
    fp16.rs           FP16 arithmetic + bulk convert
    bf16.rs           BF16 ops + bulk convert
    quant.rs          DotProd, I8MM, quantize/dequantize
    complex.rs        FCMA complex mul-acc
  sync/
    mod.rs            barriers, wait/wake
    affinity.rs       pin_p_core, pin_e_core
    prefetch.rs       PRFM wrappers
  pulse/
    mod.rs            Counters, Counter, Snapshot
    ffi.rs            dlopen libkperf, kpc_* symbols
  gemm.rs             matmul_f32, matmul_f16, matmul_bf16, matmul_i8 (auto-dispatch)
  convert.rs          cast_* bulk conversion (re-exports from numeric)
  probe/
    main.rs           acpu_probe binary — exercise every organ

file limit: 500 lines per source file. split if exceeded.

license

cyber license: don't trust. don't fear. don't beg.