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