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 <link rel="stylesheet" href="llvm.css" type="text/css">
11 <div class="doc_title"> LLVM Language Reference Manual </div>
13 <li><a href="#abstract">Abstract</a></li>
14 <li><a href="#introduction">Introduction</a></li>
15 <li><a href="#identifiers">Identifiers</a></li>
16 <li><a href="#typesystem">Type System</a>
18 <li><a href="#t_primitive">Primitive Types</a>
20 <li><a href="#t_classifications">Type Classifications</a></li>
23 <li><a href="#t_derived">Derived Types</a>
25 <li><a href="#t_array">Array Type</a></li>
26 <li><a href="#t_function">Function Type</a></li>
27 <li><a href="#t_pointer">Pointer Type</a></li>
28 <li><a href="#t_struct">Structure Type</a></li>
29 <!-- <li><a href="#t_packed" >Packed Type</a> -->
34 <li><a href="#highlevel">High Level Structure</a>
36 <li><a href="#modulestructure">Module Structure</a></li>
37 <li><a href="#globalvars">Global Variables</a></li>
38 <li><a href="#functionstructure">Function Structure</a></li>
41 <li><a href="#instref">Instruction Reference</a>
43 <li><a href="#terminators">Terminator Instructions</a>
45 <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li>
46 <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
47 <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
48 <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
49 <li><a href="#i_unwind">'<tt>unwind</tt>' Instruction</a></li>
52 <li><a href="#binaryops">Binary Operations</a>
54 <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li>
55 <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li>
56 <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li>
57 <li><a href="#i_div">'<tt>div</tt>' Instruction</a></li>
58 <li><a href="#i_rem">'<tt>rem</tt>' Instruction</a></li>
59 <li><a href="#i_setcc">'<tt>set<i>cc</i></tt>' Instructions</a></li>
62 <li><a href="#bitwiseops">Bitwise Binary Operations</a>
64 <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
65 <li><a href="#i_or">'<tt>or</tt>' Instruction</a></li>
66 <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
67 <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
68 <li><a href="#i_shr">'<tt>shr</tt>' Instruction</a></li>
71 <li><a href="#memoryops">Memory Access Operations</a>
73 <li><a href="#i_malloc">'<tt>malloc</tt>' Instruction</a></li>
74 <li><a href="#i_free">'<tt>free</tt>' Instruction</a></li>
75 <li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li>
76 <li><a href="#i_load">'<tt>load</tt>' Instruction</a></li>
77 <li><a href="#i_store">'<tt>store</tt>' Instruction</a></li>
78 <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
81 <li><a href="#otherops">Other Operations</a>
83 <li><a href="#i_phi">'<tt>phi</tt>' Instruction</a></li>
84 <li><a href="#i_cast">'<tt>cast .. to</tt>' Instruction</a></li>
85 <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
86 <li><a href="#i_call">'<tt>call</tt>' Instruction</a></li>
87 <li><a href="#i_vanext">'<tt>vanext</tt>' Instruction</a></li>
88 <li><a href="#i_vaarg">'<tt>vaarg</tt>' Instruction</a></li>
93 <li><a href="#intrinsics">Intrinsic Functions</a>
95 <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
97 <li><a href="#i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
98 <li><a href="#i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a></li>
99 <li><a href="#i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a></li>
102 <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a>
104 <li><a href="#i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
105 <li><a href="#i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
106 <li><a href="#i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
109 <li><a href="#int_codegen">Code Generator Intrinsics</a>
111 <li><a href="#i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
112 <li><a href="#i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a></li>
115 <li><a href="#int_os">Operating System Intrinsics</a>
117 <li><a href="#i_readport">'<tt>llvm.readport</tt>' Intrinsic</a></li>
118 <li><a href="#i_writeport">'<tt>llvm.writeport</tt>' Intrinsic</a></li>
119 <li><a href="#i_readio">'<tt>llvm.readio</tt>' Intrinsic</a></li>
120 <li><a href="#i_writeio">'<tt>llvm.writeio</tt>' Intrinsic</a></li>
122 <li><a href="#int_libc">Standard C Library Intrinsics</a>
124 <li><a href="#i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a></li>
125 <li><a href="#i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a></li>
126 <li><a href="#i_memset">'<tt>llvm.memset</tt>' Intrinsic</a></li>
127 <li><a href="#i_isnan">'<tt>llvm.isnan</tt>' Intrinsic</a></li>
128 <li><a href="#i_isunordered">'<tt>llvm.isunordered</tt>' Intrinsic</a></li>
131 <li><a href="#int_debugger">Debugger intrinsics</a></li>
136 <div class="doc_author">
137 <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
138 and <a href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></p>
141 <!-- *********************************************************************** -->
142 <div class="doc_section"> <a name="abstract">Abstract </a></div>
143 <!-- *********************************************************************** -->
145 <div class="doc_text">
146 <p>This document is a reference manual for the LLVM assembly language.
147 LLVM is an SSA based representation that provides type safety,
148 low-level operations, flexibility, and the capability of representing
149 'all' high-level languages cleanly. It is the common code
150 representation used throughout all phases of the LLVM compilation
154 <!-- *********************************************************************** -->
155 <div class="doc_section"> <a name="introduction">Introduction</a> </div>
156 <!-- *********************************************************************** -->
158 <div class="doc_text">
160 <p>The LLVM code representation is designed to be used in three
161 different forms: as an in-memory compiler IR, as an on-disk bytecode
162 representation (suitable for fast loading by a Just-In-Time compiler),
163 and as a human readable assembly language representation. This allows
164 LLVM to provide a powerful intermediate representation for efficient
165 compiler transformations and analysis, while providing a natural means
166 to debug and visualize the transformations. The three different forms
167 of LLVM are all equivalent. This document describes the human readable
168 representation and notation.</p>
170 <p>The LLVM representation aims to be a light-weight and low-level
171 while being expressive, typed, and extensible at the same time. It
172 aims to be a "universal IR" of sorts, by being at a low enough level
173 that high-level ideas may be cleanly mapped to it (similar to how
174 microprocessors are "universal IR's", allowing many source languages to
175 be mapped to them). By providing type information, LLVM can be used as
176 the target of optimizations: for example, through pointer analysis, it
177 can be proven that a C automatic variable is never accessed outside of
178 the current function... allowing it to be promoted to a simple SSA
179 value instead of a memory location.</p>
183 <!-- _______________________________________________________________________ -->
184 <div class="doc_subsubsection"> <a name="wellformed">Well-Formedness</a> </div>
186 <div class="doc_text">
188 <p>It is important to note that this document describes 'well formed'
189 LLVM assembly language. There is a difference between what the parser
190 accepts and what is considered 'well formed'. For example, the
191 following instruction is syntactically okay, but not well formed:</p>
194 %x = <a href="#i_add">add</a> int 1, %x
197 <p>...because the definition of <tt>%x</tt> does not dominate all of
198 its uses. The LLVM infrastructure provides a verification pass that may
199 be used to verify that an LLVM module is well formed. This pass is
200 automatically run by the parser after parsing input assembly, and by
201 the optimizer before it outputs bytecode. The violations pointed out
202 by the verifier pass indicate bugs in transformation passes or input to
205 <!-- Describe the typesetting conventions here. --> </div>
207 <!-- *********************************************************************** -->
208 <div class="doc_section"> <a name="identifiers">Identifiers</a> </div>
209 <!-- *********************************************************************** -->
211 <div class="doc_text">
213 <p>LLVM uses three different forms of identifiers, for different
217 <li>Numeric constants are represented as you would expect: 12, -3
218 123.421, etc. Floating point constants have an optional hexadecimal
220 <li>Named values are represented as a string of characters with a '%'
221 prefix. For example, %foo, %DivisionByZero,
222 %a.really.long.identifier. The actual regular expression used is '<tt>%[a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.
223 Identifiers which require other characters in their names can be
224 surrounded with quotes. In this way, anything except a <tt>"</tt>
225 character can be used in a name.</li>
226 <li>Unnamed values are represented as an unsigned numeric value with
227 a '%' prefix. For example, %12, %2, %44.</li>
229 <p>LLVM requires that values start with a '%' sign for two reasons:
230 Compilers don't need to worry about name clashes with reserved words,
231 and the set of reserved words may be expanded in the future without
232 penalty. Additionally, unnamed identifiers allow a compiler to quickly
233 come up with a temporary variable without having to avoid symbol table
235 <p>Reserved words in LLVM are very similar to reserved words in other
236 languages. There are keywords for different opcodes ('<tt><a
237 href="#i_add">add</a></tt>', '<tt><a href="#i_cast">cast</a></tt>', '<tt><a
238 href="#i_ret">ret</a></tt>', etc...), for primitive type names ('<tt><a
239 href="#t_void">void</a></tt>', '<tt><a href="#t_uint">uint</a></tt>',
240 etc...), and others. These reserved words cannot conflict with
241 variable names, because none of them start with a '%' character.</p>
242 <p>Here is an example of LLVM code to multiply the integer variable '<tt>%X</tt>'
245 <pre> %result = <a href="#i_mul">mul</a> uint %X, 8<br></pre>
246 <p>After strength reduction:</p>
247 <pre> %result = <a href="#i_shl">shl</a> uint %X, ubyte 3<br></pre>
248 <p>And the hard way:</p>
249 <pre> <a href="#i_add">add</a> uint %X, %X <i>; yields {uint}:%0</i>
251 href="#i_add">add</a> uint %0, %0 <i>; yields {uint}:%1</i>
253 href="#i_add">add</a> uint %1, %1<br></pre>
254 <p>This last way of multiplying <tt>%X</tt> by 8 illustrates several
255 important lexical features of LLVM:</p>
257 <li>Comments are delimited with a '<tt>;</tt>' and go until the end
259 <li>Unnamed temporaries are created when the result of a computation
260 is not assigned to a named value.</li>
261 <li>Unnamed temporaries are numbered sequentially</li>
263 <p>...and it also show a convention that we follow in this document.
264 When demonstrating instructions, we will follow an instruction with a
265 comment that defines the type and name of value produced. Comments are
266 shown in italic text.</p>
267 <p>The one non-intuitive notation for constants is the optional
268 hexidecimal form of floating point constants. For example, the form '<tt>double
269 0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
270 4.5e+15</tt>' which is also supported by the parser. The only time
271 hexadecimal floating point constants are useful (and the only time that
272 they are generated by the disassembler) is when an FP constant has to
273 be emitted that is not representable as a decimal floating point number
274 exactly. For example, NaN's, infinities, and other special cases are
275 represented in their IEEE hexadecimal format so that assembly and
276 disassembly do not cause any bits to change in the constants.</p>
278 <!-- *********************************************************************** -->
279 <div class="doc_section"> <a name="typesystem">Type System</a> </div>
280 <!-- *********************************************************************** -->
281 <div class="doc_text">
282 <p>The LLVM type system is one of the most important features of the
283 intermediate representation. Being typed enables a number of
284 optimizations to be performed on the IR directly, without having to do
285 extra analyses on the side before the transformation. A strong type
286 system makes it easier to read the generated code and enables novel
287 analyses and transformations that are not feasible to perform on normal
288 three address code representations.</p>
289 <!-- The written form for the type system was heavily influenced by the
290 syntactic problems with types in the C language<sup><a
291 href="#rw_stroustrup">1</a></sup>.<p> --> </div>
292 <!-- ======================================================================= -->
293 <div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div>
294 <div class="doc_text">
295 <p>The primitive types are the fundamental building blocks of the LLVM
296 system. The current set of primitive types are as follows:</p>
298 <table border="0" style="align: center">
302 <table border="1" cellspacing="0" cellpadding="4" style="align: center">
305 <td><tt>void</tt></td>
309 <td><tt>ubyte</tt></td>
310 <td>Unsigned 8 bit value</td>
313 <td><tt>ushort</tt></td>
314 <td>Unsigned 16 bit value</td>
317 <td><tt>uint</tt></td>
318 <td>Unsigned 32 bit value</td>
321 <td><tt>ulong</tt></td>
322 <td>Unsigned 64 bit value</td>
325 <td><tt>float</tt></td>
326 <td>32 bit floating point value</td>
329 <td><tt>label</tt></td>
330 <td>Branch destination</td>
336 <table border="1" cellspacing="0" cellpadding="4">
339 <td><tt>bool</tt></td>
340 <td>True or False value</td>
343 <td><tt>sbyte</tt></td>
344 <td>Signed 8 bit value</td>
347 <td><tt>short</tt></td>
348 <td>Signed 16 bit value</td>
351 <td><tt>int</tt></td>
352 <td>Signed 32 bit value</td>
355 <td><tt>long</tt></td>
356 <td>Signed 64 bit value</td>
359 <td><tt>double</tt></td>
360 <td>64 bit floating point value</td>
370 <!-- _______________________________________________________________________ -->
371 <div class="doc_subsubsection"> <a name="t_classifications">Type
372 Classifications</a> </div>
373 <div class="doc_text">
374 <p>These different primitive types fall into a few useful
377 <table border="1" cellspacing="0" cellpadding="4">
380 <td><a name="t_signed">signed</a></td>
381 <td><tt>sbyte, short, int, long, float, double</tt></td>
384 <td><a name="t_unsigned">unsigned</a></td>
385 <td><tt>ubyte, ushort, uint, ulong</tt></td>
388 <td><a name="t_integer">integer</a></td>
389 <td><tt>ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td>
392 <td><a name="t_integral">integral</a></td>
393 <td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td>
396 <td><a name="t_floating">floating point</a></td>
397 <td><tt>float, double</tt></td>
400 <td><a name="t_firstclass">first class</a></td>
401 <td><tt>bool, ubyte, sbyte, ushort, short,<br>
402 uint, int, ulong, long, float, double, <a href="#t_pointer">pointer</a></tt></td>
407 <p>The <a href="#t_firstclass">first class</a> types are perhaps the
408 most important. Values of these types are the only ones which can be
409 produced by instructions, passed as arguments, or used as operands to
410 instructions. This means that all structures and arrays must be
411 manipulated either by pointer or by component.</p>
413 <!-- ======================================================================= -->
414 <div class="doc_subsection"> <a name="t_derived">Derived Types</a> </div>
415 <div class="doc_text">
416 <p>The real power in LLVM comes from the derived types in the system.
417 This is what allows a programmer to represent arrays, functions,
418 pointers, and other useful types. Note that these derived types may be
419 recursive: For example, it is possible to have a two dimensional array.</p>
421 <!-- _______________________________________________________________________ -->
422 <div class="doc_subsubsection"> <a name="t_array">Array Type</a> </div>
423 <div class="doc_text">
425 <p>The array type is a very simple derived type that arranges elements
426 sequentially in memory. The array type requires a size (number of
427 elements) and an underlying data type.</p>
429 <pre> [<# elements> x <elementtype>]<br></pre>
430 <p>The number of elements is a constant integer value, elementtype may
431 be any type with a size.</p>
433 <p> <tt>[40 x int ]</tt>: Array of 40 integer values.<br>
434 <tt>[41 x int ]</tt>: Array of 41 integer values.<br>
435 <tt>[40 x uint]</tt>: Array of 40 unsigned integer values.</p>
437 <p>Here are some examples of multidimensional arrays:</p>
439 <table border="0" cellpadding="0" cellspacing="0">
442 <td><tt>[3 x [4 x int]]</tt></td>
443 <td>: 3x4 array integer values.</td>
446 <td><tt>[12 x [10 x float]]</tt></td>
447 <td>: 12x10 array of single precision floating point values.</td>
450 <td><tt>[2 x [3 x [4 x uint]]]</tt></td>
451 <td>: 2x3x4 array of unsigned integer values.</td>
457 <!-- _______________________________________________________________________ -->
458 <div class="doc_subsubsection"> <a name="t_function">Function Type</a> </div>
459 <div class="doc_text">
461 <p>The function type can be thought of as a function signature. It
462 consists of a return type and a list of formal parameter types.
463 Function types are usually used to build virtual function tables
464 (which are structures of pointers to functions), for indirect function
465 calls, and when defining a function.</p>
467 The return type of a function type cannot be an aggregate type.
470 <pre> <returntype> (<parameter list>)<br></pre>
471 <p>Where '<tt><parameter list></tt>' is a comma-separated list of
472 type specifiers. Optionally, the parameter list may include a type <tt>...</tt>,
473 which indicates that the function takes a variable number of arguments.
474 Variable argument functions can access their arguments with the <a
475 href="#int_varargs">variable argument handling intrinsic</a> functions.</p>
478 <table border="0" cellpadding="0" cellspacing="0">
481 <td><tt>int (int)</tt></td>
482 <td>: function taking an <tt>int</tt>, returning an <tt>int</tt></td>
485 <td><tt>float (int, int *) *</tt></td>
486 <td>: <a href="#t_pointer">Pointer</a> to a function that takes
487 an <tt>int</tt> and a <a href="#t_pointer">pointer</a> to <tt>int</tt>,
488 returning <tt>float</tt>.</td>
491 <td><tt>int (sbyte *, ...)</tt></td>
492 <td>: A vararg function that takes at least one <a
493 href="#t_pointer">pointer</a> to <tt>sbyte</tt> (signed char in C),
494 which returns an integer. This is the signature for <tt>printf</tt>
501 <!-- _______________________________________________________________________ -->
502 <div class="doc_subsubsection"> <a name="t_struct">Structure Type</a> </div>
503 <div class="doc_text">
505 <p>The structure type is used to represent a collection of data members
506 together in memory. The packing of the field types is defined to match
507 the ABI of the underlying processor. The elements of a structure may
508 be any type that has a size.</p>
509 <p>Structures are accessed using '<tt><a href="#i_load">load</a></tt>
510 and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a
511 field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>'
514 <pre> { <type list> }<br></pre>
517 <table border="0" cellpadding="0" cellspacing="0">
520 <td><tt>{ int, int, int }</tt></td>
521 <td>: a triple of three <tt>int</tt> values</td>
524 <td><tt>{ float, int (int) * }</tt></td>
525 <td>: A pair, where the first element is a <tt>float</tt> and the
526 second element is a <a href="#t_pointer">pointer</a> to a <a
527 href="#t_function">function</a> that takes an <tt>int</tt>, returning
528 an <tt>int</tt>.</td>
534 <!-- _______________________________________________________________________ -->
535 <div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div>
536 <div class="doc_text">
538 <p>As in many languages, the pointer type represents a pointer or
539 reference to another object, which must live in memory.</p>
541 <pre> <type> *<br></pre>
544 <table border="0" cellpadding="0" cellspacing="0">
547 <td><tt>[4x int]*</tt></td>
548 <td>: <a href="#t_pointer">pointer</a> to <a href="#t_array">array</a>
549 of four <tt>int</tt> values</td>
552 <td><tt>int (int *) *</tt></td>
553 <td>: A <a href="#t_pointer">pointer</a> to a <a
554 href="#t_function">function</a> that takes an <tt>int</tt>, returning
555 an <tt>int</tt>.</td>
561 <!-- _______________________________________________________________________ --><!--
562 <div class="doc_subsubsection">
563 <a name="t_packed">Packed Type</a>
566 <div class="doc_text">
568 Mention/decide that packed types work with saturation or not. Maybe have a packed+saturated type in addition to just a packed type.<p>
570 Packed types should be 'nonsaturated' because standard data types are not saturated. Maybe have a saturated packed type?<p>
574 --><!-- *********************************************************************** -->
575 <div class="doc_section"> <a name="highlevel">High Level Structure</a> </div>
576 <!-- *********************************************************************** --><!-- ======================================================================= -->
577 <div class="doc_subsection"> <a name="modulestructure">Module Structure</a> </div>
578 <div class="doc_text">
579 <p>LLVM programs are composed of "Module"s, each of which is a
580 translation unit of the input programs. Each module consists of
581 functions, global variables, and symbol table entries. Modules may be
582 combined together with the LLVM linker, which merges function (and
583 global variable) definitions, resolves forward declarations, and merges
584 symbol table entries. Here is an example of the "hello world" module:</p>
585 <pre><i>; Declare the string constant as a global constant...</i>
586 <a href="#identifiers">%.LC0</a> = <a href="#linkage_internal">internal</a> <a
587 href="#globalvars">constant</a> <a href="#t_array">[13 x sbyte]</a> c"hello world\0A\00" <i>; [13 x sbyte]*</i>
589 <i>; External declaration of the puts function</i>
590 <a href="#functionstructure">declare</a> int %puts(sbyte*) <i>; int(sbyte*)* </i>
592 <i>; Definition of main function</i>
593 int %main() { <i>; int()* </i>
594 <i>; Convert [13x sbyte]* to sbyte *...</i>
596 href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, long 0, long 0 <i>; sbyte*</i>
598 <i>; Call puts function to write out the string to stdout...</i>
600 href="#i_call">call</a> int %puts(sbyte* %cast210) <i>; int</i>
602 href="#i_ret">ret</a> int 0<br>}<br></pre>
603 <p>This example is made up of a <a href="#globalvars">global variable</a>
604 named "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>"
605 function, and a <a href="#functionstructure">function definition</a>
606 for "<tt>main</tt>".</p>
607 <a name="linkage"> In general, a module is made up of a list of global
608 values, where both functions and global variables are global values.
609 Global values are represented by a pointer to a memory location (in
610 this case, a pointer to an array of char, and a pointer to a function),
611 and have one of the following linkage types:</a>
614 <dt><tt><b><a name="linkage_internal">internal</a></b></tt> </dt>
615 <dd>Global values with internal linkage are only directly accessible
616 by objects in the current module. In particular, linking code into a
617 module with an internal global value may cause the internal to be
618 renamed as necessary to avoid collisions. Because the symbol is
619 internal to the module, all references can be updated. This
620 corresponds to the notion of the '<tt>static</tt>' keyword in C, or the
621 idea of "anonymous namespaces" in C++.
624 <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt>: </dt>
625 <dd>"<tt>linkonce</tt>" linkage is similar to <tt>internal</tt>
626 linkage, with the twist that linking together two modules defining the
627 same <tt>linkonce</tt> globals will cause one of the globals to be
628 discarded. This is typically used to implement inline functions.
629 Unreferenced <tt>linkonce</tt> globals are allowed to be discarded.
632 <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt>
633 <dd>"<tt>weak</tt>" linkage is exactly the same as <tt>linkonce</tt>
634 linkage, except that unreferenced <tt>weak</tt> globals may not be
635 discarded. This is used to implement constructs in C such as "<tt>int
636 X;</tt>" at global scope.
639 <dt><tt><b><a name="linkage_appending">appending</a></b></tt>: </dt>
640 <dd>"<tt>appending</tt>" linkage may only be applied to global
641 variables of pointer to array type. When two global variables with
642 appending linkage are linked together, the two global arrays are
643 appended together. This is the LLVM, typesafe, equivalent of having
644 the system linker append together "sections" with identical names when
648 <dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt>
649 <dd>If none of the above identifiers are used, the global is
650 externally visible, meaning that it participates in linkage and can be
651 used to resolve external symbol references.
656 <p><a name="linkage_external">For example, since the "<tt>.LC0</tt>"
657 variable is defined to be internal, if another module defined a "<tt>.LC0</tt>"
658 variable and was linked with this one, one of the two would be renamed,
659 preventing a collision. Since "<tt>main</tt>" and "<tt>puts</tt>" are
660 external (i.e., lacking any linkage declarations), they are accessible
661 outside of the current module. It is illegal for a function <i>declaration</i>
662 to have any linkage type other than "externally visible".</a></p>
665 <!-- ======================================================================= -->
666 <div class="doc_subsection">
667 <a name="globalvars">Global Variables</a>
670 <div class="doc_text">
672 <p>Global variables define regions of memory allocated at compilation
673 time instead of run-time. Global variables may optionally be
674 initialized. A variable may be defined as a global "constant", which
675 indicates that the contents of the variable will never be modified
676 (opening options for optimization).</p>
678 <p>As SSA values, global variables define pointer values that are in
679 scope (i.e. they dominate) for all basic blocks in the program. Global
680 variables always define a pointer to their "content" type because they
681 describe a region of memory, and all memory objects in LLVM are
682 accessed through pointers.</p>
687 <!-- ======================================================================= -->
688 <div class="doc_subsection">
689 <a name="functionstructure">Functions</a>
692 <div class="doc_text">
694 <p>LLVM function definitions are composed of a (possibly empty) argument list,
695 an opening curly brace, a list of basic blocks, and a closing curly brace. LLVM
696 function declarations are defined with the "<tt>declare</tt>" keyword, a
697 function name, and a function signature.</p>
699 <p>A function definition contains a list of basic blocks, forming the CFG for
700 the function. Each basic block may optionally start with a label (giving the
701 basic block a symbol table entry), contains a list of instructions, and ends
702 with a <a href="#terminators">terminator</a> instruction (such as a branch or
703 function return).</p>
705 <p>The first basic block in program is special in two ways: it is immediately
706 executed on entrance to the function, and it is not allowed to have predecessor
707 basic blocks (i.e. there can not be any branches to the entry block of a
708 function). Because the block can have no predecessors, it also cannot have any
709 <a href="#i_phi">PHI nodes</a>.</p>
711 <p>LLVM functions are identified by their name and type signature. Hence, two
712 functions with the same name but different parameter lists or return values are
713 considered different functions, and LLVM will resolves references to each
719 <!-- *********************************************************************** -->
720 <div class="doc_section"> <a name="instref">Instruction Reference</a> </div>
721 <!-- *********************************************************************** -->
722 <div class="doc_text">
723 <p>The LLVM instruction set consists of several different
724 classifications of instructions: <a href="#terminators">terminator
725 instructions</a>, <a href="#binaryops">binary instructions</a>, <a
726 href="#memoryops">memory instructions</a>, and <a href="#otherops">other
727 instructions</a>.</p>
729 <!-- ======================================================================= -->
730 <div class="doc_subsection"> <a name="terminators">Terminator
731 Instructions</a> </div>
732 <div class="doc_text">
733 <p>As mentioned <a href="#functionstructure">previously</a>, every
734 basic block in a program ends with a "Terminator" instruction, which
735 indicates which block should be executed after the current block is
736 finished. These terminator instructions typically yield a '<tt>void</tt>'
737 value: they produce control flow, not values (the one exception being
738 the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
739 <p>There are five different terminator instructions: the '<a
740 href="#i_ret"><tt>ret</tt></a>' instruction, the '<a href="#i_br"><tt>br</tt></a>'
741 instruction, the '<a href="#i_switch"><tt>switch</tt></a>' instruction,
742 the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, and the '<a
743 href="#i_unwind"><tt>unwind</tt></a>' instruction.</p>
745 <!-- _______________________________________________________________________ -->
746 <div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>'
747 Instruction</a> </div>
748 <div class="doc_text">
750 <pre> ret <type> <value> <i>; Return a value from a non-void function</i>
751 ret void <i>; Return from void function</i>
754 <p>The '<tt>ret</tt>' instruction is used to return control flow (and a
755 value) from a function, back to the caller.</p>
756 <p>There are two forms of the '<tt>ret</tt>' instruction: one that
757 returns a value and then causes control flow, and one that just causes
758 control flow to occur.</p>
760 <p>The '<tt>ret</tt>' instruction may return any '<a
761 href="#t_firstclass">first class</a>' type. Notice that a function is
762 not <a href="#wellformed">well formed</a> if there exists a '<tt>ret</tt>'
763 instruction inside of the function that returns a value that does not
764 match the return type of the function.</p>
766 <p>When the '<tt>ret</tt>' instruction is executed, control flow
767 returns back to the calling function's context. If the caller is a "<a
768 href="#i_call"><tt>call</tt></a> instruction, execution continues at
769 the instruction after the call. If the caller was an "<a
770 href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues
771 at the beginning "normal" of the destination block. If the instruction
772 returns a value, that value shall set the call or invoke instruction's
775 <pre> ret int 5 <i>; Return an integer value of 5</i>
776 ret void <i>; Return from a void function</i>
779 <!-- _______________________________________________________________________ -->
780 <div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div>
781 <div class="doc_text">
783 <pre> br bool <cond>, label <iftrue>, label <iffalse><br> br label <dest> <i>; Unconditional branch</i>
786 <p>The '<tt>br</tt>' instruction is used to cause control flow to
787 transfer to a different basic block in the current function. There are
788 two forms of this instruction, corresponding to a conditional branch
789 and an unconditional branch.</p>
791 <p>The conditional branch form of the '<tt>br</tt>' instruction takes a
792 single '<tt>bool</tt>' value and two '<tt>label</tt>' values. The
793 unconditional form of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>'
794 value as a target.</p>
796 <p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>bool</tt>'
797 argument is evaluated. If the value is <tt>true</tt>, control flows
798 to the '<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>,
799 control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p>
801 <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
802 href="#i_ret">ret</a> int 1<br>IfUnequal:<br> <a href="#i_ret">ret</a> int 0<br></pre>
804 <!-- _______________________________________________________________________ -->
805 <div class="doc_subsubsection">
806 <a name="i_switch">'<tt>switch</tt>' Instruction</a>
809 <div class="doc_text">
813 switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
818 <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
819 several different places. It is a generalization of the '<tt>br</tt>'
820 instruction, allowing a branch to occur to one of many possible
826 <p>The '<tt>switch</tt>' instruction uses three parameters: an integer
827 comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
828 an array of pairs of comparison value constants and '<tt>label</tt>'s. The
829 table is not allowed to contain duplicate constant entries.</p>
833 <p>The <tt>switch</tt> instruction specifies a table of values and
834 destinations. When the '<tt>switch</tt>' instruction is executed, this
835 table is searched for the given value. If the value is found, the
836 corresponding destination is branched to, otherwise the default value
837 it transfered to.</p>
839 <h5>Implementation:</h5>
841 <p>Depending on properties of the target machine and the particular
842 <tt>switch</tt> instruction, this instruction may be code generated in different
843 ways, for example as a series of chained conditional branches, or with a lookup
849 <i>; Emulate a conditional br instruction</i>
850 %Val = <a href="#i_cast">cast</a> bool %value to int
851 switch int %Val, label %truedest [int 0, label %falsedest ]
853 <i>; Emulate an unconditional br instruction</i>
854 switch uint 0, label %dest [ ]
856 <i>; Implement a jump table:</i>
857 switch uint %val, label %otherwise [ uint 0, label %onzero
859 uint 2, label %ontwo ]
862 <!-- _______________________________________________________________________ -->
863 <div class="doc_subsubsection"> <a name="i_invoke">'<tt>invoke</tt>'
864 Instruction</a> </div>
865 <div class="doc_text">
867 <pre> <result> = invoke <ptr to function ty> %<function ptr val>(<function args>)<br> to label <normal label> except label <exception label><br></pre>
869 <p>The '<tt>invoke</tt>' instruction causes control to transfer to a
870 specified function, with the possibility of control flow transfer to
871 either the '<tt>normal</tt>' <tt>label</tt> label or the '<tt>exception</tt>'<tt>label</tt>.
872 If the callee function returns with the "<tt><a href="#i_ret">ret</a></tt>"
873 instruction, control flow will return to the "normal" label. If the
874 callee (or any indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>"
875 instruction, control is interrupted, and continued at the dynamically
876 nearest "except" label.</p>
878 <p>This instruction requires several arguments:</p>
880 <li>'<tt>ptr to function ty</tt>': shall be the signature of the
881 pointer to function value being invoked. In most cases, this is a
882 direct function invocation, but indirect <tt>invoke</tt>s are just as
883 possible, branching off an arbitrary pointer to function value. </li>
884 <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer
885 to a function to be invoked. </li>
886 <li>'<tt>function args</tt>': argument list whose types match the
887 function signature argument types. If the function signature indicates
888 the function accepts a variable number of arguments, the extra
889 arguments can be specified. </li>
890 <li>'<tt>normal label</tt>': the label reached when the called
891 function executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
892 <li>'<tt>exception label</tt>': the label reached when a callee
893 returns with the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li>
896 <p>This instruction is designed to operate as a standard '<tt><a
897 href="#i_call">call</a></tt>' instruction in most regards. The
898 primary difference is that it establishes an association with a label,
899 which is used by the runtime library to unwind the stack.</p>
900 <p>This instruction is used in languages with destructors to ensure
901 that proper cleanup is performed in the case of either a <tt>longjmp</tt>
902 or a thrown exception. Additionally, this is important for
903 implementation of '<tt>catch</tt>' clauses in high-level languages that
906 <pre> %retval = invoke int %Test(int 15)<br> to label %Continue<br> except label %TestCleanup <i>; {int}:retval set</i>
909 <!-- _______________________________________________________________________ -->
910 <div class="doc_subsubsection"> <a name="i_unwind">'<tt>unwind</tt>'
911 Instruction</a> </div>
912 <div class="doc_text">
914 <pre> unwind<br></pre>
916 <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing
917 control flow at the first callee in the dynamic call stack which used
918 an <a href="#i_invoke"><tt>invoke</tt></a> instruction to perform the
919 call. This is primarily used to implement exception handling.</p>
921 <p>The '<tt>unwind</tt>' intrinsic causes execution of the current
922 function to immediately halt. The dynamic call stack is then searched
923 for the first <a href="#i_invoke"><tt>invoke</tt></a> instruction on
924 the call stack. Once found, execution continues at the "exceptional"
925 destination block specified by the <tt>invoke</tt> instruction. If
926 there is no <tt>invoke</tt> instruction in the dynamic call chain,
927 undefined behavior results.</p>
929 <!-- ======================================================================= -->
930 <div class="doc_subsection"> <a name="binaryops">Binary Operations</a> </div>
931 <div class="doc_text">
932 <p>Binary operators are used to do most of the computation in a
933 program. They require two operands, execute an operation on them, and
934 produce a single value. The result value of a binary operator is not
935 necessarily the same type as its operands.</p>
936 <p>There are several different binary operators:</p>
938 <!-- _______________________________________________________________________ -->
939 <div class="doc_subsubsection"> <a name="i_add">'<tt>add</tt>'
940 Instruction</a> </div>
941 <div class="doc_text">
943 <pre> <result> = add <ty> <var1>, <var2> <i>; yields {ty}:result</i>
946 <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
948 <p>The two arguments to the '<tt>add</tt>' instruction must be either <a
949 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
950 values. Both arguments must have identical types.</p>
952 <p>The value produced is the integer or floating point sum of the two
955 <pre> <result> = add int 4, %var <i>; yields {int}:result = 4 + %var</i>
958 <!-- _______________________________________________________________________ -->
959 <div class="doc_subsubsection"> <a name="i_sub">'<tt>sub</tt>'
960 Instruction</a> </div>
961 <div class="doc_text">
963 <pre> <result> = sub <ty> <var1>, <var2> <i>; yields {ty}:result</i>
966 <p>The '<tt>sub</tt>' instruction returns the difference of its two
968 <p>Note that the '<tt>sub</tt>' instruction is used to represent the '<tt>neg</tt>'
969 instruction present in most other intermediate representations.</p>
971 <p>The two arguments to the '<tt>sub</tt>' instruction must be either <a
972 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
973 values. Both arguments must have identical types.</p>
975 <p>The value produced is the integer or floating point difference of
976 the two operands.</p>
978 <pre> <result> = sub int 4, %var <i>; yields {int}:result = 4 - %var</i>
979 <result> = sub int 0, %val <i>; yields {int}:result = -%var</i>
982 <!-- _______________________________________________________________________ -->
983 <div class="doc_subsubsection"> <a name="i_mul">'<tt>mul</tt>'
984 Instruction</a> </div>
985 <div class="doc_text">
987 <pre> <result> = mul <ty> <var1>, <var2> <i>; yields {ty}:result</i>
990 <p>The '<tt>mul</tt>' instruction returns the product of its two
993 <p>The two arguments to the '<tt>mul</tt>' instruction must be either <a
994 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
995 values. Both arguments must have identical types.</p>
997 <p>The value produced is the integer or floating point product of the
999 <p>There is no signed vs unsigned multiplication. The appropriate
1000 action is taken based on the type of the operand.</p>
1002 <pre> <result> = mul int 4, %var <i>; yields {int}:result = 4 * %var</i>
1005 <!-- _______________________________________________________________________ -->
1006 <div class="doc_subsubsection"> <a name="i_div">'<tt>div</tt>'
1007 Instruction</a> </div>
1008 <div class="doc_text">
1010 <pre> <result> = div <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1013 <p>The '<tt>div</tt>' instruction returns the quotient of its two
1016 <p>The two arguments to the '<tt>div</tt>' instruction must be either <a
1017 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1018 values. Both arguments must have identical types.</p>
1020 <p>The value produced is the integer or floating point quotient of the
1023 <pre> <result> = div int 4, %var <i>; yields {int}:result = 4 / %var</i>
1026 <!-- _______________________________________________________________________ -->
1027 <div class="doc_subsubsection"> <a name="i_rem">'<tt>rem</tt>'
1028 Instruction</a> </div>
1029 <div class="doc_text">
1031 <pre> <result> = rem <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1034 <p>The '<tt>rem</tt>' instruction returns the remainder from the
1035 division of its two operands.</p>
1037 <p>The two arguments to the '<tt>rem</tt>' instruction must be either <a
1038 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1039 values. Both arguments must have identical types.</p>
1041 <p>This returns the <i>remainder</i> of a division (where the result
1042 has the same sign as the divisor), not the <i>modulus</i> (where the
1043 result has the same sign as the dividend) of a value. For more
1044 information about the difference, see: <a
1045 href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
1048 <pre> <result> = rem int 4, %var <i>; yields {int}:result = 4 % %var</i>
1051 <!-- _______________________________________________________________________ -->
1052 <div class="doc_subsubsection"> <a name="i_setcc">'<tt>set<i>cc</i></tt>'
1053 Instructions</a> </div>
1054 <div class="doc_text">
1056 <pre> <result> = seteq <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1057 <result> = setne <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1058 <result> = setlt <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1059 <result> = setgt <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1060 <result> = setle <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1061 <result> = setge <ty> <var1>, <var2> <i>; yields {bool}:result</i>
1064 <p>The '<tt>set<i>cc</i></tt>' family of instructions returns a boolean
1065 value based on a comparison of their two operands.</p>
1067 <p>The two arguments to the '<tt>set<i>cc</i></tt>' instructions must
1068 be of <a href="#t_firstclass">first class</a> type (it is not possible
1069 to compare '<tt>label</tt>'s, '<tt>array</tt>'s, '<tt>structure</tt>'
1070 or '<tt>void</tt>' values, etc...). Both arguments must have identical
1073 <p>The '<tt>seteq</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1074 value if both operands are equal.<br>
1075 The '<tt>setne</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1076 value if both operands are unequal.<br>
1077 The '<tt>setlt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1078 value if the first operand is less than the second operand.<br>
1079 The '<tt>setgt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1080 value if the first operand is greater than the second operand.<br>
1081 The '<tt>setle</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1082 value if the first operand is less than or equal to the second operand.<br>
1083 The '<tt>setge</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>'
1084 value if the first operand is greater than or equal to the second
1087 <pre> <result> = seteq int 4, 5 <i>; yields {bool}:result = false</i>
1088 <result> = setne float 4, 5 <i>; yields {bool}:result = true</i>
1089 <result> = setlt uint 4, 5 <i>; yields {bool}:result = true</i>
1090 <result> = setgt sbyte 4, 5 <i>; yields {bool}:result = false</i>
1091 <result> = setle sbyte 4, 5 <i>; yields {bool}:result = true</i>
1092 <result> = setge sbyte 4, 5 <i>; yields {bool}:result = false</i>
1095 <!-- ======================================================================= -->
1096 <div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary
1097 Operations</a> </div>
1098 <div class="doc_text">
1099 <p>Bitwise binary operators are used to do various forms of
1100 bit-twiddling in a program. They are generally very efficient
1101 instructions, and can commonly be strength reduced from other
1102 instructions. They require two operands, execute an operation on them,
1103 and produce a single value. The resulting value of the bitwise binary
1104 operators is always the same type as its first operand.</p>
1106 <!-- _______________________________________________________________________ -->
1107 <div class="doc_subsubsection"> <a name="i_and">'<tt>and</tt>'
1108 Instruction</a> </div>
1109 <div class="doc_text">
1111 <pre> <result> = and <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1114 <p>The '<tt>and</tt>' instruction returns the bitwise logical and of
1115 its two operands.</p>
1117 <p>The two arguments to the '<tt>and</tt>' instruction must be <a
1118 href="#t_integral">integral</a> values. Both arguments must have
1119 identical types.</p>
1121 <p>The truth table used for the '<tt>and</tt>' instruction is:</p>
1123 <div style="align: center">
1124 <table border="1" cellspacing="0" cellpadding="4">
1155 <pre> <result> = and int 4, %var <i>; yields {int}:result = 4 & %var</i>
1156 <result> = and int 15, 40 <i>; yields {int}:result = 8</i>
1157 <result> = and int 4, 8 <i>; yields {int}:result = 0</i>
1160 <!-- _______________________________________________________________________ -->
1161 <div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div>
1162 <div class="doc_text">
1164 <pre> <result> = or <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1167 <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive
1168 or of its two operands.</p>
1170 <p>The two arguments to the '<tt>or</tt>' instruction must be <a
1171 href="#t_integral">integral</a> values. Both arguments must have
1172 identical types.</p>
1174 <p>The truth table used for the '<tt>or</tt>' instruction is:</p>
1176 <div style="align: center">
1177 <table border="1" cellspacing="0" cellpadding="4">
1208 <pre> <result> = or int 4, %var <i>; yields {int}:result = 4 | %var</i>
1209 <result> = or int 15, 40 <i>; yields {int}:result = 47</i>
1210 <result> = or int 4, 8 <i>; yields {int}:result = 12</i>
1213 <!-- _______________________________________________________________________ -->
1214 <div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>'
1215 Instruction</a> </div>
1216 <div class="doc_text">
1218 <pre> <result> = xor <ty> <var1>, <var2> <i>; yields {ty}:result</i>
1221 <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive
1222 or of its two operands. The <tt>xor</tt> is used to implement the
1223 "one's complement" operation, which is the "~" operator in C.</p>
1225 <p>The two arguments to the '<tt>xor</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>xor</tt>' instruction is:</p>
1231 <div style="align: center">
1232 <table border="1" cellspacing="0" cellpadding="4">
1264 <pre> <result> = xor int 4, %var <i>; yields {int}:result = 4 ^ %var</i>
1265 <result> = xor int 15, 40 <i>; yields {int}:result = 39</i>
1266 <result> = xor int 4, 8 <i>; yields {int}:result = 12</i>
1267 <result> = xor int %V, -1 <i>; yields {int}:result = ~%V</i>
1270 <!-- _______________________________________________________________________ -->
1271 <div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>'
1272 Instruction</a> </div>
1273 <div class="doc_text">
1275 <pre> <result> = shl <ty> <var1>, ubyte <var2> <i>; yields {ty}:result</i>
1278 <p>The '<tt>shl</tt>' instruction returns the first operand shifted to
1279 the left a specified number of bits.</p>
1281 <p>The first argument to the '<tt>shl</tt>' instruction must be an <a
1282 href="#t_integer">integer</a> type. The second argument must be an '<tt>ubyte</tt>'
1285 <p>The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.</p>
1287 <pre> <result> = shl int 4, ubyte %var <i>; yields {int}:result = 4 << %var</i>
1288 <result> = shl int 4, ubyte 2 <i>; yields {int}:result = 16</i>
1289 <result> = shl int 1, ubyte 10 <i>; yields {int}:result = 1024</i>
1292 <!-- _______________________________________________________________________ -->
1293 <div class="doc_subsubsection"> <a name="i_shr">'<tt>shr</tt>'
1294 Instruction</a> </div>
1295 <div class="doc_text">
1297 <pre> <result> = shr <ty> <var1>, ubyte <var2> <i>; yields {ty}:result</i>
1300 <p>The '<tt>shr</tt>' instruction returns the first operand shifted to
1301 the right a specified number of bits.</p>
1303 <p>The first argument to the '<tt>shr</tt>' instruction must be an <a
1304 href="#t_integer">integer</a> type. The second argument must be an '<tt>ubyte</tt>'
1307 <p>If the first argument is a <a href="#t_signed">signed</a> type, the
1308 most significant bit is duplicated in the newly free'd bit positions.
1309 If the first argument is unsigned, zero bits shall fill the empty
1312 <pre> <result> = shr int 4, ubyte %var <i>; yields {int}:result = 4 >> %var</i>
1313 <result> = shr uint 4, ubyte 1 <i>; yields {uint}:result = 2</i>
1314 <result> = shr int 4, ubyte 2 <i>; yields {int}:result = 1</i>
1315 <result> = shr sbyte 4, ubyte 3 <i>; yields {sbyte}:result = 0</i>
1316 <result> = shr sbyte -2, ubyte 1 <i>; yields {sbyte}:result = -1</i>
1319 <!-- ======================================================================= -->
1320 <div class="doc_subsection"> <a name="memoryops">Memory Access
1321 Operations</a></div>
1322 <div class="doc_text">
1323 <p>A key design point of an SSA-based representation is how it
1324 represents memory. In LLVM, no memory locations are in SSA form, which
1325 makes things very simple. This section describes how to read, write,
1326 allocate and free memory in LLVM.</p>
1328 <!-- _______________________________________________________________________ -->
1329 <div class="doc_subsubsection"> <a name="i_malloc">'<tt>malloc</tt>'
1330 Instruction</a> </div>
1331 <div class="doc_text">
1333 <pre> <result> = malloc <type>, uint <NumElements> <i>; yields {type*}:result</i>
1334 <result> = malloc <type> <i>; yields {type*}:result</i>
1337 <p>The '<tt>malloc</tt>' instruction allocates memory from the system
1338 heap and returns a pointer to it.</p>
1340 <p>The '<tt>malloc</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
1341 bytes of memory from the operating system and returns a pointer of the
1342 appropriate type to the program. The second form of the instruction is
1343 a shorter version of the first instruction that defaults to allocating
1345 <p>'<tt>type</tt>' must be a sized type.</p>
1347 <p>Memory is allocated using the system "<tt>malloc</tt>" function, and
1348 a pointer is returned.</p>
1350 <pre> %array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
1353 href="#i_add">add</a> uint 2, 2 <i>; yields {uint}:size = uint 4</i>
1354 %array1 = malloc ubyte, uint 4 <i>; yields {ubyte*}:array1</i>
1355 %array2 = malloc [12 x ubyte], uint %size <i>; yields {[12 x ubyte]*}:array2</i>
1358 <!-- _______________________________________________________________________ -->
1359 <div class="doc_subsubsection"> <a name="i_free">'<tt>free</tt>'
1360 Instruction</a> </div>
1361 <div class="doc_text">
1363 <pre> free <type> <value> <i>; yields {void}</i>
1366 <p>The '<tt>free</tt>' instruction returns memory back to the unused
1367 memory heap, to be reallocated in the future.</p>
1370 <p>'<tt>value</tt>' shall be a pointer value that points to a value
1371 that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>'
1374 <p>Access to the memory pointed to by the pointer is not longer defined
1375 after this instruction executes.</p>
1377 <pre> %array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
1378 free [4 x ubyte]* %array
1381 <!-- _______________________________________________________________________ -->
1382 <div class="doc_subsubsection"> <a name="i_alloca">'<tt>alloca</tt>'
1383 Instruction</a> </div>
1384 <div class="doc_text">
1386 <pre> <result> = alloca <type>, uint <NumElements> <i>; yields {type*}:result</i>
1387 <result> = alloca <type> <i>; yields {type*}:result</i>
1390 <p>The '<tt>alloca</tt>' instruction allocates memory on the current
1391 stack frame of the procedure that is live until the current function
1392 returns to its caller.</p>
1394 <p>The the '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
1395 bytes of memory on the runtime stack, returning a pointer of the
1396 appropriate type to the program. The second form of the instruction is
1397 a shorter version of the first that defaults to allocating one element.</p>
1398 <p>'<tt>type</tt>' may be any sized type.</p>
1400 <p>Memory is allocated, a pointer is returned. '<tt>alloca</tt>'d
1401 memory is automatically released when the function returns. The '<tt>alloca</tt>'
1402 instruction is commonly used to represent automatic variables that must
1403 have an address available. When the function returns (either with the <tt><a
1404 href="#i_ret">ret</a></tt> or <tt><a href="#i_invoke">invoke</a></tt>
1405 instructions), the memory is reclaimed.</p>
1407 <pre> %ptr = alloca int <i>; yields {int*}:ptr</i>
1408 %ptr = alloca int, uint 4 <i>; yields {int*}:ptr</i>
1411 <!-- _______________________________________________________________________ -->
1412 <div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
1413 Instruction</a> </div>
1414 <div class="doc_text">
1416 <pre> <result> = load <ty>* <pointer><br> <result> = volatile load <ty>* <pointer><br></pre>
1418 <p>The '<tt>load</tt>' instruction is used to read from memory.</p>
1420 <p>The argument to the '<tt>load</tt>' instruction specifies the memory
1421 address to load from. The pointer must point to a <a
1422 href="#t_firstclass">first class</a> type. If the <tt>load</tt> is
1423 marked as <tt>volatile</tt> then the optimizer is not allowed to modify
1424 the number or order of execution of this <tt>load</tt> with other
1425 volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
1428 <p>The location of memory pointed to is loaded.</p>
1430 <pre> %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
1432 href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
1433 %val = load int* %ptr <i>; yields {int}:val = int 3</i>
1436 <!-- _______________________________________________________________________ -->
1437 <div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
1438 Instruction</a> </div>
1440 <pre> store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
1441 volatile store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
1444 <p>The '<tt>store</tt>' instruction is used to write to memory.</p>
1446 <p>There are two arguments to the '<tt>store</tt>' instruction: a value
1447 to store and an address to store it into. The type of the '<tt><pointer></tt>'
1448 operand must be a pointer to the type of the '<tt><value></tt>'
1449 operand. If the <tt>store</tt> is marked as <tt>volatile</tt> then the
1450 optimizer is not allowed to modify the number or order of execution of
1451 this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a
1452 href="#i_store">store</a></tt> instructions.</p>
1454 <p>The contents of memory are updated to contain '<tt><value></tt>'
1455 at the location specified by the '<tt><pointer></tt>' operand.</p>
1457 <pre> %ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
1459 href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
1460 %val = load int* %ptr <i>; yields {int}:val = int 3</i>
1462 <!-- _______________________________________________________________________ -->
1463 <div class="doc_subsubsection">
1464 <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
1467 <div class="doc_text">
1470 <result> = getelementptr <ty>* <ptrval>{, <ty> <idx>}*
1476 The '<tt>getelementptr</tt>' instruction is used to get the address of a
1477 subelement of an aggregate data structure.</p>
1481 <p>This instruction takes a list of integer constants that indicate what
1482 elements of the aggregate object to index to. The actual types of the arguments
1483 provided depend on the type of the first pointer argument. The
1484 '<tt>getelementptr</tt>' instruction is used to index down through the type
1485 levels of a structure. When indexing into a structure, only <tt>uint</tt>
1486 integer constants are allowed. When indexing into an array or pointer
1487 <tt>int</tt> and <tt>long</tt> indexes are allowed of any sign.</p>
1489 <p>For example, let's consider a C code fragment and how it gets
1490 compiled to LLVM:</p>
1504 int *foo(struct ST *s) {
1505 return &s[1].Z.B[5][13];
1509 <p>The LLVM code generated by the GCC frontend is:</p>
1512 %RT = type { sbyte, [10 x [20 x int]], sbyte }
1513 %ST = type { int, double, %RT }
1515 int* "foo"(%ST* %s) {
1516 %reg = getelementptr %ST* %s, int 1, uint 2, uint 1, int 5, int 13<br>
1523 <p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
1524 on the pointer type that is being index into. <a href="#t_pointer">Pointer</a>
1525 and <a href="#t_array">array</a> types require <tt>uint</tt>, <tt>int</tt>,
1526 <tt>ulong</tt>, or <tt>long</tt> values, and <a href="#t_struct">structure</a>
1527 types require <tt>uint</tt> <b>constants</b>.</p>
1529 <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
1530 type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ int, double, %RT
1531 }</tt>' type, a structure. The second index indexes into the third element of
1532 the structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]],
1533 sbyte }</tt>' type, another structure. The third index indexes into the second
1534 element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
1535 array. The two dimensions of the array are subscripted into, yielding an
1536 '<tt>int</tt>' type. The '<tt>getelementptr</tt>' instruction return a pointer
1537 to this element, thus computing a value of '<tt>int*</tt>' type.</p>
1539 <p>Note that it is perfectly legal to index partially through a
1540 structure, returning a pointer to an inner element. Because of this,
1541 the LLVM code for the given testcase is equivalent to:</p>
1544 int* "foo"(%ST* %s) {
1545 %t1 = getelementptr %ST* %s, int 1 <i>; yields %ST*:%t1</i>
1546 %t2 = getelementptr %ST* %t1, int 0, uint 2 <i>; yields %RT*:%t2</i>
1547 %t3 = getelementptr %RT* %t2, int 0, uint 1 <i>; yields [10 x [20 x int]]*:%t3</i>
1548 %t4 = getelementptr [10 x [20 x int]]* %t3, int 0, int 5 <i>; yields [20 x int]*:%t4</i>
1549 %t5 = getelementptr [20 x int]* %t4, int 0, int 13 <i>; yields int*:%t5</i>
1555 <i>; yields [12 x ubyte]*:aptr</i>
1556 %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, uint 1
1560 <!-- ======================================================================= -->
1561 <div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
1562 <div class="doc_text">
1563 <p>The instructions in this category are the "miscellaneous"
1564 instructions, which defy better classification.</p>
1566 <!-- _______________________________________________________________________ -->
1567 <div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>'
1568 Instruction</a> </div>
1569 <div class="doc_text">
1571 <pre> <result> = phi <ty> [ <val0>, <label0>], ...<br></pre>
1573 <p>The '<tt>phi</tt>' instruction is used to implement the φ node in
1574 the SSA graph representing the function.</p>
1576 <p>The type of the incoming values are specified with the first type
1577 field. After this, the '<tt>phi</tt>' instruction takes a list of pairs
1578 as arguments, with one pair for each predecessor basic block of the
1579 current block. Only values of <a href="#t_firstclass">first class</a>
1580 type may be used as the value arguments to the PHI node. Only labels
1581 may be used as the label arguments.</p>
1582 <p>There must be no non-phi instructions between the start of a basic
1583 block and the PHI instructions: i.e. PHI instructions must be first in
1586 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the
1587 value specified by the parameter, depending on which basic block we
1588 came from in the last <a href="#terminators">terminator</a> instruction.</p>
1590 <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>
1593 <!-- _______________________________________________________________________ -->
1594 <div class="doc_subsubsection">
1595 <a name="i_cast">'<tt>cast .. to</tt>' Instruction</a>
1598 <div class="doc_text">
1603 <result> = cast <ty> <value> to <ty2> <i>; yields ty2</i>
1609 The '<tt>cast</tt>' instruction is used as the primitive means to convert
1610 integers to floating point, change data type sizes, and break type safety (by
1618 The '<tt>cast</tt>' instruction takes a value to cast, which must be a first
1619 class value, and a type to cast it to, which must also be a <a
1620 href="#t_firstclass">first class</a> type.
1626 This instruction follows the C rules for explicit casts when determining how the
1627 data being cast must change to fit in its new container.
1631 When casting to bool, any value that would be considered true in the context of
1632 a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>' values,
1633 all else are '<tt>false</tt>'.
1637 When extending an integral value from a type of one signness to another (for
1638 example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
1639 <b>source</b> value is signed, and zero-extended if the source value is
1640 unsigned. <tt>bool</tt> values are always zero extended into either zero or
1647 %X = cast int 257 to ubyte <i>; yields ubyte:1</i>
1648 %Y = cast int 123 to bool <i>; yields bool:true</i>
1652 <!-- _______________________________________________________________________ -->
1653 <div class="doc_subsubsection">
1654 <a name="i_select">'<tt>select</tt>' Instruction</a>
1657 <div class="doc_text">
1662 <result> = select bool <cond>, <ty> <val1>, <ty> <val2> <i>; yields ty</i>
1668 The '<tt>select</tt>' instruction is used to choose one value based on a
1669 condition, without branching.
1676 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.
1682 If the boolean condition evaluates to true, the instruction returns the first
1683 value argument, otherwise it returns the second value argument.
1689 %X = select bool true, ubyte 17, ubyte 42 <i>; yields ubyte:17</i>
1697 <!-- _______________________________________________________________________ -->
1698 <div class="doc_subsubsection"> <a name="i_call">'<tt>call</tt>'
1699 Instruction</a> </div>
1700 <div class="doc_text">
1702 <pre> <result> = call <ty>* <fnptrval>(<param list>)<br></pre>
1704 <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
1706 <p>This instruction requires several arguments:</p>
1709 <p>'<tt>ty</tt>': shall be the signature of the pointer to function
1710 value being invoked. The argument types must match the types implied
1711 by this signature.</p>
1714 <p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a
1715 function to be invoked. In most cases, this is a direct function
1716 invocation, but indirect <tt>call</tt>s are just as possible,
1717 calling an arbitrary pointer to function values.</p>
1720 <p>'<tt>function args</tt>': argument list whose types match the
1721 function signature argument types. If the function signature
1722 indicates the function accepts a variable number of arguments, the
1723 extra arguments can be specified.</p>
1727 <p>The '<tt>call</tt>' instruction is used to cause control flow to
1728 transfer to a specified function, with its incoming arguments bound to
1729 the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>'
1730 instruction in the called function, control flow continues with the
1731 instruction after the function call, and the return value of the
1732 function is bound to the result argument. This is a simpler case of
1733 the <a href="#i_invoke">invoke</a> instruction.</p>
1735 <pre> %retval = call int %test(int %argc)<br> call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);<br></pre>
1737 <!-- _______________________________________________________________________ -->
1738 <div class="doc_subsubsection"> <a name="i_vanext">'<tt>vanext</tt>'
1739 Instruction</a> </div>
1740 <div class="doc_text">
1742 <pre> <resultarglist> = vanext <va_list> <arglist>, <argty><br></pre>
1744 <p>The '<tt>vanext</tt>' instruction is used to access arguments passed
1745 through the "variable argument" area of a function call. It is used to
1746 implement the <tt>va_arg</tt> macro in C.</p>
1748 <p>This instruction takes a <tt>valist</tt> value and the type of the
1749 argument. It returns another <tt>valist</tt>.</p>
1751 <p>The '<tt>vanext</tt>' instruction advances the specified <tt>valist</tt>
1752 past an argument of the specified type. In conjunction with the <a
1753 href="#i_vaarg"><tt>vaarg</tt></a> instruction, it is used to implement
1754 the <tt>va_arg</tt> macro available in C. For more information, see
1755 the variable argument handling <a href="#int_varargs">Intrinsic
1757 <p>It is legal for this instruction to be called in a function which
1758 does not take a variable number of arguments, for example, the <tt>vfprintf</tt>
1760 <p><tt>vanext</tt> is an LLVM instruction instead of an <a
1761 href="#intrinsics">intrinsic function</a> because it takes an type as
1764 <p>See the <a href="#int_varargs">variable argument processing</a>
1767 <!-- _______________________________________________________________________ -->
1768 <div class="doc_subsubsection"> <a name="i_vaarg">'<tt>vaarg</tt>'
1769 Instruction</a> </div>
1770 <div class="doc_text">
1772 <pre> <resultval> = vaarg <va_list> <arglist>, <argty><br></pre>
1774 <p>The '<tt>vaarg</tt>' instruction is used to access arguments passed
1775 through the "variable argument" area of a function call. It is used to
1776 implement the <tt>va_arg</tt> macro in C.</p>
1778 <p>This instruction takes a <tt>valist</tt> value and the type of the
1779 argument. It returns a value of the specified argument type.</p>
1781 <p>The '<tt>vaarg</tt>' instruction loads an argument of the specified
1782 type from the specified <tt>va_list</tt>. In conjunction with the <a
1783 href="#i_vanext"><tt>vanext</tt></a> instruction, it is used to
1784 implement the <tt>va_arg</tt> macro available in C. For more
1785 information, see the variable argument handling <a href="#int_varargs">Intrinsic
1787 <p>It is legal for this instruction to be called in a function which
1788 does not take a variable number of arguments, for example, the <tt>vfprintf</tt>
1790 <p><tt>vaarg</tt> is an LLVM instruction instead of an <a
1791 href="#intrinsics">intrinsic function</a> because it takes an type as
1794 <p>See the <a href="#int_varargs">variable argument processing</a>
1798 <!-- *********************************************************************** -->
1799 <div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
1800 <!-- *********************************************************************** -->
1802 <div class="doc_text">
1804 <p>LLVM supports the notion of an "intrinsic function". These functions have
1805 well known names and semantics, and are required to follow certain
1806 restrictions. Overall, these instructions represent an extension mechanism for
1807 the LLVM language that does not require changing all of the transformations in
1808 LLVM to add to the language (or the bytecode reader/writer, the parser,
1811 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix, this
1812 prefix is reserved in LLVM for intrinsic names, thus functions may not be named
1813 this. Intrinsic functions must always be external functions: you cannot define
1814 the body of intrinsic functions. Intrinsic functions may only be used in call
1815 or invoke instructions: it is illegal to take the address of an intrinsic
1816 function. Additionally, because intrinsic functions are part of the LLVM
1817 language, it is required that they all be documented here if any are added.</p>
1821 Adding an intrinsic to LLVM is straight-forward if it is possible to express the
1822 concept in LLVM directly (ie, code generator support is not _required_). To do
1823 this, extend the default implementation of the IntrinsicLowering class to handle
1824 the intrinsic. Code generators use this class to lower intrinsics they do not
1825 understand to raw LLVM instructions that they do.
1830 <!-- ======================================================================= -->
1831 <div class="doc_subsection">
1832 <a name="int_varargs">Variable Argument Handling Intrinsics</a>
1835 <div class="doc_text">
1837 <p>Variable argument support is defined in LLVM with the <a
1838 href="#i_vanext"><tt>vanext</tt></a> instruction and these three
1839 intrinsic functions. These functions are related to the similarly
1840 named macros defined in the <tt><stdarg.h></tt> header file.</p>
1842 <p>All of these functions operate on arguments that use a
1843 target-specific value type "<tt>va_list</tt>". The LLVM assembly
1844 language reference manual does not define what this type is, so all
1845 transformations should be prepared to handle intrinsics with any type
1848 <p>This example shows how the <a href="#i_vanext"><tt>vanext</tt></a>
1849 instruction and the variable argument handling intrinsic functions are
1853 int %test(int %X, ...) {
1854 ; Initialize variable argument processing
1855 %ap = call sbyte* %<a href="#i_va_start">llvm.va_start</a>()
1857 ; Read a single integer argument
1858 %tmp = vaarg sbyte* %ap, int
1860 ; Advance to the next argument
1861 %ap2 = vanext sbyte* %ap, int
1863 ; Demonstrate usage of llvm.va_copy and llvm.va_end
1864 %aq = call sbyte* %<a href="#i_va_copy">llvm.va_copy</a>(sbyte* %ap2)
1865 call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %aq)
1867 ; Stop processing of arguments.
1868 call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %ap2)
1874 <!-- _______________________________________________________________________ -->
1875 <div class="doc_subsubsection">
1876 <a name="i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
1880 <div class="doc_text">
1882 <pre> call va_list ()* %llvm.va_start()<br></pre>
1884 <p>The '<tt>llvm.va_start</tt>' intrinsic returns a new <tt><arglist></tt>
1885 for subsequent use by the variable argument intrinsics.</p>
1887 <p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
1888 macro available in C. In a target-dependent way, it initializes and
1889 returns a <tt>va_list</tt> element, so that the next <tt>vaarg</tt>
1890 will produce the first variable argument passed to the function. Unlike
1891 the C <tt>va_start</tt> macro, this intrinsic does not need to know the
1892 last argument of the function, the compiler can figure that out.</p>
1893 <p>Note that this intrinsic function is only legal to be called from
1894 within the body of a variable argument function.</p>
1897 <!-- _______________________________________________________________________ -->
1898 <div class="doc_subsubsection">
1899 <a name="i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
1902 <div class="doc_text">
1904 <pre> call void (va_list)* %llvm.va_end(va_list <arglist>)<br></pre>
1906 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt><arglist></tt>
1907 which has been initialized previously with <tt><a href="#i_va_start">llvm.va_start</a></tt>
1908 or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
1910 <p>The argument is a <tt>va_list</tt> to destroy.</p>
1912 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
1913 macro available in C. In a target-dependent way, it destroys the <tt>va_list</tt>.
1914 Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
1915 href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly
1916 with calls to <tt>llvm.va_end</tt>.</p>
1919 <!-- _______________________________________________________________________ -->
1920 <div class="doc_subsubsection">
1921 <a name="i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
1924 <div class="doc_text">
1929 call va_list (va_list)* %llvm.va_copy(va_list <destarglist>)
1934 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position
1935 from the source argument list to the destination argument list.</p>
1939 <p>The argument is the <tt>va_list</tt> to copy.</p>
1943 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
1944 macro available in C. In a target-dependent way, it copies the source
1945 <tt>va_list</tt> element into the returned list. This intrinsic is necessary
1946 because the <tt><a href="i_va_start">llvm.va_start</a></tt> intrinsic may be
1947 arbitrarily complex and require memory allocation, for example.</p>
1951 <!-- ======================================================================= -->
1952 <div class="doc_subsection">
1953 <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
1956 <div class="doc_text">
1959 LLVM support for <a href="GarbageCollection.html">Accurate Garbage
1960 Collection</a> requires the implementation and generation of these intrinsics.
1961 These intrinsics allow identification of <a href="#i_gcroot">GC roots on the
1962 stack</a>, as well as garbage collector implementations that require <a
1963 href="#i_gcread">read</a> and <a href="#i_gcwrite">write</a> barriers.
1964 Front-ends for type-safe garbage collected languages should generate these
1965 intrinsics to make use of the LLVM garbage collectors. For more details, see <a
1966 href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>.
1970 <!-- _______________________________________________________________________ -->
1971 <div class="doc_subsubsection">
1972 <a name="i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
1975 <div class="doc_text">
1980 call void (<ty>**, <ty2>*)* %llvm.gcroot(<ty>** %ptrloc, <ty2>* %metadata)
1985 <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existance of a GC root to
1986 the code generator, and allows some metadata to be associated with it.</p>
1990 <p>The first argument specifies the address of a stack object that contains the
1991 root pointer. The second pointer (which must be either a constant or a global
1992 value address) contains the meta-data to be associated with the root.</p>
1996 <p>At runtime, a call to this intrinsics stores a null pointer into the "ptrloc"
1997 location. At compile-time, the code generator generates information to allow
1998 the runtime to find the pointer at GC safe points.
2004 <!-- _______________________________________________________________________ -->
2005 <div class="doc_subsubsection">
2006 <a name="i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
2009 <div class="doc_text">
2014 call sbyte* (sbyte**)* %llvm.gcread(sbyte** %Ptr)
2019 <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
2020 locations, allowing garbage collector implementations that require read
2025 <p>The argument is the address to read from, which should be an address
2026 allocated from the garbage collector.</p>
2030 <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
2031 instruction, but may be replaced with substantially more complex code by the
2032 garbage collector runtime, as needed.</p>
2037 <!-- _______________________________________________________________________ -->
2038 <div class="doc_subsubsection">
2039 <a name="i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
2042 <div class="doc_text">
2047 call void (sbyte*, sbyte**)* %llvm.gcwrite(sbyte* %P1, sbyte** %P2)
2052 <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
2053 locations, allowing garbage collector implementations that require write
2054 barriers (such as generational or reference counting collectors).</p>
2058 <p>The first argument is the reference to store, and the second is the heap
2059 location to store to.</p>
2063 <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
2064 instruction, but may be replaced with substantially more complex code by the
2065 garbage collector runtime, as needed.</p>
2071 <!-- ======================================================================= -->
2072 <div class="doc_subsection">
2073 <a name="int_codegen">Code Generator Intrinsics</a>
2076 <div class="doc_text">
2078 These intrinsics are provided by LLVM to expose special features that may only
2079 be implemented with code generator support.
2084 <!-- _______________________________________________________________________ -->
2085 <div class="doc_subsubsection">
2086 <a name="i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
2089 <div class="doc_text">
2093 call void* ()* %llvm.returnaddress(uint <level>)
2099 The '<tt>llvm.returnaddress</tt>' intrinsic returns a target-specific value
2100 indicating the return address of the current function or one of its callers.
2106 The argument to this intrinsic indicates which function to return the address
2107 for. Zero indicates the calling function, one indicates its caller, etc. The
2108 argument is <b>required</b> to be a constant integer value.
2114 The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer indicating
2115 the return address of the specified call frame, or zero if it cannot be
2116 identified. The value returned by this intrinsic is likely to be incorrect or 0
2117 for arguments other than zero, so it should only be used for debugging purposes.
2121 Note that calling this intrinsic does not prevent function inlining or other
2122 aggressive transformations, so the value returned may not that of the obvious
2123 source-language caller.
2128 <!-- _______________________________________________________________________ -->
2129 <div class="doc_subsubsection">
2130 <a name="i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
2133 <div class="doc_text">
2137 call void* ()* %llvm.frameaddress(uint <level>)
2143 The '<tt>llvm.frameaddress</tt>' intrinsic returns the target-specific frame
2144 pointer value for the specified stack frame.
2150 The argument to this intrinsic indicates which function to return the frame
2151 pointer for. Zero indicates the calling function, one indicates its caller,
2152 etc. The argument is <b>required</b> to be a constant integer value.
2158 The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer indicating
2159 the frame address of the specified call frame, or zero if it cannot be
2160 identified. The value returned by this intrinsic is likely to be incorrect or 0
2161 for arguments other than zero, so it should only be used for debugging purposes.
2165 Note that calling this intrinsic does not prevent function inlining or other
2166 aggressive transformations, so the value returned may not that of the obvious
2167 source-language caller.
2171 <!-- ======================================================================= -->
2172 <div class="doc_subsection">
2173 <a name="int_os">Operating System Intrinsics</a>
2176 <div class="doc_text">
2178 These intrinsics are provided by LLVM to support the implementation of
2179 operating system level code.
2184 <!-- _______________________________________________________________________ -->
2185 <div class="doc_subsubsection">
2186 <a name="i_readport">'<tt>llvm.readport</tt>' Intrinsic</a>
2189 <div class="doc_text">
2193 call <integer type> (<integer type>)* %llvm.readport (<integer type> <address>)
2199 The '<tt>llvm.readport</tt>' intrinsic reads data from the specified hardware
2206 The argument to this intrinsic indicates the hardware I/O address from which
2207 to read the data. The address is in the hardware I/O address namespace (as
2208 opposed to being a memory location for memory mapped I/O).
2214 The '<tt>llvm.readport</tt>' intrinsic reads data from the hardware I/O port
2215 specified by <i>address</i> and returns the value. The address and return
2216 value must be integers, but the size is dependent upon the platform upon which
2217 the program is code generated. For example, on x86, the address must be an
2218 unsigned 16 bit value, and the return value must be 8, 16, or 32 bits.
2223 <!-- _______________________________________________________________________ -->
2224 <div class="doc_subsubsection">
2225 <a name="i_writeport">'<tt>llvm.writeport</tt>' Intrinsic</a>
2228 <div class="doc_text">
2232 call void (<integer type>, <integer type>)* %llvm.writeport (<integer type> <value>, <integer type> <address>)
2238 The '<tt>llvm.writeport</tt>' intrinsic writes data to the specified hardware
2245 The first argument is the value to write to the I/O port.
2249 The second argument indicates the hardware I/O address to which data should be
2250 written. The address is in the hardware I/O address namespace (as opposed to
2251 being a memory location for memory mapped I/O).
2257 The '<tt>llvm.writeport</tt>' intrinsic writes <i>value</i> to the I/O port
2258 specified by <i>address</i>. The address and value must be integers, but the
2259 size is dependent upon the platform upon which the program is code generated.
2260 For example, on x86, the address must be an unsigned 16 bit value, and the
2261 value written must be 8, 16, or 32 bits in length.
2266 <!-- _______________________________________________________________________ -->
2267 <div class="doc_subsubsection">
2268 <a name="i_readio">'<tt>llvm.readio</tt>' Intrinsic</a>
2271 <div class="doc_text">
2275 call <result> (<ty>*)* %llvm.readio (<ty> * <pointer>)
2281 The '<tt>llvm.readio</tt>' intrinsic reads data from a memory mapped I/O
2288 The argument to this intrinsic is a pointer indicating the memory address from
2289 which to read the data. The data must be a
2290 <a href="#t_firstclass">first class</a> type.
2296 The '<tt>llvm.readio</tt>' intrinsic reads data from a memory mapped I/O
2297 location specified by <i>pointer</i> and returns the value. The argument must
2298 be a pointer, and the return value must be a
2299 <a href="#t_firstclass">first class</a> type. However, certain architectures
2300 may not support I/O on all first class types. For example, 32 bit processors
2301 may only support I/O on data types that are 32 bits or less.
2305 This intrinsic enforces an in-order memory model for llvm.readio and
2306 llvm.writeio calls on machines that use dynamic scheduling. Dynamically
2307 scheduled processors may execute loads and stores out of order, re-ordering at
2308 run time accesses to memory mapped I/O registers. Using these intrinsics
2309 ensures that accesses to memory mapped I/O registers occur in program order.
2314 <!-- _______________________________________________________________________ -->
2315 <div class="doc_subsubsection">
2316 <a name="i_writeio">'<tt>llvm.writeio</tt>' Intrinsic</a>
2319 <div class="doc_text">
2323 call void (<ty1>, <ty2>*)* %llvm.writeio (<ty1> <value>, <ty2> * <pointer>)
2329 The '<tt>llvm.writeio</tt>' intrinsic writes data to the specified memory
2336 The first argument is the value to write to the memory mapped I/O location.
2337 The second argument is a pointer indicating the memory address to which the
2338 data should be written.
2344 The '<tt>llvm.writeio</tt>' intrinsic writes <i>value</i> to the memory mapped
2345 I/O address specified by <i>pointer</i>. The value must be a
2346 <a href="#t_firstclass">first class</a> type. However, certain architectures
2347 may not support I/O on all first class types. For example, 32 bit processors
2348 may only support I/O on data types that are 32 bits or less.
2352 This intrinsic enforces an in-order memory model for llvm.readio and
2353 llvm.writeio calls on machines that use dynamic scheduling. Dynamically
2354 scheduled processors may execute loads and stores out of order, re-ordering at
2355 run time accesses to memory mapped I/O registers. Using these intrinsics
2356 ensures that accesses to memory mapped I/O registers occur in program order.
2362 <!-- ======================================================================= -->
2363 <div class="doc_subsection">
2364 <a name="int_libc">Standard C Library Intrinsics</a>
2367 <div class="doc_text">
2369 LLVM provides intrinsics for a few important standard C library functions.
2370 These intrinsics allow source-language front-ends to pass information about the
2371 alignment of the pointer arguments to the code generator, providing opportunity
2372 for more efficient code generation.
2377 <!-- _______________________________________________________________________ -->
2378 <div class="doc_subsubsection">
2379 <a name="i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
2382 <div class="doc_text">
2386 call void (sbyte*, sbyte*, uint, uint)* %llvm.memcpy(sbyte* <dest>, sbyte* <src>,
2387 uint <len>, uint <align>)
2393 The '<tt>llvm.memcpy</tt>' intrinsic copies a block of memory from the source
2394 location to the destination location.
2398 Note that, unlike the standard libc function, the <tt>llvm.memcpy</tt> intrinsic
2399 does not return a value, and takes an extra alignment argument.
2405 The first argument is a pointer to the destination, the second is a pointer to
2406 the source. The third argument is an (arbitrarily sized) integer argument
2407 specifying the number of bytes to copy, and the fourth argument is the alignment
2408 of the source and destination locations.
2412 If the call to this intrinisic has an alignment value that is not 0 or 1, then
2413 the caller guarantees that the size of the copy is a multiple of the alignment
2414 and that both the source and destination pointers are aligned to that boundary.
2420 The '<tt>llvm.memcpy</tt>' intrinsic copies a block of memory from the source
2421 location to the destination location, which are not allowed to overlap. It
2422 copies "len" bytes of memory over. If the argument is known to be aligned to
2423 some boundary, this can be specified as the fourth argument, otherwise it should
2429 <!-- _______________________________________________________________________ -->
2430 <div class="doc_subsubsection">
2431 <a name="i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
2434 <div class="doc_text">
2438 call void (sbyte*, sbyte*, uint, uint)* %llvm.memmove(sbyte* <dest>, sbyte* <src>,
2439 uint <len>, uint <align>)
2445 The '<tt>llvm.memmove</tt>' intrinsic moves a block of memory from the source
2446 location to the destination location. It is similar to the '<tt>llvm.memcpy</tt>'
2447 intrinsic but allows the two memory locations to overlap.
2451 Note that, unlike the standard libc function, the <tt>llvm.memmove</tt> intrinsic
2452 does not return a value, and takes an extra alignment argument.
2458 The first argument is a pointer to the destination, the second is a pointer to
2459 the source. The third argument is an (arbitrarily sized) integer argument
2460 specifying the number of bytes to copy, and the fourth argument is the alignment
2461 of the source and destination locations.
2465 If the call to this intrinisic has an alignment value that is not 0 or 1, then
2466 the caller guarantees that the size of the copy is a multiple of the alignment
2467 and that both the source and destination pointers are aligned to that boundary.
2473 The '<tt>llvm.memmove</tt>' intrinsic copies a block of memory from the source
2474 location to the destination location, which may overlap. It
2475 copies "len" bytes of memory over. If the argument is known to be aligned to
2476 some boundary, this can be specified as the fourth argument, otherwise it should
2482 <!-- _______________________________________________________________________ -->
2483 <div class="doc_subsubsection">
2484 <a name="i_memset">'<tt>llvm.memset</tt>' Intrinsic</a>
2487 <div class="doc_text">
2491 call void (sbyte*, ubyte, uint, uint)* %llvm.memset(sbyte* <dest>, ubyte <val>,
2492 uint <len>, uint <align>)
2498 The '<tt>llvm.memset</tt>' intrinsic fills a block of memory with a particular
2503 Note that, unlike the standard libc function, the <tt>llvm.memset</tt> intrinsic
2504 does not return a value, and takes an extra alignment argument.
2510 The first argument is a pointer to the destination to fill, the second is the
2511 byte value to fill it with, the third argument is an (arbitrarily sized) integer
2512 argument specifying the number of bytes to fill, and the fourth argument is the
2513 known alignment of destination location.
2517 If the call to this intrinisic has an alignment value that is not 0 or 1, then
2518 the caller guarantees that the size of the copy is a multiple of the alignment
2519 and that the destination pointer is aligned to that boundary.
2525 The '<tt>llvm.memset</tt>' intrinsic fills "len" bytes of memory starting at the
2526 destination location. If the argument is known to be aligned to some boundary,
2527 this can be specified as the fourth argument, otherwise it should be set to 0 or
2533 <!-- _______________________________________________________________________ -->
2534 <div class="doc_subsubsection">
2535 <a name="i_isnan">'<tt>llvm.isnan</tt>' Intrinsic</a>
2538 <div class="doc_text">
2542 call bool (<float or double>)* %llvm.isnan(<float or double> Val)
2548 The '<tt>llvm.isnan</tt>' intrinsic returns true if the specific floating point
2555 The argument is a floating point number.
2561 If the argument is a SNAN or QNAN, it returns true, otherwise false.
2568 <!-- ======================================================================= -->
2569 <div class="doc_subsection">
2570 <a name="int_debugger">Debugger Intrinsics</a>
2573 <div class="doc_text">
2575 The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> prefix),
2576 are described in the <a
2577 href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source Level
2578 Debugging</a> document.
2583 <!-- *********************************************************************** -->
2586 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
2587 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
2588 <a href="http://validator.w3.org/check/referer"><img
2589 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
2591 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
2592 <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
2593 Last modified: $Date$
projects / oota-llvm.git / blob