From 3fd8c6432df4396c7f593e570a27b8d7c1a78b5b Mon Sep 17 00:00:00 2001 From: ultrabear Date: Sat, 13 Apr 2024 04:15:10 -0700 Subject: [PATCH 1/4] doc note that f16 and f128 hardware support is limited --- library/core/src/primitive_docs.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index e8e23f2a7ecc5..6b142c1a0cdf4 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1082,6 +1082,9 @@ impl (T,) {} /// bits. Please see [the documentation for [`prim@f32`] or [Wikipedia on /// half-precision values][wikipedia] for more information. /// +/// Note that not all major platforms have hardware support for f16, in which case a +/// software implementation will be used. This may be slower than expected. +/// /// *[See also the `std::f16::consts` module](crate::f16::consts).* /// /// [wikipedia]: https://en.wikipedia.org/wiki/Half-precision_floating-point_format @@ -1181,6 +1184,9 @@ mod prim_f64 {} /// as many bits as `f64`. Please see [the documentation for [`prim@f32`] or [Wikipedia on /// quad-precision values][wikipedia] for more information. /// +/// Note that not all major platforms have hardware support for f128, in which case a +/// software implementation will be used. This may be slower than expected. +/// /// *[See also the `std::f128::consts` module](crate::f128::consts).* /// /// [wikipedia]: https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format From e30ad6ff2c5c83823438a9a3d872a8c5da82807e Mon Sep 17 00:00:00 2001 From: Alex H Date: Sun, 14 Apr 2024 11:55:00 -0700 Subject: [PATCH 2/4] Tgross feedback tweaks Co-authored-by: Trevor Gross Update library/core/src/primitive_docs.rs Co-authored-by: Trevor Gross Update library/core/src/primitive_docs.rs --- library/core/src/primitive_docs.rs | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 6b142c1a0cdf4..b1bc3ba111238 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1082,9 +1082,8 @@ impl (T,) {} /// bits. Please see [the documentation for [`prim@f32`] or [Wikipedia on /// half-precision values][wikipedia] for more information. /// -/// Note that not all major platforms have hardware support for f16, in which case a -/// software implementation will be used. This may be slower than expected. -/// +/// Note that most major platforms will provide `f16` math support by converting to and from +/// an `f32`, which is usually fairly performant but will not be as fast as using `f32` directly. /// *[See also the `std::f16::consts` module](crate::f16::consts).* /// /// [wikipedia]: https://en.wikipedia.org/wiki/Half-precision_floating-point_format @@ -1184,8 +1183,8 @@ mod prim_f64 {} /// as many bits as `f64`. Please see [the documentation for [`prim@f32`] or [Wikipedia on /// quad-precision values][wikipedia] for more information. /// -/// Note that not all major platforms have hardware support for f128, in which case a -/// software implementation will be used. This may be slower than expected. +/// Note that most major platforms do not have hardware support for `f128`, in which case a +/// software implementation will be used. This can be significantly slower than using `f64`. /// /// *[See also the `std::f128::consts` module](crate::f128::consts).* /// From 3ef25288a4a68e4bdc03115cee9b259f33fa5b2d Mon Sep 17 00:00:00 2001 From: Alex H Date: Sun, 14 Apr 2024 23:17:44 -0700 Subject: [PATCH 3/4] Make f16 and f128 docs clearer on platform support Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com> Update library/core/src/primitive_docs.rs Rewrite f16 and f128 hw support comments to match PR feedback I wrote RISC-V allcaps in all cases, and wrote amd64 lowercase in all cases, im not sure if either is the more correct way for either platform, thats just how I normally write them, if theres a precedent elsewhere it should probably be changed to match though. Update library/core/src/primitive_docs.rs Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com> Update library/core/src/primitive_docs.rs Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com> Update library/core/src/primitive_docs.rs --- library/core/src/primitive_docs.rs | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index b1bc3ba111238..7fa119b5006ec 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1082,8 +1082,12 @@ impl (T,) {} /// bits. Please see [the documentation for [`prim@f32`] or [Wikipedia on /// half-precision values][wikipedia] for more information. /// -/// Note that most major platforms will provide `f16` math support by converting to and from -/// an `f32`, which is usually fairly performant but will not be as fast as using `f32` directly. +/// Note that most common platforms will not support `f16` in hardware without enabling extra target +/// features, with the notable exception of Apple Silicon (also known as M1, M2, etc.) processors. +/// Hardware support on x86-64 requires the avx512fp16 feature, while RISC-V requires Zhf. +/// Usually the fallback implementation will be to use `f32` hardware if it exists, and convert +/// between `f16` and `f32` when performing math. +/// /// *[See also the `std::f16::consts` module](crate::f16::consts).* /// /// [wikipedia]: https://en.wikipedia.org/wiki/Half-precision_floating-point_format @@ -1183,12 +1187,15 @@ mod prim_f64 {} /// as many bits as `f64`. Please see [the documentation for [`prim@f32`] or [Wikipedia on /// quad-precision values][wikipedia] for more information. /// -/// Note that most major platforms do not have hardware support for `f128`, in which case a -/// software implementation will be used. This can be significantly slower than using `f64`. +/// Note that no platforms have hardware support for `f128` without enabling target specific features +/// (and [only some consumer level hardware has support][wikipedia-support], for example RISC-V has support, but +/// neither amd64 nor aarch64 has support), in which case a software implementation will be used. This can be +/// significantly slower than using `f64`. /// /// *[See also the `std::f128::consts` module](crate::f128::consts).* /// /// [wikipedia]: https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format +/// [wikipedia-support]: https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format#Hardware_support #[unstable(feature = "f128", issue = "116909")] mod prim_f128 {} From 5aa2f9a208162389a743c45cebb72a994effca1c Mon Sep 17 00:00:00 2001 From: Alex H Date: Sat, 4 May 2024 12:54:34 -0700 Subject: [PATCH 4/4] Make f128 docs mention lack of any normal platform support Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com> Update library/core/src/primitive_docs.rs Remove orphaned doc link and clean up grammar a bit Update library/core/src/primitive_docs.rs --- library/core/src/primitive_docs.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 7fa119b5006ec..cc369f1733fe1 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1187,15 +1187,15 @@ mod prim_f64 {} /// as many bits as `f64`. Please see [the documentation for [`prim@f32`] or [Wikipedia on /// quad-precision values][wikipedia] for more information. /// -/// Note that no platforms have hardware support for `f128` without enabling target specific features -/// (and [only some consumer level hardware has support][wikipedia-support], for example RISC-V has support, but -/// neither amd64 nor aarch64 has support), in which case a software implementation will be used. This can be -/// significantly slower than using `f64`. +/// Note that no platforms have hardware support for `f128` without enabling target specific features, +/// as for all instruction set architectures `f128` is considered an optional feature. +/// Only Power ISA ("PowerPC") and RISCV specify it, and only certain microarchitectures +/// actually implement it. For x86-64 and AArch64, ISA support is not even specified, +/// so it will always be a software implementation significantly slower than `f64`. /// /// *[See also the `std::f128::consts` module](crate::f128::consts).* /// /// [wikipedia]: https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format -/// [wikipedia-support]: https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format#Hardware_support #[unstable(feature = "f128", issue = "116909")] mod prim_f128 {}