add a compatibility note about vector builtins
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@114101 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/www/compatibility.html b/www/compatibility.html
index bc34a86..4196e88 100644
--- a/www/compatibility.html
+++ b/www/compatibility.html
@@ -32,6 +32,7 @@
<li><a href="#c">C compatibility</a>
<ul>
<li><a href="#inline">C99 inline functions</a></li>
+ <li><a href="#vector_builtins">"missing" vector __builtin functions</a></li>
<li><a href="#lvalue-cast">Lvalue casts</a></li>
<li><a href="#blocks-in-protected-scope">Jumps to within <tt>__block</tt> variable scope</a></li>
</ul>
@@ -114,6 +115,32 @@
be changed.</li>
</ul>
+
+<!-- ======================================================================= -->
+<h3 id="vector_builtins">"missing" vector __builtin functions</h3>
+<!-- ======================================================================= -->
+
+<p>The Intel and AMD manuals document a number "<tt><*mmintrin.h></tt>"
+header files, which define a standardized API for accessing vector operations
+on X86 CPUs. These functions have names like <tt>_mm_xor_ps</tt> and
+<tt>_mm256_addsub_pd</tt>. Compilers have leeway to implement these functions
+however they want. Since Clang supports an excellent set of <a
+href="../docs/LanguageExtensions.html#vectors">native vector operations</a>,
+the Clang headers implement these interfaces in terms of the native vector
+operations.
+</p>
+
+<p>In contrast, GCC implements these functions mostly as a 1-to-1 mapping to
+builtin function calls, like <tt>__builtin_ia32_paddw128</tt>. These builtin
+functions are an internal implementation detail of GCC, and are not portable to
+the Intel compiler, the Microsoft compiler, or Clang. If you get build errors
+mentioning these, the fix is simple: switch to the *mmintrin.h functions.</p>
+
+<p>The same issue occurs for NEON and Altivec for the ARM and PowerPC
+architectures respectively. For these, make sure to use the <arm_neon.h>
+and <altivec.h> headers.</p>
+
+
<!-- ======================================================================= -->
<h3 id="lvalue-cast">Lvalue casts</h3>
<!-- ======================================================================= -->