xref: /freebsd/share/man/man7/simd.7 (revision a8cc4671c06ab77d5551a74cdebced8d859cac76)

.\" 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 September 2, 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    S1     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       Ta        Ta    S1
.It    ldiv              Ta            Ta        Ta    S      Ta    S
.It    lldiv             Ta            Ta        Ta    S
.It    memchr            Ta            Ta        Ta    S1
.It    memcmp            Ta            Ta    S   Ta    S1     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    S1
.It    strcat            Ta            Ta        Ta    S      Ta    S
.It    strchr            Ta    S       Ta        Ta    S1     Ta    S
.It    strchrnul         Ta            Ta        Ta    S1
.It    strcmp            Ta            Ta    S   Ta    S      Ta    S
.It    strcpy            Ta            Ta        Ta    S1     Ta    S    Ta    S2
.It    strcspn           Ta            Ta        Ta    S2
.It    strlen            Ta            Ta    S   Ta    S1
.It    strncmp           Ta            Ta    S   Ta           Ta    S
.It    strncpy           Ta            Ta        Ta           Ta         Ta    S2
.It    strnlen           Ta            Ta        Ta    S1
.It    strrchr           Ta    S       Ta        Ta           Ta    S
.It    strspn            Ta            Ta        Ta    S2
.It    swab              Ta            Ta        Ta           Ta    S
.It    timingsafe_bcmp   Ta            Ta        Ta    S1
.It    timingsafe_memcmp 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.