Skip to content

Commit

Permalink
float to/from bits and classify: update comments regarding non-confor…
Browse files Browse the repository at this point in the history 
…mant hardware
  • Loading branch information
@RalfJung
RalfJung committed Aug 3, 2024
1 parent eefd2ea commit e79d748
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 211 deletions.
124 changes: 11 additions & 113 deletions library/core/src/num/f32.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -654,18 +654,19 @@ impl f32 {
pub const fn classify(self) -> FpCategory {
// A previous implementation tried to only use bitmask-based checks,
// using f32::to_bits to transmute the float to its bit repr and match on that.
// Unfortunately, floating point numbers can be much worse than that.
// This also needs to not result in recursive evaluations of f64::to_bits.
// If we only cared about being "technically" correct, that's an entirely legit
// implementation.
//
// Unfortunately, there is hardware out there that does not correctly implement the IEEE
// float semantics Rust relies on: x87 uses a too large mantissa and exponent, and some
// hardware flushes subnormals to zero. Rust will misbehave on such hardware, but we can at
// least try to make things seem as sane as possible by being careful here.
//
// On some processors, in some cases, LLVM will "helpfully" lower floating point ops,
// in spite of a request for them using f32 and f64, to things like x87 operations.
// These have an f64's mantissa, but can have a larger than normal exponent.
// FIXME(jubilee): Using x87 operations is never necessary in order to function
// on x86 processors for Rust-to-Rust calls, so this issue should not happen.
// Code generation should be adjusted to use non-C calling conventions, avoiding this.
//
if self.is_infinite() {
// Thus, a value may compare unequal to infinity, despite having a "full" exponent mask.
// A value may compare unequal to infinity, despite having a "full" exponent mask.
FpCategory::Infinite
} else if self.is_nan() {
// And it may not be NaN, as it can simply be an "overextended" finite value.
Expand Down Expand Up @@ -706,20 +707,6 @@ impl f32 {
}
}

// This operates on bits, and only bits, so it can ignore concerns about weird FPUs.
// FIXME(jubilee): In a just world, this would be the entire impl for classify,
// plus a transmute. We do not live in a just world, but we can make it more so.
#[rustc_const_unstable(feature = "const_float_classify", issue = "72505")]
const fn classify_bits(b: u32) -> FpCategory {
match (b & Self::MAN_MASK, b & Self::EXP_MASK) {
(0, Self::EXP_MASK) => FpCategory::Infinite,
(_, Self::EXP_MASK) => FpCategory::Nan,
(0, 0) => FpCategory::Zero,
(_, 0) => FpCategory::Subnormal,
_ => FpCategory::Normal,
}
}

/// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with
/// positive sign bit and positive infinity.
///
Expand Down Expand Up @@ -1140,51 +1127,7 @@ impl f32 {
#[inline]
pub const fn to_bits(self) -> u32 {
// SAFETY: `u32` is a plain old datatype so we can always transmute to it.
// ...sorta.
//
// It turns out that at runtime, it is possible for a floating point number
// to be subject to a floating point mode that alters nonzero subnormal numbers
// to zero on reads and writes, aka "denormals are zero" and "flush to zero".
// This is not a problem per se, but at least one tier2 platform for Rust
// actually exhibits this behavior by default.
//
// In addition, on x86 targets with SSE or SSE2 disabled and the x87 FPU enabled,
// i.e. not soft-float, the way Rust does parameter passing can actually alter
// a number that is "not infinity" to have the same exponent as infinity,
// in a slightly unpredictable manner.
//
// And, of course evaluating to a NaN value is fairly nondeterministic.
// More precisely: when NaN should be returned is knowable, but which NaN?
// So far that's defined by a combination of LLVM and the CPU, not Rust.
// This function, however, allows observing the bitstring of a NaN,
// thus introspection on CTFE.
//
// In order to preserve, at least for the moment, const-to-runtime equivalence,
// we reject any of these possible situations from happening.
#[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")]
const fn ct_f32_to_u32(ct: f32) -> u32 {
match ct.classify() {
FpCategory::Nan => {
panic!("const-eval error: cannot use f32::to_bits on a NaN")
}
FpCategory::Subnormal => {
panic!("const-eval error: cannot use f32::to_bits on a subnormal number")
}
FpCategory::Infinite | FpCategory::Normal | FpCategory::Zero => {
// SAFETY: We have a normal floating point number. Now we transmute, i.e. do a bitcopy.
unsafe { mem::transmute::<f32, u32>(ct) }
}
}
}

#[inline(always)] // See https://github.com/rust-lang/compiler-builtins/issues/491
fn rt_f32_to_u32(x: f32) -> u32 {
// SAFETY: `u32` is a plain old datatype so we can always... uh...
// ...look, just pretend you forgot what you just read.
// Stability concerns.
unsafe { mem::transmute(x) }
}
intrinsics::const_eval_select((self,), ct_f32_to_u32, rt_f32_to_u32)
unsafe { mem::transmute(self) }
}

/// Raw transmutation from `u32`.
Expand Down Expand Up @@ -1229,53 +1172,8 @@ impl f32 {
#[inline]
pub const fn from_bits(v: u32) -> Self {
// It turns out the safety issues with sNaN were overblown! Hooray!
// SAFETY: `u32` is a plain old datatype so we can always transmute from it
// ...sorta.
//
// It turns out that at runtime, it is possible for a floating point number
// to be subject to floating point modes that alter nonzero subnormal numbers
// to zero on reads and writes, aka "denormals are zero" and "flush to zero".
// This is not a problem usually, but at least one tier2 platform for Rust
// actually exhibits this behavior by default: thumbv7neon
// aka "the Neon FPU in AArch32 state"
//
// In addition, on x86 targets with SSE or SSE2 disabled and the x87 FPU enabled,
// i.e. not soft-float, the way Rust does parameter passing can actually alter
// a number that is "not infinity" to have the same exponent as infinity,
// in a slightly unpredictable manner.
//
// And, of course evaluating to a NaN value is fairly nondeterministic.
// More precisely: when NaN should be returned is knowable, but which NaN?
// So far that's defined by a combination of LLVM and the CPU, not Rust.
// This function, however, allows observing the bitstring of a NaN,
// thus introspection on CTFE.
//
// In order to preserve, at least for the moment, const-to-runtime equivalence,
// reject any of these possible situations from happening.
#[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")]
const fn ct_u32_to_f32(ct: u32) -> f32 {
match f32::classify_bits(ct) {
FpCategory::Subnormal => {
panic!("const-eval error: cannot use f32::from_bits on a subnormal number")
}
FpCategory::Nan => {
panic!("const-eval error: cannot use f32::from_bits on NaN")
}
FpCategory::Infinite | FpCategory::Normal | FpCategory::Zero => {
// SAFETY: It's not a frumious number
unsafe { mem::transmute::<u32, f32>(ct) }
}
}
}

#[inline(always)] // See https://github.com/rust-lang/compiler-builtins/issues/491
fn rt_u32_to_f32(x: u32) -> f32 {
// SAFETY: `u32` is a plain old datatype so we can always... uh...
// ...look, just pretend you forgot what you just read.
// Stability concerns.
unsafe { mem::transmute(x) }
}
intrinsics::const_eval_select((v,), ct_u32_to_f32, rt_u32_to_f32)
// SAFETY: `u32` is a plain old datatype so we can always transmute from it.
unsafe { mem::transmute(v) }
}

/// Returns the memory representation of this floating point number as a byte array in
Expand Down
108 changes: 10 additions & 98 deletions library/core/src/num/f64.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -653,12 +653,14 @@ impl f64 {
pub const fn classify(self) -> FpCategory {
// A previous implementation tried to only use bitmask-based checks,
// using f64::to_bits to transmute the float to its bit repr and match on that.
// Unfortunately, floating point numbers can be much worse than that.
// This also needs to not result in recursive evaluations of f64::to_bits.
// If we only cared about being "technically" correct, that's an entirely legit
// implementation.
//
// Unfortunately, there is hardware out there that does not correctly implement the IEEE
// float semantics Rust relies on: x87 uses a too large exponent, and some hardware flushes
// subnormals to zero. Rust will misbehave on such hardware, but we can at least try to make
// things seem as sane as possible by being careful here.
//
// On some processors, in some cases, LLVM will "helpfully" lower floating point ops,
// in spite of a request for them using f32 and f64, to things like x87 operations.
// These have an f64's mantissa, but can have a larger than normal exponent.
// FIXME(jubilee): Using x87 operations is never necessary in order to function
// on x86 processors for Rust-to-Rust calls, so this issue should not happen.
// Code generation should be adjusted to use non-C calling conventions, avoiding this.
Expand Down Expand Up @@ -696,20 +698,6 @@ impl f64 {
}
}

// This operates on bits, and only bits, so it can ignore concerns about weird FPUs.
// FIXME(jubilee): In a just world, this would be the entire impl for classify,
// plus a transmute. We do not live in a just world, but we can make it more so.
#[rustc_const_unstable(feature = "const_float_classify", issue = "72505")]
const fn classify_bits(b: u64) -> FpCategory {
match (b & Self::MAN_MASK, b & Self::EXP_MASK) {
(0, Self::EXP_MASK) => FpCategory::Infinite,
(_, Self::EXP_MASK) => FpCategory::Nan,
(0, 0) => FpCategory::Zero,
(_, 0) => FpCategory::Subnormal,
_ => FpCategory::Normal,
}
}

/// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with
/// positive sign bit and positive infinity.
///
Expand Down Expand Up @@ -1131,33 +1119,7 @@ impl f64 {
#[inline]
pub const fn to_bits(self) -> u64 {
// SAFETY: `u64` is a plain old datatype so we can always transmute to it.
// ...sorta.
//
// See the SAFETY comment in f64::from_bits for more.
#[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")]
const fn ct_f64_to_u64(ct: f64) -> u64 {
match ct.classify() {
FpCategory::Nan => {
panic!("const-eval error: cannot use f64::to_bits on a NaN")
}
FpCategory::Subnormal => {
panic!("const-eval error: cannot use f64::to_bits on a subnormal number")
}
FpCategory::Infinite | FpCategory::Normal | FpCategory::Zero => {
// SAFETY: We have a normal floating point number. Now we transmute, i.e. do a bitcopy.
unsafe { mem::transmute::<f64, u64>(ct) }
}
}
}

#[inline(always)] // See https://github.com/rust-lang/compiler-builtins/issues/491
fn rt_f64_to_u64(rt: f64) -> u64 {
// SAFETY: `u64` is a plain old datatype so we can always... uh...
// ...look, just pretend you forgot what you just read.
// Stability concerns.
unsafe { mem::transmute::<f64, u64>(rt) }
}
intrinsics::const_eval_select((self,), ct_f64_to_u64, rt_f64_to_u64)
unsafe { mem::transmute(self) }
}

/// Raw transmutation from `u64`.
Expand Down Expand Up @@ -1202,58 +1164,8 @@ impl f64 {
#[inline]
pub const fn from_bits(v: u64) -> Self {
// It turns out the safety issues with sNaN were overblown! Hooray!
// SAFETY: `u64` is a plain old datatype so we can always transmute from it
// ...sorta.
//
// It turns out that at runtime, it is possible for a floating point number
// to be subject to floating point modes that alter nonzero subnormal numbers
// to zero on reads and writes, aka "denormals are zero" and "flush to zero".
// This is not a problem usually, but at least one tier2 platform for Rust
// actually exhibits an FTZ behavior by default: thumbv7neon
// aka "the Neon FPU in AArch32 state"
//
// Even with this, not all instructions exhibit the FTZ behaviors on thumbv7neon,
// so this should load the same bits if LLVM emits the "correct" instructions,
// but LLVM sometimes makes interesting choices about float optimization,
// and other FPUs may do similar. Thus, it is wise to indulge luxuriously in caution.
//
// In addition, on x86 targets with SSE or SSE2 disabled and the x87 FPU enabled,
// i.e. not soft-float, the way Rust does parameter passing can actually alter
// a number that is "not infinity" to have the same exponent as infinity,
// in a slightly unpredictable manner.
//
// And, of course evaluating to a NaN value is fairly nondeterministic.
// More precisely: when NaN should be returned is knowable, but which NaN?
// So far that's defined by a combination of LLVM and the CPU, not Rust.
// This function, however, allows observing the bitstring of a NaN,
// thus introspection on CTFE.
//
// In order to preserve, at least for the moment, const-to-runtime equivalence,
// reject any of these possible situations from happening.
#[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")]
const fn ct_u64_to_f64(ct: u64) -> f64 {
match f64::classify_bits(ct) {
FpCategory::Subnormal => {
panic!("const-eval error: cannot use f64::from_bits on a subnormal number")
}
FpCategory::Nan => {
panic!("const-eval error: cannot use f64::from_bits on NaN")
}
FpCategory::Infinite | FpCategory::Normal | FpCategory::Zero => {
// SAFETY: It's not a frumious number
unsafe { mem::transmute::<u64, f64>(ct) }
}
}
}

#[inline(always)] // See https://github.com/rust-lang/compiler-builtins/issues/491
fn rt_u64_to_f64(rt: u64) -> f64 {
// SAFETY: `u64` is a plain old datatype so we can always... uh...
// ...look, just pretend you forgot what you just read.
// Stability concerns.
unsafe { mem::transmute::<u64, f64>(rt) }
}
intrinsics::const_eval_select((v,), ct_u64_to_f64, rt_u64_to_f64)
// SAFETY: `u64` is a plain old datatype so we can always transmute from it.
unsafe { mem::transmute(v) }
}

/// Returns the memory representation of this floating point number as a byte array in
Expand Down

0 comments on commit e79d748

Please sign in to comment.