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 <div class="doc_title"> LLVM Language Reference Manual </div>
  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_internal">'<tt>internal</tt>' Linkage</a></li>
  28           <li><a href="#linkage_available_externally">'<tt>available_externally</tt>' Linkage</a></li>
  29           <li><a href="#linkage_linkonce">'<tt>linkonce</tt>' Linkage</a></li>
  30           <li><a href="#linkage_common">'<tt>common</tt>' Linkage</a></li>
  31           <li><a href="#linkage_weak">'<tt>weak</tt>' Linkage</a></li>
  32           <li><a href="#linkage_appending">'<tt>appending</tt>' Linkage</a></li>
  33           <li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li>
  34           <li><a href="#linkage_linkonce_odr">'<tt>linkonce_odr</tt>' Linkage</a></li>
  35           <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li>
  36           <li><a href="#linkage_external">'<tt>externally visible</tt>' Linkage</a></li>
  37           <li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li>
  38           <li><a href="#linkage_dllexport">'<tt>dllexport</tt>' Linkage</a></li>
  39         </ol>
  40       </li>
  41       <li><a href="#callingconv">Calling Conventions</a></li>
  42       <li><a href="#namedtypes">Named Types</a></li>
  43       <li><a href="#globalvars">Global Variables</a></li>
  44       <li><a href="#functionstructure">Functions</a></li>
  45       <li><a href="#aliasstructure">Aliases</a></li>
  46       <li><a href="#namedmetadatastructure">Named Metadata</a></li>
  47       <li><a href="#paramattrs">Parameter Attributes</a></li>
  48       <li><a href="#fnattrs">Function Attributes</a></li>
  49       <li><a href="#gc">Garbage Collector Names</a></li>
  50       <li><a href="#moduleasm">Module-Level Inline Assembly</a></li>
  51       <li><a href="#datalayout">Data Layout</a></li>
  52       <li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li>
  53     </ol>
  54   </li>
  55   <li><a href="#typesystem">Type System</a>
  56     <ol>
  57       <li><a href="#t_classifications">Type Classifications</a></li>
  58       <li><a href="#t_primitive">Primitive Types</a>
  59         <ol>
  60           <li><a href="#t_integer">Integer Type</a></li>
  61           <li><a href="#t_floating">Floating Point Types</a></li>
  62           <li><a href="#t_void">Void Type</a></li>
  63           <li><a href="#t_label">Label Type</a></li>
  64           <li><a href="#t_metadata">Metadata Type</a></li>
  65         </ol>
  66       </li>
  67       <li><a href="#t_derived">Derived Types</a>
  68         <ol>
  69           <li><a href="#t_aggregate">Aggregate Types</a>
  70             <ol>
  71               <li><a href="#t_array">Array Type</a></li>
  72               <li><a href="#t_struct">Structure Type</a></li>
  73               <li><a href="#t_pstruct">Packed Structure Type</a></li>
  74               <li><a href="#t_union">Union Type</a></li>
  75               <li><a href="#t_vector">Vector Type</a></li>
  76             </ol>
  77           </li>
  78           <li><a href="#t_function">Function Type</a></li>
  79           <li><a href="#t_pointer">Pointer Type</a></li>
  80           <li><a href="#t_opaque">Opaque Type</a></li>
  81         </ol>
  82       </li>
  83       <li><a href="#t_uprefs">Type Up-references</a></li>
  84     </ol>
  85   </li>
  86   <li><a href="#constants">Constants</a>
  87     <ol>
  88       <li><a href="#simpleconstants">Simple Constants</a></li>
  89       <li><a href="#complexconstants">Complex Constants</a></li>
  90       <li><a href="#globalconstants">Global Variable and Function Addresses</a></li>
  91       <li><a href="#undefvalues">Undefined Values</a></li>
  92       <li><a href="#trapvalues">Trap Values</a></li>
  93       <li><a href="#blockaddress">Addresses of Basic Blocks</a></li>
  94       <li><a href="#constantexprs">Constant Expressions</a></li>
  95     </ol>
  96   </li>
  97   <li><a href="#othervalues">Other Values</a>
  98     <ol>
  99       <li><a href="#inlineasm">Inline Assembler Expressions</a></li>
 100       <li><a href="#metadata">Metadata Nodes and Metadata Strings</a></li>
 101     </ol>
 102   </li>
 103   <li><a href="#intrinsic_globals">Intrinsic Global Variables</a>
 104     <ol>
 105       <li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li>
 106       <li><a href="#intg_compiler_used">The '<tt>llvm.compiler.used</tt>'
 107           Global Variable</a></li>
 108       <li><a href="#intg_global_ctors">The '<tt>llvm.global_ctors</tt>'
 109          Global Variable</a></li>
 110       <li><a href="#intg_global_dtors">The '<tt>llvm.global_dtors</tt>'
 111          Global Variable</a></li>
 112     </ol>
 113   </li>
 114   <li><a href="#instref">Instruction Reference</a>
 115     <ol>
 116       <li><a href="#terminators">Terminator Instructions</a>
 117         <ol>
 118           <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li>
 119           <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
 120           <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
 121           <li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li>
 122           <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
 123           <li><a href="#i_unwind">'<tt>unwind</tt>'  Instruction</a></li>
 124           <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
 125         </ol>
 126       </li>
 127       <li><a href="#binaryops">Binary Operations</a>
 128         <ol>
 129           <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li>
 130           <li><a href="#i_fadd">'<tt>fadd</tt>' Instruction</a></li>
 131           <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li>
 132           <li><a href="#i_fsub">'<tt>fsub</tt>' Instruction</a></li>
 133           <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li>
 134           <li><a href="#i_fmul">'<tt>fmul</tt>' Instruction</a></li>
 135           <li><a href="#i_udiv">'<tt>udiv</tt>' Instruction</a></li>
 136           <li><a href="#i_sdiv">'<tt>sdiv</tt>' Instruction</a></li>
 137           <li><a href="#i_fdiv">'<tt>fdiv</tt>' Instruction</a></li>
 138           <li><a href="#i_urem">'<tt>urem</tt>' Instruction</a></li>
 139           <li><a href="#i_srem">'<tt>srem</tt>' Instruction</a></li>
 140           <li><a href="#i_frem">'<tt>frem</tt>' Instruction</a></li>
 141         </ol>
 142       </li>
 143       <li><a href="#bitwiseops">Bitwise Binary Operations</a>
 144         <ol>
 145           <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
 146           <li><a href="#i_lshr">'<tt>lshr</tt>' Instruction</a></li>
 147           <li><a href="#i_ashr">'<tt>ashr</tt>' Instruction</a></li>
 148           <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
 149           <li><a href="#i_or">'<tt>or</tt>'  Instruction</a></li>
 150           <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
 151         </ol>
 152       </li>
 153       <li><a href="#vectorops">Vector Operations</a>
 154         <ol>
 155           <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li>
 156           <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li>
 157           <li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li>
 158         </ol>
 159       </li>
 160       <li><a href="#aggregateops">Aggregate Operations</a>
 161         <ol>
 162           <li><a href="#i_extractvalue">'<tt>extractvalue</tt>' Instruction</a></li>
 163           <li><a href="#i_insertvalue">'<tt>insertvalue</tt>' Instruction</a></li>
 164         </ol>
 165       </li>
 166       <li><a href="#memoryops">Memory Access and Addressing Operations</a>
 167         <ol>
 168           <li><a href="#i_alloca">'<tt>alloca</tt>'   Instruction</a></li>
 169          <li><a href="#i_load">'<tt>load</tt>'     Instruction</a></li>
 170          <li><a href="#i_store">'<tt>store</tt>'    Instruction</a></li>
 171          <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
 172         </ol>
 173       </li>
 174       <li><a href="#convertops">Conversion Operations</a>
 175         <ol>
 176           <li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li>
 177           <li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li>
 178           <li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li>
 179           <li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li>
 180           <li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li>
 181           <li><a href="#i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a></li>
 182           <li><a href="#i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a></li>
 183           <li><a href="#i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a></li>
 184           <li><a href="#i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a></li>
 185           <li><a href="#i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a></li>
 186           <li><a href="#i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a></li>
 187           <li><a href="#i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a></li>
 188         </ol>
 189       </li>
 190       <li><a href="#otherops">Other Operations</a>
 191         <ol>
 192           <li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li>
 193           <li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li>
 194           <li><a href="#i_phi">'<tt>phi</tt>'   Instruction</a></li>
 195           <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
 196           <li><a href="#i_call">'<tt>call</tt>'  Instruction</a></li>
 197           <li><a href="#i_va_arg">'<tt>va_arg</tt>'  Instruction</a></li>
 198         </ol>
 199       </li>
 200     </ol>
 201   </li>
 202   <li><a href="#intrinsics">Intrinsic Functions</a>
 203     <ol>
 204       <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
 205         <ol>
 206           <li><a href="#int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
 207           <li><a href="#int_va_end">'<tt>llvm.va_end</tt>'   Intrinsic</a></li>
 208           <li><a href="#int_va_copy">'<tt>llvm.va_copy</tt>'  Intrinsic</a></li>
 209         </ol>
 210       </li>
 211       <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a>
 212         <ol>
 213           <li><a href="#int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
 214           <li><a href="#int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
 215           <li><a href="#int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
 216         </ol>
 217       </li>
 218       <li><a href="#int_codegen">Code Generator Intrinsics</a>
 219         <ol>
 220           <li><a href="#int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
 221           <li><a href="#int_frameaddress">'<tt>llvm.frameaddress</tt>'   Intrinsic</a></li>
 222           <li><a href="#int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a></li>
 223           <li><a href="#int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li>
 224           <li><a href="#int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
 225           <li><a href="#int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
 226           <li><a href="#int_readcyclecounter"><tt>llvm.readcyclecounter</tt>' Intrinsic</a></li>
 227         </ol>
 228       </li>
 229       <li><a href="#int_libc">Standard C Library Intrinsics</a>
 230         <ol>
 231           <li><a href="#int_memcpy">'<tt>llvm.memcpy.*</tt>' Intrinsic</a></li>
 232           <li><a href="#int_memmove">'<tt>llvm.memmove.*</tt>' Intrinsic</a></li>
 233           <li><a href="#int_memset">'<tt>llvm.memset.*</tt>' Intrinsic</a></li>
 234           <li><a href="#int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a></li>
 235           <li><a href="#int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a></li>
 236           <li><a href="#int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a></li>
 237           <li><a href="#int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a></li>
 238           <li><a href="#int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a></li>
 239         </ol>
 240       </li>
 241       <li><a href="#int_manip">Bit Manipulation Intrinsics</a>
 242         <ol>
 243           <li><a href="#int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a></li>
 244           <li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li>
 245           <li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li>
 246           <li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li>
 247         </ol>
 248       </li>
 249       <li><a href="#int_overflow">Arithmetic with Overflow Intrinsics</a>
 250         <ol>
 251           <li><a href="#int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt> Intrinsics</a></li>
 252           <li><a href="#int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt> Intrinsics</a></li>
 253           <li><a href="#int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt> Intrinsics</a></li>
 254           <li><a href="#int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt> Intrinsics</a></li>
 255           <li><a href="#int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt> Intrinsics</a></li>
 256           <li><a href="#int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt> Intrinsics</a></li>
 257         </ol>
 258       </li>
 259       <li><a href="#int_fp16">Half Precision Floating Point Intrinsics</a>
 260         <ol>
 261           <li><a href="#int_convert_to_fp16">'<tt>llvm.convert.to.fp16</tt>' Intrinsic</a></li>
 262           <li><a href="#int_convert_from_fp16">'<tt>llvm.convert.from.fp16</tt>' Intrinsic</a></li>
 263         </ol>
 264       </li>
 265       <li><a href="#int_debugger">Debugger intrinsics</a></li>
 266       <li><a href="#int_eh">Exception Handling intrinsics</a></li>
 267       <li><a href="#int_trampoline">Trampoline Intrinsic</a>
 268         <ol>
 269           <li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li>
 270         </ol>
 271       </li>
 272       <li><a href="#int_atomics">Atomic intrinsics</a>
 273         <ol>
 274           <li><a href="#int_memory_barrier"><tt>llvm.memory_barrier</tt></a></li>
 275           <li><a href="#int_atomic_cmp_swap"><tt>llvm.atomic.cmp.swap</tt></a></li>
 276           <li><a href="#int_atomic_swap"><tt>llvm.atomic.swap</tt></a></li>
 277           <li><a href="#int_atomic_load_add"><tt>llvm.atomic.load.add</tt></a></li>
 278           <li><a href="#int_atomic_load_sub"><tt>llvm.atomic.load.sub</tt></a></li>
 279           <li><a href="#int_atomic_load_and"><tt>llvm.atomic.load.and</tt></a></li>
 280           <li><a href="#int_atomic_load_nand"><tt>llvm.atomic.load.nand</tt></a></li>
 281           <li><a href="#int_atomic_load_or"><tt>llvm.atomic.load.or</tt></a></li>
 282           <li><a href="#int_atomic_load_xor"><tt>llvm.atomic.load.xor</tt></a></li>
 283           <li><a href="#int_atomic_load_max"><tt>llvm.atomic.load.max</tt></a></li>
 284           <li><a href="#int_atomic_load_min"><tt>llvm.atomic.load.min</tt></a></li>
 285           <li><a href="#int_atomic_load_umax"><tt>llvm.atomic.load.umax</tt></a></li>
 286           <li><a href="#int_atomic_load_umin"><tt>llvm.atomic.load.umin</tt></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         </ol>
 310       </li>
 311     </ol>
 312   </li>
 313 </ol>
 314
 315 <div class="doc_author">
 316   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
 317             and <a href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></p>
 318 </div>
 319
 320 <!-- *********************************************************************** -->
 321 <div class="doc_section"> <a name="abstract">Abstract </a></div>
 322 <!-- *********************************************************************** -->
 323
 324 <div class="doc_text">
 325
 326 <p>This document is a reference manual for the LLVM assembly language. LLVM is
 327    a Static Single Assignment (SSA) based representation that provides type
 328    safety, low-level operations, flexibility, and the capability of representing
 329    'all' high-level languages cleanly.  It is the common code representation
 330    used throughout all phases of the LLVM compilation strategy.</p>
 331
 332 </div>
 333
 334 <!-- *********************************************************************** -->
 335 <div class="doc_section"> <a name="introduction">Introduction</a> </div>
 336 <!-- *********************************************************************** -->
 337
 338 <div class="doc_text">
 339
 340 <p>The LLVM code representation is designed to be used in three different forms:
 341    as an in-memory compiler IR, as an on-disk bitcode representation (suitable
 342    for fast loading by a Just-In-Time compiler), and as a human readable
 343    assembly language representation.  This allows LLVM to provide a powerful
 344    intermediate representation for efficient compiler transformations and
 345    analysis, while providing a natural means to debug and visualize the
 346    transformations.  The three different forms of LLVM are all equivalent.  This
 347    document describes the human readable representation and notation.</p>
 348
 349 <p>The LLVM representation aims to be light-weight and low-level while being
 350    expressive, typed, and extensible at the same time.  It aims to be a
 351    "universal IR" of sorts, by being at a low enough level that high-level ideas
 352    may be cleanly mapped to it (similar to how microprocessors are "universal
 353    IR's", allowing many source languages to be mapped to them).  By providing
 354    type information, LLVM can be used as the target of optimizations: for
 355    example, through pointer analysis, it can be proven that a C automatic
 356    variable is never accessed outside of the current function, allowing it to
 357    be promoted to a simple SSA value instead of a memory location.</p>
 358
 359 </div>
 360
 361 <!-- _______________________________________________________________________ -->
 362 <div class="doc_subsubsection"> <a name="wellformed">Well-Formedness</a> </div>
 363
 364 <div class="doc_text">
 365
 366 <p>It is important to note that this document describes 'well formed' LLVM
 367    assembly language.  There is a difference between what the parser accepts and
 368    what is considered 'well formed'.  For example, the following instruction is
 369    syntactically okay, but not well formed:</p>
 370
 371 <div class="doc_code">
 372 <pre>
 373 %x = <a href="#i_add">add</a> i32 1, %x
 374 </pre>
 375 </div>
 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 <!-- Describe the typesetting conventions here. -->
 387
 388 <!-- *********************************************************************** -->
 389 <div class="doc_section"> <a name="identifiers">Identifiers</a> </div>
 390 <!-- *********************************************************************** -->
 391
 392 <div class="doc_text">
 393
 394 <p>LLVM identifiers come in two basic types: global and local. Global
 395    identifiers (functions, global variables) begin with the <tt>'@'</tt>
 396    character. Local identifiers (register names, types) begin with
 397    the <tt>'%'</tt> character. Additionally, there are three different formats
 398    for identifiers, for different purposes:</p>
 399
 400 <ol>
 401   <li>Named values are represented as a string of characters with their prefix.
 402       For example, <tt>%foo</tt>, <tt>@DivisionByZero</tt>,
 403       <tt>%a.really.long.identifier</tt>. The actual regular expression used is
 404       '<tt>[%@][a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.  Identifiers which require
 405       other characters in their names can be surrounded with quotes. Special
 406       characters may be escaped using <tt>"\xx"</tt> where <tt>xx</tt> is the
 407       ASCII code for the character in hexadecimal.  In this way, any character
 408       can be used in a name value, even quotes themselves.</li>
 409
 410   <li>Unnamed values are represented as an unsigned numeric value with their
 411       prefix.  For example, <tt>%12</tt>, <tt>@2</tt>, <tt>%44</tt>.</li>
 412
 413   <li>Constants, which are described in a <a href="#constants">section about
 414       constants</a>, below.</li>
 415 </ol>
 416
 417 <p>LLVM requires that values start with a prefix for two reasons: Compilers
 418    don't need to worry about name clashes with reserved words, and the set of
 419    reserved words may be expanded in the future without penalty.  Additionally,
 420    unnamed identifiers allow a compiler to quickly come up with a temporary
 421    variable without having to avoid symbol table conflicts.</p>
 422
 423 <p>Reserved words in LLVM are very similar to reserved words in other
 424    languages. There are keywords for different opcodes
 425    ('<tt><a href="#i_add">add</a></tt>',
 426    '<tt><a href="#i_bitcast">bitcast</a></tt>',
 427    '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names
 428    ('<tt><a href="#t_void">void</a></tt>',
 429    '<tt><a href="#t_primitive">i32</a></tt>', etc...), and others.  These
 430    reserved words cannot conflict with variable names, because none of them
 431    start with a prefix character (<tt>'%'</tt> or <tt>'@'</tt>).</p>
 432
 433 <p>Here is an example of LLVM code to multiply the integer variable
 434    '<tt>%X</tt>' by 8:</p>
 435
 436 <p>The easy way:</p>
 437
 438 <div class="doc_code">
 439 <pre>
 440 %result = <a href="#i_mul">mul</a> i32 %X, 8
 441 </pre>
 442 </div>
 443
 444 <p>After strength reduction:</p>
 445
 446 <div class="doc_code">
 447 <pre>
 448 %result = <a href="#i_shl">shl</a> i32 %X, i8 3
 449 </pre>
 450 </div>
 451
 452 <p>And the hard way:</p>
 453
 454 <div class="doc_code">
 455 <pre>
 456 %0 = <a href="#i_add">add</a> i32 %X, %X           <i>; yields {i32}:%0</i>
 457 %1 = <a href="#i_add">add</a> i32 %0, %0           <i>; yields {i32}:%1</i>
 458 %result = <a href="#i_add">add</a> i32 %1, %1
 459 </pre>
 460 </div>
 461
 462 <p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important
 463    lexical features of LLVM:</p>
 464
 465 <ol>
 466   <li>Comments are delimited with a '<tt>;</tt>' and go until the end of
 467       line.</li>
 468
 469   <li>Unnamed temporaries are created when the result of a computation is not
 470       assigned to a named value.</li>
 471
 472   <li>Unnamed temporaries are numbered sequentially</li>
 473 </ol>
 474
 475 <p>It also shows a convention that we follow in this document.  When
 476    demonstrating instructions, we will follow an instruction with a comment that
 477    defines the type and name of value produced.  Comments are shown in italic
 478    text.</p>
 479
 480 </div>
 481
 482 <!-- *********************************************************************** -->
 483 <div class="doc_section"> <a name="highlevel">High Level Structure</a> </div>
 484 <!-- *********************************************************************** -->
 485
 486 <!-- ======================================================================= -->
 487 <div class="doc_subsection"> <a name="modulestructure">Module Structure</a>
 488 </div>
 489
 490 <div class="doc_text">
 491
 492 <p>LLVM programs are composed of "Module"s, each of which is a translation unit
 493    of the input programs.  Each module consists of functions, global variables,
 494    and symbol table entries.  Modules may be combined together with the LLVM
 495    linker, which merges function (and global variable) definitions, resolves
 496    forward declarations, and merges symbol table entries. Here is an example of
 497    the "hello world" module:</p>
 498
 499 <div class="doc_code">
 500 <pre>
 501 <i>; Declare the string constant as a global constant.</i>
 502 <a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00"    <i>; [13 x i8]*</i>
 503
 504 <i>; External declaration of the puts function</i>
 505 <a href="#functionstructure">declare</a> i32 @puts(i8 *)                                     <i>; i32(i8 *)* </i>
 506
 507 <i>; Definition of main function</i>
 508 define i32 @main() {                                        <i>; i32()* </i>
 509   <i>; Convert [13 x i8]* to i8  *...</i>
 510   %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0   <i>; i8 *</i>
 511
 512   <i>; Call puts function to write out the string to stdout.</i>
 513   <a href="#i_call">call</a> i32 @puts(i8 * %cast210)                             <i>; i32</i>
 514   <a href="#i_ret">ret</a> i32 0<br>}
 515
 516 <i>; Named metadata</i>
 517 !1 = metadata !{i32 41}
 518 !foo = !{!1, null}
 519 </pre>
 520 </div>
 521
 522 <p>This example is made up of a <a href="#globalvars">global variable</a> named
 523    "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function,
 524    a <a href="#functionstructure">function definition</a> for
 525    "<tt>main</tt>" and <a href="#namedmetadatastructure">named metadata</a>
 526    "<tt>foo"</tt>.</p>
 527
 528 <p>In general, a module is made up of a list of global values, where both
 529    functions and global variables are global values.  Global values are
 530    represented by a pointer to a memory location (in this case, a pointer to an
 531    array of char, and a pointer to a function), and have one of the
 532    following <a href="#linkage">linkage types</a>.</p>
 533
 534 </div>
 535
 536 <!-- ======================================================================= -->
 537 <div class="doc_subsection">
 538   <a name="linkage">Linkage Types</a>
 539 </div>
 540
 541 <div class="doc_text">
 542
 543 <p>All Global Variables and Functions have one of the following types of
 544    linkage:</p>
 545
 546 <dl>
 547   <dt><tt><b><a name="linkage_private">private</a></b></tt></dt>
 548   <dd>Global values with private linkage are only directly accessible by objects
 549       in the current module.  In particular, linking code into a module with an
 550       private global value may cause the private to be renamed as necessary to
 551       avoid collisions.  Because the symbol is private to the module, all
 552       references can be updated. This doesn't show up in any symbol table in the
 553       object file.</dd>
 554
 555   <dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt></dt>
 556   <dd>Similar to private, but the symbol is passed through the assembler and
 557       removed by the linker after evaluation.  Note that (unlike private
 558       symbols) linker_private symbols are subject to coalescing by the linker:
 559       weak symbols get merged and redefinitions are rejected.  However, unlike
 560       normal strong symbols, they are removed by the linker from the final
 561       linked image (executable or dynamic library).</dd>
 562
 563   <dt><tt><b><a name="linkage_internal">internal</a></b></tt></dt>
 564   <dd>Similar to private, but the value shows as a local symbol
 565       (<tt>STB_LOCAL</tt> in the case of ELF) in the object file. This
 566       corresponds to the notion of the '<tt>static</tt>' keyword in C.</dd>
 567
 568   <dt><tt><b><a name="linkage_available_externally">available_externally</a></b></tt></dt>
 569   <dd>Globals with "<tt>available_externally</tt>" linkage are never emitted
 570       into the object file corresponding to the LLVM module.  They exist to
 571       allow inlining and other optimizations to take place given knowledge of
 572       the definition of the global, which is known to be somewhere outside the
 573       module.  Globals with <tt>available_externally</tt> linkage are allowed to
 574       be discarded at will, and are otherwise the same as <tt>linkonce_odr</tt>.
 575       This linkage type is only allowed on definitions, not declarations.</dd>
 576
 577   <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt></dt>
 578   <dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of
 579       the same name when linkage occurs.  This can be used to implement
 580       some forms of inline functions, templates, or other code which must be
 581       generated in each translation unit that uses it, but where the body may
 582       be overridden with a more definitive definition later.  Unreferenced
 583       <tt>linkonce</tt> globals are allowed to be discarded.  Note that
 584       <tt>linkonce</tt> linkage does not actually allow the optimizer to
 585       inline the body of this function into callers because it doesn't know if
 586       this definition of the function is the definitive definition within the
 587       program or whether it will be overridden by a stronger definition.
 588       To enable inlining and other optimizations, use "<tt>linkonce_odr</tt>"
 589       linkage.</dd>
 590
 591   <dt><tt><b><a name="linkage_weak">weak</a></b></tt></dt>
 592   <dd>"<tt>weak</tt>" linkage has the same merging semantics as
 593       <tt>linkonce</tt> linkage, except that unreferenced globals with
 594       <tt>weak</tt> linkage may not be discarded.  This is used for globals that
 595       are declared "weak" in C source code.</dd>
 596
 597   <dt><tt><b><a name="linkage_common">common</a></b></tt></dt>
 598   <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but
 599       they are used for tentative definitions in C, such as "<tt>int X;</tt>" at
 600       global scope.
 601       Symbols with "<tt>common</tt>" linkage are merged in the same way as
 602       <tt>weak symbols</tt>, and they may not be deleted if unreferenced.
 603       <tt>common</tt> symbols may not have an explicit section,
 604       must have a zero initializer, and may not be marked '<a
 605       href="#globalvars"><tt>constant</tt></a>'.  Functions and aliases may not
 606       have common linkage.</dd>
 607
 608
 609   <dt><tt><b><a name="linkage_appending">appending</a></b></tt></dt>
 610   <dd>"<tt>appending</tt>" linkage may only be applied to global variables of
 611       pointer to array type.  When two global variables with appending linkage
 612       are linked together, the two global arrays are appended together.  This is
 613       the LLVM, typesafe, equivalent of having the system linker append together
 614       "sections" with identical names when .o files are linked.</dd>
 615
 616   <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt></dt>
 617   <dd>The semantics of this linkage follow the ELF object file model: the symbol
 618       is weak until linked, if not linked, the symbol becomes null instead of
 619       being an undefined reference.</dd>
 620
 621   <dt><tt><b><a name="linkage_linkonce_odr">linkonce_odr</a></b></tt></dt>
 622   <dt><tt><b><a name="linkage_weak_odr">weak_odr</a></b></tt></dt>
 623   <dd>Some languages allow differing globals to be merged, such as two functions
 624       with different semantics.  Other languages, such as <tt>C++</tt>, ensure
 625       that only equivalent globals are ever merged (the "one definition rule" -
 626       "ODR").  Such languages can use the <tt>linkonce_odr</tt>
 627       and <tt>weak_odr</tt> linkage types to indicate that the global will only
 628       be merged with equivalent globals.  These linkage types are otherwise the
 629       same as their non-<tt>odr</tt> versions.</dd>
 630
 631   <dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt>
 632   <dd>If none of the above identifiers are used, the global is externally
 633       visible, meaning that it participates in linkage and can be used to
 634       resolve external symbol references.</dd>
 635 </dl>
 636
 637 <p>The next two types of linkage are targeted for Microsoft Windows platform
 638    only. They are designed to support importing (exporting) symbols from (to)
 639    DLLs (Dynamic Link Libraries).</p>
 640
 641 <dl>
 642   <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt></dt>
 643   <dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function
 644       or variable via a global pointer to a pointer that is set up by the DLL
 645       exporting the symbol. On Microsoft Windows targets, the pointer name is
 646       formed by combining <code>__imp_</code> and the function or variable
 647       name.</dd>
 648
 649   <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt></dt>
 650   <dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global
 651       pointer to a pointer in a DLL, so that it can be referenced with the
 652       <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer
 653       name is formed by combining <code>__imp_</code> and the function or
 654       variable name.</dd>
 655 </dl>
 656
 657 <p>For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
 658    another module defined a "<tt>.LC0</tt>" variable and was linked with this
 659    one, one of the two would be renamed, preventing a collision.  Since
 660    "<tt>main</tt>" and "<tt>puts</tt>" are external (i.e., lacking any linkage
 661    declarations), they are accessible outside of the current module.</p>
 662
 663 <p>It is illegal for a function <i>declaration</i> to have any linkage type
 664    other than "externally visible", <tt>dllimport</tt>
 665    or <tt>extern_weak</tt>.</p>
 666
 667 <p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt>
 668    or <tt>weak_odr</tt> linkages.</p>
 669
 670 </div>
 671
 672 <!-- ======================================================================= -->
 673 <div class="doc_subsection">
 674   <a name="callingconv">Calling Conventions</a>
 675 </div>
 676
 677 <div class="doc_text">
 678
 679 <p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a>
 680    and <a href="#i_invoke">invokes</a> can all have an optional calling
 681    convention specified for the call.  The calling convention of any pair of
 682    dynamic caller/callee must match, or the behavior of the program is
 683    undefined.  The following calling conventions are supported by LLVM, and more
 684    may be added in the future:</p>
 685
 686 <dl>
 687   <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt>
 688   <dd>This calling convention (the default if no other calling convention is
 689       specified) matches the target C calling conventions.  This calling
 690       convention supports varargs function calls and tolerates some mismatch in
 691       the declared prototype and implemented declaration of the function (as
 692       does normal C).</dd>
 693
 694   <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt>
 695   <dd>This calling convention attempts to make calls as fast as possible
 696       (e.g. by passing things in registers).  This calling convention allows the
 697       target to use whatever tricks it wants to produce fast code for the
 698       target, without having to conform to an externally specified ABI
 699       (Application Binary Interface).
 700       <a href="CodeGenerator.html#tailcallopt">Tail calls can only be optimized
 701       when this or the GHC convention is used.</a>  This calling convention
 702       does not support varargs and requires the prototype of all callees to
 703       exactly match the prototype of the function definition.</dd>
 704
 705   <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt>
 706   <dd>This calling convention attempts to make code in the caller as efficient
 707       as possible under the assumption that the call is not commonly executed.
 708       As such, these calls often preserve all registers so that the call does
 709       not break any live ranges in the caller side.  This calling convention
 710       does not support varargs and requires the prototype of all callees to
 711       exactly match the prototype of the function definition.</dd>
 712
 713   <dt><b>"<tt>cc <em>10</em></tt>" - GHC convention</b>:</dt>
 714   <dd>This calling convention has been implemented specifically for use by the
 715       <a href="http://www.haskell.org/ghc">Glasgow Haskell Compiler (GHC)</a>.
 716       It passes everything in registers, going to extremes to achieve this by
 717       disabling callee save registers. This calling convention should not be
 718       used lightly but only for specific situations such as an alternative to
 719       the <em>register pinning</em> performance technique often used when
 720       implementing functional programming languages.At the moment only X86
 721       supports this convention and it has the following limitations:
 722       <ul>
 723         <li>On <em>X86-32</em> only supports up to 4 bit type parameters. No
 724             floating point types are supported.</li>
 725         <li>On <em>X86-64</em> only supports up to 10 bit type parameters and
 726             6 floating point parameters.</li>
 727       </ul>
 728       This calling convention supports
 729       <a href="CodeGenerator.html#tailcallopt">tail call optimization</a> but
 730       requires both the caller and callee are using it.
 731   </dd>
 732
 733   <dt><b>"<tt>cc &lt;<em>n</em>&gt;</tt>" - Numbered convention</b>:</dt>
 734   <dd>Any calling convention may be specified by number, allowing
 735       target-specific calling conventions to be used.  Target specific calling
 736       conventions start at 64.</dd>
 737 </dl>
 738
 739 <p>More calling conventions can be added/defined on an as-needed basis, to
 740    support Pascal conventions or any other well-known target-independent
 741    convention.</p>
 742
 743 </div>
 744
 745 <!-- ======================================================================= -->
 746 <div class="doc_subsection">
 747   <a name="visibility">Visibility Styles</a>
 748 </div>
 749
 750 <div class="doc_text">
 751
 752 <p>All Global Variables and Functions have one of the following visibility
 753    styles:</p>
 754
 755 <dl>
 756   <dt><b>"<tt>default</tt>" - Default style</b>:</dt>
 757   <dd>On targets that use the ELF object file format, default visibility means
 758       that the declaration is visible to other modules and, in shared libraries,
 759       means that the declared entity may be overridden. On Darwin, default
 760       visibility means that the declaration is visible to other modules. Default
 761       visibility corresponds to "external linkage" in the language.</dd>
 762
 763   <dt><b>"<tt>hidden</tt>" - Hidden style</b>:</dt>
 764   <dd>Two declarations of an object with hidden visibility refer to the same
 765       object if they are in the same shared object. Usually, hidden visibility
 766       indicates that the symbol will not be placed into the dynamic symbol
 767       table, so no other module (executable or shared library) can reference it
 768       directly.</dd>
 769
 770   <dt><b>"<tt>protected</tt>" - Protected style</b>:</dt>
 771   <dd>On ELF, protected visibility indicates that the symbol will be placed in
 772       the dynamic symbol table, but that references within the defining module
 773       will bind to the local symbol. That is, the symbol cannot be overridden by
 774       another module.</dd>
 775 </dl>
 776
 777 </div>
 778
 779 <!-- ======================================================================= -->
 780 <div class="doc_subsection">
 781   <a name="namedtypes">Named Types</a>
 782 </div>
 783
 784 <div class="doc_text">
 785
 786 <p>LLVM IR allows you to specify name aliases for certain types.  This can make
 787    it easier to read the IR and make the IR more condensed (particularly when
 788    recursive types are involved).  An example of a name specification is:</p>
 789
 790 <div class="doc_code">
 791 <pre>
 792 %mytype = type { %mytype*, i32 }
 793 </pre>
 794 </div>
 795
 796 <p>You may give a name to any <a href="#typesystem">type</a> except
 797    "<a href="t_void">void</a>".  Type name aliases may be used anywhere a type
 798    is expected with the syntax "%mytype".</p>
 799
 800 <p>Note that type names are aliases for the structural type that they indicate,
 801    and that you can therefore specify multiple names for the same type.  This
 802    often leads to confusing behavior when dumping out a .ll file.  Since LLVM IR
 803    uses structural typing, the name is not part of the type.  When printing out
 804    LLVM IR, the printer will pick <em>one name</em> to render all types of a
 805    particular shape.  This means that if you have code where two different
 806    source types end up having the same LLVM type, that the dumper will sometimes
 807    print the "wrong" or unexpected type.  This is an important design point and
 808    isn't going to change.</p>
 809
 810 </div>
 811
 812 <!-- ======================================================================= -->
 813 <div class="doc_subsection">
 814   <a name="globalvars">Global Variables</a>
 815 </div>
 816
 817 <div class="doc_text">
 818
 819 <p>Global variables define regions of memory allocated at compilation time
 820    instead of run-time.  Global variables may optionally be initialized, may
 821    have an explicit section to be placed in, and may have an optional explicit
 822    alignment specified.  A variable may be defined as "thread_local", which
 823    means that it will not be shared by threads (each thread will have a
 824    separated copy of the variable).  A variable may be defined as a global
 825    "constant," which indicates that the contents of the variable
 826    will <b>never</b> be modified (enabling better optimization, allowing the
 827    global data to be placed in the read-only section of an executable, etc).
 828    Note that variables that need runtime initialization cannot be marked
 829    "constant" as there is a store to the variable.</p>
 830
 831 <p>LLVM explicitly allows <em>declarations</em> of global variables to be marked
 832    constant, even if the final definition of the global is not.  This capability
 833    can be used to enable slightly better optimization of the program, but
 834    requires the language definition to guarantee that optimizations based on the
 835    'constantness' are valid for the translation units that do not include the
 836    definition.</p>
 837
 838 <p>As SSA values, global variables define pointer values that are in scope
 839    (i.e. they dominate) all basic blocks in the program.  Global variables
 840    always define a pointer to their "content" type because they describe a
 841    region of memory, and all memory objects in LLVM are accessed through
 842    pointers.</p>
 843
 844 <p>A global variable may be declared to reside in a target-specific numbered
 845    address space. For targets that support them, address spaces may affect how
 846    optimizations are performed and/or what target instructions are used to
 847    access the variable. The default address space is zero. The address space
 848    qualifier must precede any other attributes.</p>
 849
 850 <p>LLVM allows an explicit section to be specified for globals.  If the target
 851    supports it, it will emit globals to the section specified.</p>
 852
 853 <p>An explicit alignment may be specified for a global.  If not present, or if
 854    the alignment is set to zero, the alignment of the global is set by the
 855    target to whatever it feels convenient.  If an explicit alignment is
 856    specified, the global is forced to have at least that much alignment.  All
 857    alignments must be a power of 2.</p>
 858
 859 <p>For example, the following defines a global in a numbered address space with
 860    an initializer, section, and alignment:</p>
 861
 862 <div class="doc_code">
 863 <pre>
 864 @G = addrspace(5) constant float 1.0, section "foo", align 4
 865 </pre>
 866 </div>
 867
 868 </div>
 869
 870
 871 <!-- ======================================================================= -->
 872 <div class="doc_subsection">
 873   <a name="functionstructure">Functions</a>
 874 </div>
 875
 876 <div class="doc_text">
 877
 878 <p>LLVM function definitions consist of the "<tt>define</tt>" keyword, an
 879    optional <a href="#linkage">linkage type</a>, an optional
 880    <a href="#visibility">visibility style</a>, an optional
 881    <a href="#callingconv">calling convention</a>, a return type, an optional
 882    <a href="#paramattrs">parameter attribute</a> for the return type, a function
 883    name, a (possibly empty) argument list (each with optional
 884    <a href="#paramattrs">parameter attributes</a>), optional
 885    <a href="#fnattrs">function attributes</a>, an optional section, an optional
 886    alignment, an optional <a href="#gc">garbage collector name</a>, an opening
 887    curly brace, a list of basic blocks, and a closing curly brace.</p>
 888
 889 <p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an
 890    optional <a href="#linkage">linkage type</a>, an optional
 891    <a href="#visibility">visibility style</a>, an optional
 892    <a href="#callingconv">calling convention</a>, a return type, an optional
 893    <a href="#paramattrs">parameter attribute</a> for the return type, a function
 894    name, a possibly empty list of arguments, an optional alignment, and an
 895    optional <a href="#gc">garbage collector name</a>.</p>
 896
 897 <p>A function definition contains a list of basic blocks, forming the CFG
 898    (Control Flow Graph) for the function.  Each basic block may optionally start
 899    with a label (giving the basic block a symbol table entry), contains a list
 900    of instructions, and ends with a <a href="#terminators">terminator</a>
 901    instruction (such as a branch or function return).</p>
 902
 903 <p>The first basic block in a function is special in two ways: it is immediately
 904    executed on entrance to the function, and it is not allowed to have
 905    predecessor basic blocks (i.e. there can not be any branches to the entry
 906    block of a function).  Because the block can have no predecessors, it also
 907    cannot have any <a href="#i_phi">PHI nodes</a>.</p>
 908
 909 <p>LLVM allows an explicit section to be specified for functions.  If the target
 910    supports it, it will emit functions to the section specified.</p>
 911
 912 <p>An explicit alignment may be specified for a function.  If not present, or if
 913    the alignment is set to zero, the alignment of the function is set by the
 914    target to whatever it feels convenient.  If an explicit alignment is
 915    specified, the function is forced to have at least that much alignment.  All
 916    alignments must be a power of 2.</p>
 917
 918 <h5>Syntax:</h5>
 919 <div class="doc_code">
 920 <pre>
 921 define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>]
 922        [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>]
 923        &lt;ResultType&gt; @&lt;FunctionName&gt; ([argument list])
 924        [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N]
 925        [<a href="#gc">gc</a>] { ... }
 926 </pre>
 927 </div>
 928
 929 </div>
 930
 931 <!-- ======================================================================= -->
 932 <div class="doc_subsection">
 933   <a name="aliasstructure">Aliases</a>
 934 </div>
 935
 936 <div class="doc_text">
 937
 938 <p>Aliases act as "second name" for the aliasee value (which can be either
 939    function, global variable, another alias or bitcast of global value). Aliases
 940    may have an optional <a href="#linkage">linkage type</a>, and an
 941    optional <a href="#visibility">visibility style</a>.</p>
 942
 943 <h5>Syntax:</h5>
 944 <div class="doc_code">
 945 <pre>
 946 @&lt;Name&gt; = alias [Linkage] [Visibility] &lt;AliaseeTy&gt; @&lt;Aliasee&gt;
 947 </pre>
 948 </div>
 949
 950 </div>
 951
 952 <!-- ======================================================================= -->
 953 <div class="doc_subsection">
 954   <a name="namedmetadatastructure">Named Metadata</a>
 955 </div>
 956
 957 <div class="doc_text">
 958
 959 <p>Named metadata is a collection of metadata. <a href="#metadata">Metadata
 960    nodes</a> (but not metadata strings) and null are the only valid operands for
 961    a named metadata.</p>
 962
 963 <h5>Syntax:</h5>
 964 <div class="doc_code">
 965 <pre>
 966 !1 = metadata !{metadata !"one"}
 967 !name = !{null, !1}
 968 </pre>
 969 </div>
 970
 971 </div>
 972
 973 <!-- ======================================================================= -->
 974 <div class="doc_subsection"><a name="paramattrs">Parameter Attributes</a></div>
 975
 976 <div class="doc_text">
 977
 978 <p>The return type and each parameter of a function type may have a set of
 979    <i>parameter attributes</i> associated with them. Parameter attributes are
 980    used to communicate additional information about the result or parameters of
 981    a function. Parameter attributes are considered to be part of the function,
 982    not of the function type, so functions with different parameter attributes
 983    can have the same function type.</p>
 984
 985 <p>Parameter attributes are simple keywords that follow the type specified. If
 986    multiple parameter attributes are needed, they are space separated. For
 987    example:</p>
 988
 989 <div class="doc_code">
 990 <pre>
 991 declare i32 @printf(i8* noalias nocapture, ...)
 992 declare i32 @atoi(i8 zeroext)
 993 declare signext i8 @returns_signed_char()
 994 </pre>
 995 </div>
 996
 997 <p>Note that any attributes for the function result (<tt>nounwind</tt>,
 998    <tt>readonly</tt>) come immediately after the argument list.</p>
 999
1000 <p>Currently, only the following parameter attributes are defined:</p>
1001
1002 <dl>
1003   <dt><tt><b>zeroext</b></tt></dt>
1004   <dd>This indicates to the code generator that the parameter or return value
1005       should be zero-extended to a 32-bit value by the caller (for a parameter)
1006       or the callee (for a return value).</dd>
1007
1008   <dt><tt><b>signext</b></tt></dt>
1009   <dd>This indicates to the code generator that the parameter or return value
1010       should be sign-extended to a 32-bit value by the caller (for a parameter)
1011       or the callee (for a return value).</dd>
1012
1013   <dt><tt><b>inreg</b></tt></dt>
1014   <dd>This indicates that this parameter or return value should be treated in a
1015       special target-dependent fashion during while emitting code for a function
1016       call or return (usually, by putting it in a register as opposed to memory,
1017       though some targets use it to distinguish between two different kinds of
1018       registers).  Use of this attribute is target-specific.</dd>
1019
1020   <dt><tt><b><a name="byval">byval</a></b></tt></dt>
1021   <dd>This indicates that the pointer parameter should really be passed by value
1022       to the function.  The attribute implies that a hidden copy of the pointee
1023       is made between the caller and the callee, so the callee is unable to
1024       modify the value in the callee.  This attribute is only valid on LLVM
1025       pointer arguments.  It is generally used to pass structs and arrays by
1026       value, but is also valid on pointers to scalars.  The copy is considered
1027       to belong to the caller not the callee (for example,
1028       <tt><a href="#readonly">readonly</a></tt> functions should not write to
1029       <tt>byval</tt> parameters). This is not a valid attribute for return
1030       values.  The byval attribute also supports specifying an alignment with
1031       the align attribute.  This has a target-specific effect on the code
1032       generator that usually indicates a desired alignment for the synthesized
1033       stack slot.</dd>
1034
1035   <dt><tt><b>sret</b></tt></dt>
1036   <dd>This indicates that the pointer parameter specifies the address of a
1037       structure that is the return value of the function in the source program.
1038       This pointer must be guaranteed by the caller to be valid: loads and
1039       stores to the structure may be assumed by the callee to not to trap.  This
1040       may only be applied to the first parameter. This is not a valid attribute
1041       for return values. </dd>
1042
1043   <dt><tt><b>noalias</b></tt></dt>
1044   <dd>This indicates that the pointer does not alias any global or any other
1045       parameter.  The caller is responsible for ensuring that this is the
1046       case. On a function return value, <tt>noalias</tt> additionally indicates
1047       that the pointer does not alias any other pointers visible to the
1048       caller. For further details, please see the discussion of the NoAlias
1049       response in
1050       <a href="http://llvm.org/docs/AliasAnalysis.html#MustMayNo">alias
1051       analysis</a>.</dd>
1052
1053   <dt><tt><b>nocapture</b></tt></dt>
1054   <dd>This indicates that the callee does not make any copies of the pointer
1055       that outlive the callee itself. This is not a valid attribute for return
1056       values.</dd>
1057
1058   <dt><tt><b>nest</b></tt></dt>
1059   <dd>This indicates that the pointer parameter can be excised using the
1060       <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid
1061       attribute for return values.</dd>
1062 </dl>
1063
1064 </div>
1065
1066 <!-- ======================================================================= -->
1067 <div class="doc_subsection">
1068   <a name="gc">Garbage Collector Names</a>
1069 </div>
1070
1071 <div class="doc_text">
1072
1073 <p>Each function may specify a garbage collector name, which is simply a
1074    string:</p>
1075
1076 <div class="doc_code">
1077 <pre>
1078 define void @f() gc "name" { ... }
1079 </pre>
1080 </div>
1081
1082 <p>The compiler declares the supported values of <i>name</i>. Specifying a
1083    collector which will cause the compiler to alter its output in order to
1084    support the named garbage collection algorithm.</p>
1085
1086 </div>
1087
1088 <!-- ======================================================================= -->
1089 <div class="doc_subsection">
1090   <a name="fnattrs">Function Attributes</a>
1091 </div>
1092
1093 <div class="doc_text">
1094
1095 <p>Function attributes are set to communicate additional information about a
1096    function. Function attributes are considered to be part of the function, not
1097    of the function type, so functions with different parameter attributes can
1098    have the same function type.</p>
1099
1100 <p>Function attributes are simple keywords that follow the type specified. If
1101    multiple attributes are needed, they are space separated. For example:</p>
1102
1103 <div class="doc_code">
1104 <pre>
1105 define void @f() noinline { ... }
1106 define void @f() alwaysinline { ... }
1107 define void @f() alwaysinline optsize { ... }
1108 define void @f() optsize { ... }
1109 </pre>
1110 </div>
1111
1112 <dl>
1113   <dt><tt><b>alignstack(&lt;<em>n</em>&gt;)</b></tt></dt>
1114   <dd>This attribute indicates that, when emitting the prologue and epilogue,
1115       the backend should forcibly align the stack pointer. Specify the
1116       desired alignment, which must be a power of two, in parentheses.
1117
1118   <dt><tt><b>alwaysinline</b></tt></dt>
1119   <dd>This attribute indicates that the inliner should attempt to inline this
1120       function into callers whenever possible, ignoring any active inlining size
1121       threshold for this caller.</dd>
1122
1123   <dt><tt><b>inlinehint</b></tt></dt>
1124   <dd>This attribute indicates that the source code contained a hint that inlining
1125       this function is desirable (such as the "inline" keyword in C/C++).  It
1126       is just a hint; it imposes no requirements on the inliner.</dd>
1127
1128   <dt><tt><b>noinline</b></tt></dt>
1129   <dd>This attribute indicates that the inliner should never inline this
1130       function in any situation. This attribute may not be used together with
1131       the <tt>alwaysinline</tt> attribute.</dd>
1132
1133   <dt><tt><b>optsize</b></tt></dt>
1134   <dd>This attribute suggests that optimization passes and code generator passes
1135       make choices that keep the code size of this function low, and otherwise
1136       do optimizations specifically to reduce code size.</dd>
1137
1138   <dt><tt><b>noreturn</b></tt></dt>
1139   <dd>This function attribute indicates that the function never returns
1140       normally.  This produces undefined behavior at runtime if the function
1141       ever does dynamically return.</dd>
1142
1143   <dt><tt><b>nounwind</b></tt></dt>
1144   <dd>This function attribute indicates that the function never returns with an
1145       unwind or exceptional control flow.  If the function does unwind, its
1146       runtime behavior is undefined.</dd>
1147
1148   <dt><tt><b>readnone</b></tt></dt>
1149   <dd>This attribute indicates that the function computes its result (or decides
1150       to unwind an exception) based strictly on its arguments, without
1151       dereferencing any pointer arguments or otherwise accessing any mutable
1152       state (e.g. memory, control registers, etc) visible to caller functions.
1153       It does not write through any pointer arguments
1154       (including <tt><a href="#byval">byval</a></tt> arguments) and never
1155       changes any state visible to callers.  This means that it cannot unwind
1156       exceptions by calling the <tt>C++</tt> exception throwing methods, but
1157       could use the <tt>unwind</tt> instruction.</dd>
1158
1159   <dt><tt><b><a name="readonly">readonly</a></b></tt></dt>
1160   <dd>This attribute indicates that the function does not write through any
1161       pointer arguments (including <tt><a href="#byval">byval</a></tt>
1162       arguments) or otherwise modify any state (e.g. memory, control registers,
1163       etc) visible to caller functions.  It may dereference pointer arguments
1164       and read state that may be set in the caller.  A readonly function always
1165       returns the same value (or unwinds an exception identically) when called
1166       with the same set of arguments and global state.  It cannot unwind an
1167       exception by calling the <tt>C++</tt> exception throwing methods, but may
1168       use the <tt>unwind</tt> instruction.</dd>
1169
1170   <dt><tt><b><a name="ssp">ssp</a></b></tt></dt>
1171   <dd>This attribute indicates that the function should emit a stack smashing
1172       protector. It is in the form of a "canary"&mdash;a random value placed on
1173       the stack before the local variables that's checked upon return from the
1174       function to see if it has been overwritten. A heuristic is used to
1175       determine if a function needs stack protectors or not.<br>
1176 <br>
1177       If a function that has an <tt>ssp</tt> attribute is inlined into a
1178       function that doesn't have an <tt>ssp</tt> attribute, then the resulting
1179       function will have an <tt>ssp</tt> attribute.</dd>
1180
1181   <dt><tt><b>sspreq</b></tt></dt>
1182   <dd>This attribute indicates that the function should <em>always</em> emit a
1183       stack smashing protector. This overrides
1184       the <tt><a href="#ssp">ssp</a></tt> function attribute.<br>
1185 <br>
1186       If a function that has an <tt>sspreq</tt> attribute is inlined into a
1187       function that doesn't have an <tt>sspreq</tt> attribute or which has
1188       an <tt>ssp</tt> attribute, then the resulting function will have
1189       an <tt>sspreq</tt> attribute.</dd>
1190
1191   <dt><tt><b>noredzone</b></tt></dt>
1192   <dd>This attribute indicates that the code generator should not use a red
1193       zone, even if the target-specific ABI normally permits it.</dd>
1194
1195   <dt><tt><b>noimplicitfloat</b></tt></dt>
1196   <dd>This attributes disables implicit floating point instructions.</dd>
1197
1198   <dt><tt><b>naked</b></tt></dt>
1199   <dd>This attribute disables prologue / epilogue emission for the function.
1200       This can have very system-specific consequences.</dd>
1201 </dl>
1202
1203 </div>
1204
1205 <!-- ======================================================================= -->
1206 <div class="doc_subsection">
1207   <a name="moduleasm">Module-Level Inline Assembly</a>
1208 </div>
1209
1210 <div class="doc_text">
1211
1212 <p>Modules may contain "module-level inline asm" blocks, which corresponds to
1213    the GCC "file scope inline asm" blocks.  These blocks are internally
1214    concatenated by LLVM and treated as a single unit, but may be separated in
1215    the <tt>.ll</tt> file if desired.  The syntax is very simple:</p>
1216
1217 <div class="doc_code">
1218 <pre>
1219 module asm "inline asm code goes here"
1220 module asm "more can go here"
1221 </pre>
1222 </div>
1223
1224 <p>The strings can contain any character by escaping non-printable characters.
1225    The escape sequence used is simply "\xx" where "xx" is the two digit hex code
1226    for the number.</p>
1227
1228 <p>The inline asm code is simply printed to the machine code .s file when
1229    assembly code is generated.</p>
1230
1231 </div>
1232
1233 <!-- ======================================================================= -->
1234 <div class="doc_subsection">
1235   <a name="datalayout">Data Layout</a>
1236 </div>
1237
1238 <div class="doc_text">
1239
1240 <p>A module may specify a target specific data layout string that specifies how
1241    data is to be laid out in memory. The syntax for the data layout is
1242    simply:</p>
1243
1244 <div class="doc_code">
1245 <pre>
1246 target datalayout = "<i>layout specification</i>"
1247 </pre>
1248 </div>
1249
1250 <p>The <i>layout specification</i> consists of a list of specifications
1251    separated by the minus sign character ('-').  Each specification starts with
1252    a letter and may include other information after the letter to define some
1253    aspect of the data layout.  The specifications accepted are as follows:</p>
1254
1255 <dl>
1256   <dt><tt>E</tt></dt>
1257   <dd>Specifies that the target lays out data in big-endian form. That is, the
1258       bits with the most significance have the lowest address location.</dd>
1259
1260   <dt><tt>e</tt></dt>
1261   <dd>Specifies that the target lays out data in little-endian form. That is,
1262       the bits with the least significance have the lowest address
1263       location.</dd>
1264
1265   <dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1266   <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and
1267       <i>preferred</i> alignments. All sizes are in bits. Specifying
1268       the <i>pref</i> alignment is optional. If omitted, the
1269       preceding <tt>:</tt> should be omitted too.</dd>
1270
1271   <dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1272   <dd>This specifies the alignment for an integer type of a given bit
1273       <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd>
1274
1275   <dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1276   <dd>This specifies the alignment for a vector type of a given bit
1277       <i>size</i>.</dd>
1278
1279   <dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1280   <dd>This specifies the alignment for a floating point type of a given bit
1281       <i>size</i>. The value of <i>size</i> must be either 32 (float) or 64
1282       (double).</dd>
1283
1284   <dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1285   <dd>This specifies the alignment for an aggregate type of a given bit
1286       <i>size</i>.</dd>
1287
1288   <dt><tt>s<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1289   <dd>This specifies the alignment for a stack object of a given bit
1290       <i>size</i>.</dd>
1291
1292   <dt><tt>n<i>size1</i>:<i>size2</i>:<i>size3</i>...</tt></dt>
1293   <dd>This specifies a set of native integer widths for the target CPU
1294       in bits.  For example, it might contain "n32" for 32-bit PowerPC,
1295       "n32:64" for PowerPC 64, or "n8:16:32:64" for X86-64.  Elements of
1296       this set are considered to support most general arithmetic
1297       operations efficiently.</dd>
1298 </dl>
1299
1300 <p>When constructing the data layout for a given target, LLVM starts with a
1301    default set of specifications which are then (possibly) overriden by the
1302    specifications in the <tt>datalayout</tt> keyword. The default specifications
1303    are given in this list:</p>
1304
1305 <ul>
1306   <li><tt>E</tt> - big endian</li>
1307   <li><tt>p:64:64:64</tt> - 64-bit pointers with 64-bit alignment</li>
1308   <li><tt>i1:8:8</tt> - i1 is 8-bit (byte) aligned</li>
1309   <li><tt>i8:8:8</tt> - i8 is 8-bit (byte) aligned</li>
1310   <li><tt>i16:16:16</tt> - i16 is 16-bit aligned</li>
1311   <li><tt>i32:32:32</tt> - i32 is 32-bit aligned</li>
1312   <li><tt>i64:32:64</tt> - i64 has ABI alignment of 32-bits but preferred
1313   alignment of 64-bits</li>
1314   <li><tt>f32:32:32</tt> - float is 32-bit aligned</li>
1315   <li><tt>f64:64:64</tt> - double is 64-bit aligned</li>
1316   <li><tt>v64:64:64</tt> - 64-bit vector is 64-bit aligned</li>
1317   <li><tt>v128:128:128</tt> - 128-bit vector is 128-bit aligned</li>
1318   <li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li>
1319   <li><tt>s0:64:64</tt> - stack objects are 64-bit aligned</li>
1320 </ul>
1321
1322 <p>When LLVM is determining the alignment for a given type, it uses the
1323    following rules:</p>
1324
1325 <ol>
1326   <li>If the type sought is an exact match for one of the specifications, that
1327       specification is used.</li>
1328
1329   <li>If no match is found, and the type sought is an integer type, then the
1330       smallest integer type that is larger than the bitwidth of the sought type
1331       is used. If none of the specifications are larger than the bitwidth then
1332       the the largest integer type is used. For example, given the default
1333       specifications above, the i7 type will use the alignment of i8 (next
1334       largest) while both i65 and i256 will use the alignment of i64 (largest
1335       specified).</li>
1336
1337   <li>If no match is found, and the type sought is a vector type, then the
1338       largest vector type that is smaller than the sought vector type will be
1339       used as a fall back.  This happens because &lt;128 x double&gt; can be
1340       implemented in terms of 64 &lt;2 x double&gt;, for example.</li>
1341 </ol>
1342
1343 </div>
1344
1345 <!-- ======================================================================= -->
1346 <div class="doc_subsection">
1347   <a name="pointeraliasing">Pointer Aliasing Rules</a>
1348 </div>
1349
1350 <div class="doc_text">
1351
1352 <p>Any memory access must be done through a pointer value associated
1353 with an address range of the memory access, otherwise the behavior
1354 is undefined. Pointer values are associated with address ranges
1355 according to the following rules:</p>
1356
1357 <ul>
1358   <li>A pointer value formed from a
1359       <tt><a href="#i_getelementptr">getelementptr</a></tt> instruction
1360       is associated with the addresses associated with the first operand
1361       of the <tt>getelementptr</tt>.</li>
1362   <li>An address of a global variable is associated with the address
1363       range of the variable's storage.</li>
1364   <li>The result value of an allocation instruction is associated with
1365       the address range of the allocated storage.</li>
1366   <li>A null pointer in the default address-space is associated with
1367       no address.</li>
1368   <li>A pointer value formed by an
1369       <tt><a href="#i_inttoptr">inttoptr</a></tt> is associated with all
1370       address ranges of all pointer values that contribute (directly or
1371       indirectly) to the computation of the pointer's value.</li>
1372   <li>The result value of a
1373       <tt><a href="#i_bitcast">bitcast</a></tt> is associated with all
1374       addresses associated with the operand of the <tt>bitcast</tt>.</li>
1375   <li>An integer constant other than zero or a pointer value returned
1376       from a function not defined within LLVM may be associated with address
1377       ranges allocated through mechanisms other than those provided by
1378       LLVM. Such ranges shall not overlap with any ranges of addresses
1379       allocated by mechanisms provided by LLVM.</li>
1380   </ul>
1381
1382 <p>LLVM IR does not associate types with memory. The result type of a
1383 <tt><a href="#i_load">load</a></tt> merely indicates the size and
1384 alignment of the memory from which to load, as well as the
1385 interpretation of the value. The first operand of a
1386 <tt><a href="#i_store">store</a></tt> similarly only indicates the size
1387 and alignment of the store.</p>
1388
1389 <p>Consequently, type-based alias analysis, aka TBAA, aka
1390 <tt>-fstrict-aliasing</tt>, is not applicable to general unadorned
1391 LLVM IR. <a href="#metadata">Metadata</a> may be used to encode
1392 additional information which specialized optimization passes may use
1393 to implement type-based alias analysis.</p>
1394
1395 </div>
1396
1397 <!-- *********************************************************************** -->
1398 <div class="doc_section"> <a name="typesystem">Type System</a> </div>
1399 <!-- *********************************************************************** -->
1400
1401 <div class="doc_text">
1402
1403 <p>The LLVM type system is one of the most important features of the
1404    intermediate representation.  Being typed enables a number of optimizations
1405    to be performed on the intermediate representation directly, without having
1406    to do extra analyses on the side before the transformation.  A strong type
1407    system makes it easier to read the generated code and enables novel analyses
1408    and transformations that are not feasible to perform on normal three address
1409    code representations.</p>
1410
1411 </div>
1412
1413 <!-- ======================================================================= -->
1414 <div class="doc_subsection"> <a name="t_classifications">Type
1415 Classifications</a> </div>
1416
1417 <div class="doc_text">
1418
1419 <p>The types fall into a few useful classifications:</p>
1420
1421 <table border="1" cellspacing="0" cellpadding="4">
1422   <tbody>
1423     <tr><th>Classification</th><th>Types</th></tr>
1424     <tr>
1425       <td><a href="#t_integer">integer</a></td>
1426       <td><tt>i1, i2, i3, ... i8, ... i16, ... i32, ... i64, ... </tt></td>
1427     </tr>
1428     <tr>
1429       <td><a href="#t_floating">floating point</a></td>
1430       <td><tt>float, double, x86_fp80, fp128, ppc_fp128</tt></td>
1431     </tr>
1432     <tr>
1433       <td><a name="t_firstclass">first class</a></td>
1434       <td><a href="#t_integer">integer</a>,
1435           <a href="#t_floating">floating point</a>,
1436           <a href="#t_pointer">pointer</a>,
1437           <a href="#t_vector">vector</a>,
1438           <a href="#t_struct">structure</a>,
1439           <a href="#t_union">union</a>,
1440           <a href="#t_array">array</a>,
1441           <a href="#t_label">label</a>,
1442           <a href="#t_metadata">metadata</a>.
1443       </td>
1444     </tr>
1445     <tr>
1446       <td><a href="#t_primitive">primitive</a></td>
1447       <td><a href="#t_label">label</a>,
1448           <a href="#t_void">void</a>,
1449           <a href="#t_floating">floating point</a>,
1450           <a href="#t_metadata">metadata</a>.</td>
1451     </tr>
1452     <tr>
1453       <td><a href="#t_derived">derived</a></td>
1454       <td><a href="#t_array">array</a>,
1455           <a href="#t_function">function</a>,
1456           <a href="#t_pointer">pointer</a>,
1457           <a href="#t_struct">structure</a>,
1458           <a href="#t_pstruct">packed structure</a>,
1459           <a href="#t_union">union</a>,
1460           <a href="#t_vector">vector</a>,
1461           <a href="#t_opaque">opaque</a>.
1462       </td>
1463     </tr>
1464   </tbody>
1465 </table>
1466
1467 <p>The <a href="#t_firstclass">first class</a> types are perhaps the most
1468    important.  Values of these types are the only ones which can be produced by
1469    instructions.</p>
1470
1471 </div>
1472
1473 <!-- ======================================================================= -->
1474 <div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div>
1475
1476 <div class="doc_text">
1477
1478 <p>The primitive types are the fundamental building blocks of the LLVM
1479    system.</p>
1480
1481 </div>
1482
1483 <!-- _______________________________________________________________________ -->
1484 <div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div>
1485
1486 <div class="doc_text">
1487
1488 <h5>Overview:</h5>
1489 <p>The integer type is a very simple type that simply specifies an arbitrary
1490    bit width for the integer type desired. Any bit width from 1 bit to
1491    2<sup>23</sup>-1 (about 8 million) can be specified.</p>
1492
1493 <h5>Syntax:</h5>
1494 <pre>
1495   iN
1496 </pre>
1497
1498 <p>The number of bits the integer will occupy is specified by the <tt>N</tt>
1499    value.</p>
1500
1501 <h5>Examples:</h5>
1502 <table class="layout">
1503   <tr class="layout">
1504     <td class="left"><tt>i1</tt></td>
1505     <td class="left">a single-bit integer.</td>
1506   </tr>
1507   <tr class="layout">
1508     <td class="left"><tt>i32</tt></td>
1509     <td class="left">a 32-bit integer.</td>
1510   </tr>
1511   <tr class="layout">
1512     <td class="left"><tt>i1942652</tt></td>
1513     <td class="left">a really big integer of over 1 million bits.</td>
1514   </tr>
1515 </table>
1516
1517 </div>
1518
1519 <!-- _______________________________________________________________________ -->
1520 <div class="doc_subsubsection"> <a name="t_floating">Floating Point Types</a> </div>
1521
1522 <div class="doc_text">
1523
1524 <table>
1525   <tbody>
1526     <tr><th>Type</th><th>Description</th></tr>
1527     <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
1528     <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
1529     <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr>
1530     <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr>
1531     <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr>
1532   </tbody>
1533 </table>
1534
1535 </div>
1536
1537 <!-- _______________________________________________________________________ -->
1538 <div class="doc_subsubsection"> <a name="t_void">Void Type</a> </div>
1539
1540 <div class="doc_text">
1541
1542 <h5>Overview:</h5>
1543 <p>The void type does not represent any value and has no size.</p>
1544
1545 <h5>Syntax:</h5>
1546 <pre>
1547   void
1548 </pre>
1549
1550 </div>
1551
1552 <!-- _______________________________________________________________________ -->
1553 <div class="doc_subsubsection"> <a name="t_label">Label Type</a> </div>
1554
1555 <div class="doc_text">
1556
1557 <h5>Overview:</h5>
1558 <p>The label type represents code labels.</p>
1559
1560 <h5>Syntax:</h5>
1561 <pre>
1562   label
1563 </pre>
1564
1565 </div>
1566
1567 <!-- _______________________________________________________________________ -->
1568 <div class="doc_subsubsection"> <a name="t_metadata">Metadata Type</a> </div>
1569
1570 <div class="doc_text">
1571
1572 <h5>Overview:</h5>
1573 <p>The metadata type represents embedded metadata. No derived types may be
1574    created from metadata except for <a href="#t_function">function</a>
1575    arguments.
1576
1577 <h5>Syntax:</h5>
1578 <pre>
1579   metadata
1580 </pre>
1581
1582 </div>
1583
1584
1585 <!-- ======================================================================= -->
1586 <div class="doc_subsection"> <a name="t_derived">Derived Types</a> </div>
1587
1588 <div class="doc_text">
1589
1590 <p>The real power in LLVM comes from the derived types in the system.  This is
1591    what allows a programmer to represent arrays, functions, pointers, and other
1592    useful types.  Each of these types contain one or more element types which
1593    may be a primitive type, or another derived type.  For example, it is
1594    possible to have a two dimensional array, using an array as the element type
1595    of another array.</p>
1596
1597
1598 </div>
1599
1600 <!-- _______________________________________________________________________ -->
1601 <div class="doc_subsubsection"> <a name="t_aggregate">Aggregate Types</a> </div>
1602
1603 <div class="doc_text">
1604
1605 <p>Aggregate Types are a subset of derived types that can contain multiple
1606   member types. <a href="#t_array">Arrays</a>,
1607   <a href="#t_struct">structs</a>, <a href="#t_vector">vectors</a> and
1608   <a href="#t_union">unions</a> are aggregate types.</p>
1609
1610 </div>
1611
1612 </div>
1613
1614 <!-- _______________________________________________________________________ -->
1615 <div class="doc_subsubsection"> <a name="t_array">Array Type</a> </div>
1616
1617 <div class="doc_text">
1618
1619 <h5>Overview:</h5>
1620 <p>The array type is a very simple derived type that arranges elements
1621    sequentially in memory.  The array type requires a size (number of elements)
1622    and an underlying data type.</p>
1623
1624 <h5>Syntax:</h5>
1625 <pre>
1626   [&lt;# elements&gt; x &lt;elementtype&gt;]
1627 </pre>
1628
1629 <p>The number of elements is a constant integer value; <tt>elementtype</tt> may
1630    be any type with a size.</p>
1631
1632 <h5>Examples:</h5>
1633 <table class="layout">
1634   <tr class="layout">
1635     <td class="left"><tt>[40 x i32]</tt></td>
1636     <td class="left">Array of 40 32-bit integer values.</td>
1637   </tr>
1638   <tr class="layout">
1639     <td class="left"><tt>[41 x i32]</tt></td>
1640     <td class="left">Array of 41 32-bit integer values.</td>
1641   </tr>
1642   <tr class="layout">
1643     <td class="left"><tt>[4 x i8]</tt></td>
1644     <td class="left">Array of 4 8-bit integer values.</td>
1645   </tr>
1646 </table>
1647 <p>Here are some examples of multidimensional arrays:</p>
1648 <table class="layout">
1649   <tr class="layout">
1650     <td class="left"><tt>[3 x [4 x i32]]</tt></td>
1651     <td class="left">3x4 array of 32-bit integer values.</td>
1652   </tr>
1653   <tr class="layout">
1654     <td class="left"><tt>[12 x [10 x float]]</tt></td>
1655     <td class="left">12x10 array of single precision floating point values.</td>
1656   </tr>
1657   <tr class="layout">
1658     <td class="left"><tt>[2 x [3 x [4 x i16]]]</tt></td>
1659     <td class="left">2x3x4 array of 16-bit integer  values.</td>
1660   </tr>
1661 </table>
1662
1663 <p>There is no restriction on indexing beyond the end of the array implied by
1664    a static type (though there are restrictions on indexing beyond the bounds
1665    of an allocated object in some cases). This means that single-dimension
1666    'variable sized array' addressing can be implemented in LLVM with a zero
1667    length array type. An implementation of 'pascal style arrays' in LLVM could
1668    use the type "<tt>{ i32, [0 x float]}</tt>", for example.</p>
1669
1670 </div>
1671
1672 <!-- _______________________________________________________________________ -->
1673 <div class="doc_subsubsection"> <a name="t_function">Function Type</a> </div>
1674
1675 <div class="doc_text">
1676
1677 <h5>Overview:</h5>
1678 <p>The function type can be thought of as a function signature.  It consists of
1679    a return type and a list of formal parameter types. The return type of a
1680    function type is a scalar type, a void type, a struct type, or a union
1681    type.  If the return type is a struct type then all struct elements must be
1682    of first class types, and the struct must have at least one element.</p>
1683
1684 <h5>Syntax:</h5>
1685 <pre>
1686   &lt;returntype&gt; (&lt;parameter list&gt;)
1687 </pre>
1688
1689 <p>...where '<tt>&lt;parameter list&gt;</tt>' is a comma-separated list of type
1690    specifiers.  Optionally, the parameter list may include a type <tt>...</tt>,
1691    which indicates that the function takes a variable number of arguments.
1692    Variable argument functions can access their arguments with
1693    the <a href="#int_varargs">variable argument handling intrinsic</a>
1694    functions.  '<tt>&lt;returntype&gt;</tt>' is any type except
1695    <a href="#t_label">label</a>.</p>
1696
1697 <h5>Examples:</h5>
1698 <table class="layout">
1699   <tr class="layout">
1700     <td class="left"><tt>i32 (i32)</tt></td>
1701     <td class="left">function taking an <tt>i32</tt>, returning an <tt>i32</tt>
1702     </td>
1703   </tr><tr class="layout">
1704     <td class="left"><tt>float&nbsp;(i16,&nbsp;i32&nbsp;*)&nbsp;*
1705     </tt></td>
1706     <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes
1707       an <tt>i16</tt> and a <a href="#t_pointer">pointer</a> to <tt>i32</tt>,
1708       returning <tt>float</tt>.
1709     </td>
1710   </tr><tr class="layout">
1711     <td class="left"><tt>i32 (i8*, ...)</tt></td>
1712     <td class="left">A vararg function that takes at least one
1713       <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C),
1714       which returns an integer.  This is the signature for <tt>printf</tt> in
1715       LLVM.
1716     </td>
1717   </tr><tr class="layout">
1718     <td class="left"><tt>{i32, i32} (i32)</tt></td>
1719     <td class="left">A function taking an <tt>i32</tt>, returning a
1720         <a href="#t_struct">structure</a> containing two <tt>i32</tt> values
1721     </td>
1722   </tr>
1723 </table>
1724
1725 </div>
1726
1727 <!-- _______________________________________________________________________ -->
1728 <div class="doc_subsubsection"> <a name="t_struct">Structure Type</a> </div>
1729
1730 <div class="doc_text">
1731
1732 <h5>Overview:</h5>
1733 <p>The structure type is used to represent a collection of data members together
1734    in memory.  The packing of the field types is defined to match the ABI of the
1735    underlying processor.  The elements of a structure may be any type that has a
1736    size.</p>
1737
1738 <p>Structures in memory are accessed using '<tt><a href="#i_load">load</a></tt>'
1739    and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field
1740    with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.
1741    Structures in registers are accessed using the
1742    '<tt><a href="#i_extractvalue">extractvalue</a></tt>' and
1743    '<tt><a href="#i_insertvalue">insertvalue</a></tt>' instructions.</p>
1744 <h5>Syntax:</h5>
1745 <pre>
1746   { &lt;type list&gt; }
1747 </pre>
1748
1749 <h5>Examples:</h5>
1750 <table class="layout">
1751   <tr class="layout">
1752     <td class="left"><tt>{ i32, i32, i32 }</tt></td>
1753     <td class="left">A triple of three <tt>i32</tt> values</td>
1754   </tr><tr class="layout">
1755     <td class="left"><tt>{&nbsp;float,&nbsp;i32&nbsp;(i32)&nbsp;*&nbsp;}</tt></td>
1756     <td class="left">A pair, where the first element is a <tt>float</tt> and the
1757       second element is a <a href="#t_pointer">pointer</a> to a
1758       <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
1759       an <tt>i32</tt>.</td>
1760   </tr>
1761 </table>
1762
1763 </div>
1764
1765 <!-- _______________________________________________________________________ -->
1766 <div class="doc_subsubsection"> <a name="t_pstruct">Packed Structure Type</a>
1767 </div>
1768
1769 <div class="doc_text">
1770
1771 <h5>Overview:</h5>
1772 <p>The packed structure type is used to represent a collection of data members
1773    together in memory.  There is no padding between fields.  Further, the
1774    alignment of a packed structure is 1 byte.  The elements of a packed
1775    structure may be any type that has a size.</p>
1776
1777 <p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and
1778    '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with
1779    the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
1780
1781 <h5>Syntax:</h5>
1782 <pre>
1783   &lt; { &lt;type list&gt; } &gt;
1784 </pre>
1785
1786 <h5>Examples:</h5>
1787 <table class="layout">
1788   <tr class="layout">
1789     <td class="left"><tt>&lt; { i32, i32, i32 } &gt;</tt></td>
1790     <td class="left">A triple of three <tt>i32</tt> values</td>
1791   </tr><tr class="layout">
1792   <td class="left">
1793 <tt>&lt;&nbsp;{&nbsp;float,&nbsp;i32&nbsp;(i32)*&nbsp;}&nbsp;&gt;</tt></td>
1794     <td class="left">A pair, where the first element is a <tt>float</tt> and the
1795       second element is a <a href="#t_pointer">pointer</a> to a
1796       <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
1797       an <tt>i32</tt>.</td>
1798   </tr>
1799 </table>
1800
1801 </div>
1802
1803 <!-- _______________________________________________________________________ -->
1804 <div class="doc_subsubsection"> <a name="t_union">Union Type</a> </div>
1805
1806 <div class="doc_text">
1807
1808 <h5>Overview:</h5>
1809 <p>A union type describes an object with size and alignment suitable for
1810    an object of any one of a given set of types (also known as an "untagged"
1811    union). It is similar in concept and usage to a
1812    <a href="#t_struct">struct</a>, except that all members of the union
1813    have an offset of zero. The elements of a union may be any type that has a
1814    size. Unions must have at least one member - empty unions are not allowed.
1815    </p>
1816
1817 <p>The size of the union as a whole will be the size of its largest member,
1818    and the alignment requirements of the union as a whole will be the largest
1819    alignment requirement of any member.</p>
1820
1821 <p>Union members are accessed using '<tt><a href="#i_load">load</a></tt> and
1822    '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with
1823    the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.
1824    Since all members are at offset zero, the getelementptr instruction does
1825    not affect the address, only the type of the resulting pointer.</p>
1826
1827 <h5>Syntax:</h5>
1828 <pre>
1829   union { &lt;type list&gt; }
1830 </pre>
1831
1832 <h5>Examples:</h5>
1833 <table class="layout">
1834   <tr class="layout">
1835     <td class="left"><tt>union { i32, i32*, float }</tt></td>
1836     <td class="left">A union of three types: an <tt>i32</tt>, a pointer to
1837       an <tt>i32</tt>, and a <tt>float</tt>.</td>
1838   </tr><tr class="layout">
1839     <td class="left">
1840       <tt>union {&nbsp;float,&nbsp;i32&nbsp;(i32)&nbsp;*&nbsp;}</tt></td>
1841     <td class="left">A union, where the first element is a <tt>float</tt> and the
1842       second element is a <a href="#t_pointer">pointer</a> to a
1843       <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
1844       an <tt>i32</tt>.</td>
1845   </tr>
1846 </table>
1847
1848 </div>
1849
1850 <!-- _______________________________________________________________________ -->
1851 <div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div>
1852
1853 <div class="doc_text">
1854
1855 <h5>Overview:</h5>
1856 <p>The pointer type is used to specify memory locations.
1857    Pointers are commonly used to reference objects in memory.</p>
1858
1859 <p>Pointer types may have an optional address space attribute defining the
1860    numbered address space where the pointed-to object resides. The default
1861    address space is number zero. The semantics of non-zero address
1862    spaces are target-specific.</p>
1863
1864 <p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does it
1865    permit pointers to labels (<tt>label*</tt>).  Use <tt>i8*</tt> instead.</p>
1866
1867 <h5>Syntax:</h5>
1868 <pre>
1869   &lt;type&gt; *
1870 </pre>
1871
1872 <h5>Examples:</h5>
1873 <table class="layout">
1874   <tr class="layout">
1875     <td class="left"><tt>[4 x i32]*</tt></td>
1876     <td class="left">A <a href="#t_pointer">pointer</a> to <a
1877                     href="#t_array">array</a> of four <tt>i32</tt> values.</td>
1878   </tr>
1879   <tr class="layout">
1880     <td class="left"><tt>i32 (i32 *) *</tt></td>
1881     <td class="left"> A <a href="#t_pointer">pointer</a> to a <a
1882       href="#t_function">function</a> that takes an <tt>i32*</tt>, returning an
1883       <tt>i32</tt>.</td>
1884   </tr>
1885   <tr class="layout">
1886     <td class="left"><tt>i32 addrspace(5)*</tt></td>
1887     <td class="left">A <a href="#t_pointer">pointer</a> to an <tt>i32</tt> value
1888      that resides in address space #5.</td>
1889   </tr>
1890 </table>
1891
1892 </div>
1893
1894 <!-- _______________________________________________________________________ -->
1895 <div class="doc_subsubsection"> <a name="t_vector">Vector Type</a> </div>
1896
1897 <div class="doc_text">
1898
1899 <h5>Overview:</h5>
1900 <p>A vector type is a simple derived type that represents a vector of elements.
1901    Vector types are used when multiple primitive data are operated in parallel
1902    using a single instruction (SIMD).  A vector type requires a size (number of
1903    elements) and an underlying primitive data type.  Vector types are considered
1904    <a href="#t_firstclass">first class</a>.</p>
1905
1906 <h5>Syntax:</h5>
1907 <pre>
1908   &lt; &lt;# elements&gt; x &lt;elementtype&gt; &gt;
1909 </pre>
1910
1911 <p>The number of elements is a constant integer value; elementtype may be any
1912    integer or floating point type.</p>
1913
1914 <h5>Examples:</h5>
1915 <table class="layout">
1916   <tr class="layout">
1917     <td class="left"><tt>&lt;4 x i32&gt;</tt></td>
1918     <td class="left">Vector of 4 32-bit integer values.</td>
1919   </tr>
1920   <tr class="layout">
1921     <td class="left"><tt>&lt;8 x float&gt;</tt></td>
1922     <td class="left">Vector of 8 32-bit floating-point values.</td>
1923   </tr>
1924   <tr class="layout">
1925     <td class="left"><tt>&lt;2 x i64&gt;</tt></td>
1926     <td class="left">Vector of 2 64-bit integer values.</td>
1927   </tr>
1928 </table>
1929
1930 </div>
1931
1932 <!-- _______________________________________________________________________ -->
1933 <div class="doc_subsubsection"> <a name="t_opaque">Opaque Type</a> </div>
1934 <div class="doc_text">
1935
1936 <h5>Overview:</h5>
1937 <p>Opaque types are used to represent unknown types in the system.  This
1938    corresponds (for example) to the C notion of a forward declared structure
1939    type.  In LLVM, opaque types can eventually be resolved to any type (not just
1940    a structure type).</p>
1941
1942 <h5>Syntax:</h5>
1943 <pre>
1944   opaque
1945 </pre>
1946
1947 <h5>Examples:</h5>
1948 <table class="layout">
1949   <tr class="layout">
1950     <td class="left"><tt>opaque</tt></td>
1951     <td class="left">An opaque type.</td>
1952   </tr>
1953 </table>
1954
1955 </div>
1956
1957 <!-- ======================================================================= -->
1958 <div class="doc_subsection">
1959   <a name="t_uprefs">Type Up-references</a>
1960 </div>
1961
1962 <div class="doc_text">
1963
1964 <h5>Overview:</h5>
1965 <p>An "up reference" allows you to refer to a lexically enclosing type without
1966    requiring it to have a name. For instance, a structure declaration may
1967    contain a pointer to any of the types it is lexically a member of.  Example
1968    of up references (with their equivalent as named type declarations)
1969    include:</p>
1970
1971 <pre>
1972    { \2 * }                %x = type { %x* }
1973    { \2 }*                 %y = type { %y }*
1974    \1*                     %z = type %z*
1975 </pre>
1976
1977 <p>An up reference is needed by the asmprinter for printing out cyclic types
1978    when there is no declared name for a type in the cycle.  Because the
1979    asmprinter does not want to print out an infinite type string, it needs a
1980    syntax to handle recursive types that have no names (all names are optional
1981    in llvm IR).</p>
1982
1983 <h5>Syntax:</h5>
1984 <pre>
1985    \&lt;level&gt;
1986 </pre>
1987
1988 <p>The level is the count of the lexical type that is being referred to.</p>
1989
1990 <h5>Examples:</h5>
1991 <table class="layout">
1992   <tr class="layout">
1993     <td class="left"><tt>\1*</tt></td>
1994     <td class="left">Self-referential pointer.</td>
1995   </tr>
1996   <tr class="layout">
1997     <td class="left"><tt>{ { \3*, i8 }, i32 }</tt></td>
1998     <td class="left">Recursive structure where the upref refers to the out-most
1999                      structure.</td>
2000   </tr>
2001 </table>
2002
2003 </div>
2004
2005 <!-- *********************************************************************** -->
2006 <div class="doc_section"> <a name="constants">Constants</a> </div>
2007 <!-- *********************************************************************** -->
2008
2009 <div class="doc_text">
2010
2011 <p>LLVM has several different basic types of constants.  This section describes
2012    them all and their syntax.</p>
2013
2014 </div>
2015
2016 <!-- ======================================================================= -->
2017 <div class="doc_subsection"><a name="simpleconstants">Simple Constants</a></div>
2018
2019 <div class="doc_text">
2020
2021 <dl>
2022   <dt><b>Boolean constants</b></dt>
2023   <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
2024       constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd>
2025
2026   <dt><b>Integer constants</b></dt>
2027   <dd>Standard integers (such as '4') are constants of
2028       the <a href="#t_integer">integer</a> type.  Negative numbers may be used
2029       with integer types.</dd>
2030
2031   <dt><b>Floating point constants</b></dt>
2032   <dd>Floating point constants use standard decimal notation (e.g. 123.421),
2033       exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal
2034       notation (see below).  The assembler requires the exact decimal value of a
2035       floating-point constant.  For example, the assembler accepts 1.25 but
2036       rejects 1.3 because 1.3 is a repeating decimal in binary.  Floating point
2037       constants must have a <a href="#t_floating">floating point</a> type. </dd>
2038
2039   <dt><b>Null pointer constants</b></dt>
2040   <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant
2041       and must be of <a href="#t_pointer">pointer type</a>.</dd>
2042 </dl>
2043
2044 <p>The one non-intuitive notation for constants is the hexadecimal form of
2045    floating point constants.  For example, the form '<tt>double
2046    0x432ff973cafa8000</tt>' is equivalent to (but harder to read than)
2047    '<tt>double 4.5e+15</tt>'.  The only time hexadecimal floating point
2048    constants are required (and the only time that they are generated by the
2049    disassembler) is when a floating point constant must be emitted but it cannot
2050    be represented as a decimal floating point number in a reasonable number of
2051    digits.  For example, NaN's, infinities, and other special values are
2052    represented in their IEEE hexadecimal format so that assembly and disassembly
2053    do not cause any bits to change in the constants.</p>
2054
2055 <p>When using the hexadecimal form, constants of types float and double are
2056    represented using the 16-digit form shown above (which matches the IEEE754
2057    representation for double); float values must, however, be exactly
2058    representable as IEE754 single precision.  Hexadecimal format is always used
2059    for long double, and there are three forms of long double.  The 80-bit format
2060    used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits.
2061    The 128-bit format used by PowerPC (two adjacent doubles) is represented
2062    by <tt>0xM</tt> followed by 32 hexadecimal digits.  The IEEE 128-bit format
2063    is represented by <tt>0xL</tt> followed by 32 hexadecimal digits; no
2064    currently supported target uses this format.  Long doubles will only work if
2065    they match the long double format on your target.  All hexadecimal formats
2066    are big-endian (sign bit at the left).</p>
2067
2068 </div>
2069
2070 <!-- ======================================================================= -->
2071 <div class="doc_subsection">
2072 <a name="aggregateconstants"></a> <!-- old anchor -->
2073 <a name="complexconstants">Complex Constants</a>
2074 </div>
2075
2076 <div class="doc_text">
2077
2078 <p>Complex constants are a (potentially recursive) combination of simple
2079    constants and smaller complex constants.</p>
2080
2081 <dl>
2082   <dt><b>Structure constants</b></dt>
2083   <dd>Structure constants are represented with notation similar to structure
2084       type definitions (a comma separated list of elements, surrounded by braces
2085       (<tt>{}</tt>)).  For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>",
2086       where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>".
2087       Structure constants must have <a href="#t_struct">structure type</a>, and
2088       the number and types of elements must match those specified by the
2089       type.</dd>
2090
2091   <dt><b>Union constants</b></dt>
2092   <dd>Union constants are represented with notation similar to a structure with
2093       a single element - that is, a single typed element surrounded
2094       by braces (<tt>{}</tt>)).  For example: "<tt>{ i32 4 }</tt>".  The
2095       <a href="#t_union">union type</a> can be initialized with a single-element
2096       struct as long as the type of the struct element matches the type of
2097       one of the union members.</dd>
2098
2099   <dt><b>Array constants</b></dt>
2100   <dd>Array constants are represented with notation similar to array type
2101      definitions (a comma separated list of elements, surrounded by square
2102      brackets (<tt>[]</tt>)).  For example: "<tt>[ i32 42, i32 11, i32 74
2103      ]</tt>".  Array constants must have <a href="#t_array">array type</a>, and
2104      the number and types of elements must match those specified by the
2105      type.</dd>
2106
2107   <dt><b>Vector constants</b></dt>
2108   <dd>Vector constants are represented with notation similar to vector type
2109       definitions (a comma separated list of elements, surrounded by
2110       less-than/greater-than's (<tt>&lt;&gt;</tt>)).  For example: "<tt>&lt; i32
2111       42, i32 11, i32 74, i32 100 &gt;</tt>".  Vector constants must
2112       have <a href="#t_vector">vector type</a>, and the number and types of
2113       elements must match those specified by the type.</dd>
2114
2115   <dt><b>Zero initialization</b></dt>
2116   <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a
2117       value to zero of <em>any</em> type, including scalar and
2118       <a href="#t_aggregate">aggregate</a> types.
2119       This is often used to avoid having to print large zero initializers
2120       (e.g. for large arrays) and is always exactly equivalent to using explicit
2121       zero initializers.</dd>
2122
2123   <dt><b>Metadata node</b></dt>
2124   <dd>A metadata node is a structure-like constant with
2125       <a href="#t_metadata">metadata type</a>.  For example: "<tt>metadata !{
2126       i32 0, metadata !"test" }</tt>".  Unlike other constants that are meant to
2127       be interpreted as part of the instruction stream, metadata is a place to
2128       attach additional information such as debug info.</dd>
2129 </dl>
2130
2131 </div>
2132
2133 <!-- ======================================================================= -->
2134 <div class="doc_subsection">
2135   <a name="globalconstants">Global Variable and Function Addresses</a>
2136 </div>
2137
2138 <div class="doc_text">
2139
2140 <p>The addresses of <a href="#globalvars">global variables</a>
2141    and <a href="#functionstructure">functions</a> are always implicitly valid
2142    (link-time) constants.  These constants are explicitly referenced when
2143    the <a href="#identifiers">identifier for the global</a> is used and always
2144    have <a href="#t_pointer">pointer</a> type. For example, the following is a
2145    legal LLVM file:</p>
2146
2147 <div class="doc_code">
2148 <pre>
2149 @X = global i32 17
2150 @Y = global i32 42
2151 @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
2152 </pre>
2153 </div>
2154
2155 </div>
2156
2157 <!-- ======================================================================= -->
2158 <div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div>
2159 <div class="doc_text">
2160
2161 <p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and
2162    indicates that the user of the value may receive an unspecified bit-pattern.
2163    Undefined values may be of any type (other than label or void) and be used
2164    anywhere a constant is permitted.</p>
2165
2166 <p>Undefined values are useful because they indicate to the compiler that the
2167    program is well defined no matter what value is used.  This gives the
2168    compiler more freedom to optimize.  Here are some examples of (potentially
2169    surprising) transformations that are valid (in pseudo IR):</p>
2170
2171
2172 <div class="doc_code">
2173 <pre>
2174   %A = add %X, undef
2175   %B = sub %X, undef
2176   %C = xor %X, undef
2177 Safe:
2178   %A = undef
2179   %B = undef
2180   %C = undef
2181 </pre>
2182 </div>
2183
2184 <p>This is safe because all of the output bits are affected by the undef bits.
2185 Any output bit can have a zero or one depending on the input bits.</p>
2186
2187 <div class="doc_code">
2188 <pre>
2189   %A = or %X, undef
2190   %B = and %X, undef
2191 Safe:
2192   %A = -1
2193   %B = 0
2194 Unsafe:
2195   %A = undef
2196   %B = undef
2197 </pre>
2198 </div>
2199
2200 <p>These logical operations have bits that are not always affected by the input.
2201 For example, if "%X" has a zero bit, then the output of the 'and' operation will
2202 always be a zero, no matter what the corresponding bit from the undef is.  As
2203 such, it is unsafe to optimize or assume that the result of the and is undef.
2204 However, it is safe to assume that all bits of the undef could be 0, and
2205 optimize the and to 0.  Likewise, it is safe to assume that all the bits of
2206 the undef operand to the or could be set, allowing the or to be folded to
2207 -1.</p>
2208
2209 <div class="doc_code">
2210 <pre>
2211   %A = select undef, %X, %Y
2212   %B = select undef, 42, %Y
2213   %C = select %X, %Y, undef
2214 Safe:
2215   %A = %X     (or %Y)
2216   %B = 42     (or %Y)
2217   %C = %Y
2218 Unsafe:
2219   %A = undef
2220   %B = undef
2221   %C = undef
2222 </pre>
2223 </div>
2224
2225 <p>This set of examples show that undefined select (and conditional branch)
2226 conditions can go "either way" but they have to come from one of the two
2227 operands.  In the %A example, if %X and %Y were both known to have a clear low
2228 bit, then %A would have to have a cleared low bit.  However, in the %C example,
2229 the optimizer is allowed to assume that the undef operand could be the same as
2230 %Y, allowing the whole select to be eliminated.</p>
2231
2232
2233 <div class="doc_code">
2234 <pre>
2235   %A = xor undef, undef
2236
2237   %B = undef
2238   %C = xor %B, %B
2239
2240   %D = undef
2241   %E = icmp lt %D, 4
2242   %F = icmp gte %D, 4
2243
2244 Safe:
2245   %A = undef
2246   %B = undef
2247   %C = undef
2248   %D = undef
2249   %E = undef
2250   %F = undef
2251 </pre>
2252 </div>
2253
2254 <p>This example points out that two undef operands are not necessarily the same.
2255 This can be surprising to people (and also matches C semantics) where they
2256 assume that "X^X" is always zero, even if X is undef.  This isn't true for a
2257 number of reasons, but the short answer is that an undef "variable" can
2258 arbitrarily change its value over its "live range".  This is true because the
2259 "variable" doesn't actually <em>have a live range</em>.  Instead, the value is
2260 logically read from arbitrary registers that happen to be around when needed,
2261 so the value is not necessarily consistent over time.  In fact, %A and %C need
2262 to have the same semantics or the core LLVM "replace all uses with" concept
2263 would not hold.</p>
2264
2265 <div class="doc_code">
2266 <pre>
2267   %A = fdiv undef, %X
2268   %B = fdiv %X, undef
2269 Safe:
2270   %A = undef
2271 b: unreachable
2272 </pre>
2273 </div>
2274
2275 <p>These examples show the crucial difference between an <em>undefined
2276 value</em> and <em>undefined behavior</em>.  An undefined value (like undef) is
2277 allowed to have an arbitrary bit-pattern.  This means that the %A operation
2278 can be constant folded to undef because the undef could be an SNaN, and fdiv is
2279 not (currently) defined on SNaN's.  However, in the second example, we can make
2280 a more aggressive assumption: because the undef is allowed to be an arbitrary
2281 value, we are allowed to assume that it could be zero.  Since a divide by zero
2282 has <em>undefined behavior</em>, we are allowed to assume that the operation
2283 does not execute at all.  This allows us to delete the divide and all code after
2284 it: since the undefined operation "can't happen", the optimizer can assume that
2285 it occurs in dead code.
2286 </p>
2287
2288 <div class="doc_code">
2289 <pre>
2290 a:  store undef -> %X
2291 b:  store %X -> undef
2292 Safe:
2293 a: &lt;deleted&gt;
2294 b: unreachable
2295 </pre>
2296 </div>
2297
2298 <p>These examples reiterate the fdiv example: a store "of" an undefined value
2299 can be assumed to not have any effect: we can assume that the value is
2300 overwritten with bits that happen to match what was already there.  However, a
2301 store "to" an undefined location could clobber arbitrary memory, therefore, it
2302 has undefined behavior.</p>
2303
2304 </div>
2305
2306 <!-- ======================================================================= -->
2307 <div class="doc_subsection"><a name="trapvalues">Trap Values</a></div>
2308 <div class="doc_text">
2309
2310 <p>Trap values are similar to <a href="undefvalues">undef values</a>, however
2311    instead of representing an unspecified bit pattern, they represent the
2312    fact that an instruction or constant expression which cannot evoke side
2313    effects has nevertheless detected a condition which results in undefined
2314    behavior.<p>
2315
2316 <p>Any non-void instruction or constant expression other than non-intrinsic
2317    calls or invokes with a trap operand has trap as its result value.
2318    Any instruction with a trap operand which may have side effects emits
2319    those side effects as if it had an undef operand instead.</p>
2320
2321 <p>For example, an <a href="#i_and"><tt>and</tt></a> of a trap value with
2322    zero still has a trap value result. Using that value as an index in a
2323    <a href="#i_getelementptr"><tt>getelementptr</tt></a> yields a trap
2324    result. Using that result as the address of a
2325    <a href="#i_store"><tt>store</tt></a> produces undefined behavior.</p>
2326
2327 <p>There is currently no way of representing a trap constant in the IR; they
2328    only exist when produced by certain instructions, such as an
2329    <a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag
2330    set, when overflow occurs.</p>
2331
2332 </div>
2333
2334 <!-- ======================================================================= -->
2335 <div class="doc_subsection"><a name="blockaddress">Addresses of Basic
2336     Blocks</a></div>
2337 <div class="doc_text">
2338
2339 <p><b><tt>blockaddress(@function, %block)</tt></b></p>
2340
2341 <p>The '<tt>blockaddress</tt>' constant computes the address of the specified
2342    basic block in the specified function, and always has an i8* type.  Taking
2343    the address of the entry block is illegal.</p>
2344
2345 <p>This value only has defined behavior when used as an operand to the
2346    '<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction or for comparisons
2347    against null.  Pointer equality tests between labels addresses is undefined
2348    behavior - though, again, comparison against null is ok, and no label is
2349    equal to the null pointer.  This may also be passed around as an opaque
2350    pointer sized value as long as the bits are not inspected.  This allows
2351    <tt>ptrtoint</tt> and arithmetic to be performed on these values so long as
2352    the original value is reconstituted before the <tt>indirectbr</tt>.</p>
2353
2354 <p>Finally, some targets may provide defined semantics when
2355    using the value as the operand to an inline assembly, but that is target
2356    specific.
2357    </p>
2358
2359 </div>
2360
2361
2362 <!-- ======================================================================= -->
2363 <div class="doc_subsection"><a name="constantexprs">Constant Expressions</a>
2364 </div>
2365
2366 <div class="doc_text">
2367
2368 <p>Constant expressions are used to allow expressions involving other constants
2369    to be used as constants.  Constant expressions may be of
2370    any <a href="#t_firstclass">first class</a> type and may involve any LLVM
2371    operation that does not have side effects (e.g. load and call are not
2372    supported).  The following is the syntax for constant expressions:</p>
2373
2374 <dl>
2375   <dt><b><tt>trunc ( CST to TYPE )</tt></b></dt>
2376   <dd>Truncate a constant to another type. The bit size of CST must be larger
2377       than the bit size of TYPE. Both types must be integers.</dd>
2378
2379   <dt><b><tt>zext ( CST to TYPE )</tt></b></dt>
2380   <dd>Zero extend a constant to another type. The bit size of CST must be
2381       smaller or equal to the bit size of TYPE.  Both types must be
2382       integers.</dd>
2383
2384   <dt><b><tt>sext ( CST to TYPE )</tt></b></dt>
2385   <dd>Sign extend a constant to another type. The bit size of CST must be
2386       smaller or equal to the bit size of TYPE.  Both types must be
2387       integers.</dd>
2388
2389   <dt><b><tt>fptrunc ( CST to TYPE )</tt></b></dt>
2390   <dd>Truncate a floating point constant to another floating point type. The
2391       size of CST must be larger than the size of TYPE. Both types must be
2392       floating point.</dd>
2393
2394   <dt><b><tt>fpext ( CST to TYPE )</tt></b></dt>
2395   <dd>Floating point extend a constant to another type. The size of CST must be
2396       smaller or equal to the size of TYPE. Both types must be floating
2397       point.</dd>
2398
2399   <dt><b><tt>fptoui ( CST to TYPE )</tt></b></dt>
2400   <dd>Convert a floating point constant to the corresponding unsigned integer
2401       constant. TYPE must be a scalar or vector integer type. CST must be of
2402       scalar or vector floating point type. Both CST and TYPE must be scalars,
2403       or vectors of the same number of elements. If the value won't fit in the
2404       integer type, the results are undefined.</dd>
2405
2406   <dt><b><tt>fptosi ( CST to TYPE )</tt></b></dt>
2407   <dd>Convert a floating point constant to the corresponding signed integer
2408       constant.  TYPE must be a scalar or vector integer type. CST must be of
2409       scalar or vector floating point type. Both CST and TYPE must be scalars,
2410       or vectors of the same number of elements. If the value won't fit in the
2411       integer type, the results are undefined.</dd>
2412
2413   <dt><b><tt>uitofp ( CST to TYPE )</tt></b></dt>
2414   <dd>Convert an unsigned integer constant to the corresponding floating point
2415       constant. TYPE must be a scalar or vector floating point type. CST must be
2416       of scalar or vector integer type. Both CST and TYPE must be scalars, or
2417       vectors of the same number of elements. If the value won't fit in the
2418       floating point type, the results are undefined.</dd>
2419
2420   <dt><b><tt>sitofp ( CST to TYPE )</tt></b></dt>
2421   <dd>Convert a signed integer constant to the corresponding floating point
2422       constant. TYPE must be a scalar or vector floating point type. CST must be
2423       of scalar or vector integer type. Both CST and TYPE must be scalars, or
2424       vectors of the same number of elements. If the value won't fit in the
2425       floating point type, the results are undefined.</dd>
2426
2427   <dt><b><tt>ptrtoint ( CST to TYPE )</tt></b></dt>
2428   <dd>Convert a pointer typed constant to the corresponding integer constant
2429       <tt>TYPE</tt> must be an integer type. <tt>CST</tt> must be of pointer
2430       type. The <tt>CST</tt> value is zero extended, truncated, or unchanged to
2431       make it fit in <tt>TYPE</tt>.</dd>
2432
2433   <dt><b><tt>inttoptr ( CST to TYPE )</tt></b></dt>
2434   <dd>Convert a integer constant to a pointer constant.  TYPE must be a pointer
2435       type.  CST must be of integer type. The CST value is zero extended,
2436       truncated, or unchanged to make it fit in a pointer size. This one is
2437       <i>really</i> dangerous!</dd>
2438
2439   <dt><b><tt>bitcast ( CST to TYPE )</tt></b></dt>
2440   <dd>Convert a constant, CST, to another TYPE. The constraints of the operands
2441       are the same as those for the <a href="#i_bitcast">bitcast
2442       instruction</a>.</dd>
2443
2444   <dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
2445   <dt><b><tt>getelementptr inbounds ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
2446   <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
2447       constants.  As with the <a href="#i_getelementptr">getelementptr</a>
2448       instruction, the index list may have zero or more indexes, which are
2449       required to make sense for the type of "CSTPTR".</dd>
2450
2451   <dt><b><tt>select ( COND, VAL1, VAL2 )</tt></b></dt>
2452   <dd>Perform the <a href="#i_select">select operation</a> on constants.</dd>
2453
2454   <dt><b><tt>icmp COND ( VAL1, VAL2 )</tt></b></dt>
2455   <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd>
2456
2457   <dt><b><tt>fcmp COND ( VAL1, VAL2 )</tt></b></dt>
2458   <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd>
2459
2460   <dt><b><tt>extractelement ( VAL, IDX )</tt></b></dt>
2461   <dd>Perform the <a href="#i_extractelement">extractelement operation</a> on
2462       constants.</dd>
2463
2464   <dt><b><tt>insertelement ( VAL, ELT, IDX )</tt></b></dt>
2465   <dd>Perform the <a href="#i_insertelement">insertelement operation</a> on
2466     constants.</dd>
2467
2468   <dt><b><tt>shufflevector ( VEC1, VEC2, IDXMASK )</tt></b></dt>
2469   <dd>Perform the <a href="#i_shufflevector">shufflevector operation</a> on
2470       constants.</dd>
2471
2472   <dt><b><tt>OPCODE ( LHS, RHS )</tt></b></dt>
2473   <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may
2474       be any of the <a href="#binaryops">binary</a>
2475       or <a href="#bitwiseops">bitwise binary</a> operations.  The constraints
2476       on operands are the same as those for the corresponding instruction
2477       (e.g. no bitwise operations on floating point values are allowed).</dd>
2478 </dl>
2479
2480 </div>
2481
2482 <!-- *********************************************************************** -->
2483 <div class="doc_section"> <a name="othervalues">Other Values</a> </div>
2484 <!-- *********************************************************************** -->
2485
2486 <!-- ======================================================================= -->
2487 <div class="doc_subsection">
2488 <a name="inlineasm">Inline Assembler Expressions</a>
2489 </div>
2490
2491 <div class="doc_text">
2492
2493 <p>LLVM supports inline assembler expressions (as opposed
2494    to <a href="#moduleasm"> Module-Level Inline Assembly</a>) through the use of
2495    a special value.  This value represents the inline assembler as a string
2496    (containing the instructions to emit), a list of operand constraints (stored
2497    as a string), a flag that indicates whether or not the inline asm
2498    expression has side effects, and a flag indicating whether the function
2499    containing the asm needs to align its stack conservatively.  An example
2500    inline assembler expression is:</p>
2501
2502 <div class="doc_code">
2503 <pre>
2504 i32 (i32) asm "bswap $0", "=r,r"
2505 </pre>
2506 </div>
2507
2508 <p>Inline assembler expressions may <b>only</b> be used as the callee operand of
2509    a <a href="#i_call"><tt>call</tt> instruction</a>.  Thus, typically we
2510    have:</p>
2511
2512 <div class="doc_code">
2513 <pre>
2514 %X = call i32 asm "<a href="#int_bswap">bswap</a> $0", "=r,r"(i32 %Y)
2515 </pre>
2516 </div>
2517
2518 <p>Inline asms with side effects not visible in the constraint list must be
2519    marked as having side effects.  This is done through the use of the
2520    '<tt>sideeffect</tt>' keyword, like so:</p>
2521
2522 <div class="doc_code">
2523 <pre>
2524 call void asm sideeffect "eieio", ""()
2525 </pre>
2526 </div>
2527
2528 <p>In some cases inline asms will contain code that will not work unless the
2529    stack is aligned in some way, such as calls or SSE instructions on x86,
2530    yet will not contain code that does that alignment within the asm.
2531    The compiler should make conservative assumptions about what the asm might
2532    contain and should generate its usual stack alignment code in the prologue
2533    if the '<tt>alignstack</tt>' keyword is present:</p>
2534
2535 <div class="doc_code">
2536 <pre>
2537 call void asm alignstack "eieio", ""()
2538 </pre>
2539 </div>
2540
2541 <p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come
2542    first.</p>
2543
2544 <p>TODO: The format of the asm and constraints string still need to be
2545    documented here.  Constraints on what can be done (e.g. duplication, moving,
2546    etc need to be documented).  This is probably best done by reference to
2547    another document that covers inline asm from a holistic perspective.</p>
2548 </div>
2549
2550 <div class="doc_subsubsection">
2551 <a name="inlineasm_md">Inline Asm Metadata</a>
2552 </div>
2553
2554 <div class="doc_text">
2555
2556 <p>The call instructions that wrap inline asm nodes may have a "!srcloc" MDNode
2557    attached to it that contains a constant integer.  If present, the code
2558    generator will use the integer as the location cookie value when report
2559    errors through the LLVMContext error reporting mechanisms.  This allows a
2560    front-end to corrolate backend errors that occur with inline asm back to the
2561    source code that produced it.  For example:</p>
2562
2563 <div class="doc_code">
2564 <pre>
2565 call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b>
2566 ...
2567 !42 = !{ i32 1234567 }
2568 </pre>
2569 </div>
2570
2571 <p>It is up to the front-end to make sense of the magic numbers it places in the
2572    IR.</p>
2573
2574 </div>
2575
2576 <!-- ======================================================================= -->
2577 <div class="doc_subsection"><a name="metadata">Metadata Nodes and Metadata
2578   Strings</a>
2579 </div>
2580
2581 <div class="doc_text">
2582
2583 <p>LLVM IR allows metadata to be attached to instructions in the program that
2584    can convey extra information about the code to the optimizers and code
2585    generator.  One example application of metadata is source-level debug
2586    information.  There are two metadata primitives: strings and nodes. All
2587    metadata has the <tt>metadata</tt> type and is identified in syntax by a
2588    preceding exclamation point ('<tt>!</tt>').</p>
2589
2590 <p>A metadata string is a string surrounded by double quotes.  It can contain
2591    any character by escaping non-printable characters with "\xx" where "xx" is
2592    the two digit hex code.  For example: "<tt>!"test\00"</tt>".</p>
2593
2594 <p>Metadata nodes are represented with notation similar to structure constants
2595    (a comma separated list of elements, surrounded by braces and preceded by an
2596    exclamation point).  For example: "<tt>!{ metadata !"test\00", i32
2597    10}</tt>".  Metadata nodes can have any values as their operand.</p>
2598
2599 <p>A <a href="#namedmetadatastructure">named metadata</a> is a collection of
2600    metadata nodes, which can be looked up in the module symbol table. For
2601    example: "<tt>!foo =  metadata !{!4, !3}</tt>".
2602
2603 <p>Metadata can be used as function arguments. Here <tt>llvm.dbg.value</tt>
2604    function is using two metadata arguments.
2605
2606    <div class="doc_code">
2607      <pre>
2608        call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
2609      </pre>
2610    </div></p>
2611
2612 <p>Metadata can be attached with an instruction. Here metadata <tt>!21</tt> is
2613    attached with <tt>add</tt> instruction using <tt>!dbg</tt> identifier.
2614
2615   <div class="doc_code">
2616     <pre>
2617       %indvar.next = add i64 %indvar, 1, !dbg !21
2618     </pre>
2619   </div></p>
2620 </div>
2621
2622
2623 <!-- *********************************************************************** -->
2624 <div class="doc_section">
2625   <a name="intrinsic_globals">Intrinsic Global Variables</a>
2626 </div>
2627 <!-- *********************************************************************** -->
2628
2629 <p>LLVM has a number of "magic" global variables that contain data that affect
2630 code generation or other IR semantics.  These are documented here.  All globals
2631 of this sort should have a section specified as "<tt>llvm.metadata</tt>".  This
2632 section and all globals that start with "<tt>llvm.</tt>" are reserved for use
2633 by LLVM.</p>
2634
2635 <!-- ======================================================================= -->
2636 <div class="doc_subsection">
2637 <a name="intg_used">The '<tt>llvm.used</tt>' Global Variable</a>
2638 </div>
2639
2640 <div class="doc_text">
2641
2642 <p>The <tt>@llvm.used</tt> global is an array with i8* element type which has <a
2643 href="#linkage_appending">appending linkage</a>.  This array contains a list of
2644 pointers to global variables and functions which may optionally have a pointer
2645 cast formed of bitcast or getelementptr.  For example, a legal use of it is:</p>
2646
2647 <pre>
2648   @X = global i8 4
2649   @Y = global i32 123
2650
2651   @llvm.used = appending global [2 x i8*] [
2652      i8* @X,
2653      i8* bitcast (i32* @Y to i8*)
2654   ], section "llvm.metadata"
2655 </pre>
2656
2657 <p>If a global variable appears in the <tt>@llvm.used</tt> list, then the
2658 compiler, assembler, and linker are required to treat the symbol as if there is
2659 a reference to the global that it cannot see.  For example, if a variable has
2660 internal linkage and no references other than that from the <tt>@llvm.used</tt>
2661 list, it cannot be deleted.  This is commonly used to represent references from
2662 inline asms and other things the compiler cannot "see", and corresponds to
2663 "attribute((used))" in GNU C.</p>
2664
2665 <p>On some targets, the code generator must emit a directive to the assembler or
2666 object file to prevent the assembler and linker from molesting the symbol.</p>
2667
2668 </div>
2669
2670 <!-- ======================================================================= -->
2671 <div class="doc_subsection">
2672 <a name="intg_compiler_used">The '<tt>llvm.compiler.used</tt>' Global Variable</a>
2673 </div>
2674
2675 <div class="doc_text">
2676
2677 <p>The <tt>@llvm.compiler.used</tt> directive is the same as the
2678 <tt>@llvm.used</tt> directive, except that it only prevents the compiler from
2679 touching the symbol.  On targets that support it, this allows an intelligent
2680 linker to optimize references to the symbol without being impeded as it would be
2681 by <tt>@llvm.used</tt>.</p>
2682
2683 <p>This is a rare construct that should only be used in rare circumstances, and
2684 should not be exposed to source languages.</p>
2685
2686 </div>
2687
2688 <!-- ======================================================================= -->
2689 <div class="doc_subsection">
2690 <a name="intg_global_ctors">The '<tt>llvm.global_ctors</tt>' Global Variable</a>
2691 </div>
2692
2693 <div class="doc_text">
2694
2695 <p>TODO: Describe this.</p>
2696
2697 </div>
2698
2699 <!-- ======================================================================= -->
2700 <div class="doc_subsection">
2701 <a name="intg_global_dtors">The '<tt>llvm.global_dtors</tt>' Global Variable</a>
2702 </div>
2703
2704 <div class="doc_text">
2705
2706 <p>TODO: Describe this.</p>
2707
2708 </div>
2709
2710
2711 <!-- *********************************************************************** -->
2712 <div class="doc_section"> <a name="instref">Instruction Reference</a> </div>
2713 <!-- *********************************************************************** -->
2714
2715 <div class="doc_text">
2716
2717 <p>The LLVM instruction set consists of several different classifications of
2718    instructions: <a href="#terminators">terminator
2719    instructions</a>, <a href="#binaryops">binary instructions</a>,
2720    <a href="#bitwiseops">bitwise binary instructions</a>,
2721    <a href="#memoryops">memory instructions</a>, and
2722    <a href="#otherops">other instructions</a>.</p>
2723
2724 </div>
2725
2726 <!-- ======================================================================= -->
2727 <div class="doc_subsection"> <a name="terminators">Terminator
2728 Instructions</a> </div>
2729
2730 <div class="doc_text">
2731
2732 <p>As mentioned <a href="#functionstructure">previously</a>, every basic block
2733    in a program ends with a "Terminator" instruction, which indicates which
2734    block should be executed after the current block is finished. These
2735    terminator instructions typically yield a '<tt>void</tt>' value: they produce
2736    control flow, not values (the one exception being the
2737    '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
2738
2739 <p>There are seven different terminator instructions: the
2740    '<a href="#i_ret"><tt>ret</tt></a>' instruction, the
2741    '<a href="#i_br"><tt>br</tt></a>' instruction, the
2742    '<a href="#i_switch"><tt>switch</tt></a>' instruction, the
2743    '<a href="#i_indirectbr">'<tt>indirectbr</tt></a>' Instruction, the
2744    '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the
2745    '<a href="#i_unwind"><tt>unwind</tt></a>' instruction, and the
2746    '<a href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p>
2747
2748 </div>
2749
2750 <!-- _______________________________________________________________________ -->
2751 <div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>'
2752 Instruction</a> </div>
2753
2754 <div class="doc_text">
2755
2756 <h5>Syntax:</h5>
2757 <pre>
2758   ret &lt;type&gt; &lt;value&gt;       <i>; Return a value from a non-void function</i>
2759   ret void                 <i>; Return from void function</i>
2760 </pre>
2761
2762 <h5>Overview:</h5>
2763 <p>The '<tt>ret</tt>' instruction is used to return control flow (and optionally
2764    a value) from a function back to the caller.</p>
2765
2766 <p>There are two forms of the '<tt>ret</tt>' instruction: one that returns a
2767    value and then causes control flow, and one that just causes control flow to
2768    occur.</p>
2769
2770 <h5>Arguments:</h5>
2771 <p>The '<tt>ret</tt>' instruction optionally accepts a single argument, the
2772    return value. The type of the return value must be a
2773    '<a href="#t_firstclass">first class</a>' type.</p>
2774
2775 <p>A function is not <a href="#wellformed">well formed</a> if it it has a
2776    non-void return type and contains a '<tt>ret</tt>' instruction with no return
2777    value or a return value with a type that does not match its type, or if it
2778    has a void return type and contains a '<tt>ret</tt>' instruction with a
2779    return value.</p>
2780
2781 <h5>Semantics:</h5>
2782 <p>When the '<tt>ret</tt>' instruction is executed, control flow returns back to
2783    the calling function's context.  If the caller is a
2784    "<a href="#i_call"><tt>call</tt></a>" instruction, execution continues at the
2785    instruction after the call.  If the caller was an
2786    "<a href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at
2787    the beginning of the "normal" destination block.  If the instruction returns
2788    a value, that value shall set the call or invoke instruction's return
2789    value.</p>
2790
2791 <h5>Example:</h5>
2792 <pre>
2793   ret i32 5                       <i>; Return an integer value of 5</i>
2794   ret void                        <i>; Return from a void function</i>
2795   ret { i32, i8 } { i32 4, i8 2 } <i>; Return a struct of values 4 and 2</i>
2796 </pre>
2797
2798 </div>
2799 <!-- _______________________________________________________________________ -->
2800 <div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div>
2801
2802 <div class="doc_text">
2803
2804 <h5>Syntax:</h5>
2805 <pre>
2806   br i1 &lt;cond&gt;, label &lt;iftrue&gt;, label &lt;iffalse&gt;<br>  br label &lt;dest&gt;          <i>; Unconditional branch</i>
2807 </pre>
2808
2809 <h5>Overview:</h5>
2810 <p>The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
2811    different basic block in the current function.  There are two forms of this
2812    instruction, corresponding to a conditional branch and an unconditional
2813    branch.</p>
2814
2815 <h5>Arguments:</h5>
2816 <p>The conditional branch form of the '<tt>br</tt>' instruction takes a single
2817    '<tt>i1</tt>' value and two '<tt>label</tt>' values.  The unconditional form
2818    of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
2819    target.</p>
2820
2821 <h5>Semantics:</h5>
2822 <p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>i1</tt>'
2823    argument is evaluated.  If the value is <tt>true</tt>, control flows to the
2824    '<tt>iftrue</tt>' <tt>label</tt> argument.  If "cond" is <tt>false</tt>,
2825    control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p>
2826
2827 <h5>Example:</h5>
2828 <pre>
2829 Test:
2830   %cond = <a href="#i_icmp">icmp</a> eq i32 %a, %b
2831   br i1 %cond, label %IfEqual, label %IfUnequal
2832 IfEqual:
2833   <a href="#i_ret">ret</a> i32 1
2834 IfUnequal:
2835   <a href="#i_ret">ret</a> i32 0
2836 </pre>
2837
2838 </div>
2839
2840 <!-- _______________________________________________________________________ -->
2841 <div class="doc_subsubsection">
2842    <a name="i_switch">'<tt>switch</tt>' Instruction</a>
2843 </div>
2844
2845 <div class="doc_text">
2846
2847 <h5>Syntax:</h5>
2848 <pre>
2849   switch &lt;intty&gt; &lt;value&gt;, label &lt;defaultdest&gt; [ &lt;intty&gt; &lt;val&gt;, label &lt;dest&gt; ... ]
2850 </pre>
2851
2852 <h5>Overview:</h5>
2853 <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
2854    several different places.  It is a generalization of the '<tt>br</tt>'
2855    instruction, allowing a branch to occur to one of many possible
2856    destinations.</p>
2857
2858 <h5>Arguments:</h5>
2859 <p>The '<tt>switch</tt>' instruction uses three parameters: an integer
2860    comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination,
2861    and an array of pairs of comparison value constants and '<tt>label</tt>'s.
2862    The table is not allowed to contain duplicate constant entries.</p>
2863
2864 <h5>Semantics:</h5>
2865 <p>The <tt>switch</tt> instruction specifies a table of values and
2866    destinations. When the '<tt>switch</tt>' instruction is executed, this table
2867    is searched for the given value.  If the value is found, control flow is
2868    transferred to the corresponding destination; otherwise, control flow is
2869    transferred to the default destination.</p>
2870
2871 <h5>Implementation:</h5>
2872 <p>Depending on properties of the target machine and the particular
2873    <tt>switch</tt> instruction, this instruction may be code generated in
2874    different ways.  For example, it could be generated as a series of chained
2875    conditional branches or with a lookup table.</p>
2876
2877 <h5>Example:</h5>
2878 <pre>
2879  <i>; Emulate a conditional br instruction</i>
2880  %Val = <a href="#i_zext">zext</a> i1 %value to i32
2881  switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
2882
2883  <i>; Emulate an unconditional br instruction</i>
2884  switch i32 0, label %dest [ ]
2885
2886  <i>; Implement a jump table:</i>
2887  switch i32 %val, label %otherwise [ i32 0, label %onzero
2888                                      i32 1, label %onone
2889                                      i32 2, label %ontwo ]
2890 </pre>
2891
2892 </div>
2893
2894
2895 <!-- _______________________________________________________________________ -->
2896 <div class="doc_subsubsection">
2897    <a name="i_indirectbr">'<tt>indirectbr</tt>' Instruction</a>
2898 </div>
2899
2900 <div class="doc_text">
2901
2902 <h5>Syntax:</h5>
2903 <pre>
2904   indirectbr &lt;somety&gt;* &lt;address&gt;, [ label &lt;dest1&gt;, label &lt;dest2&gt;, ... ]
2905 </pre>
2906
2907 <h5>Overview:</h5>
2908
2909 <p>The '<tt>indirectbr</tt>' instruction implements an indirect branch to a label
2910    within the current function, whose address is specified by
2911    "<tt>address</tt>".  Address must be derived from a <a
2912    href="#blockaddress">blockaddress</a> constant.</p>
2913
2914 <h5>Arguments:</h5>
2915
2916 <p>The '<tt>address</tt>' argument is the address of the label to jump to.  The
2917    rest of the arguments indicate the full set of possible destinations that the
2918    address may point to.  Blocks are allowed to occur multiple times in the
2919    destination list, though this isn't particularly useful.</p>
2920
2921 <p>This destination list is required so that dataflow analysis has an accurate
2922    understanding of the CFG.</p>
2923
2924 <h5>Semantics:</h5>
2925
2926 <p>Control transfers to the block specified in the address argument.  All
2927    possible destination blocks must be listed in the label list, otherwise this
2928    instruction has undefined behavior.  This implies that jumps to labels
2929    defined in other functions have undefined behavior as well.</p>
2930
2931 <h5>Implementation:</h5>
2932
2933 <p>This is typically implemented with a jump through a register.</p>
2934
2935 <h5>Example:</h5>
2936 <pre>
2937  indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
2938 </pre>
2939
2940 </div>
2941
2942
2943 <!-- _______________________________________________________________________ -->
2944 <div class="doc_subsubsection">
2945   <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
2946 </div>
2947
2948 <div class="doc_text">
2949
2950 <h5>Syntax:</h5>
2951 <pre>
2952   &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>]
2953                 to label &lt;normal label&gt; unwind label &lt;exception label&gt;
2954 </pre>
2955
2956 <h5>Overview:</h5>
2957 <p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified
2958    function, with the possibility of control flow transfer to either the
2959    '<tt>normal</tt>' label or the '<tt>exception</tt>' label.  If the callee
2960    function returns with the "<tt><a href="#i_ret">ret</a></tt>" instruction,
2961    control flow will return to the "normal" label.  If the callee (or any
2962    indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>"
2963    instruction, control is interrupted and continued at the dynamically nearest
2964    "exception" label.</p>
2965
2966 <h5>Arguments:</h5>
2967 <p>This instruction requires several arguments:</p>
2968
2969 <ol>
2970   <li>The optional "cconv" marker indicates which <a href="#callingconv">calling
2971       convention</a> the call should use.  If none is specified, the call
2972       defaults to using C calling conventions.</li>
2973
2974   <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
2975       return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
2976       '<tt>inreg</tt>' attributes are valid here.</li>
2977
2978   <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
2979       function value being invoked.  In most cases, this is a direct function
2980       invocation, but indirect <tt>invoke</tt>s are just as possible, branching
2981       off an arbitrary pointer to function value.</li>
2982
2983   <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
2984       function to be invoked. </li>
2985
2986   <li>'<tt>function args</tt>': argument list whose types match the function
2987       signature argument types and parameter attributes. All arguments must be
2988       of <a href="#t_firstclass">first class</a> type. If the function
2989       signature indicates the function accepts a variable number of arguments,
2990       the extra arguments can be specified.</li>
2991
2992   <li>'<tt>normal label</tt>': the label reached when the called function
2993       executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
2994
2995   <li>'<tt>exception label</tt>': the label reached when a callee returns with
2996       the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li>
2997
2998   <li>The optional <a href="#fnattrs">function attributes</a> list. Only
2999       '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
3000       '<tt>readnone</tt>' attributes are valid here.</li>
3001 </ol>
3002
3003 <h5>Semantics:</h5>
3004 <p>This instruction is designed to operate as a standard
3005    '<tt><a href="#i_call">call</a></tt>' instruction in most regards.  The
3006    primary difference is that it establishes an association with a label, which
3007    is used by the runtime library to unwind the stack.</p>
3008
3009 <p>This instruction is used in languages with destructors to ensure that proper
3010    cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
3011    exception.  Additionally, this is important for implementation of
3012    '<tt>catch</tt>' clauses in high-level languages that support them.</p>
3013
3014 <p>For the purposes of the SSA form, the definition of the value returned by the
3015    '<tt>invoke</tt>' instruction is deemed to occur on the edge from the current
3016    block to the "normal" label. If the callee unwinds then no return value is
3017    available.</p>
3018
3019 <p>Note that the code generator does not yet completely support unwind, and
3020 that the invoke/unwind semantics are likely to change in future versions.</p>
3021
3022 <h5>Example:</h5>
3023 <pre>
3024   %retval = invoke i32 @Test(i32 15) to label %Continue
3025               unwind label %TestCleanup              <i>; {i32}:retval set</i>
3026   %retval = invoke <a href="#callingconv">coldcc</a> i32 %Testfnptr(i32 15) to label %Continue
3027               unwind label %TestCleanup              <i>; {i32}:retval set</i>
3028 </pre>
3029
3030 </div>
3031
3032 <!-- _______________________________________________________________________ -->
3033
3034 <div class="doc_subsubsection"> <a name="i_unwind">'<tt>unwind</tt>'
3035 Instruction</a> </div>
3036
3037 <div class="doc_text">
3038
3039 <h5>Syntax:</h5>
3040 <pre>
3041   unwind
3042 </pre>
3043
3044 <h5>Overview:</h5>
3045 <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow
3046    at the first callee in the dynamic call stack which used
3047    an <a href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call.
3048    This is primarily used to implement exception handling.</p>
3049
3050 <h5>Semantics:</h5>
3051 <p>The '<tt>unwind</tt>' instruction causes execution of the current function to
3052    immediately halt.  The dynamic call stack is then searched for the
3053    first <a href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack.
3054    Once found, execution continues at the "exceptional" destination block
3055    specified by the <tt>invoke</tt> instruction.  If there is no <tt>invoke</tt>
3056    instruction in the dynamic call chain, undefined behavior results.</p>
3057
3058 <p>Note that the code generator does not yet completely support unwind, and
3059 that the invoke/unwind semantics are likely to change in future versions.</p>
3060
3061 </div>
3062
3063 <!-- _______________________________________________________________________ -->
3064
3065 <div class="doc_subsubsection"> <a name="i_unreachable">'<tt>unreachable</tt>'
3066 Instruction</a> </div>
3067
3068 <div class="doc_text">
3069
3070 <h5>Syntax:</h5>
3071 <pre>
3072   unreachable
3073 </pre>
3074
3075 <h5>Overview:</h5>
3076 <p>The '<tt>unreachable</tt>' instruction has no defined semantics.  This
3077    instruction is used to inform the optimizer that a particular portion of the
3078    code is not reachable.  This can be used to indicate that the code after a
3079    no-return function cannot be reached, and other facts.</p>
3080
3081 <h5>Semantics:</h5>
3082 <p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p>
3083
3084 </div>
3085
3086 <!-- ======================================================================= -->
3087 <div class="doc_subsection"> <a name="binaryops">Binary Operations</a> </div>
3088
3089 <div class="doc_text">
3090
3091 <p>Binary operators are used to do most of the computation in a program.  They
3092    require two operands of the same type, execute an operation on them, and
3093    produce a single value.  The operands might represent multiple data, as is
3094    the case with the <a href="#t_vector">vector</a> data type.  The result value
3095    has the same type as its operands.</p>
3096
3097 <p>There are several different binary operators:</p>
3098
3099 </div>
3100
3101 <!-- _______________________________________________________________________ -->
3102 <div class="doc_subsubsection">
3103   <a name="i_add">'<tt>add</tt>' Instruction</a>
3104 </div>
3105
3106 <div class="doc_text">
3107
3108 <h5>Syntax:</h5>
3109 <pre>
3110   &lt;result&gt; = add &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;          <i>; yields {ty}:result</i>
3111   &lt;result&gt; = add nuw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3112   &lt;result&gt; = add nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3113   &lt;result&gt; = add nuw nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;  <i>; yields {ty}:result</i>
3114 </pre>
3115
3116 <h5>Overview:</h5>
3117 <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
3118
3119 <h5>Arguments:</h5>
3120 <p>The two arguments to the '<tt>add</tt>' instruction must
3121    be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
3122    integer values. Both arguments must have identical types.</p>
3123
3124 <h5>Semantics:</h5>
3125 <p>The value produced is the integer sum of the two operands.</p>
3126
3127 <p>If the sum has unsigned overflow, the result returned is the mathematical
3128    result modulo 2<sup>n</sup>, where n is the bit width of the result.</p>
3129
3130 <p>Because LLVM integers use a two's complement representation, this instruction
3131    is appropriate for both signed and unsigned integers.</p>
3132
3133 <p><tt>nuw</tt> and <tt>nsw</tt> stand for &quot;No Unsigned Wrap&quot;
3134    and &quot;No Signed Wrap&quot;, respectively. If the <tt>nuw</tt> and/or
3135    <tt>nsw</tt> keywords are present, the result value of the <tt>add</tt>
3136    is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
3137    respectively, occurs.</p>
3138
3139 <h5>Example:</h5>
3140 <pre>
3141   &lt;result&gt; = add i32 4, %var          <i>; yields {i32}:result = 4 + %var</i>
3142 </pre>
3143
3144 </div>
3145
3146 <!-- _______________________________________________________________________ -->
3147 <div class="doc_subsubsection">
3148   <a name="i_fadd">'<tt>fadd</tt>' Instruction</a>
3149 </div>
3150
3151 <div class="doc_text">
3152
3153 <h5>Syntax:</h5>
3154 <pre>
3155   &lt;result&gt; = fadd &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3156 </pre>
3157
3158 <h5>Overview:</h5>
3159 <p>The '<tt>fadd</tt>' instruction returns the sum of its two operands.</p>
3160
3161 <h5>Arguments:</h5>
3162 <p>The two arguments to the '<tt>fadd</tt>' instruction must be
3163    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3164    floating point values. Both arguments must have identical types.</p>
3165
3166 <h5>Semantics:</h5>
3167 <p>The value produced is the floating point sum of the two operands.</p>
3168
3169 <h5>Example:</h5>
3170 <pre>
3171   &lt;result&gt; = fadd float 4.0, %var          <i>; yields {float}:result = 4.0 + %var</i>
3172 </pre>
3173
3174 </div>
3175
3176 <!-- _______________________________________________________________________ -->
3177 <div class="doc_subsubsection">
3178    <a name="i_sub">'<tt>sub</tt>' Instruction</a>
3179 </div>
3180
3181 <div class="doc_text">
3182
3183 <h5>Syntax:</h5>
3184 <pre>
3185   &lt;result&gt; = sub &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;          <i>; yields {ty}:result</i>
3186   &lt;result&gt; = sub nuw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3187   &lt;result&gt; = sub nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3188   &lt;result&gt; = sub nuw nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;  <i>; yields {ty}:result</i>
3189 </pre>
3190
3191 <h5>Overview:</h5>
3192 <p>The '<tt>sub</tt>' instruction returns the difference of its two
3193    operands.</p>
3194
3195 <p>Note that the '<tt>sub</tt>' instruction is used to represent the
3196    '<tt>neg</tt>' instruction present in most other intermediate
3197    representations.</p>
3198
3199 <h5>Arguments:</h5>
3200 <p>The two arguments to the '<tt>sub</tt>' instruction must
3201    be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
3202    integer values.  Both arguments must have identical types.</p>
3203
3204 <h5>Semantics:</h5>
3205 <p>The value produced is the integer difference of the two operands.</p>
3206
3207 <p>If the difference has unsigned overflow, the result returned is the
3208    mathematical result modulo 2<sup>n</sup>, where n is the bit width of the
3209    result.</p>
3210
3211 <p>Because LLVM integers use a two's complement representation, this instruction
3212    is appropriate for both signed and unsigned integers.</p>
3213
3214 <p><tt>nuw</tt> and <tt>nsw</tt> stand for &quot;No Unsigned Wrap&quot;
3215    and &quot;No Signed Wrap&quot;, respectively. If the <tt>nuw</tt> and/or
3216    <tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt>
3217    is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
3218    respectively, occurs.</p>
3219
3220 <h5>Example:</h5>
3221 <pre>
3222   &lt;result&gt; = sub i32 4, %var          <i>; yields {i32}:result = 4 - %var</i>
3223   &lt;result&gt; = sub i32 0, %val          <i>; yields {i32}:result = -%var</i>
3224 </pre>
3225
3226 </div>
3227
3228 <!-- _______________________________________________________________________ -->
3229 <div class="doc_subsubsection">
3230    <a name="i_fsub">'<tt>fsub</tt>' Instruction</a>
3231 </div>
3232
3233 <div class="doc_text">
3234
3235 <h5>Syntax:</h5>
3236 <pre>
3237   &lt;result&gt; = fsub &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3238 </pre>
3239
3240 <h5>Overview:</h5>
3241 <p>The '<tt>fsub</tt>' instruction returns the difference of its two
3242    operands.</p>
3243
3244 <p>Note that the '<tt>fsub</tt>' instruction is used to represent the
3245    '<tt>fneg</tt>' instruction present in most other intermediate
3246    representations.</p>
3247
3248 <h5>Arguments:</h5>
3249 <p>The two arguments to the '<tt>fsub</tt>' instruction must be
3250    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3251    floating point values.  Both arguments must have identical types.</p>
3252
3253 <h5>Semantics:</h5>
3254 <p>The value produced is the floating point difference of the two operands.</p>
3255
3256 <h5>Example:</h5>
3257 <pre>
3258   &lt;result&gt; = fsub float 4.0, %var           <i>; yields {float}:result = 4.0 - %var</i>
3259   &lt;result&gt; = fsub float -0.0, %val          <i>; yields {float}:result = -%var</i>
3260 </pre>
3261
3262 </div>
3263
3264 <!-- _______________________________________________________________________ -->
3265 <div class="doc_subsubsection">
3266   <a name="i_mul">'<tt>mul</tt>' Instruction</a>
3267 </div>
3268
3269 <div class="doc_text">
3270
3271 <h5>Syntax:</h5>
3272 <pre>
3273   &lt;result&gt; = mul &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;          <i>; yields {ty}:result</i>
3274   &lt;result&gt; = mul nuw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3275   &lt;result&gt; = mul nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3276   &lt;result&gt; = mul nuw nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;  <i>; yields {ty}:result</i>
3277 </pre>
3278
3279 <h5>Overview:</h5>
3280 <p>The '<tt>mul</tt>' instruction returns the product of its two operands.</p>
3281
3282 <h5>Arguments:</h5>
3283 <p>The two arguments to the '<tt>mul</tt>' instruction must
3284    be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
3285    integer values.  Both arguments must have identical types.</p>
3286
3287 <h5>Semantics:</h5>
3288 <p>The value produced is the integer product of the two operands.</p>
3289
3290 <p>If the result of the multiplication has unsigned overflow, the result
3291    returned is the mathematical result modulo 2<sup>n</sup>, where n is the bit
3292    width of the result.</p>
3293
3294 <p>Because LLVM integers use a two's complement representation, and the result
3295    is the same width as the operands, this instruction returns the correct
3296    result for both signed and unsigned integers.  If a full product
3297    (e.g. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands should
3298    be sign-extended or zero-extended as appropriate to the width of the full
3299    product.</p>
3300
3301 <p><tt>nuw</tt> and <tt>nsw</tt> stand for &quot;No Unsigned Wrap&quot;
3302    and &quot;No Signed Wrap&quot;, respectively. If the <tt>nuw</tt> and/or
3303    <tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt>
3304    is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow,
3305    respectively, occurs.</p>
3306
3307 <h5>Example:</h5>
3308 <pre>
3309   &lt;result&gt; = mul i32 4, %var          <i>; yields {i32}:result = 4 * %var</i>
3310 </pre>
3311
3312 </div>
3313
3314 <!-- _______________________________________________________________________ -->
3315 <div class="doc_subsubsection">
3316   <a name="i_fmul">'<tt>fmul</tt>' Instruction</a>
3317 </div>
3318
3319 <div class="doc_text">
3320
3321 <h5>Syntax:</h5>
3322 <pre>
3323   &lt;result&gt; = fmul &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3324 </pre>
3325
3326 <h5>Overview:</h5>
3327 <p>The '<tt>fmul</tt>' instruction returns the product of its two operands.</p>
3328
3329 <h5>Arguments:</h5>
3330 <p>The two arguments to the '<tt>fmul</tt>' instruction must be
3331    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3332    floating point values.  Both arguments must have identical types.</p>
3333
3334 <h5>Semantics:</h5>
3335 <p>The value produced is the floating point product of the two operands.</p>
3336
3337 <h5>Example:</h5>
3338 <pre>
3339   &lt;result&gt; = fmul float 4.0, %var          <i>; yields {float}:result = 4.0 * %var</i>
3340 </pre>
3341
3342 </div>
3343
3344 <!-- _______________________________________________________________________ -->
3345 <div class="doc_subsubsection"> <a name="i_udiv">'<tt>udiv</tt>' Instruction
3346 </a></div>
3347
3348 <div class="doc_text">
3349
3350 <h5>Syntax:</h5>
3351 <pre>
3352   &lt;result&gt; = udiv &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3353 </pre>
3354
3355 <h5>Overview:</h5>
3356 <p>The '<tt>udiv</tt>' instruction returns the quotient of its two operands.</p>
3357
3358 <h5>Arguments:</h5>
3359 <p>The two arguments to the '<tt>udiv</tt>' instruction must be
3360    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3361    values.  Both arguments must have identical types.</p>
3362
3363 <h5>Semantics:</h5>
3364 <p>The value produced is the unsigned integer quotient of the two operands.</p>
3365
3366 <p>Note that unsigned integer division and signed integer division are distinct
3367    operations; for signed integer division, use '<tt>sdiv</tt>'.</p>
3368
3369 <p>Division by zero leads to undefined behavior.</p>
3370
3371 <h5>Example:</h5>
3372 <pre>
3373   &lt;result&gt; = udiv i32 4, %var          <i>; yields {i32}:result = 4 / %var</i>
3374 </pre>
3375
3376 </div>
3377
3378 <!-- _______________________________________________________________________ -->
3379 <div class="doc_subsubsection"> <a name="i_sdiv">'<tt>sdiv</tt>' Instruction
3380 </a> </div>
3381
3382 <div class="doc_text">
3383
3384 <h5>Syntax:</h5>
3385 <pre>
3386   &lt;result&gt; = sdiv &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;         <i>; yields {ty}:result</i>
3387   &lt;result&gt; = sdiv exact &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3388 </pre>
3389
3390 <h5>Overview:</h5>
3391 <p>The '<tt>sdiv</tt>' instruction returns the quotient of its two operands.</p>
3392
3393 <h5>Arguments:</h5>
3394 <p>The two arguments to the '<tt>sdiv</tt>' instruction must be
3395    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3396    values.  Both arguments must have identical types.</p>
3397
3398 <h5>Semantics:</h5>
3399 <p>The value produced is the signed integer quotient of the two operands rounded
3400    towards zero.</p>
3401
3402 <p>Note that signed integer division and unsigned integer division are distinct
3403    operations; for unsigned integer division, use '<tt>udiv</tt>'.</p>
3404
3405 <p>Division by zero leads to undefined behavior. Overflow also leads to
3406    undefined behavior; this is a rare case, but can occur, for example, by doing
3407    a 32-bit division of -2147483648 by -1.</p>
3408
3409 <p>If the <tt>exact</tt> keyword is present, the result value of the
3410    <tt>sdiv</tt> is a <a href="#trapvalues">trap value</a> if the result would
3411    be rounded or if overflow would occur.</p>
3412
3413 <h5>Example:</h5>
3414 <pre>
3415   &lt;result&gt; = sdiv i32 4, %var          <i>; yields {i32}:result = 4 / %var</i>
3416 </pre>
3417
3418 </div>
3419
3420 <!-- _______________________________________________________________________ -->
3421 <div class="doc_subsubsection"> <a name="i_fdiv">'<tt>fdiv</tt>'
3422 Instruction</a> </div>
3423
3424 <div class="doc_text">
3425
3426 <h5>Syntax:</h5>
3427 <pre>
3428   &lt;result&gt; = fdiv &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3429 </pre>
3430
3431 <h5>Overview:</h5>
3432 <p>The '<tt>fdiv</tt>' instruction returns the quotient of its two operands.</p>
3433
3434 <h5>Arguments:</h5>
3435 <p>The two arguments to the '<tt>fdiv</tt>' instruction must be
3436    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3437    floating point values.  Both arguments must have identical types.</p>
3438
3439 <h5>Semantics:</h5>
3440 <p>The value produced is the floating point quotient of the two operands.</p>
3441
3442 <h5>Example:</h5>
3443 <pre>
3444   &lt;result&gt; = fdiv float 4.0, %var          <i>; yields {float}:result = 4.0 / %var</i>
3445 </pre>
3446
3447 </div>
3448
3449 <!-- _______________________________________________________________________ -->
3450 <div class="doc_subsubsection"> <a name="i_urem">'<tt>urem</tt>' Instruction</a>
3451 </div>
3452
3453 <div class="doc_text">
3454
3455 <h5>Syntax:</h5>
3456 <pre>
3457   &lt;result&gt; = urem &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3458 </pre>
3459
3460 <h5>Overview:</h5>
3461 <p>The '<tt>urem</tt>' instruction returns the remainder from the unsigned
3462    division of its two arguments.</p>
3463
3464 <h5>Arguments:</h5>
3465 <p>The two arguments to the '<tt>urem</tt>' instruction must be
3466    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3467    values.  Both arguments must have identical types.</p>
3468
3469 <h5>Semantics:</h5>
3470 <p>This instruction returns the unsigned integer <i>remainder</i> of a division.
3471    This instruction always performs an unsigned division to get the
3472    remainder.</p>
3473
3474 <p>Note that unsigned integer remainder and signed integer remainder are
3475    distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p>
3476
3477 <p>Taking the remainder of a division by zero leads to undefined behavior.</p>
3478
3479 <h5>Example:</h5>
3480 <pre>
3481   &lt;result&gt; = urem i32 4, %var          <i>; yields {i32}:result = 4 % %var</i>
3482 </pre>
3483
3484 </div>
3485
3486 <!-- _______________________________________________________________________ -->
3487 <div class="doc_subsubsection">
3488   <a name="i_srem">'<tt>srem</tt>' Instruction</a>
3489 </div>
3490
3491 <div class="doc_text">
3492
3493 <h5>Syntax:</h5>
3494 <pre>
3495   &lt;result&gt; = srem &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3496 </pre>
3497
3498 <h5>Overview:</h5>
3499 <p>The '<tt>srem</tt>' instruction returns the remainder from the signed
3500    division of its two operands. This instruction can also take
3501    <a href="#t_vector">vector</a> versions of the values in which case the
3502    elements must be integers.</p>
3503
3504 <h5>Arguments:</h5>
3505 <p>The two arguments to the '<tt>srem</tt>' instruction must be
3506    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3507    values.  Both arguments must have identical types.</p>
3508
3509 <h5>Semantics:</h5>
3510 <p>This instruction returns the <i>remainder</i> of a division (where the result
3511    has the same sign as the dividend, <tt>op1</tt>), not the <i>modulo</i>
3512    operator (where the result has the same sign as the divisor, <tt>op2</tt>) of
3513    a value.  For more information about the difference,
3514    see <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
3515    Math Forum</a>. For a table of how this is implemented in various languages,
3516    please see <a href="http://en.wikipedia.org/wiki/Modulo_operation">
3517    Wikipedia: modulo operation</a>.</p>
3518
3519 <p>Note that signed integer remainder and unsigned integer remainder are
3520    distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p>
3521
3522 <p>Taking the remainder of a division by zero leads to undefined behavior.
3523    Overflow also leads to undefined behavior; this is a rare case, but can
3524    occur, for example, by taking the remainder of a 32-bit division of
3525    -2147483648 by -1.  (The remainder doesn't actually overflow, but this rule
3526    lets srem be implemented using instructions that return both the result of
3527    the division and the remainder.)</p>
3528
3529 <h5>Example:</h5>
3530 <pre>
3531   &lt;result&gt; = srem i32 4, %var          <i>; yields {i32}:result = 4 % %var</i>
3532 </pre>
3533
3534 </div>
3535
3536 <!-- _______________________________________________________________________ -->
3537 <div class="doc_subsubsection">
3538   <a name="i_frem">'<tt>frem</tt>' Instruction</a> </div>
3539
3540 <div class="doc_text">
3541
3542 <h5>Syntax:</h5>
3543 <pre>
3544   &lt;result&gt; = frem &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3545 </pre>
3546
3547 <h5>Overview:</h5>
3548 <p>The '<tt>frem</tt>' instruction returns the remainder from the division of
3549    its two operands.</p>
3550
3551 <h5>Arguments:</h5>
3552 <p>The two arguments to the '<tt>frem</tt>' instruction must be
3553    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3554    floating point values.  Both arguments must have identical types.</p>
3555
3556 <h5>Semantics:</h5>
3557 <p>This instruction returns the <i>remainder</i> of a division.  The remainder
3558    has the same sign as the dividend.</p>
3559
3560 <h5>Example:</h5>
3561 <pre>
3562   &lt;result&gt; = frem float 4.0, %var          <i>; yields {float}:result = 4.0 % %var</i>
3563 </pre>
3564
3565 </div>
3566
3567 <!-- ======================================================================= -->
3568 <div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary
3569 Operations</a> </div>
3570
3571 <div class="doc_text">
3572
3573 <p>Bitwise binary operators are used to do various forms of bit-twiddling in a
3574    program.  They are generally very efficient instructions and can commonly be
3575    strength reduced from other instructions.  They require two operands of the
3576    same type, execute an operation on them, and produce a single value.  The
3577    resulting value is the same type as its operands.</p>
3578
3579 </div>
3580
3581 <!-- _______________________________________________________________________ -->
3582 <div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>'
3583 Instruction</a> </div>
3584
3585 <div class="doc_text">
3586
3587 <h5>Syntax:</h5>
3588 <pre>
3589   &lt;result&gt; = shl &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3590 </pre>
3591
3592 <h5>Overview:</h5>
3593 <p>The '<tt>shl</tt>' instruction returns the first operand shifted to the left
3594    a specified number of bits.</p>
3595
3596 <h5>Arguments:</h5>
3597 <p>Both arguments to the '<tt>shl</tt>' instruction must be the
3598     same <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
3599     integer type.  '<tt>op2</tt>' is treated as an unsigned value.</p>
3600
3601 <h5>Semantics:</h5>
3602 <p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod
3603    2<sup>n</sup>, where <tt>n</tt> is the width of the result.  If <tt>op2</tt>
3604    is (statically or dynamically) negative or equal to or larger than the number
3605    of bits in <tt>op1</tt>, the result is undefined.  If the arguments are
3606    vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
3607    shift amount in <tt>op2</tt>.</p>
3608
3609 <h5>Example:</h5>
3610 <pre>
3611   &lt;result&gt; = shl i32 4, %var   <i>; yields {i32}: 4 &lt;&lt; %var</i>
3612   &lt;result&gt; = shl i32 4, 2      <i>; yields {i32}: 16</i>
3613   &lt;result&gt; = shl i32 1, 10     <i>; yields {i32}: 1024</i>
3614   &lt;result&gt; = shl i32 1, 32     <i>; undefined</i>
3615   &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>
3616 </pre>
3617
3618 </div>
3619
3620 <!-- _______________________________________________________________________ -->
3621 <div class="doc_subsubsection"> <a name="i_lshr">'<tt>lshr</tt>'
3622 Instruction</a> </div>
3623
3624 <div class="doc_text">
3625
3626 <h5>Syntax:</h5>
3627 <pre>
3628   &lt;result&gt; = lshr &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3629 </pre>
3630
3631 <h5>Overview:</h5>
3632 <p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first
3633    operand shifted to the right a specified number of bits with zero fill.</p>
3634
3635 <h5>Arguments:</h5>
3636 <p>Both arguments to the '<tt>lshr</tt>' instruction must be the same
3637    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3638    type. '<tt>op2</tt>' is treated as an unsigned value.</p>
3639
3640 <h5>Semantics:</h5>
3641 <p>This instruction always performs a logical shift right operation. The most
3642    significant bits of the result will be filled with zero bits after the shift.
3643    If <tt>op2</tt> is (statically or dynamically) equal to or larger than the
3644    number of bits in <tt>op1</tt>, the result is undefined. If the arguments are
3645    vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
3646    shift amount in <tt>op2</tt>.</p>
3647
3648 <h5>Example:</h5>
3649 <pre>
3650   &lt;result&gt; = lshr i32 4, 1   <i>; yields {i32}:result = 2</i>
3651   &lt;result&gt; = lshr i32 4, 2   <i>; yields {i32}:result = 1</i>
3652   &lt;result&gt; = lshr i8  4, 3   <i>; yields {i8}:result = 0</i>
3653   &lt;result&gt; = lshr i8 -2, 1   <i>; yields {i8}:result = 0x7FFFFFFF </i>
3654   &lt;result&gt; = lshr i32 1, 32  <i>; undefined</i>
3655   &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>
3656 </pre>
3657
3658 </div>
3659
3660 <!-- _______________________________________________________________________ -->
3661 <div class="doc_subsubsection"> <a name="i_ashr">'<tt>ashr</tt>'
3662 Instruction</a> </div>
3663 <div class="doc_text">
3664
3665 <h5>Syntax:</h5>
3666 <pre>
3667   &lt;result&gt; = ashr &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3668 </pre>
3669
3670 <h5>Overview:</h5>
3671 <p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first
3672    operand shifted to the right a specified number of bits with sign
3673    extension.</p>
3674
3675 <h5>Arguments:</h5>
3676 <p>Both arguments to the '<tt>ashr</tt>' instruction must be the same
3677    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3678    type.  '<tt>op2</tt>' is treated as an unsigned value.</p>
3679
3680 <h5>Semantics:</h5>
3681 <p>This instruction always performs an arithmetic shift right operation, The
3682    most significant bits of the result will be filled with the sign bit
3683    of <tt>op1</tt>.  If <tt>op2</tt> is (statically or dynamically) equal to or
3684    larger than the number of bits in <tt>op1</tt>, the result is undefined. If
3685    the arguments are vectors, each vector element of <tt>op1</tt> is shifted by
3686    the corresponding shift amount in <tt>op2</tt>.</p>
3687
3688 <h5>Example:</h5>
3689 <pre>
3690   &lt;result&gt; = ashr i32 4, 1   <i>; yields {i32}:result = 2</i>
3691   &lt;result&gt; = ashr i32 4, 2   <i>; yields {i32}:result = 1</i>
3692   &lt;result&gt; = ashr i8  4, 3   <i>; yields {i8}:result = 0</i>
3693   &lt;result&gt; = ashr i8 -2, 1   <i>; yields {i8}:result = -1</i>
3694   &lt;result&gt; = ashr i32 1, 32  <i>; undefined</i>
3695   &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>
3696 </pre>
3697
3698 </div>
3699
3700 <!-- _______________________________________________________________________ -->
3701 <div class="doc_subsubsection"> <a name="i_and">'<tt>and</tt>'
3702 Instruction</a> </div>
3703
3704 <div class="doc_text">
3705
3706 <h5>Syntax:</h5>
3707 <pre>
3708   &lt;result&gt; = and &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3709 </pre>
3710
3711 <h5>Overview:</h5>
3712 <p>The '<tt>and</tt>' instruction returns the bitwise logical and of its two
3713    operands.</p>
3714
3715 <h5>Arguments:</h5>
3716 <p>The two arguments to the '<tt>and</tt>' instruction must be
3717    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3718    values.  Both arguments must have identical types.</p>
3719
3720 <h5>Semantics:</h5>
3721 <p>The truth table used for the '<tt>and</tt>' instruction is:</p>
3722
3723 <table border="1" cellspacing="0" cellpadding="4">
3724   <tbody>
3725     <tr>
3726       <td>In0</td>
3727       <td>In1</td>
3728       <td>Out</td>
3729     </tr>
3730     <tr>
3731       <td>0</td>
3732       <td>0</td>
3733       <td>0</td>
3734     </tr>
3735     <tr>
3736       <td>0</td>
3737       <td>1</td>
3738       <td>0</td>
3739     </tr>
3740     <tr>
3741       <td>1</td>
3742       <td>0</td>
3743       <td>0</td>
3744     </tr>
3745     <tr>
3746       <td>1</td>
3747       <td>1</td>
3748       <td>1</td>
3749     </tr>
3750   </tbody>
3751 </table>
3752
3753 <h5>Example:</h5>
3754 <pre>
3755   &lt;result&gt; = and i32 4, %var         <i>; yields {i32}:result = 4 &amp; %var</i>
3756   &lt;result&gt; = and i32 15, 40          <i>; yields {i32}:result = 8</i>
3757   &lt;result&gt; = and i32 4, 8            <i>; yields {i32}:result = 0</i>
3758 </pre>
3759 </div>
3760 <!-- _______________________________________________________________________ -->
3761 <div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div>
3762
3763 <div class="doc_text">
3764
3765 <h5>Syntax:</h5>
3766 <pre>
3767   &lt;result&gt; = or &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3768 </pre>
3769
3770 <h5>Overview:</h5>
3771 <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive or of its
3772    two operands.</p>
3773
3774 <h5>Arguments:</h5>
3775 <p>The two arguments to the '<tt>or</tt>' instruction must be
3776    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3777    values.  Both arguments must have identical types.</p>
3778
3779 <h5>Semantics:</h5>
3780 <p>The truth table used for the '<tt>or</tt>' instruction is:</p>
3781
3782 <table border="1" cellspacing="0" cellpadding="4">
3783   <tbody>
3784     <tr>
3785       <td>In0</td>
3786       <td>In1</td>
3787       <td>Out</td>
3788     </tr>
3789     <tr>
3790       <td>0</td>
3791       <td>0</td>
3792       <td>0</td>
3793     </tr>
3794     <tr>
3795       <td>0</td>
3796       <td>1</td>
3797       <td>1</td>
3798     </tr>
3799     <tr>
3800       <td>1</td>
3801       <td>0</td>
3802       <td>1</td>
3803     </tr>
3804     <tr>
3805       <td>1</td>
3806       <td>1</td>
3807       <td>1</td>
3808     </tr>
3809   </tbody>
3810 </table>
3811
3812 <h5>Example:</h5>
3813 <pre>
3814   &lt;result&gt; = or i32 4, %var         <i>; yields {i32}:result = 4 | %var</i>
3815   &lt;result&gt; = or i32 15, 40          <i>; yields {i32}:result = 47</i>
3816   &lt;result&gt; = or i32 4, 8            <i>; yields {i32}:result = 12</i>
3817 </pre>
3818
3819 </div>
3820
3821 <!-- _______________________________________________________________________ -->
3822 <div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>'
3823 Instruction</a> </div>
3824
3825 <div class="doc_text">
3826
3827 <h5>Syntax:</h5>
3828 <pre>
3829   &lt;result&gt; = xor &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3830 </pre>
3831
3832 <h5>Overview:</h5>
3833 <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of
3834    its two operands.  The <tt>xor</tt> is used to implement the "one's
3835    complement" operation, which is the "~" operator in C.</p>
3836
3837 <h5>Arguments:</h5>
3838 <p>The two arguments to the '<tt>xor</tt>' instruction must be
3839    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3840    values.  Both arguments must have identical types.</p>
3841
3842 <h5>Semantics:</h5>
3843 <p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
3844
3845 <table border="1" cellspacing="0" cellpadding="4">
3846   <tbody>
3847     <tr>
3848       <td>In0</td>
3849       <td>In1</td>
3850       <td>Out</td>
3851     </tr>
3852     <tr>
3853       <td>0</td>
3854       <td>0</td>
3855       <td>0</td>
3856     </tr>
3857     <tr>
3858       <td>0</td>
3859       <td>1</td>
3860       <td>1</td>
3861     </tr>
3862     <tr>
3863       <td>1</td>
3864       <td>0</td>
3865       <td>1</td>
3866     </tr>
3867     <tr>
3868       <td>1</td>
3869       <td>1</td>
3870       <td>0</td>
3871     </tr>
3872   </tbody>
3873 </table>
3874
3875 <h5>Example:</h5>
3876 <pre>
3877   &lt;result&gt; = xor i32 4, %var         <i>; yields {i32}:result = 4 ^ %var</i>
3878   &lt;result&gt; = xor i32 15, 40          <i>; yields {i32}:result = 39</i>
3879   &lt;result&gt; = xor i32 4, 8            <i>; yields {i32}:result = 12</i>
3880   &lt;result&gt; = xor i32 %V, -1          <i>; yields {i32}:result = ~%V</i>
3881 </pre>
3882
3883 </div>
3884
3885 <!-- ======================================================================= -->
3886 <div class="doc_subsection">
3887   <a name="vectorops">Vector Operations</a>
3888 </div>
3889
3890 <div class="doc_text">
3891
3892 <p>LLVM supports several instructions to represent vector operations in a
3893    target-independent manner.  These instructions cover the element-access and
3894    vector-specific operations needed to process vectors effectively.  While LLVM
3895    does directly support these vector operations, many sophisticated algorithms
3896    will want to use target-specific intrinsics to take full advantage of a
3897    specific target.</p>
3898
3899 </div>
3900
3901 <!-- _______________________________________________________________________ -->
3902 <div class="doc_subsubsection">
3903    <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
3904 </div>
3905
3906 <div class="doc_text">
3907
3908 <h5>Syntax:</h5>
3909 <pre>
3910   &lt;result&gt; = extractelement &lt;n x &lt;ty&gt;&gt; &lt;val&gt;, i32 &lt;idx&gt;    <i>; yields &lt;ty&gt;</i>
3911 </pre>
3912
3913 <h5>Overview:</h5>
3914 <p>The '<tt>extractelement</tt>' instruction extracts a single scalar element
3915    from a vector at a specified index.</p>
3916
3917
3918 <h5>Arguments:</h5>
3919 <p>The first operand of an '<tt>extractelement</tt>' instruction is a value
3920    of <a href="#t_vector">vector</a> type.  The second operand is an index
3921    indicating the position from which to extract the element.  The index may be
3922    a variable.</p>
3923
3924 <h5>Semantics:</h5>
3925 <p>The result is a scalar of the same type as the element type of
3926    <tt>val</tt>.  Its value is the value at position <tt>idx</tt> of
3927    <tt>val</tt>.  If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
3928    results are undefined.</p>
3929
3930 <h5>Example:</h5>
3931 <pre>
3932   &lt;result&gt; = extractelement &lt;4 x i32&gt; %vec, i32 0    <i>; yields i32</i>
3933 </pre>
3934
3935 </div>
3936
3937 <!-- _______________________________________________________________________ -->
3938 <div class="doc_subsubsection">
3939    <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
3940 </div>
3941
3942 <div class="doc_text">
3943
3944 <h5>Syntax:</h5>
3945 <pre>
3946   &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>
3947 </pre>
3948
3949 <h5>Overview:</h5>
3950 <p>The '<tt>insertelement</tt>' instruction inserts a scalar element into a
3951    vector at a specified index.</p>
3952
3953 <h5>Arguments:</h5>
3954 <p>The first operand of an '<tt>insertelement</tt>' instruction is a value
3955    of <a href="#t_vector">vector</a> type.  The second operand is a scalar value
3956    whose type must equal the element type of the first operand.  The third
3957    operand is an index indicating the position at which to insert the value.
3958    The index may be a variable.</p>
3959
3960 <h5>Semantics:</h5>
3961 <p>The result is a vector of the same type as <tt>val</tt>.  Its element values
3962    are those of <tt>val</tt> except at position <tt>idx</tt>, where it gets the
3963    value <tt>elt</tt>.  If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
3964    results are undefined.</p>
3965
3966 <h5>Example:</h5>
3967 <pre>
3968   &lt;result&gt; = insertelement &lt;4 x i32&gt; %vec, i32 1, i32 0    <i>; yields &lt;4 x i32&gt;</i>
3969 </pre>
3970
3971 </div>
3972
3973 <!-- _______________________________________________________________________ -->
3974 <div class="doc_subsubsection">
3975    <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
3976 </div>
3977
3978 <div class="doc_text">
3979
3980 <h5>Syntax:</h5>
3981 <pre>
3982   &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>
3983 </pre>
3984
3985 <h5>Overview:</h5>
3986 <p>The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
3987    from two input vectors, returning a vector with the same element type as the
3988    input and length that is the same as the shuffle mask.</p>
3989
3990 <h5>Arguments:</h5>
3991 <p>The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
3992    with types that match each other. The third argument is a shuffle mask whose
3993    element type is always 'i32'.  The result of the instruction is a vector
3994    whose length is the same as the shuffle mask and whose element type is the
3995    same as the element type of the first two operands.</p>
3996
3997 <p>The shuffle mask operand is required to be a constant vector with either
3998    constant integer or undef values.</p>
3999
4000 <h5>Semantics:</h5>
4001 <p>The elements of the two input vectors are numbered from left to right across
4002    both of the vectors.  The shuffle mask operand specifies, for each element of
4003    the result vector, which element of the two input vectors the result element
4004    gets.  The element selector may be undef (meaning "don't care") and the
4005    second operand may be undef if performing a shuffle from only one vector.</p>
4006
4007 <h5>Example:</h5>
4008 <pre>
4009   &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2,
4010                           &lt;4 x i32&gt; &lt;i32 0, i32 4, i32 1, i32 5&gt;  <i>; yields &lt;4 x i32&gt;</i>
4011   &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; undef,
4012                           &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.
4013   &lt;result&gt; = shufflevector &lt;8 x i32&gt; %v1, &lt;8 x i32&gt; undef,
4014                           &lt;4 x i32&gt; &lt;i32 0, i32 1, i32 2, i32 3&gt;  <i>; yields &lt;4 x i32&gt;</i>
4015   &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2,
4016                           &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>
4017 </pre>
4018
4019 </div>
4020
4021 <!-- ======================================================================= -->
4022 <div class="doc_subsection">
4023   <a name="aggregateops">Aggregate Operations</a>
4024 </div>
4025
4026 <div class="doc_text">
4027
4028 <p>LLVM supports several instructions for working with
4029   <a href="#t_aggregate">aggregate</a> values.</p>
4030
4031 </div>
4032
4033 <!-- _______________________________________________________________________ -->
4034 <div class="doc_subsubsection">
4035    <a name="i_extractvalue">'<tt>extractvalue</tt>' Instruction</a>
4036 </div>
4037
4038 <div class="doc_text">
4039
4040 <h5>Syntax:</h5>
4041 <pre>
4042   &lt;result&gt; = extractvalue &lt;aggregate type&gt; &lt;val&gt;, &lt;idx&gt;{, &lt;idx&gt;}*
4043 </pre>
4044
4045 <h5>Overview:</h5>
4046 <p>The '<tt>extractvalue</tt>' instruction extracts the value of a member field
4047    from an <a href="#t_aggregate">aggregate</a> value.</p>
4048
4049 <h5>Arguments:</h5>
4050 <p>The first operand of an '<tt>extractvalue</tt>' instruction is a value
4051    of <a href="#t_struct">struct</a>, <a href="#t_union">union</a>  or
4052    <a href="#t_array">array</a> type.  The operands are constant indices to
4053    specify which value to extract in a similar manner as indices in a
4054    '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
4055
4056 <h5>Semantics:</h5>
4057 <p>The result is the value at the position in the aggregate specified by the
4058    index operands.</p>
4059
4060 <h5>Example:</h5>
4061 <pre>
4062   &lt;result&gt; = extractvalue {i32, float} %agg, 0    <i>; yields i32</i>
4063 </pre>
4064
4065 </div>
4066
4067 <!-- _______________________________________________________________________ -->
4068 <div class="doc_subsubsection">
4069    <a name="i_insertvalue">'<tt>insertvalue</tt>' Instruction</a>
4070 </div>
4071
4072 <div class="doc_text">
4073
4074 <h5>Syntax:</h5>
4075 <pre>
4076   &lt;result&gt; = insertvalue &lt;aggregate type&gt; &lt;val&gt;, &lt;ty&gt; &lt;elt&gt;, &lt;idx&gt;    <i>; yields &lt;aggregate type&gt;</i>
4077 </pre>
4078
4079 <h5>Overview:</h5>
4080 <p>The '<tt>insertvalue</tt>' instruction inserts a value into a member field
4081    in an <a href="#t_aggregate">aggregate</a> value.</p>
4082
4083 <h5>Arguments:</h5>
4084 <p>The first operand of an '<tt>insertvalue</tt>' instruction is a value
4085    of <a href="#t_struct">struct</a>, <a href="#t_union">union</a> or
4086    <a href="#t_array">array</a> type.  The second operand is a first-class
4087    value to insert.  The following operands are constant indices indicating
4088    the position at which to insert the value in a similar manner as indices in a
4089    '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.  The
4090    value to insert must have the same type as the value identified by the
4091    indices.</p>
4092
4093 <h5>Semantics:</h5>
4094 <p>The result is an aggregate of the same type as <tt>val</tt>.  Its value is
4095    that of <tt>val</tt> except that the value at the position specified by the
4096    indices is that of <tt>elt</tt>.</p>
4097
4098 <h5>Example:</h5>
4099 <pre>
4100   %agg1 = insertvalue {i32, float} undef, i32 1, 0         <i>; yields {i32 1, float undef}</i>
4101   %agg2 = insertvalue {i32, float} %agg1, float %val, 1    <i>; yields {i32 1, float %val}</i>
4102 </pre>
4103
4104 </div>
4105
4106
4107 <!-- ======================================================================= -->
4108 <div class="doc_subsection">
4109   <a name="memoryops">Memory Access and Addressing Operations</a>
4110 </div>
4111
4112 <div class="doc_text">
4113
4114 <p>A key design point of an SSA-based representation is how it represents
4115    memory.  In LLVM, no memory locations are in SSA form, which makes things
4116    very simple.  This section describes how to read, write, and allocate
4117    memory in LLVM.</p>
4118
4119 </div>
4120
4121 <!-- _______________________________________________________________________ -->
4122 <div class="doc_subsubsection">
4123   <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
4124 </div>
4125
4126 <div class="doc_text">
4127
4128 <h5>Syntax:</h5>
4129 <pre>
4130   &lt;result&gt; = alloca &lt;type&gt;[, i32 &lt;NumElements&gt;][, align &lt;alignment&gt;]     <i>; yields {type*}:result</i>
4131 </pre>
4132
4133 <h5>Overview:</h5>
4134 <p>The '<tt>alloca</tt>' instruction allocates memory on the stack frame of the
4135    currently executing function, to be automatically released when this function
4136    returns to its caller. The object is always allocated in the generic address
4137    space (address space zero).</p>
4138
4139 <h5>Arguments:</h5>
4140 <p>The '<tt>alloca</tt>' instruction
4141    allocates <tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory on the
4142    runtime stack, returning a pointer of the appropriate type to the program.
4143    If "NumElements" is specified, it is the number of elements allocated,
4144    otherwise "NumElements" is defaulted to be one.  If a constant alignment is
4145    specified, the value result of the allocation is guaranteed to be aligned to
4146    at least that boundary.  If not specified, or if zero, the target can choose
4147    to align the allocation on any convenient boundary compatible with the
4148    type.</p>
4149
4150 <p>'<tt>type</tt>' may be any sized type.</p>
4151
4152 <h5>Semantics:</h5>
4153 <p>Memory is allocated; a pointer is returned.  The operation is undefined if
4154    there is insufficient stack space for the allocation.  '<tt>alloca</tt>'d
4155    memory is automatically released when the function returns.  The
4156    '<tt>alloca</tt>' instruction is commonly used to represent automatic
4157    variables that must have an address available.  When the function returns
4158    (either with the <tt><a href="#i_ret">ret</a></tt>
4159    or <tt><a href="#i_unwind">unwind</a></tt> instructions), the memory is
4160    reclaimed.  Allocating zero bytes is legal, but the result is undefined.</p>
4161
4162 <h5>Example:</h5>
4163 <pre>
4164   %ptr = alloca i32                             <i>; yields {i32*}:ptr</i>
4165   %ptr = alloca i32, i32 4                      <i>; yields {i32*}:ptr</i>
4166   %ptr = alloca i32, i32 4, align 1024          <i>; yields {i32*}:ptr</i>
4167   %ptr = alloca i32, align 1024                 <i>; yields {i32*}:ptr</i>
4168 </pre>
4169
4170 </div>
4171
4172 <!-- _______________________________________________________________________ -->
4173 <div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
4174 Instruction</a> </div>
4175
4176 <div class="doc_text">
4177
4178 <h5>Syntax:</h5>
4179 <pre>
4180   &lt;result&gt; = load &lt;ty&gt;* &lt;pointer&gt;[, align &lt;alignment&gt;][, !nontemporal !&lt;index&gt;]
4181   &lt;result&gt; = volatile load &lt;ty&gt;* &lt;pointer&gt;[, align &lt;alignment&gt;][, !nontemporal !&lt;index&gt;]
4182   !&lt;index&gt; = !{ i32 1 }
4183 </pre>
4184
4185 <h5>Overview:</h5>
4186 <p>The '<tt>load</tt>' instruction is used to read from memory.</p>
4187
4188 <h5>Arguments:</h5>
4189 <p>The argument to the '<tt>load</tt>' instruction specifies the memory address
4190    from which to load.  The pointer must point to
4191    a <a href="#t_firstclass">first class</a> type.  If the <tt>load</tt> is
4192    marked as <tt>volatile</tt>, then the optimizer is not allowed to modify the
4193    number or order of execution of this <tt>load</tt> with other
4194    volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
4195    instructions.</p>
4196
4197 <p>The optional constant <tt>align</tt> argument specifies the alignment of the
4198    operation (that is, the alignment of the memory address). A value of 0 or an
4199    omitted <tt>align</tt> argument means that the operation has the preferential
4200    alignment for the target. It is the responsibility of the code emitter to
4201    ensure that the alignment information is correct. Overestimating the
4202    alignment results in undefined behavior. Underestimating the alignment may
4203    produce less efficient code. An alignment of 1 is always safe.</p>
4204
4205 <p>The optional <tt>!nontemporal</tt> metadata must reference a single
4206    metatadata name &lt;index&gt; corresponding to a metadata node with
4207    one <tt>i32</tt> entry of value 1.  The existence of
4208    the <tt>!nontemporal</tt> metatadata on the instruction tells the optimizer
4209    and code generator that this load is not expected to be reused in the cache.
4210    The code generator may select special instructions to save cache bandwidth,
4211    such as the <tt>MOVNT</tt> instruction on x86.</p>
4212
4213 <h5>Semantics:</h5>
4214 <p>The location of memory pointed to is loaded.  If the value being loaded is of
4215    scalar type then the number of bytes read does not exceed the minimum number
4216    of bytes needed to hold all bits of the type.  For example, loading an
4217    <tt>i24</tt> reads at most three bytes.  When loading a value of a type like
4218    <tt>i20</tt> with a size that is not an integral number of bytes, the result
4219    is undefined if the value was not originally written using a store of the
4220    same type.</p>
4221
4222 <h5>Examples:</h5>
4223 <pre>
4224   %ptr = <a href="#i_alloca">alloca</a> i32                               <i>; yields {i32*}:ptr</i>
4225   <a href="#i_store">store</a> i32 3, i32* %ptr                          <i>; yields {void}</i>
4226   %val = load i32* %ptr                           <i>; yields {i32}:val = i32 3</i>
4227 </pre>
4228
4229 </div>
4230
4231 <!-- _______________________________________________________________________ -->
4232 <div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
4233 Instruction</a> </div>
4234
4235 <div class="doc_text">
4236
4237 <h5>Syntax:</h5>
4238 <pre>
4239   store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;[, align &lt;alignment&gt;][, !nontemporal !<index>]                   <i>; yields {void}</i>
4240   volatile store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;[, align &lt;alignment&gt;][, !nontemporal !<index>]          <i>; yields {void}</i>
4241 </pre>
4242
4243 <h5>Overview:</h5>
4244 <p>The '<tt>store</tt>' instruction is used to write to memory.</p>
4245
4246 <h5>Arguments:</h5>
4247 <p>There are two arguments to the '<tt>store</tt>' instruction: a value to store
4248    and an address at which to store it.  The type of the
4249    '<tt>&lt;pointer&gt;</tt>' operand must be a pointer to
4250    the <a href="#t_firstclass">first class</a> type of the
4251    '<tt>&lt;value&gt;</tt>' operand. If the <tt>store</tt> is marked
4252    as <tt>volatile</tt>, then the optimizer is not allowed to modify the number
4253    or order of execution of this <tt>store</tt> with other
4254    volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
4255    instructions.</p>
4256
4257 <p>The optional constant "align" argument specifies the alignment of the
4258    operation (that is, the alignment of the memory address). A value of 0 or an
4259    omitted "align" argument means that the operation has the preferential
4260    alignment for the target. It is the responsibility of the code emitter to
4261    ensure that the alignment information is correct. Overestimating the
4262    alignment results in an undefined behavior. Underestimating the alignment may
4263    produce less efficient code. An alignment of 1 is always safe.</p>
4264
4265 <p>The optional !nontemporal metadata must reference a single metatadata
4266    name <index> corresponding to a metadata node with one i32 entry of
4267    value 1.  The existence of the !nontemporal metatadata on the
4268    instruction tells the optimizer and code generator that this load is
4269    not expected to be reused in the cache.  The code generator may
4270    select special instructions to save cache bandwidth, such as the
4271    MOVNT instruction on x86.</p>
4272
4273
4274 <h5>Semantics:</h5>
4275 <p>The contents of memory are updated to contain '<tt>&lt;value&gt;</tt>' at the
4276    location specified by the '<tt>&lt;pointer&gt;</tt>' operand.  If
4277    '<tt>&lt;value&gt;</tt>' is of scalar type then the number of bytes written
4278    does not exceed the minimum number of bytes needed to hold all bits of the
4279    type.  For example, storing an <tt>i24</tt> writes at most three bytes.  When
4280    writing a value of a type like <tt>i20</tt> with a size that is not an
4281    integral number of bytes, it is unspecified what happens to the extra bits
4282    that do not belong to the type, but they will typically be overwritten.</p>
4283
4284 <h5>Example:</h5>
4285 <pre>
4286   %ptr = <a href="#i_alloca">alloca</a> i32                               <i>; yields {i32*}:ptr</i>
4287   store i32 3, i32* %ptr                          <i>; yields {void}</i>
4288   %val = <a href="#i_load">load</a> i32* %ptr                           <i>; yields {i32}:val = i32 3</i>
4289 </pre>
4290
4291 </div>
4292
4293 <!-- _______________________________________________________________________ -->
4294 <div class="doc_subsubsection">
4295    <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
4296 </div>
4297
4298 <div class="doc_text">
4299
4300 <h5>Syntax:</h5>
4301 <pre>
4302   &lt;result&gt; = getelementptr &lt;pty&gt;* &lt;ptrval&gt;{, &lt;ty&gt; &lt;idx&gt;}*
4303   &lt;result&gt; = getelementptr inbounds &lt;pty&gt;* &lt;ptrval&gt;{, &lt;ty&gt; &lt;idx&gt;}*
4304 </pre>
4305
4306 <h5>Overview:</h5>
4307 <p>The '<tt>getelementptr</tt>' instruction is used to get the address of a
4308    subelement of an <a href="#t_aggregate">aggregate</a> data structure.
4309    It performs address calculation only and does not access memory.</p>
4310
4311 <h5>Arguments:</h5>
4312 <p>The first argument is always a pointer, and forms the basis of the
4313    calculation. The remaining arguments are indices that indicate which of the
4314    elements of the aggregate object are indexed. The interpretation of each
4315    index is dependent on the type being indexed into. The first index always
4316    indexes the pointer value given as the first argument, the second index
4317    indexes a value of the type pointed to (not necessarily the value directly
4318    pointed to, since the first index can be non-zero), etc. The first type
4319    indexed into must be a pointer value, subsequent types can be arrays,
4320    vectors, structs and unions. Note that subsequent types being indexed into
4321    can never be pointers, since that would require loading the pointer before
4322    continuing calculation.</p>
4323
4324 <p>The type of each index argument depends on the type it is indexing into.
4325    When indexing into a (optionally packed) structure or union, only <tt>i32</tt>
4326    integer <b>constants</b> are allowed.  When indexing into an array, pointer
4327    or vector, integers of any width are allowed, and they are not required to be
4328    constant.</p>
4329
4330 <p>For example, let's consider a C code fragment and how it gets compiled to
4331    LLVM:</p>
4332
4333 <div class="doc_code">
4334 <pre>
4335 struct RT {
4336   char A;
4337   int B[10][20];
4338   char C;
4339 };
4340 struct ST {
4341   int X;
4342   double Y;
4343   struct RT Z;
4344 };
4345
4346 int *foo(struct ST *s) {
4347   return &amp;s[1].Z.B[5][13];
4348 }
4349 </pre>
4350 </div>
4351
4352 <p>The LLVM code generated by the GCC frontend is:</p>
4353
4354 <div class="doc_code">
4355 <pre>
4356 %RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8  }
4357 %ST = <a href="#namedtypes">type</a> { i32, double, %RT }
4358
4359 define i32* @foo(%ST* %s) {
4360 entry:
4361   %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13
4362   ret i32* %reg
4363 }
4364 </pre>
4365 </div>
4366
4367 <h5>Semantics:</h5>
4368 <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
4369    type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT
4370    }</tt>' type, a structure.  The second index indexes into the third element
4371    of the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]],
4372    i8 }</tt>' type, another structure.  The third index indexes into the second
4373    element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an
4374    array.  The two dimensions of the array are subscripted into, yielding an
4375    '<tt>i32</tt>' type.  The '<tt>getelementptr</tt>' instruction returns a
4376    pointer to this element, thus computing a value of '<tt>i32*</tt>' type.</p>
4377
4378 <p>Note that it is perfectly legal to index partially through a structure,
4379    returning a pointer to an inner element.  Because of this, the LLVM code for
4380    the given testcase is equivalent to:</p>
4381
4382 <pre>
4383   define i32* @foo(%ST* %s) {
4384     %t1 = getelementptr %ST* %s, i32 1                        <i>; yields %ST*:%t1</i>
4385     %t2 = getelementptr %ST* %t1, i32 0, i32 2                <i>; yields %RT*:%t2</i>
4386     %t3 = getelementptr %RT* %t2, i32 0, i32 1                <i>; yields [10 x [20 x i32]]*:%t3</i>
4387     %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5  <i>; yields [20 x i32]*:%t4</i>
4388     %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13        <i>; yields i32*:%t5</i>
4389     ret i32* %t5
4390   }
4391 </pre>
4392
4393 <p>If the <tt>inbounds</tt> keyword is present, the result value of the
4394    <tt>getelementptr</tt> is a <a href="#trapvalues">trap value</a> if the
4395    base pointer is not an <i>in bounds</i> address of an allocated object,
4396    or if any of the addresses that would be formed by successive addition of
4397    the offsets implied by the indices to the base address with infinitely
4398    precise arithmetic are not an <i>in bounds</i> address of that allocated
4399    object. The <i>in bounds</i> addresses for an allocated object are all
4400    the addresses that point into the object, plus the address one byte past
4401    the end.</p>
4402
4403 <p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to
4404    the base address with silently-wrapping two's complement arithmetic, and
4405    the result value of the <tt>getelementptr</tt> may be outside the object
4406    pointed to by the base pointer. The result value may not necessarily be
4407    used to access memory though, even if it happens to point into allocated
4408    storage. See the <a href="#pointeraliasing">Pointer Aliasing Rules</a>
4409    section for more information.</p>
4410
4411 <p>The getelementptr instruction is often confusing.  For some more insight into
4412    how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p>
4413
4414 <h5>Example:</h5>
4415 <pre>
4416     <i>; yields [12 x i8]*:aptr</i>
4417     %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1
4418     <i>; yields i8*:vptr</i>
4419     %vptr = getelementptr {i32, &lt;2 x i8&gt;}* %svptr, i64 0, i32 1, i32 1
4420     <i>; yields i8*:eptr</i>
4421     %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1
4422     <i>; yields i32*:iptr</i>
4423     %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0
4424 </pre>
4425
4426 </div>
4427
4428 <!-- ======================================================================= -->
4429 <div class="doc_subsection"> <a name="convertops">Conversion Operations</a>
4430 </div>
4431
4432 <div class="doc_text">
4433
4434 <p>The instructions in this category are the conversion instructions (casting)
4435    which all take a single operand and a type. They perform various bit
4436    conversions on the operand.</p>
4437
4438 </div>
4439
4440 <!-- _______________________________________________________________________ -->
4441 <div class="doc_subsubsection">
4442    <a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
4443 </div>
4444 <div class="doc_text">
4445
4446 <h5>Syntax:</h5>
4447 <pre>
4448   &lt;result&gt; = trunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4449 </pre>
4450
4451 <h5>Overview:</h5>
4452 <p>The '<tt>trunc</tt>' instruction truncates its operand to the
4453    type <tt>ty2</tt>.</p>
4454
4455 <h5>Arguments:</h5>
4456 <p>The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must
4457    be an <a href="#t_integer">integer</a> type, and a type that specifies the
4458    size and type of the result, which must be
4459    an <a href="#t_integer">integer</a> type. The bit size of <tt>value</tt> must
4460    be larger than the bit size of <tt>ty2</tt>. Equal sized types are not
4461    allowed.</p>
4462
4463 <h5>Semantics:</h5>
4464 <p>The '<tt>trunc</tt>' instruction truncates the high order bits
4465    in <tt>value</tt> and converts the remaining bits to <tt>ty2</tt>. Since the
4466    source size must be larger than the destination size, <tt>trunc</tt> cannot
4467    be a <i>no-op cast</i>.  It will always truncate bits.</p>
4468
4469 <h5>Example:</h5>
4470 <pre>
4471   %X = trunc i32 257 to i8              <i>; yields i8:1</i>
4472   %Y = trunc i32 123 to i1              <i>; yields i1:true</i>
4473   %Z = trunc i32 122 to i1              <i>; yields i1:false</i>
4474 </pre>
4475
4476 </div>
4477
4478 <!-- _______________________________________________________________________ -->
4479 <div class="doc_subsubsection">
4480    <a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
4481 </div>
4482 <div class="doc_text">
4483
4484 <h5>Syntax:</h5>
4485 <pre>
4486   &lt;result&gt; = zext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4487 </pre>
4488
4489 <h5>Overview:</h5>
4490 <p>The '<tt>zext</tt>' instruction zero extends its operand to type
4491    <tt>ty2</tt>.</p>
4492
4493
4494 <h5>Arguments:</h5>
4495 <p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of
4496    <a href="#t_integer">integer</a> type, and a type to cast it to, which must
4497    also be of <a href="#t_integer">integer</a> type. The bit size of the
4498    <tt>value</tt> must be smaller than the bit size of the destination type,
4499    <tt>ty2</tt>.</p>
4500
4501 <h5>Semantics:</h5>
4502 <p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero
4503    bits until it reaches the size of the destination type, <tt>ty2</tt>.</p>
4504
4505 <p>When zero extending from i1, the result will always be either 0 or 1.</p>
4506
4507 <h5>Example:</h5>
4508 <pre>
4509   %X = zext i32 257 to i64              <i>; yields i64:257</i>
4510   %Y = zext i1 true to i32              <i>; yields i32:1</i>
4511 </pre>
4512
4513 </div>
4514
4515 <!-- _______________________________________________________________________ -->
4516 <div class="doc_subsubsection">
4517    <a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
4518 </div>
4519 <div class="doc_text">
4520
4521 <h5>Syntax:</h5>
4522 <pre>
4523   &lt;result&gt; = sext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4524 </pre>
4525
4526 <h5>Overview:</h5>
4527 <p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
4528
4529 <h5>Arguments:</h5>
4530 <p>The '<tt>sext</tt>' instruction takes a value to cast, which must be of
4531    <a href="#t_integer">integer</a> type, and a type to cast it to, which must
4532    also be of <a href="#t_integer">integer</a> type.  The bit size of the
4533    <tt>value</tt> must be smaller than the bit size of the destination type,
4534    <tt>ty2</tt>.</p>
4535
4536 <h5>Semantics:</h5>
4537 <p>The '<tt>sext</tt>' instruction performs a sign extension by copying the sign
4538    bit (highest order bit) of the <tt>value</tt> until it reaches the bit size
4539    of the type <tt>ty2</tt>.</p>
4540
4541 <p>When sign extending from i1, the extension always results in -1 or 0.</p>
4542
4543 <h5>Example:</h5>
4544 <pre>
4545   %X = sext i8  -1 to i16              <i>; yields i16   :65535</i>
4546   %Y = sext i1 true to i32             <i>; yields i32:-1</i>
4547 </pre>
4548
4549 </div>
4550
4551 <!-- _______________________________________________________________________ -->
4552 <div class="doc_subsubsection">
4553    <a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
4554 </div>
4555
4556 <div class="doc_text">
4557
4558 <h5>Syntax:</h5>
4559 <pre>
4560   &lt;result&gt; = fptrunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4561 </pre>
4562
4563 <h5>Overview:</h5>
4564 <p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
4565    <tt>ty2</tt>.</p>
4566
4567 <h5>Arguments:</h5>
4568 <p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
4569    point</a> value to cast and a <a href="#t_floating">floating point</a> type
4570    to cast it to. The size of <tt>value</tt> must be larger than the size of
4571    <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
4572    <i>no-op cast</i>.</p>
4573
4574 <h5>Semantics:</h5>
4575 <p>The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger
4576    <a href="#t_floating">floating point</a> type to a smaller
4577    <a href="#t_floating">floating point</a> type.  If the value cannot fit
4578    within the destination type, <tt>ty2</tt>, then the results are
4579    undefined.</p>
4580
4581 <h5>Example:</h5>
4582 <pre>
4583   %X = fptrunc double 123.0 to float         <i>; yields float:123.0</i>
4584   %Y = fptrunc double 1.0E+300 to float      <i>; yields undefined</i>
4585 </pre>
4586
4587 </div>
4588
4589 <!-- _______________________________________________________________________ -->
4590 <div class="doc_subsubsection">
4591    <a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
4592 </div>
4593 <div class="doc_text">
4594
4595 <h5>Syntax:</h5>
4596 <pre>
4597   &lt;result&gt; = fpext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4598 </pre>
4599
4600 <h5>Overview:</h5>
4601 <p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger
4602    floating point value.</p>
4603
4604 <h5>Arguments:</h5>
4605 <p>The '<tt>fpext</tt>' instruction takes a
4606    <a href="#t_floating">floating point</a> <tt>value</tt> to cast, and
4607    a <a href="#t_floating">floating point</a> type to cast it to. The source
4608    type must be smaller than the destination type.</p>
4609
4610 <h5>Semantics:</h5>
4611 <p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller
4612    <a href="#t_floating">floating point</a> type to a larger
4613    <a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be
4614    used to make a <i>no-op cast</i> because it always changes bits. Use
4615    <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p>
4616
4617 <h5>Example:</h5>
4618 <pre>
4619   %X = fpext float 3.1415 to double        <i>; yields double:3.1415</i>
4620   %Y = fpext float 1.0 to float            <i>; yields float:1.0 (no-op)</i>
4621 </pre>
4622
4623 </div>
4624
4625 <!-- _______________________________________________________________________ -->
4626 <div class="doc_subsubsection">
4627    <a name="i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a>
4628 </div>
4629 <div class="doc_text">
4630
4631 <h5>Syntax:</h5>
4632 <pre>
4633   &lt;result&gt; = fptoui &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4634 </pre>
4635
4636 <h5>Overview:</h5>
4637 <p>The '<tt>fptoui</tt>' converts a floating point <tt>value</tt> to its
4638    unsigned integer equivalent of type <tt>ty2</tt>.</p>
4639
4640 <h5>Arguments:</h5>
4641 <p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a
4642    scalar or vector <a href="#t_floating">floating point</a> value, and a type
4643    to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
4644    type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
4645    vector integer type with the same number of elements as <tt>ty</tt></p>
4646
4647 <h5>Semantics:</h5>
4648 <p>The '<tt>fptoui</tt>' instruction converts its
4649    <a href="#t_floating">floating point</a> operand into the nearest (rounding
4650    towards zero) unsigned integer value. If the value cannot fit
4651    in <tt>ty2</tt>, the results are undefined.</p>
4652
4653 <h5>Example:</h5>
4654 <pre>
4655   %X = fptoui double 123.0 to i32      <i>; yields i32:123</i>
4656   %Y = fptoui float 1.0E+300 to i1     <i>; yields undefined:1</i>
4657   %Z = fptoui float 1.04E+17 to i8     <i>; yields undefined:1</i>
4658 </pre>
4659
4660 </div>
4661
4662 <!-- _______________________________________________________________________ -->
4663 <div class="doc_subsubsection">
4664    <a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a>
4665 </div>
4666 <div class="doc_text">
4667
4668 <h5>Syntax:</h5>
4669 <pre>
4670   &lt;result&gt; = fptosi &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4671 </pre>
4672
4673 <h5>Overview:</h5>
4674 <p>The '<tt>fptosi</tt>' instruction converts
4675    <a href="#t_floating">floating point</a> <tt>value</tt> to
4676    type <tt>ty2</tt>.</p>
4677
4678 <h5>Arguments:</h5>
4679 <p>The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a
4680    scalar or vector <a href="#t_floating">floating point</a> value, and a type
4681    to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
4682    type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
4683    vector integer type with the same number of elements as <tt>ty</tt></p>
4684
4685 <h5>Semantics:</h5>
4686 <p>The '<tt>fptosi</tt>' instruction converts its
4687    <a href="#t_floating">floating point</a> operand into the nearest (rounding
4688    towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
4689    the results are undefined.</p>
4690
4691 <h5>Example:</h5>
4692 <pre>
4693   %X = fptosi double -123.0 to i32      <i>; yields i32:-123</i>
4694   %Y = fptosi float 1.0E-247 to i1      <i>; yields undefined:1</i>
4695   %Z = fptosi float 1.04E+17 to i8      <i>; yields undefined:1</i>
4696 </pre>
4697
4698 </div>
4699
4700 <!-- _______________________________________________________________________ -->
4701 <div class="doc_subsubsection">
4702    <a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a>
4703 </div>
4704 <div class="doc_text">
4705
4706 <h5>Syntax:</h5>
4707 <pre>
4708   &lt;result&gt; = uitofp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4709 </pre>
4710
4711 <h5>Overview:</h5>
4712 <p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned
4713    integer and converts that value to the <tt>ty2</tt> type.</p>
4714
4715 <h5>Arguments:</h5>
4716 <p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be a
4717    scalar or vector <a href="#t_integer">integer</a> value, and a type to cast
4718    it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
4719    type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
4720    floating point type with the same number of elements as <tt>ty</tt></p>
4721
4722 <h5>Semantics:</h5>
4723 <p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned
4724    integer quantity and converts it to the corresponding floating point
4725    value. If the value cannot fit in the floating point value, the results are
4726    undefined.</p>
4727
4728 <h5>Example:</h5>
4729 <pre>
4730   %X = uitofp i32 257 to float         <i>; yields float:257.0</i>
4731   %Y = uitofp i8 -1 to double          <i>; yields double:255.0</i>
4732 </pre>
4733
4734 </div>
4735
4736 <!-- _______________________________________________________________________ -->
4737 <div class="doc_subsubsection">
4738    <a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a>
4739 </div>
4740 <div class="doc_text">
4741
4742 <h5>Syntax:</h5>
4743 <pre>
4744   &lt;result&gt; = sitofp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4745 </pre>
4746
4747 <h5>Overview:</h5>
4748 <p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed integer
4749    and converts that value to the <tt>ty2</tt> type.</p>
4750
4751 <h5>Arguments:</h5>
4752 <p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be a
4753    scalar or vector <a href="#t_integer">integer</a> value, and a type to cast
4754    it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
4755    type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
4756    floating point type with the same number of elements as <tt>ty</tt></p>
4757
4758 <h5>Semantics:</h5>
4759 <p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed integer
4760    quantity and converts it to the corresponding floating point value. If the
4761    value cannot fit in the floating point value, the results are undefined.</p>
4762
4763 <h5>Example:</h5>
4764 <pre>
4765   %X = sitofp i32 257 to float         <i>; yields float:257.0</i>
4766   %Y = sitofp i8 -1 to double          <i>; yields double:-1.0</i>
4767 </pre>
4768
4769 </div>
4770
4771 <!-- _______________________________________________________________________ -->
4772 <div class="doc_subsubsection">
4773    <a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a>
4774 </div>
4775 <div class="doc_text">
4776
4777 <h5>Syntax:</h5>
4778 <pre>
4779   &lt;result&gt; = ptrtoint &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4780 </pre>
4781
4782 <h5>Overview:</h5>
4783 <p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to
4784    the integer type <tt>ty2</tt>.</p>
4785
4786 <h5>Arguments:</h5>
4787 <p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which
4788    must be a <a href="#t_pointer">pointer</a> value, and a type to cast it to
4789    <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.</p>
4790
4791 <h5>Semantics:</h5>
4792 <p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type
4793    <tt>ty2</tt> by interpreting the pointer value as an integer and either
4794    truncating or zero extending that value to the size of the integer type. If
4795    <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If
4796    <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they
4797    are the same size, then nothing is done (<i>no-op cast</i>) other than a type
4798    change.</p>
4799
4800 <h5>Example:</h5>
4801 <pre>
4802   %X = ptrtoint i32* %X to i8           <i>; yields truncation on 32-bit architecture</i>
4803   %Y = ptrtoint i32* %x to i64          <i>; yields zero extension on 32-bit architecture</i>
4804 </pre>
4805
4806 </div>
4807
4808 <!-- _______________________________________________________________________ -->
4809 <div class="doc_subsubsection">
4810    <a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a>
4811 </div>
4812 <div class="doc_text">
4813
4814 <h5>Syntax:</h5>
4815 <pre>
4816   &lt;result&gt; = inttoptr &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4817 </pre>
4818
4819 <h5>Overview:</h5>
4820 <p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to a
4821    pointer type, <tt>ty2</tt>.</p>
4822
4823 <h5>Arguments:</h5>
4824 <p>The '<tt>inttoptr</tt>' instruction takes an <a href="#t_integer">integer</a>
4825    value to cast, and a type to cast it to, which must be a
4826    <a href="#t_pointer">pointer</a> type.</p>
4827
4828 <h5>Semantics:</h5>
4829 <p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type
4830    <tt>ty2</tt> by applying either a zero extension or a truncation depending on
4831    the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the
4832    size of a pointer then a truncation is done. If <tt>value</tt> is smaller
4833    than the size of a pointer then a zero extension is done. If they are the
4834    same size, nothing is done (<i>no-op cast</i>).</p>
4835
4836 <h5>Example:</h5>
4837 <pre>
4838   %X = inttoptr i32 255 to i32*          <i>; yields zero extension on 64-bit architecture</i>
4839   %Y = inttoptr i32 255 to i32*          <i>; yields no-op on 32-bit architecture</i>
4840   %Z = inttoptr i64 0 to i32*            <i>; yields truncation on 32-bit architecture</i>
4841 </pre>
4842
4843 </div>
4844
4845 <!-- _______________________________________________________________________ -->
4846 <div class="doc_subsubsection">
4847    <a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a>
4848 </div>
4849 <div class="doc_text">
4850
4851 <h5>Syntax:</h5>
4852 <pre>
4853   &lt;result&gt; = bitcast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4854 </pre>
4855
4856 <h5>Overview:</h5>
4857 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
4858    <tt>ty2</tt> without changing any bits.</p>
4859
4860 <h5>Arguments:</h5>
4861 <p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be a
4862    non-aggregate first class value, and a type to cast it to, which must also be
4863    a non-aggregate <a href="#t_firstclass">first class</a> type. The bit sizes
4864    of <tt>value</tt> and the destination type, <tt>ty2</tt>, must be
4865    identical. If the source type is a pointer, the destination type must also be
4866    a pointer.  This instruction supports bitwise conversion of vectors to
4867    integers and to vectors of other types (as long as they have the same
4868    size).</p>
4869
4870 <h5>Semantics:</h5>
4871 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
4872    <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with
4873    this conversion.  The conversion is done as if the <tt>value</tt> had been
4874    stored to memory and read back as type <tt>ty2</tt>. Pointer types may only
4875    be converted to other pointer types with this instruction. To convert
4876    pointers to other types, use the <a href="#i_inttoptr">inttoptr</a> or
4877    <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p>
4878
4879 <h5>Example:</h5>
4880 <pre>
4881   %X = bitcast i8 255 to i8              <i>; yields i8 :-1</i>
4882   %Y = bitcast i32* %x to sint*          <i>; yields sint*:%x</i>
4883   %Z = bitcast &lt;2 x int&gt; %V to i64;      <i>; yields i64: %V</i>
4884 </pre>
4885
4886 </div>
4887
4888 <!-- ======================================================================= -->
4889 <div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
4890
4891 <div class="doc_text">
4892
4893 <p>The instructions in this category are the "miscellaneous" instructions, which
4894    defy better classification.</p>
4895
4896 </div>
4897
4898 <!-- _______________________________________________________________________ -->
4899 <div class="doc_subsubsection"><a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
4900 </div>
4901
4902 <div class="doc_text">
4903
4904 <h5>Syntax:</h5>
4905 <pre>
4906   &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>
4907 </pre>
4908
4909 <h5>Overview:</h5>
4910 <p>The '<tt>icmp</tt>' instruction returns a boolean value or a vector of
4911    boolean values based on comparison of its two integer, integer vector, or
4912    pointer operands.</p>
4913
4914 <h5>Arguments:</h5>
4915 <p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is
4916    the condition code indicating the kind of comparison to perform. It is not a
4917    value, just a keyword. The possible condition code are:</p>
4918
4919 <ol>
4920   <li><tt>eq</tt>: equal</li>
4921   <li><tt>ne</tt>: not equal </li>
4922   <li><tt>ugt</tt>: unsigned greater than</li>
4923   <li><tt>uge</tt>: unsigned greater or equal</li>
4924   <li><tt>ult</tt>: unsigned less than</li>
4925   <li><tt>ule</tt>: unsigned less or equal</li>
4926   <li><tt>sgt</tt>: signed greater than</li>
4927   <li><tt>sge</tt>: signed greater or equal</li>
4928   <li><tt>slt</tt>: signed less than</li>
4929   <li><tt>sle</tt>: signed less or equal</li>
4930 </ol>
4931
4932 <p>The remaining two arguments must be <a href="#t_integer">integer</a> or
4933    <a href="#t_pointer">pointer</a> or integer <a href="#t_vector">vector</a>
4934    typed.  They must also be identical types.</p>
4935
4936 <h5>Semantics:</h5>
4937 <p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to the
4938    condition code given as <tt>cond</tt>. The comparison performed always yields
4939    either an <a href="#t_integer"><tt>i1</tt></a> or vector of <tt>i1</tt>
4940    result, as follows:</p>
4941
4942 <ol>
4943   <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
4944       <tt>false</tt> otherwise. No sign interpretation is necessary or
4945       performed.</li>
4946
4947   <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
4948       <tt>false</tt> otherwise. No sign interpretation is necessary or
4949       performed.</li>
4950
4951   <li><tt>ugt</tt>: interprets the operands as unsigned values and yields
4952       <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li>
4953
4954   <li><tt>uge</tt>: interprets the operands as unsigned values and yields
4955       <tt>true</tt> if <tt>op1</tt> is greater than or equal
4956       to <tt>op2</tt>.</li>
4957
4958   <li><tt>ult</tt>: interprets the operands as unsigned values and yields
4959       <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li>
4960
4961   <li><tt>ule</tt>: interprets the operands as unsigned values and yields
4962       <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
4963
4964   <li><tt>sgt</tt>: interprets the operands as signed values and yields
4965       <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li>
4966
4967   <li><tt>sge</tt>: interprets the operands as signed values and yields
4968       <tt>true</tt> if <tt>op1</tt> is greater than or equal
4969       to <tt>op2</tt>.</li>
4970
4971   <li><tt>slt</tt>: interprets the operands as signed values and yields
4972       <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li>
4973
4974   <li><tt>sle</tt>: interprets the operands as signed values and yields
4975       <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
4976 </ol>
4977
4978 <p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer
4979    values are compared as if they were integers.</p>
4980
4981 <p>If the operands are integer vectors, then they are compared element by
4982    element. The result is an <tt>i1</tt> vector with the same number of elements
4983    as the values being compared.  Otherwise, the result is an <tt>i1</tt>.</p>
4984
4985 <h5>Example:</h5>
4986 <pre>
4987   &lt;result&gt; = icmp eq i32 4, 5          <i>; yields: result=false</i>
4988   &lt;result&gt; = icmp ne float* %X, %X     <i>; yields: result=false</i>
4989   &lt;result&gt; = icmp ult i16  4, 5        <i>; yields: result=true</i>
4990   &lt;result&gt; = icmp sgt i16  4, 5        <i>; yields: result=false</i>
4991   &lt;result&gt; = icmp ule i16 -4, 5        <i>; yields: result=false</i>
4992   &lt;result&gt; = icmp sge i16  4, 5        <i>; yields: result=false</i>
4993 </pre>
4994
4995 <p>Note that the code generator does not yet support vector types with
4996    the <tt>icmp</tt> instruction.</p>
4997
4998 </div>
4999
5000 <!-- _______________________________________________________________________ -->
5001 <div class="doc_subsubsection"><a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
5002 </div>
5003
5004 <div class="doc_text">
5005
5006 <h5>Syntax:</h5>
5007 <pre>
5008   &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>
5009 </pre>
5010
5011 <h5>Overview:</h5>
5012 <p>The '<tt>fcmp</tt>' instruction returns a boolean value or vector of boolean
5013    values based on comparison of its operands.</p>
5014
5015 <p>If the operands are floating point scalars, then the result type is a boolean
5016 (<a href="#t_integer"><tt>i1</tt></a>).</p>
5017
5018 <p>If the operands are floating point vectors, then the result type is a vector
5019    of boolean with the same number of elements as the operands being
5020    compared.</p>
5021
5022 <h5>Arguments:</h5>
5023 <p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is
5024    the condition code indicating the kind of comparison to perform. It is not a
5025    value, just a keyword. The possible condition code are:</p>
5026
5027 <ol>
5028   <li><tt>false</tt>: no comparison, always returns false</li>
5029   <li><tt>oeq</tt>: ordered and equal</li>
5030   <li><tt>ogt</tt>: ordered and greater than </li>
5031   <li><tt>oge</tt>: ordered and greater than or equal</li>
5032   <li><tt>olt</tt>: ordered and less than </li>
5033   <li><tt>ole</tt>: ordered and less than or equal</li>
5034   <li><tt>one</tt>: ordered and not equal</li>
5035   <li><tt>ord</tt>: ordered (no nans)</li>
5036   <li><tt>ueq</tt>: unordered or equal</li>
5037   <li><tt>ugt</tt>: unordered or greater than </li>
5038   <li><tt>uge</tt>: unordered or greater than or equal</li>
5039   <li><tt>ult</tt>: unordered or less than </li>
5040   <li><tt>ule</tt>: unordered or less than or equal</li>
5041   <li><tt>une</tt>: unordered or not equal</li>
5042   <li><tt>uno</tt>: unordered (either nans)</li>
5043   <li><tt>true</tt>: no comparison, always returns true</li>
5044 </ol>
5045
5046 <p><i>Ordered</i> means that neither operand is a QNAN while
5047    <i>unordered</i> means that either operand may be a QNAN.</p>
5048
5049 <p>Each of <tt>val1</tt> and <tt>val2</tt> arguments must be either
5050    a <a href="#t_floating">floating point</a> type or
5051    a <a href="#t_vector">vector</a> of floating point type.  They must have
5052    identical types.</p>
5053
5054 <h5>Semantics:</h5>
5055 <p>The '<tt>fcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt>
5056    according to the condition code given as <tt>cond</tt>.  If the operands are
5057    vectors, then the vectors are compared element by element.  Each comparison
5058    performed always yields an <a href="#t_integer">i1</a> result, as
5059    follows:</p>
5060
5061 <ol>
5062   <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
5063
5064   <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5065       <tt>op1</tt> is equal to <tt>op2</tt>.</li>
5066
5067   <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5068       <tt>op1</tt> is greater than <tt>op2</tt>.</li>
5069
5070   <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5071       <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
5072
5073   <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5074       <tt>op1</tt> is less than <tt>op2</tt>.</li>
5075
5076   <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5077       <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
5078
5079   <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
5080       <tt>op1</tt> is not equal to <tt>op2</tt>.</li>
5081
5082   <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
5083
5084   <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
5085       <tt>op1</tt> is equal to <tt>op2</tt>.</li>
5086
5087   <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
5088       <tt>op1</tt> is greater than <tt>op2</tt>.</li>
5089
5090   <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
5091       <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
5092
5093   <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
5094       <tt>op1</tt> is less than <tt>op2</tt>.</li>
5095
5096   <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
5097       <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
5098
5099   <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
5100       <tt>op1</tt> is not equal to <tt>op2</tt>.</li>
5101
5102   <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
5103
5104   <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li>
5105 </ol>
5106
5107 <h5>Example:</h5>
5108 <pre>
5109   &lt;result&gt; = fcmp oeq float 4.0, 5.0    <i>; yields: result=false</i>
5110   &lt;result&gt; = fcmp one float 4.0, 5.0    <i>; yields: result=true</i>
5111   &lt;result&gt; = fcmp olt float 4.0, 5.0    <i>; yields: result=true</i>
5112   &lt;result&gt; = fcmp ueq double 1.0, 2.0   <i>; yields: result=false</i>
5113 </pre>
5114
5115 <p>Note that the code generator does not yet support vector types with
5116    the <tt>fcmp</tt> instruction.</p>
5117
5118 </div>
5119
5120 <!-- _______________________________________________________________________ -->
5121 <div class="doc_subsubsection">
5122   <a name="i_phi">'<tt>phi</tt>' Instruction</a>
5123 </div>
5124
5125 <div class="doc_text">
5126
5127 <h5>Syntax:</h5>
5128 <pre>
5129   &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...
5130 </pre>
5131
5132 <h5>Overview:</h5>
5133 <p>The '<tt>phi</tt>' instruction is used to implement the &#966; node in the
5134    SSA graph representing the function.</p>
5135
5136 <h5>Arguments:</h5>
5137 <p>The type of the incoming values is specified with the first type field. After
5138    this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with
5139    one pair for each predecessor basic block of the current block.  Only values
5140    of <a href="#t_firstclass">first class</a> type may be used as the value
5141    arguments to the PHI node.  Only labels may be used as the label
5142    arguments.</p>
5143
5144 <p>There must be no non-phi instructions between the start of a basic block and
5145    the PHI instructions: i.e. PHI instructions must be first in a basic
5146    block.</p>
5147
5148 <p>For the purposes of the SSA form, the use of each incoming value is deemed to
5149    occur on the edge from the corresponding predecessor block to the current
5150    block (but after any definition of an '<tt>invoke</tt>' instruction's return
5151    value on the same edge).</p>
5152
5153 <h5>Semantics:</h5>
5154 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value
5155    specified by the pair corresponding to the predecessor basic block that
5156    executed just prior to the current block.</p>
5157
5158 <h5>Example:</h5>
5159 <pre>
5160 Loop:       ; Infinite loop that counts from 0 on up...
5161   %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
5162   %nextindvar = add i32 %indvar, 1
5163   br label %Loop
5164 </pre>
5165
5166 </div>
5167
5168 <!-- _______________________________________________________________________ -->
5169 <div class="doc_subsubsection">
5170    <a name="i_select">'<tt>select</tt>' Instruction</a>
5171 </div>
5172
5173 <div class="doc_text">
5174
5175 <h5>Syntax:</h5>
5176 <pre>
5177   &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>
5178
5179   <i>selty</i> is either i1 or {&lt;N x i1&gt;}
5180 </pre>
5181
5182 <h5>Overview:</h5>
5183 <p>The '<tt>select</tt>' instruction is used to choose one value based on a
5184    condition, without branching.</p>
5185
5186
5187 <h5>Arguments:</h5>
5188 <p>The '<tt>select</tt>' instruction requires an 'i1' value or a vector of 'i1'
5189    values indicating the condition, and two values of the
5190    same <a href="#t_firstclass">first class</a> type.  If the val1/val2 are
5191    vectors and the condition is a scalar, then entire vectors are selected, not
5192    individual elements.</p>
5193
5194 <h5>Semantics:</h5>
5195 <p>If the condition is an i1 and it evaluates to 1, the instruction returns the
5196    first value argument; otherwise, it returns the second value argument.</p>
5197
5198 <p>If the condition is a vector of i1, then the value arguments must be vectors
5199    of the same size, and the selection is done element by element.</p>
5200
5201 <h5>Example:</h5>
5202 <pre>
5203   %X = select i1 true, i8 17, i8 42          <i>; yields i8:17</i>
5204 </pre>
5205
5206 <p>Note that the code generator does not yet support conditions
5207    with vector type.</p>
5208
5209 </div>
5210
5211 <!-- _______________________________________________________________________ -->
5212 <div class="doc_subsubsection">
5213   <a name="i_call">'<tt>call</tt>' Instruction</a>
5214 </div>
5215
5216 <div class="doc_text">
5217
5218 <h5>Syntax:</h5>
5219 <pre>
5220   &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>]
5221 </pre>
5222
5223 <h5>Overview:</h5>
5224 <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
5225
5226 <h5>Arguments:</h5>
5227 <p>This instruction requires several arguments:</p>
5228
5229 <ol>
5230   <li>The optional "tail" marker indicates that the callee function does not
5231       access any allocas or varargs in the caller.  Note that calls may be
5232       marked "tail" even if they do not occur before
5233       a <a href="#i_ret"><tt>ret</tt></a> instruction.  If the "tail" marker is
5234       present, the function call is eligible for tail call optimization,
5235       but <a href="CodeGenerator.html#tailcallopt">might not in fact be
5236       optimized into a jump</a>.  The code generator may optimize calls marked
5237       "tail" with either 1) automatic <a href="CodeGenerator.html#sibcallopt">
5238       sibling call optimization</a> when the caller and callee have
5239       matching signatures, or 2) forced tail call optimization when the
5240       following extra requirements are met:
5241       <ul>
5242         <li>Caller and callee both have the calling
5243             convention <tt>fastcc</tt>.</li>
5244         <li>The call is in tail position (ret immediately follows call and ret
5245             uses value of call or is void).</li>
5246         <li>Option <tt>-tailcallopt</tt> is enabled,
5247             or <code>llvm::GuaranteedTailCallOpt</code> is <code>true</code>.</li>
5248         <li><a href="CodeGenerator.html#tailcallopt">Platform specific
5249             constraints are met.</a></li>
5250       </ul>
5251   </li>
5252
5253   <li>The optional "cconv" marker indicates which <a href="#callingconv">calling
5254       convention</a> the call should use.  If none is specified, the call
5255       defaults to using C calling conventions.  The calling convention of the
5256       call must match the calling convention of the target function, or else the
5257       behavior is undefined.</li>
5258
5259   <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
5260       return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
5261       '<tt>inreg</tt>' attributes are valid here.</li>
5262
5263   <li>'<tt>ty</tt>': the type of the call instruction itself which is also the
5264       type of the return value.  Functions that return no value are marked
5265       <tt><a href="#t_void">void</a></tt>.</li>
5266
5267   <li>'<tt>fnty</tt>': shall be the signature of the pointer to function value
5268       being invoked.  The argument types must match the types implied by this
5269       signature.  This type can be omitted if the function is not varargs and if
5270       the function type does not return a pointer to a function.</li>
5271
5272   <li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to
5273       be invoked. In most cases, this is a direct function invocation, but
5274       indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer
5275       to function value.</li>
5276
5277   <li>'<tt>function args</tt>': argument list whose types match the function
5278       signature argument types and parameter attributes. All arguments must be
5279       of <a href="#t_firstclass">first class</a> type. If the function
5280       signature indicates the function accepts a variable number of arguments,
5281       the extra arguments can be specified.</li>
5282
5283   <li>The optional <a href="#fnattrs">function attributes</a> list. Only
5284       '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
5285       '<tt>readnone</tt>' attributes are valid here.</li>
5286 </ol>
5287
5288 <h5>Semantics:</h5>
5289 <p>The '<tt>call</tt>' instruction is used to cause control flow to transfer to
5290    a specified function, with its incoming arguments bound to the specified
5291    values. Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called
5292    function, control flow continues with the instruction after the function
5293    call, and the return value of the function is bound to the result
5294    argument.</p>
5295
5296 <h5>Example:</h5>
5297 <pre>
5298   %retval = call i32 @test(i32 %argc)
5299   call i32 (i8 *, ...)* @printf(i8 * %msg, i32 12, i8 42)      <i>; yields i32</i>
5300   %X = tail call i32 @foo()                                    <i>; yields i32</i>
5301   %Y = tail call <a href="#callingconv">fastcc</a> i32 @foo()  <i>; yields i32</i>
5302   call void %foo(i8 97 signext)
5303
5304   %struct.A = type { i32, i8 }
5305   %r = call %struct.A @foo()                        <i>; yields { 32, i8 }</i>
5306   %gr = extractvalue %struct.A %r, 0                <i>; yields i32</i>
5307   %gr1 = extractvalue %struct.A %r, 1               <i>; yields i8</i>
5308   %Z = call void @foo() noreturn                    <i>; indicates that %foo never returns normally</i>
5309   %ZZ = call zeroext i32 @bar()                     <i>; Return value is %zero extended</i>
5310 </pre>
5311
5312 <p>llvm treats calls to some functions with names and arguments that match the
5313 standard C99 library as being the C99 library functions, and may perform
5314 optimizations or generate code for them under that assumption.  This is
5315 something we'd like to change in the future to provide better support for
5316 freestanding environments and non-C-based languages.</p>
5317
5318 </div>
5319
5320 <!-- _______________________________________________________________________ -->
5321 <div class="doc_subsubsection">
5322   <a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
5323 </div>
5324
5325 <div class="doc_text">
5326
5327 <h5>Syntax:</h5>
5328 <pre>
5329   &lt;resultval&gt; = va_arg &lt;va_list*&gt; &lt;arglist&gt;, &lt;argty&gt;
5330 </pre>
5331
5332 <h5>Overview:</h5>
5333 <p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through
5334    the "variable argument" area of a function call.  It is used to implement the
5335    <tt>va_arg</tt> macro in C.</p>
5336
5337 <h5>Arguments:</h5>
5338 <p>This instruction takes a <tt>va_list*</tt> value and the type of the
5339    argument. It returns a value of the specified argument type and increments
5340    the <tt>va_list</tt> to point to the next argument.  The actual type
5341    of <tt>va_list</tt> is target specific.</p>
5342
5343 <h5>Semantics:</h5>
5344 <p>The '<tt>va_arg</tt>' instruction loads an argument of the specified type
5345    from the specified <tt>va_list</tt> and causes the <tt>va_list</tt> to point
5346    to the next argument.  For more information, see the variable argument
5347    handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
5348
5349 <p>It is legal for this instruction to be called in a function which does not
5350    take a variable number of arguments, for example, the <tt>vfprintf</tt>
5351    function.</p>
5352
5353 <p><tt>va_arg</tt> is an LLVM instruction instead of
5354    an <a href="#intrinsics">intrinsic function</a> because it takes a type as an
5355    argument.</p>
5356
5357 <h5>Example:</h5>
5358 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
5359
5360 <p>Note that the code generator does not yet fully support va_arg on many
5361    targets. Also, it does not currently support va_arg with aggregate types on
5362    any target.</p>
5363
5364 </div>
5365
5366 <!-- *********************************************************************** -->
5367 <div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
5368 <!-- *********************************************************************** -->
5369
5370 <div class="doc_text">
5371
5372 <p>LLVM supports the notion of an "intrinsic function".  These functions have
5373    well known names and semantics and are required to follow certain
5374    restrictions.  Overall, these intrinsics represent an extension mechanism for
5375    the LLVM language that does not require changing all of the transformations
5376    in LLVM when adding to the language (or the bitcode reader/writer, the
5377    parser, etc...).</p>
5378
5379 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
5380    prefix is reserved in LLVM for intrinsic names; thus, function names may not
5381    begin with this prefix.  Intrinsic functions must always be external
5382    functions: you cannot define the body of intrinsic functions.  Intrinsic
5383    functions may only be used in call or invoke instructions: it is illegal to
5384    take the address of an intrinsic function.  Additionally, because intrinsic
5385    functions are part of the LLVM language, it is required if any are added that
5386    they be documented here.</p>
5387
5388 <p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents a
5389    family of functions that perform the same operation but on different data
5390    types. Because LLVM can represent over 8 million different integer types,
5391    overloading is used commonly to allow an intrinsic function to operate on any
5392    integer type. One or more of the argument types or the result type can be
5393    overloaded to accept any integer type. Argument types may also be defined as
5394    exactly matching a previous argument's type or the result type. This allows
5395    an intrinsic function which accepts multiple arguments, but needs all of them
5396    to be of the same type, to only be overloaded with respect to a single
5397    argument or the result.</p>
5398
5399 <p>Overloaded intrinsics will have the names of its overloaded argument types
5400    encoded into its function name, each preceded by a period. Only those types
5401    which are overloaded result in a name suffix. Arguments whose type is matched
5402    against another type do not. For example, the <tt>llvm.ctpop</tt> function
5403    can take an integer of any width and returns an integer of exactly the same
5404    integer width. This leads to a family of functions such as
5405    <tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29
5406    %val)</tt>.  Only one type, the return type, is overloaded, and only one type
5407    suffix is required. Because the argument's type is matched against the return
5408    type, it does not require its own name suffix.</p>
5409
5410 <p>To learn how to add an intrinsic function, please see the
5411    <a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p>
5412
5413 </div>
5414
5415 <!-- ======================================================================= -->
5416 <div class="doc_subsection">
5417   <a name="int_varargs">Variable Argument Handling Intrinsics</a>
5418 </div>
5419
5420 <div class="doc_text">
5421
5422 <p>Variable argument support is defined in LLVM with
5423    the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
5424    intrinsic functions.  These functions are related to the similarly named
5425    macros defined in the <tt>&lt;stdarg.h&gt;</tt> header file.</p>
5426
5427 <p>All of these functions operate on arguments that use a target-specific value
5428    type "<tt>va_list</tt>".  The LLVM assembly language reference manual does
5429    not define what this type is, so all transformations should be prepared to
5430    handle these functions regardless of the type used.</p>
5431
5432 <p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a>
5433    instruction and the variable argument handling intrinsic functions are
5434    used.</p>
5435
5436 <div class="doc_code">
5437 <pre>
5438 define i32 @test(i32 %X, ...) {
5439   ; Initialize variable argument processing
5440   %ap = alloca i8*
5441   %ap2 = bitcast i8** %ap to i8*
5442   call void @llvm.va_start(i8* %ap2)
5443
5444   ; Read a single integer argument
5445   %tmp = va_arg i8** %ap, i32
5446
5447   ; Demonstrate usage of llvm.va_copy and llvm.va_end
5448   %aq = alloca i8*
5449   %aq2 = bitcast i8** %aq to i8*
5450   call void @llvm.va_copy(i8* %aq2, i8* %ap2)
5451   call void @llvm.va_end(i8* %aq2)
5452
5453   ; Stop processing of arguments.
5454   call void @llvm.va_end(i8* %ap2)
5455   ret i32 %tmp
5456 }
5457
5458 declare void @llvm.va_start(i8*)
5459 declare void @llvm.va_copy(i8*, i8*)
5460 declare void @llvm.va_end(i8*)
5461 </pre>
5462 </div>
5463
5464 </div>
5465
5466 <!-- _______________________________________________________________________ -->
5467 <div class="doc_subsubsection">
5468   <a name="int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
5469 </div>
5470
5471
5472 <div class="doc_text">
5473
5474 <h5>Syntax:</h5>
5475 <pre>
5476   declare void %llvm.va_start(i8* &lt;arglist&gt;)
5477 </pre>
5478
5479 <h5>Overview:</h5>
5480 <p>The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*&lt;arglist&gt;</tt>
5481    for subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt>.</p>
5482
5483 <h5>Arguments:</h5>
5484 <p>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
5485
5486 <h5>Semantics:</h5>
5487 <p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
5488    macro available in C.  In a target-dependent way, it initializes
5489    the <tt>va_list</tt> element to which the argument points, so that the next
5490    call to <tt>va_arg</tt> will produce the first variable argument passed to
5491    the function.  Unlike the C <tt>va_start</tt> macro, this intrinsic does not
5492    need to know the last argument of the function as the compiler can figure
5493    that out.</p>
5494
5495 </div>
5496
5497 <!-- _______________________________________________________________________ -->
5498 <div class="doc_subsubsection">
5499  <a name="int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
5500 </div>
5501
5502 <div class="doc_text">
5503
5504 <h5>Syntax:</h5>
5505 <pre>
5506   declare void @llvm.va_end(i8* &lt;arglist&gt;)
5507 </pre>
5508
5509 <h5>Overview:</h5>
5510 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*&lt;arglist&gt;</tt>,
5511    which has been initialized previously
5512    with <tt><a href="#int_va_start">llvm.va_start</a></tt>
5513    or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
5514
5515 <h5>Arguments:</h5>
5516 <p>The argument is a pointer to a <tt>va_list</tt> to destroy.</p>
5517
5518 <h5>Semantics:</h5>
5519 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
5520    macro available in C.  In a target-dependent way, it destroys
5521    the <tt>va_list</tt> element to which the argument points.  Calls
5522    to <a href="#int_va_start"><tt>llvm.va_start</tt></a>
5523    and <a href="#int_va_copy"> <tt>llvm.va_copy</tt></a> must be matched exactly
5524    with calls to <tt>llvm.va_end</tt>.</p>
5525
5526 </div>
5527
5528 <!-- _______________________________________________________________________ -->
5529 <div class="doc_subsubsection">
5530   <a name="int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
5531 </div>
5532
5533 <div class="doc_text">
5534
5535 <h5>Syntax:</h5>
5536 <pre>
5537   declare void @llvm.va_copy(i8* &lt;destarglist&gt;, i8* &lt;srcarglist&gt;)
5538 </pre>
5539
5540 <h5>Overview:</h5>
5541 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position
5542    from the source argument list to the destination argument list.</p>
5543
5544 <h5>Arguments:</h5>
5545 <p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
5546    The second argument is a pointer to a <tt>va_list</tt> element to copy
5547    from.</p>
5548
5549 <h5>Semantics:</h5>
5550 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
5551    macro available in C.  In a target-dependent way, it copies the
5552    source <tt>va_list</tt> element into the destination <tt>va_list</tt>
5553    element.  This intrinsic is necessary because
5554    the <tt><a href="#int_va_start"> llvm.va_start</a></tt> intrinsic may be
5555    arbitrarily complex and require, for example, memory allocation.</p>
5556
5557 </div>
5558
5559 <!-- ======================================================================= -->
5560 <div class="doc_subsection">
5561   <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
5562 </div>
5563
5564 <div class="doc_text">
5565
5566 <p>LLVM support for <a href="GarbageCollection.html">Accurate Garbage
5567 Collection</a> (GC) requires the implementation and generation of these
5568 intrinsics. These intrinsics allow identification of <a href="#int_gcroot">GC
5569 roots on the stack</a>, as well as garbage collector implementations that
5570 require <a href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a>
5571 barriers.  Front-ends for type-safe garbage collected languages should generate
5572 these intrinsics to make use of the LLVM garbage collectors.  For more details,
5573 see <a href="GarbageCollection.html">Accurate Garbage Collection with
5574 LLVM</a>.</p>
5575
5576 <p>The garbage collection intrinsics only operate on objects in the generic
5577    address space (address space zero).</p>
5578
5579 </div>
5580
5581 <!-- _______________________________________________________________________ -->
5582 <div class="doc_subsubsection">
5583   <a name="int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
5584 </div>
5585
5586 <div class="doc_text">
5587
5588 <h5>Syntax:</h5>
5589 <pre>
5590   declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
5591 </pre>
5592
5593 <h5>Overview:</h5>
5594 <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
5595    the code generator, and allows some metadata to be associated with it.</p>
5596
5597 <h5>Arguments:</h5>
5598 <p>The first argument specifies the address of a stack object that contains the
5599    root pointer.  The second pointer (which must be either a constant or a
5600    global value address) contains the meta-data to be associated with the
5601    root.</p>
5602
5603 <h5>Semantics:</h5>
5604 <p>At runtime, a call to this intrinsic stores a null pointer into the "ptrloc"
5605    location.  At compile-time, the code generator generates information to allow
5606    the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>'
5607    intrinsic may only be used in a function which <a href="#gc">specifies a GC
5608    algorithm</a>.</p>
5609
5610 </div>
5611
5612 <!-- _______________________________________________________________________ -->
5613 <div class="doc_subsubsection">
5614   <a name="int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
5615 </div>
5616
5617 <div class="doc_text">
5618
5619 <h5>Syntax:</h5>
5620 <pre>
5621   declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
5622 </pre>
5623
5624 <h5>Overview:</h5>
5625 <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
5626    locations, allowing garbage collector implementations that require read
5627    barriers.</p>
5628
5629 <h5>Arguments:</h5>
5630 <p>The second argument is the address to read from, which should be an address
5631    allocated from the garbage collector.  The first object is a pointer to the
5632    start of the referenced object, if needed by the language runtime (otherwise
5633    null).</p>
5634
5635 <h5>Semantics:</h5>
5636 <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
5637    instruction, but may be replaced with substantially more complex code by the
5638    garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic
5639    may only be used in a function which <a href="#gc">specifies a GC
5640    algorithm</a>.</p>
5641
5642 </div>
5643
5644 <!-- _______________________________________________________________________ -->
5645 <div class="doc_subsubsection">
5646   <a name="int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
5647 </div>
5648
5649 <div class="doc_text">
5650
5651 <h5>Syntax:</h5>
5652 <pre>
5653   declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
5654 </pre>
5655
5656 <h5>Overview:</h5>
5657 <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
5658    locations, allowing garbage collector implementations that require write
5659    barriers (such as generational or reference counting collectors).</p>
5660
5661 <h5>Arguments:</h5>
5662 <p>The first argument is the reference to store, the second is the start of the
5663    object to store it to, and the third is the address of the field of Obj to
5664    store to.  If the runtime does not require a pointer to the object, Obj may
5665    be null.</p>
5666
5667 <h5>Semantics:</h5>
5668 <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
5669    instruction, but may be replaced with substantially more complex code by the
5670    garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic
5671    may only be used in a function which <a href="#gc">specifies a GC
5672    algorithm</a>.</p>
5673
5674 </div>
5675
5676 <!-- ======================================================================= -->
5677 <div class="doc_subsection">
5678   <a name="int_codegen">Code Generator Intrinsics</a>
5679 </div>
5680
5681 <div class="doc_text">
5682
5683 <p>These intrinsics are provided by LLVM to expose special features that may
5684    only be implemented with code generator support.</p>
5685
5686 </div>
5687
5688 <!-- _______________________________________________________________________ -->
5689 <div class="doc_subsubsection">
5690   <a name="int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
5691 </div>
5692
5693 <div class="doc_text">
5694
5695 <h5>Syntax:</h5>
5696 <pre>
5697   declare i8  *@llvm.returnaddress(i32 &lt;level&gt;)
5698 </pre>
5699
5700 <h5>Overview:</h5>
5701 <p>The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a
5702    target-specific value indicating the return address of the current function
5703    or one of its callers.</p>
5704
5705 <h5>Arguments:</h5>
5706 <p>The argument to this intrinsic indicates which function to return the address
5707    for.  Zero indicates the calling function, one indicates its caller, etc.
5708    The argument is <b>required</b> to be a constant integer value.</p>
5709
5710 <h5>Semantics:</h5>
5711 <p>The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer
5712    indicating the return address of the specified call frame, or zero if it
5713    cannot be identified.  The value returned by this intrinsic is likely to be
5714    incorrect or 0 for arguments other than zero, so it should only be used for
5715    debugging purposes.</p>
5716
5717 <p>Note that calling this intrinsic does not prevent function inlining or other
5718    aggressive transformations, so the value returned may not be that of the
5719    obvious source-language caller.</p>
5720
5721 </div>
5722
5723 <!-- _______________________________________________________________________ -->
5724 <div class="doc_subsubsection">
5725   <a name="int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
5726 </div>
5727
5728 <div class="doc_text">
5729
5730 <h5>Syntax:</h5>
5731 <pre>
5732   declare i8 *@llvm.frameaddress(i32 &lt;level&gt;)
5733 </pre>
5734
5735 <h5>Overview:</h5>
5736 <p>The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the
5737    target-specific frame pointer value for the specified stack frame.</p>
5738
5739 <h5>Arguments:</h5>
5740 <p>The argument to this intrinsic indicates which function to return the frame
5741    pointer for.  Zero indicates the calling function, one indicates its caller,
5742    etc.  The argument is <b>required</b> to be a constant integer value.</p>
5743
5744 <h5>Semantics:</h5>
5745 <p>The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer
5746    indicating the frame address of the specified call frame, or zero if it
5747    cannot be identified.  The value returned by this intrinsic is likely to be
5748    incorrect or 0 for arguments other than zero, so it should only be used for
5749    debugging purposes.</p>
5750
5751 <p>Note that calling this intrinsic does not prevent function inlining or other
5752    aggressive transformations, so the value returned may not be that of the
5753    obvious source-language caller.</p>
5754
5755 </div>
5756
5757 <!-- _______________________________________________________________________ -->
5758 <div class="doc_subsubsection">
5759   <a name="int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
5760 </div>
5761
5762 <div class="doc_text">
5763
5764 <h5>Syntax:</h5>
5765 <pre>
5766   declare i8 *@llvm.stacksave()
5767 </pre>
5768
5769 <h5>Overview:</h5>
5770 <p>The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state
5771    of the function stack, for use
5772    with <a href="#int_stackrestore"> <tt>llvm.stackrestore</tt></a>.  This is
5773    useful for implementing language features like scoped automatic variable
5774    sized arrays in C99.</p>
5775
5776 <h5>Semantics:</h5>
5777 <p>This intrinsic returns a opaque pointer value that can be passed
5778    to <a href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>.  When
5779    an <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved
5780    from <tt>llvm.stacksave</tt>, it effectively restores the state of the stack
5781    to the state it was in when the <tt>llvm.stacksave</tt> intrinsic executed.
5782    In practice, this pops any <a href="#i_alloca">alloca</a> blocks from the
5783    stack that were allocated after the <tt>llvm.stacksave</tt> was executed.</p>
5784
5785 </div>
5786
5787 <!-- _______________________________________________________________________ -->
5788 <div class="doc_subsubsection">
5789   <a name="int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
5790 </div>
5791
5792 <div class="doc_text">
5793
5794 <h5>Syntax:</h5>
5795 <pre>
5796   declare void @llvm.stackrestore(i8 * %ptr)
5797 </pre>
5798
5799 <h5>Overview:</h5>
5800 <p>The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of
5801    the function stack to the state it was in when the
5802    corresponding <a href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic
5803    executed.  This is useful for implementing language features like scoped
5804    automatic variable sized arrays in C99.</p>
5805
5806 <h5>Semantics:</h5>
5807 <p>See the description
5808    for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>.</p>
5809
5810 </div>
5811
5812 <!-- _______________________________________________________________________ -->
5813 <div class="doc_subsubsection">
5814   <a name="int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
5815 </div>
5816
5817 <div class="doc_text">
5818
5819 <h5>Syntax:</h5>
5820 <pre>
5821   declare void @llvm.prefetch(i8* &lt;address&gt;, i32 &lt;rw&gt;, i32 &lt;locality&gt;)
5822 </pre>
5823
5824 <h5>Overview:</h5>
5825 <p>The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to
5826    insert a prefetch instruction if supported; otherwise, it is a noop.
5827    Prefetches have no effect on the behavior of the program but can change its
5828    performance characteristics.</p>
5829
5830 <h5>Arguments:</h5>
5831 <p><tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the
5832    specifier determining if the fetch should be for a read (0) or write (1),
5833    and <tt>locality</tt> is a temporal locality specifier ranging from (0) - no
5834    locality, to (3) - extremely local keep in cache.  The <tt>rw</tt>
5835    and <tt>locality</tt> arguments must be constant integers.</p>
5836
5837 <h5>Semantics:</h5>
5838 <p>This intrinsic does not modify the behavior of the program.  In particular,
5839    prefetches cannot trap and do not produce a value.  On targets that support
5840    this intrinsic, the prefetch can provide hints to the processor cache for
5841    better performance.</p>
5842
5843 </div>
5844
5845 <!-- _______________________________________________________________________ -->
5846 <div class="doc_subsubsection">
5847   <a name="int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
5848 </div>
5849
5850 <div class="doc_text">
5851
5852 <h5>Syntax:</h5>
5853 <pre>
5854   declare void @llvm.pcmarker(i32 &lt;id&gt;)
5855 </pre>
5856
5857 <h5>Overview:</h5>
5858 <p>The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program
5859    Counter (PC) in a region of code to simulators and other tools.  The method
5860    is target specific, but it is expected that the marker will use exported
5861    symbols to transmit the PC of the marker.  The marker makes no guarantees
5862    that it will remain with any specific instruction after optimizations.  It is
5863    possible that the presence of a marker will inhibit optimizations.  The
5864    intended use is to be inserted after optimizations to allow correlations of
5865    simulation runs.</p>
5866
5867 <h5>Arguments:</h5>
5868 <p><tt>id</tt> is a numerical id identifying the marker.</p>
5869
5870 <h5>Semantics:</h5>
5871 <p>This intrinsic does not modify the behavior of the program.  Backends that do
5872    not support this intrinsic may ignore it.</p>
5873
5874 </div>
5875
5876 <!-- _______________________________________________________________________ -->
5877 <div class="doc_subsubsection">
5878   <a name="int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
5879 </div>
5880
5881 <div class="doc_text">
5882
5883 <h5>Syntax:</h5>
5884 <pre>
5885   declare i64 @llvm.readcyclecounter( )
5886 </pre>
5887
5888 <h5>Overview:</h5>
5889 <p>The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle
5890    counter register (or similar low latency, high accuracy clocks) on those
5891    targets that support it.  On X86, it should map to RDTSC.  On Alpha, it
5892    should map to RPCC.  As the backing counters overflow quickly (on the order
5893    of 9 seconds on alpha), this should only be used for small timings.</p>
5894
5895 <h5>Semantics:</h5>
5896 <p>When directly supported, reading the cycle counter should not modify any
5897    memory.  Implementations are allowed to either return a application specific
5898    value or a system wide value.  On backends without support, this is lowered
5899    to a constant 0.</p>
5900
5901 </div>
5902
5903 <!-- ======================================================================= -->
5904 <div class="doc_subsection">
5905   <a name="int_libc">Standard C Library Intrinsics</a>
5906 </div>
5907
5908 <div class="doc_text">
5909
5910 <p>LLVM provides intrinsics for a few important standard C library functions.
5911    These intrinsics allow source-language front-ends to pass information about
5912    the alignment of the pointer arguments to the code generator, providing
5913    opportunity for more efficient code generation.</p>
5914
5915 </div>
5916
5917 <!-- _______________________________________________________________________ -->
5918 <div class="doc_subsubsection">
5919   <a name="int_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
5920 </div>
5921
5922 <div class="doc_text">
5923
5924 <h5>Syntax:</h5>
5925 <p>This is an overloaded intrinsic. You can use <tt>llvm.memcpy</tt> on any
5926    integer bit width and for different address spaces. Not all targets support
5927    all bit widths however.</p>
5928
5929 <pre>
5930   declare void @llvm.memcpy.p0i8.p0i8.i32(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5931                                           i32 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
5932   declare void @llvm.memcpy.p0i8.p0i8.i64(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5933                                           i64 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
5934 </pre>
5935
5936 <h5>Overview:</h5>
5937 <p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
5938    source location to the destination location.</p>
5939
5940 <p>Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
5941    intrinsics do not return a value, takes extra alignment/isvolatile arguments
5942    and the pointers can be in specified address spaces.</p>
5943
5944 <h5>Arguments:</h5>
5945
5946 <p>The first argument is a pointer to the destination, the second is a pointer
5947    to the source.  The third argument is an integer argument specifying the
5948    number of bytes to copy, the fourth argument is the alignment of the
5949    source and destination locations, and the fifth is a boolean indicating a
5950    volatile access.</p>
5951
5952 <p>If the call to this intrinsic has an alignment value that is not 0 or 1,
5953    then the caller guarantees that both the source and destination pointers are
5954    aligned to that boundary.</p>
5955
5956 <p>Volatile accesses should not be deleted if dead, but the access behavior is
5957    not very cleanly specified and it is unwise to depend on it.</p>
5958
5959 <h5>Semantics:</h5>
5960
5961 <p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
5962    source location to the destination location, which are not allowed to
5963    overlap.  It copies "len" bytes of memory over.  If the argument is known to
5964    be aligned to some boundary, this can be specified as the fourth argument,
5965    otherwise it should be set to 0 or 1.</p>
5966
5967 </div>
5968
5969 <!-- _______________________________________________________________________ -->
5970 <div class="doc_subsubsection">
5971   <a name="int_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
5972 </div>
5973
5974 <div class="doc_text">
5975
5976 <h5>Syntax:</h5>
5977 <p>This is an overloaded intrinsic. You can use llvm.memmove on any integer bit
5978    width and for different address space. Not all targets support all bit
5979    widths however.</p>
5980
5981 <pre>
5982   declare void @llvm.memmove.p0i8.p0i8.i32(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5983                                            i32 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
5984   declare void @llvm.memmove.p0i8.p0i8.i64(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5985                                            i64 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
5986 </pre>
5987
5988 <h5>Overview:</h5>
5989 <p>The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the
5990    source location to the destination location. It is similar to the
5991    '<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to
5992    overlap.</p>
5993
5994 <p>Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
5995    intrinsics do not return a value, takes extra alignment/isvolatile arguments
5996    and the pointers can be in specified address spaces.</p>
5997
5998 <h5>Arguments:</h5>
5999
6000 <p>The first argument is a pointer to the destination, the second is a pointer
6001    to the source.  The third argument is an integer argument specifying the
6002    number of bytes to copy, the fourth argument is the alignment of the
6003    source and destination locations, and the fifth is a boolean indicating a
6004    volatile access.</p>
6005
6006 <p>If the call to this intrinsic has an alignment value that is not 0 or 1,
6007    then the caller guarantees that the source and destination pointers are
6008    aligned to that boundary.</p>
6009
6010 <p>Volatile accesses should not be deleted if dead, but the access behavior is
6011    not very cleanly specified and it is unwise to depend on it.</p>
6012
6013 <h5>Semantics:</h5>
6014
6015 <p>The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the
6016    source location to the destination location, which may overlap.  It copies
6017    "len" bytes of memory over.  If the argument is known to be aligned to some
6018    boundary, this can be specified as the fourth argument, otherwise it should
6019    be set to 0 or 1.</p>
6020
6021 </div>
6022
6023 <!-- _______________________________________________________________________ -->
6024 <div class="doc_subsubsection">
6025   <a name="int_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
6026 </div>
6027
6028 <div class="doc_text">
6029
6030 <h5>Syntax:</h5>
6031 <p>This is an overloaded intrinsic. You can use llvm.memset on any integer bit
6032    width and for different address spaces. Not all targets support all bit
6033    widths however.</p>
6034
6035 <pre>
6036   declare void @llvm.memset.p0i8.i32(i8 * &lt;dest&gt;, i8 &lt;val&gt;,
6037                                      i32 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
6038   declare void @llvm.memset.p0i8.i64(i8 * &lt;dest&gt;, i8 &lt;val&gt;,
6039                                      i64 &lt;len&gt;, i32 &lt;align&gt;, i1 &lt;isvolatile&gt;)
6040 </pre>
6041
6042 <h5>Overview:</h5>
6043 <p>The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a
6044    particular byte value.</p>
6045
6046 <p>Note that, unlike the standard libc function, the <tt>llvm.memset</tt>
6047    intrinsic does not return a value, takes extra alignment/volatile arguments,
6048    and the destination can be in an arbitrary address space.</p>
6049
6050 <h5>Arguments:</h5>
6051 <p>The first argument is a pointer to the destination to fill, the second is the
6052    byte value to fill it with, the third argument is an integer argument
6053    specifying the number of bytes to fill, and the fourth argument is the known
6054    alignment of destination location.</p>
6055
6056 <p>If the call to this intrinsic has an alignment value that is not 0 or 1,
6057    then the caller guarantees that the destination pointer is aligned to that
6058    boundary.</p>
6059
6060 <p>Volatile accesses should not be deleted if dead, but the access behavior is
6061    not very cleanly specified and it is unwise to depend on it.</p>
6062
6063 <h5>Semantics:</h5>
6064 <p>The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting
6065    at the destination location.  If the argument is known to be aligned to some
6066    boundary, this can be specified as the fourth argument, otherwise it should
6067    be set to 0 or 1.</p>
6068
6069 </div>
6070
6071 <!-- _______________________________________________________________________ -->
6072 <div class="doc_subsubsection">
6073   <a name="int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
6074 </div>
6075
6076 <div class="doc_text">
6077
6078 <h5>Syntax:</h5>
6079 <p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any
6080    floating point or vector of floating point type. Not all targets support all
6081    types however.</p>
6082
6083 <pre>
6084   declare float     @llvm.sqrt.f32(float %Val)
6085   declare double    @llvm.sqrt.f64(double %Val)
6086   declare x86_fp80  @llvm.sqrt.f80(x86_fp80 %Val)
6087   declare fp128     @llvm.sqrt.f128(fp128 %Val)
6088   declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
6089 </pre>
6090
6091 <h5>Overview:</h5>
6092 <p>The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand,
6093    returning the same value as the libm '<tt>sqrt</tt>' functions would.
6094    Unlike <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined
6095    behavior for negative numbers other than -0.0 (which allows for better
6096    optimization, because there is no need to worry about errno being
6097    set).  <tt>llvm.sqrt(-0.0)</tt> is defined to return -0.0 like IEEE sqrt.</p>
6098
6099 <h5>Arguments:</h5>
6100 <p>The argument and return value are floating point numbers of the same
6101    type.</p>
6102
6103 <h5>Semantics:</h5>
6104 <p>This function returns the sqrt of the specified operand if it is a
6105    nonnegative floating point number.</p>
6106
6107 </div>
6108
6109 <!-- _______________________________________________________________________ -->
6110 <div class="doc_subsubsection">
6111   <a name="int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
6112 </div>
6113
6114 <div class="doc_text">
6115
6116 <h5>Syntax:</h5>
6117 <p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any
6118    floating point or vector of floating point type. Not all targets support all
6119    types however.</p>
6120
6121 <pre>
6122   declare float     @llvm.powi.f32(float  %Val, i32 %power)
6123   declare double    @llvm.powi.f64(double %Val, i32 %power)
6124   declare x86_fp80  @llvm.powi.f80(x86_fp80  %Val, i32 %power)
6125   declare fp128     @llvm.powi.f128(fp128 %Val, i32 %power)
6126   declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128  %Val, i32 %power)
6127 </pre>
6128
6129 <h5>Overview:</h5>
6130 <p>The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the
6131    specified (positive or negative) power.  The order of evaluation of
6132    multiplications is not defined.  When a vector of floating point type is
6133    used, the second argument remains a scalar integer value.</p>
6134
6135 <h5>Arguments:</h5>
6136 <p>The second argument is an integer power, and the first is a value to raise to
6137    that power.</p>
6138
6139 <h5>Semantics:</h5>
6140 <p>This function returns the first value raised to the second power with an
6141    unspecified sequence of rounding operations.</p>
6142
6143 </div>
6144
6145 <!-- _______________________________________________________________________ -->
6146 <div class="doc_subsubsection">
6147   <a name="int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a>
6148 </div>
6149
6150 <div class="doc_text">
6151
6152 <h5>Syntax:</h5>
6153 <p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any
6154    floating point or vector of floating point type. Not all targets support all
6155    types however.</p>
6156
6157 <pre>
6158   declare float     @llvm.sin.f32(float  %Val)
6159   declare double    @llvm.sin.f64(double %Val)
6160   declare x86_fp80  @llvm.sin.f80(x86_fp80  %Val)
6161   declare fp128     @llvm.sin.f128(fp128 %Val)
6162   declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128  %Val)
6163 </pre>
6164
6165 <h5>Overview:</h5>
6166 <p>The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand.</p>
6167
6168 <h5>Arguments:</h5>
6169 <p>The argument and return value are floating point numbers of the same
6170    type.</p>
6171
6172 <h5>Semantics:</h5>
6173 <p>This function returns the sine of the specified operand, returning the same
6174    values as the libm <tt>sin</tt> functions would, and handles error conditions
6175    in the same way.</p>
6176
6177 </div>
6178
6179 <!-- _______________________________________________________________________ -->
6180 <div class="doc_subsubsection">
6181   <a name="int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a>
6182 </div>
6183
6184 <div class="doc_text">
6185
6186 <h5>Syntax:</h5>
6187 <p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any
6188    floating point or vector of floating point type. Not all targets support all
6189    types however.</p>
6190
6191 <pre>
6192   declare float     @llvm.cos.f32(float  %Val)
6193   declare double    @llvm.cos.f64(double %Val)
6194   declare x86_fp80  @llvm.cos.f80(x86_fp80  %Val)
6195   declare fp128     @llvm.cos.f128(fp128 %Val)
6196   declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128  %Val)
6197 </pre>
6198
6199 <h5>Overview:</h5>
6200 <p>The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand.</p>
6201
6202 <h5>Arguments:</h5>
6203 <p>The argument and return value are floating point numbers of the same
6204    type.</p>
6205
6206 <h5>Semantics:</h5>
6207 <p>This function returns the cosine of the specified operand, returning the same
6208    values as the libm <tt>cos</tt> functions would, and handles error conditions
6209    in the same way.</p>
6210
6211 </div>
6212
6213 <!-- _______________________________________________________________________ -->
6214 <div class="doc_subsubsection">
6215   <a name="int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a>
6216 </div>
6217
6218 <div class="doc_text">
6219
6220 <h5>Syntax:</h5>
6221 <p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any
6222    floating point or vector of floating point type. Not all targets support all
6223    types however.</p>
6224
6225 <pre>
6226   declare float     @llvm.pow.f32(float  %Val, float %Power)
6227   declare double    @llvm.pow.f64(double %Val, double %Power)
6228   declare x86_fp80  @llvm.pow.f80(x86_fp80  %Val, x86_fp80 %Power)
6229   declare fp128     @llvm.pow.f128(fp128 %Val, fp128 %Power)
6230   declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128  %Val, ppc_fp128 Power)
6231 </pre>
6232
6233 <h5>Overview:</h5>
6234 <p>The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the
6235    specified (positive or negative) power.</p>
6236
6237 <h5>Arguments:</h5>
6238 <p>The second argument is a floating point power, and the first is a value to
6239    raise to that power.</p>
6240
6241 <h5>Semantics:</h5>
6242 <p>This function returns the first value raised to the second power, returning
6243    the same values as the libm <tt>pow</tt> functions would, and handles error
6244    conditions in the same way.</p>
6245
6246 </div>
6247
6248 <!-- ======================================================================= -->
6249 <div class="doc_subsection">
6250   <a name="int_manip">Bit Manipulation Intrinsics</a>
6251 </div>
6252
6253 <div class="doc_text">
6254
6255 <p>LLVM provides intrinsics for a few important bit manipulation operations.
6256    These allow efficient code generation for some algorithms.</p>
6257
6258 </div>
6259
6260 <!-- _______________________________________________________________________ -->
6261 <div class="doc_subsubsection">
6262   <a name="int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
6263 </div>
6264
6265 <div class="doc_text">
6266
6267 <h5>Syntax:</h5>
6268 <p>This is an overloaded intrinsic function. You can use bswap on any integer
6269    type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p>
6270
6271 <pre>
6272   declare i16 @llvm.bswap.i16(i16 &lt;id&gt;)
6273   declare i32 @llvm.bswap.i32(i32 &lt;id&gt;)
6274   declare i64 @llvm.bswap.i64(i64 &lt;id&gt;)
6275 </pre>
6276
6277 <h5>Overview:</h5>
6278 <p>The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer
6279    values with an even number of bytes (positive multiple of 16 bits).  These
6280    are useful for performing operations on data that is not in the target's
6281    native byte order.</p>
6282
6283 <h5>Semantics:</h5>
6284 <p>The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high
6285    and low byte of the input i16 swapped.  Similarly,
6286    the <tt>llvm.bswap.i32</tt> intrinsic returns an i32 value that has the four
6287    bytes of the input i32 swapped, so that if the input bytes are numbered 0, 1,
6288    2, 3 then the returned i32 will have its bytes in 3, 2, 1, 0 order.
6289    The <tt>llvm.bswap.i48</tt>, <tt>llvm.bswap.i64</tt> and other intrinsics
6290    extend this concept to additional even-byte lengths (6 bytes, 8 bytes and
6291    more, respectively).</p>
6292
6293 </div>
6294
6295 <!-- _______________________________________________________________________ -->
6296 <div class="doc_subsubsection">
6297   <a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
6298 </div>
6299
6300 <div class="doc_text">
6301
6302 <h5>Syntax:</h5>
6303 <p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit
6304    width. Not all targets support all bit widths however.</p>
6305
6306 <pre>
6307   declare i8 @llvm.ctpop.i8(i8  &lt;src&gt;)
6308   declare i16 @llvm.ctpop.i16(i16 &lt;src&gt;)
6309   declare i32 @llvm.ctpop.i32(i32 &lt;src&gt;)
6310   declare i64 @llvm.ctpop.i64(i64 &lt;src&gt;)
6311   declare i256 @llvm.ctpop.i256(i256 &lt;src&gt;)
6312 </pre>
6313
6314 <h5>Overview:</h5>
6315 <p>The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set
6316    in a value.</p>
6317
6318 <h5>Arguments:</h5>
6319 <p>The only argument is the value to be counted.  The argument may be of any
6320    integer type.  The return type must match the argument type.</p>
6321
6322 <h5>Semantics:</h5>
6323 <p>The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.</p>
6324
6325 </div>
6326
6327 <!-- _______________________________________________________________________ -->
6328 <div class="doc_subsubsection">
6329   <a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a>
6330 </div>
6331
6332 <div class="doc_text">
6333
6334 <h5>Syntax:</h5>
6335 <p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any
6336    integer bit width. Not all targets support all bit widths however.</p>
6337
6338 <pre>
6339   declare i8 @llvm.ctlz.i8 (i8  &lt;src&gt;)
6340   declare i16 @llvm.ctlz.i16(i16 &lt;src&gt;)
6341   declare i32 @llvm.ctlz.i32(i32 &lt;src&gt;)
6342   declare i64 @llvm.ctlz.i64(i64 &lt;src&gt;)
6343   declare i256 @llvm.ctlz.i256(i256 &lt;src&gt;)
6344 </pre>
6345
6346 <h5>Overview:</h5>
6347 <p>The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of
6348    leading zeros in a variable.</p>
6349
6350 <h5>Arguments:</h5>
6351 <p>The only argument is the value to be counted.  The argument may be of any
6352    integer type. The return type must match the argument type.</p>
6353
6354 <h5>Semantics:</h5>
6355 <p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant)
6356    zeros in a variable.  If the src == 0 then the result is the size in bits of
6357    the type of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p>
6358
6359 </div>
6360
6361 <!-- _______________________________________________________________________ -->
6362 <div class="doc_subsubsection">
6363   <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a>
6364 </div>
6365
6366 <div class="doc_text">
6367
6368 <h5>Syntax:</h5>
6369 <p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any
6370    integer bit width. Not all targets support all bit widths however.</p>
6371
6372 <pre>
6373   declare i8 @llvm.cttz.i8 (i8  &lt;src&gt;)
6374   declare i16 @llvm.cttz.i16(i16 &lt;src&gt;)
6375   declare i32 @llvm.cttz.i32(i32 &lt;src&gt;)
6376   declare i64 @llvm.cttz.i64(i64 &lt;src&gt;)
6377   declare i256 @llvm.cttz.i256(i256 &lt;src&gt;)
6378 </pre>
6379
6380 <h5>Overview:</h5>
6381 <p>The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of
6382    trailing zeros.</p>
6383
6384 <h5>Arguments:</h5>
6385 <p>The only argument is the value to be counted.  The argument may be of any
6386    integer type.  The return type must match the argument type.</p>
6387
6388 <h5>Semantics:</h5>
6389 <p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant)
6390    zeros in a variable.  If the src == 0 then the result is the size in bits of
6391    the type of src.  For example, <tt>llvm.cttz(2) = 1</tt>.</p>
6392
6393 </div>
6394
6395 <!-- ======================================================================= -->
6396 <div class="doc_subsection">
6397   <a name="int_overflow">Arithmetic with Overflow Intrinsics</a>
6398 </div>
6399
6400 <div class="doc_text">
6401
6402 <p>LLVM provides intrinsics for some arithmetic with overflow operations.</p>
6403
6404 </div>
6405
6406 <!-- _______________________________________________________________________ -->
6407 <div class="doc_subsubsection">
6408   <a name="int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt>' Intrinsics</a>
6409 </div>
6410
6411 <div class="doc_text">
6412
6413 <h5>Syntax:</h5>
6414 <p>This is an overloaded intrinsic. You can use <tt>llvm.sadd.with.overflow</tt>
6415    on any integer bit width.</p>
6416
6417 <pre>
6418   declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
6419   declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
6420   declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
6421 </pre>
6422
6423 <h5>Overview:</h5>
6424 <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
6425    a signed addition of the two arguments, and indicate whether an overflow
6426    occurred during the signed summation.</p>
6427
6428 <h5>Arguments:</h5>
6429 <p>The arguments (%a and %b) and the first element of the result structure may
6430    be of integer types of any bit width, but they must have the same bit
6431    width. The second element of the result structure must be of
6432    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6433    undergo signed addition.</p>
6434
6435 <h5>Semantics:</h5>
6436 <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
6437    a signed addition of the two variables. They return a structure &mdash; the
6438    first element of which is the signed summation, and the second element of
6439    which is a bit specifying if the signed summation resulted in an
6440    overflow.</p>
6441
6442 <h5>Examples:</h5>
6443 <pre>
6444   %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
6445   %sum = extractvalue {i32, i1} %res, 0
6446   %obit = extractvalue {i32, i1} %res, 1
6447   br i1 %obit, label %overflow, label %normal
6448 </pre>
6449
6450 </div>
6451
6452 <!-- _______________________________________________________________________ -->
6453 <div class="doc_subsubsection">
6454   <a name="int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt>' Intrinsics</a>
6455 </div>
6456
6457 <div class="doc_text">
6458
6459 <h5>Syntax:</h5>
6460 <p>This is an overloaded intrinsic. You can use <tt>llvm.uadd.with.overflow</tt>
6461    on any integer bit width.</p>
6462
6463 <pre>
6464   declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
6465   declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
6466   declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
6467 </pre>
6468
6469 <h5>Overview:</h5>
6470 <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
6471    an unsigned addition of the two arguments, and indicate whether a carry
6472    occurred during the unsigned summation.</p>
6473
6474 <h5>Arguments:</h5>
6475 <p>The arguments (%a and %b) and the first element of the result structure may
6476    be of integer types of any bit width, but they must have the same bit
6477    width. The second element of the result structure must be of
6478    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6479    undergo unsigned addition.</p>
6480
6481 <h5>Semantics:</h5>
6482 <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
6483    an unsigned addition of the two arguments. They return a structure &mdash;
6484    the first element of which is the sum, and the second element of which is a
6485    bit specifying if the unsigned summation resulted in a carry.</p>
6486
6487 <h5>Examples:</h5>
6488 <pre>
6489   %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
6490   %sum = extractvalue {i32, i1} %res, 0
6491   %obit = extractvalue {i32, i1} %res, 1
6492   br i1 %obit, label %carry, label %normal
6493 </pre>
6494
6495 </div>
6496
6497 <!-- _______________________________________________________________________ -->
6498 <div class="doc_subsubsection">
6499   <a name="int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt>' Intrinsics</a>
6500 </div>
6501
6502 <div class="doc_text">
6503
6504 <h5>Syntax:</h5>
6505 <p>This is an overloaded intrinsic. You can use <tt>llvm.ssub.with.overflow</tt>
6506    on any integer bit width.</p>
6507
6508 <pre>
6509   declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
6510   declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
6511   declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
6512 </pre>
6513
6514 <h5>Overview:</h5>
6515 <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
6516    a signed subtraction of the two arguments, and indicate whether an overflow
6517    occurred during the signed subtraction.</p>
6518
6519 <h5>Arguments:</h5>
6520 <p>The arguments (%a and %b) and the first element of the result structure may
6521    be of integer types of any bit width, but they must have the same bit
6522    width. The second element of the result structure must be of
6523    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6524    undergo signed subtraction.</p>
6525
6526 <h5>Semantics:</h5>
6527 <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
6528    a signed subtraction of the two arguments. They return a structure &mdash;
6529    the first element of which is the subtraction, and the second element of
6530    which is a bit specifying if the signed subtraction resulted in an
6531    overflow.</p>
6532
6533 <h5>Examples:</h5>
6534 <pre>
6535   %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
6536   %sum = extractvalue {i32, i1} %res, 0
6537   %obit = extractvalue {i32, i1} %res, 1
6538   br i1 %obit, label %overflow, label %normal
6539 </pre>
6540
6541 </div>
6542
6543 <!-- _______________________________________________________________________ -->
6544 <div class="doc_subsubsection">
6545   <a name="int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt>' Intrinsics</a>
6546 </div>
6547
6548 <div class="doc_text">
6549
6550 <h5>Syntax:</h5>
6551 <p>This is an overloaded intrinsic. You can use <tt>llvm.usub.with.overflow</tt>
6552    on any integer bit width.</p>
6553
6554 <pre>
6555   declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
6556   declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
6557   declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
6558 </pre>
6559
6560 <h5>Overview:</h5>
6561 <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
6562    an unsigned subtraction of the two arguments, and indicate whether an
6563    overflow occurred during the unsigned subtraction.</p>
6564
6565 <h5>Arguments:</h5>
6566 <p>The arguments (%a and %b) and the first element of the result structure may
6567    be of integer types of any bit width, but they must have the same bit
6568    width. The second element of the result structure must be of
6569    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6570    undergo unsigned subtraction.</p>
6571
6572 <h5>Semantics:</h5>
6573 <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
6574    an unsigned subtraction of the two arguments. They return a structure &mdash;
6575    the first element of which is the subtraction, and the second element of
6576    which is a bit specifying if the unsigned subtraction resulted in an
6577    overflow.</p>
6578
6579 <h5>Examples:</h5>
6580 <pre>
6581   %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
6582   %sum = extractvalue {i32, i1} %res, 0
6583   %obit = extractvalue {i32, i1} %res, 1
6584   br i1 %obit, label %overflow, label %normal
6585 </pre>
6586
6587 </div>
6588
6589 <!-- _______________________________________________________________________ -->
6590 <div class="doc_subsubsection">
6591   <a name="int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt>' Intrinsics</a>
6592 </div>
6593
6594 <div class="doc_text">
6595
6596 <h5>Syntax:</h5>
6597 <p>This is an overloaded intrinsic. You can use <tt>llvm.smul.with.overflow</tt>
6598    on any integer bit width.</p>
6599
6600 <pre>
6601   declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
6602   declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
6603   declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
6604 </pre>
6605
6606 <h5>Overview:</h5>
6607
6608 <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
6609    a signed multiplication of the two arguments, and indicate whether an
6610    overflow occurred during the signed multiplication.</p>
6611
6612 <h5>Arguments:</h5>
6613 <p>The arguments (%a and %b) and the first element of the result structure may
6614    be of integer types of any bit width, but they must have the same bit
6615    width. The second element of the result structure must be of
6616    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6617    undergo signed multiplication.</p>
6618
6619 <h5>Semantics:</h5>
6620 <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
6621    a signed multiplication of the two arguments. They return a structure &mdash;
6622    the first element of which is the multiplication, and the second element of
6623    which is a bit specifying if the signed multiplication resulted in an
6624    overflow.</p>
6625
6626 <h5>Examples:</h5>
6627 <pre>
6628   %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
6629   %sum = extractvalue {i32, i1} %res, 0
6630   %obit = extractvalue {i32, i1} %res, 1
6631   br i1 %obit, label %overflow, label %normal
6632 </pre>
6633
6634 </div>
6635
6636 <!-- _______________________________________________________________________ -->
6637 <div class="doc_subsubsection">
6638   <a name="int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt>' Intrinsics</a>
6639 </div>
6640
6641 <div class="doc_text">
6642
6643 <h5>Syntax:</h5>
6644 <p>This is an overloaded intrinsic. You can use <tt>llvm.umul.with.overflow</tt>
6645    on any integer bit width.</p>
6646
6647 <pre>
6648   declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
6649   declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
6650   declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
6651 </pre>
6652
6653 <h5>Overview:</h5>
6654 <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
6655    a unsigned multiplication of the two arguments, and indicate whether an
6656    overflow occurred during the unsigned multiplication.</p>
6657
6658 <h5>Arguments:</h5>
6659 <p>The arguments (%a and %b) and the first element of the result structure may
6660    be of integer types of any bit width, but they must have the same bit
6661    width. The second element of the result structure must be of
6662    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6663    undergo unsigned multiplication.</p>
6664
6665 <h5>Semantics:</h5>
6666 <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
6667    an unsigned multiplication of the two arguments. They return a structure
6668    &mdash; the first element of which is the multiplication, and the second
6669    element of which is a bit specifying if the unsigned multiplication resulted
6670    in an overflow.</p>
6671
6672 <h5>Examples:</h5>
6673 <pre>
6674   %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
6675   %sum = extractvalue {i32, i1} %res, 0
6676   %obit = extractvalue {i32, i1} %res, 1
6677   br i1 %obit, label %overflow, label %normal
6678 </pre>
6679
6680 </div>
6681
6682 <!-- ======================================================================= -->
6683 <div class="doc_subsection">
6684   <a name="int_fp16">Half Precision Floating Point Intrinsics</a>
6685 </div>
6686
6687 <div class="doc_text">
6688
6689 <p>Half precision floating point is a storage-only format. This means that it is
6690    a dense encoding (in memory) but does not support computation in the
6691    format.</p>
6692
6693 <p>This means that code must first load the half-precision floating point
6694    value as an i16, then convert it to float with <a
6695    href="#int_convert_from_fp16"><tt>llvm.convert.from.fp16</tt></a>.
6696    Computation can then be performed on the float value (including extending to
6697    double etc).  To store the value back to memory, it is first converted to
6698    float if needed, then converted to i16 with
6699    <a href="#int_convert_to_fp16"><tt>llvm.convert.to.fp16</tt></a>, then
6700    storing as an i16 value.</p>
6701 </div>
6702
6703 <!-- _______________________________________________________________________ -->
6704 <div class="doc_subsubsection">
6705   <a name="int_convert_to_fp16">'<tt>llvm.convert.to.fp16</tt>' Intrinsic</a>
6706 </div>
6707
6708 <div class="doc_text">
6709
6710 <h5>Syntax:</h5>
6711 <pre>
6712   declare i16 @llvm.convert.to.fp16(f32 %a)
6713 </pre>
6714
6715 <h5>Overview:</h5>
6716 <p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs
6717    a conversion from single precision floating point format to half precision
6718    floating point format.</p>
6719
6720 <h5>Arguments:</h5>
6721 <p>The intrinsic function contains single argument - the value to be
6722    converted.</p>
6723
6724 <h5>Semantics:</h5>
6725 <p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs
6726    a conversion from single precision floating point format to half precision
6727    floating point format. The return value is an <tt>i16</tt> which
6728    contains the converted number.</p>
6729
6730 <h5>Examples:</h5>
6731 <pre>
6732   %res = call i16 @llvm.convert.to.fp16(f32 %a)
6733   store i16 %res, i16* @x, align 2
6734 </pre>
6735
6736 </div>
6737
6738 <!-- _______________________________________________________________________ -->
6739 <div class="doc_subsubsection">
6740  <a name="int_convert_from_fp16">'<tt>llvm.convert.from.fp16</tt>' Intrinsic</a>
6741 </div>
6742
6743 <div class="doc_text">
6744
6745 <h5>Syntax:</h5>
6746 <pre>
6747   declare f32 @llvm.convert.from.fp16(i16 %a)
6748 </pre>
6749
6750 <h5>Overview:</h5>
6751 <p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs
6752    a conversion from half precision floating point format to single precision
6753    floating point format.</p>
6754
6755 <h5>Arguments:</h5>
6756 <p>The intrinsic function contains single argument - the value to be
6757    converted.</p>
6758
6759 <h5>Semantics:</h5>
6760 <p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs a
6761    conversion from half single precision floating point format to single
6762    precision floating point format. The input half-float value is represented by
6763    an <tt>i16</tt> value.</p>
6764
6765 <h5>Examples:</h5>
6766 <pre>
6767   %a = load i16* @x, align 2
6768   %res = call f32 @llvm.convert.from.fp16(i16 %a)
6769 </pre>
6770
6771 </div>
6772
6773 <!-- ======================================================================= -->
6774 <div class="doc_subsection">
6775   <a name="int_debugger">Debugger Intrinsics</a>
6776 </div>
6777
6778 <div class="doc_text">
6779
6780 <p>The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt>
6781    prefix), are described in
6782    the <a href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source
6783    Level Debugging</a> document.</p>
6784
6785 </div>
6786
6787 <!-- ======================================================================= -->
6788 <div class="doc_subsection">
6789   <a name="int_eh">Exception Handling Intrinsics</a>
6790 </div>
6791
6792 <div class="doc_text">
6793
6794 <p>The LLVM exception handling intrinsics (which all start with
6795    <tt>llvm.eh.</tt> prefix), are described in
6796    the <a href="ExceptionHandling.html#format_common_intrinsics">LLVM Exception
6797    Handling</a> document.</p>
6798
6799 </div>
6800
6801 <!-- ======================================================================= -->
6802 <div class="doc_subsection">
6803   <a name="int_trampoline">Trampoline Intrinsic</a>
6804 </div>
6805
6806 <div class="doc_text">
6807
6808 <p>This intrinsic makes it possible to excise one parameter, marked with
6809    the <tt>nest</tt> attribute, from a function.  The result is a callable
6810    function pointer lacking the nest parameter - the caller does not need to
6811    provide a value for it.  Instead, the value to use is stored in advance in a
6812    "trampoline", a block of memory usually allocated on the stack, which also
6813    contains code to splice the nest value into the argument list.  This is used
6814    to implement the GCC nested function address extension.</p>
6815
6816 <p>For example, if the function is
6817    <tt>i32 f(i8* nest %c, i32 %x, i32 %y)</tt> then the resulting function
6818    pointer has signature <tt>i32 (i32, i32)*</tt>.  It can be created as
6819    follows:</p>
6820
6821 <div class="doc_code">
6822 <pre>
6823   %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
6824   %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
6825   %p = call i8* @llvm.init.trampoline( i8* %tramp1, i8* bitcast (i32 (i8* nest , i32, i32)* @f to i8*), i8* %nval )
6826   %fp = bitcast i8* %p to i32 (i32, i32)*
6827 </pre>
6828 </div>
6829
6830 <p>The call <tt>%val = call i32 %fp( i32 %x, i32 %y )</tt> is then equivalent
6831    to <tt>%val = call i32 %f( i8* %nval, i32 %x, i32 %y )</tt>.</p>
6832
6833 </div>
6834
6835 <!-- _______________________________________________________________________ -->
6836 <div class="doc_subsubsection">
6837   <a name="int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a>
6838 </div>
6839
6840 <div class="doc_text">
6841
6842 <h5>Syntax:</h5>
6843 <pre>
6844   declare i8* @llvm.init.trampoline(i8* &lt;tramp&gt;, i8* &lt;func&gt;, i8* &lt;nval&gt;)
6845 </pre>
6846
6847 <h5>Overview:</h5>
6848 <p>This fills the memory pointed to by <tt>tramp</tt> with code and returns a
6849    function pointer suitable for executing it.</p>
6850
6851 <h5>Arguments:</h5>
6852 <p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all
6853    pointers.  The <tt>tramp</tt> argument must point to a sufficiently large and
6854    sufficiently aligned block of memory; this memory is written to by the
6855    intrinsic.  Note that the size and the alignment are target-specific - LLVM
6856    currently provides no portable way of determining them, so a front-end that
6857    generates this intrinsic needs to have some target-specific knowledge.
6858    The <tt>func</tt> argument must hold a function bitcast to
6859    an <tt>i8*</tt>.</p>
6860
6861 <h5>Semantics:</h5>
6862 <p>The block of memory pointed to by <tt>tramp</tt> is filled with target
6863    dependent code, turning it into a function.  A pointer to this function is
6864    returned, but needs to be bitcast to an <a href="#int_trampoline">appropriate
6865    function pointer type</a> before being called.  The new function's signature
6866    is the same as that of <tt>func</tt> with any arguments marked with
6867    the <tt>nest</tt> attribute removed.  At most one such <tt>nest</tt> argument
6868    is allowed, and it must be of pointer type.  Calling the new function is
6869    equivalent to calling <tt>func</tt> with the same argument list, but
6870    with <tt>nval</tt> used for the missing <tt>nest</tt> argument.  If, after
6871    calling <tt>llvm.init.trampoline</tt>, the memory pointed to
6872    by <tt>tramp</tt> is modified, then the effect of any later call to the
6873    returned function pointer is undefined.</p>
6874
6875 </div>
6876
6877 <!-- ======================================================================= -->
6878 <div class="doc_subsection">
6879   <a name="int_atomics">Atomic Operations and Synchronization Intrinsics</a>
6880 </div>
6881
6882 <div class="doc_text">
6883
6884 <p>These intrinsic functions expand the "universal IR" of LLVM to represent
6885    hardware constructs for atomic operations and memory synchronization.  This
6886    provides an interface to the hardware, not an interface to the programmer. It
6887    is aimed at a low enough level to allow any programming models or APIs
6888    (Application Programming Interfaces) which need atomic behaviors to map
6889    cleanly onto it. It is also modeled primarily on hardware behavior. Just as
6890    hardware provides a "universal IR" for source languages, it also provides a
6891    starting point for developing a "universal" atomic operation and
6892    synchronization IR.</p>
6893
6894 <p>These do <em>not</em> form an API such as high-level threading libraries,
6895    software transaction memory systems, atomic primitives, and intrinsic
6896    functions as found in BSD, GNU libc, atomic_ops, APR, and other system and
6897    application libraries.  The hardware interface provided by LLVM should allow
6898    a clean implementation of all of these APIs and parallel programming models.
6899    No one model or paradigm should be selected above others unless the hardware
6900    itself ubiquitously does so.</p>
6901
6902 </div>
6903
6904 <!-- _______________________________________________________________________ -->
6905 <div class="doc_subsubsection">
6906   <a name="int_memory_barrier">'<tt>llvm.memory.barrier</tt>' Intrinsic</a>
6907 </div>
6908 <div class="doc_text">
6909 <h5>Syntax:</h5>
6910 <pre>
6911   declare void @llvm.memory.barrier( i1 &lt;ll&gt;, i1 &lt;ls&gt;, i1 &lt;sl&gt;, i1 &lt;ss&gt;, i1 &lt;device&gt; )
6912 </pre>
6913
6914 <h5>Overview:</h5>
6915 <p>The <tt>llvm.memory.barrier</tt> intrinsic guarantees ordering between
6916    specific pairs of memory access types.</p>
6917
6918 <h5>Arguments:</h5>
6919 <p>The <tt>llvm.memory.barrier</tt> intrinsic requires five boolean arguments.
6920    The first four arguments enables a specific barrier as listed below.  The
6921    fifth argument specifies that the barrier applies to io or device or uncached
6922    memory.</p>
6923
6924 <ul>
6925   <li><tt>ll</tt>: load-load barrier</li>
6926   <li><tt>ls</tt>: load-store barrier</li>
6927   <li><tt>sl</tt>: store-load barrier</li>
6928   <li><tt>ss</tt>: store-store barrier</li>
6929   <li><tt>device</tt>: barrier applies to device and uncached memory also.</li>
6930 </ul>
6931
6932 <h5>Semantics:</h5>
6933 <p>This intrinsic causes the system to enforce some ordering constraints upon
6934    the loads and stores of the program. This barrier does not
6935    indicate <em>when</em> any events will occur, it only enforces
6936    an <em>order</em> in which they occur. For any of the specified pairs of load
6937    and store operations (f.ex.  load-load, or store-load), all of the first
6938    operations preceding the barrier will complete before any of the second
6939    operations succeeding the barrier begin. Specifically the semantics for each
6940    pairing is as follows:</p>
6941
6942 <ul>
6943   <li><tt>ll</tt>: All loads before the barrier must complete before any load
6944       after the barrier begins.</li>
6945   <li><tt>ls</tt>: All loads before the barrier must complete before any
6946       store after the barrier begins.</li>
6947   <li><tt>ss</tt>: All stores before the barrier must complete before any
6948       store after the barrier begins.</li>
6949   <li><tt>sl</tt>: All stores before the barrier must complete before any
6950       load after the barrier begins.</li>
6951 </ul>
6952
6953 <p>These semantics are applied with a logical "and" behavior when more than one
6954    is enabled in a single memory barrier intrinsic.</p>
6955
6956 <p>Backends may implement stronger barriers than those requested when they do
6957    not support as fine grained a barrier as requested.  Some architectures do
6958    not need all types of barriers and on such architectures, these become
6959    noops.</p>
6960
6961 <h5>Example:</h5>
6962 <pre>
6963 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
6964 %ptr      = bitcast i8* %mallocP to i32*
6965             store i32 4, %ptr
6966
6967 %result1  = load i32* %ptr      <i>; yields {i32}:result1 = 4</i>
6968             call void @llvm.memory.barrier( i1 false, i1 true, i1 false, i1 false )
6969                                 <i>; guarantee the above finishes</i>
6970             store i32 8, %ptr   <i>; before this begins</i>
6971 </pre>
6972
6973 </div>
6974
6975 <!-- _______________________________________________________________________ -->
6976 <div class="doc_subsubsection">
6977   <a name="int_atomic_cmp_swap">'<tt>llvm.atomic.cmp.swap.*</tt>' Intrinsic</a>
6978 </div>
6979
6980 <div class="doc_text">
6981
6982 <h5>Syntax:</h5>
6983 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.cmp.swap</tt> on
6984    any integer bit width and for different address spaces. Not all targets
6985    support all bit widths however.</p>
6986
6987 <pre>
6988   declare i8 @llvm.atomic.cmp.swap.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;cmp&gt;, i8 &lt;val&gt; )
6989   declare i16 @llvm.atomic.cmp.swap.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;cmp&gt;, i16 &lt;val&gt; )
6990   declare i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;cmp&gt;, i32 &lt;val&gt; )
6991   declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;cmp&gt;, i64 &lt;val&gt; )
6992 </pre>
6993
6994 <h5>Overview:</h5>
6995 <p>This loads a value in memory and compares it to a given value. If they are
6996    equal, it stores a new value into the memory.</p>
6997
6998 <h5>Arguments:</h5>
6999 <p>The <tt>llvm.atomic.cmp.swap</tt> intrinsic takes three arguments. The result
7000    as well as both <tt>cmp</tt> and <tt>val</tt> must be integer values with the
7001    same bit width. The <tt>ptr</tt> argument must be a pointer to a value of
7002    this integer type. While any bit width integer may be used, targets may only
7003    lower representations they support in hardware.</p>
7004
7005 <h5>Semantics:</h5>
7006 <p>This entire intrinsic must be executed atomically. It first loads the value
7007    in memory pointed to by <tt>ptr</tt> and compares it with the
7008    value <tt>cmp</tt>. If they are equal, <tt>val</tt> is stored into the
7009    memory. The loaded value is yielded in all cases. This provides the
7010    equivalent of an atomic compare-and-swap operation within the SSA
7011    framework.</p>
7012
7013 <h5>Examples:</h5>
7014 <pre>
7015 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
7016 %ptr      = bitcast i8* %mallocP to i32*
7017             store i32 4, %ptr
7018
7019 %val1     = add i32 4, 4
7020 %result1  = call i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* %ptr, i32 4, %val1 )
7021                                           <i>; yields {i32}:result1 = 4</i>
7022 %stored1  = icmp eq i32 %result1, 4       <i>; yields {i1}:stored1 = true</i>
7023 %memval1  = load i32* %ptr                <i>; yields {i32}:memval1 = 8</i>
7024
7025 %val2     = add i32 1, 1
7026 %result2  = call i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* %ptr, i32 5, %val2 )
7027                                           <i>; yields {i32}:result2 = 8</i>
7028 %stored2  = icmp eq i32 %result2, 5       <i>; yields {i1}:stored2 = false</i>
7029
7030 %memval2  = load i32* %ptr                <i>; yields {i32}:memval2 = 8</i>
7031 </pre>
7032
7033 </div>
7034
7035 <!-- _______________________________________________________________________ -->
7036 <div class="doc_subsubsection">
7037   <a name="int_atomic_swap">'<tt>llvm.atomic.swap.*</tt>' Intrinsic</a>
7038 </div>
7039 <div class="doc_text">
7040 <h5>Syntax:</h5>
7041
7042 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.swap</tt> on any
7043    integer bit width. Not all targets support all bit widths however.</p>
7044
7045 <pre>
7046   declare i8 @llvm.atomic.swap.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;val&gt; )
7047   declare i16 @llvm.atomic.swap.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;val&gt; )
7048   declare i32 @llvm.atomic.swap.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;val&gt; )
7049   declare i64 @llvm.atomic.swap.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;val&gt; )
7050 </pre>
7051
7052 <h5>Overview:</h5>
7053 <p>This intrinsic loads the value stored in memory at <tt>ptr</tt> and yields
7054    the value from memory. It then stores the value in <tt>val</tt> in the memory
7055    at <tt>ptr</tt>.</p>
7056
7057 <h5>Arguments:</h5>
7058 <p>The <tt>llvm.atomic.swap</tt> intrinsic takes two arguments. Both
7059   the <tt>val</tt> argument and the result must be integers of the same bit
7060   width.  The first argument, <tt>ptr</tt>, must be a pointer to a value of this
7061   integer type. The targets may only lower integer representations they
7062   support.</p>
7063
7064 <h5>Semantics:</h5>
7065 <p>This intrinsic loads the value pointed to by <tt>ptr</tt>, yields it, and
7066    stores <tt>val</tt> back into <tt>ptr</tt> atomically. This provides the
7067    equivalent of an atomic swap operation within the SSA framework.</p>
7068
7069 <h5>Examples:</h5>
7070 <pre>
7071 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
7072 %ptr      = bitcast i8* %mallocP to i32*
7073             store i32 4, %ptr
7074
7075 %val1     = add i32 4, 4
7076 %result1  = call i32 @llvm.atomic.swap.i32.p0i32( i32* %ptr, i32 %val1 )
7077                                         <i>; yields {i32}:result1 = 4</i>
7078 %stored1  = icmp eq i32 %result1, 4     <i>; yields {i1}:stored1 = true</i>
7079 %memval1  = load i32* %ptr              <i>; yields {i32}:memval1 = 8</i>
7080
7081 %val2     = add i32 1, 1
7082 %result2  = call i32 @llvm.atomic.swap.i32.p0i32( i32* %ptr, i32 %val2 )
7083                                         <i>; yields {i32}:result2 = 8</i>
7084
7085 %stored2  = icmp eq i32 %result2, 8     <i>; yields {i1}:stored2 = true</i>
7086 %memval2  = load i32* %ptr              <i>; yields {i32}:memval2 = 2</i>
7087 </pre>
7088
7089 </div>
7090
7091 <!-- _______________________________________________________________________ -->
7092 <div class="doc_subsubsection">
7093   <a name="int_atomic_load_add">'<tt>llvm.atomic.load.add.*</tt>' Intrinsic</a>
7094
7095 </div>
7096
7097 <div class="doc_text">
7098
7099 <h5>Syntax:</h5>
7100 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.add</tt> on
7101    any integer bit width. Not all targets support all bit widths however.</p>
7102
7103 <pre>
7104   declare i8 @llvm.atomic.load.add.i8..p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
7105   declare i16 @llvm.atomic.load.add.i16..p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
7106   declare i32 @llvm.atomic.load.add.i32..p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
7107   declare i64 @llvm.atomic.load.add.i64..p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
7108 </pre>
7109
7110 <h5>Overview:</h5>
7111 <p>This intrinsic adds <tt>delta</tt> to the value stored in memory
7112    at <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p>
7113
7114 <h5>Arguments:</h5>
7115 <p>The intrinsic takes two arguments, the first a pointer to an integer value
7116    and the second an integer value. The result is also an integer value. These
7117    integer types can have any bit width, but they must all have the same bit
7118    width. The targets may only lower integer representations they support.</p>
7119
7120 <h5>Semantics:</h5>
7121 <p>This intrinsic does a series of operations atomically. It first loads the
7122    value stored at <tt>ptr</tt>. It then adds <tt>delta</tt>, stores the result
7123    to <tt>ptr</tt>. It yields the original value stored at <tt>ptr</tt>.</p>
7124
7125 <h5>Examples:</h5>
7126 <pre>
7127 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
7128 %ptr      = bitcast i8* %mallocP to i32*
7129             store i32 4, %ptr
7130 %result1  = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 4 )
7131                                 <i>; yields {i32}:result1 = 4</i>
7132 %result2  = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 2 )
7133                                 <i>; yields {i32}:result2 = 8</i>
7134 %result3  = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 5 )
7135                                 <i>; yields {i32}:result3 = 10</i>
7136 %memval1  = load i32* %ptr      <i>; yields {i32}:memval1 = 15</i>
7137 </pre>
7138
7139 </div>
7140
7141 <!-- _______________________________________________________________________ -->
7142 <div class="doc_subsubsection">
7143   <a name="int_atomic_load_sub">'<tt>llvm.atomic.load.sub.*</tt>' Intrinsic</a>
7144
7145 </div>
7146
7147 <div class="doc_text">
7148
7149 <h5>Syntax:</h5>
7150 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.sub</tt> on
7151    any integer bit width and for different address spaces. Not all targets
7152    support all bit widths however.</p>
7153
7154 <pre>
7155   declare i8 @llvm.atomic.load.sub.i8.p0i32( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
7156   declare i16 @llvm.atomic.load.sub.i16.p0i32( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
7157   declare i32 @llvm.atomic.load.sub.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
7158   declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
7159 </pre>
7160
7161 <h5>Overview:</h5>
7162 <p>This intrinsic subtracts <tt>delta</tt> to the value stored in memory at
7163    <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p>
7164
7165 <h5>Arguments:</h5>
7166 <p>The intrinsic takes two arguments, the first a pointer to an integer value
7167    and the second an integer value. The result is also an integer value. These
7168    integer types can have any bit width, but they must all have the same bit
7169    width. The targets may only lower integer representations they support.</p>
7170
7171 <h5>Semantics:</h5>
7172 <p>This intrinsic does a series of operations atomically. It first loads the
7173    value stored at <tt>ptr</tt>. It then subtracts <tt>delta</tt>, stores the
7174    result to <tt>ptr</tt>. It yields the original value stored
7175    at <tt>ptr</tt>.</p>
7176
7177 <h5>Examples:</h5>
7178 <pre>
7179 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
7180 %ptr      = bitcast i8* %mallocP to i32*
7181             store i32 8, %ptr
7182 %result1  = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 4 )
7183                                 <i>; yields {i32}:result1 = 8</i>
7184 %result2  = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 2 )
7185                                 <i>; yields {i32}:result2 = 4</i>
7186 %result3  = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 5 )
7187                                 <i>; yields {i32}:result3 = 2</i>
7188 %memval1  = load i32* %ptr      <i>; yields {i32}:memval1 = -3</i>
7189 </pre>
7190
7191 </div>
7192
7193 <!-- _______________________________________________________________________ -->
7194 <div class="doc_subsubsection">
7195   <a name="int_atomic_load_and">'<tt>llvm.atomic.load.and.*</tt>' Intrinsic</a><br>
7196   <a name="int_atomic_load_nand">'<tt>llvm.atomic.load.nand.*</tt>' Intrinsic</a><br>
7197   <a name="int_atomic_load_or">'<tt>llvm.atomic.load.or.*</tt>' Intrinsic</a><br>
7198   <a name="int_atomic_load_xor">'<tt>llvm.atomic.load.xor.*</tt>' Intrinsic</a><br>
7199 </div>
7200
7201 <div class="doc_text">
7202
7203 <h5>Syntax:</h5>
7204 <p>These are overloaded intrinsics. You can
7205   use <tt>llvm.atomic.load_and</tt>, <tt>llvm.atomic.load_nand</tt>,
7206   <tt>llvm.atomic.load_or</tt>, and <tt>llvm.atomic.load_xor</tt> on any integer
7207   bit width and for different address spaces. Not all targets support all bit
7208   widths however.</p>
7209
7210 <pre>
7211   declare i8 @llvm.atomic.load.and.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
7212   declare i16 @llvm.atomic.load.and.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
7213   declare i32 @llvm.atomic.load.and.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
7214   declare i64 @llvm.atomic.load.and.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
7215 </pre>
7216
7217 <pre>
7218   declare i8 @llvm.atomic.load.or.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
7219   declare i16 @llvm.atomic.load.or.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
7220   declare i32 @llvm.atomic.load.or.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
7221   declare i64 @llvm.atomic.load.or.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
7222 </pre>
7223
7224 <pre>
7225   declare i8 @llvm.atomic.load.nand.i8.p0i32( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
7226   declare i16 @llvm.atomic.load.nand.i16.p0i32( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
7227   declare i32 @llvm.atomic.load.nand.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
7228   declare i64 @llvm.atomic.load.nand.i64.p0i32( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
7229 </pre>
7230
7231 <pre>
7232   declare i8 @llvm.atomic.load.xor.i8.p0i32( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
7233   declare i16 @llvm.atomic.load.xor.i16.p0i32( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
7234   declare i32 @llvm.atomic.load.xor.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
7235   declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
7236 </pre>
7237
7238 <h5>Overview:</h5>
7239 <p>These intrinsics bitwise the operation (and, nand, or, xor) <tt>delta</tt> to
7240    the value stored in memory at <tt>ptr</tt>. It yields the original value
7241    at <tt>ptr</tt>.</p>
7242
7243 <h5>Arguments:</h5>
7244 <p>These intrinsics take two arguments, the first a pointer to an integer value
7245    and the second an integer value. The result is also an integer value. These
7246    integer types can have any bit width, but they must all have the same bit
7247    width. The targets may only lower integer representations they support.</p>
7248
7249 <h5>Semantics:</h5>
7250 <p>These intrinsics does a series of operations atomically. They first load the
7251    value stored at <tt>ptr</tt>. They then do the bitwise
7252    operation <tt>delta</tt>, store the result to <tt>ptr</tt>. They yield the
7253    original value stored at <tt>ptr</tt>.</p>
7254
7255 <h5>Examples:</h5>
7256 <pre>
7257 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
7258 %ptr      = bitcast i8* %mallocP to i32*
7259             store i32 0x0F0F, %ptr
7260 %result0  = call i32 @llvm.atomic.load.nand.i32.p0i32( i32* %ptr, i32 0xFF )
7261                                 <i>; yields {i32}:result0 = 0x0F0F</i>
7262 %result1  = call i32 @llvm.atomic.load.and.i32.p0i32( i32* %ptr, i32 0xFF )
7263                                 <i>; yields {i32}:result1 = 0xFFFFFFF0</i>
7264 %result2  = call i32 @llvm.atomic.load.or.i32.p0i32( i32* %ptr, i32 0F )
7265                                 <i>; yields {i32}:result2 = 0xF0</i>
7266 %result3  = call i32 @llvm.atomic.load.xor.i32.p0i32( i32* %ptr, i32 0F )
7267                                 <i>; yields {i32}:result3 = FF</i>
7268 %memval1  = load i32* %ptr      <i>; yields {i32}:memval1 = F0</i>
7269 </pre>
7270
7271 </div>
7272
7273 <!-- _______________________________________________________________________ -->
7274 <div class="doc_subsubsection">
7275   <a name="int_atomic_load_max">'<tt>llvm.atomic.load.max.*</tt>' Intrinsic</a><br>
7276   <a name="int_atomic_load_min">'<tt>llvm.atomic.load.min.*</tt>' Intrinsic</a><br>
7277   <a name="int_atomic_load_umax">'<tt>llvm.atomic.load.umax.*</tt>' Intrinsic</a><br>
7278   <a name="int_atomic_load_umin">'<tt>llvm.atomic.load.umin.*</tt>' Intrinsic</a><br>
7279 </div>
7280
7281 <div class="doc_text">
7282
7283 <h5>Syntax:</h5>
7284 <p>These are overloaded intrinsics. You can use <tt>llvm.atomic.load_max</tt>,
7285    <tt>llvm.atomic.load_min</tt>, <tt>llvm.atomic.load_umax</tt>, and
7286    <tt>llvm.atomic.load_umin</tt> on any integer bit width and for different
7287    address spaces. Not all targets support all bit widths however.</p>
7288
7289 <pre>
7290   declare i8 @llvm.atomic.load.max.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
7291   declare i16 @llvm.atomic.load.max.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
7292   declare i32 @llvm.atomic.load.max.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
7293   declare i64 @llvm.atomic.load.max.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
7294 </pre>
7295
7296 <pre>
7297   declare i8 @llvm.atomic.load.min.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
7298   declare i16 @llvm.atomic.load.min.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
7299   declare i32 @llvm.atomic.load.min.i32..p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
7300   declare i64 @llvm.atomic.load.min.i64..p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
7301 </pre>
7302
7303 <pre>
7304   declare i8 @llvm.atomic.load.umax.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
7305   declare i16 @llvm.atomic.load.umax.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
7306   declare i32 @llvm.atomic.load.umax.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
7307   declare i64 @llvm.atomic.load.umax.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
7308 </pre>
7309
7310 <pre>
7311   declare i8 @llvm.atomic.load.umin.i8..p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
7312   declare i16 @llvm.atomic.load.umin.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
7313   declare i32 @llvm.atomic.load.umin.i32..p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
7314   declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
7315 </pre>
7316
7317 <h5>Overview:</h5>
7318 <p>These intrinsics takes the signed or unsigned minimum or maximum of
7319    <tt>delta</tt> and the value stored in memory at <tt>ptr</tt>. It yields the
7320    original value at <tt>ptr</tt>.</p>
7321
7322 <h5>Arguments:</h5>
7323 <p>These intrinsics take two arguments, the first a pointer to an integer value
7324    and the second an integer value. The result is also an integer value. These
7325    integer types can have any bit width, but they must all have the same bit
7326    width. The targets may only lower integer representations they support.</p>
7327
7328 <h5>Semantics:</h5>
7329 <p>These intrinsics does a series of operations atomically. They first load the
7330    value stored at <tt>ptr</tt>. They then do the signed or unsigned min or
7331    max <tt>delta</tt> and the value, store the result to <tt>ptr</tt>. They
7332    yield the original value stored at <tt>ptr</tt>.</p>
7333
7334 <h5>Examples:</h5>
7335 <pre>
7336 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
7337 %ptr      = bitcast i8* %mallocP to i32*
7338             store i32 7, %ptr
7339 %result0  = call i32 @llvm.atomic.load.min.i32.p0i32( i32* %ptr, i32 -2 )
7340                                 <i>; yields {i32}:result0 = 7</i>
7341 %result1  = call i32 @llvm.atomic.load.max.i32.p0i32( i32* %ptr, i32 8 )
7342                                 <i>; yields {i32}:result1 = -2</i>
7343 %result2  = call i32 @llvm.atomic.load.umin.i32.p0i32( i32* %ptr, i32 10 )
7344                                 <i>; yields {i32}:result2 = 8</i>
7345 %result3  = call i32 @llvm.atomic.load.umax.i32.p0i32( i32* %ptr, i32 30 )
7346                                 <i>; yields {i32}:result3 = 8</i>
7347 %memval1  = load i32* %ptr      <i>; yields {i32}:memval1 = 30</i>
7348 </pre>
7349
7350 </div>
7351
7352
7353 <!-- ======================================================================= -->
7354 <div class="doc_subsection">
7355   <a name="int_memorymarkers">Memory Use Markers</a>
7356 </div>
7357
7358 <div class="doc_text">
7359
7360 <p>This class of intrinsics exists to information about the lifetime of memory
7361    objects and ranges where variables are immutable.</p>
7362
7363 </div>
7364
7365 <!-- _______________________________________________________________________ -->
7366 <div class="doc_subsubsection">
7367   <a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a>
7368 </div>
7369
7370 <div class="doc_text">
7371
7372 <h5>Syntax:</h5>
7373 <pre>
7374   declare void @llvm.lifetime.start(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
7375 </pre>
7376
7377 <h5>Overview:</h5>
7378 <p>The '<tt>llvm.lifetime.start</tt>' intrinsic specifies the start of a memory
7379    object's lifetime.</p>
7380
7381 <h5>Arguments:</h5>
7382 <p>The first argument is a constant integer representing the size of the
7383    object, or -1 if it is variable sized.  The second argument is a pointer to
7384    the object.</p>
7385
7386 <h5>Semantics:</h5>
7387 <p>This intrinsic indicates that before this point in the code, the value of the
7388    memory pointed to by <tt>ptr</tt> is dead.  This means that it is known to
7389    never be used and has an undefined value.  A load from the pointer that
7390    precedes this intrinsic can be replaced with
7391    <tt>'<a href="#undefvalues">undef</a>'</tt>.</p>
7392
7393 </div>
7394
7395 <!-- _______________________________________________________________________ -->
7396 <div class="doc_subsubsection">
7397   <a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a>
7398 </div>
7399
7400 <div class="doc_text">
7401
7402 <h5>Syntax:</h5>
7403 <pre>
7404   declare void @llvm.lifetime.end(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
7405 </pre>
7406
7407 <h5>Overview:</h5>
7408 <p>The '<tt>llvm.lifetime.end</tt>' intrinsic specifies the end of a memory
7409    object's lifetime.</p>
7410
7411 <h5>Arguments:</h5>
7412 <p>The first argument is a constant integer representing the size of the
7413    object, or -1 if it is variable sized.  The second argument is a pointer to
7414    the object.</p>
7415
7416 <h5>Semantics:</h5>
7417 <p>This intrinsic indicates that after this point in the code, the value of the
7418    memory pointed to by <tt>ptr</tt> is dead.  This means that it is known to
7419    never be used and has an undefined value.  Any stores into the memory object
7420    following this intrinsic may be removed as dead.
7421
7422 </div>
7423
7424 <!-- _______________________________________________________________________ -->
7425 <div class="doc_subsubsection">
7426   <a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a>
7427 </div>
7428
7429 <div class="doc_text">
7430
7431 <h5>Syntax:</h5>
7432 <pre>
7433   declare {}* @llvm.invariant.start(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;) readonly
7434 </pre>
7435
7436 <h5>Overview:</h5>
7437 <p>The '<tt>llvm.invariant.start</tt>' intrinsic specifies that the contents of
7438    a memory object will not change.</p>
7439
7440 <h5>Arguments:</h5>
7441 <p>The first argument is a constant integer representing the size of the
7442    object, or -1 if it is variable sized.  The second argument is a pointer to
7443    the object.</p>
7444
7445 <h5>Semantics:</h5>
7446 <p>This intrinsic indicates that until an <tt>llvm.invariant.end</tt> that uses
7447    the return value, the referenced memory location is constant and
7448    unchanging.</p>
7449
7450 </div>
7451
7452 <!-- _______________________________________________________________________ -->
7453 <div class="doc_subsubsection">
7454   <a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a>
7455 </div>
7456
7457 <div class="doc_text">
7458
7459 <h5>Syntax:</h5>
7460 <pre>
7461   declare void @llvm.invariant.end({}* &lt;start&gt;, i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
7462 </pre>
7463
7464 <h5>Overview:</h5>
7465 <p>The '<tt>llvm.invariant.end</tt>' intrinsic specifies that the contents of
7466    a memory object are mutable.</p>
7467
7468 <h5>Arguments:</h5>
7469 <p>The first argument is the matching <tt>llvm.invariant.start</tt> intrinsic.
7470    The second argument is a constant integer representing the size of the
7471    object, or -1 if it is variable sized and the third argument is a pointer
7472    to the object.</p>
7473
7474 <h5>Semantics:</h5>
7475 <p>This intrinsic indicates that the memory is mutable again.</p>
7476
7477 </div>
7478
7479 <!-- ======================================================================= -->
7480 <div class="doc_subsection">
7481   <a name="int_general">General Intrinsics</a>
7482 </div>
7483
7484 <div class="doc_text">
7485
7486 <p>This class of intrinsics is designed to be generic and has no specific
7487    purpose.</p>
7488
7489 </div>
7490
7491 <!-- _______________________________________________________________________ -->
7492 <div class="doc_subsubsection">
7493   <a name="int_var_annotation">'<tt>llvm.var.annotation</tt>' Intrinsic</a>
7494 </div>
7495
7496 <div class="doc_text">
7497
7498 <h5>Syntax:</h5>
7499 <pre>
7500   declare void @llvm.var.annotation(i8* &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7501 </pre>
7502
7503 <h5>Overview:</h5>
7504 <p>The '<tt>llvm.var.annotation</tt>' intrinsic.</p>
7505
7506 <h5>Arguments:</h5>
7507 <p>The first argument is a pointer to a value, the second is a pointer to a
7508    global string, the third is a pointer to a global string which is the source
7509    file name, and the last argument is the line number.</p>
7510
7511 <h5>Semantics:</h5>
7512 <p>This intrinsic allows annotation of local variables with arbitrary strings.
7513    This can be useful for special purpose optimizations that want to look for
7514    these annotations.  These have no other defined use, they are ignored by code
7515    generation and optimization.</p>
7516
7517 </div>
7518
7519 <!-- _______________________________________________________________________ -->
7520 <div class="doc_subsubsection">
7521   <a name="int_annotation">'<tt>llvm.annotation.*</tt>' Intrinsic</a>
7522 </div>
7523
7524 <div class="doc_text">
7525
7526 <h5>Syntax:</h5>
7527 <p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on
7528    any integer bit width.</p>
7529
7530 <pre>
7531   declare i8 @llvm.annotation.i8(i8 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7532   declare i16 @llvm.annotation.i16(i16 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7533   declare i32 @llvm.annotation.i32(i32 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7534   declare i64 @llvm.annotation.i64(i64 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7535   declare i256 @llvm.annotation.i256(i256 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7536 </pre>
7537
7538 <h5>Overview:</h5>
7539 <p>The '<tt>llvm.annotation</tt>' intrinsic.</p>
7540
7541 <h5>Arguments:</h5>
7542 <p>The first argument is an integer value (result of some expression), the
7543    second is a pointer to a global string, the third is a pointer to a global
7544    string which is the source file name, and the last argument is the line
7545    number.  It returns the value of the first argument.</p>
7546
7547 <h5>Semantics:</h5>
7548 <p>This intrinsic allows annotations to be put on arbitrary expressions with
7549    arbitrary strings.  This can be useful for special purpose optimizations that
7550    want to look for these annotations.  These have no other defined use, they
7551    are ignored by code generation and optimization.</p>
7552
7553 </div>
7554
7555 <!-- _______________________________________________________________________ -->
7556 <div class="doc_subsubsection">
7557   <a name="int_trap">'<tt>llvm.trap</tt>' Intrinsic</a>
7558 </div>
7559
7560 <div class="doc_text">
7561
7562 <h5>Syntax:</h5>
7563 <pre>
7564   declare void @llvm.trap()
7565 </pre>
7566
7567 <h5>Overview:</h5>
7568 <p>The '<tt>llvm.trap</tt>' intrinsic.</p>
7569
7570 <h5>Arguments:</h5>
7571 <p>None.</p>
7572
7573 <h5>Semantics:</h5>
7574 <p>This intrinsics is lowered to the target dependent trap instruction. If the
7575    target does not have a trap instruction, this intrinsic will be lowered to
7576    the call of the <tt>abort()</tt> function.</p>
7577
7578 </div>
7579
7580 <!-- _______________________________________________________________________ -->
7581 <div class="doc_subsubsection">
7582   <a name="int_stackprotector">'<tt>llvm.stackprotector</tt>' Intrinsic</a>
7583 </div>
7584
7585 <div class="doc_text">
7586
7587 <h5>Syntax:</h5>
7588 <pre>
7589   declare void @llvm.stackprotector( i8* &lt;guard&gt;, i8** &lt;slot&gt; )
7590 </pre>
7591
7592 <h5>Overview:</h5>
7593 <p>The <tt>llvm.stackprotector</tt> intrinsic takes the <tt>guard</tt> and
7594    stores it onto the stack at <tt>slot</tt>. The stack slot is adjusted to
7595    ensure that it is placed on the stack before local variables.</p>
7596
7597 <h5>Arguments:</h5>
7598 <p>The <tt>llvm.stackprotector</tt> intrinsic requires two pointer
7599    arguments. The first argument is the value loaded from the stack
7600    guard <tt>@__stack_chk_guard</tt>. The second variable is an <tt>alloca</tt>
7601    that has enough space to hold the value of the guard.</p>
7602
7603 <h5>Semantics:</h5>
7604 <p>This intrinsic causes the prologue/epilogue inserter to force the position of
7605    the <tt>AllocaInst</tt> stack slot to be before local variables on the
7606    stack. This is to ensure that if a local variable on the stack is
7607    overwritten, it will destroy the value of the guard. When the function exits,
7608    the guard on the stack is checked against the original guard. If they're
7609    different, then the program aborts by calling the <tt>__stack_chk_fail()</tt>
7610    function.</p>
7611
7612 </div>
7613
7614 <!-- _______________________________________________________________________ -->
7615 <div class="doc_subsubsection">
7616   <a name="int_objectsize">'<tt>llvm.objectsize</tt>' Intrinsic</a>
7617 </div>
7618
7619 <div class="doc_text">
7620
7621 <h5>Syntax:</h5>
7622 <pre>
7623   declare i32 @llvm.objectsize.i32( i8* &lt;object&gt;, i1 &lt;type&gt; )
7624   declare i64 @llvm.objectsize.i64( i8* &lt;object&gt;, i1 &lt;type&gt; )
7625 </pre>
7626
7627 <h5>Overview:</h5>
7628 <p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information
7629    to the optimizers to discover at compile time either a) when an
7630    operation like memcpy will either overflow a buffer that corresponds to
7631    an object, or b) to determine that a runtime check for overflow isn't
7632    necessary. An object in this context means an allocation of a
7633    specific class, structure, array, or other object.</p>
7634
7635 <h5>Arguments:</h5>
7636 <p>The <tt>llvm.objectsize</tt> intrinsic takes two arguments.  The first
7637    argument is a pointer to or into the <tt>object</tt>. The second argument
7638    is a boolean 0 or 1.  This argument determines whether you want the
7639    maximum (0) or minimum (1) bytes remaining.  This needs to be a literal 0 or
7640    1, variables are not allowed.</p>
7641
7642 <h5>Semantics:</h5>
7643 <p>The <tt>llvm.objectsize</tt> intrinsic is lowered to either a constant
7644    representing the size of the object concerned or <tt>i32/i64 -1 or 0</tt>
7645    (depending on the <tt>type</tt> argument if the size cannot be determined
7646    at compile time.</p>
7647
7648 </div>
7649
7650 <!-- *********************************************************************** -->
7651 <hr>
7652 <address>
7653   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
7654   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
7655   <a href="http://validator.w3.org/check/referer"><img
7656   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
7657
7658   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
7659   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
7660   Last modified: $Date$
7661 </address>
7662
7663 </body>
7664 </html>