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