ISA Quirks and Fixups

A portable vector type guarantees a lane count; it does not guarantee one machine instruction, identical floating-point results, or availability under every token. This page distinguishes uniform contracts we enforce from current differences callers must account for. It covers the generic magetypes::simd::generic API, primarily f32x4, f32x8, and f32x16; do not transfer these tables to legacy architecture-specific wrappers or other conversion methods without checking them.

The floating-point tables assume the normal floating-point environment. Changing rounding modes or enabling flush-to-zero can change results. NaN means a NaN result, without a guarantee about its payload or sign.

Runtime fixups: exact calls and extra work

These are source-level lowerings, not universal cycle counts. Constants can fold away, invariant count preparation can move out of a loop, and wider polyfills repeat the native sequence. The measured table below identifies its CPU, width, compiler, baseline, and workload.

abs_diff, madd_adjacent, pairwise_widen_add, saturating arithmetic, and reduce_add_u32 sometimes need several instructions because an ISA lacks that operation. That is emulation of the operation, not an extra check imposed by a safe wrapper. round() enforces ties-to-even; the scalar fallback may need rounding code while hardware backends have native rounding instructions.

Measured overhead and recorded values

Open the interactive ISA explorer to filter by CPU, ISA, width, and exact call; inspect decimal values and raw bits; or download the JSON with every paired timing round. It is an offline record viewer and does not claim to execute NEON or AVX-512 in your browser.

The first measurements use 2,048 ordinary positive f32 values, release builds, no target-cpu override, and nine alternating AB/BA rounds. Timings include loads, stores, and the loop. The percentage is the median of paired ratios; MAD describes within-process variation, not a confidence interval. These are throughput costs in this kernel, not instruction latencies or predicted application slowdowns. Different widths cannot be compared as equal work per vector. Exceptional inputs are sampled separately, not included in timing.

The M4 identity controls show measurement variation, not a benefit from adding or removing code. Integer clamp/permutation costs above are currently supported by source/codegen inspection; isolated baseline-versus-fixup timings have not yet been recorded for them. Existing int_uniform_shift benches compare runtime versus constant counts, which also changes instruction selection and is not an isolated fixup measurement. Do not label that ratio a clamp cost.

Reproduce the sample/timing run with cargo run --release -p magetypes --example isa_fixups --features avx512. Use -- --samples-only for Wasmtime/QEMU. Capture rustc -Vv and CPU identification before stdout, then collect runs with python3 xtask/isa_evidence.py CPU=run.txt --output docs/site/static/isa-explorer/data.json. The collector validates array shapes, bit encodings, and saturating-conversion outputs against an independent scalar oracle. The dataset records its library revision and probe source hash. Store actual outputs per CPU; do not synthesize ISA results from a table or report emulator timings as hardware performance.

Results we make portable

Runtime byte shifts are deferred; constant byte shifts remain available. x86 implements constant byte shifts with wider shifts and masks because it has no native byte-shift instruction. No new runtime fixups are introduced by the trait consolidation.

Float-to-integer conversion: choose the contract

to_i32 truncates finite, in-range values. Its name does not promise Rust's saturating as i32 behavior for exceptional inputs. to_i32_saturating does.

The saturating variant adds compare/select fixups on x86; NEON/WASM/scalar already have the requested conversion behavior. A caller that has proved the input range may prefer to_i32. This table does not describe to_i32_round, f64 conversions, or pixel-packing helpers.

Current floating-point differences we do not fix up

These are observable implementation differences, including differences between widths on the same backend. They are compatibility constraints to review, not recommendations to depend on unusual NaN behavior.

x86 min/max select the second operand when a NaN is involved. NEON uses vminq/vmaxq, and WASM uses min/max, which propagate NaNs. Smaller scalar vectors use Rust's numeric min/max; scalar f32x16 currently uses comparisons and selects the second operand when the comparison is false. Rust's numeric min/max ignore a single NaN and do not promise which equal signed zero is returned. The scalar contract is documented by Rust.

For an unordered not-equal mask, invert simd_eq; do not assume simd_ne currently has identical NaN behavior on every tier. If NaNs or signed zeros matter to min/max or negation, handle them explicitly. Follow-up candidates are an unordered x86 comparison predicate and sign-bit XOR negation; both need their own semantic and codegen review rather than silently changing a published operation here.

Fused arithmetic and reductions

mul_add_relaxed and mul_sub_relaxed round once on x86 v3/v4 and NEON, and twice (multiply, then add) on the scalar backend and strict WASM; relaxed WASM follows the engine's rounding choice. mul_add_fused and mul_sub_fused round once on every backend, so their results match bit for bit. NaN payloads and signs remain unspecified. One and two roundings can differ near cancellation or intermediate overflow.

On relaxed WASM, mul_add_relaxed emits relaxed multiply-add directly, without a probe, cached load, or runtime branch. A relaxed-SIMD token proves instruction availability, not fusion: the relaxed-SIMD specification permits either rounding behavior, but requires each environment to make one fixed choice per operator. mul_add_fused relies on that: on first use it evaluates one input whose fused and unfused results differ, caches the answer per element type, and then uses relaxed madd on engines that fuse and the software path on engines that round twice. The result is the same either way. The probe and the f32 software path are inline with no call site, and the f64 software path sits behind a single call: any call site in a loop made wasmtime keep loop state in memory, even when the call never ran. With wasmtime 40 on a Ryzen 9 9950X3D, a fusing engine runs f32x4 in 0.08× (chain) and 0.15× (stream) of the software path's time, within 5–45% of bare relaxed madd; engines that round twice measured the same as plain software (layout experiment). V8 (node 26.7.0) made the same choice in its baseline and optimizing tiers, with and without host FMA (tier check). Modules built with relaxed SIMD still require an engine that supports those instructions; the arithmetic fallback does not make such modules loadable on older engines.

V8's x86 QFMA lowering selects hardware FMA when the CPU exposes FMA3, otherwise separate multiply and add (source checked 2026-09-27). This choice occurs during code generation, not as a per-operation branch in the generated kernel. Thus relaxed-SIMD support alone does not imply fusion on older CPUs or VMs that hide FMA.

Single rounding has a price where the hardware cannot fuse, and mul_add_relaxed does not pay it. Measured against a * b + c on 1,024 L1-resident vectors (stream) and on 1,024 dependent steps (chain); records: per backend, WASM.

Portable software fallbacks work on whole lane arrays without a branch per lane, so LLVM vectorizes them. f32 computes the exact product in f64, adds once and narrows; a lane goes to the exact round-to-odd path only when the f64 sum is halfway between two f32 values or lies in f32's subnormal range, the only cases where narrowing can round differently. f64 uses Dekker's product and TwoSum, rounds to nearest, and sends lanes whose final addition lands exactly halfway after an inexact inner addition, or that leave the safe exponent range, to an exact integer implementation ported from libm 0.2.16. They do not probe the CPU.

Scalar helpers use the FMA instruction when the build guarantees it: with std, AArch64 NEON or x86 FMA-enabled builds use Rust's mul_add; without std, V3 or NEON target features let a compile-time token reach the intrinsic. For f64 on x86_64 with std, a cached runtime check (archmage's V3 token, once per call) also selects the instruction on CPUs that have it: on a Ryzen 9 7900X and a Core Ultra 7 265K that took 0.09–0.43× the software path's time. f32 stays in software without a compile-time guarantee, because its vectorized software path measured as fast as a per-call hardware path or faster. Results are identical on every path. Native vector backends retain their token-proven FMA intrinsics. Strict WASM portable operations use software; relaxed WASM uses the engine's madd when the cached probe shows it fuses. The bit-exact contract assumes round-to-nearest and gradual underflow; NaN payloads and signs are unspecified.

CI checks committed expected bits generated with Python exact rational arithmetic, independently of std/libm, alongside the broader randomized suite. The contract runs on native x86/ARM, cross targets, WASM and Miri, in std and no_std configurations. Bare arithmetic is checked separately against its backend's fused, unfused, or relaxed behavior.

The scalar rows above measure earlier implementations. Before the portable software rounding fixes, an assembly comparison with Rust 1.99 checked the f32/f64 helpers and portable add/sub at all six scalar vector widths: each matched the corresponding direct libm expression on baseline x86-64, x86-64-v3, AArch64, and WASM after normalizing local label numbers. That establishes code-generation equivalence for those fixtures, not a runtime speedup. Native WASM SIMD's f32 software kernel still rounds to odd. The scalar helpers now use the array algorithm above and no longer match direct libm. See the relaxed SIMD investigation for the independent counterexample and measured distinction between bare relaxed madd and portable software fusion.

On a native FMA backend, mul_add_relaxed is one FMA: the faster choice for dependency chains through the multiplicand, such as Horner polynomials. When the chain runs only through the addend (a reduction with one accumulator), a separate a * b + acc takes 0.49–0.80× the time of FMA on Arrow Lake and Zen 4, because the add finishes sooner than an FMA; with enough independent accumulators the two are equal (measurements; loop patterns and examples: Reductions). Use mul_add_fused where identical results on every backend matter more than speed. mul_add and mul_sub are deprecated so that backend-dependent rounding is an explicit choice; in magetypes 0.11 they become the fused operations.

The generic transcendentals (exp2_midp, log2_midp, pow_midp and the rest) evaluate their polynomials with mul_add_relaxed, so their last bits depend on the backend. Over every f32 input, 0.3–0.8% of exp/log results differ by 1–3 ULP between the scalar backend and AVX2, and about 11% of pow_midp(2.4) results by up to 178 ULP; the maxima against the true value move by at most 0.43 ULP (record).

Floating-point reductions retain backend-dependent association. Single-rounding multiply-add does not make an entire algorithm independent of reduction order.

Reciprocal and reciprocal square root

Observed contract gap: on Ryzen 7950X, V3 f32x4::recip() maps f32::MAX (0x7f7fffff) to +0 and -f32::MAX to -0. Their correctly rounded reciprocals are nonzero subnormals (0x00200000 / 0x80200000). Thus the current rustdoc promise that only subnormal inputs are unspecified is too broad: normal inputs with subnormal reciprocal outputs can also lose the ≤4 ULP claim. This is recorded as a gap, not silently treated as a conforming result. recip_portable() supplies the division result. A repair to the working tier needs a separate accuracy/codegen/performance review; this documentation change does not add runtime branches or alter the implementation.

On x86 128/256-bit vectors, special-case repair uses comparison and blending; native AVX-512 uses fixup instructions. NEON arranges fused refinement to avoid forming an invalid intermediate multiply. The _portable variants use division (and square root for rsqrt). Raw _approx variants have weaker guarantees; do not infer their special-case behavior from the working-tier table. Transcendental approximation domains and fixups are documented separately in Transcendentals.

Portability of cost and availability

Executable evidence

The concrete floating-point examples are asserted in the isa_quirks module of magetypes/tests/doc_examples.rs, across scalar, x86, NEON, and WASM runners. Integer contracts are covered by int_widen_narrow.rs, int_uniform_shift_saturating.rs, and the constant-shift boundary tests. convert_saturating.rs, precise_reciprocals.rs, and sigmoid_silu.rs cover their respective fixups. xtask/codegen.py checks per-ISA consumer assembly, direct storage access, and integer formulations. These gates check the tested shapes and contexts; they do not establish optimal codegen for every possible caller.