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