Software Float64 emulation using declarative device libraries

LICENSES/berkeley-softfloat-BSD-3-Clause.txt

@@ -0,0 +1,42 @@
+The Berkeley SoftFloat lookup tables (APPROX_RECIP_SQRT_K0S/K1S,
+APPROX_RECIP_K0S/K1S) and the recip / recipSqrt approximation
+functions in dist/softfloat64.metal and shaders/softfloat.metal are
+derived from John R. Hauser's Berkeley SoftFloat-3e:
+
+  Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017
+  The Regents of the University of California.
+  All Rights Reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions
+  are met:
+
+   1. Redistributions of source code must retain the above copyright
+      notice, this list of conditions, and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions, and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+
+   3. Neither the name of the University nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS",
+  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+  PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
+  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+  SUCH DAMAGE.
+
+The vendored Berkeley SoftFloat-3e and TestFloat-3e sources under
+vendor/ are also covered by this license. See
+vendor/SoftFloat-3e/COPYING.txt and vendor/TestFloat-3e/COPYING.txt
+for the unmodified upstream license texts.

LICENSES/julia-MIT.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2009-2024: Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors: https://github.com/JuliaLang/julia/contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

LICENSES/metal-softfloat-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 metal-softfloat contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -53,6 +53,11 @@ identifies cached kernels. Compiled kernels are not invalidated when a library c
 Julia library methods are recompiled when redefined, but cached kernels keep using the
 previous version, and bitcode files are read once per session.
 
+Software binary64 support is an optional library; see
+[`src/softfloat/README.md`](src/softfloat/README.md). Its legalization runs at this same
+boundary for both the caller and Julia libraries to keep late-imported runtime ABIs
+consistent.
+
 ### Testing
 
 GPUCompiler.jl's own test suite runs on GitHub Actions. In addition, Buildkite runs the test

src/GPUCompiler.jl

@@ -84,6 +84,7 @@ include("devicelib.jl")
 include("mcgen.jl")
 include("debug.jl")
 include("driver.jl")
+include("softfloat/SoftFloat.jl")
 
 # other reusable functionality
 include("execution.jl")

src/softfloat/README.md

@@ -0,0 +1,72 @@
+# Software floating point
+
+This directory implements IEEE 754 binary64 (`Float64`) support for GPU targets without
+native double-precision arithmetic, using only 64-bit integer operations. Back-ends opt in
+by returning `softfloat_libraries()...` from `GPUCompiler.device_libraries(job)` and calling
+`GPUCompiler.SoftFloat.legalize!(job, mod)` in `lower_intrinsics!`.
+The same hook legalizes Julia libraries imported after optimization, so imported runtime functions
+and their callers agree on integer ABIs. External bitcode is an ABI boundary: unsupported
+binary64 calls are rejected rather than silently changing their calling convention.
+The optimized integer routines are linked at the late library stage, from two libraries:
+small routines (sign operations, comparisons, rounding, most conversions) are forced inline,
+while the arithmetic and narrowing conversions remain out of line to avoid duplicating
+their implementation at every operation (see `OUTLINED` in `provider.jl`).
+
+The emulation operates on ordinary `Float64` code in the final LLVM module, including
+Base's pure-Julia math functions. The usual GPU restrictions still apply: external
+floating-point library calls need backend overrides, and unsupported LLVM operations
+are rejected. `legalize.jl` first outlines every floating-point operation on
+`double` values into a call to one of the integer-only routines, and then rebuilds the
+module with `double` replaced by `i64` everywhere (signatures, aggregates, constants,
+globals, attributes). The routines are linked in afterwards, through the device-library
+machinery in `../devicelib.jl`, from the table in `provider.jl`.
+
+The routines themselves are the methods of `SoftFloat64`, a `primitive type` with the bit
+representation of `Float64` that can be used as an ordinary number type on the CPU as well
+(which is how `test/softfloat.jl` validates it, bit for bit against native arithmetic).
+`binary64/types.jl` defines the type, using Base's format traits (`significand_bits`,
+`exponent_mask`, ...), and `unpack`, which yields the sign, exponent and normalized
+significand of a value. Every operation in `arithmetic.jl` and `conversions.jl` then
+computes an exact or sticky-extended significand for its result and hands it to
+`round_pack` in `rounding.jl`, which is where rounding happens: a single `round_up` decision
+implements all `RoundingMode`s, for `round_pack`, the narrowing conversions to `Float32` and
+`Float16`, and `round` to integral values. The operators default to round-to-nearest-even
+but accept a trailing rounding mode, e.g. `+(a, b, RoundUp)`, which specializes at compile
+time. `uint128.jl` provides the two-word `U128` that significand products need, since many
+back-ends cannot lower `UInt128`.
+
+The large routines (`+`, `*`, `/`, `sqrt`, `fma`) are `@noinline` so that they are shared
+between call sites; the others are meant to be inlined.
+
+Semantics, as used by the legalizer: round-to-nearest-even, gradual underflow, signed zeros,
+infinities, quiet comparisons, and canonical quiet NaN arithmetic results
+(`0x7ff8000000000000`). Sign operations preserve NaN payloads. Not supported: exception
+flags, `Float64` atomics and `frem`
+(Julia's `rem` does not use it). `Float64`→`Float16` rounds directly rather than through
+`Float32`, which would double-round. Widening `Float16` and `Float32` uses their bits
+directly, preserving subnormals even when native arithmetic flushes them to zero.
+
+`paynehanek.jl` is unrelated to the emulation itself: it is a version of Base's Payne-Hanek
+argument reduction (used by `sin`, `cos`, and `tan` for large arguments) that avoids the
+`UInt128` arithmetic many GPU back-ends cannot lower. Back-ends should override
+`Base.Math.paynehanek(::Float64)` with it.
+
+## Package boundary
+
+The numerical core is `uint128.jl` and `binary64/`; it depends only on Base and can move
+into a standalone package. `provider.jl` and `legalize.jl` are GPUCompiler integration,
+while `paynehanek.jl` is a backend workaround for Base's implementation.
+
+`SoftFloat64` currently supplies the arithmetic and conversions needed by that integration,
+plus basic numeric traits, promotion and hashing. A standalone package should complete
+and test the remaining number interface (checked integer conversions, adjacent values,
+parsing and broader promotion) before presenting it as a general replacement for `Float64`.
+
+## Provenance
+
+The algorithms in `binary64/` are those of
+[Berkeley SoftFloat 3e](https://github.com/ucb-bar/berkeley-softfloat-3) (BSD-3-Clause),
+including its reciprocal tables, by way of
+[metal-softfloat](https://github.com/guyfischman/metal-softfloat)
+(commit `8b6c592e2e383040fe2778bed8dda7904df284b1`, MIT). `paynehanek.jl` is adapted from
+Julia's `base/special/rem_pio2.jl` (MIT). The notices are in `../../LICENSES/`.

src/softfloat/SoftFloat.jl

@@ -0,0 +1,22 @@
+# software floating-point support for targets without native double precision
+
+module SoftFloat
+
+using LLVM, LLVM.IR, LLVM.Build, LLVM.Passes
+import ..GPUCompiler
+using Base: sign_mask, exponent_mask, significand_mask, exponent_one, significand_bits,
+            exponent_bits, exponent_bias, exponent_raw_max, uinttype
+
+include("uint128.jl")
+include("binary64/types.jl")
+include("binary64/rounding.jl")
+include("binary64/arithmetic.jl")
+include("binary64/comparisons.jl")
+include("binary64/conversions.jl")
+include("paynehanek.jl")
+include("provider.jl")
+include("legalize.jl")
+
+export SoftFloat64, softfloat_libraries
+
+end