std1.0.0-beta-7 SafeC docs

Module ml::float16

#include <std/ml/float16.h> source

Functions

f32_to_fp16Converts a float32 value to its IEEE 754 binary16 (fp16) bit pattern, round-to-nearest-even. Overflow rounds to +/-infinity; NaN inputs produce a valid (payload-losing but still-NaN) fp16 NaN pattern.
fp16_to_f32Converts an fp16 bit pattern back to float32. Exact -- every fp16 value (including subnormals, infinities, and NaNs) is exactly representable in float32.
f32_to_bf16Converts a float32 value to its bfloat16 bit pattern, round-to- nearest-even (a truncation of float32's top 16 bits, since bf16 shares float32's exponent width exactly). NaN inputs are kept as NaN (a mantissa bit is forced nonzero if truncation would otherwise zero it out, which would silently turn a NaN into an infinity).
bf16_to_f32Converts a bf16 bit pattern back to float32. Exact and lossless (a zero-extension into the low 16 mantissa bits) -- every bf16 value is exactly representable in float32 by construction.
half_cpu_features
half_cpu_features_name"F16C, AVX512-BF16" and the like; "none" for none.
f32_to_fp16_bulkBit-identical to the scalar functions above for every input except NaN payloads (the hardware keeps more of a NaN's payload; a NaN stays a NaN). x86-64 uses F16C for fp16 and, where present, AVX512-BF16 for float32 -> bf16 (16 values per instruction; a block holding a float32 subnormal, which that instruction flushes to zero, is converted in software instead). AArch64 uses FCVTL / FCVTN for fp16. bf16 -> float32 is a shift and float32 -> bf16 an integer rounding everywhere else, both in loops the compiler vectorizes. Arrays of 256K values or more are split across std/sync/parallel.h's thread pool.
fp16_to_f32_bulk
f32_to_bf16_bulk
bf16_to_f32_bulk
fp16_to_bf16_bulkBetween the two 16-bit formats (through float32, rounded to nearest even): fp16 -> bf16 loses 3 mantissa bits, bf16 -> fp16 rounds to fp16's range (overflow to infinity, small values to subnormals or zero).
bf16_to_fp16_bulk

Macros

HALF_CPU_F16_CONVERTfp16 conversion is in every x86-64 CPU since 2012 (F16C) and in every AArch64 core; bf16 is newer and optional -- x86 AVX512-BF16 (Cooper Lake, Sapphire Rapids, Zen 4 and later) and Arm FEAT_BF16 (Armv8.6: Neoverse V1 / N2, Apple M2 and later) -- and so is fp16 arithmetic (AVX512-FP16; Arm FEAT_FP16). Detected once at run time (cpuid + xgetbv on x86-64, getauxval on Linux AArch64, sysctl on Apple). SAFEC_HALF=soft reports none and makes the bulk conversions below use the portable code.
HALF_CPU_F16_ARITHfp16 arithmetic (AVX512-FP16 / FEAT_FP16)
HALF_CPU_BF16_CONVERTfloat32 -> bf16 instructions (AVX512-BF16 / FEAT_BF16)
HALF_CPU_BF16_DOTbf16 dot products (VDPBF16PS / BFDOT)