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