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