diff options
| author | Sean Silva <silvas@purdue.edu> | 2012-12-07 10:36:55 +0000 |
|---|---|---|
| committer | Sean Silva <silvas@purdue.edu> | 2012-12-07 10:36:55 +0000 |
| commit | f722b007b201a755b06c48eba8a6058972ddf267 (patch) | |
| tree | ce7b7ca3c46d93dccf23216f9b1328c82ff560f0 | |
| parent | ece6db5f16a83ff4cab3544643d226eeb8a15784 (diff) | |
docs: Convert LangRef to reST.
NOTE: If you have any patches in the works that modify LangRef, you will
need to rewrite the changes to LangRef.html to their equivalents in
LangRef.rst. If you need assistance feel free to contact me.
Since LangRef is mission-critical for the project and "normative", I
have taken extra care to ensure that no content was lost or altered in
the conversion. The content was converted with a tool called `pandoc`,
so there is no chance for a human error like accidentally forgetting a
sentence or whatever. After the initial conversion by `pandoc`, only
changes to the markup were done.
This is just the most literal conversion of the HTML document as
possible. It might be worth exploring some way to chop up this massive
document into separate pages, e.g. something like
`docs/LangRef/Instructions.rst`, `docs/LangRef/Intrinsics.rst`, etc.
with `docs/LangRef.rst` being an "intro/navigation page" of sorts. On
the other hand, that loses the ability to {Ctrl,Cmd}-F for a given term
right from your browser.
IMO, I think our stylesheet needs some work because I find it hard to
tell what level of nesting some of the headings are at (e.g. "is this a
new section or is it a subsection?"). The issue is present on other
pages, but the sheer size and deep section structure of LangRef really
brings this issue out. If there are any web designers out there in the
community it would be awesome if you tried to come up with something
nicer.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@169596 91177308-0d34-0410-b5e6-96231b3b80d8
| -rw-r--r-- | docs/LangRef.html | 9099 | ||||
| -rw-r--r-- | docs/LangRef.rst | 8301 | ||||
| -rw-r--r-- | docs/design_and_overview.rst | 3 |
3 files changed, 8303 insertions, 9100 deletions
diff --git a/docs/LangRef.html b/docs/LangRef.html deleted file mode 100644 index b4782c273d..0000000000 --- a/docs/LangRef.html +++ /dev/null @@ -1,9099 +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="_static/llvm.css" type="text/css"> -</head> - -<body> - -<h1>LLVM Language Reference Manual</h1> -<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_linker_private_weak">'<tt>linker_private_weak</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_linkonce_odr_auto_hide">'<tt>linkonce_odr_auto_hide</tt>' Linkage</a></li> - <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li> - <li><a href="#linkage_external">'<tt>external</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> - <li><a href="#memmodel">Memory Model for Concurrent Operations</a></li> - <li><a href="#ordering">Atomic Memory Ordering Constraints</a></li> - <li><a href="#fastmath">Fast-Math Flags</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_x86mmx">X86mmx Type</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_opaque">Opaque Structure Types</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> - </ol> - </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="#poisonvalues">Poison 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> - <ol> - <li><a href="#tbaa">'<tt>tbaa</tt>' Metadata</a></li> - <li><a href="#tbaa.struct">'<tt>tbaa.struct</tt>' Metadata</a></li> - <li><a href="#fpmath">'<tt>fpmath</tt>' Metadata</a></li> - <li><a href="#range">'<tt>range</tt>' Metadata</a></li> - </ol> - </li> - </ol> - </li> - <li><a href="#module_flags">Module Flags Metadata</a> - <ol> - <li><a href="#objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</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_resume">'<tt>resume</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_fence">'<tt>fence</tt>' Instruction</a></li> - <li><a href="#i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a></li> - <li><a href="#i_atomicrmw">'<tt>atomicrmw</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> - <li><a href="#i_landingpad">'<tt>landingpad</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> - <li><a href="#int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a></li> - <li><a href="#int_exp2">'<tt>llvm.exp2.*</tt>' Intrinsic</a></li> - <li><a href="#int_log">'<tt>llvm.log.*</tt>' Intrinsic</a></li> - <li><a href="#int_log10">'<tt>llvm.log10.*</tt>' Intrinsic</a></li> - <li><a href="#int_log2">'<tt>llvm.log2.*</tt>' Intrinsic</a></li> - <li><a href="#int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a></li> - <li><a href="#int_fabs">'<tt>llvm.fabs.*</tt>' Intrinsic</a></li> - <li><a href="#int_floor">'<tt>llvm.floor.*</tt>' Intrinsic</a></li> - <li><a href="#int_ceil">'<tt>llvm.ceil.*</tt>' Intrinsic</a></li> - <li><a href="#int_trunc">'<tt>llvm.trunc.*</tt>' Intrinsic</a></li> - <li><a href="#int_rint">'<tt>llvm.rint.*</tt>' Intrinsic</a></li> - <li><a href="#int_nearbyint">'<tt>llvm.nearbyint.*</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="#spec_arithmetic">Specialised Arithmetic Intrinsics</a> - <ol> - <li><a href="#fmuladd">'<tt>llvm.fmuladd</tt> Intrinsic</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 Intrinsics</a> - <ol> - <li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li> - <li><a href="#int_at">'<tt>llvm.adjust.trampoline</tt>' Intrinsic</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>' Intrinsic</a></li> - <li><a href="#int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a></li> - <li><a href="#int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a></li> - <li><a href="#int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</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_debugtrap"> - '<tt>llvm.debugtrap</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> - <li><a href="#int_expect"> - '<tt>llvm.expect</tt>' Intrinsic</a></li> - <li><a href="#int_donothing"> - '<tt>llvm.donothing</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> - -<!-- *********************************************************************** --> -<h2><a name="abstract">Abstract</a></h2> -<!-- *********************************************************************** --> - -<div> - -<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> - -<!-- *********************************************************************** --> -<h2><a name="introduction">Introduction</a></h2> -<!-- *********************************************************************** --> - -<div> - -<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> - -<!-- _______________________________________________________________________ --> -<h4> - <a name="wellformed">Well-Formedness</a> -</h4> - -<div> - -<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> - -<pre class="doc_code"> -%x = <a href="#i_add">add</a> i32 1, %x -</pre> - -<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> - -</div> - -<!-- Describe the typesetting conventions here. --> - -<!-- *********************************************************************** --> -<h2><a name="identifiers">Identifiers</a></h2> -<!-- *********************************************************************** --> - -<div> - -<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> - -<pre class="doc_code"> -%result = <a href="#i_mul">mul</a> i32 %X, 8 -</pre> - -<p>After strength reduction:</p> - -<pre class="doc_code"> -%result = <a href="#i_shl">shl</a> i32 %X, i8 3 -</pre> - -<p>And the hard way:</p> - -<pre class="doc_code"> -%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> - -<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> - -<!-- *********************************************************************** --> -<h2><a name="highlevel">High Level Structure</a></h2> -<!-- *********************************************************************** --> -<div> -<!-- ======================================================================= --> -<h3> - <a name="modulestructure">Module Structure</a> -</h3> - -<div> - -<p>LLVM programs are composed of <tt>Module</tt>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> - -<pre class="doc_code"> -<i>; Declare the string constant as a global constant.</i> -<a href="#identifiers">@.str</a> = <a href="#linkage_private">private</a> <a href="#globalvars">unnamed_addr</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" - -<i>; External declaration of the puts function</i> -<a href="#functionstructure">declare</a> i32 @puts(i8* <a href="#nocapture">nocapture</a>) <a href="#fnattrs">nounwind</a> - -<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]* @.str, i64 0, i64 0 - - <i>; Call puts function to write out the string to stdout.</i> - <a href="#i_call">call</a> i32 @puts(i8* %cast210) - <a href="#i_ret">ret</a> i32 0 -} - -<i>; Named metadata</i> -!1 = metadata !{i32 42} -!foo = !{!1, null} -</pre> - -<p>This example is made up of a <a href="#globalvars">global variable</a> named - "<tt>.str</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> - -<!-- ======================================================================= --> -<h3> - <a name="linkage">Linkage Types</a> -</h3> - -<div> - -<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 "<tt>private</tt>" 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 <tt>private</tt>, but the symbol is passed through the - assembler and evaluated by the linker. 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_linker_private_weak">linker_private_weak</a></b></tt></dt> - <dd>Similar to "<tt>linker_private</tt>", but the symbol is weak. Note that - <tt>linker_private_weak</tt> symbols are subject to coalescing by the - linker. The symbols 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>" lin |