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
diff --git a/docs/LangRef.html b/docs/LangRef.html
index 97b5312..1504a80 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 @@
following is the syntax for constant expressions:</p>
<dl>
- <dt><b><tt>cast ( CST to TYPE )</tt></b></dt>
+ <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>
- <dd>Cast a constant to another type.</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 @@
<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,7 +2797,163 @@
<!-- _______________________________________________________________________ -->
<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>
+ <result> = trunc <ty> <value> to <ty2> <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>
+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>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>
+ <result> = zext <ty> <value> to <ty2> <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>
+ <result> = sext <ty> <value> to <ty2> <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>
+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>
+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>
+ <result> = fpext <ty> <value> to <ty2> <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">
@@ -2748,52 +2961,211 @@
<h5>Syntax:</h5>
<pre>
- <result> = cast <ty> <value> to <ty2> <i>; yields ty2</i>
+ <result> = fptrunc <ty> <value> to <ty2> <i>; yields ty2</i>
</pre>
<h5>Overview:</h5>
+<p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
+<tt>ty2</tt>.</p>
-<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).
+
+<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>
+ <result> = fp2uint <ty> <value> to <ty2> <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>
+
+<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>
+ <result> = fp2sint <ty> <value> to <ty2> <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>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>
+<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>
-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>
-
-<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>'.
-</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.
-</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 = cast int 257 to ubyte <i>; yields ubyte:1</i>
- %Y = cast int 123 to bool <i>; yields bool:true</i>
+ %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>
+ <result> = uint2fp <ty> <value> to <ty2> <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>
+ <result> = sint2fp <ty> <value> to <ty2> <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>
+ <result> = bitconvert <ty> <value> to <ty2> <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 = bitconvert ubyte 255 to sbyte <i>; yields sbyte:-1</i>
+ %Y = bitconvert uint* %x to uint <i>; yields uint:%x</i>
</pre>
</div>