Skip site navigation (1)Skip section navigation (2)
Date:      Thu, 3 Aug 2023 22:55:51 GMT
From:      Robert Clausecker <fuz@FreeBSD.org>
To:        src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org
Subject:   git: 0588819779cd - main - share/man/man7: document libc simd usage in new man page simd(7)
Message-ID:  <202308032255.373Mtp3i072052@gitrepo.freebsd.org>

next in thread | raw e-mail | index | archive | help
The branch main has been updated by fuz:

URL: https://cgit.FreeBSD.org/src/commit/?id=0588819779cd82dc8fd9a1b63bcb531b296986eb

commit 0588819779cd82dc8fd9a1b63bcb531b296986eb
Author:     Robert Clausecker <fuz@FreeBSD.org>
AuthorDate: 2023-08-03 22:51:31 +0000
Commit:     Robert Clausecker <fuz@FreeBSD.org>
CommitDate: 2023-08-03 22:54:44 +0000

    share/man/man7: document libc simd usage in new man page simd(7)
    
    This documents SIMD usage in libc for all architectures with
    specific details on the new amd64 SIMD dispatch framework.
    
    Sponsored by:   The FreeBSD Foundation
    Approved by:    kib
    Reviewed by:    imp
    Differential Revision:  https://reviews.freebsd.org/D40693
---
 share/man/man7/Makefile |   1 +
 share/man/man7/simd.7   | 226 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 227 insertions(+)

diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile
index f50e31cdeb11..56ade5092275 100644
--- a/share/man/man7/Makefile
+++ b/share/man/man7/Makefile
@@ -26,6 +26,7 @@ MAN=	arch.7 \
 	release.7 \
 	sdoc.7 \
 	security.7 \
+	simd.7 \
 	sizeof.7 \
 	sprog.7 \
 	stats.7 \
diff --git a/share/man/man7/simd.7 b/share/man/man7/simd.7
new file mode 100644
index 000000000000..c8e17cb9e0ef
--- /dev/null
+++ b/share/man/man7/simd.7
@@ -0,0 +1,226 @@
+.\" Copyright (c) 2023 The FreeBSD Foundation
+.
+.\" This documentation was written by Robert Clausecker <fuz@FreeBSD.org>
+.\" under sponsorship from the FreeBSD Foundation.
+.
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ''AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE
+.
+.Dd July 3, 2023
+.Dt SIMD 7
+.Os
+.Sh NAME
+.Nm simd
+.Nd SIMD enhancements
+.
+.Sh DESCRIPTION
+On some architectures, the
+.Fx
+.Em libc
+provides enhanced implementations of commonly used functions, replacing
+the architecture-independent implementations used otherwise.
+Depending on architecture and function, an enhanced
+implementation of a function may either always be used or the
+.Em libc
+detects at runtime which SIMD instruction set extensions are
+supported and picks the most suitable implementation automatically.
+On
+.Cm amd64 ,
+the environment variable
+.Ev ARCHLEVEL
+can be used to override this mechanism.
+.Pp
+Enhanced functions are present in the following architectures:
+.Bl -column FUNCTION_ aarch64_ arm_ amd64_ i386_ ppc64_ -offset indent
+.It Em FUNCTION Ta Em AARCH64 Ta Em ARM Ta Em AMD64  Ta Em I386 Ta Em PPC64
+.It    bcmp     Ta            Ta        Ta    S      Ta    S
+.It    bcopy    Ta            Ta    S   Ta    S      Ta    S    Ta    SV
+.It    bzero    Ta            Ta    S   Ta    S      Ta    S
+.It    div      Ta            Ta        Ta    S      Ta    S
+.It    index    Ta    S
+.It    ldiv     Ta            Ta        Ta    S      Ta    S
+.It    lldiv    Ta            Ta        Ta    S
+.It    memcmp   Ta            Ta    S   Ta    S      Ta    S
+.It    memcpy   Ta    S       Ta    S   Ta    S      Ta    S    Ta    SV
+.It    memmove  Ta    S       Ta    S   Ta    S      Ta    S    Ta    SV
+.It    memset   Ta            Ta    S   Ta    S      Ta    S
+.It    rindex   Ta    S
+.It    stpcpy   Ta            Ta        Ta    S
+.It    strcat   Ta            Ta        Ta    S      Ta    S
+.It    strchr   Ta    S       Ta        Ta           Ta    S
+.It    strcmp   Ta            Ta    S   Ta    S      Ta    S
+.It    strcpy   Ta            Ta        Ta    S      Ta    S    Ta    S2
+.It    strlen   Ta            Ta    S   Ta    S134
+.It    strncmp  Ta            Ta    S   Ta           Ta    S
+.It    strncpy  Ta            Ta        Ta           Ta         Ta    S2
+.It    strrchr  Ta    S       Ta        Ta           Ta    S
+.It    swab     Ta            Ta        Ta           Ta    S
+.It    wcschr   Ta            Ta        Ta           Ta    S
+.It    wcscmp   Ta            Ta        Ta           Ta    S
+.It    wcslen   Ta            Ta        Ta           Ta    S
+.It    wmemchr  Ta            Ta        Ta           Ta    S
+.El
+.Pp
+.Sy S Ns :\ scalar (non-SIMD),
+.Sy 1 Ns :\ amd64 baseline,
+.Sy 2 Ns :\ x86-64-v2
+or PowerPC\ 2.05,
+.Sy 3 Ns :\ x86-64-v3,
+.Sy 4 Ns :\ x86-64-v4,
+.Sy V Ns :\ PowerPC\ VSX.
+.
+.Sh ENVIRONMENT
+.Bl -tag
+.It Ev ARCHLEVEL
+On
+.Em amd64 ,
+controls the level of SIMD enhancements used.
+If this variable is set to an architecture level from the list below
+and that architecture level is supported by the processor, SIMD
+enhancements up to
+.Ev ARCHLEVEL
+are used.
+If
+.Ev ARCHLEVEL
+is unset, not recognised, or not supported by the processor, the highest
+level of SIMD enhancements supported by the processor is used.
+.Pp
+A suffix beginning with
+.Sq ":"
+or
+.Sq "+"
+in
+.Ev ARCHLEVEL
+is ignored and may be used for future extensions.
+The architecture level can be prefixed with a
+.Sq "!"
+character to force use of the requested architecture level, even if the
+processor does not advertise that it is supported.
+This usually causes applications to crash and should only be used for
+testing purposes or if architecture level detection yields incorrect
+results.
+.Pp
+The architecture levels follow the AMD64 SysV ABI supplement:
+.Bl -tag -width x86-64-v2
+.It Cm scalar
+scalar enhancements only (no SIMD)
+.It Cm baseline
+cmov, cx8, x87 FPU, fxsr, MMX, osfxsr, SSE, SSE2
+.It Cm x86-64-v2
+cx16, lahf/sahf, popcnt, SSE3, SSSE3, SSE4.1, SSE4.2
+.It Cm x86-64-v3
+AVX, AVX2, BMI1, BMI2, F16C, FMA, lzcnt, movbe, osxsave
+.It Cm x86-64-v4
+AVX-512F/BW/CD/DQ/VL
+.El
+.El
+.
+.Sh DIAGNOSTICS
+.Bl -diag
+.It "Illegal Instruction"
+Printed by
+.Xr sh 1
+if a command is terminated through delivery of a
+.Dv SIGILL
+signal, see
+.Xr signal 3 .
+.Pp
+Use of an unsupported architecture level was forced by setting
+.Ev ARCHLEVEL
+to a string beginning with a
+.Sq "!"
+character, causing a process to crash due to use of an unsupported
+instruction.
+Unset
+.Ev ARCHLEVEL ,
+remove the
+.Sq "!"
+prefix or select a supported architecture level.
+.Pp
+Message may also appear for unrelated reasons.
+.El
+.
+.Sh SEE ALSO
+.Xr string 3 ,
+.Xr arch 7
+.Rs
+.%A H. J. Lu
+.%A Michael Matz
+.%A Milind Girkar
+.%A Jan Hubi\[u010D]ka \" \(vc
+.%A Andreas Jaeger
+.%A Mark Mitchell
+.%B System V Application Binary Interface
+.%D May 23, 2023
+.%T AMD64 Architecture Processor Supplement
+.%O Version 1.0
+.Re
+.
+.Sh HISTORY
+Architecture-specific enhanced
+.Em libc
+functions were added starting
+with
+.Fx 2.0
+for
+.Cm i386 ,
+.Fx 6.0
+for
+.Cm arm ,
+.Fx 6.1
+for
+.Cm amd64 ,
+.Fx 11.0
+for
+.Cm aarch64 ,
+and
+.Fx 12.0
+for
+.Cm powerpc64 .
+SIMD-enhanced functions were first added with
+.Fx 13.0
+for
+.Cm powerpc64
+and with
+.Fx 14.0
+for
+.Cm amd64 .
+.Pp
+A
+.Nm
+manual page appeared in
+.Fx 14.0 .
+.
+.Sh AUTHOR
+.An Robert Clausecker Aq Mt fuz@FreeBSD.org
+.
+.Sh CAVEATS
+Other parts of
+.Fx
+such as cryptographic routines in the kernel or in
+OpenSSL may also use SIMD enhancements.
+These enhancements are not subject to the
+.Ev ARCHLEVEL
+variable and may have their own configuration
+mechanism.
+.
+.Sh BUGS
+Use of SIMD enhancements cannot be configured on powerpc64.



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202308032255.373Mtp3i072052>