Newer
Older
<p>Bitwise binary operators are used to do various forms of
bit-twiddling in a program. They are generally very efficient
instructions, and can commonly be strength reduced from other
instructions. They require two operands, execute an operation on them,
and produce a single value. The resulting value of the bitwise binary
operators is always the same type as its first operand.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_and">'<tt>and</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <result> = and <ty> <var1>, <var2> <i>; yields {ty}:result</i>
<p>The '<tt>and</tt>' instruction returns the bitwise logical and of
its two operands.</p>
<p>The two arguments to the '<tt>and</tt>' instruction must be <a
href="#t_integral">integral</a> values. Both arguments must have
identical types.</p>
<p>The truth table used for the '<tt>and</tt>' instruction is:</p>
<center>
<table border="1" cellspacing="0" cellpadding="4">
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
<tbody>
<tr>
<td>In0</td>
<td>In1</td>
<td>Out</td>
</tr>
<tr>
<td>0</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>0</td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td>1</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>1</td>
<td>1</td>
<td>1</td>
</tr>
</tbody>
</table>
</center>
<pre> <result> = and int 4, %var <i>; yields {int}:result = 4 & %var</i>
<result> = and int 15, 40 <i>; yields {int}:result = 8</i>
<result> = and int 4, 8 <i>; yields {int}:result = 0</i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div>
<div class="doc_text">
<pre> <result> = or <ty> <var1>, <var2> <i>; yields {ty}:result</i>
<h5>Overview:</h5>
<p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive
or of its two operands.</p>
<p>The two arguments to the '<tt>or</tt>' instruction must be <a
href="#t_integral">integral</a> values. Both arguments must have
identical types.</p>
<p>The truth table used for the '<tt>or</tt>' instruction is:</p>
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
<p> </p>
<center>
<table border="1" cellspacing="0" cellpadding="4">
<tbody>
<tr>
<td>In0</td>
<td>In1</td>
<td>Out</td>
</tr>
<tr>
<td>0</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>0</td>
<td>1</td>
<td>1</td>
</tr>
<tr>
<td>1</td>
<td>0</td>
<td>1</td>
</tr>
<tr>
<td>1</td>
<td>1</td>
<td>1</td>
</tr>
</tbody>
</table>
</center>
<pre> <result> = or int 4, %var <i>; yields {int}:result = 4 | %var</i>
<result> = or int 15, 40 <i>; yields {int}:result = 47</i>
<result> = or int 4, 8 <i>; yields {int}:result = 12</i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <result> = xor <ty> <var1>, <var2> <i>; yields {ty}:result</i>
<p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive
or of its two operands. The <tt>xor</tt> is used to implement the
"one's complement" operation, which is the "~" operator in C.</p>
<p>The two arguments to the '<tt>xor</tt>' instruction must be <a
href="#t_integral">integral</a> values. Both arguments must have
identical types.</p>
<p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
<p> </p>
<center>
<table border="1" cellspacing="0" cellpadding="4">
<tbody>
<tr>
<td>In0</td>
<td>In1</td>
<td>Out</td>
</tr>
<tr>
<td>0</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>0</td>
<td>1</td>
<td>1</td>
</tr>
<tr>
<td>1</td>
<td>0</td>
<td>1</td>
</tr>
<tr>
<td>1</td>
<td>1</td>
<td>0</td>
</tr>
</tbody>
</table>
</center>
<p> </p>
<pre> <result> = xor int 4, %var <i>; yields {int}:result = 4 ^ %var</i>
<result> = xor int 15, 40 <i>; yields {int}:result = 39</i>
<result> = xor int 4, 8 <i>; yields {int}:result = 12</i>
Chris Lattner
committed
<result> = xor int %V, -1 <i>; yields {int}:result = ~%V</i>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <result> = shl <ty> <var1>, ubyte <var2> <i>; yields {ty}:result</i>
<p>The '<tt>shl</tt>' instruction returns the first operand shifted to
the left a specified number of bits.</p>
<p>The first argument to the '<tt>shl</tt>' instruction must be an <a
href="#t_integer">integer</a> type. The second argument must be an '<tt>ubyte</tt>'
type.</p>
<p>The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.</p>
<pre> <result> = shl int 4, ubyte %var <i>; yields {int}:result = 4 << %var</i>
<result> = shl int 4, ubyte 2 <i>; yields {int}:result = 16</i>
<result> = shl int 1, ubyte 10 <i>; yields {int}:result = 1024</i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_shr">'<tt>shr</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <result> = shr <ty> <var1>, ubyte <var2> <i>; yields {ty}:result</i>
<p>The '<tt>shr</tt>' instruction returns the first operand shifted to
the right a specified number of bits.</p>
<p>The first argument to the '<tt>shr</tt>' instruction must be an <a
href="#t_integer">integer</a> type. The second argument must be an '<tt>ubyte</tt>'
type.</p>
<p>If the first argument is a <a href="#t_signed">signed</a> type, the
most significant bit is duplicated in the newly free'd bit positions.
If the first argument is unsigned, zero bits shall fill the empty
positions.</p>
<pre> <result> = shr int 4, ubyte %var <i>; yields {int}:result = 4 >> %var</i>
<result> = shr uint 4, ubyte 1 <i>; yields {uint}:result = 2</i>
<result> = shr int 4, ubyte 2 <i>; yields {int}:result = 1</i>
<result> = shr sbyte 4, ubyte 3 <i>; yields {sbyte}:result = 0</i>
<result> = shr sbyte -2, ubyte 1 <i>; yields {sbyte}:result = -1</i>
</div>
<!-- ======================================================================= -->
<div class="doc_subsection"> <a name="memoryops">Memory Access
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>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_malloc">'<tt>malloc</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <result> = malloc <type>, uint <NumElements> <i>; yields {type*}:result</i>
<result> = malloc <type> <i>; yields {type*}:result</i>
<p>The '<tt>malloc</tt>' instruction allocates memory from the system
heap and returns a pointer to it.</p>
<p>The 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. The second form of the instruction is
a shorter version of the first instruction that defaults to allocating
one element.</p>
<p>'<tt>type</tt>' must be a sized type.</p>
<p>Memory is allocated using the system "<tt>malloc</tt>" function, and
a pointer is returned.</p>
<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>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_free">'<tt>free</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> free <type> <value> <i>; yields {void}</i>
<p>The '<tt>free</tt>' instruction returns memory back to the unused
memory heap, to be reallocated in the future.</p>
<p> </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>
<p>Access to the memory pointed to by the pointer is not longer defined
after this instruction executes.</p>
<pre> %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_alloca">'<tt>alloca</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <result> = alloca <type>, uint <NumElements> <i>; yields {type*}:result</i>
<result> = alloca <type> <i>; yields {type*}:result</i>
<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 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. The second form of the instruction is
a shorter version of the first that defaults to allocating one element.</p>
<p>'<tt>type</tt>' may be any sized type.</p>
<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_invoke">invoke</a></tt>
instructions), the memory is reclaimed.</p>
<pre> %ptr = alloca int <i>; yields {int*}:ptr</i>
%ptr = alloca int, uint 4 <i>; yields {int*}:ptr</i>
</pre>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_load">'<tt>load</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 to load from. 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>
<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>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
Instruction</a> </div>
<pre> store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
volatile store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
<p>The '<tt>store</tt>' instruction is used to write to memory.</p>
<p>There are two arguments to the '<tt>store</tt>' instruction: a value
to store and an address to store it into. 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>
<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 class="doc_subsubsection"> <a name="i_getelementptr">'<tt>getelementptr</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <result> = getelementptr <ty>* <ptrval>{, long <aidx>|, ubyte <sidx>}*<br></pre>
<p>The '<tt>getelementptr</tt>' instruction is used to get the address
of a subelement of an aggregate data structure.</p>
<p>This instruction takes a list of <tt>long</tt> values and <tt>ubyte</tt>
constants that indicate what form of addressing to perform. 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.</p>
<p>For example, let's consider a C code fragment and how it gets
compiled to LLVM:</p>
<pre>struct RT {<br> char A;<br> int B[10][20];<br> char C;<br>};<br>struct ST {<br> int X;<br> double Y;<br> struct RT Z;<br>};<br><br>int *foo(struct ST *s) {<br> return &s[1].Z.B[5][13];<br>}<br></pre>
<p>The LLVM code generated by the GCC frontend is:</p>
<pre>%RT = type { sbyte, [10 x [20 x int]], sbyte }<br>%ST = type { int, double, %RT }<br><br>int* "foo"(%ST* %s) {<br> %reg = getelementptr %ST* %s, long 1, ubyte 2, ubyte 1, long 5, long 13<br> ret int* %reg<br>}<br></pre>
<p>The index types specified for the '<tt>getelementptr</tt>'
instruction depend on the pointer type that is being index into. <a
href="t_pointer">Pointer</a> and <a href="t_array">array</a> types
require '<tt>long</tt>' values, and <a href="t_struct">structure</a>
types require '<tt>ubyte</tt>' <b>constants</b>.</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 return a pointer to this element, thus yielding a '<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>
<pre>int* "foo"(%ST* %s) {<br> %t1 = getelementptr %ST* %s , long 1 <i>; yields %ST*:%t1</i>
%t2 = getelementptr %ST* %t1, long 0, ubyte 2 <i>; yields %RT*:%t2</i>
%t3 = getelementptr %RT* %t2, long 0, ubyte 1 <i>; yields [10 x [20 x int]]*:%t3</i>
%t4 = getelementptr [10 x [20 x int]]* %t3, long 0, long 5 <i>; yields [20 x int]*:%t4</i>
%t5 = getelementptr [20 x int]* %t4, long 0, long 13 <i>; yields int*:%t5</i>
ret int* %t5
}
</pre>
<pre> <i>; yields [12 x ubyte]*:aptr</i>
%aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, ubyte 1<br></pre>
<h5> Note To The Novice:</h5>
When using indexing into global arrays with the '<tt>getelementptr</tt>'
instruction, you must remember that the </div>
<!-- ======================================================================= -->
<div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
<div class="doc_text">
<p>The instructions in this catagory 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">
<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_cast">'<tt>cast .. to</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <result> = cast <ty> <value> to <ty2> <i>; yields ty2</i>
<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>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>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>
<pre> %X = cast int 257 to ubyte <i>; yields ubyte:1</i>
%Y = cast int 123 to bool <i>; yields bool:true</i>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_call">'<tt>call</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <result> = call <ty>* <fnptrval>(<param list>)<br></pre>
<p>The '<tt>call</tt>' instruction represents a simple function call.</p>
<p>This instruction requires several arguments:</p>
<li>
<p>'<tt>ty</tt>': shall be the signature of the pointer to function
value being invoked. The argument types must match the types implied
by this signature.</p>
</li>
<li>
<p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a
function to be invoked. In most cases, this is a direct function
invocation, but indirect <tt>call</tt>s are just as possible,
calling an arbitrary pointer to function values.</p>
</li>
<li>
<p>'<tt>function args</tt>': argument list whose types match the
function signature argument types. If the function signature
indicates the function accepts a variable number of arguments, the
extra arguments can be specified.</p>
</li>
<p>The '<tt>call</tt>' instruction is used to cause control flow to
transfer to a specified function, with its incoming arguments bound to
the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>'
instruction in the called function, control flow continues with the
instruction after the function call, and the return value of the
function is bound to the result argument. This is a simpler case of
the <a href="#i_invoke">invoke</a> instruction.</p>
<pre> %retval = call int %test(int %argc)<br> call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);<br></pre>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_vanext">'<tt>vanext</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <resultarglist> = vanext <va_list> <arglist>, <argty><br></pre>
<p>The '<tt>vanext</tt>' instruction is used to access arguments passed
through the "variable argument" area of a function call. It is used to
implement the <tt>va_arg</tt> macro in C.</p>
<p>This instruction takes a <tt>valist</tt> value and the type of the
argument. It returns another <tt>valist</tt>.</p>
<p>The '<tt>vanext</tt>' instruction advances the specified <tt>valist</tt>
past an argument of the specified type. In conjunction with the <a
href="#i_vaarg"><tt>vaarg</tt></a> instruction, it is used to implement
the <tt>va_arg</tt> macro available in C. For more information, see
the variable argument handling <a href="#int_varargs">Intrinsic
Functions</a>.</p>
<p>It is legal for this instruction to be called in a function which
does not take a variable number of arguments, for example, the <tt>vfprintf</tt>
function.</p>
<p><tt>vanext</tt> is an LLVM instruction instead of an <a
href="#intrinsics">intrinsic function</a> because it takes an type as
an argument.</p>
<p>See the <a href="#int_varargs">variable argument processing</a>
section.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_vaarg">'<tt>vaarg</tt>'
Instruction</a> </div>
<div class="doc_text">
<pre> <resultval> = vaarg <va_list> <arglist>, <argty><br></pre>
<p>The '<tt>vaarg</tt>' instruction is used to access arguments passed
through the "variable argument" area of a function call. It is used to
implement the <tt>va_arg</tt> macro in C.</p>
<p>This instruction takes a <tt>valist</tt> value and the type of the
argument. It returns a value of the specified argument type.</p>
<p>The '<tt>vaarg</tt>' instruction loads an argument of the specified
type from the specified <tt>va_list</tt>. In conjunction with the <a
href="#i_vanext"><tt>vanext</tt></a> instruction, it is used to
implement the <tt>va_arg</tt> macro available in C. For more
information, see the variable argument handling <a href="#int_varargs">Intrinsic
Functions</a>.</p>
<p>It is legal for this instruction to be called in a function which
does not take a variable number of arguments, for example, the <tt>vfprintf</tt>
function.</p>
<p><tt>vaarg</tt> is an LLVM instruction instead of an <a
href="#intrinsics">intrinsic function</a> because it takes an type as
an argument.</p>
<p>See the <a href="#int_varargs">variable argument processing</a>
section.</p>
</div>
<!-- *********************************************************************** -->
<div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
<!-- *********************************************************************** -->
<div class="doc_text">
<p>LLVM supports the notion of an "intrinsic function". These
functions have well known names and semantics, and are required to
follow certain restrictions. Overall, these instructions represent an
extension mechanism for the LLVM language that does not require
changing all of the transformations in LLVM to add to the language (or
the bytecode reader/writer, the parser, etc...).</p>
<p>Intrinsic function names must all start with an "<tt>llvm.</tt>"
prefix, this prefix is reserved in LLVM for intrinsic names, thus
functions may not be named this. Intrinsic functions must always be
external functions: you cannot define the body of intrinsic functions.
Intrinsic functions may only be used in call or invoke instructions: it
is illegal to take the address of an intrinsic function. Additionally,
because intrinsic functions are part of the LLVM language, it is
required that they all be documented here if any are added.</p>
<p>Unless an intrinsic function is target-specific, there must be a
lowering pass to eliminate the intrinsic or all backends must support
the intrinsic function.</p>
</div>
<!-- ======================================================================= -->
<div class="doc_subsection"> <a name="int_varargs">Variable Argument
Handling Intrinsics</a> </div>
<div class="doc_text">
<p>Variable argument support is defined in LLVM with the <a
href="#i_vanext"><tt>vanext</tt></a> instruction and these three
intrinsic functions. These functions are related to the similarly
named macros defined in the <tt><stdarg.h></tt> header file.</p>
<p>All of these functions operate on arguments that use a
target-specific value type "<tt>va_list</tt>". The LLVM assembly
language reference manual does not define what this type is, so all
transformations should be prepared to handle intrinsics with any type
used.</p>
<p>This example shows how the <a href="#i_vanext"><tt>vanext</tt></a>
instruction and the variable argument handling intrinsic functions are
used.</p>
<pre>int %test(int %X, ...) {<br> ; Initialize variable argument processing<br> %ap = call sbyte*()* %<a
href="#i_va_start">llvm.va_start</a>()<br><br> ; Read a single integer argument<br> %tmp = vaarg sbyte* %ap, int<br><br> ; Advance to the next argument<br> %ap2 = vanext sbyte* %ap, int<br><br> ; Demonstrate usage of llvm.va_copy and llvm.va_end<br> %aq = call sbyte* (sbyte*)* %<a
href="#i_va_copy">llvm.va_copy</a>(sbyte* %ap2)<br> call void %<a
href="#i_va_end">llvm.va_end</a>(sbyte* %aq)<br><br> ; Stop processing of arguments.<br> call void %<a
href="#i_va_end">llvm.va_end</a>(sbyte* %ap2)<br> ret int %tmp<br>}<br></pre>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_va_start">'<tt>llvm.va_start</tt>'
Intrinsic</a> </div>
<div class="doc_text">
<pre> call va_list ()* %llvm.va_start()<br></pre>
<p>The '<tt>llvm.va_start</tt>' intrinsic returns a new <tt><arglist></tt>
for subsequent use by the variable argument intrinsics.</p>
<p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
macro available in C. In a target-dependent way, it initializes and
returns a <tt>va_list</tt> element, so that the next <tt>vaarg</tt>
will produce the first variable argument passed to the function. Unlike
the C <tt>va_start</tt> macro, this intrinsic does not need to know the
last argument of the function, the compiler can figure that out.</p>
<p>Note that this intrinsic function is only legal to be called from
within the body of a variable argument function.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_va_end">'<tt>llvm.va_end</tt>'
Intrinsic</a> </div>
<div class="doc_text">
<pre> call void (va_list)* %llvm.va_end(va_list <arglist>)<br></pre>
<p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt><arglist></tt>
which has been initialized previously with <tt><a href="#i_va_start">llvm.va_start</a></tt>
or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
<p>The argument is a <tt>va_list</tt> to destroy.</p>
<p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
macro available in C. In a target-dependent way, it destroys the <tt>va_list</tt>.
Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly
with calls to <tt>llvm.va_end</tt>.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="i_va_copy">'<tt>llvm.va_copy</tt>'
Intrinsic</a> </div>
<div class="doc_text">
<pre> call va_list (va_list)* %llvm.va_copy(va_list <destarglist>)<br></pre>
<p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument
position from the source argument list to the destination argument list.</p>
<p>The argument is the <tt>va_list</tt> to copy.</p>
<p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
macro available in C. In a target-dependent way, it copies the source <tt>va_list</tt>
element into the returned list. This intrinsic is necessary because the <tt><a
href="i_va_start">llvm.va_start</a></tt> intrinsic may be arbitrarily
complex and require memory allocation, for example.</p>
</div>
<!-- *********************************************************************** -->
<hr>
<div class="doc_footer">
<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
<a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a> <br>
Last modified: $Date$ </div>
</body>
</html>