Debian Codegraph @

subprojects/meson-docs/docs/markdown/Simd-module.md

raw
1 # Unstable SIMD module
2
3 This module provides helper functionality to build code with SIMD instructions.
4 Available since 0.42.0.
5
6 **Note**: this module is unstable. It is only provided as a technology
7 preview. Its API may change in arbitrary ways between releases or it
8 might be removed from Meson altogether.
9
10 ## Usage
11
12 This module is designed for the use case where you have an algorithm
13 with one or more SIMD implementation and you choose which one to use
14 at runtime.
15
16 The module provides one method, `check`, which is used like this:
17
18 rval = simd.check('mysimds',
19 mmx : 'simd_mmx.c',
20 sse : 'simd_sse.c',
21 sse2 : 'simd_sse2.c',
22 sse3 : 'simd_sse3.c',
23 ssse3 : 'simd_ssse3.c',
24 sse41 : 'simd_sse41.c',
25 sse42 : 'simd_sse42.c',
26 avx : 'simd_avx.c',
27 avx2 : 'simd_avx2.c',
28 neon : 'simd_neon.c',
29 compiler : cc)
30
31 Here the individual files contain the accelerated versions of the
32 functions in question. The `compiler` keyword argument takes the
33 compiler you are going to use to compile them. The function returns an
34 array with two values. The first value is a bunch of libraries that
35 contain the compiled code. Any SIMD code that the compiler can't
36 compile (for example, Neon instructions on an x86 machine) are
37 ignored. You should pass this value to the desired target using
38 `link_with`. The second value is a `configuration_data` object that
39 contains true for all the values that were supported. For example if
40 the compiler did support sse2 instructions, then the object would have
41 `HAVE_SSE2` set to 1.
42
43 Generating code to detect the proper instruction set at runtime is
44 straightforward. First you create a header with the configuration
45 object and then a chooser function that looks like this:
46
47 void (*fptr)(type_of_function_here) = NULL;
48
49 #if HAVE_NEON
50 if(fptr == NULL && neon_available()) {
51 fptr = neon_accelerated_function;
52 }
53 #endif
54 #if HAVE_AVX2
55 if(fptr == NULL && avx2_available()) {
56 fptr = avx_accelerated_function;
57 }
58 #endif
59
60 ...
61
62 if(fptr == NULL) {
63 fptr = default_function;
64 }
65
66 Each source file provides two functions, the `xxx_available` function
67 to query whether the CPU currently in use supports the instruction set
68 and `xxx_accelerated_function` that is the corresponding accelerated
69 implementation.
70
71 At the end of this function the function pointer points to the fastest
72 available implementation and can be invoked to do the computation.