diff options
| author | mike-m <mikem.llvm@gmail.com> | 2010-05-06 23:45:43 +0000 |
|---|---|---|
| committer | mike-m <mikem.llvm@gmail.com> | 2010-05-06 23:45:43 +0000 |
| commit | 68cb31901c590cabceee6e6356d62c84142114cb (patch) | |
| tree | 6444bddc975b662fbe47d63cd98a7b776a407c1a /docs/LangRef.html | |
| parent | c26ae5ab7e2d65b67c97524e66f50ce86445dec7 (diff) | |
Overhauled llvm/clang docs builds. Closes PR6613.
NOTE: 2nd part changeset for cfe trunk to follow.
*** PRE-PATCH ISSUES ADDRESSED
- clang api docs fail build from objdir
- clang/llvm api docs collide in install PREFIX/
- clang/llvm main docs collide in install
- clang/llvm main docs have full of hard coded destination
assumptions and make use of absolute root in static html files;
namely CommandGuide tools hard codes a website destination
for cross references and some html cross references assume
website root paths
*** IMPROVEMENTS
- bumped Doxygen from 1.4.x -> 1.6.3
- splits llvm/clang docs into 'main' and 'api' (doxygen) build trees
- provide consistent, reliable doc builds for both main+api docs
- support buid vs. install vs. website intentions
- support objdir builds
- document targets with 'make help'
- correct clean and uninstall operations
- use recursive dir delete only where absolutely necessary
- added call function fn.RMRF which safeguards against botched 'rm -rf';
if any target (or any variable is evaluated) which attempts
to remove any dirs which match a hard-coded 'safelist', a verbose
error will be printed and make will error-stop.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@103213 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/LangRef.html')
| -rw-r--r-- | docs/LangRef.html | 7780 |
1 files changed, 0 insertions, 7780 deletions
diff --git a/docs/LangRef.html b/docs/LangRef.html deleted file mode 100644 index 5a73f6afd8..0000000000 --- a/docs/LangRef.html +++ /dev/null @@ -1,7780 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> - <title>LLVM Assembly Language Reference Manual</title> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <meta name="author" content="Chris Lattner"> - <meta name="description" - content="LLVM Assembly Language Reference Manual."> - <link rel="stylesheet" href="llvm.css" type="text/css"> -</head> - -<body> - -<div class="doc_title"> LLVM Language Reference Manual </div> -<ol> - <li><a href="#abstract">Abstract</a></li> - <li><a href="#introduction">Introduction</a></li> - <li><a href="#identifiers">Identifiers</a></li> - <li><a href="#highlevel">High Level Structure</a> - <ol> - <li><a href="#modulestructure">Module Structure</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> - <li><a href="#functionstructure">Functions</a></li> - <li><a href="#aliasstructure">Aliases</a></li> - <li><a href="#namedmetadatastructure">Named Metadata</a></li> - <li><a href="#paramattrs">Parameter Attributes</a></li> - <li><a href="#fnattrs">Function Attributes</a></li> - <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> - <li><a href="#volatile">Volatile Memory Accesses</a></li> - </ol> - </li> - <li><a href="#typesystem">Type System</a> - <ol> - <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> - <li><a href="#t_metadata">Metadata Type</a></li> - </ol> - </li> - <li><a href="#t_derived">Derived Types</a> - <ol> - <li><a href="#t_aggregate">Aggregate Types</a> - <ol> - <li><a href="#t_array">Array Type</a></li> - <li><a href="#t_struct">Structure Type</a></li> - <li><a href="#t_pstruct">Packed Structure Type</a></li> - <li><a href="#t_union">Union Type</a></li> - <li><a href="#t_vector">Vector Type</a></li> - </ol> - </li> - <li><a href="#t_function">Function Type</a></li> - <li><a href="#t_pointer">Pointer Type</a></li> - <li><a href="#t_opaque">Opaque Type</a></li> - </ol> - </li> - <li><a href="#t_uprefs">Type Up-references</a></li> - </ol> - </li> - <li><a href="#constants">Constants</a> - <ol> - <li><a href="#simpleconstants">Simple Constants</a></li> - <li><a href="#complexconstants">Complex Constants</a></li> - <li><a href="#globalconstants">Global Variable and Function Addresses</a></li> - <li><a href="#undefvalues">Undefined Values</a></li> - <li><a href="#trapvalues">Trap Values</a></li> - <li><a href="#blockaddress">Addresses of Basic Blocks</a></li> - <li><a href="#constantexprs">Constant Expressions</a></li> - </ol> - </li> - <li><a href="#othervalues">Other Values</a> - <ol> - <li><a href="#inlineasm">Inline Assembler Expressions</a></li> - <li><a href="#metadata">Metadata Nodes and Metadata Strings</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> - <ol> - <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li> - <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li> - <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li> - <li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li> - <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li> - <li><a href="#i_unwind">'<tt>unwind</tt>' Instruction</a></li> - <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li> - </ol> - </li> - <li><a href="#binaryops">Binary Operations</a> - <ol> - <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li> - <li><a href="#i_fadd">'<tt>fadd</tt>' Instruction</a></li> - <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li> - <li><a href="#i_fsub">'<tt>fsub</tt>' Instruction</a></li> - <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li> - <li><a href="#i_fmul">'<tt>fmul</tt>' Instruction</a></li> - <li><a href="#i_udiv">'<tt>udiv</tt>' Instruction</a></li> - <li><a href="#i_sdiv">'<tt>sdiv</tt>' Instruction</a></li> - <li><a href="#i_fdiv">'<tt>fdiv</tt>' Instruction</a></li> - <li><a href="#i_urem">'<tt>urem</tt>' Instruction</a></li> - <li><a href="#i_srem">'<tt>srem</tt>' Instruction</a></li> - <li><a href="#i_frem">'<tt>frem</tt>' Instruction</a></li> - </ol> - </li> - <li><a href="#bitwiseops">Bitwise Binary Operations</a> - <ol> - <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li> - <li><a href="#i_lshr">'<tt>lshr</tt>' Instruction</a></li> - <li><a href="#i_ashr">'<tt>ashr</tt>' Instruction</a></li> - <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li> - <li><a href="#i_or">'<tt>or</tt>' Instruction</a></li> - <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li> - </ol> - </li> - <li><a href="#vectorops">Vector Operations</a> - <ol> - <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li> - <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li> - <li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li> - </ol> - </li> - <li><a href="#aggregateops">Aggregate Operations</a> - <ol> - <li><a href="#i_extractvalue">'<tt>extractvalue</tt>' Instruction</a></li> - <li><a href="#i_insertvalue">'<tt>insertvalue</tt>' Instruction</a></li> - </ol> - </li> - <li><a href="#memoryops">Memory Access and Addressing Operations</a> - <ol> - <li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li> - <li><a href="#i_load">'<tt>load</tt>' Instruction</a></li> - <li><a href="#i_store">'<tt>store</tt>' Instruction</a></li> - <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li> - </ol> - </li> - <li><a href="#convertops">Conversion Operations</a> - <ol> - <li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li> - <li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li> - <li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li> - <li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li> - <li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li> - <li><a href="#i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a></li> - <li><a href="#i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a></li> - <li><a href="#i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a></li> - <li><a href="#i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a></li> - <li><a href="#i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a></li> - <li><a href="#i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a></li> - <li><a href="#i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a></li> - </ol> - </li> - <li><a href="#otherops">Other Operations</a> - <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_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> - <li><a href="#i_va_arg">'<tt>va_arg</tt>' Instruction</a></li> - </ol> - </li> - </ol> - </li> - <li><a href="#intrinsics">Intrinsic Functions</a> - <ol> - <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a> - <ol> - <li><a href="#int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li> - <li><a href="#int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a></li> - <li><a href="#int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a></li> - </ol> - </li> - <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a> - <ol> - <li><a href="#int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li> - <li><a href="#int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li> - <li><a href="#int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li> - </ol> - </li> - <li><a href="#int_codegen">Code Generator Intrinsics</a> - <ol> - <li><a href="#int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li> - <li><a href="#int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a></li> - <li><a href="#int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a></li> - <li><a href="#int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li> - <li><a href="#int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li> - <li><a href="#int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li> - <li><a href="#int_readcyclecounter"><tt>llvm.readcyclecounter</tt>' Intrinsic</a></li> - </ol> - </li> - <li><a href="#int_libc">Standard C Library Intrinsics</a> - <ol> - <li><a href="#int_memcpy">'<tt>llvm.memcpy.*</tt>' Intrinsic</a></li> - <li><a href="#int_memmove">'<tt>llvm.memmove.*</tt>' Intrinsic</a></li> - <li><a href="#int_memset">'<tt>llvm.memset.*</tt>' Intrinsic</a></li> - <li><a href="#int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a></li> - <li><a href="#int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a></li> - <li><a href="#int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a></li> - <li><a href="#int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a></li> - <li><a href="#int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a></li> - </ol> - </li> - <li><a href="#int_manip">Bit Manipulation Intrinsics</a> - <ol> - <li><a href="#int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a></li> - <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> - </ol> - </li> - <li><a href="#int_overflow">Arithmetic with Overflow Intrinsics</a> - <ol> - <li><a href="#int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt> Intrinsics</a></li> - <li><a href="#int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt> Intrinsics</a></li> - <li><a href="#int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt> Intrinsics</a></li> - <li><a href="#int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt> Intrinsics</a></li> - <li><a href="#int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt> Intrinsics</a></li> - <li><a href="#int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt> Intrinsics</a></li> - </ol> - </li> - <li><a href="#int_fp16">Half Precision Floating Point Intrinsics</a> - <ol> - <li><a href="#int_convert_to_fp16">'<tt>llvm.convert.to.fp16</tt>' Intrinsic</a></li> - <li><a href="#int_convert_from_fp16">'<tt>llvm.convert.from.fp16</tt>' Intrinsic</a></li> - </ol> - </li> - <li><a href="#int_debugger">Debugger intrinsics</a></li> - <li><a href="#int_eh">Exception Handling intrinsics</a></li> - <li><a href="#int_trampoline">Trampoline Intrinsic</a> - <ol> - <li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li> - </ol> - </li> - <li><a href="#int_atomics">Atomic intrinsics</a> - <ol> - <li><a href="#int_memory_barrier"><tt>llvm.memory_barrier</tt></a></li> - <li><a href="#int_atomic_cmp_swap"><tt>llvm.atomic.cmp.swap</tt></a></li> - <li><a href="#int_atomic_swap"><tt>llvm.atomic.swap</tt></a></li> - <li><a href="#int_atomic_load_add"><tt>llvm.atomic.load.add</tt></a></li> - <li><a href="#int_atomic_load_sub"><tt>llvm.atomic.load.sub</tt></a></li> - <li><a href="#int_atomic_load_and"><tt>llvm.atomic.load.and</tt></a></li> - <li><a href="#int_atomic_load_nand"><tt>llvm.atomic.load.nand</tt></a></li> - <li><a href="#int_atomic_load_or"><tt>llvm.atomic.load.or</tt></a></li> - <li><a href="#int_atomic_load_xor"><tt>llvm.atomic.load.xor</tt></a></li> - <li><a href="#int_atomic_load_max"><tt>llvm.atomic.load.max</tt></a></li> - <li><a href="#int_atomic_load_min"><tt>llvm.atomic.load.min</tt></a></li> - <li><a href="#int_atomic_load_umax"><tt>llvm.atomic.load.umax</tt></a></li> - <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"> - '<tt>llvm.var.annotation</tt>' Intrinsic</a></li> - <li><a href="#int_annotation"> - '<tt>llvm.annotation.*</tt>' Intrinsic</a></li> - <li><a href="#int_trap"> - '<tt>llvm.trap</tt>' Intrinsic</a></li> - <li><a href="#int_stackprotector"> - '<tt>llvm.stackprotector</tt>' Intrinsic</a></li> - <li><a href="#int_objectsize"> - '<tt>llvm.objectsize</tt>' Intrinsic</a></li> - </ol> - </li> - </ol> - </li> -</ol> - -<div class="doc_author"> - <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> - and <a href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></p> -</div> - -<!-- *********************************************************************** --> -<div class="doc_section"> <a name="abstract">Abstract </a></div> -<!-- *********************************************************************** --> - -<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> - -</div> - -<!-- *********************************************************************** --> -<div class="doc_section"> <a name="introduction">Introduction</a> </div> -<!-- *********************************************************************** --> - -<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 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> - -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> <a name="wellformed">Well-Formedness</a> </div> - -<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> - -<div class="doc_code"> -<pre> -%x = <a href="#i_add">add</a> i32 1, %x -</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> - -</div> - -<!-- Describe the typesetting conventions here. --> - -<!-- *********************************************************************** --> -<div class="doc_section"> <a name="identifiers">Identifiers</a> </div> -<!-- *********************************************************************** --> - -<div class="doc_text"> - -<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, <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, <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> -</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> - -<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 (<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> - -<p>The easy way:</p> - -<div class="doc_code"> -<pre> -%result = <a href="#i_mul">mul</a> i32 %X, 8 -</pre> -</div> - -<p>After strength reduction:</p> - -<div class="doc_code"> -<pre> -%result = <a href="#i_shl">shl</a> i32 %X, i8 3 -</pre> -</div> - -<p>And the hard way:</p> - -<div class="doc_code"> -<pre> -%0 = <a href="#i_add">add</a> i32 %X, %X <i>; yields {i32}:%0</i> -%1 = <a href="#i_add">add</a> i32 %0, %0 <i>; yields {i32}:%1</i> -%result = <a href="#i_add">add</a> i32 %1, %1 -</pre> -</div> - -<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> - - <li>Unnamed temporaries are created when the result of a computation is not - assigned to a named value.</li> - - <li>Unnamed temporaries are numbered sequentially</li> -</ol> - -<p>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> - -</div> - -<!-- *********************************************************************** --> -<div class="doc_section"> <a name="highlevel">High Level Structure</a> </div> -<!-- *********************************************************************** --> - -<!-- ======================================================================= --> -<div class="doc_subsection"> <a name="modulestructure">Module Structure</a> -</div> - -<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> - -<div class="doc_code"> -<pre> -<i>; Declare the string constant as a global constant.</i> -<a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a> <a 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> - -<i>; Definition of main function</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> - - <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> - <a href="#i_ret">ret</a> i32 0<br>} - -<i>; Named metadata</i> -!1 = metadata !{i32 41} -!foo = !{!1, null} -</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, - a <a href="#functionstructure">function definition</a> for - "<tt>main</tt>" and <a href="#namedmetadatastructure">named metadata</a> - "<tt>foo"</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> - -</div> - -<!-- ======================================================================= --> -<div class="doc_subsection"> - <a name="linkage">Linkage Types</a> -</div> - -<div class="doc_text"> - -<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> - - <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> - - <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> - - <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 can be used to implement - some forms of inline functions, templates, or other code which must be - generated in each translation unit that uses it, but where the body may - be overridden with a more definitive definition later. Unreferenced - <tt>linkonce</tt> globals are allowed to be discarded. Note that - <tt>linkonce</tt> linkage does not actually allow the optimizer to - inline the body of this function into callers because it doesn't know if - this definition of the function is the definitive definition within the - program or whether it will be overridden by a stronger definition. - To enable inlining and other optimizations, use "<tt>linkonce_odr</tt>" - linkage.</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> - - - <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> - - <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_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> -</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> - -<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> - - <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> -</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 l |