ld.so.8: Describe glibc Hardware capabilities

The feature was added on glibc 2.33 as a way to improve the path search,
since the legacy hardware capabilities combination scheme does not scale
properly with new hardware support.  The legacy support was removed non
glibc 2.37, so it is the only scheme currently supported.

Reviewed-by: Stefan Puiu <stefan.puiu@gmail.com>
Signed-off-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
[alx: ffix, srcfix, semantic newlines]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

1 files changed, 68 insertions, 1 deletions

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index 86dbcc697..eb6c2c8ff 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -208,6 +208,14 @@ The objects in
 .I list
 are delimited by colons.
 .TP
+.BI \-\-glibc-hwcaps-mask " list"
+only search built-in subdirectories if in
+.IR list .
+.TP
+.BI \-\-glibc-hwcaps-prepend " list"
+Search glibc-hwcaps subdirectories in
+.IR list .
+.TP
 .B \-\-inhibit\-cache
 Do not use
 .IR /etc/ld.so.cache .
@@ -808,7 +816,7 @@ as a temporary workaround to a library misconfiguration issue.)
 .I lib*.so*
 shared objects
 .SH NOTES
-.SS Hardware capabilities
+.SS Legacy Hardware capabilities (from glibc 2.5 to glibc 2.37)
 Some shared objects are compiled using hardware-specific instructions which do
 not exist on every CPU.
 Such objects should be installed in directories whose names define the
@@ -843,6 +851,65 @@ z900, z990, z9-109, z10, zarch
 .B x86 (32-bit only)
 acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx,
 mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm
+.P
+The legacy hardware capabilities support has the drawback that
+each new feature added grows the search path exponentially,
+because it has to be added to
+every combination of the other existing features.
+.P
+For instance, on x86 32-bit,
+if the hardware supports
+.B i686
+and
+.BR sse2 ,
+the resulting search path will be
+.BR i686/sse2:i686:sse2:. .
+A new capability
+.B newcap
+will set the search path to
+.BR newcap/i686/sse2:newcap/i686:newcap/sse2:newcap:i686/sse2:i686:sse2: .
+.\"
+.SS glibc Hardware capabilities (from glibc 2.33)
+.TP
+.\" The initial discussion on various pitfalls of the old scheme is
+.\" <https://sourceware.org/pipermail/libc-alpha/2020-May/113757.html>
+.\" and the patchset that proposes the glibc-hwcap support is
+.\" <https://sourceware.org/pipermail/libc-alpha/2020-June/115250.html>
+glibc 2.33 added a new hardware capability scheme,
+where under each CPU architecture,
+certain levels can be defined,
+grouping support for certain features or special instructions.
+Each architecture level has
+a fixed set of paths that it adds to the dynamic linker search list,
+depending on the hardware of the machine.
+Since each new architecture level is
+not combined with previously existing ones,
+the new scheme does not have the drawback of
+growing the dynamic linker search list uncontrollably.
+.P
+For instance, on x86 64-bit,
+if the hardware supports
+.B x86_64-v3
+(for instance Intel Haswell or AMD Excavator),
+the resulting search path will be
+.BR glibc-hwcaps/x86-64-v3:glibc-hwcaps/x86-64-v2:.
+.\" The x86_64 architectures levels are defined the official ABI:
+.\" <https://gitlab.com/x86-psABIs/x86-64-ABI/-/blob/master/x86-64-ABI/low-level-sys-info.tex>
+.\" The PowerPC and s390x are glibc defined ones based on chip
+.\" support (which maps to ISA levels).
+The following paths are currently supported, in priority order.
+.TP
+.B PowerPC (64-bit little-endian only)
+power10, power9
+.TP
+.B s390 (64-bit only)
+z16, z15, z14, z13
+.TP
+.B x86 (64-bit only)
+x86-64-v4, x86-64-v3, x86-64-v2
+.P
+glibc 2.37 removed support for the legacy hardware capabilities.
+.\"
 .SH SEE ALSO
 .BR ld (1),
 .BR ldd (1),