For PR950:

Early commit of the documentation for new conversion instructions for
easier review.


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

1 files changed, 404 insertions, 32 deletions

diff --git a/docs/LangRef.html b/docs/LangRef.html
index 97b5312356..1504a80762 100644
--- a/docs/LangRef.html
+++ b/docs/LangRef.html
@@ -115,10 +115,22 @@
          <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
         </ol>
       </li>
+      <li><a href="#otherops">Cast Operations</a>
+        <ol>
+          <li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li>
+          <li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li>
+          <li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li>
+          <li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li>
+          <li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li>
+          <li><a href="#i_fp2uint">'<tt>fp2uint .. to</tt>' Instruction</a></li>
+          <li><a href="#i_fp2sint">'<tt>fp2sint .. to</tt>' Instruction</a></li>
+          <li><a href="#i_uint2fp">'<tt>uint2fp .. to</tt>' Instruction</a></li>
+          <li><a href="#i_sint2fp">'<tt>sint2fp .. to</tt>' Instruction</a></li>
+          <li><a href="#i_bitconvert">'<tt>bitconvert .. to</tt>' Instruction</a></li>
+        </ol>
       <li><a href="#otherops">Other Operations</a>
         <ol>
           <li><a href="#i_phi">'<tt>phi</tt>'   Instruction</a></li>
-          <li><a href="#i_cast">'<tt>cast .. to</tt>' Instruction</a></li>
           <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
           <li><a href="#i_call">'<tt>call</tt>'  Instruction</a></li>
           <li><a href="#i_va_arg">'<tt>va_arg</tt>'  Instruction</a></li>
@@ -1170,9 +1182,54 @@ that does not have side effects (e.g. load and call are not supported).  The
 following is the syntax for constant expressions:</p>
 
 <dl>
-  <dt><b><tt>cast ( CST to TYPE )</tt></b></dt>
-
-  <dd>Cast a constant to another type.</dd>
+  <dt><b><tt>trunc ( CST to TYPE )</tt></b></dt>
+  <dd>Truncate a constant to another type. The bit size of CST must be larger 
+  than the bit size of TYPE. Both types must be integral.</dd>
+
+  <dt><b><tt>zext ( CST to TYPE )</tt></b></dt>
+  <dd>Zero extend a constant to another type. The bit size of CST must be 
+  smaller or equal to the bit size of TYPE.  Both types must be integral.</dd>
+
+  <dt><b><tt>sext ( CST to TYPE )</tt></b></dt>
+  <dd>Sign extend a constant to another type. The bit size of CST must be 
+  smaller or equal to the bit size of TYPE.  Both types must be integral.</dd>
+
+  <dt><b><tt>fptrunc ( CST to TYPE )</tt></b></dt>
+  <dd>Truncate a floating point constant to another floating point type. The 
+  size of CST must be larger than the size of TYPE. Both types must be 
+  floating point.</dd>
+
+  <dt><b><tt>fpext ( CST to TYPE )</tt></b></dt>
+  <dd>Floating point extend a constant to another type. The size of CST must be 
+  smaller or equal to the size of TYPE. Both types must be floating point.</dd>
+
+  <dt><b><tt>fp2uint ( CST to TYPE )</tt></b></dt>
+  <dd>Convert a floating point constant to the corresponding unsigned integer
+  constant. TYPE must be an integer type. CST must be floating point. If the 
+  value won't fit in the integer type, the results are undefined.</dd>
+
+  <dt><b><tt>fp2sint ( CST to TYPE )</tt></b></dt>
+  <dd>Convert a floating point constant to the corresponding signed integer
+  constant. TYPE must be an integer type. CST must be floating point. If the 
+  value won't fit in the integer type, the results are undefined.</dd>
+
+  <dt><b><tt>uint2fp ( CST to TYPE )</tt></b></dt>
+  <dd>Convert an unsigned integer constant to the corresponding floating point
+  constant. TYPE must be floating point. CST must be of integer type. If the
+  value won't fit in the floating point type, the results are undefined.</dd>
+
+  <dt><b><tt>sint2fp ( CST to TYPE )</tt></b></dt>
+  <dd>Convert a signed integer constant to the corresponding floating point
+  constant. TYPE must be floating point. CST must be of integer type. If the
+  value won't fit in the floating point type, the results are undefined.</dd>
+
+  <dt><b><tt>bitconvert ( CST to TYPE )</tt></b></dt>
+  <dd>Convert a constant, CST, to another TYPE. The size of CST and TYPE must be
+  identical (same number of bits). The conversion is done as if the CST value
+  was stored to memory and read back as TYPE. In other words, no bits change 
+  with this operator, just the type.  This can be used for conversion of pointer
+  and packed types to any other type, as long as they have the same bit width.
+  </dd>
 
   <dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
 
@@ -1403,7 +1460,7 @@ branches or with a lookup table.</p>
 
 <pre>
  <i>; Emulate a conditional br instruction</i>
- %Val = <a href="#i_cast">cast</a> bool %value to int
+ %Val = <a href="#i_zext">zext</a> bool %value to int
  switch int %Val, label %truedest [int 0, label %falsedest ]
 
  <i>; Emulate an unconditional br instruction</i>
@@ -2740,60 +2797,375 @@ came from in the last <a href="#terminators">terminator</a> instruction.</p>
 
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsubsection">
-   <a name="i_cast">'<tt>cast .. to</tt>' Instruction</a>
+   <a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
 </div>
-
 <div class="doc_text">
 
 <h5>Syntax:</h5>
-
 <pre>
-  &lt;result&gt; = cast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
+  &lt;result&gt; = trunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
 </pre>
 
 <h5>Overview:</h5>
-
 <p>
-The '<tt>cast</tt>' instruction is used as the primitive means to convert
-integers to floating point, change data type sizes, and break type safety (by
-casting pointers).
+The '<tt>trunc</tt>' instruction truncates its operand to the type <tt>ty2</tt>.
 </p>
 
-
 <h5>Arguments:</h5>
+<p>
+The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must 
+be an <a href="#t_integer">integer</a> type, and a type that specifies the size 
+and type of the result, which must be an <a href="#t_integral">integral</a> 
+type.</p>
 
+<h5>Semantics:</h5>
 <p>
-The '<tt>cast</tt>' instruction takes a value to cast, which must be a first
-class value, and a type to cast it to, which must also be a <a
-href="#t_firstclass">first class</a> type.
-</p>
+The '<tt>trunc</tt>' instruction truncates the high order bits in <tt>value</tt>
+and converts the reamining bits to <tt>ty2</tt>. The bit size of <tt>value</tt>
+must be larger than the bit size of <tt>ty2</tt>. Equal sized types are not 
+allowed.  This implies that a <tt>trunc</tt> cannot be a <i>no-op cast</i>. It 
+will always truncate bits.</p>
+
+<p>When truncating to bool, the truncation is done as a comparison against 
+zero. If the <tt>value</tt> was zero, the bool result will be <tt>false</tt>. 
+If the <tt>value</tt> was non-zero, the bool result will be <tt>true</tt>.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = trunc int 257 to ubyte              <i>; yields ubyte:1</i>
+  %Y = trunc int 123 to bool               <i>; yields bool:true</i>
+</pre>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+   <a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
+</div>
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  &lt;result&gt; = zext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>zext</tt>' instruction zero extends its operand to type 
+<tt>ty2</tt>.</p>
+
+
+<h5>Arguments:</h5>
+<p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of 
+<a href="#t_integral">integral</a> type, and a type to cast it to, which must
+also be of <a href="#t_integral">integral</a> type. The bit size of the
+<tt>value</tt> must be smaller than or equal to the bit size of the 
+destination type, <tt>ty2</tt>.</p>
 
 <h5>Semantics:</h5>
+<p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero
+bits until it reaches the size of the destination type, <tt>ty2</tt>. When the
+the operand and the type are the same size, no bit filling is done and the 
+cast is considered a <i>no-op cast</i> because no bits change (only the type 
+changes).</p>
+
+<p>When zero extending to bool, the extension is done as a comparison against 
+zero. If the <tt>value</tt> was zero, the bool result will be <tt>false</tt>. 
+If the <tt>value</tt> was non-zero, the bool result will be <tt>true</tt>.</p>
 
+<h5>Example:</h5>
+<pre>
+  %X = zext int 257 to ulong              <i>; yields ulong:257</i>
+  %Y = zext bool true to int              <i>; yields int:1</i>
+</pre>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+   <a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
+</div>
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  &lt;result&gt; = sext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
+
+<h5>Arguments:</h5>
 <p>
-This instruction follows the C rules for explicit casts when determining how the
-data being cast must change to fit in its new container.
-</p>
+The '<tt>sext</tt>' instruction takes a value to cast, which must be of 
+<a href="#t_integral">integral</a> type, and a type to cast it to, which must
+also be of <a href="#t_integral">integral</a> type.</p>
 
+<h5>Semantics:</h5>
 <p>
-When casting to bool, any value that would be considered true in the context of
-a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>' values,
-all else are '<tt>false</tt>'.
+The '<tt>sext</tt>' instruction performs a sign extension by copying the sign
+bit (highest order bit) of the <tt>value</tt> until it reaches the bit size of
+the type <tt>ty2</tt>.  When the the operand and the type are the same size, 
+no bit filling is done and the cast is considered a <i>no-op cast</i> because 
+no bits change (only the type changes).</p>
+
+<p>When sign extending to bool, the extension is done as a comparison against 
+zero. If the <tt>value</tt> was zero, the bool result will be <tt>false</tt>. 
+If the <tt>value</tt> was non-zero, the bool result will be <tt>true</tt>.</p>
+
+<h5>Example:</h5>
+
+<pre>
+  %X = sext sbyte -1 to ushort           <i>; yields ushort:65535</i>
+  %Y = sext bool true to int             <i>; yields int:-1</i>
+</pre>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+   <a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
+</div>
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  &lt;result&gt; = fpext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger
+floating point value.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>fpext</tt>' instruction takes a 
+<a href="#t_floating">floating point</a> <tt>value</tt> to cast, 
+and a <a href="#t_floating">floating point</a> type to cast it to.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from one floating
+point type to another. If the type of the <tt>value</tt> and <tt>ty2</tt> are
+the same, the instruction is considered a <i>no-op cast</i> because no bits
+change.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = fpext float 3.1415 to double        <i>; yields double:3.1415</i>
+  %Y = fpext float 1.0 to float            <i>; yields float:1.0 (no-op)</i>
+</pre>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+   <a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+
+<pre>
+  &lt;result&gt; = fptrunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
+<tt>ty2</tt>.</p>
+
+
+<h5>Arguments:</h5>
+<p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
+  point</a> value to cast and a <a href="#t_floating">floating point</a> type to
+cast it to. The size of <tt>value</tt> must be larger than the size of
+<tt>ty2</a>. This implies that <tt>fptrunc</tt> cannot be used to make a 
+<i>no-op cast</i>.</p>
+
+<h5>Semantics:</h5>
+<p> The '<tt>fptrunc</tt>' instruction converts a 
+<a href="#t_floating">floating point</a> value from a larger type to a smaller 
+type. If the value cannot fit within the destination type, <tt>ty2</tt>, then 
+the results are undefined.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = fptrunc double 123.0 to float         <i>; yields float:123.0</i>
+  %Y = fptrunc double 1.0E+300 to float      <i>; yields undefined</i>
+</pre>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+   <a name="i_fp2uint">'<tt>fp2uint .. to</tt>' Instruction</a>
+</div>
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  &lt;result&gt; = fp2uint &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fp2uint</tt>' converts a floating point <tt>value</tt> to its
+unsigned integer equivalent of type <tt>ty2</tt>.
 </p>
 
-<p>
-When extending an integral value from a type of one signness to another (for
-example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
-<b>source</b> value is signed, and zero-extended if the source value is
-unsigned. <tt>bool</tt> values are always zero extended into either zero or
-one.
+<h5>Arguments:</h5>
+<p>The '<tt>fp2uint</tt>' instruction takes a value to cast, which must be a 
+<a href="#t_floating">floating point</a> value, and a type to cast it to, which
+must be an <a href="#t_integral">integral</a> type.</p>
+
+<h5>Semantics:</h5>
+<p> The '<tt>fp2uint</tt>' instruction converts its 
+<a href="#t_floating">floating point</a> operand into the nearest (rounding
+towards zero) unsigned integer value. If the value cannot fit in <tt>ty2</tt>,
+the results are undefined.</p>
+
+<p>When converting to bool, the conversion is done as a comparison against 
+zero. If the <tt>value</tt> was zero, the bool result will be <tt>false</tt>. 
+If the <tt>value</tt> was non-zero, the bool result will be <tt>true</tt>.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = fp2uint double 123.0 to int         <i>; yields int:123</i>
+  %Y = fp2uint float 1.0E+300 to bool      <i>; yields bool:true</i>
+  %X = fp2uint float 1.04E+17 to ubyte     <i>; yields undefined:1</i>
+</pre>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+   <a name="i_fp2sint">'<tt>fp2sint .. to</tt>' Instruction</a>
+</div>
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  &lt;result&gt; = fp2sint &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fp2sint</tt>' instruction converts 
+<a href="#t_floating">floating point</a> <tt>value</tt> to type <tt>ty2</tt>.
 </p>
 
+
+<h5>Arguments:</h5>
+<p> The '<tt>fp2sint</tt>' instruction takes a value to cast, which must be a 
+<a href="#t_floating">floating point</a> value, and a type to cast it to, which 
+must also be an <a href="#t_integral">integral</a> type.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>fp2sint</tt>' instruction converts its 
+<a href="#t_floating">floating point</a> operand into the nearest (rounding
+towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
+the results are undefined.</p>
+
+<p>When converting to bool, the conversion is done as a comparison against 
+zero. If the <tt>value</tt> was zero, the bool result will be <tt>false</tt>. 
+If the <tt>value</tt> was non-zero, the bool result will be <tt>true</tt>.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = fp2sint double -123.0 to int        <i>; yields int:-123</i>
+  %Y = fp2sint float 1.0E-247 to bool      <i>; yields bool:true</i>
+  %X = fp2sint float 1.04E+17 to sbyte     <i>; yields undefined:1</i>
+</pre>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+   <a name="i_uint2fp">'<tt>uint2fp .. to</tt>' Instruction</a>
+</div>
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  &lt;result&gt; = uint2fp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>uint2fp</tt>' instruction regards <tt>value</tt> as an unsigned
+integer and converts that value to the <tt>ty2</tt> type.</p>
+
+
+<h5>Arguments:</h5>
+<p>The '<tt>uint2fp</tt>' instruction takes a value to cast, which must be an
+<a href="#t_integral">integral</a> value, and a type to cast it to, which must 
+be a <a href="#t_floating">floating point</a> type.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>uint2fp</tt>' instruction interprets its operand as an unsigned
+integer quantity and converts it to the corresponding floating point value. If
+the value cannot fit in the floating point value, the results are undefined.</p>
+
+
+<h5>Example:</h5>
+<pre>
+  %X = uint2fp int 257 to float         <i>; yields float:257.0</i>
+  %Y = uint2fp sbyte -1 to double       <i>; yields double:255.0</i>
+</pre>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+   <a name="i_sint2fp">'<tt>sint2fp .. to</tt>' Instruction</a>
+</div>
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  &lt;result&gt; = sint2fp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>sint2fp</tt>' instruction regards <tt>value</tt> as a signed
+integer and converts that value to the <tt>ty2</tt> type.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>sint2fp</tt>' instruction takes a value to cast, which must be an
+<a href="#t_integral">integral</a> value, and a type to cast it to, which must be
+a <a href="#t_floating">floating point</a> type.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>sint2fp</tt>' instruction interprets its operand as a signed
+integer quantity and converts it to the corresponding floating point value. If
+the value cannot fit in the floating point value, the results are undefined.</p>
+
 <h5>Example:</h5>
+<pre>
+  %X = sint2fp int 257 to float         <i>; yields float:257.0</i>
+  %Y = sint2fp sbyte -1 to double       <i>; yields double:-1.0</i>
+</pre>
+</div>
 
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+   <a name="i_bitconvert">'<tt>bitconvert .. to</tt>' Instruction</a>
+</div>
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  &lt;result&gt; = bitconvert &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>bitconvert</tt>' instruction converts <tt>value</tt> to type
+<tt>ty2</tt> without changing any bits.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>bitconvert</tt>' instruction takes a value to cast, which must be 
+a first class value, and a type to cast it to, which must also be a <a
+  href="#t_firstclass">first class</a> type. The bit sizes of <tt>value</tt>
+and the destination type, <tt>ty2</tt>, must be identical.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>bitconvert</tt>' instruction converts <tt>value</tt> to type
+<tt>ty2</tt> as if the value had been stored to memory and read back as type
+<tt>ty2</tt>. That is, no bits are changed during the conversion. The
+<tt>bitconvert</tt> instruction may be used to construct <i>no-op casts</i> that
+the <tt>zext, sext, and fpext</tt> instructions do not permit.</p>
+
+<h5>Example:</h5>
 <pre>
-  %X = cast int 257 to ubyte              <i>; yields ubyte:1</i>
-  %Y = cast int 123 to bool               <i>; yields bool:true</i>
+  %X = bitconvert ubyte 255 to sbyte         <i>; yields sbyte:-1</i>
+  %Y = bitconvert uint* %x to uint           <i>; yields uint:%x</i>
 </pre>
 </div>