meson/docs/markdown/Simd-module.md

Unstable SIMD module

This module provides helper functionality to build code with SIMD instructions. Available since 0.42.0.

Note: this module is unstable. It is only provided as a technology preview. Its API may change in arbitrary ways between releases or it might be removed from Meson altogether.

Usage

This module is designed for the use case where you have an algorithm with one or more SIMD implementation and you choose which one to use at runtime.

The module provides one method, check, which is used like this:

rval = simd.check('mysimds',
  mmx : 'simd_mmx.c',
  sse : 'simd_sse.c',
  sse2 : 'simd_sse2.c',
  sse3 : 'simd_sse3.c',
  ssse3 : 'simd_ssse3.c',
  sse41 : 'simd_sse41.c',
  sse42 : 'simd_sse42.c',
  avx : 'simd_avx.c',
  avx2 : 'simd_avx2.c',
  neon : 'simd_neon.c',
  compiler : cc)

Here the individual files contain the accelerated versions of the functions in question. The compiler keyword argument takes the compiler you are going to use to compile them. The function returns an array with two values. The first value is a bunch of libraries that contain the compiled code. Any SIMD code that the compiler can't compile (for example, Neon instructions on an x86 machine) are ignored. You should pass this value to the desired target using link_with. The second value is a configuration_data object that contains true for all the values that were supported. For example if the compiler did support sse2 instructions, then the object would have HAVE_SSE2 set to 1.

Generating code to detect the proper instruction set at runtime is straightforward. First you create a header with the configuration object and then a chooser function that looks like this:

void (*fptr)(type_of_function_here)  = NULL;

#if HAVE_NEON
if(fptr == NULL && neon_available()) {
    fptr = neon_accelerated_function;
}
#endif
#if HAVE_AVX2
if(fptr == NULL && avx2_available()) {
    fptr = avx_accelerated_function;
}
#endif

...

if(fptr == NULL) {
    fptr = default_function;
}

Each source file provides two functions, the xxx_available function to query whether the CPU currently in use supports the instruction set and xxx_accelerated_function that is the corresponding accelerated implementation.

At the end of this function the function pointer points to the fastest available implementation and can be invoked to do the computation.