docs/LangRef.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <title>LLVM Assembly Language Reference Manual</title>
   6   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   7   <meta name="author" content="Chris Lattner">
   8   <meta name="description"
   9   content="LLVM Assembly Language Reference Manual.">
  10   <link rel="stylesheet" href="llvm.css" type="text/css">
  11 </head>
  12
  13 <body>
  14
  15 <h1>LLVM Language Reference Manual</h1>
  16 <ol>
  17   <li><a href="#abstract">Abstract</a></li>
  18   <li><a href="#introduction">Introduction</a></li>
  19   <li><a href="#identifiers">Identifiers</a></li>
  20   <li><a href="#highlevel">High Level Structure</a>
  21     <ol>
  22       <li><a href="#modulestructure">Module Structure</a></li>
  23       <li><a href="#linkage">Linkage Types</a>
  24         <ol>
  25           <li><a href="#linkage_private">'<tt>private</tt>' Linkage</a></li>
  26           <li><a href="#linkage_linker_private">'<tt>linker_private</tt>' Linkage</a></li>
  27           <li><a href="#linkage_linker_private_weak">'<tt>linker_private_weak</tt>' Linkage</a></li>
  28           <li><a href="#linkage_linker_private_weak_def_auto">'<tt>linker_private_weak_def_auto</tt>' Linkage</a></li>
  29           <li><a href="#linkage_internal">'<tt>internal</tt>' Linkage</a></li>
  30           <li><a href="#linkage_available_externally">'<tt>available_externally</tt>' Linkage</a></li>
  31           <li><a href="#linkage_linkonce">'<tt>linkonce</tt>' Linkage</a></li>
  32           <li><a href="#linkage_common">'<tt>common</tt>' Linkage</a></li>
  33           <li><a href="#linkage_weak">'<tt>weak</tt>' Linkage</a></li>
  34           <li><a href="#linkage_appending">'<tt>appending</tt>' Linkage</a></li>
  35           <li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li>
  36           <li><a href="#linkage_linkonce_odr">'<tt>linkonce_odr</tt>' Linkage</a></li>
  37           <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li>
  38           <li><a href="#linkage_external">'<tt>external</tt>' Linkage</a></li>
  39           <li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li>
  40           <li><a href="#linkage_dllexport">'<tt>dllexport</tt>' Linkage</a></li>
  41         </ol>
  42       </li>
  43       <li><a href="#callingconv">Calling Conventions</a></li>
  44       <li><a href="#namedtypes">Named Types</a></li>
  45       <li><a href="#globalvars">Global Variables</a></li>
  46       <li><a href="#functionstructure">Functions</a></li>
  47       <li><a href="#aliasstructure">Aliases</a></li>
  48       <li><a href="#namedmetadatastructure">Named Metadata</a></li>
  49       <li><a href="#paramattrs">Parameter Attributes</a></li>
  50       <li><a href="#fnattrs">Function Attributes</a></li>
  51       <li><a href="#gc">Garbage Collector Names</a></li>
  52       <li><a href="#moduleasm">Module-Level Inline Assembly</a></li>
  53       <li><a href="#datalayout">Data Layout</a></li>
  54       <li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li>
  55       <li><a href="#volatile">Volatile Memory Accesses</a></li>
  56       <li><a href="#memmodel">Memory Model for Concurrent Operations</a></li>
  57       <li><a href="#ordering">Atomic Memory Ordering Constraints</a></li>
  58     </ol>
  59   </li>
  60   <li><a href="#typesystem">Type System</a>
  61     <ol>
  62       <li><a href="#t_classifications">Type Classifications</a></li>
  63       <li><a href="#t_primitive">Primitive Types</a>
  64         <ol>
  65           <li><a href="#t_integer">Integer Type</a></li>
  66           <li><a href="#t_floating">Floating Point Types</a></li>
  67           <li><a href="#t_x86mmx">X86mmx Type</a></li>
  68           <li><a href="#t_void">Void Type</a></li>
  69           <li><a href="#t_label">Label Type</a></li>
  70           <li><a href="#t_metadata">Metadata Type</a></li>
  71         </ol>
  72       </li>
  73       <li><a href="#t_derived">Derived Types</a>
  74         <ol>
  75           <li><a href="#t_aggregate">Aggregate Types</a>
  76             <ol>
  77               <li><a href="#t_array">Array Type</a></li>
  78               <li><a href="#t_struct">Structure Type</a></li>
  79               <li><a href="#t_opaque">Opaque Structure Types</a></li>
  80               <li><a href="#t_vector">Vector Type</a></li>
  81             </ol>
  82           </li>
  83           <li><a href="#t_function">Function Type</a></li>
  84           <li><a href="#t_pointer">Pointer Type</a></li>
  85         </ol>
  86       </li>
  87     </ol>
  88   </li>
  89   <li><a href="#constants">Constants</a>
  90     <ol>
  91       <li><a href="#simpleconstants">Simple Constants</a></li>
  92       <li><a href="#complexconstants">Complex Constants</a></li>
  93       <li><a href="#globalconstants">Global Variable and Function Addresses</a></li>
  94       <li><a href="#undefvalues">Undefined Values</a></li>
  95       <li><a href="#trapvalues">Trap Values</a></li>
  96       <li><a href="#blockaddress">Addresses of Basic Blocks</a></li>
  97       <li><a href="#constantexprs">Constant Expressions</a></li>
  98     </ol>
  99   </li>
 100   <li><a href="#othervalues">Other Values</a>
 101     <ol>
 102       <li><a href="#inlineasm">Inline Assembler Expressions</a></li>
 103       <li><a href="#metadata">Metadata Nodes and Metadata Strings</a>
 104         <ol>
 105           <li><a href="#tbaa">'<tt>tbaa</tt>' Metadata</a></li>
 106           <li><a href="#fpaccuracy">'<tt>fpaccuracy</tt>' Metadata</a></li>
 107         </ol>
 108       </li>
 109     </ol>
 110   </li>
 111   <li><a href="#intrinsic_globals">Intrinsic Global Variables</a>
 112     <ol>
 113       <li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li>
 114       <li><a href="#intg_compiler_used">The '<tt>llvm.compiler.used</tt>'
 115           Global Variable</a></li>
 116       <li><a href="#intg_global_ctors">The '<tt>llvm.global_ctors</tt>'
 117          Global Variable</a></li>
 118       <li><a href="#intg_global_dtors">The '<tt>llvm.global_dtors</tt>'
 119          Global Variable</a></li>
 120     </ol>
 121   </li>
 122   <li><a href="#instref">Instruction Reference</a>
 123     <ol>
 124       <li><a href="#terminators">Terminator Instructions</a>
 125         <ol>
 126           <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li>
 127           <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
 128           <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
 129           <li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li>
 130           <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
 131           <li><a href="#i_unwind">'<tt>unwind</tt>'  Instruction</a></li>
 132           <li><a href="#i_resume">'<tt>resume</tt>'  Instruction</a></li>
 133           <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
 134         </ol>
 135       </li>
 136       <li><a href="#binaryops">Binary Operations</a>
 137         <ol>
 138           <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li>
 139           <li><a href="#i_fadd">'<tt>fadd</tt>' Instruction</a></li>
 140           <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li>
 141           <li><a href="#i_fsub">'<tt>fsub</tt>' Instruction</a></li>
 142           <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li>
 143           <li><a href="#i_fmul">'<tt>fmul</tt>' Instruction</a></li>
 144           <li><a href="#i_udiv">'<tt>udiv</tt>' Instruction</a></li>
 145           <li><a href="#i_sdiv">'<tt>sdiv</tt>' Instruction</a></li>
 146           <li><a href="#i_fdiv">'<tt>fdiv</tt>' Instruction</a></li>
 147           <li><a href="#i_urem">'<tt>urem</tt>' Instruction</a></li>
 148           <li><a href="#i_srem">'<tt>srem</tt>' Instruction</a></li>
 149           <li><a href="#i_frem">'<tt>frem</tt>' Instruction</a></li>
 150         </ol>
 151       </li>
 152       <li><a href="#bitwiseops">Bitwise Binary Operations</a>
 153         <ol>
 154           <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
 155           <li><a href="#i_lshr">'<tt>lshr</tt>' Instruction</a></li>
 156           <li><a href="#i_ashr">'<tt>ashr</tt>' Instruction</a></li>
 157           <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
 158           <li><a href="#i_or">'<tt>or</tt>'  Instruction</a></li>
 159           <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
 160         </ol>
 161       </li>
 162       <li><a href="#vectorops">Vector Operations</a>
 163         <ol>
 164           <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li>
 165           <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li>
 166           <li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li>
 167         </ol>
 168       </li>
 169       <li><a href="#aggregateops">Aggregate Operations</a>
 170         <ol>
 171           <li><a href="#i_extractvalue">'<tt>extractvalue</tt>' Instruction</a></li>
 172           <li><a href="#i_insertvalue">'<tt>insertvalue</tt>' Instruction</a></li>
 173         </ol>
 174       </li>
 175       <li><a href="#memoryops">Memory Access and Addressing Operations</a>
 176         <ol>
 177           <li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li>
 178          <li><a href="#i_load">'<tt>load</tt>' Instruction</a></li>
 179          <li><a href="#i_store">'<tt>store</tt>' Instruction</a></li>
 180          <li><a href="#i_fence">'<tt>fence</tt>' Instruction</a></li>
 181          <li><a href="#i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a></li>
 182          <li><a href="#i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a></li>
 183          <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
 184         </ol>
 185       </li>
 186       <li><a href="#convertops">Conversion Operations</a>
 187         <ol>
 188           <li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li>
 189           <li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li>
 190           <li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li>
 191           <li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li>
 192           <li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li>
 193           <li><a href="#i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a></li>
 194           <li><a href="#i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a></li>
 195           <li><a href="#i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a></li>
 196           <li><a href="#i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a></li>
 197           <li><a href="#i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a></li>
 198           <li><a href="#i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a></li>
 199           <li><a href="#i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a></li>
 200         </ol>
 201       </li>
 202       <li><a href="#otherops">Other Operations</a>
 203         <ol>
 204           <li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li>
 205           <li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li>
 206           <li><a href="#i_phi">'<tt>phi</tt>'   Instruction</a></li>
 207           <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
 208           <li><a href="#i_call">'<tt>call</tt>'  Instruction</a></li>
 209           <li><a href="#i_va_arg">'<tt>va_arg</tt>'  Instruction</a></li>
 210           <li><a href="#i_landingpad">'<tt>landingpad</tt>' Instruction</a></li>
 211         </ol>
 212       </li>
 213     </ol>
 214   </li>
 215   <li><a href="#intrinsics">Intrinsic Functions</a>
 216     <ol>
 217       <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
 218         <ol>
 219           <li><a href="#int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
 220           <li><a href="#int_va_end">'<tt>llvm.va_end</tt>'   Intrinsic</a></li>
 221           <li><a href="#int_va_copy">'<tt>llvm.va_copy</tt>'  Intrinsic</a></li>
 222         </ol>
 223       </li>
 224       <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a>
 225         <ol>
 226           <li><a href="#int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
 227           <li><a href="#int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
 228           <li><a href="#int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
 229         </ol>
 230       </li>
 231       <li><a href="#int_codegen">Code Generator Intrinsics</a>
 232         <ol>
 233           <li><a href="#int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
 234           <li><a href="#int_frameaddress">'<tt>llvm.frameaddress</tt>'   Intrinsic</a></li>
 235           <li><a href="#int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a></li>
 236           <li><a href="#int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li>
 237           <li><a href="#int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
 238           <li><a href="#int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
 239           <li><a href="#int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a></li>
 240         </ol>
 241       </li>
 242       <li><a href="#int_libc">Standard C Library Intrinsics</a>
 243         <ol>
 244           <li><a href="#int_memcpy">'<tt>llvm.memcpy.*</tt>' Intrinsic</a></li>
 245           <li><a href="#int_memmove">'<tt>llvm.memmove.*</tt>' Intrinsic</a></li>
 246           <li><a href="#int_memset">'<tt>llvm.memset.*</tt>' Intrinsic</a></li>
 247           <li><a href="#int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a></li>
 248           <li><a href="#int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a></li>
 249           <li><a href="#int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a></li>
 250           <li><a href="#int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a></li>
 251           <li><a href="#int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a></li>
 252           <li><a href="#int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a></li>
 253           <li><a href="#int_log">'<tt>llvm.log.*</tt>' Intrinsic</a></li>
 254           <li><a href="#int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a></li>
 255         </ol>
 256       </li>
 257       <li><a href="#int_manip">Bit Manipulation Intrinsics</a>
 258         <ol>
 259           <li><a href="#int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a></li>
 260           <li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li>
 261           <li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li>
 262           <li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li>
 263         </ol>
 264       </li>
 265       <li><a href="#int_overflow">Arithmetic with Overflow Intrinsics</a>
 266         <ol>
 267           <li><a href="#int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt> Intrinsics</a></li>
 268           <li><a href="#int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt> Intrinsics</a></li>
 269           <li><a href="#int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt> Intrinsics</a></li>
 270           <li><a href="#int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt> Intrinsics</a></li>
 271           <li><a href="#int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt> Intrinsics</a></li>
 272           <li><a href="#int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt> Intrinsics</a></li>
 273         </ol>
 274       </li>
 275       <li><a href="#int_fp16">Half Precision Floating Point Intrinsics</a>
 276         <ol>
 277           <li><a href="#int_convert_to_fp16">'<tt>llvm.convert.to.fp16</tt>' Intrinsic</a></li>
 278           <li><a href="#int_convert_from_fp16">'<tt>llvm.convert.from.fp16</tt>' Intrinsic</a></li>
 279         </ol>
 280       </li>
 281       <li><a href="#int_debugger">Debugger intrinsics</a></li>
 282       <li><a href="#int_eh">Exception Handling intrinsics</a></li>
 283       <li><a href="#int_trampoline">Trampoline Intrinsics</a>
 284         <ol>
 285           <li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li>
 286           <li><a href="#int_at">'<tt>llvm.adjust.trampoline</tt>' Intrinsic</a></li>
 287         </ol>
 288       </li>
 289       <li><a href="#int_memorymarkers">Memory Use Markers</a>
 290         <ol>
 291           <li><a href="#int_lifetime_start"><tt>llvm.lifetime.start</tt></a></li>
 292           <li><a href="#int_lifetime_end"><tt>llvm.lifetime.end</tt></a></li>
 293           <li><a href="#int_invariant_start"><tt>llvm.invariant.start</tt></a></li>
 294           <li><a href="#int_invariant_end"><tt>llvm.invariant.end</tt></a></li>
 295         </ol>
 296       </li>
 297       <li><a href="#int_general">General intrinsics</a>
 298         <ol>
 299           <li><a href="#int_var_annotation">
 300             '<tt>llvm.var.annotation</tt>' Intrinsic</a></li>
 301           <li><a href="#int_annotation">
 302             '<tt>llvm.annotation.*</tt>' Intrinsic</a></li>
 303           <li><a href="#int_trap">
 304             '<tt>llvm.trap</tt>' Intrinsic</a></li>
 305           <li><a href="#int_stackprotector">
 306             '<tt>llvm.stackprotector</tt>' Intrinsic</a></li>
 307           <li><a href="#int_objectsize">
 308             '<tt>llvm.objectsize</tt>' Intrinsic</a></li>
 309           <li><a href="#int_expect">
 310             '<tt>llvm.expect</tt>' Intrinsic</a></li>
 311         </ol>
 312       </li>
 313     </ol>
 314   </li>
 315 </ol>
 316
 317 <div class="doc_author">
 318   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
 319             and <a href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></p>
 320 </div>
 321
 322 <!-- *********************************************************************** -->
 323 <h2><a name="abstract">Abstract</a></h2>
 324 <!-- *********************************************************************** -->
 325
 326 <div>
 327
 328 <p>This document is a reference manual for the LLVM assembly language. LLVM is
 329    a Static Single Assignment (SSA) based representation that provides type
 330    safety, low-level operations, flexibility, and the capability of representing
 331    'all' high-level languages cleanly.  It is the common code representation
 332    used throughout all phases of the LLVM compilation strategy.</p>
 333
 334 </div>
 335
 336 <!-- *********************************************************************** -->
 337 <h2><a name="introduction">Introduction</a></h2>
 338 <!-- *********************************************************************** -->
 339
 340 <div>
 341
 342 <p>The LLVM code representation is designed to be used in three different forms:
 343    as an in-memory compiler IR, as an on-disk bitcode representation (suitable
 344    for fast loading by a Just-In-Time compiler), and as a human readable
 345    assembly language representation.  This allows LLVM to provide a powerful
 346    intermediate representation for efficient compiler transformations and
 347    analysis, while providing a natural means to debug and visualize the
 348    transformations.  The three different forms of LLVM are all equivalent.  This
 349    document describes the human readable representation and notation.</p>
 350
 351 <p>The LLVM representation aims to be light-weight and low-level while being
 352    expressive, typed, and extensible at the same time.  It aims to be a
 353    "universal IR" of sorts, by being at a low enough level that high-level ideas
 354    may be cleanly mapped to it (similar to how microprocessors are "universal
 355    IR's", allowing many source languages to be mapped to them).  By providing
 356    type information, LLVM can be used as the target of optimizations: for
 357    example, through pointer analysis, it can be proven that a C automatic
 358    variable is never accessed outside of the current function, allowing it to
 359    be promoted to a simple SSA value instead of a memory location.</p>
 360
 361 <!-- _______________________________________________________________________ -->
 362 <h4>
 363   <a name="wellformed">Well-Formedness</a>
 364 </h4>
 365
 366 <div>
 367
 368 <p>It is important to note that this document describes 'well formed' LLVM
 369    assembly language.  There is a difference between what the parser accepts and
 370    what is considered 'well formed'.  For example, the following instruction is
 371    syntactically okay, but not well formed:</p>
 372
 373 <pre class="doc_code">
 374 %x = <a href="#i_add">add</a> i32 1, %x
 375 </pre>
 376
 377 <p>because the definition of <tt>%x</tt> does not dominate all of its uses. The
 378    LLVM infrastructure provides a verification pass that may be used to verify
 379    that an LLVM module is well formed.  This pass is automatically run by the
 380    parser after parsing input assembly and by the optimizer before it outputs
 381    bitcode.  The violations pointed out by the verifier pass indicate bugs in
 382    transformation passes or input to the parser.</p>
 383
 384 </div>
 385
 386 </div>
 387
 388 <!-- Describe the typesetting conventions here. -->
 389
 390 <!-- *********************************************************************** -->
 391 <h2><a name="identifiers">Identifiers</a></h2>
 392 <!-- *********************************************************************** -->
 393
 394 <div>
 395
 396 <p>LLVM identifiers come in two basic types: global and local. Global
 397    identifiers (functions, global variables) begin with the <tt>'@'</tt>
 398    character. Local identifiers (register names, types) begin with
 399    the <tt>'%'</tt> character. Additionally, there are three different formats
 400    for identifiers, for different purposes:</p>
 401
 402 <ol>
 403   <li>Named values are represented as a string of characters with their prefix.
 404       For example, <tt>%foo</tt>, <tt>@DivisionByZero</tt>,
 405       <tt>%a.really.long.identifier</tt>. The actual regular expression used is
 406       '<tt>[%@][a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.  Identifiers which require
 407       other characters in their names can be surrounded with quotes. Special
 408       characters may be escaped using <tt>"\xx"</tt> where <tt>xx</tt> is the
 409       ASCII code for the character in hexadecimal.  In this way, any character
 410       can be used in a name value, even quotes themselves.</li>
 411
 412   <li>Unnamed values are represented as an unsigned numeric value with their
 413       prefix.  For example, <tt>%12</tt>, <tt>@2</tt>, <tt>%44</tt>.</li>
 414
 415   <li>Constants, which are described in a <a href="#constants">section about
 416       constants</a>, below.</li>
 417 </ol>
 418
 419 <p>LLVM requires that values start with a prefix for two reasons: Compilers
 420    don't need to worry about name clashes with reserved words, and the set of
 421    reserved words may be expanded in the future without penalty.  Additionally,
 422    unnamed identifiers allow a compiler to quickly come up with a temporary
 423    variable without having to avoid symbol table conflicts.</p>
 424
 425 <p>Reserved words in LLVM are very similar to reserved words in other
 426    languages. There are keywords for different opcodes
 427    ('<tt><a href="#i_add">add</a></tt>',
 428    '<tt><a href="#i_bitcast">bitcast</a></tt>',
 429    '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names
 430    ('<tt><a href="#t_void">void</a></tt>',
 431    '<tt><a href="#t_primitive">i32</a></tt>', etc...), and others.  These
 432    reserved words cannot conflict with variable names, because none of them
 433    start with a prefix character (<tt>'%'</tt> or <tt>'@'</tt>).</p>
 434
 435 <p>Here is an example of LLVM code to multiply the integer variable
 436    '<tt>%X</tt>' by 8:</p>
 437
 438 <p>The easy way:</p>
 439
 440 <pre class="doc_code">
 441 %result = <a href="#i_mul">mul</a> i32 %X, 8
 442 </pre>
 443
 444 <p>After strength reduction:</p>
 445
 446 <pre class="doc_code">
 447 %result = <a href="#i_shl">shl</a> i32 %X, i8 3
 448 </pre>
 449
 450 <p>And the hard way:</p>
 451
 452 <pre class="doc_code">
 453 %0 = <a href="#i_add">add</a> i32 %X, %X           <i>; yields {i32}:%0</i>
 454 %1 = <a href="#i_add">add</a> i32 %0, %0           <i>; yields {i32}:%1</i>
 455 %result = <a href="#i_add">add</a> i32 %1, %1
 456 </pre>
 457
 458 <p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important
 459    lexical features of LLVM:</p>
 460
 461 <ol>
 462   <li>Comments are delimited with a '<tt>;</tt>' and go until the end of
 463       line.</li>
 464
 465   <li>Unnamed temporaries are created when the result of a computation is not
 466       assigned to a named value.</li>
 467
 468   <li>Unnamed temporaries are numbered sequentially</li>
 469 </ol>
 470
 471 <p>It also shows a convention that we follow in this document.  When
 472    demonstrating instructions, we will follow an instruction with a comment that
 473    defines the type and name of value produced.  Comments are shown in italic
 474    text.</p>
 475
 476 </div>
 477
 478 <!-- *********************************************************************** -->
 479 <h2><a name="highlevel">High Level Structure</a></h2>
 480 <!-- *********************************************************************** -->
 481 <div>
 482 <!-- ======================================================================= -->
 483 <h3>
 484   <a name="modulestructure">Module Structure</a>
 485 </h3>
 486
 487 <div>
 488
 489 <p>LLVM programs are composed of "Module"s, each of which is a translation unit
 490    of the input programs.  Each module consists of functions, global variables,
 491    and symbol table entries.  Modules may be combined together with the LLVM
 492    linker, which merges function (and global variable) definitions, resolves
 493    forward declarations, and merges symbol table entries. Here is an example of
 494    the "hello world" module:</p>
 495
 496 <pre class="doc_code">
 497 <i>; Declare the string constant as a global constant.</i>&nbsp;
 498 <a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a>&nbsp;<a href="#globalvars">constant</a>&nbsp;<a href="#t_array">[13 x i8]</a> c"hello world\0A\00"      <i>; [13 x i8]*</i>&nbsp;
 499
 500 <i>; External declaration of the puts function</i>&nbsp;
 501 <a href="#functionstructure">declare</a> i32 @puts(i8*)                                      <i>; i32 (i8*)* </i>&nbsp;
 502
 503 <i>; Definition of main function</i>
 504 define i32 @main() {   <i>; i32()* </i>&nbsp;
 505   <i>; Convert [13 x i8]* to i8  *...</i>&nbsp;
 506   %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0   <i>; i8*</i>&nbsp;
 507
 508   <i>; Call puts function to write out the string to stdout.</i>&nbsp;
 509   <a href="#i_call">call</a> i32 @puts(i8* %cast210)           <i>; i32</i>&nbsp;
 510   <a href="#i_ret">ret</a> i32 0&nbsp;
 511 }
 512
 513 <i>; Named metadata</i>
 514 !1 = metadata !{i32 41}
 515 !foo = !{!1, null}
 516 </pre>
 517
 518 <p>This example is made up of a <a href="#globalvars">global variable</a> named
 519    "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function,
 520    a <a href="#functionstructure">function definition</a> for
 521    "<tt>main</tt>" and <a href="#namedmetadatastructure">named metadata</a>
 522    "<tt>foo"</tt>.</p>
 523
 524 <p>In general, a module is made up of a list of global values, where both
 525    functions and global variables are global values.  Global values are
 526    represented by a pointer to a memory location (in this case, a pointer to an
 527    array of char, and a pointer to a function), and have one of the
 528    following <a href="#linkage">linkage types</a>.</p>
 529
 530 </div>
 531
 532 <!-- ======================================================================= -->
 533 <h3>
 534   <a name="linkage">Linkage Types</a>
 535 </h3>
 536
 537 <div>
 538
 539 <p>All Global Variables and Functions have one of the following types of
 540    linkage:</p>
 541
 542 <dl>
 543   <dt><tt><b><a name="linkage_private">private</a></b></tt></dt>
 544   <dd>Global values with "<tt>private</tt>" linkage are only directly accessible
 545       by objects in the current module. In particular, linking code into a
 546       module with an private global value may cause the private to be renamed as
 547       necessary to avoid collisions.  Because the symbol is private to the
 548       module, all references can be updated. This doesn't show up in any symbol
 549       table in the object file.</dd>
 550
 551   <dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt></dt>
 552   <dd>Similar to <tt>private</tt>, but the symbol is passed through the
 553       assembler and evaluated by the linker. Unlike normal strong symbols, they
 554       are removed by the linker from the final linked image (executable or
 555       dynamic library).</dd>
 556
 557   <dt><tt><b><a name="linkage_linker_private_weak">linker_private_weak</a></b></tt></dt>
 558   <dd>Similar to "<tt>linker_private</tt>", but the symbol is weak. Note that
 559       <tt>linker_private_weak</tt> symbols are subject to coalescing by the
 560       linker. The symbols are removed by the linker from the final linked image
 561       (executable or dynamic library).</dd>
 562
 563   <dt><tt><b><a name="linkage_linker_private_weak_def_auto">linker_private_weak_def_auto</a></b></tt></dt>
 564   <dd>Similar to "<tt>linker_private_weak</tt>", but it's known that the address
 565       of the object is not taken. For instance, functions that had an inline
 566       definition, but the compiler decided not to inline it. Note,
 567       unlike <tt>linker_private</tt> and <tt>linker_private_weak</tt>,
 568       <tt>linker_private_weak_def_auto</tt> may have only <tt>default</tt>
 569       visibility.  The symbols are removed by the linker from the final linked
 570       image (executable or dynamic library).</dd>
 571
 572   <dt><tt><b><a name="linkage_internal">internal</a></b></tt></dt>
 573   <dd>Similar to private, but the value shows as a local symbol
 574       (<tt>STB_LOCAL</tt> in the case of ELF) in the object file. This
 575       corresponds to the notion of the '<tt>static</tt>' keyword in C.</dd>
 576
 577   <dt><tt><b><a name="linkage_available_externally">available_externally</a></b></tt></dt>
 578   <dd>Globals with "<tt>available_externally</tt>" linkage are never emitted
 579       into the object file corresponding to the LLVM module.  They exist to
 580       allow inlining and other optimizations to take place given knowledge of
 581       the definition of the global, which is known to be somewhere outside the
 582       module.  Globals with <tt>available_externally</tt> linkage are allowed to
 583       be discarded at will, and are otherwise the same as <tt>linkonce_odr</tt>.
 584       This linkage type is only allowed on definitions, not declarations.</dd>
 585
 586   <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt></dt>
 587   <dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of
 588       the same name when linkage occurs.  This can be used to implement
 589       some forms of inline functions, templates, or other code which must be
 590       generated in each translation unit that uses it, but where the body may
 591       be overridden with a more definitive definition later.  Unreferenced
 592       <tt>linkonce</tt> globals are allowed to be discarded.  Note that
 593       <tt>linkonce</tt> linkage does not actually allow the optimizer to
 594       inline the body of this function into callers because it doesn't know if
 595       this definition of the function is the definitive definition within the
 596       program or whether it will be overridden by a stronger definition.
 597       To enable inlining and other optimizations, use "<tt>linkonce_odr</tt>"
 598       linkage.</dd>
 599
 600   <dt><tt><b><a name="linkage_weak">weak</a></b></tt></dt>
 601   <dd>"<tt>weak</tt>" linkage has the same merging semantics as
 602       <tt>linkonce</tt> linkage, except that unreferenced globals with
 603       <tt>weak</tt> linkage may not be discarded.  This is used for globals that
 604       are declared "weak" in C source code.</dd>
 605
 606   <dt><tt><b><a name="linkage_common">common</a></b></tt></dt>
 607   <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but
 608       they are used for tentative definitions in C, such as "<tt>int X;</tt>" at
 609       global scope.
 610       Symbols with "<tt>common</tt>" linkage are merged in the same way as
 611       <tt>weak symbols</tt>, and they may not be deleted if unreferenced.
 612       <tt>common</tt> symbols may not have an explicit section,
 613       must have a zero initializer, and may not be marked '<a
 614       href="#globalvars"><tt>constant</tt></a>'.  Functions and aliases may not
 615       have common linkage.</dd>
 616
 617
 618   <dt><tt><b><a name="linkage_appending">appending</a></b></tt></dt>
 619   <dd>"<tt>appending</tt>" linkage may only be applied to global variables of
 620       pointer to array type.  When two global variables with appending linkage
 621       are linked together, the two global arrays are appended together.  This is
 622       the LLVM, typesafe, equivalent of having the system linker append together
 623       "sections" with identical names when .o files are linked.</dd>
 624
 625   <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt></dt>
 626   <dd>The semantics of this linkage follow the ELF object file model: the symbol
 627       is weak until linked, if not linked, the symbol becomes null instead of
 628       being an undefined reference.</dd>
 629
 630   <dt><tt><b><a name="linkage_linkonce_odr">linkonce_odr</a></b></tt></dt>
 631   <dt><tt><b><a name="linkage_weak_odr">weak_odr</a></b></tt></dt>
 632   <dd>Some languages allow differing globals to be merged, such as two functions
 633       with different semantics.  Other languages, such as <tt>C++</tt>, ensure
 634       that only equivalent globals are ever merged (the "one definition rule"
 635       &mdash; "ODR").  Such languages can use the <tt>linkonce_odr</tt>
 636       and <tt>weak_odr</tt> linkage types to indicate that the global will only
 637       be merged with equivalent globals.  These linkage types are otherwise the
 638       same as their non-<tt>odr</tt> versions.</dd>
 639
 640   <dt><tt><b><a name="linkage_external">external</a></b></tt></dt>
 641   <dd>If none of the above identifiers are used, the global is externally
 642       visible, meaning that it participates in linkage and can be used to
 643       resolve external symbol references.</dd>
 644 </dl>
 645
 646 <p>The next two types of linkage are targeted for Microsoft Windows platform
 647    only. They are designed to support importing (exporting) symbols from (to)
 648    DLLs (Dynamic Link Libraries).</p>
 649
 650 <dl>
 651   <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt></dt>
 652   <dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function
 653       or variable via a global pointer to a pointer that is set up by the DLL
 654       exporting the symbol. On Microsoft Windows targets, the pointer name is
 655       formed by combining <code>__imp_</code> and the function or variable
 656       name.</dd>
 657
 658   <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt></dt>
 659   <dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global
 660       pointer to a pointer in a DLL, so that it can be referenced with the
 661       <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer
 662       name is formed by combining <code>__imp_</code> and the function or
 663       variable name.</dd>
 664 </dl>
 665
 666 <p>For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
 667    another module defined a "<tt>.LC0</tt>" variable and was linked with this
 668    one, one of the two would be renamed, preventing a collision.  Since
 669    "<tt>main</tt>" and "<tt>puts</tt>" are external (i.e., lacking any linkage
 670    declarations), they are accessible outside of the current module.</p>
 671
 672 <p>It is illegal for a function <i>declaration</i> to have any linkage type
 673    other than <tt>external</tt>, <tt>dllimport</tt>
 674   or <tt>extern_weak</tt>.</p>
 675
 676 <p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt>
 677    or <tt>weak_odr</tt> linkages.</p>
 678
 679 </div>
 680
 681 <!-- ======================================================================= -->
 682 <h3>
 683   <a name="callingconv">Calling Conventions</a>
 684 </h3>
 685
 686 <div>
 687
 688 <p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a>
 689    and <a href="#i_invoke">invokes</a> can all have an optional calling
 690    convention specified for the call.  The calling convention of any pair of
 691    dynamic caller/callee must match, or the behavior of the program is
 692    undefined.  The following calling conventions are supported by LLVM, and more
 693    may be added in the future:</p>
 694
 695 <dl>
 696   <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt>
 697   <dd>This calling convention (the default if no other calling convention is
 698       specified) matches the target C calling conventions.  This calling
 699       convention supports varargs function calls and tolerates some mismatch in
 700       the declared prototype and implemented declaration of the function (as
 701       does normal C).</dd>
 702
 703   <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt>
 704   <dd>This calling convention attempts to make calls as fast as possible
 705       (e.g. by passing things in registers).  This calling convention allows the
 706       target to use whatever tricks it wants to produce fast code for the
 707       target, without having to conform to an externally specified ABI
 708       (Application Binary Interface).
 709       <a href="CodeGenerator.html#tailcallopt">Tail calls can only be optimized
 710       when this or the GHC convention is used.</a>  This calling convention
 711       does not support varargs and requires the prototype of all callees to
 712       exactly match the prototype of the function definition.</dd>
 713
 714   <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt>
 715   <dd>This calling convention attempts to make code in the caller as efficient
 716       as possible under the assumption that the call is not commonly executed.
 717       As such, these calls often preserve all registers so that the call does
 718       not break any live ranges in the caller side.  This calling convention
 719       does not support varargs and requires the prototype of all callees to
 720       exactly match the prototype of the function definition.</dd>
 721
 722   <dt><b>"<tt>cc <em>10</em></tt>" - GHC convention</b>:</dt>
 723   <dd>This calling convention has been implemented specifically for use by the
 724       <a href="http://www.haskell.org/ghc">Glasgow Haskell Compiler (GHC)</a>.
 725       It passes everything in registers, going to extremes to achieve this by
 726       disabling callee save registers. This calling convention should not be
 727       used lightly but only for specific situations such as an alternative to
 728       the <em>register pinning</em> performance technique often used when
 729       implementing functional programming languages.At the moment only X86
 730       supports this convention and it has the following limitations:
 731       <ul>
 732         <li>On <em>X86-32</em> only supports up to 4 bit type parameters. No
 733             floating point types are supported.</li>
 734         <li>On <em>X86-64</em> only supports up to 10 bit type parameters and
 735             6 floating point parameters.</li>
 736       </ul>
 737       This calling convention supports
 738       <a href="CodeGenerator.html#tailcallopt">tail call optimization</a> but
 739       requires both the caller and callee are using it.
 740   </dd>
 741
 742   <dt><b>"<tt>cc &lt;<em>n</em>&gt;</tt>" - Numbered convention</b>:</dt>
 743   <dd>Any calling convention may be specified by number, allowing
 744       target-specific calling conventions to be used.  Target specific calling
 745       conventions start at 64.</dd>
 746 </dl>
 747
 748 <p>More calling conventions can be added/defined on an as-needed basis, to
 749    support Pascal conventions or any other well-known target-independent
 750    convention.</p>
 751
 752 </div>
 753
 754 <!-- ======================================================================= -->
 755 <h3>
 756   <a name="visibility">Visibility Styles</a>
 757 </h3>
 758
 759 <div>
 760
 761 <p>All Global Variables and Functions have one of the following visibility
 762    styles:</p>
 763
 764 <dl>
 765   <dt><b>"<tt>default</tt>" - Default style</b>:</dt>
 766   <dd>On targets that use the ELF object file format, default visibility means
 767       that the declaration is visible to other modules and, in shared libraries,
 768       means that the declared entity may be overridden. On Darwin, default
 769       visibility means that the declaration is visible to other modules. Default
 770       visibility corresponds to "external linkage" in the language.</dd>
 771
 772   <dt><b>"<tt>hidden</tt>" - Hidden style</b>:</dt>
 773   <dd>Two declarations of an object with hidden visibility refer to the same
 774       object if they are in the same shared object. Usually, hidden visibility
 775       indicates that the symbol will not be placed into the dynamic symbol
 776       table, so no other module (executable or shared library) can reference it
 777       directly.</dd>
 778
 779   <dt><b>"<tt>protected</tt>" - Protected style</b>:</dt>
 780   <dd>On ELF, protected visibility indicates that the symbol will be placed in
 781       the dynamic symbol table, but that references within the defining module
 782       will bind to the local symbol. That is, the symbol cannot be overridden by
 783       another module.</dd>
 784 </dl>
 785
 786 </div>
 787
 788 <!-- ======================================================================= -->
 789 <h3>
 790   <a name="namedtypes">Named Types</a>
 791 </h3>
 792
 793 <div>
 794
 795 <p>LLVM IR allows you to specify name aliases for certain types.  This can make
 796    it easier to read the IR and make the IR more condensed (particularly when
 797    recursive types are involved).  An example of a name specification is:</p>
 798
 799 <pre class="doc_code">
 800 %mytype = type { %mytype*, i32 }
 801 </pre>
 802
 803 <p>You may give a name to any <a href="#typesystem">type</a> except
 804    "<a href="#t_void">void</a>".  Type name aliases may be used anywhere a type
 805    is expected with the syntax "%mytype".</p>
 806
 807 <p>Note that type names are aliases for the structural type that they indicate,
 808    and that you can therefore specify multiple names for the same type.  This
 809    often leads to confusing behavior when dumping out a .ll file.  Since LLVM IR
 810    uses structural typing, the name is not part of the type.  When printing out
 811    LLVM IR, the printer will pick <em>one name</em> to render all types of a
 812    particular shape.  This means that if you have code where two different
 813    source types end up having the same LLVM type, that the dumper will sometimes
 814    print the "wrong" or unexpected type.  This is an important design point and
 815    isn't going to change.</p>
 816
 817 </div>
 818
 819 <!-- ======================================================================= -->
 820 <h3>
 821   <a name="globalvars">Global Variables</a>
 822 </h3>
 823
 824 <div>
 825
 826 <p>Global variables define regions of memory allocated at compilation time
 827    instead of run-time.  Global variables may optionally be initialized, may
 828    have an explicit section to be placed in, and may have an optional explicit
 829    alignment specified.  A variable may be defined as "thread_local", which
 830    means that it will not be shared by threads (each thread will have a
 831    separated copy of the variable).  A variable may be defined as a global
 832    "constant," which indicates that the contents of the variable
 833    will <b>never</b> be modified (enabling better optimization, allowing the
 834    global data to be placed in the read-only section of an executable, etc).
 835    Note that variables that need runtime initialization cannot be marked
 836    "constant" as there is a store to the variable.</p>
 837
 838 <p>LLVM explicitly allows <em>declarations</em> of global variables to be marked
 839    constant, even if the final definition of the global is not.  This capability
 840    can be used to enable slightly better optimization of the program, but
 841    requires the language definition to guarantee that optimizations based on the
 842    'constantness' are valid for the translation units that do not include the
 843    definition.</p>
 844
 845 <p>As SSA values, global variables define pointer values that are in scope
 846    (i.e. they dominate) all basic blocks in the program.  Global variables
 847    always define a pointer to their "content" type because they describe a
 848    region of memory, and all memory objects in LLVM are accessed through
 849    pointers.</p>
 850
 851 <p>Global variables can be marked with <tt>unnamed_addr</tt> which indicates
 852   that the address is not significant, only the content. Constants marked
 853   like this can be merged with other constants if they have the same
 854   initializer. Note that a constant with significant address <em>can</em>
 855   be merged with a <tt>unnamed_addr</tt> constant, the result being a
 856   constant whose address is significant.</p>
 857
 858 <p>A global variable may be declared to reside in a target-specific numbered
 859    address space. For targets that support them, address spaces may affect how
 860    optimizations are performed and/or what target instructions are used to
 861    access the variable. The default address space is zero. The address space
 862    qualifier must precede any other attributes.</p>
 863
 864 <p>LLVM allows an explicit section to be specified for globals.  If the target
 865    supports it, it will emit globals to the section specified.</p>
 866
 867 <p>An explicit alignment may be specified for a global, which must be a power
 868    of 2.  If not present, or if the alignment is set to zero, the alignment of
 869    the global is set by the target to whatever it feels convenient.  If an
 870    explicit alignment is specified, the global is forced to have exactly that
 871    alignment.  Targets and optimizers are not allowed to over-align the global
 872    if the global has an assigned section.  In this case, the extra alignment
 873    could be observable: for example, code could assume that the globals are
 874    densely packed in their section and try to iterate over them as an array,
 875    alignment padding would break this iteration.</p>
 876
 877 <p>For example, the following defines a global in a numbered address space with
 878    an initializer, section, and alignment:</p>
 879
 880 <pre class="doc_code">
 881 @G = addrspace(5) constant float 1.0, section "foo", align 4
 882 </pre>
 883
 884 </div>
 885
 886
 887 <!-- ======================================================================= -->
 888 <h3>
 889   <a name="functionstructure">Functions</a>
 890 </h3>
 891
 892 <div>
 893
 894 <p>LLVM function definitions consist of the "<tt>define</tt>" keyword, an
 895    optional <a href="#linkage">linkage type</a>, an optional
 896    <a href="#visibility">visibility style</a>, an optional
 897    <a href="#callingconv">calling convention</a>,
 898    an optional <tt>unnamed_addr</tt> attribute, a return type, an optional
 899    <a href="#paramattrs">parameter attribute</a> for the return type, a function
 900    name, a (possibly empty) argument list (each with optional
 901    <a href="#paramattrs">parameter attributes</a>), optional
 902    <a href="#fnattrs">function attributes</a>, an optional section, an optional
 903    alignment, an optional <a href="#gc">garbage collector name</a>, an opening
 904    curly brace, a list of basic blocks, and a closing curly brace.</p>
 905
 906 <p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an
 907    optional <a href="#linkage">linkage type</a>, an optional
 908    <a href="#visibility">visibility style</a>, an optional
 909    <a href="#callingconv">calling convention</a>,
 910    an optional <tt>unnamed_addr</tt> attribute, a return type, an optional
 911    <a href="#paramattrs">parameter attribute</a> for the return type, a function
 912    name, a possibly empty list of arguments, an optional alignment, and an
 913    optional <a href="#gc">garbage collector name</a>.</p>
 914
 915 <p>A function definition contains a list of basic blocks, forming the CFG
 916    (Control Flow Graph) for the function.  Each basic block may optionally start
 917    with a label (giving the basic block a symbol table entry), contains a list
 918    of instructions, and ends with a <a href="#terminators">terminator</a>
 919    instruction (such as a branch or function return).</p>
 920
 921 <p>The first basic block in a function is special in two ways: it is immediately
 922    executed on entrance to the function, and it is not allowed to have
 923    predecessor basic blocks (i.e. there can not be any branches to the entry
 924    block of a function).  Because the block can have no predecessors, it also
 925    cannot have any <a href="#i_phi">PHI nodes</a>.</p>
 926
 927 <p>LLVM allows an explicit section to be specified for functions.  If the target
 928    supports it, it will emit functions to the section specified.</p>
 929
 930 <p>An explicit alignment may be specified for a function.  If not present, or if
 931    the alignment is set to zero, the alignment of the function is set by the
 932    target to whatever it feels convenient.  If an explicit alignment is
 933    specified, the function is forced to have at least that much alignment.  All
 934    alignments must be a power of 2.</p>
 935
 936 <p>If the <tt>unnamed_addr</tt> attribute is given, the address is know to not
 937    be significant and two identical functions can be merged.</p>
 938
 939 <h5>Syntax:</h5>
 940 <pre class="doc_code">
 941 define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>]
 942        [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>]
 943        &lt;ResultType&gt; @&lt;FunctionName&gt; ([argument list])
 944        [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N]
 945        [<a href="#gc">gc</a>] { ... }
 946 </pre>
 947
 948 </div>
 949
 950 <!-- ======================================================================= -->
 951 <h3>
 952   <a name="aliasstructure">Aliases</a>
 953 </h3>
 954
 955 <div>
 956
 957 <p>Aliases act as "second name" for the aliasee value (which can be either
 958    function, global variable, another alias or bitcast of global value). Aliases
 959    may have an optional <a href="#linkage">linkage type</a>, and an
 960    optional <a href="#visibility">visibility style</a>.</p>
 961
 962 <h5>Syntax:</h5>
 963 <pre class="doc_code">
 964 @&lt;Name&gt; = alias [Linkage] [Visibility] &lt;AliaseeTy&gt; @&lt;Aliasee&gt;
 965 </pre>
 966
 967 </div>
 968
 969 <!-- ======================================================================= -->
 970 <h3>
 971   <a name="namedmetadatastructure">Named Metadata</a>
 972 </h3>
 973
 974 <div>
 975
 976 <p>Named metadata is a collection of metadata. <a href="#metadata">Metadata
 977    nodes</a> (but not metadata strings) are the only valid operands for
 978    a named metadata.</p>
 979
 980 <h5>Syntax:</h5>
 981 <pre class="doc_code">
 982 ; Some unnamed metadata nodes, which are referenced by the named metadata.
 983 !0 = metadata !{metadata !"zero"}
 984 !1 = metadata !{metadata !"one"}
 985 !2 = metadata !{metadata !"two"}
 986 ; A named metadata.
 987 !name = !{!0, !1, !2}
 988 </pre>
 989
 990 </div>
 991
 992 <!-- ======================================================================= -->
 993 <h3>
 994   <a name="paramattrs">Parameter Attributes</a>
 995 </h3>
 996
 997 <div>
 998
 999 <p>The return type and each parameter of a function type may have a set of
1000    <i>parameter attributes</i> associated with them. Parameter attributes are
1001    used to communicate additional information about the result or parameters of
1002    a function. Parameter attributes are considered to be part of the function,
1003    not of the function type, so functions with different parameter attributes
1004    can have the same function type.</p>
1005
1006 <p>Parameter attributes are simple keywords that follow the type specified. If
1007    multiple parameter attributes are needed, they are space separated. For
1008    example:</p>
1009
1010 <pre class="doc_code">
1011 declare i32 @printf(i8* noalias nocapture, ...)
1012 declare i32 @atoi(i8 zeroext)
1013 declare signext i8 @returns_signed_char()
1014 </pre>
1015
1016 <p>Note that any attributes for the function result (<tt>nounwind</tt>,
1017    <tt>readonly</tt>) come immediately after the argument list.</p>
1018
1019 <p>Currently, only the following parameter attributes are defined:</p>
1020
1021 <dl>
1022   <dt><tt><b>zeroext</b></tt></dt>
1023   <dd>This indicates to the code generator that the parameter or return value
1024       should be zero-extended to the extent required by the target's ABI (which
1025       is usually 32-bits, but is 8-bits for a i1 on x86-64) by the caller (for a
1026       parameter) or the callee (for a return value).</dd>
1027
1028   <dt><tt><b>signext</b></tt></dt>
1029   <dd>This indicates to the code generator that the parameter or return value
1030       should be sign-extended to the extent required by the target's ABI (which
1031       is usually 32-bits) by the caller (for a parameter) or the callee (for a
1032       return value).</dd>
1033
1034   <dt><tt><b>inreg</b></tt></dt>
1035   <dd>This indicates that this parameter or return value should be treated in a
1036       special target-dependent fashion during while emitting code for a function
1037       call or return (usually, by putting it in a register as opposed to memory,
1038       though some targets use it to distinguish between two different kinds of
1039       registers).  Use of this attribute is target-specific.</dd>
1040
1041   <dt><tt><b><a name="byval">byval</a></b></tt></dt>
1042   <dd><p>This indicates that the pointer parameter should really be passed by
1043       value to the function.  The attribute implies that a hidden copy of the
1044       pointee
1045       is made between the caller and the callee, so the callee is unable to
1046       modify the value in the callee.  This attribute is only valid on LLVM
1047       pointer arguments.  It is generally used to pass structs and arrays by
1048       value, but is also valid on pointers to scalars.  The copy is considered
1049       to belong to the caller not the callee (for example,
1050       <tt><a href="#readonly">readonly</a></tt> functions should not write to
1051       <tt>byval</tt> parameters). This is not a valid attribute for return
1052       values.</p>
1053
1054       <p>The byval attribute also supports specifying an alignment with
1055       the align attribute.  It indicates the alignment of the stack slot to
1056       form and the known alignment of the pointer specified to the call site. If
1057       the alignment is not specified, then the code generator makes a
1058       target-specific assumption.</p></dd>
1059
1060   <dt><tt><b><a name="sret">sret</a></b></tt></dt>
1061   <dd>This indicates that the pointer parameter specifies the address of a
1062       structure that is the return value of the function in the source program.
1063       This pointer must be guaranteed by the caller to be valid: loads and
1064       stores to the structure may be assumed by the callee to not to trap.  This
1065       may only be applied to the first parameter. This is not a valid attribute
1066       for return values. </dd>
1067
1068   <dt><tt><b><a name="noalias">noalias</a></b></tt></dt>
1069   <dd>This indicates that pointer values
1070       <a href="#pointeraliasing"><i>based</i></a> on the argument or return
1071       value do not alias pointer values which are not <i>based</i> on it,
1072       ignoring certain "irrelevant" dependencies.
1073       For a call to the parent function, dependencies between memory
1074       references from before or after the call and from those during the call
1075       are "irrelevant" to the <tt>noalias</tt> keyword for the arguments and
1076       return value used in that call.
1077       The caller shares the responsibility with the callee for ensuring that
1078       these requirements are met.
1079       For further details, please see the discussion of the NoAlias response in
1080       <a href="AliasAnalysis.html#MustMayNo">alias analysis</a>.<br>
1081 <br>
1082       Note that this definition of <tt>noalias</tt> is intentionally
1083       similar to the definition of <tt>restrict</tt> in C99 for function
1084       arguments, though it is slightly weaker.
1085 <br>
1086       For function return values, C99's <tt>restrict</tt> is not meaningful,
1087       while LLVM's <tt>noalias</tt> is.
1088       </dd>
1089
1090   <dt><tt><b><a name="nocapture">nocapture</a></b></tt></dt>
1091   <dd>This indicates that the callee does not make any copies of the pointer
1092       that outlive the callee itself. This is not a valid attribute for return
1093       values.</dd>
1094
1095   <dt><tt><b><a name="nest">nest</a></b></tt></dt>
1096   <dd>This indicates that the pointer parameter can be excised using the
1097       <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid
1098       attribute for return values.</dd>
1099 </dl>
1100
1101 </div>
1102
1103 <!-- ======================================================================= -->
1104 <h3>
1105   <a name="gc">Garbage Collector Names</a>
1106 </h3>
1107
1108 <div>
1109
1110 <p>Each function may specify a garbage collector name, which is simply a
1111    string:</p>
1112
1113 <pre class="doc_code">
1114 define void @f() gc "name" { ... }
1115 </pre>
1116
1117 <p>The compiler declares the supported values of <i>name</i>. Specifying a
1118    collector which will cause the compiler to alter its output in order to
1119    support the named garbage collection algorithm.</p>
1120
1121 </div>
1122
1123 <!-- ======================================================================= -->
1124 <h3>
1125   <a name="fnattrs">Function Attributes</a>
1126 </h3>
1127
1128 <div>
1129
1130 <p>Function attributes are set to communicate additional information about a
1131    function. Function attributes are considered to be part of the function, not
1132    of the function type, so functions with different parameter attributes can
1133    have the same function type.</p>
1134
1135 <p>Function attributes are simple keywords that follow the type specified. If
1136    multiple attributes are needed, they are space separated. For example:</p>
1137
1138 <pre class="doc_code">
1139 define void @f() noinline { ... }
1140 define void @f() alwaysinline { ... }
1141 define void @f() alwaysinline optsize { ... }
1142 define void @f() optsize { ... }
1143 </pre>
1144
1145 <dl>
1146   <dt><tt><b>alignstack(&lt;<em>n</em>&gt;)</b></tt></dt>
1147   <dd>This attribute indicates that, when emitting the prologue and epilogue,
1148       the backend should forcibly align the stack pointer. Specify the
1149       desired alignment, which must be a power of two, in parentheses.
1150
1151   <dt><tt><b>alwaysinline</b></tt></dt>
1152   <dd>This attribute indicates that the inliner should attempt to inline this
1153       function into callers whenever possible, ignoring any active inlining size
1154       threshold for this caller.</dd>
1155
1156   <dt><tt><b>nonlazybind</b></tt></dt>
1157   <dd>This attribute suppresses lazy symbol binding for the function. This
1158       may make calls to the function faster, at the cost of extra program
1159       startup time if the function is not called during program startup.</dd>
1160
1161   <dt><tt><b>inlinehint</b></tt></dt>
1162   <dd>This attribute indicates that the source code contained a hint that inlining
1163       this function is desirable (such as the "inline" keyword in C/C++).  It
1164       is just a hint; it imposes no requirements on the inliner.</dd>
1165
1166   <dt><tt><b>naked</b></tt></dt>
1167   <dd>This attribute disables prologue / epilogue emission for the function.
1168       This can have very system-specific consequences.</dd>
1169
1170   <dt><tt><b>noimplicitfloat</b></tt></dt>
1171   <dd>This attributes disables implicit floating point instructions.</dd>
1172
1173   <dt><tt><b>noinline</b></tt></dt>
1174   <dd>This attribute indicates that the inliner should never inline this
1175       function in any situation. This attribute may not be used together with
1176       the <tt>alwaysinline</tt> attribute.</dd>
1177
1178   <dt><tt><b>noredzone</b></tt></dt>
1179   <dd>This attribute indicates that the code generator should not use a red
1180       zone, even if the target-specific ABI normally permits it.</dd>
1181
1182   <dt><tt><b>noreturn</b></tt></dt>
1183   <dd>This function attribute indicates that the function never returns
1184       normally.  This produces undefined behavior at runtime if the function
1185       ever does dynamically return.</dd>
1186
1187   <dt><tt><b>nounwind</b></tt></dt>
1188   <dd>This function attribute indicates that the function never returns with an
1189       unwind or exceptional control flow.  If the function does unwind, its
1190       runtime behavior is undefined.</dd>
1191
1192   <dt><tt><b>optsize</b></tt></dt>
1193   <dd>This attribute suggests that optimization passes and code generator passes
1194       make choices that keep the code size of this function low, and otherwise
1195       do optimizations specifically to reduce code size.</dd>
1196
1197   <dt><tt><b>readnone</b></tt></dt>
1198   <dd>This attribute indicates that the function computes its result (or decides
1199       to unwind an exception) based strictly on its arguments, without
1200       dereferencing any pointer arguments or otherwise accessing any mutable
1201       state (e.g. memory, control registers, etc) visible to caller functions.
1202       It does not write through any pointer arguments
1203       (including <tt><a href="#byval">byval</a></tt> arguments) and never
1204       changes any state visible to callers.  This means that it cannot unwind
1205       exceptions by calling the <tt>C++</tt> exception throwing methods, but
1206       could use the <tt>unwind</tt> instruction.</dd>
1207
1208   <dt><tt><b><a name="readonly">readonly</a></b></tt></dt>
1209   <dd>This attribute indicates that the function does not write through any
1210       pointer arguments (including <tt><a href="#byval">byval</a></tt>
1211       arguments) or otherwise modify any state (e.g. memory, control registers,
1212       etc) visible to caller functions.  It may dereference pointer arguments
1213       and read state that may be set in the caller.  A readonly function always
1214       returns the same value (or unwinds an exception identically) when called
1215       with the same set of arguments and global state.  It cannot unwind an
1216       exception by calling the <tt>C++</tt> exception throwing methods, but may
1217       use the <tt>unwind</tt> instruction.</dd>
1218
1219   <dt><tt><b><a name="ssp">ssp</a></b></tt></dt>
1220   <dd>This attribute indicates that the function should emit a stack smashing
1221       protector. It is in the form of a "canary"&mdash;a random value placed on
1222       the stack before the local variables that's checked upon return from the
1223       function to see if it has been overwritten. A heuristic is used to
1224       determine if a function needs stack protectors or not.<br>
1225 <br>
1226       If a function that has an <tt>ssp</tt> attribute is inlined into a
1227       function that doesn't have an <tt>ssp</tt> attribute, then the resulting
1228       function will have an <tt>ssp</tt> attribute.</dd>
1229
1230   <dt><tt><b>sspreq</b></tt></dt>
1231   <dd>This attribute indicates that the function should <em>always</em> emit a
1232       stack smashing protector. This overrides
1233       the <tt><a href="#ssp">ssp</a></tt> function attribute.<br>
1234 <br>
1235       If a function that has an <tt>sspreq</tt> attribute is inlined into a
1236       function that doesn't have an <tt>sspreq</tt> attribute or which has
1237       an <tt>ssp</tt> attribute, then the resulting function will have
1238       an <tt>sspreq</tt> attribute.</dd>
1239
1240   <dt><tt><b><a name="uwtable">uwtable</a></b></tt></dt>
1241   <dd>This attribute indicates that the ABI being targeted requires that
1242       an unwind table entry be produce for this function even if we can
1243       show that no exceptions passes by it. This is normally the case for
1244       the ELF x86-64 abi, but it can be disabled for some compilation
1245       units.</dd>
1246
1247   <dt><tt><b><a name="returns_twice">returns_twice</a></b></tt></dt>
1248   <dd>This attribute indicates that this function can return
1249   twice. The C <code>setjmp</code> is an example of such a function.
1250   The compiler disables some optimizations (like tail calls) in the caller of
1251   these functions.</dd>
1252 </dl>
1253
1254 </div>
1255
1256 <!-- ======================================================================= -->
1257 <h3>
1258   <a name="moduleasm">Module-Level Inline Assembly</a>
1259 </h3>
1260
1261 <div>
1262
1263 <p>Modules may contain "module-level inline asm" blocks, which corresponds to
1264    the GCC "file scope inline asm" blocks.  These blocks are internally
1265    concatenated by LLVM and treated as a single unit, but may be separated in
1266    the <tt>.ll</tt> file if desired.  The syntax is very simple:</p>
1267
1268 <pre class="doc_code">
1269 module asm "inline asm code goes here"
1270 module asm "more can go here"
1271 </pre>
1272
1273 <p>The strings can contain any character by escaping non-printable characters.
1274    The escape sequence used is simply "\xx" where "xx" is the two digit hex code
1275    for the number.</p>
1276
1277 <p>The inline asm code is simply printed to the machine code .s file when
1278    assembly code is generated.</p>
1279
1280 </div>
1281
1282 <!-- ======================================================================= -->
1283 <h3>
1284   <a name="datalayout">Data Layout</a>
1285 </h3>
1286
1287 <div>
1288
1289 <p>A module may specify a target specific data layout string that specifies how
1290    data is to be laid out in memory. The syntax for the data layout is
1291    simply:</p>
1292
1293 <pre class="doc_code">
1294 target datalayout = "<i>layout specification</i>"
1295 </pre>
1296
1297 <p>The <i>layout specification</i> consists of a list of specifications
1298    separated by the minus sign character ('-').  Each specification starts with
1299    a letter and may include other information after the letter to define some
1300    aspect of the data layout.  The specifications accepted are as follows:</p>
1301
1302 <dl>
1303   <dt><tt>E</tt></dt>
1304   <dd>Specifies that the target lays out data in big-endian form. That is, the
1305       bits with the most significance have the lowest address location.</dd>
1306
1307   <dt><tt>e</tt></dt>
1308   <dd>Specifies that the target lays out data in little-endian form. That is,
1309       the bits with the least significance have the lowest address
1310       location.</dd>
1311
1312   <dt><tt>S<i>size</i></tt></dt>
1313   <dd>Specifies the natural alignment of the stack in bits. Alignment promotion
1314       of stack variables is limited to the natural stack alignment to avoid
1315       dynamic stack realignment. The stack alignment must be a multiple of
1316       8-bits. If omitted, the natural stack alignment defaults to "unspecified",
1317       which does not prevent any alignment promotions.</dd>
1318
1319   <dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1320   <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and
1321       <i>preferred</i> alignments. All sizes are in bits. Specifying
1322       the <i>pref</i> alignment is optional. If omitted, the
1323       preceding <tt>:</tt> should be omitted too.</dd>
1324
1325   <dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1326   <dd>This specifies the alignment for an integer type of a given bit
1327       <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd>
1328
1329   <dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1330   <dd>This specifies the alignment for a vector type of a given bit
1331       <i>size</i>.</dd>
1332
1333   <dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1334   <dd>This specifies the alignment for a floating point type of a given bit
1335       <i>size</i>. Only values of <i>size</i> that are supported by the target
1336       will work.  32 (float) and 64 (double) are supported on all targets;
1337       80 or 128 (different flavors of long double) are also supported on some
1338       targets.
1339
1340   <dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1341   <dd>This specifies the alignment for an aggregate type of a given bit
1342       <i>size</i>.</dd>
1343
1344   <dt><tt>s<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1345   <dd>This specifies the alignment for a stack object of a given bit
1346       <i>size</i>.</dd>
1347
1348   <dt><tt>n<i>size1</i>:<i>size2</i>:<i>size3</i>...</tt></dt>
1349   <dd>This specifies a set of native integer widths for the target CPU
1350       in bits.  For example, it might contain "n32" for 32-bit PowerPC,
1351       "n32:64" for PowerPC 64, or "n8:16:32:64" for X86-64.  Elements of
1352       this set are considered to support most general arithmetic
1353       operations efficiently.</dd>
1354 </dl>
1355
1356 <p>When constructing the data layout for a given target, LLVM starts with a
1357    default set of specifications which are then (possibly) overridden by the
1358    specifications in the <tt>datalayout</tt> keyword. The default specifications
1359    are given in this list:</p>
1360
1361 <ul>
1362   <li><tt>E</tt> - big endian</li>
1363   <li><tt>p:64:64:64</tt> - 64-bit pointers with 64-bit alignment</li>
1364   <li><tt>i1:8:8</tt> - i1 is 8-bit (byte) aligned</li>
1365   <li><tt>i8:8:8</tt> - i8 is 8-bit (byte) aligned</li>
1366   <li><tt>i16:16:16</tt> - i16 is 16-bit aligned</li>
1367   <li><tt>i32:32:32</tt> - i32 is 32-bit aligned</li>
1368   <li><tt>i64:32:64</tt> - i64 has ABI alignment of 32-bits but preferred
1369   alignment of 64-bits</li>
1370   <li><tt>f32:32:32</tt> - float is 32-bit aligned</li>
1371   <li><tt>f64:64:64</tt> - double is 64-bit aligned</li>
1372   <li><tt>v64:64:64</tt> - 64-bit vector is 64-bit aligned</li>
1373   <li><tt>v128:128:128</tt> - 128-bit vector is 128-bit aligned</li>
1374   <li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li>
1375   <li><tt>s0:64:64</tt> - stack objects are 64-bit aligned</li>
1376 </ul>
1377
1378 <p>When LLVM is determining the alignment for a given type, it uses the
1379    following rules:</p>
1380
1381 <ol>
1382   <li>If the type sought is an exact match for one of the specifications, that
1383       specification is used.</li>
1384
1385   <li>If no match is found, and the type sought is an integer type, then the
1386       smallest integer type that is larger than the bitwidth of the sought type
1387       is used. If none of the specifications are larger than the bitwidth then
1388       the the largest integer type is used. For example, given the default
1389       specifications above, the i7 type will use the alignment of i8 (next
1390       largest) while both i65 and i256 will use the alignment of i64 (largest
1391       specified).</li>
1392
1393   <li>If no match is found, and the type sought is a vector type, then the
1394       largest vector type that is smaller than the sought vector type will be
1395       used as a fall back.  This happens because &lt;128 x double&gt; can be
1396       implemented in terms of 64 &lt;2 x double&gt;, for example.</li>
1397 </ol>
1398
1399 <p>The function of the data layout string may not be what you expect.  Notably,
1400    this is not a specification from the frontend of what alignment the code
1401    generator should use.</p>
1402
1403 <p>Instead, if specified, the target data layout is required to match what the
1404    ultimate <em>code generator</em> expects.  This string is used by the
1405    mid-level optimizers to
1406    improve code, and this only works if it matches what the ultimate code
1407    generator uses.  If you would like to generate IR that does not embed this
1408    target-specific detail into the IR, then you don't have to specify the
1409    string.  This will disable some optimizations that require precise layout
1410    information, but this also prevents those optimizations from introducing
1411    target specificity into the IR.</p>
1412
1413
1414
1415 </div>
1416
1417 <!-- ======================================================================= -->
1418 <h3>
1419   <a name="pointeraliasing">Pointer Aliasing Rules</a>
1420 </h3>
1421
1422 <div>
1423
1424 <p>Any memory access must be done through a pointer value associated
1425 with an address range of the memory access, otherwise the behavior
1426 is undefined. Pointer values are associated with address ranges
1427 according to the following rules:</p>
1428
1429 <ul>
1430   <li>A pointer value is associated with the addresses associated with
1431       any value it is <i>based</i> on.
1432   <li>An address of a global variable is associated with the address
1433       range of the variable's storage.</li>
1434   <li>The result value of an allocation instruction is associated with
1435       the address range of the allocated storage.</li>
1436   <li>A null pointer in the default address-space is associated with
1437       no address.</li>
1438   <li>An integer constant other than zero or a pointer value returned
1439       from a function not defined within LLVM may be associated with address
1440       ranges allocated through mechanisms other than those provided by
1441       LLVM. Such ranges shall not overlap with any ranges of addresses
1442       allocated by mechanisms provided by LLVM.</li>
1443 </ul>
1444
1445 <p>A pointer value is <i>based</i> on another pointer value according
1446    to the following rules:</p>
1447
1448 <ul>
1449   <li>A pointer value formed from a
1450       <tt><a href="#i_getelementptr">getelementptr</a></tt> operation
1451       is <i>based</i> on the first operand of the <tt>getelementptr</tt>.</li>
1452   <li>The result value of a
1453       <tt><a href="#i_bitcast">bitcast</a></tt> is <i>based</i> on the operand
1454       of the <tt>bitcast</tt>.</li>
1455   <li>A pointer value formed by an
1456       <tt><a href="#i_inttoptr">inttoptr</a></tt> is <i>based</i> on all
1457       pointer values that contribute (directly or indirectly) to the
1458       computation of the pointer's value.</li>
1459   <li>The "<i>based</i> on" relationship is transitive.</li>
1460 </ul>
1461
1462 <p>Note that this definition of <i>"based"</i> is intentionally
1463    similar to the definition of <i>"based"</i> in C99, though it is
1464    slightly weaker.</p>
1465
1466 <p>LLVM IR does not associate types with memory. The result type of a
1467 <tt><a href="#i_load">load</a></tt> merely indicates the size and
1468 alignment of the memory from which to load, as well as the
1469 interpretation of the value. The first operand type of a
1470 <tt><a href="#i_store">store</a></tt> similarly only indicates the size
1471 and alignment of the store.</p>
1472
1473 <p>Consequently, type-based alias analysis, aka TBAA, aka
1474 <tt>-fstrict-aliasing</tt>, is not applicable to general unadorned
1475 LLVM IR. <a href="#metadata">Metadata</a> may be used to encode
1476 additional information which specialized optimization passes may use
1477 to implement type-based alias analysis.</p>
1478
1479 </div>
1480
1481 <!-- ======================================================================= -->
1482 <h3>
1483   <a name="volatile">Volatile Memory Accesses</a>
1484 </h3>
1485
1486 <div>
1487
1488 <p>Certain memory accesses, such as <a href="#i_load"><tt>load</tt></a>s, <a
1489 href="#i_store"><tt>store</tt></a>s, and <a
1490 href="#int_memcpy"><tt>llvm.memcpy</tt></a>s may be marked <tt>volatile</tt>.
1491 The optimizers must not change the number of volatile operations or change their
1492 order of execution relative to other volatile operations.  The optimizers
1493 <i>may</i> change the order of volatile operations relative to non-volatile
1494 operations.  This is not Java's "volatile" and has no cross-thread
1495 synchronization behavior.</p>
1496
1497 </div>
1498
1499 <!-- ======================================================================= -->
1500 <h3>
1501   <a name="memmodel">Memory Model for Concurrent Operations</a>
1502 </h3>
1503
1504 <div>
1505
1506 <p>The LLVM IR does not define any way to start parallel threads of execution
1507 or to register signal handlers. Nonetheless, there are platform-specific
1508 ways to create them, and we define LLVM IR's behavior in their presence. This
1509 model is inspired by the C++0x memory model.</p>
1510
1511 <p>For a more informal introduction to this model, see the
1512 <a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.
1513
1514 <p>We define a <i>happens-before</i> partial order as the least partial order
1515 that</p>
1516 <ul>
1517   <li>Is a superset of single-thread program order, and</li>
1518   <li>When a <i>synchronizes-with</i> <tt>b</tt>, includes an edge from
1519       <tt>a</tt> to <tt>b</tt>. <i>Synchronizes-with</i> pairs are introduced
1520       by platform-specific techniques, like pthread locks, thread
1521       creation, thread joining, etc., and by atomic instructions.
1522       (See also <a href="#ordering">Atomic Memory Ordering Constraints</a>).
1523       </li>
1524 </ul>
1525
1526 <p>Note that program order does not introduce <i>happens-before</i> edges
1527 between a thread and signals executing inside that thread.</p>
1528
1529 <p>Every (defined) read operation (load instructions, memcpy, atomic
1530 loads/read-modify-writes, etc.) <var>R</var> reads a series of bytes written by
1531 (defined) write operations (store instructions, atomic
1532 stores/read-modify-writes, memcpy, etc.). For the purposes of this section,
1533 initialized globals are considered to have a write of the initializer which is
1534 atomic and happens before any other read or write of the memory in question.
1535 For each byte of a read <var>R</var>, <var>R<sub>byte</sub></var> may see
1536 any write to the same byte, except:</p>
1537
1538 <ul>
1539   <li>If <var>write<sub>1</sub></var> happens before
1540       <var>write<sub>2</sub></var>, and <var>write<sub>2</sub></var> happens
1541       before <var>R<sub>byte</sub></var>, then <var>R<sub>byte</sub></var>
1542       does not see <var>write<sub>1</sub></var>.
1543   <li>If <var>R<sub>byte</sub></var> happens before
1544       <var>write<sub>3</sub></var>, then <var>R<sub>byte</sub></var> does not
1545       see <var>write<sub>3</sub></var>.
1546 </ul>
1547
1548 <p>Given that definition, <var>R<sub>byte</sub></var> is defined as follows:
1549 <ul>
1550   <li>If <var>R</var> is volatile, the result is target-dependent. (Volatile
1551       is supposed to give guarantees which can support
1552       <code>sig_atomic_t</code> in C/C++, and may be used for accesses to
1553       addresses which do not behave like normal memory.  It does not generally
1554       provide cross-thread synchronization.)
1555   <li>Otherwise, if there is no write to the same byte that happens before
1556     <var>R<sub>byte</sub></var>, <var>R<sub>byte</sub></var> returns
1557     <tt>undef</tt> for that byte.
1558   <li>Otherwise, if <var>R<sub>byte</sub></var> may see exactly one write,
1559       <var>R<sub>byte</sub></var> returns the value written by that
1560       write.</li>
1561   <li>Otherwise, if <var>R</var> is atomic, and all the writes
1562       <var>R<sub>byte</sub></var> may see are atomic, it chooses one of the
1563       values written.  See the <a href="#ordering">Atomic Memory Ordering
1564       Constraints</a> section for additional constraints on how the choice
1565       is made.
1566   <li>Otherwise <var>R<sub>byte</sub></var> returns <tt>undef</tt>.</li>
1567 </ul>
1568
1569 <p><var>R</var> returns the value composed of the series of bytes it read.
1570 This implies that some bytes within the value may be <tt>undef</tt>
1571 <b>without</b> the entire value being <tt>undef</tt>. Note that this only
1572 defines the semantics of the operation; it doesn't mean that targets will
1573 emit more than one instruction to read the series of bytes.</p>
1574
1575 <p>Note that in cases where none of the atomic intrinsics are used, this model
1576 places only one restriction on IR transformations on top of what is required
1577 for single-threaded execution: introducing a store to a byte which might not
1578 otherwise be stored is not allowed in general.  (Specifically, in the case
1579 where another thread might write to and read from an address, introducing a
1580 store can change a load that may see exactly one write into a load that may
1581 see multiple writes.)</p>
1582
1583 <!-- FIXME: This model assumes all targets where concurrency is relevant have
1584 a byte-size store which doesn't affect adjacent bytes.  As far as I can tell,
1585 none of the backends currently in the tree fall into this category; however,
1586 there might be targets which care.  If there are, we want a paragraph
1587 like the following:
1588
1589 Targets may specify that stores narrower than a certain width are not
1590 available; on such a target, for the purposes of this model, treat any
1591 non-atomic write with an alignment or width less than the minimum width
1592 as if it writes to the relevant surrounding bytes.
1593 -->
1594
1595 </div>
1596
1597 <!-- ======================================================================= -->
1598 <h3>
1599       <a name="ordering">Atomic Memory Ordering Constraints</a>
1600 </h3>
1601
1602 <div>
1603
1604 <p>Atomic instructions (<a href="#i_cmpxchg"><code>cmpxchg</code></a>,
1605 <a href="#i_atomicrmw"><code>atomicrmw</code></a>,
1606 <a href="#i_fence"><code>fence</code></a>,
1607 <a href="#i_load"><code>atomic load</code></a>, and
1608 <a href="#i_store"><code>atomic store</code></a>) take an ordering parameter
1609 that determines which other atomic instructions on the same address they
1610 <i>synchronize with</i>.  These semantics are borrowed from Java and C++0x,
1611 but are somewhat more colloquial. If these descriptions aren't precise enough,
1612 check those specs (see spec references in the
1613 <a href="Atomic.html#introduction">atomics guide</a>).
1614 <a href="#i_fence"><code>fence</code></a> instructions
1615 treat these orderings somewhat differently since they don't take an address.
1616 See that instruction's documentation for details.</p>
1617
1618 <p>For a simpler introduction to the ordering constraints, see the
1619 <a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.</p>
1620
1621 <dl>
1622 <dt><code>unordered</code></dt>
1623 <dd>The set of values that can be read is governed by the happens-before
1624 partial order. A value cannot be read unless some operation wrote it.
1625 This is intended to provide a guarantee strong enough to model Java's
1626 non-volatile shared variables.  This ordering cannot be specified for
1627 read-modify-write operations; it is not strong enough to make them atomic
1628 in any interesting way.</dd>
1629 <dt><code>monotonic</code></dt>
1630 <dd>In addition to the guarantees of <code>unordered</code>, there is a single
1631 total order for modifications by <code>monotonic</code> operations on each
1632 address. All modification orders must be compatible with the happens-before
1633 order. There is no guarantee that the modification orders can be combined to
1634 a global total order for the whole program (and this often will not be
1635 possible). The read in an atomic read-modify-write operation
1636 (<a href="#i_cmpxchg"><code>cmpxchg</code></a> and
1637 <a href="#i_atomicrmw"><code>atomicrmw</code></a>)
1638 reads the value in the modification order immediately before the value it
1639 writes. If one atomic read happens before another atomic read of the same
1640 address, the later read must see the same value or a later value in the
1641 address's modification order. This disallows reordering of
1642 <code>monotonic</code> (or stronger) operations on the same address. If an
1643 address is written <code>monotonic</code>ally by one thread, and other threads
1644 <code>monotonic</code>ally read that address repeatedly, the other threads must
1645 eventually see the write. This corresponds to the C++0x/C1x
1646 <code>memory_order_relaxed</code>.</dd>
1647 <dt><code>acquire</code></dt>
1648 <dd>In addition to the guarantees of <code>monotonic</code>,
1649 a <i>synchronizes-with</i> edge may be formed with a <code>release</code>
1650 operation. This is intended to model C++'s <code>memory_order_acquire</code>.</dd>
1651 <dt><code>release</code></dt>
1652 <dd>In addition to the guarantees of <code>monotonic</code>, if this operation
1653 writes a value which is subsequently read by an <code>acquire</code> operation,
1654 it <i>synchronizes-with</i> that operation.  (This isn't a complete
1655 description; see the C++0x definition of a release sequence.) This corresponds
1656 to the C++0x/C1x <code>memory_order_release</code>.</dd>
1657 <dt><code>acq_rel</code> (acquire+release)</dt><dd>Acts as both an
1658 <code>acquire</code> and <code>release</code> operation on its address.
1659 This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>.</dd>
1660 <dt><code>seq_cst</code> (sequentially consistent)</dt><dd>
1661 <dd>In addition to the guarantees of <code>acq_rel</code>
1662 (<code>acquire</code> for an operation which only reads, <code>release</code>
1663 for an operation which only writes), there is a global total order on all
1664 sequentially-consistent operations on all addresses, which is consistent with
1665 the <i>happens-before</i> partial order and with the modification orders of
1666 all the affected addresses. Each sequentially-consistent read sees the last
1667 preceding write to the same address in this global order. This corresponds
1668 to the C++0x/C1x <code>memory_order_seq_cst</code> and Java volatile.</dd>
1669 </dl>
1670
1671 <p id="singlethread">If an atomic operation is marked <code>singlethread</code>,
1672 it only <i>synchronizes with</i> or participates in modification and seq_cst
1673 total orderings with other operations running in the same thread (for example,
1674 in signal handlers).</p>
1675
1676 </div>
1677
1678 </div>
1679
1680 <!-- *********************************************************************** -->
1681 <h2><a name="typesystem">Type System</a></h2>
1682 <!-- *********************************************************************** -->
1683
1684 <div>
1685
1686 <p>The LLVM type system is one of the most important features of the
1687    intermediate representation.  Being typed enables a number of optimizations
1688    to be performed on the intermediate representation directly, without having
1689    to do extra analyses on the side before the transformation.  A strong type
1690    system makes it easier to read the generated code and enables novel analyses
1691    and transformations that are not feasible to perform on normal three address
1692    code representations.</p>
1693
1694 <!-- ======================================================================= -->
1695 <h3>
1696   <a name="t_classifications">Type Classifications</a>
1697 </h3>
1698
1699 <div>
1700
1701 <p>The types fall into a few useful classifications:</p>
1702
1703 <table border="1" cellspacing="0" cellpadding="4">
1704   <tbody>
1705     <tr><th>Classification</th><th>Types</th></tr>
1706     <tr>
1707       <td><a href="#t_integer">integer</a></td>
1708       <td><tt>i1, i2, i3, ... i8, ... i16, ... i32, ... i64, ... </tt></td>
1709     </tr>
1710     <tr>
1711       <td><a href="#t_floating">floating point</a></td>
1712       <td><tt>float, double, x86_fp80, fp128, ppc_fp128</tt></td>
1713     </tr>
1714     <tr>
1715       <td><a name="t_firstclass">first class</a></td>
1716       <td><a href="#t_integer">integer</a>,
1717           <a href="#t_floating">floating point</a>,
1718           <a href="#t_pointer">pointer</a>,
1719           <a href="#t_vector">vector</a>,
1720           <a href="#t_struct">structure</a>,
1721           <a href="#t_array">array</a>,
1722           <a href="#t_label">label</a>,
1723           <a href="#t_metadata">metadata</a>.
1724       </td>
1725     </tr>
1726     <tr>
1727       <td><a href="#t_primitive">primitive</a></td>
1728       <td><a href="#t_label">label</a>,
1729           <a href="#t_void">void</a>,
1730           <a href="#t_integer">integer</a>,
1731           <a href="#t_floating">floating point</a>,
1732           <a href="#t_x86mmx">x86mmx</a>,
1733           <a href="#t_metadata">metadata</a>.</td>
1734     </tr>
1735     <tr>
1736       <td><a href="#t_derived">derived</a></td>
1737       <td><a href="#t_array">array</a>,
1738           <a href="#t_function">function</a>,
1739           <a href="#t_pointer">pointer</a>,
1740           <a href="#t_struct">structure</a>,
1741           <a href="#t_vector">vector</a>,
1742           <a href="#t_opaque">opaque</a>.
1743       </td>
1744     </tr>
1745   </tbody>
1746 </table>
1747
1748 <p>The <a href="#t_firstclass">first class</a> types are perhaps the most
1749    important.  Values of these types are the only ones which can be produced by
1750    instructions.</p>
1751
1752 </div>
1753
1754 <!-- ======================================================================= -->
1755 <h3>
1756   <a name="t_primitive">Primitive Types</a>
1757 </h3>
1758
1759 <div>
1760
1761 <p>The primitive types are the fundamental building blocks of the LLVM
1762    system.</p>
1763
1764 <!-- _______________________________________________________________________ -->
1765 <h4>
1766   <a name="t_integer">Integer Type</a>
1767 </h4>
1768
1769 <div>
1770
1771 <h5>Overview:</h5>
1772 <p>The integer type is a very simple type that simply specifies an arbitrary
1773    bit width for the integer type desired. Any bit width from 1 bit to
1774    2<sup>23</sup>-1 (about 8 million) can be specified.</p>
1775
1776 <h5>Syntax:</h5>
1777 <pre>
1778   iN
1779 </pre>
1780
1781 <p>The number of bits the integer will occupy is specified by the <tt>N</tt>
1782    value.</p>
1783
1784 <h5>Examples:</h5>
1785 <table class="layout">
1786   <tr class="layout">
1787     <td class="left"><tt>i1</tt></td>
1788     <td class="left">a single-bit integer.</td>
1789   </tr>
1790   <tr class="layout">
1791     <td class="left"><tt>i32</tt></td>
1792     <td class="left">a 32-bit integer.</td>
1793   </tr>
1794   <tr class="layout">
1795     <td class="left"><tt>i1942652</tt></td>
1796     <td class="left">a really big integer of over 1 million bits.</td>
1797   </tr>
1798 </table>
1799
1800 </div>
1801
1802 <!-- _______________________________________________________________________ -->
1803 <h4>
1804   <a name="t_floating">Floating Point Types</a>
1805 </h4>
1806
1807 <div>
1808
1809 <table>
1810   <tbody>
1811     <tr><th>Type</th><th>Description</th></tr>
1812     <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
1813     <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
1814     <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr>
1815     <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr>
1816     <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr>
1817   </tbody>
1818 </table>
1819
1820 </div>
1821
1822 <!-- _______________________________________________________________________ -->
1823 <h4>
1824   <a name="t_x86mmx">X86mmx Type</a>
1825 </h4>
1826
1827 <div>
1828
1829 <h5>Overview:</h5>
1830 <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>
1831
1832 <h5>Syntax:</h5>
1833 <pre>
1834   x86mmx
1835 </pre>
1836
1837 </div>
1838
1839 <!-- _______________________________________________________________________ -->
1840 <h4>
1841   <a name="t_void">Void Type</a>
1842 </h4>
1843
1844 <div>
1845
1846 <h5>Overview:</h5>
1847 <p>The void type does not represent any value and has no size.</p>
1848
1849 <h5>Syntax:</h5>
1850 <pre>
1851   void
1852 </pre>
1853
1854 </div>
1855
1856 <!-- _______________________________________________________________________ -->
1857 <h4>
1858   <a name="t_label">Label Type</a>
1859 </h4>
1860
1861 <div>
1862
1863 <h5>Overview:</h5>
1864 <p>The label type represents code labels.</p>
1865
1866 <h5>Syntax:</h5>
1867 <pre>
1868   label
1869 </pre>
1870
1871 </div>
1872
1873 <!-- _______________________________________________________________________ -->
1874 <h4>
1875   <a name="t_metadata">Metadata Type</a>
1876 </h4>
1877
1878 <div>
1879
1880 <h5>Overview:</h5>
1881 <p>The metadata type represents embedded metadata. No derived types may be
1882    created from metadata except for <a href="#t_function">function</a>
1883    arguments.
1884
1885 <h5>Syntax:</h5>
1886 <pre>
1887   metadata
1888 </pre>
1889
1890 </div>
1891
1892 </div>
1893
1894 <!-- ======================================================================= -->
1895 <h3>
1896   <a name="t_derived">Derived Types</a>
1897 </h3>
1898
1899 <div>
1900
1901 <p>The real power in LLVM comes from the derived types in the system.  This is
1902    what allows a programmer to represent arrays, functions, pointers, and other
1903    useful types.  Each of these types contain one or more element types which
1904    may be a primitive type, or another derived type.  For example, it is
1905    possible to have a two dimensional array, using an array as the element type
1906    of another array.</p>
1907
1908 <!-- _______________________________________________________________________ -->
1909 <h4>
1910   <a name="t_aggregate">Aggregate Types</a>
1911 </h4>
1912
1913 <div>
1914
1915 <p>Aggregate Types are a subset of derived types that can contain multiple
1916   member types. <a href="#t_array">Arrays</a>,
1917   <a href="#t_struct">structs</a>, and <a href="#t_vector">vectors</a> are
1918   aggregate types.</p>
1919
1920 </div>
1921
1922 <!-- _______________________________________________________________________ -->
1923 <h4>
1924   <a name="t_array">Array Type</a>
1925 </h4>
1926
1927 <div>
1928
1929 <h5>Overview:</h5>
1930 <p>The array type is a very simple derived type that arranges elements
1931    sequentially in memory.  The array type requires a size (number of elements)
1932    and an underlying data type.</p>
1933
1934 <h5>Syntax:</h5>
1935 <pre>
1936   [&lt;# elements&gt; x &lt;elementtype&gt;]
1937 </pre>
1938
1939 <p>The number of elements is a constant integer value; <tt>elementtype</tt> may
1940    be any type with a size.</p>
1941
1942 <h5>Examples:</h5>
1943 <table class="layout">
1944   <tr class="layout">
1945     <td class="left"><tt>[40 x i32]</tt></td>
1946     <td class="left">Array of 40 32-bit integer values.</td>
1947   </tr>
1948   <tr class="layout">
1949     <td class="left"><tt>[41 x i32]</tt></td>
1950     <td class="left">Array of 41 32-bit integer values.</td>
1951   </tr>
1952   <tr class="layout">
1953     <td class="left"><tt>[4 x i8]</tt></td>
1954     <td class="left">Array of 4 8-bit integer values.</td>
1955   </tr>
1956 </table>
1957 <p>Here are some examples of multidimensional arrays:</p>
1958 <table class="layout">
1959   <tr class="layout">
1960     <td class="left"><tt>[3 x [4 x i32]]</tt></td>
1961     <td class="left">3x4 array of 32-bit integer values.</td>
1962   </tr>
1963   <tr class="layout">
1964     <td class="left"><tt>[12 x [10 x float]]</tt></td>
1965     <td class="left">12x10 array of single precision floating point values.</td>
1966   </tr>
1967   <tr class="layout">
1968     <td class="left"><tt>[2 x [3 x [4 x i16]]]</tt></td>
1969     <td class="left">2x3x4 array of 16-bit integer  values.</td>
1970   </tr>
1971 </table>
1972
1973 <p>There is no restriction on indexing beyond the end of the array implied by
1974    a static type (though there are restrictions on indexing beyond the bounds
1975    of an allocated object in some cases). This means that single-dimension
1976    'variable sized array' addressing can be implemented in LLVM with a zero
1977    length array type. An implementation of 'pascal style arrays' in LLVM could
1978    use the type "<tt>{ i32, [0 x float]}</tt>", for example.</p>
1979
1980 </div>
1981
1982 <!-- _______________________________________________________________________ -->
1983 <h4>
1984   <a name="t_function">Function Type</a>
1985 </h4>
1986
1987 <div>
1988
1989 <h5>Overview:</h5>
1990 <p>The function type can be thought of as a function signature.  It consists of
1991    a return type and a list of formal parameter types. The return type of a
1992    function type is a first class type or a void type.</p>
1993
1994 <h5>Syntax:</h5>
1995 <pre>
1996   &lt;returntype&gt; (&lt;parameter list&gt;)
1997 </pre>
1998
1999 <p>...where '<tt>&lt;parameter list&gt;</tt>' is a comma-separated list of type
2000    specifiers.  Optionally, the parameter list may include a type <tt>...</tt>,
2001    which indicates that the function takes a variable number of arguments.
2002    Variable argument functions can access their arguments with
2003    the <a href="#int_varargs">variable argument handling intrinsic</a>
2004    functions.  '<tt>&lt;returntype&gt;</tt>' is any type except
2005    <a href="#t_label">label</a>.</p>
2006
2007 <h5>Examples:</h5>
2008 <table class="layout">
2009   <tr class="layout">
2010     <td class="left"><tt>i32 (i32)</tt></td>
2011     <td class="left">function taking an <tt>i32</tt>, returning an <tt>i32</tt>
2012     </td>
2013   </tr><tr class="layout">
2014     <td class="left"><tt>float&nbsp;(i16,&nbsp;i32&nbsp;*)&nbsp;*
2015     </tt></td>
2016     <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes
2017       an <tt>i16</tt> and a <a href="#t_pointer">pointer</a> to <tt>i32</tt>,
2018       returning <tt>float</tt>.
2019     </td>
2020   </tr><tr class="layout">
2021     <td class="left"><tt>i32 (i8*, ...)</tt></td>
2022     <td class="left">A vararg function that takes at least one
2023       <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C),
2024       which returns an integer.  This is the signature for <tt>printf</tt> in
2025       LLVM.
2026     </td>
2027   </tr><tr class="layout">
2028     <td class="left"><tt>{i32, i32} (i32)</tt></td>
2029     <td class="left">A function taking an <tt>i32</tt>, returning a
2030         <a href="#t_struct">structure</a> containing two <tt>i32</tt> values
2031     </td>
2032   </tr>
2033 </table>
2034
2035 </div>
2036
2037 <!-- _______________________________________________________________________ -->
2038 <h4>
2039   <a name="t_struct">Structure Type</a>
2040 </h4>
2041
2042 <div>
2043
2044 <h5>Overview:</h5>
2045 <p>The structure type is used to represent a collection of data members together
2046   in memory.  The elements of a structure may be any type that has a size.</p>
2047
2048 <p>Structures in memory are accessed using '<tt><a href="#i_load">load</a></tt>'
2049    and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field
2050    with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.
2051    Structures in registers are accessed using the
2052    '<tt><a href="#i_extractvalue">extractvalue</a></tt>' and
2053    '<tt><a href="#i_insertvalue">insertvalue</a></tt>' instructions.</p>
2054
2055 <p>Structures may optionally be "packed" structures, which indicate that the
2056   alignment of the struct is one byte, and that there is no padding between
2057   the elements.  In non-packed structs, padding between field types is inserted
2058   as defined by the TargetData string in the module, which is required to match
2059   what the underlying code generator expects.</p>
2060
2061 <p>Structures can either be "literal" or "identified".  A literal structure is
2062   defined inline with other types (e.g. <tt>{i32, i32}*</tt>) whereas identified
2063   types are always defined at the top level with a name.  Literal types are
2064   uniqued by their contents and can never be recursive or opaque since there is
2065   no way to write one.  Identified types can be recursive, can be opaqued, and are
2066   never uniqued.
2067 </p>
2068
2069 <h5>Syntax:</h5>
2070 <pre>
2071   %T1 = type { &lt;type list&gt; }     <i>; Identified normal struct type</i>
2072   %T2 = type &lt;{ &lt;type list&gt; }&gt;   <i>; Identified packed struct type</i>
2073 </pre>
2074
2075 <h5>Examples:</h5>
2076 <table class="layout">
2077   <tr class="layout">
2078     <td class="left"><tt>{ i32, i32, i32 }</tt></td>
2079     <td class="left">A triple of three <tt>i32</tt> values</td>
2080   </tr>
2081   <tr class="layout">
2082     <td class="left"><tt>{&nbsp;float,&nbsp;i32&nbsp;(i32)&nbsp;*&nbsp;}</tt></td>
2083     <td class="left">A pair, where the first element is a <tt>float</tt> and the
2084       second element is a <a href="#t_pointer">pointer</a> to a
2085       <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
2086       an <tt>i32</tt>.</td>
2087   </tr>
2088   <tr class="layout">
2089     <td class="left"><tt>&lt;{ i8, i32 }&gt;</tt></td>
2090     <td class="left">A packed struct known to be 5 bytes in size.</td>
2091   </tr>
2092 </table>
2093
2094 </div>
2095
2096 <!-- _______________________________________________________________________ -->
2097 <h4>
2098   <a name="t_opaque">Opaque Structure Types</a>
2099 </h4>
2100
2101 <div>
2102
2103 <h5>Overview:</h5>
2104 <p>Opaque structure types are used to represent named structure types that do
2105    not have a body specified.  This corresponds (for example) to the C notion of
2106    a forward declared structure.</p>
2107
2108 <h5>Syntax:</h5>
2109 <pre>
2110   %X = type opaque
2111   %52 = type opaque
2112 </pre>
2113
2114 <h5>Examples:</h5>
2115 <table class="layout">
2116   <tr class="layout">
2117     <td class="left"><tt>opaque</tt></td>
2118     <td class="left">An opaque type.</td>
2119   </tr>
2120 </table>
2121
2122 </div>
2123
2124
2125
2126 <!-- _______________________________________________________________________ -->
2127 <h4>
2128   <a name="t_pointer">Pointer Type</a>
2129 </h4>
2130
2131 <div>
2132
2133 <h5>Overview:</h5>
2134 <p>The pointer type is used to specify memory locations.
2135    Pointers are commonly used to reference objects in memory.</p>
2136
2137 <p>Pointer types may have an optional address space attribute defining the
2138    numbered address space where the pointed-to object resides. The default
2139    address space is number zero. The semantics of non-zero address
2140    spaces are target-specific.</p>
2141
2142 <p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does it
2143    permit pointers to labels (<tt>label*</tt>).  Use <tt>i8*</tt> instead.</p>
2144
2145 <h5>Syntax:</h5>
2146 <pre>
2147   &lt;type&gt; *
2148 </pre>
2149
2150 <h5>Examples:</h5>
2151 <table class="layout">
2152   <tr class="layout">
2153     <td class="left"><tt>[4 x i32]*</tt></td>
2154     <td class="left">A <a href="#t_pointer">pointer</a> to <a
2155                     href="#t_array">array</a> of four <tt>i32</tt> values.</td>
2156   </tr>
2157   <tr class="layout">
2158     <td class="left"><tt>i32 (i32*) *</tt></td>
2159     <td class="left"> A <a href="#t_pointer">pointer</a> to a <a
2160       href="#t_function">function</a> that takes an <tt>i32*</tt>, returning an
2161       <tt>i32</tt>.</td>
2162   </tr>
2163   <tr class="layout">
2164     <td class="left"><tt>i32 addrspace(5)*</tt></td>
2165     <td class="left">A <a href="#t_pointer">pointer</a> to an <tt>i32</tt> value
2166      that resides in address space #5.</td>
2167   </tr>
2168 </table>
2169
2170 </div>
2171
2172 <!-- _______________________________________________________________________ -->
2173 <h4>
2174   <a name="t_vector">Vector Type</a>
2175 </h4>
2176
2177 <div>
2178
2179 <h5>Overview:</h5>
2180 <p>A vector type is a simple derived type that represents a vector of elements.
2181    Vector types are used when multiple primitive data are operated in parallel
2182    using a single instruction (SIMD).  A vector type requires a size (number of
2183    elements) and an underlying primitive data type.  Vector types are considered
2184    <a href="#t_firstclass">first class</a>.</p>
2185
2186 <h5>Syntax:</h5>
2187 <pre>
2188   &lt; &lt;# elements&gt; x &lt;elementtype&gt; &gt;
2189 </pre>
2190
2191 <p>The number of elements is a constant integer value larger than 0; elementtype
2192    may be any integer or floating point type.  Vectors of size zero are not
2193    allowed, and pointers are not allowed as the element type.</p>
2194
2195 <h5>Examples:</h5>
2196 <table class="layout">
2197   <tr class="layout">
2198     <td class="left"><tt>&lt;4 x i32&gt;</tt></td>
2199     <td class="left">Vector of 4 32-bit integer values.</td>
2200   </tr>
2201   <tr class="layout">
2202     <td class="left"><tt>&lt;8 x float&gt;</tt></td>
2203     <td class="left">Vector of 8 32-bit floating-point values.</td>
2204   </tr>
2205   <tr class="layout">
2206     <td class="left"><tt>&lt;2 x i64&gt;</tt></td>
2207     <td class="left">Vector of 2 64-bit integer values.</td>
2208   </tr>
2209 </table>
2210
2211 </div>
2212
2213 </div>
2214
2215 </div>
2216
2217 <!-- *********************************************************************** -->
2218 <h2><a name="constants">Constants</a></h2>
2219 <!-- *********************************************************************** -->
2220
2221 <div>
2222
2223 <p>LLVM has several different basic types of constants.  This section describes
2224    them all and their syntax.</p>
2225
2226 <!-- ======================================================================= -->
2227 <h3>
2228   <a name="simpleconstants">Simple Constants</a>
2229 </h3>
2230
2231 <div>
2232
2233 <dl>
2234   <dt><b>Boolean constants</b></dt>
2235   <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
2236       constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd>
2237
2238   <dt><b>Integer constants</b></dt>
2239   <dd>Standard integers (such as '4') are constants of
2240       the <a href="#t_integer">integer</a> type.  Negative numbers may be used
2241       with integer types.</dd>
2242
2243   <dt><b>Floating point constants</b></dt>
2244   <dd>Floating point constants use standard decimal notation (e.g. 123.421),
2245       exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal
2246       notation (see below).  The assembler requires the exact decimal value of a
2247       floating-point constant.  For example, the assembler accepts 1.25 but
2248       rejects 1.3 because 1.3 is a repeating decimal in binary.  Floating point
2249       constants must have a <a href="#t_floating">floating point</a> type. </dd>
2250
2251   <dt><b>Null pointer constants</b></dt>
2252   <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant
2253       and must be of <a href="#t_pointer">pointer type</a>.</dd>
2254 </dl>
2255
2256 <p>The one non-intuitive notation for constants is the hexadecimal form of
2257    floating point constants.  For example, the form '<tt>double
2258    0x432ff973cafa8000</tt>' is equivalent to (but harder to read than)
2259    '<tt>double 4.5e+15</tt>'.  The only time hexadecimal floating point
2260    constants are required (and the only time that they are generated by the
2261    disassembler) is when a floating point constant must be emitted but it cannot
2262    be represented as a decimal floating point number in a reasonable number of
2263    digits.  For example, NaN's, infinities, and other special values are
2264    represented in their IEEE hexadecimal format so that assembly and disassembly
2265    do not cause any bits to change in the constants.</p>
2266
2267 <p>When using the hexadecimal form, constants of types float and double are
2268    represented using the 16-digit form shown above (which matches the IEEE754
2269    representation for double); float values must, however, be exactly
2270    representable as IEE754 single precision.  Hexadecimal format is always used
2271    for long double, and there are three forms of long double.  The 80-bit format
2272    used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits.
2273    The 128-bit format used by PowerPC (two adjacent doubles) is represented
2274    by <tt>0xM</tt> followed by 32 hexadecimal digits.  The IEEE 128-bit format
2275    is represented by <tt>0xL</tt> followed by 32 hexadecimal digits; no
2276    currently supported target uses this format.  Long doubles will only work if
2277    they match the long double format on your target.  All hexadecimal formats
2278    are big-endian (sign bit at the left).</p>
2279
2280 <p>There are no constants of type x86mmx.</p>
2281 </div>
2282
2283 <!-- ======================================================================= -->
2284 <h3>
2285 <a name="aggregateconstants"></a> <!-- old anchor -->
2286 <a name="complexconstants">Complex Constants</a>
2287 </h3>
2288
2289 <div>
2290
2291 <p>Complex constants are a (potentially recursive) combination of simple
2292    constants and smaller complex constants.</p>
2293
2294 <dl>
2295   <dt><b>Structure constants</b></dt>
2296   <dd>Structure constants are represented with notation similar to structure
2297       type definitions (a comma separated list of elements, surrounded by braces
2298       (<tt>{}</tt>)).  For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>",
2299       where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>".
2300       Structure constants must have <a href="#t_struct">structure type</a>, and
2301       the number and types of elements must match those specified by the
2302       type.</dd>
2303
2304   <dt><b>Array constants</b></dt>
2305   <dd>Array constants are represented with notation similar to array type
2306      definitions (a comma separated list of elements, surrounded by square
2307      brackets (<tt>[]</tt>)).  For example: "<tt>[ i32 42, i32 11, i32 74
2308      ]</tt>".  Array constants must have <a href="#t_array">array type</a>, and
2309      the number and types of elements must match those specified by the
2310      type.</dd>
2311
2312   <dt><b>Vector constants</b></dt>
2313   <dd>Vector constants are represented with notation similar to vector type
2314       definitions (a comma separated list of elements, surrounded by
2315       less-than/greater-than's (<tt>&lt;&gt;</tt>)).  For example: "<tt>&lt; i32
2316       42, i32 11, i32 74, i32 100 &gt;</tt>".  Vector constants must
2317       have <a href="#t_vector">vector type</a>, and the number and types of
2318       elements must match those specified by the type.</dd>
2319
2320   <dt><b>Zero initialization</b></dt>
2321   <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a
2322       value to zero of <em>any</em> type, including scalar and
2323       <a href="#t_aggregate">aggregate</a> types.
2324       This is often used to avoid having to print large zero initializers
2325       (e.g. for large arrays) and is always exactly equivalent to using explicit
2326       zero initializers.</dd>
2327
2328   <dt><b>Metadata node</b></dt>
2329   <dd>A metadata node is a structure-like constant with
2330       <a href="#t_metadata">metadata type</a>.  For example: "<tt>metadata !{
2331       i32 0, metadata !"test" }</tt>".  Unlike other constants that are meant to
2332       be interpreted as part of the instruction stream, metadata is a place to
2333       attach additional information such as debug info.</dd>
2334 </dl>
2335
2336 </div>
2337
2338 <!-- ======================================================================= -->
2339 <h3>
2340   <a name="globalconstants">Global Variable and Function Addresses</a>
2341 </h3>
2342
2343 <div>
2344
2345 <p>The addresses of <a href="#globalvars">global variables</a>
2346    and <a href="#functionstructure">functions</a> are always implicitly valid
2347    (link-time) constants.  These constants are explicitly referenced when
2348    the <a href="#identifiers">identifier for the global</a> is used and always
2349    have <a href="#t_pointer">pointer</a> type. For example, the following is a
2350    legal LLVM file:</p>
2351
2352 <pre class="doc_code">
2353 @X = global i32 17
2354 @Y = global i32 42
2355 @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
2356 </pre>
2357
2358 </div>
2359
2360 <!-- ======================================================================= -->
2361 <h3>
2362   <a name="undefvalues">Undefined Values</a>
2363 </h3>
2364
2365 <div>
2366
2367 <p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and
2368    indicates that the user of the value may receive an unspecified bit-pattern.
2369    Undefined values may be of any type (other than '<tt>label</tt>'
2370    or '<tt>void</tt>') and be used anywhere a constant is permitted.</p>
2371
2372 <p>Undefined values are useful because they indicate to the compiler that the
2373    program is well defined no matter what value is used.  This gives the
2374    compiler more freedom to optimize.  Here are some examples of (potentially
2375    surprising) transformations that are valid (in pseudo IR):</p>
2376
2377
2378 <pre class="doc_code">
2379   %A = add %X, undef
2380   %B = sub %X, undef
2381   %C = xor %X, undef
2382 Safe:
2383   %A = undef
2384   %B = undef
2385   %C = undef
2386 </pre>
2387
2388 <p>This is safe because all of the output bits are affected by the undef bits.
2389    Any output bit can have a zero or one depending on the input bits.</p>
2390
2391 <pre class="doc_code">
2392   %A = or %X, undef
2393   %B = and %X, undef
2394 Safe:
2395   %A = -1
2396   %B = 0
2397 Unsafe:
2398   %A = undef
2399   %B = undef
2400 </pre>
2401
2402 <p>These logical operations have bits that are not always affected by the input.
2403    For example, if <tt>%X</tt> has a zero bit, then the output of the
2404    '<tt>and</tt>' operation will always be a zero for that bit, no matter what
2405    the corresponding bit from the '<tt>undef</tt>' is. As such, it is unsafe to
2406    optimize or assume that the result of the '<tt>and</tt>' is '<tt>undef</tt>'.
2407    However, it is safe to assume that all bits of the '<tt>undef</tt>' could be
2408    0, and optimize the '<tt>and</tt>' to 0. Likewise, it is safe to assume that
2409    all the bits of the '<tt>undef</tt>' operand to the '<tt>or</tt>' could be
2410    set, allowing the '<tt>or</tt>' to be folded to -1.</p>
2411
2412 <pre class="doc_code">
2413   %A = select undef, %X, %Y
2414   %B = select undef, 42, %Y
2415   %C = select %X, %Y, undef
2416 Safe:
2417   %A = %X     (or %Y)
2418   %B = 42     (or %Y)
2419   %C = %Y
2420 Unsafe:
2421   %A = undef
2422   %B = undef
2423   %C = undef
2424 </pre>
2425
2426 <p>This set of examples shows that undefined '<tt>select</tt>' (and conditional
2427    branch) conditions can go <em>either way</em>, but they have to come from one
2428    of the two operands.  In the <tt>%A</tt> example, if <tt>%X</tt> and
2429    <tt>%Y</tt> were both known to have a clear low bit, then <tt>%A</tt> would
2430    have to have a cleared low bit. However, in the <tt>%C</tt> example, the
2431    optimizer is allowed to assume that the '<tt>undef</tt>' operand could be the
2432    same as <tt>%Y</tt>, allowing the whole '<tt>select</tt>' to be
2433    eliminated.</p>
2434
2435 <pre class="doc_code">
2436   %A = xor undef, undef
2437
2438   %B = undef
2439   %C = xor %B, %B
2440
2441   %D = undef
2442   %E = icmp lt %D, 4
2443   %F = icmp gte %D, 4
2444
2445 Safe:
2446   %A = undef
2447   %B = undef
2448   %C = undef
2449   %D = undef
2450   %E = undef
2451   %F = undef
2452 </pre>
2453
2454 <p>This example points out that two '<tt>undef</tt>' operands are not
2455    necessarily the same. This can be surprising to people (and also matches C
2456    semantics) where they assume that "<tt>X^X</tt>" is always zero, even
2457    if <tt>X</tt> is undefined. This isn't true for a number of reasons, but the
2458    short answer is that an '<tt>undef</tt>' "variable" can arbitrarily change
2459    its value over its "live range".  This is true because the variable doesn't
2460    actually <em>have a live range</em>. Instead, the value is logically read
2461    from arbitrary registers that happen to be around when needed, so the value
2462    is not necessarily consistent over time. In fact, <tt>%A</tt> and <tt>%C</tt>
2463    need to have the same semantics or the core LLVM "replace all uses with"
2464    concept would not hold.</p>
2465
2466 <pre class="doc_code">
2467   %A = fdiv undef, %X
2468   %B = fdiv %X, undef
2469 Safe:
2470   %A = undef
2471 b: unreachable
2472 </pre>
2473
2474 <p>These examples show the crucial difference between an <em>undefined
2475   value</em> and <em>undefined behavior</em>. An undefined value (like
2476   '<tt>undef</tt>') is allowed to have an arbitrary bit-pattern. This means that
2477   the <tt>%A</tt> operation can be constant folded to '<tt>undef</tt>', because
2478   the '<tt>undef</tt>' could be an SNaN, and <tt>fdiv</tt> is not (currently)
2479   defined on SNaN's. However, in the second example, we can make a more
2480   aggressive assumption: because the <tt>undef</tt> is allowed to be an
2481   arbitrary value, we are allowed to assume that it could be zero. Since a
2482   divide by zero has <em>undefined behavior</em>, we are allowed to assume that
2483   the operation does not execute at all. This allows us to delete the divide and
2484   all code after it. Because the undefined operation "can't happen", the
2485   optimizer can assume that it occurs in dead code.</p>
2486
2487 <pre class="doc_code">
2488 a:  store undef -> %X
2489 b:  store %X -> undef
2490 Safe:
2491 a: &lt;deleted&gt;
2492 b: unreachable
2493 </pre>
2494
2495 <p>These examples reiterate the <tt>fdiv</tt> example: a store <em>of</em> an
2496    undefined value can be assumed to not have any effect; we can assume that the
2497    value is overwritten with bits that happen to match what was already there.
2498    However, a store <em>to</em> an undefined location could clobber arbitrary
2499    memory, therefore, it has undefined behavior.</p>
2500
2501 </div>
2502
2503 <!-- ======================================================================= -->
2504 <h3>
2505   <a name="trapvalues">Trap Values</a>
2506 </h3>
2507
2508 <div>
2509
2510 <p>Trap values are similar to <a href="#undefvalues">undef values</a>, however
2511    instead of representing an unspecified bit pattern, they represent the
2512    fact that an instruction or constant expression which cannot evoke side
2513    effects has nevertheless detected a condition which results in undefined
2514    behavior.</p>
2515
2516 <p>There is currently no way of representing a trap value in the IR; they
2517    only exist when produced by operations such as
2518    <a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag.</p>
2519
2520 <p>Trap value behavior is defined in terms of value <i>dependence</i>:</p>
2521
2522 <ul>
2523 <li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on
2524     their operands.</li>
2525
2526 <li><a href="#i_phi"><tt>Phi</tt></a> nodes depend on the operand corresponding
2527     to their dynamic predecessor basic block.</li>
2528
2529 <li>Function arguments depend on the corresponding actual argument values in
2530     the dynamic callers of their functions.</li>
2531
2532 <li><a href="#i_call"><tt>Call</tt></a> instructions depend on the
2533     <a href="#i_ret"><tt>ret</tt></a> instructions that dynamically transfer
2534     control back to them.</li>
2535
2536 <li><a href="#i_invoke"><tt>Invoke</tt></a> instructions depend on the
2537     <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_unwind"><tt>unwind</tt></a>,
2538     or exception-throwing call instructions that dynamically transfer control
2539     back to them.</li>
2540
2541 <li>Non-volatile loads and stores depend on the most recent stores to all of the
2542     referenced memory addresses, following the order in the IR
2543     (including loads and stores implied by intrinsics such as
2544     <a href="#int_memcpy"><tt>@llvm.memcpy</tt></a>.)</li>
2545
2546 <!-- TODO: In the case of multiple threads, this only applies if the store
2547      "happens-before" the load or store. -->
2548
2549 <!-- TODO: floating-point exception state -->
2550
2551 <li>An instruction with externally visible side effects depends on the most
2552     recent preceding instruction with externally visible side effects, following
2553     the order in the IR. (This includes
2554     <a href="#volatile">volatile operations</a>.)</li>
2555
2556 <li>An instruction <i>control-depends</i> on a
2557     <a href="#terminators">terminator instruction</a>
2558     if the terminator instruction has multiple successors and the instruction
2559     is always executed when control transfers to one of the successors, and
2560     may not be executed when control is transferred to another.</li>
2561
2562 <li>Additionally, an instruction also <i>control-depends</i> on a terminator
2563     instruction if the set of instructions it otherwise depends on would be
2564     different if the terminator had transferred control to a different
2565     successor.</li>
2566
2567 <li>Dependence is transitive.</li>
2568
2569 </ul>
2570
2571 <p>Whenever a trap value is generated, all values which depend on it evaluate
2572    to trap. If they have side effects, they evoke their side effects as if each
2573    operand with a trap value were undef. If they have externally-visible side
2574    effects, the behavior is undefined.</p>
2575
2576 <p>Here are some examples:</p>
2577
2578 <pre class="doc_code">
2579 entry:
2580   %trap = sub nuw i32 0, 1           ; Results in a trap value.
2581   %still_trap = and i32 %trap, 0     ; Whereas (and i32 undef, 0) would return 0.
2582   %trap_yet_again = getelementptr i32* @h, i32 %still_trap
2583   store i32 0, i32* %trap_yet_again  ; undefined behavior
2584
2585   store i32 %trap, i32* @g           ; Trap value conceptually stored to memory.
2586   %trap2 = load i32* @g              ; Returns a trap value, not just undef.
2587
2588   store volatile i32 %trap, i32* @g  ; External observation; undefined behavior.
2589
2590   %narrowaddr = bitcast i32* @g to i16*
2591   %wideaddr = bitcast i32* @g to i64*
2592   %trap3 = load i16* %narrowaddr     ; Returns a trap value.
2593   %trap4 = load i64* %wideaddr       ; Returns a trap value.
2594
2595   %cmp = icmp slt i32 %trap, 0       ; Returns a trap value.
2596   br i1 %cmp, label %true, label %end ; Branch to either destination.
2597
2598 true:
2599   store volatile i32 0, i32* @g      ; This is control-dependent on %cmp, so
2600                                      ; it has undefined behavior.
2601   br label %end
2602
2603 end:
2604   %p = phi i32 [ 0, %entry ], [ 1, %true ]
2605                                      ; Both edges into this PHI are
2606                                      ; control-dependent on %cmp, so this
2607                                      ; always results in a trap value.
2608
2609   store volatile i32 0, i32* @g      ; This would depend on the store in %true
2610                                      ; if %cmp is true, or the store in %entry
2611                                      ; otherwise, so this is undefined behavior.
2612
2613   br i1 %cmp, label %second_true, label %second_end
2614                                      ; The same branch again, but this time the
2615                                      ; true block doesn't have side effects.
2616
2617 second_true:
2618   ; No side effects!
2619   ret void
2620
2621 second_end:
2622   store volatile i32 0, i32* @g      ; This time, the instruction always depends
2623                                      ; on the store in %end. Also, it is
2624                                      ; control-equivalent to %end, so this is
2625                                      ; well-defined (again, ignoring earlier
2626                                      ; undefined behavior in this example).
2627 </pre>
2628
2629 </div>
2630
2631 <!-- ======================================================================= -->
2632 <h3>
2633   <a name="blockaddress">Addresses of Basic Blocks</a>
2634 </h3>
2635
2636 <div>
2637
2638 <p><b><tt>blockaddress(@function, %block)</tt></b></p>
2639
2640 <p>The '<tt>blockaddress</tt>' constant computes the address of the specified
2641    basic block in the specified function, and always has an i8* type.  Taking
2642    the address of the entry block is illegal.</p>
2643
2644 <p>This value only has defined behavior when used as an operand to the
2645    '<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction, or for
2646    comparisons against null. Pointer equality tests between labels addresses
2647    results in undefined behavior &mdash; though, again, comparison against null
2648    is ok, and no label is equal to the null pointer. This may be passed around
2649    as an opaque pointer sized value as long as the bits are not inspected. This
2650    allows <tt>ptrtoint</tt> and arithmetic to be performed on these values so
2651    long as the original value is reconstituted before the <tt>indirectbr</tt>
2652    instruction.</p>
2653
2654 <p>Finally, some targets may provide defined semantics when using the value as
2655    the operand to an inline assembly, but that is target specific.</p>
2656
2657 </div>
2658
2659
2660 <!-- ======================================================================= -->
2661 <h3>
2662   <a name="constantexprs">Constant Expressions</a>
2663 </h3>
2664
2665 <div>
2666
2667 <p>Constant expressions are used to allow expressions involving other constants
2668    to be used as constants.  Constant expressions may be of
2669    any <a href="#t_firstclass">first class</a> type and may involve any LLVM
2670    operation that does not have side effects (e.g. load and call are not
2671    supported). The following is the syntax for constant expressions:</p>
2672
2673 <dl>
2674   <dt><b><tt>trunc (CST to TYPE)</tt></b></dt>
2675   <dd>Truncate a constant to another type. The bit size of CST must be larger
2676       than the bit size of TYPE. Both types must be integers.</dd>
2677
2678   <dt><b><tt>zext (CST to TYPE)</tt></b></dt>
2679   <dd>Zero extend a constant to another type. The bit size of CST must be
2680       smaller than the bit size of TYPE.  Both types must be integers.</dd>
2681
2682   <dt><b><tt>sext (CST to TYPE)</tt></b></dt>
2683   <dd>Sign extend a constant to another type. The bit size of CST must be
2684       smaller than the bit size of TYPE.  Both types must be integers.</dd>
2685
2686   <dt><b><tt>fptrunc (CST to TYPE)</tt></b></dt>
2687   <dd>Truncate a floating point constant to another floating point type. The
2688       size of CST must be larger than the size of TYPE. Both types must be
2689       floating point.</dd>
2690
2691   <dt><b><tt>fpext (CST to TYPE)</tt></b></dt>
2692   <dd>Floating point extend a constant to another type. The size of CST must be
2693       smaller or equal to the size of TYPE. Both types must be floating
2694       point.</dd>
2695
2696   <dt><b><tt>fptoui (CST to TYPE)</tt></b></dt>
2697   <dd>Convert a floating point constant to the corresponding unsigned integer
2698       constant. TYPE must be a scalar or vector integer type. CST must be of
2699       scalar or vector floating point type. Both CST and TYPE must be scalars,
2700       or vectors of the same number of elements. If the value won't fit in the
2701       integer type, the results are undefined.</dd>
2702
2703   <dt><b><tt>fptosi (CST to TYPE)</tt></b></dt>
2704   <dd>Convert a floating point constant to the corresponding signed integer
2705       constant.  TYPE must be a scalar or vector integer type. CST must be of
2706       scalar or vector floating point type. Both CST and TYPE must be scalars,
2707       or vectors of the same number of elements. If the value won't fit in the
2708       integer type, the results are undefined.</dd>
2709
2710   <dt><b><tt>uitofp (CST to TYPE)</tt></b></dt>
2711   <dd>Convert an unsigned integer constant to the corresponding floating point
2712       constant. TYPE must be a scalar or vector floating point type. CST must be
2713       of scalar or vector integer type. Both CST and TYPE must be scalars, or
2714       vectors of the same number of elements. If the value won't fit in the
2715       floating point type, the results are undefined.</dd>
2716
2717   <dt><b><tt>sitofp (CST to TYPE)</tt></b></dt>
2718   <dd>Convert a signed integer constant to the corresponding floating point
2719       constant. TYPE must be a scalar or vector floating point type. CST must be
2720       of scalar or vector integer type. Both CST and TYPE must be scalars, or
2721       vectors of the same number of elements. If the value won't fit in the
2722       floating point type, the results are undefined.</dd>
2723
2724   <dt><b><tt>ptrtoint (CST to TYPE)</tt></b></dt>
2725   <dd>Convert a pointer typed constant to the corresponding integer constant
2726       <tt>TYPE</tt> must be an integer type. <tt>CST</tt> must be of pointer
2727       type. The <tt>CST</tt> value is zero extended, truncated, or unchanged to
2728       make it fit in <tt>TYPE</tt>.</dd>
2729
2730   <dt><b><tt>inttoptr (CST to TYPE)</tt></b></dt>
2731   <dd>Convert a integer constant to a pointer constant.  TYPE must be a pointer
2732       type.  CST must be of integer type. The CST value is zero extended,
2733       truncated, or unchanged to make it fit in a pointer size. This one is
2734       <i>really</i> dangerous!</dd>
2735
2736   <dt><b><tt>bitcast (CST to TYPE)</tt></b></dt>
2737   <dd>Convert a constant, CST, to another TYPE. The constraints of the operands
2738       are the same as those for the <a href="#i_bitcast">bitcast
2739       instruction</a>.</dd>
2740
2741   <dt><b><tt>getelementptr (CSTPTR, IDX0, IDX1, ...)</tt></b></dt>
2742   <dt><b><tt>getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)</tt></b></dt>
2743   <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
2744       constants.  As with the <a href="#i_getelementptr">getelementptr</a>
2745       instruction, the index list may have zero or more indexes, which are
2746       required to make sense for the type of "CSTPTR".</dd>
2747
2748   <dt><b><tt>select (COND, VAL1, VAL2)</tt></b></dt>
2749   <dd>Perform the <a href="#i_select">select operation</a> on constants.</dd>
2750
2751   <dt><b><tt>icmp COND (VAL1, VAL2)</tt></b></dt>
2752   <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd>
2753
2754   <dt><b><tt>fcmp COND (VAL1, VAL2)</tt></b></dt>
2755   <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd>
2756
2757   <dt><b><tt>extractelement (VAL, IDX)</tt></b></dt>
2758   <dd>Perform the <a href="#i_extractelement">extractelement operation</a> on
2759       constants.</dd>
2760
2761   <dt><b><tt>insertelement (VAL, ELT, IDX)</tt></b></dt>
2762   <dd>Perform the <a href="#i_insertelement">insertelement operation</a> on
2763     constants.</dd>
2764
2765   <dt><b><tt>shufflevector (VEC1, VEC2, IDXMASK)</tt></b></dt>
2766   <dd>Perform the <a href="#i_shufflevector">shufflevector operation</a> on
2767       constants.</dd>
2768
2769   <dt><b><tt>extractvalue (VAL, IDX0, IDX1, ...)</tt></b></dt>
2770   <dd>Perform the <a href="#i_extractvalue">extractvalue operation</a> on
2771     constants. The index list is interpreted in a similar manner as indices in
2772     a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one
2773     index value must be specified.</dd>
2774
2775   <dt><b><tt>insertvalue (VAL, ELT, IDX0, IDX1, ...)</tt></b></dt>
2776   <dd>Perform the <a href="#i_insertvalue">insertvalue operation</a> on
2777     constants. The index list is interpreted in a similar manner as indices in
2778     a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one
2779     index value must be specified.</dd>
2780
2781   <dt><b><tt>OPCODE (LHS, RHS)</tt></b></dt>
2782   <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may
2783       be any of the <a href="#binaryops">binary</a>
2784       or <a href="#bitwiseops">bitwise binary</a> operations.  The constraints
2785       on operands are the same as those for the corresponding instruction
2786       (e.g. no bitwise operations on floating point values are allowed).</dd>
2787 </dl>
2788
2789 </div>
2790
2791 </div>
2792
2793 <!-- *********************************************************************** -->
2794 <h2><a name="othervalues">Other Values</a></h2>
2795 <!-- *********************************************************************** -->
2796 <div>
2797 <!-- ======================================================================= -->
2798 <h3>
2799 <a name="inlineasm">Inline Assembler Expressions</a>
2800 </h3>
2801
2802 <div>
2803
2804 <p>LLVM supports inline assembler expressions (as opposed
2805    to <a href="#moduleasm">Module-Level Inline Assembly</a>) through the use of
2806    a special value.  This value represents the inline assembler as a string
2807    (containing the instructions to emit), a list of operand constraints (stored
2808    as a string), a flag that indicates whether or not the inline asm
2809    expression has side effects, and a flag indicating whether the function
2810    containing the asm needs to align its stack conservatively.  An example
2811    inline assembler expression is:</p>
2812
2813 <pre class="doc_code">
2814 i32 (i32) asm "bswap $0", "=r,r"
2815 </pre>
2816
2817 <p>Inline assembler expressions may <b>only</b> be used as the callee operand of
2818    a <a href="#i_call"><tt>call</tt> instruction</a>.  Thus, typically we
2819    have:</p>
2820
2821 <pre class="doc_code">
2822 %X = call i32 asm "<a href="#int_bswap">bswap</a> $0", "=r,r"(i32 %Y)
2823 </pre>
2824
2825 <p>Inline asms with side effects not visible in the constraint list must be
2826    marked as having side effects.  This is done through the use of the
2827    '<tt>sideeffect</tt>' keyword, like so:</p>
2828
2829 <pre class="doc_code">
2830 call void asm sideeffect "eieio", ""()
2831 </pre>
2832
2833 <p>In some cases inline asms will contain code that will not work unless the
2834    stack is aligned in some way, such as calls or SSE instructions on x86,
2835    yet will not contain code that does that alignment within the asm.
2836    The compiler should make conservative assumptions about what the asm might
2837    contain and should generate its usual stack alignment code in the prologue
2838    if the '<tt>alignstack</tt>' keyword is present:</p>
2839
2840 <pre class="doc_code">
2841 call void asm alignstack "eieio", ""()
2842 </pre>
2843
2844 <p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come
2845    first.</p>
2846
2847 <!--
2848 <p>TODO: The format of the asm and constraints string still need to be
2849    documented here.  Constraints on what can be done (e.g. duplication, moving,
2850    etc need to be documented).  This is probably best done by reference to
2851    another document that covers inline asm from a holistic perspective.</p>
2852   -->
2853
2854 <!-- _______________________________________________________________________ -->
2855 <h4>
2856   <a name="inlineasm_md">Inline Asm Metadata</a>
2857 </h4>
2858
2859 <div>
2860
2861 <p>The call instructions that wrap inline asm nodes may have a
2862    "<tt>!srcloc</tt>" MDNode attached to it that contains a list of constant
2863    integers.  If present, the code generator will use the integer as the
2864    location cookie value when report errors through the <tt>LLVMContext</tt>
2865    error reporting mechanisms.  This allows a front-end to correlate backend
2866    errors that occur with inline asm back to the source code that produced it.
2867    For example:</p>
2868
2869 <pre class="doc_code">
2870 call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b>
2871 ...
2872 !42 = !{ i32 1234567 }
2873 </pre>
2874
2875 <p>It is up to the front-end to make sense of the magic numbers it places in the
2876    IR. If the MDNode contains multiple constants, the code generator will use
2877    the one that corresponds to the line of the asm that the error occurs on.</p>
2878
2879 </div>
2880
2881 </div>
2882
2883 <!-- ======================================================================= -->
2884 <h3>
2885   <a name="metadata">Metadata Nodes and Metadata Strings</a>
2886 </h3>
2887
2888 <div>
2889
2890 <p>LLVM IR allows metadata to be attached to instructions in the program that
2891    can convey extra information about the code to the optimizers and code
2892    generator.  One example application of metadata is source-level debug
2893    information.  There are two metadata primitives: strings and nodes. All
2894    metadata has the <tt>metadata</tt> type and is identified in syntax by a
2895    preceding exclamation point ('<tt>!</tt>').</p>
2896
2897 <p>A metadata string is a string surrounded by double quotes.  It can contain
2898    any character by escaping non-printable characters with "<tt>\xx</tt>" where
2899    "<tt>xx</tt>" is the two digit hex code.  For example:
2900    "<tt>!"test\00"</tt>".</p>
2901
2902 <p>Metadata nodes are represented with notation similar to structure constants
2903    (a comma separated list of elements, surrounded by braces and preceded by an
2904    exclamation point). Metadata nodes can have any values as their operand. For
2905    example:</p>
2906
2907 <div class="doc_code">
2908 <pre>
2909 !{ metadata !"test\00", i32 10}
2910 </pre>
2911 </div>
2912
2913 <p>A <a href="#namedmetadatastructure">named metadata</a> is a collection of
2914    metadata nodes, which can be looked up in the module symbol table. For
2915    example:</p>
2916
2917 <div class="doc_code">
2918 <pre>
2919 !foo =  metadata !{!4, !3}
2920 </pre>
2921 </div>
2922
2923 <p>Metadata can be used as function arguments. Here <tt>llvm.dbg.value</tt>
2924    function is using two metadata arguments:</p>
2925
2926 <div class="doc_code">
2927 <pre>
2928 call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
2929 </pre>
2930 </div>
2931
2932 <p>Metadata can be attached with an instruction. Here metadata <tt>!21</tt> is
2933    attached to the <tt>add</tt> instruction using the <tt>!dbg</tt>
2934    identifier:</p>
2935
2936 <div class="doc_code">
2937 <pre>
2938 %indvar.next = add i64 %indvar, 1, !dbg !21
2939 </pre>
2940 </div>
2941
2942 <p>More information about specific metadata nodes recognized by the optimizers
2943    and code generator is found below.</p>
2944
2945 <!-- _______________________________________________________________________ -->
2946 <h4>
2947   <a name="tbaa">'<tt>tbaa</tt>' Metadata</a>
2948 </h4>
2949
2950 <div>
2951
2952 <p>In LLVM IR, memory does not have types, so LLVM's own type system is not
2953    suitable for doing TBAA. Instead, metadata is added to the IR to describe
2954    a type system of a higher level language. This can be used to implement
2955    typical C/C++ TBAA, but it can also be used to implement custom alias
2956    analysis behavior for other languages.</p>
2957
2958 <p>The current metadata format is very simple. TBAA metadata nodes have up to
2959    three fields, e.g.:</p>
2960
2961 <div class="doc_code">
2962 <pre>
2963 !0 = metadata !{ metadata !"an example type tree" }
2964 !1 = metadata !{ metadata !"int", metadata !0 }
2965 !2 = metadata !{ metadata !"float", metadata !0 }
2966 !3 = metadata !{ metadata !"const float", metadata !2, i64 1 }
2967 </pre>
2968 </div>
2969
2970 <p>The first field is an identity field. It can be any value, usually
2971    a metadata string, which uniquely identifies the type. The most important
2972    name in the tree is the name of the root node. Two trees with
2973    different root node names are entirely disjoint, even if they
2974    have leaves with common names.</p>
2975
2976 <p>The second field identifies the type's parent node in the tree, or
2977    is null or omitted for a root node. A type is considered to alias
2978    all of its descendants and all of its ancestors in the tree. Also,
2979    a type is considered to alias all types in other trees, so that
2980    bitcode produced from multiple front-ends is handled conservatively.</p>
2981
2982 <p>If the third field is present, it's an integer which if equal to 1
2983    indicates that the type is "constant" (meaning
2984    <tt>pointsToConstantMemory</tt> should return true; see
2985    <a href="AliasAnalysis.html#OtherItfs">other useful
2986    <tt>AliasAnalysis</tt> methods</a>).</p>
2987
2988 </div>
2989
2990 <!-- _______________________________________________________________________ -->
2991 <h4>
2992   <a name="fpaccuracy">'<tt>fpaccuracy</tt>' Metadata</a>
2993 </h4>
2994
2995 <div>
2996
2997 <p><tt>fpaccuracy</tt> metadata may be attached to any instruction of floating
2998    point type.  It expresses the maximum relative error of the result of
2999    that instruction, in ULPs. ULP is defined as follows:</p>
3000
3001 <blockquote>
3002
3003 <p>If <tt>x</tt> is a real number that lies between two finite consecutive
3004    floating-point numbers <tt>a</tt> and <tt>b</tt>, without being equal to one
3005    of them, then <tt>ulp(x) = |b - a|</tt>, otherwise <tt>ulp(x)</tt> is the
3006    distance between the two non-equal finite floating-point numbers nearest
3007    <tt>x</tt>. Moreover, <tt>ulp(NaN)</tt> is <tt>NaN</tt>.</p>
3008
3009 </blockquote>
3010
3011 <p>The maximum relative error may be any rational number.  The metadata node
3012    shall consist of a pair of unsigned integers respectively representing
3013    the numerator and denominator.  For example, 2.5 ULP:</p>
3014
3015 <div class="doc_code">
3016 <pre>
3017 !0 = metadata !{ i32 5, i32 2 }
3018 </pre>
3019 </div>
3020
3021 </div>
3022
3023 </div>
3024
3025 </div>
3026
3027 <!-- *********************************************************************** -->
3028 <h2>
3029   <a name="intrinsic_globals">Intrinsic Global Variables</a>
3030 </h2>
3031 <!-- *********************************************************************** -->
3032 <div>
3033 <p>LLVM has a number of "magic" global variables that contain data that affect
3034 code generation or other IR semantics.  These are documented here.  All globals
3035 of this sort should have a section specified as "<tt>llvm.metadata</tt>".  This
3036 section and all globals that start with "<tt>llvm.</tt>" are reserved for use
3037 by LLVM.</p>
3038
3039 <!-- ======================================================================= -->
3040 <h3>
3041 <a name="intg_used">The '<tt>llvm.used</tt>' Global Variable</a>
3042 </h3>
3043
3044 <div>
3045
3046 <p>The <tt>@llvm.used</tt> global is an array with i8* element type which has <a
3047 href="#linkage_appending">appending linkage</a>.  This array contains a list of
3048 pointers to global variables and functions which may optionally have a pointer
3049 cast formed of bitcast or getelementptr.  For example, a legal use of it is:</p>
3050
3051 <div class="doc_code">
3052 <pre>
3053 @X = global i8 4
3054 @Y = global i32 123
3055
3056 @llvm.used = appending global [2 x i8*] [
3057    i8* @X,
3058    i8* bitcast (i32* @Y to i8*)
3059 ], section "llvm.metadata"
3060 </pre>
3061 </div>
3062
3063 <p>If a global variable appears in the <tt>@llvm.used</tt> list, then the
3064    compiler, assembler, and linker are required to treat the symbol as if there
3065    is a reference to the global that it cannot see.  For example, if a variable
3066    has internal linkage and no references other than that from
3067    the <tt>@llvm.used</tt> list, it cannot be deleted.  This is commonly used to
3068    represent references from inline asms and other things the compiler cannot
3069    "see", and corresponds to "<tt>attribute((used))</tt>" in GNU C.</p>
3070
3071 <p>On some targets, the code generator must emit a directive to the assembler or
3072    object file to prevent the assembler and linker from molesting the
3073    symbol.</p>
3074
3075 </div>
3076
3077 <!-- ======================================================================= -->
3078 <h3>
3079   <a name="intg_compiler_used">
3080     The '<tt>llvm.compiler.used</tt>' Global Variable
3081   </a>
3082 </h3>
3083
3084 <div>
3085
3086 <p>The <tt>@llvm.compiler.used</tt> directive is the same as the
3087    <tt>@llvm.used</tt> directive, except that it only prevents the compiler from
3088    touching the symbol.  On targets that support it, this allows an intelligent
3089    linker to optimize references to the symbol without being impeded as it would
3090    be by <tt>@llvm.used</tt>.</p>
3091
3092 <p>This is a rare construct that should only be used in rare circumstances, and
3093    should not be exposed to source languages.</p>
3094
3095 </div>
3096
3097 <!-- ======================================================================= -->
3098 <h3>
3099 <a name="intg_global_ctors">The '<tt>llvm.global_ctors</tt>' Global Variable</a>
3100 </h3>
3101
3102 <div>
3103
3104 <div class="doc_code">
3105 <pre>
3106 %0 = type { i32, void ()* }
3107 @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
3108 </pre>
3109 </div>
3110
3111 <p>The <tt>@llvm.global_ctors</tt> array contains a list of constructor
3112    functions and associated priorities.  The functions referenced by this array
3113    will be called in ascending order of priority (i.e. lowest first) when the
3114    module is loaded.  The order of functions with the same priority is not
3115    defined.</p>
3116
3117 </div>
3118
3119 <!-- ======================================================================= -->
3120 <h3>
3121 <a name="intg_global_dtors">The '<tt>llvm.global_dtors</tt>' Global Variable</a>
3122 </h3>
3123
3124 <div>
3125
3126 <div class="doc_code">
3127 <pre>
3128 %0 = type { i32, void ()* }
3129 @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
3130 </pre>
3131 </div>
3132
3133 <p>The <tt>@llvm.global_dtors</tt> array contains a list of destructor functions
3134    and associated priorities.  The functions referenced by this array will be
3135    called in descending order of priority (i.e. highest first) when the module
3136    is loaded.  The order of functions with the same priority is not defined.</p>
3137
3138 </div>
3139
3140 </div>
3141
3142 <!-- *********************************************************************** -->
3143 <h2><a name="instref">Instruction Reference</a></h2>
3144 <!-- *********************************************************************** -->
3145
3146 <div>
3147
3148 <p>The LLVM instruction set consists of several different classifications of
3149    instructions: <a href="#terminators">terminator
3150    instructions</a>, <a href="#binaryops">binary instructions</a>,
3151    <a href="#bitwiseops">bitwise binary instructions</a>,
3152    <a href="#memoryops">memory instructions</a>, and
3153    <a href="#otherops">other instructions</a>.</p>
3154
3155 <!-- ======================================================================= -->
3156 <h3>
3157   <a name="terminators">Terminator Instructions</a>
3158 </h3>
3159
3160 <div>
3161
3162 <p>As mentioned <a href="#functionstructure">previously</a>, every basic block
3163    in a program ends with a "Terminator" instruction, which indicates which
3164    block should be executed after the current block is finished. These
3165    terminator instructions typically yield a '<tt>void</tt>' value: they produce
3166    control flow, not values (the one exception being the
3167    '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
3168
3169 <p>The terminator instructions are:
3170    '<a href="#i_ret"><tt>ret</tt></a>',
3171    '<a href="#i_br"><tt>br</tt></a>',
3172    '<a href="#i_switch"><tt>switch</tt></a>',
3173    '<a href="#i_indirectbr"><tt>indirectbr</tt></a>',
3174    '<a href="#i_invoke"><tt>invoke</tt></a>',
3175    '<a href="#i_unwind"><tt>unwind</tt></a>',
3176    '<a href="#i_resume"><tt>resume</tt></a>', and
3177    '<a href="#i_unreachable"><tt>unreachable</tt></a>'.</p>
3178
3179 <!-- _______________________________________________________________________ -->
3180 <h4>
3181   <a name="i_ret">'<tt>ret</tt>' Instruction</a>
3182 </h4>
3183
3184 <div>
3185
3186 <h5>Syntax:</h5>
3187 <pre>
3188   ret &lt;type&gt; &lt;value&gt;       <i>; Return a value from a non-void function</i>
3189   ret void                 <i>; Return from void function</i>
3190 </pre>
3191
3192 <h5>Overview:</h5>
3193 <p>The '<tt>ret</tt>' instruction is used to return control flow (and optionally
3194    a value) from a function back to the caller.</p>
3195
3196 <p>There are two forms of the '<tt>ret</tt>' instruction: one that returns a
3197    value and then causes control flow, and one that just causes control flow to
3198    occur.</p>
3199
3200 <h5>Arguments:</h5>
3201 <p>The '<tt>ret</tt>' instruction optionally accepts a single argument, the
3202    return value. The type of the return value must be a
3203    '<a href="#t_firstclass">first class</a>' type.</p>
3204
3205 <p>A function is not <a href="#wellformed">well formed</a> if it it has a
3206    non-void return type and contains a '<tt>ret</tt>' instruction with no return
3207    value or a return value with a type that does not match its type, or if it
3208    has a void return type and contains a '<tt>ret</tt>' instruction with a
3209    return value.</p>
3210
3211 <h5>Semantics:</h5>
3212 <p>When the '<tt>ret</tt>' instruction is executed, control flow returns back to
3213    the calling function's context.  If the caller is a
3214    "<a href="#i_call"><tt>call</tt></a>" instruction, execution continues at the
3215    instruction after the call.  If the caller was an
3216    "<a href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at
3217    the beginning of the "normal" destination block.  If the instruction returns
3218    a value, that value shall set the call or invoke instruction's return
3219    value.</p>
3220
3221 <h5>Example:</h5>
3222 <pre>
3223   ret i32 5                       <i>; Return an integer value of 5</i>
3224   ret void                        <i>; Return from a void function</i>
3225   ret { i32, i8 } { i32 4, i8 2 } <i>; Return a struct of values 4 and 2</i>
3226 </pre>
3227
3228 </div>
3229 <!-- _______________________________________________________________________ -->
3230 <h4>
3231   <a name="i_br">'<tt>br</tt>' Instruction</a>
3232 </h4>
3233
3234 <div>
3235
3236 <h5>Syntax:</h5>
3237 <pre>
3238   br i1 &lt;cond&gt;, label &lt;iftrue&gt;, label &lt;iffalse&gt;
3239   br label &lt;dest&gt;          <i>; Unconditional branch</i>
3240 </pre>
3241
3242 <h5>Overview:</h5>
3243 <p>The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
3244    different basic block in the current function.  There are two forms of this
3245    instruction, corresponding to a conditional branch and an unconditional
3246    branch.</p>
3247
3248 <h5>Arguments:</h5>
3249 <p>The conditional branch form of the '<tt>br</tt>' instruction takes a single
3250    '<tt>i1</tt>' value and two '<tt>label</tt>' values.  The unconditional form
3251    of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
3252    target.</p>
3253
3254 <h5>Semantics:</h5>
3255 <p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>i1</tt>'
3256    argument is evaluated.  If the value is <tt>true</tt>, control flows to the
3257    '<tt>iftrue</tt>' <tt>label</tt> argument.  If "cond" is <tt>false</tt>,
3258    control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p>
3259
3260 <h5>Example:</h5>
3261 <pre>
3262 Test:
3263   %cond = <a href="#i_icmp">icmp</a> eq i32 %a, %b
3264   br i1 %cond, label %IfEqual, label %IfUnequal
3265 IfEqual:
3266   <a href="#i_ret">ret</a> i32 1
3267 IfUnequal:
3268   <a href="#i_ret">ret</a> i32 0
3269 </pre>
3270
3271 </div>
3272
3273 <!-- _______________________________________________________________________ -->
3274 <h4>
3275    <a name="i_switch">'<tt>switch</tt>' Instruction</a>
3276 </h4>
3277
3278 <div>
3279
3280 <h5>Syntax:</h5>
3281 <pre>
3282   switch &lt;intty&gt; &lt;value&gt;, label &lt;defaultdest&gt; [ &lt;intty&gt; &lt;val&gt;, label &lt;dest&gt; ... ]
3283 </pre>
3284
3285 <h5>Overview:</h5>
3286 <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
3287    several different places.  It is a generalization of the '<tt>br</tt>'
3288    instruction, allowing a branch to occur to one of many possible
3289    destinations.</p>
3290
3291 <h5>Arguments:</h5>
3292 <p>The '<tt>switch</tt>' instruction uses three parameters: an integer
3293    comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination,
3294    and an array of pairs of comparison value constants and '<tt>label</tt>'s.
3295    The table is not allowed to contain duplicate constant entries.</p>
3296
3297 <h5>Semantics:</h5>
3298 <p>The <tt>switch</tt> instruction specifies a table of values and
3299    destinations. When the '<tt>switch</tt>' instruction is executed, this table
3300    is searched for the given value.  If the value is found, control flow is
3301    transferred to the corresponding destination; otherwise, control flow is
3302    transferred to the default destination.</p>
3303
3304 <h5>Implementation:</h5>
3305 <p>Depending on properties of the target machine and the particular
3306    <tt>switch</tt> instruction, this instruction may be code generated in
3307    different ways.  For example, it could be generated as a series of chained
3308    conditional branches or with a lookup table.</p>
3309
3310 <h5>Example:</h5>
3311 <pre>
3312  <i>; Emulate a conditional br instruction</i>
3313  %Val = <a href="#i_zext">zext</a> i1 %value to i32
3314  switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
3315
3316  <i>; Emulate an unconditional br instruction</i>
3317  switch i32 0, label %dest [ ]
3318
3319  <i>; Implement a jump table:</i>
3320  switch i32 %val, label %otherwise [ i32 0, label %onzero
3321                                      i32 1, label %onone
3322                                      i32 2, label %ontwo ]
3323 </pre>
3324
3325 </div>
3326
3327
3328 <!-- _______________________________________________________________________ -->
3329 <h4>
3330    <a name="i_indirectbr">'<tt>indirectbr</tt>' Instruction</a>
3331 </h4>
3332
3333 <div>
3334
3335 <h5>Syntax:</h5>
3336 <pre>
3337   indirectbr &lt;somety&gt;* &lt;address&gt;, [ label &lt;dest1&gt;, label &lt;dest2&gt;, ... ]
3338 </pre>
3339
3340 <h5>Overview:</h5>
3341
3342 <p>The '<tt>indirectbr</tt>' instruction implements an indirect branch to a label
3343    within the current function, whose address is specified by
3344    "<tt>address</tt>".  Address must be derived from a <a
3345    href="#blockaddress">blockaddress</a> constant.</p>
3346
3347 <h5>Arguments:</h5>
3348
3349 <p>The '<tt>address</tt>' argument is the address of the label to jump to.  The
3350    rest of the arguments indicate the full set of possible destinations that the
3351    address may point to.  Blocks are allowed to occur multiple times in the
3352    destination list, though this isn't particularly useful.</p>
3353
3354 <p>This destination list is required so that dataflow analysis has an accurate
3355    understanding of the CFG.</p>
3356
3357 <h5>Semantics:</h5>
3358
3359 <p>Control transfers to the block specified in the address argument.  All
3360    possible destination blocks must be listed in the label list, otherwise this
3361    instruction has undefined behavior.  This implies that jumps to labels
3362    defined in other functions have undefined behavior as well.</p>
3363
3364 <h5>Implementation:</h5>
3365
3366 <p>This is typically implemented with a jump through a register.</p>
3367
3368 <h5>Example:</h5>
3369 <pre>
3370  indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
3371 </pre>
3372
3373 </div>
3374
3375
3376 <!-- _______________________________________________________________________ -->
3377 <h4>
3378   <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
3379 </h4>
3380
3381 <div>
3382
3383 <h5>Syntax:</h5>
3384 <pre>
3385   &lt;result&gt; = invoke [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] &lt;ptr to function ty&gt; &lt;function ptr val&gt;(&lt;function args&gt;) [<a href="#fnattrs">fn attrs</a>]
3386                 to label &lt;normal label&gt; unwind label &lt;exception label&gt;
3387 </pre>
3388
3389 <h5>Overview:</h5>
3390 <p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified
3391    function, with the possibility of control flow transfer to either the
3392    '<tt>normal</tt>' label or the '<tt>exception</tt>' label.  If the callee
3393    function returns with the "<tt><a href="#i_ret">ret</a></tt>" instruction,
3394    control flow will return to the "normal" label.  If the callee (or any
3395    indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>"
3396    instruction, control is interrupted and continued at the dynamically nearest
3397    "exception" label.</p>
3398
3399 <p>The '<tt>exception</tt>' label is a
3400    <i><a href="ExceptionHandling.html#overview">landing pad</a></i> for the
3401    exception. As such, '<tt>exception</tt>' label is required to have the
3402    "<a href="#i_landingpad"><tt>landingpad</tt></a>" instruction, which contains
3403    the information about about the behavior of the program after unwinding
3404    happens, as its first non-PHI instruction. The restrictions on the
3405    "<tt>landingpad</tt>" instruction's tightly couples it to the
3406    "<tt>invoke</tt>" instruction, so that the important information contained
3407    within the "<tt>landingpad</tt>" instruction can't be lost through normal
3408    code motion.</p>
3409
3410 <h5>Arguments:</h5>
3411 <p>This instruction requires several arguments:</p>
3412
3413 <ol>
3414   <li>The optional "cconv" marker indicates which <a href="#callingconv">calling
3415       convention</a> the call should use.  If none is specified, the call
3416       defaults to using C calling conventions.</li>
3417
3418   <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
3419       return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
3420       '<tt>inreg</tt>' attributes are valid here.</li>
3421
3422   <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
3423       function value being invoked.  In most cases, this is a direct function
3424       invocation, but indirect <tt>invoke</tt>s are just as possible, branching
3425       off an arbitrary pointer to function value.</li>
3426
3427   <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
3428       function to be invoked. </li>
3429
3430   <li>'<tt>function args</tt>': argument list whose types match the function
3431       signature argument types and parameter attributes. All arguments must be
3432       of <a href="#t_firstclass">first class</a> type. If the function
3433       signature indicates the function accepts a variable number of arguments,
3434       the extra arguments can be specified.</li>
3435
3436   <li>'<tt>normal label</tt>': the label reached when the called function
3437       executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
3438
3439   <li>'<tt>exception label</tt>': the label reached when a callee returns with
3440       the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li>
3441
3442   <li>The optional <a href="#fnattrs">function attributes</a> list. Only
3443       '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
3444       '<tt>readnone</tt>' attributes are valid here.</li>
3445 </ol>
3446
3447 <h5>Semantics:</h5>
3448 <p>This instruction is designed to operate as a standard
3449    '<tt><a href="#i_call">call</a></tt>' instruction in most regards.  The
3450    primary difference is that it establishes an association with a label, which
3451    is used by the runtime library to unwind the stack.</p>
3452
3453 <p>This instruction is used in languages with destructors to ensure that proper
3454    cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
3455    exception.  Additionally, this is important for implementation of
3456    '<tt>catch</tt>' clauses in high-level languages that support them.</p>
3457
3458 <p>For the purposes of the SSA form, the definition of the value returned by the
3459    '<tt>invoke</tt>' instruction is deemed to occur on the edge from the current
3460    block to the "normal" label. If the callee unwinds then no return value is
3461    available.</p>
3462
3463 <p>Note that the code generator does not yet completely support unwind, and
3464 that the invoke/unwind semantics are likely to change in future versions.</p>
3465
3466 <h5>Example:</h5>
3467 <pre>
3468   %retval = invoke i32 @Test(i32 15) to label %Continue
3469               unwind label %TestCleanup              <i>; {i32}:retval set</i>
3470   %retval = invoke <a href="#callingconv">coldcc</a> i32 %Testfnptr(i32 15) to label %Continue
3471               unwind label %TestCleanup              <i>; {i32}:retval set</i>
3472 </pre>
3473
3474 </div>
3475
3476 <!-- _______________________________________________________________________ -->
3477
3478 <h4>
3479   <a name="i_unwind">'<tt>unwind</tt>' Instruction</a>
3480 </h4>
3481
3482 <div>
3483
3484 <h5>Syntax:</h5>
3485 <pre>
3486   unwind
3487 </pre>
3488
3489 <h5>Overview:</h5>
3490 <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow
3491    at the first callee in the dynamic call stack which used
3492    an <a href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call.
3493    This is primarily used to implement exception handling.</p>
3494
3495 <h5>Semantics:</h5>
3496 <p>The '<tt>unwind</tt>' instruction causes execution of the current function to
3497    immediately halt.  The dynamic call stack is then searched for the
3498    first <a href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack.
3499    Once found, execution continues at the "exceptional" destination block
3500    specified by the <tt>invoke</tt> instruction.  If there is no <tt>invoke</tt>
3501    instruction in the dynamic call chain, undefined behavior results.</p>
3502
3503 <p>Note that the code generator does not yet completely support unwind, and
3504 that the invoke/unwind semantics are likely to change in future versions.</p>
3505
3506 </div>
3507
3508  <!-- _______________________________________________________________________ -->
3509
3510 <h4>
3511   <a name="i_resume">'<tt>resume</tt>' Instruction</a>
3512 </h4>
3513
3514 <div>
3515
3516 <h5>Syntax:</h5>
3517 <pre>
3518   resume &lt;type&gt; &lt;value&gt;
3519 </pre>
3520
3521 <h5>Overview:</h5>
3522 <p>The '<tt>resume</tt>' instruction is a terminator instruction that has no
3523    successors.</p>
3524
3525 <h5>Arguments:</h5>
3526 <p>The '<tt>resume</tt>' instruction requires one argument, which must have the
3527    same type as the result of any '<tt>landingpad</tt>' instruction in the same
3528    function.</p>
3529
3530 <h5>Semantics:</h5>
3531 <p>The '<tt>resume</tt>' instruction resumes propagation of an existing
3532    (in-flight) exception whose unwinding was interrupted with
3533    a <a href="#i_landingpad"><tt>landingpad</tt></a> instruction.</p>
3534
3535 <h5>Example:</h5>
3536 <pre>
3537   resume { i8*, i32 } %exn
3538 </pre>
3539
3540 </div>
3541
3542 <!-- _______________________________________________________________________ -->
3543
3544 <h4>
3545   <a name="i_unreachable">'<tt>unreachable</tt>' Instruction</a>
3546 </h4>
3547
3548 <div>
3549
3550 <h5>Syntax:</h5>
3551 <pre>
3552   unreachable
3553 </pre>
3554
3555 <h5>Overview:</h5>
3556 <p>The '<tt>unreachable</tt>' instruction has no defined semantics.  This
3557    instruction is used to inform the optimizer that a particular portion of the
3558    code is not reachable.  This can be used to indicate that the code after a
3559    no-return function cannot be reached, and other facts.</p>
3560
3561 <h5>Semantics:</h5>
3562 <p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p>
3563
3564 </div>
3565
3566 </div>
3567
3568 <!-- ======================================================================= -->
3569 <h3>
3570   <a name="binaryops">Binary Operations</a>
3571 </h3>
3572
3573 <div>
3574
3575 <p>Binary operators are used to do most of the computation in a program.  They
3576    require two operands of the same type, execute an operation on them, and
3577    produce a single value.  The operands might represent multiple data, as is
3578    the case with the <a href="#t_vector">vector</a> data type.  The result value
3579    has the same type as its operands.</p>
3580
3581 <p>There are several different binary operators:</p>
3582
3583 <!-- _______________________________________________________________________ -->
3584 <h4>
3585   <a name="i_add">'<tt>add</tt>' Instruction</a>
3586 </h4>
3587
3588 <div>
3589
3590 <h5>Syntax:</h5>
3591 <pre>
3592   &lt;result&gt; = add &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;          <i>; yields {ty}:result</i>
3593   &lt;result&gt; = add nuw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3594   &lt;result&gt; = add nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3595   &lt;result&gt; = add nuw nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;  <i>; yields {ty}:result</i>
3596 </pre>
3597
3598 <h5>Overview:</h5>
3599 <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
3600
3601 <h5>Arguments:</h5>
3602 <p>The two arguments to the '<tt>add</tt>' instruction must
3603    be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
3604    integer values. Both arguments must have identical types.</p>
3605
3606 <h5>Semantics:</h5>
3607 <p>The value produced is the integer sum of the two operands.</p>
3608
3609 <p>If the sum has unsigned overflow, the result returned is the mathematical
3610    result modulo 2<sup>n</sup>, where n is the bit width of the result.</p>
3611
3612 <p>Because LLVM integers use a two's complement representation, this instruction
3613    is appropriate for both signed and unsigned integers.</p>
3614
3615 <p><tt>nuw</tt> and <tt>nsw</tt> stand for &quot;No Unsigned Wrap&quot;
3616    and &quot;No Signed Wrap&quot;, respectively. If the <tt>nuw</tt> and/or
3617    <tt>nsw</tt> keywords are present, the result value of the <tt>add</tt>
3618    is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
3619    respectively, occurs.</p>
3620
3621 <h5>Example:</h5>
3622 <pre>
3623   &lt;result&gt; = add i32 4, %var          <i>; yields {i32}:result = 4 + %var</i>
3624 </pre>
3625
3626 </div>
3627
3628 <!-- _______________________________________________________________________ -->
3629 <h4>
3630   <a name="i_fadd">'<tt>fadd</tt>' Instruction</a>
3631 </h4>
3632
3633 <div>
3634
3635 <h5>Syntax:</h5>
3636 <pre>
3637   &lt;result&gt; = fadd &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3638 </pre>
3639
3640 <h5>Overview:</h5>
3641 <p>The '<tt>fadd</tt>' instruction returns the sum of its two operands.</p>
3642
3643 <h5>Arguments:</h5>
3644 <p>The two arguments to the '<tt>fadd</tt>' instruction must be
3645    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3646    floating point values. Both arguments must have identical types.</p>
3647
3648 <h5>Semantics:</h5>
3649 <p>The value produced is the floating point sum of the two operands.</p>
3650
3651 <h5>Example:</h5>
3652 <pre>
3653   &lt;result&gt; = fadd float 4.0, %var          <i>; yields {float}:result = 4.0 + %var</i>
3654 </pre>
3655
3656 </div>
3657
3658 <!-- _______________________________________________________________________ -->
3659 <h4>
3660    <a name="i_sub">'<tt>sub</tt>' Instruction</a>
3661 </h4>
3662
3663 <div>
3664
3665 <h5>Syntax:</h5>
3666 <pre>
3667   &lt;result&gt; = sub &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;          <i>; yields {ty}:result</i>
3668   &lt;result&gt; = sub nuw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3669   &lt;result&gt; = sub nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3670   &lt;result&gt; = sub nuw nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;  <i>; yields {ty}:result</i>
3671 </pre>
3672
3673 <h5>Overview:</h5>
3674 <p>The '<tt>sub</tt>' instruction returns the difference of its two
3675    operands.</p>
3676
3677 <p>Note that the '<tt>sub</tt>' instruction is used to represent the
3678    '<tt>neg</tt>' instruction present in most other intermediate
3679    representations.</p>
3680
3681 <h5>Arguments:</h5>
3682 <p>The two arguments to the '<tt>sub</tt>' instruction must
3683    be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
3684    integer values.  Both arguments must have identical types.</p>
3685
3686 <h5>Semantics:</h5>
3687 <p>The value produced is the integer difference of the two operands.</p>
3688
3689 <p>If the difference has unsigned overflow, the result returned is the
3690    mathematical result modulo 2<sup>n</sup>, where n is the bit width of the
3691    result.</p>
3692
3693 <p>Because LLVM integers use a two's complement representation, this instruction
3694    is appropriate for both signed and unsigned integers.</p>
3695
3696 <p><tt>nuw</tt> and <tt>nsw</tt> stand for &quot;No Unsigned Wrap&quot;
3697    and &quot;No Signed Wrap&quot;, respectively. If the <tt>nuw</tt> and/or
3698    <tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt>
3699    is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
3700    respectively, occurs.</p>
3701
3702 <h5>Example:</h5>
3703 <pre>
3704   &lt;result&gt; = sub i32 4, %var          <i>; yields {i32}:result = 4 - %var</i>
3705   &lt;result&gt; = sub i32 0, %val          <i>; yields {i32}:result = -%var</i>
3706 </pre>
3707
3708 </div>
3709
3710 <!-- _______________________________________________________________________ -->
3711 <h4>
3712    <a name="i_fsub">'<tt>fsub</tt>' Instruction</a>
3713 </h4>
3714
3715 <div>
3716
3717 <h5>Syntax:</h5>
3718 <pre>
3719   &lt;result&gt; = fsub &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3720 </pre>
3721
3722 <h5>Overview:</h5>
3723 <p>The '<tt>fsub</tt>' instruction returns the difference of its two
3724    operands.</p>
3725
3726 <p>Note that the '<tt>fsub</tt>' instruction is used to represent the
3727    '<tt>fneg</tt>' instruction present in most other intermediate
3728    representations.</p>
3729
3730 <h5>Arguments:</h5>
3731 <p>The two arguments to the '<tt>fsub</tt>' instruction must be
3732    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3733    floating point values.  Both arguments must have identical types.</p>
3734
3735 <h5>Semantics:</h5>
3736 <p>The value produced is the floating point difference of the two operands.</p>
3737
3738 <h5>Example:</h5>
3739 <pre>
3740   &lt;result&gt; = fsub float 4.0, %var           <i>; yields {float}:result = 4.0 - %var</i>
3741   &lt;result&gt; = fsub float -0.0, %val          <i>; yields {float}:result = -%var</i>
3742 </pre>
3743
3744 </div>
3745
3746 <!-- _______________________________________________________________________ -->
3747 <h4>
3748   <a name="i_mul">'<tt>mul</tt>' Instruction</a>
3749 </h4>
3750
3751 <div>
3752
3753 <h5>Syntax:</h5>
3754 <pre>
3755   &lt;result&gt; = mul &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;          <i>; yields {ty}:result</i>
3756   &lt;result&gt; = mul nuw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3757   &lt;result&gt; = mul nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3758   &lt;result&gt; = mul nuw nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;  <i>; yields {ty}:result</i>
3759 </pre>
3760
3761 <h5>Overview:</h5>
3762 <p>The '<tt>mul</tt>' instruction returns the product of its two operands.</p>
3763
3764 <h5>Arguments:</h5>
3765 <p>The two arguments to the '<tt>mul</tt>' instruction must
3766    be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
3767    integer values.  Both arguments must have identical types.</p>
3768
3769 <h5>Semantics:</h5>
3770 <p>The value produced is the integer product of the two operands.</p>
3771
3772 <p>If the result of the multiplication has unsigned overflow, the result
3773    returned is the mathematical result modulo 2<sup>n</sup>, where n is the bit
3774    width of the result.</p>
3775
3776 <p>Because LLVM integers use a two's complement representation, and the result
3777    is the same width as the operands, this instruction returns the correct
3778    result for both signed and unsigned integers.  If a full product
3779    (e.g. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands should
3780    be sign-extended or zero-extended as appropriate to the width of the full
3781    product.</p>
3782
3783 <p><tt>nuw</tt> and <tt>nsw</tt> stand for &quot;No Unsigned Wrap&quot;
3784    and &quot;No Signed Wrap&quot;, respectively. If the <tt>nuw</tt> and/or
3785    <tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt>
3786    is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
3787    respectively, occurs.</p>
3788
3789 <h5>Example:</h5>
3790 <pre>
3791   &lt;result&gt; = mul i32 4, %var          <i>; yields {i32}:result = 4 * %var</i>
3792 </pre>
3793
3794 </div>
3795
3796 <!-- _______________________________________________________________________ -->
3797 <h4>
3798   <a name="i_fmul">'<tt>fmul</tt>' Instruction</a>
3799 </h4>
3800
3801 <div>
3802
3803 <h5>Syntax:</h5>
3804 <pre>
3805   &lt;result&gt; = fmul &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3806 </pre>
3807
3808 <h5>Overview:</h5>
3809 <p>The '<tt>fmul</tt>' instruction returns the product of its two operands.</p>
3810
3811 <h5>Arguments:</h5>
3812 <p>The two arguments to the '<tt>fmul</tt>' instruction must be
3813    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3814    floating point values.  Both arguments must have identical types.</p>
3815
3816 <h5>Semantics:</h5>
3817 <p>The value produced is the floating point product of the two operands.</p>
3818
3819 <h5>Example:</h5>
3820 <pre>
3821   &lt;result&gt; = fmul float 4.0, %var          <i>; yields {float}:result = 4.0 * %var</i>
3822 </pre>
3823
3824 </div>
3825
3826 <!-- _______________________________________________________________________ -->
3827 <h4>
3828   <a name="i_udiv">'<tt>udiv</tt>' Instruction</a>
3829 </h4>
3830
3831 <div>
3832
3833 <h5>Syntax:</h5>
3834 <pre>
3835   &lt;result&gt; = udiv &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;         <i>; yields {ty}:result</i>
3836   &lt;result&gt; = udiv exact &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3837 </pre>
3838
3839 <h5>Overview:</h5>
3840 <p>The '<tt>udiv</tt>' instruction returns the quotient of its two operands.</p>
3841
3842 <h5>Arguments:</h5>
3843 <p>The two arguments to the '<tt>udiv</tt>' instruction must be
3844    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3845    values.  Both arguments must have identical types.</p>
3846
3847 <h5>Semantics:</h5>
3848 <p>The value produced is the unsigned integer quotient of the two operands.</p>
3849
3850 <p>Note that unsigned integer division and signed integer division are distinct
3851    operations; for signed integer division, use '<tt>sdiv</tt>'.</p>
3852
3853 <p>Division by zero leads to undefined behavior.</p>
3854
3855 <p>If the <tt>exact</tt> keyword is present, the result value of the
3856    <tt>udiv</tt> is a <a href="#trapvalues">trap value</a> if %op1 is not a
3857   multiple of %op2 (as such, "((a udiv exact b) mul b) == a").</p>
3858
3859
3860 <h5>Example:</h5>
3861 <pre>
3862   &lt;result&gt; = udiv i32 4, %var          <i>; yields {i32}:result = 4 / %var</i>
3863 </pre>
3864
3865 </div>
3866
3867 <!-- _______________________________________________________________________ -->
3868 <h4>
3869   <a name="i_sdiv">'<tt>sdiv</tt>' Instruction</a>
3870 </h4>
3871
3872 <div>
3873
3874 <h5>Syntax:</h5>
3875 <pre>
3876   &lt;result&gt; = sdiv &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;         <i>; yields {ty}:result</i>
3877   &lt;result&gt; = sdiv exact &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3878 </pre>
3879
3880 <h5>Overview:</h5>
3881 <p>The '<tt>sdiv</tt>' instruction returns the quotient of its two operands.</p>
3882
3883 <h5>Arguments:</h5>
3884 <p>The two arguments to the '<tt>sdiv</tt>' instruction must be
3885    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3886    values.  Both arguments must have identical types.</p>
3887
3888 <h5>Semantics:</h5>
3889 <p>The value produced is the signed integer quotient of the two operands rounded
3890    towards zero.</p>
3891
3892 <p>Note that signed integer division and unsigned integer division are distinct
3893    operations; for unsigned integer division, use '<tt>udiv</tt>'.</p>
3894
3895 <p>Division by zero leads to undefined behavior. Overflow also leads to
3896    undefined behavior; this is a rare case, but can occur, for example, by doing
3897    a 32-bit division of -2147483648 by -1.</p>
3898
3899 <p>If the <tt>exact</tt> keyword is present, the result value of the
3900    <tt>sdiv</tt> is a <a href="#trapvalues">trap value</a> if the result would
3901    be rounded.</p>
3902
3903 <h5>Example:</h5>
3904 <pre>
3905   &lt;result&gt; = sdiv i32 4, %var          <i>; yields {i32}:result = 4 / %var</i>
3906 </pre>
3907
3908 </div>
3909
3910 <!-- _______________________________________________________________________ -->
3911 <h4>
3912   <a name="i_fdiv">'<tt>fdiv</tt>' Instruction</a>
3913 </h4>
3914
3915 <div>
3916
3917 <h5>Syntax:</h5>
3918 <pre>
3919   &lt;result&gt; = fdiv &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3920 </pre>
3921
3922 <h5>Overview:</h5>
3923 <p>The '<tt>fdiv</tt>' instruction returns the quotient of its two operands.</p>
3924
3925 <h5>Arguments:</h5>
3926 <p>The two arguments to the '<tt>fdiv</tt>' instruction must be
3927    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3928    floating point values.  Both arguments must have identical types.</p>
3929
3930 <h5>Semantics:</h5>
3931 <p>The value produced is the floating point quotient of the two operands.</p>
3932
3933 <h5>Example:</h5>
3934 <pre>
3935   &lt;result&gt; = fdiv float 4.0, %var          <i>; yields {float}:result = 4.0 / %var</i>
3936 </pre>
3937
3938 </div>
3939
3940 <!-- _______________________________________________________________________ -->
3941 <h4>
3942   <a name="i_urem">'<tt>urem</tt>' Instruction</a>
3943 </h4>
3944
3945 <div>
3946
3947 <h5>Syntax:</h5>
3948 <pre>
3949   &lt;result&gt; = urem &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3950 </pre>
3951
3952 <h5>Overview:</h5>
3953 <p>The '<tt>urem</tt>' instruction returns the remainder from the unsigned
3954    division of its two arguments.</p>
3955
3956 <h5>Arguments:</h5>
3957 <p>The two arguments to the '<tt>urem</tt>' instruction must be
3958    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3959    values.  Both arguments must have identical types.</p>
3960
3961 <h5>Semantics:</h5>
3962 <p>This instruction returns the unsigned integer <i>remainder</i> of a division.
3963    This instruction always performs an unsigned division to get the
3964    remainder.</p>
3965
3966 <p>Note that unsigned integer remainder and signed integer remainder are
3967    distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p>
3968
3969 <p>Taking the remainder of a division by zero leads to undefined behavior.</p>
3970
3971 <h5>Example:</h5>
3972 <pre>
3973   &lt;result&gt; = urem i32 4, %var          <i>; yields {i32}:result = 4 % %var</i>
3974 </pre>
3975
3976 </div>
3977
3978 <!-- _______________________________________________________________________ -->
3979 <h4>
3980   <a name="i_srem">'<tt>srem</tt>' Instruction</a>
3981 </h4>
3982
3983 <div>
3984
3985 <h5>Syntax:</h5>
3986 <pre>
3987   &lt;result&gt; = srem &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3988 </pre>
3989
3990 <h5>Overview:</h5>
3991 <p>The '<tt>srem</tt>' instruction returns the remainder from the signed
3992    division of its two operands. This instruction can also take
3993    <a href="#t_vector">vector</a> versions of the values in which case the
3994    elements must be integers.</p>
3995
3996 <h5>Arguments:</h5>
3997 <p>The two arguments to the '<tt>srem</tt>' instruction must be
3998    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3999    values.  Both arguments must have identical types.</p>
4000
4001 <h5>Semantics:</h5>
4002 <p>This instruction returns the <i>remainder</i> of a division (where the result
4003    is either zero or has the same sign as the dividend, <tt>op1</tt>), not the
4004    <i>modulo</i> operator (where the result is either zero or has the same sign
4005    as the divisor, <tt>op2</tt>) of a value.
4006    For more information about the difference,
4007    see <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
4008    Math Forum</a>. For a table of how this is implemented in various languages,
4009    please see <a href="http://en.wikipedia.org/wiki/Modulo_operation">
4010    Wikipedia: modulo operation</a>.</p>
4011
4012 <p>Note that signed integer remainder and unsigned integer remainder are
4013    distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p>
4014
4015 <p>Taking the remainder of a division by zero leads to undefined behavior.
4016    Overflow also leads to undefined behavior; this is a rare case, but can
4017    occur, for example, by taking the remainder of a 32-bit division of
4018    -2147483648 by -1.  (The remainder doesn't actually overflow, but this rule
4019    lets srem be implemented using instructions that return both the result of
4020    the division and the remainder.)</p>
4021
4022 <h5>Example:</h5>
4023 <pre>
4024   &lt;result&gt; = srem i32 4, %var          <i>; yields {i32}:result = 4 % %var</i>
4025 </pre>
4026
4027 </div>
4028
4029 <!-- _______________________________________________________________________ -->
4030 <h4>
4031   <a name="i_frem">'<tt>frem</tt>' Instruction</a>
4032 </h4>
4033
4034 <div>
4035
4036 <h5>Syntax:</h5>
4037 <pre>
4038   &lt;result&gt; = frem &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
4039 </pre>
4040
4041 <h5>Overview:</h5>
4042 <p>The '<tt>frem</tt>' instruction returns the remainder from the division of
4043    its two operands.</p>
4044
4045 <h5>Arguments:</h5>
4046 <p>The two arguments to the '<tt>frem</tt>' instruction must be
4047    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
4048    floating point values.  Both arguments must have identical types.</p>
4049
4050 <h5>Semantics:</h5>
4051 <p>This instruction returns the <i>remainder</i> of a division.  The remainder
4052    has the same sign as the dividend.</p>
4053
4054 <h5>Example:</h5>
4055 <pre>
4056   &lt;result&gt; = frem float 4.0, %var          <i>; yields {float}:result = 4.0 % %var</i>
4057 </pre>
4058
4059 </div>
4060
4061 </div>
4062
4063 <!-- ======================================================================= -->
4064 <h3>
4065   <a name="bitwiseops">Bitwise Binary Operations</a>
4066 </h3>
4067
4068 <div>
4069
4070 <p>Bitwise binary operators are used to do various forms of bit-twiddling in a
4071    program.  They are generally very efficient instructions and can commonly be
4072    strength reduced from other instructions.  They require two operands of the
4073    same type, execute an operation on them, and produce a single value.  The
4074    resulting value is the same type as its operands.</p>
4075
4076 <!-- _______________________________________________________________________ -->
4077 <h4>
4078   <a name="i_shl">'<tt>shl</tt>' Instruction</a>
4079 </h4>
4080
4081 <div>
4082
4083 <h5>Syntax:</h5>
4084 <pre>
4085   &lt;result&gt; = shl &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;           <i>; yields {ty}:result</i>
4086   &lt;result&gt; = shl nuw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;       <i>; yields {ty}:result</i>
4087   &lt;result&gt; = shl nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;       <i>; yields {ty}:result</i>
4088   &lt;result&gt; = shl nuw nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
4089 </pre>
4090
4091 <h5>Overview:</h5>
4092 <p>The '<tt>shl</tt>' instruction returns the first operand shifted to the left
4093    a specified number of bits.</p>
4094
4095 <h5>Arguments:</h5>
4096 <p>Both arguments to the '<tt>shl</tt>' instruction must be the
4097     same <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
4098     integer type.  '<tt>op2</tt>' is treated as an unsigned value.</p>
4099
4100 <h5>Semantics:</h5>
4101 <p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod
4102    2<sup>n</sup>, where <tt>n</tt> is the width of the result.  If <tt>op2</tt>
4103    is (statically or dynamically) negative or equal to or larger than the number
4104    of bits in <tt>op1</tt>, the result is undefined.  If the arguments are
4105    vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
4106    shift amount in <tt>op2</tt>.</p>
4107
4108 <p>If the <tt>nuw</tt> keyword is present, then the shift produces a
4109    <a href="#trapvalues">trap value</a> if it shifts out any non-zero bits.  If
4110    the <tt>nsw</tt> keyword is present, then the shift produces a
4111    <a href="#trapvalues">trap value</a> if it shifts out any bits that disagree
4112    with the resultant sign bit.  As such, NUW/NSW have the same semantics as
4113    they would if the shift were expressed as a mul instruction with the same
4114    nsw/nuw bits in (mul %op1, (shl 1, %op2)).</p>
4115
4116 <h5>Example:</h5>
4117 <pre>
4118   &lt;result&gt; = shl i32 4, %var   <i>; yields {i32}: 4 &lt;&lt; %var</i>
4119   &lt;result&gt; = shl i32 4, 2      <i>; yields {i32}: 16</i>
4120   &lt;result&gt; = shl i32 1, 10     <i>; yields {i32}: 1024</i>
4121   &lt;result&gt; = shl i32 1, 32     <i>; undefined</i>
4122   &lt;result&gt; = shl &lt;2 x i32&gt; &lt; i32 1, i32 1&gt;, &lt; i32 1, i32 2&gt;   <i>; yields: result=&lt;2 x i32&gt; &lt; i32 2, i32 4&gt;</i>
4123 </pre>
4124
4125 </div>
4126
4127 <!-- _______________________________________________________________________ -->
4128 <h4>
4129   <a name="i_lshr">'<tt>lshr</tt>' Instruction</a>
4130 </h4>
4131
4132 <div>
4133
4134 <h5>Syntax:</h5>
4135 <pre>
4136   &lt;result&gt; = lshr &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;         <i>; yields {ty}:result</i>
4137   &lt;result&gt; = lshr exact &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
4138 </pre>
4139
4140 <h5>Overview:</h5>
4141 <p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first
4142    operand shifted to the right a specified number of bits with zero fill.</p>
4143
4144 <h5>Arguments:</h5>
4145 <p>Both arguments to the '<tt>lshr</tt>' instruction must be the same
4146    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
4147    type. '<tt>op2</tt>' is treated as an unsigned value.</p>
4148
4149 <h5>Semantics:</h5>
4150 <p>This instruction always performs a logical shift right operation. The most
4151    significant bits of the result will be filled with zero bits after the shift.
4152    If <tt>op2</tt> is (statically or dynamically) equal to or larger than the
4153    number of bits in <tt>op1</tt>, the result is undefined. If the arguments are
4154    vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
4155    shift amount in <tt>op2</tt>.</p>
4156
4157 <p>If the <tt>exact</tt> keyword is present, the result value of the
4158    <tt>lshr</tt> is a <a href="#trapvalues">trap value</a> if any of the bits
4159    shifted out are non-zero.</p>
4160
4161
4162 <h5>Example:</h5>
4163 <pre>
4164   &lt;result&gt; = lshr i32 4, 1   <i>; yields {i32}:result = 2</i>
4165   &lt;result&gt; = lshr i32 4, 2   <i>; yields {i32}:result = 1</i>
4166   &lt;result&gt; = lshr i8  4, 3   <i>; yields {i8}:result = 0</i>
4167   &lt;result&gt; = lshr i8 -2, 1   <i>; yields {i8}:result = 0x7FFFFFFF </i>
4168   &lt;result&gt; = lshr i32 1, 32  <i>; undefined</i>
4169   &lt;result&gt; = lshr &lt;2 x i32&gt; &lt; i32 -2, i32 4&gt;, &lt; i32 1, i32 2&gt;   <i>; yields: result=&lt;2 x i32&gt; &lt; i32 0x7FFFFFFF, i32 1&gt;</i>
4170 </pre>
4171
4172 </div>
4173
4174 <!-- _______________________________________________________________________ -->
4175 <h4>
4176   <a name="i_ashr">'<tt>ashr</tt>' Instruction</a>
4177 </h4>
4178
4179 <div>
4180
4181 <h5>Syntax:</h5>
4182 <pre>
4183   &lt;result&gt; = ashr &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;         <i>; yields {ty}:result</i>
4184   &lt;result&gt; = ashr exact &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
4185 </pre>
4186
4187 <h5>Overview:</h5>
4188 <p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first
4189    operand shifted to the right a specified number of bits with sign
4190    extension.</p>
4191
4192 <h5>Arguments:</h5>
4193 <p>Both arguments to the '<tt>ashr</tt>' instruction must be the same
4194    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
4195    type.  '<tt>op2</tt>' is treated as an unsigned value.</p>
4196
4197 <h5>Semantics:</h5>
4198 <p>This instruction always performs an arithmetic shift right operation, The
4199    most significant bits of the result will be filled with the sign bit
4200    of <tt>op1</tt>.  If <tt>op2</tt> is (statically or dynamically) equal to or
4201    larger than the number of bits in <tt>op1</tt>, the result is undefined. If
4202    the arguments are vectors, each vector element of <tt>op1</tt> is shifted by
4203    the corresponding shift amount in <tt>op2</tt>.</p>
4204
4205 <p>If the <tt>exact</tt> keyword is present, the result value of the
4206    <tt>ashr</tt> is a <a href="#trapvalues">trap value</a> if any of the bits
4207    shifted out are non-zero.</p>
4208
4209 <h5>Example:</h5>
4210 <pre>
4211   &lt;result&gt; = ashr i32 4, 1   <i>; yields {i32}:result = 2</i>
4212   &lt;result&gt; = ashr i32 4, 2   <i>; yields {i32}:result = 1</i>
4213   &lt;result&gt; = ashr i8  4, 3   <i>; yields {i8}:result = 0</i>
4214   &lt;result&gt; = ashr i8 -2, 1   <i>; yields {i8}:result = -1</i>
4215   &lt;result&gt; = ashr i32 1, 32  <i>; undefined</i>
4216   &lt;result&gt; = ashr &lt;2 x i32&gt; &lt; i32 -2, i32 4&gt;, &lt; i32 1, i32 3&gt;   <i>; yields: result=&lt;2 x i32&gt; &lt; i32 -1, i32 0&gt;</i>
4217 </pre>
4218
4219 </div>
4220
4221 <!-- _______________________________________________________________________ -->
4222 <h4>
4223   <a name="i_and">'<tt>and</tt>' Instruction</a>
4224 </h4>
4225
4226 <div>
4227
4228 <h5>Syntax:</h5>
4229 <pre>
4230   &lt;result&gt; = and &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
4231 </pre>
4232
4233 <h5>Overview:</h5>
4234 <p>The '<tt>and</tt>' instruction returns the bitwise logical and of its two
4235    operands.</p>
4236
4237 <h5>Arguments:</h5>
4238 <p>The two arguments to the '<tt>and</tt>' instruction must be
4239    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
4240    values.  Both arguments must have identical types.</p>
4241
4242 <h5>Semantics:</h5>
4243 <p>The truth table used for the '<tt>and</tt>' instruction is:</p>
4244
4245 <table border="1" cellspacing="0" cellpadding="4">
4246   <tbody>
4247     <tr>
4248       <td>In0</td>
4249       <td>In1</td>
4250       <td>Out</td>
4251     </tr>
4252     <tr>
4253       <td>0</td>
4254       <td>0</td>
4255       <td>0</td>
4256     </tr>
4257     <tr>
4258       <td>0</td>
4259       <td>1</td>
4260       <td>0</td>
4261     </tr>
4262     <tr>
4263       <td>1</td>
4264       <td>0</td>
4265       <td>0</td>
4266     </tr>
4267     <tr>
4268       <td>1</td>
4269       <td>1</td>
4270       <td>1</td>
4271     </tr>
4272   </tbody>
4273 </table>
4274
4275 <h5>Example:</h5>
4276 <pre>
4277   &lt;result&gt; = and i32 4, %var         <i>; yields {i32}:result = 4 &amp; %var</i>
4278   &lt;result&gt; = and i32 15, 40          <i>; yields {i32}:result = 8</i>
4279   &lt;result&gt; = and i32 4, 8            <i>; yields {i32}:result = 0</i>
4280 </pre>
4281 </div>
4282 <!-- _______________________________________________________________________ -->
4283 <h4>
4284   <a name="i_or">'<tt>or</tt>' Instruction</a>
4285 </h4>
4286
4287 <div>
4288
4289 <h5>Syntax:</h5>
4290 <pre>
4291   &lt;result&gt; = or &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
4292 </pre>
4293
4294 <h5>Overview:</h5>
4295 <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive or of its
4296    two operands.</p>
4297
4298 <h5>Arguments:</h5>
4299 <p>The two arguments to the '<tt>or</tt>' instruction must be
4300    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
4301    values.  Both arguments must have identical types.</p>
4302
4303 <h5>Semantics:</h5>
4304 <p>The truth table used for the '<tt>or</tt>' instruction is:</p>
4305
4306 <table border="1" cellspacing="0" cellpadding="4">
4307   <tbody>
4308     <tr>
4309       <td>In0</td>
4310       <td>In1</td>
4311       <td>Out</td>
4312     </tr>
4313     <tr>
4314       <td>0</td>
4315       <td>0</td>
4316       <td>0</td>
4317     </tr>
4318     <tr>
4319       <td>0</td>
4320       <td>1</td>
4321       <td>1</td>
4322     </tr>
4323     <tr>
4324       <td>1</td>
4325       <td>0</td>
4326       <td>1</td>
4327     </tr>
4328     <tr>
4329       <td>1</td>
4330       <td>1</td>
4331       <td>1</td>
4332     </tr>
4333   </tbody>
4334 </table>
4335
4336 <h5>Example:</h5>
4337 <pre>
4338   &lt;result&gt; = or i32 4, %var         <i>; yields {i32}:result = 4 | %var</i>
4339   &lt;result&gt; = or i32 15, 40          <i>; yields {i32}:result = 47</i>
4340   &lt;result&gt; = or i32 4, 8            <i>; yields {i32}:result = 12</i>
4341 </pre>
4342
4343 </div>
4344
4345 <!-- _______________________________________________________________________ -->
4346 <h4>
4347   <a name="i_xor">'<tt>xor</tt>' Instruction</a>
4348 </h4>
4349
4350 <div>
4351
4352 <h5>Syntax:</h5>
4353 <pre>
4354   &lt;result&gt; = xor &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
4355 </pre>
4356
4357 <h5>Overview:</h5>
4358 <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of
4359    its two operands.  The <tt>xor</tt> is used to implement the "one's
4360    complement" operation, which is the "~" operator in C.</p>
4361
4362 <h5>Arguments:</h5>
4363 <p>The two arguments to the '<tt>xor</tt>' instruction must be
4364    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
4365    values.  Both arguments must have identical types.</p>
4366
4367 <h5>Semantics:</h5>
4368 <p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
4369
4370 <table border="1" cellspacing="0" cellpadding="4">
4371   <tbody>
4372     <tr>
4373       <td>In0</td>
4374       <td>In1</td>
4375       <td>Out</td>
4376     </tr>
4377     <tr>
4378       <td>0</td>
4379       <td>0</td>
4380       <td>0</td>
4381     </tr>
4382     <tr>
4383       <td>0</td>
4384       <td>1</td>
4385       <td>1</td>
4386     </tr>
4387     <tr>
4388       <td>1</td>
4389       <td>0</td>
4390       <td>1</td>
4391     </tr>
4392     <tr>
4393       <td>1</td>
4394       <td>1</td>
4395       <td>0</td>
4396     </tr>
4397   </tbody>
4398 </table>
4399
4400 <h5>Example:</h5>
4401 <pre>
4402   &lt;result&gt; = xor i32 4, %var         <i>; yields {i32}:result = 4 ^ %var</i>
4403   &lt;result&gt; = xor i32 15, 40          <i>; yields {i32}:result = 39</i>
4404   &lt;result&gt; = xor i32 4, 8            <i>; yields {i32}:result = 12</i>
4405   &lt;result&gt; = xor i32 %V, -1          <i>; yields {i32}:result = ~%V</i>
4406 </pre>
4407
4408 </div>
4409
4410 </div>
4411
4412 <!-- ======================================================================= -->
4413 <h3>
4414   <a name="vectorops">Vector Operations</a>
4415 </h3>
4416
4417 <div>
4418
4419 <p>LLVM supports several instructions to represent vector operations in a
4420    target-independent manner.  These instructions cover the element-access and
4421    vector-specific operations needed to process vectors effectively.  While LLVM
4422    does directly support these vector operations, many sophisticated algorithms
4423    will want to use target-specific intrinsics to take full advantage of a
4424    specific target.</p>
4425
4426 <!-- _______________________________________________________________________ -->
4427 <h4>
4428    <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
4429 </h4>
4430
4431 <div>
4432
4433 <h5>Syntax:</h5>
4434 <pre>
4435   &lt;result&gt; = extractelement &lt;n x &lt;ty&gt;&gt; &lt;val&gt;, i32 &lt;idx&gt;    <i>; yields &lt;ty&gt;</i>
4436 </pre>
4437
4438 <h5>Overview:</h5>
4439 <p>The '<tt>extractelement</tt>' instruction extracts a single scalar element
4440    from a vector at a specified index.</p>
4441
4442
4443 <h5>Arguments:</h5>
4444 <p>The first operand of an '<tt>extractelement</tt>' instruction is a value
4445    of <a href="#t_vector">vector</a> type.  The second operand is an index
4446    indicating the position from which to extract the element.  The index may be
4447    a variable.</p>
4448
4449 <h5>Semantics:</h5>
4450 <p>The result is a scalar of the same type as the element type of
4451    <tt>val</tt>.  Its value is the value at position <tt>idx</tt> of
4452    <tt>val</tt>.  If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
4453    results are undefined.</p>
4454
4455 <h5>Example:</h5>
4456 <pre>
4457   &lt;result&gt; = extractelement &lt;4 x i32&gt; %vec, i32 0    <i>; yields i32</i>
4458 </pre>
4459
4460 </div>
4461
4462 <!-- _______________________________________________________________________ -->
4463 <h4>
4464    <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
4465 </h4>
4466
4467 <div>
4468
4469 <h5>Syntax:</h5>
4470 <pre>
4471   &lt;result&gt; = insertelement &lt;n x &lt;ty&gt;&gt; &lt;val&gt;, &lt;ty&gt; &lt;elt&gt;, i32 &lt;idx&gt;    <i>; yields &lt;n x &lt;ty&gt;&gt;</i>
4472 </pre>
4473
4474 <h5>Overview:</h5>
4475 <p>The '<tt>insertelement</tt>' instruction inserts a scalar element into a
4476    vector at a specified index.</p>
4477
4478 <h5>Arguments:</h5>
4479 <p>The first operand of an '<tt>insertelement</tt>' instruction is a value
4480    of <a href="#t_vector">vector</a> type.  The second operand is a scalar value
4481    whose type must equal the element type of the first operand.  The third
4482    operand is an index indicating the position at which to insert the value.
4483    The index may be a variable.</p>
4484
4485 <h5>Semantics:</h5>
4486 <p>The result is a vector of the same type as <tt>val</tt>.  Its element values
4487    are those of <tt>val</tt> except at position <tt>idx</tt>, where it gets the
4488    value <tt>elt</tt>.  If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
4489    results are undefined.</p>
4490
4491 <h5>Example:</h5>
4492 <pre>
4493   &lt;result&gt; = insertelement &lt;4 x i32&gt; %vec, i32 1, i32 0    <i>; yields &lt;4 x i32&gt;</i>
4494 </pre>
4495
4496 </div>
4497
4498 <!-- _______________________________________________________________________ -->
4499 <h4>
4500    <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
4501 </h4>
4502
4503 <div>
4504
4505 <h5>Syntax:</h5>
4506 <pre>
4507   &lt;result&gt; = shufflevector &lt;n x &lt;ty&gt;&gt; &lt;v1&gt;, &lt;n x &lt;ty&gt;&gt; &lt;v2&gt;, &lt;m x i32&gt; &lt;mask&gt;    <i>; yields &lt;m x &lt;ty&gt;&gt;</i>
4508 </pre>
4509
4510 <h5>Overview:</h5>
4511 <p>The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
4512    from two input vectors, returning a vector with the same element type as the
4513    input and length that is the same as the shuffle mask.</p>
4514
4515 <h5>Arguments:</h5>
4516 <p>The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
4517    with types that match each other. The third argument is a shuffle mask whose
4518    element type is always 'i32'.  The result of the instruction is a vector
4519    whose length is the same as the shuffle mask and whose element type is the
4520    same as the element type of the first two operands.</p>
4521
4522 <p>The shuffle mask operand is required to be a constant vector with either
4523    constant integer or undef values.</p>
4524
4525 <h5>Semantics:</h5>
4526 <p>The elements of the two input vectors are numbered from left to right across
4527    both of the vectors.  The shuffle mask operand specifies, for each element of
4528    the result vector, which element of the two input vectors the result element
4529    gets.  The element selector may be undef (meaning "don't care") and the
4530    second operand may be undef if performing a shuffle from only one vector.</p>
4531
4532 <h5>Example:</h5>
4533 <pre>
4534   &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2,
4535                           &lt;4 x i32&gt; &lt;i32 0, i32 4, i32 1, i32 5&gt;  <i>; yields &lt;4 x i32&gt;</i>
4536   &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; undef,
4537                           &lt;4 x i32&gt; &lt;i32 0, i32 1, i32 2, i32 3&gt;  <i>; yields &lt;4 x i32&gt;</i> - Identity shuffle.
4538   &lt;result&gt; = shufflevector &lt;8 x i32&gt; %v1, &lt;8 x i32&gt; undef,
4539                           &lt;4 x i32&gt; &lt;i32 0, i32 1, i32 2, i32 3&gt;  <i>; yields &lt;4 x i32&gt;</i>
4540   &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2,
4541                           &lt;8 x i32&gt; &lt;i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 &gt;  <i>; yields &lt;8 x i32&gt;</i>
4542 </pre>
4543
4544 </div>
4545
4546 </div>
4547
4548 <!-- ======================================================================= -->
4549 <h3>
4550   <a name="aggregateops">Aggregate Operations</a>
4551 </h3>
4552
4553 <div>
4554
4555 <p>LLVM supports several instructions for working with
4556   <a href="#t_aggregate">aggregate</a> values.</p>
4557
4558 <!-- _______________________________________________________________________ -->
4559 <h4>
4560    <a name="i_extractvalue">'<tt>extractvalue</tt>' Instruction</a>
4561 </h4>
4562
4563 <div>
4564
4565 <h5>Syntax:</h5>
4566 <pre>
4567   &lt;result&gt; = extractvalue &lt;aggregate type&gt; &lt;val&gt;, &lt;idx&gt;{, &lt;idx&gt;}*
4568 </pre>
4569
4570 <h5>Overview:</h5>
4571 <p>The '<tt>extractvalue</tt>' instruction extracts the value of a member field
4572    from an <a href="#t_aggregate">aggregate</a> value.</p>
4573
4574 <h5>Arguments:</h5>
4575 <p>The first operand of an '<tt>extractvalue</tt>' instruction is a value
4576    of <a href="#t_struct">struct</a> or
4577    <a href="#t_array">array</a> type.  The operands are constant indices to
4578    specify which value to extract in a similar manner as indices in a
4579    '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
4580    <p>The major differences to <tt>getelementptr</tt> indexing are:</p>
4581      <ul>
4582        <li>Since the value being indexed is not a pointer, the first index is
4583            omitted and assumed to be zero.</li>
4584        <li>At least one index must be specified.</li>
4585        <li>Not only struct indices but also array indices must be in
4586            bounds.</li>
4587      </ul>
4588
4589 <h5>Semantics:</h5>
4590 <p>The result is the value at the position in the aggregate specified by the
4591    index operands.</p>
4592
4593 <h5>Example:</h5>
4594 <pre>
4595   &lt;result&gt; = extractvalue {i32, float} %agg, 0    <i>; yields i32</i>
4596 </pre>
4597
4598 </div>
4599
4600 <!-- _______________________________________________________________________ -->
4601 <h4>
4602    <a name="i_insertvalue">'<tt>insertvalue</tt>' Instruction</a>
4603 </h4>
4604
4605 <div>
4606
4607 <h5>Syntax:</h5>
4608 <pre>
4609   &lt;result&gt; = insertvalue &lt;aggregate type&gt; &lt;val&gt;, &lt;ty&gt; &lt;elt&gt;, &lt;idx&gt;{, &lt;idx&gt;}*    <i>; yields &lt;aggregate type&gt;</i>
4610 </pre>
4611
4612 <h5>Overview:</h5>
4613 <p>The '<tt>insertvalue</tt>' instruction inserts a value into a member field
4614    in an <a href="#t_aggregate">aggregate</a> value.</p>
4615
4616 <h5>Arguments:</h5>
4617 <p>The first operand of an '<tt>insertvalue</tt>' instruction is a value
4618    of <a href="#t_struct">struct</a> or
4619    <a href="#t_array">array</a> type.  The second operand is a first-class
4620    value to insert.  The following operands are constant indices indicating
4621    the position at which to insert the value in a similar manner as indices in a
4622    '<tt><a href="#i_extractvalue">extractvalue</a></tt>' instruction.  The
4623    value to insert must have the same type as the value identified by the
4624    indices.</p>
4625
4626 <h5>Semantics:</h5>
4627 <p>The result is an aggregate of the same type as <tt>val</tt>.  Its value is
4628    that of <tt>val</tt> except that the value at the position specified by the
4629    indices is that of <tt>elt</tt>.</p>
4630
4631 <h5>Example:</h5>
4632 <pre>
4633   %agg1 = insertvalue {i32, float} undef, i32 1, 0              <i>; yields {i32 1, float undef}</i>
4634   %agg2 = insertvalue {i32, float} %agg1, float %val, 1         <i>; yields {i32 1, float %val}</i>
4635   %agg3 = insertvalue {i32, {float}} %agg1, float %val, 1, 0    <i>; yields {i32 1, float %val}</i>
4636 </pre>
4637
4638 </div>
4639
4640 </div>
4641
4642 <!-- ======================================================================= -->
4643 <h3>
4644   <a name="memoryops">Memory Access and Addressing Operations</a>
4645 </h3>
4646
4647 <div>
4648
4649 <p>A key design point of an SSA-based representation is how it represents
4650    memory.  In LLVM, no memory locations are in SSA form, which makes things
4651    very simple.  This section describes how to read, write, and allocate
4652    memory in LLVM.</p>
4653
4654 <!-- _______________________________________________________________________ -->
4655 <h4>
4656   <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
4657 </h4>
4658
4659 <div>
4660
4661 <h5>Syntax:</h5>
4662 <pre>
4663   &lt;result&gt; = alloca &lt;type&gt;[, &lt;ty&gt; &lt;NumElements&gt;][, align &lt;alignment&gt;]     <i>; yields {type*}:result</i>
4664 </pre>
4665
4666 <h5>Overview:</h5>
4667 <p>The '<tt>alloca</tt>' instruction allocates memory on the stack frame of the
4668    currently executing function, to be automatically released when this function
4669    returns to its caller. The object is always allocated in the generic address
4670    space (address space zero).</p>
4671
4672 <h5>Arguments:</h5>
4673 <p>The '<tt>alloca</tt>' instruction
4674    allocates <tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory on the
4675    runtime stack, returning a pointer of the appropriate type to the program.
4676    If "NumElements" is specified, it is the number of elements allocated,
4677    otherwise "NumElements" is defaulted to be one.  If a constant alignment is
4678    specified, the value result of the allocation is guaranteed to be aligned to
4679    at least that boundary.  If not specified, or if zero, the target can choose
4680    to align the allocation on any convenient boundary compatible with the
4681    type.</p>
4682
4683 <p>'<tt>type</tt>' may be any sized type.</p>
4684
4685 <h5>Semantics:</h5>
4686 <p>Memory is allocated; a pointer is returned.  The operation is undefined if
4687    there is insufficient stack space for the allocation.  '<tt>alloca</tt>'d
4688    memory is automatically released when the function returns.  The
4689    '<tt>alloca</tt>' instruction is commonly used to represent automatic
4690    variables that must have an address available.  When the function returns
4691    (either with the <tt><a href="#i_ret">ret</a></tt>
4692    or <tt><a href="#i_unwind">unwind</a></tt> instructions), the memory is
4693    reclaimed.  Allocating zero bytes is legal, but the result is undefined.</p>
4694
4695 <h5>Example:</h5>
4696 <pre>
4697   %ptr = alloca i32                             <i>; yields {i32*}:ptr</i>
4698   %ptr = alloca i32, i32 4                      <i>; yields {i32*}:ptr</i>
4699   %ptr = alloca i32, i32 4, align 1024          <i>; yields {i32*}:ptr</i>
4700   %ptr = alloca i32, align 1024                 <i>; yields {i32*}:ptr</i>
4701 </pre>
4702
4703 </div>
4704
4705 <!-- _______________________________________________________________________ -->
4706 <h4>
4707   <a name="i_load">'<tt>load</tt>' Instruction</a>
4708 </h4>
4709
4710 <div>
4711
4712 <h5>Syntax:</h5>
4713 <pre>
4714   &lt;result&gt; = load [volatile] &lt;ty&gt;* &lt;pointer&gt;[, align &lt;alignment&gt;][, !nontemporal !&lt;index&gt;]
4715   &lt;result&gt; = load atomic [volatile] &lt;ty&gt;* &lt;pointer&gt; [singlethread] &lt;ordering&gt;, align &lt;alignment&gt;
4716   !&lt;index&gt; = !{ i32 1 }
4717 </pre>
4718
4719 <h5>Overview:</h5>
4720 <p>The '<tt>load</tt>' instruction is used to read from memory.</p>
4721
4722 <h5>Arguments:</h5>
4723 <p>The argument to the '<tt>load</tt>' instruction specifies the memory address
4724    from which to load.  The pointer must point to
4725    a <a href="#t_firstclass">first class</a> type.  If the <tt>load</tt> is
4726    marked as <tt>volatile</tt>, then the optimizer is not allowed to modify the
4727    number or order of execution of this <tt>load</tt> with other <a
4728    href="#volatile">volatile operations</a>.</p>
4729
4730 <p>If the <code>load</code> is marked as <code>atomic</code>, it takes an extra
4731    <a href="#ordering">ordering</a> and optional <code>singlethread</code>
4732    argument.  The <code>release</code> and <code>acq_rel</code> orderings are
4733    not valid on <code>load</code> instructions.  Atomic loads produce <a
4734    href="#memorymodel">defined</a> results when they may see multiple atomic
4735    stores.  The type of the pointee must be an integer type whose bit width
4736    is a power of two greater than or equal to eight and less than or equal
4737    to a target-specific size limit. <code>align</code> must be explicitly
4738    specified on atomic loads, and the load has undefined behavior if the
4739    alignment is not set to a value which is at least the size in bytes of
4740    the pointee. <code>!nontemporal</code> does not have any defined semantics
4741    for atomic loads.</p>
4742
4743 <p>The optional constant <tt>align</tt> argument specifies the alignment of the
4744    operation (that is, the alignment of the memory address). A value of 0 or an
4745    omitted <tt>align</tt> argument means that the operation has the preferential
4746    alignment for the target. It is the responsibility of the code emitter to
4747    ensure that the alignment information is correct. Overestimating the
4748    alignment results in undefined behavior. Underestimating the alignment may
4749    produce less efficient code. An alignment of 1 is always safe.</p>
4750
4751 <p>The optional <tt>!nontemporal</tt> metadata must reference a single
4752    metatadata name &lt;index&gt; corresponding to a metadata node with
4753    one <tt>i32</tt> entry of value 1.  The existence of
4754    the <tt>!nontemporal</tt> metatadata on the instruction tells the optimizer
4755    and code generator that this load is not expected to be reused in the cache.
4756    The code generator may select special instructions to save cache bandwidth,
4757    such as the <tt>MOVNT</tt> instruction on x86.</p>
4758
4759 <h5>Semantics:</h5>
4760 <p>The location of memory pointed to is loaded.  If the value being loaded is of
4761    scalar type then the number of bytes read does not exceed the minimum number
4762    of bytes needed to hold all bits of the type.  For example, loading an
4763    <tt>i24</tt> reads at most three bytes.  When loading a value of a type like
4764    <tt>i20</tt> with a size that is not an integral number of bytes, the result
4765    is undefined if the value was not originally written using a store of the
4766    same type.</p>
4767
4768 <h5>Examples:</h5>
4769 <pre>
4770   %ptr = <a href="#i_alloca">alloca</a> i32                               <i>; yields {i32*}:ptr</i>
4771   <a href="#i_store">store</a> i32 3, i32* %ptr                          <i>; yields {void}</i>
4772   %val = load i32* %ptr                           <i>; yields {i32}:val = i32 3</i>
4773 </pre>
4774
4775 </div>
4776
4777 <!-- _______________________________________________________________________ -->
4778 <h4>
4779   <a name="i_store">'<tt>store</tt>' Instruction</a>
4780 </h4>
4781
4782 <div>
4783
4784 <h5>Syntax:</h5>
4785 <pre>
4786   store [volatile] &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;[, align &lt;alignment&gt;][, !nontemporal !&lt;index&gt;]                   <i>; yields {void}</i>
4787   store atomic [volatile] &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt; [singlethread] &lt;ordering&gt;, align &lt;alignment&gt;             <i>; yields {void}</i>
4788 </pre>
4789
4790 <h5>Overview:</h5>
4791 <p>The '<tt>store</tt>' instruction is used to write to memory.</p>
4792
4793 <h5>Arguments:</h5>
4794 <p>There are two arguments to the '<tt>store</tt>' instruction: a value to store
4795    and an address at which to store it.  The type of the
4796    '<tt>&lt;pointer&gt;</tt>' operand must be a pointer to
4797    the <a href="#t_firstclass">first class</a> type of the
4798    '<tt>&lt;value&gt;</tt>' operand. If the <tt>store</tt> is marked as
4799    <tt>volatile</tt>, then the optimizer is not allowed to modify the number or
4800    order of execution of this <tt>store</tt> with other <a
4801    href="#volatile">volatile operations</a>.</p>
4802
4803 <p>If the <code>store</code> is marked as <code>atomic</code>, it takes an extra
4804    <a href="#ordering">ordering</a> and optional <code>singlethread</code>
4805    argument.  The <code>acquire</code> and <code>acq_rel</code> orderings aren't
4806    valid on <code>store</code> instructions.  Atomic loads produce <a
4807    href="#memorymodel">defined</a> results when they may see multiple atomic
4808    stores. The type of the pointee must be an integer type whose bit width
4809    is a power of two greater than or equal to eight and less than or equal
4810    to a target-specific size limit. <code>align</code> must be explicitly
4811    specified on atomic stores, and the store has undefined behavior if the
4812    alignment is not set to a value which is at least the size in bytes of
4813    the pointee. <code>!nontemporal</code> does not have any defined semantics
4814    for atomic stores.</p>
4815
4816 <p>The optional constant "align" argument specifies the alignment of the
4817    operation (that is, the alignment of the memory address). A value of 0 or an
4818    omitted "align" argument means that the operation has the preferential
4819    alignment for the target. It is the responsibility of the code emitter to
4820    ensure that the alignment information is correct. Overestimating the
4821    alignment results in an undefined behavior. Underestimating the alignment may
4822    produce less efficient code. An alignment of 1 is always safe.</p>
4823
4824 <p>The optional !nontemporal metadata must reference a single metatadata
4825    name &lt;index&gt; corresponding to a metadata node with one i32 entry of
4826    value 1.  The existence of the !nontemporal metatadata on the
4827    instruction tells the optimizer and code generator that this load is
4828    not expected to be reused in the cache.  The code generator may
4829    select special instructions to save cache bandwidth, such as the
4830    MOVNT instruction on x86.</p>
4831
4832
4833 <h5>Semantics:</h5>
4834 <p>The contents of memory are updated to contain '<tt>&lt;value&gt;</tt>' at the
4835    location specified by the '<tt>&lt;pointer&gt;</tt>' operand.  If
4836    '<tt>&lt;value&gt;</tt>' is of scalar type then the number of bytes written
4837    does not exceed the minimum number of bytes needed to hold all bits of the
4838    type.  For example, storing an <tt>i24</tt> writes at most three bytes.  When
4839    writing a value of a type like <tt>i20</tt> with a size that is not an
4840    integral number of bytes, it is unspecified what happens to the extra bits
4841    that do not belong to the type, but they will typically be overwritten.</p>
4842
4843 <h5>Example:</h5>
4844 <pre>
4845   %ptr = <a href="#i_alloca">alloca</a> i32                               <i>; yields {i32*}:ptr</i>
4846   store i32 3, i32* %ptr                          <i>; yields {void}</i>
4847   %val = <a href="#i_load">load</a> i32* %ptr                           <i>; yields {i32}:val = i32 3</i>
4848 </pre>
4849
4850 </div>
4851
4852 <!-- _______________________________________________________________________ -->
4853 <h4>
4854 <a name="i_fence">'<tt>fence</tt>' Instruction</a>
4855 </h4>
4856
4857 <div>
4858
4859 <h5>Syntax:</h5>
4860 <pre>
4861   fence [singlethread] &lt;ordering&gt;                   <i>; yields {void}</i>
4862 </pre>
4863
4864 <h5>Overview:</h5>
4865 <p>The '<tt>fence</tt>' instruction is used to introduce happens-before edges
4866 between operations.</p>
4867
4868 <h5>Arguments:</h5> <p>'<code>fence</code>' instructions take an <a
4869 href="#ordering">ordering</a> argument which defines what
4870 <i>synchronizes-with</i> edges they add.  They can only be given
4871 <code>acquire</code>, <code>release</code>, <code>acq_rel</code>, and
4872 <code>seq_cst</code> orderings.</p>
4873
4874 <h5>Semantics:</h5>
4875 <p>A fence <var>A</var> which has (at least) <code>release</code> ordering
4876 semantics <i>synchronizes with</i> a fence <var>B</var> with (at least)
4877 <code>acquire</code> ordering semantics if and only if there exist atomic
4878 operations <var>X</var> and <var>Y</var>, both operating on some atomic object
4879 <var>M</var>, such that <var>A</var> is sequenced before <var>X</var>,
4880 <var>X</var> modifies <var>M</var> (either directly or through some side effect
4881 of a sequence headed by <var>X</var>), <var>Y</var> is sequenced before
4882 <var>B</var>, and <var>Y</var> observes <var>M</var>. This provides a
4883 <i>happens-before</i> dependency between <var>A</var> and <var>B</var>. Rather
4884 than an explicit <code>fence</code>, one (but not both) of the atomic operations
4885 <var>X</var> or <var>Y</var> might provide a <code>release</code> or
4886 <code>acquire</code> (resp.) ordering constraint and still
4887 <i>synchronize-with</i> the explicit <code>fence</code> and establish the
4888 <i>happens-before</i> edge.</p>
4889
4890 <p>A <code>fence</code> which has <code>seq_cst</code> ordering, in addition to
4891 having both <code>acquire</code> and <code>release</code> semantics specified
4892 above, participates in the global program order of other <code>seq_cst</code>
4893 operations and/or fences.</p>
4894
4895 <p>The optional "<a href="#singlethread"><code>singlethread</code></a>" argument
4896 specifies that the fence only synchronizes with other fences in the same
4897 thread.  (This is useful for interacting with signal handlers.)</p>
4898
4899 <h5>Example:</h5>
4900 <pre>
4901   fence acquire                          <i>; yields {void}</i>
4902   fence singlethread seq_cst             <i>; yields {void}</i>
4903 </pre>
4904
4905 </div>
4906
4907 <!-- _______________________________________________________________________ -->
4908 <h4>
4909 <a name="i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a>
4910 </h4>
4911
4912 <div>
4913
4914 <h5>Syntax:</h5>
4915 <pre>
4916   cmpxchg [volatile] &lt;ty&gt;* &lt;pointer&gt;, &lt;ty&gt; &lt;cmp&gt;, &lt;ty&gt; &lt;new&gt; [singlethread] &lt;ordering&gt;                   <i>; yields {ty}</i>
4917 </pre>
4918
4919 <h5>Overview:</h5>
4920 <p>The '<tt>cmpxchg</tt>' instruction is used to atomically modify memory.
4921 It loads a value in memory and compares it to a given value. If they are
4922 equal, it stores a new value into the memory.</p>
4923
4924 <h5>Arguments:</h5>
4925 <p>There are three arguments to the '<code>cmpxchg</code>' instruction: an
4926 address to operate on, a value to compare to the value currently be at that
4927 address, and a new value to place at that address if the compared values are
4928 equal.  The type of '<var>&lt;cmp&gt;</var>' must be an integer type whose
4929 bit width is a power of two greater than or equal to eight and less than
4930 or equal to a target-specific size limit. '<var>&lt;cmp&gt;</var>' and
4931 '<var>&lt;new&gt;</var>' must have the same type, and the type of
4932 '<var>&lt;pointer&gt;</var>' must be a pointer to that type. If the
4933 <code>cmpxchg</code> is marked as <code>volatile</code>, then the
4934 optimizer is not allowed to modify the number or order of execution
4935 of this <code>cmpxchg</code> with other <a href="#volatile">volatile
4936 operations</a>.</p>
4937
4938 <!-- FIXME: Extend allowed types. -->
4939
4940 <p>The <a href="#ordering"><var>ordering</var></a> argument specifies how this
4941 <code>cmpxchg</code> synchronizes with other atomic operations.</p>
4942
4943 <p>The optional "<code>singlethread</code>" argument declares that the
4944 <code>cmpxchg</code> is only atomic with respect to code (usually signal
4945 handlers) running in the same thread as the <code>cmpxchg</code>.  Otherwise the
4946 cmpxchg is atomic with respect to all other code in the system.</p>
4947
4948 <p>The pointer passed into cmpxchg must have alignment greater than or equal to
4949 the size in memory of the operand.
4950
4951 <h5>Semantics:</h5>
4952 <p>The contents of memory at the location specified by the
4953 '<tt>&lt;pointer&gt;</tt>' operand is read and compared to
4954 '<tt>&lt;cmp&gt;</tt>'; if the read value is the equal,
4955 '<tt>&lt;new&gt;</tt>' is written.  The original value at the location
4956 is returned.
4957
4958 <p>A successful <code>cmpxchg</code> is a read-modify-write instruction for the
4959 purpose of identifying <a href="#release_sequence">release sequences</a>.  A
4960 failed <code>cmpxchg</code> is equivalent to an atomic load with an ordering
4961 parameter determined by dropping any <code>release</code> part of the
4962 <code>cmpxchg</code>'s ordering.</p>
4963
4964 <!--
4965 FIXME: Is compare_exchange_weak() necessary?  (Consider after we've done
4966 optimization work on ARM.)
4967
4968 FIXME: Is a weaker ordering constraint on failure helpful in practice?
4969 -->
4970
4971 <h5>Example:</h5>
4972 <pre>
4973 entry:
4974   %orig = atomic <a href="#i_load">load</a> i32* %ptr unordered                       <i>; yields {i32}</i>
4975   <a href="#i_br">br</a> label %loop
4976
4977 loop:
4978   %cmp = <a href="#i_phi">phi</a> i32 [ %orig, %entry ], [%old, %loop]
4979   %squared = <a href="#i_mul">mul</a> i32 %cmp, %cmp
4980   %old = cmpxchg i32* %ptr, i32 %cmp, i32 %squared                       <i>; yields {i32}</i>
4981   %success = <a href="#i_icmp">icmp</a> eq i32 %cmp, %old
4982   <a href="#i_br">br</a> i1 %success, label %done, label %loop
4983
4984 done:
4985   ...
4986 </pre>
4987
4988 </div>
4989
4990 <!-- _______________________________________________________________________ -->
4991 <h4>
4992 <a name="i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a>
4993 </h4>
4994
4995 <div>
4996
4997 <h5>Syntax:</h5>
4998 <pre>
4999   atomicrmw [volatile] &lt;operation&gt; &lt;ty&gt;* &lt;pointer&gt;, &lt;ty&gt; &lt;value&gt; [singlethread] &lt;ordering&gt;                   <i>; yields {ty}</i>
5000 </pre>
5001
5002 <h5>Overview:</h5>
5003 <p>The '<tt>atomicrmw</tt>' instruction is used to atomically modify memory.</p>
5004
5005 <h5>Arguments:</h5>
5006 <p>There are three arguments to the '<code>atomicrmw</code>' instruction: an
5007 operation to apply, an address whose value to modify, an argument to the
5008 operation.  The operation must be one of the following keywords:</p>
5009 <ul>
5010   <li>xchg</li>
5011   <li>add</li>
5012   <li>sub</li>
5013   <li>and</li>
5014   <li>nand</li>
5015   <li>or</li>
5016   <li>xor</li>
5017   <li>max</li>
5018   <li>min</li>
5019   <li>umax</li>
5020   <li>umin</li>
5021 </ul>
5022
5023 <p>The type of '<var>&lt;value&gt;</var>' must be an integer type whose
5024 bit width is a power of two greater than or equal to eight and less than
5025 or equal to a target-specific size limit.  The type of the
5026 '<code>&lt;pointer&gt;</code>' operand must be a pointer to that type.
5027 If the <code>atomicrmw</code> is marked as <code>volatile</code>, then the
5028 optimizer is not allowed to modify the number or order of execution of this
5029 <code>atomicrmw</code> with other <a href="#volatile">volatile
5030   operations</a>.</p>
5031
5032 <!-- FIXME: Extend allowed types. -->
5033
5034 <h5>Semantics:</h5>
5035 <p>The contents of memory at the location specified by the
5036 '<tt>&lt;pointer&gt;</tt>' operand are atomically read, modified, and written
5037 back.  The original value at the location is returned.  The modification is
5038 specified by the <var>operation</var> argument:</p>
5039
5040 <ul>
5041   <li>xchg: <code>*ptr = val</code></li>
5042   <li>add: <code>*ptr = *ptr + val</code></li>
5043   <li>sub: <code>*ptr = *ptr - val</code></li>
5044   <li>and: <code>*ptr = *ptr &amp; val</code></li>
5045   <li>nand: <code>*ptr = ~(*ptr &amp; val)</code></li>
5046   <li>or: <code>*ptr = *ptr | val</code></li>
5047   <li>xor: <code>*ptr = *ptr ^ val</code></li>
5048   <li>max: <code>*ptr = *ptr &gt; val ? *ptr : val</code> (using a signed comparison)</li>
5049   <li>min: <code>*ptr = *ptr &lt; val ? *ptr : val</code> (using a signed comparison)</li>
5050   <li>umax: <code>*ptr = *ptr &gt; val ? *ptr : val</code> (using an unsigned comparison)</li>
5051   <li>umin: <code>*ptr = *ptr &lt; val ? *ptr : val</code> (using an unsigned comparison)</li>
5052 </ul>
5053
5054 <h5>Example:</h5>
5055 <pre>
5056   %old = atomicrmw add i32* %ptr, i32 1 acquire                        <i>; yields {i32}</i>
5057 </pre>
5058
5059 </div>
5060
5061 <!-- _______________________________________________________________________ -->
5062 <h4>
5063    <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
5064 </h4>
5065
5066 <div>
5067
5068 <h5>Syntax:</h5>
5069 <pre>
5070   &lt;result&gt; = getelementptr &lt;pty&gt;* &lt;ptrval&gt;{, &lt;ty&gt; &lt;idx&gt;}*
5071   &lt;result&gt; = getelementptr inbounds &lt;pty&gt;* &lt;ptrval&gt;{, &lt;ty&gt; &lt;idx&gt;}*
5072 </pre>
5073
5074 <h5>Overview:</h5>
5075 <p>The '<tt>getelementptr</tt>' instruction is used to get the address of a
5076    subelement of an <a href="#t_aggregate">aggregate</a> data structure.
5077    It performs address calculation only and does not access memory.</p>
5078
5079 <h5>Arguments:</h5>
5080 <p>The first argument is always a pointer, and forms the basis of the
5081    calculation. The remaining arguments are indices that indicate which of the
5082    elements of the aggregate object are indexed. The interpretation of each
5083    index is dependent on the type being indexed into. The first index always
5084    indexes the pointer value given as the first argument, the second index
5085    indexes a value of the type pointed to (not necessarily the value directly
5086    pointed to, since the first index can be non-zero), etc. The first type
5087    indexed into must be a pointer value, subsequent types can be arrays,
5088    vectors, and structs. Note that subsequent types being indexed into
5089    can never be pointers, since that would require loading the pointer before
5090    continuing calculation.</p>
5091
5092 <p>The type of each index argument depends on the type it is indexing into.
5093    When indexing into a (optionally packed) structure, only <tt>i32</tt>
5094    integer <b>constants</b> are allowed.  When indexing into an array, pointer
5095    or vector, integers of any width are allowed, and they are not required to be
5096    constant.  These integers are treated as signed values where relevant.</p>
5097
5098 <p>For example, let's consider a C code fragment and how it gets compiled to
5099    LLVM:</p>
5100
5101 <pre class="doc_code">
5102 struct RT {
5103   char A;
5104   int B[10][20];
5105   char C;
5106 };
5107 struct ST {
5108   int X;
5109   double Y;
5110   struct RT Z;
5111 };
5112
5113 int *foo(struct ST *s) {
5114   return &amp;s[1].Z.B[5][13];
5115 }
5116 </pre>
5117
5118 <p>The LLVM code generated by the GCC frontend is:</p>
5119
5120 <pre class="doc_code">
5121 %RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8  }
5122 %ST = <a href="#namedtypes">type</a> { i32, double, %RT }
5123
5124 define i32* @foo(%ST* %s) {
5125 entry:
5126   %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13
5127   ret i32* %reg
5128 }
5129 </pre>
5130
5131 <h5>Semantics:</h5>
5132 <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
5133    type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT
5134    }</tt>' type, a structure.  The second index indexes into the third element
5135    of the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]],
5136    i8 }</tt>' type, another structure.  The third index indexes into the second
5137    element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an
5138    array.  The two dimensions of the array are subscripted into, yielding an
5139    '<tt>i32</tt>' type.  The '<tt>getelementptr</tt>' instruction returns a
5140    pointer to this element, thus computing a value of '<tt>i32*</tt>' type.</p>
5141
5142 <p>Note that it is perfectly legal to index partially through a structure,
5143    returning a pointer to an inner element.  Because of this, the LLVM code for
5144    the given testcase is equivalent to:</p>
5145
5146 <pre>
5147   define i32* @foo(%ST* %s) {
5148     %t1 = getelementptr %ST* %s, i32 1                        <i>; yields %ST*:%t1</i>
5149     %t2 = getelementptr %ST* %t1, i32 0, i32 2                <i>; yields %RT*:%t2</i>
5150     %t3 = getelementptr %RT* %t2, i32 0, i32 1                <i>; yields [10 x [20 x i32]]*:%t3</i>
5151     %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5  <i>; yields [20 x i32]*:%t4</i>
5152     %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13        <i>; yields i32*:%t5</i>
5153     ret i32* %t5
5154   }
5155 </pre>
5156
5157 <p>If the <tt>inbounds</tt> keyword is present, the result value of the
5158    <tt>getelementptr</tt> is a <a href="#trapvalues">trap value</a> if the
5159    base pointer is not an <i>in bounds</i> address of an allocated object,
5160    or if any of the addresses that would be formed by successive addition of
5161    the offsets implied by the indices to the base address with infinitely
5162    precise signed arithmetic are not an <i>in bounds</i> address of that
5163    allocated object. The <i>in bounds</i> addresses for an allocated object
5164    are all the addresses that point into the object, plus the address one
5165    byte past the end.</p>
5166
5167 <p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to
5168    the base address with silently-wrapping two's complement arithmetic. If the
5169    offsets have a different width from the pointer, they are sign-extended or
5170    truncated to the width of the pointer. The result value of the
5171    <tt>getelementptr</tt> may be outside the object pointed to by the base
5172    pointer. The result value may not necessarily be used to access memory
5173    though, even if it happens to point into allocated storage. See the
5174    <a href="#pointeraliasing">Pointer Aliasing Rules</a> section for more
5175    information.</p>
5176
5177 <p>The getelementptr instruction is often confusing.  For some more insight into
5178    how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p>
5179
5180 <h5>Example:</h5>
5181 <pre>
5182     <i>; yields [12 x i8]*:aptr</i>
5183     %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1
5184     <i>; yields i8*:vptr</i>
5185     %vptr = getelementptr {i32, &lt;2 x i8&gt;}* %svptr, i64 0, i32 1, i32 1
5186     <i>; yields i8*:eptr</i>
5187     %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1
5188     <i>; yields i32*:iptr</i>
5189     %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0
5190 </pre>
5191
5192 </div>
5193
5194 </div>
5195
5196 <!-- ======================================================================= -->
5197 <h3>
5198   <a name="convertops">Conversion Operations</a>
5199 </h3>
5200
5201 <div>
5202
5203 <p>The instructions in this category are the conversion instructions (casting)
5204    which all take a single operand and a type. They perform various bit
5205    conversions on the operand.</p>
5206
5207 <!-- _______________________________________________________________________ -->
5208 <h4>
5209    <a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
5210 </h4>
5211
5212 <div>
5213
5214 <h5>Syntax:</h5>
5215 <pre>
5216   &lt;result&gt; = trunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5217 </pre>
5218
5219 <h5>Overview:</h5>
5220 <p>The '<tt>trunc</tt>' instruction truncates its operand to the
5221    type <tt>ty2</tt>.</p>
5222
5223 <h5>Arguments:</h5>
5224 <p>The '<tt>trunc</tt>' instruction takes a value to trunc, and a type to trunc it to.
5225    Both types must be of <a href="#t_integer">integer</a> types, or vectors
5226    of the same number of integers.
5227    The bit size of the <tt>value</tt> must be larger than
5228    the bit size of the destination type, <tt>ty2</tt>.
5229    Equal sized types are not allowed.</p>
5230
5231 <h5>Semantics:</h5>
5232 <p>The '<tt>trunc</tt>' instruction truncates the high order bits
5233    in <tt>value</tt> and converts the remaining bits to <tt>ty2</tt>. Since the
5234    source size must be larger than the destination size, <tt>trunc</tt> cannot
5235    be a <i>no-op cast</i>.  It will always truncate bits.</p>
5236
5237 <h5>Example:</h5>
5238 <pre>
5239   %X = trunc i32 257 to i8                        <i>; yields i8:1</i>
5240   %Y = trunc i32 123 to i1                        <i>; yields i1:true</i>
5241   %Z = trunc i32 122 to i1                        <i>; yields i1:false</i>
5242   %W = trunc &lt;2 x i16&gt; &lt;i16 8, i16 7&gt; to &lt;2 x i8&gt; <i>; yields &lt;i8 8, i8 7&gt;</i>
5243 </pre>
5244
5245 </div>
5246
5247 <!-- _______________________________________________________________________ -->
5248 <h4>
5249    <a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
5250 </h4>
5251
5252 <div>
5253
5254 <h5>Syntax:</h5>
5255 <pre>
5256   &lt;result&gt; = zext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5257 </pre>
5258
5259 <h5>Overview:</h5>
5260 <p>The '<tt>zext</tt>' instruction zero extends its operand to type
5261    <tt>ty2</tt>.</p>
5262
5263
5264 <h5>Arguments:</h5>
5265 <p>The '<tt>zext</tt>' instruction takes a value to cast, and a type to cast it to.
5266    Both types must be of <a href="#t_integer">integer</a> types, or vectors
5267    of the same number of integers.
5268    The bit size of the <tt>value</tt> must be smaller than
5269    the bit size of the destination type,
5270    <tt>ty2</tt>.</p>
5271
5272 <h5>Semantics:</h5>
5273 <p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero
5274    bits until it reaches the size of the destination type, <tt>ty2</tt>.</p>
5275
5276 <p>When zero extending from i1, the result will always be either 0 or 1.</p>
5277
5278 <h5>Example:</h5>
5279 <pre>
5280   %X = zext i32 257 to i64              <i>; yields i64:257</i>
5281   %Y = zext i1 true to i32              <i>; yields i32:1</i>
5282   %Z = zext &lt;2 x i16&gt; &lt;i16 8, i16 7&gt; to &lt;2 x i32&gt; <i>; yields &lt;i32 8, i32 7&gt;</i>
5283 </pre>
5284
5285 </div>
5286
5287 <!-- _______________________________________________________________________ -->
5288 <h4>
5289    <a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
5290 </h4>
5291
5292 <div>
5293
5294 <h5>Syntax:</h5>
5295 <pre>
5296   &lt;result&gt; = sext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5297 </pre>
5298
5299 <h5>Overview:</h5>
5300 <p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
5301
5302 <h5>Arguments:</h5>
5303 <p>The '<tt>sext</tt>' instruction takes a value to cast, and a type to cast it to.
5304    Both types must be of <a href="#t_integer">integer</a> types, or vectors
5305    of the same number of integers.
5306    The bit size of the <tt>value</tt> must be smaller than
5307    the bit size of the destination type,
5308    <tt>ty2</tt>.</p>
5309
5310 <h5>Semantics:</h5>
5311 <p>The '<tt>sext</tt>' instruction performs a sign extension by copying the sign
5312    bit (highest order bit) of the <tt>value</tt> until it reaches the bit size
5313    of the type <tt>ty2</tt>.</p>
5314
5315 <p>When sign extending from i1, the extension always results in -1 or 0.</p>
5316
5317 <h5>Example:</h5>
5318 <pre>
5319   %X = sext i8  -1 to i16              <i>; yields i16   :65535</i>
5320   %Y = sext i1 true to i32             <i>; yields i32:-1</i>
5321   %Z = sext &lt;2 x i16&gt; &lt;i16 8, i16 7&gt; to &lt;2 x i32&gt; <i>; yields &lt;i32 8, i32 7&gt;</i>
5322 </pre>
5323
5324 </div>
5325
5326 <!-- _______________________________________________________________________ -->
5327 <h4>
5328    <a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
5329 </h4>
5330
5331 <div>
5332
5333 <h5>Syntax:</h5>
5334 <pre>
5335   &lt;result&gt; = fptrunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5336 </pre>
5337
5338 <h5>Overview:</h5>
5339 <p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
5340    <tt>ty2</tt>.</p>
5341
5342 <h5>Arguments:</h5>
5343 <p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
5344    point</a> value to cast and a <a href="#t_floating">floating point</a> type
5345    to cast it to. The size of <tt>value</tt> must be larger than the size of
5346    <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
5347    <i>no-op cast</i>.</p>
5348
5349 <h5>Semantics:</h5>
5350 <p>The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger
5351    <a href="#t_floating">floating point</a> type to a smaller
5352    <a href="#t_floating">floating point</a> type.  If the value cannot fit
5353    within the destination type, <tt>ty2</tt>, then the results are
5354    undefined.</p>
5355
5356 <h5>Example:</h5>
5357 <pre>
5358   %X = fptrunc double 123.0 to float         <i>; yields float:123.0</i>
5359   %Y = fptrunc double 1.0E+300 to float      <i>; yields undefined</i>
5360 </pre>
5361
5362 </div>
5363
5364 <!-- _______________________________________________________________________ -->
5365 <h4>
5366    <a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
5367 </h4>
5368
5369 <div>
5370
5371 <h5>Syntax:</h5>
5372 <pre>
5373   &lt;result&gt; = fpext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5374 </pre>
5375
5376 <h5>Overview:</h5>
5377 <p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger
5378    floating point value.</p>
5379
5380 <h5>Arguments:</h5>
5381 <p>The '<tt>fpext</tt>' instruction takes a
5382    <a href="#t_floating">floating point</a> <tt>value</tt> to cast, and
5383    a <a href="#t_floating">floating point</a> type to cast it to. The source
5384    type must be smaller than the destination type.</p>
5385
5386 <h5>Semantics:</h5>
5387 <p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller
5388    <a href="#t_floating">floating point</a> type to a larger
5389    <a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be
5390    used to make a <i>no-op cast</i> because it always changes bits. Use
5391    <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p>
5392
5393 <h5>Example:</h5>
5394 <pre>
5395   %X = fpext float 3.125 to double         <i>; yields double:3.125000e+00</i>
5396   %Y = fpext double %X to fp128            <i>; yields fp128:0xL00000000000000004000900000000000</i>
5397 </pre>
5398
5399 </div>
5400
5401 <!-- _______________________________________________________________________ -->
5402 <h4>
5403    <a name="i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a>
5404 </h4>
5405
5406 <div>
5407
5408 <h5>Syntax:</h5>
5409 <pre>
5410   &lt;result&gt; = fptoui &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5411 </pre>
5412
5413 <h5>Overview:</h5>
5414 <p>The '<tt>fptoui</tt>' converts a floating point <tt>value</tt> to its
5415    unsigned integer equivalent of type <tt>ty2</tt>.</p>
5416
5417 <h5>Arguments:</h5>
5418 <p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a
5419    scalar or vector <a href="#t_floating">floating point</a> value, and a type
5420    to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
5421    type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
5422    vector integer type with the same number of elements as <tt>ty</tt></p>
5423
5424 <h5>Semantics:</h5>
5425 <p>The '<tt>fptoui</tt>' instruction converts its
5426    <a href="#t_floating">floating point</a> operand into the nearest (rounding
5427    towards zero) unsigned integer value. If the value cannot fit
5428    in <tt>ty2</tt>, the results are undefined.</p>
5429
5430 <h5>Example:</h5>
5431 <pre>
5432   %X = fptoui double 123.0 to i32      <i>; yields i32:123</i>
5433   %Y = fptoui float 1.0E+300 to i1     <i>; yields undefined:1</i>
5434   %Z = fptoui float 1.04E+17 to i8     <i>; yields undefined:1</i>
5435 </pre>
5436
5437 </div>
5438
5439 <!-- _______________________________________________________________________ -->
5440 <h4>
5441    <a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a>
5442 </h4>
5443
5444 <div>
5445
5446 <h5>Syntax:</h5>
5447 <pre>
5448   &lt;result&gt; = fptosi &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5449 </pre>
5450
5451 <h5>Overview:</h5>
5452 <p>The '<tt>fptosi</tt>' instruction converts
5453    <a href="#t_floating">floating point</a> <tt>value</tt> to
5454    type <tt>ty2</tt>.</p>
5455
5456 <h5>Arguments:</h5>
5457 <p>The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a
5458    scalar or vector <a href="#t_floating">floating point</a> value, and a type
5459    to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
5460    type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
5461    vector integer type with the same number of elements as <tt>ty</tt></p>
5462
5463 <h5>Semantics:</h5>
5464 <p>The '<tt>fptosi</tt>' instruction converts its
5465    <a href="#t_floating">floating point</a> operand into the nearest (rounding
5466    towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
5467    the results are undefined.</p>
5468
5469 <h5>Example:</h5>
5470 <pre>
5471   %X = fptosi double -123.0 to i32      <i>; yields i32:-123</i>
5472   %Y = fptosi float 1.0E-247 to i1      <i>; yields undefined:1</i>
5473   %Z = fptosi float 1.04E+17 to i8      <i>; yields undefined:1</i>
5474 </pre>
5475
5476 </div>
5477
5478 <!-- _______________________________________________________________________ -->
5479 <h4>
5480    <a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a>
5481 </h4>
5482
5483 <div>
5484
5485 <h5>Syntax:</h5>
5486 <pre>
5487   &lt;result&gt; = uitofp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5488 </pre>
5489
5490 <h5>Overview:</h5>
5491 <p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned
5492    integer and converts that value to the <tt>ty2</tt> type.</p>
5493
5494 <h5>Arguments:</h5>
5495 <p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be a
5496    scalar or vector <a href="#t_integer">integer</a> value, and a type to cast
5497    it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
5498    type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
5499    floating point type with the same number of elements as <tt>ty</tt></p>
5500
5501 <h5>Semantics:</h5>
5502 <p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned
5503    integer quantity and converts it to the corresponding floating point
5504    value. If the value cannot fit in the floating point value, the results are
5505    undefined.</p>
5506
5507 <h5>Example:</h5>
5508 <pre>
5509   %X = uitofp i32 257 to float         <i>; yields float:257.0</i>
5510   %Y = uitofp i8 -1 to double          <i>; yields double:255.0</i>
5511 </pre>
5512
5513 </div>
5514
5515 <!-- _______________________________________________________________________ -->
5516 <h4>
5517    <a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a>
5518 </h4>
5519
5520 <div>
5521
5522 <h5>Syntax:</h5>
5523 <pre>
5524   &lt;result&gt; = sitofp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5525 </pre>
5526
5527 <h5>Overview:</h5>
5528 <p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed integer
5529    and converts that value to the <tt>ty2</tt> type.</p>
5530
5531 <h5>Arguments:</h5>
5532 <p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be a
5533    scalar or vector <a href="#t_integer">integer</a> value, and a type to cast
5534    it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
5535    type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
5536    floating point type with the same number of elements as <tt>ty</tt></p>
5537
5538 <h5>Semantics:</h5>
5539 <p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed integer
5540    quantity and converts it to the corresponding floating point value. If the
5541    value cannot fit in the floating point value, the results are undefined.</p>
5542
5543 <h5>Example:</h5>
5544 <pre>
5545   %X = sitofp i32 257 to float         <i>; yields float:257.0</i>
5546   %Y = sitofp i8 -1 to double          <i>; yields double:-1.0</i>
5547 </pre>
5548
5549 </div>
5550
5551 <!-- _______________________________________________________________________ -->
5552 <h4>
5553    <a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a>
5554 </h4>
5555
5556 <div>
5557
5558 <h5>Syntax:</h5>
5559 <pre>
5560   &lt;result&gt; = ptrtoint &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5561 </pre>
5562
5563 <h5>Overview:</h5>
5564 <p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to
5565    the integer type <tt>ty2</tt>.</p>
5566
5567 <h5>Arguments:</h5>
5568 <p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which
5569    must be a <a href="#t_pointer">pointer</a> value, and a type to cast it to
5570    <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.</p>
5571
5572 <h5>Semantics:</h5>
5573 <p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type
5574    <tt>ty2</tt> by interpreting the pointer value as an integer and either
5575    truncating or zero extending that value to the size of the integer type. If
5576    <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If
5577    <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they
5578    are the same size, then nothing is done (<i>no-op cast</i>) other than a type
5579    change.</p>
5580
5581 <h5>Example:</h5>
5582 <pre>
5583   %X = ptrtoint i32* %X to i8           <i>; yields truncation on 32-bit architecture</i>
5584   %Y = ptrtoint i32* %x to i64          <i>; yields zero extension on 32-bit architecture</i>
5585 </pre>
5586
5587 </div>
5588
5589 <!-- _______________________________________________________________________ -->
5590 <h4>
5591    <a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a>
5592 </h4>
5593
5594 <div>
5595
5596 <h5>Syntax:</h5>
5597 <pre>
5598   &lt;result&gt; = inttoptr &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5599 </pre>
5600
5601 <h5>Overview:</h5>
5602 <p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to a
5603    pointer type, <tt>ty2</tt>.</p>
5604
5605 <h5>Arguments:</h5>
5606 <p>The '<tt>inttoptr</tt>' instruction takes an <a href="#t_integer">integer</a>
5607    value to cast, and a type to cast it to, which must be a
5608    <a href="#t_pointer">pointer</a> type.</p>
5609
5610 <h5>Semantics:</h5>
5611 <p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type
5612    <tt>ty2</tt> by applying either a zero extension or a truncation depending on
5613    the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the
5614    size of a pointer then a truncation is done. If <tt>value</tt> is smaller
5615    than the size of a pointer then a zero extension is done. If they are the
5616    same size, nothing is done (<i>no-op cast</i>).</p>
5617
5618 <h5>Example:</h5>
5619 <pre>
5620   %X = inttoptr i32 255 to i32*          <i>; yields zero extension on 64-bit architecture</i>
5621   %Y = inttoptr i32 255 to i32*          <i>; yields no-op on 32-bit architecture</i>
5622   %Z = inttoptr i64 0 to i32*            <i>; yields truncation on 32-bit architecture</i>
5623 </pre>
5624
5625 </div>
5626
5627 <!-- _______________________________________________________________________ -->
5628 <h4>
5629    <a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a>
5630 </h4>
5631
5632 <div>
5633
5634 <h5>Syntax:</h5>
5635 <pre>
5636   &lt;result&gt; = bitcast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
5637 </pre>
5638
5639 <h5>Overview:</h5>
5640 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
5641    <tt>ty2</tt> without changing any bits.</p>
5642
5643 <h5>Arguments:</h5>
5644 <p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be a
5645    non-aggregate first class value, and a type to cast it to, which must also be
5646    a non-aggregate <a href="#t_firstclass">first class</a> type. The bit sizes
5647    of <tt>value</tt> and the destination type, <tt>ty2</tt>, must be
5648    identical. If the source type is a pointer, the destination type must also be
5649    a pointer.  This instruction supports bitwise conversion of vectors to
5650    integers and to vectors of other types (as long as they have the same
5651    size).</p>
5652
5653 <h5>Semantics:</h5>
5654 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
5655    <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with
5656    this conversion.  The conversion is done as if the <tt>value</tt> had been
5657    stored to memory and read back as type <tt>ty2</tt>. Pointer types may only
5658    be converted to other pointer types with this instruction. To convert
5659    pointers to other types, use the <a href="#i_inttoptr">inttoptr</a> or
5660    <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p>
5661
5662 <h5>Example:</h5>
5663 <pre>
5664   %X = bitcast i8 255 to i8              <i>; yields i8 :-1</i>
5665   %Y = bitcast i32* %x to sint*          <i>; yields sint*:%x</i>
5666   %Z = bitcast &lt;2 x int&gt; %V to i64;      <i>; yields i64: %V</i>
5667 </pre>
5668
5669 </div>
5670
5671 </div>
5672
5673 <!-- ======================================================================= -->
5674 <h3>
5675   <a name="otherops">Other Operations</a>
5676 </h3>
5677
5678 <div>
5679
5680 <p>The instructions in this category are the "miscellaneous" instructions, which
5681    defy better classification.</p>
5682
5683 <!-- _______________________________________________________________________ -->
5684 <h4>
5685   <a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
5686 </h4>
5687
5688 <div>
5689
5690 <h5>Syntax:</h5>
5691 <pre>
5692   &lt;result&gt; = icmp &lt;cond&gt; &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {i1} or {&lt;N x i1&gt;}:result</i>
5693 </pre>
5694
5695 <h5>Overview:</h5>
5696 <p>The '<tt>icmp</tt>' instruction returns a boolean value or a vector of
5697    boolean values based on comparison of its two integer, integer vector, or
5698    pointer operands.</p>
5699
5700 <h5>Arguments:</h5>
5701 <p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is
5702    the condition code indicating the kind of comparison to perform. It is not a
5703    value, just a keyword. The possible condition code are:</p>
5704
5705 <ol>
5706   <li><tt>eq</tt>: equal</li>
5707   <li><tt>ne</tt>: not equal </li>
5708   <li><tt>ugt</tt>: unsigned greater than</li>
5709   <li><tt>uge</tt>: unsigned greater or equal</li>
5710   <li><tt>ult</tt>: unsigned less than</li>
5711   <li><tt>ule</tt>: unsigned less or equal</li>
5712   <li><tt>sgt</tt>: signed greater than</li>
5713   <li><tt>sge</tt>: signed greater or equal</li>
5714   <li><tt>slt</tt>: signed less than</li>
5715   <li><tt>sle</tt>: signed less or equal</li>
5716 </ol>
5717
5718 <p>The remaining two arguments must be <a href="#t_integer">integer</a> or
5719    <a href="#t_pointer">pointer</a> or integer <a href="#t_vector">vector</a>
5720    typed.  They must also be identical types.</p>
5721
5722 <h5>Semantics:</h5>
5723 <p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to the
5724    condition code given as <tt>cond</tt>. The comparison performed always yields
5725    either an <a href="#t_integer"><tt>i1</tt></a> or vector of <tt>i1</tt>
5726    result, as follows:</p>
5727
5728 <ol>
5729   <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
5730       <tt>false</tt> otherwise. No sign interpretation is necessary or
5731       performed.</li>
5732
5733   <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
5734       <tt>false</tt> otherwise. No sign interpretation is necessary or
5735       performed.</li>
5736
5737   <li><tt>ugt</tt>: interprets the operands as unsigned values and yields
5738       <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li>
5739
5740   <li><tt>uge</tt>: interprets the operands as unsigned values and yields
5741       <tt>true</tt> if <tt>op1</tt> is greater than or equal
5742       to <tt>op2</tt>.</li>
5743
5744   <li><tt>ult</tt>: interprets the operands as unsigned values and yields
5745       <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li>
5746
5747   <li><tt>ule</tt>: interprets the operands as unsigned values and yields
5748       <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
5749
5750   <li><tt>sgt</tt>: interprets the operands as signed values and yields
5751       <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li>
5752
5753   <li><tt>sge</tt>: interprets the operands as signed values and yields
5754       <tt>true</tt> if <tt>op1</tt> is greater than or equal
5755       to <tt>op2</tt>.</li>
5756
5757   <li><tt>slt</tt>: interprets the operands as signed values and yields
5758       <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li>
5759
5760   <li><tt>sle</tt>: interprets the operands as signed values and yields
5761       <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
5762 </ol>
5763
5764 <p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer
5765    values are compared as if they were integers.</p>
5766
5767 <p>If the operands are integer vectors, then they are compared element by
5768    element. The result is an <tt>i1</tt> vector with the same number of elements
5769    as the values being compared.  Otherwise, the result is an <tt>i1</tt>.</p>
5770
5771 <h5>Example:</h5>
5772 <pre>
5773   &lt;result&gt; = icmp eq i32 4, 5          <i>; yields: result=false</i>
5774   &lt;result&gt; = icmp ne float* %X, %X     <i>; yields: result=false</i>
5775   &lt;result&gt; = icmp ult i16  4, 5        <i>; yields: result=true</i>
5776   &lt;result&gt; = icmp sgt i16  4, 5        <i>; yields: result=false</i>
5777   &lt;result&gt; = icmp ule i16 -4, 5        <i>; yields: result=false</i>
5778   &lt;result&gt; = icmp sge i16  4, 5        <i>; yields: result=false</i>
5779 </pre>
5780
5781 <p>Note that the code generator does not yet support vector types with
5782    the <tt>icmp</tt> instruction.</p>
5783
5784 </div>
5785
5786 <!-- _______________________________________________________________________ -->
5787 <h4>
5788   <a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
5789 </h4>
5790
5791 <div>
5792
5793 <h5>Syntax:</h5>
5794 <pre>
5795   &lt;result&gt; = fcmp &lt;cond&gt; &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;     <i>; yields {i1} or {&lt;N x i1&gt;}:result</i>
5796 </pre>
5797
5798 <h5>Overview:</h5>
5799 <p>The '<tt>fcmp</tt>' instruction returns a boolean value or vector of boolean
5800    values based on comparison of its operands.</p>
5801
5802 <p>If the operands are floating point scalars, then the result type is a boolean
5803 (<a href="#t_integer"><tt>i1</tt></a>).</p>
5804
5805 <p>If the operands are floating point vectors, then the result type is a vector
5806    of boolean with the same number of elements as the operands being
5807    compared.</p>
5808
5809 <h5>Arguments:</h5>
5810 <p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is
5811    the condition code indicating the kind of comparison to perform. It is not a
5812    value, just a keyword. The possible condition code are:</p>
5813
5814 <ol>
5815   <li><tt>false</tt>: no comparison, always returns false</li>
5816   <li><tt>oeq</tt>: ordered and equal</li>
5817   <li><tt>ogt</tt>: ordered and greater than </li>
5818   <li><tt>oge</tt>: ordered and greater than or equal</li>
5819   <li><tt>olt</tt>: ordered and less than </li>
5820   <li><tt>ole</tt>: ordered and less than or equal</li>
5821   <li><tt>one</tt>: ordered and not equal</li>
5822   <li><tt>ord</tt>: ordered (no nans)</li>
5823   <li><tt>ueq</tt>: unordered or equal</li>
5824   <li><tt>ugt</tt>: unordered or greater than </li>
5825   <li><tt>uge</tt>: unordered or greater than or equal</li>
5826   <li><tt>ult</tt>: unordered or less than </li>
5827   <li><tt>ule</tt>: unordered or less than or equal</li>
5828   <li><tt>une</tt>: unordered or not equal</li>
5829   <li><tt>uno</tt>: unordered (either nans)</li>
5830   <li><tt>true</tt>: no comparison, always returns true</li>
5831 </ol>
5832
5833 <p><i>Ordered</i> means that neither operand is a QNAN while
5834    <i>unordered</i> means that either operand may be a QNAN.</p>
5835
5836 <p>Each of <tt>val1</tt> and <tt>val2</tt> arguments must be either
5837    a <a href="#t_floating">floating point</a> type or
5838    a <a href="#t_vector">vector</a> of floating point type.  They must have
5839    identical types.</p>
5840
5841 <h5>Semantics:</h5>
5842 <p>The '<tt>fcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt>
5843    according to the condition code given as <tt>cond</tt>.  If the operands are
5844    vectors, then the vectors are compared element by element.  Each comparison
5845    performed always yields an <a href="#t_integer">i1</a> result, as
5846    follows:</p>
5847
5848 <ol>
5849   <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
5850
5851   <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5852       <tt>op1</tt> is equal to <tt>op2</tt>.</li>
5853
5854   <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5855       <tt>op1</tt> is greater than <tt>op2</tt>.</li>
5856
5857   <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5858       <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
5859
5860   <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5861       <tt>op1</tt> is less than <tt>op2</tt>.</li>
5862
5863   <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5864       <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
5865
5866   <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5867       <tt>op1</tt> is not equal to <tt>op2</tt>.</li>
5868
5869   <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
5870
5871   <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
5872       <tt>op1</tt> is equal to <tt>op2</tt>.</li>
5873
5874   <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
5875       <tt>op1</tt> is greater than <tt>op2</tt>.</li>
5876
5877   <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
5878       <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
5879
5880   <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
5881       <tt>op1</tt> is less than <tt>op2</tt>.</li>
5882
5883   <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
5884       <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
5885
5886   <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
5887       <tt>op1</tt> is not equal to <tt>op2</tt>.</li>
5888
5889   <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
5890
5891   <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li>
5892 </ol>
5893
5894 <h5>Example:</h5>
5895 <pre>
5896   &lt;result&gt; = fcmp oeq float 4.0, 5.0    <i>; yields: result=false</i>
5897   &lt;result&gt; = fcmp one float 4.0, 5.0    <i>; yields: result=true</i>
5898   &lt;result&gt; = fcmp olt float 4.0, 5.0    <i>; yields: result=true</i>
5899   &lt;result&gt; = fcmp ueq double 1.0, 2.0   <i>; yields: result=false</i>
5900 </pre>
5901
5902 <p>Note that the code generator does not yet support vector types with
5903    the <tt>fcmp</tt> instruction.</p>
5904
5905 </div>
5906
5907 <!-- _______________________________________________________________________ -->
5908 <h4>
5909   <a name="i_phi">'<tt>phi</tt>' Instruction</a>
5910 </h4>
5911
5912 <div>
5913
5914 <h5>Syntax:</h5>
5915 <pre>
5916   &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...
5917 </pre>
5918
5919 <h5>Overview:</h5>
5920 <p>The '<tt>phi</tt>' instruction is used to implement the &#966; node in the
5921    SSA graph representing the function.</p>
5922
5923 <h5>Arguments:</h5>
5924 <p>The type of the incoming values is specified with the first type field. After
5925    this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with
5926    one pair for each predecessor basic block of the current block.  Only values
5927    of <a href="#t_firstclass">first class</a> type may be used as the value
5928    arguments to the PHI node.  Only labels may be used as the label
5929    arguments.</p>
5930
5931 <p>There must be no non-phi instructions between the start of a basic block and
5932    the PHI instructions: i.e. PHI instructions must be first in a basic
5933    block.</p>
5934
5935 <p>For the purposes of the SSA form, the use of each incoming value is deemed to
5936    occur on the edge from the corresponding predecessor block to the current
5937    block (but after any definition of an '<tt>invoke</tt>' instruction's return
5938    value on the same edge).</p>
5939
5940 <h5>Semantics:</h5>
5941 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value
5942    specified by the pair corresponding to the predecessor basic block that
5943    executed just prior to the current block.</p>
5944
5945 <h5>Example:</h5>
5946 <pre>
5947 Loop:       ; Infinite loop that counts from 0 on up...
5948   %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
5949   %nextindvar = add i32 %indvar, 1
5950   br label %Loop
5951 </pre>
5952
5953 </div>
5954
5955 <!-- _______________________________________________________________________ -->
5956 <h4>
5957    <a name="i_select">'<tt>select</tt>' Instruction</a>
5958 </h4>
5959
5960 <div>
5961
5962 <h5>Syntax:</h5>
5963 <pre>
5964   &lt;result&gt; = select <i>selty</i> &lt;cond&gt;, &lt;ty&gt; &lt;val1&gt;, &lt;ty&gt; &lt;val2&gt;             <i>; yields ty</i>
5965
5966   <i>selty</i> is either i1 or {&lt;N x i1&gt;}
5967 </pre>
5968
5969 <h5>Overview:</h5>
5970 <p>The '<tt>select</tt>' instruction is used to choose one value based on a
5971    condition, without branching.</p>
5972
5973
5974 <h5>Arguments:</h5>
5975 <p>The '<tt>select</tt>' instruction requires an 'i1' value or a vector of 'i1'
5976    values indicating the condition, and two values of the
5977    same <a href="#t_firstclass">first class</a> type.  If the val1/val2 are
5978    vectors and the condition is a scalar, then entire vectors are selected, not
5979    individual elements.</p>
5980
5981 <h5>Semantics:</h5>
5982 <p>If the condition is an i1 and it evaluates to 1, the instruction returns the
5983    first value argument; otherwise, it returns the second value argument.</p>
5984
5985 <p>If the condition is a vector of i1, then the value arguments must be vectors
5986    of the same size, and the selection is done element by element.</p>
5987
5988 <h5>Example:</h5>
5989 <pre>
5990   %X = select i1 true, i8 17, i8 42          <i>; yields i8:17</i>
5991 </pre>
5992
5993 <p>Note that the code generator does not yet support conditions
5994    with vector type.</p>
5995
5996 </div>
5997
5998 <!-- _______________________________________________________________________ -->
5999 <h4>
6000   <a name="i_call">'<tt>call</tt>' Instruction</a>
6001 </h4>
6002
6003 <div>
6004
6005 <h5>Syntax:</h5>
6006 <pre>
6007   &lt;result&gt; = [tail] call [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] &lt;ty&gt; [&lt;fnty&gt;*] &lt;fnptrval&gt;(&lt;function args&gt;) [<a href="#fnattrs">fn attrs</a>]
6008 </pre>
6009
6010 <h5>Overview:</h5>
6011 <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
6012
6013 <h5>Arguments:</h5>
6014 <p>This instruction requires several arguments:</p>
6015
6016 <ol>
6017   <li>The optional "tail" marker indicates that the callee function does not
6018       access any allocas or varargs in the caller.  Note that calls may be
6019       marked "tail" even if they do not occur before
6020       a <a href="#i_ret"><tt>ret</tt></a> instruction.  If the "tail" marker is
6021       present, the function call is eligible for tail call optimization,
6022       but <a href="CodeGenerator.html#tailcallopt">might not in fact be
6023       optimized into a jump</a>.  The code generator may optimize calls marked
6024       "tail" with either 1) automatic <a href="CodeGenerator.html#sibcallopt">
6025       sibling call optimization</a> when the caller and callee have
6026       matching signatures, or 2) forced tail call optimization when the
6027       following extra requirements are met:
6028       <ul>
6029         <li>Caller and callee both have the calling
6030             convention <tt>fastcc</tt>.</li>
6031         <li>The call is in tail position (ret immediately follows call and ret
6032             uses value of call or is void).</li>
6033         <li>Option <tt>-tailcallopt</tt> is enabled,
6034             or <code>llvm::GuaranteedTailCallOpt</code> is <code>true</code>.</li>
6035         <li><a href="CodeGenerator.html#tailcallopt">Platform specific
6036             constraints are met.</a></li>
6037       </ul>
6038   </li>
6039
6040   <li>The optional "cconv" marker indicates which <a href="#callingconv">calling
6041       convention</a> the call should use.  If none is specified, the call
6042       defaults to using C calling conventions.  The calling convention of the
6043       call must match the calling convention of the target function, or else the
6044       behavior is undefined.</li>
6045
6046   <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
6047       return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
6048       '<tt>inreg</tt>' attributes are valid here.</li>
6049
6050   <li>'<tt>ty</tt>': the type of the call instruction itself which is also the
6051       type of the return value.  Functions that return no value are marked
6052       <tt><a href="#t_void">void</a></tt>.</li>
6053
6054   <li>'<tt>fnty</tt>': shall be the signature of the pointer to function value
6055       being invoked.  The argument types must match the types implied by this
6056       signature.  This type can be omitted if the function is not varargs and if
6057       the function type does not return a pointer to a function.</li>
6058
6059   <li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to
6060       be invoked. In most cases, this is a direct function invocation, but
6061       indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer
6062       to function value.</li>
6063
6064   <li>'<tt>function args</tt>': argument list whose types match the function
6065       signature argument types and parameter attributes. All arguments must be
6066       of <a href="#t_firstclass">first class</a> type. If the function
6067       signature indicates the function accepts a variable number of arguments,
6068       the extra arguments can be specified.</li>
6069
6070   <li>The optional <a href="#fnattrs">function attributes</a> list. Only
6071       '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
6072       '<tt>readnone</tt>' attributes are valid here.</li>
6073 </ol>
6074
6075 <h5>Semantics:</h5>
6076 <p>The '<tt>call</tt>' instruction is used to cause control flow to transfer to
6077    a specified function, with its incoming arguments bound to the specified
6078    values. Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called
6079    function, control flow continues with the instruction after the function
6080    call, and the return value of the function is bound to the result
6081    argument.</p>
6082
6083 <h5>Example:</h5>
6084 <pre>
6085   %retval = call i32 @test(i32 %argc)
6086   call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42)        <i>; yields i32</i>
6087   %X = tail call i32 @foo()                                    <i>; yields i32</i>
6088   %Y = tail call <a href="#callingconv">fastcc</a> i32 @foo()  <i>; yields i32</i>
6089   call void %foo(i8 97 signext)
6090
6091   %struct.A = type { i32, i8 }
6092   %r = call %struct.A @foo()                        <i>; yields { 32, i8 }</i>
6093   %gr = extractvalue %struct.A %r, 0                <i>; yields i32</i>
6094   %gr1 = extractvalue %struct.A %r, 1               <i>; yields i8</i>
6095   %Z = call void @foo() noreturn                    <i>; indicates that %foo never returns normally</i>
6096   %ZZ = call zeroext i32 @bar()                     <i>; Return value is %zero extended</i>
6097 </pre>
6098
6099 <p>llvm treats calls to some functions with names and arguments that match the
6100 standard C99 library as being the C99 library functions, and may perform
6101 optimizations or generate code for them under that assumption.  This is
6102 something we'd like to change in the future to provide better support for
6103 freestanding environments and non-C-based languages.</p>
6104
6105 </div>
6106
6107 <!-- _______________________________________________________________________ -->
6108 <h4>
6109   <a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
6110 </h4>
6111
6112 <div>
6113
6114 <h5>Syntax:</h5>
6115 <pre>
6116   &lt;resultval&gt; = va_arg &lt;va_list*&gt; &lt;arglist&gt;, &lt;argty&gt;
6117 </pre>
6118
6119 <h5>Overview:</h5>
6120 <p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through
6121    the "variable argument" area of a function call.  It is used to implement the
6122    <tt>va_arg</tt> macro in C.</p>
6123
6124 <h5>Arguments:</h5>
6125 <p>This instruction takes a <tt>va_list*</tt> value and the type of the
6126    argument. It returns a value of the specified argument type and increments
6127    the <tt>va_list</tt> to point to the next argument.  The actual type
6128    of <tt>va_list</tt> is target specific.</p>
6129
6130 <h5>Semantics:</h5>
6131 <p>The '<tt>va_arg</tt>' instruction loads an argument of the specified type
6132    from the specified <tt>va_list</tt> and causes the <tt>va_list</tt> to point
6133    to the next argument.  For more information, see the variable argument
6134    handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
6135
6136 <p>It is legal for this instruction to be called in a function which does not
6137    take a variable number of arguments, for example, the <tt>vfprintf</tt>
6138    function.</p>
6139
6140 <p><tt>va_arg</tt> is an LLVM instruction instead of
6141    an <a href="#intrinsics">intrinsic function</a> because it takes a type as an
6142    argument.</p>
6143
6144 <h5>Example:</h5>
6145 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
6146
6147 <p>Note that the code generator does not yet fully support va_arg on many
6148    targets. Also, it does not currently support va_arg with aggregate types on
6149    any target.</p>
6150
6151 </div>
6152
6153 <!-- _______________________________________________________________________ -->
6154 <h4>
6155   <a name="i_landingpad">'<tt>landingpad</tt>' Instruction</a>
6156 </h4>
6157
6158 <div>
6159
6160 <h5>Syntax:</h5>
6161 <pre>
6162   &lt;resultval&gt; = landingpad &lt;somety&gt; personality &lt;type&gt; &lt;pers_fn&gt; &lt;clause&gt;+
6163   &lt;resultval&gt; = landingpad &lt;somety&gt; personality &lt;type&gt; &lt;pers_fn&gt; cleanup &lt;clause&gt;*
6164
6165   &lt;clause&gt; := catch &lt;type&gt; &lt;value&gt;
6166   &lt;clause&gt; := filter &lt;array constant type&gt; &lt;array constant&gt;
6167 </pre>
6168
6169 <h5>Overview:</h5>
6170 <p>The '<tt>landingpad</tt>' instruction is used by
6171    <a href="ExceptionHandling.html#overview">LLVM's exception handling
6172    system</a> to specify that a basic block is a landing pad &mdash; one where
6173    the exception lands, and corresponds to the code found in the
6174    <i><tt>catch</tt></i> portion of a <i><tt>try/catch</tt></i> sequence. It
6175    defines values supplied by the personality function (<tt>pers_fn</tt>) upon
6176    re-entry to the function. The <tt>resultval</tt> has the
6177    type <tt>somety</tt>.</p>
6178
6179 <h5>Arguments:</h5>
6180 <p>This instruction takes a <tt>pers_fn</tt> value. This is the personality
6181    function associated with the unwinding mechanism. The optional
6182    <tt>cleanup</tt> flag indicates that the landing pad block is a cleanup.</p>
6183
6184 <p>A <tt>clause</tt> begins with the clause type &mdash; <tt>catch</tt>
6185    or <tt>filter</tt> &mdash; and contains the global variable representing the
6186    "type" that may be caught or filtered respectively. Unlike the
6187    <tt>catch</tt> clause, the <tt>filter</tt> clause takes an array constant as
6188    its argument. Use "<tt>[0 x i8**] undef</tt>" for a filter which cannot
6189    throw. The '<tt>landingpad</tt>' instruction must contain <em>at least</em>
6190    one <tt>clause</tt> or the <tt>cleanup</tt> flag.</p>
6191
6192 <h5>Semantics:</h5>
6193 <p>The '<tt>landingpad</tt>' instruction defines the values which are set by the
6194    personality function (<tt>pers_fn</tt>) upon re-entry to the function, and
6195    therefore the "result type" of the <tt>landingpad</tt> instruction. As with
6196    calling conventions, how the personality function results are represented in
6197    LLVM IR is target specific.</p>
6198
6199 <p>The clauses are applied in order from top to bottom. If two
6200    <tt>landingpad</tt> instructions are merged together through inlining, the
6201    clauses from the calling function are appended to the list of clauses.</p>
6202
6203 <p>The <tt>landingpad</tt> instruction has several restrictions:</p>
6204
6205 <ul>
6206   <li>A landing pad block is a basic block which is the unwind destination of an
6207       '<tt>invoke</tt>' instruction.</li>
6208   <li>A landing pad block must have a '<tt>landingpad</tt>' instruction as its
6209       first non-PHI instruction.</li>
6210   <li>There can be only one '<tt>landingpad</tt>' instruction within the landing
6211       pad block.</li>
6212   <li>A basic block that is not a landing pad block may not include a
6213       '<tt>landingpad</tt>' instruction.</li>
6214   <li>All '<tt>landingpad</tt>' instructions in a function must have the same
6215       personality function.</li>
6216 </ul>
6217
6218 <h5>Example:</h5>
6219 <pre>
6220   ;; A landing pad which can catch an integer.
6221   %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
6222            catch i8** @_ZTIi
6223   ;; A landing pad that is a cleanup.
6224   %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
6225            cleanup
6226   ;; A landing pad which can catch an integer and can only throw a double.
6227   %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
6228            catch i8** @_ZTIi
6229            filter [1 x i8**] [@_ZTId]
6230 </pre>
6231
6232 </div>
6233
6234 </div>
6235
6236 </div>
6237
6238 <!-- *********************************************************************** -->
6239 <h2><a name="intrinsics">Intrinsic Functions</a></h2>
6240 <!-- *********************************************************************** -->
6241
6242 <div>
6243
6244 <p>LLVM supports the notion of an "intrinsic function".  These functions have
6245    well known names and semantics and are required to follow certain
6246    restrictions.  Overall, these intrinsics represent an extension mechanism for
6247    the LLVM language that does not require changing all of the transformations
6248    in LLVM when adding to the language (or the bitcode reader/writer, the
6249    parser, etc...).</p>
6250
6251 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
6252    prefix is reserved in LLVM for intrinsic names; thus, function names may not
6253    begin with this prefix.  Intrinsic functions must always be external
6254    functions: you cannot define the body of intrinsic functions.  Intrinsic
6255    functions may only be used in call or invoke instructions: it is illegal to
6256    take the address of an intrinsic function.  Additionally, because intrinsic
6257    functions are part of the LLVM language, it is required if any are added that
6258    they be documented here.</p>
6259
6260 <p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents a
6261    family of functions that perform the same operation but on different data
6262    types. Because LLVM can represent over 8 million different integer types,
6263    overloading is used commonly to allow an intrinsic function to operate on any
6264    integer type. One or more of the argument types or the result type can be
6265    overloaded to accept any integer type. Argument types may also be defined as
6266    exactly matching a previous argument's type or the result type. This allows
6267    an intrinsic function which accepts multiple arguments, but needs all of them
6268    to be of the same type, to only be overloaded with respect to a single
6269    argument or the result.</p>
6270
6271 <p>Overloaded intrinsics will have the names of its overloaded argument types
6272    encoded into its function name, each preceded by a period. Only those types
6273    which are overloaded result in a name suffix. Arguments whose type is matched
6274    against another type do not. For example, the <tt>llvm.ctpop</tt> function
6275    can take an integer of any width and returns an integer of exactly the same
6276    integer width. This leads to a family of functions such as
6277    <tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29
6278    %val)</tt>.  Only one type, the return type, is overloaded, and only one type
6279    suffix is required. Because the argument's type is matched against the return
6280    type, it does not require its own name suffix.</p>
6281
6282 <p>To learn how to add an intrinsic function, please see the
6283    <a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p>
6284
6285 <!-- ======================================================================= -->
6286 <h3>
6287   <a name="int_varargs">Variable Argument Handling Intrinsics</a>
6288 </h3>
6289
6290 <div>
6291
6292 <p>Variable argument support is defined in LLVM with
6293    the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
6294    intrinsic functions.  These functions are related to the similarly named
6295    macros defined in the <tt>&lt;stdarg.h&gt;</tt> header file.</p>
6296
6297 <p>All of these functions operate on arguments that use a target-specific value
6298    type "<tt>va_list</tt>".  The LLVM assembly language reference manual does
6299    not define what this type is, so all transformations should be prepared to
6300    handle these functions regardless of the type used.</p>
6301
6302 <p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a>
6303    instruction and the variable argument handling intrinsic functions are
6304    used.</p>
6305
6306 <pre class="doc_code">
6307 define i32 @test(i32 %X, ...) {
6308   ; Initialize variable argument processing
6309   %ap = alloca i8*
6310   %ap2 = bitcast i8** %ap to i8*
6311   call void @llvm.va_start(i8* %ap2)
6312
6313   ; Read a single integer argument
6314   %tmp = va_arg i8** %ap, i32
6315
6316   ; Demonstrate usage of llvm.va_copy and llvm.va_end
6317   %aq = alloca i8*
6318   %aq2 = bitcast i8** %aq to i8*
6319   call void @llvm.va_copy(i8* %aq2, i8* %ap2)
6320   call void @llvm.va_end(i8* %aq2)
6321
6322   ; Stop processing of arguments.
6323   call void @llvm.va_end(i8* %ap2)
6324   ret i32 %tmp
6325 }
6326
6327 declare void @llvm.va_start(i8*)
6328 declare void @llvm.va_copy(i8*, i8*)
6329 declare void @llvm.va_end(i8*)
6330 </pre>
6331
6332 <!-- _______________________________________________________________________ -->
6333 <h4>
6334   <a name="int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
6335 </h4>
6336
6337
6338 <div>
6339
6340 <h5>Syntax:</h5>
6341 <pre>
6342   declare void %llvm.va_start(i8* &lt;arglist&gt;)
6343 </pre>
6344
6345 <h5>Overview:</h5>
6346 <p>The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*&lt;arglist&gt;</tt>
6347    for subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt>.</p>
6348
6349 <h5>Arguments:</h5>
6350 <p>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
6351
6352 <h5>Semantics:</h5>
6353 <p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
6354    macro available in C.  In a target-dependent way, it initializes
6355    the <tt>va_list</tt> element to which the argument points, so that the next
6356    call to <tt>va_arg</tt> will produce the first variable argument passed to
6357    the function.  Unlike the C <tt>va_start</tt> macro, this intrinsic does not
6358    need to know the last argument of the function as the compiler can figure
6359    that out.</p>
6360
6361 </div>
6362
6363 <!-- _______________________________________________________________________ -->
6364 <h4>
6365  <a name="int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
6366 </h4>
6367
6368 <div>
6369
6370 <h5>Syntax:</h5>
6371 <pre>
6372   declare void @llvm.va_end(i8* &lt;arglist&gt;)
6373 </pre>
6374
6375 <h5>Overview:</h5>
6376 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*&lt;arglist&gt;</tt>,
6377    which has been initialized previously
6378    with <tt><a href="#int_va_start">llvm.va_start</a></tt>
6379    or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
6380
6381 <h5>Arguments:</h5>
6382 <p>The argument is a pointer to a <tt>va_list</tt> to destroy.</p>
6383
6384 <h5>Semantics:</h5>
6385 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
6386    macro available in C.  In a target-dependent way, it destroys
6387    the <tt>va_list</tt> element to which the argument points.  Calls
6388    to <a href="#int_va_start"><tt>llvm.va_start</tt></a>
6389    and <a href="#int_va_copy"> <tt>llvm.va_copy</tt></a> must be matched exactly
6390    with calls to <tt>llvm.va_end</tt>.</p>
6391
6392 </div>
6393
6394 <!-- _______________________________________________________________________ -->
6395 <h4>
6396   <a name="int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
6397 </h4>
6398
6399 <div>
6400
6401 <h5>Syntax:</h5>
6402 <pre>
6403   declare void @llvm.va_copy(i8* &lt;destarglist&gt;, i8* &lt;srcarglist&gt;)
6404 </pre>
6405
6406 <h5>Overview:</h5>
6407 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position
6408    from the source argument list to the destination argument list.</p>
6409
6410 <h5>Arguments:</h5>
6411 <p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
6412    The second argument is a pointer to a <tt>va_list</tt> element to copy
6413    from.</p>
6414
6415 <h5>Semantics:</h5>
6416 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
6417    macro available in C.  In a target-dependent way, it copies the
6418    source <tt>va_list</tt> element into the destination <tt>va_list</tt>
6419    element.  This intrinsic is necessary because
6420    the <tt><a href="#int_va_start"> llvm.va_start</a></tt> intrinsic may be
6421    arbitrarily complex and require, for example, memory allocation.</p>
6422
6423 </div>
6424
6425 </div>
6426
6427 <!-- ======================================================================= -->
6428 <h3>
6429   <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
6430 </h3>
6431
6432 <div>
6433
6434 <p>LLVM support for <a href="GarbageCollection.html">Accurate Garbage
6435 Collection</a> (GC) requires the implementation and generation of these
6436 intrinsics. These intrinsics allow identification of <a href="#int_gcroot">GC
6437 roots on the stack</a>, as well as garbage collector implementations that
6438 require <a href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a>
6439 barriers.  Front-ends for type-safe garbage collected languages should generate
6440 these intrinsics to make use of the LLVM garbage collectors.  For more details,
6441 see <a href="GarbageCollection.html">Accurate Garbage Collection with
6442 LLVM</a>.</p>
6443
6444 <p>The garbage collection intrinsics only operate on objects in the generic
6445    address space (address space zero).</p>
6446
6447 <!-- _______________________________________________________________________ -->
6448 <h4>
6449   <a name="int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
6450 </h4>
6451
6452 <div>
6453
6454 <h5>Syntax:</h5>
6455 <pre>
6456   declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
6457 </pre>
6458
6459 <h5>Overview:</h5>
6460 <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
6461    the code generator, and allows some metadata to be associated with it.</p>
6462
6463 <h5>Arguments:</h5>
6464 <p>The first argument specifies the address of a stack object that contains the
6465    root pointer.  The second pointer (which must be either a constant or a
6466    global value address) contains the meta-data to be associated with the
6467    root.</p>
6468
6469 <h5>Semantics:</h5>
6470 <p>At runtime, a call to this intrinsic stores a null pointer into the "ptrloc"
6471    location.  At compile-time, the code generator generates information to allow
6472    the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>'
6473    intrinsic may only be used in a function which <a href="#gc">specifies a GC
6474    algorithm</a>.</p>
6475
6476 </div>
6477
6478 <!-- _______________________________________________________________________ -->
6479 <h4>
6480   <a name="int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
6481 </h4>
6482
6483 <div>
6484
6485 <h5>Syntax:</h5>
6486 <pre>
6487   declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
6488 </pre>
6489
6490 <h5>Overview:</h5>
6491 <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
6492    locations, allowing garbage collector implementations that require read
6493    barriers.</p>
6494
6495 <h5>Arguments:</h5>
6496 <p>The second argument is the address to read from, which should be an address
6497    allocated from the garbage collector.  The first object is a pointer to the
6498    start of the referenced object, if needed by the language runtime (otherwise
6499    null).</p>
6500
6501 <h5>Semantics:</h5>
6502 <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
6503    instruction, but may be replaced with substantially more complex code by the
6504    garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic
6505    may only be used in a function which <a href="#gc">specifies a GC
6506    algorithm</a>.</p>
6507
6508 </div>
6509
6510 <!-- _______________________________________________________________________ -->
6511 <h4>
6512   <a name="int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
6513 </h4>
6514
6515 <div>
6516
6517 <h5>Syntax:</h5>
6518 <pre>
6519   declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
6520 </pre>
6521
6522 <h5>Overview:</h5>
6523 <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
6524    locations, allowing garbage collector implementations that require write
6525    barriers (such as generational or reference counting collectors).</p>
6526
6527 <h5>Arguments:</h5>
6528 <p>The first argument is the reference to store, the second is the start of the
6529    object to store it to, and the third is the address of the field of Obj to
6530    store to.  If the runtime does not require a pointer to the object, Obj may
6531    be null.</p>
6532
6533 <h5>Semantics:</h5>
6534 <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
6535    instruction, but may be replaced with substantially more complex code by the
6536    garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic
6537    may only be used in a function which <a href="#gc">specifies a GC
6538    algorithm</a>.</p>
6539
6540 </div>
6541
6542 </div>
6543
6544 <!-- ======================================================================= -->
6545 <h3>
6546   <a name="int_codegen">Code Generator Intrinsics</a>
6547 </h3>
6548
6549 <div>
6550
6551 <p>These intrinsics are provided by LLVM to expose special features that may
6552    only be implemented with code generator support.</p>
6553
6554 <!-- _______________________________________________________________________ -->
6555 <h4>
6556   <a name="int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
6557 </h4>
6558
6559 <div>
6560
6561 <h5>Syntax:</h5>
6562 <pre>
6563   declare i8  *@llvm.returnaddress(i32 &lt;level&gt;)
6564 </pre>
6565
6566 <h5>Overview:</h5>
6567 <p>The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a
6568    target-specific value indicating the return address of the current function
6569    or one of its callers.</p>
6570
6571 <h5>Arguments:</h5>
6572 <p>The argument to this intrinsic indicates which function to return the address
6573    for.  Zero indicates the calling function, one indicates its caller, etc.
6574    The argument is <b>required</b> to be a constant integer value.</p>
6575
6576 <h5>Semantics:</h5>
6577 <p>The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer
6578    indicating the return address of the specified call frame, or zero if it
6579    cannot be identified.  The value returned by this intrinsic is likely to be
6580    incorrect or 0 for arguments other than zero, so it should only be used for
6581    debugging purposes.</p>
6582
6583 <p>Note that calling this intrinsic does not prevent function inlining or other
6584    aggressive transformations, so the value returned may not be that of the
6585    obvious source-language caller.</p>
6586
6587 </div>
6588
6589 <!-- _______________________________________________________________________ -->
6590 <h4>
6591   <a name="int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
6592 </h4>
6593
6594 <div>
6595
6596 <h5>Syntax:</h5>
6597 <pre>
6598   declare i8* @llvm.frameaddress(i32 &lt;level&gt;)
6599 </pre>
6600
6601 <h5>Overview:</h5>
6602 <p>The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the
6603    target-specific frame pointer value for the specified stack frame.</p>
6604
6605 <h5>Arguments:</h5>
6606 <p>The argument to this intrinsic indicates which function to return the frame
6607    pointer for.  Zero indicates the calling function, one indicates its caller,
6608    etc.  The argument is <b>required</b> to be a constant integer value.</p>
6609
6610 <h5>Semantics:</h5>
6611 <p>The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer
6612    indicating the frame address of the specified call frame, or zero if it
6613    cannot be identified.  The value returned by this intrinsic is likely to be
6614    incorrect or 0 for arguments other than zero, so it should only be used for
6615    debugging purposes.</p>
6616
6617 <p>Note that calling this intrinsic does not prevent function inlining or other
6618    aggressive transformations, so the value returned may not be that of the
6619    obvious source-language caller.</p>
6620
6621 </div>
6622
6623 <!-- _______________________________________________________________________ -->
6624 <h4>
6625   <a name="int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
6626 </h4>
6627
6628 <div>
6629
6630 <h5>Syntax:</h5>
6631 <pre>
6632   declare i8* @llvm.stacksave()
6633 </pre>
6634
6635 <h5>Overview:</h5>
6636 <p>The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state
6637    of the function stack, for use
6638    with <a href="#int_stackrestore"> <tt>llvm.stackrestore</tt></a>.  This is
6639    useful for implementing language features like scoped automatic variable
6640    sized arrays in C99.</p>
6641
6642 <h5>Semantics:</h5>
6643 <p>This intrinsic returns a opaque pointer value that can be passed
6644    to <a href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>.  When
6645    an <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved
6646    from <tt>llvm.stacksave</tt>, it effectively restores the state of the stack
6647    to the state it was in when the <tt>llvm.stacksave</tt> intrinsic executed.
6648    In practice, this pops any <a href="#i_alloca">alloca</a> blocks from the
6649    stack that were allocated after the <tt>llvm.stacksave</tt> was executed.</p>
6650
6651 </div>
6652
6653 <!-- _______________________________________________________________________ -->
6654 <h4>
6655   <a name="int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
6656 </h4>
6657
6658 <div>
6659
6660 <h5>Syntax:</h5>
6661 <pre>
6662   declare void @llvm.stackrestore(i8* %ptr)
6663 </pre>
6664
6665 <h5>Overview:</h5>
6666 <p>The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of
6667    the function stack to the state it was in when the
6668    corresponding <a href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic
6669    executed.  This is useful for implementing language features like scoped
6670    automatic variable sized arrays in C99.</p>
6671
6672 <h5>Semantics:</h5>
6673 <p>See the description
6674    for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>.</p>
6675
6676 </div>
6677
6678 <!-- _______________________________________________________________________ -->
6679 <h4>
6680   <a name="int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
6681 </h4>
6682
6683 <div>
6684
6685 <h5>Syntax:</h5>
6686 <pre>
6687   declare void @llvm.prefetch(i8* &lt;address&gt;, i32 &lt;rw&gt;, i32 &lt;locality&gt;, i32 &lt;cache type&gt;)
6688 </pre>
6689
6690 <h5>Overview:</h5>
6691 <p>The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to
6692    insert a prefetch instruction if supported; otherwise, it is a noop.
6693    Prefetches have no effect on the behavior of the program but can change its
6694    performance characteristics.</p>
6695
6696 <h5>Arguments:</h5>
6697 <p><tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the
6698    specifier determining if the fetch should be for a read (0) or write (1),
6699    and <tt>locality</tt> is a temporal locality specifier ranging from (0) - no
6700    locality, to (3) - extremely local keep in cache. The <tt>cache type</tt>
6701    specifies whether the prefetch is performed on the data (1) or instruction (0)
6702    cache. The <tt>rw</tt>, <tt>locality</tt> and <tt>cache type</tt> arguments
6703    must be constant integers.</p>
6704
6705 <h5>Semantics:</h5>
6706 <p>This intrinsic does not modify the behavior of the program.  In particular,
6707    prefetches cannot trap and do not produce a value.  On targets that support
6708    this intrinsic, the prefetch can provide hints to the processor cache for
6709    better performance.</p>
6710
6711 </div>
6712
6713 <!-- _______________________________________________________________________ -->
6714 <h4>
6715   <a name="int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
6716 </h4>
6717
6718 <div>
6719
6720 <h5>Syntax:</h5>
6721 <pre>
6722   declare void @llvm.pcmarker(i32 &lt;id&gt;)
6723 </pre>
6724
6725 <h5>Overview:</h5>
6726 <p>The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program
6727    Counter (PC) in a region of code to simulators and other tools.  The method
6728    is target specific, but it is expected that the marker will use exported
6729    symbols to transmit the PC of the marker.  The marker makes no guarantees
6730    that it will remain with any specific instruction after optimizations.  It is
6731    possible that the presence of a marker will inhibit optimizations.  The
6732    intended use is to be inserted after optimizations to allow correlations of
6733    simulation runs.</p>
6734
6735 <h5>Arguments:</h5>
6736 <p><tt>id</tt> is a numerical id identifying the marker.</p>
6737
6738 <h5>Semantics:</h5>
6739 <p>This intrinsic does not modify the behavior of the program.  Backends that do
6740    not support this intrinsic may ignore it.</p>
6741
6742 </div>
6743
6744 <!-- _______________________________________________________________________ -->
6745 <h4>
6746   <a name="int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
6747 </h4>
6748
6749 <div>
6750
6751 <h5>Syntax:</h5>
6752 <pre>
6753   declare i64 @llvm.readcyclecounter()
6754 </pre>
6755
6756 <h5>Overview:</h5>
6757 <p>The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle
6758    counter register (or similar low latency, high accuracy clocks) on those
6759    targets that support it.  On X86, it should map to RDTSC.  On Alpha, it
6760    should map to RPCC.  As the backing counters overflow quickly (on the order
6761    of 9 seconds on alpha), this should only be used for small timings.</p>
6762
6763 <h5>Semantics:</h5>
6764 <p>When directly supported, reading the cycle counter should not modify any
6765    memory.  Implementations are allowed to either return a application specific
6766    value or a system wide value.  On backends without support, this is lowered
6767    to a constant 0.</p>
6768
6769 </div>
6770
6771 </div>
6772
6773 <!-- ======================================================================= -->
6774 <h3>
6775   <a name="int_libc">Standard C Library Intrinsics</a>
6776 </h3>
6777
6778 <div>
6779
6780 <p>LLVM provides intrinsics for a few important standard C library functions.
6781    These intrinsics allow source-language front-ends to pass information about
6782    the alignment of the pointer arguments to the code generator, providing
6783    opportunity for more efficient code generation.</p>
6784
6785 <!-- _______________________________________________________________________ -->
6786 <h4>
6787   <a name="int_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
6788 </h4>
6789
6790 <div>
6791
6792 <h5>Syntax:</h5>
6793 <p>This is an overloaded intrinsic. You can use <tt>llvm.memcpy</tt> on any
6794    integer bit width and for different address spaces. Not all targets support
6795    all bit widths however.</p>
6796
6797 <pre>
6798   declare void @llvm.memcpy.p0i8.p0i8.i32(i8* &lt;dest&gt;, i8* &lt;src&gt;,
6799                                           i32 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
6800   declare void @llvm.memcpy.p0i8.p0i8.i64(i8* &lt;dest&gt;, i8* &lt;src&gt;,
6801                                           i64 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
6802 </pre>
6803
6804 <h5>Overview:</h5>
6805 <p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
6806    source location to the destination location.</p>
6807
6808 <p>Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
6809    intrinsics do not return a value, takes extra alignment/isvolatile arguments
6810    and the pointers can be in specified address spaces.</p>
6811
6812 <h5>Arguments:</h5>
6813
6814 <p>The first argument is a pointer to the destination, the second is a pointer
6815    to the source.  The third argument is an integer argument specifying the
6816    number of bytes to copy, the fourth argument is the alignment of the
6817    source and destination locations, and the fifth is a boolean indicating a
6818    volatile access.</p>
6819
6820 <p>If the call to this intrinsic has an alignment value that is not 0 or 1,
6821    then the caller guarantees that both the source and destination pointers are
6822    aligned to that boundary.</p>
6823
6824 <p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
6825    <tt>llvm.memcpy</tt> call is a <a href="#volatile">volatile operation</a>.
6826    The detailed access behavior is not very cleanly specified and it is unwise
6827    to depend on it.</p>
6828
6829 <h5>Semantics:</h5>
6830
6831 <p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
6832    source location to the destination location, which are not allowed to
6833    overlap.  It copies "len" bytes of memory over.  If the argument is known to
6834    be aligned to some boundary, this can be specified as the fourth argument,
6835    otherwise it should be set to 0 or 1.</p>
6836
6837 </div>
6838
6839 <!-- _______________________________________________________________________ -->
6840 <h4>
6841   <a name="int_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
6842 </h4>
6843
6844 <div>
6845
6846 <h5>Syntax:</h5>
6847 <p>This is an overloaded intrinsic. You can use llvm.memmove on any integer bit
6848    width and for different address space. Not all targets support all bit
6849    widths however.</p>
6850
6851 <pre>
6852   declare void @llvm.memmove.p0i8.p0i8.i32(i8* &lt;dest&gt;, i8* &lt;src&gt;,
6853                                            i32 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
6854   declare void @llvm.memmove.p0i8.p0i8.i64(i8* &lt;dest&gt;, i8* &lt;src&gt;,
6855                                            i64 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
6856 </pre>
6857
6858 <h5>Overview:</h5>
6859 <p>The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the
6860    source location to the destination location. It is similar to the
6861    '<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to
6862    overlap.</p>
6863
6864 <p>Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
6865    intrinsics do not return a value, takes extra alignment/isvolatile arguments
6866    and the pointers can be in specified address spaces.</p>
6867
6868 <h5>Arguments:</h5>
6869
6870 <p>The first argument is a pointer to the destination, the second is a pointer
6871    to the source.  The third argument is an integer argument specifying the
6872    number of bytes to copy, the fourth argument is the alignment of the
6873    source and destination locations, and the fifth is a boolean indicating a
6874    volatile access.</p>
6875
6876 <p>If the call to this intrinsic has an alignment value that is not 0 or 1,
6877    then the caller guarantees that the source and destination pointers are
6878    aligned to that boundary.</p>
6879
6880 <p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
6881    <tt>llvm.memmove</tt> call is a <a href="#volatile">volatile operation</a>.
6882    The detailed access behavior is not very cleanly specified and it is unwise
6883    to depend on it.</p>
6884
6885 <h5>Semantics:</h5>
6886
6887 <p>The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the
6888    source location to the destination location, which may overlap.  It copies
6889    "len" bytes of memory over.  If the argument is known to be aligned to some
6890    boundary, this can be specified as the fourth argument, otherwise it should
6891    be set to 0 or 1.</p>
6892
6893 </div>
6894
6895 <!-- _______________________________________________________________________ -->
6896 <h4>
6897   <a name="int_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
6898 </h4>
6899
6900 <div>
6901
6902 <h5>Syntax:</h5>
6903 <p>This is an overloaded intrinsic. You can use llvm.memset on any integer bit
6904    width and for different address spaces. However, not all targets support all
6905    bit widths.</p>
6906
6907 <pre>
6908   declare void @llvm.memset.p0i8.i32(i8* &lt;dest&gt;, i8 &lt;val&gt;,
6909                                      i32 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
6910   declare void @llvm.memset.p0i8.i64(i8* &lt;dest&gt;, i8 &lt;val&gt;,
6911                                      i64 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
6912 </pre>
6913
6914 <h5>Overview:</h5>
6915 <p>The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a
6916    particular byte value.</p>
6917
6918 <p>Note that, unlike the standard libc function, the <tt>llvm.memset</tt>
6919    intrinsic does not return a value and takes extra alignment/volatile
6920    arguments.  Also, the destination can be in an arbitrary address space.</p>
6921
6922 <h5>Arguments:</h5>
6923 <p>The first argument is a pointer to the destination to fill, the second is the
6924    byte value with which to fill it, the third argument is an integer argument
6925    specifying the number of bytes to fill, and the fourth argument is the known
6926    alignment of the destination location.</p>
6927
6928 <p>If the call to this intrinsic has an alignment value that is not 0 or 1,
6929    then the caller guarantees that the destination pointer is aligned to that
6930    boundary.</p>
6931
6932 <p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
6933    <tt>llvm.memset</tt> call is a <a href="#volatile">volatile operation</a>.
6934    The detailed access behavior is not very cleanly specified and it is unwise
6935    to depend on it.</p>
6936
6937 <h5>Semantics:</h5>
6938 <p>The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting
6939    at the destination location.  If the argument is known to be aligned to some
6940    boundary, this can be specified as the fourth argument, otherwise it should
6941    be set to 0 or 1.</p>
6942
6943 </div>
6944
6945 <!-- _______________________________________________________________________ -->
6946 <h4>
6947   <a name="int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
6948 </h4>
6949
6950 <div>
6951
6952 <h5>Syntax:</h5>
6953 <p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any
6954    floating point or vector of floating point type. Not all targets support all
6955    types however.</p>
6956
6957 <pre>
6958   declare float     @llvm.sqrt.f32(float %Val)
6959   declare double    @llvm.sqrt.f64(double %Val)
6960   declare x86_fp80  @llvm.sqrt.f80(x86_fp80 %Val)
6961   declare fp128     @llvm.sqrt.f128(fp128 %Val)
6962   declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
6963 </pre>
6964
6965 <h5>Overview:</h5>
6966 <p>The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand,
6967    returning the same value as the libm '<tt>sqrt</tt>' functions would.
6968    Unlike <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined
6969    behavior for negative numbers other than -0.0 (which allows for better
6970    optimization, because there is no need to worry about errno being
6971    set).  <tt>llvm.sqrt(-0.0)</tt> is defined to return -0.0 like IEEE sqrt.</p>
6972
6973 <h5>Arguments:</h5>
6974 <p>The argument and return value are floating point numbers of the same
6975    type.</p>
6976
6977 <h5>Semantics:</h5>
6978 <p>This function returns the sqrt of the specified operand if it is a
6979    nonnegative floating point number.</p>
6980
6981 </div>
6982
6983 <!-- _______________________________________________________________________ -->
6984 <h4>
6985   <a name="int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
6986 </h4>
6987
6988 <div>
6989
6990 <h5>Syntax:</h5>
6991 <p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any
6992    floating point or vector of floating point type. Not all targets support all
6993    types however.</p>
6994
6995 <pre>
6996   declare float     @llvm.powi.f32(float  %Val, i32 %power)
6997   declare double    @llvm.powi.f64(double %Val, i32 %power)
6998   declare x86_fp80  @llvm.powi.f80(x86_fp80  %Val, i32 %power)
6999   declare fp128     @llvm.powi.f128(fp128 %Val, i32 %power)
7000   declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128  %Val, i32 %power)
7001 </pre>
7002
7003 <h5>Overview:</h5>
7004 <p>The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the
7005    specified (positive or negative) power.  The order of evaluation of
7006    multiplications is not defined.  When a vector of floating point type is
7007    used, the second argument remains a scalar integer value.</p>
7008
7009 <h5>Arguments:</h5>
7010 <p>The second argument is an integer power, and the first is a value to raise to
7011    that power.</p>
7012
7013 <h5>Semantics:</h5>
7014 <p>This function returns the first value raised to the second power with an
7015    unspecified sequence of rounding operations.</p>
7016
7017 </div>
7018
7019 <!-- _______________________________________________________________________ -->
7020 <h4>
7021   <a name="int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a>
7022 </h4>
7023
7024 <div>
7025
7026 <h5>Syntax:</h5>
7027 <p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any
7028    floating point or vector of floating point type. Not all targets support all
7029    types however.</p>
7030
7031 <pre>
7032   declare float     @llvm.sin.f32(float  %Val)
7033   declare double    @llvm.sin.f64(double %Val)
7034   declare x86_fp80  @llvm.sin.f80(x86_fp80  %Val)
7035   declare fp128     @llvm.sin.f128(fp128 %Val)
7036   declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128  %Val)
7037 </pre>
7038
7039 <h5>Overview:</h5>
7040 <p>The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand.</p>
7041
7042 <h5>Arguments:</h5>
7043 <p>The argument and return value are floating point numbers of the same
7044    type.</p>
7045
7046 <h5>Semantics:</h5>
7047 <p>This function returns the sine of the specified operand, returning the same
7048    values as the libm <tt>sin</tt> functions would, and handles error conditions
7049    in the same way.</p>
7050
7051 </div>
7052
7053 <!-- _______________________________________________________________________ -->
7054 <h4>
7055   <a name="int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a>
7056 </h4>
7057
7058 <div>
7059
7060 <h5>Syntax:</h5>
7061 <p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any
7062    floating point or vector of floating point type. Not all targets support all
7063    types however.</p>
7064
7065 <pre>
7066   declare float     @llvm.cos.f32(float  %Val)
7067   declare double    @llvm.cos.f64(double %Val)
7068   declare x86_fp80  @llvm.cos.f80(x86_fp80  %Val)
7069   declare fp128     @llvm.cos.f128(fp128 %Val)
7070   declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128  %Val)
7071 </pre>
7072
7073 <h5>Overview:</h5>
7074 <p>The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand.</p>
7075
7076 <h5>Arguments:</h5>
7077 <p>The argument and return value are floating point numbers of the same
7078    type.</p>
7079
7080 <h5>Semantics:</h5>
7081 <p>This function returns the cosine of the specified operand, returning the same
7082    values as the libm <tt>cos</tt> functions would, and handles error conditions
7083    in the same way.</p>
7084
7085 </div>
7086
7087 <!-- _______________________________________________________________________ -->
7088 <h4>
7089   <a name="int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a>
7090 </h4>
7091
7092 <div>
7093
7094 <h5>Syntax:</h5>
7095 <p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any
7096    floating point or vector of floating point type. Not all targets support all
7097    types however.</p>
7098
7099 <pre>
7100   declare float     @llvm.pow.f32(float  %Val, float %Power)
7101   declare double    @llvm.pow.f64(double %Val, double %Power)
7102   declare x86_fp80  @llvm.pow.f80(x86_fp80  %Val, x86_fp80 %Power)
7103   declare fp128     @llvm.pow.f128(fp128 %Val, fp128 %Power)
7104   declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128  %Val, ppc_fp128 Power)
7105 </pre>
7106
7107 <h5>Overview:</h5>
7108 <p>The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the
7109    specified (positive or negative) power.</p>
7110
7111 <h5>Arguments:</h5>
7112 <p>The second argument is a floating point power, and the first is a value to
7113    raise to that power.</p>
7114
7115 <h5>Semantics:</h5>
7116 <p>This function returns the first value raised to the second power, returning
7117    the same values as the libm <tt>pow</tt> functions would, and handles error
7118    conditions in the same way.</p>
7119
7120 </div>
7121
7122 <!-- _______________________________________________________________________ -->
7123 <h4>
7124   <a name="int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a>
7125 </h4>
7126
7127 <div>
7128
7129 <h5>Syntax:</h5>
7130 <p>This is an overloaded intrinsic. You can use <tt>llvm.exp</tt> on any
7131    floating point or vector of floating point type. Not all targets support all
7132    types however.</p>
7133
7134 <pre>
7135   declare float     @llvm.exp.f32(float  %Val)
7136   declare double    @llvm.exp.f64(double %Val)
7137   declare x86_fp80  @llvm.exp.f80(x86_fp80  %Val)
7138   declare fp128     @llvm.exp.f128(fp128 %Val)
7139   declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128  %Val)
7140 </pre>
7141
7142 <h5>Overview:</h5>
7143 <p>The '<tt>llvm.exp.*</tt>' intrinsics perform the exp function.</p>
7144
7145 <h5>Arguments:</h5>
7146 <p>The argument and return value are floating point numbers of the same
7147    type.</p>
7148
7149 <h5>Semantics:</h5>
7150 <p>This function returns the same values as the libm <tt>exp</tt> functions
7151    would, and handles error conditions in the same way.</p>
7152
7153 </div>
7154
7155 <!-- _______________________________________________________________________ -->
7156 <h4>
7157   <a name="int_log">'<tt>llvm.log.*</tt>' Intrinsic</a>
7158 </h4>
7159
7160 <div>
7161
7162 <h5>Syntax:</h5>
7163 <p>This is an overloaded intrinsic. You can use <tt>llvm.log</tt> on any
7164    floating point or vector of floating point type. Not all targets support all
7165    types however.</p>
7166
7167 <pre>
7168   declare float     @llvm.log.f32(float  %Val)
7169   declare double    @llvm.log.f64(double %Val)
7170   declare x86_fp80  @llvm.log.f80(x86_fp80  %Val)
7171   declare fp128     @llvm.log.f128(fp128 %Val)
7172   declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128  %Val)
7173 </pre>
7174
7175 <h5>Overview:</h5>
7176 <p>The '<tt>llvm.log.*</tt>' intrinsics perform the log function.</p>
7177
7178 <h5>Arguments:</h5>
7179 <p>The argument and return value are floating point numbers of the same
7180    type.</p>
7181
7182 <h5>Semantics:</h5>
7183 <p>This function returns the same values as the libm <tt>log</tt> functions
7184    would, and handles error conditions in the same way.</p>
7185
7186 </div>
7187
7188 <!-- _______________________________________________________________________ -->
7189 <h4>
7190   <a name="int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a>
7191 </h4>
7192
7193 <div>
7194
7195 <h5>Syntax:</h5>
7196 <p>This is an overloaded intrinsic. You can use <tt>llvm.fma</tt> on any
7197    floating point or vector of floating point type. Not all targets support all
7198    types however.</p>
7199
7200 <pre>
7201   declare float     @llvm.fma.f32(float  %a, float  %b, float  %c)
7202   declare double    @llvm.fma.f64(double %a, double %b, double %c)
7203   declare x86_fp80  @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c)
7204   declare fp128     @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c)
7205   declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c)
7206 </pre>
7207
7208 <h5>Overview:</h5>
7209 <p>The '<tt>llvm.fma.*</tt>' intrinsics perform the fused multiply-add
7210    operation.</p>
7211
7212 <h5>Arguments:</h5>
7213 <p>The argument and return value are floating point numbers of the same
7214    type.</p>
7215
7216 <h5>Semantics:</h5>
7217 <p>This function returns the same values as the libm <tt>fma</tt> functions
7218    would.</p>
7219
7220 </div>
7221
7222 </div>
7223
7224 <!-- ======================================================================= -->
7225 <h3>
7226   <a name="int_manip">Bit Manipulation Intrinsics</a>
7227 </h3>
7228
7229 <div>
7230
7231 <p>LLVM provides intrinsics for a few important bit manipulation operations.
7232    These allow efficient code generation for some algorithms.</p>
7233
7234 <!-- _______________________________________________________________________ -->
7235 <h4>
7236   <a name="int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
7237 </h4>
7238
7239 <div>
7240
7241 <h5>Syntax:</h5>
7242 <p>This is an overloaded intrinsic function. You can use bswap on any integer
7243    type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p>
7244
7245 <pre>
7246   declare i16 @llvm.bswap.i16(i16 &lt;id&gt;)
7247   declare i32 @llvm.bswap.i32(i32 &lt;id&gt;)
7248   declare i64 @llvm.bswap.i64(i64 &lt;id&gt;)
7249 </pre>
7250
7251 <h5>Overview:</h5>
7252 <p>The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer
7253    values with an even number of bytes (positive multiple of 16 bits).  These
7254    are useful for performing operations on data that is not in the target's
7255    native byte order.</p>
7256
7257 <h5>Semantics:</h5>
7258 <p>The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high
7259    and low byte of the input i16 swapped.  Similarly,
7260    the <tt>llvm.bswap.i32</tt> intrinsic returns an i32 value that has the four
7261    bytes of the input i32 swapped, so that if the input bytes are numbered 0, 1,
7262    2, 3 then the returned i32 will have its bytes in 3, 2, 1, 0 order.
7263    The <tt>llvm.bswap.i48</tt>, <tt>llvm.bswap.i64</tt> and other intrinsics
7264    extend this concept to additional even-byte lengths (6 bytes, 8 bytes and
7265    more, respectively).</p>
7266
7267 </div>
7268
7269 <!-- _______________________________________________________________________ -->
7270 <h4>
7271   <a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
7272 </h4>
7273
7274 <div>
7275
7276 <h5>Syntax:</h5>
7277 <p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit
7278    width, or on any vector with integer elements. Not all targets support all
7279   bit widths or vector types, however.</p>
7280
7281 <pre>
7282   declare i8 @llvm.ctpop.i8(i8  &lt;src&gt;)
7283   declare i16 @llvm.ctpop.i16(i16 &lt;src&gt;)
7284   declare i32 @llvm.ctpop.i32(i32 &lt;src&gt;)
7285   declare i64 @llvm.ctpop.i64(i64 &lt;src&gt;)
7286   declare i256 @llvm.ctpop.i256(i256 &lt;src&gt;)
7287   declare &lt;2 x i32&gt; @llvm.ctpop.v2i32(&lt;2 x i32&gt; &lt;src&gt;)
7288 </pre>
7289
7290 <h5>Overview:</h5>
7291 <p>The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set
7292    in a value.</p>
7293
7294 <h5>Arguments:</h5>
7295 <p>The only argument is the value to be counted.  The argument may be of any
7296    integer type, or a vector with integer elements.
7297    The return type must match the argument type.</p>
7298
7299 <h5>Semantics:</h5>
7300 <p>The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable, or within each
7301    element of a vector.</p>
7302
7303 </div>
7304
7305 <!-- _______________________________________________________________________ -->
7306 <h4>
7307   <a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a>
7308 </h4>
7309
7310 <div>
7311
7312 <h5>Syntax:</h5>
7313 <p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any
7314    integer bit width, or any vector whose elements are integers. Not all
7315    targets support all bit widths or vector types, however.</p>
7316
7317 <pre>
7318   declare i8 @llvm.ctlz.i8 (i8  &lt;src&gt;)
7319   declare i16 @llvm.ctlz.i16(i16 &lt;src&gt;)
7320   declare i32 @llvm.ctlz.i32(i32 &lt;src&gt;)
7321   declare i64 @llvm.ctlz.i64(i64 &lt;src&gt;)
7322   declare i256 @llvm.ctlz.i256(i256 &lt;src&gt;)
7323   declare &lt;2 x i32&gt; @llvm.ctlz.v2i32(&lt;2 x i32&gt; &lt;src;gt)
7324 </pre>
7325
7326 <h5>Overview:</h5>
7327 <p>The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of
7328    leading zeros in a variable.</p>
7329
7330 <h5>Arguments:</h5>
7331 <p>The only argument is the value to be counted.  The argument may be of any
7332    integer type, or any vector type with integer element type.
7333    The return type must match the argument type.</p>
7334
7335 <h5>Semantics:</h5>
7336 <p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant)
7337    zeros in a variable, or within each element of the vector if the operation
7338    is of vector type.  If the src == 0 then the result is the size in bits of
7339    the type of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p>
7340
7341 </div>
7342
7343 <!-- _______________________________________________________________________ -->
7344 <h4>
7345   <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a>
7346 </h4>
7347
7348 <div>
7349
7350 <h5>Syntax:</h5>
7351 <p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any
7352    integer bit width, or any vector of integer elements. Not all targets
7353    support all bit widths or vector types, however.</p>
7354
7355 <pre>
7356   declare i8 @llvm.cttz.i8 (i8  &lt;src&gt;)
7357   declare i16 @llvm.cttz.i16(i16 &lt;src&gt;)
7358   declare i32 @llvm.cttz.i32(i32 &lt;src&gt;)
7359   declare i64 @llvm.cttz.i64(i64 &lt;src&gt;)
7360   declare i256 @llvm.cttz.i256(i256 &lt;src&gt;)
7361   declase &lt;2 x i32&gt; @llvm.cttz.v2i32(&lt;2 x i32&gt; &lt;src&gt;)
7362 </pre>
7363
7364 <h5>Overview:</h5>
7365 <p>The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of
7366    trailing zeros.</p>
7367
7368 <h5>Arguments:</h5>
7369 <p>The only argument is the value to be counted.  The argument may be of any
7370    integer type, or a vectory with integer element type..  The return type
7371    must match the argument type.</p>
7372
7373 <h5>Semantics:</h5>
7374 <p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant)
7375    zeros in a variable, or within each element of a vector.
7376    If the src == 0 then the result is the size in bits of
7377    the type of src.  For example, <tt>llvm.cttz(2) = 1</tt>.</p>
7378
7379 </div>
7380
7381 </div>
7382
7383 <!-- ======================================================================= -->
7384 <h3>
7385   <a name="int_overflow">Arithmetic with Overflow Intrinsics</a>
7386 </h3>
7387
7388 <div>
7389
7390 <p>LLVM provides intrinsics for some arithmetic with overflow operations.</p>
7391
7392 <!-- _______________________________________________________________________ -->
7393 <h4>
7394   <a name="int_sadd_overflow">
7395     '<tt>llvm.sadd.with.overflow.*</tt>' Intrinsics
7396   </a>
7397 </h4>
7398
7399 <div>
7400
7401 <h5>Syntax:</h5>
7402 <p>This is an overloaded intrinsic. You can use <tt>llvm.sadd.with.overflow</tt>
7403    on any integer bit width.</p>
7404
7405 <pre>
7406   declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
7407   declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
7408   declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
7409 </pre>
7410
7411 <h5>Overview:</h5>
7412 <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
7413    a signed addition of the two arguments, and indicate whether an overflow
7414    occurred during the signed summation.</p>
7415
7416 <h5>Arguments:</h5>
7417 <p>The arguments (%a and %b) and the first element of the result structure may
7418    be of integer types of any bit width, but they must have the same bit
7419    width. The second element of the result structure must be of
7420    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
7421    undergo signed addition.</p>
7422
7423 <h5>Semantics:</h5>
7424 <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
7425    a signed addition of the two variables. They return a structure &mdash; the
7426    first element of which is the signed summation, and the second element of
7427    which is a bit specifying if the signed summation resulted in an
7428    overflow.</p>
7429
7430 <h5>Examples:</h5>
7431 <pre>
7432   %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
7433   %sum = extractvalue {i32, i1} %res, 0
7434   %obit = extractvalue {i32, i1} %res, 1
7435   br i1 %obit, label %overflow, label %normal
7436 </pre>
7437
7438 </div>
7439
7440 <!-- _______________________________________________________________________ -->
7441 <h4>
7442   <a name="int_uadd_overflow">
7443     '<tt>llvm.uadd.with.overflow.*</tt>' Intrinsics
7444   </a>
7445 </h4>
7446
7447 <div>
7448
7449 <h5>Syntax:</h5>
7450 <p>This is an overloaded intrinsic. You can use <tt>llvm.uadd.with.overflow</tt>
7451    on any integer bit width.</p>
7452
7453 <pre>
7454   declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
7455   declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
7456   declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
7457 </pre>
7458
7459 <h5>Overview:</h5>
7460 <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
7461    an unsigned addition of the two arguments, and indicate whether a carry
7462    occurred during the unsigned summation.</p>
7463
7464 <h5>Arguments:</h5>
7465 <p>The arguments (%a and %b) and the first element of the result structure may
7466    be of integer types of any bit width, but they must have the same bit
7467    width. The second element of the result structure must be of
7468    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
7469    undergo unsigned addition.</p>
7470
7471 <h5>Semantics:</h5>
7472 <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
7473    an unsigned addition of the two arguments. They return a structure &mdash;
7474    the first element of which is the sum, and the second element of which is a
7475    bit specifying if the unsigned summation resulted in a carry.</p>
7476
7477 <h5>Examples:</h5>
7478 <pre>
7479   %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
7480   %sum = extractvalue {i32, i1} %res, 0
7481   %obit = extractvalue {i32, i1} %res, 1
7482   br i1 %obit, label %carry, label %normal
7483 </pre>
7484
7485 </div>
7486
7487 <!-- _______________________________________________________________________ -->
7488 <h4>
7489   <a name="int_ssub_overflow">
7490     '<tt>llvm.ssub.with.overflow.*</tt>' Intrinsics
7491   </a>
7492 </h4>
7493
7494 <div>
7495
7496 <h5>Syntax:</h5>
7497 <p>This is an overloaded intrinsic. You can use <tt>llvm.ssub.with.overflow</tt>
7498    on any integer bit width.</p>
7499
7500 <pre>
7501   declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
7502   declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
7503   declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
7504 </pre>
7505
7506 <h5>Overview:</h5>
7507 <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
7508    a signed subtraction of the two arguments, and indicate whether an overflow
7509    occurred during the signed subtraction.</p>
7510
7511 <h5>Arguments:</h5>
7512 <p>The arguments (%a and %b) and the first element of the result structure may
7513    be of integer types of any bit width, but they must have the same bit
7514    width. The second element of the result structure must be of
7515    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
7516    undergo signed subtraction.</p>
7517
7518 <h5>Semantics:</h5>
7519 <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
7520    a signed subtraction of the two arguments. They return a structure &mdash;
7521    the first element of which is the subtraction, and the second element of
7522    which is a bit specifying if the signed subtraction resulted in an
7523    overflow.</p>
7524
7525 <h5>Examples:</h5>
7526 <pre>
7527   %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
7528   %sum = extractvalue {i32, i1} %res, 0
7529   %obit = extractvalue {i32, i1} %res, 1
7530   br i1 %obit, label %overflow, label %normal
7531 </pre>
7532
7533 </div>
7534
7535 <!-- _______________________________________________________________________ -->
7536 <h4>
7537   <a name="int_usub_overflow">
7538     '<tt>llvm.usub.with.overflow.*</tt>' Intrinsics
7539   </a>
7540 </h4>
7541
7542 <div>
7543
7544 <h5>Syntax:</h5>
7545 <p>This is an overloaded intrinsic. You can use <tt>llvm.usub.with.overflow</tt>
7546    on any integer bit width.</p>
7547
7548 <pre>
7549   declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
7550   declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
7551   declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
7552 </pre>
7553
7554 <h5>Overview:</h5>
7555 <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
7556    an unsigned subtraction of the two arguments, and indicate whether an
7557    overflow occurred during the unsigned subtraction.</p>
7558
7559 <h5>Arguments:</h5>
7560 <p>The arguments (%a and %b) and the first element of the result structure may
7561    be of integer types of any bit width, but they must have the same bit
7562    width. The second element of the result structure must be of
7563    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
7564    undergo unsigned subtraction.</p>
7565
7566 <h5>Semantics:</h5>
7567 <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
7568    an unsigned subtraction of the two arguments. They return a structure &mdash;
7569    the first element of which is the subtraction, and the second element of
7570    which is a bit specifying if the unsigned subtraction resulted in an
7571    overflow.</p>
7572
7573 <h5>Examples:</h5>
7574 <pre>
7575   %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
7576   %sum = extractvalue {i32, i1} %res, 0
7577   %obit = extractvalue {i32, i1} %res, 1
7578   br i1 %obit, label %overflow, label %normal
7579 </pre>
7580
7581 </div>
7582
7583 <!-- _______________________________________________________________________ -->
7584 <h4>
7585   <a name="int_smul_overflow">
7586     '<tt>llvm.smul.with.overflow.*</tt>' Intrinsics
7587   </a>
7588 </h4>
7589
7590 <div>
7591
7592 <h5>Syntax:</h5>
7593 <p>This is an overloaded intrinsic. You can use <tt>llvm.smul.with.overflow</tt>
7594    on any integer bit width.</p>
7595
7596 <pre>
7597   declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
7598   declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
7599   declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
7600 </pre>
7601
7602 <h5>Overview:</h5>
7603
7604 <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
7605    a signed multiplication of the two arguments, and indicate whether an
7606    overflow occurred during the signed multiplication.</p>
7607
7608 <h5>Arguments:</h5>
7609 <p>The arguments (%a and %b) and the first element of the result structure may
7610    be of integer types of any bit width, but they must have the same bit
7611    width. The second element of the result structure must be of
7612    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
7613    undergo signed multiplication.</p>
7614
7615 <h5>Semantics:</h5>
7616 <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
7617    a signed multiplication of the two arguments. They return a structure &mdash;
7618    the first element of which is the multiplication, and the second element of
7619    which is a bit specifying if the signed multiplication resulted in an
7620    overflow.</p>
7621
7622 <h5>Examples:</h5>
7623 <pre>
7624   %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
7625   %sum = extractvalue {i32, i1} %res, 0
7626   %obit = extractvalue {i32, i1} %res, 1
7627   br i1 %obit, label %overflow, label %normal
7628 </pre>
7629
7630 </div>
7631
7632 <!-- _______________________________________________________________________ -->
7633 <h4>
7634   <a name="int_umul_overflow">
7635     '<tt>llvm.umul.with.overflow.*</tt>' Intrinsics
7636   </a>
7637 </h4>
7638
7639 <div>
7640
7641 <h5>Syntax:</h5>
7642 <p>This is an overloaded intrinsic. You can use <tt>llvm.umul.with.overflow</tt>
7643    on any integer bit width.</p>
7644
7645 <pre>
7646   declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
7647   declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
7648   declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
7649 </pre>
7650
7651 <h5>Overview:</h5>
7652 <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
7653    a unsigned multiplication of the two arguments, and indicate whether an
7654    overflow occurred during the unsigned multiplication.</p>
7655
7656 <h5>Arguments:</h5>
7657 <p>The arguments (%a and %b) and the first element of the result structure may
7658    be of integer types of any bit width, but they must have the same bit
7659    width. The second element of the result structure must be of
7660    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
7661    undergo unsigned multiplication.</p>
7662
7663 <h5>Semantics:</h5>
7664 <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
7665    an unsigned multiplication of the two arguments. They return a structure
7666    &mdash; the first element of which is the multiplication, and the second
7667    element of which is a bit specifying if the unsigned multiplication resulted
7668    in an overflow.</p>
7669
7670 <h5>Examples:</h5>
7671 <pre>
7672   %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
7673   %sum = extractvalue {i32, i1} %res, 0
7674   %obit = extractvalue {i32, i1} %res, 1
7675   br i1 %obit, label %overflow, label %normal
7676 </pre>
7677
7678 </div>
7679
7680 </div>
7681
7682 <!-- ======================================================================= -->
7683 <h3>
7684   <a name="int_fp16">Half Precision Floating Point Intrinsics</a>
7685 </h3>
7686
7687 <div>
7688
7689 <p>Half precision floating point is a storage-only format. This means that it is
7690    a dense encoding (in memory) but does not support computation in the
7691    format.</p>
7692
7693 <p>This means that code must first load the half-precision floating point
7694    value as an i16, then convert it to float with <a
7695    href="#int_convert_from_fp16"><tt>llvm.convert.from.fp16</tt></a>.
7696    Computation can then be performed on the float value (including extending to
7697    double etc).  To store the value back to memory, it is first converted to
7698    float if needed, then converted to i16 with
7699    <a href="#int_convert_to_fp16"><tt>llvm.convert.to.fp16</tt></a>, then
7700    storing as an i16 value.</p>
7701
7702 <!-- _______________________________________________________________________ -->
7703 <h4>
7704   <a name="int_convert_to_fp16">
7705     '<tt>llvm.convert.to.fp16</tt>' Intrinsic
7706   </a>
7707 </h4>
7708
7709 <div>
7710
7711 <h5>Syntax:</h5>
7712 <pre>
7713   declare i16 @llvm.convert.to.fp16(f32 %a)
7714 </pre>
7715
7716 <h5>Overview:</h5>
7717 <p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs
7718    a conversion from single precision floating point format to half precision
7719    floating point format.</p>
7720
7721 <h5>Arguments:</h5>
7722 <p>The intrinsic function contains single argument - the value to be
7723    converted.</p>
7724
7725 <h5>Semantics:</h5>
7726 <p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs
7727    a conversion from single precision floating point format to half precision
7728    floating point format. The return value is an <tt>i16</tt> which
7729    contains the converted number.</p>
7730
7731 <h5>Examples:</h5>
7732 <pre>
7733   %res = call i16 @llvm.convert.to.fp16(f32 %a)
7734   store i16 %res, i16* @x, align 2
7735 </pre>
7736
7737 </div>
7738
7739 <!-- _______________________________________________________________________ -->
7740 <h4>
7741   <a name="int_convert_from_fp16">
7742     '<tt>llvm.convert.from.fp16</tt>' Intrinsic
7743   </a>
7744 </h4>
7745
7746 <div>
7747
7748 <h5>Syntax:</h5>
7749 <pre>
7750   declare f32 @llvm.convert.from.fp16(i16 %a)
7751 </pre>
7752
7753 <h5>Overview:</h5>
7754 <p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs
7755    a conversion from half precision floating point format to single precision
7756    floating point format.</p>
7757
7758 <h5>Arguments:</h5>
7759 <p>The intrinsic function contains single argument - the value to be
7760    converted.</p>
7761
7762 <h5>Semantics:</h5>
7763 <p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs a
7764    conversion from half single precision floating point format to single
7765    precision floating point format. The input half-float value is represented by
7766    an <tt>i16</tt> value.</p>
7767
7768 <h5>Examples:</h5>
7769 <pre>
7770   %a = load i16* @x, align 2
7771   %res = call f32 @llvm.convert.from.fp16(i16 %a)
7772 </pre>
7773
7774 </div>
7775
7776 </div>
7777
7778 <!-- ======================================================================= -->
7779 <h3>
7780   <a name="int_debugger">Debugger Intrinsics</a>
7781 </h3>
7782
7783 <div>
7784
7785 <p>The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt>
7786    prefix), are described in
7787    the <a href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source
7788    Level Debugging</a> document.</p>
7789
7790 </div>
7791
7792 <!-- ======================================================================= -->
7793 <h3>
7794   <a name="int_eh">Exception Handling Intrinsics</a>
7795 </h3>
7796
7797 <div>
7798
7799 <p>The LLVM exception handling intrinsics (which all start with
7800    <tt>llvm.eh.</tt> prefix), are described in
7801    the <a href="ExceptionHandling.html#format_common_intrinsics">LLVM Exception
7802    Handling</a> document.</p>
7803
7804 </div>
7805
7806 <!-- ======================================================================= -->
7807 <h3>
7808   <a name="int_trampoline">Trampoline Intrinsics</a>
7809 </h3>
7810
7811 <div>
7812
7813 <p>These intrinsics make it possible to excise one parameter, marked with
7814    the <a href="#nest"><tt>nest</tt></a> attribute, from a function.
7815    The result is a callable
7816    function pointer lacking the nest parameter - the caller does not need to
7817    provide a value for it.  Instead, the value to use is stored in advance in a
7818    "trampoline", a block of memory usually allocated on the stack, which also
7819    contains code to splice the nest value into the argument list.  This is used
7820    to implement the GCC nested function address extension.</p>
7821
7822 <p>For example, if the function is
7823    <tt>i32 f(i8* nest %c, i32 %x, i32 %y)</tt> then the resulting function
7824    pointer has signature <tt>i32 (i32, i32)*</tt>.  It can be created as
7825    follows:</p>
7826
7827 <pre class="doc_code">
7828   %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
7829   %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
7830   call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval)
7831   %p = call i8* @llvm.adjust.trampoline(i8* %tramp1)
7832   %fp = bitcast i8* %p to i32 (i32, i32)*
7833 </pre>
7834
7835 <p>The call <tt>%val = call i32 %fp(i32 %x, i32 %y)</tt> is then equivalent
7836    to <tt>%val = call i32 %f(i8* %nval, i32 %x, i32 %y)</tt>.</p>
7837
7838 <!-- _______________________________________________________________________ -->
7839 <h4>
7840   <a name="int_it">
7841     '<tt>llvm.init.trampoline</tt>' Intrinsic
7842   </a>
7843 </h4>
7844
7845 <div>
7846
7847 <h5>Syntax:</h5>
7848 <pre>
7849   declare void @llvm.init.trampoline(i8* &lt;tramp&gt;, i8* &lt;func&gt;, i8* &lt;nval&gt;)
7850 </pre>
7851
7852 <h5>Overview:</h5>
7853 <p>This fills the memory pointed to by <tt>tramp</tt> with executable code,
7854    turning it into a trampoline.</p>
7855
7856 <h5>Arguments:</h5>
7857 <p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all
7858    pointers.  The <tt>tramp</tt> argument must point to a sufficiently large and
7859    sufficiently aligned block of memory; this memory is written to by the
7860    intrinsic.  Note that the size and the alignment are target-specific - LLVM
7861    currently provides no portable way of determining them, so a front-end that
7862    generates this intrinsic needs to have some target-specific knowledge.
7863    The <tt>func</tt> argument must hold a function bitcast to
7864    an <tt>i8*</tt>.</p>
7865
7866 <h5>Semantics:</h5>
7867 <p>The block of memory pointed to by <tt>tramp</tt> is filled with target
7868    dependent code, turning it into a function.  Then <tt>tramp</tt> needs to be
7869    passed to <a href="#int_at">llvm.adjust.trampoline</a> to get a pointer
7870    which can be <a href="#int_trampoline">bitcast (to a new function) and
7871    called</a>.  The new function's signature is the same as that of
7872    <tt>func</tt> with any arguments marked with the <tt>nest</tt> attribute
7873    removed.  At most one such <tt>nest</tt> argument is allowed, and it must be of
7874    pointer type.  Calling the new function is equivalent to calling <tt>func</tt>
7875    with the same argument list, but with <tt>nval</tt> used for the missing
7876    <tt>nest</tt> argument.  If, after calling <tt>llvm.init.trampoline</tt>, the
7877    memory pointed to by <tt>tramp</tt> is modified, then the effect of any later call
7878    to the returned function pointer is undefined.</p>
7879 </div>
7880
7881 <!-- _______________________________________________________________________ -->
7882 <h4>
7883   <a name="int_at">
7884     '<tt>llvm.adjust.trampoline</tt>' Intrinsic
7885   </a>
7886 </h4>
7887
7888 <div>
7889
7890 <h5>Syntax:</h5>
7891 <pre>
7892   declare i8* @llvm.adjust.trampoline(i8* &lt;tramp&gt;)
7893 </pre>
7894
7895 <h5>Overview:</h5>
7896 <p>This performs any required machine-specific adjustment to the address of a
7897    trampoline (passed as <tt>tramp</tt>).</p>
7898
7899 <h5>Arguments:</h5>
7900 <p><tt>tramp</tt> must point to a block of memory which already has trampoline code
7901    filled in by a previous call to <a href="#int_it"><tt>llvm.init.trampoline</tt>
7902    </a>.</p>
7903
7904 <h5>Semantics:</h5>
7905 <p>On some architectures the address of the code to be executed needs to be
7906    different to the address where the trampoline is actually stored.  This
7907    intrinsic returns the executable address corresponding to <tt>tramp</tt>
7908    after performing the required machine specific adjustments.
7909    The pointer returned can then be <a href="#int_trampoline"> bitcast and
7910    executed</a>.
7911 </p>
7912
7913 </div>
7914
7915 </div>
7916
7917 <!-- ======================================================================= -->
7918 <h3>
7919   <a name="int_memorymarkers">Memory Use Markers</a>
7920 </h3>
7921
7922 <div>
7923
7924 <p>This class of intrinsics exists to information about the lifetime of memory
7925    objects and ranges where variables are immutable.</p>
7926
7927 <!-- _______________________________________________________________________ -->
7928 <h4>
7929   <a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a>
7930 </h4>
7931
7932 <div>
7933
7934 <h5>Syntax:</h5>
7935 <pre>
7936   declare void @llvm.lifetime.start(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
7937 </pre>
7938
7939 <h5>Overview:</h5>
7940 <p>The '<tt>llvm.lifetime.start</tt>' intrinsic specifies the start of a memory
7941    object's lifetime.</p>
7942
7943 <h5>Arguments:</h5>
7944 <p>The first argument is a constant integer representing the size of the
7945    object, or -1 if it is variable sized.  The second argument is a pointer to
7946    the object.</p>
7947
7948 <h5>Semantics:</h5>
7949 <p>This intrinsic indicates that before this point in the code, the value of the
7950    memory pointed to by <tt>ptr</tt> is dead.  This means that it is known to
7951    never be used and has an undefined value.  A load from the pointer that
7952    precedes this intrinsic can be replaced with
7953    <tt>'<a href="#undefvalues">undef</a>'</tt>.</p>
7954
7955 </div>
7956
7957 <!-- _______________________________________________________________________ -->
7958 <h4>
7959   <a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a>
7960 </h4>
7961
7962 <div>
7963
7964 <h5>Syntax:</h5>
7965 <pre>
7966   declare void @llvm.lifetime.end(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
7967 </pre>
7968
7969 <h5>Overview:</h5>
7970 <p>The '<tt>llvm.lifetime.end</tt>' intrinsic specifies the end of a memory
7971    object's lifetime.</p>
7972
7973 <h5>Arguments:</h5>
7974 <p>The first argument is a constant integer representing the size of the
7975    object, or -1 if it is variable sized.  The second argument is a pointer to
7976    the object.</p>
7977
7978 <h5>Semantics:</h5>
7979 <p>This intrinsic indicates that after this point in the code, the value of the
7980    memory pointed to by <tt>ptr</tt> is dead.  This means that it is known to
7981    never be used and has an undefined value.  Any stores into the memory object
7982    following this intrinsic may be removed as dead.
7983
7984 </div>
7985
7986 <!-- _______________________________________________________________________ -->
7987 <h4>
7988   <a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a>
7989 </h4>
7990
7991 <div>
7992
7993 <h5>Syntax:</h5>
7994 <pre>
7995   declare {}* @llvm.invariant.start(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
7996 </pre>
7997
7998 <h5>Overview:</h5>
7999 <p>The '<tt>llvm.invariant.start</tt>' intrinsic specifies that the contents of
8000    a memory object will not change.</p>
8001
8002 <h5>Arguments:</h5>
8003 <p>The first argument is a constant integer representing the size of the
8004    object, or -1 if it is variable sized.  The second argument is a pointer to
8005    the object.</p>
8006
8007 <h5>Semantics:</h5>
8008 <p>This intrinsic indicates that until an <tt>llvm.invariant.end</tt> that uses
8009    the return value, the referenced memory location is constant and
8010    unchanging.</p>
8011
8012 </div>
8013
8014 <!-- _______________________________________________________________________ -->
8015 <h4>
8016   <a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a>
8017 </h4>
8018
8019 <div>
8020
8021 <h5>Syntax:</h5>
8022 <pre>
8023   declare void @llvm.invariant.end({}* &lt;start&gt;, i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
8024 </pre>
8025
8026 <h5>Overview:</h5>
8027 <p>The '<tt>llvm.invariant.end</tt>' intrinsic specifies that the contents of
8028    a memory object are mutable.</p>
8029
8030 <h5>Arguments:</h5>
8031 <p>The first argument is the matching <tt>llvm.invariant.start</tt> intrinsic.
8032    The second argument is a constant integer representing the size of the
8033    object, or -1 if it is variable sized and the third argument is a pointer
8034    to the object.</p>
8035
8036 <h5>Semantics:</h5>
8037 <p>This intrinsic indicates that the memory is mutable again.</p>
8038
8039 </div>
8040
8041 </div>
8042
8043 <!-- ======================================================================= -->
8044 <h3>
8045   <a name="int_general">General Intrinsics</a>
8046 </h3>
8047
8048 <div>
8049
8050 <p>This class of intrinsics is designed to be generic and has no specific
8051    purpose.</p>
8052
8053 <!-- _______________________________________________________________________ -->
8054 <h4>
8055   <a name="int_var_annotation">'<tt>llvm.var.annotation</tt>' Intrinsic</a>
8056 </h4>
8057
8058 <div>
8059
8060 <h5>Syntax:</h5>
8061 <pre>
8062   declare void @llvm.var.annotation(i8* &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt;)
8063 </pre>
8064
8065 <h5>Overview:</h5>
8066 <p>The '<tt>llvm.var.annotation</tt>' intrinsic.</p>
8067
8068 <h5>Arguments:</h5>
8069 <p>The first argument is a pointer to a value, the second is a pointer to a
8070    global string, the third is a pointer to a global string which is the source
8071    file name, and the last argument is the line number.</p>
8072
8073 <h5>Semantics:</h5>
8074 <p>This intrinsic allows annotation of local variables with arbitrary strings.
8075    This can be useful for special purpose optimizations that want to look for
8076    these annotations.  These have no other defined use; they are ignored by code
8077    generation and optimization.</p>
8078
8079 </div>
8080
8081 <!-- _______________________________________________________________________ -->
8082 <h4>
8083   <a name="int_annotation">'<tt>llvm.annotation.*</tt>' Intrinsic</a>
8084 </h4>
8085
8086 <div>
8087
8088 <h5>Syntax:</h5>
8089 <p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on
8090    any integer bit width.</p>
8091
8092 <pre>
8093   declare i8 @llvm.annotation.i8(i8 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt;)
8094   declare i16 @llvm.annotation.i16(i16 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt;)
8095   declare i32 @llvm.annotation.i32(i32 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt;)
8096   declare i64 @llvm.annotation.i64(i64 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt;)
8097   declare i256 @llvm.annotation.i256(i256 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt;)
8098 </pre>
8099
8100 <h5>Overview:</h5>
8101 <p>The '<tt>llvm.annotation</tt>' intrinsic.</p>
8102
8103 <h5>Arguments:</h5>
8104 <p>The first argument is an integer value (result of some expression), the
8105    second is a pointer to a global string, the third is a pointer to a global
8106    string which is the source file name, and the last argument is the line
8107    number.  It returns the value of the first argument.</p>
8108
8109 <h5>Semantics:</h5>
8110 <p>This intrinsic allows annotations to be put on arbitrary expressions with
8111    arbitrary strings.  This can be useful for special purpose optimizations that
8112    want to look for these annotations.  These have no other defined use; they
8113    are ignored by code generation and optimization.</p>
8114
8115 </div>
8116
8117 <!-- _______________________________________________________________________ -->
8118 <h4>
8119   <a name="int_trap">'<tt>llvm.trap</tt>' Intrinsic</a>
8120 </h4>
8121
8122 <div>
8123
8124 <h5>Syntax:</h5>
8125 <pre>
8126   declare void @llvm.trap()
8127 </pre>
8128
8129 <h5>Overview:</h5>
8130 <p>The '<tt>llvm.trap</tt>' intrinsic.</p>
8131
8132 <h5>Arguments:</h5>
8133 <p>None.</p>
8134
8135 <h5>Semantics:</h5>
8136 <p>This intrinsics is lowered to the target dependent trap instruction. If the
8137    target does not have a trap instruction, this intrinsic will be lowered to
8138    the call of the <tt>abort()</tt> function.</p>
8139
8140 </div>
8141
8142 <!-- _______________________________________________________________________ -->
8143 <h4>
8144   <a name="int_stackprotector">'<tt>llvm.stackprotector</tt>' Intrinsic</a>
8145 </h4>
8146
8147 <div>
8148
8149 <h5>Syntax:</h5>
8150 <pre>
8151   declare void @llvm.stackprotector(i8* &lt;guard&gt;, i8** &lt;slot&gt;)
8152 </pre>
8153
8154 <h5>Overview:</h5>
8155 <p>The <tt>llvm.stackprotector</tt> intrinsic takes the <tt>guard</tt> and
8156    stores it onto the stack at <tt>slot</tt>. The stack slot is adjusted to
8157    ensure that it is placed on the stack before local variables.</p>
8158
8159 <h5>Arguments:</h5>
8160 <p>The <tt>llvm.stackprotector</tt> intrinsic requires two pointer
8161    arguments. The first argument is the value loaded from the stack
8162    guard <tt>@__stack_chk_guard</tt>. The second variable is an <tt>alloca</tt>
8163    that has enough space to hold the value of the guard.</p>
8164
8165 <h5>Semantics:</h5>
8166 <p>This intrinsic causes the prologue/epilogue inserter to force the position of
8167    the <tt>AllocaInst</tt> stack slot to be before local variables on the
8168    stack. This is to ensure that if a local variable on the stack is
8169    overwritten, it will destroy the value of the guard. When the function exits,
8170    the guard on the stack is checked against the original guard. If they are
8171    different, then the program aborts by calling the <tt>__stack_chk_fail()</tt>
8172    function.</p>
8173
8174 </div>
8175
8176 <!-- _______________________________________________________________________ -->
8177 <h4>
8178   <a name="int_objectsize">'<tt>llvm.objectsize</tt>' Intrinsic</a>
8179 </h4>
8180
8181 <div>
8182
8183 <h5>Syntax:</h5>
8184 <pre>
8185   declare i32 @llvm.objectsize.i32(i8* &lt;object&gt;, i1 &lt;type&gt;)
8186   declare i64 @llvm.objectsize.i64(i8* &lt;object&gt;, i1 &lt;type&gt;)
8187 </pre>
8188
8189 <h5>Overview:</h5>
8190 <p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information to
8191    the optimizers to determine at compile time whether a) an operation (like
8192    memcpy) will overflow a buffer that corresponds to an object, or b) that a
8193    runtime check for overflow isn't necessary. An object in this context means
8194    an allocation of a specific class, structure, array, or other object.</p>
8195
8196 <h5>Arguments:</h5>
8197 <p>The <tt>llvm.objectsize</tt> intrinsic takes two arguments. The first
8198    argument is a pointer to or into the <tt>object</tt>. The second argument
8199    is a boolean 0 or 1. This argument determines whether you want the
8200    maximum (0) or minimum (1) bytes remaining. This needs to be a literal 0 or
8201    1, variables are not allowed.</p>
8202
8203 <h5>Semantics:</h5>
8204 <p>The <tt>llvm.objectsize</tt> intrinsic is lowered to either a constant
8205    representing the size of the object concerned, or <tt>i32/i64 -1 or 0</tt>,
8206    depending on the <tt>type</tt> argument, if the size cannot be determined at
8207    compile time.</p>
8208
8209 </div>
8210 <!-- _______________________________________________________________________ -->
8211 <h4>
8212   <a name="int_expect">'<tt>llvm.expect</tt>' Intrinsic</a>
8213 </h4>
8214
8215 <div>
8216
8217 <h5>Syntax:</h5>
8218 <pre>
8219   declare i32 @llvm.expect.i32(i32 &lt;val&gt;, i32 &lt;expected_val&gt;)
8220   declare i64 @llvm.expect.i64(i64 &lt;val&gt;, i64 &lt;expected_val&gt;)
8221 </pre>
8222
8223 <h5>Overview:</h5>
8224 <p>The <tt>llvm.expect</tt> intrinsic provides information about expected (the
8225    most probable) value of <tt>val</tt>, which can be used by optimizers.</p>
8226
8227 <h5>Arguments:</h5>
8228 <p>The <tt>llvm.expect</tt> intrinsic takes two arguments. The first
8229    argument is a value. The second argument is an expected value, this needs to
8230    be a constant value, variables are not allowed.</p>
8231
8232 <h5>Semantics:</h5>
8233 <p>This intrinsic is lowered to the <tt>val</tt>.</p>
8234 </div>
8235
8236 </div>
8237
8238 </div>
8239 <!-- *********************************************************************** -->
8240 <hr>
8241 <address>
8242   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
8243   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
8244   <a href="http://validator.w3.org/check/referer"><img
8245   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
8246
8247   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
8248   <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
8249   Last modified: $Date$
8250 </address>
8251
8252 </body>
8253 </html>