For PR1297:

Document changes to bswap and bit counting intrinsics. bswap's name now
requires two types in the suffix per overloaded intrinsic naming rules.
The ctpop, cttz, and ctlz intrinsics were changed to always return i32.


git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@35550 91177308-0d34-0410-b5e6-96231b3b80d8

docs/LangRef.html

@@ -3580,10 +3580,10 @@ argument.</p>
 <div class="doc_text">
 
 <p>LLVM supports the notion of an "intrinsic function".  These functions have
-well known names and semantics and are required to follow certain
+well known names and semantics and are required to follow certain restrictions.
-restrictions. Overall, these instructions represent an extension mechanism for
+Overall, these intrinsics represent an extension mechanism for the LLVM 
-the LLVM language that does not require changing all of the transformations in
+language that does not require changing all of the transformations in LLVM to 
-LLVM to add to the language (or the bytecode reader/writer, the parser,
+add to the language (or the bytecode reader/writer, the parser,
 etc...).</p>
 
 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
@@ -3594,9 +3594,20 @@ or invoke instructions: it is illegal to take the address of an intrinsic
 function.  Additionally, because intrinsic functions are part of the LLVM
 language, it is required that they all be documented here if any are added.</p>
 
+<p>Some intrinsic functions can be overloaded. That is, the intrinsic represents
+a family of functions that perform the same operation but on different data
+types. This is most frequent with the integer types. Since LLVM can represent
+over 8 million different integer types, there is a way to declare an intrinsic 
+that can be overloaded based on its arguments. Such intrinsics will have the
+names of the arbitrary types encoded into the intrinsic function name, each
+preceded by a period. For example, the <tt>llvm.ctpop</tt> function can take an
+integer of any width. This leads to a family of functions such as 
+<tt>i32 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i32 @llvm.ctpop.i29(i29 %val)</tt>.
+</p>
 
-<p>To learn how to add an intrinsic function, please see the <a
+
-href="ExtendingLLVM.html">Extending LLVM Guide</a>.
+<p>To learn how to add an intrinsic function, please see the 
+<a href="ExtendingLLVM.html">Extending LLVM Guide</a>.
 </p>
 
 </div>
@@ -4421,29 +4432,34 @@ These allow efficient code generation for some algorithms.
 <div class="doc_text">
 
 <h5>Syntax:</h5>
+<p>This is an overloaded intrinsic function. You can use bswap on any integer
+type that is an even number of bytes (i.e. BitWidth % 16 == 0). Note the suffix
+that includes the type for the result and the operand.
 <pre>
-  declare i16 @llvm.bswap.i16(i16 &lt;id&gt;)
+  declare i16 @llvm.bswap.i16.i16(i16 &lt;id&gt;)
-  declare i32 @llvm.bswap.i32(i32 &lt;id&gt;)
+  declare i32 @llvm.bswap.i32.i32(i32 &lt;id&gt;)
-  declare i64 @llvm.bswap.i64(i64 &lt;id&gt;)
+  declare i64 @llvm.bswap.i64.i32(i64 &lt;id&gt;)
 </pre>
 
 <h5>Overview:</h5>
 
 <p>
-The '<tt>llvm.bwsap</tt>' family of intrinsics is used to byteswap a 16, 32 or
+The '<tt>llvm.bwsap</tt>' family of intrinsics is used to byteswap integer 
-64 bit quantity.  These are useful for performing operations on data that is not
+values with an even number of bytes (positive multiple of 16 bits).  These are 
-in the target's  native byte order.
+useful for performing operations on data that is not in the target's native 
+byte order.
 </p>
 
 <h5>Semantics:</h5>
 
 <p>
-The <tt>llvm.bswap.16</tt> intrinsic returns an i16 value that has the high 
+The <tt>llvm.bswap.16.i16</tt> intrinsic returns an i16 value that has the high 
 and low byte of the input i16 swapped.  Similarly, the <tt>llvm.bswap.i32</tt> 
 intrinsic returns an i32 value that has the four bytes of the input i32 
 swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the returned 
-i32 will have its bytes in 3, 2, 1, 0 order.  The <tt>llvm.bswap.i64</tt> 
+i32 will have its bytes in 3, 2, 1, 0 order.  The <tt>llvm.bswap.i48.i48</tt>, 
-intrinsic extends this concept to 64 bits.
+<tt>llvm.bswap.i64.i64</tt> and other intrinsics extend this concept to
+additional even-byte lengths (6 bytes, 8 bytes and more, respectively).
 </p>
 
 </div>
@@ -4456,11 +4472,14 @@ intrinsic extends this concept to 64 bits.
 <div class="doc_text">
 
 <h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit
+width. Not all targets support all bit widths however.
 <pre>
-  declare i8  @llvm.ctpop.i8 (i8  &lt;src&gt;)
+  declare i32 @llvm.ctpop.i8 (i8  &lt;src&gt;)
-  declare i16 @llvm.ctpop.i16(i16 &lt;src&gt;)
+  declare i32 @llvm.ctpop.i16(i16 &lt;src&gt;)
   declare i32 @llvm.ctpop.i32(i32 &lt;src&gt;)
-  declare i64 @llvm.ctpop.i64(i64 &lt;src&gt;)
+  declare i32 @llvm.ctpop.i64(i64 &lt;src&gt;)
+  declare i32 @llvm.ctpop.i256(i256 &lt;src&gt;)
 </pre>
 
 <h5>Overview:</h5>
@@ -4492,11 +4511,14 @@ The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.
 <div class="doc_text">
 
 <h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any 
+integer bit width. Not all targets support all bit widths however.
 <pre>
-  declare i8  @llvm.ctlz.i8 (i8  &lt;src&gt;)
+  declare i32 @llvm.ctlz.i8 (i8  &lt;src&gt;)
-  declare i16 @llvm.ctlz.i16(i16 &lt;src&gt;)
+  declare i32 @llvm.ctlz.i16(i16 &lt;src&gt;)
   declare i32 @llvm.ctlz.i32(i32 &lt;src&gt;)
-  declare i64 @llvm.ctlz.i64(i64 &lt;src&gt;)
+  declare i32 @llvm.ctlz.i64(i64 &lt;src&gt;)
+  declare i32 @llvm.ctlz.i256(i256 &lt;src&gt;)
 </pre>
 
 <h5>Overview:</h5>
@@ -4532,11 +4554,14 @@ of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.
 <div class="doc_text">
 
 <h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any 
+integer bit width. Not all targets support all bit widths however.
 <pre>
-  declare i8  @llvm.cttz.i8 (i8  &lt;src&gt;)
+  declare i32 @llvm.cttz.i8 (i8  &lt;src&gt;)
-  declare i16 @llvm.cttz.i16(i16 &lt;src&gt;)
+  declare i32 @llvm.cttz.i16(i16 &lt;src&gt;)
   declare i32 @llvm.cttz.i32(i32 &lt;src&gt;)
-  declare i64 @llvm.cttz.i64(i64 &lt;src&gt;)
+  declare i32 @llvm.cttz.i64(i64 &lt;src&gt;)
+  declare i32 @llvm.cttz.i256(i256 &lt;src&gt;)
 </pre>
 
 <h5>Overview:</h5>