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