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. Signed-off-by: Adhemerval Zanella <adhemerval.zanella@xxxxxxxxxx> --- man8/ld.so.8 | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/man8/ld.so.8 b/man8/ld.so.8 index cf03cb85e..ed27744cb 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,59 @@ 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 +.PP +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. +.PP +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. +.PP +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 +.PP +glibc 2.37 removed support for the legacy hardware capabilities. +. .SH SEE ALSO .BR ld (1), .BR ldd (1), -- 2.34.1
