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