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
This commit is contained in:
parent
d8385768fb
commit
0588819779
@ -26,6 +26,7 @@ MAN= arch.7 \
|
||||
release.7 \
|
||||
sdoc.7 \
|
||||
security.7 \
|
||||
simd.7 \
|
||||
sizeof.7 \
|
||||
sprog.7 \
|
||||
stats.7 \
|
||||
|
226
share/man/man7/simd.7
Normal file
226
share/man/man7/simd.7
Normal file
@ -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.
|
Loading…
Reference in New Issue
Block a user