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