[llvm-commits] CVS: llvm/docs/LangRef.html
Chris Lattner
lattner at cs.uiuc.edu
Sat Apr 8 16:07:17 PDT 2006
Changes in directory llvm/docs:
LangRef.html updated: 1.146 -> 1.147
---
Log message:
Move the vector instructions to their own subsection.
---
Diffs of the changes: (+490 -467)
LangRef.html | 957 ++++++++++++++++++++++++++++++-----------------------------
1 files changed, 490 insertions(+), 467 deletions(-)
Index: llvm/docs/LangRef.html
diff -u llvm/docs/LangRef.html:1.146 llvm/docs/LangRef.html:1.147
--- llvm/docs/LangRef.html:1.146 Fri Apr 7 23:40:53 2006
+++ llvm/docs/LangRef.html Sat Apr 8 18:07:04 2006
@@ -91,6 +91,16 @@
<li><a href="#i_shr">'<tt>shr</tt>' Instruction</a></li>
</ol>
</li>
+ <li><a href="#vectorops">Vector Operations</a>
+ <ol>
+ <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li>
+ <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li>
+ <li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li>
+ <li><a href="#i_vsetint">'<tt>vsetint</tt>' Instruction</a></li>
+ <li><a href="#i_vsetfp">'<tt>vsetfp</tt>' Instruction</a></li>
+ <li><a href="#i_vselect">'<tt>vselect</tt>' Instruction</a></li>
+ </ol>
+ </li>
<li><a href="#memoryops">Memory Access Operations</a>
<ol>
<li><a href="#i_malloc">'<tt>malloc</tt>' Instruction</a></li>
@@ -106,12 +116,6 @@
<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_vsetint">'<tt>vsetint</tt>' Instruction</a></li>
- <li><a href="#i_vsetfp">'<tt>vsetfp</tt>' Instruction</a></li>
- <li><a href="#i_vselect">'<tt>vselect</tt>' Instruction</a></li>
- <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li>
- <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li>
- <li><a href="#i_shufflevector">'<tt>shufflevector</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>
</ol>
@@ -1896,21 +1900,23 @@
<!-- ======================================================================= -->
<div class="doc_subsection">
- <a name="memoryops">Memory Access Operations</a>
+ <a name="vectorops">Vector Operations</a>
</div>
<div class="doc_text">
-<p>A key design point of an SSA-based representation is how it
-represents memory. In LLVM, no memory locations are in SSA form, which
-makes things very simple. This section describes how to read, write,
-allocate, and free memory in LLVM.</p>
+<p>LLVM supports several instructions to represent vector operations in a
+target-independent manner. This instructions cover the element-access and
+vector-specific operations needed to process vectors effectively. While LLVM
+does directly support these vector operations, many sophisticated algorithms
+will want to use target-specific intrinsics to take full advantage of a specific
+target.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
+ <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
</div>
<div class="doc_text">
@@ -1918,48 +1924,45 @@
<h5>Syntax:</h5>
<pre>
- <result> = malloc <type>[, uint <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
+ <result> = extractelement <n x <ty>> <val>, uint <idx> <i>; yields <ty></i>
</pre>
<h5>Overview:</h5>
-<p>The '<tt>malloc</tt>' instruction allocates memory from the system
-heap and returns a pointer to it.</p>
+<p>
+The '<tt>extractelement</tt>' instruction extracts a single scalar
+element from a packed vector at a specified index.
+</p>
-<h5>Arguments:</h5>
-<p>The '<tt>malloc</tt>' instruction allocates
-<tt>sizeof(<type>)*NumElements</tt>
-bytes of memory from the operating system and returns a pointer of the
-appropriate type to the program. If "NumElements" is specified, it is the
-number of elements allocated. If an alignment is specified, the value result
-of the allocation is guaranteed to be aligned to at least that boundary. If
-not specified, or if zero, the target can choose to align the allocation on any
-convenient boundary.</p>
+<h5>Arguments:</h5>
-<p>'<tt>type</tt>' must be a sized type.</p>
+<p>
+The first operand of an '<tt>extractelement</tt>' instruction is a
+value of <a href="#t_packed">packed</a> type. The second operand is
+an index indicating the position from which to extract the element.
+The index may be a variable.</p>
<h5>Semantics:</h5>
-<p>Memory is allocated using the system "<tt>malloc</tt>" function, and
-a pointer is returned.</p>
+<p>
+The result is a scalar of the same type as the element type of
+<tt>val</tt>. Its value is the value at position <tt>idx</tt> of
+<tt>val</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
+results are undefined.
+</p>
<h5>Example:</h5>
<pre>
- %array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
-
- %size = <a href="#i_add">add</a> uint 2, 2 <i>; yields {uint}:size = uint 4</i>
- %array1 = malloc ubyte, uint 4 <i>; yields {ubyte*}:array1</i>
- %array2 = malloc [12 x ubyte], uint %size <i>; yields {[12 x ubyte]*}:array2</i>
- %array3 = malloc int, uint 4, align 1024 <i>; yields {int*}:array3</i>
- %array4 = malloc int, align 1024 <i>; yields {int*}:array4</i>
+ %result = extractelement <4 x int> %vec, uint 0 <i>; yields int</i>
</pre>
</div>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="i_free">'<tt>free</tt>' Instruction</a>
+ <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
</div>
<div class="doc_text">
@@ -1967,36 +1970,45 @@
<h5>Syntax:</h5>
<pre>
- free <type> <value> <i>; yields {void}</i>
+ <result> = insertelement <n x <ty>> <val>, <ty> <elt>, uint <idx> <i>; yields <n x <ty>></i>
</pre>
<h5>Overview:</h5>
-<p>The '<tt>free</tt>' instruction returns memory back to the unused
-memory heap to be reallocated in the future.</p>
+<p>
+The '<tt>insertelement</tt>' instruction inserts a scalar
+element into a packed vector at a specified index.
+</p>
+
<h5>Arguments:</h5>
-<p>'<tt>value</tt>' shall be a pointer value that points to a value
-that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>'
-instruction.</p>
+<p>
+The first operand of an '<tt>insertelement</tt>' instruction is a
+value of <a href="#t_packed">packed</a> type. The second operand is a
+scalar value whose type must equal the element type of the first
+operand. The third operand is an index indicating the position at
+which to insert the value. The index may be a variable.</p>
<h5>Semantics:</h5>
-<p>Access to the memory pointed to by the pointer is no longer defined
-after this instruction executes.</p>
+<p>
+The result is a packed vector of the same type as <tt>val</tt>. Its
+element values are those of <tt>val</tt> except at position
+<tt>idx</tt>, where it gets the value <tt>elt</tt>. If <tt>idx</tt>
+exceeds the length of <tt>val</tt>, the results are undefined.
+</p>
<h5>Example:</h5>
<pre>
- %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
- free [4 x ubyte]* %array
+ %result = insertelement <4 x int> %vec, int 1, uint 0 <i>; yields <4 x int></i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
+ <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
</div>
<div class="doc_text">
@@ -2004,243 +2016,255 @@
<h5>Syntax:</h5>
<pre>
- <result> = alloca <type>[, uint <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
+ <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <n x uint> <mask> <i>; yields <n x <ty>></i>
</pre>
<h5>Overview:</h5>
-<p>The '<tt>alloca</tt>' instruction allocates memory on the current
-stack frame of the procedure that is live until the current function
-returns to its caller.</p>
+<p>
+The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
+from two input vectors, returning a vector of the same type.
+</p>
<h5>Arguments:</h5>
-<p>The '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
-bytes of memory on the runtime stack, returning a pointer of the
-appropriate type to the program. If "NumElements" is specified, it is the
-number of elements allocated. If an alignment is specified, the value result
-of the allocation is guaranteed to be aligned to at least that boundary. If
-not specified, or if zero, the target can choose to align the allocation on any
-convenient boundary.</p>
+<p>
+The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
+with types that match each other and types that match the result of the
+instruction. The third argument is a shuffle mask, which has the same number
+of elements as the other vector type, but whose element type is always 'uint'.
+</p>
-<p>'<tt>type</tt>' may be any sized type.</p>
+<p>
+The shuffle mask operand is required to be a constant vector with either
+constant integer or undef values.
+</p>
<h5>Semantics:</h5>
-<p>Memory is allocated; a pointer is returned. '<tt>alloca</tt>'d
-memory is automatically released when the function returns. The '<tt>alloca</tt>'
-instruction is commonly used to represent automatic variables that must
-have an address available. When the function returns (either with the <tt><a
- href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt>
-instructions), the memory is reclaimed.</p>
+<p>
+The elements of the two input vectors are numbered from left to right across
+both of the vectors. The shuffle mask operand specifies, for each element of
+the result vector, which element of the two input registers the result element
+gets. The element selector may be undef (meaning "don't care") and the second
+operand may be undef if performing a shuffle from only one vector.
+</p>
<h5>Example:</h5>
<pre>
- %ptr = alloca int <i>; yields {int*}:ptr</i>
- %ptr = alloca int, uint 4 <i>; yields {int*}:ptr</i>
- %ptr = alloca int, uint 4, align 1024 <i>; yields {int*}:ptr</i>
- %ptr = alloca int, align 1024 <i>; yields {int*}:ptr</i>
+ %result = shufflevector <4 x int> %v1, <4 x int> %v2,
+ <4 x uint> <uint 0, uint 4, uint 1, uint 5> <i>; yields <4 x int></i>
+ %result = shufflevector <4 x int> %v1, <4 x int> undef,
+ <4 x uint> <uint 0, uint 1, uint 2, uint 3> <i>; yields <4 x int></i> - Identity shuffle.
</pre>
</div>
+
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
+<div class="doc_subsubsection"> <a name="i_vsetint">'<tt>vsetint</tt>'
Instruction</a> </div>
<div class="doc_text">
<h5>Syntax:</h5>
-<pre> <result> = load <ty>* <pointer><br> <result> = volatile load <ty>* <pointer><br></pre>
-<h5>Overview:</h5>
-<p>The '<tt>load</tt>' instruction is used to read from memory.</p>
-<h5>Arguments:</h5>
-<p>The argument to the '<tt>load</tt>' instruction specifies the memory
-address from which to load. The pointer must point to a <a
- href="#t_firstclass">first class</a> type. If the <tt>load</tt> is
-marked as <tt>volatile</tt>, then the optimizer is not allowed to modify
-the number or order of execution of this <tt>load</tt> with other
-volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
-instructions. </p>
-<h5>Semantics:</h5>
-<p>The location of memory pointed to is loaded.</p>
-<h5>Examples:</h5>
-<pre> %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
- <a
- href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
- %val = load int* %ptr <i>; yields {int}:val = int 3</i>
-</pre>
-</div>
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
-Instruction</a> </div>
-<h5>Syntax:</h5>
-<pre> store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
- volatile store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
+<pre><result> = vsetint <op>, <n x <ty>> <var1>, <var2> <i>; yields <n x bool></i>
</pre>
+
<h5>Overview:</h5>
-<p>The '<tt>store</tt>' instruction is used to write to memory.</p>
+
+<p>The '<tt>vsetint</tt>' instruction takes two integer vectors and
+returns a vector of boolean values representing, at each position, the
+result of the comparison between the values at that position in the
+two operands.</p>
+
<h5>Arguments:</h5>
-<p>There are two arguments to the '<tt>store</tt>' instruction: a value
-to store and an address in which to store it. The type of the '<tt><pointer></tt>'
-operand must be a pointer to the type of the '<tt><value></tt>'
-operand. If the <tt>store</tt> is marked as <tt>volatile</tt>, then the
-optimizer is not allowed to modify the number or order of execution of
-this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a
- href="#i_store">store</a></tt> instructions.</p>
+
+<p>The arguments to a '<tt>vsetint</tt>' instruction are a comparison
+operation and two value arguments. The value arguments must be of <a
+href="#t_integral">integral</a> <a href="#t_packed">packed</a> type,
+and they must have identical types. The operation argument must be
+one of <tt>eq</tt>, <tt>ne</tt>, <tt>slt</tt>, <tt>sgt</tt>,
+<tt>sle</tt>, <tt>sge</tt>, <tt>ult</tt>, <tt>ugt</tt>, <tt>ule</tt>,
+<tt>uge</tt>, <tt>true</tt>, and <tt>false</tt>. The result is a
+packed <tt>bool</tt> value with the same length as each operand.</p>
+
<h5>Semantics:</h5>
-<p>The contents of memory are updated to contain '<tt><value></tt>'
-at the location specified by the '<tt><pointer></tt>' operand.</p>
+
+<p>The following table shows the semantics of '<tt>vsetint</tt>'. For
+each position of the result, the comparison is done on the
+corresponding positions of the two value arguments. Note that the
+signedness of the comparison depends on the comparison opcode and
+<i>not</i> on the signedness of the value operands. E.g., <tt>vsetint
+slt <4 x unsigned> %x, %y</tt> does an elementwise <i>signed</i>
+comparison of <tt>%x</tt> and <tt>%y</tt>.</p>
+
+<table border="1" cellspacing="0" cellpadding="4">
+ <tbody>
+ <tr><th>Operation</th><th>Result is true iff</th><th>Comparison is</th></tr>
+ <tr><td><tt>eq</tt></td><td>var1 == var2</td><td>--</td></tr>
+ <tr><td><tt>ne</tt></td><td>var1 != var2</td><td>--</td></tr>
+ <tr><td><tt>slt</tt></td><td>var1 < var2</td><td>signed</td></tr>
+ <tr><td><tt>sgt</tt></td><td>var1 > var2</td><td>signed</td></tr>
+ <tr><td><tt>sle</tt></td><td>var1 <= var2</td><td>signed</td></tr>
+ <tr><td><tt>sge</tt></td><td>var1 >= var2</td><td>signed</td></tr>
+ <tr><td><tt>ult</tt></td><td>var1 < var2</td><td>unsigned</td></tr>
+ <tr><td><tt>ugt</tt></td><td>var1 > var2</td><td>unsigned</td></tr>
+ <tr><td><tt>ule</tt></td><td>var1 <= var2</td><td>unsigned</td></tr>
+ <tr><td><tt>uge</tt></td><td>var1 >= var2</td><td>unsigned</td></tr>
+ <tr><td><tt>true</tt></td><td>always</td><td>--</td></tr>
+ <tr><td><tt>false</tt></td><td>never</td><td>--</td></tr>
+ </tbody>
+</table>
+
<h5>Example:</h5>
-<pre> %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
- <a
- href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
- %val = load int* %ptr <i>; yields {int}:val = int 3</i>
+<pre> <result> = vsetint eq <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = false, false</i>
+ <result> = vsetint ne <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = true, true</i>
+ <result> = vsetint slt <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = true, false</i>
+ <result> = vsetint sgt <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = false, true</i>
+ <result> = vsetint sle <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = true, false</i>
+ <result> = vsetint sge <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = false, true</i>
</pre>
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection"> <a name="i_vsetfp">'<tt>vsetfp</tt>'
+Instruction</a> </div>
<div class="doc_text">
<h5>Syntax:</h5>
-<pre>
- <result> = getelementptr <ty>* <ptrval>{, <ty> <idx>}*
+<pre><result> = vsetfp <op>, <n x <ty>> <var1>, <var2> <i>; yields <n x bool></i>
</pre>
<h5>Overview:</h5>
-<p>
-The '<tt>getelementptr</tt>' instruction is used to get the address of a
-subelement of an aggregate data structure.</p>
+<p>The '<tt>vsetfp</tt>' instruction takes two floating point vector
+arguments and returns a vector of boolean values representing, at each
+position, the result of the comparison between the values at that
+position in the two operands.</p>
<h5>Arguments:</h5>
-<p>This instruction takes a list of integer constants that indicate what
-elements of the aggregate object to index to. The actual types of the arguments
-provided depend on the type of the first pointer argument. The
-'<tt>getelementptr</tt>' instruction is used to index down through the type
-levels of a structure or to a specific index in an array. When indexing into a
-structure, only <tt>uint</tt>
-integer constants are allowed. When indexing into an array or pointer,
-<tt>int</tt> and <tt>long</tt> indexes are allowed of any sign.</p>
+<p>The arguments to a '<tt>vsetfp</tt>' instruction are a comparison
+operation and two value arguments. The value arguments must be of <a
+href="t_floating">floating point</a> <a href="#t_packed">packed</a>
+type, and they must have identical types. The operation argument must
+be one of <tt>eq</tt>, <tt>ne</tt>, <tt>lt</tt>, <tt>gt</tt>,
+<tt>le</tt>, <tt>ge</tt>, <tt>oeq</tt>, <tt>one</tt>, <tt>olt</tt>,
+<tt>ogt</tt>, <tt>ole</tt>, <tt>oge</tt>, <tt>ueq</tt>, <tt>une</tt>,
+<tt>ult</tt>, <tt>ugt</tt>, <tt>ule</tt>, <tt>uge</tt>, <tt>o</tt>,
+<tt>u</tt>, <tt>true</tt>, and <tt>false</tt>. The result is a packed
+<tt>bool</tt> value with the same length as each operand.</p>
-<p>For example, let's consider a C code fragment and how it gets
-compiled to LLVM:</p>
+<h5>Semantics:</h5>
-<pre>
- struct RT {
- char A;
- int B[10][20];
- char C;
- };
- struct ST {
- int X;
- double Y;
- struct RT Z;
- };
+<p>The following table shows the semantics of '<tt>vsetfp</tt>' for
+floating point types. If either operand is a floating point Not a
+Number (NaN) value, the operation is unordered, and the value in the
+first column below is produced at that position. Otherwise, the
+operation is ordered, and the value in the second column is
+produced.</p>
- int *foo(struct ST *s) {
- return &s[1].Z.B[5][13];
- }
+<table border="1" cellspacing="0" cellpadding="4">
+ <tbody>
+ <tr><th>Operation</th><th>If unordered<th>Otherwise true iff</th></tr>
+ <tr><td><tt>eq</tt></td><td>undefined</td><td>var1 == var2</td></tr>
+ <tr><td><tt>ne</tt></td><td>undefined</td><td>var1 != var2</td></tr>
+ <tr><td><tt>lt</tt></td><td>undefined</td><td>var1 < var2</td></tr>
+ <tr><td><tt>gt</tt></td><td>undefined</td><td>var1 > var2</td></tr>
+ <tr><td><tt>le</tt></td><td>undefined</td><td>var1 <= var2</td></tr>
+ <tr><td><tt>ge</tt></td><td>undefined</td><td>var1 >= var2</td></tr>
+ <tr><td><tt>oeq</tt></td><td>false</td><td>var1 == var2</td></tr>
+ <tr><td><tt>one</tt></td><td>false</td><td>var1 != var2</td></tr>
+ <tr><td><tt>olt</tt></td><td>false</td><td>var1 < var2</td></tr>
+ <tr><td><tt>ogt</tt></td><td>false</td><td>var1 > var2</td></tr>
+ <tr><td><tt>ole</tt></td><td>false</td><td>var1 <= var2</td></tr>
+ <tr><td><tt>oge</tt></td><td>false</td><td>var1 >= var2</td></tr>
+ <tr><td><tt>ueq</tt></td><td>true</td><td>var1 == var2</td></tr>
+ <tr><td><tt>une</tt></td><td>true</td><td>var1 != var2</td></tr>
+ <tr><td><tt>ult</tt></td><td>true</td><td>var1 < var2</td></tr>
+ <tr><td><tt>ugt</tt></td><td>true</td><td>var1 > var2</td></tr>
+ <tr><td><tt>ule</tt></td><td>true</td><td>var1 <= var2</td></tr>
+ <tr><td><tt>uge</tt></td><td>true</td><td>var1 >= var2</td></tr>
+ <tr><td><tt>o</tt></td><td>false</td><td>always</td></tr>
+ <tr><td><tt>u</tt></td><td>true</td><td>never</td></tr>
+ <tr><td><tt>true</tt></td><td>true</td><td>always</td></tr>
+ <tr><td><tt>false</tt></td><td>false</td><td>never</td></tr>
+ </tbody>
+</table>
+
+<h5>Example:</h5>
+<pre> <result> = vsetfp eq <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = false, false</i>
+ <result> = vsetfp ne <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = true, true</i>
+ <result> = vsetfp lt <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = true, false</i>
+ <result> = vsetfp gt <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = false, true</i>
+ <result> = vsetfp le <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = true, false</i>
+ <result> = vsetfp ge <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = false, true</i>
</pre>
+</div>
-<p>The LLVM code generated by the GCC frontend is:</p>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="i_vselect">'<tt>vselect</tt>' Instruction</a>
+</div>
-<pre>
- %RT = type { sbyte, [10 x [20 x int]], sbyte }
- %ST = type { int, double, %RT }
+<div class="doc_text">
- implementation
+<h5>Syntax:</h5>
- int* %foo(%ST* %s) {
- entry:
- %reg = getelementptr %ST* %s, int 1, uint 2, uint 1, int 5, int 13
- ret int* %reg
- }
+<pre>
+ <result> = vselect <n x bool> <cond>, <n x <ty>> <val1>, <n x <ty>> <val2> <i>; yields <n x <ty>></i>
</pre>
-<h5>Semantics:</h5>
+<h5>Overview:</h5>
-<p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
-on the pointer type that is being indexed into. <a href="#t_pointer">Pointer</a>
-and <a href="#t_array">array</a> types require <tt>uint</tt>, <tt>int</tt>,
-<tt>ulong</tt>, or <tt>long</tt> values, and <a href="#t_struct">structure</a>
-types require <tt>uint</tt> <b>constants</b>.</p>
+<p>
+The '<tt>vselect</tt>' instruction chooses one value at each position
+of a vector based on a condition.
+</p>
-<p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
-type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ int, double, %RT
-}</tt>' type, a structure. The second index indexes into the third element of
-the structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]],
-sbyte }</tt>' type, another structure. The third index indexes into the second
-element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
-array. The two dimensions of the array are subscripted into, yielding an
-'<tt>int</tt>' type. The '<tt>getelementptr</tt>' instruction returns a pointer
-to this element, thus computing a value of '<tt>int*</tt>' type.</p>
-<p>Note that it is perfectly legal to index partially through a
-structure, returning a pointer to an inner element. Because of this,
-the LLVM code for the given testcase is equivalent to:</p>
+<h5>Arguments:</h5>
-<pre>
- int* %foo(%ST* %s) {
- %t1 = getelementptr %ST* %s, int 1 <i>; yields %ST*:%t1</i>
- %t2 = getelementptr %ST* %t1, int 0, uint 2 <i>; yields %RT*:%t2</i>
- %t3 = getelementptr %RT* %t2, int 0, uint 1 <i>; yields [10 x [20 x int]]*:%t3</i>
- %t4 = getelementptr [10 x [20 x int]]* %t3, int 0, int 5 <i>; yields [20 x int]*:%t4</i>
- %t5 = getelementptr [20 x int]* %t4, int 0, int 13 <i>; yields int*:%t5</i>
- ret int* %t5
- }
-</pre>
+<p>
+The '<tt>vselect</tt>' instruction requires a <a
+href="#t_packed">packed</a> <tt>bool</tt> value indicating the
+condition at each vector position, and two values of the same packed
+type. All three operands must have the same length. The type of the
+result is the same as the type of the two value operands.</p>
-<p>Note that it is undefined to access an array out of bounds: array and
-pointer indexes must always be within the defined bounds of the array type.
-The one exception for this rules is zero length arrays. These arrays are
-defined to be accessible as variable length arrays, which requires access
-beyond the zero'th element.</p>
+<h5>Semantics:</h5>
+
+<p>
+At each position where the <tt>bool</tt> vector is true, that position
+of the result gets its value from the first value argument; otherwise,
+it gets its value from the second value argument.
+</p>
<h5>Example:</h5>
<pre>
- <i>; yields [12 x ubyte]*:aptr</i>
- %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, uint 1
+ %X = vselect bool <2 x bool> <bool true, bool false>, <2 x ubyte> <ubyte 17, ubyte 17>,
+ <2 x ubyte> <ubyte 42, ubyte 42> <i>; yields <2 x ubyte>:17, 42</i>
</pre>
-
</div>
+
+
+
<!-- ======================================================================= -->
-<div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
-<div class="doc_text">
-<p>The instructions in this category are the "miscellaneous"
-instructions, which defy better classification.</p>
+<div class="doc_subsection">
+ <a name="memoryops">Memory Access Operations</a>
</div>
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>'
-Instruction</a> </div>
+
<div class="doc_text">
-<h5>Syntax:</h5>
-<pre> <result> = phi <ty> [ <val0>, <label0>], ...<br></pre>
-<h5>Overview:</h5>
-<p>The '<tt>phi</tt>' instruction is used to implement the φ node in
-the SSA graph representing the function.</p>
-<h5>Arguments:</h5>
-<p>The type of the incoming values are specified with the first type
-field. After this, the '<tt>phi</tt>' instruction takes a list of pairs
-as arguments, with one pair for each predecessor basic block of the
-current block. Only values of <a href="#t_firstclass">first class</a>
-type may be used as the value arguments to the PHI node. Only labels
-may be used as the label arguments.</p>
-<p>There must be no non-phi instructions between the start of a basic
-block and the PHI instructions: i.e. PHI instructions must be first in
-a basic block.</p>
-<h5>Semantics:</h5>
-<p>At runtime, the '<tt>phi</tt>' instruction logically takes on the
-value specified by the parameter, depending on which basic block we
-came from in the last <a href="#terminators">terminator</a> instruction.</p>
-<h5>Example:</h5>
-<pre>Loop: ; Infinite loop that counts from 0 on up...<br> %indvar = phi uint [ 0, %LoopHeader ], [ %nextindvar, %Loop ]<br> %nextindvar = add uint %indvar, 1<br> br label %Loop<br></pre>
+
+<p>A key design point of an SSA-based representation is how it
+represents memory. In LLVM, no memory locations are in SSA form, which
+makes things very simple. This section describes how to read, write,
+allocate, and free memory in LLVM.</p>
+
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="i_cast">'<tt>cast .. to</tt>' Instruction</a>
+ <a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
</div>
<div class="doc_text">
@@ -2248,58 +2272,48 @@
<h5>Syntax:</h5>
<pre>
- <result> = cast <ty> <value> to <ty2> <i>; yields ty2</i>
+ <result> = malloc <type>[, uint <NumElements>][, align <alignment>] <i>; yields {type*}:result</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).
-</p>
-
+<p>The '<tt>malloc</tt>' instruction allocates memory from the system
+heap and returns a pointer to it.</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>
-
-<h5>Semantics:</h5>
+<p>The '<tt>malloc</tt>' instruction allocates
+<tt>sizeof(<type>)*NumElements</tt>
+bytes of memory from the operating system and returns a pointer of the
+appropriate type to the program. If "NumElements" is specified, it is the
+number of elements allocated. If an alignment is specified, the value result
+of the allocation is guaranteed to be aligned to at least that boundary. If
+not specified, or if zero, the target can choose to align the allocation on any
+convenient boundary.</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>'<tt>type</tt>' must be a sized type.</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>
+<h5>Semantics:</h5>
-<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>Memory is allocated using the system "<tt>malloc</tt>" function, and
+a pointer is returned.</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>
+ %array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
+
+ %size = <a href="#i_add">add</a> uint 2, 2 <i>; yields {uint}:size = uint 4</i>
+ %array1 = malloc ubyte, uint 4 <i>; yields {ubyte*}:array1</i>
+ %array2 = malloc [12 x ubyte], uint %size <i>; yields {[12 x ubyte]*}:array2</i>
+ %array3 = malloc int, uint 4, align 1024 <i>; yields {int*}:array3</i>
+ %array4 = malloc int, align 1024 <i>; yields {int*}:array4</i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="i_select">'<tt>select</tt>' Instruction</a>
+ <a name="i_free">'<tt>free</tt>' Instruction</a>
</div>
<div class="doc_text">
@@ -2307,271 +2321,280 @@
<h5>Syntax:</h5>
<pre>
- <result> = select bool <cond>, <ty> <val1>, <ty> <val2> <i>; yields ty</i>
+ free <type> <value> <i>; yields {void}</i>
</pre>
<h5>Overview:</h5>
-<p>
-The '<tt>select</tt>' instruction is used to choose one value based on a
-condition, without branching.
-</p>
-
+<p>The '<tt>free</tt>' instruction returns memory back to the unused
+memory heap to be reallocated in the future.</p>
<h5>Arguments:</h5>
-<p>
-The '<tt>select</tt>' instruction requires a boolean value indicating the condition, and two values of the same <a href="#t_firstclass">first class</a> type.
-</p>
+<p>'<tt>value</tt>' shall be a pointer value that points to a value
+that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>'
+instruction.</p>
<h5>Semantics:</h5>
-<p>
-If the boolean condition evaluates to true, the instruction returns the first
-value argument; otherwise, it returns the second value argument.
-</p>
+<p>Access to the memory pointed to by the pointer is no longer defined
+after this instruction executes.</p>
<h5>Example:</h5>
<pre>
- %X = select bool true, ubyte 17, ubyte 42 <i>; yields ubyte:17</i>
+ %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
+ free [4 x ubyte]* %array
</pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_vsetint">'<tt>vsetint</tt>'
-Instruction</a> </div>
+<div class="doc_subsubsection">
+ <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
+</div>
+
<div class="doc_text">
+
<h5>Syntax:</h5>
-<pre><result> = vsetint <op>, <n x <ty>> <var1>, <var2> <i>; yields <n x bool></i>
+
+<pre>
+ <result> = alloca <type>[, uint <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
</pre>
<h5>Overview:</h5>
-<p>The '<tt>vsetint</tt>' instruction takes two integer vectors and
-returns a vector of boolean values representing, at each position, the
-result of the comparison between the values at that position in the
-two operands.</p>
+<p>The '<tt>alloca</tt>' instruction allocates memory on the current
+stack frame of the procedure that is live until the current function
+returns to its caller.</p>
<h5>Arguments:</h5>
-<p>The arguments to a '<tt>vsetint</tt>' instruction are a comparison
-operation and two value arguments. The value arguments must be of <a
-href="#t_integral">integral</a> <a href="#t_packed">packed</a> type,
-and they must have identical types. The operation argument must be
-one of <tt>eq</tt>, <tt>ne</tt>, <tt>slt</tt>, <tt>sgt</tt>,
-<tt>sle</tt>, <tt>sge</tt>, <tt>ult</tt>, <tt>ugt</tt>, <tt>ule</tt>,
-<tt>uge</tt>, <tt>true</tt>, and <tt>false</tt>. The result is a
-packed <tt>bool</tt> value with the same length as each operand.</p>
+<p>The '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
+bytes of memory on the runtime stack, returning a pointer of the
+appropriate type to the program. If "NumElements" is specified, it is the
+number of elements allocated. If an alignment is specified, the value result
+of the allocation is guaranteed to be aligned to at least that boundary. If
+not specified, or if zero, the target can choose to align the allocation on any
+convenient boundary.</p>
-<h5>Semantics:</h5>
+<p>'<tt>type</tt>' may be any sized type.</p>
-<p>The following table shows the semantics of '<tt>vsetint</tt>'. For
-each position of the result, the comparison is done on the
-corresponding positions of the two value arguments. Note that the
-signedness of the comparison depends on the comparison opcode and
-<i>not</i> on the signedness of the value operands. E.g., <tt>vsetint
-slt <4 x unsigned> %x, %y</tt> does an elementwise <i>signed</i>
-comparison of <tt>%x</tt> and <tt>%y</tt>.</p>
+<h5>Semantics:</h5>
-<table border="1" cellspacing="0" cellpadding="4">
- <tbody>
- <tr><th>Operation</th><th>Result is true iff</th><th>Comparison is</th></tr>
- <tr><td><tt>eq</tt></td><td>var1 == var2</td><td>--</td></tr>
- <tr><td><tt>ne</tt></td><td>var1 != var2</td><td>--</td></tr>
- <tr><td><tt>slt</tt></td><td>var1 < var2</td><td>signed</td></tr>
- <tr><td><tt>sgt</tt></td><td>var1 > var2</td><td>signed</td></tr>
- <tr><td><tt>sle</tt></td><td>var1 <= var2</td><td>signed</td></tr>
- <tr><td><tt>sge</tt></td><td>var1 >= var2</td><td>signed</td></tr>
- <tr><td><tt>ult</tt></td><td>var1 < var2</td><td>unsigned</td></tr>
- <tr><td><tt>ugt</tt></td><td>var1 > var2</td><td>unsigned</td></tr>
- <tr><td><tt>ule</tt></td><td>var1 <= var2</td><td>unsigned</td></tr>
- <tr><td><tt>uge</tt></td><td>var1 >= var2</td><td>unsigned</td></tr>
- <tr><td><tt>true</tt></td><td>always</td><td>--</td></tr>
- <tr><td><tt>false</tt></td><td>never</td><td>--</td></tr>
- </tbody>
-</table>
+<p>Memory is allocated; a pointer is returned. '<tt>alloca</tt>'d
+memory is automatically released when the function returns. The '<tt>alloca</tt>'
+instruction is commonly used to represent automatic variables that must
+have an address available. When the function returns (either with the <tt><a
+ href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt>
+instructions), the memory is reclaimed.</p>
<h5>Example:</h5>
-<pre> <result> = vsetint eq <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = false, false</i>
- <result> = vsetint ne <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = true, true</i>
- <result> = vsetint slt <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = true, false</i>
- <result> = vsetint sgt <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = false, true</i>
- <result> = vsetint sle <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = true, false</i>
- <result> = vsetint sge <2 x int> <int 0, int 1>, <int 1, int 0> <i>; yields {<2 x bool>}:result = false, true</i>
+
+<pre>
+ %ptr = alloca int <i>; yields {int*}:ptr</i>
+ %ptr = alloca int, uint 4 <i>; yields {int*}:ptr</i>
+ %ptr = alloca int, uint 4, align 1024 <i>; yields {int*}:ptr</i>
+ %ptr = alloca int, align 1024 <i>; yields {int*}:ptr</i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="i_vsetfp">'<tt>vsetfp</tt>'
+<div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
Instruction</a> </div>
<div class="doc_text">
<h5>Syntax:</h5>
-<pre><result> = vsetfp <op>, <n x <ty>> <var1>, <var2> <i>; yields <n x bool></i>
-</pre>
-
+<pre> <result> = load <ty>* <pointer><br> <result> = volatile load <ty>* <pointer><br></pre>
<h5>Overview:</h5>
-
-<p>The '<tt>vsetfp</tt>' instruction takes two floating point vector
-arguments and returns a vector of boolean values representing, at each
-position, the result of the comparison between the values at that
-position in the two operands.</p>
-
+<p>The '<tt>load</tt>' instruction is used to read from memory.</p>
<h5>Arguments:</h5>
-
-<p>The arguments to a '<tt>vsetfp</tt>' instruction are a comparison
-operation and two value arguments. The value arguments must be of <a
-href="t_floating">floating point</a> <a href="#t_packed">packed</a>
-type, and they must have identical types. The operation argument must
-be one of <tt>eq</tt>, <tt>ne</tt>, <tt>lt</tt>, <tt>gt</tt>,
-<tt>le</tt>, <tt>ge</tt>, <tt>oeq</tt>, <tt>one</tt>, <tt>olt</tt>,
-<tt>ogt</tt>, <tt>ole</tt>, <tt>oge</tt>, <tt>ueq</tt>, <tt>une</tt>,
-<tt>ult</tt>, <tt>ugt</tt>, <tt>ule</tt>, <tt>uge</tt>, <tt>o</tt>,
-<tt>u</tt>, <tt>true</tt>, and <tt>false</tt>. The result is a packed
-<tt>bool</tt> value with the same length as each operand.</p>
-
+<p>The argument to the '<tt>load</tt>' instruction specifies the memory
+address from which to load. The pointer must point to a <a
+ href="#t_firstclass">first class</a> type. If the <tt>load</tt> is
+marked as <tt>volatile</tt>, then the optimizer is not allowed to modify
+the number or order of execution of this <tt>load</tt> with other
+volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
+instructions. </p>
<h5>Semantics:</h5>
-
-<p>The following table shows the semantics of '<tt>vsetfp</tt>' for
-floating point types. If either operand is a floating point Not a
-Number (NaN) value, the operation is unordered, and the value in the
-first column below is produced at that position. Otherwise, the
-operation is ordered, and the value in the second column is
-produced.</p>
-
-<table border="1" cellspacing="0" cellpadding="4">
- <tbody>
- <tr><th>Operation</th><th>If unordered<th>Otherwise true iff</th></tr>
- <tr><td><tt>eq</tt></td><td>undefined</td><td>var1 == var2</td></tr>
- <tr><td><tt>ne</tt></td><td>undefined</td><td>var1 != var2</td></tr>
- <tr><td><tt>lt</tt></td><td>undefined</td><td>var1 < var2</td></tr>
- <tr><td><tt>gt</tt></td><td>undefined</td><td>var1 > var2</td></tr>
- <tr><td><tt>le</tt></td><td>undefined</td><td>var1 <= var2</td></tr>
- <tr><td><tt>ge</tt></td><td>undefined</td><td>var1 >= var2</td></tr>
- <tr><td><tt>oeq</tt></td><td>false</td><td>var1 == var2</td></tr>
- <tr><td><tt>one</tt></td><td>false</td><td>var1 != var2</td></tr>
- <tr><td><tt>olt</tt></td><td>false</td><td>var1 < var2</td></tr>
- <tr><td><tt>ogt</tt></td><td>false</td><td>var1 > var2</td></tr>
- <tr><td><tt>ole</tt></td><td>false</td><td>var1 <= var2</td></tr>
- <tr><td><tt>oge</tt></td><td>false</td><td>var1 >= var2</td></tr>
- <tr><td><tt>ueq</tt></td><td>true</td><td>var1 == var2</td></tr>
- <tr><td><tt>une</tt></td><td>true</td><td>var1 != var2</td></tr>
- <tr><td><tt>ult</tt></td><td>true</td><td>var1 < var2</td></tr>
- <tr><td><tt>ugt</tt></td><td>true</td><td>var1 > var2</td></tr>
- <tr><td><tt>ule</tt></td><td>true</td><td>var1 <= var2</td></tr>
- <tr><td><tt>uge</tt></td><td>true</td><td>var1 >= var2</td></tr>
- <tr><td><tt>o</tt></td><td>false</td><td>always</td></tr>
- <tr><td><tt>u</tt></td><td>true</td><td>never</td></tr>
- <tr><td><tt>true</tt></td><td>true</td><td>always</td></tr>
- <tr><td><tt>false</tt></td><td>false</td><td>never</td></tr>
- </tbody>
-</table>
-
+<p>The location of memory pointed to is loaded.</p>
+<h5>Examples:</h5>
+<pre> %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
+ <a
+ href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
+ %val = load int* %ptr <i>; yields {int}:val = int 3</i>
+</pre>
+</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
+Instruction</a> </div>
+<h5>Syntax:</h5>
+<pre> store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
+ volatile store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
+</pre>
+<h5>Overview:</h5>
+<p>The '<tt>store</tt>' instruction is used to write to memory.</p>
+<h5>Arguments:</h5>
+<p>There are two arguments to the '<tt>store</tt>' instruction: a value
+to store and an address in which to store it. The type of the '<tt><pointer></tt>'
+operand must be a pointer to the type of the '<tt><value></tt>'
+operand. If the <tt>store</tt> is marked as <tt>volatile</tt>, then the
+optimizer is not allowed to modify the number or order of execution of
+this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a
+ href="#i_store">store</a></tt> instructions.</p>
+<h5>Semantics:</h5>
+<p>The contents of memory are updated to contain '<tt><value></tt>'
+at the location specified by the '<tt><pointer></tt>' operand.</p>
<h5>Example:</h5>
-<pre> <result> = vsetfp eq <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = false, false</i>
- <result> = vsetfp ne <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = true, true</i>
- <result> = vsetfp lt <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = true, false</i>
- <result> = vsetfp gt <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = false, true</i>
- <result> = vsetfp le <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = true, false</i>
- <result> = vsetfp ge <2 x float> <float 0.0, float 1.0>, <float 1.0, float 0.0> <i>; yields {<2 x bool>}:result = false, true</i>
+<pre> %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
+ <a
+ href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
+ %val = load int* %ptr <i>; yields {int}:val = int 3</i>
</pre>
-</div>
-
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="i_vselect">'<tt>vselect</tt>' Instruction</a>
+ <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
</div>
<div class="doc_text">
-
<h5>Syntax:</h5>
-
<pre>
- <result> = vselect <n x bool> <cond>, <n x <ty>> <val1>, <n x <ty>> <val2> <i>; yields <n x <ty>></i>
+ <result> = getelementptr <ty>* <ptrval>{, <ty> <idx>}*
</pre>
<h5>Overview:</h5>
<p>
-The '<tt>vselect</tt>' instruction chooses one value at each position
-of a vector based on a condition.
-</p>
-
+The '<tt>getelementptr</tt>' instruction is used to get the address of a
+subelement of an aggregate data structure.</p>
<h5>Arguments:</h5>
-<p>
-The '<tt>vselect</tt>' instruction requires a <a
-href="#t_packed">packed</a> <tt>bool</tt> value indicating the
-condition at each vector position, and two values of the same packed
-type. All three operands must have the same length. The type of the
-result is the same as the type of the two value operands.</p>
-
-<h5>Semantics:</h5>
-
-<p>
-At each position where the <tt>bool</tt> vector is true, that position
-of the result gets its value from the first value argument; otherwise,
-it gets its value from the second value argument.
-</p>
+<p>This instruction takes a list of integer constants that indicate what
+elements of the aggregate object to index to. The actual types of the arguments
+provided depend on the type of the first pointer argument. The
+'<tt>getelementptr</tt>' instruction is used to index down through the type
+levels of a structure or to a specific index in an array. When indexing into a
+structure, only <tt>uint</tt>
+integer constants are allowed. When indexing into an array or pointer,
+<tt>int</tt> and <tt>long</tt> indexes are allowed of any sign.</p>
-<h5>Example:</h5>
+<p>For example, let's consider a C code fragment and how it gets
+compiled to LLVM:</p>
<pre>
- %X = vselect bool <2 x bool> <bool true, bool false>, <2 x ubyte> <ubyte 17, ubyte 17>,
- <2 x ubyte> <ubyte 42, ubyte 42> <i>; yields <2 x ubyte>:17, 42</i>
+ struct RT {
+ char A;
+ int B[10][20];
+ char C;
+ };
+ struct ST {
+ int X;
+ double Y;
+ struct RT Z;
+ };
+
+ int *foo(struct ST *s) {
+ return &s[1].Z.B[5][13];
+ }
</pre>
-</div>
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
-</div>
+<p>The LLVM code generated by the GCC frontend is:</p>
-<div class="doc_text">
+<pre>
+ %RT = type { sbyte, [10 x [20 x int]], sbyte }
+ %ST = type { int, double, %RT }
-<h5>Syntax:</h5>
+ implementation
-<pre>
- <result> = extractelement <n x <ty>> <val>, uint <idx> <i>; yields <ty></i>
+ int* %foo(%ST* %s) {
+ entry:
+ %reg = getelementptr %ST* %s, int 1, uint 2, uint 1, int 5, int 13
+ ret int* %reg
+ }
</pre>
-<h5>Overview:</h5>
-
-<p>
-The '<tt>extractelement</tt>' instruction extracts a single scalar
-element from a packed vector at a specified index.
-</p>
+<h5>Semantics:</h5>
+<p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
+on the pointer type that is being indexed into. <a href="#t_pointer">Pointer</a>
+and <a href="#t_array">array</a> types require <tt>uint</tt>, <tt>int</tt>,
+<tt>ulong</tt>, or <tt>long</tt> values, and <a href="#t_struct">structure</a>
+types require <tt>uint</tt> <b>constants</b>.</p>
-<h5>Arguments:</h5>
+<p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
+type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ int, double, %RT
+}</tt>' type, a structure. The second index indexes into the third element of
+the structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]],
+sbyte }</tt>' type, another structure. The third index indexes into the second
+element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
+array. The two dimensions of the array are subscripted into, yielding an
+'<tt>int</tt>' type. The '<tt>getelementptr</tt>' instruction returns a pointer
+to this element, thus computing a value of '<tt>int*</tt>' type.</p>
-<p>
-The first operand of an '<tt>extractelement</tt>' instruction is a
-value of <a href="#t_packed">packed</a> type. The second operand is
-an index indicating the position from which to extract the element.
-The index may be a variable.</p>
+<p>Note that it is perfectly legal to index partially through a
+structure, returning a pointer to an inner element. Because of this,
+the LLVM code for the given testcase is equivalent to:</p>
-<h5>Semantics:</h5>
+<pre>
+ int* %foo(%ST* %s) {
+ %t1 = getelementptr %ST* %s, int 1 <i>; yields %ST*:%t1</i>
+ %t2 = getelementptr %ST* %t1, int 0, uint 2 <i>; yields %RT*:%t2</i>
+ %t3 = getelementptr %RT* %t2, int 0, uint 1 <i>; yields [10 x [20 x int]]*:%t3</i>
+ %t4 = getelementptr [10 x [20 x int]]* %t3, int 0, int 5 <i>; yields [20 x int]*:%t4</i>
+ %t5 = getelementptr [20 x int]* %t4, int 0, int 13 <i>; yields int*:%t5</i>
+ ret int* %t5
+ }
+</pre>
-<p>
-The result is a scalar of the same type as the element type of
-<tt>val</tt>. Its value is the value at position <tt>idx</tt> of
-<tt>val</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
-results are undefined.
-</p>
+<p>Note that it is undefined to access an array out of bounds: array and
+pointer indexes must always be within the defined bounds of the array type.
+The one exception for this rules is zero length arrays. These arrays are
+defined to be accessible as variable length arrays, which requires access
+beyond the zero'th element.</p>
<h5>Example:</h5>
<pre>
- %result = extractelement <4 x int> %vec, uint 0 <i>; yields int</i>
+ <i>; yields [12 x ubyte]*:aptr</i>
+ %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, uint 1
</pre>
-</div>
+</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
+<div class="doc_text">
+<p>The instructions in this category are the "miscellaneous"
+instructions, which defy better classification.</p>
+</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>'
+Instruction</a> </div>
+<div class="doc_text">
+<h5>Syntax:</h5>
+<pre> <result> = phi <ty> [ <val0>, <label0>], ...<br></pre>
+<h5>Overview:</h5>
+<p>The '<tt>phi</tt>' instruction is used to implement the φ node in
+the SSA graph representing the function.</p>
+<h5>Arguments:</h5>
+<p>The type of the incoming values are specified with the first type
+field. After this, the '<tt>phi</tt>' instruction takes a list of pairs
+as arguments, with one pair for each predecessor basic block of the
+current block. Only values of <a href="#t_firstclass">first class</a>
+type may be used as the value arguments to the PHI node. Only labels
+may be used as the label arguments.</p>
+<p>There must be no non-phi instructions between the start of a basic
+block and the PHI instructions: i.e. PHI instructions must be first in
+a basic block.</p>
+<h5>Semantics:</h5>
+<p>At runtime, the '<tt>phi</tt>' instruction logically takes on the
+value specified by the parameter, depending on which basic block we
+came from in the last <a href="#terminators">terminator</a> instruction.</p>
+<h5>Example:</h5>
+<pre>Loop: ; Infinite loop that counts from 0 on up...<br> %indvar = phi uint [ 0, %LoopHeader ], [ %nextindvar, %Loop ]<br> %nextindvar = add uint %indvar, 1<br> br label %Loop<br></pre>
+</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
+ <a name="i_cast">'<tt>cast .. to</tt>' Instruction</a>
</div>
<div class="doc_text">
@@ -2579,45 +2602,58 @@
<h5>Syntax:</h5>
<pre>
- <result> = insertelement <n x <ty>> <val>, <ty> <elt>, uint <idx> <i>; yields <n x <ty>></i>
+ <result> = cast <ty> <value> to <ty2> <i>; yields ty2</i>
</pre>
<h5>Overview:</h5>
<p>
-The '<tt>insertelement</tt>' instruction inserts a scalar
-element into a packed vector at a specified index.
+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).
</p>
<h5>Arguments:</h5>
<p>
-The first operand of an '<tt>insertelement</tt>' instruction is a
-value of <a href="#t_packed">packed</a> type. The second operand is a
-scalar value whose type must equal the element type of the first
-operand. The third operand is an index indicating the position at
-which to insert the value. The index may be a variable.</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>
<h5>Semantics:</h5>
<p>
-The result is a packed vector of the same type as <tt>val</tt>. Its
-element values are those of <tt>val</tt> except at position
-<tt>idx</tt>, where it gets the value <tt>elt</tt>. If <tt>idx</tt>
-exceeds the length of <tt>val</tt>, the results are undefined.
+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>
<h5>Example:</h5>
<pre>
- %result = insertelement <4 x int> %vec, int 1, uint 0 <i>; yields <4 x int></i>
+ %X = cast int 257 to ubyte <i>; yields ubyte:1</i>
+ %Y = cast int 123 to bool <i>; yields bool:true</i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
+ <a name="i_select">'<tt>select</tt>' Instruction</a>
</div>
<div class="doc_text">
@@ -2625,47 +2661,34 @@
<h5>Syntax:</h5>
<pre>
- <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <n x uint> <mask> <i>; yields <n x <ty>></i>
+ <result> = select bool <cond>, <ty> <val1>, <ty> <val2> <i>; yields ty</i>
</pre>
<h5>Overview:</h5>
<p>
-The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
-from two input vectors, returning a vector of the same type.
+The '<tt>select</tt>' instruction is used to choose one value based on a
+condition, without branching.
</p>
-<h5>Arguments:</h5>
-<p>
-The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
-with types that match each other and types that match the result of the
-instruction. The third argument is a shuffle mask, which has the same number
-of elements as the other vector type, but whose element type is always 'uint'.
-</p>
+<h5>Arguments:</h5>
<p>
-The shuffle mask operand is required to be a constant vector with either
-constant integer or undef values.
+The '<tt>select</tt>' instruction requires a boolean value indicating the condition, and two values of the same <a href="#t_firstclass">first class</a> type.
</p>
<h5>Semantics:</h5>
<p>
-The elements of the two input vectors are numbered from left to right across
-both of the vectors. The shuffle mask operand specifies, for each element of
-the result vector, which element of the two input registers the result element
-gets. The element selector may be undef (meaning "don't care") and the second
-operand may be undef if performing a shuffle from only one vector.
+If the boolean condition evaluates to true, the instruction returns the first
+value argument; otherwise, it returns the second value argument.
</p>
<h5>Example:</h5>
<pre>
- %result = shufflevector <4 x int> %v1, <4 x int> %v2,
- <4 x uint> <uint 0, uint 4, uint 1, uint 5> <i>; yields <4 x int></i>
- %result = shufflevector <4 x int> %v1, <4 x int> undef,
- <4 x uint> <uint 0, uint 1, uint 2, uint 3> <i>; yields <4 x int></i> - Identity shuffle.
+ %X = select bool true, ubyte 17, ubyte 42 <i>; yields ubyte:17</i>
</pre>
</div>
@@ -3794,7 +3817,7 @@
<a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
- Last modified: $Date: 2006/04/08 04:40:53 $
+ Last modified: $Date: 2006/04/08 23:07:04 $
</address>
</body>
</html>
More information about the llvm-commits
mailing list