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