Rollup merge of #124750 - ultrabear:ultrabear_softfloatdoc, r=workingjubilee

Document That `f16` And `f128` Hardware Support is Limited (v2)

This PR is identical to #123892, which was approved and merged but then removed from master by a force-push due to a [CI bug](https://rust-lang.zulipchat.com/#narrow/stream/242791-t-infra/topic/ci.20broken.3F).

r? ghost

Original PR description:

---

This adds a small paragraph to the recently added f16 and f128 types explaining that hardware support may be limited, and that performance may suffer as a result of that.

I mainly wrote this because I felt it may be useful to express in some form; as a launchpoint for readers of the documentation if they have issues with performance.

I tried to word the documentation in a way that doesn't create false assumptions (that f16/f128 is too slow to use, for instance), removing the software implementation part could mislead people to thinking that f16/f128 is only available on some platforms, not all, so I believe it is important to keep in.\
"not all *major* platforms" is specifically said so as to not be redundant, because not all platforms implement many things, but the average rustacean is probably going to be using x86_64 or aarch64 derived ISA's, which is who this documentation is targeted towards.

I'm not sure of the best way to word the documentation, or if it should even be added, but I feel like it may be useful to have (potentially in a reworded way, I'm not very confident in the current wording and cannot decide if that is because it is too vague to be useful or too specific to be generally correct).

1 files changed, 12 insertions, 0 deletions

diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs
index 18a9503cfd2..d8597369b9b 100644
--- a/library/core/src/primitive_docs.rs
+++ b/library/core/src/primitive_docs.rs
@@ -1133,6 +1133,12 @@ impl<T> (T,) {}
 /// bits. Please see [the documentation for [`prim@f32`] or [Wikipedia on
 /// half-precision values][wikipedia] for more information.
 ///
+/// 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
@@ -1232,6 +1238,12 @@ 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,
+/// 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