add `ppcf128` library API by folkertdev · Pull Request #164021 · rust-lang/rust

folkertdev · 2026-10-09T07:47:23Z

The constants are from C, though for MIN and MAX the C values are kind of wrong...

#include <float.h>
#include <stdio.h>
#include <math.h>
#include <string.h>

static long double from_components(double hi, double lo)
{
    double parts[2] = { hi, lo };
    long double x;
    memcpy(&x, parts, sizeof x);
    return x;
}

static void print_const(const char *const_name, long double x)
{
    unsigned char bytes[sizeof x];
    memcpy(bytes, &x, sizeof bytes);

    printf("%s: [\n    ", const_name);
    for (size_t i = 0; i < sizeof bytes; i++) {
        if (i == 8) {
            printf("\n    ");
        }
        printf("0x%02x, ", bytes[i]);
    }
    puts("\n]");
}

int main(void)
{
    print_const("MIN", -LDBL_MAX);
    print_const("MAX", LDBL_MAX);
    print_const("NAN", nanl(""));
    print_const("INFINITY", (long double)INFINITY);
    print_const("NEG_INFINITY", -((long double) INFINITY));

    double hi, lo;

    hi = DBL_MAX;
    lo = DBL_MAX * (DBL_EPSILON / 4.0);

    // LDBL_MAX is not right
    volatile long double MORE_MAX = from_components(hi, lo);
    printf("isfinite(ours): %d\n", isfinite(MORE_MAX));
    printf("ours > LDBL_MAX: %d\n", MORE_MAX > LDBL_MAX);

    hi = DBL_MIN;
    lo = DBL_MIN* (DBL_EPSILON / 4.0);

    // LDBL_MIN is not right
    volatile long double MORE_MIN = from_components(hi, lo);
    printf("isfinite(ours): %d\n", isfinite(MORE_MIN));
    printf("ours < LDBL_MIN: %d\n", MORE_MIN < LDBL_MIN);

    return 0;
}

So, LDBL_MAX is not actually the maximum finite value (I think this is a precision issue, they're off by one bit). I opted to have our MAX actually be the biggest finite value, and MIN the smallest.

folkertdev · 2026-10-12T11:27:28Z

r? tgross35
cc @beetrees

We can debate what should be added for this type (and x87 f80 soon). Conversions to/from components and bytes seem useful to me. Equality and ordering are easy to provide and may come in handy. The constants are just kinda because we can.

The main concern here is really that for macros it is convenient to have an API surface that matches other floats (as much as possible). I don't anticipate these methods and values getting a lot of use on their own.

rustbot · 2026-10-12T11:27:33Z

tgross35 is currently at their maximum review capacity.
They may take a while to respond.

rustbot · 2026-10-12T11:27:38Z

rustc_codegen_cranelift is developed in its own repository. If possible, consider making this change to rust-lang/rustc_codegen_cranelift instead.

cc @bjorn3

stdarch is developed in its own repository. If possible, consider making this change to rust-lang/stdarch instead.

cc @Amanieu, @sayantn

tgross35 · 2026-10-14T13:13:21Z

The docs for ppcf128 should be improved in this PR, especially since we're adding invariants but I'm not exactly sure what they are. And we should tell the user what to expect for component and bitwise conversions.

E.g. the term "normal form" needs to be defined, maybe with a table of how +0.0, -0.0, infinity, qNaN etc are represented. Also something about NaNs similar to a significantly simplified version of https://doc.rust-lang.org/std/primitive.f32.html#nan-bit-patterns (or just link that and note any differences).

View changes since the review

hmm, what should that look like. +0.0 can be either ppcf128::from_components(0.0, 0.0) or ppcf128::from_components(0.0, -0.0).

For NaN any value where the first component is NaN is a NaN. We don't have any operations that would clear NaN at the moment I believe, and we don't plan on adding any.

You could probably just put it into a table like this:

Value Preferred Representation Allowed Representations Notes

+0.0 (+0.0, +0.0) (+0.0, ±0.0) Nonzero second components are not allowed

-0.0 (-0.0, -0.0) (-0.0, ±0.0) Nonzero second components are not allowed

+∞ (+∞, +0.0) (+∞, ±0.0) Nonzero second components are not allowed

-∞ (-∞, -0.0) (-∞, ±0.0) Nonzero second components are not allowed

NaN (NaN, +0.0) (NaN, *) Any NaN is allowed in the first component, any representation is allowed in the second component

x ∈ ℝ (x₁, x₂) N/A x₁ + x₂ must round to x₁

Where "Preferred representation" is what the constants are and probably what we get from operations, and "Allowed Representations" are what you can have without it being UB.

tgross35 · 2026-10-14T15:25:14Z

+    #[unstable(feature = "powerpc_ppcf128", issue = "163323")]
+    pub const unsafe fn from_components_unchecked(large: f64, small: f64) -> Self {
+        unsafe { core::mem::transmute([large, small]) }
+    }


So this does add the precondition even though that's not what is currently in https://github.com/rust-lang/rfcs/pull/4003/changes#diff-62de97c7dda87de848b9cc9e60b093d8da9493c25b42ef407537ad0c5e29ae82R144? That will need to be rectified at some point, probably worth a FIXME.

View changes since the review

We sort of realized that LLVM does not clearly specify the assumptions, and it is very likely that we will run into miscompilations if we don't enforce normalizaton.

tgross35 · 2026-10-14T15:26:28Z

From<f16, f32, f64> probably also makes sense

View changes since the review

Or perhaps a general From<T> where f64: From<T>

I think doing separate impls is more consistent with other float types: for example, we don't impl From<T> for f128 where f64: From<T>.

Those require separate bodies, whereas every From<T> for ppcf128 has to go via f64 anyway. I can't really think of any reasonable exception we would have in std.

But I suppose it doesn't hurt to be consistent. Could be a from_via_f64! macro and cover the integers as well.

Just the three From implementations seem fine to me. We can add more later, but I don't think the ergonomics will be a big deal for this type.

beetrees · 2026-10-15T13:18:40Z

+    #[unstable(feature = "powerpc_ppcf128", issue = "163323")]
+    #[rustc_const_unstable(feature = "powerpc_ppcf128", issue = "163323")]
+    #[inline]
+    pub const fn to_bits(self) -> u128 {


Given the endianess-dependency footgun, I'm not sure to_bits is worthwhile having - I'm struggling to think of any use cases that wouldn't be better served by to_{ne,le,be}_bytes() or to_components().{0,1}.to_bits(). Thoughts?

View changes since the review

I do think there is value overall in having a consistent interface across float types (e.g. for macros, but also for humans so that there are fewer edge cases to remember).

It also (and this is really why I added it now) serves as a good place to document the endianness behavior.

I feel like having consistency here would hide the fact that ppcf128 is not like other float types - due to the endianness problem storing the bits would be a footgun (unlike other float types where the bits are target independent - to_{ne,le,be}_bytes provide consistent behaviour across types here so are better for this use case), and manipulating the bits from to_bits like you would another float type for soft-float routines would also likely be incorrect as it is actually two floats in an endian-dependent order (to_components is much less error-prone for this use case). I'm having difficulty thinking of a useful macro example where calling to_bits and performing the same operations on it as would be done on another float type (e.g. as part of a macro) wouldn't be a logic error.

Code using to_bits often has a from_bits, which would have to be unsafe here. I think that makes the generic code argument less convincing.

Sure, it's more a general principle, that we can deviate from if there is good reason.

I'll remove the method and try to put the doc example somewhere because I do think it illustrates the endianness problem well.

tgross35 · 2026-10-15T19:10:12Z

Some things were marked as resolved but looks like might not have been pushed

folkertdev · 2026-10-15T22:45:00Z

I've pushed everything I have now

tgross35 · 2026-10-15T22:19:43Z

+/// large component. Creating a value with components that are not in normal form
+/// (e.g. with [`ppcf128::from_components_unchecked`]) is [undefined behavior].


I wonder if this should say "using a value created with" rather than "creating a value with"? I think this would be more consistent with behavior elsewhere, where it's the use of something invalid rather than the existence of something invalid that is unsound.

Cc @RalfJung

View changes since the review

This is an open question that has not been answered yet I think -- is this a validity invariant or a safety invariant.

This is an open question that has not been answered yet I think -- is this a validity invariant or a safety invariant.

This is tricky. We're really trying to guard against the optimizer doing something weird. We deduce that LLVM optimizes based on the value being in normal form, so if that is ever not the case, the program might miscompile. As far as we're aware, LLVM never formally states that it requires the value to be in normal form though, it just falls out of the logic.

So, I think that means it's a validity invariant?

Not necessarily. If it's only UB to perform an operation like fadd on a bad value, that could be a safety invariant. It's a validity invariant if LLVM is allowed to speculatively execute fadd though. So it's probably safer to say that it is a validity invariant.

That means Miri has to check it. (Though that can be a separate PR.)

LLVM never formally states that it requires the value to be in normal form though, it just falls out of the logic.

Could you file an issue on the LLVM side with an example of the misbehavior you found? This should be documented in the LangRef.

tgross35 · 2026-10-15T22:28:00Z

+/// Combining a large `f64` with a small one provides meaningful extra precision, while
+/// being able to use existing `f64` hardware instructions.
+///
+/// # Normal form


Is "normal form" a term from somewhere? If not, perhaps uses of the term should be "valid representations" because it's usable vs. invalid. Rather than something like x87_f80 where there's a preferred form and pseudo forms, but you can use either without things breaking.

View changes since the review

tgross35 · 2026-10-15T22:50:36Z

+    ///
+    /// # Examples
+    ///
+    #[doc = ppcf128_doctest_prelude!()]


Nit: I'd move the ``` out of this macro and just put it before, since I know some syntax highlighters naively look for code fences in the docs which would break.

View changes since the review

I know, but we need to emit

/// ```only-powerpc

for doc builds. I think that all needs to be on one line, so I don't really see another way than having it just be part of the macro.

Ah that is kind of annoying. Could something like

rust/library/core/src/num/f128.rs

Lines 153 to 156 in 4ebd258

#[doc(test(attr(

feature(cfg_target_has_reliable_f16_f128),

allow(internal_features, unused_features)

)))]

work maybe? If it lets you add a cfg.

found a workaround with all(doc, not(doctest)), so the examples are shown in the docs, but don't actually get run by doctest on non-powerpc targets.

So now the triple backtics are no longer inside the macro, and overall the examples get a bit simpler.

tgross35 · 2026-10-15T23:42:59Z

+    #[unstable(feature = "powerpc_ppcf128", issue = "163323")]
+    #[rustc_const_unstable(feature = "powerpc_ppcf128", issue = "163323")]
+    #[inline]
+    pub const fn to_bits(self) -> u128 {


Code using to_bits often has a from_bits, which would have to be unsafe here. I think that makes the generic code argument less convincing.

rustbot · 2026-10-26T23:10:14Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

folkertdev added the F-c_longdouble `#![feature(c_longdouble)]` label Oct 9, 2026

folkertdev force-pushed the ppcf128-library-api branch from 1c271dd to 6a31122 Compare October 9, 2026 21:27

This comment has been minimized.

Sign in to view

folkertdev force-pushed the ppcf128-library-api branch from 6a31122 to 355c9be Compare October 12, 2026 11:07

rustbot assigned tgross35 Oct 12, 2026

folkertdev marked this pull request as ready for review October 12, 2026 11:27

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Oct 12, 2026

tgross35 reviewed Oct 14, 2026

View reviewed changes

beetrees reviewed Oct 14, 2026

View reviewed changes

Comment thread library/stdarch/crates/core_arch/src/powerpc/mod.rs Outdated

This comment has been minimized.

Sign in to view

folkertdev force-pushed the ppcf128-library-api branch from 2b4f5be to ae02207 Compare October 15, 2026 13:12

beetrees reviewed Oct 15, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

beetrees mentioned this pull request Oct 15, 2026

c-variadic: support ppcf128 #164004

Merged

folkertdev force-pushed the ppcf128-library-api branch from ae02207 to 24792b3 Compare October 15, 2026 21:36

This comment has been minimized.

Sign in to view

folkertdev force-pushed the ppcf128-library-api branch from 05ef1fc to df84afb Compare October 15, 2026 22:38

This comment has been minimized.

Sign in to view

tgross35 reviewed Oct 15, 2026

View reviewed changes

folkertdev force-pushed the ppcf128-library-api branch from df84afb to d1f8c30 Compare October 24, 2026 15:47

This comment has been minimized.

Sign in to view

folkertdev mentioned this pull request Oct 25, 2026

C interop: f80, f128 and c_longdouble rust-lang/goals#701

Open

This comment has been minimized.

Sign in to view

folkertdev added 5 commits October 27, 2026 00:08

add ppcf128 API

e8e2d61

doc updates

ee0b258

ignore doc tests on non-powerpc targets

366b6b5

add representations table

e967f98

remove to_bits and fix the doc prelude macro

7f937e4

folkertdev force-pushed the ppcf128-library-api branch from d1f8c30 to 7f937e4 Compare October 26, 2026 23:10

Value	Preferred Representation	Allowed Representations	Notes
+0.0	(+0.0, +0.0)	(+0.0, ±0.0)	Nonzero second components are not allowed
-0.0	(-0.0, -0.0)	(-0.0, ±0.0)	Nonzero second components are not allowed
+∞	(+∞, +0.0)	(+∞, ±0.0)	Nonzero second components are not allowed
-∞	(-∞, -0.0)	(-∞, ±0.0)	Nonzero second components are not allowed
NaN	(NaN, +0.0)	(NaN, *)	Any NaN is allowed in the first component, any representation is allowed in the second component
x ∈ ℝ	(x₁, x₂)	N/A	x₁ + x₂ must round to x₁

		/// large component. Creating a value with components that are not in normal form
		/// (e.g. with [`ppcf128::from_components_unchecked`]) is [undefined behavior].

	#[doc(test(attr(
	feature(cfg_target_has_reliable_f16_f128),
	allow(internal_features, unused_features)
	)))]

Conversation

folkertdev commented Oct 9, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

folkertdev commented Oct 12, 2026

Uh oh!

rustbot commented Oct 12, 2026

Uh oh!

rustbot commented Oct 12, 2026

Uh oh!

Uh oh!

tgross35 Oct 14, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tgross35 Oct 14, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tgross35 Oct 14, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

beetrees Oct 15, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

beetrees Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

tgross35 commented Oct 15, 2026

Uh oh!

This comment has been minimized.

folkertdev commented Oct 15, 2026

Uh oh!

This comment has been minimized.

tgross35 Oct 15, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tgross35 Oct 15, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

folkertdev commented Oct 9, 2026 •

edited by rustbot

Loading

tgross35 Oct 14, 2026 •

edited by rustbot

Loading

tgross35 Oct 14, 2026 •

edited by rustbot

Loading

tgross35 Oct 14, 2026 •

edited by rustbot

Loading

beetrees Oct 15, 2026 •

edited by rustbot

Loading

beetrees Oct 15, 2026 •

edited

Loading

tgross35 Oct 15, 2026 •

edited by rustbot

Loading

tgross35 Oct 15, 2026 •

edited by rustbot

Loading

tgross35 Oct 15, 2026 •

edited by rustbot

Loading