| <!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> |
| </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_log">'<tt>llvm.log.*</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> |
| </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>" 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_linkonce_odr_auto_hide">linkonce_odr_auto_hide</a></b></tt></dt> |
| <dd>Similar to "<tt>linkonce_odr</tt>", but nothing in the translation unit |
| takes the address of this definition. For instance, functions that had an |
| inline definition, but the compiler decided not to inline it. |
| <tt>linkonce_odr_auto_hide</tt> may have only <tt>default</tt> visibility. |
| The symbols are removed by the linker from the final linked image |
| (executable or dynamic library).</dd> |
| |
| <dt><tt><b><a name="linkage_external">external</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 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 <tt>external</tt>, <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> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="callingconv">Calling Conventions</a> |
| </h3> |
| |
| <div> |
| |
| <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> |
| |
| <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> |
| |
| <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). |
| <a href="CodeGenerator.html#tailcallopt">Tail calls can only be optimized |
| when this or the GHC convention is used.</a> 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> |
| |
| <dt><b>"<tt>cc <em>10</em></tt>" - GHC convention</b>:</dt> |
| <dd>This calling convention has been implemented specifically for use by the |
| <a href="http://www.haskell.org/ghc">Glasgow Haskell Compiler (GHC)</a>. |
| It passes everything in registers, going to extremes to achieve this by |
| disabling callee save registers. This calling convention should not be |
| used lightly but only for specific situations such as an alternative to |
| the <em>register pinning</em> performance technique often used when |
| implementing functional programming languages.At the moment only X86 |
| supports this convention and it has the following limitations: |
| <ul> |
| <li>On <em>X86-32</em> only supports up to 4 bit type parameters. No |
| floating point types are supported.</li> |
| <li>On <em>X86-64</em> only supports up to 10 bit type parameters and |
| 6 floating point parameters.</li> |
| </ul> |
| This calling convention supports |
| <a href="CodeGenerator.html#tailcallopt">tail call optimization</a> but |
| requires both the caller and callee are using it. |
| </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> |
| </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> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="visibility">Visibility Styles</a> |
| </h3> |
| |
| <div> |
| |
| <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> |
| |
| <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> |
| |
| <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> |
| </dl> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="namedtypes">Named Types</a> |
| </h3> |
| |
| <div> |
| |
| <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> |
| |
| <pre class="doc_code"> |
| %mytype = type { %mytype*, i32 } |
| </pre> |
| |
| <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> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="globalvars">Global Variables</a> |
| </h3> |
| |
| <div> |
| |
| <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.</p> |
| |
| <p>A variable may be defined as <tt>thread_local</tt>, which |
| means that it will not be shared by threads (each thread will have a |
| separated copy of the variable). Not all targets support thread-local |
| variables. Optionally, a TLS model may be specified:</p> |
| |
| <dl> |
| <dt><b><tt>localdynamic</tt></b>:</dt> |
| <dd>For variables that are only used within the current shared library.</dd> |
| |
| <dt><b><tt>initialexec</tt></b>:</dt> |
| <dd>For variables in modules that will not be loaded dynamically.</dd> |
| |
| <dt><b><tt>localexec</tt></b>:</dt> |
| <dd>For variables defined in the executable and only used within it.</dd> |
| </dl> |
| |
| <p>The models correspond to the ELF TLS models; see |
| <a href="http://people.redhat.com/drepper/tls.pdf">ELF |
| Handling For Thread-Local Storage</a> for more information on under which |
| circumstances the different models may be used. The target may choose a |
| different TLS model if the specified model is not supported, or if a better |
| choice of model can be made.</p> |
| |
| <p>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>Global variables can be marked with <tt>unnamed_addr</tt> which indicates |
| that the address is not significant, only the content. Constants marked |
| like this can be merged with other constants if they have the same |
| initializer. Note that a constant with significant address <em>can</em> |
| be merged with a <tt>unnamed_addr</tt> constant, the result being a |
| constant whose address is significant.</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> |
| |
| <p>An explicit alignment may be specified for a global, which must be a power |
| of 2. 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 exactly that |
| alignment. Targets and optimizers are not allowed to over-align the global |
| if the global has an assigned section. In this case, the extra alignment |
| could be observable: for example, code could assume that the globals are |
| densely packed in their section and try to iterate over them as an array, |
| alignment padding would break this iteration.</p> |
| |
| <p>For example, the following defines a global in a numbered address space with |
| an initializer, section, and alignment:</p> |
| |
| <pre class="doc_code"> |
| @G = addrspace(5) constant float 1.0, section "foo", align 4 |
| </pre> |
| |
| <p>The following example defines a thread-local global with |
| the <tt>initialexec</tt> TLS model:</p> |
| |
| <pre class="doc_code"> |
| @G = thread_local(initialexec) global i32 0, align 4 |
| </pre> |
| |
| </div> |
| |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="functionstructure">Functions</a> |
| </h3> |
| |
| <div> |
| |
| <p>LLVM function definitions consist of the "<tt>define</tt>" keyword, an |
| optional <a href="#linkage">linkage type</a>, an optional |
| <a href="#visibility">visibility style</a>, an optional |
| <a href="#callingconv">calling convention</a>, |
| an optional <tt>unnamed_addr</tt> attribute, a return type, an optional |
| <a href="#paramattrs">parameter attribute</a> for the return type, a function |
| name, a (possibly empty) argument list (each with optional |
| <a href="#paramattrs">parameter attributes</a>), optional |
| <a href="#fnattrs">function attributes</a>, an optional section, an optional |
| alignment, an optional <a href="#gc">garbage collector name</a>, an opening |
| curly brace, a list of basic blocks, and a closing curly brace.</p> |
| |
| <p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an |
| optional <a href="#linkage">linkage type</a>, an optional |
| <a href="#visibility">visibility style</a>, an optional |
| <a href="#callingconv">calling convention</a>, |
| an optional <tt>unnamed_addr</tt> attribute, a return type, an optional |
| <a href="#paramattrs">parameter attribute</a> for the return type, a function |
| name, a possibly empty list of arguments, an optional alignment, and an |
| optional <a href="#gc">garbage collector name</a>.</p> |
| |
| <p>A function definition contains a list of basic blocks, forming the CFG |
| (Control Flow Graph) for the function. Each basic block may optionally start |
| with a label (giving the basic block a symbol table entry), contains a list |
| of instructions, and ends with a <a href="#terminators">terminator</a> |
| instruction (such as a branch or function return).</p> |
| |
| <p>The first basic block in a function is special in two ways: it is immediately |
| executed on entrance to the function, and it is not allowed to have |
| predecessor basic blocks (i.e. there can not be any branches to the entry |
| block of a function). Because the block can have no predecessors, it also |
| cannot have any <a href="#i_phi">PHI nodes</a>.</p> |
| |
| <p>LLVM allows an explicit section to be specified for functions. If the target |
| supports it, it will emit functions to the section specified.</p> |
| |
| <p>An explicit alignment may be specified for a function. If not present, or if |
| the alignment is set to zero, the alignment of the function is set by the |
| target to whatever it feels convenient. If an explicit alignment is |
| specified, the function is forced to have at least that much alignment. All |
| alignments must be a power of 2.</p> |
| |
| <p>If the <tt>unnamed_addr</tt> attribute is given, the address is know to not |
| be significant and two identical functions can be merged.</p> |
| |
| <h5>Syntax:</h5> |
| <pre class="doc_code"> |
| define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>] |
| [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] |
| <ResultType> @<FunctionName> ([argument list]) |
| [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N] |
| [<a href="#gc">gc</a>] { ... } |
| </pre> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="aliasstructure">Aliases</a> |
| </h3> |
| |
| <div> |
| |
| <p>Aliases act as "second name" for the aliasee value (which can be either |
| function, global variable, another alias or bitcast of global value). Aliases |
| may have an optional <a href="#linkage">linkage type</a>, and an |
| optional <a href="#visibility">visibility style</a>.</p> |
| |
| <h5>Syntax:</h5> |
| <pre class="doc_code"> |
| @<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee> |
| </pre> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="namedmetadatastructure">Named Metadata</a> |
| </h3> |
| |
| <div> |
| |
| <p>Named metadata is a collection of metadata. <a href="#metadata">Metadata |
| nodes</a> (but not metadata strings) are the only valid operands for |
| a named metadata.</p> |
| |
| <h5>Syntax:</h5> |
| <pre class="doc_code"> |
| ; Some unnamed metadata nodes, which are referenced by the named metadata. |
| !0 = metadata !{metadata !"zero"} |
| !1 = metadata !{metadata !"one"} |
| !2 = metadata !{metadata !"two"} |
| ; A named metadata. |
| !name = !{!0, !1, !2} |
| </pre> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="paramattrs">Parameter Attributes</a> |
| </h3> |
| |
| <div> |
| |
| <p>The return type and each parameter of a function type may have a set of |
| <i>parameter attributes</i> associated with them. Parameter attributes are |
| used to communicate additional information about the result or parameters of |
| a function. Parameter attributes are considered to be part of the function, |
| not of the function type, so functions with different parameter attributes |
| can have the same function type.</p> |
| |
| <p>Parameter attributes are simple keywords that follow the type specified. If |
| multiple parameter attributes are needed, they are space separated. For |
| example:</p> |
| |
| <pre class="doc_code"> |
| declare i32 @printf(i8* noalias nocapture, ...) |
| declare i32 @atoi(i8 zeroext) |
| declare signext i8 @returns_signed_char() |
| </pre> |
| |
| <p>Note that any attributes for the function result (<tt>nounwind</tt>, |
| <tt>readonly</tt>) come immediately after the argument list.</p> |
| |
| <p>Currently, only the following parameter attributes are defined:</p> |
| |
| <dl> |
| <dt><tt><b>zeroext</b></tt></dt> |
| <dd>This indicates to the code generator that the parameter or return value |
| should be zero-extended to the extent required by the target's ABI (which |
| is usually 32-bits, but is 8-bits for a i1 on x86-64) by the caller (for a |
| parameter) or the callee (for a return value).</dd> |
| |
| <dt><tt><b>signext</b></tt></dt> |
| <dd>This indicates to the code generator that the parameter or return value |
| should be sign-extended to the extent required by the target's ABI (which |
| is usually 32-bits) by the caller (for a parameter) or the callee (for a |
| return value).</dd> |
| |
| <dt><tt><b>inreg</b></tt></dt> |
| <dd>This indicates that this parameter or return value should be treated in a |
| special target-dependent fashion during while emitting code for a function |
| call or return (usually, by putting it in a register as opposed to memory, |
| though some targets use it to distinguish between two different kinds of |
| registers). Use of this attribute is target-specific.</dd> |
| |
| <dt><tt><b><a name="byval">byval</a></b></tt></dt> |
| <dd><p>This indicates that the pointer parameter should really be passed by |
| value to the function. The attribute implies that a hidden copy of the |
| pointee |
| is made between the caller and the callee, so the callee is unable to |
| modify the value in the caller. This attribute is only valid on LLVM |
| pointer arguments. It is generally used to pass structs and arrays by |
| value, but is also valid on pointers to scalars. The copy is considered |
| to belong to the caller not the callee (for example, |
| <tt><a href="#readonly">readonly</a></tt> functions should not write to |
| <tt>byval</tt> parameters). This is not a valid attribute for return |
| values.</p> |
| |
| <p>The byval attribute also supports specifying an alignment with |
| the align attribute. It indicates the alignment of the stack slot to |
| form and the known alignment of the pointer specified to the call site. If |
| the alignment is not specified, then the code generator makes a |
| target-specific assumption.</p></dd> |
| |
| <dt><tt><b><a name="sret">sret</a></b></tt></dt> |
| <dd>This indicates that the pointer parameter specifies the address of a |
| structure that is the return value of the function in the source program. |
| This pointer must be guaranteed by the caller to be valid: loads and |
| stores to the structure may be assumed by the callee to not to trap and |
| to be properly aligned. This may only be applied to the first parameter. |
| This is not a valid attribute for return values. </dd> |
| |
| <dt><tt><b><a name="noalias">noalias</a></b></tt></dt> |
| <dd>This indicates that pointer values |
| <a href="#pointeraliasing"><i>based</i></a> on the argument or return |
| value do not alias pointer values which are not <i>based</i> on it, |
| ignoring certain "irrelevant" dependencies. |
| For a call to the parent function, dependencies between memory |
| references from before or after the call and from those during the call |
| are "irrelevant" to the <tt>noalias</tt> keyword for the arguments and |
| return value used in that call. |
| The caller shares the responsibility with the callee for ensuring that |
| these requirements are met. |
| For further details, please see the discussion of the NoAlias response in |
| <a href="AliasAnalysis.html#MustMayNo">alias analysis</a>.<br> |
| <br> |
| Note that this definition of <tt>noalias</tt> is intentionally |
| similar to the definition of <tt>restrict</tt> in C99 for function |
| arguments, though it is slightly weaker. |
| <br> |
| For function return values, C99's <tt>restrict</tt> is not meaningful, |
| while LLVM's <tt>noalias</tt> is. |
| </dd> |
| |
| <dt><tt><b><a name="nocapture">nocapture</a></b></tt></dt> |
| <dd>This indicates that the callee does not make any copies of the pointer |
| that outlive the callee itself. This is not a valid attribute for return |
| values.</dd> |
| |
| <dt><tt><b><a name="nest">nest</a></b></tt></dt> |
| <dd>This indicates that the pointer parameter can be excised using the |
| <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid |
| attribute for return values.</dd> |
| </dl> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="gc">Garbage Collector Names</a> |
| </h3> |
| |
| <div> |
| |
| <p>Each function may specify a garbage collector name, which is simply a |
| string:</p> |
| |
| <pre class="doc_code"> |
| define void @f() gc "name" { ... } |
| </pre> |
| |
| <p>The compiler declares the supported values of <i>name</i>. Specifying a |
| collector which will cause the compiler to alter its output in order to |
| support the named garbage collection algorithm.</p> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="fnattrs">Function Attributes</a> |
| </h3> |
| |
| <div> |
| |
| <p>Function attributes are set to communicate additional information about a |
| function. Function attributes are considered to be part of the function, not |
| of the function type, so functions with different parameter attributes can |
| have the same function type.</p> |
| |
| <p>Function attributes are simple keywords that follow the type specified. If |
| multiple attributes are needed, they are space separated. For example:</p> |
| |
| <pre class="doc_code"> |
| define void @f() noinline { ... } |
| define void @f() alwaysinline { ... } |
| define void @f() alwaysinline optsize { ... } |
| define void @f() optsize { ... } |
| </pre> |
| |
| <dl> |
| <dt><tt><b>address_safety</b></tt></dt> |
| <dd>This attribute indicates that the address safety analysis |
| is enabled for this function. </dd> |
| |
| <dt><tt><b>alignstack(<<em>n</em>>)</b></tt></dt> |
| <dd>This attribute indicates that, when emitting the prologue and epilogue, |
| the backend should forcibly align the stack pointer. Specify the |
| desired alignment, which must be a power of two, in parentheses. |
| |
| <dt><tt><b>alwaysinline</b></tt></dt> |
| <dd>This attribute indicates that the inliner should attempt to inline this |
| function into callers whenever possible, ignoring any active inlining size |
| threshold for this caller.</dd> |
| |
| <dt><tt><b>nonlazybind</b></tt></dt> |
| <dd>This attribute suppresses lazy symbol binding for the function. This |
| may make calls to the function faster, at the cost of extra program |
| startup time if the function is not called during program startup.</dd> |
| |
| <dt><tt><b>inlinehint</b></tt></dt> |
| <dd>This attribute indicates that the source code contained a hint that inlining |
| this function is desirable (such as the "inline" keyword in C/C++). It |
| is just a hint; it imposes no requirements on the inliner.</dd> |
| |
| <dt><tt><b>naked</b></tt></dt> |
| <dd>This attribute disables prologue / epilogue emission for the function. |
| This can have very system-specific consequences.</dd> |
| |
| <dt><tt><b>noimplicitfloat</b></tt></dt> |
| <dd>This attributes disables implicit floating point instructions.</dd> |
| |
| <dt><tt><b>noinline</b></tt></dt> |
| <dd>This attribute indicates that the inliner should never inline this |
| function in any situation. This attribute may not be used together with |
| the <tt>alwaysinline</tt> attribute.</dd> |
| |
| <dt><tt><b>noredzone</b></tt></dt> |
| <dd>This attribute indicates that the code generator should not use a red |
| zone, even if the target-specific ABI normally permits it.</dd> |
| |
| <dt><tt><b>noreturn</b></tt></dt> |
| <dd>This function attribute indicates that the function never returns |
| normally. This produces undefined behavior at runtime if the function |
| ever does dynamically return.</dd> |
| |
| <dt><tt><b>nounwind</b></tt></dt> |
| <dd>This function attribute indicates that the function never returns with an |
| unwind or exceptional control flow. If the function does unwind, its |
| runtime behavior is undefined.</dd> |
| |
| <dt><tt><b>optsize</b></tt></dt> |
| <dd>This attribute suggests that optimization passes and code generator passes |
| make choices that keep the code size of this function low, and otherwise |
| do optimizations specifically to reduce code size.</dd> |
| |
| <dt><tt><b>readnone</b></tt></dt> |
| <dd>This attribute indicates that the function computes its result (or decides |
| to unwind an exception) based strictly on its arguments, without |
| dereferencing any pointer arguments or otherwise accessing any mutable |
| state (e.g. memory, control registers, etc) visible to caller functions. |
| It does not write through any pointer arguments |
| (including <tt><a href="#byval">byval</a></tt> arguments) and never |
| changes any state visible to callers. This means that it cannot unwind |
| exceptions by calling the <tt>C++</tt> exception throwing methods.</dd> |
| |
| <dt><tt><b><a name="readonly">readonly</a></b></tt></dt> |
| <dd>This attribute indicates that the function does not write through any |
| pointer arguments (including <tt><a href="#byval">byval</a></tt> |
| arguments) or otherwise modify any state (e.g. memory, control registers, |
| etc) visible to caller functions. It may dereference pointer arguments |
| and read state that may be set in the caller. A readonly function always |
| returns the same value (or unwinds an exception identically) when called |
| with the same set of arguments and global state. It cannot unwind an |
| exception by calling the <tt>C++</tt> exception throwing methods.</dd> |
| |
| <dt><tt><b><a name="returns_twice">returns_twice</a></b></tt></dt> |
| <dd>This attribute indicates that this function can return twice. The |
| C <code>setjmp</code> is an example of such a function. The compiler |
| disables some optimizations (like tail calls) in the caller of these |
| functions.</dd> |
| |
| <dt><tt><b><a name="ssp">ssp</a></b></tt></dt> |
| <dd>This attribute indicates that the function should emit a stack smashing |
| protector. It is in the form of a "canary"—a random value placed on |
| the stack before the local variables that's checked upon return from the |
| function to see if it has been overwritten. A heuristic is used to |
| determine if a function needs stack protectors or not.<br> |
| <br> |
| If a function that has an <tt>ssp</tt> attribute is inlined into a |
| function that doesn't have an <tt>ssp</tt> attribute, then the resulting |
| function will have an <tt>ssp</tt> attribute.</dd> |
| |
| <dt><tt><b>sspreq</b></tt></dt> |
| <dd>This attribute indicates that the function should <em>always</em> emit a |
| stack smashing protector. This overrides |
| the <tt><a href="#ssp">ssp</a></tt> function attribute.<br> |
| <br> |
| If a function that has an <tt>sspreq</tt> attribute is inlined into a |
| function that doesn't have an <tt>sspreq</tt> attribute or which has |
| an <tt>ssp</tt> attribute, then the resulting function will have |
| an <tt>sspreq</tt> attribute.</dd> |
| |
| <dt><tt><b><a name="uwtable">uwtable</a></b></tt></dt> |
| <dd>This attribute indicates that the ABI being targeted requires that |
| an unwind table entry be produce for this function even if we can |
| show that no exceptions passes by it. This is normally the case for |
| the ELF x86-64 abi, but it can be disabled for some compilation |
| units.</dd> |
| </dl> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="moduleasm">Module-Level Inline Assembly</a> |
| </h3> |
| |
| <div> |
| |
| <p>Modules may contain "module-level inline asm" blocks, which corresponds to |
| the GCC "file scope inline asm" blocks. These blocks are internally |
| concatenated by LLVM and treated as a single unit, but may be separated in |
| the <tt>.ll</tt> file if desired. The syntax is very simple:</p> |
| |
| <pre class="doc_code"> |
| module asm "inline asm code goes here" |
| module asm "more can go here" |
| </pre> |
| |
| <p>The strings can contain any character by escaping non-printable characters. |
| The escape sequence used is simply "\xx" where "xx" is the two digit hex code |
| for the number.</p> |
| |
| <p>The inline asm code is simply printed to the machine code .s file when |
| assembly code is generated.</p> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="datalayout">Data Layout</a> |
| </h3> |
| |
| <div> |
| |
| <p>A module may specify a target specific data layout string that specifies how |
| data is to be laid out in memory. The syntax for the data layout is |
| simply:</p> |
| |
| <pre class="doc_code"> |
| target datalayout = "<i>layout specification</i>" |
| </pre> |
| |
| <p>The <i>layout specification</i> consists of a list of specifications |
| separated by the minus sign character ('-'). Each specification starts with |
| a letter and may include other information after the letter to define some |
| aspect of the data layout. The specifications accepted are as follows:</p> |
| |
| <dl> |
| <dt><tt>E</tt></dt> |
| <dd>Specifies that the target lays out data in big-endian form. That is, the |
| bits with the most significance have the lowest address location.</dd> |
| |
| <dt><tt>e</tt></dt> |
| <dd>Specifies that the target lays out data in little-endian form. That is, |
| the bits with the least significance have the lowest address |
| location.</dd> |
| |
| <dt><tt>S<i>size</i></tt></dt> |
| <dd>Specifies the natural alignment of the stack in bits. Alignment promotion |
| of stack variables is limited to the natural stack alignment to avoid |
| dynamic stack realignment. The stack alignment must be a multiple of |
| 8-bits. If omitted, the natural stack alignment defaults to "unspecified", |
| which does not prevent any alignment promotions.</dd> |
| |
| <dt><tt>p[n]:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> |
| <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and |
| <i>preferred</i> alignments for address space <i>n</i>. All sizes are in |
| bits. Specifying the <i>pref</i> alignment is optional. If omitted, the |
| preceding <tt>:</tt> should be omitted too. The address space, |
| <i>n</i> is optional, and if not specified, denotes the default address |
| space 0. The value of <i>n</i> must be in the range [1,2^23).</dd> |
| |
| <dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> |
| <dd>This specifies the alignment for an integer type of a given bit |
| <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd> |
| |
| <dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> |
| <dd>This specifies the alignment for a vector type of a given bit |
| <i>size</i>.</dd> |
| |
| <dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> |
| <dd>This specifies the alignment for a floating point type of a given bit |
| <i>size</i>. Only values of <i>size</i> that are supported by the target |
| will work. 32 (float) and 64 (double) are supported on all targets; |
| 80 or 128 (different flavors of long double) are also supported on some |
| targets. |
| |
| <dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> |
| <dd>This specifies the alignment for an aggregate type of a given bit |
| <i>size</i>.</dd> |
| |
| <dt><tt>s<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> |
| <dd>This specifies the alignment for a stack object of a given bit |
| <i>size</i>.</dd> |
| |
| <dt><tt>n<i>size1</i>:<i>size2</i>:<i>size3</i>...</tt></dt> |
| <dd>This specifies a set of native integer widths for the target CPU |
| in bits. For example, it might contain "n32" for 32-bit PowerPC, |
| "n32:64" for PowerPC 64, or "n8:16:32:64" for X86-64. Elements of |
| this set are considered to support most general arithmetic |
| operations efficiently.</dd> |
| </dl> |
| |
| <p>When constructing the data layout for a given target, LLVM starts with a |
| default set of specifications which are then (possibly) overridden by the |
| specifications in the <tt>datalayout</tt> keyword. The default specifications |
| are given in this list:</p> |
| |
| <ul> |
| <li><tt>E</tt> - big endian</li> |
| <li><tt>p:64:64:64</tt> - 64-bit pointers with 64-bit alignment</li> |
| <li><tt>p1:32:32:32</tt> - 32-bit pointers with 32-bit alignment for |
| address space 1</li> |
| <li><tt>p2:16:32:32</tt> - 16-bit pointers with 32-bit alignment for |
| address space 2</li> |
| <li><tt>i1:8:8</tt> - i1 is 8-bit (byte) aligned</li> |
| <li><tt>i8:8:8</tt> - i8 is 8-bit (byte) aligned</li> |
| <li><tt>i16:16:16</tt> - i16 is 16-bit aligned</li> |
| <li><tt>i32:32:32</tt> - i32 is 32-bit aligned</li> |
| <li><tt>i64:32:64</tt> - i64 has ABI alignment of 32-bits but preferred |
| alignment of 64-bits</li> |
| <li><tt>f32:32:32</tt> - float is 32-bit aligned</li> |
| <li><tt>f64:64:64</tt> - double is 64-bit aligned</li> |
| <li><tt>v64:64:64</tt> - 64-bit vector is 64-bit aligned</li> |
| <li><tt>v128:128:128</tt> - 128-bit vector is 128-bit aligned</li> |
| <li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li> |
| <li><tt>s0:64:64</tt> - stack objects are 64-bit aligned</li> |
| </ul> |
| |
| <p>When LLVM is determining the alignment for a given type, it uses the |
| following rules:</p> |
| |
| <ol> |
| <li>If the type sought is an exact match for one of the specifications, that |
| specification is used.</li> |
| |
| <li>If no match is found, and the type sought is an integer type, then the |
| smallest integer type that is larger than the bitwidth of the sought type |
| is used. If none of the specifications are larger than the bitwidth then |
| the largest integer type is used. For example, given the default |
| specifications above, the i7 type will use the alignment of i8 (next |
| largest) while both i65 and i256 will use the alignment of i64 (largest |
| specified).</li> |
| |
| <li>If no match is found, and the type sought is a vector type, then the |
| largest vector type that is smaller than the sought vector type will be |
| used as a fall back. This happens because <128 x double> can be |
| implemented in terms of 64 <2 x double>, for example.</li> |
| </ol> |
| |
| <p>The function of the data layout string may not be what you expect. Notably, |
| this is not a specification from the frontend of what alignment the code |
| generator should use.</p> |
| |
| <p>Instead, if specified, the target data layout is required to match what the |
| ultimate <em>code generator</em> expects. This string is used by the |
| mid-level optimizers to |
| improve code, and this only works if it matches what the ultimate code |
| generator uses. If you would like to generate IR that does not embed this |
| target-specific detail into the IR, then you don't have to specify the |
| string. This will disable some optimizations that require precise layout |
| information, but this also prevents those optimizations from introducing |
| target specificity into the IR.</p> |
| |
| |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="pointeraliasing">Pointer Aliasing Rules</a> |
| </h3> |
| |
| <div> |
| |
| <p>Any memory access must be done through a pointer value associated |
| with an address range of the memory access, otherwise the behavior |
| is undefined. Pointer values are associated with address ranges |
| according to the following rules:</p> |
| |
| <ul> |
| <li>A pointer value is associated with the addresses associated with |
| any value it is <i>based</i> on. |
| <li>An address of a global variable is associated with the address |
| range of the variable's storage.</li> |
| <li>The result value of an allocation instruction is associated with |
| the address range of the allocated storage.</li> |
| <li>A null pointer in the default address-space is associated with |
| no address.</li> |
| <li>An integer constant other than zero or a pointer value returned |
| from a function not defined within LLVM may be associated with address |
| ranges allocated through mechanisms other than those provided by |
| LLVM. Such ranges shall not overlap with any ranges of addresses |
| allocated by mechanisms provided by LLVM.</li> |
| </ul> |
| |
| <p>A pointer value is <i>based</i> on another pointer value according |
| to the following rules:</p> |
| |
| <ul> |
| <li>A pointer value formed from a |
| <tt><a href="#i_getelementptr">getelementptr</a></tt> operation |
| is <i>based</i> on the first operand of the <tt>getelementptr</tt>.</li> |
| <li>The result value of a |
| <tt><a href="#i_bitcast">bitcast</a></tt> is <i>based</i> on the operand |
| of the <tt>bitcast</tt>.</li> |
| <li>A pointer value formed by an |
| <tt><a href="#i_inttoptr">inttoptr</a></tt> is <i>based</i> on all |
| pointer values that contribute (directly or indirectly) to the |
| computation of the pointer's value.</li> |
| <li>The "<i>based</i> on" relationship is transitive.</li> |
| </ul> |
| |
| <p>Note that this definition of <i>"based"</i> is intentionally |
| similar to the definition of <i>"based"</i> in C99, though it is |
| slightly weaker.</p> |
| |
| <p>LLVM IR does not associate types with memory. The result type of a |
| <tt><a href="#i_load">load</a></tt> merely indicates the size and |
| alignment of the memory from which to load, as well as the |
| interpretation of the value. The first operand type of a |
| <tt><a href="#i_store">store</a></tt> similarly only indicates the size |
| and alignment of the store.</p> |
| |
| <p>Consequently, type-based alias analysis, aka TBAA, aka |
| <tt>-fstrict-aliasing</tt>, is not applicable to general unadorned |
| LLVM IR. <a href="#metadata">Metadata</a> may be used to encode |
| additional information which specialized optimization passes may use |
| to implement type-based alias analysis.</p> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="volatile">Volatile Memory Accesses</a> |
| </h3> |
| |
| <div> |
| |
| <p>Certain memory accesses, such as <a href="#i_load"><tt>load</tt></a>s, <a |
| href="#i_store"><tt>store</tt></a>s, and <a |
| href="#int_memcpy"><tt>llvm.memcpy</tt></a>s may be marked <tt>volatile</tt>. |
| The optimizers must not change the number of volatile operations or change their |
| order of execution relative to other volatile operations. The optimizers |
| <i>may</i> change the order of volatile operations relative to non-volatile |
| operations. This is not Java's "volatile" and has no cross-thread |
| synchronization behavior.</p> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="memmodel">Memory Model for Concurrent Operations</a> |
| </h3> |
| |
| <div> |
| |
| <p>The LLVM IR does not define any way to start parallel threads of execution |
| or to register signal handlers. Nonetheless, there are platform-specific |
| ways to create them, and we define LLVM IR's behavior in their presence. This |
| model is inspired by the C++0x memory model.</p> |
| |
| <p>For a more informal introduction to this model, see the |
| <a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>. |
| |
| <p>We define a <i>happens-before</i> partial order as the least partial order |
| that</p> |
| <ul> |
| <li>Is a superset of single-thread program order, and</li> |
| <li>When a <i>synchronizes-with</i> <tt>b</tt>, includes an edge from |
| <tt>a</tt> to <tt>b</tt>. <i>Synchronizes-with</i> pairs are introduced |
| by platform-specific techniques, like pthread locks, thread |
| creation, thread joining, etc., and by atomic instructions. |
| (See also <a href="#ordering">Atomic Memory Ordering Constraints</a>). |
| </li> |
| </ul> |
| |
| <p>Note that program order does not introduce <i>happens-before</i> edges |
| between a thread and signals executing inside that thread.</p> |
| |
| <p>Every (defined) read operation (load instructions, memcpy, atomic |
| loads/read-modify-writes, etc.) <var>R</var> reads a series of bytes written by |
| (defined) write operations (store instructions, atomic |
| stores/read-modify-writes, memcpy, etc.). For the purposes of this section, |
| initialized globals are considered to have a write of the initializer which is |
| atomic and happens before any other read or write of the memory in question. |
| For each byte of a read <var>R</var>, <var>R<sub>byte</sub></var> may see |
| any write to the same byte, except:</p> |
| |
| <ul> |
| <li>If <var>write<sub>1</sub></var> happens before |
| <var>write<sub>2</sub></var>, and <var>write<sub>2</sub></var> happens |
| before <var>R<sub>byte</sub></var>, then <var>R<sub>byte</sub></var> |
| does not see <var>write<sub>1</sub></var>. |
| <li>If <var>R<sub>byte</sub></var> happens before |
| <var>write<sub>3</sub></var>, then <var>R<sub>byte</sub></var> does not |
| see <var>write<sub>3</sub></var>. |
| </ul> |
| |
| <p>Given that definition, <var>R<sub>byte</sub></var> is defined as follows: |
| <ul> |
| <li>If <var>R</var> is volatile, the result is target-dependent. (Volatile |
| is supposed to give guarantees which can support |
| <code>sig_atomic_t</code> in C/C++, and may be used for accesses to |
| addresses which do not behave like normal memory. It does not generally |
| provide cross-thread synchronization.) |
| <li>Otherwise, if there is no write to the same byte that happens before |
| <var>R<sub>byte</sub></var>, <var>R<sub>byte</sub></var> returns |
| <tt>undef</tt> for that byte. |
| <li>Otherwise, if <var>R<sub>byte</sub></var> may see exactly one write, |
| <var>R<sub>byte</sub></var> returns the value written by that |
| write.</li> |
| <li>Otherwise, if <var>R</var> is atomic, and all the writes |
| <var>R<sub>byte</sub></var> may see are atomic, it chooses one of the |
| values written. See the <a href="#ordering">Atomic Memory Ordering |
| Constraints</a> section for additional constraints on how the choice |
| is made. |
| <li>Otherwise <var>R<sub>byte</sub></var> returns <tt>undef</tt>.</li> |
| </ul> |
| |
| <p><var>R</var> returns the value composed of the series of bytes it read. |
| This implies that some bytes within the value may be <tt>undef</tt> |
| <b>without</b> the entire value being <tt>undef</tt>. Note that this only |
| defines the semantics of the operation; it doesn't mean that targets will |
| emit more than one instruction to read the series of bytes.</p> |
| |
| <p>Note that in cases where none of the atomic intrinsics are used, this model |
| places only one restriction on IR transformations on top of what is required |
| for single-threaded execution: introducing a store to a byte which might not |
| otherwise be stored is not allowed in general. (Specifically, in the case |
| where another thread might write to and read from an address, introducing a |
| store can change a load that may see exactly one write into a load that may |
| see multiple writes.)</p> |
| |
| <!-- FIXME: This model assumes all targets where concurrency is relevant have |
| a byte-size store which doesn't affect adjacent bytes. As far as I can tell, |
| none of the backends currently in the tree fall into this category; however, |
| there might be targets which care. If there are, we want a paragraph |
| like the following: |
| |
| Targets may specify that stores narrower than a certain width are not |
| available; on such a target, for the purposes of this model, treat any |
| non-atomic write with an alignment or width less than the minimum width |
| as if it writes to the relevant surrounding bytes. |
| --> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="ordering">Atomic Memory Ordering Constraints</a> |
| </h3> |
| |
| <div> |
| |
| <p>Atomic instructions (<a href="#i_cmpxchg"><code>cmpxchg</code></a>, |
| <a href="#i_atomicrmw"><code>atomicrmw</code></a>, |
| <a href="#i_fence"><code>fence</code></a>, |
| <a href="#i_load"><code>atomic load</code></a>, and |
| <a href="#i_store"><code>atomic store</code></a>) take an ordering parameter |
| that determines which other atomic instructions on the same address they |
| <i>synchronize with</i>. These semantics are borrowed from Java and C++0x, |
| but are somewhat more colloquial. If these descriptions aren't precise enough, |
| check those specs (see spec references in the |
| <a href="Atomics.html#introduction">atomics guide</a>). |
| <a href="#i_fence"><code>fence</code></a> instructions |
| treat these orderings somewhat differently since they don't take an address. |
| See that instruction's documentation for details.</p> |
| |
| <p>For a simpler introduction to the ordering constraints, see the |
| <a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.</p> |
| |
| <dl> |
| <dt><code>unordered</code></dt> |
| <dd>The set of values that can be read is governed by the happens-before |
| partial order. A value cannot be read unless some operation wrote it. |
| This is intended to provide a guarantee strong enough to model Java's |
| non-volatile shared variables. This ordering cannot be specified for |
| read-modify-write operations; it is not strong enough to make them atomic |
| in any interesting way.</dd> |
| <dt><code>monotonic</code></dt> |
| <dd>In addition to the guarantees of <code>unordered</code>, there is a single |
| total order for modifications by <code>monotonic</code> operations on each |
| address. All modification orders must be compatible with the happens-before |
| order. There is no guarantee that the modification orders can be combined to |
| a global total order for the whole program (and this often will not be |
| possible). The read in an atomic read-modify-write operation |
| (<a href="#i_cmpxchg"><code>cmpxchg</code></a> and |
| <a href="#i_atomicrmw"><code>atomicrmw</code></a>) |
| reads the value in the modification order immediately before the value it |
| writes. If one atomic read happens before another atomic read of the same |
| address, the later read must see the same value or a later value in the |
| address's modification order. This disallows reordering of |
| <code>monotonic</code> (or stronger) operations on the same address. If an |
| address is written <code>monotonic</code>ally by one thread, and other threads |
| <code>monotonic</code>ally read that address repeatedly, the other threads must |
| eventually see the write. This corresponds to the C++0x/C1x |
| <code>memory_order_relaxed</code>.</dd> |
| <dt><code>acquire</code></dt> |
| <dd>In addition to the guarantees of <code>monotonic</code>, |
| a <i>synchronizes-with</i> edge may be formed with a <code>release</code> |
| operation. This is intended to model C++'s <code>memory_order_acquire</code>.</dd> |
| <dt><code>release</code></dt> |
| <dd>In addition to the guarantees of <code>monotonic</code>, if this operation |
| writes a value which is subsequently read by an <code>acquire</code> operation, |
| it <i>synchronizes-with</i> that operation. (This isn't a complete |
| description; see the C++0x definition of a release sequence.) This corresponds |
| to the C++0x/C1x <code>memory_order_release</code>.</dd> |
| <dt><code>acq_rel</code> (acquire+release)</dt><dd>Acts as both an |
| <code>acquire</code> and <code>release</code> operation on its address. |
| This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>.</dd> |
| <dt><code>seq_cst</code> (sequentially consistent)</dt><dd> |
| <dd>In addition to the guarantees of <code>acq_rel</code> |
| (<code>acquire</code> for an operation which only reads, <code>release</code> |
| for an operation which only writes), there is a global total order on all |
| sequentially-consistent operations on all addresses, which is consistent with |
| the <i>happens-before</i> partial order and with the modification orders of |
| all the affected addresses. Each sequentially-consistent read sees the last |
| preceding write to the same address in this global order. This corresponds |
| to the C++0x/C1x <code>memory_order_seq_cst</code> and Java volatile.</dd> |
| </dl> |
| |
| <p id="singlethread">If an atomic operation is marked <code>singlethread</code>, |
| it only <i>synchronizes with</i> or participates in modification and seq_cst |
| total orderings with other operations running in the same thread (for example, |
| in signal handlers).</p> |
| |
| </div> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <h2><a name="typesystem">Type System</a></h2> |
| <!-- *********************************************************************** --> |
| |
| <div> |
| |
| <p>The LLVM type system is one of the most important features of the |
| intermediate representation. Being typed enables a number of optimizations |
| to be performed on the intermediate representation directly, without having |
| to do extra analyses on the side before the transformation. A strong type |
| system makes it easier to read the generated code and enables novel analyses |
| and transformations that are not feasible to perform on normal three address |
| code representations.</p> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="t_classifications">Type Classifications</a> |
| </h3> |
| |
| <div> |
| |
| <p>The types fall into a few useful classifications:</p> |
| |
| <table border="1" cellspacing="0" cellpadding="4"> |
| <tbody> |
| <tr><th>Classification</th><th>Types</th></tr> |
| <tr> |
| <td><a href="#t_integer">integer</a></td> |
| <td><tt>i1, i2, i3, ... i8, ... i16, ... i32, ... i64, ... </tt></td> |
| </tr> |
| <tr> |
| <td><a href="#t_floating">floating point</a></td> |
| <td><tt>half, float, double, x86_fp80, fp128, ppc_fp128</tt></td> |
| </tr> |
| <tr> |
| <td><a name="t_firstclass">first class</a></td> |
| <td><a href="#t_integer">integer</a>, |
| <a href="#t_floating">floating point</a>, |
| <a href="#t_pointer">pointer</a>, |
| <a href="#t_vector">vector</a>, |
| <a href="#t_struct">structure</a>, |
| <a href="#t_array">array</a>, |
| <a href="#t_label">label</a>, |
| <a href="#t_metadata">metadata</a>. |
| </td> |
| </tr> |
| <tr> |
| <td><a href="#t_primitive">primitive</a></td> |
| <td><a href="#t_label">label</a>, |
| <a href="#t_void">void</a>, |
| <a href="#t_integer">integer</a>, |
| <a href="#t_floating">floating point</a>, |
| <a href="#t_x86mmx">x86mmx</a>, |
| <a href="#t_metadata">metadata</a>.</td> |
| </tr> |
| <tr> |
| <td><a href="#t_derived">derived</a></td> |
| <td><a href="#t_array">array</a>, |
| <a href="#t_function">function</a>, |
| <a href="#t_pointer">pointer</a>, |
| <a href="#t_struct">structure</a>, |
| <a href="#t_vector">vector</a>, |
| <a href="#t_opaque">opaque</a>. |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p>The <a href="#t_firstclass">first class</a> types are perhaps the most |
| important. Values of these types are the only ones which can be produced by |
| instructions.</p> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="t_primitive">Primitive Types</a> |
| </h3> |
| |
| <div> |
| |
| <p>The primitive types are the fundamental building blocks of the LLVM |
| system.</p> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_integer">Integer Type</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>The integer type is a very simple type that simply specifies an arbitrary |
| bit width for the integer type desired. Any bit width from 1 bit to |
| 2<sup>23</sup>-1 (about 8 million) can be specified.</p> |
| |
| <h5>Syntax:</h5> |
| <pre> |
| iN |
| </pre> |
| |
| <p>The number of bits the integer will occupy is specified by the <tt>N</tt> |
| value.</p> |
| |
| <h5>Examples:</h5> |
| <table class="layout"> |
| <tr class="layout"> |
| <td class="left"><tt>i1</tt></td> |
| <td class="left">a single-bit integer.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt>i32</tt></td> |
| <td class="left">a 32-bit integer.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt>i1942652</tt></td> |
| <td class="left">a really big integer of over 1 million bits.</td> |
| </tr> |
| </table> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_floating">Floating Point Types</a> |
| </h4> |
| |
| <div> |
| |
| <table> |
| <tbody> |
| <tr><th>Type</th><th>Description</th></tr> |
| <tr><td><tt>half</tt></td><td>16-bit floating point value</td></tr> |
| <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr> |
| <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr> |
| <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr> |
| <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr> |
| <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr> |
| </tbody> |
| </table> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_x86mmx">X86mmx Type</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>The x86mmx type represents a value held in an MMX register on an x86 machine. The operations allowed on it are quite limited: parameters and return values, load and store, and bitcast. User-specified MMX instructions are represented as intrinsic or asm calls with arguments and/or results of this type. There are no arrays, vectors or constants of this type.</p> |
| |
| <h5>Syntax:</h5> |
| <pre> |
| x86mmx |
| </pre> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_void">Void Type</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>The void type does not represent any value and has no size.</p> |
| |
| <h5>Syntax:</h5> |
| <pre> |
| void |
| </pre> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_label">Label Type</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>The label type represents code labels.</p> |
| |
| <h5>Syntax:</h5> |
| <pre> |
| label |
| </pre> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_metadata">Metadata Type</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>The metadata type represents embedded metadata. No derived types may be |
| created from metadata except for <a href="#t_function">function</a> |
| arguments. |
| |
| <h5>Syntax:</h5> |
| <pre> |
| metadata |
| </pre> |
| |
| </div> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="t_derived">Derived Types</a> |
| </h3> |
| |
| <div> |
| |
| <p>The real power in LLVM comes from the derived types in the system. This is |
| what allows a programmer to represent arrays, functions, pointers, and other |
| useful types. Each of these types contain one or more element types which |
| may be a primitive type, or another derived type. For example, it is |
| possible to have a two dimensional array, using an array as the element type |
| of another array.</p> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_aggregate">Aggregate Types</a> |
| </h4> |
| |
| <div> |
| |
| <p>Aggregate Types are a subset of derived types that can contain multiple |
| member types. <a href="#t_array">Arrays</a> and |
| <a href="#t_struct">structs</a> are aggregate types. |
| <a href="#t_vector">Vectors</a> are not considered to be aggregate types.</p> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_array">Array Type</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>The array type is a very simple derived type that arranges elements |
| sequentially in memory. The array type requires a size (number of elements) |
| and an underlying data type.</p> |
| |
| <h5>Syntax:</h5> |
| <pre> |
| [<# elements> x <elementtype>] |
| </pre> |
| |
| <p>The number of elements is a constant integer value; <tt>elementtype</tt> may |
| be any type with a size.</p> |
| |
| <h5>Examples:</h5> |
| <table class="layout"> |
| <tr class="layout"> |
| <td class="left"><tt>[40 x i32]</tt></td> |
| <td class="left">Array of 40 32-bit integer values.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt>[41 x i32]</tt></td> |
| <td class="left">Array of 41 32-bit integer values.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt>[4 x i8]</tt></td> |
| <td class="left">Array of 4 8-bit integer values.</td> |
| </tr> |
| </table> |
| <p>Here are some examples of multidimensional arrays:</p> |
| <table class="layout"> |
| <tr class="layout"> |
| <td class="left"><tt>[3 x [4 x i32]]</tt></td> |
| <td class="left">3x4 array of 32-bit integer values.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt>[12 x [10 x float]]</tt></td> |
| <td class="left">12x10 array of single precision floating point values.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt>[2 x [3 x [4 x i16]]]</tt></td> |
| <td class="left">2x3x4 array of 16-bit integer values.</td> |
| </tr> |
| </table> |
| |
| <p>There is no restriction on indexing beyond the end of the array implied by |
| a static type (though there are restrictions on indexing beyond the bounds |
| of an allocated object in some cases). This means that single-dimension |
| 'variable sized array' addressing can be implemented in LLVM with a zero |
| length array type. An implementation of 'pascal style arrays' in LLVM could |
| use the type "<tt>{ i32, [0 x float]}</tt>", for example.</p> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_function">Function Type</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>The function type can be thought of as a function signature. It consists of |
| a return type and a list of formal parameter types. The return type of a |
| function type is a first class type or a void type.</p> |
| |
| <h5>Syntax:</h5> |
| <pre> |
| <returntype> (<parameter list>) |
| </pre> |
| |
| <p>...where '<tt><parameter list></tt>' is a comma-separated list of type |
| specifiers. Optionally, the parameter list may include a type <tt>...</tt>, |
| which indicates that the function takes a variable number of arguments. |
| Variable argument functions can access their arguments with |
| the <a href="#int_varargs">variable argument handling intrinsic</a> |
| functions. '<tt><returntype></tt>' is any type except |
| <a href="#t_label">label</a>.</p> |
| |
| <h5>Examples:</h5> |
| <table class="layout"> |
| <tr class="layout"> |
| <td class="left"><tt>i32 (i32)</tt></td> |
| <td class="left">function taking an <tt>i32</tt>, returning an <tt>i32</tt> |
| </td> |
| </tr><tr class="layout"> |
| <td class="left"><tt>float (i16, i32 *) * |
| </tt></td> |
| <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes |
| an <tt>i16</tt> and a <a href="#t_pointer">pointer</a> to <tt>i32</tt>, |
| returning <tt>float</tt>. |
| </td> |
| </tr><tr class="layout"> |
| <td class="left"><tt>i32 (i8*, ...)</tt></td> |
| <td class="left">A vararg function that takes at least one |
| <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C), |
| which returns an integer. This is the signature for <tt>printf</tt> in |
| LLVM. |
| </td> |
| </tr><tr class="layout"> |
| <td class="left"><tt>{i32, i32} (i32)</tt></td> |
| <td class="left">A function taking an <tt>i32</tt>, returning a |
| <a href="#t_struct">structure</a> containing two <tt>i32</tt> values |
| </td> |
| </tr> |
| </table> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_struct">Structure Type</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>The structure type is used to represent a collection of data members together |
| in memory. The elements of a structure may be any type that has a size.</p> |
| |
| <p>Structures in memory are accessed using '<tt><a href="#i_load">load</a></tt>' |
| and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field |
| with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. |
| Structures in registers are accessed using the |
| '<tt><a href="#i_extractvalue">extractvalue</a></tt>' and |
| '<tt><a href="#i_insertvalue">insertvalue</a></tt>' instructions.</p> |
| |
| <p>Structures may optionally be "packed" structures, which indicate that the |
| alignment of the struct is one byte, and that there is no padding between |
| the elements. In non-packed structs, padding between field types is inserted |
| as defined by the DataLayout string in the module, which is required to match |
| what the underlying code generator expects.</p> |
| |
| <p>Structures can either be "literal" or "identified". A literal structure is |
| defined inline with other types (e.g. <tt>{i32, i32}*</tt>) whereas identified |
| types are always defined at the top level with a name. Literal types are |
| uniqued by their contents and can never be recursive or opaque since there is |
| no way to write one. Identified types can be recursive, can be opaqued, and are |
| never uniqued. |
| </p> |
| |
| <h5>Syntax:</h5> |
| <pre> |
| %T1 = type { <type list> } <i>; Identified normal struct type</i> |
| %T2 = type <{ <type list> }> <i>; Identified packed struct type</i> |
| </pre> |
| |
| <h5>Examples:</h5> |
| <table class="layout"> |
| <tr class="layout"> |
| <td class="left"><tt>{ i32, i32, i32 }</tt></td> |
| <td class="left">A triple of three <tt>i32</tt> values</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt>{ float, i32 (i32) * }</tt></td> |
| <td class="left">A pair, where the first element is a <tt>float</tt> and the |
| second element is a <a href="#t_pointer">pointer</a> to a |
| <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning |
| an <tt>i32</tt>.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt><{ i8, i32 }></tt></td> |
| <td class="left">A packed struct known to be 5 bytes in size.</td> |
| </tr> |
| </table> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_opaque">Opaque Structure Types</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>Opaque structure types are used to represent named structure types that do |
| not have a body specified. This corresponds (for example) to the C notion of |
| a forward declared structure.</p> |
| |
| <h5>Syntax:</h5> |
| <pre> |
| %X = type opaque |
| %52 = type opaque |
| </pre> |
| |
| <h5>Examples:</h5> |
| <table class="layout"> |
| <tr class="layout"> |
| <td class="left"><tt>opaque</tt></td> |
| <td class="left">An opaque type.</td> |
| </tr> |
| </table> |
| |
| </div> |
| |
| |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_pointer">Pointer Type</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>The pointer type is used to specify memory locations. |
| Pointers are commonly used to reference objects in memory.</p> |
| |
| <p>Pointer types may have an optional address space attribute defining the |
| numbered address space where the pointed-to object resides. The default |
| address space is number zero. The semantics of non-zero address |
| spaces are target-specific.</p> |
| |
| <p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does it |
| permit pointers to labels (<tt>label*</tt>). Use <tt>i8*</tt> instead.</p> |
| |
| <h5>Syntax:</h5> |
| <pre> |
| <type> * |
| </pre> |
| |
| <h5>Examples:</h5> |
| <table class="layout"> |
| <tr class="layout"> |
| <td class="left"><tt>[4 x i32]*</tt></td> |
| <td class="left">A <a href="#t_pointer">pointer</a> to <a |
| href="#t_array">array</a> of four <tt>i32</tt> values.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt>i32 (i32*) *</tt></td> |
| <td class="left"> A <a href="#t_pointer">pointer</a> to a <a |
| href="#t_function">function</a> that takes an <tt>i32*</tt>, returning an |
| <tt>i32</tt>.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt>i32 addrspace(5)*</tt></td> |
| <td class="left">A <a href="#t_pointer">pointer</a> to an <tt>i32</tt> value |
| that resides in address space #5.</td> |
| </tr> |
| </table> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="t_vector">Vector Type</a> |
| </h4> |
| |
| <div> |
| |
| <h5>Overview:</h5> |
| <p>A vector type is a simple derived type that represents a vector of elements. |
| Vector types are used when multiple primitive data are operated in parallel |
| using a single instruction (SIMD). A vector type requires a size (number of |
| elements) and an underlying primitive data type. Vector types are considered |
| <a href="#t_firstclass">first class</a>.</p> |
| |
| <h5>Syntax:</h5> |
| <pre> |
| < <# elements> x <elementtype> > |
| </pre> |
| |
| <p>The number of elements is a constant integer value larger than 0; elementtype |
| may be any integer or floating point type, or a pointer to these types. |
| Vectors of size zero are not allowed. </p> |
| |
| <h5>Examples:</h5> |
| <table class="layout"> |
| <tr class="layout"> |
| <td class="left"><tt><4 x i32></tt></td> |
| <td class="left">Vector of 4 32-bit integer values.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt><8 x float></tt></td> |
| <td class="left">Vector of 8 32-bit floating-point values.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt><2 x i64></tt></td> |
| <td class="left">Vector of 2 64-bit integer values.</td> |
| </tr> |
| <tr class="layout"> |
| <td class="left"><tt><4 x i64*></tt></td> |
| <td class="left">Vector of 4 pointers to 64-bit integer values.</td> |
| </tr> |
| </table> |
| |
| </div> |
| |
| </div> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <h2><a name="constants">Constants</a></h2> |
| <!-- *********************************************************************** --> |
| |
| <div> |
| |
| <p>LLVM has several different basic types of constants. This section describes |
| them all and their syntax.</p> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="simpleconstants">Simple Constants</a> |
| </h3> |
| |
| <div> |
| |
| <dl> |
| <dt><b>Boolean constants</b></dt> |
| <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid |
| constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd> |
| |
| <dt><b>Integer constants</b></dt> |
| <dd>Standard integers (such as '4') are constants of |
| the <a href="#t_integer">integer</a> type. Negative numbers may be used |
| with integer types.</dd> |
| |
| <dt><b>Floating point constants</b></dt> |
| <dd>Floating point constants use standard decimal notation (e.g. 123.421), |
| exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal |
| notation (see below). The assembler requires the exact decimal value of a |
| floating-point constant. For example, the assembler accepts 1.25 but |
| rejects 1.3 because 1.3 is a repeating decimal in binary. Floating point |
| constants must have a <a href="#t_floating">floating point</a> type. </dd> |
| |
| <dt><b>Null pointer constants</b></dt> |
| <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant |
| and must be of <a href="#t_pointer">pointer type</a>.</dd> |
| </dl> |
| |
| <p>The one non-intuitive notation for constants is the hexadecimal form of |
| floating point constants. For example, the form '<tt>double |
| 0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) |
| '<tt>double 4.5e+15</tt>'. The only time hexadecimal floating point |
| constants are required (and the only time that they are generated by the |
| disassembler) is when a floating point constant must be emitted but it cannot |
| be represented as a decimal floating point number in a reasonable number of |
| digits. For example, NaN's, infinities, and other special values are |
| represented in their IEEE hexadecimal format so that assembly and disassembly |
| do not cause any bits to change in the constants.</p> |
| |
| <p>When using the hexadecimal form, constants of types half, float, and double are |
| represented using the 16-digit form shown above (which matches the IEEE754 |
| representation for double); half and float values must, however, be exactly |
| representable as IEE754 half and single precision, respectively. |
| Hexadecimal format is always used |
| for long double, and there are three forms of long double. The 80-bit format |
| used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits. |
| The 128-bit format used by PowerPC (two adjacent doubles) is represented |
| by <tt>0xM</tt> followed by 32 hexadecimal digits. The IEEE 128-bit format |
| is represented by <tt>0xL</tt> followed by 32 hexadecimal digits; no |
| currently supported target uses this format. Long doubles will only work if |
| they match the long double format on your target. The IEEE 16-bit format |
| (half precision) is represented by <tt>0xH</tt> followed by 4 hexadecimal |
| digits. All hexadecimal formats are big-endian (sign bit at the left).</p> |
| |
| <p>There are no constants of type x86mmx.</p> |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="aggregateconstants"></a> <!-- old anchor --> |
| <a name="complexconstants">Complex Constants</a> |
| </h3> |
| |
| <div> |
| |
| <p>Complex constants are a (potentially recursive) combination of simple |
| constants and smaller complex constants.</p> |
| |
| <dl> |
| <dt><b>Structure constants</b></dt> |
| <dd>Structure constants are represented with notation similar to structure |
| type definitions (a comma separated list of elements, surrounded by braces |
| (<tt>{}</tt>)). For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>", |
| where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>". |
| Structure constants must have <a href="#t_struct">structure type</a>, and |
| the number and types of elements must match those specified by the |
| type.</dd> |
| |
| <dt><b>Array constants</b></dt> |
| <dd>Array constants are represented with notation similar to array type |
| definitions (a comma separated list of elements, surrounded by square |
| brackets (<tt>[]</tt>)). For example: "<tt>[ i32 42, i32 11, i32 74 |
| ]</tt>". Array constants must have <a href="#t_array">array type</a>, and |
| the number and types of elements must match those specified by the |
| type.</dd> |
| |
| <dt><b>Vector constants</b></dt> |
| <dd>Vector constants are represented with notation similar to vector type |
| definitions (a comma separated list of elements, surrounded by |
| less-than/greater-than's (<tt><></tt>)). For example: "<tt>< i32 |
| 42, i32 11, i32 74, i32 100 ></tt>". Vector constants must |
| have <a href="#t_vector">vector type</a>, and the number and types of |
| elements must match those specified by the type.</dd> |
| |
| <dt><b>Zero initialization</b></dt> |
| <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a |
| value to zero of <em>any</em> type, including scalar and |
| <a href="#t_aggregate">aggregate</a> types. |
| This is often used to avoid having to print large zero initializers |
| (e.g. for large arrays) and is always exactly equivalent to using explicit |
| zero initializers.</dd> |
| |
| <dt><b>Metadata node</b></dt> |
| <dd>A metadata node is a structure-like constant with |
| <a href="#t_metadata">metadata type</a>. For example: "<tt>metadata !{ |
| i32 0, metadata !"test" }</tt>". Unlike other constants that are meant to |
| be interpreted as part of the instruction stream, metadata is a place to |
| attach additional information such as debug info.</dd> |
| </dl> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="globalconstants">Global Variable and Function Addresses</a> |
| </h3> |
| |
| <div> |
| |
| <p>The addresses of <a href="#globalvars">global variables</a> |
| and <a href="#functionstructure">functions</a> are always implicitly valid |
| (link-time) constants. These constants are explicitly referenced when |
| the <a href="#identifiers">identifier for the global</a> is used and always |
| have <a href="#t_pointer">pointer</a> type. For example, the following is a |
| legal LLVM file:</p> |
| |
| <pre class="doc_code"> |
| @X = global i32 17 |
| @Y = global i32 42 |
| @Z = global [2 x i32*] [ i32* @X, i32* @Y ] |
| </pre> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="undefvalues">Undefined Values</a> |
| </h3> |
| |
| <div> |
| |
| <p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and |
| indicates that the user of the value may receive an unspecified bit-pattern. |
| Undefined values may be of any type (other than '<tt>label</tt>' |
| or '<tt>void</tt>') and be used anywhere a constant is permitted.</p> |
| |
| <p>Undefined values are useful because they indicate to the compiler that the |
| program is well defined no matter what value is used. This gives the |
| compiler more freedom to optimize. Here are some examples of (potentially |
| surprising) transformations that are valid (in pseudo IR):</p> |
| |
| |
| <pre class="doc_code"> |
| %A = add %X, undef |
| %B = sub %X, undef |
| %C = xor %X, undef |
| Safe: |
| %A = undef |
| %B = undef |
| %C = undef |
| </pre> |
| |
| <p>This is safe because all of the output bits are affected by the undef bits. |
| Any output bit can have a zero or one depending on the input bits.</p> |
| |
| <pre class="doc_code"> |
| %A = or %X, undef |
| %B = and %X, undef |
| Safe: |
| %A = -1 |
| %B = 0 |
| Unsafe: |
| %A = undef |
| %B = undef |
| </pre> |
| |
| <p>These logical operations have bits that are not always affected by the input. |
| For example, if <tt>%X</tt> has a zero bit, then the output of the |
| '<tt>and</tt>' operation will always be a zero for that bit, no matter what |
| the corresponding bit from the '<tt>undef</tt>' is. As such, it is unsafe to |
| optimize or assume that the result of the '<tt>and</tt>' is '<tt>undef</tt>'. |
| However, it is safe to assume that all bits of the '<tt>undef</tt>' could be |
| 0, and optimize the '<tt>and</tt>' to 0. Likewise, it is safe to assume that |
| all the bits of the '<tt>undef</tt>' operand to the '<tt>or</tt>' could be |
| set, allowing the '<tt>or</tt>' to be folded to -1.</p> |
| |
| <pre class="doc_code"> |
| %A = select undef, %X, %Y |
| %B = select undef, 42, %Y |
| %C = select %X, %Y, undef |
| Safe: |
| %A = %X (or %Y) |
| %B = 42 (or %Y) |
| %C = %Y |
| Unsafe: |
| %A = undef |
| %B = undef |
| %C = undef |
| </pre> |
| |
| <p>This set of examples shows that undefined '<tt>select</tt>' (and conditional |
| branch) conditions can go <em>either way</em>, but they have to come from one |
| of the two operands. In the <tt>%A</tt> example, if <tt>%X</tt> and |
| <tt>%Y</tt> were both known to have a clear low bit, then <tt>%A</tt> would |
| have to have a cleared low bit. However, in the <tt>%C</tt> example, the |
| optimizer is allowed to assume that the '<tt>undef</tt>' operand could be the |
| same as <tt>%Y</tt>, allowing the whole '<tt>select</tt>' to be |
| eliminated.</p> |
| |
| <pre class="doc_code"> |
| %A = xor undef, undef |
| |
| %B = undef |
| %C = xor %B, %B |
| |
| %D = undef |
| %E = icmp lt %D, 4 |
| %F = icmp gte %D, 4 |
| |
| Safe: |
| %A = undef |
| %B = undef |
| %C = undef |
| %D = undef |
| %E = undef |
| %F = undef |
| </pre> |
| |
| <p>This example points out that two '<tt>undef</tt>' operands are not |
| necessarily the same. This can be surprising to people (and also matches C |
| semantics) where they assume that "<tt>X^X</tt>" is always zero, even |
| if <tt>X</tt> is undefined. This isn't true for a number of reasons, but the |
| short answer is that an '<tt>undef</tt>' "variable" can arbitrarily change |
| its value over its "live range". This is true because the variable doesn't |
| actually <em>have a live range</em>. Instead, the value is logically read |
| from arbitrary registers that happen to be around when needed, so the value |
| is not necessarily consistent over time. In fact, <tt>%A</tt> and <tt>%C</tt> |
| need to have the same semantics or the core LLVM "replace all uses with" |
| concept would not hold.</p> |
| |
| <pre class="doc_code"> |
| %A = fdiv undef, %X |
| %B = fdiv %X, undef |
| Safe: |
| %A = undef |
| b: unreachable |
| </pre> |
| |
| <p>These examples show the crucial difference between an <em>undefined |
| value</em> and <em>undefined behavior</em>. An undefined value (like |
| '<tt>undef</tt>') is allowed to have an arbitrary bit-pattern. This means that |
| the <tt>%A</tt> operation can be constant folded to '<tt>undef</tt>', because |
| the '<tt>undef</tt>' could be an SNaN, and <tt>fdiv</tt> is not (currently) |
| defined on SNaN's. However, in the second example, we can make a more |
| aggressive assumption: because the <tt>undef</tt> is allowed to be an |
| arbitrary value, we are allowed to assume that it could be zero. Since a |
| divide by zero has <em>undefined behavior</em>, we are allowed to assume that |
| the operation does not execute at all. This allows us to delete the divide and |
| all code after it. Because the undefined operation "can't happen", the |
| optimizer can assume that it occurs in dead code.</p> |
| |
| <pre class="doc_code"> |
| a: store undef -> %X |
| b: store %X -> undef |
| Safe: |
| a: <deleted> |
| b: unreachable |
| </pre> |
| |
| <p>These examples reiterate the <tt>fdiv</tt> example: a store <em>of</em> an |
| undefined value can be assumed to not have any effect; we can assume that the |
| value is overwritten with bits that happen to match what was already there. |
| However, a store <em>to</em> an undefined location could clobber arbitrary |
| memory, therefore, it has undefined behavior.</p> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="poisonvalues">Poison Values</a> |
| </h3> |
| |
| <div> |
| |
| <p>Poison values are similar to <a href="#undefvalues">undef values</a>, however |
| they also represent the fact that an instruction or constant expression which |
| cannot evoke side effects has nevertheless detected a condition which results |
| in undefined behavior.</p> |
| |
| <p>There is currently no way of representing a poison value in the IR; they |
| only exist when produced by operations such as |
| <a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag.</p> |
| |
| <p>Poison value behavior is defined in terms of value <i>dependence</i>:</p> |
| |
| <ul> |
| <li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on |
| their operands.</li> |
| |
| <li><a href="#i_phi"><tt>Phi</tt></a> nodes depend on the operand corresponding |
| to their dynamic predecessor basic block.</li> |
| |
| <li>Function arguments depend on the corresponding actual argument values in |
| the dynamic callers of their functions.</li> |
| |
| <li><a href="#i_call"><tt>Call</tt></a> instructions depend on the |
| <a href="#i_ret"><tt>ret</tt></a> instructions that dynamically transfer |
| control back to them.</li> |
| |
| <li><a href="#i_invoke"><tt>Invoke</tt></a> instructions depend on the |
| <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_resume"><tt>resume</tt></a>, |
| or exception-throwing call instructions that dynamically transfer control |
| back to them.</li> |
| |
| <li>Non-volatile loads and stores depend on the most recent stores to all of the |
| referenced memory addresses, following the order in the IR |
| (including loads and stores implied by intrinsics such as |
| <a href="#int_memcpy"><tt>@llvm.memcpy</tt></a>.)</li> |
| |
| <!-- TODO: In the case of multiple threads, this only applies if the store |
| "happens-before" the load or store. --> |
| |
| <!-- TODO: floating-point exception state --> |
| |
| <li>An instruction with externally visible side effects depends on the most |
| recent preceding instruction with externally visible side effects, following |
| the order in the IR. (This includes |
| <a href="#volatile">volatile operations</a>.)</li> |
| |
| <li>An instruction <i>control-depends</i> on a |
| <a href="#terminators">terminator instruction</a> |
| if the terminator instruction has multiple successors and the instruction |
| is always executed when control transfers to one of the successors, and |
| may not be executed when control is transferred to another.</li> |
| |
| <li>Additionally, an instruction also <i>control-depends</i> on a terminator |
| instruction if the set of instructions it otherwise depends on would be |
| different if the terminator had transferred control to a different |
| successor.</li> |
| |
| <li>Dependence is transitive.</li> |
| |
| </ul> |
| |
| <p>Poison Values have the same behavior as <a href="#undefvalues">undef values</a>, |
| with the additional affect that any instruction which has a <i>dependence</i> |
| on a poison value has undefined behavior.</p> |
| |
| <p>Here are some examples:</p> |
| |
| <pre class="doc_code"> |
| entry: |
| %poison = sub nuw i32 0, 1 ; Results in a poison value. |
| %still_poison = and i32 %poison, 0 ; 0, but also poison. |
| %poison_yet_again = getelementptr i32* @h, i32 %still_poison |
| store i32 0, i32* %poison_yet_again ; memory at @h[0] is poisoned |
| |
| store i32 %poison, i32* @g ; Poison value stored to memory. |
| %poison2 = load i32* @g ; Poison value loaded back from memory. |
| |
| store volatile i32 %poison, i32* @g ; External observation; undefined behavior. |
| |
| %narrowaddr = bitcast i32* @g to i16* |
| %wideaddr = bitcast i32* @g to i64* |
| %poison3 = load i16* %narrowaddr ; Returns a poison value. |
| %poison4 = load i64* %wideaddr ; Returns a poison value. |
| |
| %cmp = icmp slt i32 %poison, 0 ; Returns a poison value. |
| br i1 %cmp, label %true, label %end ; Branch to either destination. |
| |
| true: |
| store volatile i32 0, i32* @g ; This is control-dependent on %cmp, so |
| ; it has undefined behavior. |
| br label %end |
| |
| end: |
| %p = phi i32 [ 0, %entry ], [ 1, %true ] |
| ; Both edges into this PHI are |
| ; control-dependent on %cmp, so this |
| ; always results in a poison value. |
| |
| store volatile i32 0, i32* @g ; This would depend on the store in %true |
| ; if %cmp is true, or the store in %entry |
| ; otherwise, so this is undefined behavior. |
| |
| br i1 %cmp, label %second_true, label %second_end |
| ; The same branch again, but this time the |
| ; true block doesn't have side effects. |
| |
| second_true: |
| ; No side effects! |
| ret void |
| |
| second_end: |
| store volatile i32 0, i32* @g ; This time, the instruction always depends |
| ; on the store in %end. Also, it is |
| ; control-equivalent to %end, so this is |
| ; well-defined (ignoring earlier undefined |
| ; behavior in this example). |
| </pre> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="blockaddress">Addresses of Basic Blocks</a> |
| </h3> |
| |
| <div> |
| |
| <p><b><tt>blockaddress(@function, %block)</tt></b></p> |
| |
| <p>The '<tt>blockaddress</tt>' constant computes the address of the specified |
| basic block in the specified function, and always has an i8* type. Taking |
| the address of the entry block is illegal.</p> |
| |
| <p>This value only has defined behavior when used as an operand to the |
| '<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction, or for |
| comparisons against null. Pointer equality tests between labels addresses |
| results in undefined behavior — though, again, comparison against null |
| is ok, and no label is equal to the null pointer. This may be passed around |
| as an opaque pointer sized value as long as the bits are not inspected. This |
| allows <tt>ptrtoint</tt> and arithmetic to be performed on these values so |
| long as the original value is reconstituted before the <tt>indirectbr</tt> |
| instruction.</p> |
| |
| <p>Finally, some targets may provide defined semantics when using the value as |
| the operand to an inline assembly, but that is target specific.</p> |
| |
| </div> |
| |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="constantexprs">Constant Expressions</a> |
| </h3> |
| |
| <div> |
| |
| <p>Constant expressions are used to allow expressions involving other constants |
| to be used as constants. Constant expressions may be of |
| any <a href="#t_firstclass">first class</a> type and may involve any LLVM |
| operation that does not have side effects (e.g. load and call are not |
| supported). The following is the syntax for constant expressions:</p> |
| |
| <dl> |
| <dt><b><tt>trunc (CST to TYPE)</tt></b></dt> |
| <dd>Truncate a constant to another type. The bit size of CST must be larger |
| than the bit size of TYPE. Both types must be integers.</dd> |
| |
| <dt><b><tt>zext (CST to TYPE)</tt></b></dt> |
| <dd>Zero extend a constant to another type. The bit size of CST must be |
| smaller than the bit size of TYPE. Both types must be integers.</dd> |
| |
| <dt><b><tt>sext (CST to TYPE)</tt></b></dt> |
| <dd>Sign extend a constant to another type. The bit size of CST must be |
| smaller than the bit size of TYPE. Both types must be integers.</dd> |
| |
| <dt><b><tt>fptrunc (CST to TYPE)</tt></b></dt> |
| <dd>Truncate a floating point constant to another floating point type. The |
| size of CST must be larger than the size of TYPE. Both types must be |
| floating point.</dd> |
| |
| <dt><b><tt>fpext (CST to TYPE)</tt></b></dt> |
| <dd>Floating point extend a constant to another type. The size of CST must be |
| smaller or equal to the size of TYPE. Both types must be floating |
| point.</dd> |
| |
| <dt><b><tt>fptoui (CST to TYPE)</tt></b></dt> |
| <dd>Convert a floating point constant to the corresponding unsigned integer |
| constant. TYPE must be a scalar or vector integer type. CST must be of |
| scalar or vector floating point type. Both CST and TYPE must be scalars, |
| or vectors of the same number of elements. If the value won't fit in the |
| integer type, the results are undefined.</dd> |
| |
| <dt><b><tt>fptosi (CST to TYPE)</tt></b></dt> |
| <dd>Convert a floating point constant to the corresponding signed integer |
| constant. TYPE must be a scalar or vector integer type. CST must be of |
| scalar or vector floating point type. Both CST and TYPE must be scalars, |
| or vectors of the same number of elements. If the value won't fit in the |
| integer type, the results are undefined.</dd> |
| |
| <dt><b><tt>uitofp (CST to TYPE)</tt></b></dt> |
| <dd>Convert an unsigned integer constant to the corresponding floating point |
| constant. TYPE must be a scalar or vector floating point type. CST must be |
| of scalar or vector integer type. Both CST and TYPE must be scalars, or |
| vectors of the same number of elements. If the value won't fit in the |
| floating point type, the results are undefined.</dd> |
| |
| <dt><b><tt>sitofp (CST to TYPE)</tt></b></dt> |
| <dd>Convert a signed integer constant to the corresponding floating point |
| constant. TYPE must be a scalar or vector floating point type. CST must be |
| of scalar or vector integer type. Both CST and TYPE must be scalars, or |
| vectors of the same number of elements. If the value won't fit in the |
| floating point type, the results are undefined.</dd> |
| |
| <dt><b><tt>ptrtoint (CST to TYPE)</tt></b></dt> |
| <dd>Convert a pointer typed constant to the corresponding integer constant |
| <tt>TYPE</tt> must be an integer type. <tt>CST</tt> must be of pointer |
| type. The <tt>CST</tt> value is zero extended, truncated, or unchanged to |
| make it fit in <tt>TYPE</tt>.</dd> |
| |
| <dt><b><tt>inttoptr (CST to TYPE)</tt></b></dt> |
| <dd>Convert an integer constant to a pointer constant. TYPE must be a pointer |
| type. CST must be of integer type. The CST value is zero extended, |
| truncated, or unchanged to make it fit in a pointer size. This one is |
| <i>really</i> dangerous!</dd> |
| |
| <dt><b><tt>bitcast (CST to TYPE)</tt></b></dt> |
| <dd>Convert a constant, CST, to another TYPE. The constraints of the operands |
| are the same as those for the <a href="#i_bitcast">bitcast |
| instruction</a>.</dd> |
| |
| <dt><b><tt>getelementptr (CSTPTR, IDX0, IDX1, ...)</tt></b></dt> |
| <dt><b><tt>getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)</tt></b></dt> |
| <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on |
| constants. As with the <a href="#i_getelementptr">getelementptr</a> |
| instruction, the index list may have zero or more indexes, which are |
| required to make sense for the type of "CSTPTR".</dd> |
| |
| <dt><b><tt>select (COND, VAL1, VAL2)</tt></b></dt> |
| <dd>Perform the <a href="#i_select">select operation</a> on constants.</dd> |
| |
| <dt><b><tt>icmp COND (VAL1, VAL2)</tt></b></dt> |
| <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd> |
| |
| <dt><b><tt>fcmp COND (VAL1, VAL2)</tt></b></dt> |
| <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd> |
| |
| <dt><b><tt>extractelement (VAL, IDX)</tt></b></dt> |
| <dd>Perform the <a href="#i_extractelement">extractelement operation</a> on |
| constants.</dd> |
| |
| <dt><b><tt>insertelement (VAL, ELT, IDX)</tt></b></dt> |
| <dd>Perform the <a href="#i_insertelement">insertelement operation</a> on |
| constants.</dd> |
| |
| <dt><b><tt>shufflevector (VEC1, VEC2, IDXMASK)</tt></b></dt> |
| <dd>Perform the <a href="#i_shufflevector">shufflevector operation</a> on |
| constants.</dd> |
| |
| <dt><b><tt>extractvalue (VAL, IDX0, IDX1, ...)</tt></b></dt> |
| <dd>Perform the <a href="#i_extractvalue">extractvalue operation</a> on |
| constants. The index list is interpreted in a similar manner as indices in |
| a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one |
| index value must be specified.</dd> |
| |
| <dt><b><tt>insertvalue (VAL, ELT, IDX0, IDX1, ...)</tt></b></dt> |
| <dd>Perform the <a href="#i_insertvalue">insertvalue operation</a> on |
| constants. The index list is interpreted in a similar manner as indices in |
| a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one |
| index value must be specified.</dd> |
| |
| <dt><b><tt>OPCODE (LHS, RHS)</tt></b></dt> |
| <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may |
| be any of the <a href="#binaryops">binary</a> |
| or <a href="#bitwiseops">bitwise binary</a> operations. The constraints |
| on operands are the same as those for the corresponding instruction |
| (e.g. no bitwise operations on floating point values are allowed).</dd> |
| </dl> |
| |
| </div> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <h2><a name="othervalues">Other Values</a></h2> |
| <!-- *********************************************************************** --> |
| <div> |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="inlineasm">Inline Assembler Expressions</a> |
| </h3> |
| |
| <div> |
| |
| <p>LLVM supports inline assembler expressions (as opposed |
| to <a href="#moduleasm">Module-Level Inline Assembly</a>) through the use of |
| a special value. This value represents the inline assembler as a string |
| (containing the instructions to emit), a list of operand constraints (stored |
| as a string), a flag that indicates whether or not the inline asm |
| expression has side effects, and a flag indicating whether the function |
| containing the asm needs to align its stack conservatively. An example |
| inline assembler expression is:</p> |
| |
| <pre class="doc_code"> |
| i32 (i32) asm "bswap $0", "=r,r" |
| </pre> |
| |
| <p>Inline assembler expressions may <b>only</b> be used as the callee operand of |
| a <a href="#i_call"><tt>call</tt></a> or an |
| <a href="#i_invoke"><tt>invoke</tt></a> instruction. |
| Thus, typically we have:</p> |
| |
| <pre class="doc_code"> |
| %X = call i32 asm "<a href="#int_bswap">bswap</a> $0", "=r,r"(i32 %Y) |
| </pre> |
| |
| <p>Inline asms with side effects not visible in the constraint list must be |
| marked as having side effects. This is done through the use of the |
| '<tt>sideeffect</tt>' keyword, like so:</p> |
| |
| <pre class="doc_code"> |
| call void asm sideeffect "eieio", ""() |
| </pre> |
| |
| <p>In some cases inline asms will contain code that will not work unless the |
| stack is aligned in some way, such as calls or SSE instructions on x86, |
| yet will not contain code that does that alignment within the asm. |
| The compiler should make conservative assumptions about what the asm might |
| contain and should generate its usual stack alignment code in the prologue |
| if the '<tt>alignstack</tt>' keyword is present:</p> |
| |
| <pre class="doc_code"> |
| call void asm alignstack "eieio", ""() |
| </pre> |
| |
| <p>Inline asms also support using non-standard assembly dialects. The assumed |
| dialect is ATT. When the '<tt>inteldialect</tt>' keyword is present, the |
| inline asm is using the Intel dialect. Currently, ATT and Intel are the |
| only supported dialects. An example is:</p> |
| |
| <pre class="doc_code"> |
| call void asm inteldialect "eieio", ""() |
| </pre> |
| |
| <p>If multiple keywords appear the '<tt>sideeffect</tt>' keyword must come |
| first, the '<tt>alignstack</tt>' keyword second and the |
| '<tt>inteldialect</tt>' keyword last.</p> |
| |
| <!-- |
| <p>TODO: The format of the asm and constraints string still need to be |
| documented here. Constraints on what can be done (e.g. duplication, moving, |
| etc need to be documented). This is probably best done by reference to |
| another document that covers inline asm from a holistic perspective.</p> |
| --> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="inlineasm_md">Inline Asm Metadata</a> |
| </h4> |
| |
| <div> |
| |
| <p>The call instructions that wrap inline asm nodes may have a |
| "<tt>!srcloc</tt>" MDNode attached to it that contains a list of constant |
| integers. If present, the code generator will use the integer as the |
| location cookie value when report errors through the <tt>LLVMContext</tt> |
| error reporting mechanisms. This allows a front-end to correlate backend |
| errors that occur with inline asm back to the source code that produced it. |
| For example:</p> |
| |
| <pre class="doc_code"> |
| call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b> |
| ... |
| !42 = !{ i32 1234567 } |
| </pre> |
| |
| <p>It is up to the front-end to make sense of the magic numbers it places in the |
| IR. If the MDNode contains multiple constants, the code generator will use |
| the one that corresponds to the line of the asm that the error occurs on.</p> |
| |
| </div> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <h3> |
| <a name="metadata">Metadata Nodes and Metadata Strings</a> |
| </h3> |
| |
| <div> |
| |
| <p>LLVM IR allows metadata to be attached to instructions in the program that |
| can convey extra information about the code to the optimizers and code |
| generator. One example application of metadata is source-level debug |
| information. There are two metadata primitives: strings and nodes. All |
| metadata has the <tt>metadata</tt> type and is identified in syntax by a |
| preceding exclamation point ('<tt>!</tt>').</p> |
| |
| <p>A metadata string is a string surrounded by double quotes. It can contain |
| any character by escaping non-printable characters with "<tt>\xx</tt>" where |
| "<tt>xx</tt>" is the two digit hex code. For example: |
| "<tt>!"test\00"</tt>".</p> |
| |
| <p>Metadata nodes are represented with notation similar to structure constants |
| (a comma separated list of elements, surrounded by braces and preceded by an |
| exclamation point). Metadata nodes can have any values as their operand. For |
| example:</p> |
| |
| <div class="doc_code"> |
| <pre> |
| !{ metadata !"test\00", i32 10} |
| </pre> |
| </div> |
| |
| <p>A <a href="#namedmetadatastructure">named metadata</a> is a collection of |
| metadata nodes, which can be looked up in the module symbol table. For |
| example:</p> |
| |
| <div class="doc_code"> |
| <pre> |
| !foo = metadata !{!4, !3} |
| </pre> |
| </div> |
| |
| <p>Metadata can be used as function arguments. Here <tt>llvm.dbg.value</tt> |
| function is using two metadata arguments:</p> |
| |
| <div class="doc_code"> |
| <pre> |
| call void @llvm.dbg.value(metadata !24, i64 0, metadata !25) |
| </pre> |
| </div> |
| |
| <p>Metadata can be attached with an instruction. Here metadata <tt>!21</tt> is |
| attached to the <tt>add</tt> instruction using the <tt>!dbg</tt> |
| identifier:</p> |
| |
| <div class="doc_code"> |
| <pre> |
| %indvar.next = add i64 %indvar, 1, !dbg !21 |
| </pre> |
| </div> |
| |
| <p>More information about specific metadata nodes recognized by the optimizers |
| and code generator is found below.</p> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="tbaa">'<tt>tbaa</tt>' Metadata</a> |
| </h4> |
| |
| <div> |
| |
| <p>In LLVM IR, memory does not have types, so LLVM's own type system is not |
| suitable for doing TBAA. Instead, metadata is added to the IR to describe |
| a type system of a higher level language. This can be used to implement |
| typical C/C++ TBAA, but it can also be used to implement custom alias |
| analysis behavior for other languages.</p> |
| |
| <p>The current metadata format is very simple. TBAA metadata nodes have up to |
| three fields, e.g.:</p> |
| |
| <div class="doc_code"> |
| <pre> |
| !0 = metadata !{ metadata !"an example type tree" } |
| !1 = metadata !{ metadata !"int", metadata !0 } |
| !2 = metadata !{ metadata !"float", metadata !0 } |
| !3 = metadata !{ metadata !"const float", metadata !2, i64 1 } |
| </pre> |
| </div> |
| |
| <p>The first field is an identity field. It can be any value, usually |
| a metadata string, which uniquely identifies the type. The most important |
| name in the tree is the name of the root node. Two trees with |
| different root node names are entirely disjoint, even if they |
| have leaves with common names.</p> |
| |
| <p>The second field identifies the type's parent node in the tree, or |
| is null or omitted for a root node. A type is considered to alias |
| all of its descendants and all of its ancestors in the tree. Also, |
| a type is considered to alias all types in other trees, so that |
| bitcode produced from multiple front-ends is handled conservatively.</p> |
| |
| <p>If the third field is present, it's an integer which if equal to 1 |
| indicates that the type is "constant" (meaning |
| <tt>pointsToConstantMemory</tt> should return true; see |
| <a href="AliasAnalysis.html#OtherItfs">other useful |
| <tt>AliasAnalysis</tt> methods</a>).</p> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="tbaa.struct">'<tt>tbaa.struct</tt>' Metadata</a> |
| </h4> |
| |
| <div> |
| |
| <p>The <a href="#int_memcpy"><tt>llvm.memcpy</tt></a> is often used to implement |
| aggregate assignment operations in C and similar languages, however it is |
| defined to copy a contiguous region of memory, which is more than strictly |
| necessary for aggregate types which contain holes due to padding. Also, it |
| doesn't contain any TBAA information about the fields of the aggregate.</p> |
| |
| <p><tt>!tbaa.struct</tt> metadata can describe which memory subregions in a memcpy |
| are padding and what the TBAA tags of the struct are.</p> |
| |
| <p>The current metadata format is very simple. <tt>!tbaa.struct</tt> metadata nodes |
| are a list of operands which are in conceptual groups of three. For each |
| group of three, the first operand gives the byte offset of a field in bytes, |
| the second gives its size in bytes, and the third gives its |
| tbaa tag. e.g.:</p> |
| |
| <div class="doc_code"> |
| <pre> |
| !4 = metadata !{ i64 0, i64 4, metadata !1, i64 8, i64 4, metadata !2 } |
| </pre> |
| </div> |
| |
| <p>This describes a struct with two fields. The first is at offset 0 bytes |
| with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes |
| and has size 4 bytes and has tbaa tag !2.</p> |
| |
| <p>Note that the fields need not be contiguous. In this example, there is a |
| 4 byte gap between the two fields. This gap represents padding which |
| does not carry useful data and need not be preserved.</p> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="fpmath">'<tt>fpmath</tt>' Metadata</a> |
| </h4> |
| |
| <div> |
| |
| <p><tt>fpmath</tt> metadata may be attached to any instruction of floating point |
| type. It can be used to express the maximum acceptable error in the result of |
| that instruction, in ULPs, thus potentially allowing the compiler to use a |
| more efficient but less accurate method of computing it. ULP is defined as |
| follows:</p> |
| |
| <blockquote> |
| |
| <p>If <tt>x</tt> is a real number that lies between two finite consecutive |
| floating-point numbers <tt>a</tt> and <tt>b</tt>, without being equal to one |
| of them, then <tt>ulp(x) = |b - a|</tt>, otherwise <tt>ulp(x)</tt> is the |
| distance between the two non-equal finite floating-point numbers nearest |
| <tt>x</tt>. Moreover, <tt>ulp(NaN)</tt> is <tt>NaN</tt>.</p> |
| |
| </blockquote> |
| |
| <p>The metadata node shall consist of a single positive floating point number |
| representing the maximum relative error, for example:</p> |
| |
| <div class="doc_code"> |
| <pre> |
| !0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs |
| </pre> |
| </div> |
| |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <h4> |
| <a name="range">'<tt>range</tt>' Metadata</a> |
| </h4> |
| |
| <div> |
| <p><tt>range</tt> metadata may be attached only to loads of integer types. It |
| expresses the possible ranges the loaded value is in. The ranges are |
| represented with a flattened list of integers. The loaded value is known to |
| be in the union of the ranges defined by each consecutive pair. Each pair |
| has the following properties:</p> |
| <ul> |
| <li>The type must match the type loaded by the instruction.</li> |
| <li>The pair <tt>a,b</tt> represents the range <tt>[a,b)</tt>.</li> |
| <li>Both <tt>a</tt> and <tt>b</tt> are constants.</li> |
| <li>The range is allowed to wrap.</li> |
| <li>The range should not represent the full or empty set. That is, |
| <tt>a!=b</tt>. </li> |
| </ul> |
| <p> In addition, the pairs must be in signed order of the lower bound and |
| they must be non-contiguous.</p> |
| |
| <p>Examples:</p> |
| <div class="doc_code"> |
| <pre> |
| %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1 |
| %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1 |
| %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5 |
| %d = load i8* %z, align 1, !range !3 ; Can only be -2, -1, 3, 4 or 5 |
| ... |
| !0 = metadata !{ i8 0, i8 2 } |
| !1 = metadata !{ i8 255, i8 2 } |
| !2 = metadata !{ i8 0, i8 2, i8 3, i8 6 } |
| !3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 } |
| </pre> |
| </div> |
| </div> |
| </div> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <h2> |
| <a name="module_flags">Module Flags Metadata</a> |
| </h2> |
| <!-- *********************************************************************** --> |
| |
| <div> |
| |
| <p>Information about the module as a whole is difficult to convey to LLVM's |
| subsystems. The LLVM IR isn't sufficient to transmit this |
| information. The <tt>llvm.module.flags</tt> named metadata exists in order to |
| facilitate this. These flags are in the form of key / value pairs — |
| much like a dictionary — making it easy for any subsystem who cares |
| about a flag to look it up.</p> |
| |
| <p>The <tt>llvm.module.flags</tt> metadata contains a list of metadata |
| triplets. Each triplet has the following form:</p> |
| |
| <ul> |
| <li>The first element is a <i>behavior</i> flag, which specifies the behavior |
| when two (or more) modules are merged together, and it encounters two (or |
| more) metadata with the same ID. The supported behaviors are described |
| below.</li> |
| |
| <li>The second element is a metadata string that is a unique ID for the |
| metadata. How each ID is interpreted is documented below.</li> |
| |
| <li>The third element is the value of the flag. |