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 July 29, 2025 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 for 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 PPC64 54.It bcmp Ta A Ta Ta S1 55.It bcopy Ta A Ta S Ta S Ta SV 56.It bzero Ta A Ta S Ta S 57.It div Ta Ta Ta S 58.It index Ta A Ta Ta S1 59.It ldiv Ta Ta Ta S 60.It lldiv Ta Ta Ta S 61.It memchr Ta A Ta Ta S1 62.It memcmp Ta A Ta S Ta S1 63.It memccpy Ta A Ta Ta S1 64.It memcpy Ta A Ta S Ta S Ta SV 65.It memmove Ta A Ta S Ta S Ta SV 66.It memrchr Ta A Ta Ta S1 67.It memset Ta A Ta S Ta S 68.It rindex Ta A Ta Ta S1 69.It stpcpy Ta A Ta Ta S1 70.It stpncpy Ta Ta Ta S1 71.It strcat Ta A Ta Ta S1 72.It strchr Ta A Ta Ta S1 73.It strchrnul Ta A Ta Ta S1 74.It strcmp Ta A Ta S Ta S1 75.It strcpy Ta A Ta Ta S1 Ta S2 76.It strcspn Ta S Ta Ta S2 77.It strlcat Ta A Ta Ta S1 78.It strlcpy Ta A Ta Ta S1 79.It strlen Ta A Ta S Ta S1 80.It strncat Ta A Ta Ta S1 81.It strncmp Ta A Ta S Ta S1 82.It strncpy Ta Ta Ta S1 Ta S2 83.It strnlen Ta A Ta Ta S1 84.It strrchr Ta A Ta Ta S1 85.It strpbrk Ta S Ta Ta S2 86.It strsep Ta S Ta Ta S2 87.It strspn Ta S Ta Ta S2 88.It timingsafe_bcmp Ta A Ta Ta S1 89.It timingsafe_memcmp Ta S Ta Ta S 90.El 91.Pp 92.Sy S Ns :\ scalar (non-SIMD), 93.Sy 1 Ns :\ amd64 baseline, 94.Sy 2 Ns :\ x86-64-v2 95or PowerPC\ 2.05, 96.Sy 3 Ns :\ x86-64-v3, 97.Sy 4 Ns :\ x86-64-v4, 98.Sy V Ns :\ PowerPC\ VSX, 99.Sy A Ns :\ Arm\ ASIMD (NEON). 100. 101.Sh ENVIRONMENT 102.Bl -tag 103.It Ev ARCHLEVEL 104On 105.Em amd64 , 106controls the level of SIMD enhancements used. 107If this variable is set to an architecture level from the list below 108and that architecture level is supported by the processor, SIMD 109enhancements up to 110.Ev ARCHLEVEL 111are used. 112If 113.Ev ARCHLEVEL 114is unset, not recognised, or not supported by the processor, the highest 115level of SIMD enhancements supported by the processor is used. 116.Pp 117A suffix beginning with 118.Sq ":" 119or 120.Sq "+" 121in 122.Ev ARCHLEVEL 123is ignored and may be used for future extensions. 124The architecture level can be prefixed with a 125.Sq "!" 126character to force use of the requested architecture level, even if the 127processor does not advertise that it is supported. 128This usually causes applications to crash and should only be used for 129testing purposes or if architecture level detection yields incorrect 130results. 131.Pp 132The architecture levels follow the AMD64 SysV ABI supplement: 133.Bl -tag -width x86-64-v2 134.It Cm scalar 135scalar enhancements only (no SIMD) 136.It Cm baseline 137cmov, cx8, x87 FPU, fxsr, MMX, osfxsr, SSE, SSE2 138.It Cm x86-64-v2 139cx16, lahf/sahf, popcnt, SSE3, SSSE3, SSE4.1, SSE4.2 140.It Cm x86-64-v3 141AVX, AVX2, BMI1, BMI2, F16C, FMA, lzcnt, movbe, osxsave 142.It Cm x86-64-v4 143AVX-512F/BW/CD/DQ/VL 144.El 145.El 146. 147.Sh DIAGNOSTICS 148.Bl -diag 149.It "Illegal Instruction" 150Printed by 151.Xr sh 1 152if a command is terminated through delivery of a 153.Dv SIGILL 154signal, see 155.Xr signal 3 . 156.Pp 157Use of an unsupported architecture level was forced by setting 158.Ev ARCHLEVEL 159to a string beginning with a 160.Sq "!" 161character, causing a process to crash due to use of an unsupported 162instruction. 163Unset 164.Ev ARCHLEVEL , 165remove the 166.Sq "!" 167prefix or select a supported architecture level. 168.Pp 169Message may also appear for unrelated reasons. 170.El 171. 172.Sh SEE ALSO 173.Xr string 3 , 174.Xr arch 7 175.Rs 176.%A H. J. Lu 177.%A Michael Matz 178.%A Milind Girkar 179.%A Jan Hubi\[u010D]ka \" \(vc 180.%A Andreas Jaeger 181.%A Mark Mitchell 182.%B System V Application Binary Interface 183.%D May 23, 2023 184.%T AMD64 Architecture Processor Supplement 185.%O Version 1.0 186.Re 187. 188.Sh HISTORY 189Architecture-specific enhanced 190.Em libc 191functions were added starting 192with 193.Fx 2.0 194for 195.Cm i386 , 196.Fx 6.0 197for 198.Cm arm , 199.Fx 6.1 200for 201.Cm amd64 , 202.Fx 11.0 203for 204.Cm aarch64 , 205and 206.Fx 12.0 207for 208.Cm powerpc64 . 209SIMD-enhanced functions were first added with 210.Fx 13.0 211for 212.Cm powerpc64 213and with 214.Fx 14.1 215for 216.Cm amd64 . 217.Pp 218A 219.Nm 220manual page appeared in 221.Fx 14.1 . 222. 223.Sh AUTHOR 224.An Robert Clausecker Aq Mt fuz@FreeBSD.org 225. 226.Sh CAVEATS 227Other parts of 228.Fx 229such as cryptographic routines in the kernel or in 230OpenSSL may also use SIMD enhancements. 231These enhancements are not subject to the 232.Ev ARCHLEVEL 233variable and may have their own configuration 234mechanism. 235. 236.Sh BUGS 237Use of SIMD enhancements cannot be configured on powerpc64. 238