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