Merge pull request #1374 from mesonbuild/simd

Add support for SIMD detection

3 files changed, 88 insertions, 1 deletions

diff --git a/docs/markdown/Module-reference.md b/docs/markdown/Module-reference.md
index 866c141..80e3b8f 100644
--- a/docs/markdown/Module-reference.md
+++ b/docs/markdown/Module-reference.md
@@ -1,4 +1,6 @@
-Meson has a selection of modules to make common requirements easy to use. Modules can be thought of like the standard library of a programming language. Currently Meson provides the following modules.
+Meson has a selection of modules to make common requirements easy to use.
+Modules can be thought of like the standard library of a programming language.
+Currently Meson provides the following modules.
 
 * [Gnome](Gnome-module.md)
 * [i18n](i18n-module.md)
@@ -8,3 +10,11 @@ Meson has a selection of modules to make common requirements easy to use. Module
 * [Python3](Python-3-module.md)
 * [RPM](RPM-module.md)
 * [Windows](Windows-module.md)
+
+In addition there are unstable modules. These are meant for testing new
+functionality but note that they do *not* provide a stable API. It can
+change in arbitrary ways between releases. The modules might also be removed
+without warning in future releases.
+
+ * [SIMD](Simd-module.md)
+ 
\ No newline at end of file
diff --git a/docs/markdown/Release-notes-for-0.42.0.md b/docs/markdown/Release-notes-for-0.42.0.md
index a19db49..3374d3b 100644
--- a/docs/markdown/Release-notes-for-0.42.0.md
+++ b/docs/markdown/Release-notes-for-0.42.0.md
@@ -58,3 +58,10 @@ Rust's [linkage reference][rust-linkage].
 
 Both the address- and undefined behavior sanitizers can now be used
 simultaneously by passing `-Db_sanitize=address,undefined` to Meson.
+
+## Unstable SIMD module
+
+A new experimental module to compile code with many different SIMD
+instruction sets and selecting the best one at runtime. This module
+is unstable, meaning its API is subject to change in later releases.
+It might also be removed altogether.
diff --git a/docs/markdown/Simd-module.md b/docs/markdown/Simd-module.md
new file mode 100644
index 0000000..0fd1dda
--- /dev/null
+++ b/docs/markdown/Simd-module.md
@@ -0,0 +1,70 @@
+# 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.