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