[PATCH v2] ld.so.8: Update "Hardware capabilities" section for glibc 2.31.

[Carlos O'Donell <carlos@redhat.com>]

On 5/28/20 5:35 AM, Florian Weimer wrote:
> * Carlos O'Donell:
> 
>> +The following names are currently recognized as of the release of glibc 2.31:
>> +.\" This information comes from glibc's sysdeps/*/dl-procinfo.c and is
>> +.\" currently not directly documented in the glibc manual. We document
>> +.\" it here with the help of the glibc maintainers.
> 
> I'm not sure if this list is correct.  Did you filter the hwcap strings
> based on HWCAP_IMPORTANT?

This turned out to be much harder than expected. Here is the updated
list with all the filtering documented.

v2
- For each arch checked against 

8< --- 8< --- 8<
The "Hardware capabilities" section is seeing an update in upstream
glibc as we review how the search directories are handled between
the various architectures. In the meantime we should update the man
page to reflect the current set of search paths for all supported
target machines.

Signed-off-by: Carlos O'Donell <carlos@redhat.com>
---
 man8/ld.so.8 | 179 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 161 insertions(+), 18 deletions(-)

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index f34eca3d8..3dbb34a23 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -746,36 +746,179 @@ 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
 required hardware capabilities, such as
-.IR /usr/lib/sse2/ .
-The dynamic linker checks these directories against the hardware of the
-machine and selects the most suitable version of a given shared object.
-Hardware capability directories can be cascaded to combine CPU features.
-The list of supported hardware capability names depends on the CPU.
-The following names are currently recognized:
-.\" Presumably, this info comes from sysdeps/i386/dl-procinfo.c and
-.\" similar files
+.IR /usr/lib64/haswell/ .
+The dynamic linker checks these directories against the hardware of the machine
+and selects the most suitable version of a given shared object.  Hardware
+capability directories can be cascaded to combine CPU features.  The list of
+supported hardware capability names depends on the CPU.  The list of supported
+hardware capability names may change with each release of the C library and is
+considered an optimization, and should not be relied upon for correct operation
+of the application. Applications should provide a default non-optimized
+implementation that is installed in the default library search paths.
+Care should be taken when packaging such application with a package manager,
+particularly the scenario where an optimized library is being removed.  With
+certain package managers, particularly rpm, the newer version of the
+application is installed first, which means that for a period of time during
+the upgrade all applications that use the library may start with a mixed set of
+libraries e.g.  the old library from the feature-based search path, and new
+libraries from the upgrade. To avoid this scenario the new library version
+should delete all known optimized libraries in the post-install phase.
+.TP
+The following names are currently recognized as of the release of glibc 2.31:
+.\" This information comes from glibc's sysdeps/*/dl-procinfo.c and
+.\" sysdeps/*/dl-procinfo.h and is currently not directly documented in the
+.\" glibc manual. The analysis is non-trivial and requires some filtering
+.\" via _dl_string_platform(), _dl_string_hwcap() and HWCAP_IMPORTANT.
+.\" We document it here with the help of the glibc maintainers.
 .TP
 .B Alpha
-ev4, ev5, ev56, ev6, ev67
+.\" One item per line to allow comparison with source specification.
+.\" Notes:
+.\" - List current as of commit 38c67888183db1b6ac21f2f9681b8a384987dfe8.
+.\" - List exposed via _dl_string_platform() from GLRO(dl_alpha_platforms).
+ev4,
+ev5,
+ev56,
+ev6,
+ev67
+.TP
+.B Arm AArch32
+.\" One item per line to allow comparison with source specification.
+.\" Notes:
+.\" - List current as of commit 38c67888183db1b6ac21f2f9681b8a384987dfe8.
+.\" - List exposed via _dl_string_hwcap() from GLRO(dl_arm_cap_flags)
+.\"   which uses HWCAP_IMPORTANT to limit the list to vfp and neon.
+neon,
+vfp
+.TP
+.B Arm AArch64
+.\" One item per line to allow comparison with source specification.
+.\" Notes:
+.\" - List current as of commit 38c67888183db1b6ac21f2f9681b8a384987dfe8.
+.\" - List exposed via _dl_string_hwcap() from GLRO(dl_aarch64_cap_flags)
+.\"   which uses HWCAP_IMPORTANT to limit the list to atomics.
+atomics
+.TP
+.B C-Sky
+.\" One item per line to allow comparison with source specification.
+.\" Notes:
+.\" - List current as of commit 38c67888183db1b6ac21f2f9681b8a384987dfe8.
+.\" - List exposed via _dl_string_platform() from GLRO(dl_csky_platforms).
+ck610,
+ck807,
+ck810,
+ck860
 .TP
 .B MIPS
-loongson2e, loongson2f, octeon, octeon2
+.\" One item per line to allow comparison with source specification.
+.\" Notes:
+.\" - List current as of commit 38c67888183db1b6ac21f2f9681b8a384987dfe8.
+.\" - List exposed via _dl_string_platform() from GLRO(dl_mips_platforms).
+loongson2e,
+loongson2f,
+octeon,
+octeon2
 .TP
 .B PowerPC
-4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle,
-fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601,
-ppc64, smt, spe, ucache, vsx
+.\" One item per line to allow comparison with source specification.
+.\" Notes:
+.\" - List current as of commit 38c67888183db1b6ac21f2f9681b8a384987dfe8.
+.\" - List exposed via _dl_string_hwcap() from GLRO(dl_powerpc_cap_flags)
+.\"   which uses HWCAP_IMPORTANT to limit the list to altivec and dfp.
+.\" - Additional list exposed via _dl_string_platform() from a programmatic
+.\"   construction of power architecutre names (requires reading the code).
+altivec,
+dfp,
+power4,
+power5,
+power5+,
+power6,
+power6x,
+power7,
+power8,
+power9,
+ppc970,
+ppc-cell-be,
+ppca2,
+ppc405,
+ppc440,
+ppc464,
+ppc476
 .TP
 .B SPARC
-flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
+.\" One item per line to allow comparison with source specification.
+.\" Notes:
+.\" - List current as of commit 38c67888183db1b6ac21f2f9681b8a384987dfe8.
+.\" - List exposed via _dl_string_hwcap() from GLRO(dl_sparc_cap_flags)
+.\"   which uses HWCAP_IMPORTANT to limit the list to v9, ultra3,
+.\"   v9v (HWCAP_SPARC_BLKINIT), and v9v2 (HWCAP_SPARC_N2).
+ultra3,
+v9 (32-bit only),
+v9v,
+v9v2
 .TP
 .B s390
-dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle,
-z900, z990, z9-109, z10, zarch
+.\" One item per line to allow comparison with source specification.
+.\" Notes:
+.\" - etf3enh and hpage deprecated in glibc 2.17 by commit
+.\"   0ab234b7db4991121eb572bf5c4971bfeb2d49a2.
+.\" - List current as of commit 38c67888183db1b6ac21f2f9681b8a384987dfe8.
+.\" - List exposed via _dl_string_hwcap() from GLRO(dl_s390_cap_flags)
+.\"   which uses HWCAP_IMPORTANT to limit the list to zarch, ldisp,
+.\"   eimm, dfp, vx, vxe, and vxe2.
+.\" - Additional list exposed via _dl_string_platform() from
+.\"   GLRO(dl_s390_platforms). 
+dfp,
+eimm,
+g5,
+ldisp,
+vx,
+vxe,
+vxe2,
+z10,
+z13,
+z14,
+z15,
+z196,
+z900,
+z9-109,
+z990,
+zarch,
+zEC12
 .TP
 .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
+.\" One item per line to allow comparison with source specification.
+.\" Notes:
+.\" - i386 and i486 deprecated in glibc 2.26 by commit
+.\"   1432d38ea04ab5e96f21a382101856db5b49ad8a
+.\" - List current as of commit 38c67888183db1b6ac21f2f9681b8a384987dfe8.
+.\" - List is exposed via _dl_string_hwcap() from GLRO(dl_x86_hwcap_flags)
+.\"   and uses HWCAP_IMPORTANT to limit the list to sse2. 
+.\"   - Defined in sysdeps/x86/dl-hwcap.h (not the normal place for this).
+.\" - Additional list exposed via _dl_string_platform() from
+.\"   GLRO(dl_x86_platforms) and filtered via HWCAP_PLATFORMS_START and
+.\"   HWCAP_PLATFORMS_COUNT.
+sse2,
+i386 (removed in glibc 2.26),
+i486 (removed in glibc 2.26),
+i586,
+i686
+.TP
+.B x86 (64-bit only)
+.\" One item per line to allow comparison with source specification.
+.\" Notes:
+.\" - Added haswell, and xeon-phi in glibc 2.26 with commit
+.\"   1432d38ea04ab5e96f21a382101856db5b49ad8a
+.\" - List current as of commit 38c67888183db1b6ac21f2f9681b8a384987dfe8.
+.\" - List is exposed via _dl_string_hwcap() from GLRO(dl_x86_hwcap_flags) 
+.\"   and uses HWCAP_IMPORTANT to limit the list to x86_64 and avx512_1.
+.\" - Additional list exposed via _dl_string_platform() from
+.\"   GLRO(dl_x86_platforms) and filtered via HWCAP_PLATFORMS_START and
+.\"   HWCAP_PLATFORMS_COUNT.
+x86_64,
+avx512_1,
+haswell (since glibc 2.26),
+xeon-phi (since glibc 2.26)
 .SH SEE ALSO
 .BR ld (1),
 .BR ldd (1),
-- 
2.26.2