Files
wuffs/std/softfloat
Claude 044437a8ec std/brotli: speed up the encoder at qualities 10 and 11, byte-exactly
- encode_float.wuffs: package-private fast paths for the f32/f64 add, sub,
  mul, compare and int conversion calls in the encoder's hot loops. Calling
  std/softfloat is a cross-package public call (a receiver check, never
  inlined). Each fast path returns exactly the softfloat result and falls
  back to it for the uncommon cases. script/manual-test-brotli-float.c
  cross-checks them against hardware float and double arithmetic.
- Zopfli update_nodes: compute a length's cost only when its copy code
  changes, hoist the distance cache values and the continuation byte, and
  use a table for small int to f32 conversions.
- FindBlocks: memoize (block_switch_bitcost + insert_cost) for capped costs
  and skip the subtraction for costs at or above a per-byte threshold
  (S(c) = c - min_cost is monotone, so such costs would be capped anyway).
- BrotliPopulationCost: per-call memo of each count's term and depth, and
  skip the zero terms of the entropy sums.
- std/softfloat: a 64-bit f32_add_mags.

Output is unchanged (mimic tests on gcc and clang, parity sweeps).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UZ978BikvkegL2JUkqoB1e
2026-10-27 23:21:31 +00:00
..

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 floats (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.

f64_add and f64_sub have a fast path for the common case where both operands are normal (f64_add_normal): it orders the operands by magnitude, aligns the significands with a sticky bit, adds or subtracts them and rounds inline. Only a result that is subnormal falls back to the general code (f64_add_mags, f64_sub_mags). Adding (or subtracting) a zero and a finite non-zero value also returns early.

Likewise, f32_add, f32_sub and f32_mul compute the result directly in binary32 (with 32-bit significands for add and sub and an exact 48-bit product for mul) when both operands are normal and the result is normal (or, for add and mul, overflows to infinity), and add and sub return early for a zero plus a finite non-zero value. f32_from_u32 converts integers below 1 << 24 (which are exact) directly. Otherwise (zeroes, subnormal operands or results, infinities and NaNs), they, and f32_div always, 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. The fast paths never produce a NaN, so NaN results (and their payloads) are exactly those of the "via f64" computation.

The comparison functions (f64_cmp, f64_lt, f64_min, etc. and their f32 counterparts) compare the bit patterns directly when neither operand is negative or a NaN (when a | b is at most the bit pattern of +inf), and otherwise call f64_cmp_slow or f32_cmp_slow.

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.

script/manual-test-softfloat-sweep.c systematically checks the f32 add, sub, mul and div operations over every pair of operand exponents ([0 ..= 255] squared), both signs and 40 x 40 mantissa patterns (exact results, ties, carries, cancellation, subnormal results, overflow, NaN payloads): each result must equal the hardware's (any NaN matching any NaN) and, bit-for-bit including NaNs, the "via f64" composition f64_to_f32(f64_op(f32_to_f64(a), f32_to_f64(b))). It does the same for the f64 add, sub, mul and div operations (every pair of exponents in [0 ..= 2047], 9 x 9 mantissa patterns, NaN results checked bit-for-bit against the NaN rule above), and checks f64_to_f32 (326 exponents times 2²⁰ fraction patterns times both signs), f32_to_f64 (every f32), f32_from_u32 and f32_from_i32 (every 32-bit integer) and f32_from_u64 (2³² structured values). It also checks the f32 and f64 cmp, eq, ne, lt, le, gt, ge, min and max functions on every pair of 594 values (both signs, zero, subnormal, normal and maximal exponents, boundary mantissas and their neighbors, infinities and NaNs) against the hardware's comparison operators. Result (x86-64, gcc 13 -O2, 4 threads):

f32_add            419430400 operand pairs,        0 mismatches
f32_sub            419430400 operand pairs,        0 mismatches
f32_mul            419430400 operand pairs,        0 mismatches
f32_div            419430400 operand pairs,        0 mismatches
f64_add           1358954496 operand pairs,        0 mismatches
f64_sub           1358954496 operand pairs,        0 mismatches
f64_mul           1358954496 operand pairs,        0 mismatches
f64_div           1358954496 operand pairs,        0 mismatches
f64_to_f32         341835776 operands,             0 mismatches
f32_to_f64        4294967296 operands,             0 mismatches
f32_from_u32      4294967296 operands,             0 mismatches
f32_from_i32      4294967296 operands,             0 mismatches
f32_from_u64      4294967296 operands,             0 mismatches
f32_compare           352836 operand pairs,        0 mismatches
f64_compare           352836 operand pairs,        0 mismatches
PASS: 0 mismatches in total