mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-21 18:27:22 +00:00
6c5ee6e55a
Some of the string functions in contrib/arm-optimized routines are SIMD enhanced which is not reflect on the simd(7) manpage. This commit addresses that and introduces a new label A for functions enhanced with the Arm ASIMD (Neon) extension. Approved by: emaste Reviewed by: fuz (GSoC mentor) MFC to: stable/14 Sponsored by: Google LLC (GSoC 2024) Differential Revision: https://reviews.freebsd.org/D45523
243 lines
7.8 KiB
Groff
243 lines
7.8 KiB
Groff
.\" 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 June 7, 2024
|
|
.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 for 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 A Ta Ta S1
|
|
.It ldiv Ta Ta Ta S Ta S
|
|
.It lldiv Ta Ta Ta S
|
|
.It memchr Ta A Ta Ta S1
|
|
.It memcmp Ta A Ta S Ta S1 Ta S
|
|
.It memccpy Ta Ta Ta S1
|
|
.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 memrchr Ta A Ta Ta S1
|
|
.It memset Ta A Ta S Ta S Ta S
|
|
.It rindex Ta A Ta Ta S1 Ta S
|
|
.It stpcpy Ta A Ta Ta S1
|
|
.It stpncpy Ta Ta Ta S1
|
|
.It strcat Ta Ta Ta S1 Ta S
|
|
.It strchr Ta A Ta Ta S1 Ta S
|
|
.It strchrnul Ta A Ta Ta S1
|
|
.It strcmp Ta S Ta S Ta S1 Ta S
|
|
.It strcpy Ta A Ta Ta S1 Ta S Ta S2
|
|
.It strcspn Ta Ta Ta S2
|
|
.It strlcat Ta Ta Ta S1
|
|
.It strlcpy Ta Ta Ta S1
|
|
.It strlen Ta A Ta S Ta S1
|
|
.It strncat Ta Ta Ta S1
|
|
.It strncmp Ta S Ta S Ta S1 Ta S
|
|
.It strncpy Ta Ta Ta S1 Ta Ta S2
|
|
.It strnlen Ta A Ta Ta S1
|
|
.It strrchr Ta A Ta Ta S1 Ta S
|
|
.It strpbrk Ta Ta Ta S2
|
|
.It strsep Ta Ta Ta S2
|
|
.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,
|
|
.Sy A Ns :\ Arm\ ASIMD (NEON).
|
|
.
|
|
.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.1
|
|
for
|
|
.Cm amd64 .
|
|
.Pp
|
|
A
|
|
.Nm
|
|
manual page appeared in
|
|
.Fx 14.1 .
|
|
.
|
|
.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.
|