Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 2b7d320d90c8d7989d9c33bd6a6280fb3fd9d2c9 / . / docs / LangRef.html
blob: 86041a4d49f50ae1be99cc30c31d98c23f193fbb [file] [log] [blame]
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html><head><title>llvm Assembly Language Reference Manual</title></head>
3<body bgcolor=white>
4
5<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
6<tr><td>&nbsp; <font size=+5 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>llvm Assembly Language Reference Manual</b></font></td>
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>
25 <li><a href="#t_packed" >Packed Type</a>
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>
43 <li><a href="#unaryops">Unary Operations</a>
44 <ol>
45 <li><a href="#i_not" >'<tt>not</tt>' Instruction</a>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]46 </ol>
47 <li><a href="#binaryops">Binary Operations</a>
48 <ol>
49 <li><a href="#i_add" >'<tt>add</tt>' Instruction</a>
50 <li><a href="#i_sub" >'<tt>sub</tt>' Instruction</a>
51 <li><a href="#i_mul" >'<tt>mul</tt>' Instruction</a>
52 <li><a href="#i_div" >'<tt>div</tt>' Instruction</a>
53 <li><a href="#i_rem" >'<tt>rem</tt>' Instruction</a>
54 <li><a href="#i_setcc">'<tt>set<i>cc</i></tt>' Instructions</a>
55 </ol>
56 <li><a href="#bitwiseops">Bitwise Binary Operations</a>
57 <ol>
58 <li><a href="#i_and">'<tt>and</tt>' Instruction</a>
59 <li><a href="#i_or" >'<tt>or</tt>' Instruction</a>
60 <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a>
61 <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a>
62 <li><a href="#i_shr">'<tt>shr</tt>' Instruction</a>
63 </ol>
64 <li><a href="#memoryops">Memory Access Operations</a>
65 <ol>
66 <li><a href="#i_malloc" >'<tt>malloc</tt>' Instruction</a>
67 <li><a href="#i_free" >'<tt>free</tt>' Instruction</a>
68 <li><a href="#i_alloca" >'<tt>alloca</tt>' Instruction</a>
69 <li><a href="#i_load" >'<tt>load</tt>' Instruction</a>
70 <li><a href="#i_store" >'<tt>store</tt>' Instruction</a>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]71 <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]72 </ol>
73 <li><a href="#otherops">Other Operations</a>
74 <ol>
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]75 <li><a href="#i_cast">'<tt>cast .. to</tt>' Instruction</a>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]76 <li><a href="#i_call" >'<tt>call</tt>' Instruction</a>
77 <li><a href="#i_icall">'<tt>icall</tt>' Instruction</a>
78 <li><a href="#i_phi" >'<tt>phi</tt>' Instruction</a>
79 </ol>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]80 </ol>
81 <li><a href="#related">Related Work</a>
82</ol>
83
84
85<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]86<p><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
87<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]88<a name="abstract">Abstract
89</b></font></td></tr></table><ul>
90<!-- *********************************************************************** -->
91
92<blockquote>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]93 This document describes the LLVM assembly language. LLVM is an SSA based
94 representation that is a useful midlevel IR, providing type safety, low level
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]95 operations, flexibility, and the capability of representing 'all' high level
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]96 languages cleanly.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]97</blockquote>
98
99
100
101
102<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]103</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
104<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]105<a name="introduction">Introduction
106</b></font></td></tr></table><ul>
107<!-- *********************************************************************** -->
108
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]109The LLVM code representation is designed to be used in three different forms: as
110an in-memory compiler IR, as an on-disk bytecode representation, suitable for
111fast loading by a dynamic compiler, and as a human readable assembly language
112representation. This allows LLVM to provide a powerful intermediate
113representation for efficient compiler transformations and analysis, while
114providing a natural means to debug and visualize the transformations. The three
115different forms of LLVM are all equivalent. This document describes the human
116readable representation and notation.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]117
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]118The LLVM representation aims to be a light weight and low level while being
119expressive, type safe, and extensible at the same time. It aims to be a
120"universal IR" of sorts, by being at a low enough level that high level ideas
121may be cleanly mapped to it (similar to how microprocessors are "universal
122IR's", allowing many source languages to be mapped to them). By providing type
123safety, LLVM can be used as the target of optimizations: for example, through
124pointer analysis, it can be proven that a C automatic variable is never accessed
125outside of the current function... allowing it to be promoted to a simple SSA
126value instead of a memory location.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]127
128<!-- _______________________________________________________________________ -->
129</ul><a name="wellformed"><h4><hr size=0>Well Formedness</h4><ul>
130
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]131It is important to note that this document describes 'well formed' llvm assembly
132language. There is a difference between what the parser accepts and what is
133considered 'well formed'. For example, the following instruction is
134syntactically okay, but not well formed:<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]135
136<pre>
137 %x = <a href="#i_add">add</a> int 1, %x
138</pre>
139
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]140...because only a <tt><a href="#i_phi">phi</a></tt> node may refer to itself.
141The LLVM api provides a verification pass (created by the
142<tt>createVerifierPass</tt> function) that may be used to verify that an LLVM
143module is well formed. This pass is automatically run by the parser after
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]144parsing input assembly, and by the optimizer before it outputs bytecode. The
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]145violations pointed out by the verifier pass indicate bugs in transformation
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]146passes or input to the parser.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]147
148Describe the typesetting conventions here.
149
150
151<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]152</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
153<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]154<a name="identifiers">Identifiers
155</b></font></td></tr></table><ul>
156<!-- *********************************************************************** -->
157
158LLVM uses three different forms of identifiers, for different purposes:<p>
159
160<ol>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]161<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]162<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>'.
163<li>Unnamed values are represented as an unsigned numeric value with a '%' prefix. For example, %12, %2, %44.
164</ol><p>
165
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]166LLVM requires the values start with a '%' sign for two reasons: Compilers don't
167need to worry about name clashes with reserved words, and the set of reserved
168words may be expanded in the future without penalty. Additionally, unnamed
169identifiers allow a compiler to quickly come up with a temporary variable
170without having to avoid symbol table conflicts.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]171
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]172Reserved words in LLVM are very similar to reserved words in other languages.
173There are keywords for different opcodes ('<tt><a href="#i_add">add</a></tt>',
174'<tt><a href="#i_cast">cast</a></tt>', '<tt><a href="#i_ret">ret</a></tt>',
175etc...), for primitive type names ('<tt><a href="#t_void">void</a></tt>',
176'<tt><a href="#t_uint">uint</a></tt>', etc...), and others. These reserved
177words cannot conflict with variable names, because none of them start with a '%'
178character.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]179
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]180Here is an example of LLVM code to multiply the integer variable '<tt>%X</tt>'
181by 8:<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]182
183The easy way:
184<pre>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]185 %result = <a href="#i_mul">mul</a> uint %X, 8
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]186</pre>
187
188After strength reduction:
189<pre>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]190 %result = <a href="#i_shl">shl</a> uint %X, ubyte 3
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]191</pre>
192
193And the hard way:
194<pre>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]195 <a href="#i_add">add</a> uint %X, %X <i>; yields {int}:%0</i>
196 <a href="#i_add">add</a> uint %0, %0 <i>; yields {int}:%1</i>
197 %result = <a href="#i_add">add</a> uint %1, %1
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]198</pre>
199
200This last way of multiplying <tt>%X</tt> by 8 illustrates several important lexical features of LLVM:<p>
201
202<ol>
203<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]204<li>Unnamed temporaries are created when the result of a computation is not
205 assigned to a named value.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]206<li>Unnamed temporaries are numbered sequentially
207</ol><p>
208
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]209...and it also show a convention that we follow in this document. When
210demonstrating instructions, we will follow an instruction with a comment that
211defines the type and name of value produced. Comments are shown in italic
212text.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]213
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]214The one unintuitive notation for constants is the optional hexidecimal form of
215floating point constants. For example, the form '<tt>double
2160x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
2174.5e+15</tt>' which is also supported by the parser. The only time hexadecimal
218floating point constants are useful (and the only time that they are generated
219by the disassembler) is when an FP constant has to be emitted that is not
220representable as a decimal floating point number exactly. For example, NaN's,
221infinities, and other special cases are represented in their IEEE hexadecimal
222format so that assembly and disassembly do not cause any bits to change in the
223constants.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]224
225
226<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]227</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
228<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]229<a name="typesystem">Type System
230</b></font></td></tr></table><ul>
231<!-- *********************************************************************** -->
232
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]233The LLVM type system is one of the most important features of the intermediate
234representation. Being strongly typed enables a number of optimizations to be
235performed on the IR directly, without having to do extra analyses on the side
236before the transformation. A strong type system makes it easier to read the
237generated code and enables novel analyses and transformations that are not
238feasible to perform on normal three address code representations.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]239
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]240The written form for the type system was heavily influenced by the syntactic
241problems with types in the C language<sup><a
242href="#rw_stroustrup">1</a></sup>.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]243
244
245
246<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]247</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
248<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]249<a name="t_primitive">Primitive Types
250</b></font></td></tr></table><ul>
251
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]252The primitive types are the fundemental building blocks of the LLVM system. The
253current set of primitive types are as follows:<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]254
255<table border=0 align=center><tr><td>
256
257<table border=1 cellspacing=0 cellpadding=4 align=center>
258<tr><td><tt>void</tt></td> <td>No value</td></tr>
259<tr><td><tt>ubyte</tt></td> <td>Unsigned 8 bit value</td></tr>
260<tr><td><tt>ushort</tt></td><td>Unsigned 16 bit value</td></tr>
261<tr><td><tt>uint</tt></td> <td>Unsigned 32 bit value</td></tr>
262<tr><td><tt>ulong</tt></td> <td>Unsigned 64 bit value</td></tr>
263<tr><td><tt>float</tt></td> <td>32 bit floating point value</td></tr>
264<tr><td><tt>label</tt></td> <td>Branch destination</td></tr>
265</table>
266
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]267</td><td valign=top>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]268
269<table border=1 cellspacing=0 cellpadding=4 align=center>
270<tr><td><tt>bool</tt></td> <td>True or False value</td></tr>
271<tr><td><tt>sbyte</tt></td> <td>Signed 8 bit value</td></tr>
272<tr><td><tt>short</tt></td> <td>Signed 16 bit value</td></tr>
273<tr><td><tt>int</tt></td> <td>Signed 32 bit value</td></tr>
274<tr><td><tt>long</tt></td> <td>Signed 64 bit value</td></tr>
275<tr><td><tt>double</tt></td><td>64 bit floating point value</td></tr>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]276</table>
277
278</td></tr></table><p>
279
280
281
282<!-- _______________________________________________________________________ -->
283</ul><a name="t_classifications"><h4><hr size=0>Type Classifications</h4><ul>
284
285These different primitive types fall into a few useful classifications:<p>
286
287<table border=1 cellspacing=0 cellpadding=4 align=center>
288<tr><td><a name="t_signed">signed</td> <td><tt>sbyte, short, int, long, float, double</tt></td></tr>
289<tr><td><a name="t_unsigned">unsigned</td><td><tt>ubyte, ushort, uint, ulong</tt></td></tr>
290<tr><td><a name="t_integral">integral</td><td><tt>ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td></tr>
291<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^]292<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]293</table><p>
294
295
296
297
298
299<!-- ======================================================================= -->
300</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>
301<a name="t_derived">Derived Types
302</b></font></td></tr></table><ul>
303
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]304The real power in LLVM comes from the derived types in the system. This is what
305allows a programmer to represent arrays, functions, pointers, and other useful
306types. Note that these derived types may be recursive: For example, it is
307possible to have a two dimensional array.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]308
309
310
311<!-- _______________________________________________________________________ -->
312</ul><a name="t_array"><h4><hr size=0>Array Type</h4><ul>
313
314<h5>Overview:</h5>
315
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]316The array type is a very simple derived type that arranges elements sequentially
317in memory. The array type requires a size (number of elements) and an
318underlying data type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]319
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]320<h5>Syntax:</h5>
321<pre>
322 [&lt;# elements&gt; x &lt;elementtype&gt;]
323</pre>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]324
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]325The number of elements is a constant integer value, elementtype may be any type
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]326with a size.<p>
327
328<h5>Examples:</h5>
329<ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]330 <tt>[40 x int ]</tt>: Array of 40 integer values.<br>
331 <tt>[41 x int ]</tt>: Array of 41 integer values.<br>
332 <tt>[40 x uint]</tt>: Array of 40 unsigned integer values.<p>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]333</ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]334
335Here are some examples of multidimensional arrays:<p>
336<ul>
337<table border=0 cellpadding=0 cellspacing=0>
338<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]339<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]340<tr><td><tt>[2 x [3 x [4 x uint]]]</tt></td><td>: 2x3x4 array of unsigned integer values.</td></tr>
341</table>
342</ul>
343
344
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]345<!-- _______________________________________________________________________ -->
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]346</ul><a name="t_function"><h4><hr size=0>Function Type</h4><ul>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]347
348<h5>Overview:</h5>
349
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]350The function type can be thought of as a function signature. It consists of a
351return type and a list of formal parameter types. Function types are usually
352used when to build virtual function tables (which are structures of pointers to
353functions), for indirect function calls, and when defining a function.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]354
355<h5>Syntax:</h5>
356<pre>
357 &lt;returntype&gt; (&lt;parameter list&gt;)
358</pre>
359
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]360Where '<tt>&lt;parameter list&gt;</tt>' is a comma seperated list of type
361specifiers. Optionally, the parameter list may include a type <tt>...</tt>,
362which indicates that the function takes a variable number of arguments. Note
363that there currently is no way to define a function in LLVM that takes a
364variable number of arguments, but it is possible to <b>call</b> a function that
365is vararg.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]366
367<h5>Examples:</h5>
368<ul>
369<table border=0 cellpadding=0 cellspacing=0>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]370
371<tr><td><tt>int (int)</tt></td><td>: function taking an <tt>int</tt>, returning
372an <tt>int</tt></td></tr>
373
374<tr><td><tt>float (int, int *) *</tt></td><td>: <a href="#t_pointer">Pointer</a>
375to a function that takes an <tt>int</tt> and a <a href="#t_pointer">pointer</a>
376to <tt>int</tt>, returning <tt>float</tt>.</td></tr>
377
378<tr><td><tt>int (sbyte *, ...)</tt></td><td>: A vararg function that takes at
379least one <a href="#t_pointer">pointer</a> to <tt>sbyte</tt> (signed char in C),
380which returns an integer. This is the signature for <tt>printf</tt> in
381LLVM.</td></tr>
382
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]383</table>
384</ul>
385
386
387
388<!-- _______________________________________________________________________ -->
389</ul><a name="t_struct"><h4><hr size=0>Structure Type</h4><ul>
390
391<h5>Overview:</h5>
392
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]393The structure type is used to represent a collection of data members together in
394memory. Although the runtime is allowed to lay out the data members any way
395that it would like, they are guaranteed to be "close" to each other.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]396
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]397Structures are accessed using '<tt><a href="#i_load">load</a></tt> and '<tt><a
398href="#i_store">store</a></tt>' by getting a pointer to a field with the '<tt><a
399href="#i_getelementptr">getelementptr</a></tt>' instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]400
401<h5>Syntax:</h5>
402<pre>
403 { &lt;type list&gt; }
404</pre>
405
406
407<h5>Examples:</h5>
408<table border=0 cellpadding=0 cellspacing=0>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]409
410<tr><td><tt>{ int, int, int }</tt></td><td>: a triple of three <tt>int</tt>
411values</td></tr>
412
413<tr><td><tt>{ float, int (int *) * }</tt></td><td>: A pair, where the first
414element is a <tt>float</tt> and the second element is a <a
415href="#t_pointer">pointer</a> to a <a href="t_function">function</a> that takes
416an <tt>int</tt>, returning an <tt>int</tt>.</td></tr>
417
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]418</table>
419
420
421<!-- _______________________________________________________________________ -->
422</ul><a name="t_pointer"><h4><hr size=0>Pointer Type</h4><ul>
423
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]424<h5>Overview:</h5>
425
426As in many languages, the pointer type represents a pointer or reference to
427another object, which must live in memory.<p>
428
429<h5>Syntax:</h5>
430<pre>
431 &lt;type&gt; *
432</pre>
433
434<h5>Examples:</h5>
435
436<table border=0 cellpadding=0 cellspacing=0>
437
438<tr><td><tt>[4x int]*</tt></td><td>: <a href="#t_pointer">pointer</a> to <a
439href="#t_array">array</a> of four <tt>int</tt> values</td></tr>
440
441<tr><td><tt>int (int *) *</tt></td><td>: A <a href="#t_pointer">pointer</a> to a
442<a href="t_function">function</a> that takes an <tt>int</tt>, returning an
443<tt>int</tt>.</td></tr>
444
445</table>
446<p>
447
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]448
449<!-- _______________________________________________________________________ -->
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]450<!--
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]451</ul><a name="t_packed"><h4><hr size=0>Packed Type</h4><ul>
452
453Mention/decide that packed types work with saturation or not. Maybe have a packed+saturated type in addition to just a packed type.<p>
454
455Packed types should be 'nonsaturated' because standard data types are not saturated. Maybe have a saturated packed type?<p>
456
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]457-->
458
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]459
460<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]461</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
462<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]463<a name="highlevel">High Level Structure
464</b></font></td></tr></table><ul>
465<!-- *********************************************************************** -->
466
467
468<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]469</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
470<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]471<a name="modulestructure">Module Structure
472</b></font></td></tr></table><ul>
473
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]474LLVM programs are composed of "Module"s, each of which is a translation unit of
475the input programs. Each module consists of functions, global variables, and
476symbol table entries. Modules may be combined together with the LLVM linker,
477which merges function (and global variable) definitions, resolves forward
478declarations, 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]479
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]480<pre>
481<i>; Declare the string constant as a global constant...</i>
482<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>
483
484<i>; Forward declaration of puts</i>
485<a href="#functionstructure">declare</a> int "puts"(sbyte*) <i>; int(sbyte*)* </i>
486
487<i>; Definition of main function</i>
488int "main"() { <i>; int()* </i>
489 <i>; Convert [13x sbyte]* to sbyte *...</i>
490 %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, uint 0, uint 0 <i>; sbyte*</i>
491
492 <i>; Call puts function to write out the string to stdout...</i>
493 <a href="#i_call">call</a> int %puts(sbyte* %cast210) <i>; int</i>
494 <a href="#i_ret">ret</a> int 0
495}
496</pre>
497
498This example is made up of a <a href="#globalvars">global variable</a> named
499"<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, and a
500<a href="#functionstructure">function definition</a> for "<tt>main</tt>".<p>
501
502<a name="linkage_decl">
503In general, a module is made up of a list of global values, where both functions
504and global variables are global values. Global values are represented by a
505pointer to a memory location (in this case, a pointer to an array of char, and a
506pointer to a function), and can be either "internal" or externally accessible
507(which corresponds to the static keyword in C, when used at function scope).<p>
508
509For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
510another module defined a "<tt>.LC0</tt>" variable and was linked with this one,
511one of the two would be renamed, preventing a collision. Since "<tt>main</tt>"
512and "<tt>puts</tt>" are external (lacking "<tt>internal</tt>" declarations),
513they are accessible outside of the current module. It is illegal for a function
514declaration to be "<tt>internal</tt>".<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]515
516
517<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]518</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
519<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
520<a name="globalvars">Global Variables
521</b></font></td></tr></table><ul>
522
523Global variables define regions of memory allocated at compilation time instead
524of runtime. Global variables, may optionally be initialized. A variable may be
525defined as a global "constant", which indicates that the contents of the
526variable will never be modified (opening options for optimization). Constants
527must always have an initial value.<p>
528
529As SSA values, global variables define pointer values that are in scope in
530(i.e. they dominate) all basic blocks in the program. Global variables always
531define a pointer to their "content" type because they describe a region of
532memory, and all memory objects in LLVM are accessed through pointers.<p>
533
534
535
536<!-- ======================================================================= -->
537</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
538<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]539<a name="functionstructure">Function Structure
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]540</b></font></td></tr></table><ul>
541
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]542LLVM functions definitions are composed of a (possibly empty) argument list, an
543opening curly brace, a list of basic blocks, and a closing curly brace. LLVM
544function declarations are defined with the "<tt>declare</tt>" keyword, a
545function name and a function signature.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]546
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]547A function definition contains a list of basic blocks, forming the CFG for the
548function. Each basic block may optionally start with a label (giving the basic
549block a symbol table entry), contains a list of instructions, and ends with a <a
550href="#terminators">terminator</a> instruction (such as a branch or function
551return).<p>
552
553The first basic block in program is special in two ways: it is immediately
554executed on entrance to the function, and it is not allowed to have predecessor
555basic blocks (i.e. there can not be any branches to the entry block of a
556function).<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]557
558
559<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]560</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
561<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]562<a name="instref">Instruction Reference
563</b></font></td></tr></table><ul>
564<!-- *********************************************************************** -->
565
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]566The LLVM instruction set consists of several different classifications of
567instructions: <a href="#terminators">terminator instructions</a>, a <a
568href="#unaryops">unary instruction</a>, <a href="#binaryops">binary
569instructions</a>, <a href="#memoryops">memory instructions</a>, and <a
570href="#otherops">other instructions</a>.<p>
571
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]572
573<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]574</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
575<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]576<a name="terminators">Terminator Instructions
577</b></font></td></tr></table><ul>
578
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]579As mentioned <a href="#functionstructure">previously</a>, every basic block in a
580program ends with a "Terminator" instruction, which indicates where control flow
581should go now that this basic block has been completely executed. These
582terminator instructions typically yield a '<tt>void</tt>' value: they produce
583control flow, not values (the one exception being the '<a
584href="#i_invoke"><tt>invoke</tt></a>' instruction).<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]585
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]586There are four different terminator instructions: the '<a
587href="#i_ret"><tt>ret</tt></a>' instruction, the '<a
588href="#i_br"><tt>br</tt></a>' instruction, the '<a
589href="#i_switch"><tt>switch</tt></a>' instruction, and the '<a
590href="#i_invoke"><tt>invoke</tt></a>' instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]591
592
593<!-- _______________________________________________________________________ -->
594</ul><a name="i_ret"><h4><hr size=0>'<tt>ret</tt>' Instruction</h4><ul>
595
596<h5>Syntax:</h5>
597<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]598 ret &lt;type&gt; &lt;value&gt; <i>; Return a value from a non-void function</i>
599 ret void <i>; Return from void function</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]600</pre>
601
602<h5>Overview:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]603
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]604The '<tt>ret</tt>' instruction is used to return control flow (and a value) from
605a function, back to the caller.<p>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]606
607There are two forms of the '<tt>ret</tt>' instructruction: one that returns a
608value and then causes control flow, and one that just causes control flow to
609occur.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]610
611<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]612
613The '<tt>ret</tt>' instruction may return any '<a href="#t_firstclass">first
614class</a>' type. Notice that a function is not <a href="#wellformed">well
615formed</a> if there exists a '<tt>ret</tt>' instruction inside of the function
616that returns a value that does not match the return type of the function.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]617
618<h5>Semantics:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]619
620When the '<tt>ret</tt>' instruction is executed, control flow returns back to
621the calling function's context. If the instruction returns a value, that value
622shall be propogated into the calling function's data space.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]623
624<h5>Example:</h5>
625<pre>
626 ret int 5 <i>; Return an integer value of 5</i>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]627 ret void <i>; Return from a void function</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]628</pre>
629
630
631<!-- _______________________________________________________________________ -->
632</ul><a name="i_br"><h4><hr size=0>'<tt>br</tt>' Instruction</h4><ul>
633
634<h5>Syntax:</h5>
635<pre>
636 br bool &lt;cond&gt;, label &lt;iftrue&gt;, label &lt;iffalse&gt;
637 br label &lt;dest&gt; <i>; Unconditional branch</i>
638</pre>
639
640<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]641
642The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
643different basic block in the current function. There are two forms of this
644instruction, corresponding to a conditional branch and an unconditional
645branch.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]646
647<h5>Arguments:</h5>
648
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]649The conditional branch form of the '<tt>br</tt>' instruction takes a single
650'<tt>bool</tt>' value and two '<tt>label</tt>' values. The unconditional form
651of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
652target.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]653
654<h5>Semantics:</h5>
655
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]656Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>bool</tt>'
657argument is evaluated. If the value is <tt>true</tt>, control flows to the
658'<tt>iftrue</tt>' '<tt>label</tt>' argument. If "cond" is <tt>false</tt>,
659control flows to the '<tt>iffalse</tt>' '<tt>label</tt>' argument.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]660
661<h5>Example:</h5>
662<pre>
663Test:
664 %cond = <a href="#i_setcc">seteq</a> int %a, %b
665 br bool %cond, label %IfEqual, label %IfUnequal
666IfEqual:
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]667 <a href="#i_ret">ret</a> int 1
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]668IfUnequal:
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]669 <a href="#i_ret">ret</a> int 0
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]670</pre>
671
672
673<!-- _______________________________________________________________________ -->
674</ul><a name="i_switch"><h4><hr size=0>'<tt>switch</tt>' Instruction</h4><ul>
675
676<h5>Syntax:</h5>
677<pre>
678 <i>; Definitions for lookup indirect branch</i>
679 %switchtype = type [&lt;anysize&gt; x { uint, label }]
680
681 <i>; Lookup indirect branch</i>
682 switch uint &lt;value&gt;, label &lt;defaultdest&gt;, %switchtype &lt;switchtable&gt;
683
684 <i>; Indexed indirect branch</i>
685 switch uint &lt;idxvalue&gt;, label &lt;defaultdest&gt;, [&lt;anysize&gt; x label] &lt;desttable&gt;
686</pre>
687
688<h5>Overview:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]689
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]690The '<tt>switch</tt>' instruction is used to transfer control flow to one of
691several different places. It is a generalization of the '<tt>br</tt>'
692instruction, allowing a branch to occur to one of many possible destinations.<p>
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>' statement supports two different styles of indirect
695branching: lookup branching and indexed branching. Lookup branching is
696generally useful if the values to switch on are spread far appart, where index
697branching is useful if the values to switch on are generally dense.<p>
698
699The two different forms of the '<tt>switch</tt>' statement are simple hints to
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]700the underlying implementation. For example, the compiler may choose to
701implement a small indirect branch table as a series of predicated comparisons:
702if it is faster for the target architecture.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]703
704<h5>Arguments:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]705
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]706The lookup form of the '<tt>switch</tt>' instruction uses three parameters: a
707'<tt>uint</tt>' comparison value '<tt>value</tt>', a default '<tt>label</tt>'
708destination, and an array of pairs of comparison value constants and
709'<tt>label</tt>'s. The sized array must be a constant value.<p>
710
711The indexed form of the '<tt>switch</tt>' instruction uses three parameters: an
712'<tt>uint</tt>' index value, a default '<tt>label</tt>' and a sized array of
713'<tt>label</tt>'s. The '<tt>dests</tt>' array must be a constant array.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]714
715<h5>Semantics:</h5>
716
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]717The lookup style switch statement specifies a table of values and destinations.
718When the '<tt>switch</tt>' instruction is executed, this table is searched for
719the given value. If the value is found, the corresponding destination is
720branched to. <p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]721
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]722The index branch form simply looks up a label element directly in a table and
723branches to it.<p>
724
725In either case, the compiler knows the static size of the array, because it is
726provided as part of the constant values type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]727
728<h5>Example:</h5>
729<pre>
730 <i>; Emulate a conditional br instruction</i>
731 %Val = <a href="#i_cast">cast</a> bool %value to uint
732 switch uint %Val, label %truedest, [1 x label] [label %falsedest ]
733
734 <i>; Emulate an unconditional br instruction</i>
735 switch uint 0, label %dest, [ 0 x label] [ ]
736
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]737 <i>; Implement a jump table:</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]738 switch uint %val, label %otherwise, [3 x label] [ label %onzero,
739 label %onone,
740 label %ontwo ]
741
742</pre>
743
744
745
746<!-- _______________________________________________________________________ -->
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]747</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]748
749<h5>Syntax:</h5>
750<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]751 &lt;result&gt; = invoke &lt;ptr to function ty&gt; %&lt;function ptr val&gt;(&lt;function args&gt;)
752 to label &lt;normal label&gt; except label &lt;exception label&gt;
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]753</pre>
754
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]755<h5>Overview:</h5> The '<tt>invoke</tt>' instruction is used to cause control
756flow to transfer to a specified function, with the possibility of control flow
757transfer to either the '<tt>normal label</tt>' label or the '<tt>exception
758label</tt>'. The '<tt><a href="#i_call">call</a></tt>' instruction is closely
759related, but guarantees that control flow either never returns from the called
760function, or that it returns to the instruction succeeding the '<tt><a
761href="#i_call">call</a></tt>' instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]762
763<h5>Arguments:</h5>
764
765This instruction requires several arguments:<p>
766<ol>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]767
768<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^]769function value being invoked. In most cases, this is a direct function
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]770invocation, but indirect <tt>invoke</tt>'s are just as possible, branching off
771an arbitrary pointer to function value.<p>
772
773<li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
774function to be invoked.
775
776<li>'<tt>function args</tt>': argument list whose types match the function
777signature argument types.
778
779<li>'<tt>normal label</tt>': the label reached when the called function executes
780a '<tt><a href="#i_ret">ret</a></tt>' instruction.
781
782<li>'<tt>exception label</tt>': the label reached when an exception is thrown.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]783</ol>
784
785<h5>Semantics:</h5>
786
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]787This instruction is designed to operate as a standard '<tt><a
788href="#i_call">call</a></tt>' instruction in most regards. The primary
789difference is that it associates a label with the function invocation that may
790be accessed via the runtime library provided by the execution environment. This
791instruction is used in languages with destructors to ensure that proper cleanup
792is performed in the case of either a <tt>longjmp</tt> or a thrown exception.
793Additionally, this is important for implementation of '<tt>catch</tt>' clauses
794in high-level languages that support them.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]795
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]796For a more comprehensive explanation of this instruction look in the llvm/docs/2001-05-18-ExceptionHandling.txt document.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]797
798<h5>Example:</h5>
799<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]800 %retval = invoke int %Test(int 15)
801 to label %Continue except label %TestCleanup <i>; {int}:retval set</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]802</pre>
803
804
805
806<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]807</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
808<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]809<a name="unaryops">Unary Operations
810</b></font></td></tr></table><ul>
811
812Unary operators are used to do a simple operation to a single value.<p>
813
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]814There is only one unary operator: the '<a href="#i_not"><tt>not</tt></a>' instruction.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]815
816
817<!-- _______________________________________________________________________ -->
818</ul><a name="i_not"><h4><hr size=0>'<tt>not</tt>' Instruction</h4><ul>
819
820<h5>Syntax:</h5>
821<pre>
822 &lt;result&gt; = not &lt;ty&gt; &lt;var&gt; <i>; yields {ty}:result</i>
823</pre>
824
825<h5>Overview:</h5>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]826The '<tt>not</tt>' instruction returns the bitwise complement of its operand.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]827
828<h5>Arguments:</h5>
829The single argument to '<tt>not</tt>' must be of of <a href="#t_integral">integral</a> type.<p>
830
831
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]832<h5>Semantics:</h5> The '<tt>not</tt>' instruction returns the bitwise
833complement (AKA ones complement) of an <a href="#t_integral">integral</a>
834type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]835
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]836<pre>
837 &lt;result&gt; = xor bool true, &lt;var&gt; <i>; yields {bool}:result</i>
838</pre>
839
840<h5>Example:</h5>
841<pre>
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]842 %x = not int 1 <i>; {int}:x is now equal to -2</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]843 %x = not bool true <i>; {bool}:x is now equal to false</i>
844</pre>
845
846
847
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]848<!-- ======================================================================= -->
849</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>
850<a name="binaryops">Binary Operations
851</b></font></td></tr></table><ul>
852
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]853Binary operators are used to do most of the computation in a program. They
854require two operands, execute an operation on them, and produce a single value.
855The result value of a binary operator is not neccesarily the same type as its
856operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]857
858There are several different binary operators:<p>
859
860
861<!-- _______________________________________________________________________ -->
862</ul><a name="i_add"><h4><hr size=0>'<tt>add</tt>' Instruction</h4><ul>
863
864<h5>Syntax:</h5>
865<pre>
866 &lt;result&gt; = add &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
867</pre>
868
869<h5>Overview:</h5>
870The '<tt>add</tt>' instruction returns the sum of its two operands.<p>
871
872<h5>Arguments:</h5>
873The two arguments to the '<tt>add</tt>' instruction must be either <a href="#t_integral">integral</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
874
875<h5>Semantics:</h5>
876...<p>
877
878<h5>Example:</h5>
879<pre>
880 &lt;result&gt; = add int 4, %var <i>; yields {int}:result = 4 + %var</i>
881</pre>
882
883
884<!-- _______________________________________________________________________ -->
885</ul><a name="i_sub"><h4><hr size=0>'<tt>sub</tt>' Instruction</h4><ul>
886
887<h5>Syntax:</h5>
888<pre>
889 &lt;result&gt; = sub &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
890</pre>
891
892<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]893
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]894The '<tt>sub</tt>' instruction returns the difference of its two operands.<p>
895
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]896Note that the '<tt>sub</tt>' instruction is used to represent the '<tt>neg</tt>'
897instruction present in most other intermediate representations.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]898
899<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]900
901The two arguments to the '<tt>sub</tt>' instruction must be either <a
902href="#t_integral">integral</a> or <a href="#t_floating">floating point</a>
903values. Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]904
905<h5>Semantics:</h5>
906...<p>
907
908<h5>Example:</h5>
909<pre>
910 &lt;result&gt; = sub int 4, %var <i>; yields {int}:result = 4 - %var</i>
911 &lt;result&gt; = sub int 0, %val <i>; yields {int}:result = -%var</i>
912</pre>
913
914<!-- _______________________________________________________________________ -->
915</ul><a name="i_mul"><h4><hr size=0>'<tt>mul</tt>' Instruction</h4><ul>
916
917<h5>Syntax:</h5>
918<pre>
919 &lt;result&gt; = mul &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
920</pre>
921
922<h5>Overview:</h5>
923The '<tt>mul</tt>' instruction returns the product of its two operands.<p>
924
925<h5>Arguments:</h5>
926The two arguments to the '<tt>mul</tt>' instruction must be either <a href="#t_integral">integral</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
927
928<h5>Semantics:</h5>
929...<p>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]930
931There is no signed vs unsigned multiplication. The appropriate action is taken
932based on the type of the operand. <p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]933
934
935<h5>Example:</h5>
936<pre>
937 &lt;result&gt; = mul int 4, %var <i>; yields {int}:result = 4 * %var</i>
938</pre>
939
940
941<!-- _______________________________________________________________________ -->
942</ul><a name="i_div"><h4><hr size=0>'<tt>div</tt>' Instruction</h4><ul>
943
944<h5>Syntax:</h5>
945<pre>
946 &lt;result&gt; = div &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
947</pre>
948
949<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]950
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]951The '<tt>div</tt>' instruction returns the quotient of its two operands.<p>
952
953<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]954
955The two arguments to the '<tt>div</tt>' instruction must be either <a
956href="#t_integral">integral</a> or <a href="#t_floating">floating point</a>
957values. Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]958
959<h5>Semantics:</h5>
960...<p>
961
962<h5>Example:</h5>
963<pre>
964 &lt;result&gt; = div int 4, %var <i>; yields {int}:result = 4 / %var</i>
965</pre>
966
967
968<!-- _______________________________________________________________________ -->
969</ul><a name="i_rem"><h4><hr size=0>'<tt>rem</tt>' Instruction</h4><ul>
970
971<h5>Syntax:</h5>
972<pre>
973 &lt;result&gt; = rem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
974</pre>
975
976<h5>Overview:</h5>
977The '<tt>rem</tt>' instruction returns the remainder from the division of its two operands.<p>
978
979<h5>Arguments:</h5>
980The two arguments to the '<tt>rem</tt>' instruction must be either <a href="#t_integral">integral</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
981
982<h5>Semantics:</h5>
983TODO: remainder or modulus?<p>
984...<p>
985
986<h5>Example:</h5>
987<pre>
988 &lt;result&gt; = rem int 4, %var <i>; yields {int}:result = 4 % %var</i>
989</pre>
990
991
992<!-- _______________________________________________________________________ -->
993</ul><a name="i_setcc"><h4><hr size=0>'<tt>set<i>cc</i></tt>' Instructions</h4><ul>
994
995<h5>Syntax:</h5>
996<pre>
997 &lt;result&gt; = seteq &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
998 &lt;result&gt; = setne &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
999 &lt;result&gt; = setlt &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1000 &lt;result&gt; = setgt &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1001 &lt;result&gt; = setle &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1002 &lt;result&gt; = setge &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {bool}:result</i>
1003</pre>
1004
1005<h5>Overview:</h5>
1006The '<tt>set<i>cc</i></tt>' family of instructions returns a boolean value based on a comparison of their two operands.<p>
1007
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1008<h5>Arguments:</h5> The two arguments to the '<tt>set<i>cc</i></tt>'
1009instructions must be of <a href="#t_firstclass">first class</a> or <a
1010href="#t_pointer">pointer</a> type (it is not possible to compare
1011'<tt>label</tt>'s, '<tt>array</tt>'s, '<tt>structure</tt>' or '<tt>void</tt>'
1012values). Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1013
1014The '<tt>setlt</tt>', '<tt>setgt</tt>', '<tt>setle</tt>', and '<tt>setge</tt>' instructions do not operate on '<tt>bool</tt>' typed arguments.<p>
1015
1016<h5>Semantics:</h5>
1017The '<tt>seteq</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if both operands are equal.<br>
1018The '<tt>setne</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if both operands are unequal.<br>
1019The '<tt>setlt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if the first operand is less than the second operand.<br>
1020The '<tt>setgt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if the first operand is greater than the second operand.<br>
1021The '<tt>setle</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if the first operand is less than or equal to the second operand.<br>
1022The '<tt>setge</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if the first operand is greater than or equal to the second operand.<p>
1023
1024<h5>Example:</h5>
1025<pre>
1026 &lt;result&gt; = seteq int 4, 5 <i>; yields {bool}:result = false</i>
1027 &lt;result&gt; = setne float 4, 5 <i>; yields {bool}:result = true</i>
1028 &lt;result&gt; = setlt uint 4, 5 <i>; yields {bool}:result = true</i>
1029 &lt;result&gt; = setgt sbyte 4, 5 <i>; yields {bool}:result = false</i>
1030 &lt;result&gt; = setle sbyte 4, 5 <i>; yields {bool}:result = true</i>
1031 &lt;result&gt; = setge sbyte 4, 5 <i>; yields {bool}:result = false</i>
1032</pre>
1033
1034
1035
1036<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]1037</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1038<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]1039<a name="bitwiseops">Bitwise Binary Operations
1040</b></font></td></tr></table><ul>
1041
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]1042Bitwise binary operators are used to do various forms of bit-twiddling in a
1043program. They are generally very efficient instructions, and can commonly be
1044strength reduced from other instructions. They require two operands, execute an
1045operation on them, and produce a single value. The resulting value of the
1046bitwise binary operators is always the same type as its first operand.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1047
1048<!-- _______________________________________________________________________ -->
1049</ul><a name="i_and"><h4><hr size=0>'<tt>and</tt>' Instruction</h4><ul>
1050
1051<h5>Syntax:</h5>
1052<pre>
1053 &lt;result&gt; = and &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1054</pre>
1055
1056<h5>Overview:</h5>
1057The '<tt>and</tt>' instruction returns the bitwise logical and of its two operands.<p>
1058
1059<h5>Arguments:</h5>
1060The two arguments to the '<tt>and</tt>' instruction must be either <a href="#t_integral">integral</a> or <a href="#t_bool"><tt>bool</tt></a> values. Both arguments must have identical types.<p>
1061
1062
1063<h5>Semantics:</h5>
1064...<p>
1065
1066
1067<h5>Example:</h5>
1068<pre>
1069 &lt;result&gt; = and int 4, %var <i>; yields {int}:result = 4 & %var</i>
1070 &lt;result&gt; = and int 15, 40 <i>; yields {int}:result = 8</i>
1071 &lt;result&gt; = and int 4, 8 <i>; yields {int}:result = 0</i>
1072</pre>
1073
1074
1075
1076<!-- _______________________________________________________________________ -->
1077</ul><a name="i_or"><h4><hr size=0>'<tt>or</tt>' Instruction</h4><ul>
1078
1079<h5>Syntax:</h5>
1080<pre>
1081 &lt;result&gt; = or &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1082</pre>
1083
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1084<h5>Overview:</h5> The '<tt>or</tt>' instruction returns the bitwise logical
1085inclusive or of its two operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1086
1087<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1088
1089The two arguments to the '<tt>or</tt>' instruction must be either <a
1090href="#t_integral">integral</a> or <a href="#t_bool"><tt>bool</tt></a> values.
1091Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1092
1093
1094<h5>Semantics:</h5>
1095...<p>
1096
1097
1098<h5>Example:</h5>
1099<pre>
1100 &lt;result&gt; = or int 4, %var <i>; yields {int}:result = 4 | %var</i>
1101 &lt;result&gt; = or int 15, 40 <i>; yields {int}:result = 47</i>
1102 &lt;result&gt; = or int 4, 8 <i>; yields {int}:result = 12</i>
1103</pre>
1104
1105
1106<!-- _______________________________________________________________________ -->
1107</ul><a name="i_xor"><h4><hr size=0>'<tt>xor</tt>' Instruction</h4><ul>
1108
1109<h5>Syntax:</h5>
1110<pre>
1111 &lt;result&gt; = xor &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt; <i>; yields {ty}:result</i>
1112</pre>
1113
1114<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1115
1116The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of its
1117two operands.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1118
1119<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1120
1121The two arguments to the '<tt>xor</tt>' instruction must be either <a
1122href="#t_integral">integral</a> or <a href="#t_bool"><tt>bool</tt></a> values.
1123Both arguments must have identical types.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1124
1125
1126<h5>Semantics:</h5>
1127...<p>
1128
1129
1130<h5>Example:</h5>
1131<pre>
1132 &lt;result&gt; = xor int 4, %var <i>; yields {int}:result = 4 ^ %var</i>
1133 &lt;result&gt; = xor int 15, 40 <i>; yields {int}:result = 39</i>
1134 &lt;result&gt; = xor int 4, 8 <i>; yields {int}:result = 12</i>
1135</pre>
1136
1137
1138<!-- _______________________________________________________________________ -->
1139</ul><a name="i_shl"><h4><hr size=0>'<tt>shl</tt>' Instruction</h4><ul>
1140
1141<h5>Syntax:</h5>
1142<pre>
1143 &lt;result&gt; = shl &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt; <i>; yields {ty}:result</i>
1144</pre>
1145
1146<h5>Overview:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1147
1148The '<tt>shl</tt>' instruction returns the first operand shifted to the left a
1149specified number of bits.
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1150
1151<h5>Arguments:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1152
1153The first argument to the '<tt>shl</tt>' instruction must be an <a
1154href="#t_integral">integral</a> type. The second argument must be an
1155'<tt>ubyte</tt>' type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1156
1157<h5>Semantics:</h5>
1158... 0 bits are shifted into the emptied bit positions...<p>
1159
1160
1161<h5>Example:</h5>
1162<pre>
1163 &lt;result&gt; = shl int 4, ubyte %var <i>; yields {int}:result = 4 << %var</i>
1164 &lt;result&gt; = shl int 4, ubyte 2 <i>; yields {int}:result = 16</i>
1165 &lt;result&gt; = shl int 1, ubyte 10 <i>; yields {int}:result = 1024</i>
1166</pre>
1167
1168
1169<!-- _______________________________________________________________________ -->
1170</ul><a name="i_shr"><h4><hr size=0>'<tt>shr</tt>' Instruction</h4><ul>
1171
1172
1173<h5>Syntax:</h5>
1174<pre>
1175 &lt;result&gt; = shr &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt; <i>; yields {ty}:result</i>
1176</pre>
1177
1178<h5>Overview:</h5>
1179The '<tt>shr</tt>' instruction returns the first operand shifted to the right a specified number of bits.
1180
1181<h5>Arguments:</h5>
1182The first argument to the '<tt>shr</tt>' instruction must be an <a href="#t_integral">integral</a> type. The second argument must be an '<tt>ubyte</tt>' type.<p>
1183
1184<h5>Semantics:</h5>
1185... if the first argument is a <a href="#t_signed">signed</a> type, the most significant bit is duplicated in the newly free'd bit positions. If the first argument is unsigned, zeros shall fill the empty positions...<p>
1186
1187<h5>Example:</h5>
1188<pre>
1189 &lt;result&gt; = shr int 4, ubyte %var <i>; yields {int}:result = 4 >> %var</i>
1190 &lt;result&gt; = shr int 4, ubyte 1 <i>; yields {int}:result = 2</i>
1191 &lt;result&gt; = shr int 4, ubyte 2 <i>; yields {int}:result = 1</i>
1192 &lt;result&gt; = shr int 4, ubyte 3 <i>; yields {int}:result = 0</i>
1193</pre>
1194
1195
1196
1197
1198
1199<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]1200</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1201<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]1202<a name="memoryops">Memory Access Operations
1203</b></font></td></tr></table><ul>
1204
1205Accessing memory in SSA form is, well, sticky at best. This section describes how to read and write memory in LLVM.<p>
1206
1207
1208<!-- _______________________________________________________________________ -->
1209</ul><a name="i_malloc"><h4><hr size=0>'<tt>malloc</tt>' Instruction</h4><ul>
1210
1211<h5>Syntax:</h5>
1212<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1213 &lt;result&gt; = malloc &lt;type&gt;, uint &lt;NumElements&gt; <i>; yields {type*}:result</i>
1214 &lt;result&gt; = malloc &lt;type&gt; <i>; yields {type*}:result</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1215</pre>
1216
1217<h5>Overview:</h5>
1218The '<tt>malloc</tt>' instruction allocates memory from the system heap and returns a pointer to it.<p>
1219
1220<h5>Arguments:</h5>
1221
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1222The the '<tt>malloc</tt>' instruction allocates
1223<tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory from the operating
1224system, and returns a pointer of the appropriate type to the program. The
1225second form of the instruction is a shorter version of the first instruction
1226that defaults to allocating one element.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1227
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1228'<tt>type</tt>' must be a sized type<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1229
1230<h5>Semantics:</h5>
1231Memory is allocated, a pointer is returned.<p>
1232
1233<h5>Example:</h5>
1234<pre>
1235 %array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
1236
1237 %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]1238 %array1 = malloc ubyte, uint 4 <i>; yields {ubyte*}:array1</i>
1239 %array2 = malloc [12 x ubyte], uint %size <i>; yields {[12 x ubyte]*}:array2</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1240</pre>
1241
1242
1243<!-- _______________________________________________________________________ -->
1244</ul><a name="i_free"><h4><hr size=0>'<tt>free</tt>' Instruction</h4><ul>
1245
1246<h5>Syntax:</h5>
1247<pre>
1248 free &lt;type&gt; &lt;value&gt; <i>; yields {void}</i>
1249</pre>
1250
1251
1252<h5>Overview:</h5>
1253The '<tt>free</tt>' instruction returns memory back to the unused memory heap, to be reallocated in the future.<p>
1254
1255
1256<h5>Arguments:</h5>
1257
1258'<tt>value</tt>' shall be a pointer value that points to a value that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' instruction.<p>
1259
1260
1261<h5>Semantics:</h5>
1262Memory is available for use after this point. The contents of the '<tt>value</tt>' pointer are undefined after this instruction.<p>
1263
1264
1265<h5>Example:</h5>
1266<pre>
1267 %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
1268 free [4 x ubyte]* %array
1269</pre>
1270
1271
1272<!-- _______________________________________________________________________ -->
1273</ul><a name="i_alloca"><h4><hr size=0>'<tt>alloca</tt>' Instruction</h4><ul>
1274
1275<h5>Syntax:</h5>
1276<pre>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1277 &lt;result&gt; = alloca &lt;type&gt;, uint &lt;NumElements&gt; <i>; yields {type*}:result</i>
1278 &lt;result&gt; = alloca &lt;type&gt; <i>; yields {type*}:result</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1279</pre>
1280
1281<h5>Overview:</h5>
1282
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1283The '<tt>alloca</tt>' instruction allocates memory on the current stack frame of
1284the procedure that is live until the current function returns to its caller.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1285
1286<h5>Arguments:</h5>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1287
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1288The the '<tt>alloca</tt>' instruction allocates
1289<tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory on the runtime stack,
1290returning a pointer of the appropriate type to the program. The second form of
1291the instruction is a shorter version of the first that defaults to allocating
1292one element.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1293
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1294'<tt>type</tt>' may be any sized type.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1295
1296<h5>Semantics:</h5>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1297
1298Memory is allocated, a pointer is returned. '<tt>alloca</tt>'d memory is
1299automatically released when the function returns. The '<tt>alloca</tt>'
1300instruction is commonly used to represent automatic variables that must have an
1301address available, as well as spilled variables.<p>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1302
1303<h5>Example:</h5>
1304<pre>
1305 %ptr = alloca int <i>; yields {int*}:ptr</i>
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1306 %ptr = alloca int, uint 4 <i>; yields {int*}:ptr</i>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1307</pre>
1308
1309
1310<!-- _______________________________________________________________________ -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]1311</ul><a name="i_load"><h4><hr size=0>'<tt>load</tt>' Instruction</h4><ul>
1312
1313<h5>Syntax:</h5>
1314<pre>
1315 &lt;result&gt; = load &lt;ty&gt;* &lt;pointer&gt;
1316</pre>
1317
1318<h5>Overview:</h5>
1319The '<tt>load</tt>' instruction is used to read from memory.<p>
1320
1321<h5>Arguments:</h5>
1322
1323The 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>
1324
1325<h5>Semantics:</h5>
1326
1327The location of memory pointed to is loaded.
1328
1329<h5>Examples:</h5>
1330<pre>
1331 %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
1332 <a href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
1333 %val = load int* %ptr <i>; yields {int}:val = int 3</i>
1334</pre>
1335
1336
1337
1338
1339<!-- _______________________________________________________________________ -->
1340</ul><a name="i_store"><h4><hr size=0>'<tt>store</tt>' Instruction</h4><ul>
1341
1342<h5>Syntax:</h5>
1343<pre>
1344 store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt; <i>; yields {void}</i>
1345</pre>
1346
1347<h5>Overview:</h5>
1348The '<tt>store</tt>' instruction is used to write to memory.<p>
1349
1350<h5>Arguments:</h5>
1351
1352There are two arguments to the '<tt>store</tt>' instruction: a value to store
1353and an address to store it into. The type of the '<tt>&lt;pointer&gt;</tt>'
1354operand must be a pointer to the type of the '<tt>&lt;value&gt;</tt>'
1355operand.<p>
1356
1357<h5>Semantics:</h5> The contents of memory are updated to contain
1358'<tt>&lt;value&gt;</tt>' at the location specified by the
1359'<tt>&lt;pointer&gt;</tt>' operand.<p>
1360
1361<h5>Example:</h5>
1362<pre>
1363 %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
1364 <a href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
1365 %val = load int* %ptr <i>; yields {int}:val = int 3</i>
1366</pre>
1367
1368
1369
1370
1371<!-- _______________________________________________________________________ -->
Chris Lattner7faa8832002-04-14 06:13:44 +0000[diff] [blame]1372</ul><a name="i_getelementptr"><h4><hr size=0>'<tt>getelementptr</tt>' Instruction</h4><ul>
1373
1374<h5>Syntax:</h5>
1375<pre>
1376 &lt;result&gt; = getelementptr &lt;ty&gt;* &lt;ptrval&gt;{, uint &lt;aidx&gt;|, ubyte &lt;sidx&gt;}*
1377</pre>
1378
1379<h5>Overview:</h5>
1380
1381The '<tt>getelementptr</tt>' instruction is used to get the address of a
1382subelement of an aggregate data structure. In addition to being present as an
1383explicit instruction, the '<tt>getelementptr</tt>' functionality is present in
1384both the '<tt><a href="#i_load">load</a></tt>' and '<tt><a
1385href="#i_store">store</a></tt>' instructions to allow more compact specification
1386of common expressions.<p>
1387
1388<h5>Arguments:</h5>
1389
1390This instruction takes a list of <tt>uint</tt> values and <tt>ubyte</tt>
1391constants that indicate what form of addressing to perform. The actual types of
1392the arguments provided depend on the type of the first pointer argument. The
1393'<tt>getelementptr</tt>' instruction is used to index down through the type
1394levels of a structure.<p>
1395
1396TODO.
1397
1398<h5>Semantics:</h5>
1399
1400
1401<h5>Example:</h5>
1402<pre>
1403 %aptr = getelementptr {int, [12 x ubyte]}* %sptr, 1 <i>; yields {[12 x ubyte]*}:aptr</i>
1404 %ub = load [12x ubyte]* %aptr, 4 <i>;yields {ubyte}:ub</i>
1405</pre>
1406
1407
1408
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1409<!-- ======================================================================= -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]1410</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1411<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]1412<a name="otherops">Other Operations
1413</b></font></td></tr></table><ul>
1414
1415The instructions in this catagory are the "miscellaneous" functions, that defy better classification.<p>
1416
1417
1418<!-- _______________________________________________________________________ -->
Chris Lattner33ba0d92001-07-09 00:26:23 +0000[diff] [blame]1419</ul><a name="i_cast"><h4><hr size=0>'<tt>cast .. to</tt>' Instruction</h4><ul>
1420
1421<h1>TODO</h1>
1422
1423<a name="logical_integrals">
1424 Talk about what is considered true or false for integrals.
1425
1426
1427
1428<h5>Syntax:</h5>
1429<pre>
1430</pre>
1431
1432<h5>Overview:</h5>
1433
1434
1435<h5>Arguments:</h5>
1436
1437
1438<h5>Semantics:</h5>
1439
1440
1441<h5>Example:</h5>
1442<pre>
1443</pre>
1444
1445
1446
1447<!-- _______________________________________________________________________ -->
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1448</ul><a name="i_call"><h4><hr size=0>'<tt>call</tt>' Instruction</h4><ul>
1449
1450<h5>Syntax:</h5>
1451<pre>
1452
1453</pre>
1454
1455<h5>Overview:</h5>
1456
1457
1458<h5>Arguments:</h5>
1459
1460
1461<h5>Semantics:</h5>
1462
1463
1464<h5>Example:</h5>
1465<pre>
1466 %retval = call int %test(int %argc)
1467</pre>
1468
1469
1470<!-- _______________________________________________________________________ --></ul><a name="i_icall"><h3><hr size=0>'<tt>icall</tt>' Instruction</h3><ul>
1471
1472Indirect calls are desperately needed to implement virtual function tables (C++, java) and function pointers (C, C++, ...).<p>
1473
1474A new instruction <tt>icall</tt> or similar should be introduced to represent an indirect call.<p>
1475
1476Example:
1477<pre>
1478 %retval = icall int %funcptr(int %arg1) <i>; yields {int}:%retval</i>
1479</pre>
1480
1481
1482
1483<!-- _______________________________________________________________________ -->
1484</ul><a name="i_phi"><h4><hr size=0>'<tt>phi</tt>' Instruction</h4><ul>
1485
1486<h5>Syntax:</h5>
1487<pre>
1488</pre>
1489
1490<h5>Overview:</h5>
1491
1492
1493<h5>Arguments:</h5>
1494
1495
1496<h5>Semantics:</h5>
1497
1498
1499<h5>Example:</h5>
1500<pre>
1501</pre>
1502
1503
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1504
1505<!-- *********************************************************************** -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]1506</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
1507<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1508<a name="related">Related Work
1509</b></font></td></tr></table><ul>
1510<!-- *********************************************************************** -->
1511
1512
1513Codesigned virtual machines.<p>
1514
1515<dl>
1516<a name="rw_safetsa">
1517<dt>SafeTSA
1518<DD>Description here<p>
1519
1520<a name="rw_java">
1521<dt><a href="http://www.javasoft.com">Java</a>
1522<DD>Desciption here<p>
1523
1524<a name="rw_net">
1525<dt><a href="http://www.microsoft.com/net">Microsoft .net</a>
1526<DD>Desciption here<p>
1527
1528<a name="rw_gccrtl">
1529<dt><a href="http://www.math.umn.edu/systems_guide/gcc-2.95.1/gcc_15.html">GNU RTL Intermediate Representation</a>
1530<DD>Desciption here<p>
1531
1532<a name="rw_ia64">
1533<dt><a href="http://developer.intel.com/design/ia-64/index.htm">IA64 Architecture &amp; Instruction Set</a>
1534<DD>Desciption here<p>
1535
1536<a name="rw_mmix">
1537<dt><a href="http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html">MMIX Instruction Set</a>
1538<DD>Desciption here<p>
1539
1540<a name="rw_stroustrup">
1541<dt><a href="http://www.research.att.com/~bs/devXinterview.html">"Interview With Bjarne Stroustrup"</a>
1542<DD>This interview influenced the design and thought process behind LLVM in several ways, most notably the way that derived types are written in text format. See the question that starts with "you defined the C declarator syntax as an experiment that failed".<p>
1543</dl>
1544
1545<!-- _______________________________________________________________________ -->
1546</ul><a name="rw_vectorization"><h3><hr size=0>Vectorized Architectures</h3><ul>
1547
1548<dl>
1549<a name="rw_intel_simd">
1550<dt>Intel MMX, MMX2, SSE, SSE2
1551<DD>Description here<p>
1552
1553<a name="rw_amd_simd">
1554<dt><a href="http://www.nondot.org/~sabre/os/H1ChipFeatures/3DNow!TechnologyManual.pdf">AMD 3Dnow!, 3Dnow! 2</a>
1555<DD>Desciption here<p>
1556
1557<a name="rw_sun_simd">
1558<dt><a href="http://www.nondot.org/~sabre/os/H1ChipFeatures/VISInstructionSetUsersManual.pdf">Sun VIS ISA</a>
1559<DD>Desciption here<p>
1560
1561
1562</dl>
1563
1564more...
1565
1566<!-- *********************************************************************** -->
1567</ul>
1568<!-- *********************************************************************** -->
1569
1570
1571<hr>
1572<font size=-1>
1573<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
1574<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
1575<!-- hhmts start -->
Chris Lattner2b7d3202002-05-06 03:03:22 +0000[diff] [blame^]1576Last modified: Fri May 3 14:39:52 CDT 2002
Chris Lattner00950542001-06-06 20:29:01 +0000[diff] [blame]1577<!-- hhmts end -->
1578</font>
1579</body></html>