mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-17 16:32:11 +01:00
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
190 lines
10 KiB
Markdown
190 lines
10 KiB
Markdown
# 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's `a +
|
|
b`, `a - b`, `a * b` and `a / b`.
|
|
- `f64_fma(a, b, c)`: C's `fma(a, b, c)`, i.e. `(a * b) + c` with a single
|
|
rounding.
|
|
- `f64_neg(a)`, `f64_abs(a)`: flip or clear the sign bit (C's `-a` and
|
|
`fabs(a)`).
|
|
- `f64_is_nan(a)`: 1 if `a` is a NaN, else 0.
|
|
- `f64_cmp(a, b)`: 0 if `a < b`, 1 if `a == b`, 2 if `a > 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
|
|
return `base.u32` instead of `base.bool` because the Wuffs-to-C code
|
|
generator cannot (yet) emit public functions that return a `base.bool`.
|
|
- `f64_min(a, b)`, `f64_max(a, b)`: exactly brotli's `BROTLI_MIN(double, a, b)`
|
|
and `BROTLI_MAX(double, a, b)`, which are `(a < b) ? a : b` and `(a > b) ? a :
|
|
b`. These are not IEEE 754 `minNum` / `maxNum`: given a NaN, or given `-0`
|
|
and `+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 for `u32`, and for 64-bit integers whose magnitude
|
|
is at most `1 << 53`).
|
|
- `f64_to_u64_trunc(a)`: C's `(uint64_t)a`, truncating towards zero. C only
|
|
defines this for `a` in the range `(-1, 1 << 64)`. Out of that range, this
|
|
function returns 0 for NaNs and negative values and `0xFFFF_FFFF_FFFF_FFFF`
|
|
for 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's `log2((double)v)`, see below. `log2_u64(0)` is `-inf`.
|
|
- `log2_f64(x)`: glibc's `log2(x)`, for any `x` (including subnormals, zeroes,
|
|
negative numbers, infinities and NaNs).
|
|
|
|
binary32:
|
|
|
|
- `f32_add`, `f32_sub`, `f32_mul`, `f32_div`: C's `a + b`, `a - b`, `a * b` and
|
|
`a / b` on `float`s (evaluated in `float` precision, i.e. C's
|
|
`FLT_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 their `f64`
|
|
counterparts.
|
|
- `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 subnormal `f32` 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 `fma`s, 3 multiplications and 6 additions / subtractions on the
|
|
main path; 13 `fma`s, 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.
|