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