1.\" Copyright (c) 2023 The FreeBSD Foundation 2. 3.\" This documentation was written by Robert Clausecker <fuz@FreeBSD.org> 4.\" under sponsorship from the FreeBSD Foundation. 5. 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14. 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ''AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE 26. 27.Dd August 31, 2023 28.Dt SIMD 7 29.Os 30.Sh NAME 31.Nm simd 32.Nd SIMD enhancements 33. 34.Sh DESCRIPTION 35On some architectures, the 36.Fx 37.Em libc 38provides enhanced implementations of commonly used functions, replacing 39the architecture-independent implementations used otherwise. 40Depending on architecture and function, an enhanced 41implementation of a function may either always be used or the 42.Em libc 43detects at runtime which SIMD instruction set extensions are 44supported and picks the most suitable implementation automatically. 45On 46.Cm amd64 , 47the environment variable 48.Ev ARCHLEVEL 49can be used to override this mechanism. 50.Pp 51Enhanced functions are present in the following architectures: 52.Bl -column FUNCTION________ aarch64_ arm_ amd64_ i386_ ppc64_ -offset indent 53.It Em FUNCTION Ta Em AARCH64 Ta Em ARM Ta Em AMD64 Ta Em I386 Ta Em PPC64 54.It bcmp Ta Ta Ta S1 Ta S 55.It bcopy Ta Ta S Ta S Ta S Ta SV 56.It bzero Ta Ta S Ta S Ta S 57.It div Ta Ta Ta S Ta S 58.It index Ta S Ta Ta S1 59.It ldiv Ta Ta Ta S Ta S 60.It lldiv Ta Ta Ta S 61.It memchr Ta Ta Ta S1 62.It memcmp Ta Ta S Ta S1 Ta S 63.It memcpy Ta S Ta S Ta S Ta S Ta SV 64.It memmove Ta S Ta S Ta S Ta S Ta SV 65.It memset Ta Ta S Ta S Ta S 66.It rindex Ta S 67.It stpcpy Ta Ta Ta S1 68.It strcat Ta Ta Ta S Ta S 69.It strchr Ta S Ta Ta S1 Ta S 70.It strchrnul Ta Ta Ta S1 71.It strcmp Ta Ta S Ta S Ta S 72.It strcpy Ta Ta Ta S1 Ta S Ta S2 73.It strcspn Ta Ta Ta S2 74.It strlen Ta Ta S Ta S1 75.It strncmp Ta Ta S Ta Ta S 76.It strncpy Ta Ta Ta Ta Ta S2 77.It strnlen Ta Ta Ta S1 78.It strrchr Ta S Ta Ta Ta S 79.It strspn Ta Ta Ta S2 80.It swab Ta Ta Ta Ta S 81.It timingsafe_bcmp Ta Ta Ta S1 82.It wcschr Ta Ta Ta Ta S 83.It wcscmp Ta Ta Ta Ta S 84.It wcslen Ta Ta Ta Ta S 85.It wmemchr Ta Ta Ta Ta S 86.El 87.Pp 88.Sy S Ns :\ scalar (non-SIMD), 89.Sy 1 Ns :\ amd64 baseline, 90.Sy 2 Ns :\ x86-64-v2 91or PowerPC\ 2.05, 92.Sy 3 Ns :\ x86-64-v3, 93.Sy 4 Ns :\ x86-64-v4, 94.Sy V Ns :\ PowerPC\ VSX. 95. 96.Sh ENVIRONMENT 97.Bl -tag 98.It Ev ARCHLEVEL 99On 100.Em amd64 , 101controls the level of SIMD enhancements used. 102If this variable is set to an architecture level from the list below 103and that architecture level is supported by the processor, SIMD 104enhancements up to 105.Ev ARCHLEVEL 106are used. 107If 108.Ev ARCHLEVEL 109is unset, not recognised, or not supported by the processor, the highest 110level of SIMD enhancements supported by the processor is used. 111.Pp 112A suffix beginning with 113.Sq ":" 114or 115.Sq "+" 116in 117.Ev ARCHLEVEL 118is ignored and may be used for future extensions. 119The architecture level can be prefixed with a 120.Sq "!" 121character to force use of the requested architecture level, even if the 122processor does not advertise that it is supported. 123This usually causes applications to crash and should only be used for 124testing purposes or if architecture level detection yields incorrect 125results. 126.Pp 127The architecture levels follow the AMD64 SysV ABI supplement: 128.Bl -tag -width x86-64-v2 129.It Cm scalar 130scalar enhancements only (no SIMD) 131.It Cm baseline 132cmov, cx8, x87 FPU, fxsr, MMX, osfxsr, SSE, SSE2 133.It Cm x86-64-v2 134cx16, lahf/sahf, popcnt, SSE3, SSSE3, SSE4.1, SSE4.2 135.It Cm x86-64-v3 136AVX, AVX2, BMI1, BMI2, F16C, FMA, lzcnt, movbe, osxsave 137.It Cm x86-64-v4 138AVX-512F/BW/CD/DQ/VL 139.El 140.El 141. 142.Sh DIAGNOSTICS 143.Bl -diag 144.It "Illegal Instruction" 145Printed by 146.Xr sh 1 147if a command is terminated through delivery of a 148.Dv SIGILL 149signal, see 150.Xr signal 3 . 151.Pp 152Use of an unsupported architecture level was forced by setting 153.Ev ARCHLEVEL 154to a string beginning with a 155.Sq "!" 156character, causing a process to crash due to use of an unsupported 157instruction. 158Unset 159.Ev ARCHLEVEL , 160remove the 161.Sq "!" 162prefix or select a supported architecture level. 163.Pp 164Message may also appear for unrelated reasons. 165.El 166. 167.Sh SEE ALSO 168.Xr string 3 , 169.Xr arch 7 170.Rs 171.%A H. J. Lu 172.%A Michael Matz 173.%A Milind Girkar 174.%A Jan Hubi\[u010D]ka \" \(vc 175.%A Andreas Jaeger 176.%A Mark Mitchell 177.%B System V Application Binary Interface 178.%D May 23, 2023 179.%T AMD64 Architecture Processor Supplement 180.%O Version 1.0 181.Re 182. 183.Sh HISTORY 184Architecture-specific enhanced 185.Em libc 186functions were added starting 187with 188.Fx 2.0 189for 190.Cm i386 , 191.Fx 6.0 192for 193.Cm arm , 194.Fx 6.1 195for 196.Cm amd64 , 197.Fx 11.0 198for 199.Cm aarch64 , 200and 201.Fx 12.0 202for 203.Cm powerpc64 . 204SIMD-enhanced functions were first added with 205.Fx 13.0 206for 207.Cm powerpc64 208and with 209.Fx 14.0 210for 211.Cm amd64 . 212.Pp 213A 214.Nm 215manual page appeared in 216.Fx 14.0 . 217. 218.Sh AUTHOR 219.An Robert Clausecker Aq Mt fuz@FreeBSD.org 220. 221.Sh CAVEATS 222Other parts of 223.Fx 224such as cryptographic routines in the kernel or in 225OpenSSL may also use SIMD enhancements. 226These enhancements are not subject to the 227.Ev ARCHLEVEL 228variable and may have their own configuration 229mechanism. 230. 231.Sh BUGS 232Use of SIMD enhancements cannot be configured on powerpc64. 233