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