Squashed 'third_party/boostorg/predef/' content from commit 560ff52
Change-Id: Ib7804ff2c768e0d597993b019146292dfb41e9dc
git-subtree-dir: third_party/boostorg/predef
git-subtree-split: 560ff5298ead78276872604f1ee6523e63a4fa90
diff --git a/doc/hardware_simd.qbk b/doc/hardware_simd.qbk
new file mode 100644
index 0000000..c613310
--- /dev/null
+++ b/doc/hardware_simd.qbk
@@ -0,0 +1,89 @@
+SIMD predefs depend on compiler options. For example, you will have to add the
+option `-msse3` to clang or gcc to enable SSE3. SIMD predefs are also inclusive.
+This means that if SSE3 is enabled, then every other extensions with a lower
+version number will implicitly be enabled and detected. However, some extensions
+are CPU specific, they may not be detected nor enabled when an upper version is
+enabled.
+
+[note SSE(1) and SSE2 are automatically enabled by default when using x86-64
+architecture.]
+
+To check if any SIMD extension has been enabled, you can use:
+
+``
+#include <boost/predef/hardware/simd.h>
+#include <iostream>
+
+int main()
+{
+#if defined(BOOST_HW_SIMD_AVAILABLE)
+ std::cout << "SIMD detected!" << std::endl;
+#endif
+ return 0;
+}
+``
+
+When writing SIMD specific code, you may want to check if a particular extension
+has been detected. To do so you have to use the right architecture predef and
+compare it. Those predef are of the form `BOOST_HW_SIMD_"ARCH"` (where `"ARCH"`
+is either `ARM`, `PPC`, or `X86`). For example, if you compile code for x86
+architecture, you will have to use `BOOST_HW_SIMD_X86`. Its value will be the
+version number of the most recent SIMD extension detected for the architecture.
+
+To check if an extension has been enabled:
+
+``
+#include <boost/predef/hardware/simd.h>
+#include <iostream>
+
+int main()
+{
+#if BOOST_HW_SIMD_X86 >= BOOST_HW_SIMD_X86_SSE3_VERSION
+ std::cout << "This is SSE3!" << std::endl;
+#endif
+ return 0;
+}
+``
+
+[note The *_VERSION* defines that map version number to actual real
+identifiers. This way it is easier to write comparisons without messing up with
+version numbers.]
+
+To *"stricly"* check the most recent detected extension:
+
+``
+#include <boost/predef/hardware/simd.h>
+#include <iostream>
+
+int main()
+{
+#if BOOST_HW_SIMD_X86 == BOOST_HW_SIMD_X86_SSE3_VERSION
+ std::cout << "This is SSE3 and this is the most recent enabled extension!"
+ << std::endl;
+#endif
+ return 0;
+}
+``
+
+Because of the version systems of predefs and of the inclusive property of SIMD
+extensions macros, you can easily check for ranges of supported extensions:
+
+``
+#include <boost/predef/hardware/simd.h>
+#include <iostream>
+
+int main()
+{
+#if BOOST_HW_SIMD_X86 >= BOOST_HW_SIMD_X86_SSE2_VERSION &&\
+ BOOST_HW_SIMD_X86 <= BOOST_HW_SIMD_X86_SSSE3_VERSION
+ std::cout << "This is SSE2, SSE3 and SSSE3!" << std::endl;
+#endif
+ return 0;
+}
+``
+
+[note Unlike gcc and clang, Visual Studio does not allow you to specify precisely
+the SSE variants you want to use, the only detections that will take place are
+SSE, SSE2, AVX and AVX2. For more informations,
+ see [@https://msdn.microsoft.com/en-us/library/b0084kay.aspx here].]
+