git: 0588819779cd - main - share/man/man7: document libc simd usage in new man page simd(7)
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Thu, 03 Aug 2023 22:55:51 UTC
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.