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.