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