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

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

[Adhemerval Zanella]

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

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

[Stefan Puiu]

On Thu, Oct 26, 2023 at 9:28 PM Adhemerval Zanella
<adhemerval.zanella@linaro.org> 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>
> ---
>  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),

LGTM, thanks!

Stefan.

> --
> 2.34.1
>

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

[Alejandro Colomar]

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

Hi Stefan,

On Fri, Oct 27, 2023 at 11:57:51AM +0300, Stefan Puiu wrote:
> LGTM, thanks!

Should I count that as an acked-by?

Cheers,
Alex

> 
> Stefan.
> 
> > --
> > 2.34.1
> >

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

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

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

[Stefan Puiu]

Hi again Alex,

(hopefully this time without HTML)

On Fri, Oct 27, 2023 at 12:43 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Stefan,
>
> On Fri, Oct 27, 2023 at 11:57:51AM +0300, Stefan Puiu wrote:
> > LGTM, thanks!
>
> Should I count that as an acked-by?
Yes. Didn't know the procedure for saying that with tags.

Thanks,
Stefan.

>
> Cheers,
> Alex
>
> >
> > Stefan.
> >
> > > --
> > > 2.34.1
> > >
>
> --
> <https://www.alejandro-colomar.es/>

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

[Alejandro Colomar]

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

Hi Stefan,

On Fri, Oct 27, 2023 at 01:37:42PM +0300, Stefan Puiu wrote:
> Hi again Alex,
> 
> (hopefully this time without HTML)

Yup; there's no HTML this time.

> 
> On Fri, Oct 27, 2023 at 12:43 PM Alejandro Colomar <alx@kernel.org> wrote:
> >
> > Hi Stefan,
> >
> > On Fri, Oct 27, 2023 at 11:57:51AM +0300, Stefan Puiu wrote:
> > > LGTM, thanks!
> >
> > Should I count that as an acked-by?
> Yes. Didn't know the procedure for saying that with tags.

Thanks!
Alex

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

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

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

[Alejandro Colomar]

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

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

[Alejandro Colomar]

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

On Fri, Oct 27, 2023 at 01:37:42PM +0300, Stefan Puiu wrote:
> Hi again Alex,
> 
> (hopefully this time without HTML)
> 
> On Fri, Oct 27, 2023 at 12:43 PM Alejandro Colomar <alx@kernel.org> wrote:
> >
> > Hi Stefan,
> >
> > On Fri, Oct 27, 2023 at 11:57:51AM +0300, Stefan Puiu wrote:
> > > LGTM, thanks!
> >
> > Should I count that as an acked-by?
> Yes. Didn't know the procedure for saying that with tags.

Heh, in the end I had a short-circuit in my brain and wrote Reviewed-by.  :)

> 
> Thanks,
> Stefan.
> 
> >
> > Cheers,
> > Alex
> >
> > >
> > > Stefan.
> > >
> > > > --
> > > > 2.34.1
> > > >
> >
> > --
> > <https://www.alejandro-colomar.es/>

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

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