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

[Alejandro Colomar <alx@kernel.org>]

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

Hi Adhemerval,

On Wed, Oct 18, 2023 at 02:21:03PM -0300, Adhemerval Zanella wrote:
> 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

Please don't use more than 80 columns in man(7) source.  See this
warning:

$ make --debug=print lint-man-mandoc
LINT (mandoc)	.tmp/man/man8/ld.so.8.lint-man.mandoc.touch
! (mandoc -man -Tlint  man8/ld.so.8 2>&1 \
   | grep -v -f './share/lint/mandoc/man.ignore.grep' \
   ||:; \
) \
| grep ^ >&2
mandoc: man8/ld.so.8:849:81: STYLE: input text line longer than 80 bytes: The legacy hardware ...
mandoc: man8/ld.so.8:850:82: STYLE: input text line longer than 80 bytes: name incur in cascad...
mandoc: man8/ld.so.8:854:81: STYLE: input text line longer than 80 bytes: during library resol...
mandoc: man8/ld.so.8:867:82: STYLE: input text line longer than 80 bytes: The glibc 2.33 added...
mandoc: man8/ld.so.8:870:81: STYLE: input text line longer than 80 bytes: priority over the le...
mandoc: man8/ld.so.8:882:1: WARNING: skipping blank line in line scope
make: *** [share/mk/lint/man/man.mk:32: .tmp/man/man8/ld.so.8.lint-man.mandoc.touch] Error 1

> +name incur in cascading extra paths added on the search path list, adding a lot of

Also, please use semantic newlines.  See man-pages(7):

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
       In the source of a manual page, new sentences should be started
       on  new  lines,  long  sentences  should be split into lines at
       clause breaks (commas, semicolons, colons, and so on), and long
       clauses should be split at phrase boundaries.  This convention,
       sometimes known as "semantic newlines", makes it easier to  see
       the  effect of patches, which often operate at the level of in‐
       dividual sentences, clauses, or phrases.

> +overhead on
> +.B
> +ld.so

We prefer having it all in one line:  .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: .
> +

Please don't use blank lines in man(7) source.  If you want a paragraph
separator, use '.PP'.  See this warning:

$ make build-catman
TROFF	.tmp/man/man8/ld.so.8.cat.set
an.tmac:man8/ld.so.8:866: style: blank line in input
an.tmac:man8/ld.so.8:882: style: blank line in input
an.tmac:man8/ld.so.8:884: style: blank line in input
make: *** [share/mk/build/catman.mk:54: .tmp/man/man8/ld.so.8.cat.set] Error 1
make: *** Deleting file '.tmp/man/man8/ld.so.8.cat.set'


> +The glibc 2.33 added a new hardware capability scheme, where each ABI can define a

s/The //
s/, /,\n/

> +set of paths based on expected hardware support. Each path is added depending of

s/\. /\.\n/

(And if we ever had two sentences in the same source line, there should
be two spaces.  But we don't.)

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

TP means tagged paragraph.  If you don't want a _tagged_ paragraph, you
just want a paragraph, which is PP.

> +The glibc 2.37 removed support for the legacy hardware capabilities.
> +

This blank is unnecessary, although you may want some separator before
the .SH, for which '.' or '.\"' would be acceptable.

Thanks,
Alex

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