| 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. |