Tracking Issue for float_semantics RFC 3514

[traviscross]

This is a tracking issue for RFC 3514:

• add float semantics RFC rfcs#3514

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

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

• Accept an RFC.
  • add float semantics RFC rfcs#3514
• Update library documentation.
  • float types: document NaN bit pattern guarantees #129559
• Add documentation to the reference.
  • See the instructions.
• N/A: Add formatting for new syntax to the style guide.
  • See the nightly style procedure.
• Stabilize.
  • stabilize const_fn_floating_point_arithmetic #128596

Unresolved Questions

• Should we be concerned that LLVM does not actually document that it uses IEEE float semantics? It does assume IEEE semantics in its own optimization passes.
• Are there any other targets with floating-point trouble?
• What exactly is the set of "extra" NaNs for all remaining targets?
• To what extend does this specification apply to platform intrinsics? On the one hand, it seems reasonable to expect platform intrinsics to have the behavior of the platform instructions. On the other hand, we implement some platform intrinsics with the portable LLVM simd intrinsics, and those are subject to the NaN-non-determinism described above. So the current de-facto semantics of at least some platform intrinsics is that they do not match what the platform does.

Related

TODO.

cc @RalfJung @rust-lang/lang

[RalfJung]

The RFC largely documents how rustc and Miri already behave. So the main task here is to write suitable documentation -- not sure where the discussion of which NaNs can be generated would even go. Probably somewhere in the reference, but ideally mentioned in the f32/f64 type docs as well, or so?

The other main outcome of this is that can we proceed with stabilization of #57241.

[RalfJung]

With #129559 having landed, is there anything else left to do here?

[RalfJung]

As of llvm/llvm-project#102140, LLVM now also properly documents the guarantees that we promise to our users -- just in time for the release. :D

[bstrie]

is there anything else left to do here?

Going over the checkmarks listed in the issue:

Add documentation to the reference.

I don't think this issue needs to consider updating the reference. The specific guarantees around floating-point semantics are well-documented in the library API docs, and the reference doesn't tend to concern itself with library specifics.

If the reference contained any language suggesting that const evaluation is deterministic in all cases, then we'd need to correct that, but I can't find any language to that effect. To be clear, the reference probably should talk about the semantic guarantees of const evaluation, but the lack of that is a broader issue, not specific to this feature.

Are there any other targets with floating-point trouble?

This isn't an actionable question because we the list of targets is unbounded. If there are such troubles then those are likely soundness bugs, and since this feature is already stable, those should be filed as separate issues, there's nothing to block closing this.

What exactly is the set of "extra" NaNs for all remaining targets?

The library docs already make a best-effort attempt at this. If they can be fleshed out further in the future, that can be tracked in separate issues.

To what extend does this specification apply to platform intrinsics?

I'm unclear regarding the desired result of asking this question. Intrinsics are perma-unstable, so their behavior can be changed at any time. If some of the wrapper functions that we use to provide stable interfaces to intrinsics are impacted by such a decision, then that's a concern for the documentation of those wrapper functions, but AFAIK the stdlib makes few (no?) strong guarantees about what intrinsics it lowers to, and if it wants to clarify those guarantees, that's a separate issue from this one.

So ultimately I think there's nothing left to do here and a member of the lang team can close this.

[RalfJung]

The "platform intrinsics" point refers to the operations in core::arch, many of which are stable.

Regarding the "extra" NaN patterns, it'd be good to figure this out at least for powerpc and s390x, to cover our tier 2 targets with host tools. To cover all tier 2 targets we also need loongarch64 and nvptx64.

[bstrie]

The "platform intrinsics" point refers to the operations in core::arch, many of which are stable.

core::arch is staggeringly huge, can we get a concrete example? Also, even if they're stable, they're not/will never be const-stable, correct?

Regarding the "extra" NaN patterns, it'd be good to figure this out at least for powerpc and s390x, to cover our tier 2 targets with host tools.

Shall we make it an explicit tier requirement for targets to document this before they can be promoted? At the same time, the documentation is explicit that unmentioned targets may have any NaN payload, which is something that we can trivially relax at any point in the future. And I'm actually somewhat wary of documenting these values because we can't control whether the targets will have a change of heart and decide to add more possible payloads in the future.

[bstrie]

Regarding updating the reference, I'd like to ask whether or not the docs for inline assembly are considered sufficiently precise to capture the language in the RFC. There's plenty of stuff in the docs about preserving FP registers, but maybe it would be useful to state the requirements plainly as the RFC does.