Tracking Issue for f16 and f128 float types

[traviscross]

This is a tracking issue for the RFC 3453 (rust-lang/rfcs#3453).

The feature gate for the issue is #![feature(f16_and_f128)].

From the RFC:

This RFC proposes adding new IEEE-compliant floating point types f16 and f128 into the core language and standard library. We will provide a soft float implementation for all targets, and use hardware support where possible.

About tracking issues

Tracking issues are used to record the overall progress of implementation. They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions. A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature. Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Steps

• Implement the RFC (see the list of tasks here]
• Adjust documentation (see instructions on rustc-dev-guide)
• Stabilization PR (see instructions on rustc-dev-guide)

Unresolved questions

• Do any new target features need to be marked as "forbidden" since they affect ABI? The logic here looks like that may be the case.

Implementation history

• Add basic support stubs to IR and backend interfaces: Add stubs in IR and ABI for f16 and f128 #121728
• Add AST support and intrinsics: f16 and f128 step 2: intrinsics #121841 (comment)
• Connect the frontend, add the feature gate: f16 and f128 step 3: compiler support & feature gate #121926
• Add the most basic traits that rustc more or less expects for primitives Add basic trait impls for f16 and f128 #123085
• Finish support in rustdoc Add f16 and f128 to rustdoc's PrimitiveType #123581
• Add library support. Some parts are blocked on const eval, compiler builtins updates, and LLVM lowering bugs. hooray, this part is done!
  • f16 and f128 step 4: basic library support #122470
  • Add a Debug impl and some basic functions to f16 and f128 #123783
  • Add constants for f16 and f128 #123850
  • Add more constants, functions, and tests for f16 and f128 #126608
  • Add classify and related methods for f16 and f128  #127020
  • Add f16 and f128 math functions #127027
• Add needed functions to compiler-builtins. Unfortunately this one will block almost everything else on the list.
  • Add builtins for f16/f128 float conversions compiler-builtins#593
  • Add addition, subtraction, multiplication, and compare operations for f128 compiler-builtins#606
  • Add f128 float to integer conversion functions compiler-builtins#613
  • Add f128 int to float conversions compiler-builtins#624
  • Add __divtf3 compiler-builtins#622
  • Add __powitf2 symbol for f128 integer exponentiation compiler-builtins#614
  • Others
• Figure out parsing and printing
  • Migrate the tester to accept more types Rewrite test-float-parse in Rust #127510
  • Add f16, which should be straightforward Add f16 formatting and parsing #127013
  • Figure out f128 which will not be straightforward. Our current implementations are pretty u64-dependent so they can't fit a f128 mantissa. We could make them generic but probably want to instead use an implementation that is slower but better for size.
• Update const eval
  • Basic arithmetic Add f16 and f128 const eval for binary and unary operationations #126429
  • Casting Enable const casting for f16 and f128 #127032
  • Miri shims
• Figure out mangling Add encoding for f16 and f128 #122106 Add v0 symbol mangling for f16 and f128 #123816
• Ensure known demanglers get updated or at least have issues for adding the new types unneeded with the forward-compatible demangling
• Add SIMD operations that can make use of these types Add SIMD operations that use f16 and f128 #125440
  • Implement AVX512_FP16 stdarch#1605
  • NVPTX: Add f16 SIMD intrinsics stdarch#1626
• Enable assembly registers where it makes sense Enable f16 and f128 in assembly on platforms that support it #125398
  • Add f16 and f128 inline ASM support for aarch64 #129536
  • Add f16 and f128 inline ASM support for x86 and x86-64 #126417
  • Add f16 inline ASM support for RISC-V #126530
  • Add f16 inline ASM support for 32-bit ARM #126555
• Make sure the GCC and Clif backends handle these types gracefully
  • Support f16 and f128 rustc_codegen_gcc#461 (merged upstream, waiting on sync)
  • Support f16 and f128 rustc_codegen_cranelift#1461
  • Migrate float intrinsics to have a fallback (changes from Wishlist: allow adding intrinsics in a way that doesn't break every backend #93145)
• Make sure all relevant unimplementeds and FIXMEs are removed from tools that need library support
  • Resolve Clippy f16 and f128 unimplemented!/FIXMEs  #126636
  • Replace f16 and f128 pattern matching stubs with real implementations #123088
  • Update f16/f128 FIXMEs that needed (NEG_)INFINITY #127496
• Make use of new diagnostic attributes, e.g. f16_nan
• Figure out ABI & platform-specific problems (thanks @beetrees for just about all of these)
  • f16 ABI bugs in compiler-rt f16 generates code that uses the incorrect ABI for compiler-rt #123885
  • 32-bit ABI bugs from LLVM [clang] missing support for _Float128 (C23) llvm/llvm-project#80195 (comment)
  • f16 miscompilations from LLVM (affects T2 and T3 targets) LLVM miscompiles consecutive half operations by using too much precision on several backends llvm/llvm-project#97975 LLVM miscompiles passing/returning half on several backends by using lossy conversions llvm/llvm-project#97981
  • f16 abs and neg quieten signalling NaNs on emulated targets [X86] LLVM >= 18 folding bitcast -> and -> bitcast to @llvm.fabs.f16 generates call to __extendhfsf2 llvm/llvm-project#104915 (comment)
  • x86-32 "f16" ABI needs SSE, incompatible with i586 targets #131819
  • Tier 1 MinGW incompatibilities from GCC https://gcc.gnu.org/bugzilla/show_bug.cgi?id=115054
  • Tier2 PowerPC BE precision issues f128 symbols on powerpc64 give inaccurate results #125109
  • Tier2 Power9 possible ABI issues f128 from_bits / to_bits sometimes gets reversed on ppc #125102
  • Tier2 PowerPC LE f128 as f16 casting bug LLVM f128 -> f16 conversion selection failure on powerpc64le llvm/llvm-project#92866
  • Tier 2 PowerPC sometimes uses the wrong symbol names PowerPC fp128 -> half uses __trunctfhf2 but should be __trunckfhf2 llvm/llvm-project#98126
  • Tier 2 Loongarch failure to select loongarch64 half (f16) failure to select with +f and +d llvm/llvm-project#93894 (fixed upstream)
  • Tier 2 arm64ec does not support these types Can't pass or return half or fp128 on arm64ec llvm/llvm-project#94434
  • Tier 2 s390x-unknown-linux-gnu doesn't support f16: SystemZ Backend: Add support for operations such as FP16_TO_FP and FP_TO_FP16 llvm/llvm-project#50374
  • Tier 2 wasm32 correctness bug On wasm32, half operation results aren't correctly rounded between each operation llvm/llvm-project#96437
  • Tier 2 nvptx64-nvidia-cuda doesn't support f128: fp128 causes compilation failures when compiling for nvptx64-nvidia-cuda llvm/llvm-project#95471
  • Tier 3 mips LLVM crashes with f128 Compiler crash when targeting mips64 when returning fp128 after calling a function returning { i8, i128 } llvm/llvm-project#96432
  • Tier 3 sparc-unknown-linux-gnu doesn't support passing f128 directly (error message SPARCv8 does not handle f128 in calls; pass indirectly): Passing long double args on 32-bit SPARC violates ABI llvm/llvm-project#41838
  • Tier 3 powerpc64-ibm-aix doesn't currently support f128 arguments: fp128 arguments cause a compiler error on powerpc64-ibm-aix llvm/llvm-project#101545
• Other misc miscompilations or bugs
  • LLVM does fma.f16 incorrectly llvm.fma.f16 intrinsic is expanded incorrectly on targets without native half FMA support  llvm/llvm-project#98389
  • powi.f16 constant folding returns incorrect values Misoptimization: EarlyCSEPass uses replaces powi.f16 with float result llvm/llvm-project#98665
• Eventually, stabilization

Note that unimplemented!("f16_f128") and // FIXME(f16_f128) is being used where relevant, to make the todo list easily greppable.

Nice to have changes:

• Better debuginfo for MSVC Improve MSVC debug info for f16 and f128 #121837
  • f16: Add Natvis visualiser and debuginfo tests for f16 #127001
  • f128
• A bit of ecosystem support
  • Rust-analyzer Add f16 and f128 support (add to FloatTy) rust-analyzer#17451
  • Bytemuck Support f16 and f128 under a nightly flag Lokathor/bytemuck#250
  • Zerocopy Add support for the unstable f16 and f128 types google/zerocopy#2042
  • Serde
  • num
  • rug https://gitlab.com/tspiteri/rug/-/issues/68
  • syntax highlighters

[tgross35]

A blocking issue should be added: ensure C compatibility with ABI-cafe or similar

#114607 (comment)

[tgross35]

Implementation steps (could somebody link this in the top post?):

(massive todo list moved to the top post)

@rustbot claim

[scottmcm]

It appears that today f128 doesn't trigger the incomplete_features lint: https://play.rust-lang.org/?version=nightly&mode=release&edition=2021&gist=9d8a3698d5d506fc960bde270e9a1a54

It might be a good idea to do that for now, to avoid people making threads like https://users.rust-lang.org/t/display-for-f128/114405?u=scottmcm

[beetrees]

Tier 3 powerpc64-ibm-aix doesn't currently support f128 arguments: llvm/llvm-project#101545

[beetrees]

llvm/llvm-project#104915: f16 abs and neg quieten signalling NaNs on targets where f16 is not natively supported.