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
• Stabilize.
  • stabilize const_fn_floating_point_arithmetic #128596
• Add documentation to the reference.
  • In particular, inline asm interactions still need to be documented.

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?
  • We will treat these as target-specific bugs when they show up
• What exactly is the set of "extra" NaNs for all remaining targets?
  • Add target-specific NaN payloads for the missing tier 2 targets #138870 covers all tier 2 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.

[RalfJung]

core::arch is staggeringly huge, can we get a concrete example?

Just anything that performs float arithmetic will do. I am sure those intrinsics exist there, I just don't know how they will be called. :)

And specifically ARM NEON does not follow the spec we have laid down for scalar operations, see #129880. I assume in this case we want to say the intrinsics behave like the vendor intended, not like "normal" Rust float ops?

Also, even if they're stable, they're not/will never be const-stable, correct?

Probably not, but that doesn't relief us from defining their semantics.

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.

I think it is enough to document what we can find out about our existing tier 2 targets, as your PR does. As you said, newly promoted targets will be correct by default, and if anyone cares they can file an issue.

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.

What specifically are you referring to here?

[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.

What specifically are you referring to here?

The RFC's section "Assumptions about floating-point environment" includes language like "when leaving the inline assembly block, the floating-point control bits must be in exactly the same state as when the inline assembly block was entered". The reference's section on inline assembly ( https://doc.rust-lang.org/nightly/reference/inline-assembly.html ) doesn't have general language to this effect, instead it has stuff like "These flags registers must be restored upon exiting the assembly code if the preserves_flags option is set [lists some specific FP flags for some specific platforms, among others]", or "On x86, the x87 floating-point register stack must remain unchanged unless [...]". It seems to be more concerned with specifics and have more implied exceptions than the blanket statement in the RFC would suggest, at least to me.

[RalfJung]

Ah, good point. Yes, all parts of the "FP control machinery" must be left unchanged or restored to their original value. Also, the initial state of the "FP control machinery" (e.g. exception flags) when the asm block starts is entirely unspecified and not correlated with what previous Rust code or previous inline asm blocks did in any way.

@Amanieu what would be the best way to specify this? I lack the low-level knowledge to properly express this.

[programmerjake]

fp flags generally have two parts: control bits (current rounding mode, if fp exceptions cause interrupts or are ignored, things like enabling treating denormals as zero, etc.) and status bits (if a underflow occurred, if a division by zero occurred, etc.). generally any rust code isn't permitted to change the control bits from the defaults, and llvm is allowed to arbitrarily change the status bits and ignores whatever values the status bits have.

therefore, i think it's reasonable for inline asm to (unless marked with preserves_flags) change the status however it likes, but the control bits must be restored to their default values before exiting any inline asm block (this includes calling other functions from in inline asm) if the control bits were changed in inline asm.

[Amanieu]

Essentially this boils down to properly specifying the calling convention. Specifically, what the FPU control mode should be set to on entry to a function and what it is set to on exit. Since inline asm is fundamentally just an FFI call, we just need to specify this as part of the asm "calling convention". This is also relevant for extern "C" where C code needs to be careful to call Rust code with the proper FPU control mode.

This would have to be specified separately for each architecture, for example:

On x86:

• Rounding mode must be round-to-nearest.
• Flush-to-zero and denormals-are-zero must be disabled.
• Floating-point exceptions don't trap.

On ARM:

• Rounding mode must be round-to-nearest.
• Flush-to-zero and denormals-are-zero must be disabled.
• Floating-point exceptions don't trap.
• We don't care about DN which controls which NaN pattern is generated.
• AHP must be disabled so that we have standard IEEE754 f16 semantics.

[DemiMarie]

See #139277: There are platforms and use-cases on which supporting denormal numbers is impractial, either because it breaks real-time guarantees (which are required by the application), requires OS support that is not present, or is (in the case of at least some GPUs) simply not possible. Audio DSP on x86-64 is one example of such a use-case. Writing Metal shaders in Rust is another.