diff options
Diffstat (limited to 'docs/LangRef.html')
| -rw-r--r-- | docs/LangRef.html | 6249 |
1 files changed, 3151 insertions, 3098 deletions
diff --git a/docs/LangRef.html b/docs/LangRef.html index f229150..21e41d5 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -20,7 +20,24 @@ <li><a href="#highlevel">High Level Structure</a> <ol> <li><a href="#modulestructure">Module Structure</a></li> - <li><a href="#linkage">Linkage Types</a></li> + <li><a href="#linkage">Linkage Types</a> + <ol> + <li><a href="#linkage_private">'<tt>private</tt>' Linkage</a></li> + <li><a href="#linkage_linker_private">'<tt>linker_private</tt>' Linkage</a></li> + <li><a href="#linkage_internal">'<tt>internal</tt>' Linkage</a></li> + <li><a href="#linkage_available_externally">'<tt>available_externally</tt>' Linkage</a></li> + <li><a href="#linkage_linkonce">'<tt>linkonce</tt>' Linkage</a></li> + <li><a href="#linkage_common">'<tt>common</tt>' Linkage</a></li> + <li><a href="#linkage_weak">'<tt>weak</tt>' Linkage</a></li> + <li><a href="#linkage_appending">'<tt>appending</tt>' Linkage</a></li> + <li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li> + <li><a href="#linkage_linkonce_odr">'<tt>linkonce_odr</tt>' Linkage</a></li> + <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li> + <li><a href="#linkage_external">'<tt>externally visible</tt>' Linkage</a></li> + <li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li> + <li><a href="#linkage_dllexport">'<tt>dllexport</tt>' Linkage</a></li> + </ol> + </li> <li><a href="#callingconv">Calling Conventions</a></li> <li><a href="#namedtypes">Named Types</a></li> <li><a href="#globalvars">Global Variables</a></li> @@ -31,6 +48,7 @@ <li><a href="#gc">Garbage Collector Names</a></li> <li><a href="#moduleasm">Module-Level Inline Assembly</a></li> <li><a href="#datalayout">Data Layout</a></li> + <li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li> </ol> </li> <li><a href="#typesystem">Type System</a> @@ -38,6 +56,7 @@ <li><a href="#t_classifications">Type Classifications</a></li> <li><a href="#t_primitive">Primitive Types</a> <ol> + <li><a href="#t_integer">Integer Type</a></li> <li><a href="#t_floating">Floating Point Types</a></li> <li><a href="#t_void">Void Type</a></li> <li><a href="#t_label">Label Type</a></li> @@ -46,7 +65,6 @@ </li> <li><a href="#t_derived">Derived Types</a> <ol> - <li><a href="#t_integer">Integer Type</a></li> <li><a href="#t_array">Array Type</a></li> <li><a href="#t_function">Function Type</a></li> <li><a href="#t_pointer">Pointer Type</a></li> @@ -74,6 +92,17 @@ <li><a href="#inlineasm">Inline Assembler Expressions</a></li> </ol> </li> + <li><a href="#intrinsic_globals">Intrinsic Global Variables</a> + <ol> + <li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li> + <li><a href="#intg_compiler_used">The '<tt>llvm.compiler.used</tt>' + Global Variable</a></li> + <li><a href="#intg_global_ctors">The '<tt>llvm.global_ctors</tt>' + Global Variable</a></li> + <li><a href="#intg_global_dtors">The '<tt>llvm.global_dtors</tt>' + Global Variable</a></li> + </ol> + </li> <li><a href="#instref">Instruction Reference</a> <ol> <li><a href="#terminators">Terminator Instructions</a> @@ -155,8 +184,6 @@ <ol> <li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li> <li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li> - <li><a href="#i_vicmp">'<tt>vicmp</tt>' Instruction</a></li> - <li><a href="#i_vfcmp">'<tt>vfcmp</tt>' Instruction</a></li> <li><a href="#i_phi">'<tt>phi</tt>' Instruction</a></li> <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li> <li><a href="#i_call">'<tt>call</tt>' Instruction</a></li> @@ -210,8 +237,6 @@ <li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li> <li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li> <li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li> - <li><a href="#int_part_select">'<tt>llvm.part.select.*</tt>' Intrinsic </a></li> - <li><a href="#int_part_set">'<tt>llvm.part.set.*</tt>' Intrinsic </a></li> </ol> </li> <li><a href="#int_overflow">Arithmetic with Overflow Intrinsics</a> @@ -248,6 +273,14 @@ <li><a href="#int_atomic_load_umin"><tt>llvm.atomic.load.umin</tt></a></li> </ol> </li> + <li><a href="#int_memorymarkers">Memory Use Markers</a> + <ol> + <li><a href="#int_lifetime_start"><tt>llvm.lifetime.start</tt></a></li> + <li><a href="#int_lifetime_end"><tt>llvm.lifetime.end</tt></a></li> + <li><a href="#int_invariant_start"><tt>llvm.invariant.start</tt></a></li> + <li><a href="#int_invariant_end"><tt>llvm.invariant.end</tt></a></li> + </ol> + </li> <li><a href="#int_general">General intrinsics</a> <ol> <li><a href="#int_var_annotation"> @@ -274,12 +307,13 @@ <!-- *********************************************************************** --> <div class="doc_text"> -<p>This document is a reference manual for the LLVM assembly language. -LLVM is a Static Single Assignment (SSA) based representation that provides -type safety, low-level operations, flexibility, and the capability of -representing 'all' high-level languages cleanly. It is the common code -representation used throughout all phases of the LLVM compilation -strategy.</p> + +<p>This document is a reference manual for the LLVM assembly language. LLVM is + a Static Single Assignment (SSA) based representation that provides type + safety, low-level operations, flexibility, and the capability of representing + 'all' high-level languages cleanly. It is the common code representation + used throughout all phases of the LLVM compilation strategy.</p> + </div> <!-- *********************************************************************** --> @@ -288,26 +322,24 @@ strategy.</p> <div class="doc_text"> -<p>The LLVM code representation is designed to be used in three -different forms: as an in-memory compiler IR, as an on-disk bitcode -representation (suitable for fast loading by a Just-In-Time compiler), -and as a human readable assembly language representation. This allows -LLVM to provide a powerful intermediate representation for efficient -compiler transformations and analysis, while providing a natural means -to debug and visualize the transformations. The three different forms -of LLVM are all equivalent. This document describes the human readable -representation and notation.</p> +<p>The LLVM code representation is designed to be used in three different forms: + as an in-memory compiler IR, as an on-disk bitcode representation (suitable + for fast loading by a Just-In-Time compiler), and as a human readable + assembly language representation. This allows LLVM to provide a powerful + intermediate representation for efficient compiler transformations and + analysis, while providing a natural means to debug and visualize the + transformations. The three different forms of LLVM are all equivalent. This + document describes the human readable representation and notation.</p> -<p>The LLVM representation aims to be light-weight and low-level -while being expressive, typed, and extensible at the same time. It -aims to be a "universal IR" of sorts, by being at a low enough level -that high-level ideas may be cleanly mapped to it (similar to how -microprocessors are "universal IR's", allowing many source languages to -be mapped to them). By providing type information, LLVM can be used as -the target of optimizations: for example, through pointer analysis, it -can be proven that a C automatic variable is never accessed outside of -the current function... allowing it to be promoted to a simple SSA -value instead of a memory location.</p> +<p>The LLVM representation aims to be light-weight and low-level while being + expressive, typed, and extensible at the same time. It aims to be a + "universal IR" of sorts, by being at a low enough level that high-level ideas + may be cleanly mapped to it (similar to how microprocessors are "universal + IR's", allowing many source languages to be mapped to them). By providing + type information, LLVM can be used as the target of optimizations: for + example, through pointer analysis, it can be proven that a C automatic + variable is never accessed outside of the current function... allowing it to + be promoted to a simple SSA value instead of a memory location.</p> </div> @@ -316,10 +348,10 @@ value instead of a memory location.</p> <div class="doc_text"> -<p>It is important to note that this document describes 'well formed' -LLVM assembly language. There is a difference between what the parser -accepts and what is considered 'well formed'. For example, the -following instruction is syntactically okay, but not well formed:</p> +<p>It is important to note that this document describes 'well formed' LLVM + assembly language. There is a difference between what the parser accepts and + what is considered 'well formed'. For example, the following instruction is + syntactically okay, but not well formed:</p> <div class="doc_code"> <pre> @@ -327,13 +359,13 @@ following instruction is syntactically okay, but not well formed:</p> </pre> </div> -<p>...because the definition of <tt>%x</tt> does not dominate all of -its uses. The LLVM infrastructure provides a verification pass that may -be used to verify that an LLVM module is well formed. This pass is -automatically run by the parser after parsing input assembly and by -the optimizer before it outputs bitcode. The violations pointed out -by the verifier pass indicate bugs in transformation passes or input to -the parser.</p> +<p>...because the definition of <tt>%x</tt> does not dominate all of its + uses. The LLVM infrastructure provides a verification pass that may be used + to verify that an LLVM module is well formed. This pass is automatically run + by the parser after parsing input assembly and by the optimizer before it + outputs bitcode. The violations pointed out by the verifier pass indicate + bugs in transformation passes or input to the parser.</p> + </div> <!-- Describe the typesetting conventions here. --> @@ -344,44 +376,47 @@ the parser.</p> <div class="doc_text"> - <p>LLVM identifiers come in two basic types: global and local. Global - identifiers (functions, global variables) begin with the @ character. Local - identifiers (register names, types) begin with the % character. Additionally, - there are three different formats for identifiers, for different purposes:</p> +<p>LLVM identifiers come in two basic types: global and local. Global + identifiers (functions, global variables) begin with the <tt>'@'</tt> + character. Local identifiers (register names, types) begin with + the <tt>'%'</tt> character. Additionally, there are three different formats + for identifiers, for different purposes:</p> <ol> <li>Named values are represented as a string of characters with their prefix. - For example, %foo, @DivisionByZero, %a.really.long.identifier. The actual - regular expression used is '<tt>[%@][a-zA-Z$._][a-zA-Z$._0-9]*</tt>'. - Identifiers which require other characters in their names can be surrounded - with quotes. Special characters may be escaped using "\xx" where xx is the - ASCII code for the character in hexadecimal. In this way, any character can - be used in a name value, even quotes themselves. + For example, <tt>%foo</tt>, <tt>@DivisionByZero</tt>, + <tt>%a.really.long.identifier</tt>. The actual regular expression used is + '<tt>[%@][a-zA-Z$._][a-zA-Z$._0-9]*</tt>'. Identifiers which require + other characters in their names can be surrounded with quotes. Special + characters may be escaped using <tt>"\xx"</tt> where <tt>xx</tt> is the + ASCII code for the character in hexadecimal. In this way, any character + can be used in a name value, even quotes themselves.</li> <li>Unnamed values are represented as an unsigned numeric value with their - prefix. For example, %12, @2, %44.</li> + prefix. For example, <tt>%12</tt>, <tt>@2</tt>, <tt>%44</tt>.</li> <li>Constants, which are described in a <a href="#constants">section about - constants</a>, below.</li> + constants</a>, below.</li> </ol> <p>LLVM requires that values start with a prefix for two reasons: Compilers -don't need to worry about name clashes with reserved words, and the set of -reserved words may be expanded in the future without penalty. Additionally, -unnamed identifiers allow a compiler to quickly come up with a temporary -variable without having to avoid symbol table conflicts.</p> + don't need to worry about name clashes with reserved words, and the set of + reserved words may be expanded in the future without penalty. Additionally, + unnamed identifiers allow a compiler to quickly come up with a temporary + variable without having to avoid symbol table conflicts.</p> <p>Reserved words in LLVM are very similar to reserved words in other -languages. There are keywords for different opcodes -('<tt><a href="#i_add">add</a></tt>', - '<tt><a href="#i_bitcast">bitcast</a></tt>', - '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names ('<tt><a -href="#t_void">void</a></tt>', '<tt><a href="#t_primitive">i32</a></tt>', etc...), -and others. These reserved words cannot conflict with variable names, because -none of them start with a prefix character ('%' or '@').</p> + languages. There are keywords for different opcodes + ('<tt><a href="#i_add">add</a></tt>', + '<tt><a href="#i_bitcast">bitcast</a></tt>', + '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names + ('<tt><a href="#t_void">void</a></tt>', + '<tt><a href="#t_primitive">i32</a></tt>', etc...), and others. These + reserved words cannot conflict with variable names, because none of them + start with a prefix character (<tt>'%'</tt> or <tt>'@'</tt>).</p> <p>Here is an example of LLVM code to multiply the integer variable -'<tt>%X</tt>' by 8:</p> + '<tt>%X</tt>' by 8:</p> <p>The easy way:</p> @@ -409,25 +444,23 @@ none of them start with a prefix character ('%' or '@').</p> </pre> </div> -<p>This last way of multiplying <tt>%X</tt> by 8 illustrates several -important lexical features of LLVM:</p> +<p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important + lexical features of LLVM:</p> <ol> - <li>Comments are delimited with a '<tt>;</tt>' and go until the end of - line.</li> + line.</li> <li>Unnamed temporaries are created when the result of a computation is not - assigned to a named value.</li> + assigned to a named value.</li> <li>Unnamed temporaries are numbered sequentially</li> - </ol> <p>...and it also shows a convention that we follow in this document. When -demonstrating instructions, we will follow an instruction with a comment that -defines the type and name of value produced. Comments are shown in italic -text.</p> + demonstrating instructions, we will follow an instruction with a comment that + defines the type and name of value produced. Comments are shown in italic + text.</p> </div> @@ -441,12 +474,12 @@ text.</p> <div class="doc_text"> -<p>LLVM programs are composed of "Module"s, each of which is a -translation unit of the input programs. Each module consists of -functions, global variables, and symbol table entries. Modules may be -combined together with the LLVM linker, which merges function (and -global variable) definitions, resolves forward declarations, and merges -symbol table entries. Here is an example of the "hello world" module:</p> +<p>LLVM programs are composed of "Module"s, each of which is a translation unit + of the input programs. Each module consists of functions, global variables, + and symbol table entries. Modules may be combined together with the LLVM + linker, which merges function (and global variable) definitions, resolves + forward declarations, and merges symbol table entries. Here is an example of + the "hello world" module:</p> <div class="doc_code"> <pre><i>; Declare the string constant as a global constant...</i> @@ -454,32 +487,32 @@ symbol table entries. Here is an example of the "hello world" module:</p> href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" <i>; [13 x i8]*</i> <i>; External declaration of the puts function</i> -<a href="#functionstructure">declare</a> i32 @puts(i8 *) <i>; i32(i8 *)* </i> +<a href="#functionstructure">declare</a> i32 @puts(i8 *) <i>; i32(i8 *)* </i> <i>; Definition of main function</i> -define i32 @main() { <i>; i32()* </i> +define i32 @main() { <i>; i32()* </i> <i>; Convert [13 x i8]* to i8 *...</i> %cast210 = <a - href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0 <i>; i8 *</i> + href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0 <i>; i8 *</i> <i>; Call puts function to write out the string to stdout...</i> <a - href="#i_call">call</a> i32 @puts(i8 * %cast210) <i>; i32</i> + href="#i_call">call</a> i32 @puts(i8 * %cast210) <i>; i32</i> <a href="#i_ret">ret</a> i32 0<br>}<br> </pre> </div> -<p>This example is made up of a <a href="#globalvars">global variable</a> -named "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" -function, and a <a href="#functionstructure">function definition</a> -for "<tt>main</tt>".</p> +<p>This example is made up of a <a href="#globalvars">global variable</a> named + "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, and + a <a href="#functionstructure">function definition</a> for + "<tt>main</tt>".</p> -<p>In general, a module is made up of a list of global values, -where both functions and global variables are global values. Global values are -represented by a pointer to a memory location (in this case, a pointer to an -array of char, and a pointer to a function), and have one of the following <a -href="#linkage">linkage types</a>.</p> +<p>In general, a module is made up of a list of global values, where both + functions and global variables are global values. Global values are + represented by a pointer to a memory location (in this case, a pointer to an + array of char, and a pointer to a function), and have one of the + following <a href="#linkage">linkage types</a>.</p> </div> @@ -490,139 +523,126 @@ href="#linkage">linkage types</a>.</p> <div class="doc_text"> -<p> -All Global Variables and Functions have one of the following types of linkage: -</p> +<p>All Global Variables and Functions have one of the following types of + linkage:</p> <dl> - <dt><tt><b><a name="linkage_private">private</a></b></tt>: </dt> - - <dd>Global values with private linkage are only directly accessible by - objects in the current module. In particular, linking code into a module with - an private global value may cause the private to be renamed as necessary to - avoid collisions. Because the symbol is private to the module, all - references can be updated. This doesn't show up in any symbol table in the - object file. - </dd> + <dd>Global values with private linkage are only directly accessible by objects + in the current module. In particular, linking code into a module with an + private global value may cause the private to be renamed as necessary to + avoid collisions. Because the symbol is private to the module, all + references can be updated. This doesn't show up in any symbol table in the + object file.</dd> + + <dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt>: </dt> + <dd>Similar to private, but the symbol is passed through the assembler and + removed by the linker after evaluation. Note that (unlike private + symbols) linker_private symbols are subject to coalescing by the linker: + weak symbols get merged and redefinitions are rejected. However, unlike + normal strong symbols, they are removed by the linker from the final + linked image (executable or dynamic library).</dd> <dt><tt><b><a name="linkage_internal">internal</a></b></tt>: </dt> + <dd>Similar to private, but the value shows as a local symbol + (<tt>STB_LOCAL</tt> in the case of ELF) in the object file. This + corresponds to the notion of the '<tt>static</tt>' keyword in C.</dd> - <dd> Similar to private, but the value shows as a local symbol (STB_LOCAL in - the case of ELF) in the object file. This corresponds to the notion of the - '<tt>static</tt>' keyword in C. - </dd> - - <dt><tt><b><a name="available_externally">available_externally</a></b></tt>: - </dt> - + <dt><tt><b><a name="linkage_available_externally">available_externally</a></b></tt>: </dt> <dd>Globals with "<tt>available_externally</tt>" linkage are never emitted - into the object file corresponding to the LLVM module. They exist to - allow inlining and other optimizations to take place given knowledge of the - definition of the global, which is known to be somewhere outside the module. - Globals with <tt>available_externally</tt> linkage are allowed to be discarded - at will, and are otherwise the same as <tt>linkonce_odr</tt>. This linkage - type is only allowed on definitions, not declarations.</dd> + into the object file corresponding to the LLVM module. They exist to + allow inlining and other optimizations to take place given knowledge of + the definition of the global, which is known to be somewhere outside the + module. Globals with <tt>available_externally</tt> linkage are allowed to + be discarded at will, and are otherwise the same as <tt>linkonce_odr</tt>. + This linkage type is only allowed on definitions, not declarations.</dd> <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt>: </dt> - <dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of - the same name when linkage occurs. This is typically used to implement - inline functions, templates, or other code which must be generated in each - translation unit that uses it. Unreferenced <tt>linkonce</tt> globals are - allowed to be discarded. - </dd> - - <dt><tt><b><a name="linkage_common">common</a></b></tt>: </dt> - - <dd>"<tt>common</tt>" linkage is exactly the same as <tt>linkonce</tt> - linkage, except that unreferenced <tt>common</tt> globals may not be - discarded. This is used for globals that may be emitted in multiple - translation units, but that are not guaranteed to be emitted into every - translation unit that uses them. One example of this is tentative - definitions in C, such as "<tt>int X;</tt>" at global scope. - </dd> + the same name when linkage occurs. This is typically used to implement + inline functions, templates, or other code which must be generated in each + translation unit that uses it. Unreferenced <tt>linkonce</tt> globals are + allowed to be discarded.</dd> <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt> + <dd>"<tt>weak</tt>" linkage has the same merging semantics as + <tt>linkonce</tt> linkage, except that unreferenced globals with + <tt>weak</tt> linkage may not be discarded. This is used for globals that + are declared "weak" in C source code.</dd> + + <dt><tt><b><a name="linkage_common">common</a></b></tt>: </dt> + <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but + they are used for tentative definitions in C, such as "<tt>int X;</tt>" at + global scope. + Symbols with "<tt>common</tt>" linkage are merged in the same way as + <tt>weak symbols</tt>, and they may not be deleted if unreferenced. + <tt>common</tt> symbols may not have an explicit section, + must have a zero initializer, and may not be marked '<a + href="#globalvars"><tt>constant</tt></a>'. Functions and aliases may not + have common linkage.</dd> - <dd>"<tt>weak</tt>" linkage is the same as <tt>common</tt> linkage, except - that some targets may choose to emit different assembly sequences for them - for target-dependent reasons. This is used for globals that are declared - "weak" in C source code. - </dd> <dt><tt><b><a name="linkage_appending">appending</a></b></tt>: </dt> - <dd>"<tt>appending</tt>" linkage may only be applied to global variables of - pointer to array type. When two global variables with appending linkage are - linked together, the two global arrays are appended together. This is the - LLVM, typesafe, equivalent of having the system linker append together - "sections" with identical names when .o files are linked. - </dd> + pointer to array type. When two global variables with appending linkage + are linked together, the two global arrays are appended together. This is + the LLVM, typesafe, equivalent of having the system linker append together + "sections" with identical names when .o files are linked.</dd> <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt>: </dt> - - <dd>The semantics of this linkage follow the ELF object file model: the - symbol is weak until linked, if not linked, the symbol becomes null instead - of being an undefined reference. - </dd> - - <dt><tt><b><a name="linkage_linkonce">linkonce_odr</a></b></tt>: </dt> - <dt><tt><b><a name="linkage_weak">weak_odr</a></b></tt>: </dt> - <dd>Some languages allow differing globals to be merged, such as two - functions with different semantics. Other languages, such as <tt>C++</tt>, - ensure that only equivalent globals are ever merged (the "one definition - rule" - "ODR"). Such languages can use the <tt>linkonce_odr</tt> - and <tt>weak_odr</tt> linkage types to indicate that the global will only - be merged with equivalent globals. These linkage types are otherwise the - same as their non-<tt>odr</tt> versions. - </dd> + <dd>The semantics of this linkage follow the ELF object file model: the symbol + is weak until linked, if not linked, the symbol becomes null instead of + being an undefined reference.</dd> + + <dt><tt><b><a name="linkage_linkonce_odr">linkonce_odr</a></b></tt>: </dt> + <dt><tt><b><a name="linkage_weak_odr">weak_odr</a></b></tt>: </dt> + <dd>Some languages allow differing globals to be merged, such as two functions + with different semantics. Other languages, such as <tt>C++</tt>, ensure + that only equivalent globals are ever merged (the "one definition rule" - + "ODR"). Such languages can use the <tt>linkonce_odr</tt> + and <tt>weak_odr</tt> linkage types to indicate that the global will only + be merged with equivalent globals. These linkage types are otherwise the + same as their non-<tt>odr</tt> versions.</dd> <dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt> - <dd>If none of the above identifiers are used, the global is externally - visible, meaning that it participates in linkage and can be used to resolve - external symbol references. - </dd> + visible, meaning that it participates in linkage and can be used to + resolve external symbol references.</dd> </dl> - <p> - The next two types of linkage are targeted for Microsoft Windows platform - only. They are designed to support importing (exporting) symbols from (to) - DLLs (Dynamic Link Libraries). - </p> +<p>The next two types of linkage are targeted for Microsoft Windows platform + only. They are designed to support importing (exporting) symbols from (to) + DLLs (Dynamic Link Libraries).</p> - <dl> +<dl> <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt>: </dt> - <dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function - or variable via a global pointer to a pointer that is set up by the DLL - exporting the symbol. On Microsoft Windows targets, the pointer name is - formed by combining <code>__imp_</code> and the function or variable name. - </dd> + or variable via a global pointer to a pointer that is set up by the DLL + exporting the symbol. On Microsoft Windows targets, the pointer name is + formed by combining <code>__imp_</code> and the function or variable + name.</dd> <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt>: </dt> - <dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global - pointer to a pointer in a DLL, so that it can be referenced with the - <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer - name is formed by combining <code>__imp_</code> and the function or variable - name. - </dd> - + pointer to a pointer in a DLL, so that it can be referenced with the + <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer + name is formed by combining <code>__imp_</code> and the function or + variable name.</dd> </dl> -<p>For example, since the "<tt>.LC0</tt>" -variable is defined to be internal, if another module defined a "<tt>.LC0</tt>" -variable and was linked with this one, one of the two would be renamed, -preventing a collision. Since "<tt>main</tt>" and "<tt>puts</tt>" are -external (i.e., lacking any linkage declarations), they are accessible -outside of the current module.</p> -<p>It is illegal for a function <i>declaration</i> -to have any linkage type other than "externally visible", <tt>dllimport</tt> -or <tt>extern_weak</tt>.</p> +<p>For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if + another module defined a "<tt>.LC0</tt>" variable and was linked with this + one, one of the two would be renamed, preventing a collision. Since + "<tt>main</tt>" and "<tt>puts</tt>" are external (i.e., lacking any linkage + declarations), they are accessible outside of the current module.</p> + +<p>It is illegal for a function <i>declaration</i> to have any linkage type + other than "externally visible", <tt>dllimport</tt> + or <tt>extern_weak</tt>.</p> + <p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt> -or <tt>weak_odr</tt> linkages.</p> + or <tt>weak_odr</tt> linkages.</p> + </div> <!-- ======================================================================= --> @@ -633,55 +653,48 @@ or <tt>weak_odr</tt> linkages.</p> <div class="doc_text"> <p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a> -and <a href="#i_invoke">invokes</a> can all have an optional calling convention -specified for the call. The calling convention of any pair of dynamic -caller/callee must match, or the behavior of the program is undefined. The -following calling conventions are supported by LLVM, and more may be added in -the future:</p> + and <a href="#i_invoke">invokes</a> can all have an optional calling + convention specified for the call. The calling convention of any pair of + dynamic caller/callee must match, or the behavior of the program is + undefined. The following calling conventions are supported by LLVM, and more + may be added in the future:</p> <dl> <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt> - <dd>This calling convention (the default if no other calling convention is - specified) matches the target C calling conventions. This calling convention - supports varargs function calls and tolerates some mismatch in the declared - prototype and implemented declaration of the function (as does normal C). - </dd> + specified) matches the target C calling conventions. This calling + convention supports varargs function calls and tolerates some mismatch in + the declared prototype and implemented declaration of the function (as + does normal C).</dd> <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt> - <dd>This calling convention attempts to make calls as fast as possible - (e.g. by passing things in registers). This calling convention allows the - target to use whatever tricks it wants to produce fast code for the target, - without having to conform to an externally specified ABI (Application Binary - Interface). Implementations of this convention should allow arbitrary - <a href="CodeGenerator.html#tailcallopt">tail call optimization</a> to be - supported. This calling convention does not support varargs and requires the - prototype of all callees to exactly match the prototype of the function - definition. - </dd> + (e.g. by passing things in registers). This calling convention allows the + target to use whatever tricks it wants to produce fast code for the + target, without having to conform to an externally specified ABI + (Application Binary Interface). Implementations of this convention should + allow arbitrary <a href="CodeGenerator.html#tailcallopt">tail call + optimization</a> to be supported. This calling convention does not + support varargs and requires the prototype of all callees to exactly match + the prototype of the function definition.</dd> <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt> - <dd>This calling convention attempts to make code in the caller as efficient - as possible under the assumption that the call is not commonly executed. As - such, these calls often preserve all registers so that the call does not break - any live ranges in the caller side. This calling convention does not support - varargs and requires the prototype of all callees to exactly match the - prototype of the function definition. - </dd> + as possible under the assumption that the call is not commonly executed. + As such, these calls often preserve all registers so that the call does + not break any live ranges in the caller side. This calling convention + does not support varargs and requires the prototype of all callees to + exactly match the prototype of the function definition.</dd> <dt><b>"<tt>cc <<em>n</em>></tt>" - Numbered convention</b>:</dt> - <dd>Any calling convention may be specified by number, allowing - target-specific calling conventions to be used. Target specific calling - conventions start at 64. - </dd> + target-specific calling conventions to be used. Target specific calling + conventions start at 64.</dd> </dl> <p>More calling conventions can be added/defined on an as-needed basis, to -support pascal conventions or any other well-known target-independent -convention.</p> + support Pascal conventions or any other well-known target-independent + convention.</p> </div> @@ -692,37 +705,29 @@ convention.</p> <div class="doc_text"> -<p> -All Global Variables and Functions have one of the following visibility styles: -</p> +<p>All Global Variables and Functions have one of the following visibility + styles:</p> <dl> <dt><b>"<tt>default</tt>" - Default style</b>:</dt> - <dd>On targets that use the ELF object file format, default visibility means - that the declaration is visible to other - modules and, in shared libraries, means that the declared entity may be - overridden. On Darwin, default visibility means that the declaration is - visible to other modules. Default visibility corresponds to "external - linkage" in the language. - </dd> + that the declaration is visible to other modules and, in shared libraries, + means that the declared entity may be overridden. On Darwin, default + visibility means that the declaration is visible to other modules. Default + visibility corresponds to "external linkage" in the language.</dd> <dt><b>"<tt>hidden</tt>" - Hidden style</b>:</dt> - <dd>Two declarations of an object with hidden visibility refer to the same - object if they are in the same shared object. Usually, hidden visibility - indicates that the symbol will not be placed into the dynamic symbol table, - so no other module (executable or shared library) can reference it - directly. - </dd> + object if they are in the same shared object. Usually, hidden visibility + indicates that the symbol will not be placed into the dynamic symbol + table, so no other module (executable or shared library) can reference it + directly.</dd> <dt><b>"<tt>protected</tt>" - Protected style</b>:</dt> - <dd>On ELF, protected visibility indicates that the symbol will be placed in - the dynamic symbol table, but that references within the defining module will - bind to the local symbol. That is, the symbol cannot be overridden by another - module. - </dd> + the dynamic symbol table, but that references within the defining module + will bind to the local symbol. That is, the symbol cannot be overridden by + another module.</dd> </dl> </div> @@ -735,9 +740,8 @@ All Global Variables and Functions have one of the following visibility styles: <div class="doc_text"> <p>LLVM IR allows you to specify name aliases for certain types. This can make -it easier to read the IR and make the IR more condensed (particularly when -recursive types are involved). An example of a name specification is: -</p> + it easier to read the IR and make the IR more condensed (particularly when + recursive types are involved). An example of a name specification is:</p> <div class="doc_code"> <pre> @@ -745,19 +749,19 @@ recursive types are involved). An example of a name specification is: </pre> </div> -<p>You may give a name to any <a href="#typesystem">type</a> except "<a -href="t_void">void</a>". Type name aliases may be used anywhere a type is -expected with the syntax "%mytype".</p> +<p>You may give a name to any <a href="#typesystem">type</a> except + "<a href="t_void">void</a>". Type name aliases may be used anywhere a type + is expected with the syntax "%mytype".</p> <p>Note that type names are aliases for the structural type that they indicate, -and that you can therefore specify multiple names for the same type. This often -leads to confusing behavior when dumping out a .ll file. Since LLVM IR uses -structural typing, the name is not part of the type. When printing out LLVM IR, -the printer will pick <em>one name</em> to render all types of a particular -shape. This means that if you have code where two different source types end up -having the same LLVM type, that the dumper will sometimes print the "wrong" or -unexpected type. This is an important design point and isn't going to -change.</p> + and that you can therefore specify multiple names for the same type. This + often leads to confusing behavior when dumping out a .ll file. Since LLVM IR + uses structural typing, the name is not part of the type. When printing out + LLVM IR, the printer will pick <em>one name</em> to render all types of a + particular shape. This means that if you have code where two different + source types end up having the same LLVM type, that the dumper will sometimes + print the "wrong" or unexpected type. This is an important design point and + isn't going to change.</p> </div> @@ -769,48 +773,47 @@ change.</p> <div class="doc_text"> <p>Global variables define regions of memory allocated at compilation time -instead of run-time. Global variables may optionally be initialized, may have -an explicit section to be placed in, and may have an optional explicit alignment -specified. A variable may be defined as "thread_local", which means that it -will not be shared by threads (each thread will have a separated copy of the -variable). A variable may be defined as a global "constant," which indicates -that the contents of the variable will <b>never</b> be modified (enabling better -optimization, allowing the global data to be placed in the read-only section of -an executable, etc). Note that variables that need runtime initialization -cannot be marked "constant" as there is a store to the variable.</p> - -<p> -LLVM explicitly allows <em>declarations</em> of global variables to be marked -constant, even if the final definition of the global is not. This capability -can be used to enable slightly better optimization of the program, but requires -the language definition to guarantee that optimizations based on the -'constantness' are valid for the translation units that do not include the -definition. -</p> - -<p>As SSA values, global variables define pointer values that are in -scope (i.e. they dominate) all basic blocks in the program. Global -variables always define a pointer to their "content" type because they -describe a region of memory, and all memory objects in LLVM are -accessed through pointers.</p> - -<p>A global variable may be declared to reside in a target-specifc numbered -address space. For targets that support them, address spaces may affect how -optimizations are performed and/or what target instructions are used to access -the variable. The default address space is zero. The address space qualifier -must precede any other attributes.</p> + instead of run-time. Global variables may optionally be initialized, may + have an explicit section to be placed in, and may have an optional explicit + alignment specified. A variable may be defined as "thread_local", which + means that it will not be shared by threads (each thread will have a + separated copy of the variable). A variable may be defined as a global + "constant," which indicates that the contents of the variable + will <b>never</b> be modified (enabling better optimization, allowing the + global data to be placed in the read-only section of an executable, etc). + Note that variables that need runtime initialization cannot be marked + "constant" as there is a store to the variable.</p> + +<p>LLVM explicitly allows <em>declarations</em> of global variables to be marked + constant, even if the final definition of the global is not. This capability + can be used to enable slightly better optimization of the program, but + requires the language definition to guarantee that optimizations based on the + 'constantness' are valid for the translation units that do not include the + definition.</p> + +<p>As SSA values, global variables define pointer values that are in scope + (i.e. they dominate) all basic blocks in the program. Global variables + always define a pointer to their "content" type because they describe a + region of memory, and all memory objects in LLVM are accessed through + pointers.</p> + +<p>A global variable may be declared to reside in a target-specific numbered + address space. For targets that support them, address spaces may affect how + optimizations are performed and/or what target instructions are used to + access the variable. The default address space is zero. The address space + qualifier must precede any other attributes.</p> <p>LLVM allows an explicit section to be specified for globals. If the target -supports it, it will emit globals to the section specified.</p> + supports it, it will emit globals to the section specified.</p> <p>An explicit alignment may be specified for a global. If not present, or if -the alignment is set to zero, the alignment of the global is set by the target -to whatever it feels convenient. If an explicit alignment is specified, the -global is forced to have at least that much alignment. All alignments must be -a power of 2.</p> + the alignment is set to zero, the alignment of the global is set by the + target to whatever it feels convenient. If an explicit alignment is + specified, the global is forced to have at least that much alignment. All + alignments must be a power of 2.</p> -<p>For example, the following defines a global in a numbered address space with -an initializer, section, and alignment:</p> +<p>For example, the following defines a global in a numbered address space with + an initializer, section, and alignment:</p> <div class="doc_code"> <pre> @@ -828,74 +831,72 @@ an initializer, section, and alignment:</p> <div class="doc_text"> -<p>LLVM function definitions consist of the "<tt>define</tt>" keyord, -an optional <a href="#linkage">linkage type</a>, an optional -<a href="#visibility">visibility style</a>, an optional -<a href="#callingconv">calling convention</a>, a return type, an optional -<a href="#paramattrs">parameter attribute</a> for the return type, a function -name, a (possibly empty) argument list (each with optional -<a href="#paramattrs">parameter attributes</a>), optional -<a href="#fnattrs">function attributes</a>, an optional section, -an optional alignment, an optional <a href="#gc">garbage collector name</a>, -an opening curly brace, a list of basic blocks, and a closing curly brace. +<p>LLVM function definitions consist of the "<tt>define</tt>" keyord, an + optional <a href="#linkage">linkage type</a>, an optional + <a href="#visibility">visibility style</a>, an optional + <a href="#callingconv">calling convention</a>, a return type, an optional + <a href="#paramattrs">parameter attribute</a> for the return type, a function + name, a (possibly empty) argument list (each with optional + <a href="#paramattrs">parameter attributes</a>), optional + <a href="#fnattrs">function attributes</a>, an optional section, an optional + alignment, an optional <a href="#gc">garbage collector name</a>, an opening + curly brace, a list of basic blocks, and a closing curly brace.</p> -LLVM function declarations consist of the "<tt>declare</tt>" keyword, an -optional <a href="#linkage">linkage type</a>, an optional -<a href="#visibility">visibility style</a>, an optional -<a href="#callingconv">calling convention</a>, a return type, an optional -<a href="#paramattrs">parameter attribute</a> for the return type, a function -name, a possibly empty list of arguments, an optional alignment, and an optional -<a href="#gc">garbage collector name</a>.</p> +<p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an + optional <a href="#linkage">linkage type</a>, an optional + <a href="#visibility">visibility style</a>, an optional + <a href="#callingconv">calling convention</a>, a return type, an optional + <a href="#paramattrs">parameter attribute</a> for the return type, a function + name, a possibly empty list of arguments, an optional alignment, and an + optional <a href="#gc">garbage collector name</a>.</p> <p>A function definition contains a list of basic blocks, forming the CFG -(Control Flow Graph) for -the function. Each basic block may optionally start with a label (giving the -basic block a symbol table entry), contains a list of instructions, and ends -with a <a href="#terminators">terminator</a> instruction (such as a branch or -function return).</p> + (Control Flow Graph) for the function. Each basic block may optionally start + with a label (giving the basic block a symbol table entry), contains a list + of instructions, and ends with a <a href="#terminators">terminator</a> + instruction (such as a branch or function return).</p> <p>The first basic block in a function is special in two ways: it is immediately -executed on entrance to the function, and it is not allowed to have predecessor -basic blocks (i.e. there can not be any branches to the entry block of a -function). Because the block can have no predecessors, it also cannot have any -<a href="#i_phi">PHI nodes</a>.</p> + executed on entrance to the function, and it is not allowed to have + predecessor basic blocks (i.e. there can not be any branches to the entry + block of a function). Because the block can have no predecessors, it also + cannot have any <a href="#i_phi">PHI nodes</a>.</p> <p>LLVM allows an explicit section to be specified for functions. If the target -supports it, it will emit functions to the section specified.</p> + supports it, it will emit functions to the section specified.</p> <p>An explicit alignment may be specified for a function. If not present, or if -the alignment is set to zero, the alignment of the function is set by the target -to whatever it feels convenient. If an explicit alignment is specified, the -function is forced to have at least that much alignment. All alignments must be -a power of 2.</p> - - <h5>Syntax:</h5> + the alignment is set to zero, the alignment of the function is set by the + target to whatever it feels convenient. If an explicit alignment is + specified, the function is forced to have at least that much alignment. All + alignments must be a power of 2.</p> +<h5>Syntax:</h5> <div class="doc_code"> -<tt> +<pre> define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>] - [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] - <ResultType> @<FunctionName> ([argument list]) - [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N] - [<a href="#gc">gc</a>] { ... } -</tt> + [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] + <ResultType> @<FunctionName> ([argument list]) + [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N] + [<a href="#gc">gc</a>] { ... } +</pre> </div> </div> - <!-- ======================================================================= --> <div class="doc_subsection"> <a name="aliasstructure">Aliases</a> </div> + <div class="doc_text"> - <p>Aliases act as "second name" for the aliasee value (which can be either - function, global variable, another alias or bitcast of global value). Aliases - may have an optional <a href="#linkage">linkage type</a>, and an - optional <a href="#visibility">visibility style</a>.</p> - <h5>Syntax:</h5> +<p>Aliases act as "second name" for the aliasee value (which can be either + function, global variable, another alias or bitcast of global value). Aliases + may have an optional <a href="#linkage">linkage type</a>, and an + optional <a href="#visibility">visibility style</a>.</p> +<h5>Syntax:</h5> <div class="doc_code"> <pre> @<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee> @@ -904,21 +905,21 @@ define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>] </div> - - <!-- ======================================================================= --> <div class="doc_subsection"><a name="paramattrs">Parameter Attributes</a></div> + <div class="doc_text"> - <p>The return type and each parameter of a function type may have a set of - <i>parameter attributes</i> associated with them. Parameter attributes are - used to communicate additional information about the result or parameters of - a function. Parameter attributes are considered to be part of the function, - not of the function type, so functions with different parameter attributes - can have the same function type.</p> - <p>Parameter attributes are simple keywords that follow the type specified. If - multiple parameter attributes are needed, they are space separated. For - example:</p> +<p>The return type and each parameter of a function type may have a set of + <i>parameter attributes</i> associated with them. Parameter attributes are + used to communicate additional information about the result or parameters of + a function. Parameter attributes are considered to be part of the function, + not of the function type, so functions with different parameter attributes + can have the same function type.</p> + +<p>Parameter attributes are simple keywords that follow the type specified. If + multiple parameter attributes are needed, they are space separated. For + example:</p> <div class="doc_code"> <pre> @@ -928,71 +929,72 @@ declare signext i8 @returns_signed_char() </pre> </div> - <p>Note that any attributes for the function result (<tt>nounwind</tt>, - <tt>readonly</tt>) come immediately after the argument list.</p> - - <p>Currently, only the following parameter attributes are defined:</p> - <dl> - <dt><tt>zeroext</tt></dt> - <dd>This indicates to the code generator that the parameter or return value - should be zero-extended to a 32-bit value by the caller (for a parameter) - or the callee (for a return value).</dd> - - <dt><tt>signext</tt></dt> - <dd>This indicates to the code generator that the parameter or return value - should be sign-extended to a 32-bit value by the caller (for a parameter) - or the callee (for a return value).</dd> - - <dt><tt>inreg</tt></dt> - <dd>This indicates that this parameter or return value should be treated - in a special target-dependent fashion during while emitting code for a - function call or return (usually, by putting it in a register as opposed - to memory, though some targets use it to distinguish between two different - kinds of registers). Use of this attribute is target-specific.</dd> - - <dt><tt><a name="byval">byval</a></tt></dt> - <dd>This indicates that the pointer parameter should really be passed by - value to the function. The attribute implies that a hidden copy of the - pointee is made between the caller and the callee, so the callee is unable - to modify the value in the callee. This attribute is only valid on LLVM - pointer arguments. It is generally used to pass structs and arrays by - value, but is also valid on pointers to scalars. The copy is considered to - belong to the caller not the callee (for example, - <tt><a href="#readonly">readonly</a></tt> functions should not write to - <tt>byval</tt> parameters). This is not a valid attribute for return - values. The byval attribute also supports specifying an alignment with the - align attribute. This has a target-specific effect on the code generator - that usually indicates a desired alignment for the synthesized stack - slot.</dd> - - <dt><tt>sret</tt></dt> - <dd>This indicates that the pointer parameter specifies the address of a - structure that is the return value of the function in the source program. - This pointer must be guaranteed by the caller to be valid: loads and stores - to the structure may be assumed by the callee to not to trap. This may only - be applied to the first parameter. This is not a valid attribute for - return values. </dd> - - <dt><tt>noalias</tt></dt> - <dd>This indicates that the pointer does not alias any global or any other - parameter. The caller is responsible for ensuring that this is the - case. On a function return value, <tt>noalias</tt> additionally indicates - that the pointer does not alias any other pointers visible to the - caller. For further details, please see the discussion of the NoAlias - response in - <a href="http://llvm.org/docs/AliasAnalysis.html#MustMayNo">alias - analysis</a>.</dd> - - <dt><tt>nocapture</tt></dt> - <dd>This indicates that the callee does not make any copies of the pointer - that outlive the callee itself. This is not a valid attribute for return - values.</dd> - - <dt><tt>nest</tt></dt> - <dd>This indicates that the pointer parameter can be excised using the - <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid - attribute for return values.</dd> - </dl> +<p>Note that any attributes for the function result (<tt>nounwind</tt>, + <tt>readonly</tt>) come immediately after the argument list.</p> + +<p>Currently, only the following parameter attributes are defined:</p> + +<dl> + <dt><tt>zeroext</tt></dt> + <dd>This indicates to the code generator that the parameter or return value + should be zero-extended to a 32-bit value by the caller (for a parameter) + or the callee (for a return value).</dd> + + <dt><tt>signext</tt></dt> + <dd>This indicates to the code generator that the parameter or return value + should be sign-extended to a 32-bit value by the caller (for a parameter) + or the callee (for a return value).</dd> + + <dt><tt>inreg</tt></dt> + <dd>This indicates that this parameter or return value should be treated in a + special target-dependent fashion during while emitting code for a function + call or return (usually, by putting it in a register as opposed to memory, + though some targets use it to distinguish between two different kinds of + registers). Use of this attribute is target-specific.</dd> + + <dt><tt><a name="byval">byval</a></tt></dt> + <dd>This indicates that the pointer parameter should really be passed by value + to the function. The attribute implies that a hidden copy of the pointee + is made between the caller and the callee, so the callee is unable to + modify the value in the callee. This attribute is only valid on LLVM + pointer arguments. It is generally used to pass structs and arrays by + value, but is also valid on pointers to scalars. The copy is considered + to belong to the caller not the callee (for example, + <tt><a href="#readonly">readonly</a></tt> functions should not write to + <tt>byval</tt> parameters). This is not a valid attribute for return + values. The byval attribute also supports specifying an alignment with + the align attribute. This has a target-specific effect on the code + generator that usually indicates a desired alignment for the synthesized + stack slot.</dd> + + <dt><tt>sret</tt></dt> + <dd>This indicates that the pointer parameter specifies the address of a + structure that is the return value of the function in the source program. + This pointer must be guaranteed by the caller to be valid: loads and + stores to the structure may be assumed by the callee to not to trap. This + may only be applied to the first parameter. This is not a valid attribute + for return values. </dd> + + <dt><tt>noalias</tt></dt> + <dd>This indicates that the pointer does not alias any global or any other + parameter. The caller is responsible for ensuring that this is the + case. On a function return value, <tt>noalias</tt> additionally indicates + that the pointer does not alias any other pointers visible to the + caller. For further details, please see the discussion of the NoAlias + response in + <a href="http://llvm.org/docs/AliasAnalysis.html#MustMayNo">alias + analysis</a>.</dd> + + <dt><tt>nocapture</tt></dt> + <dd>This indicates that the callee does not make any copies of the pointer + that outlive the callee itself. This is not a valid attribute for return + values.</dd> + + <dt><tt>nest</tt></dt> + <dd>This indicates that the pointer parameter can be excised using the + <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid + attribute for return values.</dd> +</dl> </div> @@ -1002,15 +1004,20 @@ declare signext i8 @returns_signed_char() </div> <div class="doc_text"> + <p>Each function may specify a garbage collector name, which is simply a -string.</p> + string:</p> -<div class="doc_code"><pre ->define void @f() gc "name" { ...</pre></div> +<div class="doc_code"> +<pre> +define void @f() gc "name" { ... +</pre> +</div> <p>The compiler declares the supported values of <i>name</i>. Specifying a -collector which will cause the compiler to alter its output in order to support -the named garbage collection algorithm.</p> + collector which will cause the compiler to alter its output in order to + support the named garbage collection algorithm.</p> + </div> <!-- ======================================================================= --> @@ -1020,14 +1027,13 @@ the named garbage collection algorithm.</p> <div class="doc_text"> -<p>Function attributes are set to communicate additional information about - a function. Function attributes are considered to be part of the function, - not of the function type, so functions with different parameter attributes - can have the same function type.</p> +<p>Function attributes are set to communicate additional information about a + function. Function attributes are considered to be part of the function, not + of the function type, so functions with different parameter attributes can + have the same function type.</p> - <p>Function attributes are simple keywords that follow the type specified. If - multiple attributes are needed, they are space separated. For - example:</p> +<p>Function attributes are simple keywords that follow the type specified. If + multiple attributes are needed, they are space separated. For example:</p> <div class="doc_code"> <pre> @@ -1039,80 +1045,89 @@ define void @f() optsize </div> <dl> -<dt><tt>alwaysinline</tt></dt> -<dd>This attribute indicates that the inliner should attempt to inline this -function into callers whenever possible, ignoring any active inlining size -threshold for this caller.</dd> - -<dt><tt>noinline</tt></dt> -<dd>This attribute indicates that the inliner should never inline this function -in any situation. This attribute may not be used together with the -<tt>alwaysinline</tt> attribute.</dd> - -<dt><tt>optsize</tt></dt> -<dd>This attribute suggests that optimization passes and code generator passes -make choices that keep the code size of this function low, and otherwise do -optimizations specifically to reduce code size.</dd> - -<dt><tt>noreturn</tt></dt> -<dd>This function attribute indicates that the function never returns normally. -This produces undefined behavior at runtime if the function ever does -dynamically return.</dd> - -<dt><tt>nounwind</tt></dt> -<dd>This function attribute indicates that the function never returns with an -unwind or exceptional control flow. If the function does unwind, its runtime -behavior is undefined.</dd> - -<dt><tt>readnone</tt></dt> -<dd>This attribute indicates that the function computes its result (or decides to -unwind an exception) based strictly on its arguments, without dereferencing any -pointer arguments or otherwise accessing any mutable state (e.g. memory, control -registers, etc) visible to caller functions. It does not write through any -pointer arguments (including <tt><a href="#byval">byval</a></tt> arguments) and -never changes any state visible to callers. This means that it cannot unwind -exceptions by calling the <tt>C++</tt> exception throwing methods, but could -use the <tt>unwind</tt> instruction.</dd> - -<dt><tt><a name="readonly">readonly</a></tt></dt> -<dd>This attribute indicates that the function does not write through any -pointer arguments (including <tt><a href="#byval">byval</a></tt> arguments) -or otherwise modify any state (e.g. memory, control registers, etc) visible to -caller functions. It may dereference pointer arguments and read state that may -be set in the caller. A readonly function always returns the same value (or -unwinds an exception identically) when called with the same set of arguments -and global state. It cannot unwind an exception by calling the <tt>C++</tt> -exception throwing methods, but may use the <tt>unwind</tt> instruction.</dd> - -<dt><tt><a name="ssp">ssp</a></tt></dt> -<dd>This attribute indicates that the function should emit a stack smashing -protector. It is in the form of a "canary"—a random value placed on the -stack before the local variables that's checked upon return from the function to -see if it has been overwritten. A heuristic is used to determine if a function -needs stack protectors or not. - -<br><br>If a function that has an <tt>ssp</tt> attribute is inlined into a function -that doesn't have an <tt>ssp</tt> attribute, then the resulting function will -have an <tt>ssp</tt> attribute.</dd> - -<dt><tt>sspreq</tt></dt> -<dd>This attribute indicates that the function should <em>always</em> emit a -stack smashing protector. This overrides the <tt><a href="#ssp">ssp</a></tt> -function attribute. - -If a function that has an <tt>sspreq</tt> attribute is inlined into a -function that doesn't have an <tt>sspreq</tt> attribute or which has -an <tt>ssp</tt> attribute, then the resulting function will have -an <tt>sspreq</tt> attribute.</dd> - -<dt><tt>noredzone</tt></dt> -<dd>This attribute indicates that the code generator should not use a -red zone, even if the target-specific ABI normally permits it. -</dd> - -<dt><tt>noimplicitfloat</tt></dt> -<dd>This attributes disables implicit floating point instructions.</dd> - + <dt><tt>alwaysinline</tt></dt> + <dd>This attribute indicates that the inliner should attempt to inline this + function into callers whenever possible, ignoring any active inlining size + threshold for this caller.</dd> + + <dt><tt>inlinehint</tt></dt> + <dd>This attribute indicates that the source code contained a hint that inlining + this function is desirable (such as the "inline" keyword in C/C++). It + is just a hint; it imposes no requirements on the inliner.</dd> + + <dt><tt>noinline</tt></dt> + <dd>This attribute indicates that the inliner should never inline this + function in any situation. This attribute may not be used together with + the <tt>alwaysinline</tt> attribute.</dd> + + <dt><tt>optsize</tt></dt> + <dd>This attribute suggests that optimization passes and code generator passes + make choices that keep the code size of this function low, and otherwise + do optimizations specifically to reduce code size.</dd> + + <dt><tt>noreturn</tt></dt> + <dd>This function attribute indicates that the function never returns + normally. This produces undefined behavior at runtime if the function + ever does dynamically return.</dd> + + <dt><tt>nounwind</tt></dt> + <dd>This function attribute indicates that the function never returns with an + unwind or exceptional control flow. If the function does unwind, its + runtime behavior is undefined.</dd> + + <dt><tt>readnone</tt></dt> + <dd>This attribute indicates that the function computes its result (or decides + to unwind an exception) based strictly on its arguments, without + dereferencing any pointer arguments or otherwise accessing any mutable + state (e.g. memory, control registers, etc) visible to caller functions. + It does not write through any pointer arguments + (including <tt><a href="#byval">byval</a></tt> arguments) and never + changes any state visible to callers. This means that it cannot unwind + exceptions by calling the <tt>C++</tt> exception throwing methods, but + could use the <tt>unwind</tt> instruction.</dd> + + <dt><tt><a name="readonly">readonly</a></tt></dt> + <dd>This attribute indicates that the function does not write through any + pointer arguments (including <tt><a href="#byval">byval</a></tt> + arguments) or otherwise modify any state (e.g. memory, control registers, + etc) visible to caller functions. It may dereference pointer arguments + and read state that may be set in the caller. A readonly function always + returns the same value (or unwinds an exception identically) when called + with the same set of arguments and global state. It cannot unwind an + exception by calling the <tt>C++</tt> exception throwing methods, but may + use the <tt>unwind</tt> instruction.</dd> + + <dt><tt><a name="ssp">ssp</a></tt></dt> + <dd>This attribute indicates that the function should emit a stack smashing + protector. It is in the form of a "canary"—a random value placed on + the stack before the local variables that's checked upon return from the + function to see if it has been overwritten. A heuristic is used to + determine if a function needs stack protectors or not.<br> +<br> + If a function that has an <tt>ssp</tt> attribute is inlined into a + function that doesn't have an <tt>ssp</tt> attribute, then the resulting + function will have an <tt>ssp</tt> attribute.</dd> + + <dt><tt>sspreq</tt></dt> + <dd>This attribute indicates that the function should <em>always</em> emit a + stack smashing protector. This overrides + the <tt><a href="#ssp">ssp</a></tt> function attribute.<br> +<br> + If a function that has an <tt>sspreq</tt> attribute is inlined into a + function that doesn't have an <tt>sspreq</tt> attribute or which has + an <tt>ssp</tt> attribute, then the resulting function will have + an <tt>sspreq</tt> attribute.</dd> + + <dt><tt>noredzone</tt></dt> + <dd>This attribute indicates that the code generator should not use a red + zone, even if the target-specific ABI normally permits it.</dd> + + <dt><tt>noimplicitfloat</tt></dt> + <dd>This attributes disables implicit floating point instructions.</dd> + + <dt><tt>naked</tt></dt> + <dd>This attribute disables prologue / epilogue emission for the function. + This can have very system-specific consequences.</dd> </dl> </div> @@ -1123,12 +1138,11 @@ red zone, even if the target-specific ABI normally permits it. </div> <div class="doc_text"> -<p> -Modules may contain "module-level inline asm" blocks, which corresponds to the -GCC "file scope inline asm" blocks. These blocks are internally concatenated by -LLVM and treated as a single unit, but may be separated in the .ll file if -desired. The syntax is very simple: -</p> + +<p>Modules may contain "module-level inline asm" blocks, which corresponds to + the GCC "file scope inline asm" blocks. These blocks are internally + concatenated by LLVM and treated as a single unit, but may be separated in + the <tt>.ll</tt> file if desired. The syntax is very simple:</p> <div class="doc_code"> <pre> @@ -1139,13 +1153,11 @@ module asm "more can go here" <p>The strings can contain any character by escaping non-printable characters. The escape sequence used is simply "\xx" where "xx" is the two digit hex code - for the number. -</p> + for the number.</p> + +<p>The inline asm code is simply printed to the machine code .s file when + assembly code is generated.</p> -<p> - The inline asm code is simply printed to the machine code .s file when - assembly code is generated. -</p> </div> <!-- ======================================================================= --> @@ -1154,46 +1166,65 @@ module asm "more can go here" </div> <div class="doc_text"> + <p>A module may specify a target specific data layout string that specifies how -data is to be laid out in memory. The syntax for the data layout is simply:</p> -<pre> target datalayout = "<i>layout specification</i>"</pre> -<p>The <i>layout specification</i> consists of a list of specifications -separated by the minus sign character ('-'). Each specification starts with a -letter and may include other information after the letter to define some -aspect of the data layout. The specifications accepted are as follows: </p> + data is to be laid out in memory. The syntax for the data layout is + simply:</p> + +<div class="doc_code"> +<pre> +target datalayout = "<i>layout specification</i>" +</pre> +</div> + +<p>The <i>layout specification</i> consists of a list of specifications + separated by the minus sign character ('-'). Each specification starts with + a letter and may include other information after the letter to define some + aspect of the data layout. The specifications accepted are as follows:</p> + <dl> <dt><tt>E</tt></dt> <dd>Specifies that the target lays out data in big-endian form. That is, the - bits with the most significance have the lowest address location.</dd> + bits with the most significance have the lowest address location.</dd> + <dt><tt>e</tt></dt> <dd>Specifies that the target lays out data in little-endian form. That is, - the bits with the least significance have the lowest address location.</dd> + the bits with the least significance have the lowest address + location.</dd> + <dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and - <i>preferred</i> alignments. All sizes are in bits. Specifying the <i>pref</i> - alignment is optional. If omitted, the preceding <tt>:</tt> should be omitted - too.</dd> + <i>preferred</i> alignments. All sizes are in bits. Specifying + the <i>pref</i> alignment is optional. If omitted, the + preceding <tt>:</tt> should be omitted too.</dd> + <dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the alignment for an integer type of a given bit - <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd> + <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd> + <dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the alignment for a vector type of a given bit - <i>size</i>.</dd> + <i>size</i>.</dd> + <dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the alignment for a floating point type of a given bit - <i>size</i>. The value of <i>size</i> must be either 32 (float) or 64 - (double).</dd> + <i>size</i>. The value of <i>size</i> must be either 32 (float) or 64 + (double).</dd> + <dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the alignment for an aggregate type of a given bit - <i>size</i>.</dd> + <i>size</i>.</dd> + <dt><tt>s<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the alignment for a stack object of a given bit - <i>size</i>.</dd> + <i>size</i>.</dd> </dl> + <p>When constructing the data layout for a given target, LLVM starts with a -default set of specifications which are then (possibly) overriden by the -specifications in the <tt>datalayout</tt> keyword. The default specifications -are given in this list:</p> + default set of specifications which are then (possibly) overriden by the + specifications in the <tt>datalayout</tt> keyword. The default specifications + are given in this list:</p> + <ul> <li><tt>E</tt> - big endian</li> <li><tt>p:32:64:64</tt> - 32-bit pointers with 64-bit alignment</li> @@ -1210,22 +1241,80 @@ are given in this list:</p> <li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li> <li><tt>s0:64:64</tt> - stack objects are 64-bit aligned</li> </ul> -<p>When LLVM is determining the alignment for a given type, it uses the -following rules:</p> + +<p>When LLVM is determining the alignment for a given type, it uses the + following rules:</p> + <ol> <li>If the type sought is an exact match for one of the specifications, that - specification is used.</li> + specification is used.</li> + <li>If no match is found, and the type sought is an integer type, then the - smallest integer type that is larger than the bitwidth of the sought type is - used. If none of the specifications are larger than the bitwidth then the the - largest integer type is used. For example, given the default specifications - above, the i7 type will use the alignment of i8 (next largest) while both - i65 and i256 will use the alignment of i64 (largest specified).</li> + smallest integer type that is larger than the bitwidth of the sought type + is used. If none of the specifications are larger than the bitwidth then + the the largest integer type is used. For example, given the default + specifications above, the i7 type will use the alignment of i8 (next + largest) while both i65 and i256 will use the alignment of i64 (largest + specified).</li> + <li>If no match is found, and the type sought is a vector type, then the - largest vector type that is smaller than the sought vector type will be used - as a fall back. This happens because <128 x double> can be implemented - in terms of 64 <2 x double>, for example.</li> + largest vector type that is smaller than the sought vector type will be + used as a fall back. This happens because <128 x double> can be + implemented in terms of 64 <2 x double>, for example.</li> </ol> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="pointeraliasing">Pointer Aliasing Rules</a> +</div> + +<div class="doc_text"> + +<p>Any memory access must be done through a pointer value associated +with an address range of the memory access, otherwise the behavior +is undefined. Pointer values are associated with address ranges +according to the following rules:</p> + +<ul> + <li>A pointer value formed from a + <tt><a href="#i_getelementptr">getelementptr</a></tt> instruction + is associated with the addresses associated with the first operand + of the <tt>getelementptr</tt>.</li> + <li>An address of a global variable is associated with the address + range of the variable's storage.</li> + <li>The result value of an allocation instruction is associated with + the address range of the allocated storage.</li> + <li>A null pointer in the default address-space is associated with + no address.</li> + <li>A pointer value formed by an + <tt><a href="#i_inttoptr">inttoptr</a></tt> is associated with all + address ranges of all pointer values that contribute (directly or + indirectly) to the computation of the pointer's value.</li> + <li>The result value of a + <tt><a href="#i_bitcast">bitcast</a></tt> is associated with all + addresses associated with the operand of the <tt>bitcast</tt>.</li> + <li>An integer constant other than zero or a pointer value returned + from a function not defined within LLVM may be associated with address + ranges allocated through mechanisms other than those provided by + LLVM. Such ranges shall not overlap with any ranges of addresses + allocated by mechanisms provided by LLVM.</li> + </ul> + +<p>LLVM IR does not associate types with memory. The result type of a +<tt><a href="#i_load">load</a></tt> merely indicates the size and +alignment of the memory from which to load, as well as the +interpretation of the value. The first operand of a +<tt><a href="#i_store">store</a></tt> similarly only indicates the size +and alignment of the store.</p> + +<p>Consequently, type-based alias analysis, aka TBAA, aka +<tt>-fstrict-aliasing</tt>, is not applicable to general unadorned +LLVM IR. <a href="#metadata">Metadata</a> may be used to encode +additional information which specialized optimization passes may use +to implement type-based alias analysis.</p> + </div> <!-- *********************************************************************** --> @@ -1235,22 +1324,22 @@ following rules:</p> <div class="doc_text"> <p>The LLVM type system is one of the most important features of the -intermediate representation. Being typed enables a number of -optimizations to be performed on the intermediate representation directly, -without having to do -extra analyses on the side before the transformation. A strong type -system makes it easier to read the generated code and enables novel -analyses and transformations that are not feasible to perform on normal -three address code representations.</p> + intermediate representation. Being typed enables a number of optimizations + to be performed on the intermediate representation directly, without having + to do extra analyses on the side before the transformation. A strong type + system makes it easier to read the generated code and enables novel analyses + and transformations that are not feasible to perform on normal three address + code representations.</p> </div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="t_classifications">Type Classifications</a> </div> + <div class="doc_text"> -<p>The types fall into a few useful -classifications:</p> + +<p>The types fall into a few useful classifications:</p> <table border="1" cellspacing="0" cellpadding="4"> <tbody> @@ -1297,18 +1386,60 @@ classifications:</p> </tbody> </table> -<p>The <a href="#t_firstclass">first class</a> types are perhaps the -most important. Values of these types are the only ones which can be -produced by instructions, passed as arguments, or used as operands to -instructions.</p> +<p>The <a href="#t_firstclass">first class</a> types are perhaps the most + important. Values of these types are the only ones which can be produced by + instructions.</p> + </div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div> <div class="doc_text"> + <p>The primitive types are the fundamental building blocks of the LLVM -system.</p> + system.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div> + +<div class="doc_text"> + +<h5>Overview:</h5> +<p>The integer type is a very simple type that simply specifies an arbitrary + bit width for the integer type desired. Any bit width from 1 bit to + 2<sup>23</sup>-1 (about 8 million) can be specified.</p> + +<h5>Syntax:</h5> +<pre> + iN +</pre> + +<p>The number of bits the integer will occupy is specified by the <tt>N</tt> + value.</p> + +<h5>Examples:</h5> +<table class="layout"> + <tr class="layout"> + <td class="left"><tt>i1</tt></td> + <td class="left">a single-bit integer.</td> + </tr> + <tr class="layout"> + <td class="left"><tt>i32</tt></td> + <td class="left">a 32-bit integer.</td> + </tr> + <tr class="layout"> + <td class="left"><tt>i1942652</tt></td> + <td class="left">a really big integer of over 1 million bits.</td> + </tr> +</table> + +<p>Note that the code generator does not yet support large integer types to be + used as function return types. The specific limit on how large a return type + the code generator can currently handle is target-dependent; currently it's + often 64 bits for 32-bit targets and 128 bits for 64-bit targets.</p> </div> @@ -1316,60 +1447,65 @@ system.</p> <div class="doc_subsubsection"> <a name="t_floating">Floating Point Types</a> </div> <div class="doc_text"> - <table> - <tbody> - <tr><th>Type</th><th>Description</th></tr> - <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr> - <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr> - <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr> - <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr> - <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr> - </tbody> - </table> + +<table> + <tbody> + <tr><th>Type</th><th>Description</th></tr> + <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr> + <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr> + <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr> + <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr> + <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr> + </tbody> +</table> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_void">Void Type</a> </div> <div class="doc_text"> + <h5>Overview:</h5> <p>The void type does not represent any value and has no size.</p> <h5>Syntax:</h5> - <pre> void </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_label">Label Type</a> </div> <div class="doc_text"> + <h5>Overview:</h5> <p>The label type represents code labels.</p> <h5>Syntax:</h5> - <pre> label </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_metadata">Metadata Type</a> </div> <div class="doc_text"> + <h5>Overview:</h5> -<p>The metadata type represents embedded metadata. The only derived type that -may contain metadata is <tt>metadata*</tt> or a function type that returns or -takes metadata typed parameters, but not pointer to metadata types.</p> +<p>The metadata type represents embedded metadata. No derived types may be + created from metadata except for <a href="#t_function">function</a> + arguments. <h5>Syntax:</h5> - <pre> metadata </pre> + </div> @@ -1378,53 +1514,12 @@ takes metadata typed parameters, but not pointer to metadata types.</p> <div class="doc_text"> -<p>The real power in LLVM comes from the derived types in the system. -This is what allows a programmer to represent arrays, functions, -pointers, and other useful types. Note that these derived types may be -recursive: For example, it is possible to have a two dimensional array.</p> - -</div> - -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div> - -<div class="doc_text"> - -<h5>Overview:</h5> -<p>The integer type is a very simple derived type that simply specifies an -arbitrary bit width for the integer type desired. Any bit width from 1 bit to -2^23-1 (about 8 million) can be specified.</p> - -<h5>Syntax:</h5> - -<pre> - iN -</pre> - -<p>The number of bits the integer will occupy is specified by the <tt>N</tt> -value.</p> - -<h5>Examples:</h5> -<table class="layout"> - <tr class="layout"> - <td class="left"><tt>i1</tt></td> - <td class="left">a single-bit integer.</td> - </tr> - <tr class="layout"> - <td class="left"><tt>i32</tt></td> - <td class="left">a 32-bit integer.</td> - </tr> - <tr class="layout"> - <td class="left"><tt>i1942652</tt></td> - <td class="left">a really big integer of over 1 million bits.</td> - </tr> -</table> - -<p>Note that the code generator does not yet support large integer types -to be used as function return types. The specific limit on how large a -return type the code generator can currently handle is target-dependent; -currently it's often 64 bits for 32-bit targets and 128 bits for 64-bit -targets.</p> +<p>The real power in LLVM comes from the derived types in the system. This is + what allows a programmer to represent arrays, functions, pointers, and other + useful types. Each of these types contain one or more element types which + may be a primitive type, or another derived type. For example, it is + possible to have a two dimensional array, using an array as the element type + of another array.</p> </div> @@ -1434,19 +1529,17 @@ targets.</p> <div class="doc_text"> <h5>Overview:</h5> - <p>The array type is a very simple derived type that arranges elements -sequentially in memory. The array type requires a size (number of -elements) and an underlying data type.</p> + sequentially in memory. The array type requires a size (number of elements) + and an underlying data type.</p> <h5>Syntax:</h5> - <pre> [<# elements> x <elementtype>] </pre> -<p>The number of elements is a constant integer value; elementtype may -be any type with a size.</p> +<p>The number of elements is a constant integer value; <tt>elementtype</tt> may + be any type with a size.</p> <h5>Examples:</h5> <table class="layout"> @@ -1479,45 +1572,44 @@ be any type with a size.</p> </tr> </table> -<p>Note that 'variable sized arrays' can be implemented in LLVM with a zero -length array. Normally, accesses past the end of an array are undefined in -LLVM (e.g. it is illegal to access the 5th element of a 3 element array). -As a special case, however, zero length arrays are recognized to be variable -length. This allows implementation of 'pascal style arrays' with the LLVM -type "{ i32, [0 x float]}", for example.</p> +<p>Note that 'variable sized arrays' can be implemented in LLVM with a zero + length array. Normally, accesses past the end of an array are undefined in + LLVM (e.g. it is illegal to access the 5th element of a 3 element array). As + a special case, however, zero length arrays are recognized to be variable + length. This allows implementation of 'pascal style arrays' with the LLVM + type "<tt>{ i32, [0 x float]}</tt>", for example.</p> -<p>Note that the code generator does not yet support large aggregate types -to be used as function return types. The specific limit on how large an -aggregate return type the code generator can currently handle is -target-dependent, and also dependent on the aggregate element types.</p> +<p>Note that the code generator does not yet support large aggregate types to be + used as function return types. The specific limit on how large an aggregate + return type the code generator can currently handle is target-dependent, and + also dependent on the aggregate element types.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_function">Function Type</a> </div> + <div class="doc_text"> <h5>Overview:</h5> - -<p>The function type can be thought of as a function signature. It -consists of a return type and a list of formal parameter types. The -return type of a function type is a scalar type, a void type, or a struct type. -If the return type is a struct type then all struct elements must be of first -class types, and the struct must have at least one element.</p> +<p>The function type can be thought of as a function signature. It consists of + a return type and a list of formal parameter types. The return type of a + function type is a scalar type, a void type, or a struct type. If the return + type is a struct type then all struct elements must be of first class types, + and the struct must have at least one element.</p> <h5>Syntax:</h5> - <pre> - <returntype list> (<parameter list>) + <returntype> (<parameter list>) </pre> <p>...where '<tt><parameter list></tt>' is a comma-separated list of type -specifiers. Optionally, the parameter list may include a type <tt>...</tt>, -which indicates that the function takes a variable number of arguments. -Variable argument functions can access their arguments with the <a - href="#int_varargs">variable argument handling intrinsic</a> functions. -'<tt><returntype list></tt>' is a comma-separated list of -<a href="#t_firstclass">first class</a> type specifiers.</p> + specifiers. Optionally, the parameter list may include a type <tt>...</tt>, + which indicates that the function takes a variable number of arguments. + Variable argument functions can access their arguments with + the <a href="#int_varargs">variable argument handling intrinsic</a> + functions. '<tt><returntype></tt>' is a any type except + <a href="#t_label">label</a>.</p> <h5>Examples:</h5> <table class="layout"> @@ -1542,27 +1634,34 @@ Variable argument functions can access their arguments with the <a </td> </tr><tr class="layout"> <td class="left"><tt>{i32, i32} (i32)</tt></td> - <td class="left">A function taking an <tt>i32</tt>, returning two - <tt>i32</tt> values as an aggregate of type <tt>{ i32, i32 }</tt> + <td class="left">A function taking an <tt>i32</tt>, returning a + <a href="#t_struct">structure</a> containing two <tt>i32</tt> values </td> </tr> </table> </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_struct">Structure Type</a> </div> + <div class="doc_text"> + <h5>Overview:</h5> -<p>The structure type is used to represent a collection of data members -together in memory. The packing of the field types is defined to match -the ABI of the underlying processor. The elements of a structure may -be any type that has a size.</p> -<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> -and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a -field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' -instruction.</p> +<p>The structure type is used to represent a collection of data members together + in memory. The packing of the field types is defined to match the ABI of the + underlying processor. The elements of a structure may be any type that has a + size.</p> + +<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and + '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with + the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p> + <h5>Syntax:</h5> -<pre> { <type list> }<br></pre> +<pre> + { <type list> } +</pre> + <h5>Examples:</h5> <table class="layout"> <tr class="layout"> @@ -1577,28 +1676,34 @@ instruction.</p> </tr> </table> -<p>Note that the code generator does not yet support large aggregate types -to be used as function return types. The specific limit on how large an -aggregate return type the code generator can currently handle is -target-dependent, and also dependent on the aggregate element types.</p> +<p>Note that the code generator does not yet support large aggregate types to be + used as function return types. The specific limit on how large an aggregate + return type the code generator can currently handle is target-dependent, and + also dependent on the aggregate element types.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_pstruct">Packed Structure Type</a> </div> + <div class="doc_text"> + <h5>Overview:</h5> <p>The packed structure type is used to represent a collection of data members -together in memory. There is no padding between fields. Further, the alignment -of a packed structure is 1 byte. The elements of a packed structure may -be any type that has a size.</p> -<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> -and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a -field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' -instruction.</p> + together in memory. There is no padding between fields. Further, the + alignment of a packed structure is 1 byte. The elements of a packed + structure may be any type that has a size.</p> + +<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and + '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with + the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p> + <h5>Syntax:</h5> -<pre> < { <type list> } > <br></pre> +<pre> + < { <type list> } > +</pre> + <h5>Examples:</h5> <table class="layout"> <tr class="layout"> @@ -1613,23 +1718,28 @@ instruction.</p> an <tt>i32</tt>.</td> </tr> </table> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div> + <div class="doc_text"> + <h5>Overview:</h5> -<p>As in many languages, the pointer type represents a pointer or -reference to another object, which must live in memory. Pointer types may have -an optional address space attribute defining the target-specific numbered -address space where the pointed-to object resides. The default address space is -zero.</p> +<p>As in many languages, the pointer type represents a pointer or reference to + another object, which must live in memory. Pointer types may have an optional + address space attribute defining the target-specific numbered address space + where the pointed-to object resides. The default address space is zero.</p> -<p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does -it permit pointers to labels (<tt>label*</tt>). Use <tt>i8*</tt> instead.</p> +<p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does it + permit pointers to labels (<tt>label*</tt>). Use <tt>i8*</tt> instead.</p> <h5>Syntax:</h5> -<pre> <type> *<br></pre> +<pre> + <type> * +</pre> + <h5>Examples:</h5> <table class="layout"> <tr class="layout"> @@ -1649,33 +1759,31 @@ it permit pointers to labels (<tt>label*</tt>). Use <tt>i8*</tt> instead.</p> that resides in address space #5.</td> </tr> </table> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_vector">Vector Type</a> </div> + <div class="doc_text"> <h5>Overview:</h5> - -<p>A vector type is a simple derived type that represents a vector -of elements. Vector types are used when multiple primitive data -are operated in parallel using a single instruction (SIMD). -A vector type requires a size (number of -elements) and an underlying primitive data type. Vectors must have a power -of two length (1, 2, 4, 8, 16 ...). Vector types are -considered <a href="#t_firstclass">first class</a>.</p> +<p>A vector type is a simple derived type that represents a vector of elements. + Vector types are used when multiple primitive data are operated in parallel + using a single instruction (SIMD). A vector type requires a size (number of + elements) and an underlying primitive data type. Vectors must have a power + of two length (1, 2, 4, 8, 16 ...). Vector types are considered + <a href="#t_firstclass">first class</a>.</p> <h5>Syntax:</h5> - <pre> < <# elements> x <elementtype> > </pre> -<p>The number of elements is a constant integer value; elementtype may -be any integer or floating point type.</p> +<p>The number of elements is a constant integer value; elementtype may be any + integer or floating point type.</p> <h5>Examples:</h5> - <table class="layout"> <tr class="layout"> <td class="left"><tt><4 x i32></tt></td> @@ -1691,10 +1799,10 @@ be any integer or floating point type.</p> </tr> </table> -<p>Note that the code generator does not yet support large vector types -to be used as function return types. The specific limit on how large a -vector return type codegen can currently handle is target-dependent; -currently it's often a few times longer than a hardware vector register.</p> +<p>Note that the code generator does not yet support large vector types to be + used as function return types. The specific limit on how large a vector + return type codegen can currently handle is target-dependent; currently it's + often a few times longer than a hardware vector register.</p> </div> @@ -1703,26 +1811,24 @@ currently it's often a few times longer than a hardware vector register.</p> <div class="doc_text"> <h5>Overview:</h5> - <p>Opaque types are used to represent unknown types in the system. This -corresponds (for example) to the C notion of a forward declared structure type. -In LLVM, opaque types can eventually be resolved to any type (not just a -structure type).</p> + corresponds (for example) to the C notion of a forward declared structure + type. In LLVM, opaque types can eventually be resolved to any type (not just + a structure type).</p> <h5>Syntax:</h5> - <pre> opaque </pre> <h5>Examples:</h5> - <table class="layout"> <tr class="layout"> <td class="left"><tt>opaque</tt></td> <td class="left">An opaque type.</td> </tr> </table> + </div> <!-- ======================================================================= --> @@ -1731,12 +1837,13 @@ structure type).</p> </div> <div class="doc_text"> + <h5>Overview:</h5> -<p> -An "up reference" allows you to refer to a lexically enclosing type without -requiring it to have a name. For instance, a structure declaration may contain a -pointer to any of the types it is lexically a member of. Example of up -references (with their equivalent as named type declarations) include:</p> +<p>An "up reference" allows you to refer to a lexically enclosing type without + requiring it to have a name. For instance, a structure declaration may + contain a pointer to any of the types it is lexically a member of. Example + of up references (with their equivalent as named type declarations) + include:</p> <pre> { \2 * } %x = type { %x* } @@ -1744,24 +1851,20 @@ references (with their equivalent as named type declarations) include:</p> \1* %z = type %z* </pre> -<p> -An up reference is needed by the asmprinter for printing out cyclic types when -there is no declared name for a type in the cycle. Because the asmprinter does -not want to print out an infinite type string, it needs a syntax to handle -recursive types that have no names (all names are optional in llvm IR). -</p> +<p>An up reference is needed by the asmprinter for printing out cyclic types + when there is no declared name for a type in the cycle. Because the + asmprinter does not want to print out an infinite type string, it needs a + syntax to handle recursive types that have no names (all names are optional + in llvm IR).</p> <h5>Syntax:</h5> <pre> \<level> </pre> -<p> -The level is the count of the lexical type that is being referred to. -</p> +<p>The level is the count of the lexical type that is being referred to.</p> <h5>Examples:</h5> - <table class="layout"> <tr class="layout"> <td class="left"><tt>\1*</tt></td> @@ -1773,8 +1876,8 @@ The level is the count of the lexical type that is being referred to. structure.</td> </tr> </table> -</div> +</div> <!-- *********************************************************************** --> <div class="doc_section"> <a name="constants">Constants</a> </div> @@ -1783,7 +1886,7 @@ The level is the count of the lexical type that is being referred to. <div class="doc_text"> <p>LLVM has several different basic types of constants. This section describes -them all and their syntax.</p> + them all and their syntax.</p> </div> @@ -1794,118 +1897,103 @@ them all and their syntax.</p> <dl> <dt><b>Boolean constants</b></dt> - <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid - constants of the <tt><a href="#t_primitive">i1</a></tt> type. - </dd> + constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd> <dt><b>Integer constants</b></dt> - - <dd>Standard integers (such as '4') are constants of the <a - href="#t_integer">integer</a> type. Negative numbers may be used with - integer types. - </dd> + <dd>Standard integers (such as '4') are constants of + the <a href="#t_integer">integer</a> type. Negative numbers may be used + with integer types.</dd> <dt><b>Floating point constants</b></dt> - <dd>Floating point constants use standard decimal notation (e.g. 123.421), - exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal - notation (see below). The assembler requires the exact decimal value of - a floating-point constant. For example, the assembler accepts 1.25 but - rejects 1.3 because 1.3 is a repeating decimal in binary. Floating point - constants must have a <a href="#t_floating">floating point</a> type. </dd> + exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal + notation (see below). The assembler requires the exact decimal value of a + floating-point constant. For example, the assembler accepts 1.25 but + rejects 1.3 because 1.3 is a repeating decimal in binary. Floating point + constants must have a <a href="#t_floating">floating point</a> type. </dd> <dt><b>Null pointer constants</b></dt> - <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant - and must be of <a href="#t_pointer">pointer type</a>.</dd> - + and must be of <a href="#t_pointer">pointer type</a>.</dd> </dl> -<p>The one non-intuitive notation for constants is the hexadecimal form -of floating point constants. For example, the form '<tt>double -0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double -4.5e+15</tt>'. The only time hexadecimal floating point constants are required -(and the only time that they are generated by the disassembler) is when a -floating point constant must be emitted but it cannot be represented as a -decimal floating point number in a reasonable number of digits. For example, -NaN's, infinities, and other -special values are represented in their IEEE hexadecimal format so that -assembly and disassembly do not cause any bits to change in the constants.</p> +<p>The one non-intuitive notation for constants is the hexadecimal form of + floating point constants. For example, the form '<tt>double + 0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) + '<tt>double 4.5e+15</tt>'. The only time hexadecimal floating point + constants are required (and the only time that they are generated by the + disassembler) is when a floating point constant must be emitted but it cannot + be represented as a decimal floating point number in a reasonable number of + digits. For example, NaN's, infinities, and other special values are + represented in their IEEE hexadecimal format so that assembly and disassembly + do not cause any bits to change in the constants.</p> + <p>When using the hexadecimal form, constants of types float and double are -represented using the 16-digit form shown above (which matches the IEEE754 -representation for double); float values must, however, be exactly representable -as IEE754 single precision. -Hexadecimal format is always used for long -double, and there are three forms of long double. The 80-bit -format used by x86 is represented as <tt>0xK</tt> -followed by 20 hexadecimal digits. -The 128-bit format used by PowerPC (two adjacent doubles) is represented -by <tt>0xM</tt> followed by 32 hexadecimal digits. The IEEE 128-bit -format is represented -by <tt>0xL</tt> followed by 32 hexadecimal digits; no currently supported -target uses this format. Long doubles will only work if they match -the long double format on your target. All hexadecimal formats are big-endian -(sign bit at the left).</p> + represented using the 16-digit form shown above (which matches the IEEE754 + representation for double); float values must, however, be exactly + representable as IEE754 single precision. Hexadecimal format is always used + for long double, and there are three forms of long double. The 80-bit format + used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits. + The 128-bit format used by PowerPC (two adjacent doubles) is represented + by <tt>0xM</tt> followed by 32 hexadecimal digits. The IEEE 128-bit format + is represented by <tt>0xL</tt> followed by 32 hexadecimal digits; no + currently supported target uses this format. Long doubles will only work if + they match the long double format on your target. All hexadecimal formats + are big-endian (sign bit at the left).</p> + </div> <!-- ======================================================================= --> <div class="doc_subsection"> -<a name="aggregateconstants"> <!-- old anchor --> -<a name="complexconstants">Complex Constants</a></a> +<a name="aggregateconstants"></a> <!-- old anchor --> +<a name="complexconstants">Complex Constants</a> </div> <div class="doc_text"> + <p>Complex constants are a (potentially recursive) combination of simple -constants and smaller complex constants.</p> + constants and smaller complex constants.</p> <dl> <dt><b>Structure constants</b></dt> - <dd>Structure constants are represented with notation similar to structure - type definitions (a comma separated list of elements, surrounded by braces - (<tt>{}</tt>)). For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>", - where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>". Structure constants - must have <a href="#t_struct">structure type</a>, and the number and - types of elements must match those specified by the type. - </dd> + type definitions (a comma separated list of elements, surrounded by braces + (<tt>{}</tt>)). For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>", + where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>". + Structure constants must have <a href="#t_struct">structure type</a>, and + the number and types of elements must match those specified by the + type.</dd> <dt><b>Array constants</b></dt> - <dd>Array constants are represented with notation similar to array type - definitions (a comma separated list of elements, surrounded by square brackets - (<tt>[]</tt>)). For example: "<tt>[ i32 42, i32 11, i32 74 ]</tt>". Array - constants must have <a href="#t_array">array type</a>, and the number and - types of elements must match those specified by the type. - </dd> + definitions (a comma separated list of elements, surrounded by square + brackets (<tt>[]</tt>)). For example: "<tt>[ i32 42, i32 11, i32 74 + ]</tt>". Array constants must have <a href="#t_array">array type</a>, and + the number and types of elements must match those specified by the + type.</dd> <dt><b>Vector constants</b></dt> - <dd>Vector constants are represented with notation similar to vector type - definitions (a comma separated list of elements, surrounded by - less-than/greater-than's (<tt><></tt>)). For example: "<tt>< i32 42, - i32 11, i32 74, i32 100 ></tt>". Vector constants must have <a - href="#t_vector">vector type</a>, and the number and types of elements must - match those specified by the type. - </dd> + definitions (a comma separated list of elements, surrounded by + less-than/greater-than's (<tt><></tt>)). For example: "<tt>< i32 + 42, i32 11, i32 74, i32 100 ></tt>". Vector constants must + have <a href="#t_vector">vector type</a>, and the number and types of + elements must match those specified by the type.</dd> <dt><b>Zero initialization</b></dt> - <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a - value to zero of <em>any</em> type, including scalar and aggregate types. - This is often used to avoid having to print large zero initializers (e.g. for - large arrays) and is always exactly equivalent to using explicit zero - initializers. - </dd> + value to zero of <em>any</em> type, including scalar and aggregate types. + This is often used to avoid having to print large zero initializers + (e.g. for large arrays) and is always exactly equivalent to using explicit + zero initializers.</dd> <dt><b>Metadata node</b></dt> - <dd>A metadata node is a structure-like constant with - <a href="#t_metadata">metadata type</a>. For example: - "<tt>metadata !{ i32 0, metadata !"test" }</tt>". Unlike other constants - that are meant to be interpreted as part of the instruction stream, metadata - is a place to attach additional information such as debug info. - </dd> + <a href="#t_metadata">metadata type</a>. For example: "<tt>metadata !{ + i32 0, metadata !"test" }</tt>". Unlike other constants that are meant to + be interpreted as part of the instruction stream, metadata is a place to + attach additional information such as debug info.</dd> </dl> </div> @@ -1917,12 +2005,12 @@ constants and smaller complex constants.</p> <div class="doc_text"> -<p>The addresses of <a href="#globalvars">global variables</a> and <a -href="#functionstructure">functions</a> are always implicitly valid (link-time) -constants. These constants are explicitly referenced when the <a -href="#identifiers">identifier for the global</a> is used and always have <a -href="#t_pointer">pointer</a> type. For example, the following is a legal LLVM -file:</p> +<p>The addresses of <a href="#globalvars">global variables</a> + and <a href="#functionstructure">functions</a> are always implicitly valid + (link-time) constants. These constants are explicitly referenced when + the <a href="#identifiers">identifier for the global</a> is used and always + have <a href="#t_pointer">pointer</a> type. For example, the following is a + legal LLVM file:</p> <div class="doc_code"> <pre> @@ -1937,13 +2025,150 @@ file:</p> <!-- ======================================================================= --> <div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div> <div class="doc_text"> - <p>The string '<tt>undef</tt>' is recognized as a type-less constant that has - no specific value. Undefined values may be of any type and be used anywhere - a constant is permitted.</p> - <p>Undefined values indicate to the compiler that the program is well defined - no matter what value is used, giving the compiler more freedom to optimize. - </p> +<p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and + indicates that the user of the value may receive an unspecified bit-pattern. + Undefined values may be of any type (other than label or void) and be used + anywhere a constant is permitted.</p> + +<p>Undefined values are useful because they indicate to the compiler that the + program is well defined no matter what value is used. This gives the + compiler more freedom to optimize. Here are some examples of (potentially + surprising) transformations that are valid (in pseudo IR):</p> + + +<div class="doc_code"> +<pre> + %A = add %X, undef + %B = sub %X, undef + %C = xor %X, undef +Safe: + %A = undef + %B = undef + %C = undef +</pre> +</div> + +<p>This is safe because all of the output bits are affected by the undef bits. +Any output bit can have a zero or one depending on the input bits.</p> + +<div class="doc_code"> +<pre> + %A = or %X, undef + %B = and %X, undef +Safe: + %A = -1 + %B = 0 +Unsafe: + %A = undef + %B = undef +</pre> +</div> + +<p>These logical operations have bits that are not always affected by the input. +For example, if "%X" has a zero bit, then the output of the 'and' operation will +always be a zero, no matter what the corresponding bit from the undef is. As +such, it is unsafe to optimize or assume that the result of the and is undef. +However, it is safe to assume that all bits of the undef could be 0, and +optimize the and to 0. Likewise, it is safe to assume that all the bits of +the undef operand to the or could be set, allowing the or to be folded to +-1.</p> + +<div class="doc_code"> +<pre> + %A = select undef, %X, %Y + %B = select undef, 42, %Y + %C = select %X, %Y, undef +Safe: + %A = %X (or %Y) + %B = 42 (or %Y) + %C = %Y +Unsafe: + %A = undef + %B = undef + %C = undef +</pre> +</div> + +<p>This set of examples show that undefined select (and conditional branch) +conditions can go "either way" but they have to come from one of the two +operands. In the %A example, if %X and %Y were both known to have a clear low +bit, then %A would have to have a cleared low bit. However, in the %C example, +the optimizer is allowed to assume that the undef operand could be the same as +%Y, allowing the whole select to be eliminated.</p> + + +<div class="doc_code"> +<pre> + %A = xor undef, undef + + %B = undef + %C = xor %B, %B + + %D = undef + %E = icmp lt %D, 4 + %F = icmp gte %D, 4 + +Safe: + %A = undef + %B = undef + %C = undef + %D = undef + %E = undef + %F = undef +</pre> +</div> + +<p>This example points out that two undef operands are not necessarily the same. +This can be surprising to people (and also matches C semantics) where they +assume that "X^X" is always zero, even if X is undef. This isn't true for a +number of reasons, but the short answer is that an undef "variable" can +arbitrarily change its value over its "live range". This is true because the +"variable" doesn't actually <em>have a live range</em>. Instead, the value is +logically read from arbitrary registers that happen to be around when needed, +so the value is not necessarily consistent over time. In fact, %A and %C need +to have the same semantics or the core LLVM "replace all uses with" concept +would not hold.</p> + +<div class="doc_code"> +<pre> + %A = fdiv undef, %X + %B = fdiv %X, undef +Safe: + %A = undef +b: unreachable +</pre> +</div> + +<p>These examples show the crucial difference between an <em>undefined +value</em> and <em>undefined behavior</em>. An undefined value (like undef) is +allowed to have an arbitrary bit-pattern. This means that the %A operation +can be constant folded to undef because the undef could be an SNaN, and fdiv is +not (currently) defined on SNaN's. However, in the second example, we can make +a more aggressive assumption: because the undef is allowed to be an arbitrary +value, we are allowed to assume that it could be zero. Since a divide by zero +has <em>undefined behavior</em>, we are allowed to assume that the operation +does not execute at all. This allows us to delete the divide and all code after +it: since the undefined operation "can't happen", the optimizer can assume that +it occurs in dead code. +</p> + +<div class="doc_code"> +<pre> +a: store undef -> %X +b: store %X -> undef +Safe: +a: <deleted> +b: unreachable +</pre> +</div> + +<p>These examples reiterate the fdiv example: a store "of" an undefined value +can be assumed to not have any effect: we can assume that the value is +overwritten with bits that happen to match what was already there. However, a +store "to" an undefined location could clobber arbitrary memory, therefore, it +has undefined behavior.</p> + </div> <!-- ======================================================================= --> @@ -1953,71 +2178,75 @@ file:</p> <div class="doc_text"> <p>Constant expressions are used to allow expressions involving other constants -to be used as constants. Constant expressions may be of any <a -href="#t_firstclass">first class</a> type and may involve any LLVM operation -that does not have side effects (e.g. load and call are not supported). The -following is the syntax for constant expressions:</p> + to be used as constants. Constant expressions may be of + any <a href="#t_firstclass">first class</a> type and may involve any LLVM + operation that does not have side effects (e.g. load and call are not + supported). The following is the syntax for constant expressions:</p> <dl> <dt><b><tt>trunc ( CST to TYPE )</tt></b></dt> - <dd>Truncate a constant to another type. The bit size of CST must be larger - than the bit size of TYPE. Both types must be integers.</dd> + <dd>Truncate a constant to another type. The bit size of CST must be larger + than the bit size of TYPE. Both types must be integers.</dd> <dt><b><tt>zext ( CST to TYPE )</tt></b></dt> - <dd>Zero extend a constant to another type. The bit size of CST must be - smaller or equal to the bit size of TYPE. Both types must be integers.</dd> + <dd>Zero extend a constant to another type. The bit size of CST must be + smaller or equal to the bit size of TYPE. Both types must be + integers.</dd> <dt><b><tt>sext ( CST to TYPE )</tt></b></dt> - <dd>Sign extend a constant to another type. The bit size of CST must be - smaller or equal to the bit size of TYPE. Both types must be integers.</dd> + <dd>Sign extend a constant to another type. The bit size of CST must be + smaller or equal to the bit size of TYPE. Both types must be + integers.</dd> <dt><b><tt>fptrunc ( CST to TYPE )</tt></b></dt> - <dd>Truncate a floating point constant to another floating point type. The - size of CST must be larger than the size of TYPE. Both types must be - floating point.</dd> + <dd>Truncate a floating point constant to another floating point type. The + size of CST must be larger than the size of TYPE. Both types must be + floating point.</dd> <dt><b><tt>fpext ( CST to TYPE )</tt></b></dt> - <dd>Floating point extend a constant to another type. The size of CST must be - smaller or equal to the size of TYPE. Both types must be floating point.</dd> + <dd>Floating point extend a constant to another type. The size of CST must be + smaller or equal to the size of TYPE. Both types must be floating + point.</dd> <dt><b><tt>fptoui ( CST to TYPE )</tt></b></dt> <dd>Convert a floating point constant to the corresponding unsigned integer - constant. TYPE must be a scalar or vector integer type. CST must be of scalar - or vector floating point type. Both CST and TYPE must be scalars, or vectors - of the same number of elements. If the value won't fit in the integer type, - the results are undefined.</dd> + constant. TYPE must be a scalar or vector integer type. CST must be of + scalar or vector floating point type. Both CST and TYPE must be scalars, + or vectors of the same number of elements. If the value won't fit in the + integer type, the results are undefined.</dd> <dt><b><tt>fptosi ( CST to TYPE )</tt></b></dt> <dd>Convert a floating point constant to the corresponding signed integer - constant. TYPE must be a scalar or vector integer type. CST must be of scalar - or vector floating point type. Both CST and TYPE must be scalars, or vectors - of the same number of elements. If the value won't fit in the integer type, - the results are undefined.</dd> + constant. TYPE must be a scalar or vector integer type. CST must be of + scalar or vector floating point type. Both CST and TYPE must be scalars, + or vectors of the same number of elements. If the value won't fit in the + integer type, the results are undefined.</dd> <dt><b><tt>uitofp ( CST to TYPE )</tt></b></dt> <dd>Convert an unsigned integer constant to the corresponding floating point - constant. TYPE must be a scalar or vector floating point type. CST must be of - scalar or vector integer type. Both CST and TYPE must be scalars, or vectors - of the same number of elements. If the value won't fit in the floating point - type, the results are undefined.</dd> + constant. TYPE must be a scalar or vector floating point type. CST must be + of scalar or vector integer type. Both CST and TYPE must be scalars, or + vectors of the same number of elements. If the value won't fit in the + floating point type, the results are undefined.</dd> <dt><b><tt>sitofp ( CST to TYPE )</tt></b></dt> <dd>Convert a signed integer constant to the corresponding floating point - constant. TYPE must be a scalar or vector floating point type. CST must be of - scalar or vector integer type. Both CST and TYPE must be scalars, or vectors - of the same number of elements. If the value won't fit in the floating point - type, the results are undefined.</dd> + constant. TYPE must be a scalar or vector floating point type. CST must be + of scalar or vector integer type. Both CST and TYPE must be scalars, or + vectors of the same number of elements. If the value won't fit in the + floating point type, the results are undefined.</dd> <dt><b><tt>ptrtoint ( CST to TYPE )</tt></b></dt> <dd>Convert a pointer typed constant to the corresponding integer constant - TYPE must be an integer type. CST must be of pointer type. The CST value is - zero extended, truncated, or unchanged to make it fit in TYPE.</dd> + <tt>TYPE</tt> must be an integer type. <tt>CST</tt> must be of pointer + type. The <tt>CST</tt> value is zero extended, truncated, or unchanged to + make it fit in <tt>TYPE</tt>.</dd> <dt><b><tt>inttoptr ( CST to TYPE )</tt></b></dt> - <dd>Convert a integer constant to a pointer constant. TYPE must be a - pointer type. CST must be of integer type. The CST value is zero extended, - truncated, or unchanged to make it fit in a pointer size. This one is - <i>really</i> dangerous!</dd> + <dd>Convert a integer constant to a pointer constant. TYPE must be a pointer + type. CST must be of integer type. The CST value is zero extended, + truncated, or unchanged to make it fit in a pointer size. This one is + <i>really</i> dangerous!</dd> <dt><b><tt>bitcast ( CST to TYPE )</tt></b></dt> <dd>Convert a constant, CST, to another TYPE. The constraints of the operands @@ -2025,16 +2254,14 @@ following is the syntax for constant expressions:</p> instruction</a>.</dd> <dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt> - + <dt><b><tt>getelementptr inbounds ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt> <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on - constants. As with the <a href="#i_getelementptr">getelementptr</a> - instruction, the index list may have zero or more indexes, which are required - to make sense for the type of "CSTPTR".</dd> + constants. As with the <a href="#i_getelementptr">getelementptr</a> + instruction, the index list may have zero or more indexes, which are + required to make sense for the type of "CSTPTR".</dd> <dt><b><tt>select ( COND, VAL1, VAL2 )</tt></b></dt> - - <dd>Perform the <a href="#i_select">select operation</a> on - constants.</dd> + <dd>Perform the <a href="#i_select">select operation</a> on constants.</dd> <dt><b><tt>icmp COND ( VAL1, VAL2 )</tt></b></dt> <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd> @@ -2042,36 +2269,26 @@ following is the syntax for constant expressions:</p> <dt><b><tt>fcmp COND ( VAL1, VAL2 )</tt></b></dt> <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd> - <dt><b><tt>vicmp COND ( VAL1, VAL2 )</tt></b></dt> - <dd>Performs the <a href="#i_vicmp">vicmp operation</a> on constants.</dd> - - <dt><b><tt>vfcmp COND ( VAL1, VAL2 )</tt></b></dt> - <dd>Performs the <a href="#i_vfcmp">vfcmp operation</a> on constants.</dd> - <dt><b><tt>extractelement ( VAL, IDX )</tt></b></dt> - - <dd>Perform the <a href="#i_extractelement">extractelement - operation</a> on constants.</dd> + <dd>Perform the <a href="#i_extractelement">extractelement operation</a> on + constants.</dd> <dt><b><tt>insertelement ( VAL, ELT, IDX )</tt></b></dt> - - <dd>Perform the <a href="#i_insertelement">insertelement - operation</a> on constants.</dd> - + <dd>Perform the <a href="#i_insertelement">insertelement operation</a> on + constants.</dd> <dt><b><tt>shufflevector ( VEC1, VEC2, IDXMASK )</tt></b></dt> - - <dd>Perform the <a href="#i_shufflevector">shufflevector - operation</a> on constants.</dd> + <dd>Perform the <a href="#i_shufflevector">shufflevector operation</a> on + constants.</dd> <dt><b><tt>OPCODE ( LHS, RHS )</tt></b></dt> - - <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may - be any of the <a href="#binaryops">binary</a> or <a href="#bitwiseops">bitwise - binary</a> operations. The constraints on operands are the same as those for - the corresponding instruction (e.g. no bitwise operations on floating point - values are allowed).</dd> + <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may + be any of the <a href="#binaryops">binary</a> + or <a href="#bitwiseops">bitwise binary</a> operations. The constraints + on operands are the same as those for the corresponding instruction + (e.g. no bitwise operations on floating point values are allowed).</dd> </dl> + </div> <!-- ======================================================================= --> @@ -2080,31 +2297,30 @@ following is the syntax for constant expressions:</p> <div class="doc_text"> -<p>Embedded metadata provides a way to attach arbitrary data to the -instruction stream without affecting the behaviour of the program. There are -two metadata primitives, strings and nodes. All metadata has the -<tt>metadata</tt> type and is identified in syntax by a preceding exclamation -point ('<tt>!</tt>'). -</p> +<p>Embedded metadata provides a way to attach arbitrary data to the instruction + stream without affecting the behaviour of the program. There are two + metadata primitives, strings and nodes. All metadata has the + <tt>metadata</tt> type and is identified in syntax by a preceding exclamation + point ('<tt>!</tt>').</p> <p>A metadata string is a string surrounded by double quotes. It can contain -any character by escaping non-printable characters with "\xx" where "xx" is -the two digit hex code. For example: "<tt>!"test\00"</tt>". -</p> + any character by escaping non-printable characters with "\xx" where "xx" is + the two digit hex code. For example: "<tt>!"test\00"</tt>".</p> <p>Metadata nodes are represented with notation similar to structure constants -(a comma separated list of elements, surrounded by braces and preceeded by an -exclamation point). For example: "<tt>!{ metadata !"test\00", i32 10}</tt>". -</p> + (a comma separated list of elements, surrounded by braces and preceded by an + exclamation point). For example: "<tt>!{ metadata !"test\00", i32 + 10}</tt>".</p> -<p>A metadata node will attempt to track changes to the values it holds. In -the event that a value is deleted, it will be replaced with a typeless -"<tt>null</tt>", such as "<tt>metadata !{null, i32 10}</tt>".</p> +<p>A metadata node will attempt to track changes to the values it holds. In the + event that a value is deleted, it will be replaced with a typeless + "<tt>null</tt>", such as "<tt>metadata !{null, i32 10}</tt>".</p> <p>Optimizations may rely on metadata to provide additional information about -the program that isn't available in the instructions, or that isn't easily -computable. Similarly, the code generator may expect a certain metadata format -to be used to express debugging information.</p> + the program that isn't available in the instructions, or that isn't easily + computable. Similarly, the code generator may expect a certain metadata + format to be used to express debugging information.</p> + </div> <!-- *********************************************************************** --> @@ -2118,14 +2334,14 @@ to be used to express debugging information.</p> <div class="doc_text"> -<p> -LLVM supports inline assembler expressions (as opposed to <a href="#moduleasm"> -Module-Level Inline Assembly</a>) through the use of a special value. This -value represents the inline assembler as a string (containing the instructions -to emit), a list of operand constraints (stored as a string), and a flag that -indicates whether or not the inline asm expression has side effects. An example -inline assembler expression is: -</p> +<p>LLVM supports inline assembler expressions (as opposed + to <a href="#moduleasm"> Module-Level Inline Assembly</a>) through the use of + a special value. This value represents the inline assembler as a string + (containing the instructions to emit), a list of operand constraints (stored + as a string), a flag that indicates whether or not the inline asm + expression has side effects, and a flag indicating whether the asm came + originally from an asm block. An example inline assembler + expression is:</p> <div class="doc_code"> <pre> @@ -2133,10 +2349,9 @@ i32 (i32) asm "bswap $0", "=r,r" </pre> </div> -<p> -Inline assembler expressions may <b>only</b> be used as the callee operand of -a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we have: -</p> +<p>Inline assembler expressions may <b>only</b> be used as the callee operand of + a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we + have:</p> <div class="doc_code"> <pre> @@ -2144,11 +2359,9 @@ a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we have: </pre> </div> -<p> -Inline asms with side effects not visible in the constraint list must be marked -as having side effects. This is done through the use of the -'<tt>sideeffect</tt>' keyword, like so: -</p> +<p>Inline asms with side effects not visible in the constraint list must be + marked as having side effects. This is done through the use of the + '<tt>sideeffect</tt>' keyword, like so:</p> <div class="doc_code"> <pre> @@ -2156,26 +2369,126 @@ call void asm sideeffect "eieio", ""() </pre> </div> +<p>Inline asms derived from asm blocks are similarly marked with the + '<tt>msasm</tt>' keyword:</p> + +<div class="doc_code"> +<pre> +call void asm msasm "eieio", ""() +</pre> +</div> + +<p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come + first.</p> + <p>TODO: The format of the asm and constraints string still need to be -documented here. Constraints on what can be done (e.g. duplication, moving, etc -need to be documented). This is probably best done by reference to another -document that covers inline asm from a holistic perspective. -</p> + documented here. Constraints on what can be done (e.g. duplication, moving, + etc need to be documented). This is probably best done by reference to + another document that covers inline asm from a holistic perspective.</p> </div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="intrinsic_globals">Intrinsic Global Variables</a> +</div> +<!-- *********************************************************************** --> + +<p>LLVM has a number of "magic" global variables that contain data that affect +code generation or other IR semantics. These are documented here. All globals +of this sort should have a section specified as "<tt>llvm.metadata</tt>". This +section and all globals that start with "<tt>llvm.</tt>" are reserved for use +by LLVM.</p> + +<!-- ======================================================================= --> +<div class="doc_subsection"> +<a name="intg_used">The '<tt>llvm.used</tt>' Global Variable</a> +</div> + +<div class="doc_text"> + +<p>The <tt>@llvm.used</tt> global is an array with i8* element type which has <a +href="#linkage_appending">appending linkage</a>. This array contains a list of +pointers to global variables and functions which may optionally have a pointer +cast formed of bitcast or getelementptr. For example, a legal use of it is:</p> + +<pre> + @X = global i8 4 + @Y = global i32 123 + + @llvm.used = appending global [2 x i8*] [ + i8* @X, + i8* bitcast (i32* @Y to i8*) + ], section "llvm.metadata" +</pre> + +<p>If a global variable appears in the <tt>@llvm.used</tt> list, then the +compiler, assembler, and linker are required to treat the symbol as if there is +a reference to the global that it cannot see. For example, if a variable has +internal linkage and no references other than that from the <tt>@llvm.used</tt> +list, it cannot be deleted. This is commonly used to represent references from +inline asms and other things the compiler cannot "see", and corresponds to +"attribute((used))" in GNU C.</p> + +<p>On some targets, the code generator must emit a directive to the assembler or +object file to prevent the assembler and linker from molesting the symbol.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> +<a name="intg_compiler_used">The '<tt>llvm.compiler.used</tt>' Global Variable</a> +</div> + +<div class="doc_text"> + +<p>The <tt>@llvm.compiler.used</tt> directive is the same as the +<tt>@llvm.used</tt> directive, except that it only prevents the compiler from +touching the symbol. On targets that support it, this allows an intelligent +linker to optimize references to the symbol without being impeded as it would be +by <tt>@llvm.used</tt>.</p> + +<p>This is a rare construct that should only be used in rare circumstances, and +should not be exposed to source languages.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> +<a name="intg_global_ctors">The '<tt>llvm.global_ctors</tt>' Global Variable</a> +</div> + +<div class="doc_text"> + +<p>TODO: Describe this.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> +<a name="intg_global_dtors">The '<tt>llvm.global_dtors</tt>' Global Variable</a> +</div> + +<div class="doc_text"> + +<p>TODO: Describe this.</p> + +</div> + + <!-- *********************************************************************** --> <div class="doc_section"> <a name="instref">Instruction Reference</a> </div> <!-- *********************************************************************** --> <div class="doc_text"> -<p>The LLVM instruction set consists of several different -classifications of instructions: <a href="#terminators">terminator -instructions</a>, <a href="#binaryops">binary instructions</a>, -<a href="#bitwiseops">bitwise binary instructions</a>, <a - href="#memoryops">memory instructions</a>, and <a href="#otherops">other -instructions</a>.</p> +<p>The LLVM instruction set consists of several different classifications of + instructions: <a href="#terminators">terminator + instructions</a>, <a href="#binaryops">binary instructions</a>, + <a href="#bitwiseops">bitwise binary instructions</a>, + <a href="#memoryops">memory instructions</a>, and + <a href="#otherops">other instructions</a>.</p> </div> @@ -2185,25 +2498,29 @@ Instructions</a> </div> <div class="doc_text"> -<p>As mentioned <a href="#functionstructure">previously</a>, every -basic block in a program ends with a "Terminator" instruction, which -indicates which block should be executed after the current block is -finished. These terminator instructions typically yield a '<tt>void</tt>' -value: they produce control flow, not values (the one exception being -the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p> -<p>There are six different terminator instructions: the '<a - href="#i_ret"><tt>ret</tt></a>' instruction, the '<a href="#i_br"><tt>br</tt></a>' -instruction, the '<a href="#i_switch"><tt>switch</tt></a>' instruction, -the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the '<a - href="#i_unwind"><tt>unwind</tt></a>' instruction, and the '<a - href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p> +<p>As mentioned <a href="#functionstructure">previously</a>, every basic block + in a program ends with a "Terminator" instruction, which indicates which + block should be executed after the current block is finished. These + terminator instructions typically yield a '<tt>void</tt>' value: they produce + control flow, not values (the one exception being the + '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p> + +<p>There are six different terminator instructions: the + '<a href="#i_ret"><tt>ret</tt></a>' instruction, the + '<a href="#i_br"><tt>br</tt></a>' instruction, the + '<a href="#i_switch"><tt>switch</tt></a>' instruction, the + '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the + '<a href="#i_unwind"><tt>unwind</tt></a>' instruction, and the + '<a href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> <pre> ret <type> <value> <i>; Return a value from a non-void function</i> @@ -2211,38 +2528,35 @@ Instruction</a> </div> </pre> <h5>Overview:</h5> +<p>The '<tt>ret</tt>' instruction is used to return control flow (and optionally + a value) from a function back to the caller.</p> -<p>The '<tt>ret</tt>' instruction is used to return control flow (and -optionally a value) from a function back to the caller.</p> -<p>There are two forms of the '<tt>ret</tt>' instruction: one that -returns a value and then causes control flow, and one that just causes -control flow to occur.</p> +<p>There are two forms of the '<tt>ret</tt>' instruction: one that returns a + value and then causes control flow, and one that just causes control flow to + occur.</p> <h5>Arguments:</h5> +<p>The '<tt>ret</tt>' instruction optionally accepts a single argument, the + return value. The type of the return value must be a + '<a href="#t_firstclass">first class</a>' type.</p> -<p>The '<tt>ret</tt>' instruction optionally accepts a single argument, -the return value. The type of the return value must be a -'<a href="#t_firstclass">first class</a>' type.</p> - -<p>A function is not <a href="#wellformed">well formed</a> if -it it has a non-void return type and contains a '<tt>ret</tt>' -instruction with no return value or a return value with a type that -does not match its type, or if it has a void return type and contains -a '<tt>ret</tt>' instruction with a return value.</p> +<p>A function is not <a href="#wellformed">well formed</a> if it it has a + non-void return type and contains a '<tt>ret</tt>' instruction with no return + value or a return value with a type that does not match its type, or if it + has a void return type and contains a '<tt>ret</tt>' instruction with a + return value.</p> <h5>Semantics:</h5> - -<p>When the '<tt>ret</tt>' instruction is executed, control flow -returns back to the calling function's context. If the caller is a "<a - href="#i_call"><tt>call</tt></a>" instruction, execution continues at -the instruction after the call. If the caller was an "<a - href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues -at the beginning of the "normal" destination block. If the instruction -returns a value, that value shall set the call or invoke instruction's -return value.</p> +<p>When the '<tt>ret</tt>' instruction is executed, control flow returns back to + the calling function's context. If the caller is a + "<a href="#i_call"><tt>call</tt></a>" instruction, execution continues at the + instruction after the call. If the caller was an + "<a href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at + the beginning of the "normal" destination block. If the instruction returns + a value, that value shall set the call or invoke instruction's return + value.</p> <h5>Example:</h5> - <pre> ret i32 5 <i>; Return an integer value of 5</i> ret void <i>; Return from a void function</i> @@ -2260,73 +2574,83 @@ return value.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> br i1 <cond>, label <iftrue>, label <iffalse><br> br label <dest> <i>; Unconditional branch</i> +<pre> + br i1 <cond>, label <iftrue>, label <iffalse><br> br label <dest> <i>; Unconditional branch</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>br</tt>' instruction is used to cause control flow to -transfer to a different basic block in the current function. There are -two forms of this instruction, corresponding to a conditional branch -and an unconditional branch.</p> +<p>The '<tt>br</tt>' instruction is used to cause control flow to transfer to a + different basic block in the current function. There are two forms of this + instruction, corresponding to a conditional branch and an unconditional + branch.</p> + <h5>Arguments:</h5> -<p>The conditional branch form of the '<tt>br</tt>' instruction takes a -single '<tt>i1</tt>' value and two '<tt>label</tt>' values. The -unconditional form of the '<tt>br</tt>' instruction takes a single -'<tt>label</tt>' value as a target.</p> +<p>The conditional branch form of the '<tt>br</tt>' instruction takes a single + '<tt>i1</tt>' value and two '<tt>label</tt>' values. The unconditional form + of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a + target.</p> + <h5>Semantics:</h5> <p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>i1</tt>' -argument is evaluated. If the value is <tt>true</tt>, control flows -to the '<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>, -control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p> + argument is evaluated. If the value is <tt>true</tt>, control flows to the + '<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>, + control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p> + <h5>Example:</h5> -<pre>Test:<br> %cond = <a href="#i_icmp">icmp</a> eq i32 %a, %b<br> br i1 %cond, label %IfEqual, label %IfUnequal<br>IfEqual:<br> <a - href="#i_ret">ret</a> i32 1<br>IfUnequal:<br> <a href="#i_ret">ret</a> i32 0<br></pre> +<pre> +Test: + %cond = <a href="#i_icmp">icmp</a> eq i32 %a, %b + br i1 %cond, label %IfEqual, label %IfUnequal +IfEqual: + <a href="#i_ret">ret</a> i32 1 +IfUnequal: + <a href="#i_ret">ret</a> i32 0 +</pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_switch">'<tt>switch</tt>' Instruction</a> </div> <div class="doc_text"> -<h5>Syntax:</h5> +<h5>Syntax:</h5> <pre> switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ] </pre> <h5>Overview:</h5> - <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of -several different places. It is a generalization of the '<tt>br</tt>' -instruction, allowing a branch to occur to one of many possible -destinations.</p> - + several different places. It is a generalization of the '<tt>br</tt>' + instruction, allowing a branch to occur to one of many possible + destinations.</p> <h5>Arguments:</h5> - <p>The '<tt>switch</tt>' instruction uses three parameters: an integer -comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and -an array of pairs of comparison value constants and '<tt>label</tt>'s. The -table is not allowed to contain duplicate constant entries.</p> + comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, + and an array of pairs of comparison value constants and '<tt>label</tt>'s. + The table is not allowed to contain duplicate constant entries.</p> <h5>Semantics:</h5> - <p>The <tt>switch</tt> instruction specifies a table of values and -destinations. When the '<tt>switch</tt>' instruction is executed, this -table is searched for the given value. If the value is found, control flow is -transfered to the corresponding destination; otherwise, control flow is -transfered to the default destination.</p> + destinations. When the '<tt>switch</tt>' instruction is executed, this table + is searched for the given value. If the value is found, control flow is + transferred to the corresponding destination; otherwise, control flow is + transferred to the default destination.</p> <h5>Implementation:</h5> - <p>Depending on properties of the target machine and the particular -<tt>switch</tt> instruction, this instruction may be code generated in different -ways. For example, it could be generated as a series of chained conditional -branches or with a lookup table.</p> + <tt>switch</tt> instruction, this instruction may be code generated in + different ways. For example, it could be generated as a series of chained + conditional branches or with a lookup table.</p> <h5>Example:</h5> - <pre> <i>; Emulate a conditional br instruction</i> %Val = <a href="#i_zext">zext</a> i1 %value to i32 @@ -2340,6 +2664,7 @@ branches or with a lookup table.</p> i32 1, label %onone i32 2, label %ontwo ] </pre> + </div> <!-- _______________________________________________________________________ --> @@ -2350,79 +2675,72 @@ branches or with a lookup table.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = invoke [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] <ptr to function ty> <function ptr val>(<function args>) [<a href="#fnattrs">fn attrs</a>] to label <normal label> unwind label <exception label> </pre> <h5>Overview:</h5> - <p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified -function, with the possibility of control flow transfer to either the -'<tt>normal</tt>' label or the -'<tt>exception</tt>' label. If the callee function returns with the -"<tt><a href="#i_ret">ret</a></tt>" instruction, control flow will return to the -"normal" label. If the callee (or any indirect callees) returns with the "<a -href="#i_unwind"><tt>unwind</tt></a>" instruction, control is interrupted and -continued at the dynamically nearest "exception" label.</p> + function, with the possibility of control flow transfer to either the + '<tt>normal</tt>' label or the '<tt>exception</tt>' label. If the callee + function returns with the "<tt><a href="#i_ret">ret</a></tt>" instruction, + control flow will return to the "normal" label. If the callee (or any + indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>" + instruction, control is interrupted and continued at the dynamically nearest + "exception" label.</p> <h5>Arguments:</h5> - <p>This instruction requires several arguments:</p> <ol> - <li> - The optional "cconv" marker indicates which <a href="#callingconv">calling - convention</a> the call should use. If none is specified, the call defaults - to using C calling conventions. - </li> + <li>The optional "cconv" marker indicates which <a href="#callingconv">calling + convention</a> the call should use. If none is specified, the call + defaults to using C calling conventions.</li> <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for - return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', - and '<tt>inreg</tt>' attributes are valid here.</li> + return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and + '<tt>inreg</tt>' attributes are valid here.</li> <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to - function value being invoked. In most cases, this is a direct function - invocation, but indirect <tt>invoke</tt>s are just as possible, branching off - an arbitrary pointer to function value. - </li> + function value being invoked. In most cases, this is a direct function + invocation, but indirect <tt>invoke</tt>s are just as possible, branching + off an arbitrary pointer to function value.</li> <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a - function to be invoked. </li> + function to be invoked. </li> <li>'<tt>function args</tt>': argument list whose types match the function - signature argument types. If the function signature indicates the function - accepts a variable number of arguments, the extra arguments can be - specified. </li> + signature argument types. If the function signature indicates the + function accepts a variable number of arguments, the extra arguments can + be specified.</li> <li>'<tt>normal label</tt>': the label reached when the called function - executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li> + executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li> <li>'<tt>exception label</tt>': the label reached when a callee returns with - the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li> + the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li> <li>The optional <a href="#fnattrs">function attributes</a> list. Only - '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and - '<tt>readnone</tt>' attributes are valid here.</li> + '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and + '<tt>readnone</tt>' attributes are valid here.</li> </ol> <h5>Semantics:</h5> - -<p>This instruction is designed to operate as a standard '<tt><a -href="#i_call">call</a></tt>' instruction in most regards. The primary -difference is that it establishes an association with a label, which is used by -the runtime library to unwind the stack.</p> +<p>This instruction is designed to operate as a standard + '<tt><a href="#i_call">call</a></tt>' instruction in most regards. The + primary difference is that it establishes an association with a label, which + is used by the runtime library to unwind the stack.</p> <p>This instruction is used in languages with destructors to ensure that proper -cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown -exception. Additionally, this is important for implementation of -'<tt>catch</tt>' clauses in high-level languages that support them.</p> + cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown + exception. Additionally, this is important for implementation of + '<tt>catch</tt>' clauses in high-level languages that support them.</p> -<p>For the purposes of the SSA form, the definition of the value -returned by the '<tt>invoke</tt>' instruction is deemed to occur on -the edge from the current block to the "normal" label. If the callee -unwinds then no return value is available.</p> +<p>For the purposes of the SSA form, the definition of the value returned by the + '<tt>invoke</tt>' instruction is deemed to occur on the edge from the current + block to the "normal" label. If the callee unwinds then no return value is + available.</p> <h5>Example:</h5> <pre> @@ -2431,8 +2749,8 @@ unwinds then no return value is available.</p> %retval = invoke <a href="#callingconv">coldcc</a> i32 %Testfnptr(i32 15) to label %Continue unwind label %TestCleanup <i>; {i32}:retval set</i> </pre> -</div> +</div> <!-- _______________________________________________________________________ --> @@ -2447,20 +2765,19 @@ Instruction</a> </div> </pre> <h5>Overview:</h5> - <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow -at the first callee in the dynamic call stack which used an <a -href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. This is -primarily used to implement exception handling.</p> + at the first callee in the dynamic call stack which used + an <a href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. + This is primarily used to implement exception handling.</p> <h5>Semantics:</h5> - <p>The '<tt>unwind</tt>' instruction causes execution of the current function to -immediately halt. The dynamic call stack is then searched for the first <a -href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. Once found, -execution continues at the "exceptional" destination block specified by the -<tt>invoke</tt> instruction. If there is no <tt>invoke</tt> instruction in the -dynamic call chain, undefined behavior results.</p> + immediately halt. The dynamic call stack is then searched for the + first <a href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. + Once found, execution continues at the "exceptional" destination block + specified by the <tt>invoke</tt> instruction. If there is no <tt>invoke</tt> + instruction in the dynamic call chain, undefined behavior results.</p> + </div> <!-- _______________________________________________________________________ --> @@ -2476,29 +2793,31 @@ Instruction</a> </div> </pre> <h5>Overview:</h5> - <p>The '<tt>unreachable</tt>' instruction has no defined semantics. This -instruction is used to inform the optimizer that a particular portion of the -code is not reachable. This can be used to indicate that the code after a -no-return function cannot be reached, and other facts.</p> + instruction is used to inform the optimizer that a particular portion of the + code is not reachable. This can be used to indicate that the code after a + no-return function cannot be reached, and other facts.</p> <h5>Semantics:</h5> - <p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p> -</div> - +</div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="binaryops">Binary Operations</a> </div> + <div class="doc_text"> -<p>Binary operators are used to do most of the computation in a -program. They require two operands of the same type, execute an operation on them, and -produce a single value. The operands might represent -multiple data, as is the case with the <a href="#t_vector">vector</a> data type. -The result value has the same type as its operands.</p> + +<p>Binary operators are used to do most of the computation in a program. They + require two operands of the same type, execute an operation on them, and + produce a single value. The operands might represent multiple data, as is + the case with the <a href="#t_vector">vector</a> data type. The result value + has the same type as its operands.</p> + <p>There are several different binary operators:</p> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_add">'<tt>add</tt>' Instruction</a> @@ -2507,39 +2826,42 @@ The result value has the same type as its operands.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> - <result> = add <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = add <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = add nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = add nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = add nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p> <h5>Arguments:</h5> - -<p>The two arguments to the '<tt>add</tt>' instruction must be <a - href="#t_integer">integer</a> or - <a href="#t_vector">vector</a> of integer values. Both arguments must - have identical types.</p> +<p>The two arguments to the '<tt>add</tt>' instruction must + be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of + integer values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the integer sum of the two operands.</p> -<p>If the sum has unsigned overflow, the result returned is the -mathematical result modulo 2<sup>n</sup>, where n is the bit width of -the result.</p> +<p>If the sum has unsigned overflow, the result returned is the mathematical + result modulo 2<sup>n</sup>, where n is the bit width of the result.</p> -<p>Because LLVM integers use a two's complement representation, this -instruction is appropriate for both signed and unsigned integers.</p> +<p>Because LLVM integers use a two's complement representation, this instruction + is appropriate for both signed and unsigned integers.</p> -<h5>Example:</h5> +<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" + and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or + <tt>nsw</tt> keywords are present, the result value of the <tt>add</tt> + is undefined if unsigned and/or signed overflow, respectively, occurs.</p> +<h5>Example:</h5> <pre> <result> = add i32 4, %var <i>; yields {i32}:result = 4 + %var</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_fadd">'<tt>fadd</tt>' Instruction</a> @@ -2548,31 +2870,28 @@ instruction is appropriate for both signed and unsigned integers.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = fadd <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - <p>The '<tt>fadd</tt>' instruction returns the sum of its two operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>fadd</tt>' instruction must be -<a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of -floating point values. Both arguments must have identical types.</p> + <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of + floating point values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the floating point sum of the two operands.</p> <h5>Example:</h5> - <pre> <result> = fadd float 4.0, %var <i>; yields {float}:result = 4.0 + %var</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_sub">'<tt>sub</tt>' Instruction</a> @@ -2581,42 +2900,47 @@ floating point values. Both arguments must have identical types.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> - <result> = sub <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sub <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sub nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sub nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sub nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - <p>The '<tt>sub</tt>' instruction returns the difference of its two -operands.</p> + operands.</p> <p>Note that the '<tt>sub</tt>' instruction is used to represent the -'<tt>neg</tt>' instruction present in most other intermediate -representations.</p> + '<tt>neg</tt>' instruction present in most other intermediate + representations.</p> <h5>Arguments:</h5> - -<p>The two arguments to the '<tt>sub</tt>' instruction must be <a - href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of - integer values. Both arguments must have identical types.</p> +<p>The two arguments to the '<tt>sub</tt>' instruction must + be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of + integer values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the integer difference of the two operands.</p> <p>If the difference has unsigned overflow, the result returned is the -mathematical result modulo 2<sup>n</sup>, where n is the bit width of -the result.</p> + mathematical result modulo 2<sup>n</sup>, where n is the bit width of the + result.</p> + +<p>Because LLVM integers use a two's complement representation, this instruction + is appropriate for both signed and unsigned integers.</p> -<p>Because LLVM integers use a two's complement representation, this -instruction is appropriate for both signed and unsigned integers.</p> +<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" + and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or + <tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt> + is undefined if unsigned and/or signed overflow, respectively, occurs.</p> <h5>Example:</h5> <pre> <result> = sub i32 4, %var <i>; yields {i32}:result = 4 - %var</i> <result> = sub i32 0, %val <i>; yields {i32}:result = -%var</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -2627,28 +2951,24 @@ instruction is appropriate for both signed and unsigned integers.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = fsub <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - <p>The '<tt>fsub</tt>' instruction returns the difference of its two -operands.</p> + operands.</p> <p>Note that the '<tt>fsub</tt>' instruction is used to represent the -'<tt>fneg</tt>' instruction present in most other intermediate -representations.</p> + '<tt>fneg</tt>' instruction present in most other intermediate + representations.</p> <h5>Arguments:</h5> - -<p>The two arguments to the '<tt>fsub</tt>' instruction must be <a - <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> - of floating point values. Both arguments must have identical types.</p> +<p>The two arguments to the '<tt>fsub</tt>' instruction must be + <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of + floating point values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the floating point difference of the two operands.</p> <h5>Example:</h5> @@ -2656,6 +2976,7 @@ representations.</p> <result> = fsub float 4.0, %var <i>; yields {float}:result = 4.0 - %var</i> <result> = fsub float -0.0, %val <i>; yields {float}:result = -%var</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -2666,34 +2987,45 @@ representations.</p> <div class="doc_text"> <h5>Syntax:</h5> -<pre> <result> = mul <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = mul <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = mul nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = mul nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = mul nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>mul</tt>' instruction returns the product of its two -operands.</p> +<p>The '<tt>mul</tt>' instruction returns the product of its two operands.</p> <h5>Arguments:</h5> - -<p>The two arguments to the '<tt>mul</tt>' instruction must be <a -href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> +<p>The two arguments to the '<tt>mul</tt>' instruction must + be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of + integer values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the integer product of the two operands.</p> -<p>If the result of the multiplication has unsigned overflow, -the result returned is the mathematical result modulo -2<sup>n</sup>, where n is the bit width of the result.</p> -<p>Because LLVM integers use a two's complement representation, and the -result is the same width as the operands, this instruction returns the -correct result for both signed and unsigned integers. If a full product -(e.g. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands -should be sign-extended or zero-extended as appropriate to the -width of the full product.</p> +<p>If the result of the multiplication has unsigned overflow, the result + returned is the mathematical result modulo 2<sup>n</sup>, where n is the bit + width of the result.</p> + +<p>Because LLVM integers use a two's complement representation, and the result + is the same width as the operands, this instruction returns the correct + result for both signed and unsigned integers. If a full product + (e.g. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands should + be sign-extended or zero-extended as appropriate to the width of the full + product.</p> + +<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" + and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or + <tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt> + is undefined if unsigned and/or signed overflow, respectively, occurs.</p> + <h5>Example:</h5> -<pre> <result> = mul i32 4, %var <i>; yields {i32}:result = 4 * %var</i> +<pre> + <result> = mul i32 4, %var <i>; yields {i32}:result = 4 * %var</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -2704,140 +3036,170 @@ width of the full product.</p> <div class="doc_text"> <h5>Syntax:</h5> -<pre> <result> = fmul <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = fmul <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>fmul</tt>' instruction returns the product of its two -operands.</p> +<p>The '<tt>fmul</tt>' instruction returns the product of its two operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>fmul</tt>' instruction must be -<a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> -of floating point values. Both arguments must have identical types.</p> + <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of + floating point values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the floating point product of the two operands.</p> <h5>Example:</h5> -<pre> <result> = fmul float 4.0, %var <i>; yields {float}:result = 4.0 * %var</i> +<pre> + <result> = fmul float 4.0, %var <i>; yields {float}:result = 4.0 * %var</i> </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_udiv">'<tt>udiv</tt>' Instruction </a></div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = udiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = udiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>udiv</tt>' instruction returns the quotient of its two -operands.</p> +<p>The '<tt>udiv</tt>' instruction returns the quotient of its two operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>udiv</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the unsigned integer quotient of the two operands.</p> + <p>Note that unsigned integer division and signed integer division are distinct -operations; for signed integer division, use '<tt>sdiv</tt>'.</p> + operations; for signed integer division, use '<tt>sdiv</tt>'.</p> + <p>Division by zero leads to undefined behavior.</p> + <h5>Example:</h5> -<pre> <result> = udiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> +<pre> + <result> = udiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_sdiv">'<tt>sdiv</tt>' Instruction </a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> <pre> - <result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = sdiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>sdiv</tt>' instruction returns the quotient of its two -operands.</p> +<p>The '<tt>sdiv</tt>' instruction returns the quotient of its two operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>sdiv</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> <h5>Semantics:</h5> -<p>The value produced is the signed integer quotient of the two operands rounded towards zero.</p> +<p>The value produced is the signed integer quotient of the two operands rounded + towards zero.</p> + <p>Note that signed integer division and unsigned integer division are distinct -operations; for unsigned integer division, use '<tt>udiv</tt>'.</p> + operations; for unsigned integer division, use '<tt>udiv</tt>'.</p> + <p>Division by zero leads to undefined behavior. Overflow also leads to -undefined behavior; this is a rare case, but can occur, for example, -by doing a 32-bit division of -2147483648 by -1.</p> + undefined behavior; this is a rare case, but can occur, for example, by doing + a 32-bit division of -2147483648 by -1.</p> + +<p>If the <tt>exact</tt> keyword is present, the result value of the + <tt>sdiv</tt> is undefined if the result would be rounded or if overflow + would occur.</p> + <h5>Example:</h5> -<pre> <result> = sdiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> +<pre> + <result> = sdiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_fdiv">'<tt>fdiv</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> <pre> <result> = fdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> -<h5>Overview:</h5> -<p>The '<tt>fdiv</tt>' instruction returns the quotient of its two -operands.</p> +<h5>Overview:</h5> +<p>The '<tt>fdiv</tt>' instruction returns the quotient of its two operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>fdiv</tt>' instruction must be -<a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> -of floating point values. Both arguments must have identical types.</p> + <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of + floating point values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The value produced is the floating point quotient of the two operands.</p> <h5>Example:</h5> - <pre> <result> = fdiv float 4.0, %var <i>; yields {float}:result = 4.0 / %var</i> </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_urem">'<tt>urem</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = urem <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = urem <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>urem</tt>' instruction returns the remainder from the -unsigned division of its two arguments.</p> +<p>The '<tt>urem</tt>' instruction returns the remainder from the unsigned + division of its two arguments.</p> + <h5>Arguments:</h5> <p>The two arguments to the '<tt>urem</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> + <h5>Semantics:</h5> <p>This instruction returns the unsigned integer <i>remainder</i> of a division. -This instruction always performs an unsigned division to get the remainder.</p> + This instruction always performs an unsigned division to get the + remainder.</p> + <p>Note that unsigned integer remainder and signed integer remainder are -distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p> + distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p> + <p>Taking the remainder of a division by zero leads to undefined behavior.</p> + <h5>Example:</h5> -<pre> <result> = urem i32 4, %var <i>; yields {i32}:result = 4 % %var</i> +<pre> + <result> = urem i32 4, %var <i>; yields {i32}:result = 4 % %var</i> </pre> </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_srem">'<tt>srem</tt>' Instruction</a> @@ -2846,47 +3208,48 @@ distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = srem <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>srem</tt>' instruction returns the remainder from the -signed division of its two operands. This instruction can also take -<a href="#t_vector">vector</a> versions of the values in which case -the elements must be integers.</p> +<p>The '<tt>srem</tt>' instruction returns the remainder from the signed + division of its two operands. This instruction can also take + <a href="#t_vector">vector</a> versions of the values in which case the + elements must be integers.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>srem</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>This instruction returns the <i>remainder</i> of a division (where the result -has the same sign as the dividend, <tt>op1</tt>), not the <i>modulo</i> -operator (where the result has the same sign as the divisor, <tt>op2</tt>) of -a value. For more information about the difference, see <a - href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The -Math Forum</a>. For a table of how this is implemented in various languages, -please see <a href="http://en.wikipedia.org/wiki/Modulo_operation"> -Wikipedia: modulo operation</a>.</p> + has the same sign as the dividend, <tt>op1</tt>), not the <i>modulo</i> + operator (where the result has the same sign as the divisor, <tt>op2</tt>) of + a value. For more information about the difference, + see <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The + Math Forum</a>. For a table of how this is implemented in various languages, + please see <a href="http://en.wikipedia.org/wiki/Modulo_operation"> + Wikipedia: modulo operation</a>.</p> + <p>Note that signed integer remainder and unsigned integer remainder are -distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p> + distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p> + <p>Taking the remainder of a division by zero leads to undefined behavior. -Overflow also leads to undefined behavior; this is a rare case, but can occur, -for example, by taking the remainder of a 32-bit division of -2147483648 by -1. -(The remainder doesn't actually overflow, but this rule lets srem be -implemented using instructions that return both the result of the division -and the remainder.)</p> + Overflow also leads to undefined behavior; this is a rare case, but can + occur, for example, by taking the remainder of a 32-bit division of + -2147483648 by -1. (The remainder doesn't actually overflow, but this rule + lets srem be implemented using instructions that return both the result of + the division and the remainder.)</p> + <h5>Example:</h5> -<pre> <result> = srem i32 4, %var <i>; yields {i32}:result = 4 % %var</i> +<pre> + <result> = srem i32 4, %var <i>; yields {i32}:result = 4 % %var</i> </pre> </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_frem">'<tt>frem</tt>' Instruction</a> </div> @@ -2894,99 +3257,110 @@ and the remainder.)</p> <div class="doc_text"> <h5>Syntax:</h5> -<pre> <result> = frem <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = frem <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>frem</tt>' instruction returns the remainder from the -division of its two operands.</p> +<p>The '<tt>frem</tt>' instruction returns the remainder from the division of + its two operands.</p> + <h5>Arguments:</h5> <p>The two arguments to the '<tt>frem</tt>' instruction must be -<a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> -of floating point values. Both arguments must have identical types.</p> + <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of + floating point values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - -<p>This instruction returns the <i>remainder</i> of a division. -The remainder has the same sign as the dividend.</p> +<p>This instruction returns the <i>remainder</i> of a division. The remainder + has the same sign as the dividend.</p> <h5>Example:</h5> - <pre> <result> = frem float 4.0, %var <i>; yields {float}:result = 4.0 % %var</i> </pre> + </div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary Operations</a> </div> + <div class="doc_text"> -<p>Bitwise binary operators are used to do various forms of -bit-twiddling in a program. They are generally very efficient -instructions and can commonly be strength reduced from other -instructions. They require two operands of the same type, execute an operation on them, -and produce a single value. The resulting value is the same type as its operands.</p> + +<p>Bitwise binary operators are used to do various forms of bit-twiddling in a + program. They are generally very efficient instructions and can commonly be + strength reduced from other instructions. They require two operands of the + same type, execute an operation on them, and produce a single value. The + resulting value is the same type as its operands.</p> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = shl <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = shl <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>shl</tt>' instruction returns the first operand shifted to -the left a specified number of bits.</p> +<p>The '<tt>shl</tt>' instruction returns the first operand shifted to the left + a specified number of bits.</p> <h5>Arguments:</h5> - -<p>Both arguments to the '<tt>shl</tt>' instruction must be the same <a - href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -type. '<tt>op2</tt>' is treated as an unsigned value.</p> +<p>Both arguments to the '<tt>shl</tt>' instruction must be the + same <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of + integer type. '<tt>op2</tt>' is treated as an unsigned value.</p> <h5>Semantics:</h5> +<p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod + 2<sup>n</sup>, where <tt>n</tt> is the width of the result. If <tt>op2</tt> + is (statically or dynamically) negative or equal to or larger than the number + of bits in <tt>op1</tt>, the result is undefined. If the arguments are + vectors, each vector element of <tt>op1</tt> is shifted by the corresponding + shift amount in <tt>op2</tt>.</p> -<p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod 2<sup>n</sup>, -where n is the width of the result. If <tt>op2</tt> is (statically or dynamically) negative or -equal to or larger than the number of bits in <tt>op1</tt>, the result is undefined. -If the arguments are vectors, each vector element of <tt>op1</tt> is shifted by the -corresponding shift amount in <tt>op2</tt>.</p> - -<h5>Example:</h5><pre> +<h5>Example:</h5> +<pre> <result> = shl i32 4, %var <i>; yields {i32}: 4 << %var</i> <result> = shl i32 4, 2 <i>; yields {i32}: 16</i> <result> = shl i32 1, 10 <i>; yields {i32}: 1024</i> <result> = shl i32 1, 32 <i>; undefined</i> <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> <i>; yields: result=<2 x i32> < i32 2, i32 4></i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_lshr">'<tt>lshr</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = lshr <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = lshr <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> -<p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first -operand shifted to the right a specified number of bits with zero fill.</p> +<p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first + operand shifted to the right a specified number of bits with zero fill.</p> <h5>Arguments:</h5> <p>Both arguments to the '<tt>lshr</tt>' instruction must be the same -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -type. '<tt>op2</tt>' is treated as an unsigned value.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + type. '<tt>op2</tt>' is treated as an unsigned value.</p> <h5>Semantics:</h5> - <p>This instruction always performs a logical shift right operation. The most -significant bits of the result will be filled with zero bits after the -shift. If <tt>op2</tt> is (statically or dynamically) equal to or larger than -the number of bits in <tt>op1</tt>, the result is undefined. If the arguments are -vectors, each vector element of <tt>op1</tt> is shifted by the corresponding shift -amount in <tt>op2</tt>.</p> + significant bits of the result will be filled with zero bits after the shift. + If <tt>op2</tt> is (statically or dynamically) equal to or larger than the + number of bits in <tt>op1</tt>, the result is undefined. If the arguments are + vectors, each vector element of <tt>op1</tt> is shifted by the corresponding + shift amount in <tt>op2</tt>.</p> <h5>Example:</h5> <pre> @@ -2997,6 +3371,7 @@ amount in <tt>op2</tt>.</p> <result> = lshr i32 1, 32 <i>; undefined</i> <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> <i>; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1></i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3005,25 +3380,27 @@ Instruction</a> </div> <div class="doc_text"> <h5>Syntax:</h5> -<pre> <result> = ashr <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = ashr <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> -<p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first -operand shifted to the right a specified number of bits with sign extension.</p> +<p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first + operand shifted to the right a specified number of bits with sign + extension.</p> <h5>Arguments:</h5> <p>Both arguments to the '<tt>ashr</tt>' instruction must be the same -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -type. '<tt>op2</tt>' is treated as an unsigned value.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + type. '<tt>op2</tt>' is treated as an unsigned value.</p> <h5>Semantics:</h5> -<p>This instruction always performs an arithmetic shift right operation, -The most significant bits of the result will be filled with the sign bit -of <tt>op1</tt>. If <tt>op2</tt> is (statically or dynamically) equal to or -larger than the number of bits in <tt>op1</tt>, the result is undefined. If the -arguments are vectors, each vector element of <tt>op1</tt> is shifted by the -corresponding shift amount in <tt>op2</tt>.</p> +<p>This instruction always performs an arithmetic shift right operation, The + most significant bits of the result will be filled with the sign bit + of <tt>op1</tt>. If <tt>op2</tt> is (statically or dynamically) equal to or + larger than the number of bits in <tt>op1</tt>, the result is undefined. If + the arguments are vectors, each vector element of <tt>op1</tt> is shifted by + the corresponding shift amount in <tt>op2</tt>.</p> <h5>Example:</h5> <pre> @@ -3034,6 +3411,7 @@ corresponding shift amount in <tt>op2</tt>.</p> <result> = ashr i32 1, 32 <i>; undefined</i> <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> <i>; yields: result=<2 x i32> < i32 -1, i32 0></i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3043,26 +3421,22 @@ Instruction</a> </div> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = and <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>and</tt>' instruction returns the bitwise logical and of -its two operands.</p> +<p>The '<tt>and</tt>' instruction returns the bitwise logical and of its two + operands.</p> <h5>Arguments:</h5> - <p>The two arguments to the '<tt>and</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> <h5>Semantics:</h5> <p>The truth table used for the '<tt>and</tt>' instruction is:</p> -<p> </p> -<div> + <table border="1" cellspacing="0" cellpadding="4"> <tbody> <tr> @@ -3092,7 +3466,7 @@ values. Both arguments must have identical types.</p> </tr> </tbody> </table> -</div> + <h5>Example:</h5> <pre> <result> = and i32 4, %var <i>; yields {i32}:result = 4 & %var</i> @@ -3102,22 +3476,26 @@ values. Both arguments must have identical types.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = or <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = or <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive -or of its two operands.</p> -<h5>Arguments:</h5> +<p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive or of its + two operands.</p> +<h5>Arguments:</h5> <p>The two arguments to the '<tt>or</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> + <h5>Semantics:</h5> <p>The truth table used for the '<tt>or</tt>' instruction is:</p> -<p> </p> -<div> + <table border="1" cellspacing="0" cellpadding="4"> <tbody> <tr> @@ -3147,34 +3525,40 @@ values. Both arguments must have identical types.</p> </tr> </tbody> </table> -</div> + <h5>Example:</h5> -<pre> <result> = or i32 4, %var <i>; yields {i32}:result = 4 | %var</i> +<pre> + <result> = or i32 4, %var <i>; yields {i32}:result = 4 | %var</i> <result> = or i32 15, 40 <i>; yields {i32}:result = 47</i> <result> = or i32 4, 8 <i>; yields {i32}:result = 12</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = xor <ty> <op1>, <op2> <i>; yields {ty}:result</i> +<pre> + <result> = xor <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive -or of its two operands. The <tt>xor</tt> is used to implement the -"one's complement" operation, which is the "~" operator in C.</p> +<p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of + its two operands. The <tt>xor</tt> is used to implement the "one's + complement" operation, which is the "~" operator in C.</p> + <h5>Arguments:</h5> <p>The two arguments to the '<tt>xor</tt>' instruction must be -<a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer -values. Both arguments must have identical types.</p> + <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer + values. Both arguments must have identical types.</p> <h5>Semantics:</h5> - <p>The truth table used for the '<tt>xor</tt>' instruction is:</p> -<p> </p> -<div> + <table border="1" cellspacing="0" cellpadding="4"> <tbody> <tr> @@ -3204,14 +3588,15 @@ values. Both arguments must have identical types.</p> </tr> </tbody> </table> -</div> -<p> </p> + <h5>Example:</h5> -<pre> <result> = xor i32 4, %var <i>; yields {i32}:result = 4 ^ %var</i> +<pre> + <result> = xor i32 4, %var <i>; yields {i32}:result = 4 ^ %var</i> <result> = xor i32 15, 40 <i>; yields {i32}:result = 39</i> <result> = xor i32 4, 8 <i>; yields {i32}:result = 12</i> <result> = xor i32 %V, -1 <i>; yields {i32}:result = ~%V</i> </pre> + </div> <!-- ======================================================================= --> @@ -3222,11 +3607,11 @@ values. Both arguments must have identical types.</p> <div class="doc_text"> <p>LLVM supports several instructions to represent vector operations in a -target-independent manner. These instructions cover the element-access and -vector-specific operations needed to process vectors effectively. While LLVM -does directly support these vector operations, many sophisticated algorithms -will want to use target-specific intrinsics to take full advantage of a specific -target.</p> + target-independent manner. These instructions cover the element-access and + vector-specific operations needed to process vectors effectively. While LLVM + does directly support these vector operations, many sophisticated algorithms + will want to use target-specific intrinsics to take full advantage of a + specific target.</p> </div> @@ -3238,43 +3623,33 @@ target.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = extractelement <n x <ty>> <val>, i32 <idx> <i>; yields <ty></i> </pre> <h5>Overview:</h5> - -<p> -The '<tt>extractelement</tt>' instruction extracts a single scalar -element from a vector at a specified index. -</p> +<p>The '<tt>extractelement</tt>' instruction extracts a single scalar element + from a vector at a specified index.</p> <h5>Arguments:</h5> - -<p> -The first operand of an '<tt>extractelement</tt>' instruction is a -value of <a href="#t_vector">vector</a> type. The second operand is -an index indicating the position from which to extract the element. -The index may be a variable.</p> +<p>The first operand of an '<tt>extractelement</tt>' instruction is a value + of <a href="#t_vector">vector</a> type. The second operand is an index + indicating the position from which to extract the element. The index may be + a variable.</p> <h5>Semantics:</h5> - -<p> -The result is a scalar of the same type as the element type of -<tt>val</tt>. Its value is the value at position <tt>idx</tt> of -<tt>val</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the -results are undefined. -</p> +<p>The result is a scalar of the same type as the element type of + <tt>val</tt>. Its value is the value at position <tt>idx</tt> of + <tt>val</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the + results are undefined.</p> <h5>Example:</h5> - <pre> %result = extractelement <4 x i32> %vec, i32 0 <i>; yields i32</i> </pre> -</div> +</div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> @@ -3284,42 +3659,32 @@ results are undefined. <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = insertelement <n x <ty>> <val>, <ty> <elt>, i32 <idx> <i>; yields <n x <ty>></i> </pre> <h5>Overview:</h5> - -<p> -The '<tt>insertelement</tt>' instruction inserts a scalar -element into a vector at a specified index. -</p> - +<p>The '<tt>insertelement</tt>' instruction inserts a scalar element into a + vector at a specified index.</p> <h5>Arguments:</h5> - -<p> -The first operand of an '<tt>insertelement</tt>' instruction is a -value of <a href="#t_vector">vector</a> type. The second operand is a -scalar value whose type must equal the element type of the first -operand. The third operand is an index indicating the position at -which to insert the value. The index may be a variable.</p> +<p>The first operand of an '<tt>insertelement</tt>' instruction is a value + of <a href="#t_vector">vector</a> type. The second operand is a scalar value + whose type must equal the element type of the first operand. The third + operand is an index indicating the position at which to insert the value. + The index may be a variable.</p> <h5>Semantics:</h5> - -<p> -The result is a vector of the same type as <tt>val</tt>. Its -element values are those of <tt>val</tt> except at position -<tt>idx</tt>, where it gets the value <tt>elt</tt>. If <tt>idx</tt> -exceeds the length of <tt>val</tt>, the results are undefined. -</p> +<p>The result is a vector of the same type as <tt>val</tt>. Its element values + are those of <tt>val</tt> except at position <tt>idx</tt>, where it gets the + value <tt>elt</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the + results are undefined.</p> <h5>Example:</h5> - <pre> %result = insertelement <4 x i32> %vec, i32 1, i32 0 <i>; yields <4 x i32></i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3330,46 +3695,33 @@ exceeds the length of <tt>val</tt>, the results are undefined. <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> <i>; yields <m x <ty>></i> </pre> <h5>Overview:</h5> - -<p> -The '<tt>shufflevector</tt>' instruction constructs a permutation of elements -from two input vectors, returning a vector with the same element type as -the input and length that is the same as the shuffle mask. -</p> +<p>The '<tt>shufflevector</tt>' instruction constructs a permutation of elements + from two input vectors, returning a vector with the same element type as the + input and length that is the same as the shuffle mask.</p> <h5>Arguments:</h5> +<p>The first two operands of a '<tt>shufflevector</tt>' instruction are vectors + with types that match each other. The third argument is a shuffle mask whose + element type is always 'i32'. The result of the instruction is a vector + whose length is the same as the shuffle mask and whose element type is the + same as the element type of the first two operands.</p> -<p> -The first two operands of a '<tt>shufflevector</tt>' instruction are vectors -with types that match each other. The third argument is a shuffle mask whose -element type is always 'i32'. The result of the instruction is a vector whose -length is the same as the shuffle mask and whose element type is the same as -the element type of the first two operands. -</p> - -<p> -The shuffle mask operand is required to be a constant vector with either -constant integer or undef values. -</p> +<p>The shuffle mask operand is required to be a constant vector with either + constant integer or undef values.</p> <h5>Semantics:</h5> - -<p> -The elements of the two input vectors are numbered from left to right across -both of the vectors. The shuffle mask operand specifies, for each element of -the result vector, which element of the two input vectors the result element -gets. The element selector may be undef (meaning "don't care") and the second -operand may be undef if performing a shuffle from only one vector. -</p> +<p>The elements of the two input vectors are numbered from left to right across + both of the vectors. The shuffle mask operand specifies, for each element of + the result vector, which element of the two input vectors the result element + gets. The element selector may be undef (meaning "don't care") and the + second operand may be undef if performing a shuffle from only one vector.</p> <h5>Example:</h5> - <pre> %result = shufflevector <4 x i32> %v1, <4 x i32> %v2, <4 x i32> <i32 0, i32 4, i32 1, i32 5> <i>; yields <4 x i32></i> @@ -3380,8 +3732,8 @@ operand may be undef if performing a shuffle from only one vector. %result = shufflevector <4 x i32> %v1, <4 x i32> %v2, <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > <i>; yields <8 x i32></i> </pre> -</div> +</div> <!-- ======================================================================= --> <div class="doc_subsection"> @@ -3390,8 +3742,7 @@ operand may be undef if performing a shuffle from only one vector. <div class="doc_text"> -<p>LLVM supports several instructions for working with aggregate values. -</p> +<p>LLVM supports several instructions for working with aggregate values.</p> </div> @@ -3403,43 +3754,31 @@ operand may be undef if performing a shuffle from only one vector. <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}* </pre> <h5>Overview:</h5> - -<p> -The '<tt>extractvalue</tt>' instruction extracts the value of a struct field -or array element from an aggregate value. -</p> - +<p>The '<tt>extractvalue</tt>' instruction extracts the value of a struct field + or array element from an aggregate value.</p> <h5>Arguments:</h5> - -<p> -The first operand of an '<tt>extractvalue</tt>' instruction is a -value of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> -type. The operands are constant indices to specify which value to extract -in a similar manner as indices in a -'<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. -</p> +<p>The first operand of an '<tt>extractvalue</tt>' instruction is a value + of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> type. The + operands are constant indices to specify which value to extract in a similar + manner as indices in a + '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p> <h5>Semantics:</h5> - -<p> -The result is the value at the position in the aggregate specified by -the index operands. -</p> +<p>The result is the value at the position in the aggregate specified by the + index operands.</p> <h5>Example:</h5> - <pre> %result = extractvalue {i32, float} %agg, 0 <i>; yields i32</i> </pre> -</div> +</div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> @@ -3449,46 +3788,35 @@ the index operands. <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = insertvalue <aggregate type> <val>, <ty> <val>, <idx> <i>; yields <n x <ty>></i> </pre> <h5>Overview:</h5> - -<p> -The '<tt>insertvalue</tt>' instruction inserts a value -into a struct field or array element in an aggregate. -</p> +<p>The '<tt>insertvalue</tt>' instruction inserts a value into a struct field or + array element in an aggregate.</p> <h5>Arguments:</h5> - -<p> -The first operand of an '<tt>insertvalue</tt>' instruction is a -value of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> type. -The second operand is a first-class value to insert. -The following operands are constant indices -indicating the position at which to insert the value in a similar manner as -indices in a -'<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. -The value to insert must have the same type as the value identified -by the indices. -</p> +<p>The first operand of an '<tt>insertvalue</tt>' instruction is a value + of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> type. The + second operand is a first-class value to insert. The following operands are + constant indices indicating the position at which to insert the value in a + similar manner as indices in a + '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. The + value to insert must have the same type as the value identified by the + indices.</p> <h5>Semantics:</h5> - -<p> -The result is an aggregate of the same type as <tt>val</tt>. Its -value is that of <tt>val</tt> except that the value at the position -specified by the indices is that of <tt>elt</tt>. -</p> +<p>The result is an aggregate of the same type as <tt>val</tt>. Its value is + that of <tt>val</tt> except that the value at the position specified by the + indices is that of <tt>elt</tt>.</p> <h5>Example:</h5> - <pre> %result = insertvalue {i32, float} %agg, i32 1, 0 <i>; yields {i32, float}</i> </pre> + </div> @@ -3499,10 +3827,10 @@ specified by the indices is that of <tt>elt</tt>. <div class="doc_text"> -<p>A key design point of an SSA-based representation is how it -represents memory. In LLVM, no memory locations are in SSA form, which -makes things very simple. This section describes how to read, write, -allocate, and free memory in LLVM.</p> +<p>A key design point of an SSA-based representation is how it represents + memory. In LLVM, no memory locations are in SSA form, which makes things + very simple. This section describes how to read, write, allocate, and free + memory in LLVM.</p> </div> @@ -3514,39 +3842,33 @@ allocate, and free memory in LLVM.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = malloc <type>[, i32 <NumElements>][, align <alignment>] <i>; yields {type*}:result</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>malloc</tt>' instruction allocates memory from the system -heap and returns a pointer to it. The object is always allocated in the generic -address space (address space zero).</p> +<p>The '<tt>malloc</tt>' instruction allocates memory from the system heap and + returns a pointer to it. The object is always allocated in the generic + address space (address space zero).</p> <h5>Arguments:</h5> - <p>The '<tt>malloc</tt>' instruction allocates -<tt>sizeof(<type>)*NumElements</tt> -bytes of memory from the operating system and returns a pointer of the -appropriate type to the program. If "NumElements" is specified, it is the -number of elements allocated, otherwise "NumElements" is defaulted to be one. -If a constant alignment is specified, the value result of the allocation is -guaranteed to be aligned to at least that boundary. If not specified, or if -zero, the target can choose to align the allocation on any convenient boundary -compatible with the type.</p> + <tt>sizeof(<type>)*NumElements</tt> bytes of memory from the operating + system and returns a pointer of the appropriate type to the program. If + "NumElements" is specified, it is the number of elements allocated, otherwise + "NumElements" is defaulted to be one. If a constant alignment is specified, + the value result of the allocation is guaranteed to be aligned to at least + that boundary. If not specified, or if zero, the target can choose to align + the allocation on any convenient boundary compatible with the type.</p> <p>'<tt>type</tt>' must be a sized type.</p> <h5>Semantics:</h5> - -<p>Memory is allocated using the system "<tt>malloc</tt>" function, and -a pointer is returned. The result of a zero byte allocation is undefined. The -result is null if there is insufficient memory available.</p> +<p>Memory is allocated using the system "<tt>malloc</tt>" function, and a + pointer is returned. The result of a zero byte allocation is undefined. The + result is null if there is insufficient memory available.</p> <h5>Example:</h5> - <pre> %array = malloc [4 x i8] <i>; yields {[%4 x i8]*}:array</i> @@ -3557,8 +3879,7 @@ result is null if there is insufficient memory available.</p> %array4 = malloc i32, align 1024 <i>; yields {i32*}:array4</i> </pre> -<p>Note that the code generator does not yet respect the - alignment value.</p> +<p>Note that the code generator does not yet respect the alignment value.</p> </div> @@ -3570,34 +3891,29 @@ result is null if there is insufficient memory available.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> free <type> <value> <i>; yields {void}</i> </pre> <h5>Overview:</h5> - -<p>The '<tt>free</tt>' instruction returns memory back to the unused -memory heap to be reallocated in the future.</p> +<p>The '<tt>free</tt>' instruction returns memory back to the unused memory heap + to be reallocated in the future.</p> <h5>Arguments:</h5> - -<p>'<tt>value</tt>' shall be a pointer value that points to a value -that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' -instruction.</p> +<p>'<tt>value</tt>' shall be a pointer value that points to a value that was + allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' instruction.</p> <h5>Semantics:</h5> - -<p>Access to the memory pointed to by the pointer is no longer defined -after this instruction executes. If the pointer is null, the operation -is a noop.</p> +<p>Access to the memory pointed to by the pointer is no longer defined after + this instruction executes. If the pointer is null, the operation is a + noop.</p> <h5>Example:</h5> - <pre> %array = <a href="#i_malloc">malloc</a> [4 x i8] <i>; yields {[4 x i8]*}:array</i> free [4 x i8]* %array </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3608,137 +3924,150 @@ is a noop.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = alloca <type>[, i32 <NumElements>][, align <alignment>] <i>; yields {type*}:result</i> </pre> <h5>Overview:</h5> - <p>The '<tt>alloca</tt>' instruction allocates memory on the stack frame of the -currently executing function, to be automatically released when this function -returns to its caller. The object is always allocated in the generic address -space (address space zero).</p> + currently executing function, to be automatically released when this function + returns to its caller. The object is always allocated in the generic address + space (address space zero).</p> <h5>Arguments:</h5> - -<p>The '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt> -bytes of memory on the runtime stack, returning a pointer of the -appropriate type to the program. If "NumElements" is specified, it is the -number of elements allocated, otherwise "NumElements" is defaulted to be one. -If a constant alignment is specified, the value result of the allocation is -guaranteed to be aligned to at least that boundary. If not specified, or if -zero, the target can choose to align the allocation on any convenient boundary -compatible with the type.</p> +<p>The '<tt>alloca</tt>' instruction + allocates <tt>sizeof(<type>)*NumElements</tt> bytes of memory on the + runtime stack, returning a pointer of the appropriate type to the program. + If "NumElements" is specified, it is the number of elements allocated, + otherwise "NumElements" is defaulted to be one. If a constant alignment is + specified, the value result of the allocation is guaranteed to be aligned to + at least that boundary. If not specified, or if zero, the target can choose + to align the allocation on any convenient boundary compatible with the + type.</p> <p>'<tt>type</tt>' may be any sized type.</p> <h5>Semantics:</h5> - <p>Memory is allocated; a pointer is returned. The operation is undefined if -there is insufficient stack space for the allocation. '<tt>alloca</tt>'d -memory is automatically released when the function returns. The '<tt>alloca</tt>' -instruction is commonly used to represent automatic variables that must -have an address available. When the function returns (either with the <tt><a - href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt> -instructions), the memory is reclaimed. Allocating zero bytes -is legal, but the result is undefined.</p> + there is insufficient stack space for the allocation. '<tt>alloca</tt>'d + memory is automatically released when the function returns. The + '<tt>alloca</tt>' instruction is commonly used to represent automatic + variables that must have an address available. When the function returns + (either with the <tt><a href="#i_ret">ret</a></tt> + or <tt><a href="#i_unwind">unwind</a></tt> instructions), the memory is + reclaimed. Allocating zero bytes is legal, but the result is undefined.</p> <h5>Example:</h5> - <pre> %ptr = alloca i32 <i>; yields {i32*}:ptr</i> %ptr = alloca i32, i32 4 <i>; yields {i32*}:ptr</i> %ptr = alloca i32, i32 4, align 1024 <i>; yields {i32*}:ptr</i> %ptr = alloca i32, align 1024 <i>; yields {i32*}:ptr</i> </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = load <ty>* <pointer>[, align <alignment>]<br> <result> = volatile load <ty>* <pointer>[, align <alignment>]<br></pre> +<pre> + <result> = load <ty>* <pointer>[, align <alignment>] + <result> = volatile load <ty>* <pointer>[, align <alignment>] +</pre> + <h5>Overview:</h5> <p>The '<tt>load</tt>' instruction is used to read from memory.</p> + <h5>Arguments:</h5> -<p>The argument to the '<tt>load</tt>' instruction specifies the memory -address from which to load. The pointer must point to a <a - href="#t_firstclass">first class</a> type. If the <tt>load</tt> is -marked as <tt>volatile</tt>, then the optimizer is not allowed to modify -the number or order of execution of this <tt>load</tt> with other -volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt> -instructions. </p> -<p> -The optional constant "align" argument specifies the alignment of the operation -(that is, the alignment of the memory address). A value of 0 or an -omitted "align" argument means that the operation has the preferential -alignment for the target. It is the responsibility of the code emitter -to ensure that the alignment information is correct. Overestimating -the alignment results in an undefined behavior. Underestimating the -alignment may produce less efficient code. An alignment of 1 is always -safe. -</p> +<p>The argument to the '<tt>load</tt>' instruction specifies the memory address + from which to load. The pointer must point to + a <a href="#t_firstclass">first class</a> type. If the <tt>load</tt> is + marked as <tt>volatile</tt>, then the optimizer is not allowed to modify the + number or order of execution of this <tt>load</tt> with other + volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt> + instructions. </p> + +<p>The optional constant "align" argument specifies the alignment of the + operation (that is, the alignment of the memory address). A value of 0 or an + omitted "align" argument means that the operation has the preferential + alignment for the target. It is the responsibility of the code emitter to + ensure that the alignment information is correct. Overestimating the + alignment results in an undefined behavior. Underestimating the alignment may + produce less efficient code. An alignment of 1 is always safe.</p> + <h5>Semantics:</h5> -<p>The location of memory pointed to is loaded. If the value being loaded -is of scalar type then the number of bytes read does not exceed the minimum -number of bytes needed to hold all bits of the type. For example, loading an -<tt>i24</tt> reads at most three bytes. When loading a value of a type like -<tt>i20</tt> with a size that is not an integral number of bytes, the result -is undefined if the value was not originally written using a store of the -same type.</p> +<p>The location of memory pointed to is loaded. If the value being loaded is of + scalar type then the number of bytes read does not exceed the minimum number + of bytes needed to hold all bits of the type. For example, loading an + <tt>i24</tt> reads at most three bytes. When loading a value of a type like + <tt>i20</tt> with a size that is not an integral number of bytes, the result + is undefined if the value was not originally written using a store of the + same type.</p> + <h5>Examples:</h5> -<pre> %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i> - <a - href="#i_store">store</a> i32 3, i32* %ptr <i>; yields {void}</i> +<pre> + %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i> + <a href="#i_store">store</a> i32 3, i32* %ptr <i>; yields {void}</i> %val = load i32* %ptr <i>; yields {i32}:val = i32 3</i> </pre> + </div> + <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> store <ty> <value>, <ty>* <pointer>[, align <alignment>] <i>; yields {void}</i> +<pre> + store <ty> <value>, <ty>* <pointer>[, align <alignment>] <i>; yields {void}</i> volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>] <i>; yields {void}</i> </pre> + <h5>Overview:</h5> <p>The '<tt>store</tt>' instruction is used to write to memory.</p> + <h5>Arguments:</h5> -<p>There are two arguments to the '<tt>store</tt>' instruction: a value -to store and an address at which to store it. The type of the '<tt><pointer></tt>' -operand must be a pointer to the <a href="#t_firstclass">first class</a> type -of the '<tt><value></tt>' -operand. If the <tt>store</tt> is marked as <tt>volatile</tt>, then the -optimizer is not allowed to modify the number or order of execution of -this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a - href="#i_store">store</a></tt> instructions.</p> -<p> -The optional constant "align" argument specifies the alignment of the operation -(that is, the alignment of the memory address). A value of 0 or an -omitted "align" argument means that the operation has the preferential -alignment for the target. It is the responsibility of the code emitter -to ensure that the alignment information is correct. Overestimating -the alignment results in an undefined behavior. Underestimating the -alignment may produce less efficient code. An alignment of 1 is always -safe. -</p> +<p>There are two arguments to the '<tt>store</tt>' instruction: a value to store + and an address at which to store it. The type of the + '<tt><pointer></tt>' operand must be a pointer to + the <a href="#t_firstclass">first class</a> type of the + '<tt><value></tt>' operand. If the <tt>store</tt> is marked + as <tt>volatile</tt>, then the optimizer is not allowed to modify the number + or order of execution of this <tt>store</tt> with other + volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt> + instructions.</p> + +<p>The optional constant "align" argument specifies the alignment of the + operation (that is, the alignment of the memory address). A value of 0 or an + omitted "align" argument means that the operation has the preferential + alignment for the target. It is the responsibility of the code emitter to + ensure that the alignment information is correct. Overestimating the + alignment results in an undefined behavior. Underestimating the alignment may + produce less efficient code. An alignment of 1 is always safe.</p> + <h5>Semantics:</h5> -<p>The contents of memory are updated to contain '<tt><value></tt>' -at the location specified by the '<tt><pointer></tt>' operand. -If '<tt><value></tt>' is of scalar type then the number of bytes -written does not exceed the minimum number of bytes needed to hold all -bits of the type. For example, storing an <tt>i24</tt> writes at most -three bytes. When writing a value of a type like <tt>i20</tt> with a -size that is not an integral number of bytes, it is unspecified what -happens to the extra bits that do not belong to the type, but they will -typically be overwritten.</p> +<p>The contents of memory are updated to contain '<tt><value></tt>' at the + location specified by the '<tt><pointer></tt>' operand. If + '<tt><value></tt>' is of scalar type then the number of bytes written + does not exceed the minimum number of bytes needed to hold all bits of the + type. For example, storing an <tt>i24</tt> writes at most three bytes. When + writing a value of a type like <tt>i20</tt> with a size that is not an + integral number of bytes, it is unspecified what happens to the extra bits + that do not belong to the type, but they will typically be overwritten.</p> + <h5>Example:</h5> -<pre> %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i> +<pre> + %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i> store i32 3, i32* %ptr <i>; yields {void}</i> %val = <a href="#i_load">load</a> i32* %ptr <i>; yields {i32}:val = i32 3</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3747,38 +4076,39 @@ typically be overwritten.</p> </div> <div class="doc_text"> + <h5>Syntax:</h5> <pre> <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}* + <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}* </pre> <h5>Overview:</h5> - -<p> -The '<tt>getelementptr</tt>' instruction is used to get the address of a -subelement of an aggregate data structure. It performs address calculation only -and does not access memory.</p> +<p>The '<tt>getelementptr</tt>' instruction is used to get the address of a + subelement of an aggregate data structure. It performs address calculation + only and does not access memory.</p> <h5>Arguments:</h5> - <p>The first argument is always a pointer, and forms the basis of the -calculation. The remaining arguments are indices, that indicate which of the -elements of the aggregate object are indexed. The interpretation of each index -is dependent on the type being indexed into. The first index always indexes the -pointer value given as the first argument, the second index indexes a value of -the type pointed to (not necessarily the value directly pointed to, since the -first index can be non-zero), etc. The first type indexed into must be a pointer -value, subsequent types can be arrays, vectors and structs. Note that subsequent -types being indexed into can never be pointers, since that would require loading -the pointer before continuing calculation.</p> + calculation. The remaining arguments are indices that indicate which of the + elements of the aggregate object are indexed. The interpretation of each + index is dependent on the type being indexed into. The first index always + indexes the pointer value given as the first argument, the second index + indexes a value of the type pointed to (not necessarily the value directly + pointed to, since the first index can be non-zero), etc. The first type + indexed into must be a pointer value, subsequent types can be arrays, vectors + and structs. Note that subsequent types being indexed into can never be + pointers, since that would require loading the pointer before continuing + calculation.</p> <p>The type of each index argument depends on the type it is indexing into. -When indexing into a (packed) structure, only <tt>i32</tt> integer -<b>constants</b> are allowed. When indexing into an array, pointer or vector, -integers of any width are allowed (also non-constants).</p> + When indexing into a (optionally packed) structure, only <tt>i32</tt> integer + <b>constants</b> are allowed. When indexing into an array, pointer or + vector, integers of any width are allowed, and they are not required to be + constant.</p> -<p>For example, let's consider a C code fragment and how it gets -compiled to LLVM:</p> +<p>For example, let's consider a C code fragment and how it gets compiled to + LLVM:</p> <div class="doc_code"> <pre> @@ -3806,7 +4136,7 @@ int *foo(struct ST *s) { %RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8 } %ST = <a href="#namedtypes">type</a> { i32, double, %RT } -define i32* %foo(%ST* %s) { +define i32* @foo(%ST* %s) { entry: %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13 ret i32* %reg @@ -3815,23 +4145,22 @@ entry: </div> <h5>Semantics:</h5> - <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>' -type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT -}</tt>' type, a structure. The second index indexes into the third element of -the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]], -i8 }</tt>' type, another structure. The third index indexes into the second -element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an -array. The two dimensions of the array are subscripted into, yielding an -'<tt>i32</tt>' type. The '<tt>getelementptr</tt>' instruction returns a pointer -to this element, thus computing a value of '<tt>i32*</tt>' type.</p> + type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT + }</tt>' type, a structure. The second index indexes into the third element + of the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]], + i8 }</tt>' type, another structure. The third index indexes into the second + element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an + array. The two dimensions of the array are subscripted into, yielding an + '<tt>i32</tt>' type. The '<tt>getelementptr</tt>' instruction returns a + pointer to this element, thus computing a value of '<tt>i32*</tt>' type.</p> -<p>Note that it is perfectly legal to index partially through a -structure, returning a pointer to an inner element. Because of this, -the LLVM code for the given testcase is equivalent to:</p> +<p>Note that it is perfectly legal to index partially through a structure, + returning a pointer to an inner element. Because of this, the LLVM code for + the given testcase is equivalent to:</p> <pre> - define i32* %foo(%ST* %s) { + define i32* @foo(%ST* %s) { %t1 = getelementptr %ST* %s, i32 1 <i>; yields %ST*:%t1</i> %t2 = getelementptr %ST* %t1, i32 0, i32 2 <i>; yields %RT*:%t2</i> %t3 = getelementptr %RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i> @@ -3841,20 +4170,27 @@ the LLVM code for the given testcase is equivalent to:</p> } </pre> -<p>Note that it is undefined to access an array out of bounds: array -and pointer indexes must always be within the defined bounds of the -array type when accessed with an instruction that dereferences the -pointer (e.g. a load or store instruction). The one exception for -this rule is zero length arrays. These arrays are defined to be -accessible as variable length arrays, which requires access beyond the -zero'th element.</p> +<p>If the <tt>inbounds</tt> keyword is present, the result value of the + <tt>getelementptr</tt> is undefined if the base pointer is not an + <i>in bounds</i> address of an allocated object, or if any of the addresses + that would be formed by successive addition of the offsets implied by the + indices to the base address with infinitely precise arithmetic are not an + <i>in bounds</i> address of that allocated object. + The <i>in bounds</i> addresses for an allocated object are all the addresses + that point into the object, plus the address one byte past the end.</p> -<p>The getelementptr instruction is often confusing. For some more insight -into how it works, see <a href="GetElementPtr.html">the getelementptr -FAQ</a>.</p> +<p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to + the base address with silently-wrapping two's complement arithmetic, and + the result value of the <tt>getelementptr</tt> may be outside the object + pointed to by the base pointer. The result value may not necessarily be + used to access memory though, even if it happens to point into allocated + storage. See the <a href="#pointeraliasing">Pointer Aliasing Rules</a> + section for more information.</p> -<h5>Example:</h5> +<p>The getelementptr instruction is often confusing. For some more insight into + how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p> +<h5>Example:</h5> <pre> <i>; yields [12 x i8]*:aptr</i> %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1 @@ -3865,15 +4201,19 @@ FAQ</a>.</p> <i>; yields i32*:iptr</i> %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0 </pre> + </div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="convertops">Conversion Operations</a> </div> + <div class="doc_text"> + <p>The instructions in this category are the conversion instructions (casting) -which all take a single operand and a type. They perform various bit conversions -on the operand.</p> + which all take a single operand and a type. They perform various bit + conversions on the operand.</p> + </div> <!-- _______________________________________________________________________ --> @@ -3888,24 +4228,22 @@ on the operand.</p> </pre> <h5>Overview:</h5> -<p> -The '<tt>trunc</tt>' instruction truncates its operand to the type <tt>ty2</tt>. -</p> +<p>The '<tt>trunc</tt>' instruction truncates its operand to the + type <tt>ty2</tt>.</p> <h5>Arguments:</h5> -<p> -The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must -be an <a href="#t_integer">integer</a> type, and a type that specifies the size -and type of the result, which must be an <a href="#t_integer">integer</a> -type. The bit size of <tt>value</tt> must be larger than the bit size of -<tt>ty2</tt>. Equal sized types are not allowed.</p> +<p>The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must + be an <a href="#t_integer">integer</a> type, and a type that specifies the + size and type of the result, which must be + an <a href="#t_integer">integer</a> type. The bit size of <tt>value</tt> must + be larger than the bit size of <tt>ty2</tt>. Equal sized types are not + allowed.</p> <h5>Semantics:</h5> -<p> -The '<tt>trunc</tt>' instruction truncates the high order bits in <tt>value</tt> -and converts the remaining bits to <tt>ty2</tt>. Since the source size must be -larger than the destination size, <tt>trunc</tt> cannot be a <i>no-op cast</i>. -It will always truncate bits.</p> +<p>The '<tt>trunc</tt>' instruction truncates the high order bits + in <tt>value</tt> and converts the remaining bits to <tt>ty2</tt>. Since the + source size must be larger than the destination size, <tt>trunc</tt> cannot + be a <i>no-op cast</i>. It will always truncate bits.</p> <h5>Example:</h5> <pre> @@ -3913,6 +4251,7 @@ It will always truncate bits.</p> %Y = trunc i32 123 to i1 <i>; yields i1:true</i> %Y = trunc i32 122 to i1 <i>; yields i1:false</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3928,19 +4267,19 @@ It will always truncate bits.</p> <h5>Overview:</h5> <p>The '<tt>zext</tt>' instruction zero extends its operand to type -<tt>ty2</tt>.</p> + <tt>ty2</tt>.</p> <h5>Arguments:</h5> <p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of -<a href="#t_integer">integer</a> type, and a type to cast it to, which must -also be of <a href="#t_integer">integer</a> type. The bit size of the -<tt>value</tt> must be smaller than the bit size of the destination type, -<tt>ty2</tt>.</p> + <a href="#t_integer">integer</a> type, and a type to cast it to, which must + also be of <a href="#t_integer">integer</a> type. The bit size of the + <tt>value</tt> must be smaller than the bit size of the destination type, + <tt>ty2</tt>.</p> <h5>Semantics:</h5> <p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero -bits until it reaches the size of the destination type, <tt>ty2</tt>.</p> + bits until it reaches the size of the destination type, <tt>ty2</tt>.</p> <p>When zero extending from i1, the result will always be either 0 or 1.</p> @@ -3949,6 +4288,7 @@ bits until it reaches the size of the destination type, <tt>ty2</tt>.</p> %X = zext i32 257 to i64 <i>; yields i64:257</i> %Y = zext i1 true to i32 <i>; yields i32:1</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3966,18 +4306,16 @@ bits until it reaches the size of the destination type, <tt>ty2</tt>.</p> <p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p> <h5>Arguments:</h5> -<p> -The '<tt>sext</tt>' instruction takes a value to cast, which must be of -<a href="#t_integer">integer</a> type, and a type to cast it to, which must -also be of <a href="#t_integer">integer</a> type. The bit size of the -<tt>value</tt> must be smaller than the bit size of the destination type, -<tt>ty2</tt>.</p> +<p>The '<tt>sext</tt>' instruction takes a value to cast, which must be of + <a href="#t_integer">integer</a> type, and a type to cast it to, which must + also be of <a href="#t_integer">integer</a> type. The bit size of the + <tt>value</tt> must be smaller than the bit size of the destination type, + <tt>ty2</tt>.</p> <h5>Semantics:</h5> -<p> -The '<tt>sext</tt>' instruction performs a sign extension by copying the sign -bit (highest order bit) of the <tt>value</tt> until it reaches the bit size of -the type <tt>ty2</tt>.</p> +<p>The '<tt>sext</tt>' instruction performs a sign extension by copying the sign + bit (highest order bit) of the <tt>value</tt> until it reaches the bit size + of the type <tt>ty2</tt>.</p> <p>When sign extending from i1, the extension always results in -1 or 0.</p> @@ -3986,6 +4324,7 @@ the type <tt>ty2</tt>.</p> %X = sext i8 -1 to i16 <i>; yields i16 :65535</i> %Y = sext i1 true to i32 <i>; yields i32:-1</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -3996,34 +4335,34 @@ the type <tt>ty2</tt>.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = fptrunc <ty> <value> to <ty2> <i>; yields ty2</i> </pre> <h5>Overview:</h5> <p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type -<tt>ty2</tt>.</p> - + <tt>ty2</tt>.</p> <h5>Arguments:</h5> <p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating - point</a> value to cast and a <a href="#t_floating">floating point</a> type to -cast it to. The size of <tt>value</tt> must be larger than the size of -<tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a -<i>no-op cast</i>.</p> + point</a> value to cast and a <a href="#t_floating">floating point</a> type + to cast it to. The size of <tt>value</tt> must be larger than the size of + <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a + <i>no-op cast</i>.</p> <h5>Semantics:</h5> -<p> The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger -<a href="#t_floating">floating point</a> type to a smaller -<a href="#t_floating">floating point</a> type. If the value cannot fit within -the destination type, <tt>ty2</tt>, then the results are undefined.</p> +<p>The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger + <a href="#t_floating">floating point</a> type to a smaller + <a href="#t_floating">floating point</a> type. If the value cannot fit + within the destination type, <tt>ty2</tt>, then the results are + undefined.</p> <h5>Example:</h5> <pre> %X = fptrunc double 123.0 to float <i>; yields float:123.0</i> %Y = fptrunc double 1.0E+300 to float <i>; yields undefined</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4039,26 +4378,27 @@ the destination type, <tt>ty2</tt>, then the results are undefined.</p> <h5>Overview:</h5> <p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger -floating point value.</p> + floating point value.</p> <h5>Arguments:</h5> <p>The '<tt>fpext</tt>' instruction takes a -<a href="#t_floating">floating point</a> <tt>value</tt> to cast, -and a <a href="#t_floating">floating point</a> type to cast it to. The source -type must be smaller than the destination type.</p> + <a href="#t_floating">floating point</a> <tt>value</tt> to cast, and + a <a href="#t_floating">floating point</a> type to cast it to. The source + type must be smaller than the destination type.</p> <h5>Semantics:</h5> <p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller -<a href="#t_floating">floating point</a> type to a larger -<a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be -used to make a <i>no-op cast</i> because it always changes bits. Use -<tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p> + <a href="#t_floating">floating point</a> type to a larger + <a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be + used to make a <i>no-op cast</i> because it always changes bits. Use + <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p> <h5>Example:</h5> <pre> %X = fpext float 3.1415 to double <i>; yields double:3.1415</i> %Y = fpext float 1.0 to float <i>; yields float:1.0 (no-op)</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4074,21 +4414,20 @@ used to make a <i>no-op cast</i> because it always changes bits. Use <h5>Overview:</h5> <p>The '<tt>fptoui</tt>' converts a floating point <tt>value</tt> to its -unsigned integer equivalent of type <tt>ty2</tt>. -</p> + unsigned integer equivalent of type <tt>ty2</tt>.</p> <h5>Arguments:</h5> -<p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a -scalar or vector <a href="#t_floating">floating point</a> value, and a type -to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> -type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a -vector integer type with the same number of elements as <tt>ty</tt></p> +<p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a + scalar or vector <a href="#t_floating">floating point</a> value, and a type + to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> + type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a + vector integer type with the same number of elements as <tt>ty</tt></p> <h5>Semantics:</h5> -<p> The '<tt>fptoui</tt>' instruction converts its -<a href="#t_floating">floating point</a> operand into the nearest (rounding -towards zero) unsigned integer value. If the value cannot fit in <tt>ty2</tt>, -the results are undefined.</p> +<p>The '<tt>fptoui</tt>' instruction converts its + <a href="#t_floating">floating point</a> operand into the nearest (rounding + towards zero) unsigned integer value. If the value cannot fit + in <tt>ty2</tt>, the results are undefined.</p> <h5>Example:</h5> <pre> @@ -4096,6 +4435,7 @@ the results are undefined.</p> %Y = fptoui float 1.0E+300 to i1 <i>; yields undefined:1</i> %X = fptoui float 1.04E+17 to i8 <i>; yields undefined:1</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4111,21 +4451,21 @@ the results are undefined.</p> <h5>Overview:</h5> <p>The '<tt>fptosi</tt>' instruction converts -<a href="#t_floating">floating point</a> <tt>value</tt> to type <tt>ty2</tt>. -</p> + <a href="#t_floating">floating point</a> <tt>value</tt> to + type <tt>ty2</tt>.</p> <h5>Arguments:</h5> -<p> The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a -scalar or vector <a href="#t_floating">floating point</a> value, and a type -to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> -type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a -vector integer type with the same number of elements as <tt>ty</tt></p> +<p>The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a + scalar or vector <a href="#t_floating">floating point</a> value, and a type + to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> + type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a + vector integer type with the same number of elements as <tt>ty</tt></p> <h5>Semantics:</h5> <p>The '<tt>fptosi</tt>' instruction converts its -<a href="#t_floating">floating point</a> operand into the nearest (rounding -towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>, -the results are undefined.</p> + <a href="#t_floating">floating point</a> operand into the nearest (rounding + towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>, + the results are undefined.</p> <h5>Example:</h5> <pre> @@ -4133,6 +4473,7 @@ the results are undefined.</p> %Y = fptosi float 1.0E-247 to i1 <i>; yields undefined:1</i> %X = fptosi float 1.04E+17 to i8 <i>; yields undefined:1</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4148,25 +4489,27 @@ the results are undefined.</p> <h5>Overview:</h5> <p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned -integer and converts that value to the <tt>ty2</tt> type.</p> + integer and converts that value to the <tt>ty2</tt> type.</p> <h5>Arguments:</h5> <p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be a -scalar or vector <a href="#t_integer">integer</a> value, and a type to cast it -to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a> -type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector -floating point type with the same number of elements as <tt>ty</tt></p> + scalar or vector <a href="#t_integer">integer</a> value, and a type to cast + it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a> + type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector + floating point type with the same number of elements as <tt>ty</tt></p> <h5>Semantics:</h5> <p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned -integer quantity and converts it to the corresponding floating point value. If -the value cannot fit in the floating point value, the results are undefined.</p> + integer quantity and converts it to the corresponding floating point + value. If the value cannot fit in the floating point value, the results are + undefined.</p> <h5>Example:</h5> <pre> %X = uitofp i32 257 to float <i>; yields float:257.0</i> %Y = uitofp i8 -1 to double <i>; yields double:255.0</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4181,26 +4524,27 @@ the value cannot fit in the floating point value, the results are undefined.</p> </pre> <h5>Overview:</h5> -<p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed -integer and converts that value to the <tt>ty2</tt> type.</p> +<p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed integer + and converts that value to the <tt>ty2</tt> type.</p> <h5>Arguments:</h5> <p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be a -scalar or vector <a href="#t_integer">integer</a> value, and a type to cast it -to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a> -type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector -floating point type with the same number of elements as <tt>ty</tt></p> + scalar or vector <a href="#t_integer">integer</a> value, and a type to cast + it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a> + type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector + floating point type with the same number of elements as <tt>ty</tt></p> <h5>Semantics:</h5> -<p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed -integer quantity and converts it to the corresponding floating point value. If -the value cannot fit in the floating point value, the results are undefined.</p> +<p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed integer + quantity and converts it to the corresponding floating point value. If the + value cannot fit in the floating point value, the results are undefined.</p> <h5>Example:</h5> <pre> %X = sitofp i32 257 to float <i>; yields float:257.0</i> %Y = sitofp i8 -1 to double <i>; yields double:-1.0</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4215,28 +4559,29 @@ the value cannot fit in the floating point value, the results are undefined.</p> </pre> <h5>Overview:</h5> -<p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to -the integer type <tt>ty2</tt>.</p> +<p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to + the integer type <tt>ty2</tt>.</p> <h5>Arguments:</h5> -<p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which -must be a <a href="#t_pointer">pointer</a> value, and a type to cast it to -<tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.</p> +<p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which + must be a <a href="#t_pointer">pointer</a> value, and a type to cast it to + <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.</p> <h5>Semantics:</h5> <p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type -<tt>ty2</tt> by interpreting the pointer value as an integer and either -truncating or zero extending that value to the size of the integer type. If -<tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If -<tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they -are the same size, then nothing is done (<i>no-op cast</i>) other than a type -change.</p> + <tt>ty2</tt> by interpreting the pointer value as an integer and either + truncating or zero extending that value to the size of the integer type. If + <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If + <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they + are the same size, then nothing is done (<i>no-op cast</i>) other than a type + change.</p> <h5>Example:</h5> <pre> %X = ptrtoint i32* %X to i8 <i>; yields truncation on 32-bit architecture</i> %Y = ptrtoint i32* %x to i64 <i>; yields zero extension on 32-bit architecture</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4251,21 +4596,21 @@ change.</p> </pre> <h5>Overview:</h5> -<p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to -a pointer type, <tt>ty2</tt>.</p> +<p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to a + pointer type, <tt>ty2</tt>.</p> <h5>Arguments:</h5> <p>The '<tt>inttoptr</tt>' instruction takes an <a href="#t_integer">integer</a> -value to cast, and a type to cast it to, which must be a -<a href="#t_pointer">pointer</a> type.</p> + value to cast, and a type to cast it to, which must be a + <a href="#t_pointer">pointer</a> type.</p> <h5>Semantics:</h5> <p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type -<tt>ty2</tt> by applying either a zero extension or a truncation depending on -the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the -size of a pointer then a truncation is done. If <tt>value</tt> is smaller than -the size of a pointer then a zero extension is done. If they are the same size, -nothing is done (<i>no-op cast</i>).</p> + <tt>ty2</tt> by applying either a zero extension or a truncation depending on + the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the + size of a pointer then a truncation is done. If <tt>value</tt> is smaller + than the size of a pointer then a zero extension is done. If they are the + same size, nothing is done (<i>no-op cast</i>).</p> <h5>Example:</h5> <pre> @@ -4273,6 +4618,7 @@ nothing is done (<i>no-op cast</i>).</p> %X = inttoptr i32 255 to i32* <i>; yields no-op on 32-bit architecture</i> %Y = inttoptr i64 0 to i32* <i>; yields truncation on 32-bit architecture</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4287,29 +4633,27 @@ nothing is done (<i>no-op cast</i>).</p> </pre> <h5>Overview:</h5> - <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type -<tt>ty2</tt> without changing any bits.</p> + <tt>ty2</tt> without changing any bits.</p> <h5>Arguments:</h5> - -<p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be -a non-aggregate first class value, and a type to cast it to, which must also be -a non-aggregate <a href="#t_firstclass">first class</a> type. The bit sizes of -<tt>value</tt> -and the destination type, <tt>ty2</tt>, must be identical. If the source -type is a pointer, the destination type must also be a pointer. This -instruction supports bitwise conversion of vectors to integers and to vectors -of other types (as long as they have the same size).</p> +<p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be a + non-aggregate first class value, and a type to cast it to, which must also be + a non-aggregate <a href="#t_firstclass">first class</a> type. The bit sizes + of <tt>value</tt> and the destination type, <tt>ty2</tt>, must be + identical. If the source type is a pointer, the destination type must also be + a pointer. This instruction supports bitwise conversion of vectors to + integers and to vectors of other types (as long as they have the same + size).</p> <h5>Semantics:</h5> <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type -<tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with -this conversion. The conversion is done as if the <tt>value</tt> had been -stored to memory and read back as type <tt>ty2</tt>. Pointer types may only be -converted to other pointer types with this instruction. To convert pointers to -other types, use the <a href="#i_inttoptr">inttoptr</a> or -<a href="#i_ptrtoint">ptrtoint</a> instructions first.</p> + <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with + this conversion. The conversion is done as if the <tt>value</tt> had been + stored to memory and read back as type <tt>ty2</tt>. Pointer types may only + be converted to other pointer types with this instruction. To convert + pointers to other types, use the <a href="#i_inttoptr">inttoptr</a> or + <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p> <h5>Example:</h5> <pre> @@ -4317,31 +4661,40 @@ other types, use the <a href="#i_inttoptr">inttoptr</a> or %Y = bitcast i32* %x to sint* <i>; yields sint*:%x</i> %Z = bitcast <2 x int> %V to i64; <i>; yields i64: %V</i> </pre> + </div> <!-- ======================================================================= --> <div class="doc_subsection"> <a name="otherops">Other Operations</a> </div> + <div class="doc_text"> -<p>The instructions in this category are the "miscellaneous" -instructions, which defy better classification.</p> + +<p>The instructions in this category are the "miscellaneous" instructions, which + defy better classification.</p> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"><a name="i_icmp">'<tt>icmp</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = icmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i> +<pre> + <result> = icmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>icmp</tt>' instruction returns a boolean value or -a vector of boolean values based on comparison -of its two integer, integer vector, or pointer operands.</p> +<p>The '<tt>icmp</tt>' instruction returns a boolean value or a vector of + boolean values based on comparison of its two integer, integer vector, or + pointer operands.</p> + <h5>Arguments:</h5> <p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is -the condition code indicating the kind of comparison to perform. It is not -a value, just a keyword. The possible condition code are: -</p> + the condition code indicating the kind of comparison to perform. It is not a + value, just a keyword. The possible condition code are:</p> + <ol> <li><tt>eq</tt>: equal</li> <li><tt>ne</tt>: not equal </li> @@ -4354,48 +4707,63 @@ a value, just a keyword. The possible condition code are: <li><tt>slt</tt>: signed less than</li> <li><tt>sle</tt>: signed less or equal</li> </ol> + <p>The remaining two arguments must be <a href="#t_integer">integer</a> or -<a href="#t_pointer">pointer</a> -or integer <a href="#t_vector">vector</a> typed. -They must also be identical types.</p> + <a href="#t_pointer">pointer</a> or integer <a href="#t_vector">vector</a> + typed. They must also be identical types.</p> + <h5>Semantics:</h5> -<p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to -the condition code given as <tt>cond</tt>. The comparison performed always -yields either an <a href="#t_primitive"><tt>i1</tt></a> or vector of <tt>i1</tt> result, as follows: -</p> +<p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to the + condition code given as <tt>cond</tt>. The comparison performed always yields + either an <a href="#t_integer"><tt>i1</tt></a> or vector of <tt>i1</tt> + result, as follows:</p> + <ol> <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal, - <tt>false</tt> otherwise. No sign interpretation is necessary or performed. - </li> + <tt>false</tt> otherwise. No sign interpretation is necessary or + performed.</li> + <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal, - <tt>false</tt> otherwise. No sign interpretation is necessary or performed.</li> + <tt>false</tt> otherwise. No sign interpretation is necessary or + performed.</li> + <li><tt>ugt</tt>: interprets the operands as unsigned values and yields - <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <li><tt>uge</tt>: interprets the operands as unsigned values and yields - <tt>true</tt> if <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is greater than or equal + to <tt>op2</tt>.</li> + <li><tt>ult</tt>: interprets the operands as unsigned values and yields - <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li> + <li><tt>ule</tt>: interprets the operands as unsigned values and yields - <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <li><tt>sgt</tt>: interprets the operands as signed values and yields - <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <li><tt>sge</tt>: interprets the operands as signed values and yields - <tt>true</tt> if <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is greater than or equal + to <tt>op2</tt>.</li> + <li><tt>slt</tt>: interprets the operands as signed values and yields - <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li> + <li><tt>sle</tt>: interprets the operands as signed values and yields - <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> </ol> + <p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer -values are compared as if they were integers.</p> -<p>If the operands are integer vectors, then they are compared -element by element. The result is an <tt>i1</tt> vector with -the same number of elements as the values being compared. -Otherwise, the result is an <tt>i1</tt>. -</p> + values are compared as if they were integers.</p> + +<p>If the operands are integer vectors, then they are compared element by + element. The result is an <tt>i1</tt> vector with the same number of elements + as the values being compared. Otherwise, the result is an <tt>i1</tt>.</p> <h5>Example:</h5> -<pre> <result> = icmp eq i32 4, 5 <i>; yields: result=false</i> +<pre> + <result> = icmp eq i32 4, 5 <i>; yields: result=false</i> <result> = icmp ne float* %X, %X <i>; yields: result=false</i> <result> = icmp ult i16 4, 5 <i>; yields: result=true</i> <result> = icmp sgt i16 4, 5 <i>; yields: result=false</i> @@ -4411,25 +4779,30 @@ Otherwise, the result is an <tt>i1</tt>. <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"><a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<pre> <result> = fcmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i> +<pre> + <result> = fcmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i> </pre> + <h5>Overview:</h5> -<p>The '<tt>fcmp</tt>' instruction returns a boolean value -or vector of boolean values based on comparison -of its operands.</p> -<p> -If the operands are floating point scalars, then the result -type is a boolean (<a href="#t_primitive"><tt>i1</tt></a>). -</p> -<p>If the operands are floating point vectors, then the result type -is a vector of boolean with the same number of elements as the -operands being compared.</p> +<p>The '<tt>fcmp</tt>' instruction returns a boolean value or vector of boolean + values based on comparison of its operands.</p> + +<p>If the operands are floating point scalars, then the result type is a boolean +(<a href="#t_integer"><tt>i1</tt></a>).</p> + +<p>If the operands are floating point vectors, then the result type is a vector + of boolean with the same number of elements as the operands being + compared.</p> + <h5>Arguments:</h5> <p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is -the condition code indicating the kind of comparison to perform. It is not -a value, just a keyword. The possible condition code are:</p> + the condition code indicating the kind of comparison to perform. It is not a + value, just a keyword. The possible condition code are:</p> + <ol> <li><tt>false</tt>: no comparison, always returns false</li> <li><tt>oeq</tt>: ordered and equal</li> @@ -4448,52 +4821,71 @@ a value, just a keyword. The possible condition code are:</p> <li><tt>uno</tt>: unordered (either nans)</li> <li><tt>true</tt>: no comparison, always returns true</li> </ol> + <p><i>Ordered</i> means that neither operand is a QNAN while -<i>unordered</i> means that either operand may be a QNAN.</p> -<p>Each of <tt>val1</tt> and <tt>val2</tt> arguments must be -either a <a href="#t_floating">floating point</a> type -or a <a href="#t_vector">vector</a> of floating point type. -They must have identical types.</p> + <i>unordered</i> means that either operand may be a QNAN.</p> + +<p>Each of <tt>val1</tt> and <tt>val2</tt> arguments must be either + a <a href="#t_floating">floating point</a> type or + a <a href="#t_vector">vector</a> of floating point type. They must have + identical types.</p> + <h5>Semantics:</h5> <p>The '<tt>fcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt> -according to the condition code given as <tt>cond</tt>. -If the operands are vectors, then the vectors are compared -element by element. -Each comparison performed -always yields an <a href="#t_primitive">i1</a> result, as follows:</p> + according to the condition code given as <tt>cond</tt>. If the operands are + vectors, then the vectors are compared element by element. Each comparison + performed always yields an <a href="#t_integer">i1</a> result, as + follows:</p> + <ol> <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li> + <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is equal to <tt>op2</tt>.</li> + <tt>op1</tt> is equal to <tt>op2</tt>.</li> + <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is greather than <tt>op2</tt>.</li> + <tt>op1</tt> is greather than <tt>op2</tt>.</li> + <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is less than <tt>op2</tt>.</li> + <tt>op1</tt> is less than <tt>op2</tt>.</li> + <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and - <tt>op1</tt> is not equal to <tt>op2</tt>.</li> + <tt>op1</tt> is not equal to <tt>op2</tt>.</li> + <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li> + <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is equal to <tt>op2</tt>.</li> + <tt>op1</tt> is equal to <tt>op2</tt>.</li> + <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <tt>op1</tt> is greater than <tt>op2</tt>.</li> + <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> + <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is less than <tt>op2</tt>.</li> + <tt>op1</tt> is less than <tt>op2</tt>.</li> + <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> + <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or - <tt>op1</tt> is not equal to <tt>op2</tt>.</li> + <tt>op1</tt> is not equal to <tt>op2</tt>.</li> + <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li> + <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li> </ol> <h5>Example:</h5> -<pre> <result> = fcmp oeq float 4.0, 5.0 <i>; yields: result=false</i> +<pre> + <result> = fcmp oeq float 4.0, 5.0 <i>; yields: result=false</i> <result> = fcmp one float 4.0, 5.0 <i>; yields: result=true</i> <result> = fcmp olt float 4.0, 5.0 <i>; yields: result=true</i> <result> = fcmp ueq double 1.0, 2.0 <i>; yields: result=false</i> @@ -4506,143 +4898,41 @@ always yields an <a href="#t_primitive">i1</a> result, as follows:</p> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="i_vicmp">'<tt>vicmp</tt>' Instruction</a> -</div> -<div class="doc_text"> -<h5>Syntax:</h5> -<pre> <result> = vicmp <cond> <ty> <op1>, <op2> <i>; yields {ty}:result</i> -</pre> -<h5>Overview:</h5> -<p>The '<tt>vicmp</tt>' instruction returns an integer vector value based on -element-wise comparison of its two integer vector operands.</p> -<h5>Arguments:</h5> -<p>The '<tt>vicmp</tt>' instruction takes three operands. The first operand is -the condition code indicating the kind of comparison to perform. It is not -a value, just a keyword. The possible condition code are:</p> -<ol> - <li><tt>eq</tt>: equal</li> - <li><tt>ne</tt>: not equal </li> - <li><tt>ugt</tt>: unsigned greater than</li> - <li><tt>uge</tt>: unsigned greater or equal</li> - <li><tt>ult</tt>: unsigned less than</li> - <li><tt>ule</tt>: unsigned less or equal</li> - <li><tt>sgt</tt>: signed greater than</li> - <li><tt>sge</tt>: signed greater or equal</li> - <li><tt>slt</tt>: signed less than</li> - <li><tt>sle</tt>: signed less or equal</li> -</ol> -<p>The remaining two arguments must be <a href="#t_vector">vector</a> or -<a href="#t_integer">integer</a> typed. They must also be identical types.</p> -<h5>Semantics:</h5> -<p>The '<tt>vicmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt> -according to the condition code given as <tt>cond</tt>. The comparison yields a -<a href="#t_vector">vector</a> of <a href="#t_integer">integer</a> result, of -identical type as the values being compared. The most significant bit in each -element is 1 if the element-wise comparison evaluates to true, and is 0 -otherwise. All other bits of the result are undefined. The condition codes -are evaluated identically to the <a href="#i_icmp">'<tt>icmp</tt>' -instruction</a>.</p> - -<h5>Example:</h5> -<pre> - <result> = vicmp eq <2 x i32> < i32 4, i32 0>, < i32 5, i32 0> <i>; yields: result=<2 x i32> < i32 0, i32 -1 ></i> - <result> = vicmp ult <2 x i8 > < i8 1, i8 2>, < i8 2, i8 2 > <i>; yields: result=<2 x i8> < i8 -1, i8 0 ></i> -</pre> -</div> - -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> - <a name="i_vfcmp">'<tt>vfcmp</tt>' Instruction</a> -</div> -<div class="doc_text"> -<h5>Syntax:</h5> -<pre> <result> = vfcmp <cond> <ty> <op1>, <op2></pre> -<h5>Overview:</h5> -<p>The '<tt>vfcmp</tt>' instruction returns an integer vector value based on -element-wise comparison of its two floating point vector operands. The output -elements have the same width as the input elements.</p> -<h5>Arguments:</h5> -<p>The '<tt>vfcmp</tt>' instruction takes three operands. The first operand is -the condition code indicating the kind of comparison to perform. It is not -a value, just a keyword. The possible condition code are:</p> -<ol> - <li><tt>false</tt>: no comparison, always returns false</li> - <li><tt>oeq</tt>: ordered and equal</li> - <li><tt>ogt</tt>: ordered and greater than </li> - <li><tt>oge</tt>: ordered and greater than or equal</li> - <li><tt>olt</tt>: ordered and less than </li> - <li><tt>ole</tt>: ordered and less than or equal</li> - <li><tt>one</tt>: ordered and not equal</li> - <li><tt>ord</tt>: ordered (no nans)</li> - <li><tt>ueq</tt>: unordered or equal</li> - <li><tt>ugt</tt>: unordered or greater than </li> - <li><tt>uge</tt>: unordered or greater than or equal</li> - <li><tt>ult</tt>: unordered or less than </li> - <li><tt>ule</tt>: unordered or less than or equal</li> - <li><tt>une</tt>: unordered or not equal</li> - <li><tt>uno</tt>: unordered (either nans)</li> - <li><tt>true</tt>: no comparison, always returns true</li> -</ol> -<p>The remaining two arguments must be <a href="#t_vector">vector</a> of -<a href="#t_floating">floating point</a> typed. They must also be identical -types.</p> -<h5>Semantics:</h5> -<p>The '<tt>vfcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt> -according to the condition code given as <tt>cond</tt>. The comparison yields a -<a href="#t_vector">vector</a> of <a href="#t_integer">integer</a> result, with -an identical number of elements as the values being compared, and each element -having identical with to the width of the floating point elements. The most -significant bit in each element is 1 if the element-wise comparison evaluates to -true, and is 0 otherwise. All other bits of the result are undefined. The -condition codes are evaluated identically to the -<a href="#i_fcmp">'<tt>fcmp</tt>' instruction</a>.</p> - -<h5>Example:</h5> -<pre> - <i>; yields: result=<2 x i32> < i32 0, i32 -1 ></i> - <result> = vfcmp oeq <2 x float> < float 4, float 0 >, < float 5, float 0 > - - <i>; yields: result=<2 x i64> < i64 -1, i64 0 ></i> - <result> = vfcmp ult <2 x double> < double 1, double 2 >, < double 2, double 2> -</pre> -</div> - -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>' Instruction</a> </div> <div class="doc_text"> <h5>Syntax:</h5> +<pre> + <result> = phi <ty> [ <val0>, <label0>], ... +</pre> -<pre> <result> = phi <ty> [ <val0>, <label0>], ...<br></pre> <h5>Overview:</h5> -<p>The '<tt>phi</tt>' instruction is used to implement the φ node in -the SSA graph representing the function.</p> -<h5>Arguments:</h5> - -<p>The type of the incoming values is specified with the first type -field. After this, the '<tt>phi</tt>' instruction takes a list of pairs -as arguments, with one pair for each predecessor basic block of the -current block. Only values of <a href="#t_firstclass">first class</a> -type may be used as the value arguments to the PHI node. Only labels -may be used as the label arguments.</p> - -<p>There must be no non-phi instructions between the start of a basic -block and the PHI instructions: i.e. PHI instructions must be first in -a basic block.</p> +<p>The '<tt>phi</tt>' instruction is used to implement the φ node in the + SSA graph representing the function.</p> -<p>For the purposes of the SSA form, the use of each incoming value is -deemed to occur on the edge from the corresponding predecessor block -to the current block (but after any definition of an '<tt>invoke</tt>' -instruction's return value on the same edge).</p> +<h5>Arguments:</h5> +<p>The type of the incoming values is specified with the first type field. After + this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with + one pair for each predecessor basic block of the current block. Only values + of <a href="#t_firstclass">first class</a> type may be used as the value + arguments to the PHI node. Only labels may be used as the label + arguments.</p> + +<p>There must be no non-phi instructions between the start of a basic block and + the PHI instructions: i.e. PHI instructions must be first in a basic + block.</p> + +<p>For the purposes of the SSA form, the use of each incoming value is deemed to + occur on the edge from the corresponding predecessor block to the current + block (but after any definition of an '<tt>invoke</tt>' instruction's return + value on the same edge).</p> <h5>Semantics:</h5> - <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value -specified by the pair corresponding to the predecessor basic block that executed -just prior to the current block.</p> + specified by the pair corresponding to the predecessor basic block that + executed just prior to the current block.</p> <h5>Example:</h5> <pre> @@ -4651,6 +4941,7 @@ Loop: ; Infinite loop that counts from 0 on up... %nextindvar = add i32 %indvar, 1 br label %Loop </pre> + </div> <!-- _______________________________________________________________________ --> @@ -4661,7 +4952,6 @@ Loop: ; Infinite loop that counts from 0 on up... <div class="doc_text"> <h5>Syntax:</h5> - <pre> <result> = select <i>selty</i> <cond>, <ty> <val1>, <ty> <val2> <i>; yields ty</i> @@ -4669,38 +4959,25 @@ Loop: ; Infinite loop that counts from 0 on up... </pre> <h5>Overview:</h5> - -<p> -The '<tt>select</tt>' instruction is used to choose one value based on a -condition, without branching. -</p> +<p>The '<tt>select</tt>' instruction is used to choose one value based on a + condition, without branching.</p> <h5>Arguments:</h5> - -<p> -The '<tt>select</tt>' instruction requires an 'i1' value or -a vector of 'i1' values indicating the -condition, and two values of the same <a href="#t_firstclass">first class</a> -type. If the val1/val2 are vectors and -the condition is a scalar, then entire vectors are selected, not -individual elements. -</p> +<p>The '<tt>select</tt>' instruction requires an 'i1' value or a vector of 'i1' + values indicating the condition, and two values of the + same <a href="#t_firstclass">first class</a> type. If the val1/val2 are + vectors and the condition is a scalar, then entire vectors are selected, not + individual elements.</p> <h5>Semantics:</h5> +<p>If the condition is an i1 and it evaluates to 1, the instruction returns the + first value argument; otherwise, it returns the second value argument.</p> -<p> -If the condition is an i1 and it evaluates to 1, the instruction returns the first -value argument; otherwise, it returns the second value argument. -</p> -<p> -If the condition is a vector of i1, then the value arguments must -be vectors of the same size, and the selection is done element -by element. -</p> +<p>If the condition is a vector of i1, then the value arguments must be vectors + of the same size, and the selection is done element by element.</p> <h5>Example:</h5> - <pre> %X = select i1 true, i8 17, i8 42 <i>; yields i8:17</i> </pre> @@ -4710,7 +4987,6 @@ by element. </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="i_call">'<tt>call</tt>' Instruction</a> @@ -4724,75 +5000,60 @@ by element. </pre> <h5>Overview:</h5> - <p>The '<tt>call</tt>' instruction represents a simple function call.</p> <h5>Arguments:</h5> - <p>This instruction requires several arguments:</p> <ol> - <li> - <p>The optional "tail" marker indicates whether the callee function accesses - any allocas or varargs in the caller. If the "tail" marker is present, the - function call is eligible for tail call optimization. Note that calls may - be marked "tail" even if they do not occur before a <a - href="#i_ret"><tt>ret</tt></a> instruction.</p> - </li> - <li> - <p>The optional "cconv" marker indicates which <a href="#callingconv">calling - convention</a> the call should use. If none is specified, the call defaults - to using C calling conventions.</p> - </li> + <li>The optional "tail" marker indicates whether the callee function accesses + any allocas or varargs in the caller. If the "tail" marker is present, + the function call is eligible for tail call optimization. Note that calls + may be marked "tail" even if they do not occur before + a <a href="#i_ret"><tt>ret</tt></a> instruction.</li> - <li> - <p>The optional <a href="#paramattrs">Parameter Attributes</a> list for - return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', - and '<tt>inreg</tt>' attributes are valid here.</p> - </li> + <li>The optional "cconv" marker indicates which <a href="#callingconv">calling + convention</a> the call should use. If none is specified, the call + defaults to using C calling conventions.</li> - <li> - <p>'<tt>ty</tt>': the type of the call instruction itself which is also - the type of the return value. Functions that return no value are marked - <tt><a href="#t_void">void</a></tt>.</p> - </li> - <li> - <p>'<tt>fnty</tt>': shall be the signature of the pointer to function - value being invoked. The argument types must match the types implied by - this signature. This type can be omitted if the function is not varargs - and if the function type does not return a pointer to a function.</p> - </li> - <li> - <p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to - be invoked. In most cases, this is a direct function invocation, but - indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer - to function value.</p> - </li> - <li> - <p>'<tt>function args</tt>': argument list whose types match the - function signature argument types. All arguments must be of - <a href="#t_firstclass">first class</a> type. If the function signature - indicates the function accepts a variable number of arguments, the extra - arguments can be specified.</p> - </li> - <li> - <p>The optional <a href="#fnattrs">function attributes</a> list. Only - '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and - '<tt>readnone</tt>' attributes are valid here.</p> - </li> + <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for + return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and + '<tt>inreg</tt>' attributes are valid here.</li> + + <li>'<tt>ty</tt>': the type of the call instruction itself which is also the + type of the return value. Functions that return no value are marked + <tt><a href="#t_void">void</a></tt>.</li> + + <li>'<tt>fnty</tt>': shall be the signature of the pointer to function value + being invoked. The argument types must match the types implied by this + signature. This type can be omitted if the function is not varargs and if + the function type does not return a pointer to a function.</li> + + <li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to + be invoked. In most cases, this is a direct function invocation, but + indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer + to function value.</li> + + <li>'<tt>function args</tt>': argument list whose types match the function + signature argument types. All arguments must be of + <a href="#t_firstclass">first class</a> type. If the function signature + indicates the function accepts a variable number of arguments, the extra + arguments can be specified.</li> + + <li>The optional <a href="#fnattrs">function attributes</a> list. Only + '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and + '<tt>readnone</tt>' attributes are valid here.</li> </ol> <h5>Semantics:</h5> - -<p>The '<tt>call</tt>' instruction is used to cause control flow to -transfer to a specified function, with its incoming arguments bound to -the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>' -instruction in the called function, control flow continues with the -instruction after the function call, and the return value of the -function is bound to the result argument.</p> +<p>The '<tt>call</tt>' instruction is used to cause control flow to transfer to + a specified function, with its incoming arguments bound to the specified + values. Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called + function, control flow continues with the instruction after the function + call, and the return value of the function is bound to the result + argument.</p> <h5>Example:</h5> - <pre> %retval = call i32 @test(i32 %argc) call i32 (i8 *, ...)* @printf(i8 * %msg, i32 12, i8 42) <i>; yields i32</i> @@ -4808,6 +5069,12 @@ function is bound to the result argument.</p> %ZZ = call zeroext i32 @bar() <i>; Return value is %zero extended</i> </pre> +<p>llvm treats calls to some functions with names and arguments that match the +standard C99 library as being the C99 library functions, and may perform +optimizations or generate code for them under that assumption. This is +something we'd like to change in the future to provide better support for +freestanding environments and non-C-based langauges.</p> + </div> <!-- _______________________________________________________________________ --> @@ -4818,47 +5085,41 @@ function is bound to the result argument.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> <resultval> = va_arg <va_list*> <arglist>, <argty> </pre> <h5>Overview:</h5> - <p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through -the "variable argument" area of a function call. It is used to implement the -<tt>va_arg</tt> macro in C.</p> + the "variable argument" area of a function call. It is used to implement the + <tt>va_arg</tt> macro in C.</p> <h5>Arguments:</h5> - -<p>This instruction takes a <tt>va_list*</tt> value and the type of -the argument. It returns a value of the specified argument type and -increments the <tt>va_list</tt> to point to the next argument. The -actual type of <tt>va_list</tt> is target specific.</p> +<p>This instruction takes a <tt>va_list*</tt> value and the type of the + argument. It returns a value of the specified argument type and increments + the <tt>va_list</tt> to point to the next argument. The actual type + of <tt>va_list</tt> is target specific.</p> <h5>Semantics:</h5> - -<p>The '<tt>va_arg</tt>' instruction loads an argument of the specified -type from the specified <tt>va_list</tt> and causes the -<tt>va_list</tt> to point to the next argument. For more information, -see the variable argument handling <a href="#int_varargs">Intrinsic -Functions</a>.</p> +<p>The '<tt>va_arg</tt>' instruction loads an argument of the specified type + from the specified <tt>va_list</tt> and causes the <tt>va_list</tt> to point + to the next argument. For more information, see the variable argument + handling <a href="#int_varargs">Intrinsic Functions</a>.</p> <p>It is legal for this instruction to be called in a function which does not -take a variable number of arguments, for example, the <tt>vfprintf</tt> -function.</p> + take a variable number of arguments, for example, the <tt>vfprintf</tt> + function.</p> -<p><tt>va_arg</tt> is an LLVM instruction instead of an <a -href="#intrinsics">intrinsic function</a> because it takes a type as an -argument.</p> +<p><tt>va_arg</tt> is an LLVM instruction instead of + an <a href="#intrinsics">intrinsic function</a> because it takes a type as an + argument.</p> <h5>Example:</h5> - <p>See the <a href="#int_varargs">variable argument processing</a> section.</p> -<p>Note that the code generator does not yet fully support va_arg - on many targets. Also, it does not currently support va_arg with - aggregate types on any target.</p> +<p>Note that the code generator does not yet fully support va_arg on many + targets. Also, it does not currently support va_arg with aggregate types on + any target.</p> </div> @@ -4869,45 +5130,45 @@ argument.</p> <div class="doc_text"> <p>LLVM supports the notion of an "intrinsic function". These functions have -well known names and semantics and are required to follow certain restrictions. -Overall, these intrinsics represent an extension mechanism for the LLVM -language that does not require changing all of the transformations in LLVM when -adding to the language (or the bitcode reader/writer, the parser, etc...).</p> + well known names and semantics and are required to follow certain + restrictions. Overall, these intrinsics represent an extension mechanism for + the LLVM language that does not require changing all of the transformations + in LLVM when adding to the language (or the bitcode reader/writer, the + parser, etc...).</p> <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This -prefix is reserved in LLVM for intrinsic names; thus, function names may not -begin with this prefix. Intrinsic functions must always be external functions: -you cannot define the body of intrinsic functions. Intrinsic functions may -only be used in call or invoke instructions: it is illegal to take the address -of an intrinsic function. Additionally, because intrinsic functions are part -of the LLVM language, it is required if any are added that they be documented -here.</p> - -<p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents -a family of functions that perform the same operation but on different data -types. Because LLVM can represent over 8 million different integer types, -overloading is used commonly to allow an intrinsic function to operate on any -integer type. One or more of the argument types or the result type can be -overloaded to accept any integer type. Argument types may also be defined as -exactly matching a previous argument's type or the result type. This allows an -intrinsic function which accepts multiple arguments, but needs all of them to -be of the same type, to only be overloaded with respect to a single argument or -the result.</p> - -<p>Overloaded intrinsics will have the names of its overloaded argument types -encoded into its function name, each preceded by a period. Only those types -which are overloaded result in a name suffix. Arguments whose type is matched -against another type do not. For example, the <tt>llvm.ctpop</tt> function can -take an integer of any width and returns an integer of exactly the same integer -width. This leads to a family of functions such as -<tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29 %val)</tt>. -Only one type, the return type, is overloaded, and only one type suffix is -required. Because the argument's type is matched against the return type, it -does not require its own name suffix.</p> + prefix is reserved in LLVM for intrinsic names; thus, function names may not + begin with this prefix. Intrinsic functions must always be external + functions: you cannot define the body of intrinsic functions. Intrinsic + functions may only be used in call or invoke instructions: it is illegal to + take the address of an intrinsic function. Additionally, because intrinsic + functions are part of the LLVM language, it is required if any are added that + they be documented here.</p> + +<p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents a + family of functions that perform the same operation but on different data + types. Because LLVM can represent over 8 million different integer types, + overloading is used commonly to allow an intrinsic function to operate on any + integer type. One or more of the argument types or the result type can be + overloaded to accept any integer type. Argument types may also be defined as + exactly matching a previous argument's type or the result type. This allows + an intrinsic function which accepts multiple arguments, but needs all of them + to be of the same type, to only be overloaded with respect to a single + argument or the result.</p> + +<p>Overloaded intrinsics will have the names of its overloaded argument types + encoded into its function name, each preceded by a period. Only those types + which are overloaded result in a name suffix. Arguments whose type is matched + against another type do not. For example, the <tt>llvm.ctpop</tt> function + can take an integer of any width and returns an integer of exactly the same + integer width. This leads to a family of functions such as + <tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29 + %val)</tt>. Only one type, the return type, is overloaded, and only one type + suffix is required. Because the argument's type is matched against the return + type, it does not require its own name suffix.</p> <p>To learn how to add an intrinsic function, please see the -<a href="ExtendingLLVM.html">Extending LLVM Guide</a>. -</p> + <a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p> </div> @@ -4918,20 +5179,19 @@ does not require its own name suffix.</p> <div class="doc_text"> -<p>Variable argument support is defined in LLVM with the <a - href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three -intrinsic functions. These functions are related to the similarly -named macros defined in the <tt><stdarg.h></tt> header file.</p> +<p>Variable argument support is defined in LLVM with + the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three + intrinsic functions. These functions are related to the similarly named + macros defined in the <tt><stdarg.h></tt> header file.</p> -<p>All of these functions operate on arguments that use a -target-specific value type "<tt>va_list</tt>". The LLVM assembly -language reference manual does not define what this type is, so all -transformations should be prepared to handle these functions regardless of -the type used.</p> +<p>All of these functions operate on arguments that use a target-specific value + type "<tt>va_list</tt>". The LLVM assembly language reference manual does + not define what this type is, so all transformations should be prepared to + handle these functions regardless of the type used.</p> <p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a> -instruction and the variable argument handling intrinsic functions are -used.</p> + instruction and the variable argument handling intrinsic functions are + used.</p> <div class="doc_code"> <pre> @@ -4970,25 +5230,27 @@ declare void @llvm.va_end(i8*) <div class="doc_text"> + <h5>Syntax:</h5> -<pre> declare void %llvm.va_start(i8* <arglist>)<br></pre> +<pre> + declare void %llvm.va_start(i8* <arglist>) +</pre> + <h5>Overview:</h5> -<p>The '<tt>llvm.va_start</tt>' intrinsic initializes -<tt>*<arglist></tt> for subsequent use by <tt><a -href="#i_va_arg">va_arg</a></tt>.</p> +<p>The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*<arglist></tt> + for subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt>.</p> <h5>Arguments:</h5> - <p>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt> -macro available in C. In a target-dependent way, it initializes the -<tt>va_list</tt> element to which the argument points, so that the next call to -<tt>va_arg</tt> will produce the first variable argument passed to the function. -Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the -last argument of the function as the compiler can figure that out.</p> + macro available in C. In a target-dependent way, it initializes + the <tt>va_list</tt> element to which the argument points, so that the next + call to <tt>va_arg</tt> will produce the first variable argument passed to + the function. Unlike the C <tt>va_start</tt> macro, this intrinsic does not + need to know the last argument of the function as the compiler can figure + that out.</p> </div> @@ -4998,26 +5260,28 @@ last argument of the function as the compiler can figure that out.</p> </div> <div class="doc_text"> + <h5>Syntax:</h5> -<pre> declare void @llvm.va_end(i8* <arglist>)<br></pre> -<h5>Overview:</h5> +<pre> + declare void @llvm.va_end(i8* <arglist>) +</pre> +<h5>Overview:</h5> <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*<arglist></tt>, -which has been initialized previously with <tt><a href="#int_va_start">llvm.va_start</a></tt> -or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p> + which has been initialized previously + with <tt><a href="#int_va_start">llvm.va_start</a></tt> + or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p> <h5>Arguments:</h5> - <p>The argument is a pointer to a <tt>va_list</tt> to destroy.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt> -macro available in C. In a target-dependent way, it destroys the -<tt>va_list</tt> element to which the argument points. Calls to <a -href="#int_va_start"><tt>llvm.va_start</tt></a> and <a href="#int_va_copy"> -<tt>llvm.va_copy</tt></a> must be matched exactly with calls to -<tt>llvm.va_end</tt>.</p> + macro available in C. In a target-dependent way, it destroys + the <tt>va_list</tt> element to which the argument points. Calls + to <a href="#int_va_start"><tt>llvm.va_start</tt></a> + and <a href="#int_va_copy"> <tt>llvm.va_copy</tt></a> must be matched exactly + with calls to <tt>llvm.va_end</tt>.</p> </div> @@ -5029,30 +5293,26 @@ href="#int_va_start"><tt>llvm.va_start</tt></a> and <a href="#int_va_copy"> <div class="doc_text"> <h5>Syntax:</h5> - <pre> declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>) </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position -from the source argument list to the destination argument list.</p> + from the source argument list to the destination argument list.</p> <h5>Arguments:</h5> - <p>The first argument is a pointer to a <tt>va_list</tt> element to initialize. -The second argument is a pointer to a <tt>va_list</tt> element to copy from.</p> - + The second argument is a pointer to a <tt>va_list</tt> element to copy + from.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> -macro available in C. In a target-dependent way, it copies the source -<tt>va_list</tt> element into the destination <tt>va_list</tt> element. This -intrinsic is necessary because the <tt><a href="#int_va_start"> -llvm.va_start</a></tt> intrinsic may be arbitrarily complex and require, for -example, memory allocation.</p> + macro available in C. In a target-dependent way, it copies the + source <tt>va_list</tt> element into the destination <tt>va_list</tt> + element. This intrinsic is necessary because + the <tt><a href="#int_va_start"> llvm.va_start</a></tt> intrinsic may be + arbitrarily complex and require, for example, memory allocation.</p> </div> @@ -5063,20 +5323,18 @@ example, memory allocation.</p> <div class="doc_text"> -<p> -LLVM support for <a href="GarbageCollection.html">Accurate Garbage +<p>LLVM support for <a href="GarbageCollection.html">Accurate Garbage Collection</a> (GC) requires the implementation and generation of these -intrinsics. -These intrinsics allow identification of <a href="#int_gcroot">GC roots on the -stack</a>, as well as garbage collector implementations that require <a -href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a> barriers. -Front-ends for type-safe garbage collected languages should generate these -intrinsics to make use of the LLVM garbage collectors. For more details, see <a -href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>. -</p> +intrinsics. These intrinsics allow identification of <a href="#int_gcroot">GC +roots on the stack</a>, as well as garbage collector implementations that +require <a href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a> +barriers. Front-ends for type-safe garbage collected languages should generate +these intrinsics to make use of the LLVM garbage collectors. For more details, +see <a href="GarbageCollection.html">Accurate Garbage Collection with +LLVM</a>.</p> -<p>The garbage collection intrinsics only operate on objects in the generic - address space (address space zero).</p> +<p>The garbage collection intrinsics only operate on objects in the generic + address space (address space zero).</p> </div> @@ -5088,33 +5346,29 @@ href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>. <div class="doc_text"> <h5>Syntax:</h5> - <pre> declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata) </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to -the code generator, and allows some metadata to be associated with it.</p> + the code generator, and allows some metadata to be associated with it.</p> <h5>Arguments:</h5> - <p>The first argument specifies the address of a stack object that contains the -root pointer. The second pointer (which must be either a constant or a global -value address) contains the meta-data to be associated with the root.</p> + root pointer. The second pointer (which must be either a constant or a + global value address) contains the meta-data to be associated with the + root.</p> <h5>Semantics:</h5> - <p>At runtime, a call to this intrinsic stores a null pointer into the "ptrloc" -location. At compile-time, the code generator generates information to allow -the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>' -intrinsic may only be used in a function which <a href="#gc">specifies a GC -algorithm</a>.</p> + location. At compile-time, the code generator generates information to allow + the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>' + intrinsic may only be used in a function which <a href="#gc">specifies a GC + algorithm</a>.</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a> @@ -5123,35 +5377,30 @@ algorithm</a>.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr) </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap -locations, allowing garbage collector implementations that require read -barriers.</p> + locations, allowing garbage collector implementations that require read + barriers.</p> <h5>Arguments:</h5> - <p>The second argument is the address to read from, which should be an address -allocated from the garbage collector. The first object is a pointer to the -start of the referenced object, if needed by the language runtime (otherwise -null).</p> + allocated from the garbage collector. The first object is a pointer to the + start of the referenced object, if needed by the language runtime (otherwise + null).</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load -instruction, but may be replaced with substantially more complex code by the -garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic -may only be used in a function which <a href="#gc">specifies a GC -algorithm</a>.</p> + instruction, but may be replaced with substantially more complex code by the + garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic + may only be used in a function which <a href="#gc">specifies a GC + algorithm</a>.</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a> @@ -5160,46 +5409,39 @@ algorithm</a>.</p> <div class="doc_text"> <h5>Syntax:</h5> - <pre> declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2) </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap -locations, allowing garbage collector implementations that require write -barriers (such as generational or reference counting collectors).</p> + locations, allowing garbage collector implementations that require write + barriers (such as generational or reference counting collectors).</p> <h5>Arguments:</h5> - <p>The first argument is the reference to store, the second is the start of the -object to store it to, and the third is the address of the field of Obj to -store to. If the runtime does not require a pointer to the object, Obj may be -null.</p> + object to store it to, and the third is the address of the field of Obj to + store to. If the runtime does not require a pointer to the object, Obj may + be null.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store -instruction, but may be replaced with substantially more complex code by the -garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic -may only be used in a function which <a href="#gc">specifies a GC -algorithm</a>.</p> + instruction, but may be replaced with substantially more complex code by the + garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic + may only be used in a function which <a href="#gc">specifies a GC + algorithm</a>.</p> </div> - - <!-- ======================================================================= --> <div class="doc_subsection"> <a name="int_codegen">Code Generator Intrinsics</a> </div> <div class="doc_text"> -<p> -These intrinsics are provided by LLVM to expose special features that may only -be implemented with code generator support. -</p> + +<p>These intrinsics are provided by LLVM to expose special features that may + only be implemented with code generator support.</p> </div> @@ -5216,38 +5458,28 @@ be implemented with code generator support. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a -target-specific value indicating the return address of the current function -or one of its callers. -</p> +<p>The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a + target-specific value indicating the return address of the current function + or one of its callers.</p> <h5>Arguments:</h5> - -<p> -The argument to this intrinsic indicates which function to return the address -for. Zero indicates the calling function, one indicates its caller, etc. The -argument is <b>required</b> to be a constant integer value. -</p> +<p>The argument to this intrinsic indicates which function to return the address + for. Zero indicates the calling function, one indicates its caller, etc. + The argument is <b>required</b> to be a constant integer value.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer + indicating the return address of the specified call frame, or zero if it + cannot be identified. The value returned by this intrinsic is likely to be + incorrect or 0 for arguments other than zero, so it should only be used for + debugging purposes.</p> -<p> -The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer indicating -the return address of the specified call frame, or zero if it cannot be -identified. The value returned by this intrinsic is likely to be incorrect or 0 -for arguments other than zero, so it should only be used for debugging purposes. -</p> +<p>Note that calling this intrinsic does not prevent function inlining or other + aggressive transformations, so the value returned may not be that of the + obvious source-language caller.</p> -<p> -Note that calling this intrinsic does not prevent function inlining or other -aggressive transformations, so the value returned may not be that of the obvious -source-language caller. -</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a> @@ -5261,34 +5493,25 @@ source-language caller. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the -target-specific frame pointer value for the specified stack frame. -</p> +<p>The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the + target-specific frame pointer value for the specified stack frame.</p> <h5>Arguments:</h5> - -<p> -The argument to this intrinsic indicates which function to return the frame -pointer for. Zero indicates the calling function, one indicates its caller, -etc. The argument is <b>required</b> to be a constant integer value. -</p> +<p>The argument to this intrinsic indicates which function to return the frame + pointer for. Zero indicates the calling function, one indicates its caller, + etc. The argument is <b>required</b> to be a constant integer value.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer + indicating the frame address of the specified call frame, or zero if it + cannot be identified. The value returned by this intrinsic is likely to be + incorrect or 0 for arguments other than zero, so it should only be used for + debugging purposes.</p> -<p> -The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer indicating -the frame address of the specified call frame, or zero if it cannot be -identified. The value returned by this intrinsic is likely to be incorrect or 0 -for arguments other than zero, so it should only be used for debugging purposes. -</p> +<p>Note that calling this intrinsic does not prevent function inlining or other + aggressive transformations, so the value returned may not be that of the + obvious source-language caller.</p> -<p> -Note that calling this intrinsic does not prevent function inlining or other -aggressive transformations, so the value returned may not be that of the obvious -source-language caller. -</p> </div> <!-- _______________________________________________________________________ --> @@ -5304,25 +5527,20 @@ source-language caller. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state of -the function stack, for use with <a href="#int_stackrestore"> -<tt>llvm.stackrestore</tt></a>. This is useful for implementing language -features like scoped automatic variable sized arrays in C99. -</p> +<p>The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state + of the function stack, for use + with <a href="#int_stackrestore"> <tt>llvm.stackrestore</tt></a>. This is + useful for implementing language features like scoped automatic variable + sized arrays in C99.</p> <h5>Semantics:</h5> - -<p> -This intrinsic returns a opaque pointer value that can be passed to <a -href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>. When an -<tt>llvm.stackrestore</tt> intrinsic is executed with a value saved from -<tt>llvm.stacksave</tt>, it effectively restores the state of the stack to the -state it was in when the <tt>llvm.stacksave</tt> intrinsic executed. In -practice, this pops any <a href="#i_alloca">alloca</a> blocks from the stack -that were allocated after the <tt>llvm.stacksave</tt> was executed. -</p> +<p>This intrinsic returns a opaque pointer value that can be passed + to <a href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>. When + an <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved + from <tt>llvm.stacksave</tt>, it effectively restores the state of the stack + to the state it was in when the <tt>llvm.stacksave</tt> intrinsic executed. + In practice, this pops any <a href="#i_alloca">alloca</a> blocks from the + stack that were allocated after the <tt>llvm.stacksave</tt> was executed.</p> </div> @@ -5339,24 +5557,18 @@ that were allocated after the <tt>llvm.stacksave</tt> was executed. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of -the function stack to the state it was in when the corresponding <a -href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic executed. This is -useful for implementing language features like scoped automatic variable sized -arrays in C99. -</p> +<p>The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of + the function stack to the state it was in when the + corresponding <a href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic + executed. This is useful for implementing language features like scoped + automatic variable sized arrays in C99.</p> <h5>Semantics:</h5> - -<p> -See the description for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>. -</p> +<p>See the description + for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>.</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a> @@ -5370,34 +5582,23 @@ See the description for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>. </pre> <h5>Overview:</h5> - - -<p> -The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to insert -a prefetch instruction if supported; otherwise, it is a noop. Prefetches have -no -effect on the behavior of the program but can change its performance -characteristics. -</p> +<p>The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to + insert a prefetch instruction if supported; otherwise, it is a noop. + Prefetches have no effect on the behavior of the program but can change its + performance characteristics.</p> <h5>Arguments:</h5> - -<p> -<tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the specifier -determining if the fetch should be for a read (0) or write (1), and -<tt>locality</tt> is a temporal locality specifier ranging from (0) - no -locality, to (3) - extremely local keep in cache. The <tt>rw</tt> and -<tt>locality</tt> arguments must be constant integers. -</p> +<p><tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the + specifier determining if the fetch should be for a read (0) or write (1), + and <tt>locality</tt> is a temporal locality specifier ranging from (0) - no + locality, to (3) - extremely local keep in cache. The <tt>rw</tt> + and <tt>locality</tt> arguments must be constant integers.</p> <h5>Semantics:</h5> - -<p> -This intrinsic does not modify the behavior of the program. In particular, -prefetches cannot trap and do not produce a value. On targets that support this -intrinsic, the prefetch can provide hints to the processor cache for better -performance. -</p> +<p>This intrinsic does not modify the behavior of the program. In particular, + prefetches cannot trap and do not produce a value. On targets that support + this intrinsic, the prefetch can provide hints to the processor cache for + better performance.</p> </div> @@ -5414,32 +5615,21 @@ performance. </pre> <h5>Overview:</h5> - - -<p> -The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program Counter -(PC) in a region of -code to simulators and other tools. The method is target specific, but it is -expected that the marker will use exported symbols to transmit the PC of the -marker. -The marker makes no guarantees that it will remain with any specific instruction -after optimizations. It is possible that the presence of a marker will inhibit -optimizations. The intended use is to be inserted after optimizations to allow -correlations of simulation runs. -</p> +<p>The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program + Counter (PC) in a region of code to simulators and other tools. The method + is target specific, but it is expected that the marker will use exported + symbols to transmit the PC of the marker. The marker makes no guarantees + that it will remain with any specific instruction after optimizations. It is + possible that the presence of a marker will inhibit optimizations. The + intended use is to be inserted after optimizations to allow correlations of + simulation runs.</p> <h5>Arguments:</h5> - -<p> -<tt>id</tt> is a numerical id identifying the marker. -</p> +<p><tt>id</tt> is a numerical id identifying the marker.</p> <h5>Semantics:</h5> - -<p> -This intrinsic does not modify the behavior of the program. Backends that do not -support this intrinisic may ignore it. -</p> +<p>This intrinsic does not modify the behavior of the program. Backends that do + not support this intrinisic may ignore it.</p> </div> @@ -5456,23 +5646,17 @@ support this intrinisic may ignore it. </pre> <h5>Overview:</h5> - - -<p> -The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle -counter register (or similar low latency, high accuracy clocks) on those targets -that support it. On X86, it should map to RDTSC. On Alpha, it should map to RPCC. -As the backing counters overflow quickly (on the order of 9 seconds on alpha), this -should only be used for small timings. -</p> +<p>The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle + counter register (or similar low latency, high accuracy clocks) on those + targets that support it. On X86, it should map to RDTSC. On Alpha, it + should map to RPCC. As the backing counters overflow quickly (on the order + of 9 seconds on alpha), this should only be used for small timings.</p> <h5>Semantics:</h5> - -<p> -When directly supported, reading the cycle counter should not modify any memory. -Implementations are allowed to either return a application specific value or a -system wide value. On backends without support, this is lowered to a constant 0. -</p> +<p>When directly supported, reading the cycle counter should not modify any + memory. Implementations are allowed to either return a application specific + value or a system wide value. On backends without support, this is lowered + to a constant 0.</p> </div> @@ -5482,12 +5666,11 @@ system wide value. On backends without support, this is lowered to a constant 0 </div> <div class="doc_text"> -<p> -LLVM provides intrinsics for a few important standard C library functions. -These intrinsics allow source-language front-ends to pass information about the -alignment of the pointer arguments to the code generator, providing opportunity -for more efficient code generation. -</p> + +<p>LLVM provides intrinsics for a few important standard C library functions. + These intrinsics allow source-language front-ends to pass information about + the alignment of the pointer arguments to the code generator, providing + opportunity for more efficient code generation.</p> </div> @@ -5499,11 +5682,12 @@ for more efficient code generation. <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use llvm.memcpy on any integer bit -width. Not all targets support all bit widths however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.memcpy</tt> on any + integer bit width. Not all targets support all bit widths however.</p> + <pre> declare void @llvm.memcpy.i8(i8 * <dest>, i8 * <src>, - i8 <len>, i32 <align>) + i8 <len>, i32 <align>) declare void @llvm.memcpy.i16(i8 * <dest>, i8 * <src>, i16 <len>, i32 <align>) declare void @llvm.memcpy.i32(i8 * <dest>, i8 * <src>, @@ -5513,44 +5697,31 @@ width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> +<p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the + source location to the destination location.</p> -<p> -The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source -location to the destination location. -</p> - -<p> -Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt> -intrinsics do not return a value, and takes an extra alignment argument. -</p> +<p>Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt> + intrinsics do not return a value, and takes an extra alignment argument.</p> <h5>Arguments:</h5> +<p>The first argument is a pointer to the destination, the second is a pointer + to the source. The third argument is an integer argument specifying the + number of bytes to copy, and the fourth argument is the alignment of the + source and destination locations.</p> -<p> -The first argument is a pointer to the destination, the second is a pointer to -the source. The third argument is an integer argument -specifying the number of bytes to copy, and the fourth argument is the alignment -of the source and destination locations. -</p> - -<p> -If the call to this intrinisic has an alignment value that is not 0 or 1, then -the caller guarantees that both the source and destination pointers are aligned -to that boundary. -</p> +<p>If the call to this intrinisic has an alignment value that is not 0 or 1, + then the caller guarantees that both the source and destination pointers are + aligned to that boundary.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the + source location to the destination location, which are not allowed to + overlap. It copies "len" bytes of memory over. If the argument is known to + be aligned to some boundary, this can be specified as the fourth argument, + otherwise it should be set to 0 or 1.</p> -<p> -The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source -location to the destination location, which are not allowed to overlap. It -copies "len" bytes of memory over. If the argument is known to be aligned to -some boundary, this can be specified as the fourth argument, otherwise it should -be set to 0 or 1. -</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a> @@ -5560,10 +5731,11 @@ be set to 0 or 1. <h5>Syntax:</h5> <p>This is an overloaded intrinsic. You can use llvm.memmove on any integer bit -width. Not all targets support all bit widths however.</p> + width. Not all targets support all bit widths however.</p> + <pre> declare void @llvm.memmove.i8(i8 * <dest>, i8 * <src>, - i8 <len>, i32 <align>) + i8 <len>, i32 <align>) declare void @llvm.memmove.i16(i8 * <dest>, i8 * <src>, i16 <len>, i32 <align>) declare void @llvm.memmove.i32(i8 * <dest>, i8 * <src>, @@ -5573,45 +5745,33 @@ width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> +<p>The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the + source location to the destination location. It is similar to the + '<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to + overlap.</p> -<p> -The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the source -location to the destination location. It is similar to the -'<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to overlap. -</p> - -<p> -Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt> -intrinsics do not return a value, and takes an extra alignment argument. -</p> +<p>Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt> + intrinsics do not return a value, and takes an extra alignment argument.</p> <h5>Arguments:</h5> +<p>The first argument is a pointer to the destination, the second is a pointer + to the source. The third argument is an integer argument specifying the + number of bytes to copy, and the fourth argument is the alignment of the + source and destination locations.</p> -<p> -The first argument is a pointer to the destination, the second is a pointer to -the source. The third argument is an integer argument -specifying the number of bytes to copy, and the fourth argument is the alignment -of the source and destination locations. -</p> - -<p> -If the call to this intrinisic has an alignment value that is not 0 or 1, then -the caller guarantees that the source and destination pointers are aligned to -that boundary. -</p> +<p>If the call to this intrinisic has an alignment value that is not 0 or 1, + then the caller guarantees that the source and destination pointers are + aligned to that boundary.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the + source location to the destination location, which may overlap. It copies + "len" bytes of memory over. If the argument is known to be aligned to some + boundary, this can be specified as the fourth argument, otherwise it should + be set to 0 or 1.</p> -<p> -The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the source -location to the destination location, which may overlap. It -copies "len" bytes of memory over. If the argument is known to be aligned to -some boundary, this can be specified as the fourth argument, otherwise it should -be set to 0 or 1. -</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a> @@ -5621,10 +5781,11 @@ be set to 0 or 1. <h5>Syntax:</h5> <p>This is an overloaded intrinsic. You can use llvm.memset on any integer bit -width. Not all targets support all bit widths however.</p> + width. Not all targets support all bit widths however.</p> + <pre> declare void @llvm.memset.i8(i8 * <dest>, i8 <val>, - i8 <len>, i32 <align>) + i8 <len>, i32 <align>) declare void @llvm.memset.i16(i8 * <dest>, i8 <val>, i16 <len>, i32 <align>) declare void @llvm.memset.i32(i8 * <dest>, i8 <val>, @@ -5634,43 +5795,30 @@ width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> +<p>The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a + particular byte value.</p> -<p> -The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a particular -byte value. -</p> - -<p> -Note that, unlike the standard libc function, the <tt>llvm.memset</tt> intrinsic -does not return a value, and takes an extra alignment argument. -</p> +<p>Note that, unlike the standard libc function, the <tt>llvm.memset</tt> + intrinsic does not return a value, and takes an extra alignment argument.</p> <h5>Arguments:</h5> +<p>The first argument is a pointer to the destination to fill, the second is the + byte value to fill it with, the third argument is an integer argument + specifying the number of bytes to fill, and the fourth argument is the known + alignment of destination location.</p> -<p> -The first argument is a pointer to the destination to fill, the second is the -byte value to fill it with, the third argument is an integer -argument specifying the number of bytes to fill, and the fourth argument is the -known alignment of destination location. -</p> - -<p> -If the call to this intrinisic has an alignment value that is not 0 or 1, then -the caller guarantees that the destination pointer is aligned to that boundary. -</p> +<p>If the call to this intrinisic has an alignment value that is not 0 or 1, + then the caller guarantees that the destination pointer is aligned to that + boundary.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting + at the destination location. If the argument is known to be aligned to some + boundary, this can be specified as the fourth argument, otherwise it should + be set to 0 or 1.</p> -<p> -The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting at -the -destination location. If the argument is known to be aligned to some boundary, -this can be specified as the fourth argument, otherwise it should be set to 0 or -1. -</p> </div> - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a> @@ -5679,9 +5827,10 @@ this can be specified as the fourth argument, otherwise it should be set to 0 or <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any -floating point or vector of floating point type. Not all targets support all -types however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any + floating point or vector of floating point type. Not all targets support all + types however.</p> + <pre> declare float @llvm.sqrt.f32(float %Val) declare double @llvm.sqrt.f64(double %Val) @@ -5691,28 +5840,21 @@ types however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand, -returning the same value as the libm '<tt>sqrt</tt>' functions would. Unlike -<tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined behavior for -negative numbers other than -0.0 (which allows for better optimization, because -there is no need to worry about errno being set). <tt>llvm.sqrt(-0.0)</tt> is -defined to return -0.0 like IEEE sqrt. -</p> +<p>The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand, + returning the same value as the libm '<tt>sqrt</tt>' functions would. + Unlike <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined + behavior for negative numbers other than -0.0 (which allows for better + optimization, because there is no need to worry about errno being + set). <tt>llvm.sqrt(-0.0)</tt> is defined to return -0.0 like IEEE sqrt.</p> <h5>Arguments:</h5> - -<p> -The argument and return value are floating point numbers of the same type. -</p> +<p>The argument and return value are floating point numbers of the same + type.</p> <h5>Semantics:</h5> +<p>This function returns the sqrt of the specified operand if it is a + nonnegative floating point number.</p> -<p> -This function returns the sqrt of the specified operand if it is a nonnegative -floating point number. -</p> </div> <!-- _______________________________________________________________________ --> @@ -5723,9 +5865,10 @@ floating point number. <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any -floating point or vector of floating point type. Not all targets support all -types however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any + floating point or vector of floating point type. Not all targets support all + types however.</p> + <pre> declare float @llvm.powi.f32(float %Val, i32 %power) declare double @llvm.powi.f64(double %Val, i32 %power) @@ -5735,26 +5878,19 @@ types however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the -specified (positive or negative) power. The order of evaluation of -multiplications is not defined. When a vector of floating point type is -used, the second argument remains a scalar integer value. -</p> +<p>The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the + specified (positive or negative) power. The order of evaluation of + multiplications is not defined. When a vector of floating point type is + used, the second argument remains a scalar integer value.</p> <h5>Arguments:</h5> - -<p> -The second argument is an integer power, and the first is a value to raise to -that power. -</p> +<p>The second argument is an integer power, and the first is a value to raise to + that power.</p> <h5>Semantics:</h5> +<p>This function returns the first value raised to the second power with an + unspecified sequence of rounding operations.</p> -<p> -This function returns the first value raised to the second power with an -unspecified sequence of rounding operations.</p> </div> <!-- _______________________________________________________________________ --> @@ -5765,9 +5901,10 @@ unspecified sequence of rounding operations.</p> <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any -floating point or vector of floating point type. Not all targets support all -types however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any + floating point or vector of floating point type. Not all targets support all + types however.</p> + <pre> declare float @llvm.sin.f32(float %Val) declare double @llvm.sin.f64(double %Val) @@ -5777,23 +5914,17 @@ types however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand. -</p> +<p>The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand.</p> <h5>Arguments:</h5> - -<p> -The argument and return value are floating point numbers of the same type. -</p> +<p>The argument and return value are floating point numbers of the same + type.</p> <h5>Semantics:</h5> +<p>This function returns the sine of the specified operand, returning the same + values as the libm <tt>sin</tt> functions would, and handles error conditions + in the same way.</p> -<p> -This function returns the sine of the specified operand, returning the -same values as the libm <tt>sin</tt> functions would, and handles error -conditions in the same way.</p> </div> <!-- _______________________________________________________________________ --> @@ -5804,9 +5935,10 @@ conditions in the same way.</p> <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any -floating point or vector of floating point type. Not all targets support all -types however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any + floating point or vector of floating point type. Not all targets support all + types however.</p> + <pre> declare float @llvm.cos.f32(float %Val) declare double @llvm.cos.f64(double %Val) @@ -5816,23 +5948,17 @@ types however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand. -</p> +<p>The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand.</p> <h5>Arguments:</h5> - -<p> -The argument and return value are floating point numbers of the same type. -</p> +<p>The argument and return value are floating point numbers of the same + type.</p> <h5>Semantics:</h5> +<p>This function returns the cosine of the specified operand, returning the same + values as the libm <tt>cos</tt> functions would, and handles error conditions + in the same way.</p> -<p> -This function returns the cosine of the specified operand, returning the -same values as the libm <tt>cos</tt> functions would, and handles error -conditions in the same way.</p> </div> <!-- _______________________________________________________________________ --> @@ -5843,9 +5969,10 @@ conditions in the same way.</p> <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any -floating point or vector of floating point type. Not all targets support all -types however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any + floating point or vector of floating point type. Not all targets support all + types however.</p> + <pre> declare float @llvm.pow.f32(float %Val, float %Power) declare double @llvm.pow.f64(double %Val, double %Power) @@ -5855,39 +5982,29 @@ types however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the -specified (positive or negative) power. -</p> +<p>The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the + specified (positive or negative) power.</p> <h5>Arguments:</h5> - -<p> -The second argument is a floating point power, and the first is a value to -raise to that power. -</p> +<p>The second argument is a floating point power, and the first is a value to + raise to that power.</p> <h5>Semantics:</h5> +<p>This function returns the first value raised to the second power, returning + the same values as the libm <tt>pow</tt> functions would, and handles error + conditions in the same way.</p> -<p> -This function returns the first value raised to the second power, -returning the -same values as the libm <tt>pow</tt> functions would, and handles error -conditions in the same way.</p> </div> - <!-- ======================================================================= --> <div class="doc_subsection"> <a name="int_manip">Bit Manipulation Intrinsics</a> </div> <div class="doc_text"> -<p> -LLVM provides intrinsics for a few important bit manipulation operations. -These allow efficient code generation for some algorithms. -</p> + +<p>LLVM provides intrinsics for a few important bit manipulation operations. + These allow efficient code generation for some algorithms.</p> </div> @@ -5900,7 +6017,8 @@ These allow efficient code generation for some algorithms. <h5>Syntax:</h5> <p>This is an overloaded intrinsic function. You can use bswap on any integer -type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p> + type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p> + <pre> declare i16 @llvm.bswap.i16(i16 <id>) declare i32 @llvm.bswap.i32(i32 <id>) @@ -5908,25 +6026,20 @@ type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer -values with an even number of bytes (positive multiple of 16 bits). These are -useful for performing operations on data that is not in the target's native -byte order. -</p> +<p>The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer + values with an even number of bytes (positive multiple of 16 bits). These + are useful for performing operations on data that is not in the target's + native byte order.</p> <h5>Semantics:</h5> - -<p> -The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high -and low byte of the input i16 swapped. Similarly, the <tt>llvm.bswap.i32</tt> -intrinsic returns an i32 value that has the four bytes of the input i32 -swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the returned -i32 will have its bytes in 3, 2, 1, 0 order. The <tt>llvm.bswap.i48</tt>, -<tt>llvm.bswap.i64</tt> and other intrinsics extend this concept to -additional even-byte lengths (6 bytes, 8 bytes and more, respectively). -</p> +<p>The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high + and low byte of the input i16 swapped. Similarly, + the <tt>llvm.bswap.i32</tt> intrinsic returns an i32 value that has the four + bytes of the input i32 swapped, so that if the input bytes are numbered 0, 1, + 2, 3 then the returned i32 will have its bytes in 3, 2, 1, 0 order. + The <tt>llvm.bswap.i48</tt>, <tt>llvm.bswap.i64</tt> and other intrinsics + extend this concept to additional even-byte lengths (6 bytes, 8 bytes and + more, respectively).</p> </div> @@ -5939,7 +6052,8 @@ additional even-byte lengths (6 bytes, 8 bytes and more, respectively). <h5>Syntax:</h5> <p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit -width. Not all targets support all bit widths however.</p> + width. Not all targets support all bit widths however.</p> + <pre> declare i8 @llvm.ctpop.i8(i8 <src>) declare i16 @llvm.ctpop.i16(i16 <src>) @@ -5949,24 +6063,16 @@ width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set in a -value. -</p> +<p>The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set + in a value.</p> <h5>Arguments:</h5> - -<p> -The only argument is the value to be counted. The argument may be of any -integer type. The return type must match the argument type. -</p> +<p>The only argument is the value to be counted. The argument may be of any + integer type. The return type must match the argument type.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.</p> -<p> -The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable. -</p> </div> <!-- _______________________________________________________________________ --> @@ -5977,8 +6083,9 @@ The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable. <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any -integer bit width. Not all targets support all bit widths however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any + integer bit width. Not all targets support all bit widths however.</p> + <pre> declare i8 @llvm.ctlz.i8 (i8 <src>) declare i16 @llvm.ctlz.i16(i16 <src>) @@ -5988,30 +6095,20 @@ integer bit width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of -leading zeros in a variable. -</p> +<p>The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of + leading zeros in a variable.</p> <h5>Arguments:</h5> - -<p> -The only argument is the value to be counted. The argument may be of any -integer type. The return type must match the argument type. -</p> +<p>The only argument is the value to be counted. The argument may be of any + integer type. The return type must match the argument type.</p> <h5>Semantics:</h5> +<p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant) + zeros in a variable. If the src == 0 then the result is the size in bits of + the type of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p> -<p> -The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant) zeros -in a variable. If the src == 0 then the result is the size in bits of the type -of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>. -</p> </div> - - <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a> @@ -6020,8 +6117,9 @@ of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>. <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any -integer bit width. Not all targets support all bit widths however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any + integer bit width. Not all targets support all bit widths however.</p> + <pre> declare i8 @llvm.cttz.i8 (i8 <src>) declare i16 @llvm.cttz.i16(i16 <src>) @@ -6031,130 +6129,17 @@ integer bit width. Not all targets support all bit widths however.</p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of -trailing zeros. -</p> +<p>The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of + trailing zeros.</p> <h5>Arguments:</h5> - -<p> -The only argument is the value to be counted. The argument may be of any -integer type. The return type must match the argument type. -</p> +<p>The only argument is the value to be counted. The argument may be of any + integer type. The return type must match the argument type.</p> <h5>Semantics:</h5> - -<p> -The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant) zeros -in a variable. If the src == 0 then the result is the size in bits of the type -of src. For example, <tt>llvm.cttz(2) = 1</tt>. -</p> -</div> - -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> - <a name="int_part_select">'<tt>llvm.part.select.*</tt>' Intrinsic</a> -</div> - -<div class="doc_text"> - -<h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.part.select</tt> -on any integer bit width.</p> -<pre> - declare i17 @llvm.part.select.i17 (i17 %val, i32 %loBit, i32 %hiBit) - declare i29 @llvm.part.select.i29 (i29 %val, i32 %loBit, i32 %hiBit) -</pre> - -<h5>Overview:</h5> -<p>The '<tt>llvm.part.select</tt>' family of intrinsic functions selects a -range of bits from an integer value and returns them in the same bit width as -the original value.</p> - -<h5>Arguments:</h5> -<p>The first argument, <tt>%val</tt> and the result may be integer types of -any bit width but they must have the same bit width. The second and third -arguments must be <tt>i32</tt> type since they specify only a bit index.</p> - -<h5>Semantics:</h5> -<p>The operation of the '<tt>llvm.part.select</tt>' intrinsic has two modes -of operation: forwards and reverse. If <tt>%loBit</tt> is greater than -<tt>%hiBits</tt> then the intrinsic operates in reverse mode. Otherwise it -operates in forward mode.</p> -<p>In forward mode, this intrinsic is the equivalent of shifting <tt>%val</tt> -right by <tt>%loBit</tt> bits and then ANDing it with a mask with -only the <tt>%hiBit - %loBit</tt> bits set, as follows:</p> -<ol> - <li>The <tt>%val</tt> is shifted right (LSHR) by the number of bits specified - by <tt>%loBits</tt>. This normalizes the value to the low order bits.</li> - <li>The <tt>%loBits</tt> value is subtracted from the <tt>%hiBits</tt> value - to determine the number of bits to retain.</li> - <li>A mask of the retained bits is created by shifting a -1 value.</li> - <li>The mask is ANDed with <tt>%val</tt> to produce the result.</li> -</ol> -<p>In reverse mode, a similar computation is made except that the bits are -returned in the reverse order. So, for example, if <tt>X</tt> has the value -<tt>i16 0x0ACF (101011001111)</tt> and we apply -<tt>part.select(i16 X, 8, 3)</tt> to it, we get back the value -<tt>i16 0x0026 (000000100110)</tt>.</p> -</div> - -<div class="doc_subsubsection"> - <a name="int_part_set">'<tt>llvm.part.set.*</tt>' Intrinsic</a> -</div> - -<div class="doc_text"> - -<h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use <tt>llvm.part.set</tt> -on any integer bit width.</p> -<pre> - declare i17 @llvm.part.set.i17.i9 (i17 %val, i9 %repl, i32 %lo, i32 %hi) - declare i29 @llvm.part.set.i29.i9 (i29 %val, i9 %repl, i32 %lo, i32 %hi) -</pre> - -<h5>Overview:</h5> -<p>The '<tt>llvm.part.set</tt>' family of intrinsic functions replaces a range -of bits in an integer value with another integer value. It returns the integer -with the replaced bits.</p> - -<h5>Arguments:</h5> -<p>The first argument, <tt>%val</tt>, and the result may be integer types of -any bit width, but they must have the same bit width. <tt>%val</tt> is the value -whose bits will be replaced. The second argument, <tt>%repl</tt> may be an -integer of any bit width. The third and fourth arguments must be <tt>i32</tt> -type since they specify only a bit index.</p> - -<h5>Semantics:</h5> -<p>The operation of the '<tt>llvm.part.set</tt>' intrinsic has two modes -of operation: forwards and reverse. If <tt>%lo</tt> is greater than -<tt>%hi</tt> then the intrinsic operates in reverse mode. Otherwise it -operates in forward mode.</p> - -<p>For both modes, the <tt>%repl</tt> value is prepared for use by either -truncating it down to the size of the replacement area or zero extending it -up to that size.</p> - -<p>In forward mode, the bits between <tt>%lo</tt> and <tt>%hi</tt> (inclusive) -are replaced with corresponding bits from <tt>%repl</tt>. That is the 0th bit -in <tt>%repl</tt> replaces the <tt>%lo</tt>th bit in <tt>%val</tt> and etc. up -to the <tt>%hi</tt>th bit.</p> - -<p>In reverse mode, a similar computation is made except that the bits are -reversed. That is, the <tt>0</tt>th bit in <tt>%repl</tt> replaces the -<tt>%hi</tt> bit in <tt>%val</tt> and etc. down to the <tt>%lo</tt>th bit.</p> - -<h5>Examples:</h5> - -<pre> - llvm.part.set(0xFFFF, 0, 4, 7) -> 0xFF0F - llvm.part.set(0xFFFF, 0, 7, 4) -> 0xFF0F - llvm.part.set(0xFFFF, 1, 7, 4) -> 0xFF8F - llvm.part.set(0xFFFF, F, 8, 3) -> 0xFFE7 - llvm.part.set(0xFFFF, 0, 3, 8) -> 0xFE07 -</pre> +<p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant) + zeros in a variable. If the src == 0 then the result is the size in bits of + the type of src. For example, <tt>llvm.cttz(2) = 1</tt>.</p> </div> @@ -6164,9 +6149,8 @@ reversed. That is, the <tt>0</tt>th bit in <tt>%repl</tt> replaces the </div> <div class="doc_text"> -<p> -LLVM provides intrinsics for some arithmetic with overflow operations. -</p> + +<p>LLVM provides intrinsics for some arithmetic with overflow operations.</p> </div> @@ -6178,9 +6162,8 @@ LLVM provides intrinsics for some arithmetic with overflow operations. <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.sadd.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b) @@ -6189,24 +6172,23 @@ on any integer bit width.</p> </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform -a signed addition of the two arguments, and indicate whether an overflow -occurred during the signed summation.</p> + a signed addition of the two arguments, and indicate whether an overflow + occurred during the signed summation.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo signed addition.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo signed addition.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform -a signed addition of the two variables. They return a structure — the -first element of which is the signed summation, and the second element of which -is a bit specifying if the signed summation resulted in an overflow.</p> + a signed addition of the two variables. They return a structure — the + first element of which is the signed summation, and the second element of + which is a bit specifying if the signed summation resulted in an + overflow.</p> <h5>Examples:</h5> <pre> @@ -6226,9 +6208,8 @@ is a bit specifying if the signed summation resulted in an overflow.</p> <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.uadd.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b) @@ -6237,24 +6218,22 @@ on any integer bit width.</p> </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform -an unsigned addition of the two arguments, and indicate whether a carry occurred -during the unsigned summation.</p> + an unsigned addition of the two arguments, and indicate whether a carry + occurred during the unsigned summation.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo unsigned addition.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo unsigned addition.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform -an unsigned addition of the two arguments. They return a structure — the -first element of which is the sum, and the second element of which is a bit -specifying if the unsigned summation resulted in a carry.</p> + an unsigned addition of the two arguments. They return a structure — + the first element of which is the sum, and the second element of which is a + bit specifying if the unsigned summation resulted in a carry.</p> <h5>Examples:</h5> <pre> @@ -6274,9 +6253,8 @@ specifying if the unsigned summation resulted in a carry.</p> <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.ssub.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b) @@ -6285,24 +6263,23 @@ on any integer bit width.</p> </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform -a signed subtraction of the two arguments, and indicate whether an overflow -occurred during the signed subtraction.</p> + a signed subtraction of the two arguments, and indicate whether an overflow + occurred during the signed subtraction.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo signed subtraction.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo signed subtraction.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform -a signed subtraction of the two arguments. They return a structure — the -first element of which is the subtraction, and the second element of which is a bit -specifying if the signed subtraction resulted in an overflow.</p> + a signed subtraction of the two arguments. They return a structure — + the first element of which is the subtraction, and the second element of + which is a bit specifying if the signed subtraction resulted in an + overflow.</p> <h5>Examples:</h5> <pre> @@ -6322,9 +6299,8 @@ specifying if the signed subtraction resulted in an overflow.</p> <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.usub.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b) @@ -6333,24 +6309,23 @@ on any integer bit width.</p> </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform -an unsigned subtraction of the two arguments, and indicate whether an overflow -occurred during the unsigned subtraction.</p> + an unsigned subtraction of the two arguments, and indicate whether an + overflow occurred during the unsigned subtraction.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo unsigned subtraction.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo unsigned subtraction.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform -an unsigned subtraction of the two arguments. They return a structure — the -first element of which is the subtraction, and the second element of which is a bit -specifying if the unsigned subtraction resulted in an overflow.</p> + an unsigned subtraction of the two arguments. They return a structure — + the first element of which is the subtraction, and the second element of + which is a bit specifying if the unsigned subtraction resulted in an + overflow.</p> <h5>Examples:</h5> <pre> @@ -6370,9 +6345,8 @@ specifying if the unsigned subtraction resulted in an overflow.</p> <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.smul.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b) @@ -6383,23 +6357,22 @@ on any integer bit width.</p> <h5>Overview:</h5> <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform -a signed multiplication of the two arguments, and indicate whether an overflow -occurred during the signed multiplication.</p> + a signed multiplication of the two arguments, and indicate whether an + overflow occurred during the signed multiplication.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo signed multiplication.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo signed multiplication.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform -a signed multiplication of the two arguments. They return a structure — -the first element of which is the multiplication, and the second element of -which is a bit specifying if the signed multiplication resulted in an -overflow.</p> + a signed multiplication of the two arguments. They return a structure — + the first element of which is the multiplication, and the second element of + which is a bit specifying if the signed multiplication resulted in an + overflow.</p> <h5>Examples:</h5> <pre> @@ -6419,9 +6392,8 @@ overflow.</p> <div class="doc_text"> <h5>Syntax:</h5> - <p>This is an overloaded intrinsic. You can use <tt>llvm.umul.with.overflow</tt> -on any integer bit width.</p> + on any integer bit width.</p> <pre> declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b) @@ -6430,26 +6402,23 @@ on any integer bit width.</p> </pre> <h5>Overview:</h5> - <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform -a unsigned multiplication of the two arguments, and indicate whether an overflow -occurred during the unsigned multiplication.</p> + a unsigned multiplication of the two arguments, and indicate whether an + overflow occurred during the unsigned multiplication.</p> <h5>Arguments:</h5> - <p>The arguments (%a and %b) and the first element of the result structure may -be of integer types of any bit width, but they must have the same bit width. The -second element of the result structure must be of type <tt>i1</tt>. <tt>%a</tt> -and <tt>%b</tt> are the two values that will undergo unsigned -multiplication.</p> + be of integer types of any bit width, but they must have the same bit + width. The second element of the result structure must be of + type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will + undergo unsigned multiplication.</p> <h5>Semantics:</h5> - <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform -an unsigned multiplication of the two arguments. They return a structure — -the first element of which is the multiplication, and the second element of -which is a bit specifying if the unsigned multiplication resulted in an -overflow.</p> + an unsigned multiplication of the two arguments. They return a structure + — the first element of which is the multiplication, and the second + element of which is a bit specifying if the unsigned multiplication resulted + in an overflow.</p> <h5>Examples:</h5> <pre> @@ -6467,14 +6436,13 @@ overflow.</p> </div> <div class="doc_text"> -<p> -The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> prefix), -are described in the <a -href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source Level -Debugging</a> document. -</p> -</div> +<p>The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> + prefix), are described in + the <a href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source + Level Debugging</a> document.</p> + +</div> <!-- ======================================================================= --> <div class="doc_subsection"> @@ -6482,10 +6450,12 @@ Debugging</a> document. </div> <div class="doc_text"> -<p> The LLVM exception handling intrinsics (which all start with -<tt>llvm.eh.</tt> prefix), are described in the <a -href="ExceptionHandling.html#format_common_intrinsics">LLVM Exception -Handling</a> document. </p> + +<p>The LLVM exception handling intrinsics (which all start with + <tt>llvm.eh.</tt> prefix), are described in + the <a href="ExceptionHandling.html#format_common_intrinsics">LLVM Exception + Handling</a> document.</p> + </div> <!-- ======================================================================= --> @@ -6494,70 +6464,74 @@ Handling</a> document. </p> </div> <div class="doc_text"> -<p> - This intrinsic makes it possible to excise one parameter, marked with - the <tt>nest</tt> attribute, from a function. The result is a callable - function pointer lacking the nest parameter - the caller does not need - to provide a value for it. Instead, the value to use is stored in - advance in a "trampoline", a block of memory usually allocated - on the stack, which also contains code to splice the nest value into the - argument list. This is used to implement the GCC nested function address - extension. -</p> -<p> - For example, if the function is - <tt>i32 f(i8* nest %c, i32 %x, i32 %y)</tt> then the resulting function - pointer has signature <tt>i32 (i32, i32)*</tt>. It can be created as follows:</p> + +<p>This intrinsic makes it possible to excise one parameter, marked with + the <tt>nest</tt> attribute, from a function. The result is a callable + function pointer lacking the nest parameter - the caller does not need to + provide a value for it. Instead, the value to use is stored in advance in a + "trampoline", a block of memory usually allocated on the stack, which also + contains code to splice the nest value into the argument list. This is used + to implement the GCC nested function address extension.</p> + +<p>For example, if the function is + <tt>i32 f(i8* nest %c, i32 %x, i32 %y)</tt> then the resulting function + pointer has signature <tt>i32 (i32, i32)*</tt>. It can be created as + follows:</p> + +<div class="doc_code"> <pre> %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86 %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0 %p = call i8* @llvm.init.trampoline( i8* %tramp1, i8* bitcast (i32 (i8* nest , i32, i32)* @f to i8*), i8* %nval ) %fp = bitcast i8* %p to i32 (i32, i32)* </pre> - <p>The call <tt>%val = call i32 %fp( i32 %x, i32 %y )</tt> is then equivalent - to <tt>%val = call i32 %f( i8* %nval, i32 %x, i32 %y )</tt>.</p> +</div> + +<p>The call <tt>%val = call i32 %fp( i32 %x, i32 %y )</tt> is then equivalent + to <tt>%val = call i32 %f( i8* %nval, i32 %x, i32 %y )</tt>.</p> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> <pre> -declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>) + declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>) </pre> + <h5>Overview:</h5> -<p> - This fills the memory pointed to by <tt>tramp</tt> with code - and returns a function pointer suitable for executing it. -</p> +<p>This fills the memory pointed to by <tt>tramp</tt> with code and returns a + function pointer suitable for executing it.</p> + <h5>Arguments:</h5> -<p> - The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all - pointers. The <tt>tramp</tt> argument must point to a sufficiently large - and sufficiently aligned block of memory; this memory is written to by the - intrinsic. Note that the size and the alignment are target-specific - LLVM - currently provides no portable way of determining them, so a front-end that - generates this intrinsic needs to have some target-specific knowledge. - The <tt>func</tt> argument must hold a function bitcast to an <tt>i8*</tt>. -</p> +<p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all + pointers. The <tt>tramp</tt> argument must point to a sufficiently large and + sufficiently aligned block of memory; this memory is written to by the + intrinsic. Note that the size and the alignment are target-specific - LLVM + currently provides no portable way of determining them, so a front-end that + generates this intrinsic needs to have some target-specific knowledge. + The <tt>func</tt> argument must hold a function bitcast to + an <tt>i8*</tt>.</p> + <h5>Semantics:</h5> -<p> - The block of memory pointed to by <tt>tramp</tt> is filled with target - dependent code, turning it into a function. A pointer to this function is - returned, but needs to be bitcast to an - <a href="#int_trampoline">appropriate function pointer type</a> - before being called. The new function's signature is the same as that of - <tt>func</tt> with any arguments marked with the <tt>nest</tt> attribute - removed. At most one such <tt>nest</tt> argument is allowed, and it must be - of pointer type. Calling the new function is equivalent to calling - <tt>func</tt> with the same argument list, but with <tt>nval</tt> used for the - missing <tt>nest</tt> argument. If, after calling - <tt>llvm.init.trampoline</tt>, the memory pointed to by <tt>tramp</tt> is - modified, then the effect of any later call to the returned function pointer is - undefined. -</p> +<p>The block of memory pointed to by <tt>tramp</tt> is filled with target + dependent code, turning it into a function. A pointer to this function is + returned, but needs to be bitcast to an <a href="#int_trampoline">appropriate + function pointer type</a> before being called. The new function's signature + is the same as that of <tt>func</tt> with any arguments marked with + the <tt>nest</tt> attribute removed. At most one such <tt>nest</tt> argument + is allowed, and it must be of pointer type. Calling the new function is + equivalent to calling <tt>func</tt> with the same argument list, but + with <tt>nval</tt> used for the missing <tt>nest</tt> argument. If, after + calling <tt>llvm.init.trampoline</tt>, the memory pointed to + by <tt>tramp</tt> is modified, then the effect of any later call to the + returned function pointer is undefined.</p> + </div> <!-- ======================================================================= --> @@ -6566,27 +6540,25 @@ declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <n </div> <div class="doc_text"> -<p> - These intrinsic functions expand the "universal IR" of LLVM to represent - hardware constructs for atomic operations and memory synchronization. This - provides an interface to the hardware, not an interface to the programmer. It - is aimed at a low enough level to allow any programming models or APIs - (Application Programming Interfaces) which - need atomic behaviors to map cleanly onto it. It is also modeled primarily on - hardware behavior. Just as hardware provides a "universal IR" for source - languages, it also provides a starting point for developing a "universal" - atomic operation and synchronization IR. -</p> -<p> - These do <em>not</em> form an API such as high-level threading libraries, - software transaction memory systems, atomic primitives, and intrinsic - functions as found in BSD, GNU libc, atomic_ops, APR, and other system and - application libraries. The hardware interface provided by LLVM should allow - a clean implementation of all of these APIs and parallel programming models. - No one model or paradigm should be selected above others unless the hardware - itself ubiquitously does so. -</p> +<p>These intrinsic functions expand the "universal IR" of LLVM to represent + hardware constructs for atomic operations and memory synchronization. This + provides an interface to the hardware, not an interface to the programmer. It + is aimed at a low enough level to allow any programming models or APIs + (Application Programming Interfaces) which need atomic behaviors to map + cleanly onto it. It is also modeled primarily on hardware behavior. Just as + hardware provides a "universal IR" for source languages, it also provides a + starting point for developing a "universal" atomic operation and + synchronization IR.</p> + +<p>These do <em>not</em> form an API such as high-level threading libraries, + software transaction memory systems, atomic primitives, and intrinsic + functions as found in BSD, GNU libc, atomic_ops, APR, and other system and + application libraries. The hardware interface provided by LLVM should allow + a clean implementation of all of these APIs and parallel programming models. + No one model or paradigm should be selected above others unless the hardware + itself ubiquitously does so.</p> + </div> <!-- _______________________________________________________________________ --> @@ -6596,59 +6568,56 @@ declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <n <div class="doc_text"> <h5>Syntax:</h5> <pre> -declare void @llvm.memory.barrier( i1 <ll>, i1 <ls>, i1 <sl>, i1 <ss>, -i1 <device> ) - + declare void @llvm.memory.barrier( i1 <ll>, i1 <ls>, i1 <sl>, i1 <ss>, i1 <device> ) </pre> + <h5>Overview:</h5> -<p> - The <tt>llvm.memory.barrier</tt> intrinsic guarantees ordering between - specific pairs of memory access types. -</p> +<p>The <tt>llvm.memory.barrier</tt> intrinsic guarantees ordering between + specific pairs of memory access types.</p> + <h5>Arguments:</h5> -<p> - The <tt>llvm.memory.barrier</tt> intrinsic requires five boolean arguments. - The first four arguments enables a specific barrier as listed below. The fith - argument specifies that the barrier applies to io or device or uncached memory. +<p>The <tt>llvm.memory.barrier</tt> intrinsic requires five boolean arguments. + The first four arguments enables a specific barrier as listed below. The + fith argument specifies that the barrier applies to io or device or uncached + memory.</p> + +<ul> + <li><tt>ll</tt>: load-load barrier</li> + <li><tt>ls</tt>: load-store barrier</li> + <li><tt>sl</tt>: store-load barrier</li> + <li><tt>ss</tt>: store-store barrier</li> + <li><tt>device</tt>: barrier applies to device and uncached memory also.</li> +</ul> -</p> - <ul> - <li><tt>ll</tt>: load-load barrier</li> - <li><tt>ls</tt>: load-store barrier</li> - <li><tt>sl</tt>: store-load barrier</li> - <li><tt>ss</tt>: store-store barrier</li> - <li><tt>device</tt>: barrier applies to device and uncached memory also.</li> - </ul> <h5>Semantics:</h5> -<p> - This intrinsic causes the system to enforce some ordering constraints upon - the loads and stores of the program. This barrier does not indicate - <em>when</em> any events will occur, it only enforces an <em>order</em> in - which they occur. For any of the specified pairs of load and store operations - (f.ex. load-load, or store-load), all of the first operations preceding the - barrier will complete before any of the second operations succeeding the - barrier begin. Specifically the semantics for each pairing is as follows: -</p> - <ul> - <li><tt>ll</tt>: All loads before the barrier must complete before any load - after the barrier begins.</li> - - <li><tt>ls</tt>: All loads before the barrier must complete before any - store after the barrier begins.</li> - <li><tt>ss</tt>: All stores before the barrier must complete before any - store after the barrier begins.</li> - <li><tt>sl</tt>: All stores before the barrier must complete before any - load after the barrier begins.</li> - </ul> -<p> - These semantics are applied with a logical "and" behavior when more than one - is enabled in a single memory barrier intrinsic. -</p> -<p> - Backends may implement stronger barriers than those requested when they do not - support as fine grained a barrier as requested. Some architectures do not - need all types of barriers and on such architectures, these become noops. -</p> +<p>This intrinsic causes the system to enforce some ordering constraints upon + the loads and stores of the program. This barrier does not + indicate <em>when</em> any events will occur, it only enforces + an <em>order</em> in which they occur. For any of the specified pairs of load + and store operations (f.ex. load-load, or store-load), all of the first + operations preceding the barrier will complete before any of the second + operations succeeding the barrier begin. Specifically the semantics for each + pairing is as follows:</p> + +<ul> + <li><tt>ll</tt>: All loads before the barrier must complete before any load + after the barrier begins.</li> + <li><tt>ls</tt>: All loads before the barrier must complete before any + store after the barrier begins.</li> + <li><tt>ss</tt>: All stores before the barrier must complete before any + store after the barrier begins.</li> + <li><tt>sl</tt>: All stores before the barrier must complete before any + load after the barrier begins.</li> +</ul> + +<p>These semantics are applied with a logical "and" behavior when more than one + is enabled in a single memory barrier intrinsic.</p> + +<p>Backends may implement stronger barriers than those requested when they do + not support as fine grained a barrier as requested. Some architectures do + not need all types of barriers and on such architectures, these become + noops.</p> + <h5>Example:</h5> <pre> %ptr = malloc i32 @@ -6659,50 +6628,48 @@ i1 <device> ) <i>; guarantee the above finishes</i> store i32 8, %ptr <i>; before this begins</i> </pre> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_atomic_cmp_swap">'<tt>llvm.atomic.cmp.swap.*</tt>' Intrinsic</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<p> - This is an overloaded intrinsic. You can use <tt>llvm.atomic.cmp.swap</tt> on - any integer bit width and for different address spaces. Not all targets - support all bit widths however.</p> +<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.cmp.swap</tt> on + any integer bit width and for different address spaces. Not all targets + support all bit widths however.</p> <pre> -declare i8 @llvm.atomic.cmp.swap.i8.p0i8( i8* <ptr>, i8 <cmp>, i8 <val> ) -declare i16 @llvm.atomic.cmp.swap.i16.p0i16( i16* <ptr>, i16 <cmp>, i16 <val> ) -declare i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* <ptr>, i32 <cmp>, i32 <val> ) -declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* <ptr>, i64 <cmp>, i64 <val> ) - + declare i8 @llvm.atomic.cmp.swap.i8.p0i8( i8* <ptr>, i8 <cmp>, i8 <val> ) + declare i16 @llvm.atomic.cmp.swap.i16.p0i16( i16* <ptr>, i16 <cmp>, i16 <val> ) + declare i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* <ptr>, i32 <cmp>, i32 <val> ) + declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* <ptr>, i64 <cmp>, i64 <val> ) </pre> + <h5>Overview:</h5> -<p> - This loads a value in memory and compares it to a given value. If they are - equal, it stores a new value into the memory. -</p> +<p>This loads a value in memory and compares it to a given value. If they are + equal, it stores a new value into the memory.</p> + <h5>Arguments:</h5> -<p> - The <tt>llvm.atomic.cmp.swap</tt> intrinsic takes three arguments. The result as - well as both <tt>cmp</tt> and <tt>val</tt> must be integer values with the - same bit width. The <tt>ptr</tt> argument must be a pointer to a value of - this integer type. While any bit width integer may be used, targets may only - lower representations they support in hardware. +<p>The <tt>llvm.atomic.cmp.swap</tt> intrinsic takes three arguments. The result + as well as both <tt>cmp</tt> and <tt>val</tt> must be integer values with the + same bit width. The <tt>ptr</tt> argument must be a pointer to a value of + this integer type. While any bit width integer may be used, targets may only + lower representations they support in hardware.</p> -</p> <h5>Semantics:</h5> -<p> - This entire intrinsic must be executed atomically. It first loads the value - in memory pointed to by <tt>ptr</tt> and compares it with the value - <tt>cmp</tt>. If they are equal, <tt>val</tt> is stored into the memory. The - loaded value is yielded in all cases. This provides the equivalent of an - atomic compare-and-swap operation within the SSA framework. -</p> -<h5>Examples:</h5> +<p>This entire intrinsic must be executed atomically. It first loads the value + in memory pointed to by <tt>ptr</tt> and compares it with the + value <tt>cmp</tt>. If they are equal, <tt>val</tt> is stored into the + memory. The loaded value is yielded in all cases. This provides the + equivalent of an atomic compare-and-swap operation within the SSA + framework.</p> +<h5>Examples:</h5> <pre> %ptr = malloc i32 store i32 4, %ptr @@ -6720,6 +6687,7 @@ declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* <ptr>, i64 <cmp>, %memval2 = load i32* %ptr <i>; yields {i32}:memval2 = 8</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -6729,38 +6697,33 @@ declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* <ptr>, i64 <cmp>, <div class="doc_text"> <h5>Syntax:</h5> -<p> - This is an overloaded intrinsic. You can use <tt>llvm.atomic.swap</tt> on any - integer bit width. Not all targets support all bit widths however.</p> -<pre> -declare i8 @llvm.atomic.swap.i8.p0i8( i8* <ptr>, i8 <val> ) -declare i16 @llvm.atomic.swap.i16.p0i16( i16* <ptr>, i16 <val> ) -declare i32 @llvm.atomic.swap.i32.p0i32( i32* <ptr>, i32 <val> ) -declare i64 @llvm.atomic.swap.i64.p0i64( i64* <ptr>, i64 <val> ) +<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.swap</tt> on any + integer bit width. Not all targets support all bit widths however.</p> +<pre> + declare i8 @llvm.atomic.swap.i8.p0i8( i8* <ptr>, i8 <val> ) + declare i16 @llvm.atomic.swap.i16.p0i16( i16* <ptr>, i16 <val> ) + declare i32 @llvm.atomic.swap.i32.p0i32( i32* <ptr>, i32 <val> ) + declare i64 @llvm.atomic.swap.i64.p0i64( i64* <ptr>, i64 <val> ) </pre> + <h5>Overview:</h5> -<p> - This intrinsic loads the value stored in memory at <tt>ptr</tt> and yields - the value from memory. It then stores the value in <tt>val</tt> in the memory - at <tt>ptr</tt>. -</p> +<p>This intrinsic loads the value stored in memory at <tt>ptr</tt> and yields + the value from memory. It then stores the value in <tt>val</tt> in the memory + at <tt>ptr</tt>.</p> + <h5>Arguments:</h5> +<p>The <tt>llvm.atomic.swap</tt> intrinsic takes two arguments. Both + the <tt>val</tt> argument and the result must be integers of the same bit + width. The first argument, <tt>ptr</tt>, must be a pointer to a value of this + integer type. The targets may only lower integer representations they + support.</p> -<p> - The <tt>llvm.atomic.swap</tt> intrinsic takes two arguments. Both the - <tt>val</tt> argument and the result must be integers of the same bit width. - The first argument, <tt>ptr</tt>, must be a pointer to a value of this - integer type. The targets may only lower integer representations they - support. -</p> <h5>Semantics:</h5> -<p> - This intrinsic loads the value pointed to by <tt>ptr</tt>, yields it, and - stores <tt>val</tt> back into <tt>ptr</tt> atomically. This provides the - equivalent of an atomic swap operation within the SSA framework. +<p>This intrinsic loads the value pointed to by <tt>ptr</tt>, yields it, and + stores <tt>val</tt> back into <tt>ptr</tt> atomically. This provides the + equivalent of an atomic swap operation within the SSA framework.</p> -</p> <h5>Examples:</h5> <pre> %ptr = malloc i32 @@ -6779,6 +6742,7 @@ declare i64 @llvm.atomic.swap.i64.p0i64( i64* <ptr>, i64 <val> ) %stored2 = icmp eq i32 %result2, 8 <i>; yields {i1}:stored2 = true</i> %memval2 = load i32* %ptr <i>; yields {i32}:memval2 = 2</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -6786,37 +6750,34 @@ declare i64 @llvm.atomic.swap.i64.p0i64( i64* <ptr>, i64 <val> ) <a name="int_atomic_load_add">'<tt>llvm.atomic.load.add.*</tt>' Intrinsic</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<p> - This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.add</tt> on any - integer bit width. Not all targets support all bit widths however.</p> -<pre> -declare i8 @llvm.atomic.load.add.i8..p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.add.i16..p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.add.i32..p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.add.i64..p0i64( i64* <ptr>, i64 <delta> ) +<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.add</tt> on + any integer bit width. Not all targets support all bit widths however.</p> +<pre> + declare i8 @llvm.atomic.load.add.i8..p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.add.i16..p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.add.i32..p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.add.i64..p0i64( i64* <ptr>, i64 <delta> ) </pre> + <h5>Overview:</h5> -<p> - This intrinsic adds <tt>delta</tt> to the value stored in memory at - <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>. -</p> +<p>This intrinsic adds <tt>delta</tt> to the value stored in memory + at <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p> + <h5>Arguments:</h5> -<p> +<p>The intrinsic takes two arguments, the first a pointer to an integer value + and the second an integer value. The result is also an integer value. These + integer types can have any bit width, but they must all have the same bit + width. The targets may only lower integer representations they support.</p> - The intrinsic takes two arguments, the first a pointer to an integer value - and the second an integer value. The result is also an integer value. These - integer types can have any bit width, but they must all have the same bit - width. The targets may only lower integer representations they support. -</p> <h5>Semantics:</h5> -<p> - This intrinsic does a series of operations atomically. It first loads the - value stored at <tt>ptr</tt>. It then adds <tt>delta</tt>, stores the result - to <tt>ptr</tt>. It yields the original value stored at <tt>ptr</tt>. -</p> +<p>This intrinsic does a series of operations atomically. It first loads the + value stored at <tt>ptr</tt>. It then adds <tt>delta</tt>, stores the result + to <tt>ptr</tt>. It yields the original value stored at <tt>ptr</tt>.</p> <h5>Examples:</h5> <pre> @@ -6830,6 +6791,7 @@ declare i64 @llvm.atomic.load.add.i64..p0i64( i64* <ptr>, i64 <delta> <i>; yields {i32}:result3 = 10</i> %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 15</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -6837,38 +6799,36 @@ declare i64 @llvm.atomic.load.add.i64..p0i64( i64* <ptr>, i64 <delta> <a name="int_atomic_load_sub">'<tt>llvm.atomic.load.sub.*</tt>' Intrinsic</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<p> - This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.sub</tt> on - any integer bit width and for different address spaces. Not all targets - support all bit widths however.</p> -<pre> -declare i8 @llvm.atomic.load.sub.i8.p0i32( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.sub.i16.p0i32( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.sub.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* <ptr>, i64 <delta> ) +<p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.sub</tt> on + any integer bit width and for different address spaces. Not all targets + support all bit widths however.</p> +<pre> + declare i8 @llvm.atomic.load.sub.i8.p0i32( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.sub.i16.p0i32( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.sub.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* <ptr>, i64 <delta> ) </pre> + <h5>Overview:</h5> -<p> - This intrinsic subtracts <tt>delta</tt> to the value stored in memory at - <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>. -</p> +<p>This intrinsic subtracts <tt>delta</tt> to the value stored in memory at + <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p> + <h5>Arguments:</h5> -<p> +<p>The intrinsic takes two arguments, the first a pointer to an integer value + and the second an integer value. The result is also an integer value. These + integer types can have any bit width, but they must all have the same bit + width. The targets may only lower integer representations they support.</p> - The intrinsic takes two arguments, the first a pointer to an integer value - and the second an integer value. The result is also an integer value. These - integer types can have any bit width, but they must all have the same bit - width. The targets may only lower integer representations they support. -</p> <h5>Semantics:</h5> -<p> - This intrinsic does a series of operations atomically. It first loads the - value stored at <tt>ptr</tt>. It then subtracts <tt>delta</tt>, stores the - result to <tt>ptr</tt>. It yields the original value stored at <tt>ptr</tt>. -</p> +<p>This intrinsic does a series of operations atomically. It first loads the + value stored at <tt>ptr</tt>. It then subtracts <tt>delta</tt>, stores the + result to <tt>ptr</tt>. It yields the original value stored + at <tt>ptr</tt>.</p> <h5>Examples:</h5> <pre> @@ -6882,6 +6842,7 @@ declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* <ptr>, i64 <delta> <i>; yields {i32}:result3 = 2</i> %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = -3</i> </pre> + </div> <!-- _______________________________________________________________________ --> @@ -6890,67 +6851,61 @@ declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* <ptr>, i64 <delta> <a name="int_atomic_load_nand">'<tt>llvm.atomic.load.nand.*</tt>' Intrinsic</a><br> <a name="int_atomic_load_or">'<tt>llvm.atomic.load.or.*</tt>' Intrinsic</a><br> <a name="int_atomic_load_xor">'<tt>llvm.atomic.load.xor.*</tt>' Intrinsic</a><br> - </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<p> - These are overloaded intrinsics. You can use <tt>llvm.atomic.load_and</tt>, - <tt>llvm.atomic.load_nand</tt>, <tt>llvm.atomic.load_or</tt>, and - <tt>llvm.atomic.load_xor</tt> on any integer bit width and for different - address spaces. Not all targets support all bit widths however.</p> -<pre> -declare i8 @llvm.atomic.load.and.i8.p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.and.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.and.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.and.i64.p0i64( i64* <ptr>, i64 <delta> ) +<p>These are overloaded intrinsics. You can + use <tt>llvm.atomic.load_and</tt>, <tt>llvm.atomic.load_nand</tt>, + <tt>llvm.atomic.load_or</tt>, and <tt>llvm.atomic.load_xor</tt> on any integer + bit width and for different address spaces. Not all targets support all bit + widths however.</p> +<pre> + declare i8 @llvm.atomic.load.and.i8.p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.and.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.and.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.and.i64.p0i64( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.or.i8.p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.or.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.or.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.or.i64.p0i64( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.or.i8.p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.or.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.or.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.or.i64.p0i64( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.nand.i8.p0i32( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.nand.i16.p0i32( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.nand.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.nand.i64.p0i32( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.nand.i8.p0i32( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.nand.i16.p0i32( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.nand.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.nand.i64.p0i32( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.xor.i8.p0i32( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.xor.i16.p0i32( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.xor.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.xor.i8.p0i32( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.xor.i16.p0i32( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.xor.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* <ptr>, i64 <delta> ) </pre> + <h5>Overview:</h5> -<p> - These intrinsics bitwise the operation (and, nand, or, xor) <tt>delta</tt> to - the value stored in memory at <tt>ptr</tt>. It yields the original value - at <tt>ptr</tt>. -</p> +<p>These intrinsics bitwise the operation (and, nand, or, xor) <tt>delta</tt> to + the value stored in memory at <tt>ptr</tt>. It yields the original value + at <tt>ptr</tt>.</p> + <h5>Arguments:</h5> -<p> +<p>These intrinsics take two arguments, the first a pointer to an integer value + and the second an integer value. The result is also an integer value. These + integer types can have any bit width, but they must all have the same bit + width. The targets may only lower integer representations they support.</p> - These intrinsics take two arguments, the first a pointer to an integer value - and the second an integer value. The result is also an integer value. These - integer types can have any bit width, but they must all have the same bit - width. The targets may only lower integer representations they support. -</p> <h5>Semantics:</h5> -<p> - These intrinsics does a series of operations atomically. They first load the - value stored at <tt>ptr</tt>. They then do the bitwise operation - <tt>delta</tt>, store the result to <tt>ptr</tt>. They yield the original - value stored at <tt>ptr</tt>. -</p> +<p>These intrinsics does a series of operations atomically. They first load the + value stored at <tt>ptr</tt>. They then do the bitwise + operation <tt>delta</tt>, store the result to <tt>ptr</tt>. They yield the + original value stored at <tt>ptr</tt>.</p> <h5>Examples:</h5> <pre> @@ -6966,8 +6921,8 @@ declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* <ptr>, i64 <delta> <i>; yields {i32}:result3 = FF</i> %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = F0</i> </pre> -</div> +</div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> @@ -6975,68 +6930,60 @@ declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* <ptr>, i64 <delta> <a name="int_atomic_load_min">'<tt>llvm.atomic.load.min.*</tt>' Intrinsic</a><br> <a name="int_atomic_load_umax">'<tt>llvm.atomic.load.umax.*</tt>' Intrinsic</a><br> <a name="int_atomic_load_umin">'<tt>llvm.atomic.load.umin.*</tt>' Intrinsic</a><br> - </div> + <div class="doc_text"> + <h5>Syntax:</h5> -<p> - These are overloaded intrinsics. You can use <tt>llvm.atomic.load_max</tt>, - <tt>llvm.atomic.load_min</tt>, <tt>llvm.atomic.load_umax</tt>, and - <tt>llvm.atomic.load_umin</tt> on any integer bit width and for different - address spaces. Not all targets - support all bit widths however.</p> -<pre> -declare i8 @llvm.atomic.load.max.i8.p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.max.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.max.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.max.i64.p0i64( i64* <ptr>, i64 <delta> ) +<p>These are overloaded intrinsics. You can use <tt>llvm.atomic.load_max</tt>, + <tt>llvm.atomic.load_min</tt>, <tt>llvm.atomic.load_umax</tt>, and + <tt>llvm.atomic.load_umin</tt> on any integer bit width and for different + address spaces. Not all targets support all bit widths however.</p> +<pre> + declare i8 @llvm.atomic.load.max.i8.p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.max.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.max.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.max.i64.p0i64( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.min.i8.p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.min.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.min.i32..p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.min.i64..p0i64( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.min.i8.p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.min.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.min.i32..p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.min.i64..p0i64( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.umax.i8.p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.umax.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.umax.i32.p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.umax.i64.p0i64( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.umax.i8.p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.umax.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.umax.i32.p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.umax.i64.p0i64( i64* <ptr>, i64 <delta> ) </pre> <pre> -declare i8 @llvm.atomic.load.umin.i8..p0i8( i8* <ptr>, i8 <delta> ) -declare i16 @llvm.atomic.load.umin.i16.p0i16( i16* <ptr>, i16 <delta> ) -declare i32 @llvm.atomic.load.umin.i32..p0i32( i32* <ptr>, i32 <delta> ) -declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* <ptr>, i64 <delta> ) - + declare i8 @llvm.atomic.load.umin.i8..p0i8( i8* <ptr>, i8 <delta> ) + declare i16 @llvm.atomic.load.umin.i16.p0i16( i16* <ptr>, i16 <delta> ) + declare i32 @llvm.atomic.load.umin.i32..p0i32( i32* <ptr>, i32 <delta> ) + declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* <ptr>, i64 <delta> ) </pre> + <h5>Overview:</h5> -<p> - These intrinsics takes the signed or unsigned minimum or maximum of - <tt>delta</tt> and the value stored in memory at <tt>ptr</tt>. It yields the - original value at <tt>ptr</tt>. -</p> +<p>These intrinsics takes the signed or unsigned minimum or maximum of + <tt>delta</tt> and the value stored in memory at <tt>ptr</tt>. It yields the + original value at <tt>ptr</tt>.</p> + <h5>Arguments:</h5> -<p> +<p>These intrinsics take two arguments, the first a pointer to an integer value + and the second an integer value. The result is also an integer value. These + integer types can have any bit width, but they must all have the same bit + width. The targets may only lower integer representations they support.</p> - These intrinsics take two arguments, the first a pointer to an integer value - and the second an integer value. The result is also an integer value. These - integer types can have any bit width, but they must all have the same bit - width. The targets may only lower integer representations they support. -</p> <h5>Semantics:</h5> -<p> - These intrinsics does a series of operations atomically. They first load the - value stored at <tt>ptr</tt>. They then do the signed or unsigned min or max - <tt>delta</tt> and the value, store the result to <tt>ptr</tt>. They yield - the original value stored at <tt>ptr</tt>. -</p> +<p>These intrinsics does a series of operations atomically. They first load the + value stored at <tt>ptr</tt>. They then do the signed or unsigned min or + max <tt>delta</tt> and the value, store the result to <tt>ptr</tt>. They + yield the original value stored at <tt>ptr</tt>.</p> <h5>Examples:</h5> <pre> @@ -7052,6 +6999,134 @@ declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* <ptr>, i64 <delta&g <i>; yields {i32}:result3 = 8</i> %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 30</i> </pre> + +</div> + + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="int_memorymarkers">Memory Use Markers</a> +</div> + +<div class="doc_text"> + +<p>This class of intrinsics exists to information about the lifetime of memory + objects and ranges where variables are immutable.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a> +</div> + +<div class="doc_text"> + +<h5>Syntax:</h5> +<pre> + declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>) +</pre> + +<h5>Overview:</h5> +<p>The '<tt>llvm.lifetime.start</tt>' intrinsic specifies the start of a memory + object's lifetime.</p> + +<h5>Arguments:</h5> +<p>The first argument is a constant integer representing the size of the + object, or -1 if it is variable sized. The second argument is a pointer to + the object.</p> + +<h5>Semantics:</h5> +<p>This intrinsic indicates that before this point in the code, the value of the + memory pointed to by <tt>ptr</tt> is dead. This means that it is known to + never be used and has an undefined value. A load from the pointer that is + preceded by this intrinsic can be replaced with + <tt>'<a href="#undefvalues">undef</a>'</tt>.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a> +</div> + +<div class="doc_text"> + +<h5>Syntax:</h5> +<pre> + declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>) +</pre> + +<h5>Overview:</h5> +<p>The '<tt>llvm.lifetime.end</tt>' intrinsic specifies the end of a memory + object's lifetime.</p> + +<h5>Arguments:</h5> +<p>The first argument is a constant integer representing the size of the + object, or -1 if it is variable sized. The second argument is a pointer to + the object.</p> + +<h5>Semantics:</h5> +<p>This intrinsic indicates that after this point in the code, the value of the + memory pointed to by <tt>ptr</tt> is dead. This means that it is known to + never be used and has an undefined value. Any stores into the memory object + following this intrinsic may be removed as dead. + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a> +</div> + +<div class="doc_text"> + +<h5>Syntax:</h5> +<pre> + declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>) readonly +</pre> + +<h5>Overview:</h5> +<p>The '<tt>llvm.invariant.start</tt>' intrinsic specifies that the contents of + a memory object will not change.</p> + +<h5>Arguments:</h5> +<p>The first argument is a constant integer representing the size of the + object, or -1 if it is variable sized. The second argument is a pointer to + the object.</p> + +<h5>Semantics:</h5> +<p>This intrinsic indicates that until an <tt>llvm.invariant.end</tt> that uses + the return value, the referenced memory location is constant and + unchanging.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a> +</div> + +<div class="doc_text"> + +<h5>Syntax:</h5> +<pre> + declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>) +</pre> + +<h5>Overview:</h5> +<p>The '<tt>llvm.invariant.end</tt>' intrinsic specifies that the contents of + a memory object are mutable.</p> + +<h5>Arguments:</h5> +<p>The first argument is the matching <tt>llvm.invariant.start</tt> intrinsic. + The second argument is a constant integer representing the size of the + object, or -1 if it is variable sized and the third argument is a pointer + to the object.</p> + +<h5>Semantics:</h5> +<p>This intrinsic indicates that the memory is mutable again.</p> + </div> <!-- ======================================================================= --> @@ -7060,8 +7135,10 @@ declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* <ptr>, i64 <delta&g </div> <div class="doc_text"> -<p> This class of intrinsics is designed to be generic and has -no specific purpose. </p> + +<p>This class of intrinsics is designed to be generic and has no specific + purpose.</p> + </div> <!-- _______________________________________________________________________ --> @@ -7077,27 +7154,19 @@ no specific purpose. </p> </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.var.annotation</tt>' intrinsic -</p> +<p>The '<tt>llvm.var.annotation</tt>' intrinsic.</p> <h5>Arguments:</h5> - -<p> -The first argument is a pointer to a value, the second is a pointer to a -global string, the third is a pointer to a global string which is the source -file name, and the last argument is the line number. -</p> +<p>The first argument is a pointer to a value, the second is a pointer to a + global string, the third is a pointer to a global string which is the source + file name, and the last argument is the line number.</p> <h5>Semantics:</h5> +<p>This intrinsic allows annotation of local variables with arbitrary strings. + This can be useful for special purpose optimizations that want to look for + these annotations. These have no other defined use, they are ignored by code + generation and optimization.</p> -<p> -This intrinsic allows annotation of local variables with arbitrary strings. -This can be useful for special purpose optimizations that want to look for these -annotations. These have no other defined use, they are ignored by code -generation and optimization. -</p> </div> <!-- _______________________________________________________________________ --> @@ -7108,9 +7177,9 @@ generation and optimization. <div class="doc_text"> <h5>Syntax:</h5> -<p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on -any integer bit width. -</p> +<p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on + any integer bit width.</p> + <pre> declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int> ) declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int> ) @@ -7120,28 +7189,20 @@ any integer bit width. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.annotation</tt>' intrinsic. -</p> +<p>The '<tt>llvm.annotation</tt>' intrinsic.</p> <h5>Arguments:</h5> - -<p> -The first argument is an integer value (result of some expression), -the second is a pointer to a global string, the third is a pointer to a global -string which is the source file name, and the last argument is the line number. -It returns the value of the first argument. -</p> +<p>The first argument is an integer value (result of some expression), the + second is a pointer to a global string, the third is a pointer to a global + string which is the source file name, and the last argument is the line + number. It returns the value of the first argument.</p> <h5>Semantics:</h5> +<p>This intrinsic allows annotations to be put on arbitrary expressions with + arbitrary strings. This can be useful for special purpose optimizations that + want to look for these annotations. These have no other defined use, they + are ignored by code generation and optimization.</p> -<p> -This intrinsic allows annotations to be put on arbitrary expressions -with arbitrary strings. This can be useful for special purpose optimizations -that want to look for these annotations. These have no other defined use, they -are ignored by code generation and optimization. -</p> </div> <!-- _______________________________________________________________________ --> @@ -7157,58 +7218,50 @@ are ignored by code generation and optimization. </pre> <h5>Overview:</h5> - -<p> -The '<tt>llvm.trap</tt>' intrinsic -</p> +<p>The '<tt>llvm.trap</tt>' intrinsic.</p> <h5>Arguments:</h5> - -<p> -None -</p> +<p>None.</p> <h5>Semantics:</h5> +<p>This intrinsics is lowered to the target dependent trap instruction. If the + target does not have a trap instruction, this intrinsic will be lowered to + the call of the <tt>abort()</tt> function.</p> -<p> -This intrinsics is lowered to the target dependent trap instruction. If the -target does not have a trap instruction, this intrinsic will be lowered to the -call of the abort() function. -</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="int_stackprotector">'<tt>llvm.stackprotector</tt>' Intrinsic</a> </div> + <div class="doc_text"> + <h5>Syntax:</h5> <pre> -declare void @llvm.stackprotector( i8* <guard>, i8** <slot> ) - + declare void @llvm.stackprotector( i8* <guard>, i8** <slot> ) </pre> + <h5>Overview:</h5> -<p> - The <tt>llvm.stackprotector</tt> intrinsic takes the <tt>guard</tt> and stores - it onto the stack at <tt>slot</tt>. The stack slot is adjusted to ensure that - it is placed on the stack before local variables. -</p> +<p>The <tt>llvm.stackprotector</tt> intrinsic takes the <tt>guard</tt> and + stores it onto the stack at <tt>slot</tt>. The stack slot is adjusted to + ensure that it is placed on the stack before local variables.</p> + <h5>Arguments:</h5> -<p> - The <tt>llvm.stackprotector</tt> intrinsic requires two pointer arguments. The - first argument is the value loaded from the stack guard - <tt>@__stack_chk_guard</tt>. The second variable is an <tt>alloca</tt> that - has enough space to hold the value of the guard. -</p> +<p>The <tt>llvm.stackprotector</tt> intrinsic requires two pointer + arguments. The first argument is the value loaded from the stack + guard <tt>@__stack_chk_guard</tt>. The second variable is an <tt>alloca</tt> + that has enough space to hold the value of the guard.</p> + <h5>Semantics:</h5> -<p> - This intrinsic causes the prologue/epilogue inserter to force the position of - the <tt>AllocaInst</tt> stack slot to be before local variables on the - stack. This is to ensure that if a local variable on the stack is overwritten, - it will destroy the value of the guard. When the function exits, the guard on - the stack is checked against the original guard. If they're different, then - the program aborts by calling the <tt>__stack_chk_fail()</tt> function. -</p> +<p>This intrinsic causes the prologue/epilogue inserter to force the position of + the <tt>AllocaInst</tt> stack slot to be before local variables on the + stack. This is to ensure that if a local variable on the stack is + overwritten, it will destroy the value of the guard. When the function exits, + the guard on the stack is checked against the original guard. If they're + different, then the program aborts by calling the <tt>__stack_chk_fail()</tt> + function.</p> + </div> <!-- *********************************************************************** --> @@ -7221,7 +7274,7 @@ declare void @llvm.stackprotector( i8* <guard>, i8** <slot> ) <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2009-06-20 13:26:06 +0000 (Sat, 20 Jun 2009) $ + Last modified: $Date: 2009-10-13 23:56:55 +0200 (Tue, 13 Oct 2009) $ </address> </body> |
