Re: [PATCH v4] ld.so.8: Describe glibc Hardware capabilities

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 8108 bytes --]

Hi Adhemerval, Stefan,

On Thu, Oct 26, 2023 at 03:28:02PM -0300, Adhemerval Zanella wrote:
> 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@linaro.org>

Patch applied.  Thanks!  I amended the patch with some small tweaks (see
diff below).
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=eb82265f495a2c55e76c213c7b877b8eafc2d2a4>

Cheers,
Alex

---

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index 3526bcd6e..eb6c2c8ff 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -851,44 +851,50 @@ .SS Legacy Hardware capabilities (from glibc 2.5 to glibc 2.37)
 .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
+.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 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
+.\" <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
+.\" <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
+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
+(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
+.\" <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.
@@ -901,9 +907,9 @@ .SS glibc Hardware capabilities (from glibc 2.33)
 .TP
 .B x86 (64-bit only)
 x86-64-v4, x86-64-v3, x86-64-v2
-.PP
+.P
 glibc 2.37 removed support for the legacy hardware capabilities.
-.
+.\"
 .SH SEE ALSO
 .BR ld (1),
 .BR ldd (1),

> ---
>  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
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]