Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / a64c3fa47e39f74c6e1f8d82249a719d6c696970 / . / docs / LangRef.html
blob: a4bab0e57709f42deee8da581f180715b2ea7522 [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
Chris Lattner25839f02003-10-10 05:01:39 +0000[diff] [blame]544to implement inline functions. Unreferenced <tt>linkonce</tt> globals are
545allowed to be discarded.<p>
546
547<a name="linkage_weak">
548<dt><tt><b>weak</b></tt>:
549
550<dd>"<tt>weak</tt>" linkage is exactly the same as <tt>linkonce</tt> linkage,
551except that unreferenced <tt>weak</tt> globals may not be discarded. This is
552used to implement constructs in C such as "<tt>int X;</tt>" at global scope.<p>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]553
554<a name="linkage_appending">
555<dt><tt><b>appending</b></tt>:
556
557<dd>"<tt>appending</tt>" linkage may only applied to global variables of pointer
558to array type. When two global variables with appending linkage are linked
559together, the two global arrays are appended together. This is the LLVM,
560typesafe, equivalent of having the system linker append together "sections" with
561identical names when .o files are linked.<p>
562
563<a name="linkage_external">
564<dt><tt><b>externally visible</b></tt>:
565
566<dd>If none of the above identifiers are used, the global is externally visible,
567meaning that it participates in linkage and can be used to resolve external
568symbol references.<p>
569
570</dl><p>
571
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]572
573For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
574another module defined a "<tt>.LC0</tt>" variable and was linked with this one,
575one of the two would be renamed, preventing a collision. Since "<tt>main</tt>"
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]576and "<tt>puts</tt>" are external (i.e., lacking any linkage declarations), they
577are accessible outside of the current module. It is illegal for a function
578<i>declaration</i> to have any linkage type other than "externally visible".<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]579
580
581<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]582</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
583<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
584<a name="globalvars">Global Variables
585</b></font></td></tr></table><ul>
586
587Global variables define regions of memory allocated at compilation time instead
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]588of run-time. Global variables may optionally be initialized. A variable may
589be defined as a global "constant", which indicates that the contents of the
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]590variable will never be modified (opening options for optimization). Constants
591must always have an initial value.<p>
592
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]593As SSA values, global variables define pointer values that are in scope
594(i.e. they dominate) for all basic blocks in the program. Global variables
595always define a pointer to their "content" type because they describe a region
596of memory, and all memory objects in LLVM are accessed through pointers.<p>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]597
598
599
600<!-- ======================================================================= -->
601</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
602<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]603<a name="functionstructure">Functions
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]604</b></font></td></tr></table><ul>
605
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]606LLVM functions definitions are composed of a (possibly empty) argument list, an
607opening curly brace, a list of basic blocks, and a closing curly brace. LLVM
608function declarations are defined with the "<tt>declare</tt>" keyword, a
609function name and a function signature.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]610
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]611A function definition contains a list of basic blocks, forming the CFG for the
612function. Each basic block may optionally start with a label (giving the basic
613block a symbol table entry), contains a list of instructions, and ends with a <a
614href="#terminators">terminator</a> instruction (such as a branch or function
615return).<p>
616
617The first basic block in program is special in two ways: it is immediately
618executed on entrance to the function, and it is not allowed to have predecessor
619basic 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]620function). Because the block can have no predecessors, it also cannot have any
621<a href="#i_phi">PHI nodes</a>.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]622
623
624<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]625</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
626<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]627<a name="instref">Instruction Reference
628</b></font></td></tr></table><ul>
629<!-- *********************************************************************** -->
630
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]631The LLVM instruction set consists of several different classifications of
Chris Lattnere489aa52002-08-14 17:55:59 +0000[diff] [blame]632instructions: <a href="#terminators">terminator instructions</a>, <a
633href="#binaryops">binary instructions</a>, <a href="#memoryops">memory
634instructions</a>, and <a href="#otherops">other instructions</a>.<p>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]635
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]636
637<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]638</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
639<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]640<a name="terminators">Terminator Instructions
641</b></font></td></tr></table><ul>
642
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]643As mentioned <a href="#functionstructure">previously</a>, every basic block in a
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]644program ends with a "Terminator" instruction, which indicates which block should
645be executed after the current block is finished. These terminator instructions
646typically yield a '<tt>void</tt>' value: they produce control flow, not values
647(the one exception being the '<a href="#i_invoke"><tt>invoke</tt></a>'
648instruction).<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]649
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]650There are five different terminator instructions: the '<a
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]651href="#i_ret"><tt>ret</tt></a>' instruction, the '<a
652href="#i_br"><tt>br</tt></a>' instruction, the '<a
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]653href="#i_switch"><tt>switch</tt></a>' instruction, the '<a
654href="#i_invoke"><tt>invoke</tt></a>' instruction, and the '<a
655href="#i_unwind"><tt>unwind</tt></a>' instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]656
657
658<!-- _______________________________________________________________________ -->
659</ul><a name="i_ret"><h4><hr size=0>'<tt>ret</tt>' Instruction</h4><ul>
660
661<h5>Syntax:</h5>
662<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]663 ret &lt;type&gt; &lt;value&gt; <i>; Return a value from a non-void function</i>
664 ret void <i>; Return from void function</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]665</pre>
666
667<h5>Overview:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]668
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]669The '<tt>ret</tt>' instruction is used to return control flow (and a value) from
670a function, back to the caller.<p>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]671
672There are two forms of the '<tt>ret</tt>' instructruction: one that returns a
673value and then causes control flow, and one that just causes control flow to
674occur.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]675
676<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]677
678The '<tt>ret</tt>' instruction may return any '<a href="#t_firstclass">first
679class</a>' type. Notice that a function is not <a href="#wellformed">well
680formed</a> if there exists a '<tt>ret</tt>' instruction inside of the function
681that returns a value that does not match the return type of the function.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]682
683<h5>Semantics:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]684
685When the '<tt>ret</tt>' instruction is executed, control flow returns back to
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]686the calling function's context. If the caller is a "<a
687href="#i_call"><tt>call</tt></a> instruction, execution continues at the
688instruction after the call. If the caller was an "<a
689href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at the
690beginning "normal" of the destination block. If the instruction returns a
691value, that value shall set the call or invoke instruction's return value.<p>
692
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]693
694<h5>Example:</h5>
695<pre>
696 ret int 5 <i>; Return an integer value of 5</i>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]697 ret void <i>; Return from a void function</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]698</pre>
699
700
701<!-- _______________________________________________________________________ -->
702</ul><a name="i_br"><h4><hr size=0>'<tt>br</tt>' Instruction</h4><ul>
703
704<h5>Syntax:</h5>
705<pre>
706 br bool &lt;cond&gt;, label &lt;iftrue&gt;, label &lt;iffalse&gt;
707 br label &lt;dest&gt; <i>; Unconditional branch</i>
708</pre>
709
710<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]711
712The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
713different basic block in the current function. There are two forms of this
714instruction, corresponding to a conditional branch and an unconditional
715branch.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]716
717<h5>Arguments:</h5>
718
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]719The conditional branch form of the '<tt>br</tt>' instruction takes a single
720'<tt>bool</tt>' value and two '<tt>label</tt>' values. The unconditional form
721of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
722target.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]723
724<h5>Semantics:</h5>
725
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]726Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>bool</tt>'
727argument is evaluated. If the value is <tt>true</tt>, control flows to the
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]728'<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>,
729control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]730
731<h5>Example:</h5>
732<pre>
733Test:
734 %cond = <a href="#i_setcc">seteq</a> int %a, %b
735 br bool %cond, label %IfEqual, label %IfUnequal
736IfEqual:
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]737 <a href="#i_ret">ret</a> int 1
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]738IfUnequal:
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]739 <a href="#i_ret">ret</a> int 0
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]740</pre>
741
742
743<!-- _______________________________________________________________________ -->
744</ul><a name="i_switch"><h4><hr size=0>'<tt>switch</tt>' Instruction</h4><ul>
745
746<h5>Syntax:</h5>
747<pre>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]748 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]749
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]750</pre>
751
752<h5>Overview:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]753
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]754The '<tt>switch</tt>' instruction is used to transfer control flow to one of
755several different places. It is a generalization of the '<tt>br</tt>'
756instruction, allowing a branch to occur to one of many possible destinations.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]757
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]758<h5>Arguments:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]759
Chris Lattnerc29b1252003-05-08 05:08:48 +0000[diff] [blame]760The '<tt>switch</tt>' instruction uses three parameters: a '<tt>uint</tt>'
761comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
762an array of pairs of comparison value constants and '<tt>label</tt>'s.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]763
764<h5>Semantics:</h5>
765
Chris Lattnerc29b1252003-05-08 05:08:48 +0000[diff] [blame]766The <tt>switch</tt> instruction specifies a table of values and destinations.
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]767When the '<tt>switch</tt>' instruction is executed, this table is searched for
768the given value. If the value is found, the corresponding destination is
Chris Lattnerc29b1252003-05-08 05:08:48 +0000[diff] [blame]769branched to, otherwise the default value it transfered to.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]770
Chris Lattnerc29b1252003-05-08 05:08:48 +0000[diff] [blame]771<h5>Implementation:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]772
Chris Lattnerc29b1252003-05-08 05:08:48 +0000[diff] [blame]773Depending on properties of the target machine and the particular <tt>switch</tt>
774instruction, this instruction may be code generated as a series of chained
775conditional branches, or with a lookup table.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]776
777<h5>Example:</h5>
778<pre>
779 <i>; Emulate a conditional br instruction</i>
780 %Val = <a href="#i_cast">cast</a> bool %value to uint
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]781 switch uint %Val, label %truedest [int 0, label %falsedest ]
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]782
783 <i>; Emulate an unconditional br instruction</i>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]784 switch uint 0, label %dest [ ]
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]785
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]786 <i>; Implement a jump table:</i>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]787 switch uint %val, label %otherwise [ int 0, label %onzero,
788 int 1, label %onone,
789 int 2, label %ontwo ]
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]790</pre>
791
792
793
794<!-- _______________________________________________________________________ -->
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]795</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]796
797<h5>Syntax:</h5>
798<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]799 &lt;result&gt; = invoke &lt;ptr to function ty&gt; %&lt;function ptr val&gt;(&lt;function args&gt;)
800 to label &lt;normal label&gt; except label &lt;exception label&gt;
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]801</pre>
802
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]803<h5>Overview:</h5>
804
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]805The '<tt>invoke</tt>' instruction causes control to transfer to a specified
806function, with the possibility of control flow transfer to either the
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]807'<tt>normal</tt>' <tt>label</tt> label or the '<tt>exception</tt>'
808<tt>label</tt>. If the callee function returns with the "<tt><a
809href="#i_ret">ret</a></tt>" instruction, control flow will return to the
810"normal" label. If the callee (or any indirect callees) returns with the "<a
811href="#i_unwind"><tt>unwind</tt></a>" instruction, control is interrupted, and
812continued at the dynamically nearest "except" label.<p>
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]813
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]814
815<h5>Arguments:</h5>
816
817This instruction requires several arguments:<p>
818<ol>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]819
820<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]821function value being invoked. In most cases, this is a direct function
Misha Brukmane6fe6712002-09-18 02:35:14 +0000[diff] [blame]822invocation, but indirect <tt>invoke</tt>s are just as possible, branching off
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]823an arbitrary pointer to function value.
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]824
825<li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
826function to be invoked.
827
828<li>'<tt>function args</tt>': argument list whose types match the function
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]829signature argument types. If the function signature indicates the function
830accepts a variable number of arguments, the extra arguments can be specified.
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]831
832<li>'<tt>normal label</tt>': the label reached when the called function executes
833a '<tt><a href="#i_ret">ret</a></tt>' instruction.
834
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]835<li>'<tt>exception label</tt>': the label reached when a callee returns with the
836<a href="#i_unwind"><tt>unwind</tt></a> instruction.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]837</ol>
838
839<h5>Semantics:</h5>
840
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]841This instruction is designed to operate as a standard '<tt><a
842href="#i_call">call</a></tt>' instruction in most regards. The primary
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]843difference 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]844
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]845This instruction is used in languages with destructors to ensure that proper
846cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
847exception. Additionally, this is important for implementation of
848'<tt>catch</tt>' clauses in high-level languages that support them.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]849
850<h5>Example:</h5>
851<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]852 %retval = invoke int %Test(int 15)
Chris Lattnerb3ceec22003-08-28 22:12:25 +0000[diff] [blame]853 to label %Continue
854 except label %TestCleanup <i>; {int}:retval set</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]855</pre>
856
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]857<!-- _______________________________________________________________________ -->
858</ul><a name="i_unwind"><h4><hr size=0>'<tt>unwind</tt>' Instruction</h4><ul>
859
860<h5>Syntax:</h5>
861<pre>
862 unwind
863</pre>
864
865<h5>Overview:</h5>
866
867The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow at
868the first callee in the dynamic call stack which used an <a
869href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. This is
870primarily used to implement exception handling.
871
872<h5>Semantics:</h5>
873
874The '<tt>unwind</tt>' intrinsic causes execution of the current function to
875immediately halt. The dynamic call stack is then searched for the first <a
876href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. Once found,
877execution continues at the "exceptional" destination block specified by the
878<tt>invoke</tt> instruction. If there is no <tt>invoke</tt> instruction in the
879dynamic call chain, undefined behavior results.
880
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]881
882
883<!-- ======================================================================= -->
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]884</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>
885<a name="binaryops">Binary Operations
886</b></font></td></tr></table><ul>
887
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]888Binary operators are used to do most of the computation in a program. They
889require two operands, execute an operation on them, and produce a single value.
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]890The result value of a binary operator is not necessarily the same type as its
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]891operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]892
893There are several different binary operators:<p>
894
895
896<!-- _______________________________________________________________________ -->
897</ul><a name="i_add"><h4><hr size=0>'<tt>add</tt>' Instruction</h4><ul>
898
899<h5>Syntax:</h5>
900<pre>
901 &lt;result&gt; = add &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
902</pre>
903
904<h5>Overview:</h5>
905The '<tt>add</tt>' instruction returns the sum of its two operands.<p>
906
907<h5>Arguments:</h5>
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]908The 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]909
910<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]911
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]912The value produced is the integer or floating point sum of the two operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]913
914<h5>Example:</h5>
915<pre>
916 &lt;result&gt; = add int 4, %var <i>; yields {int}:result = 4 + %var</i>
917</pre>
918
919
920<!-- _______________________________________________________________________ -->
921</ul><a name="i_sub"><h4><hr size=0>'<tt>sub</tt>' Instruction</h4><ul>
922
923<h5>Syntax:</h5>
924<pre>
925 &lt;result&gt; = sub &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
926</pre>
927
928<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]929
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]930The '<tt>sub</tt>' instruction returns the difference of its two operands.<p>
931
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]932Note that the '<tt>sub</tt>' instruction is used to represent the '<tt>neg</tt>'
933instruction present in most other intermediate representations.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]934
935<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]936
937The two arguments to the '<tt>sub</tt>' instruction must be either <a
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]938href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]939values. Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]940
941<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]942
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]943The value produced is the integer or floating point difference of the two
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]944operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]945
946<h5>Example:</h5>
947<pre>
948 &lt;result&gt; = sub int 4, %var <i>; yields {int}:result = 4 - %var</i>
949 &lt;result&gt; = sub int 0, %val <i>; yields {int}:result = -%var</i>
950</pre>
951
952<!-- _______________________________________________________________________ -->
953</ul><a name="i_mul"><h4><hr size=0>'<tt>mul</tt>' Instruction</h4><ul>
954
955<h5>Syntax:</h5>
956<pre>
957 &lt;result&gt; = mul &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
958</pre>
959
960<h5>Overview:</h5>
961The '<tt>mul</tt>' instruction returns the product of its two operands.<p>
962
963<h5>Arguments:</h5>
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]964The 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]965
966<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]967
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]968The value produced is the integer or floating point product of the two
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]969operands.<p>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]970
971There is no signed vs unsigned multiplication. The appropriate action is taken
972based on the type of the operand. <p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]973
974
975<h5>Example:</h5>
976<pre>
977 &lt;result&gt; = mul int 4, %var <i>; yields {int}:result = 4 * %var</i>
978</pre>
979
980
981<!-- _______________________________________________________________________ -->
982</ul><a name="i_div"><h4><hr size=0>'<tt>div</tt>' Instruction</h4><ul>
983
984<h5>Syntax:</h5>
985<pre>
986 &lt;result&gt; = div &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
987</pre>
988
989<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]990
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]991The '<tt>div</tt>' instruction returns the quotient of its two operands.<p>
992
993<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]994
995The two arguments to the '<tt>div</tt>' instruction must be either <a
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]996href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]997values. Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]998
999<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1000
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1001The value produced is the integer or floating point quotient of the two
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1002operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1003
1004<h5>Example:</h5>
1005<pre>
1006 &lt;result&gt; = div int 4, %var <i>; yields {int}:result = 4 / %var</i>
1007</pre>
1008
1009
1010<!-- _______________________________________________________________________ -->
1011</ul><a name="i_rem"><h4><hr size=0>'<tt>rem</tt>' Instruction</h4><ul>
1012
1013<h5>Syntax:</h5>
1014<pre>
1015 &lt;result&gt; = rem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1016</pre>
1017
1018<h5>Overview:</h5>
1019The '<tt>rem</tt>' instruction returns the remainder from the division of its two operands.<p>
1020
1021<h5>Arguments:</h5>
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1022The 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]1023
1024<h5>Semantics:</h5>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1025
1026This returns the <i>remainder</i> of a division (where the result has the same
1027sign as the divisor), not the <i>modulus</i> (where the result has the same sign
1028as the dividend) of a value. For more information about the difference, see: <a
1029href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The Math
1030Forum</a>.<p>
1031
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1032<h5>Example:</h5>
1033<pre>
1034 &lt;result&gt; = rem int 4, %var <i>; yields {int}:result = 4 % %var</i>
1035</pre>
1036
1037
1038<!-- _______________________________________________________________________ -->
1039</ul><a name="i_setcc"><h4><hr size=0>'<tt>set<i>cc</i></tt>' Instructions</h4><ul>
1040
1041<h5>Syntax:</h5>
1042<pre>
1043 &lt;result&gt; = seteq &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1044 &lt;result&gt; = setne &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1045 &lt;result&gt; = setlt &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1046 &lt;result&gt; = setgt &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1047 &lt;result&gt; = setle &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1048 &lt;result&gt; = setge &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1049</pre>
1050
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1051<h5>Overview:</h5> The '<tt>set<i>cc</i></tt>' family of instructions returns a
1052boolean value based on a comparison of their two operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1053
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1054<h5>Arguments:</h5> The two arguments to the '<tt>set<i>cc</i></tt>'
1055instructions must be of <a href="#t_firstclass">first class</a> or <a
1056href="#t_pointer">pointer</a> type (it is not possible to compare
1057'<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]1058values, etc...). Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1059
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1060<h5>Semantics:</h5>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1061
1062The '<tt>seteq</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1063both operands are equal.<br>
1064
1065The '<tt>setne</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1066both operands are unequal.<br>
1067
1068The '<tt>setlt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1069the first operand is less than the second operand.<br>
1070
1071The '<tt>setgt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1072the first operand is greater than the second operand.<br>
1073
1074The '<tt>setle</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1075the first operand is less than or equal to the second operand.<br>
1076
1077The '<tt>setge</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1078the first operand is greater than or equal to the second operand.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1079
1080<h5>Example:</h5>
1081<pre>
1082 &lt;result&gt; = seteq int 4, 5 <i>; yields {bool}:result = false</i>
1083 &lt;result&gt; = setne float 4, 5 <i>; yields {bool}:result = true</i>
1084 &lt;result&gt; = setlt uint 4, 5 <i>; yields {bool}:result = true</i>
1085 &lt;result&gt; = setgt sbyte 4, 5 <i>; yields {bool}:result = false</i>
1086 &lt;result&gt; = setle sbyte 4, 5 <i>; yields {bool}:result = true</i>
1087 &lt;result&gt; = setge sbyte 4, 5 <i>; yields {bool}:result = false</i>
1088</pre>
1089
1090
1091
1092<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1093</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1094<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]1095<a name="bitwiseops">Bitwise Binary Operations
1096</b></font></td></tr></table><ul>
1097
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1098Bitwise binary operators are used to do various forms of bit-twiddling in a
1099program. They are generally very efficient instructions, and can commonly be
1100strength reduced from other instructions. They require two operands, execute an
1101operation on them, and produce a single value. The resulting value of the
1102bitwise binary operators is always the same type as its first operand.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1103
1104<!-- _______________________________________________________________________ -->
1105</ul><a name="i_and"><h4><hr size=0>'<tt>and</tt>' Instruction</h4><ul>
1106
1107<h5>Syntax:</h5>
1108<pre>
1109 &lt;result&gt; = and &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1110</pre>
1111
1112<h5>Overview:</h5>
1113The '<tt>and</tt>' instruction returns the bitwise logical and of its two operands.<p>
1114
1115<h5>Arguments:</h5>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1116
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1117The two arguments to the '<tt>and</tt>' instruction must be <a
1118href="#t_integral">integral</a> values. Both arguments must have identical
1119types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1120
1121
1122<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1123
1124The truth table used for the '<tt>and</tt>' instruction is:<p>
1125
Chris Lattnerc98cbbc2002-06-25 18:06:50 +0000[diff] [blame]1126<center><table border=1 cellspacing=0 cellpadding=4>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1127<tr><td>In0</td> <td>In1</td> <td>Out</td></tr>
1128<tr><td>0</td> <td>0</td> <td>0</td></tr>
1129<tr><td>0</td> <td>1</td> <td>0</td></tr>
1130<tr><td>1</td> <td>0</td> <td>0</td></tr>
1131<tr><td>1</td> <td>1</td> <td>1</td></tr>
1132</table></center><p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1133
1134
1135<h5>Example:</h5>
1136<pre>
1137 &lt;result&gt; = and int 4, %var <i>; yields {int}:result = 4 & %var</i>
1138 &lt;result&gt; = and int 15, 40 <i>; yields {int}:result = 8</i>
1139 &lt;result&gt; = and int 4, 8 <i>; yields {int}:result = 0</i>
1140</pre>
1141
1142
1143
1144<!-- _______________________________________________________________________ -->
1145</ul><a name="i_or"><h4><hr size=0>'<tt>or</tt>' Instruction</h4><ul>
1146
1147<h5>Syntax:</h5>
1148<pre>
1149 &lt;result&gt; = or &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1150</pre>
1151
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1152<h5>Overview:</h5> The '<tt>or</tt>' instruction returns the bitwise logical
1153inclusive or of its two operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1154
1155<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1156
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1157The two arguments to the '<tt>or</tt>' instruction must be <a
1158href="#t_integral">integral</a> values. Both arguments must have identical
1159types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1160
1161
1162<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1163
1164The truth table used for the '<tt>or</tt>' instruction is:<p>
1165
Chris Lattnerc98cbbc2002-06-25 18:06:50 +0000[diff] [blame]1166<center><table border=1 cellspacing=0 cellpadding=4>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1167<tr><td>In0</td> <td>In1</td> <td>Out</td></tr>
1168<tr><td>0</td> <td>0</td> <td>0</td></tr>
1169<tr><td>0</td> <td>1</td> <td>1</td></tr>
1170<tr><td>1</td> <td>0</td> <td>1</td></tr>
1171<tr><td>1</td> <td>1</td> <td>1</td></tr>
1172</table></center><p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1173
1174
1175<h5>Example:</h5>
1176<pre>
1177 &lt;result&gt; = or int 4, %var <i>; yields {int}:result = 4 | %var</i>
1178 &lt;result&gt; = or int 15, 40 <i>; yields {int}:result = 47</i>
1179 &lt;result&gt; = or int 4, 8 <i>; yields {int}:result = 12</i>
1180</pre>
1181
1182
1183<!-- _______________________________________________________________________ -->
1184</ul><a name="i_xor"><h4><hr size=0>'<tt>xor</tt>' Instruction</h4><ul>
1185
1186<h5>Syntax:</h5>
1187<pre>
1188 &lt;result&gt; = xor &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1189</pre>
1190
1191<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1192
1193The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of its
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1194two operands. The <tt>xor</tt> is used to implement the "one's complement"
1195operation, which is the "~" operator in C.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1196
1197<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1198
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1199The two arguments to the '<tt>xor</tt>' instruction must be <a
1200href="#t_integral">integral</a> values. Both arguments must have identical
1201types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1202
1203
1204<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1205
1206The truth table used for the '<tt>xor</tt>' instruction is:<p>
1207
Chris Lattnerc98cbbc2002-06-25 18:06:50 +0000[diff] [blame]1208<center><table border=1 cellspacing=0 cellpadding=4>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1209<tr><td>In0</td> <td>In1</td> <td>Out</td></tr>
1210<tr><td>0</td> <td>0</td> <td>0</td></tr>
1211<tr><td>0</td> <td>1</td> <td>1</td></tr>
1212<tr><td>1</td> <td>0</td> <td>1</td></tr>
1213<tr><td>1</td> <td>1</td> <td>0</td></tr>
1214</table></center><p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1215
1216
1217<h5>Example:</h5>
1218<pre>
1219 &lt;result&gt; = xor int 4, %var <i>; yields {int}:result = 4 ^ %var</i>
1220 &lt;result&gt; = xor int 15, 40 <i>; yields {int}:result = 39</i>
1221 &lt;result&gt; = xor int 4, 8 <i>; yields {int}:result = 12</i>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1222 &lt;result&gt; = xor int %V, -1 <i>; yields {int}:result = ~%V</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1223</pre>
1224
1225
1226<!-- _______________________________________________________________________ -->
1227</ul><a name="i_shl"><h4><hr size=0>'<tt>shl</tt>' Instruction</h4><ul>
1228
1229<h5>Syntax:</h5>
1230<pre>
1231 &lt;result&gt; = shl &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt; <i>; yields {ty}:result</i>
1232</pre>
1233
1234<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1235
1236The '<tt>shl</tt>' instruction returns the first operand shifted to the left a
1237specified number of bits.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1238
1239<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1240
1241The first argument to the '<tt>shl</tt>' instruction must be an <a
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1242href="#t_integer">integer</a> type. The second argument must be an
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1243'<tt>ubyte</tt>' type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1244
1245<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1246
1247The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1248
1249
1250<h5>Example:</h5>
1251<pre>
1252 &lt;result&gt; = shl int 4, ubyte %var <i>; yields {int}:result = 4 << %var</i>
1253 &lt;result&gt; = shl int 4, ubyte 2 <i>; yields {int}:result = 16</i>
1254 &lt;result&gt; = shl int 1, ubyte 10 <i>; yields {int}:result = 1024</i>
1255</pre>
1256
1257
1258<!-- _______________________________________________________________________ -->
1259</ul><a name="i_shr"><h4><hr size=0>'<tt>shr</tt>' Instruction</h4><ul>
1260
1261
1262<h5>Syntax:</h5>
1263<pre>
1264 &lt;result&gt; = shr &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt; <i>; yields {ty}:result</i>
1265</pre>
1266
1267<h5>Overview:</h5>
1268The '<tt>shr</tt>' instruction returns the first operand shifted to the right a specified number of bits.
1269
1270<h5>Arguments:</h5>
Chris Lattnereaee9e12002-09-03 00:52:52 +0000[diff] [blame]1271The 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]1272
1273<h5>Semantics:</h5>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1274
1275If the first argument is a <a href="#t_signed">signed</a> type, the most
1276significant bit is duplicated in the newly free'd bit positions. If the first
1277argument is unsigned, zero bits shall fill the empty positions.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1278
1279<h5>Example:</h5>
1280<pre>
1281 &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]1282 &lt;result&gt; = shr uint 4, ubyte 1 <i>; yields {uint}:result = 2</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1283 &lt;result&gt; = shr int 4, ubyte 2 <i>; yields {int}:result = 1</i>
Chris Lattner8c6bb902003-06-18 21:30:51 +0000[diff] [blame]1284 &lt;result&gt; = shr sbyte 4, ubyte 3 <i>; yields {sbyte}:result = 0</i>
1285 &lt;result&gt; = shr sbyte -2, ubyte 1 <i>; yields {sbyte}:result = -1</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1286</pre>
1287
1288
1289
1290
1291
1292<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1293</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1294<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]1295<a name="memoryops">Memory Access Operations
1296</b></font></td></tr></table><ul>
1297
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1298A key design point of an SSA-based representation is how it represents memory.
1299In LLVM, no memory locations are in SSA form, which makes things very simple.
1300This section describes how to read, write, allocate and free memory in LLVM.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1301
1302
1303<!-- _______________________________________________________________________ -->
1304</ul><a name="i_malloc"><h4><hr size=0>'<tt>malloc</tt>' Instruction</h4><ul>
1305
1306<h5>Syntax:</h5>
1307<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1308 &lt;result&gt; = malloc &lt;type&gt;, uint &lt;NumElements&gt; <i>; yields {type*}:result</i>
1309 &lt;result&gt; = malloc &lt;type&gt; <i>; yields {type*}:result</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1310</pre>
1311
1312<h5>Overview:</h5>
1313The '<tt>malloc</tt>' instruction allocates memory from the system heap and returns a pointer to it.<p>
1314
1315<h5>Arguments:</h5>
1316
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1317The the '<tt>malloc</tt>' instruction allocates
1318<tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory from the operating
1319system, and returns a pointer of the appropriate type to the program. The
1320second form of the instruction is a shorter version of the first instruction
1321that defaults to allocating one element.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1322
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1323'<tt>type</tt>' must be a sized type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1324
1325<h5>Semantics:</h5>
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1326
1327Memory is allocated using the system "<tt>malloc</tt>" function, and a pointer
1328is returned.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1329
1330<h5>Example:</h5>
1331<pre>
1332 %array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
1333
1334 %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]1335 %array1 = malloc ubyte, uint 4 <i>; yields {ubyte*}:array1</i>
1336 %array2 = malloc [12 x ubyte], uint %size <i>; yields {[12 x ubyte]*}:array2</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1337</pre>
1338
1339
1340<!-- _______________________________________________________________________ -->
1341</ul><a name="i_free"><h4><hr size=0>'<tt>free</tt>' Instruction</h4><ul>
1342
1343<h5>Syntax:</h5>
1344<pre>
1345 free &lt;type&gt; &lt;value&gt; <i>; yields {void}</i>
1346</pre>
1347
1348
1349<h5>Overview:</h5>
1350The '<tt>free</tt>' instruction returns memory back to the unused memory heap, to be reallocated in the future.<p>
1351
1352
1353<h5>Arguments:</h5>
1354
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1355'<tt>value</tt>' shall be a pointer value that points to a value that was
1356allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1357
1358
1359<h5>Semantics:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1360
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1361Access 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]1362
1363<h5>Example:</h5>
1364<pre>
1365 %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
1366 free [4 x ubyte]* %array
1367</pre>
1368
1369
1370<!-- _______________________________________________________________________ -->
1371</ul><a name="i_alloca"><h4><hr size=0>'<tt>alloca</tt>' Instruction</h4><ul>
1372
1373<h5>Syntax:</h5>
1374<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1375 &lt;result&gt; = alloca &lt;type&gt;, uint &lt;NumElements&gt; <i>; yields {type*}:result</i>
1376 &lt;result&gt; = alloca &lt;type&gt; <i>; yields {type*}:result</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1377</pre>
1378
1379<h5>Overview:</h5>
1380
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1381The '<tt>alloca</tt>' instruction allocates memory on the current stack frame of
1382the procedure that is live until the current function returns to its caller.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1383
1384<h5>Arguments:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1385
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1386The the '<tt>alloca</tt>' instruction allocates
1387<tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory on the runtime stack,
1388returning a pointer of the appropriate type to the program. The second form of
1389the instruction is a shorter version of the first that defaults to allocating
1390one element.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1391
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1392'<tt>type</tt>' may be any sized type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1393
1394<h5>Semantics:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1395
1396Memory is allocated, a pointer is returned. '<tt>alloca</tt>'d memory is
1397automatically released when the function returns. The '<tt>alloca</tt>'
1398instruction is commonly used to represent automatic variables that must have an
Chris Lattner27f71f22003-09-03 00:41:47 +0000[diff] [blame]1399address available. When the function returns (either with the <tt><a
1400href="#i_ret">ret</a></tt> or <tt><a href="#i_invoke">invoke</a></tt>
1401instructions), the memory is reclaimed.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1402
1403<h5>Example:</h5>
1404<pre>
1405 %ptr = alloca int <i>; yields {int*}:ptr</i>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1406 %ptr = alloca int, uint 4 <i>; yields {int*}:ptr</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1407</pre>
1408
1409
1410<!-- _______________________________________________________________________ -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1411</ul><a name="i_load"><h4><hr size=0>'<tt>load</tt>' Instruction</h4><ul>
1412
1413<h5>Syntax:</h5>
1414<pre>
1415 &lt;result&gt; = load &lt;ty&gt;* &lt;pointer&gt;
Chris Lattnerf0651072003-09-08 18:27:49 +0000[diff] [blame]1416 &lt;result&gt; = volatile load &lt;ty&gt;* &lt;pointer&gt;
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1417</pre>
1418
1419<h5>Overview:</h5>
1420The '<tt>load</tt>' instruction is used to read from memory.<p>
1421
1422<h5>Arguments:</h5>
1423
Chris Lattnerf0651072003-09-08 18:27:49 +0000[diff] [blame]1424The argument to the '<tt>load</tt>' instruction specifies the memory address to
1425load from. The pointer must point to a <a href="t_firstclass">first class</a>
1426type. If the <tt>load</tt> is marked as <tt>volatile</tt> then the optimizer is
1427not allowed to modify the number or order of execution of this <tt>load</tt>
1428with other volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
1429instructions. <p>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1430
1431<h5>Semantics:</h5>
1432
1433The location of memory pointed to is loaded.
1434
1435<h5>Examples:</h5>
1436<pre>
1437 %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
1438 <a href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
1439 %val = load int* %ptr <i>; yields {int}:val = int 3</i>
1440</pre>
1441
1442
1443
1444
1445<!-- _______________________________________________________________________ -->
1446</ul><a name="i_store"><h4><hr size=0>'<tt>store</tt>' Instruction</h4><ul>
1447
1448<h5>Syntax:</h5>
1449<pre>
1450 store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt; <i>; yields {void}</i>
Chris Lattnerf0651072003-09-08 18:27:49 +0000[diff] [blame]1451 volatile store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt; <i>; yields {void}</i>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1452</pre>
1453
1454<h5>Overview:</h5>
1455The '<tt>store</tt>' instruction is used to write to memory.<p>
1456
1457<h5>Arguments:</h5>
1458
1459There are two arguments to the '<tt>store</tt>' instruction: a value to store
1460and an address to store it into. The type of the '<tt>&lt;pointer&gt;</tt>'
Chris Lattnerf0651072003-09-08 18:27:49 +0000[diff] [blame]1461operand must be a pointer to the type of the '<tt>&lt;value&gt;</tt>' operand.
1462If the <tt>store</tt> is marked as <tt>volatile</tt> then the optimizer is not
1463allowed to modify the number or order of execution of this <tt>store</tt> with
1464other volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
1465instructions.<p>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1466
1467<h5>Semantics:</h5> The contents of memory are updated to contain
1468'<tt>&lt;value&gt;</tt>' at the location specified by the
1469'<tt>&lt;pointer&gt;</tt>' operand.<p>
1470
1471<h5>Example:</h5>
1472<pre>
1473 %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
1474 <a href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
1475 %val = load int* %ptr <i>; yields {int}:val = int 3</i>
1476</pre>
1477
1478
1479
1480
1481<!-- _______________________________________________________________________ -->
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1482</ul><a name="i_getelementptr"><h4><hr size=0>'<tt>getelementptr</tt>' Instruction</h4><ul>
1483
1484<h5>Syntax:</h5>
1485<pre>
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1486 &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]1487</pre>
1488
1489<h5>Overview:</h5>
1490
1491The '<tt>getelementptr</tt>' instruction is used to get the address of a
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1492subelement of an aggregate data structure.<p>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1493
1494<h5>Arguments:</h5>
1495
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1496This instruction takes a list of <tt>long</tt> values and <tt>ubyte</tt>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1497constants that indicate what form of addressing to perform. The actual types of
1498the arguments provided depend on the type of the first pointer argument. The
1499'<tt>getelementptr</tt>' instruction is used to index down through the type
1500levels of a structure.<p>
1501
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1502For example, lets consider a C code fragment and how it gets compiled to
1503LLVM:<p>
1504
1505<pre>
1506struct RT {
1507 char A;
1508 int B[10][20];
1509 char C;
1510};
1511struct ST {
1512 int X;
1513 double Y;
1514 struct RT Z;
1515};
1516
1517int *foo(struct ST *s) {
1518 return &amp;s[1].Z.B[5][13];
1519}
1520</pre>
1521
1522The LLVM code generated by the GCC frontend is:
1523
1524<pre>
1525%RT = type { sbyte, [10 x [20 x int]], sbyte }
1526%ST = type { int, double, %RT }
1527
1528int* "foo"(%ST* %s) {
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1529 %reg = getelementptr %ST* %s, long 1, ubyte 2, ubyte 1, long 5, long 13
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1530 ret int* %reg
1531}
1532</pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1533
1534<h5>Semantics:</h5>
1535
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1536The index types specified for the '<tt>getelementptr</tt>' instruction depend on
1537the pointer type that is being index into. <a href="t_pointer">Pointer</a> and
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1538<a href="t_array">array</a> types require '<tt>long</tt>' values, and <a
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1539href="t_struct">structure</a> types require '<tt>ubyte</tt>'
1540<b>constants</b>.<p>
1541
1542In the example above, the first index is indexing into the '<tt>%ST*</tt>' type,
1543which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ int, double, %RT }</tt>'
1544type, a structure. The second index indexes into the third element of the
1545structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]], sbyte
1546}</tt>' type, another structure. The third index indexes into the second
1547element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
1548array. The two dimensions of the array are subscripted into, yielding an
1549'<tt>int</tt>' type. The '<tt>getelementptr</tt>' instruction return a pointer
1550to this element, thus yielding a '<tt>int*</tt>' type.<p>
1551
1552Note that it is perfectly legal to index partially through a structure,
1553returning a pointer to an inner element. Because of this, the LLVM code for the
1554given testcase is equivalent to:<p>
1555
1556<pre>
1557int* "foo"(%ST* %s) {
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1558 %t1 = getelementptr %ST* %s , long 1 <i>; yields %ST*:%t1</i>
1559 %t2 = getelementptr %ST* %t1, long 0, ubyte 2 <i>; yields %RT*:%t2</i>
1560 %t3 = getelementptr %RT* %t2, long 0, ubyte 1 <i>; yields [10 x [20 x int]]*:%t3</i>
1561 %t4 = getelementptr [10 x [20 x int]]* %t3, long 0, long 5 <i>; yields [20 x int]*:%t4</i>
1562 %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]1563 ret int* %t5
1564}
1565</pre>
1566
1567
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1568
1569<h5>Example:</h5>
1570<pre>
Chris Lattnerf31860b2002-08-19 21:14:38 +0000[diff] [blame]1571 <i>; yields [12 x ubyte]*:aptr</i>
Chris Lattner3dfa10b2002-12-13 06:01:21 +0000[diff] [blame]1572 %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, ubyte 1
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1573</pre>
1574
1575
1576
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1577<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1578</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1579<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]1580<a name="otherops">Other Operations
1581</b></font></td></tr></table><ul>
1582
Chris Lattner43c2eb72003-09-03 04:20:13 +0000[diff] [blame]1583The instructions in this catagory are the "miscellaneous" instructions, which defy better classification.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1584
1585
1586<!-- _______________________________________________________________________ -->
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1587</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]1588
1589<h5>Syntax:</h5>
1590<pre>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1591 &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1592</pre>
1593
1594<h5>Overview:</h5>
1595
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1596The '<tt>phi</tt>' instruction is used to implement the &phi; node in the SSA
1597graph representing the function.<p>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1598
1599<h5>Arguments:</h5>
1600
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1601The type of the incoming values are specified with the first type field. After
1602this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with
1603one pair for each predecessor basic block of the current block.<p>
1604
1605There must be no non-phi instructions between the start of a basic block and the
1606PHI instructions: i.e. PHI instructions must be first in a basic block.<p>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1607
1608<h5>Semantics:</h5>
1609
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1610At runtime, the '<tt>phi</tt>' instruction logically takes on the value
1611specified by the parameter, depending on which basic block we came from in the
1612last <a href="#terminators">terminator</a> instruction.<p>
1613
1614<h5>Example:</h5>
1615
1616<pre>
1617Loop: ; Infinite loop that counts from 0 on up...
1618 %indvar = phi uint [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
1619 %nextindvar = add uint %indvar, 1
1620 br label %Loop
1621</pre>
1622
1623
1624<!-- _______________________________________________________________________ -->
1625</ul><a name="i_cast"><h4><hr size=0>'<tt>cast .. to</tt>' Instruction</h4><ul>
1626
1627<h5>Syntax:</h5>
1628<pre>
1629 &lt;result&gt; = cast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt; <i>; yields ty2</i>
1630</pre>
1631
1632<h5>Overview:</h5>
1633
1634The '<tt>cast</tt>' instruction is used as the primitive means to convert
1635integers to floating point, change data type sizes, and break type safety (by
1636casting pointers).<p>
1637
1638<h5>Arguments:</h5>
1639
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1640The '<tt>cast</tt>' instruction takes a value to cast, which must be a first
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1641class value, and a type to cast it to, which must also be a first class type.<p>
1642
1643<h5>Semantics:</h5>
1644
1645This instruction follows the C rules for explicit casts when determining how the
1646data being cast must change to fit in its new container.<p>
1647
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1648When casting to bool, any value that would be considered true in the context of
1649a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>' values,
1650all else are '<tt>false</tt>'.<p>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1651
Chris Lattnerf8856bc2002-08-13 20:52:09 +0000[diff] [blame]1652When extending an integral value from a type of one signness to another (for
1653example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
1654<b>source</b> value is signed, and zero-extended if the source value is
Chris Lattner2b4dcbb2002-08-15 19:36:05 +0000[diff] [blame]1655unsigned. <tt>bool</tt> values are always zero extended into either zero or
1656one.<p>
Chris Lattnerf8856bc2002-08-13 20:52:09 +0000[diff] [blame]1657
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1658<h5>Example:</h5>
1659<pre>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1660 %X = cast int 257 to ubyte <i>; yields ubyte:1</i>
Chris Lattner7bae3952002-06-25 18:03:17 +0000[diff] [blame]1661 %Y = cast int 123 to bool <i>; yields bool:true</i>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1662</pre>
1663
1664
1665
1666<!-- _______________________________________________________________________ -->
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1667</ul><a name="i_call"><h4><hr size=0>'<tt>call</tt>' Instruction</h4><ul>
1668
1669<h5>Syntax:</h5>
1670<pre>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1671 &lt;result&gt; = call &lt;ty&gt;* &lt;fnptrval&gt;(&lt;param list&gt;)
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1672</pre>
1673
1674<h5>Overview:</h5>
1675
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1676The '<tt>call</tt>' instruction represents a simple function call.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1677
1678<h5>Arguments:</h5>
1679
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1680This instruction requires several arguments:<p>
1681<ol>
1682
1683<li>'<tt>ty</tt>': shall be the signature of the pointer to function value being
1684invoked. The argument types must match the types implied by this signature.<p>
1685
1686<li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to be
1687invoked. In most cases, this is a direct function invocation, but indirect
Misha Brukmane6fe6712002-09-18 02:35:14 +0000[diff] [blame]1688<tt>call</tt>s are just as possible, calling an arbitrary pointer to function
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1689values.<p>
1690
1691<li>'<tt>function args</tt>': argument list whose types match the function
1692signature argument types. If the function signature indicates the function
1693accepts a variable number of arguments, the extra arguments can be specified.
1694</ol>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1695
1696<h5>Semantics:</h5>
1697
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1698The '<tt>call</tt>' instruction is used to cause control flow to transfer to a
1699specified function, with its incoming arguments bound to the specified values.
1700Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called function,
1701control flow continues with the instruction after the function call, and the
1702return value of the function is bound to the result argument. This is a simpler
1703case of the <a href="#i_invoke">invoke</a> instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1704
1705<h5>Example:</h5>
1706<pre>
1707 %retval = call int %test(int %argc)
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1708 call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);
1709
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1710</pre>
1711
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1712<!-- _______________________________________________________________________ -->
1713</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]1714
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1715<h5>Syntax:</h5>
1716<pre>
1717 &lt;result&gt; = va_arg &lt;va_list&gt;* &lt;arglist&gt;, &lt;retty&gt;
1718</pre>
1719
1720<h5>Overview:</h5>
1721
1722The '<tt>va_arg</tt>' instruction is used to access arguments passed through the
1723"variable argument" area of a function call. It corresponds directly to the
1724<tt>va_arg</tt> macro in C.<p>
1725
1726<h5>Arguments:</h5>
1727
1728This instruction takes a pointer to a <tt>valist</tt> value to read a new
1729argument from. The return type of the instruction is defined by the second
1730argument, a type.<p>
1731
1732<h5>Semantics:</h5>
1733
1734The '<tt>va_arg</tt>' instruction works just like the <tt>va_arg</tt> macro
1735available in C. In a target-dependent way, it reads the argument indicated by
1736the value the arglist points to, updates the arglist, then returns a value of
1737the specified type. This instruction should be used in conjunction with the
1738variable argument handling <a href="#int_varargs">Intrinsic Functions</a>.<p>
1739
1740It is legal for this instruction to be called in a function which does not take
1741a variable number of arguments, for example, the <tt>vfprintf</tt> function.<p>
1742
1743<tt>va_arg</tt> is an LLVM instruction instead of an <a
1744href="#intrinsics">intrinsic function</a> because the return type depends on an
1745argument.<p>
1746
1747<h5>Example:</h5>
1748
1749See the <a href="#int_varargs">variable argument processing</a> section.<p>
1750
1751<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame]1752</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
1753<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1754<a name="intrinsics">Intrinsic Functions
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1755</b></font></td></tr></table><ul>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1756<!-- *********************************************************************** -->
1757
1758LLVM supports the notion of an "intrinsic function". These functions have well
1759known names and semantics, and are required to follow certain restrictions.
1760Overall, these instructions represent an extension mechanism for the LLVM
1761language that does not require changing all of the transformations in LLVM to
1762add to the language (or the bytecode reader/writer, the parser, etc...).<p>
1763
1764Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix, this
1765prefix is reserved in LLVM for intrinsic names, thus functions may not be named
1766this. Intrinsic functions must always be external functions: you cannot define
1767the body of intrinsic functions. Intrinsic functions may only be used in call
1768or invoke instructions: it is illegal to take the address of an intrinsic
1769function. Additionally, because intrinsic functions are part of the LLVM
1770language, it is required that they all be documented here if any are added.<p>
1771
1772Unless an intrinsic function is target-specific, there must be a lowering pass
1773to eliminate the intrinsic or all backends must support the intrinsic
1774function.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1775
1776
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1777<!-- ======================================================================= -->
1778</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1779<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
1780<a name="int_varargs">Variable Argument Handling Intrinsics
1781</b></font></td></tr></table><ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1782
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1783Variable argument support is defined in LLVM with the <a
1784href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three intrinsic
1785functions. These function correspond almost directly to the similarly named
1786macros defined in the <tt>&lt;stdarg.h&gt;</tt> header file.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1787
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1788All of these functions operate on arguments that use a target-specific type
1789"<tt>va_list</tt>". The LLVM assembly language reference manual does not define
1790what this type is, so all transformations should be prepared to handle
1791intrinsics with any type used.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1792
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1793This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction
1794and the variable argument handling intrinsic functions are used.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1795
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1796<pre>
1797int %test(int %X, ...) {
1798 ; Allocate two va_list items. On this target, va_list is of type sbyte*
1799 %ap = alloca sbyte*
1800 %aq = alloca sbyte*
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1801
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1802 ; Initialize variable argument processing
Chris Lattnera1a20972003-05-08 15:55:44 +0000[diff] [blame]1803 call void (sbyte**)* %<a href="#i_va_start">llvm.va_start</a>(sbyte** %ap)
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1804
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1805 ; Read a single integer argument
1806 %tmp = <a href="#i_va_arg">va_arg</a> sbyte** %ap, int
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1807
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1808 ; Demonstrate usage of llvm.va_copy and llvm_va_end
1809 %apv = load sbyte** %ap
1810 call void %<a href="#i_va_copy">llvm.va_copy</a>(sbyte** %aq, sbyte* %apv)
1811 call void %<a href="#i_va_end">llvm.va_end</a>(sbyte** %aq)
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1812
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1813 ; Stop processing of arguments.
1814 call void %<a href="#i_va_end">llvm.va_end</a>(sbyte** %ap)
1815 ret int %tmp
1816}
1817</pre>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1818
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1819<!-- _______________________________________________________________________ -->
1820</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]1821
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1822<h5>Syntax:</h5>
1823<pre>
Chris Lattnera1a20972003-05-08 15:55:44 +0000[diff] [blame]1824 call void (va_list*)* %llvm.va_start(&lt;va_list&gt;* &lt;arglist&gt;)
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1825</pre>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1826
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1827<h5>Overview:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1828
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1829The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*&lt;arglist&gt;</tt> for
1830subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt> and <tt><a
1831href="#i_va_end">llvm.va_end</a></tt>, and must be called before either are
1832invoked.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1833
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1834<h5>Arguments:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1835
Chris Lattnera1a20972003-05-08 15:55:44 +0000[diff] [blame]1836The argument is a pointer to a <tt>va_list</tt> element to initialize.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1837
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1838<h5>Semantics:</h5>
1839
1840The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
1841macro available in C. In a target-dependent way, it initializes the
Chris Lattnera1a20972003-05-08 15:55:44 +0000[diff] [blame]1842<tt>va_list</tt> element the argument points to, so that the next call to
1843<tt>va_arg</tt> will produce the first variable argument passed to the function.
1844Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the
1845last argument of the function, the compiler can figure that out.<p>
Chris Lattnerd9ad5b32003-05-08 04:57:36 +0000[diff] [blame]1846
1847
1848<!-- _______________________________________________________________________ -->
1849</ul><a name="i_va_end"><h4><hr size=0>'<tt>llvm.va_end</tt>' Intrinsic</h4><ul>
1850
1851<h5>Syntax:</h5>
1852<pre>
1853 call void (va_list*)* %llvm.va_end(&lt;va_list&gt;* &lt;arglist&gt;)
1854</pre>
1855
1856<h5>Overview:</h5>
1857
1858The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*&lt;arglist&gt;</tt> which
1859has been initialized previously with <tt><a
1860href="#i_va_begin">llvm.va_begin</a></tt>.<p>
1861
1862<h5>Arguments:</h5>
1863
1864The argument is a pointer to a <tt>va_list</tt> element to destroy.<p>
1865
1866<h5>Semantics:</h5>
1867
1868The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt> macro
1869available in C. In a target-dependent way, it destroys the <tt>va_list</tt>
1870that the argument points to. Calls to <a
1871href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
1872href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly with calls
1873to <tt>llvm.va_end</tt>.<p>
1874
1875
1876
1877<!-- _______________________________________________________________________ -->
1878</ul><a name="i_va_copy"><h4><hr size=0>'<tt>llvm.va_copy</tt>' Intrinsic</h4><ul>
1879
1880<h5>Syntax:</h5>
1881<pre>
1882 call void (va_list*, va_list)* %va_copy(&lt;va_list&gt;* &lt;destarglist&gt;,
1883 &lt;va_list&gt; &lt;srcarglist&gt;)
1884</pre>
1885
1886<h5>Overview:</h5>
1887
1888The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position from
1889the source argument list to the destination argument list.<p>
1890
1891<h5>Arguments:</h5>
1892
1893The first argument is a pointer to a <tt>va_list</tt> element to initialize.
1894The second argument is a <tt>va_list</tt> element to copy from.<p>
1895
1896
1897<h5>Semantics:</h5>
1898
1899The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> macro
1900available in C. In a target-dependent way, it copies the source
1901<tt>va_list</tt> element into the destination list. This intrinsic is necessary
1902because the <tt><a href="i_va_begin">llvm.va_begin</a></tt> intrinsic may be
1903arbitrarily complex and require memory allocation, for example.<p>
Chris Lattner6536cfe2002-05-06 22:08:29 +0000[diff] [blame]1904
1905
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1906<!-- *********************************************************************** -->
1907</ul>
1908<!-- *********************************************************************** -->
1909
1910
1911<hr>
1912<font size=-1>
1913<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
1914<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
1915<!-- hhmts start -->
Chris Lattner25839f02003-10-10 05:01:39 +0000[diff] [blame]1916Last modified: Thu Oct 9 23:58:41 CDT 2003
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1917<!-- hhmts end -->
1918</font>
1919</body></html>