Wuffs the Language has no floating point types, but some reference implementations (notably the brotli encoder) make decisions with double and float arithmetic and libm's log2. Porting them with byte-identical output needs bit-exact floating point results. This package implements f64 and f32 add, sub, mul, div, fma, comparisons, min/max, integer conversions and f64<->f32 conversions on bit patterns, with round-to-nearest-even, subnormals, infinities and NaNs, following the structure of Berkeley SoftFloat 3. It also ports glibc 2.39's x86-64 __log2_fma log2 implementation (the variant selected on CPUs with FMA and AVX2), following the shipped machine code's fused operations. Verification: test/c/std/softfloat.c checks every operation against the C compiler's native arithmetic on edge cases and random operands. The script/manual-test-softfloat-*.c programs run 10^8 random operations per operation group and compare log2_u64 against libm for every integer in [1, 2^32) plus 10^7 larger values; all with zero mismatches. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011NoosQNe7DKWnqDCBeqw1p
Soft Float
std/softfloat implements IEEE 754 binary64 (f64, C's double) and binary32
(f32, C's float) arithmetic using only integer operations. Wuffs the
Language has no floating point types, but some file formats' reference
implementations make decisions (e.g. a compressor choosing between encodings)
with floating point arithmetic. Porting them to Wuffs with byte-for-byte
identical output needs bit-exact floating point results. The motivating user is
a Wuffs port of the brotli encoder, whose cost models use double and float
arithmetic and libm's log2.
Values are passed around as their bit patterns: an f64 is a base.u64 and an
f32 is a base.u32, the same bits that C's memcpy from a double or
float would give. All of the functions are pure methods on the arith
struct, which has no state (other than Wuffs' usual initialization check).
// C example. The bits of 0.1 and 0.2 are 0x3FB999999999999A and
// 0x3FC999999999999A. Their sum is 0x3FD3333333333334 (0.30000000000000004).
wuffs_softfloat__arith sf;
wuffs_softfloat__arith__initialize(&sf, sizeof sf, WUFFS_VERSION, 0);
uint64_t sum = wuffs_softfloat__arith__f64_add(
&sf, 0x3FB999999999999A, 0x3FC999999999999A);
// Wuffs example, with a "sf : softfloat.arith" field in this struct.
sum = this.sf.f64_add(a: 0x3FB9_9999_9999_999A, b: 0x3FC9_9999_9999_999A)
API
binary64:
f64_add(a, b),f64_sub(a, b),f64_mul(a, b),f64_div(a, b): C'sa + b,a - b,a * banda / b.f64_fma(a, b, c): C'sfma(a, b, c), i.e.(a * b) + cwith a single rounding.f64_neg(a),f64_abs(a): flip or clear the sign bit (C's-aandfabs(a)).f64_is_nan(a): 1 ifais a NaN, else 0.f64_cmp(a, b): 0 ifa < b, 1 ifa == b, 2 ifa > b, 3 if unordered (either is a NaN).f64_eq,f64_ne,f64_lt,f64_le,f64_gt,f64_ge: C's==,!=,<,<=,>and>=, returning 1 (true) or 0 (false). Any comparison involving a NaN is false (except!=, which is true) and-0 == +0. These returnbase.u32instead ofbase.boolbecause the Wuffs-to-C code generator cannot (yet) emit public functions that return abase.bool.f64_min(a, b),f64_max(a, b): exactly brotli'sBROTLI_MIN(double, a, b)andBROTLI_MAX(double, a, b), which are(a < b) ? a : band(a > b) ? a : b. These are not IEEE 754minNum/maxNum: given a NaN, or given-0and+0, they return the second argument.f64_from_u64(a),f64_from_u32(a),f64_from_i64(a): C's(double)a, rounding to nearest (exact foru32, and for 64-bit integers whose magnitude is at most1 << 53).f64_to_u64_trunc(a): C's(uint64_t)a, truncating towards zero. C only defines this forain the range(-1, 1 << 64). Out of that range, this function returns 0 for NaNs and negative values and0xFFFF_FFFF_FFFF_FFFFfor large values, but callers should not rely on that.f64_to_f32(a): C's(float)a, rounding to nearest (ties to even), overflowing to infinity and underflowing to subnormals or zero.log2_u64(v): glibc'slog2((double)v), see below.log2_u64(0)is-inf.log2_f64(x): glibc'slog2(x), for anyx(including subnormals, zeroes, negative numbers, infinities and NaNs).
binary32:
f32_add,f32_sub,f32_mul,f32_div: C'sa + b,a - b,a * banda / bonfloats (evaluated infloatprecision, i.e. C'sFLT_EVAL_METHOD == 0, as on x86-64).f32_neg,f32_abs,f32_is_nan,f32_cmp,f32_eq,f32_ne,f32_lt,f32_le,f32_gt,f32_ge,f32_min,f32_max: like theirf64counterparts.f32_to_f64(a): C's(double)a, which is exact.f32_from_u32(a),f32_from_i32(a),f32_from_u64(a): C's(float)a, rounding to nearest.
All arithmetic rounds to nearest, ties to even (the default IEEE 754 rounding mode, and the only one implemented), and handles signed zeroes, subnormals (gradual underflow, no flush-to-zero), infinities and NaNs as IEEE 754 requires. Exception flags (inexact, overflow, etc.) are not reported.
NaNs: whenever IEEE 754 (and x86 hardware) produces a NaN, so does this
package, but the NaN's payload and sign bit are not guaranteed to match any
particular hardware. Invalid operations like 0 / 0 produce 0xFFF8... (x86's
"default NaN") and NaN operands are propagated (quietened), preferring the
first NaN operand.
Implementation
The f64 operations follow the structure of John Hauser's Berkeley SoftFloat
(release 3): unpack the sign, exponent and significand, handle special cases,
compute an exact or sticky-bit-augmented integer significand (with 10 extra
low bits for guard, round and sticky), then normalize and round in one place
(round_pack_f64). Multiplication and fused multiply-add compute exact 128-bit
products using 32-bit limbs (Wuffs has no 128-bit integers). Division is exact
integer long division, 11 quotient bits per (64-bit integer) division step,
with the final remainder as the sticky bit. Leading zero counts use a 256-entry
table.
The f32 add, sub, mul and div operations convert their operands exactly to
f64, perform the f64 operation and then round to f32. This double
rounding is innocuous: binary64's 53 bits of precision are more than `(2 * 24)
- 2
, which suffices for+,-,*and/(S. A. Figueroa, "When is double rounding innocuous?", ACM SIGNUM Newsletter, 1995). The tests confirm this against hardware, including for subnormalf32` results.
log2
The encoder being ported calls libm's log2((double)v) for integers v. glibc's
log2 is not correctly rounded (its documented maximum error is about 0.55
ULP), so a correctly rounded log2 would not match it for every input.
Instead, log2_f64 is a bit-exact port of the glibc function itself. (Note
that brotli's FastLog2(v) only calls log2 for v >= 256. For smaller v
it reads kBrotliLog2Table, whose entries are float literals widened to
double, which a port should copy verbatim rather than compute.)
Specifically, it ports glibc 2.39's __log2_fma, the variant of
sysdeps/ieee754/dbl-64/e_log2.c (by Szabolcs Nagy, from ARM's
optimized-routines) that glibc's x86-64 log2 IFUNC resolves to on CPUs with
FMA and AVX2. Compiling that C code with -mfma lets the compiler contract
some (but not all) a * b + c expressions into fused multiply-adds, which
changes the rounding, so the port follows the machine code of the shipped
Ubuntu glibc 2.39 libm.so.6, not just the C source. The exact sequence of
operations (9 fmas, 3 multiplications and 6 additions / subtractions on the
main path; 13 fmas, 3 multiplications and 4 additions / subtractions on the
separate near-1.0 path) was transcribed from its disassembly, and the
constants (InvLn2hi, InvLn2lo, the two polynomials and the 64-entry
invc/logc table) were read from its __log2_data and confirmed against
glibc's e_log2_data.c. Since every softfloat operation is correctly rounded,
the port then matches glibc by construction.
Other libm implementations (e.g. glibc's non-FMA variant on older x86-64 CPUs,
musl, macOS or MSVC) can produce different log2 results for some inputs. The
port matches the configuration listed above, which is the reference
configuration for the brotli port.
Verification
test/c/std/softfloat.c (run by wuffs test std/softfloat, under both gcc and
clang) checks every operation against the C compiler's own double and float
arithmetic on every pair of 34 (f64) or 23 (f32) edge-case values (±0,
±min/max subnormal, ±min normal, ±1, ±max, ±inf, NaNs, f32 rounding
boundaries, etc.), on those edge cases paired with pseudo-random values, and on
250,000 pseudo-random (deterministic xorshift64*) operand pairs biased towards
subnormals, huge values, nearby exponents (cancellation) and sparse or dense
fractions (exact results and rounding ties). It also checks brotli-specific
patterns such as (size_t)(x + 0.5), (float)FastLog2(n) + 2 and the
literal_costs Kahan summation. fma and log2 results are checked against
golden checksums; with wuffs test -mimic std/softfloat the same checksums are
also recomputed from libm's fma and log2.
script/manual-test-softfloat-ops.c runs much longer randomized comparisons
(by default 10⁸ iterations per group of operations) against the hardware and
libm. Result, on an x86-64 machine (gcc 13 -O2, no -mfma, no
-ffast-math):
f64_add 100000000 iterations, 0 mismatches, 8.0 seconds
f64_sub 100000000 iterations, 0 mismatches, 8.1 seconds
f64_mul 100000000 iterations, 0 mismatches, 8.0 seconds
f64_div 100000000 iterations, 0 mismatches, 11.7 seconds
f64_fma 100000000 iterations, 0 mismatches, 13.0 seconds
f64_cmp 100000000 iterations, 0 mismatches, 7.5 seconds
f64_predicates 100000000 iterations, 0 mismatches, 7.9 seconds
f64_min_max 100000000 iterations, 0 mismatches, 7.7 seconds
f32_add 100000000 iterations, 0 mismatches, 10.3 seconds
f32_sub 100000000 iterations, 0 mismatches, 10.3 seconds
f32_mul 100000000 iterations, 0 mismatches, 10.0 seconds
f32_div 100000000 iterations, 0 mismatches, 14.3 seconds
f32_cmp 100000000 iterations, 0 mismatches, 8.3 seconds
f32_predicates 100000000 iterations, 0 mismatches, 8.5 seconds
f32_min_max 100000000 iterations, 0 mismatches, 8.3 seconds
conversions 100000000 iterations, 0 mismatches, 23.3 seconds
brotli_patterns 25000000 iterations, 0 mismatches, 14.4 seconds
log2_f64 25000000 iterations, 0 mismatches, 8.0 seconds
PASS: 0 mismatches in total
(3 minutes 9 seconds in total, single-threaded)
script/manual-test-softfloat-log2.c compares log2_u64(v) to glibc's
log2((double)v) for every v in [1, 1 << 32) and for 10⁷ pseudo-random v
in [1 << 32, 1 << 53). Result (glibc 2.39, x86-64 with FMA and AVX2, 4
threads):
exhaustive: 4294967295 values checked, 0 mismatches, 376 seconds
random: 10000000 values checked, 0 mismatches, 379 seconds in total
PASS: 0 mismatches in total
(6 minutes 20 seconds wall clock in total)
No exception table is needed.