[PATCH 4/5] ld.so.8: Describe glibc Hardware capabilities

Adhemerval Zanella
2023-10-18T17:31:25Z

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

Signed-off-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
---
man8/ld.so.8 | 47 ++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index a0020be98..0e742cddd 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 .
@@ -797,7 +805,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
@@ -832,6 +840,43 @@ 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
+.SS glibc Hardware capabilities (from glibc 2.33)
+The legacy hardware capabilities combinations has the drawback where each feature
+name incur in cascading extra paths added on the search path list, adding a lot of
+overhead on
+.B
+ld.so
+during library resolution. For instance, on x86 32-bit, if the hardware supports
+.B i686
+and
+.B sse2
+, the resulting search path will be
+.B
+i686/sse2:i686:sse2:. .
+A new capability
+.B newcap
+will set the search path to
+.B
+newcap/i686/sse2:newcap/i686:newcap/sse2:newcap:i686/sse2:i686:sse2: .
+
+The glibc 2.33 added a new hardware capability scheme, where each ABI can define a
+set of paths based on expected hardware support. Each path is added depending of
+the hardware of the machine, and they are not combined together. They also have
+priority over the legacy hardware capabilities. The following paths are currently
+supported.
+.TP
+.B PowerPC (64-bit little-endian only)
+power9, power10
+.TP
+.B s390 (64-bit only)
+z13, z14, z15, z16
+.TP
+.B x86 (64-bit only)
+x86-64-v2, x86-64-v3, x86-64-v4
+.TP
+
+The glibc 2.37 removed support for the legacy hardware capabilities.
+
.SH SEE ALSO
.BR ld (1),
.BR ldd (1),
--
2.34.1