share/man/man7/simd.7

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