1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
5 <title>LLVM Assembly Language Reference Manual</title>
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
7 <meta name="author" content="Chris Lattner">
8 <meta name="description"
9 content="LLVM Assembly Language Reference Manual.">
10 <link rel="stylesheet" href="llvm.css" type="text/css">
15 <div class="doc_title"> LLVM Language Reference Manual </div>
17 <li><a href="#abstract">Abstract</a></li>
18 <li><a href="#introduction">Introduction</a></li>
19 <li><a href="#identifiers">Identifiers</a></li>
20 <li><a href="#highlevel">High Level Structure</a>
22 <li><a href="#modulestructure">Module Structure</a></li>
23 <li><a href="#globalvars">Global Variables</a></li>
24 <li><a href="#functionstructure">Function Structure</a></li>
27 <li><a href="#typesystem">Type System</a>
29 <li><a href="#t_primitive">Primitive Types</a>
31 <li><a href="#t_classifications">Type Classifications</a></li>
34 <li><a href="#t_derived">Derived Types</a>
36 <li><a href="#t_array">Array Type</a></li>
37 <li><a href="#t_function">Function Type</a></li>
38 <li><a href="#t_pointer">Pointer Type</a></li>
39 <li><a href="#t_struct">Structure Type</a></li>
40 <li><a href="#t_packed">Packed Type</a></li>
45 <li><a href="#constants">Constants</a>
47 <li><a href="#instref">Instruction Reference</a>
49 <li><a href="#terminators">Terminator Instructions</a>
51 <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li>
52 <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
53 <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
54 <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
55 <li><a href="#i_unwind">'<tt>unwind</tt>' Instruction</a></li>
56 <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
59 <li><a href="#binaryops">Binary Operations</a>
61 <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li>
62 <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li>
63 <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li>
64 <li><a href="#i_div">'<tt>div</tt>' Instruction</a></li>
65 <li><a href="#i_rem">'<tt>rem</tt>' Instruction</a></li>
66 <li><a href="#i_setcc">'<tt>set<i>cc</i></tt>' Instructions</a></li>
69 <li><a href="#bitwiseops">Bitwise Binary Operations</a>
71 <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
72 <li><a href="#i_or">'<tt>or</tt>' Instruction</a></li>
73 <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
74 <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
75 <li><a href="#i_shr">'<tt>shr</tt>' Instruction</a></li>
78 <li><a href="#memoryops">Memory Access Operations</a>
80 <li><a href="#i_malloc">'<tt>malloc</tt>' Instruction</a></li>
81 <li><a href="#i_free">'<tt>free</tt>' Instruction</a></li>
82 <li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li>
83 <li><a href="#i_load">'<tt>load</tt>' Instruction</a></li>
84 <li><a href="#i_store">'<tt>store</tt>' Instruction</a></li>
85 <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
88 <li><a href="#otherops">Other Operations</a>
90 <li><a href="#i_phi">'<tt>phi</tt>' Instruction</a></li>
91 <li><a href="#i_cast">'<tt>cast .. to</tt>' Instruction</a></li>
92 <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
93 <li><a href="#i_call">'<tt>call</tt>' Instruction</a></li>
94 <li><a href="#i_vanext">'<tt>vanext</tt>' Instruction</a></li>
95 <li><a href="#i_vaarg">'<tt>vaarg</tt>' Instruction</a></li>
100 <li><a href="#intrinsics">Intrinsic Functions</a>
102 <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
104 <li><a href="#i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
105 <li><a href="#i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a></li>
106 <li><a href="#i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a></li>
109 <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a>
111 <li><a href="#i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
112 <li><a href="#i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
113 <li><a href="#i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
116 <li><a href="#int_codegen">Code Generator Intrinsics</a>
118 <li><a href="#i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
119 <li><a href="#i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a></li>
122 <li><a href="#int_os">Operating System Intrinsics</a>
124 <li><a href="#i_readport">'<tt>llvm.readport</tt>' Intrinsic</a></li>
125 <li><a href="#i_writeport">'<tt>llvm.writeport</tt>' Intrinsic</a></li>
126 <li><a href="#i_readio">'<tt>llvm.readio</tt>' Intrinsic</a></li>
127 <li><a href="#i_writeio">'<tt>llvm.writeio</tt>' Intrinsic</a></li>
129 <li><a href="#int_libc">Standard C Library Intrinsics</a>
131 <li><a href="#i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a></li>
132 <li><a href="#i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a></li>
133 <li><a href="#i_memset">'<tt>llvm.memset</tt>' Intrinsic</a></li>
134 <li><a href="#i_isunordered">'<tt>llvm.isunordered</tt>' Intrinsic</a></li>
137 <li><a href="#int_debugger">Debugger intrinsics</a></li>
142 <div class="doc_author">
143 <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
144 and <a href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></p>
147 <!-- *********************************************************************** -->
148 <div class="doc_section"> <a name="abstract">Abstract </a></div>
149 <!-- *********************************************************************** -->
151 <div class="doc_text">
152 <p>This document is a reference manual for the LLVM assembly language.
153 LLVM is an SSA based representation that provides type safety,
154 low-level operations, flexibility, and the capability of representing
155 'all' high-level languages cleanly. It is the common code
156 representation used throughout all phases of the LLVM compilation
160 <!-- *********************************************************************** -->
161 <div class="doc_section"> <a name="introduction">Introduction</a> </div>
162 <!-- *********************************************************************** -->
164 <div class="doc_text">
166 <p>The LLVM code representation is designed to be used in three
167 different forms: as an in-memory compiler IR, as an on-disk bytecode
168 representation (suitable for fast loading by a Just-In-Time compiler),
169 and as a human readable assembly language representation. This allows
170 LLVM to provide a powerful intermediate representation for efficient
171 compiler transformations and analysis, while providing a natural means
172 to debug and visualize the transformations. The three different forms
173 of LLVM are all equivalent. This document describes the human readable
174 representation and notation.</p>
176 <p>The LLVM representation aims to be a light-weight and low-level
177 while being expressive, typed, and extensible at the same time. It
178 aims to be a "universal IR" of sorts, by being at a low enough level
179 that high-level ideas may be cleanly mapped to it (similar to how
180 microprocessors are "universal IR's", allowing many source languages to
181 be mapped to them). By providing type information, LLVM can be used as
182 the target of optimizations: for example, through pointer analysis, it
183 can be proven that a C automatic variable is never accessed outside of
184 the current function... allowing it to be promoted to a simple SSA
185 value instead of a memory location.</p>
189 <!-- _______________________________________________________________________ -->
190 <div class="doc_subsubsection"> <a name="wellformed">Well-Formedness</a> </div>
192 <div class="doc_text">
194 <p>It is important to note that this document describes 'well formed'
195 LLVM assembly language. There is a difference between what the parser
196 accepts and what is considered 'well formed'. For example, the
197 following instruction is syntactically okay, but not well formed:</p>
200 %x = <a href="#i_add">add</a> int 1, %x
203 <p>...because the definition of <tt>%x</tt> does not dominate all of
204 its uses. The LLVM infrastructure provides a verification pass that may
205 be used to verify that an LLVM module is well formed. This pass is
206 automatically run by the parser after parsing input assembly, and by
207 the optimizer before it outputs bytecode. The violations pointed out
208 by the verifier pass indicate bugs in transformation passes or input to
211 <!-- Describe the typesetting conventions here. --> </div>
213 <!-- *********************************************************************** -->
214 <div class="doc_section"> <a name="identifiers">Identifiers</a> </div>
215 <!-- *********************************************************************** -->
217 <div class="doc_text">
219 <p>LLVM uses three different forms of identifiers, for different
223 <li>Numeric constants are represented as you would expect: 12, -3
224 123.421, etc. Floating point constants have an optional hexadecimal
226 <li>Named values are represented as a string of characters with a '%'
227 prefix. For example, %foo, %DivisionByZero,
228 %a.really.long.identifier. The actual regular expression used is '<tt>%[a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.
229 Identifiers which require other characters in their names can be
230 surrounded with quotes. In this way, anything except a <tt>"</tt>
231 character can be used in a name.</li>
232 <li>Unnamed values are represented as an unsigned numeric value with
233 a '%' prefix. For example, %12, %2, %44.</li>
235 <p>LLVM requires that values start with a '%' sign for two reasons:
236 Compilers don't need to worry about name clashes with reserved words,
237 and the set of reserved words may be expanded in the future without
238 penalty. Additionally, unnamed identifiers allow a compiler to quickly
239 come up with a temporary variable without having to avoid symbol table
241 <p>Reserved words in LLVM are very similar to reserved words in other
242 languages. There are keywords for different opcodes ('<tt><a
243 href="#i_add">add</a></tt>', '<tt><a href="#i_cast">cast</a></tt>', '<tt><a
244 href="#i_ret">ret</a></tt>', etc...), for primitive type names ('<tt><a
245 href="#t_void">void</a></tt>', '<tt><a href="#t_uint">uint</a></tt>',
246 etc...), and others. These reserved words cannot conflict with
247 variable names, because none of them start with a '%' character.</p>
248 <p>Here is an example of LLVM code to multiply the integer variable '<tt>%X</tt>'
251 <pre> %result = <a href="#i_mul">mul</a> uint %X, 8<br></pre>
252 <p>After strength reduction:</p>
253 <pre> %result = <a href="#i_shl">shl</a> uint %X, ubyte 3<br></pre>
254 <p>And the hard way:</p>
255 <pre> <a href="#i_add">add</a> uint %X, %X <i>; yields {uint}:%0</i>
257 href="#i_add">add</a> uint %0, %0 <i>; yields {uint}:%1</i>
259 href="#i_add">add</a> uint %1, %1<br></pre>
260 <p>This last way of multiplying <tt>%X</tt> by 8 illustrates several
261 important lexical features of LLVM:</p>
263 <li>Comments are delimited with a '<tt>;</tt>' and go until the end
265 <li>Unnamed temporaries are created when the result of a computation
266 is not assigned to a named value.</li>
267 <li>Unnamed temporaries are numbered sequentially</li>
269 <p>...and it also show a convention that we follow in this document.
270 When demonstrating instructions, we will follow an instruction with a
271 comment that defines the type and name of value produced. Comments are
272 shown in italic text.</p>
273 <p>The one non-intuitive notation for constants is the optional
274 hexidecimal form of floating point constants. For example, the form '<tt>double
275 0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
276 4.5e+15</tt>' which is also supported by the parser. The only time
277 hexadecimal floating point constants are useful (and the only time that
278 they are generated by the disassembler) is when an FP constant has to
279 be emitted that is not representable as a decimal floating point number
280 exactly. For example, NaN's, infinities, and other special cases are
281 represented in their IEEE hexadecimal format so that assembly and
282 disassembly do not cause any bits to change in the constants.</p>
285 <!-- *********************************************************************** -->
286 <div class="doc_section"> <a name="highlevel">High Level Structure</a> </div>
287 <!-- *********************************************************************** -->
289 <!-- ======================================================================= -->
290 <div class="doc_subsection"> <a name="modulestructure">Module Structure</a>
293 <div class="doc_text">
295 <p>LLVM programs are composed of "Module"s, each of which is a
296 translation unit of the input programs. Each module consists of
297 functions, global variables, and symbol table entries. Modules may be
298 combined together with the LLVM linker, which merges function (and
299 global variable) definitions, resolves forward declarations, and merges
300 symbol table entries. Here is an example of the "hello world" module:</p>
302 <pre><i>; Declare the string constant as a global constant...</i>
303 <a href="#identifiers">%.LC0</a> = <a href="#linkage_internal">internal</a> <a
304 href="#globalvars">constant</a> <a href="#t_array">[13 x sbyte]</a> c"hello world\0A\00" <i>; [13 x sbyte]*</i>
306 <i>; External declaration of the puts function</i>
307 <a href="#functionstructure">declare</a> int %puts(sbyte*) <i>; int(sbyte*)* </i>
309 <i>; Definition of main function</i>
310 int %main() { <i>; int()* </i>
311 <i>; Convert [13x sbyte]* to sbyte *...</i>
313 href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, long 0, long 0 <i>; sbyte*</i>
315 <i>; Call puts function to write out the string to stdout...</i>
317 href="#i_call">call</a> int %puts(sbyte* %cast210) <i>; int</i>
319 href="#i_ret">ret</a> int 0<br>}<br></pre>
321 <p>This example is made up of a <a href="#globalvars">global variable</a>
322 named "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>"
323 function, and a <a href="#functionstructure">function definition</a>
324 for "<tt>main</tt>".</p>
326 <a name="linkage"> In general, a module is made up of a list of global
327 values, where both functions and global variables are global values.
328 Global values are represented by a pointer to a memory location (in
329 this case, a pointer to an array of char, and a pointer to a function),
330 and have one of the following linkage types:</a>
335 <dt><tt><b><a name="linkage_internal">internal</a></b></tt> </dt>
336 <dd>Global values with internal linkage are only directly accessible
337 by objects in the current module. In particular, linking code into a
338 module with an internal global value may cause the internal to be
339 renamed as necessary to avoid collisions. Because the symbol is
340 internal to the module, all references can be updated. This
341 corresponds to the notion of the '<tt>static</tt>' keyword in C, or the
342 idea of "anonymous namespaces" in C++.
345 <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt>: </dt>
346 <dd>"<tt>linkonce</tt>" linkage is similar to <tt>internal</tt>
347 linkage, with the twist that linking together two modules defining the
348 same <tt>linkonce</tt> globals will cause one of the globals to be
349 discarded. This is typically used to implement inline functions.
350 Unreferenced <tt>linkonce</tt> globals are allowed to be discarded.
353 <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt>
354 <dd>"<tt>weak</tt>" linkage is exactly the same as <tt>linkonce</tt>
355 linkage, except that unreferenced <tt>weak</tt> globals may not be
356 discarded. This is used to implement constructs in C such as "<tt>int
357 X;</tt>" at global scope.
360 <dt><tt><b><a name="linkage_appending">appending</a></b></tt>: </dt>
361 <dd>"<tt>appending</tt>" linkage may only be applied to global
362 variables of pointer to array type. When two global variables with
363 appending linkage are linked together, the two global arrays are
364 appended together. This is the LLVM, typesafe, equivalent of having
365 the system linker append together "sections" with identical names when
369 <dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt>
370 <dd>If none of the above identifiers are used, the global is
371 externally visible, meaning that it participates in linkage and can be
372 used to resolve external symbol references.
379 <p><a name="linkage_external">For example, since the "<tt>.LC0</tt>"
380 variable is defined to be internal, if another module defined a "<tt>.LC0</tt>"
381 variable and was linked with this one, one of the two would be renamed,
382 preventing a collision. Since "<tt>main</tt>" and "<tt>puts</tt>" are
383 external (i.e., lacking any linkage declarations), they are accessible
384 outside of the current module. It is illegal for a function <i>declaration</i>
385 to have any linkage type other than "externally visible".</a></p>
388 <!-- ======================================================================= -->
389 <div class="doc_subsection">
390 <a name="globalvars">Global Variables</a>
393 <div class="doc_text">
395 <p>Global variables define regions of memory allocated at compilation
396 time instead of run-time. Global variables may optionally be
397 initialized. A variable may be defined as a global "constant", which
398 indicates that the contents of the variable will never be modified
399 (enabling better optimization, allowing the global data to be placed in the
400 read-only section of an executable, etc).</p>
402 <p>As SSA values, global variables define pointer values that are in
403 scope (i.e. they dominate) all basic blocks in the program. Global
404 variables always define a pointer to their "content" type because they
405 describe a region of memory, and all memory objects in LLVM are
406 accessed through pointers.</p>
411 <!-- ======================================================================= -->
412 <div class="doc_subsection">
413 <a name="functionstructure">Functions</a>
416 <div class="doc_text">
418 <p>LLVM function definitions are composed of a (possibly empty) argument list,
419 an opening curly brace, a list of basic blocks, and a closing curly brace. LLVM
420 function declarations are defined with the "<tt>declare</tt>" keyword, a
421 function name, and a function signature.</p>
423 <p>A function definition contains a list of basic blocks, forming the CFG for
424 the function. Each basic block may optionally start with a label (giving the
425 basic block a symbol table entry), contains a list of instructions, and ends
426 with a <a href="#terminators">terminator</a> instruction (such as a branch or
427 function return).</p>
429 <p>The first basic block in program is special in two ways: it is immediately
430 executed on entrance to the function, and it is not allowed to have predecessor
431 basic blocks (i.e. there can not be any branches to the entry block of a
432 function). Because the block can have no predecessors, it also cannot have any
433 <a href="#i_phi">PHI nodes</a>.</p>
435 <p>LLVM functions are identified by their name and type signature. Hence, two
436 functions with the same name but different parameter lists or return values are
437 considered different functions, and LLVM will resolves references to each
444 <!-- *********************************************************************** -->
445 <div class="doc_section"> <a name="typesystem">Type System</a> </div>
446 <!-- *********************************************************************** -->
448 <div class="doc_text">
450 <p>The LLVM type system is one of the most important features of the
451 intermediate representation. Being typed enables a number of
452 optimizations to be performed on the IR directly, without having to do
453 extra analyses on the side before the transformation. A strong type
454 system makes it easier to read the generated code and enables novel
455 analyses and transformations that are not feasible to perform on normal
456 three address code representations.</p>
460 <!-- ======================================================================= -->
461 <div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div>
462 <div class="doc_text">
463 <p>The primitive types are the fundamental building blocks of the LLVM
464 system. The current set of primitive types are as follows:</p>
466 <table class="layout">
471 <tr><th>Type</th><th>Description</th></tr>
472 <tr><td><tt>void</tt></td><td>No value</td></tr>
473 <tr><td><tt>ubyte</tt></td><td>Unsigned 8 bit value</td></tr>
474 <tr><td><tt>ushort</tt></td><td>Unsigned 16 bit value</td></tr>
475 <tr><td><tt>uint</tt></td><td>Unsigned 32 bit value</td></tr>
476 <tr><td><tt>ulong</tt></td><td>Unsigned 64 bit value</td></tr>
477 <tr><td><tt>float</tt></td><td>32 bit floating point value</td></tr>
478 <tr><td><tt>label</tt></td><td>Branch destination</td></tr>
485 <tr><th>Type</th><th>Description</th></tr>
486 <tr><td><tt>bool</tt></td><td>True or False value</td></tr>
487 <tr><td><tt>sbyte</tt></td><td>Signed 8 bit value</td></tr>
488 <tr><td><tt>short</tt></td><td>Signed 16 bit value</td></tr>
489 <tr><td><tt>int</tt></td><td>Signed 32 bit value</td></tr>
490 <tr><td><tt>long</tt></td><td>Signed 64 bit value</td></tr>
491 <tr><td><tt>double</tt></td><td>64 bit floating point value</td></tr>
499 <!-- _______________________________________________________________________ -->
500 <div class="doc_subsubsection"> <a name="t_classifications">Type
501 Classifications</a> </div>
502 <div class="doc_text">
503 <p>These different primitive types fall into a few useful
506 <table border="1" cellspacing="0" cellpadding="4">
508 <tr><th>Classification</th><th>Types</th></tr>
510 <td><a name="t_signed">signed</a></td>
511 <td><tt>sbyte, short, int, long, float, double</tt></td>
514 <td><a name="t_unsigned">unsigned</a></td>
515 <td><tt>ubyte, ushort, uint, ulong</tt></td>
518 <td><a name="t_integer">integer</a></td>
519 <td><tt>ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td>
522 <td><a name="t_integral">integral</a></td>
523 <td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long</tt>
527 <td><a name="t_floating">floating point</a></td>
528 <td><tt>float, double</tt></td>
531 <td><a name="t_firstclass">first class</a></td>
532 <td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long,<br>
533 float, double, <a href="#t_pointer">pointer</a>,
534 <a href="#t_packed">packed</a></tt></td>
539 <p>The <a href="#t_firstclass">first class</a> types are perhaps the
540 most important. Values of these types are the only ones which can be
541 produced by instructions, passed as arguments, or used as operands to
542 instructions. This means that all structures and arrays must be
543 manipulated either by pointer or by component.</p>
545 <!-- ======================================================================= -->
546 <div class="doc_subsection"> <a name="t_derived">Derived Types</a> </div>
547 <div class="doc_text">
548 <p>The real power in LLVM comes from the derived types in the system.
549 This is what allows a programmer to represent arrays, functions,
550 pointers, and other useful types. Note that these derived types may be
551 recursive: For example, it is possible to have a two dimensional array.</p>
553 <!-- _______________________________________________________________________ -->
554 <div class="doc_subsubsection"> <a name="t_array">Array Type</a> </div>
555 <div class="doc_text">
557 <p>The array type is a very simple derived type that arranges elements
558 sequentially in memory. The array type requires a size (number of
559 elements) and an underlying data type.</p>
561 <pre> [<# elements> x <elementtype>]<br></pre>
562 <p>The number of elements is a constant integer value, elementtype may
563 be any type with a size.</p>
565 <table class="layout">
568 <tt>[40 x int ]</tt><br/>
569 <tt>[41 x int ]</tt><br/>
570 <tt>[40 x uint]</tt><br/>
573 Array of 40 integer values.<br/>
574 Array of 41 integer values.<br/>
575 Array of 40 unsigned integer values.<br/>
579 <p>Here are some examples of multidimensional arrays:</p>
580 <table class="layout">
583 <tt>[3 x [4 x int]]</tt><br/>
584 <tt>[12 x [10 x float]]</tt><br/>
585 <tt>[2 x [3 x [4 x uint]]]</tt><br/>
588 3x4 array integer values.<br/>
589 12x10 array of single precision floating point values.<br/>
590 2x3x4 array of unsigned integer values.<br/>
596 <!-- _______________________________________________________________________ -->
597 <div class="doc_subsubsection"> <a name="t_function">Function Type</a> </div>
598 <div class="doc_text">
600 <p>The function type can be thought of as a function signature. It
601 consists of a return type and a list of formal parameter types.
602 Function types are usually used to build virtual function tables
603 (which are structures of pointers to functions), for indirect function
604 calls, and when defining a function.</p>
606 The return type of a function type cannot be an aggregate type.
609 <pre> <returntype> (<parameter list>)<br></pre>
610 <p>Where '<tt><parameter list></tt>' is a comma-separated list of type
611 specifiers. Optionally, the parameter list may include a type <tt>...</tt>,
612 which indicates that the function takes a variable number of arguments.
613 Variable argument functions can access their arguments with the <a
614 href="#int_varargs">variable argument handling intrinsic</a> functions.</p>
616 <table class="layout">
619 <tt>int (int)</tt> <br/>
620 <tt>float (int, int *) *</tt><br/>
621 <tt>int (sbyte *, ...)</tt><br/>
624 function taking an <tt>int</tt>, returning an <tt>int</tt><br/>
625 <a href="#t_pointer">Pointer</a> to a function that takes an
626 <tt>int</tt> and a <a href="#t_pointer">pointer</a> to <tt>int</tt>,
627 returning <tt>float</tt>.<br/>
628 A vararg function that takes at least one <a href="#t_pointer">pointer</a>
629 to <tt>sbyte</tt> (signed char in C), which returns an integer. This is
630 the signature for <tt>printf</tt> in LLVM.<br/>
636 <!-- _______________________________________________________________________ -->
637 <div class="doc_subsubsection"> <a name="t_struct">Structure Type</a> </div>
638 <div class="doc_text">
640 <p>The structure type is used to represent a collection of data members
641 together in memory. The packing of the field types is defined to match
642 the ABI of the underlying processor. The elements of a structure may
643 be any type that has a size.</p>
644 <p>Structures are accessed using '<tt><a href="#i_load">load</a></tt>
645 and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a
646 field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>'
649 <pre> { <type list> }<br></pre>
651 <table class="layout">
654 <tt>{ int, int, int }</tt><br/>
655 <tt>{ float, int (int) * }</tt><br/>
658 a triple of three <tt>int</tt> values<br/>
659 A pair, where the first element is a <tt>float</tt> and the second element
660 is a <a href="#t_pointer">pointer</a> to a <a href="#t_function">function</a>
661 that takes an <tt>int</tt>, returning an <tt>int</tt>.<br/>
667 <!-- _______________________________________________________________________ -->
668 <div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div>
669 <div class="doc_text">
671 <p>As in many languages, the pointer type represents a pointer or
672 reference to another object, which must live in memory.</p>
674 <pre> <type> *<br></pre>
676 <table class="layout">
679 <tt>[4x int]*</tt><br/>
680 <tt>int (int *) *</tt><br/>
683 A <a href="#t_pointer">pointer</a> to <a href="#t_array">array</a> of
684 four <tt>int</tt> values<br/>
685 A <a href="#t_pointer">pointer</a> to a <a
686 href="#t_function">function</a> that takes an <tt>int</tt>, returning an
693 <!-- _______________________________________________________________________ -->
694 <div class="doc_subsubsection"> <a name="t_packed">Packed Type</a> </div>
695 <div class="doc_text">
697 <p>A packed type is a simple derived type that represents a vector
698 of elements. Packed types are used when multiple primitive data
699 are operated in parallel using a single instruction (SIMD).
700 A packed type requires a size (number of
701 elements) and an underlying primitive data type. Packed types are
702 considered <a href="#t_firstclass">first class</a>.</p>
704 <pre> < <# elements> x <elementtype> ><br></pre>
705 <p>The number of elements is a constant integer value, elementtype may
706 be any integral or floating point type.</p>
708 <table class="layout">
711 <tt><4 x int></tt><br/>
712 <tt><8 x float></tt><br/>
713 <tt><2 x uint></tt><br/>
716 Packed vector of 4 integer values.<br/>
717 Packed vector of 8 floating-point values.<br/>
718 Packed vector of 2 unsigned integer values.<br/>
725 <!-- *********************************************************************** -->
726 <div class="doc_section"> <a name="instref">Instruction Reference</a> </div>
727 <!-- *********************************************************************** -->
728 <div class="doc_text">
729 <p>The LLVM instruction set consists of several different
730 classifications of instructions: <a href="#terminators">terminator
731 instructions</a>, <a href="#binaryops">binary instructions</a>, <a
732 href="#memoryops">memory instructions</a>, and <a href="#otherops">other
733 instructions</a>.</p>
735 <!-- ======================================================================= -->
736 <div class="doc_subsection"> <a name="terminators">Terminator
737 Instructions</a> </div>
738 <div class="doc_text">
739 <p>As mentioned <a href="#functionstructure">previously</a>, every
740 basic block in a program ends with a "Terminator" instruction, which
741 indicates which block should be executed after the current block is
742 finished. These terminator instructions typically yield a '<tt>void</tt>'
743 value: they produce control flow, not values (the one exception being
744 the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
745 <p>There are five different terminator instructions: the '<a
746 href="#i_ret"><tt>ret</tt></a>' instruction, the '<a href="#i_br"><tt>br</tt></a>'
747 instruction, the '<a href="#i_switch"><tt>switch</tt></a>' instruction,
748 the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the '<a
749 href="#i_unwind"><tt>unwind</tt></a>' instruction, and the '<a
750 href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p>
752 <!-- _______________________________________________________________________ -->
753 <div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>'
754 Instruction</a> </div>
755 <div class="doc_text">
757 <pre> ret <type> <value> <i>; Return a value from a non-void function</i>
758 ret void <i>; Return from void function</i>
761 <p>The '<tt>ret</tt>' instruction is used to return control flow (and a
762 value) from a function, back to the caller.</p>
763 <p>There are two forms of the '<tt>ret</tt>' instruction: one that
764 returns a value and then causes control flow, and one that just causes
765 control flow to occur.</p>
767 <p>The '<tt>ret</tt>' instruction may return any '<a
768 href="#t_firstclass">first class</a>' type. Notice that a function is
769 not <a href="#wellformed">well formed</a> if there exists a '<tt>ret</tt>'
770 instruction inside of the function that returns a value that does not
771 match the return type of the function.</p>
773 <p>When the '<tt>ret</tt>' instruction is executed, control flow
774 returns back to the calling function's context. If the caller is a "<a
775 href="#i_call"><tt>call</tt></a>" instruction, execution continues at
776 the instruction after the call. If the caller was an "<a
777 href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues
778 at the beginning "normal" of the destination block. If the instruction
779 returns a value, that value shall set the call or invoke instruction's
782 <pre> ret int 5 <i>; Return an integer value of 5</i>
783 ret void <i>; Return from a void function</i>
786 <!-- _______________________________________________________________________ -->
787 <div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div>
788 <div class="doc_text">
790 <pre> br bool <cond>, label <iftrue>, label <iffalse><br> br label <dest> <i>; Unconditional branch</i>
793 <p>The '<tt>br</tt>' instruction is used to cause control flow to
794 transfer to a different basic block in the current function. There are
795 two forms of this instruction, corresponding to a conditional branch
796 and an unconditional branch.</p>
798 <p>The conditional branch form of the '<tt>br</tt>' instruction takes a
799 single '<tt>bool</tt>' value and two '<tt>label</tt>' values. The
800 unconditional form of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>'
801 value as a target.</p>
803 <p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>bool</tt>'
804 argument is evaluated. If the value is <tt>true</tt>, control flows
805 to the '<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>,
806 control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p>
808 <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
809 href="#i_ret">ret</a> int 1<br>IfUnequal:<br> <a href="#i_ret">ret</a> int 0<br></pre>
811 <!-- _______________________________________________________________________ -->
812 <div class="doc_subsubsection">
813 <a name="i_switch">'<tt>switch</tt>' Instruction</a>
816 <div class="doc_text">
820 switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
825 <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
826 several different places. It is a generalization of the '<tt>br</tt>'
827 instruction, allowing a branch to occur to one of many possible
833 <p>The '<tt>switch</tt>' instruction uses three parameters: an integer
834 comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
835 an array of pairs of comparison value constants and '<tt>label</tt>'s. The
836 table is not allowed to contain duplicate constant entries.</p>
840 <p>The <tt>switch</tt> instruction specifies a table of values and
841 destinations. When the '<tt>switch</tt>' instruction is executed, this
842 table is searched for the given value. If the value is found, control flow is
843 transfered to the corresponding destination; otherwise, control flow is
844 transfered to the default destination.</p>
846 <h5>Implementation:</h5>
848 <p>Depending on properties of the target machine and the particular
849 <tt>switch</tt> instruction, this instruction may be code generated in different
850 ways. For example, it could be generated as a series of chained conditional
851 branches or with a lookup table.</p>
856 <i>; Emulate a conditional br instruction</i>
857 %Val = <a href="#i_cast">cast</a> bool %value to int
858 switch int %Val, label %truedest [int 0, label %falsedest ]
860 <i>; Emulate an unconditional br instruction</i>
861 switch uint 0, label %dest [ ]
863 <i>; Implement a jump table:</i>
864 switch uint %val, label %otherwise [ uint 0, label %onzero
866 uint 2, label %ontwo ]
869 <!-- _______________________________________________________________________ -->
870 <div class="doc_subsubsection"> <a name="i_invoke">'<tt>invoke</tt>'
871 Instruction</a> </div>
872 <div class="doc_text">
874 <pre> <result> = invoke <ptr to function ty> %<function ptr val>(<function args>)<br> to label <normal label> except label <exception label><br></pre>
876 <p>The '<tt>invoke</tt>' instruction causes control to transfer to a
877 specified function, with the possibility of control flow transfer to
878 either the '<tt>normal</tt>' <tt>label</tt> label or the '<tt>exception</tt>'<tt>label</tt>.
879 If the callee function returns with the "<tt><a href="#i_ret">ret</a></tt>"
880 instruction, control flow will return to the "normal" label. If the
881 callee (or any indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>"
882 instruction, control is interrupted, and continued at the dynamically
883 nearest "except" label.</p>
885 <p>This instruction requires several arguments:</p>
887 <li>'<tt>ptr to function ty</tt>': shall be the signature of the
888 pointer to function value being invoked. In most cases, this is a
889 direct function invocation, but indirect <tt>invoke</tt>s are just as
890 possible, branching off an arbitrary pointer to function value. </li>
891 <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer
892 to a function to be invoked. </li>
893 <li>'<tt>function args</tt>': argument list whose types match the
894 function signature argument types. If the function signature indicates
895 the function accepts a variable number of arguments, the extra
896 arguments can be specified. </li>
897 <li>'<tt>normal label</tt>': the label reached when the called
898 function executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
899 <li>'<tt>exception label</tt>': the label reached when a callee
900 returns with the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li>
903 <p>This instruction is designed to operate as a standard '<tt><a
904 href="#i_call">call</a></tt>' instruction in most regards. The
905 primary difference is that it establishes an association with a label,
906 which is used by the runtime library to unwind the stack.</p>
907 <p>This instruction is used in languages with destructors to ensure
908 that proper cleanup is performed in the case of either a <tt>longjmp</tt>
909 or a thrown exception. Additionally, this is important for
910 implementation of '<tt>catch</tt>' clauses in high-level languages that
913 <pre> %retval = invoke int %Test(int 15)<br> to label %Continue<br> except label %TestCleanup <i>; {int}:retval set</i>
918 <!-- _______________________________________________________________________ -->
920 <div class="doc_subsubsection"> <a name="i_unwind">'<tt>unwind</tt>'
921 Instruction</a> </div>
923 <div class="doc_text">
932 <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow
933 at the first callee in the dynamic call stack which used an <a
934 href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. This is
935 primarily used to implement exception handling.</p>
939 <p>The '<tt>unwind</tt>' intrinsic causes execution of the current function to
940 immediately halt. The dynamic call stack is then searched for the first <a
941 href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. Once found,
942 execution continues at the "exceptional" destination block specified by the
943 <tt>invoke</tt> instruction. If there is no <tt>invoke</tt> instruction in the
944 dynamic call chain, undefined behavior results.</p>
947 <!-- _______________________________________________________________________ -->
949 <div class="doc_subsubsection"> <a name="i_unreachable">'<tt>unreachable</tt>'
950 Instruction</a> </div>
952 <div class="doc_text">
961 <p>The '<tt>unreachable</tt>' instruction has no defined semantics. This
962 instruction is used to inform the optimizer that a particular portion of the
963 code is not reachable. This can be used to indicate that the code after a
964 no-return function cannot be reached, and other facts.</p>
968 <p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p>
973 <!-- ======================================================================= -->
974 <div class="doc_subsection"> <a name="binaryops">Binary Operations</a> </div>
975 <div class="doc_text">
976 <p>Binary operators are used to do most of the computation in a
977 program. They require two operands, execute an operation on them, and
978 produce a single value. Although, that single value might represent
979 multiple data, as is the case with the <a href="#t_packed">packed</a> data type.
980 The result value of a binary operator is not
981 necessarily the same type as its operands.</p>
982 <p>There are several different binary operators:</p>
984 <!-- _______________________________________________________________________ -->
985 <div class="doc_subsubsection"> <a name="i_add">'<tt>add</tt>'
986 Instruction</a> </div>
987 <div class="doc_text">
989 <pre> <result> = add <ty> <var1>, <var2> <i>; yields {ty}:result</i>
992 <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
994 <p>The two arguments to the '<tt>add</tt>' instruction must be either <a
995 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a> values.
996 This instruction can also take <a href="#t_packed">packed</a> versions of the values.
997 Both arguments must have identical types.</p>
999 <p>The value produced is the integer or floating point sum of the two
1002 <pre> <result> = add int 4, %var <i>; yields {int}:result = 4 + %var</i>
1005 <!-- _______________________________________________________________________ -->
1006 <div class="doc_subsubsection"> <a name="i_sub">'<tt>sub</tt>'
1007 Instruction</a> </div>
1008 <div class="doc_text">
1010 <pre> <result> = sub <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1013 <p>The '<tt>sub</tt>' instruction returns the difference of its two
1015 <p>Note that the '<tt>sub</tt>' instruction is used to represent the '<tt>neg</tt>'
1016 instruction present in most other intermediate representations.</p>
1018 <p>The two arguments to the '<tt>sub</tt>' instruction must be either <a
1019 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1021 This instruction can also take <a href="#t_packed">packed</a> versions of the values.
1022 Both arguments must have identical types.</p>
1024 <p>The value produced is the integer or floating point difference of
1025 the two operands.</p>
1027 <pre> <result> = sub int 4, %var <i>; yields {int}:result = 4 - %var</i>
1028 <result> = sub int 0, %val <i>; yields {int}:result = -%var</i>
1031 <!-- _______________________________________________________________________ -->
1032 <div class="doc_subsubsection"> <a name="i_mul">'<tt>mul</tt>'
1033 Instruction</a> </div>
1034 <div class="doc_text">
1036 <pre> <result> = mul <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1039 <p>The '<tt>mul</tt>' instruction returns the product of its two
1042 <p>The two arguments to the '<tt>mul</tt>' instruction must be either <a
1043 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1045 This instruction can also take <a href="#t_packed">packed</a> versions of the values.
1046 Both arguments must have identical types.</p>
1048 <p>The value produced is the integer or floating point product of the
1050 <p>There is no signed vs unsigned multiplication. The appropriate
1051 action is taken based on the type of the operand.</p>
1053 <pre> <result> = mul int 4, %var <i>; yields {int}:result = 4 * %var</i>
1056 <!-- _______________________________________________________________________ -->
1057 <div class="doc_subsubsection"> <a name="i_div">'<tt>div</tt>'
1058 Instruction</a> </div>
1059 <div class="doc_text">
1061 <pre> <result> = div <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1064 <p>The '<tt>div</tt>' instruction returns the quotient of its two
1067 <p>The two arguments to the '<tt>div</tt>' instruction must be either <a
1068 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1070 This instruction can also take <a href="#t_packed">packed</a> versions of the values.
1071 Both arguments must have identical types.</p>
1073 <p>The value produced is the integer or floating point quotient of the
1076 <pre> <result> = div int 4, %var <i>; yields {int}:result = 4 / %var</i>
1079 <!-- _______________________________________________________________________ -->
1080 <div class="doc_subsubsection"> <a name="i_rem">'<tt>rem</tt>'
1081 Instruction</a> </div>
1082 <div class="doc_text">
1084 <pre> <result> = rem <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1087 <p>The '<tt>rem</tt>' instruction returns the remainder from the
1088 division of its two operands.</p>
1090 <p>The two arguments to the '<tt>rem</tt>' instruction must be either <a
1091 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1093 This instruction can also take <a href="#t_packed">packed</a> versions of the values.
1094 Both arguments must have identical types.</p>
1096 <p>This returns the <i>remainder</i> of a division (where the result
1097 has the same sign as the divisor), not the <i>modulus</i> (where the
1098 result has the same sign as the dividend) of a value. For more
1099 information about the difference, see: <a
1100 href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
1103 <pre> <result> = rem int 4, %var <i>; yields {int}:result = 4 % %var</i>
1106 <!-- _______________________________________________________________________ -->
1107 <div class="doc_subsubsection"> <a name="i_setcc">'<tt>set<i>cc</i></tt>'
1108 Instructions</a> </div>
1109 <div class="doc_text">
1111 <pre> <result> = seteq <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1112 <result> = setne <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1113 <result> = setlt <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1114 <result> = setgt <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1115 <result> = setle <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1116 <result> = setge <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1119 <p>The '<tt>set<i>cc</i></tt>' family of instructions returns a boolean
1120 value based on a comparison of their two operands.</p>
1122 <p>The two arguments to the '<tt>set<i>cc</i></tt>' instructions must
1123 be of <a href="#t_firstclass">first class</a> type (it is not possible
1124 to compare '<tt>label</tt>'s, '<tt>array</tt>'s, '<tt>structure</tt>'
1125 or '<tt>void</tt>' values, etc...). Both arguments must have identical
1128 <p>The '<tt>seteq</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1129 value if both operands are equal.<br>
1130 The '<tt>setne</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1131 value if both operands are unequal.<br>
1132 The '<tt>setlt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1133 value if the first operand is less than the second operand.<br>
1134 The '<tt>setgt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1135 value if the first operand is greater than the second operand.<br>
1136 The '<tt>setle</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1137 value if the first operand is less than or equal to the second operand.<br>
1138 The '<tt>setge</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1139 value if the first operand is greater than or equal to the second
1142 <pre> <result> = seteq int 4, 5 <i>; yields {bool}:result = false</i>
1143 <result> = setne float 4, 5 <i>; yields {bool}:result = true</i>
1144 <result> = setlt uint 4, 5 <i>; yields {bool}:result = true</i>
1145 <result> = setgt sbyte 4, 5 <i>; yields {bool}:result = false</i>
1146 <result> = setle sbyte 4, 5 <i>; yields {bool}:result = true</i>
1147 <result> = setge sbyte 4, 5 <i>; yields {bool}:result = false</i>
1150 <!-- ======================================================================= -->
1151 <div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary
1152 Operations</a> </div>
1153 <div class="doc_text">
1154 <p>Bitwise binary operators are used to do various forms of
1155 bit-twiddling in a program. They are generally very efficient
1156 instructions, and can commonly be strength reduced from other
1157 instructions. They require two operands, execute an operation on them,
1158 and produce a single value. The resulting value of the bitwise binary
1159 operators is always the same type as its first operand.</p>
1161 <!-- _______________________________________________________________________ -->
1162 <div class="doc_subsubsection"> <a name="i_and">'<tt>and</tt>'
1163 Instruction</a> </div>
1164 <div class="doc_text">
1166 <pre> <result> = and <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1169 <p>The '<tt>and</tt>' instruction returns the bitwise logical and of
1170 its two operands.</p>
1172 <p>The two arguments to the '<tt>and</tt>' instruction must be <a
1173 href="#t_integral">integral</a> values. Both arguments must have
1174 identical types.</p>
1176 <p>The truth table used for the '<tt>and</tt>' instruction is:</p>
1178 <div style="align: center">
1179 <table border="1" cellspacing="0" cellpadding="4">
1210 <pre> <result> = and int 4, %var <i>; yields {int}:result = 4 & %var</i>
1211 <result> = and int 15, 40 <i>; yields {int}:result = 8</i>
1212 <result> = and int 4, 8 <i>; yields {int}:result = 0</i>
1215 <!-- _______________________________________________________________________ -->
1216 <div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div>
1217 <div class="doc_text">
1219 <pre> <result> = or <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1222 <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive
1223 or of its two operands.</p>
1225 <p>The two arguments to the '<tt>or</tt>' instruction must be <a
1226 href="#t_integral">integral</a> values. Both arguments must have
1227 identical types.</p>
1229 <p>The truth table used for the '<tt>or</tt>' instruction is:</p>
1231 <div style="align: center">
1232 <table border="1" cellspacing="0" cellpadding="4">
1263 <pre> <result> = or int 4, %var <i>; yields {int}:result = 4 | %var</i>
1264 <result> = or int 15, 40 <i>; yields {int}:result = 47</i>
1265 <result> = or int 4, 8 <i>; yields {int}:result = 12</i>
1268 <!-- _______________________________________________________________________ -->
1269 <div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>'
1270 Instruction</a> </div>
1271 <div class="doc_text">
1273 <pre> <result> = xor <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1276 <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive
1277 or of its two operands. The <tt>xor</tt> is used to implement the
1278 "one's complement" operation, which is the "~" operator in C.</p>
1280 <p>The two arguments to the '<tt>xor</tt>' instruction must be <a
1281 href="#t_integral">integral</a> values. Both arguments must have
1282 identical types.</p>
1284 <p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
1286 <div style="align: center">
1287 <table border="1" cellspacing="0" cellpadding="4">
1319 <pre> <result> = xor int 4, %var <i>; yields {int}:result = 4 ^ %var</i>
1320 <result> = xor int 15, 40 <i>; yields {int}:result = 39</i>
1321 <result> = xor int 4, 8 <i>; yields {int}:result = 12</i>
1322 <result> = xor int %V, -1 <i>; yields {int}:result = ~%V</i>
1325 <!-- _______________________________________________________________________ -->
1326 <div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>'
1327 Instruction</a> </div>
1328 <div class="doc_text">
1330 <pre> <result> = shl <ty> <var1>, ubyte <var2> <i>; yields {ty}:result</i>
1333 <p>The '<tt>shl</tt>' instruction returns the first operand shifted to
1334 the left a specified number of bits.</p>
1336 <p>The first argument to the '<tt>shl</tt>' instruction must be an <a
1337 href="#t_integer">integer</a> type. The second argument must be an '<tt>ubyte</tt>'
1340 <p>The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.</p>
1342 <pre> <result> = shl int 4, ubyte %var <i>; yields {int}:result = 4 << %var</i>
1343 <result> = shl int 4, ubyte 2 <i>; yields {int}:result = 16</i>
1344 <result> = shl int 1, ubyte 10 <i>; yields {int}:result = 1024</i>
1347 <!-- _______________________________________________________________________ -->
1348 <div class="doc_subsubsection"> <a name="i_shr">'<tt>shr</tt>'
1349 Instruction</a> </div>
1350 <div class="doc_text">
1352 <pre> <result> = shr <ty> <var1>, ubyte <var2> <i>; yields {ty}:result</i>
1355 <p>The '<tt>shr</tt>' instruction returns the first operand shifted to
1356 the right a specified number of bits.</p>
1358 <p>The first argument to the '<tt>shr</tt>' instruction must be an <a
1359 href="#t_integer">integer</a> type. The second argument must be an '<tt>ubyte</tt>'
1362 <p>If the first argument is a <a href="#t_signed">signed</a> type, the
1363 most significant bit is duplicated in the newly free'd bit positions.
1364 If the first argument is unsigned, zero bits shall fill the empty
1367 <pre> <result> = shr int 4, ubyte %var <i>; yields {int}:result = 4 >> %var</i>
1368 <result> = shr uint 4, ubyte 1 <i>; yields {uint}:result = 2</i>
1369 <result> = shr int 4, ubyte 2 <i>; yields {int}:result = 1</i>
1370 <result> = shr sbyte 4, ubyte 3 <i>; yields {sbyte}:result = 0</i>
1371 <result> = shr sbyte -2, ubyte 1 <i>; yields {sbyte}:result = -1</i>
1374 <!-- ======================================================================= -->
1375 <div class="doc_subsection"> <a name="memoryops">Memory Access
1376 Operations</a></div>
1377 <div class="doc_text">
1378 <p>A key design point of an SSA-based representation is how it
1379 represents memory. In LLVM, no memory locations are in SSA form, which
1380 makes things very simple. This section describes how to read, write,
1381 allocate and free memory in LLVM.</p>
1383 <!-- _______________________________________________________________________ -->
1384 <div class="doc_subsubsection"> <a name="i_malloc">'<tt>malloc</tt>'
1385 Instruction</a> </div>
1386 <div class="doc_text">
1388 <pre> <result> = malloc <type>, uint <NumElements> <i>; yields {type*}:result</i>
1389 <result> = malloc <type> <i>; yields {type*}:result</i>
1392 <p>The '<tt>malloc</tt>' instruction allocates memory from the system
1393 heap and returns a pointer to it.</p>
1395 <p>The '<tt>malloc</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
1396 bytes of memory from the operating system and returns a pointer of the
1397 appropriate type to the program. The second form of the instruction is
1398 a shorter version of the first instruction that defaults to allocating
1400 <p>'<tt>type</tt>' must be a sized type.</p>
1402 <p>Memory is allocated using the system "<tt>malloc</tt>" function, and
1403 a pointer is returned.</p>
1405 <pre> %array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
1408 href="#i_add">add</a> uint 2, 2 <i>; yields {uint}:size = uint 4</i>
1409 %array1 = malloc ubyte, uint 4 <i>; yields {ubyte*}:array1</i>
1410 %array2 = malloc [12 x ubyte], uint %size <i>; yields {[12 x ubyte]*}:array2</i>
1413 <!-- _______________________________________________________________________ -->
1414 <div class="doc_subsubsection"> <a name="i_free">'<tt>free</tt>'
1415 Instruction</a> </div>
1416 <div class="doc_text">
1418 <pre> free <type> <value> <i>; yields {void}</i>
1421 <p>The '<tt>free</tt>' instruction returns memory back to the unused
1422 memory heap, to be reallocated in the future.</p>
1425 <p>'<tt>value</tt>' shall be a pointer value that points to a value
1426 that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>'
1429 <p>Access to the memory pointed to by the pointer is not longer defined
1430 after this instruction executes.</p>
1432 <pre> %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
1433 free [4 x ubyte]* %array
1436 <!-- _______________________________________________________________________ -->
1437 <div class="doc_subsubsection"> <a name="i_alloca">'<tt>alloca</tt>'
1438 Instruction</a> </div>
1439 <div class="doc_text">
1441 <pre> <result> = alloca <type>, uint <NumElements> <i>; yields {type*}:result</i>
1442 <result> = alloca <type> <i>; yields {type*}:result</i>
1445 <p>The '<tt>alloca</tt>' instruction allocates memory on the current
1446 stack frame of the procedure that is live until the current function
1447 returns to its caller.</p>
1449 <p>The the '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
1450 bytes of memory on the runtime stack, returning a pointer of the
1451 appropriate type to the program. The second form of the instruction is
1452 a shorter version of the first that defaults to allocating one element.</p>
1453 <p>'<tt>type</tt>' may be any sized type.</p>
1455 <p>Memory is allocated, a pointer is returned. '<tt>alloca</tt>'d
1456 memory is automatically released when the function returns. The '<tt>alloca</tt>'
1457 instruction is commonly used to represent automatic variables that must
1458 have an address available. When the function returns (either with the <tt><a
1459 href="#i_ret">ret</a></tt> or <tt><a href="#i_invoke">invoke</a></tt>
1460 instructions), the memory is reclaimed.</p>
1462 <pre> %ptr = alloca int <i>; yields {int*}:ptr</i>
1463 %ptr = alloca int, uint 4 <i>; yields {int*}:ptr</i>
1466 <!-- _______________________________________________________________________ -->
1467 <div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
1468 Instruction</a> </div>
1469 <div class="doc_text">
1471 <pre> <result> = load <ty>* <pointer><br> <result> = volatile load <ty>* <pointer><br></pre>
1473 <p>The '<tt>load</tt>' instruction is used to read from memory.</p>
1475 <p>The argument to the '<tt>load</tt>' instruction specifies the memory
1476 address to load from. The pointer must point to a <a
1477 href="#t_firstclass">first class</a> type. If the <tt>load</tt> is
1478 marked as <tt>volatile</tt> then the optimizer is not allowed to modify
1479 the number or order of execution of this <tt>load</tt> with other
1480 volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
1483 <p>The location of memory pointed to is loaded.</p>
1485 <pre> %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
1487 href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
1488 %val = load int* %ptr <i>; yields {int}:val = int 3</i>
1491 <!-- _______________________________________________________________________ -->
1492 <div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
1493 Instruction</a> </div>
1495 <pre> store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
1496 volatile store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
1499 <p>The '<tt>store</tt>' instruction is used to write to memory.</p>
1501 <p>There are two arguments to the '<tt>store</tt>' instruction: a value
1502 to store and an address to store it into. The type of the '<tt><pointer></tt>'
1503 operand must be a pointer to the type of the '<tt><value></tt>'
1504 operand. If the <tt>store</tt> is marked as <tt>volatile</tt> then the
1505 optimizer is not allowed to modify the number or order of execution of
1506 this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a
1507 href="#i_store">store</a></tt> instructions.</p>
1509 <p>The contents of memory are updated to contain '<tt><value></tt>'
1510 at the location specified by the '<tt><pointer></tt>' operand.</p>
1512 <pre> %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
1514 href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
1515 %val = load int* %ptr <i>; yields {int}:val = int 3</i>
1517 <!-- _______________________________________________________________________ -->
1518 <div class="doc_subsubsection">
1519 <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
1522 <div class="doc_text">
1525 <result> = getelementptr <ty>* <ptrval>{, <ty> <idx>}*
1531 The '<tt>getelementptr</tt>' instruction is used to get the address of a
1532 subelement of an aggregate data structure.</p>
1536 <p>This instruction takes a list of integer constants that indicate what
1537 elements of the aggregate object to index to. The actual types of the arguments
1538 provided depend on the type of the first pointer argument. The
1539 '<tt>getelementptr</tt>' instruction is used to index down through the type
1540 levels of a structure. When indexing into a structure, only <tt>uint</tt>
1541 integer constants are allowed. When indexing into an array or pointer
1542 <tt>int</tt> and <tt>long</tt> indexes are allowed of any sign.</p>
1544 <p>For example, let's consider a C code fragment and how it gets
1545 compiled to LLVM:</p>
1559 int *foo(struct ST *s) {
1560 return &s[1].Z.B[5][13];
1564 <p>The LLVM code generated by the GCC frontend is:</p>
1567 %RT = type { sbyte, [10 x [20 x int]], sbyte }
1568 %ST = type { int, double, %RT }
1572 int* %foo(%ST* %s) {
1574 %reg = getelementptr %ST* %s, int 1, uint 2, uint 1, int 5, int 13
1581 <p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
1582 on the pointer type that is being index into. <a href="#t_pointer">Pointer</a>
1583 and <a href="#t_array">array</a> types require <tt>uint</tt>, <tt>int</tt>,
1584 <tt>ulong</tt>, or <tt>long</tt> values, and <a href="#t_struct">structure</a>
1585 types require <tt>uint</tt> <b>constants</b>.</p>
1587 <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
1588 type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ int, double, %RT
1589 }</tt>' type, a structure. The second index indexes into the third element of
1590 the structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]],
1591 sbyte }</tt>' type, another structure. The third index indexes into the second
1592 element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
1593 array. The two dimensions of the array are subscripted into, yielding an
1594 '<tt>int</tt>' type. The '<tt>getelementptr</tt>' instruction return a pointer
1595 to this element, thus computing a value of '<tt>int*</tt>' type.</p>
1597 <p>Note that it is perfectly legal to index partially through a
1598 structure, returning a pointer to an inner element. Because of this,
1599 the LLVM code for the given testcase is equivalent to:</p>
1602 int* "foo"(%ST* %s) {
1603 %t1 = getelementptr %ST* %s, int 1 <i>; yields %ST*:%t1</i>
1604 %t2 = getelementptr %ST* %t1, int 0, uint 2 <i>; yields %RT*:%t2</i>
1605 %t3 = getelementptr %RT* %t2, int 0, uint 1 <i>; yields [10 x [20 x int]]*:%t3</i>
1606 %t4 = getelementptr [10 x [20 x int]]* %t3, int 0, int 5 <i>; yields [20 x int]*:%t4</i>
1607 %t5 = getelementptr [20 x int]* %t4, int 0, int 13 <i>; yields int*:%t5</i>
1613 <i>; yields [12 x ubyte]*:aptr</i>
1614 %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, uint 1
1618 <!-- ======================================================================= -->
1619 <div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
1620 <div class="doc_text">
1621 <p>The instructions in this category are the "miscellaneous"
1622 instructions, which defy better classification.</p>
1624 <!-- _______________________________________________________________________ -->
1625 <div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>'
1626 Instruction</a> </div>
1627 <div class="doc_text">
1629 <pre> <result> = phi <ty> [ <val0>, <label0>], ...<br></pre>
1631 <p>The '<tt>phi</tt>' instruction is used to implement the φ node in
1632 the SSA graph representing the function.</p>
1634 <p>The type of the incoming values are specified with the first type
1635 field. After this, the '<tt>phi</tt>' instruction takes a list of pairs
1636 as arguments, with one pair for each predecessor basic block of the
1637 current block. Only values of <a href="#t_firstclass">first class</a>
1638 type may be used as the value arguments to the PHI node. Only labels
1639 may be used as the label arguments.</p>
1640 <p>There must be no non-phi instructions between the start of a basic
1641 block and the PHI instructions: i.e. PHI instructions must be first in
1644 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the
1645 value specified by the parameter, depending on which basic block we
1646 came from in the last <a href="#terminators">terminator</a> instruction.</p>
1648 <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>
1651 <!-- _______________________________________________________________________ -->
1652 <div class="doc_subsubsection">
1653 <a name="i_cast">'<tt>cast .. to</tt>' Instruction</a>
1656 <div class="doc_text">
1661 <result> = cast <ty> <value> to <ty2> <i>; yields ty2</i>
1667 The '<tt>cast</tt>' instruction is used as the primitive means to convert
1668 integers to floating point, change data type sizes, and break type safety (by
1676 The '<tt>cast</tt>' instruction takes a value to cast, which must be a first
1677 class value, and a type to cast it to, which must also be a <a
1678 href="#t_firstclass">first class</a> type.
1684 This instruction follows the C rules for explicit casts when determining how the
1685 data being cast must change to fit in its new container.
1689 When casting to bool, any value that would be considered true in the context of
1690 a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>' values,
1691 all else are '<tt>false</tt>'.
1695 When extending an integral value from a type of one signness to another (for
1696 example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
1697 <b>source</b> value is signed, and zero-extended if the source value is
1698 unsigned. <tt>bool</tt> values are always zero extended into either zero or
1705 %X = cast int 257 to ubyte <i>; yields ubyte:1</i>
1706 %Y = cast int 123 to bool <i>; yields bool:true</i>
1710 <!-- _______________________________________________________________________ -->
1711 <div class="doc_subsubsection">
1712 <a name="i_select">'<tt>select</tt>' Instruction</a>
1715 <div class="doc_text">
1720 <result> = select bool <cond>, <ty> <val1>, <ty> <val2> <i>; yields ty</i>
1726 The '<tt>select</tt>' instruction is used to choose one value based on a
1727 condition, without branching.
1734 The '<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.
1740 If the boolean condition evaluates to true, the instruction returns the first
1741 value argument, otherwise it returns the second value argument.
1747 %X = select bool true, ubyte 17, ubyte 42 <i>; yields ubyte:17</i>
1755 <!-- _______________________________________________________________________ -->
1756 <div class="doc_subsubsection"> <a name="i_call">'<tt>call</tt>'
1757 Instruction</a> </div>
1758 <div class="doc_text">
1760 <pre> <result> = call <ty>* <fnptrval>(<param list>)<br></pre>
1762 <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
1764 <p>This instruction requires several arguments:</p>
1767 <p>'<tt>ty</tt>': shall be the signature of the pointer to function
1768 value being invoked. The argument types must match the types implied
1769 by this signature.</p>
1772 <p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a
1773 function to be invoked. In most cases, this is a direct function
1774 invocation, but indirect <tt>call</tt>s are just as possible,
1775 calling an arbitrary pointer to function values.</p>
1778 <p>'<tt>function args</tt>': argument list whose types match the
1779 function signature argument types. If the function signature
1780 indicates the function accepts a variable number of arguments, the
1781 extra arguments can be specified.</p>
1785 <p>The '<tt>call</tt>' instruction is used to cause control flow to
1786 transfer to a specified function, with its incoming arguments bound to
1787 the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>'
1788 instruction in the called function, control flow continues with the
1789 instruction after the function call, and the return value of the
1790 function is bound to the result argument. This is a simpler case of
1791 the <a href="#i_invoke">invoke</a> instruction.</p>
1793 <pre> %retval = call int %test(int %argc)<br> call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);<br></pre>
1796 <!-- _______________________________________________________________________ -->
1797 <div class="doc_subsubsection">
1798 <a name="i_vanext">'<tt>vanext</tt>' Instruction</a>
1801 <div class="doc_text">
1806 <resultarglist> = vanext <va_list> <arglist>, <argty>
1811 <p>The '<tt>vanext</tt>' instruction is used to access arguments passed
1812 through the "variable argument" area of a function call. It is used to
1813 implement the <tt>va_arg</tt> macro in C.</p>
1817 <p>This instruction takes a <tt>va_list</tt> value and the type of the
1818 argument. It returns another <tt>va_list</tt>. The actual type of
1819 <tt>va_list</tt> may be defined differently for different targets. Most targets
1820 use a <tt>va_list</tt> type of <tt>sbyte*</tt> or some other pointer type.</p>
1824 <p>The '<tt>vanext</tt>' instruction advances the specified <tt>va_list</tt>
1825 past an argument of the specified type. In conjunction with the <a
1826 href="#i_vaarg"><tt>vaarg</tt></a> instruction, it is used to implement
1827 the <tt>va_arg</tt> macro available in C. For more information, see
1828 the variable argument handling <a href="#int_varargs">Intrinsic
1831 <p>It is legal for this instruction to be called in a function which
1832 does not take a variable number of arguments, for example, the <tt>vfprintf</tt>
1835 <p><tt>vanext</tt> is an LLVM instruction instead of an <a
1836 href="#intrinsics">intrinsic function</a> because it takes a type as an
1837 argument. The type refers to the current argument in the <tt>va_list</tt>, it
1838 tells the compiler how far on the stack it needs to advance to find the next
1843 <p>See the <a href="#int_varargs">variable argument processing</a>
1848 <!-- _______________________________________________________________________ -->
1849 <div class="doc_subsubsection">
1850 <a name="i_vaarg">'<tt>vaarg</tt>' Instruction</a>
1853 <div class="doc_text">
1858 <resultval> = vaarg <va_list> <arglist>, <argty>
1863 <p>The '<tt>vaarg</tt>' instruction is used to access arguments passed through
1864 the "variable argument" area of a function call. It is used to implement the
1865 <tt>va_arg</tt> macro in C.</p>
1869 <p>This instruction takes a <tt>va_list</tt> value and the type of the
1870 argument. It returns a value of the specified argument type. Again, the actual
1871 type of <tt>va_list</tt> is target specific.</p>
1875 <p>The '<tt>vaarg</tt>' instruction loads an argument of the specified type from
1876 the specified <tt>va_list</tt>. In conjunction with the <a
1877 href="#i_vanext"><tt>vanext</tt></a> instruction, it is used to implement the
1878 <tt>va_arg</tt> macro available in C. For more information, see the variable
1879 argument handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
1881 <p>It is legal for this instruction to be called in a function which does not
1882 take a variable number of arguments, for example, the <tt>vfprintf</tt>
1885 <p><tt>vaarg</tt> is an LLVM instruction instead of an <a
1886 href="#intrinsics">intrinsic function</a> because it takes an type as an
1891 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
1895 <!-- *********************************************************************** -->
1896 <div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
1897 <!-- *********************************************************************** -->
1899 <div class="doc_text">
1901 <p>LLVM supports the notion of an "intrinsic function". These functions have
1902 well known names and semantics, and are required to follow certain
1903 restrictions. Overall, these instructions represent an extension mechanism for
1904 the LLVM language that does not require changing all of the transformations in
1905 LLVM to add to the language (or the bytecode reader/writer, the parser,
1908 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix, this
1909 prefix is reserved in LLVM for intrinsic names, thus functions may not be named
1910 this. Intrinsic functions must always be external functions: you cannot define
1911 the body of intrinsic functions. Intrinsic functions may only be used in call
1912 or invoke instructions: it is illegal to take the address of an intrinsic
1913 function. Additionally, because intrinsic functions are part of the LLVM
1914 language, it is required that they all be documented here if any are added.</p>
1918 Adding an intrinsic to LLVM is straight-forward if it is possible to express the
1919 concept in LLVM directly (ie, code generator support is not _required_). To do
1920 this, extend the default implementation of the IntrinsicLowering class to handle
1921 the intrinsic. Code generators use this class to lower intrinsics they do not
1922 understand to raw LLVM instructions that they do.
1927 <!-- ======================================================================= -->
1928 <div class="doc_subsection">
1929 <a name="int_varargs">Variable Argument Handling Intrinsics</a>
1932 <div class="doc_text">
1934 <p>Variable argument support is defined in LLVM with the <a
1935 href="#i_vanext"><tt>vanext</tt></a> instruction and these three
1936 intrinsic functions. These functions are related to the similarly
1937 named macros defined in the <tt><stdarg.h></tt> header file.</p>
1939 <p>All of these functions operate on arguments that use a
1940 target-specific value type "<tt>va_list</tt>". The LLVM assembly
1941 language reference manual does not define what this type is, so all
1942 transformations should be prepared to handle intrinsics with any type
1945 <p>This example shows how the <a href="#i_vanext"><tt>vanext</tt></a>
1946 instruction and the variable argument handling intrinsic functions are
1950 int %test(int %X, ...) {
1951 ; Initialize variable argument processing
1952 %ap = call sbyte* %<a href="#i_va_start">llvm.va_start</a>()
1954 ; Read a single integer argument
1955 %tmp = vaarg sbyte* %ap, int
1957 ; Advance to the next argument
1958 %ap2 = vanext sbyte* %ap, int
1960 ; Demonstrate usage of llvm.va_copy and llvm.va_end
1961 %aq = call sbyte* %<a href="#i_va_copy">llvm.va_copy</a>(sbyte* %ap2)
1962 call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %aq)
1964 ; Stop processing of arguments.
1965 call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %ap2)
1971 <!-- _______________________________________________________________________ -->
1972 <div class="doc_subsubsection">
1973 <a name="i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
1977 <div class="doc_text">
1979 <pre> call <va_list> ()* %llvm.va_start()<br></pre>
1981 <p>The '<tt>llvm.va_start</tt>' intrinsic returns a new <tt><arglist></tt>
1982 for subsequent use by the variable argument intrinsics.</p>
1984 <p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
1985 macro available in C. In a target-dependent way, it initializes and
1986 returns a <tt>va_list</tt> element, so that the next <tt>vaarg</tt>
1987 will produce the first variable argument passed to the function. Unlike
1988 the C <tt>va_start</tt> macro, this intrinsic does not need to know the
1989 last argument of the function, the compiler can figure that out.</p>
1990 <p>Note that this intrinsic function is only legal to be called from
1991 within the body of a variable argument function.</p>
1994 <!-- _______________________________________________________________________ -->
1995 <div class="doc_subsubsection">
1996 <a name="i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
1999 <div class="doc_text">
2001 <pre> call void (<va_list>)* %llvm.va_end(<va_list> <arglist>)<br></pre>
2003 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt><arglist></tt>
2004 which has been initialized previously with <tt><a href="#i_va_start">llvm.va_start</a></tt>
2005 or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
2007 <p>The argument is a <tt>va_list</tt> to destroy.</p>
2009 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
2010 macro available in C. In a target-dependent way, it destroys the <tt>va_list</tt>.
2011 Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
2012 href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly
2013 with calls to <tt>llvm.va_end</tt>.</p>
2016 <!-- _______________________________________________________________________ -->
2017 <div class="doc_subsubsection">
2018 <a name="i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
2021 <div class="doc_text">
2026 call <va_list> (<va_list>)* %llvm.va_copy(<va_list> <destarglist>)
2031 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position
2032 from the source argument list to the destination argument list.</p>
2036 <p>The argument is the <tt>va_list</tt> to copy.</p>
2040 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
2041 macro available in C. In a target-dependent way, it copies the source
2042 <tt>va_list</tt> element into the returned list. This intrinsic is necessary
2043 because the <tt><a href="#i_va_start">llvm.va_start</a></tt> intrinsic may be
2044 arbitrarily complex and require memory allocation, for example.</p>
2048 <!-- ======================================================================= -->
2049 <div class="doc_subsection">
2050 <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
2053 <div class="doc_text">
2056 LLVM support for <a href="GarbageCollection.html">Accurate Garbage
2057 Collection</a> requires the implementation and generation of these intrinsics.
2058 These intrinsics allow identification of <a href="#i_gcroot">GC roots on the
2059 stack</a>, as well as garbage collector implementations that require <a
2060 href="#i_gcread">read</a> and <a href="#i_gcwrite">write</a> barriers.
2061 Front-ends for type-safe garbage collected languages should generate these
2062 intrinsics to make use of the LLVM garbage collectors. For more details, see <a
2063 href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>.
2067 <!-- _______________________________________________________________________ -->
2068 <div class="doc_subsubsection">
2069 <a name="i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
2072 <div class="doc_text">
2077 call void (<ty>**, <ty2>*)* %llvm.gcroot(<ty>** %ptrloc, <ty2>* %metadata)
2082 <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existance of a GC root to
2083 the code generator, and allows some metadata to be associated with it.</p>
2087 <p>The first argument specifies the address of a stack object that contains the
2088 root pointer. The second pointer (which must be either a constant or a global
2089 value address) contains the meta-data to be associated with the root.</p>
2093 <p>At runtime, a call to this intrinsics stores a null pointer into the "ptrloc"
2094 location. At compile-time, the code generator generates information to allow
2095 the runtime to find the pointer at GC safe points.
2101 <!-- _______________________________________________________________________ -->
2102 <div class="doc_subsubsection">
2103 <a name="i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
2106 <div class="doc_text">
2111 call sbyte* (sbyte**)* %llvm.gcread(sbyte** %Ptr)
2116 <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
2117 locations, allowing garbage collector implementations that require read
2122 <p>The argument is the address to read from, which should be an address
2123 allocated from the garbage collector.</p>
2127 <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
2128 instruction, but may be replaced with substantially more complex code by the
2129 garbage collector runtime, as needed.</p>
2134 <!-- _______________________________________________________________________ -->
2135 <div class="doc_subsubsection">
2136 <a name="i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
2139 <div class="doc_text">
2144 call void (sbyte*, sbyte**)* %llvm.gcwrite(sbyte* %P1, sbyte** %P2)
2149 <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
2150 locations, allowing garbage collector implementations that require write
2151 barriers (such as generational or reference counting collectors).</p>
2155 <p>The first argument is the reference to store, and the second is the heap
2156 location to store to.</p>
2160 <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
2161 instruction, but may be replaced with substantially more complex code by the
2162 garbage collector runtime, as needed.</p>
2168 <!-- ======================================================================= -->
2169 <div class="doc_subsection">
2170 <a name="int_codegen">Code Generator Intrinsics</a>
2173 <div class="doc_text">
2175 These intrinsics are provided by LLVM to expose special features that may only
2176 be implemented with code generator support.
2181 <!-- _______________________________________________________________________ -->
2182 <div class="doc_subsubsection">
2183 <a name="i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
2186 <div class="doc_text">
2190 call void* ()* %llvm.returnaddress(uint <level>)
2196 The '<tt>llvm.returnaddress</tt>' intrinsic returns a target-specific value
2197 indicating the return address of the current function or one of its callers.
2203 The argument to this intrinsic indicates which function to return the address
2204 for. Zero indicates the calling function, one indicates its caller, etc. The
2205 argument is <b>required</b> to be a constant integer value.
2211 The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer indicating
2212 the return address of the specified call frame, or zero if it cannot be
2213 identified. The value returned by this intrinsic is likely to be incorrect or 0
2214 for arguments other than zero, so it should only be used for debugging purposes.
2218 Note that calling this intrinsic does not prevent function inlining or other
2219 aggressive transformations, so the value returned may not that of the obvious
2220 source-language caller.
2225 <!-- _______________________________________________________________________ -->
2226 <div class="doc_subsubsection">
2227 <a name="i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
2230 <div class="doc_text">
2234 call void* ()* %llvm.frameaddress(uint <level>)
2240 The '<tt>llvm.frameaddress</tt>' intrinsic returns the target-specific frame
2241 pointer value for the specified stack frame.
2247 The argument to this intrinsic indicates which function to return the frame
2248 pointer for. Zero indicates the calling function, one indicates its caller,
2249 etc. The argument is <b>required</b> to be a constant integer value.
2255 The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer indicating
2256 the frame address of the specified call frame, or zero if it cannot be
2257 identified. The value returned by this intrinsic is likely to be incorrect or 0
2258 for arguments other than zero, so it should only be used for debugging purposes.
2262 Note that calling this intrinsic does not prevent function inlining or other
2263 aggressive transformations, so the value returned may not that of the obvious
2264 source-language caller.
2268 <!-- ======================================================================= -->
2269 <div class="doc_subsection">
2270 <a name="int_os">Operating System Intrinsics</a>
2273 <div class="doc_text">
2275 These intrinsics are provided by LLVM to support the implementation of
2276 operating system level code.
2281 <!-- _______________________________________________________________________ -->
2282 <div class="doc_subsubsection">
2283 <a name="i_readport">'<tt>llvm.readport</tt>' Intrinsic</a>
2286 <div class="doc_text">
2290 call <integer type> (<integer type>)* %llvm.readport (<integer type> <address>)
2296 The '<tt>llvm.readport</tt>' intrinsic reads data from the specified hardware
2303 The argument to this intrinsic indicates the hardware I/O address from which
2304 to read the data. The address is in the hardware I/O address namespace (as
2305 opposed to being a memory location for memory mapped I/O).
2311 The '<tt>llvm.readport</tt>' intrinsic reads data from the hardware I/O port
2312 specified by <i>address</i> and returns the value. The address and return
2313 value must be integers, but the size is dependent upon the platform upon which
2314 the program is code generated. For example, on x86, the address must be an
2315 unsigned 16 bit value, and the return value must be 8, 16, or 32 bits.
2320 <!-- _______________________________________________________________________ -->
2321 <div class="doc_subsubsection">
2322 <a name="i_writeport">'<tt>llvm.writeport</tt>' Intrinsic</a>
2325 <div class="doc_text">
2329 call void (<integer type>, <integer type>)* %llvm.writeport (<integer type> <value>, <integer type> <address>)
2335 The '<tt>llvm.writeport</tt>' intrinsic writes data to the specified hardware
2342 The first argument is the value to write to the I/O port.
2346 The second argument indicates the hardware I/O address to which data should be
2347 written. The address is in the hardware I/O address namespace (as opposed to
2348 being a memory location for memory mapped I/O).
2354 The '<tt>llvm.writeport</tt>' intrinsic writes <i>value</i> to the I/O port
2355 specified by <i>address</i>. The address and value must be integers, but the
2356 size is dependent upon the platform upon which the program is code generated.
2357 For example, on x86, the address must be an unsigned 16 bit value, and the
2358 value written must be 8, 16, or 32 bits in length.
2363 <!-- _______________________________________________________________________ -->
2364 <div class="doc_subsubsection">
2365 <a name="i_readio">'<tt>llvm.readio</tt>' Intrinsic</a>
2368 <div class="doc_text">
2372 call <result> (<ty>*)* %llvm.readio (<ty> * <pointer>)
2378 The '<tt>llvm.readio</tt>' intrinsic reads data from a memory mapped I/O
2385 The argument to this intrinsic is a pointer indicating the memory address from
2386 which to read the data. The data must be a
2387 <a href="#t_firstclass">first class</a> type.
2393 The '<tt>llvm.readio</tt>' intrinsic reads data from a memory mapped I/O
2394 location specified by <i>pointer</i> and returns the value. The argument must
2395 be a pointer, and the return value must be a
2396 <a href="#t_firstclass">first class</a> type. However, certain architectures
2397 may not support I/O on all first class types. For example, 32 bit processors
2398 may only support I/O on data types that are 32 bits or less.
2402 This intrinsic enforces an in-order memory model for llvm.readio and
2403 llvm.writeio calls on machines that use dynamic scheduling. Dynamically
2404 scheduled processors may execute loads and stores out of order, re-ordering at
2405 run time accesses to memory mapped I/O registers. Using these intrinsics
2406 ensures that accesses to memory mapped I/O registers occur in program order.
2411 <!-- _______________________________________________________________________ -->
2412 <div class="doc_subsubsection">
2413 <a name="i_writeio">'<tt>llvm.writeio</tt>' Intrinsic</a>
2416 <div class="doc_text">
2420 call void (<ty1>, <ty2>*)* %llvm.writeio (<ty1> <value>, <ty2> * <pointer>)
2426 The '<tt>llvm.writeio</tt>' intrinsic writes data to the specified memory
2433 The first argument is the value to write to the memory mapped I/O location.
2434 The second argument is a pointer indicating the memory address to which the
2435 data should be written.
2441 The '<tt>llvm.writeio</tt>' intrinsic writes <i>value</i> to the memory mapped
2442 I/O address specified by <i>pointer</i>. The value must be a
2443 <a href="#t_firstclass">first class</a> type. However, certain architectures
2444 may not support I/O on all first class types. For example, 32 bit processors
2445 may only support I/O on data types that are 32 bits or less.
2449 This intrinsic enforces an in-order memory model for llvm.readio and
2450 llvm.writeio calls on machines that use dynamic scheduling. Dynamically
2451 scheduled processors may execute loads and stores out of order, re-ordering at
2452 run time accesses to memory mapped I/O registers. Using these intrinsics
2453 ensures that accesses to memory mapped I/O registers occur in program order.
2458 <!-- ======================================================================= -->
2459 <div class="doc_subsection">
2460 <a name="int_libc">Standard C Library Intrinsics</a>
2463 <div class="doc_text">
2465 LLVM provides intrinsics for a few important standard C library functions.
2466 These intrinsics allow source-language front-ends to pass information about the
2467 alignment of the pointer arguments to the code generator, providing opportunity
2468 for more efficient code generation.
2473 <!-- _______________________________________________________________________ -->
2474 <div class="doc_subsubsection">
2475 <a name="i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
2478 <div class="doc_text">
2482 call void (sbyte*, sbyte*, uint, uint)* %llvm.memcpy(sbyte* <dest>, sbyte* <src>,
2483 uint <len>, uint <align>)
2489 The '<tt>llvm.memcpy</tt>' intrinsic copies a block of memory from the source
2490 location to the destination location.
2494 Note that, unlike the standard libc function, the <tt>llvm.memcpy</tt> intrinsic
2495 does not return a value, and takes an extra alignment argument.
2501 The first argument is a pointer to the destination, the second is a pointer to
2502 the source. The third argument is an (arbitrarily sized) integer argument
2503 specifying the number of bytes to copy, and the fourth argument is the alignment
2504 of the source and destination locations.
2508 If the call to this intrinisic has an alignment value that is not 0 or 1, then
2509 the caller guarantees that the size of the copy is a multiple of the alignment
2510 and that both the source and destination pointers are aligned to that boundary.
2516 The '<tt>llvm.memcpy</tt>' intrinsic copies a block of memory from the source
2517 location to the destination location, which are not allowed to overlap. It
2518 copies "len" bytes of memory over. If the argument is known to be aligned to
2519 some boundary, this can be specified as the fourth argument, otherwise it should
2525 <!-- _______________________________________________________________________ -->
2526 <div class="doc_subsubsection">
2527 <a name="i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
2530 <div class="doc_text">
2534 call void (sbyte*, sbyte*, uint, uint)* %llvm.memmove(sbyte* <dest>, sbyte* <src>,
2535 uint <len>, uint <align>)
2541 The '<tt>llvm.memmove</tt>' intrinsic moves a block of memory from the source
2542 location to the destination location. It is similar to the '<tt>llvm.memcpy</tt>'
2543 intrinsic but allows the two memory locations to overlap.
2547 Note that, unlike the standard libc function, the <tt>llvm.memmove</tt> intrinsic
2548 does not return a value, and takes an extra alignment argument.
2554 The first argument is a pointer to the destination, the second is a pointer to
2555 the source. The third argument is an (arbitrarily sized) integer argument
2556 specifying the number of bytes to copy, and the fourth argument is the alignment
2557 of the source and destination locations.
2561 If the call to this intrinisic has an alignment value that is not 0 or 1, then
2562 the caller guarantees that the size of the copy is a multiple of the alignment
2563 and that both the source and destination pointers are aligned to that boundary.
2569 The '<tt>llvm.memmove</tt>' intrinsic copies a block of memory from the source
2570 location to the destination location, which may overlap. It
2571 copies "len" bytes of memory over. If the argument is known to be aligned to
2572 some boundary, this can be specified as the fourth argument, otherwise it should
2578 <!-- _______________________________________________________________________ -->
2579 <div class="doc_subsubsection">
2580 <a name="i_memset">'<tt>llvm.memset</tt>' Intrinsic</a>
2583 <div class="doc_text">
2587 call void (sbyte*, ubyte, uint, uint)* %llvm.memset(sbyte* <dest>, ubyte <val>,
2588 uint <len>, uint <align>)
2594 The '<tt>llvm.memset</tt>' intrinsic fills a block of memory with a particular
2599 Note that, unlike the standard libc function, the <tt>llvm.memset</tt> intrinsic
2600 does not return a value, and takes an extra alignment argument.
2606 The first argument is a pointer to the destination to fill, the second is the
2607 byte value to fill it with, the third argument is an (arbitrarily sized) integer
2608 argument specifying the number of bytes to fill, and the fourth argument is the
2609 known alignment of destination location.
2613 If the call to this intrinisic has an alignment value that is not 0 or 1, then
2614 the caller guarantees that the size of the copy is a multiple of the alignment
2615 and that the destination pointer is aligned to that boundary.
2621 The '<tt>llvm.memset</tt>' intrinsic fills "len" bytes of memory starting at the
2622 destination location. If the argument is known to be aligned to some boundary,
2623 this can be specified as the fourth argument, otherwise it should be set to 0 or
2629 <!-- _______________________________________________________________________ -->
2630 <div class="doc_subsubsection">
2631 <a name="i_isunordered">'<tt>llvm.isunordered</tt>' Intrinsic</a>
2634 <div class="doc_text">
2638 call bool (<float or double>, <float or double>)* %llvm.isunordered(<float or double> Val1,
2639 <float or double> Val2)
2645 The '<tt>llvm.isunordered</tt>' intrinsic returns true if either or both of the
2646 specified floating point values is a NAN.
2652 The arguments are floating point numbers of the same type.
2658 If either or both of the arguments is a SNAN or QNAN, it returns true, otherwise
2666 <!-- ======================================================================= -->
2667 <div class="doc_subsection">
2668 <a name="int_debugger">Debugger Intrinsics</a>
2671 <div class="doc_text">
2673 The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> prefix),
2674 are described in the <a
2675 href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source Level
2676 Debugging</a> document.
2681 <!-- *********************************************************************** -->
2684 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
2685 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
2686 <a href="http://validator.w3.org/check/referer"><img
2687 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
2689 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
2690 <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
2691 Last modified: $Date$