diff options
| -rw-r--r-- | docs/LangRef.html | 5374 |
1 files changed, 2598 insertions, 2776 deletions
diff --git a/docs/LangRef.html b/docs/LangRef.html index 4fb712ee3b..9b801cffc3 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -287,12 +287,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> <!-- *********************************************************************** --> @@ -301,26 +302,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> @@ -329,10 +328,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> @@ -340,13 +339,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. --> @@ -357,44 +356,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> @@ -422,25 +424,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> @@ -454,12 +454,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> @@ -467,32 +467,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> @@ -503,21 +503,18 @@ 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> @@ -526,121 +523,111 @@ All Global Variables and Functions have one of the following types of linkage: <dt><tt><b><a name="linkage_internal">internal</a></b></tt>: </dt> - <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> + <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> - <dt><tt><b><a name="linkage_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> + 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> + <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> <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt> <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> + 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> + <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>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> <!-- ======================================================================= --> @@ -651,55 +638,52 @@ 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> @@ -710,37 +694,32 @@ 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> @@ -753,9 +732,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> @@ -763,19 +741,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> @@ -787,48 +765,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-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> + 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 |