Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / f9e8a0f03f2749dd8e3f4e311592be6106742396 / . / docs / LangRef.html
blob: a664f328d5d54596850162c028d22f03c2038306 [file] [log] [blame]
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]2<html><head><title>LLVM Assembly Language Reference Manual</title></head>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]3<body bgcolor=white>
4
5<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]6<tr><td>&nbsp; <font size=+5 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>LLVM Language Reference Manual</b></font></td>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]7</tr></table>
8
9<ol>
10 <li><a href="#abstract">Abstract</a>
11 <li><a href="#introduction">Introduction</a>
12 <li><a href="#identifiers">Identifiers</a>
13 <li><a href="#typesystem">Type System</a>
14 <ol>
15 <li><a href="#t_primitive">Primitive Types</a>
16 <ol>
17 <li><a href="#t_classifications">Type Classifications</a>
18 </ol>
19 <li><a href="#t_derived">Derived Types</a>
20 <ol>
21 <li><a href="#t_array" >Array Type</a>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]22 <li><a href="#t_function">Function Type</a>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]23 <li><a href="#t_pointer">Pointer Type</a>
24 <li><a href="#t_struct" >Structure Type</a>
Chris Lattner690d99b2002-08-29 18:33:48 +0000[diff] [blame]25 <!-- <li><a href="#t_packed" >Packed Type</a> -->
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]26 </ol>
27 </ol>
28 <li><a href="#highlevel">High Level Structure</a>
29 <ol>
30 <li><a href="#modulestructure">Module Structure</a>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]31 <li><a href="#globalvars">Global Variables</a>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]32 <li><a href="#functionstructure">Function Structure</a>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]33 </ol>
34 <li><a href="#instref">Instruction Reference</a>
35 <ol>
36 <li><a href="#terminators">Terminator Instructions</a>
37 <ol>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]38 <li><a href="#i_ret" >'<tt>ret</tt>' Instruction</a>
39 <li><a href="#i_br" >'<tt>br</tt>' Instruction</a>
40 <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a>
41 <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]42 <li><a href="#i_unwind" >'<tt>unwind</tt>' Instruction</a>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]43 </ol>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]44 <li><a href="#binaryops">Binary Operations</a>
45 <ol>
46 <li><a href="#i_add" >'<tt>add</tt>' Instruction</a>
47 <li><a href="#i_sub" >'<tt>sub</tt>' Instruction</a>
48 <li><a href="#i_mul" >'<tt>mul</tt>' Instruction</a>
49 <li><a href="#i_div" >'<tt>div</tt>' Instruction</a>
50 <li><a href="#i_rem" >'<tt>rem</tt>' Instruction</a>
51 <li><a href="#i_setcc">'<tt>set<i>cc</i></tt>' Instructions</a>
52 </ol>
53 <li><a href="#bitwiseops">Bitwise Binary Operations</a>
54 <ol>
55 <li><a href="#i_and">'<tt>and</tt>' Instruction</a>
56 <li><a href="#i_or" >'<tt>or</tt>' Instruction</a>
57 <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a>
58 <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a>
59 <li><a href="#i_shr">'<tt>shr</tt>' Instruction</a>
60 </ol>
61 <li><a href="#memoryops">Memory Access Operations</a>
62 <ol>
63 <li><a href="#i_malloc" >'<tt>malloc</tt>' Instruction</a>
64 <li><a href="#i_free" >'<tt>free</tt>' Instruction</a>
65 <li><a href="#i_alloca" >'<tt>alloca</tt>' Instruction</a>
66 <li><a href="#i_load" >'<tt>load</tt>' Instruction</a>
67 <li><a href="#i_store" >'<tt>store</tt>' Instruction</a>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]68 <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]69 </ol>
70 <li><a href="#otherops">Other Operations</a>
71 <ol>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]72 <li><a href="#i_phi" >'<tt>phi</tt>' Instruction</a>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]73 <li><a href="#i_cast">'<tt>cast .. to</tt>' Instruction</a>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]74 <li><a href="#i_call" >'<tt>call</tt>' Instruction</a>
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]75 <li><a href="#i_vanext">'<tt>vanext</tt>' Instruction</a>
76 <li><a href="#i_vaarg" >'<tt>vaarg</tt>' Instruction</a>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]77 </ol>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]78 </ol>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]79 <li><a href="#intrinsics">Intrinsic Functions</a>
80 <ol>
81 <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
82 <ol>
83 <li><a href="#i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
84 <li><a href="#i_va_end" >'<tt>llvm.va_end</tt>' Intrinsic</a>
85 <li><a href="#i_va_copy" >'<tt>llvm.va_copy</tt>' Intrinsic</a>
86 </ol>
87 </ol>
Chris Lattnerd816bcf2002-08-30 21:50:21 +0000[diff] [blame]88
89 <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and <A href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></b><p>
90
91
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]92</ol>
93
94
95<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]96<p><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
97<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]98<a name="abstract">Abstract
99</b></font></td></tr></table><ul>
100<!-- *********************************************************************** -->
101
102<blockquote>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]103 This document is a reference manual for the LLVM assembly language. LLVM is
Chris Lattnerfde246a2003-09-02 23:38:41 +0000[diff] [blame]104 an SSA based representation that provides type safety, low-level operations,
105 flexibility, and the capability of representing 'all' high-level languages
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]106 cleanly. It is the common code representation used throughout all phases of
107 the LLVM compilation strategy.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]108</blockquote>
109
110
111
112
113<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]114</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
115<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]116<a name="introduction">Introduction
117</b></font></td></tr></table><ul>
118<!-- *********************************************************************** -->
119
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]120The LLVM code representation is designed to be used in three different forms: as
Chris Lattnerfde246a2003-09-02 23:38:41 +0000[diff] [blame]121an in-memory compiler IR, as an on-disk bytecode representation (suitable for
122fast loading by a Just-In-Time compiler), and as a human readable assembly
123language representation. This allows LLVM to provide a powerful intermediate
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]124representation for efficient compiler transformations and analysis, while
125providing a natural means to debug and visualize the transformations. The three
126different forms of LLVM are all equivalent. This document describes the human
127readable representation and notation.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]128
Chris Lattnerfde246a2003-09-02 23:38:41 +0000[diff] [blame]129The LLVM representation aims to be a light-weight and low-level while being
Chris Lattnerb7c6c2a2002-06-25 20:20:08 +0000[diff] [blame]130expressive, typed, and extensible at the same time. It aims to be a "universal
Chris Lattnerfde246a2003-09-02 23:38:41 +0000[diff] [blame]131IR" of sorts, by being at a low enough level that high-level ideas may be
Chris Lattnerb7c6c2a2002-06-25 20:20:08 +0000[diff] [blame]132cleanly mapped to it (similar to how microprocessors are "universal IR's",
133allowing many source languages to be mapped to them). By providing type
134information, LLVM can be used as the target of optimizations: for example,
135through pointer analysis, it can be proven that a C automatic variable is never
136accessed outside of the current function... allowing it to be promoted to a
137simple SSA value instead of a memory location.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]138
139<!-- _______________________________________________________________________ -->
140</ul><a name="wellformed"><h4><hr size=0>Well Formedness</h4><ul>
141
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]142It is important to note that this document describes 'well formed' LLVM assembly
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]143language. There is a difference between what the parser accepts and what is
144considered 'well formed'. For example, the following instruction is
145syntactically okay, but not well formed:<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]146
147<pre>
148 %x = <a href="#i_add">add</a> int 1, %x
149</pre>
150
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]151...because the definition of <tt>%x</tt> does not dominate all of its uses. The
152LLVM infrastructure provides a verification pass that may be used to verify that
153an LLVM module is well formed. This pass is automatically run by the parser
154after parsing input assembly, and by the optimizer before it outputs bytecode.
155The violations pointed out by the verifier pass indicate bugs in transformation
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]156passes or input to the parser.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]157
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]158<!-- Describe the typesetting conventions here. -->
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]159
160
161<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]162</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
163<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]164<a name="identifiers">Identifiers
165</b></font></td></tr></table><ul>
166<!-- *********************************************************************** -->
167
168LLVM uses three different forms of identifiers, for different purposes:<p>
169
170<ol>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]171<li>Numeric constants are represented as you would expect: 12, -3 123.421, etc.
172Floating point constants have an optional hexidecimal notation.
173
174<li>Named values are represented as a string of characters with a '%' prefix.
175For example, %foo, %DivisionByZero, %a.really.long.identifier. The actual
176regular expression used is '<tt>%[a-zA-Z$._][a-zA-Z$._0-9]*</tt>'. Identifiers
177which require other characters in their names can be surrounded with quotes. In
178this way, anything except a <tt>"</tt> character can be used in a name.
179
180<li>Unnamed values are represented as an unsigned numeric value with a '%'
181prefix. For example, %12, %2, %44.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]182</ol><p>
183
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]184LLVM requires the values start with a '%' sign for two reasons: Compilers don't
185need to worry about name clashes with reserved words, and the set of reserved
186words may be expanded in the future without penalty. Additionally, unnamed
187identifiers allow a compiler to quickly come up with a temporary variable
188without having to avoid symbol table conflicts.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]189
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]190Reserved words in LLVM are very similar to reserved words in other languages.
191There are keywords for different opcodes ('<tt><a href="#i_add">add</a></tt>',
192'<tt><a href="#i_cast">cast</a></tt>', '<tt><a href="#i_ret">ret</a></tt>',
193etc...), for primitive type names ('<tt><a href="#t_void">void</a></tt>',
194'<tt><a href="#t_uint">uint</a></tt>', etc...), and others. These reserved
195words cannot conflict with variable names, because none of them start with a '%'
196character.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]197
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]198Here is an example of LLVM code to multiply the integer variable '<tt>%X</tt>'
199by 8:<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]200
201The easy way:
202<pre>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]203 %result = <a href="#i_mul">mul</a> uint %X, 8
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]204</pre>
205
206After strength reduction:
207<pre>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]208 %result = <a href="#i_shl">shl</a> uint %X, ubyte 3
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]209</pre>
210
211And the hard way:
212<pre>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]213 <a href="#i_add">add</a> uint %X, %X <i>; yields {uint}:%0</i>
214 <a href="#i_add">add</a> uint %0, %0 <i>; yields {uint}:%1</i>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]215 %result = <a href="#i_add">add</a> uint %1, %1
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]216</pre>
217
218This last way of multiplying <tt>%X</tt> by 8 illustrates several important lexical features of LLVM:<p>
219
220<ol>
221<li>Comments are delimited with a '<tt>;</tt>' and go until the end of line.
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]222<li>Unnamed temporaries are created when the result of a computation is not
223 assigned to a named value.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]224<li>Unnamed temporaries are numbered sequentially
225</ol><p>
226
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]227...and it also show a convention that we follow in this document. When
228demonstrating instructions, we will follow an instruction with a comment that
229defines the type and name of value produced. Comments are shown in italic
230text.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]231
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]232The one non-intuitive notation for constants is the optional hexidecimal form of
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]233floating point constants. For example, the form '<tt>double
2340x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
2354.5e+15</tt>' which is also supported by the parser. The only time hexadecimal
236floating point constants are useful (and the only time that they are generated
237by the disassembler) is when an FP constant has to be emitted that is not
238representable as a decimal floating point number exactly. For example, NaN's,
239infinities, and other special cases are represented in their IEEE hexadecimal
240format so that assembly and disassembly do not cause any bits to change in the
241constants.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]242
243
244<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]245</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
246<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]247<a name="typesystem">Type System
248</b></font></td></tr></table><ul>
249<!-- *********************************************************************** -->
250
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]251The LLVM type system is one of the most important features of the intermediate
Chris Lattnerb7c6c2a2002-06-25 20:20:08 +0000[diff] [blame]252representation. Being typed enables a number of optimizations to be performed
253on the IR directly, without having to do extra analyses on the side before the
254transformation. A strong type system makes it easier to read the generated code
255and enables novel analyses and transformations that are not feasible to perform
256on normal three address code representations.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]257
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]258<!-- The written form for the type system was heavily influenced by the
259syntactic problems with types in the C language<sup><a
260href="#rw_stroustrup">1</a></sup>.<p> -->
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]261
262
263
264<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]265</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
266<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]267<a name="t_primitive">Primitive Types
268</b></font></td></tr></table><ul>
269
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]270The primitive types are the fundemental building blocks of the LLVM system. The
271current set of primitive types are as follows:<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]272
273<table border=0 align=center><tr><td>
274
275<table border=1 cellspacing=0 cellpadding=4 align=center>
276<tr><td><tt>void</tt></td> <td>No value</td></tr>
277<tr><td><tt>ubyte</tt></td> <td>Unsigned 8 bit value</td></tr>
278<tr><td><tt>ushort</tt></td><td>Unsigned 16 bit value</td></tr>
279<tr><td><tt>uint</tt></td> <td>Unsigned 32 bit value</td></tr>
280<tr><td><tt>ulong</tt></td> <td>Unsigned 64 bit value</td></tr>
281<tr><td><tt>float</tt></td> <td>32 bit floating point value</td></tr>
282<tr><td><tt>label</tt></td> <td>Branch destination</td></tr>
283</table>
284
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]285</td><td valign=top>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]286
287<table border=1 cellspacing=0 cellpadding=4 align=center>
288<tr><td><tt>bool</tt></td> <td>True or False value</td></tr>
289<tr><td><tt>sbyte</tt></td> <td>Signed 8 bit value</td></tr>
290<tr><td><tt>short</tt></td> <td>Signed 16 bit value</td></tr>
291<tr><td><tt>int</tt></td> <td>Signed 32 bit value</td></tr>
292<tr><td><tt>long</tt></td> <td>Signed 64 bit value</td></tr>
293<tr><td><tt>double</tt></td><td>64 bit floating point value</td></tr>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]294</table>
295
296</td></tr></table><p>
297
298
299
300<!-- _______________________________________________________________________ -->
301</ul><a name="t_classifications"><h4><hr size=0>Type Classifications</h4><ul>
302
303These different primitive types fall into a few useful classifications:<p>
304
305<table border=1 cellspacing=0 cellpadding=4 align=center>
306<tr><td><a name="t_signed">signed</td> <td><tt>sbyte, short, int, long, float, double</tt></td></tr>
307<tr><td><a name="t_unsigned">unsigned</td><td><tt>ubyte, ushort, uint, ulong</tt></td></tr>
Chris Lattnerb5561ff2003-06-18 21:28:11 +0000[diff] [blame]308<tr><td><a name="t_integer">integer</td><td><tt>ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td></tr>
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]309<tr><td><a name="t_integral">integral</td><td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td></tr>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]310<tr><td><a name="t_floating">floating point</td><td><tt>float, double</tt></td></tr>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]311<tr><td><a name="t_firstclass">first class</td><td><tt>bool, ubyte, sbyte, ushort, short,<br> uint, int, ulong, long, float, double, <a href="#t_pointer">pointer</a></tt></td></tr>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]312</table><p>
313
Chris Lattner478921b2003-10-30 01:31:37 +0000[diff] [blame]314The <a href="#t_firstclass">first class</a> types are perhaps the most
315important. Values of these types are the only ones which can be produced by
316instructions, passed as arguments, or used as operands to instructions. This
317means that all structures and arrays must be manipulated either by pointer or by
318component.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]319
320
321<!-- ======================================================================= -->
322</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
323<a name="t_derived">Derived Types
324</b></font></td></tr></table><ul>
325
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]326The real power in LLVM comes from the derived types in the system. This is what
327allows a programmer to represent arrays, functions, pointers, and other useful
328types. Note that these derived types may be recursive: For example, it is
329possible to have a two dimensional array.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]330
331
332
333<!-- _______________________________________________________________________ -->
334</ul><a name="t_array"><h4><hr size=0>Array Type</h4><ul>
335
336<h5>Overview:</h5>
337
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]338The array type is a very simple derived type that arranges elements sequentially
339in memory. The array type requires a size (number of elements) and an
340underlying data type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]341
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]342<h5>Syntax:</h5>
343<pre>
344 [&lt;# elements&gt; x &lt;elementtype&gt;]
345</pre>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]346
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]347The number of elements is a constant integer value, elementtype may be any type
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]348with a size.<p>
349
350<h5>Examples:</h5>
351<ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]352 <tt>[40 x int ]</tt>: Array of 40 integer values.<br>
353 <tt>[41 x int ]</tt>: Array of 41 integer values.<br>
354 <tt>[40 x uint]</tt>: Array of 40 unsigned integer values.<p>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]355</ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]356
357Here are some examples of multidimensional arrays:<p>
358<ul>
359<table border=0 cellpadding=0 cellspacing=0>
360<tr><td><tt>[3 x [4 x int]]</tt></td><td>: 3x4 array integer values.</td></tr>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]361<tr><td><tt>[12 x [10 x float]]</tt></td><td>: 12x10 array of single precision floating point values.</td></tr>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]362<tr><td><tt>[2 x [3 x [4 x uint]]]</tt></td><td>: 2x3x4 array of unsigned integer values.</td></tr>
363</table>
364</ul>
365
366
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]367<!-- _______________________________________________________________________ -->
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]368</ul><a name="t_function"><h4><hr size=0>Function Type</h4><ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]369
370<h5>Overview:</h5>
371
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]372The function type can be thought of as a function signature. It consists of a
373return type and a list of formal parameter types. Function types are usually
374used when to build virtual function tables (which are structures of pointers to
375functions), for indirect function calls, and when defining a function.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]376
377<h5>Syntax:</h5>
378<pre>
379 &lt;returntype&gt; (&lt;parameter list&gt;)
380</pre>
381
Misha Brukmanbc0e9982003-07-14 17:20:40 +0000[diff] [blame]382Where '<tt>&lt;parameter list&gt;</tt>' is a comma-separated list of type
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]383specifiers. Optionally, the parameter list may include a type <tt>...</tt>,
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]384which indicates that the function takes a variable number of arguments.
385Variable argument functions can access their arguments with the <a
386href="#int_varargs">variable argument handling intrinsic</a> functions.
387<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]388
389<h5>Examples:</h5>
390<ul>
391<table border=0 cellpadding=0 cellspacing=0>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]392
393<tr><td><tt>int (int)</tt></td><td>: function taking an <tt>int</tt>, returning
394an <tt>int</tt></td></tr>
395
396<tr><td><tt>float (int, int *) *</tt></td><td>: <a href="#t_pointer">Pointer</a>
397to a function that takes an <tt>int</tt> and a <a href="#t_pointer">pointer</a>
398to <tt>int</tt>, returning <tt>float</tt>.</td></tr>
399
400<tr><td><tt>int (sbyte *, ...)</tt></td><td>: A vararg function that takes at
401least one <a href="#t_pointer">pointer</a> to <tt>sbyte</tt> (signed char in C),
402which returns an integer. This is the signature for <tt>printf</tt> in
403LLVM.</td></tr>
404
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]405</table>
406</ul>
407
408
409
410<!-- _______________________________________________________________________ -->
411</ul><a name="t_struct"><h4><hr size=0>Structure Type</h4><ul>
412
413<h5>Overview:</h5>
414
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]415The structure type is used to represent a collection of data members together in
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]416memory. The packing of the field types is defined to match the ABI of the
417underlying processor. The elements of a structure may be any type that has a
418size.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]419
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]420Structures are accessed using '<tt><a href="#i_load">load</a></tt> and '<tt><a
421href="#i_store">store</a></tt>' by getting a pointer to a field with the '<tt><a
422href="#i_getelementptr">getelementptr</a></tt>' instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]423
424<h5>Syntax:</h5>
425<pre>
426 { &lt;type list&gt; }
427</pre>
428
429
430<h5>Examples:</h5>
431<table border=0 cellpadding=0 cellspacing=0>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]432
433<tr><td><tt>{ int, int, int }</tt></td><td>: a triple of three <tt>int</tt>
434values</td></tr>
435
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]436<tr><td><tt>{ float, int (int) * }</tt></td><td>: A pair, where the first
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]437element is a <tt>float</tt> and the second element is a <a
438href="#t_pointer">pointer</a> to a <a href="t_function">function</a> that takes
439an <tt>int</tt>, returning an <tt>int</tt>.</td></tr>
440
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]441</table>
442
443
444<!-- _______________________________________________________________________ -->
445</ul><a name="t_pointer"><h4><hr size=0>Pointer Type</h4><ul>
446
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]447<h5>Overview:</h5>
448
449As in many languages, the pointer type represents a pointer or reference to
450another object, which must live in memory.<p>
451
452<h5>Syntax:</h5>
453<pre>
454 &lt;type&gt; *
455</pre>
456
457<h5>Examples:</h5>
458
459<table border=0 cellpadding=0 cellspacing=0>
460
461<tr><td><tt>[4x int]*</tt></td><td>: <a href="#t_pointer">pointer</a> to <a
462href="#t_array">array</a> of four <tt>int</tt> values</td></tr>
463
464<tr><td><tt>int (int *) *</tt></td><td>: A <a href="#t_pointer">pointer</a> to a
465<a href="t_function">function</a> that takes an <tt>int</tt>, returning an
466<tt>int</tt>.</td></tr>
467
468</table>
469<p>
470
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]471
472<!-- _______________________________________________________________________ -->
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]473<!--
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]474</ul><a name="t_packed"><h4><hr size=0>Packed Type</h4><ul>
475
476Mention/decide that packed types work with saturation or not. Maybe have a packed+saturated type in addition to just a packed type.<p>
477
478Packed types should be 'nonsaturated' because standard data types are not saturated. Maybe have a saturated packed type?<p>
479
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]480-->
481
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]482
483<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]484</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
485<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]486<a name="highlevel">High Level Structure
487</b></font></td></tr></table><ul>
488<!-- *********************************************************************** -->
489
490
491<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]492</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
493<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]494<a name="modulestructure">Module Structure
495</b></font></td></tr></table><ul>
496
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]497LLVM programs are composed of "Module"s, each of which is a translation unit of
498the input programs. Each module consists of functions, global variables, and
499symbol table entries. Modules may be combined together with the LLVM linker,
500which merges function (and global variable) definitions, resolves forward
501declarations, and merges symbol table entries. Here is an example of the "hello world" module:<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]502
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]503<pre>
504<i>; Declare the string constant as a global constant...</i>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]505<a href="#identifiers">%.LC0</a> = <a href="#linkage_internal">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x sbyte]</a> c"hello world\0A\00" <i>; [13 x sbyte]*</i>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]506
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]507<i>; External declaration of the puts function</i>
508<a href="#functionstructure">declare</a> int %puts(sbyte*) <i>; int(sbyte*)* </i>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]509
510<i>; Definition of main function</i>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]511int %main() { <i>; int()* </i>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]512 <i>; Convert [13x sbyte]* to sbyte *...</i>
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]513 %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, long 0, long 0 <i>; sbyte*</i>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]514
515 <i>; Call puts function to write out the string to stdout...</i>
516 <a href="#i_call">call</a> int %puts(sbyte* %cast210) <i>; int</i>
517 <a href="#i_ret">ret</a> int 0
518}
519</pre>
520
521This example is made up of a <a href="#globalvars">global variable</a> named
522"<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, and a
523<a href="#functionstructure">function definition</a> for "<tt>main</tt>".<p>
524
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]525<a name="linkage">
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]526In general, a module is made up of a list of global values, where both functions
527and global variables are global values. Global values are represented by a
528pointer to a memory location (in this case, a pointer to an array of char, and a
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]529pointer to a function), and have one of the following linkage types:<p>
530
531<dl>
532<a name="linkage_internal">
533<dt><tt><b>internal</b></tt>
534
535<dd>Global values with internal linkage are only directly accessible by objects
536in the current module. In particular, linking code into a module with an
537internal global value may cause the internal to be renamed as necessary to avoid
538collisions. Because the symbol is internal to the module, all references can be
539updated. This corresponds to the notion of the '<tt>static</tt>' keyword in C,
540or the idea of "anonymous namespaces" in C++.<p>
541
542<a name="linkage_linkonce">
543<dt><tt><b>linkonce</b></tt>:
544
545<dd>"<tt>linkonce</tt>" linkage is similar to <tt>internal</tt> linkage, with
546the twist that linking together two modules defining the same <tt>linkonce</tt>
547globals will cause one of the globals to be discarded. This is typically used
Chris Lattner25839f02003-10-10 05:01:39 +0000[diff] [blame]548to implement inline functions. Unreferenced <tt>linkonce</tt> globals are
549allowed to be discarded.<p>
550
551<a name="linkage_weak">
552<dt><tt><b>weak</b></tt>:
553
554<dd>"<tt>weak</tt>" linkage is exactly the same as <tt>linkonce</tt> linkage,
555except that unreferenced <tt>weak</tt> globals may not be discarded. This is
556used to implement constructs in C such as "<tt>int X;</tt>" at global scope.<p>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]557
558<a name="linkage_appending">
559<dt><tt><b>appending</b></tt>:
560
561<dd>"<tt>appending</tt>" linkage may only applied to global variables of pointer
562to array type. When two global variables with appending linkage are linked
563together, the two global arrays are appended together. This is the LLVM,
564typesafe, equivalent of having the system linker append together "sections" with
565identical names when .o files are linked.<p>
566
567<a name="linkage_external">
568<dt><tt><b>externally visible</b></tt>:
569
570<dd>If none of the above identifiers are used, the global is externally visible,
571meaning that it participates in linkage and can be used to resolve external
572symbol references.<p>
573
574</dl><p>
575
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]576
577For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
578another module defined a "<tt>.LC0</tt>" variable and was linked with this one,
579one of the two would be renamed, preventing a collision. Since "<tt>main</tt>"
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]580and "<tt>puts</tt>" are external (i.e., lacking any linkage declarations), they
581are accessible outside of the current module. It is illegal for a function
582<i>declaration</i> to have any linkage type other than "externally visible".<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]583
584
585<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]586</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
587<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
588<a name="globalvars">Global Variables
589</b></font></td></tr></table><ul>
590
591Global variables define regions of memory allocated at compilation time instead
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]592of run-time. Global variables may optionally be initialized. A variable may
593be defined as a global "constant", which indicates that the contents of the
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]594variable will never be modified (opening options for optimization). Constants
595must always have an initial value.<p>
596
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]597As SSA values, global variables define pointer values that are in scope
598(i.e. they dominate) for all basic blocks in the program. Global variables
599always define a pointer to their "content" type because they describe a region
600of memory, and all memory objects in LLVM are accessed through pointers.<p>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]601
602
603
604<!-- ======================================================================= -->
605</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
606<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]607<a name="functionstructure">Functions
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]608</b></font></td></tr></table><ul>
609
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]610LLVM functions definitions are composed of a (possibly empty) argument list, an
611opening curly brace, a list of basic blocks, and a closing curly brace. LLVM
612function declarations are defined with the "<tt>declare</tt>" keyword, a
613function name and a function signature.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]614
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]615A function definition contains a list of basic blocks, forming the CFG for the
616function. Each basic block may optionally start with a label (giving the basic
617block a symbol table entry), contains a list of instructions, and ends with a <a
618href="#terminators">terminator</a> instruction (such as a branch or function
619return).<p>
620
621The first basic block in program is special in two ways: it is immediately
622executed on entrance to the function, and it is not allowed to have predecessor
623basic blocks (i.e. there can not be any branches to the entry block of a
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]624function). Because the block can have no predecessors, it also cannot have any
625<a href="#i_phi">PHI nodes</a>.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]626
627
628<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]629</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
630<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]631<a name="instref">Instruction Reference
632</b></font></td></tr></table><ul>
633<!-- *********************************************************************** -->
634
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]635The LLVM instruction set consists of several different classifications of
Chris Lattnere489aa52002-08-14 17:55:59 +0000[diff] [blame]636instructions: <a href="#terminators">terminator instructions</a>, <a
637href="#binaryops">binary instructions</a>, <a href="#memoryops">memory
638instructions</a>, and <a href="#otherops">other instructions</a>.<p>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]639
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]640
641<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]642</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
643<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]644<a name="terminators">Terminator Instructions
645</b></font></td></tr></table><ul>
646
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]647As mentioned <a href="#functionstructure">previously</a>, every basic block in a
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]648program ends with a "Terminator" instruction, which indicates which block should
649be executed after the current block is finished. These terminator instructions
650typically yield a '<tt>void</tt>' value: they produce control flow, not values
651(the one exception being the '<a href="#i_invoke"><tt>invoke</tt></a>'
652instruction).<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]653
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]654There are five different terminator instructions: the '<a
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]655href="#i_ret"><tt>ret</tt></a>' instruction, the '<a
656href="#i_br"><tt>br</tt></a>' instruction, the '<a
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]657href="#i_switch"><tt>switch</tt></a>' instruction, the '<a
658href="#i_invoke"><tt>invoke</tt></a>' instruction, and the '<a
659href="#i_unwind"><tt>unwind</tt></a>' instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]660
661
662<!-- _______________________________________________________________________ -->
663</ul><a name="i_ret"><h4><hr size=0>'<tt>ret</tt>' Instruction</h4><ul>
664
665<h5>Syntax:</h5>
666<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]667 ret &lt;type&gt; &lt;value&gt; <i>; Return a value from a non-void function</i>
668 ret void <i>; Return from void function</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]669</pre>
670
671<h5>Overview:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]672
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]673The '<tt>ret</tt>' instruction is used to return control flow (and a value) from
674a function, back to the caller.<p>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]675
676There are two forms of the '<tt>ret</tt>' instructruction: one that returns a
677value and then causes control flow, and one that just causes control flow to
678occur.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]679
680<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]681
682The '<tt>ret</tt>' instruction may return any '<a href="#t_firstclass">first
683class</a>' type. Notice that a function is not <a href="#wellformed">well
684formed</a> if there exists a '<tt>ret</tt>' instruction inside of the function
685that returns a value that does not match the return type of the function.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]686
687<h5>Semantics:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]688
689When the '<tt>ret</tt>' instruction is executed, control flow returns back to
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]690the calling function's context. If the caller is a "<a
691href="#i_call"><tt>call</tt></a> instruction, execution continues at the
692instruction after the call. If the caller was an "<a
693href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at the
694beginning "normal" of the destination block. If the instruction returns a
695value, that value shall set the call or invoke instruction's return value.<p>
696
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]697
698<h5>Example:</h5>
699<pre>
700 ret int 5 <i>; Return an integer value of 5</i>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]701 ret void <i>; Return from a void function</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]702</pre>
703
704
705<!-- _______________________________________________________________________ -->
706</ul><a name="i_br"><h4><hr size=0>'<tt>br</tt>' Instruction</h4><ul>
707
708<h5>Syntax:</h5>
709<pre>
710 br bool &lt;cond&gt;, label &lt;iftrue&gt;, label &lt;iffalse&gt;
711 br label &lt;dest&gt; <i>; Unconditional branch</i>
712</pre>
713
714<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]715
716The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
717different basic block in the current function. There are two forms of this
718instruction, corresponding to a conditional branch and an unconditional
719branch.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]720
721<h5>Arguments:</h5>
722
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]723The conditional branch form of the '<tt>br</tt>' instruction takes a single
724'<tt>bool</tt>' value and two '<tt>label</tt>' values. The unconditional form
725of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
726target.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]727
728<h5>Semantics:</h5>
729
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]730Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>bool</tt>'
731argument is evaluated. If the value is <tt>true</tt>, control flows to the
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]732'<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>,
733control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]734
735<h5>Example:</h5>
736<pre>
737Test:
738 %cond = <a href="#i_setcc">seteq</a> int %a, %b
739 br bool %cond, label %IfEqual, label %IfUnequal
740IfEqual:
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]741 <a href="#i_ret">ret</a> int 1
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]742IfUnequal:
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]743 <a href="#i_ret">ret</a> int 0
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]744</pre>
745
746
747<!-- _______________________________________________________________________ -->
748</ul><a name="i_switch"><h4><hr size=0>'<tt>switch</tt>' Instruction</h4><ul>
749
750<h5>Syntax:</h5>
751<pre>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]752 switch uint &lt;value&gt;, label &lt;defaultdest&gt; [ int &lt;val&gt;, label &dest&gt;, ... ]
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]753
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]754</pre>
755
756<h5>Overview:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]757
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]758The '<tt>switch</tt>' instruction is used to transfer control flow to one of
759several different places. It is a generalization of the '<tt>br</tt>'
760instruction, allowing a branch to occur to one of many possible destinations.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]761
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]762<h5>Arguments:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]763
Chris Lattnerc29b1252003-05-08 05:08:48 +0000[diff] [blame]764The '<tt>switch</tt>' instruction uses three parameters: a '<tt>uint</tt>'
765comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
766an array of pairs of comparison value constants and '<tt>label</tt>'s.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]767
768<h5>Semantics:</h5>
769
Chris Lattnerc29b1252003-05-08 05:08:48 +0000[diff] [blame]770The <tt>switch</tt> instruction specifies a table of values and destinations.
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]771When the '<tt>switch</tt>' instruction is executed, this table is searched for
772the given value. If the value is found, the corresponding destination is
Chris Lattnerc29b1252003-05-08 05:08:48 +0000[diff] [blame]773branched to, otherwise the default value it transfered to.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]774
Chris Lattnerc29b1252003-05-08 05:08:48 +0000[diff] [blame]775<h5>Implementation:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]776
Chris Lattnerc29b1252003-05-08 05:08:48 +0000[diff] [blame]777Depending on properties of the target machine and the particular <tt>switch</tt>
778instruction, this instruction may be code generated as a series of chained
779conditional branches, or with a lookup table.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]780
781<h5>Example:</h5>
782<pre>
783 <i>; Emulate a conditional br instruction</i>
784 %Val = <a href="#i_cast">cast</a> bool %value to uint
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]785 switch uint %Val, label %truedest [int 0, label %falsedest ]
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]786
787 <i>; Emulate an unconditional br instruction</i>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]788 switch uint 0, label %dest [ ]
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]789
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]790 <i>; Implement a jump table:</i>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]791 switch uint %val, label %otherwise [ int 0, label %onzero,
792 int 1, label %onone,
793 int 2, label %ontwo ]
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]794</pre>
795
796
797
798<!-- _______________________________________________________________________ -->
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]799</ul><a name="i_invoke"><h4><hr size=0>'<tt>invoke</tt>' Instruction</h4><ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]800
801<h5>Syntax:</h5>
802<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]803 &lt;result&gt; = invoke &lt;ptr to function ty&gt; %&lt;function ptr val&gt;(&lt;function args&gt;)
804 to label &lt;normal label&gt; except label &lt;exception label&gt;
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]805</pre>
806
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]807<h5>Overview:</h5>
808
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]809The '<tt>invoke</tt>' instruction causes control to transfer to a specified
810function, with the possibility of control flow transfer to either the
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]811'<tt>normal</tt>' <tt>label</tt> label or the '<tt>exception</tt>'
812<tt>label</tt>. If the callee function returns with the "<tt><a
813href="#i_ret">ret</a></tt>" instruction, control flow will return to the
814"normal" label. If the callee (or any indirect callees) returns with the "<a
815href="#i_unwind"><tt>unwind</tt></a>" instruction, control is interrupted, and
816continued at the dynamically nearest "except" label.<p>
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]817
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]818
819<h5>Arguments:</h5>
820
821This instruction requires several arguments:<p>
822<ol>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]823
824<li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]825function value being invoked. In most cases, this is a direct function
Misha Brukmane6fe6712002-09-18 02:35:14 +0000[diff] [blame]826invocation, but indirect <tt>invoke</tt>s are just as possible, branching off
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]827an arbitrary pointer to function value.
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]828
829<li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
830function to be invoked.
831
832<li>'<tt>function args</tt>': argument list whose types match the function
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]833signature argument types. If the function signature indicates the function
834accepts a variable number of arguments, the extra arguments can be specified.
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]835
836<li>'<tt>normal label</tt>': the label reached when the called function executes
837a '<tt><a href="#i_ret">ret</a></tt>' instruction.
838
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]839<li>'<tt>exception label</tt>': the label reached when a callee returns with the
840<a href="#i_unwind"><tt>unwind</tt></a> instruction.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]841</ol>
842
843<h5>Semantics:</h5>
844
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]845This instruction is designed to operate as a standard '<tt><a
846href="#i_call">call</a></tt>' instruction in most regards. The primary
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]847difference is that it establishes an association with a label, which is used by the runtime library to unwind the stack.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]848
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]849This instruction is used in languages with destructors to ensure that proper
850cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
851exception. Additionally, this is important for implementation of
852'<tt>catch</tt>' clauses in high-level languages that support them.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]853
854<h5>Example:</h5>
855<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]856 %retval = invoke int %Test(int 15)
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]857 to label %Continue
858 except label %TestCleanup <i>; {int}:retval set</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]859</pre>
860
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]861<!-- _______________________________________________________________________ -->
862</ul><a name="i_unwind"><h4><hr size=0>'<tt>unwind</tt>' Instruction</h4><ul>
863
864<h5>Syntax:</h5>
865<pre>
866 unwind
867</pre>
868
869<h5>Overview:</h5>
870
871The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow at
872the first callee in the dynamic call stack which used an <a
873href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. This is
874primarily used to implement exception handling.
875
876<h5>Semantics:</h5>
877
878The '<tt>unwind</tt>' intrinsic causes execution of the current function to
879immediately halt. The dynamic call stack is then searched for the first <a
880href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. Once found,
881execution continues at the "exceptional" destination block specified by the
882<tt>invoke</tt> instruction. If there is no <tt>invoke</tt> instruction in the
883dynamic call chain, undefined behavior results.
884
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]885
886
887<!-- ======================================================================= -->
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]888</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
889<a name="binaryops">Binary Operations
890</b></font></td></tr></table><ul>
891
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]892Binary operators are used to do most of the computation in a program. They
893require two operands, execute an operation on them, and produce a single value.
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]894The result value of a binary operator is not necessarily the same type as its
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]895operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]896
897There are several different binary operators:<p>
898
899
900<!-- _______________________________________________________________________ -->
901</ul><a name="i_add"><h4><hr size=0>'<tt>add</tt>' Instruction</h4><ul>
902
903<h5>Syntax:</h5>
904<pre>
905 &lt;result&gt; = add &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
906</pre>
907
908<h5>Overview:</h5>
909The '<tt>add</tt>' instruction returns the sum of its two operands.<p>
910
911<h5>Arguments:</h5>
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]912The two arguments to the '<tt>add</tt>' instruction must be either <a href="#t_integer">integer</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]913
914<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]915
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]916The value produced is the integer or floating point sum of the two operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]917
918<h5>Example:</h5>
919<pre>
920 &lt;result&gt; = add int 4, %var <i>; yields {int}:result = 4 + %var</i>
921</pre>
922
923
924<!-- _______________________________________________________________________ -->
925</ul><a name="i_sub"><h4><hr size=0>'<tt>sub</tt>' Instruction</h4><ul>
926
927<h5>Syntax:</h5>
928<pre>
929 &lt;result&gt; = sub &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
930</pre>
931
932<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]933
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]934The '<tt>sub</tt>' instruction returns the difference of its two operands.<p>
935
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]936Note that the '<tt>sub</tt>' instruction is used to represent the '<tt>neg</tt>'
937instruction present in most other intermediate representations.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]938
939<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]940
941The two arguments to the '<tt>sub</tt>' instruction must be either <a
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]942href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]943values. Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]944
945<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]946
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]947The value produced is the integer or floating point difference of the two
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]948operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]949
950<h5>Example:</h5>
951<pre>
952 &lt;result&gt; = sub int 4, %var <i>; yields {int}:result = 4 - %var</i>
953 &lt;result&gt; = sub int 0, %val <i>; yields {int}:result = -%var</i>
954</pre>
955
956<!-- _______________________________________________________________________ -->
957</ul><a name="i_mul"><h4><hr size=0>'<tt>mul</tt>' Instruction</h4><ul>
958
959<h5>Syntax:</h5>
960<pre>
961 &lt;result&gt; = mul &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
962</pre>
963
964<h5>Overview:</h5>
965The '<tt>mul</tt>' instruction returns the product of its two operands.<p>
966
967<h5>Arguments:</h5>
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]968The two arguments to the '<tt>mul</tt>' instruction must be either <a href="#t_integer">integer</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]969
970<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]971
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]972The value produced is the integer or floating point product of the two
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]973operands.<p>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]974
975There is no signed vs unsigned multiplication. The appropriate action is taken
976based on the type of the operand. <p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]977
978
979<h5>Example:</h5>
980<pre>
981 &lt;result&gt; = mul int 4, %var <i>; yields {int}:result = 4 * %var</i>
982</pre>
983
984
985<!-- _______________________________________________________________________ -->
986</ul><a name="i_div"><h4><hr size=0>'<tt>div</tt>' Instruction</h4><ul>
987
988<h5>Syntax:</h5>
989<pre>
990 &lt;result&gt; = div &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
991</pre>
992
993<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]994
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]995The '<tt>div</tt>' instruction returns the quotient of its two operands.<p>
996
997<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]998
999The two arguments to the '<tt>div</tt>' instruction must be either <a
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1000href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1001values. Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1002
1003<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1004
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1005The value produced is the integer or floating point quotient of the two
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1006operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1007
1008<h5>Example:</h5>
1009<pre>
1010 &lt;result&gt; = div int 4, %var <i>; yields {int}:result = 4 / %var</i>
1011</pre>
1012
1013
1014<!-- _______________________________________________________________________ -->
1015</ul><a name="i_rem"><h4><hr size=0>'<tt>rem</tt>' Instruction</h4><ul>
1016
1017<h5>Syntax:</h5>
1018<pre>
1019 &lt;result&gt; = rem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1020</pre>
1021
1022<h5>Overview:</h5>
1023The '<tt>rem</tt>' instruction returns the remainder from the division of its two operands.<p>
1024
1025<h5>Arguments:</h5>
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1026The two arguments to the '<tt>rem</tt>' instruction must be either <a href="#t_integer">integer</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1027
1028<h5>Semantics:</h5>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1029
1030This returns the <i>remainder</i> of a division (where the result has the same
1031sign as the divisor), not the <i>modulus</i> (where the result has the same sign
1032as the dividend) of a value. For more information about the difference, see: <a
1033href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The Math
1034Forum</a>.<p>
1035
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1036<h5>Example:</h5>
1037<pre>
1038 &lt;result&gt; = rem int 4, %var <i>; yields {int}:result = 4 % %var</i>
1039</pre>
1040
1041
1042<!-- _______________________________________________________________________ -->
1043</ul><a name="i_setcc"><h4><hr size=0>'<tt>set<i>cc</i></tt>' Instructions</h4><ul>
1044
1045<h5>Syntax:</h5>
1046<pre>
1047 &lt;result&gt; = seteq &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1048 &lt;result&gt; = setne &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1049 &lt;result&gt; = setlt &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1050 &lt;result&gt; = setgt &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1051 &lt;result&gt; = setle &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1052 &lt;result&gt; = setge &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1053</pre>
1054
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1055<h5>Overview:</h5> The '<tt>set<i>cc</i></tt>' family of instructions returns a
1056boolean value based on a comparison of their two operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1057
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1058<h5>Arguments:</h5> The two arguments to the '<tt>set<i>cc</i></tt>'
Chris Lattner478921b2003-10-30 01:31:37 +0000[diff] [blame]1059instructions must be of <a href="#t_firstclass">first class</a> type (it is not
1060possible to compare '<tt>label</tt>'s, '<tt>array</tt>'s, '<tt>structure</tt>'
1061or '<tt>void</tt>' values, etc...). Both arguments must have identical
1062types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1063
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1064<h5>Semantics:</h5>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1065
1066The '<tt>seteq</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1067both operands are equal.<br>
1068
1069The '<tt>setne</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1070both operands are unequal.<br>
1071
1072The '<tt>setlt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1073the first operand is less than the second operand.<br>
1074
1075The '<tt>setgt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1076the first operand is greater than the second operand.<br>
1077
1078The '<tt>setle</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1079the first operand is less than or equal to the second operand.<br>
1080
1081The '<tt>setge</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1082the first operand is greater than or equal to the second operand.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1083
1084<h5>Example:</h5>
1085<pre>
1086 &lt;result&gt; = seteq int 4, 5 <i>; yields {bool}:result = false</i>
1087 &lt;result&gt; = setne float 4, 5 <i>; yields {bool}:result = true</i>
1088 &lt;result&gt; = setlt uint 4, 5 <i>; yields {bool}:result = true</i>
1089 &lt;result&gt; = setgt sbyte 4, 5 <i>; yields {bool}:result = false</i>
1090 &lt;result&gt; = setle sbyte 4, 5 <i>; yields {bool}:result = true</i>
1091 &lt;result&gt; = setge sbyte 4, 5 <i>; yields {bool}:result = false</i>
1092</pre>
1093
1094
1095
1096<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1097</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1098<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1099<a name="bitwiseops">Bitwise Binary Operations
1100</b></font></td></tr></table><ul>
1101
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1102Bitwise binary operators are used to do various forms of bit-twiddling in a
1103program. They are generally very efficient instructions, and can commonly be
1104strength reduced from other instructions. They require two operands, execute an
1105operation on them, and produce a single value. The resulting value of the
1106bitwise binary operators is always the same type as its first operand.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1107
1108<!-- _______________________________________________________________________ -->
1109</ul><a name="i_and"><h4><hr size=0>'<tt>and</tt>' Instruction</h4><ul>
1110
1111<h5>Syntax:</h5>
1112<pre>
1113 &lt;result&gt; = and &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1114</pre>
1115
1116<h5>Overview:</h5>
1117The '<tt>and</tt>' instruction returns the bitwise logical and of its two operands.<p>
1118
1119<h5>Arguments:</h5>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1120
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1121The two arguments to the '<tt>and</tt>' instruction must be <a
1122href="#t_integral">integral</a> values. Both arguments must have identical
1123types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1124
1125
1126<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1127
1128The truth table used for the '<tt>and</tt>' instruction is:<p>
1129
Chris Lattnerc98cbbc2002-06-25 18:06:50 +0000[diff] [blame]1130<center><table border=1 cellspacing=0 cellpadding=4>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1131<tr><td>In0</td> <td>In1</td> <td>Out</td></tr>
1132<tr><td>0</td> <td>0</td> <td>0</td></tr>
1133<tr><td>0</td> <td>1</td> <td>0</td></tr>
1134<tr><td>1</td> <td>0</td> <td>0</td></tr>
1135<tr><td>1</td> <td>1</td> <td>1</td></tr>
1136</table></center><p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1137
1138
1139<h5>Example:</h5>
1140<pre>
1141 &lt;result&gt; = and int 4, %var <i>; yields {int}:result = 4 & %var</i>
1142 &lt;result&gt; = and int 15, 40 <i>; yields {int}:result = 8</i>
1143 &lt;result&gt; = and int 4, 8 <i>; yields {int}:result = 0</i>
1144</pre>
1145
1146
1147
1148<!-- _______________________________________________________________________ -->
1149</ul><a name="i_or"><h4><hr size=0>'<tt>or</tt>' Instruction</h4><ul>
1150
1151<h5>Syntax:</h5>
1152<pre>
1153 &lt;result&gt; = or &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1154</pre>
1155
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1156<h5>Overview:</h5> The '<tt>or</tt>' instruction returns the bitwise logical
1157inclusive or of its two operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1158
1159<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1160
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1161The two arguments to the '<tt>or</tt>' instruction must be <a
1162href="#t_integral">integral</a> values. Both arguments must have identical
1163types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1164
1165
1166<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1167
1168The truth table used for the '<tt>or</tt>' instruction is:<p>
1169
Chris Lattnerc98cbbc2002-06-25 18:06:50 +0000[diff] [blame]1170<center><table border=1 cellspacing=0 cellpadding=4>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1171<tr><td>In0</td> <td>In1</td> <td>Out</td></tr>
1172<tr><td>0</td> <td>0</td> <td>0</td></tr>
1173<tr><td>0</td> <td>1</td> <td>1</td></tr>
1174<tr><td>1</td> <td>0</td> <td>1</td></tr>
1175<tr><td>1</td> <td>1</td> <td>1</td></tr>
1176</table></center><p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1177
1178
1179<h5>Example:</h5>
1180<pre>
1181 &lt;result&gt; = or int 4, %var <i>; yields {int}:result = 4 | %var</i>
1182 &lt;result&gt; = or int 15, 40 <i>; yields {int}:result = 47</i>
1183 &lt;result&gt; = or int 4, 8 <i>; yields {int}:result = 12</i>
1184</pre>
1185
1186
1187<!-- _______________________________________________________________________ -->
1188</ul><a name="i_xor"><h4><hr size=0>'<tt>xor</tt>' Instruction</h4><ul>
1189
1190<h5>Syntax:</h5>
1191<pre>
1192 &lt;result&gt; = xor &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1193</pre>
1194
1195<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1196
1197The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of its
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1198two operands. The <tt>xor</tt> is used to implement the "one's complement"
1199operation, which is the "~" operator in C.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1200
1201<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1202
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1203The two arguments to the '<tt>xor</tt>' instruction must be <a
1204href="#t_integral">integral</a> values. Both arguments must have identical
1205types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1206
1207
1208<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1209
1210The truth table used for the '<tt>xor</tt>' instruction is:<p>
1211
Chris Lattnerc98cbbc2002-06-25 18:06:50 +0000[diff] [blame]1212<center><table border=1 cellspacing=0 cellpadding=4>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1213<tr><td>In0</td> <td>In1</td> <td>Out</td></tr>
1214<tr><td>0</td> <td>0</td> <td>0</td></tr>
1215<tr><td>0</td> <td>1</td> <td>1</td></tr>
1216<tr><td>1</td> <td>0</td> <td>1</td></tr>
1217<tr><td>1</td> <td>1</td> <td>0</td></tr>
1218</table></center><p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1219
1220
1221<h5>Example:</h5>
1222<pre>
1223 &lt;result&gt; = xor int 4, %var <i>; yields {int}:result = 4 ^ %var</i>
1224 &lt;result&gt; = xor int 15, 40 <i>; yields {int}:result = 39</i>
1225 &lt;result&gt; = xor int 4, 8 <i>; yields {int}:result = 12</i>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1226 &lt;result&gt; = xor int %V, -1 <i>; yields {int}:result = ~%V</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1227</pre>
1228
1229
1230<!-- _______________________________________________________________________ -->
1231</ul><a name="i_shl"><h4><hr size=0>'<tt>shl</tt>' Instruction</h4><ul>
1232
1233<h5>Syntax:</h5>
1234<pre>
1235 &lt;result&gt; = shl &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt; <i>; yields {ty}:result</i>
1236</pre>
1237
1238<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1239
1240The '<tt>shl</tt>' instruction returns the first operand shifted to the left a
1241specified number of bits.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1242
1243<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1244
1245The first argument to the '<tt>shl</tt>' instruction must be an <a
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1246href="#t_integer">integer</a> type. The second argument must be an
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1247'<tt>ubyte</tt>' type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1248
1249<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1250
1251The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1252
1253
1254<h5>Example:</h5>
1255<pre>
1256 &lt;result&gt; = shl int 4, ubyte %var <i>; yields {int}:result = 4 << %var</i>
1257 &lt;result&gt; = shl int 4, ubyte 2 <i>; yields {int}:result = 16</i>
1258 &lt;result&gt; = shl int 1, ubyte 10 <i>; yields {int}:result = 1024</i>
1259</pre>
1260
1261
1262<!-- _______________________________________________________________________ -->
1263</ul><a name="i_shr"><h4><hr size=0>'<tt>shr</tt>' Instruction</h4><ul>
1264
1265
1266<h5>Syntax:</h5>
1267<pre>
1268 &lt;result&gt; = shr &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt; <i>; yields {ty}:result</i>
1269</pre>
1270
1271<h5>Overview:</h5>
1272The '<tt>shr</tt>' instruction returns the first operand shifted to the right a specified number of bits.
1273
1274<h5>Arguments:</h5>
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1275The 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>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1276
1277<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1278
1279If the first argument is a <a href="#t_signed">signed</a> type, the most
1280significant bit is duplicated in the newly free'd bit positions. If the first
1281argument is unsigned, zero bits shall fill the empty positions.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1282
1283<h5>Example:</h5>
1284<pre>
1285 &lt;result&gt; = shr int 4, ubyte %var <i>; yields {int}:result = 4 >> %var</i>
Chris Lattner8c6bb902003-06-18 21:30:51 +0000[diff] [blame]1286 &lt;result&gt; = shr uint 4, ubyte 1 <i>; yields {uint}:result = 2</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1287 &lt;result&gt; = shr int 4, ubyte 2 <i>; yields {int}:result = 1</i>
Chris Lattner8c6bb902003-06-18 21:30:51 +0000[diff] [blame]1288 &lt;result&gt; = shr sbyte 4, ubyte 3 <i>; yields {sbyte}:result = 0</i>
1289 &lt;result&gt; = shr sbyte -2, ubyte 1 <i>; yields {sbyte}:result = -1</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1290</pre>
1291
1292
1293
1294
1295
1296<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1297</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1298<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1299<a name="memoryops">Memory Access Operations
1300</b></font></td></tr></table><ul>
1301
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1302A key design point of an SSA-based representation is how it represents memory.
1303In LLVM, no memory locations are in SSA form, which makes things very simple.
1304This section describes how to read, write, allocate and free memory in LLVM.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1305
1306
1307<!-- _______________________________________________________________________ -->
1308</ul><a name="i_malloc"><h4><hr size=0>'<tt>malloc</tt>' Instruction</h4><ul>
1309
1310<h5>Syntax:</h5>
1311<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1312 &lt;result&gt; = malloc &lt;type&gt;, uint &lt;NumElements&gt; <i>; yields {type*}:result</i>
1313 &lt;result&gt; = malloc &lt;type&gt; <i>; yields {type*}:result</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1314</pre>
1315
1316<h5>Overview:</h5>
1317The '<tt>malloc</tt>' instruction allocates memory from the system heap and returns a pointer to it.<p>
1318
1319<h5>Arguments:</h5>
1320
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1321The the '<tt>malloc</tt>' instruction allocates
1322<tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory from the operating
1323system, and returns a pointer of the appropriate type to the program. The
1324second form of the instruction is a shorter version of the first instruction
1325that defaults to allocating one element.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1326
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1327'<tt>type</tt>' must be a sized type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1328
1329<h5>Semantics:</h5>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1330
1331Memory is allocated using the system "<tt>malloc</tt>" function, and a pointer
1332is returned.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1333
1334<h5>Example:</h5>
1335<pre>
1336 %array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
1337
1338 %size = <a href="#i_add">add</a> uint 2, 2 <i>; yields {uint}:size = uint 4</i>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1339 %array1 = malloc ubyte, uint 4 <i>; yields {ubyte*}:array1</i>
1340 %array2 = malloc [12 x ubyte], uint %size <i>; yields {[12 x ubyte]*}:array2</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1341</pre>
1342
1343
1344<!-- _______________________________________________________________________ -->
1345</ul><a name="i_free"><h4><hr size=0>'<tt>free</tt>' Instruction</h4><ul>
1346
1347<h5>Syntax:</h5>
1348<pre>
1349 free &lt;type&gt; &lt;value&gt; <i>; yields {void}</i>
1350</pre>
1351
1352
1353<h5>Overview:</h5>
1354The '<tt>free</tt>' instruction returns memory back to the unused memory heap, to be reallocated in the future.<p>
1355
1356
1357<h5>Arguments:</h5>
1358
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1359'<tt>value</tt>' shall be a pointer value that points to a value that was
1360allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1361
1362
1363<h5>Semantics:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1364
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1365Access to the memory pointed to by the pointer is not longer defined after this instruction executes.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1366
1367<h5>Example:</h5>
1368<pre>
1369 %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
1370 free [4 x ubyte]* %array
1371</pre>
1372
1373
1374<!-- _______________________________________________________________________ -->
1375</ul><a name="i_alloca"><h4><hr size=0>'<tt>alloca</tt>' Instruction</h4><ul>
1376
1377<h5>Syntax:</h5>
1378<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1379 &lt;result&gt; = alloca &lt;type&gt;, uint &lt;NumElements&gt; <i>; yields {type*}:result</i>
1380 &lt;result&gt; = alloca &lt;type&gt; <i>; yields {type*}:result</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1381</pre>
1382
1383<h5>Overview:</h5>
1384
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1385The '<tt>alloca</tt>' instruction allocates memory on the current stack frame of
1386the procedure that is live until the current function returns to its caller.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1387
1388<h5>Arguments:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1389
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1390The the '<tt>alloca</tt>' instruction allocates
1391<tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory on the runtime stack,
1392returning a pointer of the appropriate type to the program. The second form of
1393the instruction is a shorter version of the first that defaults to allocating
1394one element.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1395
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1396'<tt>type</tt>' may be any sized type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1397
1398<h5>Semantics:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1399
1400Memory is allocated, a pointer is returned. '<tt>alloca</tt>'d memory is
1401automatically released when the function returns. The '<tt>alloca</tt>'
1402instruction is commonly used to represent automatic variables that must have an
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1403address available. When the function returns (either with the <tt><a
1404href="#i_ret">ret</a></tt> or <tt><a href="#i_invoke">invoke</a></tt>
1405instructions), the memory is reclaimed.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1406
1407<h5>Example:</h5>
1408<pre>
1409 %ptr = alloca int <i>; yields {int*}:ptr</i>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1410 %ptr = alloca int, uint 4 <i>; yields {int*}:ptr</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1411</pre>
1412
1413
1414<!-- _______________________________________________________________________ -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1415</ul><a name="i_load"><h4><hr size=0>'<tt>load</tt>' Instruction</h4><ul>
1416
1417<h5>Syntax:</h5>
1418<pre>
1419 &lt;result&gt; = load &lt;ty&gt;* &lt;pointer&gt;
Chris Lattnerf0651072003-09-08 18:27:49 +0000[diff] [blame]1420 &lt;result&gt; = volatile load &lt;ty&gt;* &lt;pointer&gt;
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1421</pre>
1422
1423<h5>Overview:</h5>
1424The '<tt>load</tt>' instruction is used to read from memory.<p>
1425
1426<h5>Arguments:</h5>
1427
Chris Lattnerf0651072003-09-08 18:27:49 +0000[diff] [blame]1428The argument to the '<tt>load</tt>' instruction specifies the memory address to
1429load from. The pointer must point to a <a href="t_firstclass">first class</a>
1430type. If the <tt>load</tt> is marked as <tt>volatile</tt> then the optimizer is
1431not allowed to modify the number or order of execution of this <tt>load</tt>
1432with other volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
1433instructions. <p>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1434
1435<h5>Semantics:</h5>
1436
1437The location of memory pointed to is loaded.
1438
1439<h5>Examples:</h5>
1440<pre>
1441 %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
1442 <a href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
1443 %val = load int* %ptr <i>; yields {int}:val = int 3</i>
1444</pre>
1445
1446
1447
1448
1449<!-- _______________________________________________________________________ -->
1450</ul><a name="i_store"><h4><hr size=0>'<tt>store</tt>' Instruction</h4><ul>
1451
1452<h5>Syntax:</h5>
1453<pre>
1454 store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt; <i>; yields {void}</i>
Chris Lattnerf0651072003-09-08 18:27:49 +0000[diff] [blame]1455 volatile store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt; <i>; yields {void}</i>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1456</pre>
1457
1458<h5>Overview:</h5>
1459The '<tt>store</tt>' instruction is used to write to memory.<p>
1460
1461<h5>Arguments:</h5>
1462
1463There are two arguments to the '<tt>store</tt>' instruction: a value to store
1464and an address to store it into. The type of the '<tt>&lt;pointer&gt;</tt>'
Chris Lattnerf0651072003-09-08 18:27:49 +0000[diff] [blame]1465operand must be a pointer to the type of the '<tt>&lt;value&gt;</tt>' operand.
1466If the <tt>store</tt> is marked as <tt>volatile</tt> then the optimizer is not
1467allowed to modify the number or order of execution of this <tt>store</tt> with
1468other volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
1469instructions.<p>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1470
1471<h5>Semantics:</h5> The contents of memory are updated to contain
1472'<tt>&lt;value&gt;</tt>' at the location specified by the
1473'<tt>&lt;pointer&gt;</tt>' operand.<p>
1474
1475<h5>Example:</h5>
1476<pre>
1477 %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
1478 <a href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
1479 %val = load int* %ptr <i>; yields {int}:val = int 3</i>
1480</pre>
1481
1482
1483
1484
1485<!-- _______________________________________________________________________ -->
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1486</ul><a name="i_getelementptr"><h4><hr size=0>'<tt>getelementptr</tt>' Instruction</h4><ul>
1487
1488<h5>Syntax:</h5>
1489<pre>
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1490 &lt;result&gt; = getelementptr &lt;ty&gt;* &lt;ptrval&gt;{, long &lt;aidx&gt;|, ubyte &lt;sidx&gt;}*
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1491</pre>
1492
1493<h5>Overview:</h5>
1494
1495The '<tt>getelementptr</tt>' instruction is used to get the address of a
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1496subelement of an aggregate data structure.<p>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1497
1498<h5>Arguments:</h5>
1499
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1500This instruction takes a list of <tt>long</tt> values and <tt>ubyte</tt>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1501constants that indicate what form of addressing to perform. The actual types of
1502the arguments provided depend on the type of the first pointer argument. The
1503'<tt>getelementptr</tt>' instruction is used to index down through the type
1504levels of a structure.<p>
1505
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1506For example, lets consider a C code fragment and how it gets compiled to
1507LLVM:<p>
1508
1509<pre>
1510struct RT {
1511 char A;
1512 int B[10][20];
1513 char C;
1514};
1515struct ST {
1516 int X;
1517 double Y;
1518 struct RT Z;
1519};
1520
1521int *foo(struct ST *s) {
1522 return &amp;s[1].Z.B[5][13];
1523}
1524</pre>
1525
1526The LLVM code generated by the GCC frontend is:
1527
1528<pre>
1529%RT = type { sbyte, [10 x [20 x int]], sbyte }
1530%ST = type { int, double, %RT }
1531
1532int* "foo"(%ST* %s) {
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1533 %reg = getelementptr %ST* %s, long 1, ubyte 2, ubyte 1, long 5, long 13
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1534 ret int* %reg
1535}
1536</pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1537
1538<h5>Semantics:</h5>
1539
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1540The index types specified for the '<tt>getelementptr</tt>' instruction depend on
1541the pointer type that is being index into. <a href="t_pointer">Pointer</a> and
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1542<a href="t_array">array</a> types require '<tt>long</tt>' values, and <a
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1543href="t_struct">structure</a> types require '<tt>ubyte</tt>'
1544<b>constants</b>.<p>
1545
1546In the example above, the first index is indexing into the '<tt>%ST*</tt>' type,
1547which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ int, double, %RT }</tt>'
1548type, a structure. The second index indexes into the third element of the
1549structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]], sbyte
1550}</tt>' type, another structure. The third index indexes into the second
1551element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
1552array. The two dimensions of the array are subscripted into, yielding an
1553'<tt>int</tt>' type. The '<tt>getelementptr</tt>' instruction return a pointer
1554to this element, thus yielding a '<tt>int*</tt>' type.<p>
1555
1556Note that it is perfectly legal to index partially through a structure,
1557returning a pointer to an inner element. Because of this, the LLVM code for the
1558given testcase is equivalent to:<p>
1559
1560<pre>
1561int* "foo"(%ST* %s) {
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1562 %t1 = getelementptr %ST* %s , long 1 <i>; yields %ST*:%t1</i>
1563 %t2 = getelementptr %ST* %t1, long 0, ubyte 2 <i>; yields %RT*:%t2</i>
1564 %t3 = getelementptr %RT* %t2, long 0, ubyte 1 <i>; yields [10 x [20 x int]]*:%t3</i>
1565 %t4 = getelementptr [10 x [20 x int]]* %t3, long 0, long 5 <i>; yields [20 x int]*:%t4</i>
1566 %t5 = getelementptr [20 x int]* %t4, long 0, long 13 <i>; yields int*:%t5</i>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1567 ret int* %t5
1568}
1569</pre>
1570
1571
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1572
1573<h5>Example:</h5>
1574<pre>
Chris Lattnerf31860b2002-08-19 21:14:38 +0000[diff] [blame]1575 <i>; yields [12 x ubyte]*:aptr</i>
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1576 %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, ubyte 1
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1577</pre>
1578
1579
1580
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1581<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1582</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1583<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1584<a name="otherops">Other Operations
1585</b></font></td></tr></table><ul>
1586
Chris Lattner43c2eb72003-09-03 04:20:13 +0000[diff] [blame]1587The instructions in this catagory are the "miscellaneous" instructions, which defy better classification.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1588
1589
1590<!-- _______________________________________________________________________ -->
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1591</ul><a name="i_phi"><h4><hr size=0>'<tt>phi</tt>' Instruction</h4><ul>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1592
1593<h5>Syntax:</h5>
1594<pre>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1595 &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1596</pre>
1597
1598<h5>Overview:</h5>
1599
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1600The '<tt>phi</tt>' instruction is used to implement the &phi; node in the SSA
1601graph representing the function.<p>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1602
1603<h5>Arguments:</h5>
1604
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1605The type of the incoming values are specified with the first type field. After
1606this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with
Chris Lattner478921b2003-10-30 01:31:37 +0000[diff] [blame]1607one pair for each predecessor basic block of the current block. Only values of
1608<a href="#t_firstclass">first class</a> type may be used as the value arguments
1609to the PHI node. Only labels be used as the label arguments.<p>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1610
1611There must be no non-phi instructions between the start of a basic block and the
1612PHI instructions: i.e. PHI instructions must be first in a basic block.<p>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1613
1614<h5>Semantics:</h5>
1615
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1616At runtime, the '<tt>phi</tt>' instruction logically takes on the value
1617specified by the parameter, depending on which basic block we came from in the
1618last <a href="#terminators">terminator</a> instruction.<p>
1619
1620<h5>Example:</h5>
1621
1622<pre>
1623Loop: ; Infinite loop that counts from 0 on up...
1624 %indvar = phi uint [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
1625 %nextindvar = add uint %indvar, 1
1626 br label %Loop
1627</pre>
1628
1629
1630<!-- _______________________________________________________________________ -->
1631</ul><a name="i_cast"><h4><hr size=0>'<tt>cast .. to</tt>' Instruction</h4><ul>
1632
1633<h5>Syntax:</h5>
1634<pre>
1635 &lt;result&gt; = cast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt; <i>; yields ty2</i>
1636</pre>
1637
1638<h5>Overview:</h5>
1639
1640The '<tt>cast</tt>' instruction is used as the primitive means to convert
1641integers to floating point, change data type sizes, and break type safety (by
1642casting pointers).<p>
1643
1644<h5>Arguments:</h5>
1645
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1646The '<tt>cast</tt>' instruction takes a value to cast, which must be a first
Chris Lattner478921b2003-10-30 01:31:37 +0000[diff] [blame]1647class value, and a type to cast it to, which must also be a <a
1648href="#t_firstclass">first class</a> type.<p>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1649
1650<h5>Semantics:</h5>
1651
1652This instruction follows the C rules for explicit casts when determining how the
1653data being cast must change to fit in its new container.<p>
1654
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1655When casting to bool, any value that would be considered true in the context of
1656a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>' values,
1657all else are '<tt>false</tt>'.<p>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1658
Chris Lattnerf8856bc2002-08-13 20:52:09 +0000[diff] [blame]1659When extending an integral value from a type of one signness to another (for
1660example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
1661<b>source</b> value is signed, and zero-extended if the source value is
Chris Lattner2b4dcbb2002-08-15 19:36:05 +0000[diff] [blame]1662unsigned. <tt>bool</tt> values are always zero extended into either zero or
1663one.<p>
Chris Lattnerf8856bc2002-08-13 20:52:09 +0000[diff] [blame]1664
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1665<h5>Example:</h5>
1666<pre>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1667 %X = cast int 257 to ubyte <i>; yields ubyte:1</i>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1668 %Y = cast int 123 to bool <i>; yields bool:true</i>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1669</pre>
1670
1671
1672
1673<!-- _______________________________________________________________________ -->
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1674</ul><a name="i_call"><h4><hr size=0>'<tt>call</tt>' Instruction</h4><ul>
1675
1676<h5>Syntax:</h5>
1677<pre>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1678 &lt;result&gt; = call &lt;ty&gt;* &lt;fnptrval&gt;(&lt;param list&gt;)
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1679</pre>
1680
1681<h5>Overview:</h5>
1682
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1683The '<tt>call</tt>' instruction represents a simple function call.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1684
1685<h5>Arguments:</h5>
1686
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1687This instruction requires several arguments:<p>
1688<ol>
1689
1690<li>'<tt>ty</tt>': shall be the signature of the pointer to function value being
1691invoked. The argument types must match the types implied by this signature.<p>
1692
1693<li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to be
1694invoked. In most cases, this is a direct function invocation, but indirect
Misha Brukmane6fe6712002-09-18 02:35:14 +0000[diff] [blame]1695<tt>call</tt>s are just as possible, calling an arbitrary pointer to function
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1696values.<p>
1697
1698<li>'<tt>function args</tt>': argument list whose types match the function
1699signature argument types. If the function signature indicates the function
1700accepts a variable number of arguments, the extra arguments can be specified.
1701</ol>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1702
1703<h5>Semantics:</h5>
1704
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1705The '<tt>call</tt>' instruction is used to cause control flow to transfer to a
1706specified function, with its incoming arguments bound to the specified values.
1707Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called function,
1708control flow continues with the instruction after the function call, and the
1709return value of the function is bound to the result argument. This is a simpler
1710case of the <a href="#i_invoke">invoke</a> instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1711
1712<h5>Example:</h5>
1713<pre>
1714 %retval = call int %test(int %argc)
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1715 call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);
1716
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1717</pre>
1718
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1719<!-- _______________________________________________________________________ -->
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1720</ul><a name="i_vanext"><h4><hr size=0>'<tt>vanext</tt>' Instruction</h4><ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1721
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1722<h5>Syntax:</h5>
1723<pre>
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1724 &lt;resultarglist&gt; = vanext &lt;va_list&gt; &lt;arglist&gt;, &lt;argty&gt;
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1725</pre>
1726
1727<h5>Overview:</h5>
1728
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1729The '<tt>vanext</tt>' instruction is used to access arguments passed through
1730the "variable argument" area of a function call. It is used to implement the
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1731<tt>va_arg</tt> macro in C.<p>
1732
1733<h5>Arguments:</h5>
1734
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1735This instruction takes a <tt>valist</tt> value and the type of the argument. It
1736returns another <tt>valist</tt>.
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1737
1738<h5>Semantics:</h5>
1739
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1740The '<tt>vanext</tt>' instruction advances the specified <tt>valist</tt> past
1741an argument of the specified type. In conjunction with the <a
1742href="#i_vaarg"><tt>vaarg</tt></a> instruction, it is used to implement the
1743<tt>va_arg</tt> macro available in C. For more information, see the variable
1744argument handling <a href="#int_varargs">Intrinsic Functions</a>.<p>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1745
1746It is legal for this instruction to be called in a function which does not take
1747a variable number of arguments, for example, the <tt>vfprintf</tt> function.<p>
1748
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1749<tt>vanext</tt> is an LLVM instruction instead of an <a
1750href="#intrinsics">intrinsic function</a> because it takes an type as an
1751argument.</p>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1752
1753<h5>Example:</h5>
1754
1755See the <a href="#int_varargs">variable argument processing</a> section.<p>
1756
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1757
1758
1759<!-- _______________________________________________________________________ -->
1760</ul><a name="i_vaarg"><h4><hr size=0>'<tt>vaarg</tt>' Instruction</h4><ul>
1761
1762<h5>Syntax:</h5>
1763<pre>
1764 &lt;resultval&gt; = vaarg &lt;va_list&gt; &lt;arglist&gt;, &lt;argty&gt;
1765</pre>
1766
1767<h5>Overview:</h5>
1768
1769The '<tt>vaarg</tt>' instruction is used to access arguments passed through
1770the "variable argument" area of a function call. It is used to implement the
1771<tt>va_arg</tt> macro in C.<p>
1772
1773<h5>Arguments:</h5>
1774
1775This instruction takes a <tt>valist</tt> value and the type of the argument. It
1776returns a value of the specified argument type.
1777
1778<h5>Semantics:</h5>
1779
1780The '<tt>vaarg</tt>' instruction loads an argument of the specified type from
1781the specified <tt>va_list</tt>. In conjunction with the <a
1782href="#i_vanext"><tt>vanext</tt></a> instruction, it is used to implement the
1783<tt>va_arg</tt> macro available in C. For more information, see the variable
1784argument handling <a href="#int_varargs">Intrinsic Functions</a>.<p>
1785
1786It is legal for this instruction to be called in a function which does not take
1787a variable number of arguments, for example, the <tt>vfprintf</tt> function.<p>
1788
1789<tt>vaarg</tt> is an LLVM instruction instead of an <a
1790href="#intrinsics">intrinsic function</a> because it takes an type as an
1791argument.</p>
1792
1793<h5>Example:</h5>
1794
1795See the <a href="#int_varargs">variable argument processing</a> section.<p>
1796
1797
1798
1799
1800
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1801<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1802</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
1803<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1804<a name="intrinsics">Intrinsic Functions
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1805</b></font></td></tr></table><ul>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1806<!-- *********************************************************************** -->
1807
1808LLVM supports the notion of an "intrinsic function". These functions have well
1809known names and semantics, and are required to follow certain restrictions.
1810Overall, these instructions represent an extension mechanism for the LLVM
1811language that does not require changing all of the transformations in LLVM to
1812add to the language (or the bytecode reader/writer, the parser, etc...).<p>
1813
1814Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix, this
1815prefix is reserved in LLVM for intrinsic names, thus functions may not be named
1816this. Intrinsic functions must always be external functions: you cannot define
1817the body of intrinsic functions. Intrinsic functions may only be used in call
1818or invoke instructions: it is illegal to take the address of an intrinsic
1819function. Additionally, because intrinsic functions are part of the LLVM
1820language, it is required that they all be documented here if any are added.<p>
1821
1822Unless an intrinsic function is target-specific, there must be a lowering pass
1823to eliminate the intrinsic or all backends must support the intrinsic
1824function.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1825
1826
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1827<!-- ======================================================================= -->
1828</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1829<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
1830<a name="int_varargs">Variable Argument Handling Intrinsics
1831</b></font></td></tr></table><ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1832
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1833Variable argument support is defined in LLVM with the <a
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1834href="#i_vanext"><tt>vanext</tt></a> instruction and these three intrinsic
1835functions. These functions are related to the similarly named macros defined in
1836the <tt>&lt;stdarg.h&gt;</tt> header file.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1837
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1838All of these functions operate on arguments that use a target-specific value
1839type "<tt>va_list</tt>". The LLVM assembly language reference manual does not
1840define what this type is, so all transformations should be prepared to handle
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1841intrinsics with any type used.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1842
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1843This example shows how the <a href="#i_vanext"><tt>vanext</tt></a> instruction
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1844and the variable argument handling intrinsic functions are used.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1845
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1846<pre>
1847int %test(int %X, ...) {
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1848 ; Initialize variable argument processing
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1849 %ap = call sbyte*()* %<a href="#i_va_start">llvm.va_start</a>()
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1850
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1851 ; Read a single integer argument
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1852 %tmp = vaarg sbyte* %ap, int
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1853
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1854 ; Advance to the next argument
1855 %ap2 = vanext sbyte* %ap, int
1856
1857 ; Demonstrate usage of llvm.va_copy and llvm.va_end
1858 %aq = call sbyte* (sbyte*)* %<a href="#i_va_copy">llvm.va_copy</a>(sbyte* %ap2)
1859 call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %aq)
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1860
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1861 ; Stop processing of arguments.
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1862 call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %ap2)
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1863 ret int %tmp
1864}
1865</pre>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1866
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1867<!-- _______________________________________________________________________ -->
1868</ul><a name="i_va_start"><h4><hr size=0>'<tt>llvm.va_start</tt>' Intrinsic</h4><ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1869
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1870<h5>Syntax:</h5>
1871<pre>
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1872 call va_list ()* %llvm.va_start()
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1873</pre>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1874
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1875<h5>Overview:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1876
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1877The '<tt>llvm.va_start</tt>' intrinsic returns a new <tt>&lt;arglist&gt;</tt>
1878for subsequent use by the variable argument intrinsics.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1879
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1880<h5>Semantics:</h5>
1881
1882The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1883macro available in C. In a target-dependent way, it initializes and returns a
1884<tt>va_list</tt> element, so that the next <tt>vaarg</tt> will produce the first
1885variable argument passed to the function. Unlike the C <tt>va_start</tt> macro,
1886this intrinsic does not need to know the last argument of the function, the
1887compiler can figure that out.<p>
1888
1889Note that this intrinsic function is only legal to be called from within the
1890body of a variable argument function.<p>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1891
1892
1893<!-- _______________________________________________________________________ -->
1894</ul><a name="i_va_end"><h4><hr size=0>'<tt>llvm.va_end</tt>' Intrinsic</h4><ul>
1895
1896<h5>Syntax:</h5>
1897<pre>
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1898 call void (va_list)* %llvm.va_end(va_list &lt;arglist&gt;)
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1899</pre>
1900
1901<h5>Overview:</h5>
1902
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1903The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>&lt;arglist&gt;</tt> which has
1904been initialized previously with <tt><a
Chris Lattner2c1bbd82003-10-21 15:43:55 +0000[diff] [blame]1905href="#i_va_start">llvm.va_start</a></tt> or <tt><a
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1906href="#i_va_copy">llvm.va_copy</a></tt>.<p>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1907
1908<h5>Arguments:</h5>
1909
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1910The argument is a <tt>va_list</tt> to destroy.<p>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1911
1912<h5>Semantics:</h5>
1913
1914The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt> macro
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1915available in C. In a target-dependent way, it destroys the <tt>va_list</tt>.
1916Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1917href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly with calls
1918to <tt>llvm.va_end</tt>.<p>
1919
1920
1921
1922<!-- _______________________________________________________________________ -->
1923</ul><a name="i_va_copy"><h4><hr size=0>'<tt>llvm.va_copy</tt>' Intrinsic</h4><ul>
1924
1925<h5>Syntax:</h5>
1926<pre>
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1927 call va_list (va_list)* %llvm.va_copy(va_list &lt;destarglist&gt;)
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1928</pre>
1929
1930<h5>Overview:</h5>
1931
1932The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position from
1933the source argument list to the destination argument list.<p>
1934
1935<h5>Arguments:</h5>
1936
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1937The argument is the <tt>va_list</tt> to copy.
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1938
1939<h5>Semantics:</h5>
1940
1941The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> macro
1942available in C. In a target-dependent way, it copies the source
Chris Lattner8d1a81d2003-10-18 05:51:36 +0000[diff] [blame]1943<tt>va_list</tt> element into the returned list. This intrinsic is necessary
Chris Lattner2c1bbd82003-10-21 15:43:55 +0000[diff] [blame]1944because the <tt><a href="i_va_start">llvm.va_start</a></tt> intrinsic may be
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1945arbitrarily complex and require memory allocation, for example.<p>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1946
1947
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1948<!-- *********************************************************************** -->
1949</ul>
1950<!-- *********************************************************************** -->
1951
1952
1953<hr>
1954<font size=-1>
1955<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
John Criswell0f6d7c02003-10-27 18:18:16 +0000[diff] [blame]1956<a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
1957<br>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1958<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
1959<!-- hhmts start -->
Chris Lattner478921b2003-10-30 01:31:37 +0000[diff] [blame]1960Last modified: Wed Oct 29 19:30:46 CST 2003
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1961<!-- hhmts end -->
1962</font>
1963</body></html>