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="#paramattrs">Parameter Attributes</a></li>
  47       <li><a href="#fnattrs">Function Attributes</a></li>
  48       <li><a href="#gc">Garbage Collector Names</a></li>
  49       <li><a href="#moduleasm">Module-Level Inline Assembly</a></li>
  50       <li><a href="#datalayout">Data Layout</a></li>
  51       <li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li>
  52     </ol>
  53   </li>
  54   <li><a href="#typesystem">Type System</a>
  55     <ol>
  56       <li><a href="#t_classifications">Type Classifications</a></li>
  57       <li><a href="#t_primitive">Primitive Types</a>
  58         <ol>
  59           <li><a href="#t_integer">Integer Type</a></li>
  60           <li><a href="#t_floating">Floating Point Types</a></li>
  61           <li><a href="#t_void">Void Type</a></li>
  62           <li><a href="#t_label">Label Type</a></li>
  63           <li><a href="#t_metadata">Metadata Type</a></li>
  64         </ol>
  65       </li>
  66       <li><a href="#t_derived">Derived Types</a>
  67         <ol>
  68           <li><a href="#t_array">Array Type</a></li>
  69           <li><a href="#t_function">Function Type</a></li>
  70           <li><a href="#t_pointer">Pointer Type</a></li>
  71           <li><a href="#t_struct">Structure Type</a></li>
  72           <li><a href="#t_pstruct">Packed Structure Type</a></li>
  73           <li><a href="#t_vector">Vector Type</a></li>
  74           <li><a href="#t_opaque">Opaque Type</a></li>
  75         </ol>
  76       </li>
  77       <li><a href="#t_uprefs">Type Up-references</a></li>
  78     </ol>
  79   </li>
  80   <li><a href="#constants">Constants</a>
  81     <ol>
  82       <li><a href="#simpleconstants">Simple Constants</a></li>
  83       <li><a href="#complexconstants">Complex Constants</a></li>
  84       <li><a href="#globalconstants">Global Variable and Function Addresses</a></li>
  85       <li><a href="#undefvalues">Undefined Values</a></li>
  86       <li><a href="#blockaddress">Addresses of Basic Blocks</a></li>
  87       <li><a href="#constantexprs">Constant Expressions</a></li>
  88       <li><a href="#metadata">Embedded Metadata</a></li>
  89     </ol>
  90   </li>
  91   <li><a href="#othervalues">Other Values</a>
  92     <ol>
  93       <li><a href="#inlineasm">Inline Assembler Expressions</a></li>
  94     </ol>
  95   </li>
  96   <li><a href="#intrinsic_globals">Intrinsic Global Variables</a>
  97     <ol>
  98       <li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li>
  99       <li><a href="#intg_compiler_used">The '<tt>llvm.compiler.used</tt>'
 100           Global Variable</a></li>
 101       <li><a href="#intg_global_ctors">The '<tt>llvm.global_ctors</tt>'
 102          Global Variable</a></li>
 103       <li><a href="#intg_global_dtors">The '<tt>llvm.global_dtors</tt>'
 104          Global Variable</a></li>
 105     </ol>
 106   </li>
 107   <li><a href="#instref">Instruction Reference</a>
 108     <ol>
 109       <li><a href="#terminators">Terminator Instructions</a>
 110         <ol>
 111           <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li>
 112           <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
 113           <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
 114           <li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li>
 115           <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
 116           <li><a href="#i_unwind">'<tt>unwind</tt>'  Instruction</a></li>
 117           <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
 118         </ol>
 119       </li>
 120       <li><a href="#binaryops">Binary Operations</a>
 121         <ol>
 122           <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li>
 123           <li><a href="#i_fadd">'<tt>fadd</tt>' Instruction</a></li>
 124           <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li>
 125           <li><a href="#i_fsub">'<tt>fsub</tt>' Instruction</a></li>
 126           <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li>
 127           <li><a href="#i_fmul">'<tt>fmul</tt>' Instruction</a></li>
 128           <li><a href="#i_udiv">'<tt>udiv</tt>' Instruction</a></li>
 129           <li><a href="#i_sdiv">'<tt>sdiv</tt>' Instruction</a></li>
 130           <li><a href="#i_fdiv">'<tt>fdiv</tt>' Instruction</a></li>
 131           <li><a href="#i_urem">'<tt>urem</tt>' Instruction</a></li>
 132           <li><a href="#i_srem">'<tt>srem</tt>' Instruction</a></li>
 133           <li><a href="#i_frem">'<tt>frem</tt>' Instruction</a></li>
 134         </ol>
 135       </li>
 136       <li><a href="#bitwiseops">Bitwise Binary Operations</a>
 137         <ol>
 138           <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
 139           <li><a href="#i_lshr">'<tt>lshr</tt>' Instruction</a></li>
 140           <li><a href="#i_ashr">'<tt>ashr</tt>' Instruction</a></li>
 141           <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
 142           <li><a href="#i_or">'<tt>or</tt>'  Instruction</a></li>
 143           <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
 144         </ol>
 145       </li>
 146       <li><a href="#vectorops">Vector Operations</a>
 147         <ol>
 148           <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li>
 149           <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li>
 150           <li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li>
 151         </ol>
 152       </li>
 153       <li><a href="#aggregateops">Aggregate Operations</a>
 154         <ol>
 155           <li><a href="#i_extractvalue">'<tt>extractvalue</tt>' Instruction</a></li>
 156           <li><a href="#i_insertvalue">'<tt>insertvalue</tt>' Instruction</a></li>
 157         </ol>
 158       </li>
 159       <li><a href="#memoryops">Memory Access and Addressing Operations</a>
 160         <ol>
 161           <li><a href="#i_alloca">'<tt>alloca</tt>'   Instruction</a></li>
 162          <li><a href="#i_load">'<tt>load</tt>'     Instruction</a></li>
 163          <li><a href="#i_store">'<tt>store</tt>'    Instruction</a></li>
 164          <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
 165         </ol>
 166       </li>
 167       <li><a href="#convertops">Conversion Operations</a>
 168         <ol>
 169           <li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li>
 170           <li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li>
 171           <li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li>
 172           <li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li>
 173           <li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li>
 174           <li><a href="#i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a></li>
 175           <li><a href="#i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a></li>
 176           <li><a href="#i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a></li>
 177           <li><a href="#i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a></li>
 178           <li><a href="#i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a></li>
 179           <li><a href="#i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a></li>
 180           <li><a href="#i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a></li>
 181         </ol>
 182       </li>
 183       <li><a href="#otherops">Other Operations</a>
 184         <ol>
 185           <li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li>
 186           <li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li>
 187           <li><a href="#i_phi">'<tt>phi</tt>'   Instruction</a></li>
 188           <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
 189           <li><a href="#i_call">'<tt>call</tt>'  Instruction</a></li>
 190           <li><a href="#i_va_arg">'<tt>va_arg</tt>'  Instruction</a></li>
 191         </ol>
 192       </li>
 193     </ol>
 194   </li>
 195   <li><a href="#intrinsics">Intrinsic Functions</a>
 196     <ol>
 197       <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
 198         <ol>
 199           <li><a href="#int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
 200           <li><a href="#int_va_end">'<tt>llvm.va_end</tt>'   Intrinsic</a></li>
 201           <li><a href="#int_va_copy">'<tt>llvm.va_copy</tt>'  Intrinsic</a></li>
 202         </ol>
 203       </li>
 204       <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a>
 205         <ol>
 206           <li><a href="#int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
 207           <li><a href="#int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
 208           <li><a href="#int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
 209         </ol>
 210       </li>
 211       <li><a href="#int_codegen">Code Generator Intrinsics</a>
 212         <ol>
 213           <li><a href="#int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
 214           <li><a href="#int_frameaddress">'<tt>llvm.frameaddress</tt>'   Intrinsic</a></li>
 215           <li><a href="#int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a></li>
 216           <li><a href="#int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li>
 217           <li><a href="#int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
 218           <li><a href="#int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
 219           <li><a href="#int_readcyclecounter"><tt>llvm.readcyclecounter</tt>' Intrinsic</a></li>
 220         </ol>
 221       </li>
 222       <li><a href="#int_libc">Standard C Library Intrinsics</a>
 223         <ol>
 224           <li><a href="#int_memcpy">'<tt>llvm.memcpy.*</tt>' Intrinsic</a></li>
 225           <li><a href="#int_memmove">'<tt>llvm.memmove.*</tt>' Intrinsic</a></li>
 226           <li><a href="#int_memset">'<tt>llvm.memset.*</tt>' Intrinsic</a></li>
 227           <li><a href="#int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a></li>
 228           <li><a href="#int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a></li>
 229           <li><a href="#int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a></li>
 230           <li><a href="#int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a></li>
 231           <li><a href="#int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a></li>
 232         </ol>
 233       </li>
 234       <li><a href="#int_manip">Bit Manipulation Intrinsics</a>
 235         <ol>
 236           <li><a href="#int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a></li>
 237           <li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li>
 238           <li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li>
 239           <li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li>
 240         </ol>
 241       </li>
 242       <li><a href="#int_overflow">Arithmetic with Overflow Intrinsics</a>
 243         <ol>
 244           <li><a href="#int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt> Intrinsics</a></li>
 245           <li><a href="#int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt> Intrinsics</a></li>
 246           <li><a href="#int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt> Intrinsics</a></li>
 247           <li><a href="#int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt> Intrinsics</a></li>
 248           <li><a href="#int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt> Intrinsics</a></li>
 249           <li><a href="#int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt> Intrinsics</a></li>
 250         </ol>
 251       </li>
 252       <li><a href="#int_debugger">Debugger intrinsics</a></li>
 253       <li><a href="#int_eh">Exception Handling intrinsics</a></li>
 254       <li><a href="#int_trampoline">Trampoline Intrinsic</a>
 255         <ol>
 256           <li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li>
 257         </ol>
 258       </li>
 259       <li><a href="#int_atomics">Atomic intrinsics</a>
 260         <ol>
 261           <li><a href="#int_memory_barrier"><tt>llvm.memory_barrier</tt></a></li>
 262           <li><a href="#int_atomic_cmp_swap"><tt>llvm.atomic.cmp.swap</tt></a></li>
 263           <li><a href="#int_atomic_swap"><tt>llvm.atomic.swap</tt></a></li>
 264           <li><a href="#int_atomic_load_add"><tt>llvm.atomic.load.add</tt></a></li>
 265           <li><a href="#int_atomic_load_sub"><tt>llvm.atomic.load.sub</tt></a></li>
 266           <li><a href="#int_atomic_load_and"><tt>llvm.atomic.load.and</tt></a></li>
 267           <li><a href="#int_atomic_load_nand"><tt>llvm.atomic.load.nand</tt></a></li>
 268           <li><a href="#int_atomic_load_or"><tt>llvm.atomic.load.or</tt></a></li>
 269           <li><a href="#int_atomic_load_xor"><tt>llvm.atomic.load.xor</tt></a></li>
 270           <li><a href="#int_atomic_load_max"><tt>llvm.atomic.load.max</tt></a></li>
 271           <li><a href="#int_atomic_load_min"><tt>llvm.atomic.load.min</tt></a></li>
 272           <li><a href="#int_atomic_load_umax"><tt>llvm.atomic.load.umax</tt></a></li>
 273           <li><a href="#int_atomic_load_umin"><tt>llvm.atomic.load.umin</tt></a></li>
 274         </ol>
 275       </li>
 276       <li><a href="#int_memorymarkers">Memory Use Markers</a>
 277         <ol>
 278           <li><a href="#int_lifetime_start"><tt>llvm.lifetime.start</tt></a></li>
 279           <li><a href="#int_lifetime_end"><tt>llvm.lifetime.end</tt></a></li>
 280           <li><a href="#int_invariant_start"><tt>llvm.invariant.start</tt></a></li>
 281           <li><a href="#int_invariant_end"><tt>llvm.invariant.end</tt></a></li>
 282         </ol>
 283       </li>
 284       <li><a href="#int_general">General intrinsics</a>
 285         <ol>
 286           <li><a href="#int_var_annotation">
 287             '<tt>llvm.var.annotation</tt>' Intrinsic</a></li>
 288           <li><a href="#int_annotation">
 289             '<tt>llvm.annotation.*</tt>' Intrinsic</a></li>
 290           <li><a href="#int_trap">
 291             '<tt>llvm.trap</tt>' Intrinsic</a></li>
 292           <li><a href="#int_stackprotector">
 293             '<tt>llvm.stackprotector</tt>' Intrinsic</a></li>
 294           <li><a href="#int_objectsize">
 295             '<tt>llvm.objectsize</tt>' Intrinsic</a></li>
 296         </ol>
 297       </li>
 298     </ol>
 299   </li>
 300 </ol>
 301
 302 <div class="doc_author">
 303   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
 304             and <a href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></p>
 305 </div>
 306
 307 <!-- *********************************************************************** -->
 308 <div class="doc_section"> <a name="abstract">Abstract </a></div>
 309 <!-- *********************************************************************** -->
 310
 311 <div class="doc_text">
 312
 313 <p>This document is a reference manual for the LLVM assembly language. LLVM is
 314    a Static Single Assignment (SSA) based representation that provides type
 315    safety, low-level operations, flexibility, and the capability of representing
 316    'all' high-level languages cleanly.  It is the common code representation
 317    used throughout all phases of the LLVM compilation strategy.</p>
 318
 319 </div>
 320
 321 <!-- *********************************************************************** -->
 322 <div class="doc_section"> <a name="introduction">Introduction</a> </div>
 323 <!-- *********************************************************************** -->
 324
 325 <div class="doc_text">
 326
 327 <p>The LLVM code representation is designed to be used in three different forms:
 328    as an in-memory compiler IR, as an on-disk bitcode representation (suitable
 329    for fast loading by a Just-In-Time compiler), and as a human readable
 330    assembly language representation.  This allows LLVM to provide a powerful
 331    intermediate representation for efficient compiler transformations and
 332    analysis, while providing a natural means to debug and visualize the
 333    transformations.  The three different forms of LLVM are all equivalent.  This
 334    document describes the human readable representation and notation.</p>
 335
 336 <p>The LLVM representation aims to be light-weight and low-level while being
 337    expressive, typed, and extensible at the same time.  It aims to be a
 338    "universal IR" of sorts, by being at a low enough level that high-level ideas
 339    may be cleanly mapped to it (similar to how microprocessors are "universal
 340    IR's", allowing many source languages to be mapped to them).  By providing
 341    type information, LLVM can be used as the target of optimizations: for
 342    example, through pointer analysis, it can be proven that a C automatic
 343    variable is never accessed outside of the current function, allowing it to
 344    be promoted to a simple SSA value instead of a memory location.</p>
 345
 346 </div>
 347
 348 <!-- _______________________________________________________________________ -->
 349 <div class="doc_subsubsection"> <a name="wellformed">Well-Formedness</a> </div>
 350
 351 <div class="doc_text">
 352
 353 <p>It is important to note that this document describes 'well formed' LLVM
 354    assembly language.  There is a difference between what the parser accepts and
 355    what is considered 'well formed'.  For example, the following instruction is
 356    syntactically okay, but not well formed:</p>
 357
 358 <div class="doc_code">
 359 <pre>
 360 %x = <a href="#i_add">add</a> i32 1, %x
 361 </pre>
 362 </div>
 363
 364 <p>because the definition of <tt>%x</tt> does not dominate all of its uses. The
 365    LLVM infrastructure provides a verification pass that may be used to verify
 366    that an LLVM module is well formed.  This pass is automatically run by the
 367    parser after parsing input assembly and by the optimizer before it outputs
 368    bitcode.  The violations pointed out by the verifier pass indicate bugs in
 369    transformation passes or input to the parser.</p>
 370
 371 </div>
 372
 373 <!-- Describe the typesetting conventions here. -->
 374
 375 <!-- *********************************************************************** -->
 376 <div class="doc_section"> <a name="identifiers">Identifiers</a> </div>
 377 <!-- *********************************************************************** -->
 378
 379 <div class="doc_text">
 380
 381 <p>LLVM identifiers come in two basic types: global and local. Global
 382    identifiers (functions, global variables) begin with the <tt>'@'</tt>
 383    character. Local identifiers (register names, types) begin with
 384    the <tt>'%'</tt> character. Additionally, there are three different formats
 385    for identifiers, for different purposes:</p>
 386
 387 <ol>
 388   <li>Named values are represented as a string of characters with their prefix.
 389       For example, <tt>%foo</tt>, <tt>@DivisionByZero</tt>,
 390       <tt>%a.really.long.identifier</tt>. The actual regular expression used is
 391       '<tt>[%@][a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.  Identifiers which require
 392       other characters in their names can be surrounded with quotes. Special
 393       characters may be escaped using <tt>"\xx"</tt> where <tt>xx</tt> is the
 394       ASCII code for the character in hexadecimal.  In this way, any character
 395       can be used in a name value, even quotes themselves.</li>
 396
 397   <li>Unnamed values are represented as an unsigned numeric value with their
 398       prefix.  For example, <tt>%12</tt>, <tt>@2</tt>, <tt>%44</tt>.</li>
 399
 400   <li>Constants, which are described in a <a href="#constants">section about
 401       constants</a>, below.</li>
 402 </ol>
 403
 404 <p>LLVM requires that values start with a prefix for two reasons: Compilers
 405    don't need to worry about name clashes with reserved words, and the set of
 406    reserved words may be expanded in the future without penalty.  Additionally,
 407    unnamed identifiers allow a compiler to quickly come up with a temporary
 408    variable without having to avoid symbol table conflicts.</p>
 409
 410 <p>Reserved words in LLVM are very similar to reserved words in other
 411    languages. There are keywords for different opcodes
 412    ('<tt><a href="#i_add">add</a></tt>',
 413    '<tt><a href="#i_bitcast">bitcast</a></tt>',
 414    '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names
 415    ('<tt><a href="#t_void">void</a></tt>',
 416    '<tt><a href="#t_primitive">i32</a></tt>', etc...), and others.  These
 417    reserved words cannot conflict with variable names, because none of them
 418    start with a prefix character (<tt>'%'</tt> or <tt>'@'</tt>).</p>
 419
 420 <p>Here is an example of LLVM code to multiply the integer variable
 421    '<tt>%X</tt>' by 8:</p>
 422
 423 <p>The easy way:</p>
 424
 425 <div class="doc_code">
 426 <pre>
 427 %result = <a href="#i_mul">mul</a> i32 %X, 8
 428 </pre>
 429 </div>
 430
 431 <p>After strength reduction:</p>
 432
 433 <div class="doc_code">
 434 <pre>
 435 %result = <a href="#i_shl">shl</a> i32 %X, i8 3
 436 </pre>
 437 </div>
 438
 439 <p>And the hard way:</p>
 440
 441 <div class="doc_code">
 442 <pre>
 443 %0 = <a href="#i_add">add</a> i32 %X, %X           <i>; yields {i32}:%0</i>
 444 %1 = <a href="#i_add">add</a> i32 %0, %0           <i>; yields {i32}:%1</i>
 445 %result = <a href="#i_add">add</a> i32 %1, %1
 446 </pre>
 447 </div>
 448
 449 <p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important
 450    lexical features of LLVM:</p>
 451
 452 <ol>
 453   <li>Comments are delimited with a '<tt>;</tt>' and go until the end of
 454       line.</li>
 455
 456   <li>Unnamed temporaries are created when the result of a computation is not
 457       assigned to a named value.</li>
 458
 459   <li>Unnamed temporaries are numbered sequentially</li>
 460 </ol>
 461
 462 <p>It also shows a convention that we follow in this document.  When
 463    demonstrating instructions, we will follow an instruction with a comment that
 464    defines the type and name of value produced.  Comments are shown in italic
 465    text.</p>
 466
 467 </div>
 468
 469 <!-- *********************************************************************** -->
 470 <div class="doc_section"> <a name="highlevel">High Level Structure</a> </div>
 471 <!-- *********************************************************************** -->
 472
 473 <!-- ======================================================================= -->
 474 <div class="doc_subsection"> <a name="modulestructure">Module Structure</a>
 475 </div>
 476
 477 <div class="doc_text">
 478
 479 <p>LLVM programs are composed of "Module"s, each of which is a translation unit
 480    of the input programs.  Each module consists of functions, global variables,
 481    and symbol table entries.  Modules may be combined together with the LLVM
 482    linker, which merges function (and global variable) definitions, resolves
 483    forward declarations, and merges symbol table entries. Here is an example of
 484    the "hello world" module:</p>
 485
 486 <div class="doc_code">
 487 <pre>
 488 <i>; Declare the string constant as a global constant.</i>
 489 <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>
 490
 491 <i>; External declaration of the puts function</i>
 492 <a href="#functionstructure">declare</a> i32 @puts(i8 *)                                     <i>; i32(i8 *)* </i>
 493
 494 <i>; Definition of main function</i>
 495 define i32 @main() {                                        <i>; i32()* </i>
 496   <i>; Convert [13 x i8]* to i8  *...</i>
 497   %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0   <i>; i8 *</i>
 498
 499   <i>; Call puts function to write out the string to stdout.</i>
 500   <a href="#i_call">call</a> i32 @puts(i8 * %cast210)                             <i>; i32</i>
 501   <a href="#i_ret">ret</a> i32 0<br>}<br>
 502 </pre>
 503 </div>
 504
 505 <p>This example is made up of a <a href="#globalvars">global variable</a> named
 506    "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, and
 507    a <a href="#functionstructure">function definition</a> for
 508    "<tt>main</tt>".</p>
 509
 510 <p>In general, a module is made up of a list of global values, where both
 511    functions and global variables are global values.  Global values are
 512    represented by a pointer to a memory location (in this case, a pointer to an
 513    array of char, and a pointer to a function), and have one of the
 514    following <a href="#linkage">linkage types</a>.</p>
 515
 516 </div>
 517
 518 <!-- ======================================================================= -->
 519 <div class="doc_subsection">
 520   <a name="linkage">Linkage Types</a>
 521 </div>
 522
 523 <div class="doc_text">
 524
 525 <p>All Global Variables and Functions have one of the following types of
 526    linkage:</p>
 527
 528 <dl>
 529   <dt><tt><b><a name="linkage_private">private</a></b></tt></dt>
 530   <dd>Global values with private linkage are only directly accessible by objects
 531       in the current module.  In particular, linking code into a module with an
 532       private global value may cause the private to be renamed as necessary to
 533       avoid collisions.  Because the symbol is private to the module, all
 534       references can be updated. This doesn't show up in any symbol table in the
 535       object file.</dd>
 536
 537   <dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt></dt>
 538   <dd>Similar to private, but the symbol is passed through the assembler and
 539       removed by the linker after evaluation.  Note that (unlike private
 540       symbols) linker_private symbols are subject to coalescing by the linker:
 541       weak symbols get merged and redefinitions are rejected.  However, unlike
 542       normal strong symbols, they are removed by the linker from the final
 543       linked image (executable or dynamic library).</dd>
 544
 545   <dt><tt><b><a name="linkage_internal">internal</a></b></tt></dt>
 546   <dd>Similar to private, but the value shows as a local symbol
 547       (<tt>STB_LOCAL</tt> in the case of ELF) in the object file. This
 548       corresponds to the notion of the '<tt>static</tt>' keyword in C.</dd>
 549
 550   <dt><tt><b><a name="linkage_available_externally">available_externally</a></b></tt></dt>
 551   <dd>Globals with "<tt>available_externally</tt>" linkage are never emitted
 552       into the object file corresponding to the LLVM module.  They exist to
 553       allow inlining and other optimizations to take place given knowledge of
 554       the definition of the global, which is known to be somewhere outside the
 555       module.  Globals with <tt>available_externally</tt> linkage are allowed to
 556       be discarded at will, and are otherwise the same as <tt>linkonce_odr</tt>.
 557       This linkage type is only allowed on definitions, not declarations.</dd>
 558
 559   <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt></dt>
 560   <dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of
 561       the same name when linkage occurs.  This is typically used to implement
 562       inline functions, templates, or other code which must be generated in each
 563       translation unit that uses it.  Unreferenced <tt>linkonce</tt> globals are
 564       allowed to be discarded.</dd>
 565
 566   <dt><tt><b><a name="linkage_weak">weak</a></b></tt></dt>
 567   <dd>"<tt>weak</tt>" linkage has the same merging semantics as
 568       <tt>linkonce</tt> linkage, except that unreferenced globals with
 569       <tt>weak</tt> linkage may not be discarded.  This is used for globals that
 570       are declared "weak" in C source code.</dd>
 571
 572   <dt><tt><b><a name="linkage_common">common</a></b></tt></dt>
 573   <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but
 574       they are used for tentative definitions in C, such as "<tt>int X;</tt>" at
 575       global scope.
 576       Symbols with "<tt>common</tt>" linkage are merged in the same way as
 577       <tt>weak symbols</tt>, and they may not be deleted if unreferenced.
 578       <tt>common</tt> symbols may not have an explicit section,
 579       must have a zero initializer, and may not be marked '<a
 580       href="#globalvars"><tt>constant</tt></a>'.  Functions and aliases may not
 581       have common linkage.</dd>
 582
 583
 584   <dt><tt><b><a name="linkage_appending">appending</a></b></tt></dt>
 585   <dd>"<tt>appending</tt>" linkage may only be applied to global variables of
 586       pointer to array type.  When two global variables with appending linkage
 587       are linked together, the two global arrays are appended together.  This is
 588       the LLVM, typesafe, equivalent of having the system linker append together
 589       "sections" with identical names when .o files are linked.</dd>
 590
 591   <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt></dt>
 592   <dd>The semantics of this linkage follow the ELF object file model: the symbol
 593       is weak until linked, if not linked, the symbol becomes null instead of
 594       being an undefined reference.</dd>
 595
 596   <dt><tt><b><a name="linkage_linkonce_odr">linkonce_odr</a></b></tt></dt>
 597   <dt><tt><b><a name="linkage_weak_odr">weak_odr</a></b></tt></dt>
 598   <dd>Some languages allow differing globals to be merged, such as two functions
 599       with different semantics.  Other languages, such as <tt>C++</tt>, ensure
 600       that only equivalent globals are ever merged (the "one definition rule" -
 601       "ODR").  Such languages can use the <tt>linkonce_odr</tt>
 602       and <tt>weak_odr</tt> linkage types to indicate that the global will only
 603       be merged with equivalent globals.  These linkage types are otherwise the
 604       same as their non-<tt>odr</tt> versions.</dd>
 605
 606   <dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt>
 607   <dd>If none of the above identifiers are used, the global is externally
 608       visible, meaning that it participates in linkage and can be used to
 609       resolve external symbol references.</dd>
 610 </dl>
 611
 612 <p>The next two types of linkage are targeted for Microsoft Windows platform
 613    only. They are designed to support importing (exporting) symbols from (to)
 614    DLLs (Dynamic Link Libraries).</p>
 615
 616 <dl>
 617   <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt></dt>
 618   <dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function
 619       or variable via a global pointer to a pointer that is set up by the DLL
 620       exporting the symbol. On Microsoft Windows targets, the pointer name is
 621       formed by combining <code>__imp_</code> and the function or variable
 622       name.</dd>
 623
 624   <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt></dt>
 625   <dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global
 626       pointer to a pointer in a DLL, so that it can be referenced with the
 627       <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer
 628       name is formed by combining <code>__imp_</code> and the function or
 629       variable name.</dd>
 630 </dl>
 631
 632 <p>For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
 633    another module defined a "<tt>.LC0</tt>" variable and was linked with this
 634    one, one of the two would be renamed, preventing a collision.  Since
 635    "<tt>main</tt>" and "<tt>puts</tt>" are external (i.e., lacking any linkage
 636    declarations), they are accessible outside of the current module.</p>
 637
 638 <p>It is illegal for a function <i>declaration</i> to have any linkage type
 639    other than "externally visible", <tt>dllimport</tt>
 640    or <tt>extern_weak</tt>.</p>
 641
 642 <p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt>
 643    or <tt>weak_odr</tt> linkages.</p>
 644
 645 </div>
 646
 647 <!-- ======================================================================= -->
 648 <div class="doc_subsection">
 649   <a name="callingconv">Calling Conventions</a>
 650 </div>
 651
 652 <div class="doc_text">
 653
 654 <p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a>
 655    and <a href="#i_invoke">invokes</a> can all have an optional calling
 656    convention specified for the call.  The calling convention of any pair of
 657    dynamic caller/callee must match, or the behavior of the program is
 658    undefined.  The following calling conventions are supported by LLVM, and more
 659    may be added in the future:</p>
 660
 661 <dl>
 662   <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt>
 663   <dd>This calling convention (the default if no other calling convention is
 664       specified) matches the target C calling conventions.  This calling
 665       convention supports varargs function calls and tolerates some mismatch in
 666       the declared prototype and implemented declaration of the function (as
 667       does normal C).</dd>
 668
 669   <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt>
 670   <dd>This calling convention attempts to make calls as fast as possible
 671       (e.g. by passing things in registers).  This calling convention allows the
 672       target to use whatever tricks it wants to produce fast code for the
 673       target, without having to conform to an externally specified ABI
 674       (Application Binary Interface).  Implementations of this convention should
 675       allow arbitrary <a href="CodeGenerator.html#tailcallopt">tail call
 676       optimization</a> to be supported.  This calling convention does not
 677       support varargs and requires the prototype of all callees to exactly match
 678       the prototype of the function definition.</dd>
 679
 680   <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt>
 681   <dd>This calling convention attempts to make code in the caller as efficient
 682       as possible under the assumption that the call is not commonly executed.
 683       As such, these calls often preserve all registers so that the call does
 684       not break any live ranges in the caller side.  This calling convention
 685       does not support varargs and requires the prototype of all callees to
 686       exactly match the prototype of the function definition.</dd>
 687
 688   <dt><b>"<tt>cc &lt;<em>n</em>&gt;</tt>" - Numbered convention</b>:</dt>
 689   <dd>Any calling convention may be specified by number, allowing
 690       target-specific calling conventions to be used.  Target specific calling
 691       conventions start at 64.</dd>
 692 </dl>
 693
 694 <p>More calling conventions can be added/defined on an as-needed basis, to
 695    support Pascal conventions or any other well-known target-independent
 696    convention.</p>
 697
 698 </div>
 699
 700 <!-- ======================================================================= -->
 701 <div class="doc_subsection">
 702   <a name="visibility">Visibility Styles</a>
 703 </div>
 704
 705 <div class="doc_text">
 706
 707 <p>All Global Variables and Functions have one of the following visibility
 708    styles:</p>
 709
 710 <dl>
 711   <dt><b>"<tt>default</tt>" - Default style</b>:</dt>
 712   <dd>On targets that use the ELF object file format, default visibility means
 713       that the declaration is visible to other modules and, in shared libraries,
 714       means that the declared entity may be overridden. On Darwin, default
 715       visibility means that the declaration is visible to other modules. Default
 716       visibility corresponds to "external linkage" in the language.</dd>
 717
 718   <dt><b>"<tt>hidden</tt>" - Hidden style</b>:</dt>
 719   <dd>Two declarations of an object with hidden visibility refer to the same
 720       object if they are in the same shared object. Usually, hidden visibility
 721       indicates that the symbol will not be placed into the dynamic symbol
 722       table, so no other module (executable or shared library) can reference it
 723       directly.</dd>
 724
 725   <dt><b>"<tt>protected</tt>" - Protected style</b>:</dt>
 726   <dd>On ELF, protected visibility indicates that the symbol will be placed in
 727       the dynamic symbol table, but that references within the defining module
 728       will bind to the local symbol. That is, the symbol cannot be overridden by
 729       another module.</dd>
 730 </dl>
 731
 732 </div>
 733
 734 <!-- ======================================================================= -->
 735 <div class="doc_subsection">
 736   <a name="namedtypes">Named Types</a>
 737 </div>
 738
 739 <div class="doc_text">
 740
 741 <p>LLVM IR allows you to specify name aliases for certain types.  This can make
 742    it easier to read the IR and make the IR more condensed (particularly when
 743    recursive types are involved).  An example of a name specification is:</p>
 744
 745 <div class="doc_code">
 746 <pre>
 747 %mytype = type { %mytype*, i32 }
 748 </pre>
 749 </div>
 750
 751 <p>You may give a name to any <a href="#typesystem">type</a> except
 752    "<a href="t_void">void</a>".  Type name aliases may be used anywhere a type
 753    is expected with the syntax "%mytype".</p>
 754
 755 <p>Note that type names are aliases for the structural type that they indicate,
 756    and that you can therefore specify multiple names for the same type.  This
 757    often leads to confusing behavior when dumping out a .ll file.  Since LLVM IR
 758    uses structural typing, the name is not part of the type.  When printing out
 759    LLVM IR, the printer will pick <em>one name</em> to render all types of a
 760    particular shape.  This means that if you have code where two different
 761    source types end up having the same LLVM type, that the dumper will sometimes
 762    print the "wrong" or unexpected type.  This is an important design point and
 763    isn't going to change.</p>
 764
 765 </div>
 766
 767 <!-- ======================================================================= -->
 768 <div class="doc_subsection">
 769   <a name="globalvars">Global Variables</a>
 770 </div>
 771
 772 <div class="doc_text">
 773
 774 <p>Global variables define regions of memory allocated at compilation time
 775    instead of run-time.  Global variables may optionally be initialized, may
 776    have an explicit section to be placed in, and may have an optional explicit
 777    alignment specified.  A variable may be defined as "thread_local", which
 778    means that it will not be shared by threads (each thread will have a
 779    separated copy of the variable).  A variable may be defined as a global
 780    "constant," which indicates that the contents of the variable
 781    will <b>never</b> be modified (enabling better optimization, allowing the
 782    global data to be placed in the read-only section of an executable, etc).
 783    Note that variables that need runtime initialization cannot be marked
 784    "constant" as there is a store to the variable.</p>
 785
 786 <p>LLVM explicitly allows <em>declarations</em> of global variables to be marked
 787    constant, even if the final definition of the global is not.  This capability
 788    can be used to enable slightly better optimization of the program, but
 789    requires the language definition to guarantee that optimizations based on the
 790    'constantness' are valid for the translation units that do not include the
 791    definition.</p>
 792
 793 <p>As SSA values, global variables define pointer values that are in scope
 794    (i.e. they dominate) all basic blocks in the program.  Global variables
 795    always define a pointer to their "content" type because they describe a
 796    region of memory, and all memory objects in LLVM are accessed through
 797    pointers.</p>
 798
 799 <p>A global variable may be declared to reside in a target-specific numbered
 800    address space. For targets that support them, address spaces may affect how
 801    optimizations are performed and/or what target instructions are used to
 802    access the variable. The default address space is zero. The address space
 803    qualifier must precede any other attributes.</p>
 804
 805 <p>LLVM allows an explicit section to be specified for globals.  If the target
 806    supports it, it will emit globals to the section specified.</p>
 807
 808 <p>An explicit alignment may be specified for a global.  If not present, or if
 809    the alignment is set to zero, the alignment of the global is set by the
 810    target to whatever it feels convenient.  If an explicit alignment is
 811    specified, the global is forced to have at least that much alignment.  All
 812    alignments must be a power of 2.</p>
 813
 814 <p>For example, the following defines a global in a numbered address space with
 815    an initializer, section, and alignment:</p>
 816
 817 <div class="doc_code">
 818 <pre>
 819 @G = addrspace(5) constant float 1.0, section "foo", align 4
 820 </pre>
 821 </div>
 822
 823 </div>
 824
 825
 826 <!-- ======================================================================= -->
 827 <div class="doc_subsection">
 828   <a name="functionstructure">Functions</a>
 829 </div>
 830
 831 <div class="doc_text">
 832
 833 <p>LLVM function definitions consist of the "<tt>define</tt>" keyord, an
 834    optional <a href="#linkage">linkage type</a>, an optional
 835    <a href="#visibility">visibility style</a>, an optional
 836    <a href="#callingconv">calling convention</a>, a return type, an optional
 837    <a href="#paramattrs">parameter attribute</a> for the return type, a function
 838    name, a (possibly empty) argument list (each with optional
 839    <a href="#paramattrs">parameter attributes</a>), optional
 840    <a href="#fnattrs">function attributes</a>, an optional section, an optional
 841    alignment, an optional <a href="#gc">garbage collector name</a>, an opening
 842    curly brace, a list of basic blocks, and a closing curly brace.</p>
 843
 844 <p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an
 845    optional <a href="#linkage">linkage type</a>, an optional
 846    <a href="#visibility">visibility style</a>, an optional
 847    <a href="#callingconv">calling convention</a>, a return type, an optional
 848    <a href="#paramattrs">parameter attribute</a> for the return type, a function
 849    name, a possibly empty list of arguments, an optional alignment, and an
 850    optional <a href="#gc">garbage collector name</a>.</p>
 851
 852 <p>A function definition contains a list of basic blocks, forming the CFG
 853    (Control Flow Graph) for the function.  Each basic block may optionally start
 854    with a label (giving the basic block a symbol table entry), contains a list
 855    of instructions, and ends with a <a href="#terminators">terminator</a>
 856    instruction (such as a branch or function return).</p>
 857
 858 <p>The first basic block in a function is special in two ways: it is immediately
 859    executed on entrance to the function, and it is not allowed to have
 860    predecessor basic blocks (i.e. there can not be any branches to the entry
 861    block of a function).  Because the block can have no predecessors, it also
 862    cannot have any <a href="#i_phi">PHI nodes</a>.</p>
 863
 864 <p>LLVM allows an explicit section to be specified for functions.  If the target
 865    supports it, it will emit functions to the section specified.</p>
 866
 867 <p>An explicit alignment may be specified for a function.  If not present, or if
 868    the alignment is set to zero, the alignment of the function is set by the
 869    target to whatever it feels convenient.  If an explicit alignment is
 870    specified, the function is forced to have at least that much alignment.  All
 871    alignments must be a power of 2.</p>
 872
 873 <h5>Syntax:</h5>
 874 <div class="doc_code">
 875 <pre>
 876 define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>]
 877        [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>]
 878        &lt;ResultType&gt; @&lt;FunctionName&gt; ([argument list])
 879        [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N]
 880        [<a href="#gc">gc</a>] { ... }
 881 </pre>
 882 </div>
 883
 884 </div>
 885
 886 <!-- ======================================================================= -->
 887 <div class="doc_subsection">
 888   <a name="aliasstructure">Aliases</a>
 889 </div>
 890
 891 <div class="doc_text">
 892
 893 <p>Aliases act as "second name" for the aliasee value (which can be either
 894    function, global variable, another alias or bitcast of global value). Aliases
 895    may have an optional <a href="#linkage">linkage type</a>, and an
 896    optional <a href="#visibility">visibility style</a>.</p>
 897
 898 <h5>Syntax:</h5>
 899 <div class="doc_code">
 900 <pre>
 901 @&lt;Name&gt; = alias [Linkage] [Visibility] &lt;AliaseeTy&gt; @&lt;Aliasee&gt;
 902 </pre>
 903 </div>
 904
 905 </div>
 906
 907 <!-- ======================================================================= -->
 908 <div class="doc_subsection"><a name="paramattrs">Parameter Attributes</a></div>
 909
 910 <div class="doc_text">
 911
 912 <p>The return type and each parameter of a function type may have a set of
 913    <i>parameter attributes</i> associated with them. Parameter attributes are
 914    used to communicate additional information about the result or parameters of
 915    a function. Parameter attributes are considered to be part of the function,
 916    not of the function type, so functions with different parameter attributes
 917    can have the same function type.</p>
 918
 919 <p>Parameter attributes are simple keywords that follow the type specified. If
 920    multiple parameter attributes are needed, they are space separated. For
 921    example:</p>
 922
 923 <div class="doc_code">
 924 <pre>
 925 declare i32 @printf(i8* noalias nocapture, ...)
 926 declare i32 @atoi(i8 zeroext)
 927 declare signext i8 @returns_signed_char()
 928 </pre>
 929 </div>
 930
 931 <p>Note that any attributes for the function result (<tt>nounwind</tt>,
 932    <tt>readonly</tt>) come immediately after the argument list.</p>
 933
 934 <p>Currently, only the following parameter attributes are defined:</p>
 935
 936 <dl>
 937   <dt><tt><b>zeroext</b></tt></dt>
 938   <dd>This indicates to the code generator that the parameter or return value
 939       should be zero-extended to a 32-bit value by the caller (for a parameter)
 940       or the callee (for a return value).</dd>
 941
 942   <dt><tt><b>signext</b></tt></dt>
 943   <dd>This indicates to the code generator that the parameter or return value
 944       should be sign-extended to a 32-bit value by the caller (for a parameter)
 945       or the callee (for a return value).</dd>
 946
 947   <dt><tt><b>inreg</b></tt></dt>
 948   <dd>This indicates that this parameter or return value should be treated in a
 949       special target-dependent fashion during while emitting code for a function
 950       call or return (usually, by putting it in a register as opposed to memory,
 951       though some targets use it to distinguish between two different kinds of
 952       registers).  Use of this attribute is target-specific.</dd>
 953
 954   <dt><tt><b><a name="byval">byval</a></b></tt></dt>
 955   <dd>This indicates that the pointer parameter should really be passed by value
 956       to the function.  The attribute implies that a hidden copy of the pointee
 957       is made between the caller and the callee, so the callee is unable to
 958       modify the value in the callee.  This attribute is only valid on LLVM
 959       pointer arguments.  It is generally used to pass structs and arrays by
 960       value, but is also valid on pointers to scalars.  The copy is considered
 961       to belong to the caller not the callee (for example,
 962       <tt><a href="#readonly">readonly</a></tt> functions should not write to
 963       <tt>byval</tt> parameters). This is not a valid attribute for return
 964       values.  The byval attribute also supports specifying an alignment with
 965       the align attribute.  This has a target-specific effect on the code
 966       generator that usually indicates a desired alignment for the synthesized
 967       stack slot.</dd>
 968
 969   <dt><tt><b>sret</b></tt></dt>
 970   <dd>This indicates that the pointer parameter specifies the address of a
 971       structure that is the return value of the function in the source program.
 972       This pointer must be guaranteed by the caller to be valid: loads and
 973       stores to the structure may be assumed by the callee to not to trap.  This
 974       may only be applied to the first parameter. This is not a valid attribute
 975       for return values. </dd>
 976
 977   <dt><tt><b>noalias</b></tt></dt>
 978   <dd>This indicates that the pointer does not alias any global or any other
 979       parameter.  The caller is responsible for ensuring that this is the
 980       case. On a function return value, <tt>noalias</tt> additionally indicates
 981       that the pointer does not alias any other pointers visible to the
 982       caller. For further details, please see the discussion of the NoAlias
 983       response in
 984       <a href="http://llvm.org/docs/AliasAnalysis.html#MustMayNo">alias
 985       analysis</a>.</dd>
 986
 987   <dt><tt><b>nocapture</b></tt></dt>
 988   <dd>This indicates that the callee does not make any copies of the pointer
 989       that outlive the callee itself. This is not a valid attribute for return
 990       values.</dd>
 991
 992   <dt><tt><b>nest</b></tt></dt>
 993   <dd>This indicates that the pointer parameter can be excised using the
 994       <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid
 995       attribute for return values.</dd>
 996 </dl>
 997
 998 </div>
 999
1000 <!-- ======================================================================= -->
1001 <div class="doc_subsection">
1002   <a name="gc">Garbage Collector Names</a>
1003 </div>
1004
1005 <div class="doc_text">
1006
1007 <p>Each function may specify a garbage collector name, which is simply a
1008    string:</p>
1009
1010 <div class="doc_code">
1011 <pre>
1012 define void @f() gc "name" { ... }
1013 </pre>
1014 </div>
1015
1016 <p>The compiler declares the supported values of <i>name</i>. Specifying a
1017    collector which will cause the compiler to alter its output in order to
1018    support the named garbage collection algorithm.</p>
1019
1020 </div>
1021
1022 <!-- ======================================================================= -->
1023 <div class="doc_subsection">
1024   <a name="fnattrs">Function Attributes</a>
1025 </div>
1026
1027 <div class="doc_text">
1028
1029 <p>Function attributes are set to communicate additional information about a
1030    function. Function attributes are considered to be part of the function, not
1031    of the function type, so functions with different parameter attributes can
1032    have the same function type.</p>
1033
1034 <p>Function attributes are simple keywords that follow the type specified. If
1035    multiple attributes are needed, they are space separated. For example:</p>
1036
1037 <div class="doc_code">
1038 <pre>
1039 define void @f() noinline { ... }
1040 define void @f() alwaysinline { ... }
1041 define void @f() alwaysinline optsize { ... }
1042 define void @f() optsize { ... }
1043 </pre>
1044 </div>
1045
1046 <dl>
1047   <dt><tt><b>alwaysinline</b></tt></dt>
1048   <dd>This attribute indicates that the inliner should attempt to inline this
1049       function into callers whenever possible, ignoring any active inlining size
1050       threshold for this caller.</dd>
1051
1052   <dt><tt><b>inlinehint</b></tt></dt>
1053   <dd>This attribute indicates that the source code contained a hint that inlining
1054       this function is desirable (such as the "inline" keyword in C/C++).  It
1055       is just a hint; it imposes no requirements on the inliner.</dd>
1056
1057   <dt><tt><b>noinline</b></tt></dt>
1058   <dd>This attribute indicates that the inliner should never inline this
1059       function in any situation. This attribute may not be used together with
1060       the <tt>alwaysinline</tt> attribute.</dd>
1061
1062   <dt><tt><b>optsize</b></tt></dt>
1063   <dd>This attribute suggests that optimization passes and code generator passes
1064       make choices that keep the code size of this function low, and otherwise
1065       do optimizations specifically to reduce code size.</dd>
1066
1067   <dt><tt><b>noreturn</b></tt></dt>
1068   <dd>This function attribute indicates that the function never returns
1069       normally.  This produces undefined behavior at runtime if the function
1070       ever does dynamically return.</dd>
1071
1072   <dt><tt><b>nounwind</b></tt></dt>
1073   <dd>This function attribute indicates that the function never returns with an
1074       unwind or exceptional control flow.  If the function does unwind, its
1075       runtime behavior is undefined.</dd>
1076
1077   <dt><tt><b>readnone</b></tt></dt>
1078   <dd>This attribute indicates that the function computes its result (or decides
1079       to unwind an exception) based strictly on its arguments, without
1080       dereferencing any pointer arguments or otherwise accessing any mutable
1081       state (e.g. memory, control registers, etc) visible to caller functions.
1082       It does not write through any pointer arguments
1083       (including <tt><a href="#byval">byval</a></tt> arguments) and never
1084       changes any state visible to callers.  This means that it cannot unwind
1085       exceptions by calling the <tt>C++</tt> exception throwing methods, but
1086       could use the <tt>unwind</tt> instruction.</dd>
1087
1088   <dt><tt><b><a name="readonly">readonly</a></b></tt></dt>
1089   <dd>This attribute indicates that the function does not write through any
1090       pointer arguments (including <tt><a href="#byval">byval</a></tt>
1091       arguments) or otherwise modify any state (e.g. memory, control registers,
1092       etc) visible to caller functions.  It may dereference pointer arguments
1093       and read state that may be set in the caller.  A readonly function always
1094       returns the same value (or unwinds an exception identically) when called
1095       with the same set of arguments and global state.  It cannot unwind an
1096       exception by calling the <tt>C++</tt> exception throwing methods, but may
1097       use the <tt>unwind</tt> instruction.</dd>
1098
1099   <dt><tt><b><a name="ssp">ssp</a></b></tt></dt>
1100   <dd>This attribute indicates that the function should emit a stack smashing
1101       protector. It is in the form of a "canary"&mdash;a random value placed on
1102       the stack before the local variables that's checked upon return from the
1103       function to see if it has been overwritten. A heuristic is used to
1104       determine if a function needs stack protectors or not.<br>
1105 <br>
1106       If a function that has an <tt>ssp</tt> attribute is inlined into a
1107       function that doesn't have an <tt>ssp</tt> attribute, then the resulting
1108       function will have an <tt>ssp</tt> attribute.</dd>
1109
1110   <dt><tt><b>sspreq</b></tt></dt>
1111   <dd>This attribute indicates that the function should <em>always</em> emit a
1112       stack smashing protector. This overrides
1113       the <tt><a href="#ssp">ssp</a></tt> function attribute.<br>
1114 <br>
1115       If a function that has an <tt>sspreq</tt> attribute is inlined into a
1116       function that doesn't have an <tt>sspreq</tt> attribute or which has
1117       an <tt>ssp</tt> attribute, then the resulting function will have
1118       an <tt>sspreq</tt> attribute.</dd>
1119
1120   <dt><tt><b>noredzone</b></tt></dt>
1121   <dd>This attribute indicates that the code generator should not use a red
1122       zone, even if the target-specific ABI normally permits it.</dd>
1123
1124   <dt><tt><b>noimplicitfloat</b></tt></dt>
1125   <dd>This attributes disables implicit floating point instructions.</dd>
1126
1127   <dt><tt><b>naked</b></tt></dt>
1128   <dd>This attribute disables prologue / epilogue emission for the function.
1129       This can have very system-specific consequences.</dd>
1130 </dl>
1131
1132 </div>
1133
1134 <!-- ======================================================================= -->
1135 <div class="doc_subsection">
1136   <a name="moduleasm">Module-Level Inline Assembly</a>
1137 </div>
1138
1139 <div class="doc_text">
1140
1141 <p>Modules may contain "module-level inline asm" blocks, which corresponds to
1142    the GCC "file scope inline asm" blocks.  These blocks are internally
1143    concatenated by LLVM and treated as a single unit, but may be separated in
1144    the <tt>.ll</tt> file if desired.  The syntax is very simple:</p>
1145
1146 <div class="doc_code">
1147 <pre>
1148 module asm "inline asm code goes here"
1149 module asm "more can go here"
1150 </pre>
1151 </div>
1152
1153 <p>The strings can contain any character by escaping non-printable characters.
1154    The escape sequence used is simply "\xx" where "xx" is the two digit hex code
1155    for the number.</p>
1156
1157 <p>The inline asm code is simply printed to the machine code .s file when
1158    assembly code is generated.</p>
1159
1160 </div>
1161
1162 <!-- ======================================================================= -->
1163 <div class="doc_subsection">
1164   <a name="datalayout">Data Layout</a>
1165 </div>
1166
1167 <div class="doc_text">
1168
1169 <p>A module may specify a target specific data layout string that specifies how
1170    data is to be laid out in memory. The syntax for the data layout is
1171    simply:</p>
1172
1173 <div class="doc_code">
1174 <pre>
1175 target datalayout = "<i>layout specification</i>"
1176 </pre>
1177 </div>
1178
1179 <p>The <i>layout specification</i> consists of a list of specifications
1180    separated by the minus sign character ('-').  Each specification starts with
1181    a letter and may include other information after the letter to define some
1182    aspect of the data layout.  The specifications accepted are as follows:</p>
1183
1184 <dl>
1185   <dt><tt>E</tt></dt>
1186   <dd>Specifies that the target lays out data in big-endian form. That is, the
1187       bits with the most significance have the lowest address location.</dd>
1188
1189   <dt><tt>e</tt></dt>
1190   <dd>Specifies that the target lays out data in little-endian form. That is,
1191       the bits with the least significance have the lowest address
1192       location.</dd>
1193
1194   <dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1195   <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and
1196       <i>preferred</i> alignments. All sizes are in bits. Specifying
1197       the <i>pref</i> alignment is optional. If omitted, the
1198       preceding <tt>:</tt> should be omitted too.</dd>
1199
1200   <dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1201   <dd>This specifies the alignment for an integer type of a given bit
1202       <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd>
1203
1204   <dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1205   <dd>This specifies the alignment for a vector type of a given bit
1206       <i>size</i>.</dd>
1207
1208   <dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1209   <dd>This specifies the alignment for a floating point type of a given bit
1210       <i>size</i>. The value of <i>size</i> must be either 32 (float) or 64
1211       (double).</dd>
1212
1213   <dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1214   <dd>This specifies the alignment for an aggregate type of a given bit
1215       <i>size</i>.</dd>
1216
1217   <dt><tt>s<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
1218   <dd>This specifies the alignment for a stack object of a given bit
1219       <i>size</i>.</dd>
1220
1221   <dt><tt>n<i>size1</i>:<i>size2</i>:<i>size3</i>...</tt></dt>
1222   <dd>This specifies a set of native integer widths for the target CPU
1223       in bits.  For example, it might contain "n32" for 32-bit PowerPC,
1224       "n32:64" for PowerPC 64, or "n8:16:32:64" for X86-64.  Elements of
1225       this set are considered to support most general arithmetic
1226       operations efficiently.</dd>
1227 </dl>
1228
1229 <p>When constructing the data layout for a given target, LLVM starts with a
1230    default set of specifications which are then (possibly) overriden by the
1231    specifications in the <tt>datalayout</tt> keyword. The default specifications
1232    are given in this list:</p>
1233
1234 <ul>
1235   <li><tt>E</tt> - big endian</li>
1236   <li><tt>p:32:64:64</tt> - 32-bit pointers with 64-bit alignment</li>
1237   <li><tt>i1:8:8</tt> - i1 is 8-bit (byte) aligned</li>
1238   <li><tt>i8:8:8</tt> - i8 is 8-bit (byte) aligned</li>
1239   <li><tt>i16:16:16</tt> - i16 is 16-bit aligned</li>
1240   <li><tt>i32:32:32</tt> - i32 is 32-bit aligned</li>
1241   <li><tt>i64:32:64</tt> - i64 has ABI alignment of 32-bits but preferred
1242   alignment of 64-bits</li>
1243   <li><tt>f32:32:32</tt> - float is 32-bit aligned</li>
1244   <li><tt>f64:64:64</tt> - double is 64-bit aligned</li>
1245   <li><tt>v64:64:64</tt> - 64-bit vector is 64-bit aligned</li>
1246   <li><tt>v128:128:128</tt> - 128-bit vector is 128-bit aligned</li>
1247   <li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li>
1248   <li><tt>s0:64:64</tt> - stack objects are 64-bit aligned</li>
1249 </ul>
1250
1251 <p>When LLVM is determining the alignment for a given type, it uses the
1252    following rules:</p>
1253
1254 <ol>
1255   <li>If the type sought is an exact match for one of the specifications, that
1256       specification is used.</li>
1257
1258   <li>If no match is found, and the type sought is an integer type, then the
1259       smallest integer type that is larger than the bitwidth of the sought type
1260       is used. If none of the specifications are larger than the bitwidth then
1261       the the largest integer type is used. For example, given the default
1262       specifications above, the i7 type will use the alignment of i8 (next
1263       largest) while both i65 and i256 will use the alignment of i64 (largest
1264       specified).</li>
1265
1266   <li>If no match is found, and the type sought is a vector type, then the
1267       largest vector type that is smaller than the sought vector type will be
1268       used as a fall back.  This happens because &lt;128 x double&gt; can be
1269       implemented in terms of 64 &lt;2 x double&gt;, for example.</li>
1270 </ol>
1271
1272 </div>
1273
1274 <!-- ======================================================================= -->
1275 <div class="doc_subsection">
1276   <a name="pointeraliasing">Pointer Aliasing Rules</a>
1277 </div>
1278
1279 <div class="doc_text">
1280
1281 <p>Any memory access must be done through a pointer value associated
1282 with an address range of the memory access, otherwise the behavior
1283 is undefined. Pointer values are associated with address ranges
1284 according to the following rules:</p>
1285
1286 <ul>
1287   <li>A pointer value formed from a
1288       <tt><a href="#i_getelementptr">getelementptr</a></tt> instruction
1289       is associated with the addresses associated with the first operand
1290       of the <tt>getelementptr</tt>.</li>
1291   <li>An address of a global variable is associated with the address
1292       range of the variable's storage.</li>
1293   <li>The result value of an allocation instruction is associated with
1294       the address range of the allocated storage.</li>
1295   <li>A null pointer in the default address-space is associated with
1296       no address.</li>
1297   <li>A pointer value formed by an
1298       <tt><a href="#i_inttoptr">inttoptr</a></tt> is associated with all
1299       address ranges of all pointer values that contribute (directly or
1300       indirectly) to the computation of the pointer's value.</li>
1301   <li>The result value of a
1302       <tt><a href="#i_bitcast">bitcast</a></tt> is associated with all
1303       addresses associated with the operand of the <tt>bitcast</tt>.</li>
1304   <li>An integer constant other than zero or a pointer value returned
1305       from a function not defined within LLVM may be associated with address
1306       ranges allocated through mechanisms other than those provided by
1307       LLVM. Such ranges shall not overlap with any ranges of addresses
1308       allocated by mechanisms provided by LLVM.</li>
1309   </ul>
1310
1311 <p>LLVM IR does not associate types with memory. The result type of a
1312 <tt><a href="#i_load">load</a></tt> merely indicates the size and
1313 alignment of the memory from which to load, as well as the
1314 interpretation of the value. The first operand of a
1315 <tt><a href="#i_store">store</a></tt> similarly only indicates the size
1316 and alignment of the store.</p>
1317
1318 <p>Consequently, type-based alias analysis, aka TBAA, aka
1319 <tt>-fstrict-aliasing</tt>, is not applicable to general unadorned
1320 LLVM IR. <a href="#metadata">Metadata</a> may be used to encode
1321 additional information which specialized optimization passes may use
1322 to implement type-based alias analysis.</p>
1323
1324 </div>
1325
1326 <!-- *********************************************************************** -->
1327 <div class="doc_section"> <a name="typesystem">Type System</a> </div>
1328 <!-- *********************************************************************** -->
1329
1330 <div class="doc_text">
1331
1332 <p>The LLVM type system is one of the most important features of the
1333    intermediate representation.  Being typed enables a number of optimizations
1334    to be performed on the intermediate representation directly, without having
1335    to do extra analyses on the side before the transformation.  A strong type
1336    system makes it easier to read the generated code and enables novel analyses
1337    and transformations that are not feasible to perform on normal three address
1338    code representations.</p>
1339
1340 </div>
1341
1342 <!-- ======================================================================= -->
1343 <div class="doc_subsection"> <a name="t_classifications">Type
1344 Classifications</a> </div>
1345
1346 <div class="doc_text">
1347
1348 <p>The types fall into a few useful classifications:</p>
1349
1350 <table border="1" cellspacing="0" cellpadding="4">
1351   <tbody>
1352     <tr><th>Classification</th><th>Types</th></tr>
1353     <tr>
1354       <td><a href="#t_integer">integer</a></td>
1355       <td><tt>i1, i2, i3, ... i8, ... i16, ... i32, ... i64, ... </tt></td>
1356     </tr>
1357     <tr>
1358       <td><a href="#t_floating">floating point</a></td>
1359       <td><tt>float, double, x86_fp80, fp128, ppc_fp128</tt></td>
1360     </tr>
1361     <tr>
1362       <td><a name="t_firstclass">first class</a></td>
1363       <td><a href="#t_integer">integer</a>,
1364           <a href="#t_floating">floating point</a>,
1365           <a href="#t_pointer">pointer</a>,
1366           <a href="#t_vector">vector</a>,
1367           <a href="#t_struct">structure</a>,
1368           <a href="#t_array">array</a>,
1369           <a href="#t_label">label</a>,
1370           <a href="#t_metadata">metadata</a>.
1371       </td>
1372     </tr>
1373     <tr>
1374       <td><a href="#t_primitive">primitive</a></td>
1375       <td><a href="#t_label">label</a>,
1376           <a href="#t_void">void</a>,
1377           <a href="#t_floating">floating point</a>,
1378           <a href="#t_metadata">metadata</a>.</td>
1379     </tr>
1380     <tr>
1381       <td><a href="#t_derived">derived</a></td>
1382       <td><a href="#t_integer">integer</a>,
1383           <a href="#t_array">array</a>,
1384           <a href="#t_function">function</a>,
1385           <a href="#t_pointer">pointer</a>,
1386           <a href="#t_struct">structure</a>,
1387           <a href="#t_pstruct">packed structure</a>,
1388           <a href="#t_vector">vector</a>,
1389           <a href="#t_opaque">opaque</a>.
1390       </td>
1391     </tr>
1392   </tbody>
1393 </table>
1394
1395 <p>The <a href="#t_firstclass">first class</a> types are perhaps the most
1396    important.  Values of these types are the only ones which can be produced by
1397    instructions.</p>
1398
1399 </div>
1400
1401 <!-- ======================================================================= -->
1402 <div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div>
1403
1404 <div class="doc_text">
1405
1406 <p>The primitive types are the fundamental building blocks of the LLVM
1407    system.</p>
1408
1409 </div>
1410
1411 <!-- _______________________________________________________________________ -->
1412 <div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div>
1413
1414 <div class="doc_text">
1415
1416 <h5>Overview:</h5>
1417 <p>The integer type is a very simple type that simply specifies an arbitrary
1418    bit width for the integer type desired. Any bit width from 1 bit to
1419    2<sup>23</sup>-1 (about 8 million) can be specified.</p>
1420
1421 <h5>Syntax:</h5>
1422 <pre>
1423   iN
1424 </pre>
1425
1426 <p>The number of bits the integer will occupy is specified by the <tt>N</tt>
1427    value.</p>
1428
1429 <h5>Examples:</h5>
1430 <table class="layout">
1431   <tr class="layout">
1432     <td class="left"><tt>i1</tt></td>
1433     <td class="left">a single-bit integer.</td>
1434   </tr>
1435   <tr class="layout">
1436     <td class="left"><tt>i32</tt></td>
1437     <td class="left">a 32-bit integer.</td>
1438   </tr>
1439   <tr class="layout">
1440     <td class="left"><tt>i1942652</tt></td>
1441     <td class="left">a really big integer of over 1 million bits.</td>
1442   </tr>
1443 </table>
1444
1445 </div>
1446
1447 <!-- _______________________________________________________________________ -->
1448 <div class="doc_subsubsection"> <a name="t_floating">Floating Point Types</a> </div>
1449
1450 <div class="doc_text">
1451
1452 <table>
1453   <tbody>
1454     <tr><th>Type</th><th>Description</th></tr>
1455     <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
1456     <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
1457     <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr>
1458     <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr>
1459     <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr>
1460   </tbody>
1461 </table>
1462
1463 </div>
1464
1465 <!-- _______________________________________________________________________ -->
1466 <div class="doc_subsubsection"> <a name="t_void">Void Type</a> </div>
1467
1468 <div class="doc_text">
1469
1470 <h5>Overview:</h5>
1471 <p>The void type does not represent any value and has no size.</p>
1472
1473 <h5>Syntax:</h5>
1474 <pre>
1475   void
1476 </pre>
1477
1478 </div>
1479
1480 <!-- _______________________________________________________________________ -->
1481 <div class="doc_subsubsection"> <a name="t_label">Label Type</a> </div>
1482
1483 <div class="doc_text">
1484
1485 <h5>Overview:</h5>
1486 <p>The label type represents code labels.</p>
1487
1488 <h5>Syntax:</h5>
1489 <pre>
1490   label
1491 </pre>
1492
1493 </div>
1494
1495 <!-- _______________________________________________________________________ -->
1496 <div class="doc_subsubsection"> <a name="t_metadata">Metadata Type</a> </div>
1497
1498 <div class="doc_text">
1499
1500 <h5>Overview:</h5>
1501 <p>The metadata type represents embedded metadata. No derived types may be
1502    created from metadata except for <a href="#t_function">function</a>
1503    arguments.
1504
1505 <h5>Syntax:</h5>
1506 <pre>
1507   metadata
1508 </pre>
1509
1510 </div>
1511
1512
1513 <!-- ======================================================================= -->
1514 <div class="doc_subsection"> <a name="t_derived">Derived Types</a> </div>
1515
1516 <div class="doc_text">
1517
1518 <p>The real power in LLVM comes from the derived types in the system.  This is
1519    what allows a programmer to represent arrays, functions, pointers, and other
1520    useful types.  Each of these types contain one or more element types which
1521    may be a primitive type, or another derived type.  For example, it is
1522    possible to have a two dimensional array, using an array as the element type
1523    of another array.</p>
1524
1525 </div>
1526
1527 <!-- _______________________________________________________________________ -->
1528 <div class="doc_subsubsection"> <a name="t_array">Array Type</a> </div>
1529
1530 <div class="doc_text">
1531
1532 <h5>Overview:</h5>
1533 <p>The array type is a very simple derived type that arranges elements
1534    sequentially in memory.  The array type requires a size (number of elements)
1535    and an underlying data type.</p>
1536
1537 <h5>Syntax:</h5>
1538 <pre>
1539   [&lt;# elements&gt; x &lt;elementtype&gt;]
1540 </pre>
1541
1542 <p>The number of elements is a constant integer value; <tt>elementtype</tt> may
1543    be any type with a size.</p>
1544
1545 <h5>Examples:</h5>
1546 <table class="layout">
1547   <tr class="layout">
1548     <td class="left"><tt>[40 x i32]</tt></td>
1549     <td class="left">Array of 40 32-bit integer values.</td>
1550   </tr>
1551   <tr class="layout">
1552     <td class="left"><tt>[41 x i32]</tt></td>
1553     <td class="left">Array of 41 32-bit integer values.</td>
1554   </tr>
1555   <tr class="layout">
1556     <td class="left"><tt>[4 x i8]</tt></td>
1557     <td class="left">Array of 4 8-bit integer values.</td>
1558   </tr>
1559 </table>
1560 <p>Here are some examples of multidimensional arrays:</p>
1561 <table class="layout">
1562   <tr class="layout">
1563     <td class="left"><tt>[3 x [4 x i32]]</tt></td>
1564     <td class="left">3x4 array of 32-bit integer values.</td>
1565   </tr>
1566   <tr class="layout">
1567     <td class="left"><tt>[12 x [10 x float]]</tt></td>
1568     <td class="left">12x10 array of single precision floating point values.</td>
1569   </tr>
1570   <tr class="layout">
1571     <td class="left"><tt>[2 x [3 x [4 x i16]]]</tt></td>
1572     <td class="left">2x3x4 array of 16-bit integer  values.</td>
1573   </tr>
1574 </table>
1575
1576 <p>There is no restriction on indexing beyond the end of the array implied by
1577    a static type (though there are restrictions on indexing beyond the bounds
1578    of an allocated object in some cases). This means that single-dimension
1579    'variable sized array' addressing can be implemented in LLVM with a zero
1580    length array type. An implementation of 'pascal style arrays' in LLVM could
1581    use the type "<tt>{ i32, [0 x float]}</tt>", for example.</p>
1582
1583 </div>
1584
1585 <!-- _______________________________________________________________________ -->
1586 <div class="doc_subsubsection"> <a name="t_function">Function Type</a> </div>
1587
1588 <div class="doc_text">
1589
1590 <h5>Overview:</h5>
1591 <p>The function type can be thought of as a function signature.  It consists of
1592    a return type and a list of formal parameter types. The return type of a
1593    function type is a scalar type, a void type, or a struct type.  If the return
1594    type is a struct type then all struct elements must be of first class types,
1595    and the struct must have at least one element.</p>
1596
1597 <h5>Syntax:</h5>
1598 <pre>
1599   &lt;returntype&gt; (&lt;parameter list&gt;)
1600 </pre>
1601
1602 <p>...where '<tt>&lt;parameter list&gt;</tt>' is a comma-separated list of type
1603    specifiers.  Optionally, the parameter list may include a type <tt>...</tt>,
1604    which indicates that the function takes a variable number of arguments.
1605    Variable argument functions can access their arguments with
1606    the <a href="#int_varargs">variable argument handling intrinsic</a>
1607    functions.  '<tt>&lt;returntype&gt;</tt>' is a any type except
1608    <a href="#t_label">label</a>.</p>
1609
1610 <h5>Examples:</h5>
1611 <table class="layout">
1612   <tr class="layout">
1613     <td class="left"><tt>i32 (i32)</tt></td>
1614     <td class="left">function taking an <tt>i32</tt>, returning an <tt>i32</tt>
1615     </td>
1616   </tr><tr class="layout">
1617     <td class="left"><tt>float&nbsp;(i16&nbsp;signext,&nbsp;i32&nbsp;*)&nbsp;*
1618     </tt></td>
1619     <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes
1620       an <tt>i16</tt> that should be sign extended and a
1621       <a href="#t_pointer">pointer</a> to <tt>i32</tt>, returning
1622       <tt>float</tt>.
1623     </td>
1624   </tr><tr class="layout">
1625     <td class="left"><tt>i32 (i8*, ...)</tt></td>
1626     <td class="left">A vararg function that takes at least one
1627       <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C),
1628       which returns an integer.  This is the signature for <tt>printf</tt> in
1629       LLVM.
1630     </td>
1631   </tr><tr class="layout">
1632     <td class="left"><tt>{i32, i32} (i32)</tt></td>
1633     <td class="left">A function taking an <tt>i32</tt>, returning a
1634         <a href="#t_struct">structure</a> containing two <tt>i32</tt> values
1635     </td>
1636   </tr>
1637 </table>
1638
1639 </div>
1640
1641 <!-- _______________________________________________________________________ -->
1642 <div class="doc_subsubsection"> <a name="t_struct">Structure Type</a> </div>
1643
1644 <div class="doc_text">
1645
1646 <h5>Overview:</h5>
1647 <p>The structure type is used to represent a collection of data members together
1648    in memory.  The packing of the field types is defined to match the ABI of the
1649    underlying processor.  The elements of a structure may be any type that has a
1650    size.</p>
1651
1652 <p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and
1653    '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with
1654    the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
1655
1656 <h5>Syntax:</h5>
1657 <pre>
1658   { &lt;type list&gt; }
1659 </pre>
1660
1661 <h5>Examples:</h5>
1662 <table class="layout">
1663   <tr class="layout">
1664     <td class="left"><tt>{ i32, i32, i32 }</tt></td>
1665     <td class="left">A triple of three <tt>i32</tt> values</td>
1666   </tr><tr class="layout">
1667     <td class="left"><tt>{&nbsp;float,&nbsp;i32&nbsp;(i32)&nbsp;*&nbsp;}</tt></td>
1668     <td class="left">A pair, where the first element is a <tt>float</tt> and the
1669       second element is a <a href="#t_pointer">pointer</a> to a
1670       <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
1671       an <tt>i32</tt>.</td>
1672   </tr>
1673 </table>
1674
1675 </div>
1676
1677 <!-- _______________________________________________________________________ -->
1678 <div class="doc_subsubsection"> <a name="t_pstruct">Packed Structure Type</a>
1679 </div>
1680
1681 <div class="doc_text">
1682
1683 <h5>Overview:</h5>
1684 <p>The packed structure type is used to represent a collection of data members
1685    together in memory.  There is no padding between fields.  Further, the
1686    alignment of a packed structure is 1 byte.  The elements of a packed
1687    structure may be any type that has a size.</p>
1688
1689 <p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and
1690    '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with
1691    the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
1692
1693 <h5>Syntax:</h5>
1694 <pre>
1695   &lt; { &lt;type list&gt; } &gt;
1696 </pre>
1697
1698 <h5>Examples:</h5>
1699 <table class="layout">
1700   <tr class="layout">
1701     <td class="left"><tt>&lt; { i32, i32, i32 } &gt;</tt></td>
1702     <td class="left">A triple of three <tt>i32</tt> values</td>
1703   </tr><tr class="layout">
1704   <td class="left">
1705 <tt>&lt;&nbsp;{&nbsp;float,&nbsp;i32&nbsp;(i32)*&nbsp;}&nbsp;&gt;</tt></td>
1706     <td class="left">A pair, where the first element is a <tt>float</tt> and the
1707       second element is a <a href="#t_pointer">pointer</a> to a
1708       <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
1709       an <tt>i32</tt>.</td>
1710   </tr>
1711 </table>
1712
1713 </div>
1714
1715 <!-- _______________________________________________________________________ -->
1716 <div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div>
1717
1718 <div class="doc_text">
1719
1720 <h5>Overview:</h5>
1721 <p>As in many languages, the pointer type represents a pointer or reference to
1722    another object, which must live in memory. Pointer types may have an optional
1723    address space attribute defining the target-specific numbered address space
1724    where the pointed-to object resides. The default address space is zero.</p>
1725
1726 <p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does it
1727    permit pointers to labels (<tt>label*</tt>).  Use <tt>i8*</tt> instead.</p>
1728
1729 <h5>Syntax:</h5>
1730 <pre>
1731   &lt;type&gt; *
1732 </pre>
1733
1734 <h5>Examples:</h5>
1735 <table class="layout">
1736   <tr class="layout">
1737     <td class="left"><tt>[4 x i32]*</tt></td>
1738     <td class="left">A <a href="#t_pointer">pointer</a> to <a
1739                     href="#t_array">array</a> of four <tt>i32</tt> values.</td>
1740   </tr>
1741   <tr class="layout">
1742     <td class="left"><tt>i32 (i32 *) *</tt></td>
1743     <td class="left"> A <a href="#t_pointer">pointer</a> to a <a
1744       href="#t_function">function</a> that takes an <tt>i32*</tt>, returning an
1745       <tt>i32</tt>.</td>
1746   </tr>
1747   <tr class="layout">
1748     <td class="left"><tt>i32 addrspace(5)*</tt></td>
1749     <td class="left">A <a href="#t_pointer">pointer</a> to an <tt>i32</tt> value
1750      that resides in address space #5.</td>
1751   </tr>
1752 </table>
1753
1754 </div>
1755
1756 <!-- _______________________________________________________________________ -->
1757 <div class="doc_subsubsection"> <a name="t_vector">Vector Type</a> </div>
1758
1759 <div class="doc_text">
1760
1761 <h5>Overview:</h5>
1762 <p>A vector type is a simple derived type that represents a vector of elements.
1763    Vector types are used when multiple primitive data are operated in parallel
1764    using a single instruction (SIMD).  A vector type requires a size (number of
1765    elements) and an underlying primitive data type.  Vector types are considered
1766    <a href="#t_firstclass">first class</a>.</p>
1767
1768 <h5>Syntax:</h5>
1769 <pre>
1770   &lt; &lt;# elements&gt; x &lt;elementtype&gt; &gt;
1771 </pre>
1772
1773 <p>The number of elements is a constant integer value; elementtype may be any
1774    integer or floating point type.</p>
1775
1776 <h5>Examples:</h5>
1777 <table class="layout">
1778   <tr class="layout">
1779     <td class="left"><tt>&lt;4 x i32&gt;</tt></td>
1780     <td class="left">Vector of 4 32-bit integer values.</td>
1781   </tr>
1782   <tr class="layout">
1783     <td class="left"><tt>&lt;8 x float&gt;</tt></td>
1784     <td class="left">Vector of 8 32-bit floating-point values.</td>
1785   </tr>
1786   <tr class="layout">
1787     <td class="left"><tt>&lt;2 x i64&gt;</tt></td>
1788     <td class="left">Vector of 2 64-bit integer values.</td>
1789   </tr>
1790 </table>
1791
1792 </div>
1793
1794 <!-- _______________________________________________________________________ -->
1795 <div class="doc_subsubsection"> <a name="t_opaque">Opaque Type</a> </div>
1796 <div class="doc_text">
1797
1798 <h5>Overview:</h5>
1799 <p>Opaque types are used to represent unknown types in the system.  This
1800    corresponds (for example) to the C notion of a forward declared structure
1801    type.  In LLVM, opaque types can eventually be resolved to any type (not just
1802    a structure type).</p>
1803
1804 <h5>Syntax:</h5>
1805 <pre>
1806   opaque
1807 </pre>
1808
1809 <h5>Examples:</h5>
1810 <table class="layout">
1811   <tr class="layout">
1812     <td class="left"><tt>opaque</tt></td>
1813     <td class="left">An opaque type.</td>
1814   </tr>
1815 </table>
1816
1817 </div>
1818
1819 <!-- ======================================================================= -->
1820 <div class="doc_subsection">
1821   <a name="t_uprefs">Type Up-references</a>
1822 </div>
1823
1824 <div class="doc_text">
1825
1826 <h5>Overview:</h5>
1827 <p>An "up reference" allows you to refer to a lexically enclosing type without
1828    requiring it to have a name. For instance, a structure declaration may
1829    contain a pointer to any of the types it is lexically a member of.  Example
1830    of up references (with their equivalent as named type declarations)
1831    include:</p>
1832
1833 <pre>
1834    { \2 * }                %x = type { %x* }
1835    { \2 }*                 %y = type { %y }*
1836    \1*                     %z = type %z*
1837 </pre>
1838
1839 <p>An up reference is needed by the asmprinter for printing out cyclic types
1840    when there is no declared name for a type in the cycle.  Because the
1841    asmprinter does not want to print out an infinite type string, it needs a
1842    syntax to handle recursive types that have no names (all names are optional
1843    in llvm IR).</p>
1844
1845 <h5>Syntax:</h5>
1846 <pre>
1847    \&lt;level&gt;
1848 </pre>
1849
1850 <p>The level is the count of the lexical type that is being referred to.</p>
1851
1852 <h5>Examples:</h5>
1853 <table class="layout">
1854   <tr class="layout">
1855     <td class="left"><tt>\1*</tt></td>
1856     <td class="left">Self-referential pointer.</td>
1857   </tr>
1858   <tr class="layout">
1859     <td class="left"><tt>{ { \3*, i8 }, i32 }</tt></td>
1860     <td class="left">Recursive structure where the upref refers to the out-most
1861                      structure.</td>
1862   </tr>
1863 </table>
1864
1865 </div>
1866
1867 <!-- *********************************************************************** -->
1868 <div class="doc_section"> <a name="constants">Constants</a> </div>
1869 <!-- *********************************************************************** -->
1870
1871 <div class="doc_text">
1872
1873 <p>LLVM has several different basic types of constants.  This section describes
1874    them all and their syntax.</p>
1875
1876 </div>
1877
1878 <!-- ======================================================================= -->
1879 <div class="doc_subsection"><a name="simpleconstants">Simple Constants</a></div>
1880
1881 <div class="doc_text">
1882
1883 <dl>
1884   <dt><b>Boolean constants</b></dt>
1885   <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
1886       constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd>
1887
1888   <dt><b>Integer constants</b></dt>
1889   <dd>Standard integers (such as '4') are constants of
1890       the <a href="#t_integer">integer</a> type.  Negative numbers may be used
1891       with integer types.</dd>
1892
1893   <dt><b>Floating point constants</b></dt>
1894   <dd>Floating point constants use standard decimal notation (e.g. 123.421),
1895       exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal
1896       notation (see below).  The assembler requires the exact decimal value of a
1897       floating-point constant.  For example, the assembler accepts 1.25 but
1898       rejects 1.3 because 1.3 is a repeating decimal in binary.  Floating point
1899       constants must have a <a href="#t_floating">floating point</a> type. </dd>
1900
1901   <dt><b>Null pointer constants</b></dt>
1902   <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant
1903       and must be of <a href="#t_pointer">pointer type</a>.</dd>
1904 </dl>
1905
1906 <p>The one non-intuitive notation for constants is the hexadecimal form of
1907    floating point constants.  For example, the form '<tt>double
1908    0x432ff973cafa8000</tt>' is equivalent to (but harder to read than)
1909    '<tt>double 4.5e+15</tt>'.  The only time hexadecimal floating point
1910    constants are required (and the only time that they are generated by the
1911    disassembler) is when a floating point constant must be emitted but it cannot
1912    be represented as a decimal floating point number in a reasonable number of
1913    digits.  For example, NaN's, infinities, and other special values are
1914    represented in their IEEE hexadecimal format so that assembly and disassembly
1915    do not cause any bits to change in the constants.</p>
1916
1917 <p>When using the hexadecimal form, constants of types float and double are
1918    represented using the 16-digit form shown above (which matches the IEEE754
1919    representation for double); float values must, however, be exactly
1920    representable as IEE754 single precision.  Hexadecimal format is always used
1921    for long double, and there are three forms of long double.  The 80-bit format
1922    used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits.
1923    The 128-bit format used by PowerPC (two adjacent doubles) is represented
1924    by <tt>0xM</tt> followed by 32 hexadecimal digits.  The IEEE 128-bit format
1925    is represented by <tt>0xL</tt> followed by 32 hexadecimal digits; no
1926    currently supported target uses this format.  Long doubles will only work if
1927    they match the long double format on your target.  All hexadecimal formats
1928    are big-endian (sign bit at the left).</p>
1929
1930 </div>
1931
1932 <!-- ======================================================================= -->
1933 <div class="doc_subsection">
1934 <a name="aggregateconstants"></a> <!-- old anchor -->
1935 <a name="complexconstants">Complex Constants</a>
1936 </div>
1937
1938 <div class="doc_text">
1939
1940 <p>Complex constants are a (potentially recursive) combination of simple
1941    constants and smaller complex constants.</p>
1942
1943 <dl>
1944   <dt><b>Structure constants</b></dt>
1945   <dd>Structure constants are represented with notation similar to structure
1946       type definitions (a comma separated list of elements, surrounded by braces
1947       (<tt>{}</tt>)).  For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>",
1948       where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>".
1949       Structure constants must have <a href="#t_struct">structure type</a>, and
1950       the number and types of elements must match those specified by the
1951       type.</dd>
1952
1953   <dt><b>Array constants</b></dt>
1954   <dd>Array constants are represented with notation similar to array type
1955      definitions (a comma separated list of elements, surrounded by square
1956      brackets (<tt>[]</tt>)).  For example: "<tt>[ i32 42, i32 11, i32 74
1957      ]</tt>".  Array constants must have <a href="#t_array">array type</a>, and
1958      the number and types of elements must match those specified by the
1959      type.</dd>
1960
1961   <dt><b>Vector constants</b></dt>
1962   <dd>Vector constants are represented with notation similar to vector type
1963       definitions (a comma separated list of elements, surrounded by
1964       less-than/greater-than's (<tt>&lt;&gt;</tt>)).  For example: "<tt>&lt; i32
1965       42, i32 11, i32 74, i32 100 &gt;</tt>".  Vector constants must
1966       have <a href="#t_vector">vector type</a>, and the number and types of
1967       elements must match those specified by the type.</dd>
1968
1969   <dt><b>Zero initialization</b></dt>
1970   <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a
1971       value to zero of <em>any</em> type, including scalar and aggregate types.
1972       This is often used to avoid having to print large zero initializers
1973       (e.g. for large arrays) and is always exactly equivalent to using explicit
1974       zero initializers.</dd>
1975
1976   <dt><b>Metadata node</b></dt>
1977   <dd>A metadata node is a structure-like constant with
1978       <a href="#t_metadata">metadata type</a>.  For example: "<tt>metadata !{
1979       i32 0, metadata !"test" }</tt>".  Unlike other constants that are meant to
1980       be interpreted as part of the instruction stream, metadata is a place to
1981       attach additional information such as debug info.</dd>
1982 </dl>
1983
1984 </div>
1985
1986 <!-- ======================================================================= -->
1987 <div class="doc_subsection">
1988   <a name="globalconstants">Global Variable and Function Addresses</a>
1989 </div>
1990
1991 <div class="doc_text">
1992
1993 <p>The addresses of <a href="#globalvars">global variables</a>
1994    and <a href="#functionstructure">functions</a> are always implicitly valid
1995    (link-time) constants.  These constants are explicitly referenced when
1996    the <a href="#identifiers">identifier for the global</a> is used and always
1997    have <a href="#t_pointer">pointer</a> type. For example, the following is a
1998    legal LLVM file:</p>
1999
2000 <div class="doc_code">
2001 <pre>
2002 @X = global i32 17
2003 @Y = global i32 42
2004 @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
2005 </pre>
2006 </div>
2007
2008 </div>
2009
2010 <!-- ======================================================================= -->
2011 <div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div>
2012 <div class="doc_text">
2013
2014 <p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and
2015    indicates that the user of the value may receive an unspecified bit-pattern.
2016    Undefined values may be of any type (other than label or void) and be used
2017    anywhere a constant is permitted.</p>
2018
2019 <p>Undefined values are useful because they indicate to the compiler that the
2020    program is well defined no matter what value is used.  This gives the
2021    compiler more freedom to optimize.  Here are some examples of (potentially
2022    surprising) transformations that are valid (in pseudo IR):</p>
2023
2024
2025 <div class="doc_code">
2026 <pre>
2027   %A = add %X, undef
2028   %B = sub %X, undef
2029   %C = xor %X, undef
2030 Safe:
2031   %A = undef
2032   %B = undef
2033   %C = undef
2034 </pre>
2035 </div>
2036
2037 <p>This is safe because all of the output bits are affected by the undef bits.
2038 Any output bit can have a zero or one depending on the input bits.</p>
2039
2040 <div class="doc_code">
2041 <pre>
2042   %A = or %X, undef
2043   %B = and %X, undef
2044 Safe:
2045   %A = -1
2046   %B = 0
2047 Unsafe:
2048   %A = undef
2049   %B = undef
2050 </pre>
2051 </div>
2052
2053 <p>These logical operations have bits that are not always affected by the input.
2054 For example, if "%X" has a zero bit, then the output of the 'and' operation will
2055 always be a zero, no matter what the corresponding bit from the undef is.  As
2056 such, it is unsafe to optimize or assume that the result of the and is undef.
2057 However, it is safe to assume that all bits of the undef could be 0, and
2058 optimize the and to 0.  Likewise, it is safe to assume that all the bits of
2059 the undef operand to the or could be set, allowing the or to be folded to
2060 -1.</p>
2061
2062 <div class="doc_code">
2063 <pre>
2064   %A = select undef, %X, %Y
2065   %B = select undef, 42, %Y
2066   %C = select %X, %Y, undef
2067 Safe:
2068   %A = %X     (or %Y)
2069   %B = 42     (or %Y)
2070   %C = %Y
2071 Unsafe:
2072   %A = undef
2073   %B = undef
2074   %C = undef
2075 </pre>
2076 </div>
2077
2078 <p>This set of examples show that undefined select (and conditional branch)
2079 conditions can go "either way" but they have to come from one of the two
2080 operands.  In the %A example, if %X and %Y were both known to have a clear low
2081 bit, then %A would have to have a cleared low bit.  However, in the %C example,
2082 the optimizer is allowed to assume that the undef operand could be the same as
2083 %Y, allowing the whole select to be eliminated.</p>
2084
2085
2086 <div class="doc_code">
2087 <pre>
2088   %A = xor undef, undef
2089
2090   %B = undef
2091   %C = xor %B, %B
2092
2093   %D = undef
2094   %E = icmp lt %D, 4
2095   %F = icmp gte %D, 4
2096
2097 Safe:
2098   %A = undef
2099   %B = undef
2100   %C = undef
2101   %D = undef
2102   %E = undef
2103   %F = undef
2104 </pre>
2105 </div>
2106
2107 <p>This example points out that two undef operands are not necessarily the same.
2108 This can be surprising to people (and also matches C semantics) where they
2109 assume that "X^X" is always zero, even if X is undef.  This isn't true for a
2110 number of reasons, but the short answer is that an undef "variable" can
2111 arbitrarily change its value over its "live range".  This is true because the
2112 "variable" doesn't actually <em>have a live range</em>.  Instead, the value is
2113 logically read from arbitrary registers that happen to be around when needed,
2114 so the value is not necessarily consistent over time.  In fact, %A and %C need
2115 to have the same semantics or the core LLVM "replace all uses with" concept
2116 would not hold.</p>
2117
2118 <div class="doc_code">
2119 <pre>
2120   %A = fdiv undef, %X
2121   %B = fdiv %X, undef
2122 Safe:
2123   %A = undef
2124 b: unreachable
2125 </pre>
2126 </div>
2127
2128 <p>These examples show the crucial difference between an <em>undefined
2129 value</em> and <em>undefined behavior</em>.  An undefined value (like undef) is
2130 allowed to have an arbitrary bit-pattern.  This means that the %A operation
2131 can be constant folded to undef because the undef could be an SNaN, and fdiv is
2132 not (currently) defined on SNaN's.  However, in the second example, we can make
2133 a more aggressive assumption: because the undef is allowed to be an arbitrary
2134 value, we are allowed to assume that it could be zero.  Since a divide by zero
2135 has <em>undefined behavior</em>, we are allowed to assume that the operation
2136 does not execute at all.  This allows us to delete the divide and all code after
2137 it: since the undefined operation "can't happen", the optimizer can assume that
2138 it occurs in dead code.
2139 </p>
2140
2141 <div class="doc_code">
2142 <pre>
2143 a:  store undef -> %X
2144 b:  store %X -> undef
2145 Safe:
2146 a: &lt;deleted&gt;
2147 b: unreachable
2148 </pre>
2149 </div>
2150
2151 <p>These examples reiterate the fdiv example: a store "of" an undefined value
2152 can be assumed to not have any effect: we can assume that the value is
2153 overwritten with bits that happen to match what was already there.  However, a
2154 store "to" an undefined location could clobber arbitrary memory, therefore, it
2155 has undefined behavior.</p>
2156
2157 </div>
2158
2159 <!-- ======================================================================= -->
2160 <div class="doc_subsection"><a name="blockaddress">Addresses of Basic
2161     Blocks</a></div>
2162 <div class="doc_text">
2163
2164 <p><b><tt>blockaddress(@function, %block)</tt></b></p>
2165
2166 <p>The '<tt>blockaddress</tt>' constant computes the address of the specified
2167    basic block in the specified function, and always has an i8* type.  Taking
2168    the address of the entry block is illegal.</p>
2169
2170 <p>This value only has defined behavior when used as an operand to the
2171    '<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction or for comparisons
2172    against null.  Pointer equality tests between labels addresses is undefined
2173    behavior - though, again, comparison against null is ok, and no label is
2174    equal to the null pointer.  This may also be passed around as an opaque
2175    pointer sized value as long as the bits are not inspected.  This allows
2176    <tt>ptrtoint</tt> and arithmetic to be performed on these values so long as
2177    the original value is reconstituted before the <tt>indirectbr</tt>.</p>
2178
2179 <p>Finally, some targets may provide defined semantics when
2180    using the value as the operand to an inline assembly, but that is target
2181    specific.
2182    </p>
2183
2184 </div>
2185
2186
2187 <!-- ======================================================================= -->
2188 <div class="doc_subsection"><a name="constantexprs">Constant Expressions</a>
2189 </div>
2190
2191 <div class="doc_text">
2192
2193 <p>Constant expressions are used to allow expressions involving other constants
2194    to be used as constants.  Constant expressions may be of
2195    any <a href="#t_firstclass">first class</a> type and may involve any LLVM
2196    operation that does not have side effects (e.g. load and call are not
2197    supported).  The following is the syntax for constant expressions:</p>
2198
2199 <dl>
2200   <dt><b><tt>trunc ( CST to TYPE )</tt></b></dt>
2201   <dd>Truncate a constant to another type. The bit size of CST must be larger
2202       than the bit size of TYPE. Both types must be integers.</dd>
2203
2204   <dt><b><tt>zext ( CST to TYPE )</tt></b></dt>
2205   <dd>Zero extend a constant to another type. The bit size of CST must be
2206       smaller or equal to the bit size of TYPE.  Both types must be
2207       integers.</dd>
2208
2209   <dt><b><tt>sext ( CST to TYPE )</tt></b></dt>
2210   <dd>Sign extend a constant to another type. The bit size of CST must be
2211       smaller or equal to the bit size of TYPE.  Both types must be
2212       integers.</dd>
2213
2214   <dt><b><tt>fptrunc ( CST to TYPE )</tt></b></dt>
2215   <dd>Truncate a floating point constant to another floating point type. The
2216       size of CST must be larger than the size of TYPE. Both types must be
2217       floating point.</dd>
2218
2219   <dt><b><tt>fpext ( CST to TYPE )</tt></b></dt>
2220   <dd>Floating point extend a constant to another type. The size of CST must be
2221       smaller or equal to the size of TYPE. Both types must be floating
2222       point.</dd>
2223
2224   <dt><b><tt>fptoui ( CST to TYPE )</tt></b></dt>
2225   <dd>Convert a floating point constant to the corresponding unsigned integer
2226       constant. TYPE must be a scalar or vector integer type. CST must be of
2227       scalar or vector floating point type. Both CST and TYPE must be scalars,
2228       or vectors of the same number of elements. If the value won't fit in the
2229       integer type, the results are undefined.</dd>
2230
2231   <dt><b><tt>fptosi ( CST to TYPE )</tt></b></dt>
2232   <dd>Convert a floating point constant to the corresponding signed integer
2233       constant.  TYPE must be a scalar or vector integer type. CST must be of
2234       scalar or vector floating point type. Both CST and TYPE must be scalars,
2235       or vectors of the same number of elements. If the value won't fit in the
2236       integer type, the results are undefined.</dd>
2237
2238   <dt><b><tt>uitofp ( CST to TYPE )</tt></b></dt>
2239   <dd>Convert an unsigned integer constant to the corresponding floating point
2240       constant. TYPE must be a scalar or vector floating point type. CST must be
2241       of scalar or vector integer type. Both CST and TYPE must be scalars, or
2242       vectors of the same number of elements. If the value won't fit in the
2243       floating point type, the results are undefined.</dd>
2244
2245   <dt><b><tt>sitofp ( CST to TYPE )</tt></b></dt>
2246   <dd>Convert a signed integer constant to the corresponding floating point
2247       constant. TYPE must be a scalar or vector floating point type. CST must be
2248       of scalar or vector integer type. Both CST and TYPE must be scalars, or
2249       vectors of the same number of elements. If the value won't fit in the
2250       floating point type, the results are undefined.</dd>
2251
2252   <dt><b><tt>ptrtoint ( CST to TYPE )</tt></b></dt>
2253   <dd>Convert a pointer typed constant to the corresponding integer constant
2254       <tt>TYPE</tt> must be an integer type. <tt>CST</tt> must be of pointer
2255       type. The <tt>CST</tt> value is zero extended, truncated, or unchanged to
2256       make it fit in <tt>TYPE</tt>.</dd>
2257
2258   <dt><b><tt>inttoptr ( CST to TYPE )</tt></b></dt>
2259   <dd>Convert a integer constant to a pointer constant.  TYPE must be a pointer
2260       type.  CST must be of integer type. The CST value is zero extended,
2261       truncated, or unchanged to make it fit in a pointer size. This one is
2262       <i>really</i> dangerous!</dd>
2263
2264   <dt><b><tt>bitcast ( CST to TYPE )</tt></b></dt>
2265   <dd>Convert a constant, CST, to another TYPE. The constraints of the operands
2266       are the same as those for the <a href="#i_bitcast">bitcast
2267       instruction</a>.</dd>
2268
2269   <dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
2270   <dt><b><tt>getelementptr inbounds ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
2271   <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
2272       constants.  As with the <a href="#i_getelementptr">getelementptr</a>
2273       instruction, the index list may have zero or more indexes, which are
2274       required to make sense for the type of "CSTPTR".</dd>
2275
2276   <dt><b><tt>select ( COND, VAL1, VAL2 )</tt></b></dt>
2277   <dd>Perform the <a href="#i_select">select operation</a> on constants.</dd>
2278
2279   <dt><b><tt>icmp COND ( VAL1, VAL2 )</tt></b></dt>
2280   <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd>
2281
2282   <dt><b><tt>fcmp COND ( VAL1, VAL2 )</tt></b></dt>
2283   <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd>
2284
2285   <dt><b><tt>extractelement ( VAL, IDX )</tt></b></dt>
2286   <dd>Perform the <a href="#i_extractelement">extractelement operation</a> on
2287       constants.</dd>
2288
2289   <dt><b><tt>insertelement ( VAL, ELT, IDX )</tt></b></dt>
2290   <dd>Perform the <a href="#i_insertelement">insertelement operation</a> on
2291     constants.</dd>
2292
2293   <dt><b><tt>shufflevector ( VEC1, VEC2, IDXMASK )</tt></b></dt>
2294   <dd>Perform the <a href="#i_shufflevector">shufflevector operation</a> on
2295       constants.</dd>
2296
2297   <dt><b><tt>OPCODE ( LHS, RHS )</tt></b></dt>
2298   <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may
2299       be any of the <a href="#binaryops">binary</a>
2300       or <a href="#bitwiseops">bitwise binary</a> operations.  The constraints
2301       on operands are the same as those for the corresponding instruction
2302       (e.g. no bitwise operations on floating point values are allowed).</dd>
2303 </dl>
2304
2305 </div>
2306
2307 <!-- ======================================================================= -->
2308 <div class="doc_subsection"><a name="metadata">Embedded Metadata</a>
2309 </div>
2310
2311 <div class="doc_text">
2312
2313 <p>Embedded metadata provides a way to attach arbitrary data to the instruction
2314    stream without affecting the behaviour of the program.  There are two
2315    metadata primitives, strings and nodes. All metadata has the
2316    <tt>metadata</tt> type and is identified in syntax by a preceding exclamation
2317    point ('<tt>!</tt>').</p>
2318
2319 <p>A metadata string is a string surrounded by double quotes.  It can contain
2320    any character by escaping non-printable characters with "\xx" where "xx" is
2321    the two digit hex code.  For example: "<tt>!"test\00"</tt>".</p>
2322
2323 <p>Metadata nodes are represented with notation similar to structure constants
2324    (a comma separated list of elements, surrounded by braces and preceded by an
2325    exclamation point).  For example: "<tt>!{ metadata !"test\00", i32
2326    10}</tt>".</p>
2327
2328 <p>A metadata node will attempt to track changes to the values it holds. In the
2329    event that a value is deleted, it will be replaced with a typeless
2330    "<tt>null</tt>", such as "<tt>metadata !{null, i32 10}</tt>".</p>
2331
2332 <p>A named metadata is a collection of metadata nodes. For example: "<tt>!foo =
2333    metadata !{!4, !3}</tt>".
2334
2335 <p>Optimizations may rely on metadata to provide additional information about
2336    the program that isn't available in the instructions, or that isn't easily
2337    computable. Similarly, the code generator may expect a certain metadata
2338    format to be used to express debugging information.</p>
2339
2340 </div>
2341
2342 <!-- *********************************************************************** -->
2343 <div class="doc_section"> <a name="othervalues">Other Values</a> </div>
2344 <!-- *********************************************************************** -->
2345
2346 <!-- ======================================================================= -->
2347 <div class="doc_subsection">
2348 <a name="inlineasm">Inline Assembler Expressions</a>
2349 </div>
2350
2351 <div class="doc_text">
2352
2353 <p>LLVM supports inline assembler expressions (as opposed
2354    to <a href="#moduleasm"> Module-Level Inline Assembly</a>) through the use of
2355    a special value.  This value represents the inline assembler as a string
2356    (containing the instructions to emit), a list of operand constraints (stored
2357    as a string), a flag that indicates whether or not the inline asm
2358    expression has side effects, and a flag indicating whether the function
2359    containing the asm needs to align its stack conservatively.  An example
2360    inline assembler expression is:</p>
2361
2362 <div class="doc_code">
2363 <pre>
2364 i32 (i32) asm "bswap $0", "=r,r"
2365 </pre>
2366 </div>
2367
2368 <p>Inline assembler expressions may <b>only</b> be used as the callee operand of
2369    a <a href="#i_call"><tt>call</tt> instruction</a>.  Thus, typically we
2370    have:</p>
2371
2372 <div class="doc_code">
2373 <pre>
2374 %X = call i32 asm "<a href="#int_bswap">bswap</a> $0", "=r,r"(i32 %Y)
2375 </pre>
2376 </div>
2377
2378 <p>Inline asms with side effects not visible in the constraint list must be
2379    marked as having side effects.  This is done through the use of the
2380    '<tt>sideeffect</tt>' keyword, like so:</p>
2381
2382 <div class="doc_code">
2383 <pre>
2384 call void asm sideeffect "eieio", ""()
2385 </pre>
2386 </div>
2387
2388 <p>In some cases inline asms will contain code that will not work unless the
2389    stack is aligned in some way, such as calls or SSE instructions on x86,
2390    yet will not contain code that does that alignment within the asm.
2391    The compiler should make conservative assumptions about what the asm might
2392    contain and should generate its usual stack alignment code in the prologue
2393    if the '<tt>alignstack</tt>' keyword is present:</p>
2394
2395 <div class="doc_code">
2396 <pre>
2397 call void asm alignstack "eieio", ""()
2398 </pre>
2399 </div>
2400
2401 <p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come
2402    first.</p>
2403
2404 <p>TODO: The format of the asm and constraints string still need to be
2405    documented here.  Constraints on what can be done (e.g. duplication, moving,
2406    etc need to be documented).  This is probably best done by reference to
2407    another document that covers inline asm from a holistic perspective.</p>
2408
2409 </div>
2410
2411
2412 <!-- *********************************************************************** -->
2413 <div class="doc_section">
2414   <a name="intrinsic_globals">Intrinsic Global Variables</a>
2415 </div>
2416 <!-- *********************************************************************** -->
2417
2418 <p>LLVM has a number of "magic" global variables that contain data that affect
2419 code generation or other IR semantics.  These are documented here.  All globals
2420 of this sort should have a section specified as "<tt>llvm.metadata</tt>".  This
2421 section and all globals that start with "<tt>llvm.</tt>" are reserved for use
2422 by LLVM.</p>
2423
2424 <!-- ======================================================================= -->
2425 <div class="doc_subsection">
2426 <a name="intg_used">The '<tt>llvm.used</tt>' Global Variable</a>
2427 </div>
2428
2429 <div class="doc_text">
2430
2431 <p>The <tt>@llvm.used</tt> global is an array with i8* element type which has <a
2432 href="#linkage_appending">appending linkage</a>.  This array contains a list of
2433 pointers to global variables and functions which may optionally have a pointer
2434 cast formed of bitcast or getelementptr.  For example, a legal use of it is:</p>
2435
2436 <pre>
2437   @X = global i8 4
2438   @Y = global i32 123
2439
2440   @llvm.used = appending global [2 x i8*] [
2441      i8* @X,
2442      i8* bitcast (i32* @Y to i8*)
2443   ], section "llvm.metadata"
2444 </pre>
2445
2446 <p>If a global variable appears in the <tt>@llvm.used</tt> list, then the
2447 compiler, assembler, and linker are required to treat the symbol as if there is
2448 a reference to the global that it cannot see.  For example, if a variable has
2449 internal linkage and no references other than that from the <tt>@llvm.used</tt>
2450 list, it cannot be deleted.  This is commonly used to represent references from
2451 inline asms and other things the compiler cannot "see", and corresponds to
2452 "attribute((used))" in GNU C.</p>
2453
2454 <p>On some targets, the code generator must emit a directive to the assembler or
2455 object file to prevent the assembler and linker from molesting the symbol.</p>
2456
2457 </div>
2458
2459 <!-- ======================================================================= -->
2460 <div class="doc_subsection">
2461 <a name="intg_compiler_used">The '<tt>llvm.compiler.used</tt>' Global Variable</a>
2462 </div>
2463
2464 <div class="doc_text">
2465
2466 <p>The <tt>@llvm.compiler.used</tt> directive is the same as the
2467 <tt>@llvm.used</tt> directive, except that it only prevents the compiler from
2468 touching the symbol.  On targets that support it, this allows an intelligent
2469 linker to optimize references to the symbol without being impeded as it would be
2470 by <tt>@llvm.used</tt>.</p>
2471
2472 <p>This is a rare construct that should only be used in rare circumstances, and
2473 should not be exposed to source languages.</p>
2474
2475 </div>
2476
2477 <!-- ======================================================================= -->
2478 <div class="doc_subsection">
2479 <a name="intg_global_ctors">The '<tt>llvm.global_ctors</tt>' Global Variable</a>
2480 </div>
2481
2482 <div class="doc_text">
2483
2484 <p>TODO: Describe this.</p>
2485
2486 </div>
2487
2488 <!-- ======================================================================= -->
2489 <div class="doc_subsection">
2490 <a name="intg_global_dtors">The '<tt>llvm.global_dtors</tt>' Global Variable</a>
2491 </div>
2492
2493 <div class="doc_text">
2494
2495 <p>TODO: Describe this.</p>
2496
2497 </div>
2498
2499
2500 <!-- *********************************************************************** -->
2501 <div class="doc_section"> <a name="instref">Instruction Reference</a> </div>
2502 <!-- *********************************************************************** -->
2503
2504 <div class="doc_text">
2505
2506 <p>The LLVM instruction set consists of several different classifications of
2507    instructions: <a href="#terminators">terminator
2508    instructions</a>, <a href="#binaryops">binary instructions</a>,
2509    <a href="#bitwiseops">bitwise binary instructions</a>,
2510    <a href="#memoryops">memory instructions</a>, and
2511    <a href="#otherops">other instructions</a>.</p>
2512
2513 </div>
2514
2515 <!-- ======================================================================= -->
2516 <div class="doc_subsection"> <a name="terminators">Terminator
2517 Instructions</a> </div>
2518
2519 <div class="doc_text">
2520
2521 <p>As mentioned <a href="#functionstructure">previously</a>, every basic block
2522    in a program ends with a "Terminator" instruction, which indicates which
2523    block should be executed after the current block is finished. These
2524    terminator instructions typically yield a '<tt>void</tt>' value: they produce
2525    control flow, not values (the one exception being the
2526    '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
2527
2528 <p>There are six different terminator instructions: the
2529    '<a href="#i_ret"><tt>ret</tt></a>' instruction, the
2530    '<a href="#i_br"><tt>br</tt></a>' instruction, the
2531    '<a href="#i_switch"><tt>switch</tt></a>' instruction, the
2532    '<a href="#i_indirectbr">'<tt>indirectbr</tt></a>' Instruction, the
2533    '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the
2534    '<a href="#i_unwind"><tt>unwind</tt></a>' instruction, and the
2535    '<a href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p>
2536
2537 </div>
2538
2539 <!-- _______________________________________________________________________ -->
2540 <div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>'
2541 Instruction</a> </div>
2542
2543 <div class="doc_text">
2544
2545 <h5>Syntax:</h5>
2546 <pre>
2547   ret &lt;type&gt; &lt;value&gt;       <i>; Return a value from a non-void function</i>
2548   ret void                 <i>; Return from void function</i>
2549 </pre>
2550
2551 <h5>Overview:</h5>
2552 <p>The '<tt>ret</tt>' instruction is used to return control flow (and optionally
2553    a value) from a function back to the caller.</p>
2554
2555 <p>There are two forms of the '<tt>ret</tt>' instruction: one that returns a
2556    value and then causes control flow, and one that just causes control flow to
2557    occur.</p>
2558
2559 <h5>Arguments:</h5>
2560 <p>The '<tt>ret</tt>' instruction optionally accepts a single argument, the
2561    return value. The type of the return value must be a
2562    '<a href="#t_firstclass">first class</a>' type.</p>
2563
2564 <p>A function is not <a href="#wellformed">well formed</a> if it it has a
2565    non-void return type and contains a '<tt>ret</tt>' instruction with no return
2566    value or a return value with a type that does not match its type, or if it
2567    has a void return type and contains a '<tt>ret</tt>' instruction with a
2568    return value.</p>
2569
2570 <h5>Semantics:</h5>
2571 <p>When the '<tt>ret</tt>' instruction is executed, control flow returns back to
2572    the calling function's context.  If the caller is a
2573    "<a href="#i_call"><tt>call</tt></a>" instruction, execution continues at the
2574    instruction after the call.  If the caller was an
2575    "<a href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at
2576    the beginning of the "normal" destination block.  If the instruction returns
2577    a value, that value shall set the call or invoke instruction's return
2578    value.</p>
2579
2580 <h5>Example:</h5>
2581 <pre>
2582   ret i32 5                       <i>; Return an integer value of 5</i>
2583   ret void                        <i>; Return from a void function</i>
2584   ret { i32, i8 } { i32 4, i8 2 } <i>; Return a struct of values 4 and 2</i>
2585 </pre>
2586
2587 </div>
2588 <!-- _______________________________________________________________________ -->
2589 <div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div>
2590
2591 <div class="doc_text">
2592
2593 <h5>Syntax:</h5>
2594 <pre>
2595   br i1 &lt;cond&gt;, label &lt;iftrue&gt;, label &lt;iffalse&gt;<br>  br label &lt;dest&gt;          <i>; Unconditional branch</i>
2596 </pre>
2597
2598 <h5>Overview:</h5>
2599 <p>The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
2600    different basic block in the current function.  There are two forms of this
2601    instruction, corresponding to a conditional branch and an unconditional
2602    branch.</p>
2603
2604 <h5>Arguments:</h5>
2605 <p>The conditional branch form of the '<tt>br</tt>' instruction takes a single
2606    '<tt>i1</tt>' value and two '<tt>label</tt>' values.  The unconditional form
2607    of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
2608    target.</p>
2609
2610 <h5>Semantics:</h5>
2611 <p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>i1</tt>'
2612    argument is evaluated.  If the value is <tt>true</tt>, control flows to the
2613    '<tt>iftrue</tt>' <tt>label</tt> argument.  If "cond" is <tt>false</tt>,
2614    control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p>
2615
2616 <h5>Example:</h5>
2617 <pre>
2618 Test:
2619   %cond = <a href="#i_icmp">icmp</a> eq i32 %a, %b
2620   br i1 %cond, label %IfEqual, label %IfUnequal
2621 IfEqual:
2622   <a href="#i_ret">ret</a> i32 1
2623 IfUnequal:
2624   <a href="#i_ret">ret</a> i32 0
2625 </pre>
2626
2627 </div>
2628
2629 <!-- _______________________________________________________________________ -->
2630 <div class="doc_subsubsection">
2631    <a name="i_switch">'<tt>switch</tt>' Instruction</a>
2632 </div>
2633
2634 <div class="doc_text">
2635
2636 <h5>Syntax:</h5>
2637 <pre>
2638   switch &lt;intty&gt; &lt;value&gt;, label &lt;defaultdest&gt; [ &lt;intty&gt; &lt;val&gt;, label &lt;dest&gt; ... ]
2639 </pre>
2640
2641 <h5>Overview:</h5>
2642 <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
2643    several different places.  It is a generalization of the '<tt>br</tt>'
2644    instruction, allowing a branch to occur to one of many possible
2645    destinations.</p>
2646
2647 <h5>Arguments:</h5>
2648 <p>The '<tt>switch</tt>' instruction uses three parameters: an integer
2649    comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination,
2650    and an array of pairs of comparison value constants and '<tt>label</tt>'s.
2651    The table is not allowed to contain duplicate constant entries.</p>
2652
2653 <h5>Semantics:</h5>
2654 <p>The <tt>switch</tt> instruction specifies a table of values and
2655    destinations. When the '<tt>switch</tt>' instruction is executed, this table
2656    is searched for the given value.  If the value is found, control flow is
2657    transferred to the corresponding destination; otherwise, control flow is
2658    transferred to the default destination.</p>
2659
2660 <h5>Implementation:</h5>
2661 <p>Depending on properties of the target machine and the particular
2662    <tt>switch</tt> instruction, this instruction may be code generated in
2663    different ways.  For example, it could be generated as a series of chained
2664    conditional branches or with a lookup table.</p>
2665
2666 <h5>Example:</h5>
2667 <pre>
2668  <i>; Emulate a conditional br instruction</i>
2669  %Val = <a href="#i_zext">zext</a> i1 %value to i32
2670  switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
2671
2672  <i>; Emulate an unconditional br instruction</i>
2673  switch i32 0, label %dest [ ]
2674
2675  <i>; Implement a jump table:</i>
2676  switch i32 %val, label %otherwise [ i32 0, label %onzero
2677                                      i32 1, label %onone
2678                                      i32 2, label %ontwo ]
2679 </pre>
2680
2681 </div>
2682
2683
2684 <!-- _______________________________________________________________________ -->
2685 <div class="doc_subsubsection">
2686    <a name="i_indirectbr">'<tt>indirectbr</tt>' Instruction</a>
2687 </div>
2688
2689 <div class="doc_text">
2690
2691 <h5>Syntax:</h5>
2692 <pre>
2693   indirectbr &lt;somety&gt;* &lt;address&gt;, [ label &lt;dest1&gt;, label &lt;dest2&gt;, ... ]
2694 </pre>
2695
2696 <h5>Overview:</h5>
2697
2698 <p>The '<tt>indirectbr</tt>' instruction implements an indirect branch to a label
2699    within the current function, whose address is specified by
2700    "<tt>address</tt>".  Address must be derived from a <a
2701    href="#blockaddress">blockaddress</a> constant.</p>
2702
2703 <h5>Arguments:</h5>
2704
2705 <p>The '<tt>address</tt>' argument is the address of the label to jump to.  The
2706    rest of the arguments indicate the full set of possible destinations that the
2707    address may point to.  Blocks are allowed to occur multiple times in the
2708    destination list, though this isn't particularly useful.</p>
2709
2710 <p>This destination list is required so that dataflow analysis has an accurate
2711    understanding of the CFG.</p>
2712
2713 <h5>Semantics:</h5>
2714
2715 <p>Control transfers to the block specified in the address argument.  All
2716    possible destination blocks must be listed in the label list, otherwise this
2717    instruction has undefined behavior.  This implies that jumps to labels
2718    defined in other functions have undefined behavior as well.</p>
2719
2720 <h5>Implementation:</h5>
2721
2722 <p>This is typically implemented with a jump through a register.</p>
2723
2724 <h5>Example:</h5>
2725 <pre>
2726  indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
2727 </pre>
2728
2729 </div>
2730
2731
2732 <!-- _______________________________________________________________________ -->
2733 <div class="doc_subsubsection">
2734   <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
2735 </div>
2736
2737 <div class="doc_text">
2738
2739 <h5>Syntax:</h5>
2740 <pre>
2741   &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>]
2742                 to label &lt;normal label&gt; unwind label &lt;exception label&gt;
2743 </pre>
2744
2745 <h5>Overview:</h5>
2746 <p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified
2747    function, with the possibility of control flow transfer to either the
2748    '<tt>normal</tt>' label or the '<tt>exception</tt>' label.  If the callee
2749    function returns with the "<tt><a href="#i_ret">ret</a></tt>" instruction,
2750    control flow will return to the "normal" label.  If the callee (or any
2751    indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>"
2752    instruction, control is interrupted and continued at the dynamically nearest
2753    "exception" label.</p>
2754
2755 <h5>Arguments:</h5>
2756 <p>This instruction requires several arguments:</p>
2757
2758 <ol>
2759   <li>The optional "cconv" marker indicates which <a href="#callingconv">calling
2760       convention</a> the call should use.  If none is specified, the call
2761       defaults to using C calling conventions.</li>
2762
2763   <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
2764       return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
2765       '<tt>inreg</tt>' attributes are valid here.</li>
2766
2767   <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
2768       function value being invoked.  In most cases, this is a direct function
2769       invocation, but indirect <tt>invoke</tt>s are just as possible, branching
2770       off an arbitrary pointer to function value.</li>
2771
2772   <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
2773       function to be invoked. </li>
2774
2775   <li>'<tt>function args</tt>': argument list whose types match the function
2776       signature argument types.  If the function signature indicates the
2777       function accepts a variable number of arguments, the extra arguments can
2778       be specified.</li>
2779
2780   <li>'<tt>normal label</tt>': the label reached when the called function
2781       executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
2782
2783   <li>'<tt>exception label</tt>': the label reached when a callee returns with
2784       the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li>
2785
2786   <li>The optional <a href="#fnattrs">function attributes</a> list. Only
2787       '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
2788       '<tt>readnone</tt>' attributes are valid here.</li>
2789 </ol>
2790
2791 <h5>Semantics:</h5>
2792 <p>This instruction is designed to operate as a standard
2793    '<tt><a href="#i_call">call</a></tt>' instruction in most regards.  The
2794    primary difference is that it establishes an association with a label, which
2795    is used by the runtime library to unwind the stack.</p>
2796
2797 <p>This instruction is used in languages with destructors to ensure that proper
2798    cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
2799    exception.  Additionally, this is important for implementation of
2800    '<tt>catch</tt>' clauses in high-level languages that support them.</p>
2801
2802 <p>For the purposes of the SSA form, the definition of the value returned by the
2803    '<tt>invoke</tt>' instruction is deemed to occur on the edge from the current
2804    block to the "normal" label. If the callee unwinds then no return value is
2805    available.</p>
2806
2807 <h5>Example:</h5>
2808 <pre>
2809   %retval = invoke i32 @Test(i32 15) to label %Continue
2810               unwind label %TestCleanup              <i>; {i32}:retval set</i>
2811   %retval = invoke <a href="#callingconv">coldcc</a> i32 %Testfnptr(i32 15) to label %Continue
2812               unwind label %TestCleanup              <i>; {i32}:retval set</i>
2813 </pre>
2814
2815 </div>
2816
2817 <!-- _______________________________________________________________________ -->
2818
2819 <div class="doc_subsubsection"> <a name="i_unwind">'<tt>unwind</tt>'
2820 Instruction</a> </div>
2821
2822 <div class="doc_text">
2823
2824 <h5>Syntax:</h5>
2825 <pre>
2826   unwind
2827 </pre>
2828
2829 <h5>Overview:</h5>
2830 <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow
2831    at the first callee in the dynamic call stack which used
2832    an <a href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call.
2833    This is primarily used to implement exception handling.</p>
2834
2835 <h5>Semantics:</h5>
2836 <p>The '<tt>unwind</tt>' instruction causes execution of the current function to
2837    immediately halt.  The dynamic call stack is then searched for the
2838    first <a href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack.
2839    Once found, execution continues at the "exceptional" destination block
2840    specified by the <tt>invoke</tt> instruction.  If there is no <tt>invoke</tt>
2841    instruction in the dynamic call chain, undefined behavior results.</p>
2842
2843 </div>
2844
2845 <!-- _______________________________________________________________________ -->
2846
2847 <div class="doc_subsubsection"> <a name="i_unreachable">'<tt>unreachable</tt>'
2848 Instruction</a> </div>
2849
2850 <div class="doc_text">
2851
2852 <h5>Syntax:</h5>
2853 <pre>
2854   unreachable
2855 </pre>
2856
2857 <h5>Overview:</h5>
2858 <p>The '<tt>unreachable</tt>' instruction has no defined semantics.  This
2859    instruction is used to inform the optimizer that a particular portion of the
2860    code is not reachable.  This can be used to indicate that the code after a
2861    no-return function cannot be reached, and other facts.</p>
2862
2863 <h5>Semantics:</h5>
2864 <p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p>
2865
2866 </div>
2867
2868 <!-- ======================================================================= -->
2869 <div class="doc_subsection"> <a name="binaryops">Binary Operations</a> </div>
2870
2871 <div class="doc_text">
2872
2873 <p>Binary operators are used to do most of the computation in a program.  They
2874    require two operands of the same type, execute an operation on them, and
2875    produce a single value.  The operands might represent multiple data, as is
2876    the case with the <a href="#t_vector">vector</a> data type.  The result value
2877    has the same type as its operands.</p>
2878
2879 <p>There are several different binary operators:</p>
2880
2881 </div>
2882
2883 <!-- _______________________________________________________________________ -->
2884 <div class="doc_subsubsection">
2885   <a name="i_add">'<tt>add</tt>' Instruction</a>
2886 </div>
2887
2888 <div class="doc_text">
2889
2890 <h5>Syntax:</h5>
2891 <pre>
2892   &lt;result&gt; = add &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;          <i>; yields {ty}:result</i>
2893   &lt;result&gt; = add nuw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
2894   &lt;result&gt; = add nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
2895   &lt;result&gt; = add nuw nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;  <i>; yields {ty}:result</i>
2896 </pre>
2897
2898 <h5>Overview:</h5>
2899 <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
2900
2901 <h5>Arguments:</h5>
2902 <p>The two arguments to the '<tt>add</tt>' instruction must
2903    be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
2904    integer values. Both arguments must have identical types.</p>
2905
2906 <h5>Semantics:</h5>
2907 <p>The value produced is the integer sum of the two operands.</p>
2908
2909 <p>If the sum has unsigned overflow, the result returned is the mathematical
2910    result modulo 2<sup>n</sup>, where n is the bit width of the result.</p>
2911
2912 <p>Because LLVM integers use a two's complement representation, this instruction
2913    is appropriate for both signed and unsigned integers.</p>
2914
2915 <p><tt>nuw</tt> and <tt>nsw</tt> stand for &quot;No Unsigned Wrap&quot;
2916    and &quot;No Signed Wrap&quot;, respectively. If the <tt>nuw</tt> and/or
2917    <tt>nsw</tt> keywords are present, the result value of the <tt>add</tt>
2918    is undefined if unsigned and/or signed overflow, respectively, occurs.</p>
2919
2920 <h5>Example:</h5>
2921 <pre>
2922   &lt;result&gt; = add i32 4, %var          <i>; yields {i32}:result = 4 + %var</i>
2923 </pre>
2924
2925 </div>
2926
2927 <!-- _______________________________________________________________________ -->
2928 <div class="doc_subsubsection">
2929   <a name="i_fadd">'<tt>fadd</tt>' Instruction</a>
2930 </div>
2931
2932 <div class="doc_text">
2933
2934 <h5>Syntax:</h5>
2935 <pre>
2936   &lt;result&gt; = fadd &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
2937 </pre>
2938
2939 <h5>Overview:</h5>
2940 <p>The '<tt>fadd</tt>' instruction returns the sum of its two operands.</p>
2941
2942 <h5>Arguments:</h5>
2943 <p>The two arguments to the '<tt>fadd</tt>' instruction must be
2944    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
2945    floating point values. Both arguments must have identical types.</p>
2946
2947 <h5>Semantics:</h5>
2948 <p>The value produced is the floating point sum of the two operands.</p>
2949
2950 <h5>Example:</h5>
2951 <pre>
2952   &lt;result&gt; = fadd float 4.0, %var          <i>; yields {float}:result = 4.0 + %var</i>
2953 </pre>
2954
2955 </div>
2956
2957 <!-- _______________________________________________________________________ -->
2958 <div class="doc_subsubsection">
2959    <a name="i_sub">'<tt>sub</tt>' Instruction</a>
2960 </div>
2961
2962 <div class="doc_text">
2963
2964 <h5>Syntax:</h5>
2965 <pre>
2966   &lt;result&gt; = sub &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;          <i>; yields {ty}:result</i>
2967   &lt;result&gt; = sub nuw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
2968   &lt;result&gt; = sub nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
2969   &lt;result&gt; = sub nuw nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;  <i>; yields {ty}:result</i>
2970 </pre>
2971
2972 <h5>Overview:</h5>
2973 <p>The '<tt>sub</tt>' instruction returns the difference of its two
2974    operands.</p>
2975
2976 <p>Note that the '<tt>sub</tt>' instruction is used to represent the
2977    '<tt>neg</tt>' instruction present in most other intermediate
2978    representations.</p>
2979
2980 <h5>Arguments:</h5>
2981 <p>The two arguments to the '<tt>sub</tt>' instruction must
2982    be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
2983    integer values.  Both arguments must have identical types.</p>
2984
2985 <h5>Semantics:</h5>
2986 <p>The value produced is the integer difference of the two operands.</p>
2987
2988 <p>If the difference has unsigned overflow, the result returned is the
2989    mathematical result modulo 2<sup>n</sup>, where n is the bit width of the
2990    result.</p>
2991
2992 <p>Because LLVM integers use a two's complement representation, this instruction
2993    is appropriate for both signed and unsigned integers.</p>
2994
2995 <p><tt>nuw</tt> and <tt>nsw</tt> stand for &quot;No Unsigned Wrap&quot;
2996    and &quot;No Signed Wrap&quot;, respectively. If the <tt>nuw</tt> and/or
2997    <tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt>
2998    is undefined if unsigned and/or signed overflow, respectively, occurs.</p>
2999
3000 <h5>Example:</h5>
3001 <pre>
3002   &lt;result&gt; = sub i32 4, %var          <i>; yields {i32}:result = 4 - %var</i>
3003   &lt;result&gt; = sub i32 0, %val          <i>; yields {i32}:result = -%var</i>
3004 </pre>
3005
3006 </div>
3007
3008 <!-- _______________________________________________________________________ -->
3009 <div class="doc_subsubsection">
3010    <a name="i_fsub">'<tt>fsub</tt>' Instruction</a>
3011 </div>
3012
3013 <div class="doc_text">
3014
3015 <h5>Syntax:</h5>
3016 <pre>
3017   &lt;result&gt; = fsub &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3018 </pre>
3019
3020 <h5>Overview:</h5>
3021 <p>The '<tt>fsub</tt>' instruction returns the difference of its two
3022    operands.</p>
3023
3024 <p>Note that the '<tt>fsub</tt>' instruction is used to represent the
3025    '<tt>fneg</tt>' instruction present in most other intermediate
3026    representations.</p>
3027
3028 <h5>Arguments:</h5>
3029 <p>The two arguments to the '<tt>fsub</tt>' instruction must be
3030    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3031    floating point values.  Both arguments must have identical types.</p>
3032
3033 <h5>Semantics:</h5>
3034 <p>The value produced is the floating point difference of the two operands.</p>
3035
3036 <h5>Example:</h5>
3037 <pre>
3038   &lt;result&gt; = fsub float 4.0, %var           <i>; yields {float}:result = 4.0 - %var</i>
3039   &lt;result&gt; = fsub float -0.0, %val          <i>; yields {float}:result = -%var</i>
3040 </pre>
3041
3042 </div>
3043
3044 <!-- _______________________________________________________________________ -->
3045 <div class="doc_subsubsection">
3046   <a name="i_mul">'<tt>mul</tt>' Instruction</a>
3047 </div>
3048
3049 <div class="doc_text">
3050
3051 <h5>Syntax:</h5>
3052 <pre>
3053   &lt;result&gt; = mul &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;          <i>; yields {ty}:result</i>
3054   &lt;result&gt; = mul nuw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3055   &lt;result&gt; = mul nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;      <i>; yields {ty}:result</i>
3056   &lt;result&gt; = mul nuw nsw &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;  <i>; yields {ty}:result</i>
3057 </pre>
3058
3059 <h5>Overview:</h5>
3060 <p>The '<tt>mul</tt>' instruction returns the product of its two operands.</p>
3061
3062 <h5>Arguments:</h5>
3063 <p>The two arguments to the '<tt>mul</tt>' instruction must
3064    be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
3065    integer values.  Both arguments must have identical types.</p>
3066
3067 <h5>Semantics:</h5>
3068 <p>The value produced is the integer product of the two operands.</p>
3069
3070 <p>If the result of the multiplication has unsigned overflow, the result
3071    returned is the mathematical result modulo 2<sup>n</sup>, where n is the bit
3072    width of the result.</p>
3073
3074 <p>Because LLVM integers use a two's complement representation, and the result
3075    is the same width as the operands, this instruction returns the correct
3076    result for both signed and unsigned integers.  If a full product
3077    (e.g. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands should
3078    be sign-extended or zero-extended as appropriate to the width of the full
3079    product.</p>
3080
3081 <p><tt>nuw</tt> and <tt>nsw</tt> stand for &quot;No Unsigned Wrap&quot;
3082    and &quot;No Signed Wrap&quot;, respectively. If the <tt>nuw</tt> and/or
3083    <tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt>
3084    is undefined if unsigned and/or signed overflow, respectively, occurs.</p>
3085
3086 <h5>Example:</h5>
3087 <pre>
3088   &lt;result&gt; = mul i32 4, %var          <i>; yields {i32}:result = 4 * %var</i>
3089 </pre>
3090
3091 </div>
3092
3093 <!-- _______________________________________________________________________ -->
3094 <div class="doc_subsubsection">
3095   <a name="i_fmul">'<tt>fmul</tt>' Instruction</a>
3096 </div>
3097
3098 <div class="doc_text">
3099
3100 <h5>Syntax:</h5>
3101 <pre>
3102   &lt;result&gt; = fmul &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3103 </pre>
3104
3105 <h5>Overview:</h5>
3106 <p>The '<tt>fmul</tt>' instruction returns the product of its two operands.</p>
3107
3108 <h5>Arguments:</h5>
3109 <p>The two arguments to the '<tt>fmul</tt>' instruction must be
3110    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3111    floating point values.  Both arguments must have identical types.</p>
3112
3113 <h5>Semantics:</h5>
3114 <p>The value produced is the floating point product of the two operands.</p>
3115
3116 <h5>Example:</h5>
3117 <pre>
3118   &lt;result&gt; = fmul float 4.0, %var          <i>; yields {float}:result = 4.0 * %var</i>
3119 </pre>
3120
3121 </div>
3122
3123 <!-- _______________________________________________________________________ -->
3124 <div class="doc_subsubsection"> <a name="i_udiv">'<tt>udiv</tt>' Instruction
3125 </a></div>
3126
3127 <div class="doc_text">
3128
3129 <h5>Syntax:</h5>
3130 <pre>
3131   &lt;result&gt; = udiv &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3132 </pre>
3133
3134 <h5>Overview:</h5>
3135 <p>The '<tt>udiv</tt>' instruction returns the quotient of its two operands.</p>
3136
3137 <h5>Arguments:</h5>
3138 <p>The two arguments to the '<tt>udiv</tt>' instruction must be
3139    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3140    values.  Both arguments must have identical types.</p>
3141
3142 <h5>Semantics:</h5>
3143 <p>The value produced is the unsigned integer quotient of the two operands.</p>
3144
3145 <p>Note that unsigned integer division and signed integer division are distinct
3146    operations; for signed integer division, use '<tt>sdiv</tt>'.</p>
3147
3148 <p>Division by zero leads to undefined behavior.</p>
3149
3150 <h5>Example:</h5>
3151 <pre>
3152   &lt;result&gt; = udiv i32 4, %var          <i>; yields {i32}:result = 4 / %var</i>
3153 </pre>
3154
3155 </div>
3156
3157 <!-- _______________________________________________________________________ -->
3158 <div class="doc_subsubsection"> <a name="i_sdiv">'<tt>sdiv</tt>' Instruction
3159 </a> </div>
3160
3161 <div class="doc_text">
3162
3163 <h5>Syntax:</h5>
3164 <pre>
3165   &lt;result&gt; = sdiv &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;         <i>; yields {ty}:result</i>
3166   &lt;result&gt; = sdiv exact &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3167 </pre>
3168
3169 <h5>Overview:</h5>
3170 <p>The '<tt>sdiv</tt>' instruction returns the quotient of its two operands.</p>
3171
3172 <h5>Arguments:</h5>
3173 <p>The two arguments to the '<tt>sdiv</tt>' instruction must be
3174    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3175    values.  Both arguments must have identical types.</p>
3176
3177 <h5>Semantics:</h5>
3178 <p>The value produced is the signed integer quotient of the two operands rounded
3179    towards zero.</p>
3180
3181 <p>Note that signed integer division and unsigned integer division are distinct
3182    operations; for unsigned integer division, use '<tt>udiv</tt>'.</p>
3183
3184 <p>Division by zero leads to undefined behavior. Overflow also leads to
3185    undefined behavior; this is a rare case, but can occur, for example, by doing
3186    a 32-bit division of -2147483648 by -1.</p>
3187
3188 <p>If the <tt>exact</tt> keyword is present, the result value of the
3189    <tt>sdiv</tt> is undefined if the result would be rounded or if overflow
3190    would occur.</p>
3191
3192 <h5>Example:</h5>
3193 <pre>
3194   &lt;result&gt; = sdiv i32 4, %var          <i>; yields {i32}:result = 4 / %var</i>
3195 </pre>
3196
3197 </div>
3198
3199 <!-- _______________________________________________________________________ -->
3200 <div class="doc_subsubsection"> <a name="i_fdiv">'<tt>fdiv</tt>'
3201 Instruction</a> </div>
3202
3203 <div class="doc_text">
3204
3205 <h5>Syntax:</h5>
3206 <pre>
3207   &lt;result&gt; = fdiv &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3208 </pre>
3209
3210 <h5>Overview:</h5>
3211 <p>The '<tt>fdiv</tt>' instruction returns the quotient of its two operands.</p>
3212
3213 <h5>Arguments:</h5>
3214 <p>The two arguments to the '<tt>fdiv</tt>' instruction must be
3215    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3216    floating point values.  Both arguments must have identical types.</p>
3217
3218 <h5>Semantics:</h5>
3219 <p>The value produced is the floating point quotient of the two operands.</p>
3220
3221 <h5>Example:</h5>
3222 <pre>
3223   &lt;result&gt; = fdiv float 4.0, %var          <i>; yields {float}:result = 4.0 / %var</i>
3224 </pre>
3225
3226 </div>
3227
3228 <!-- _______________________________________________________________________ -->
3229 <div class="doc_subsubsection"> <a name="i_urem">'<tt>urem</tt>' Instruction</a>
3230 </div>
3231
3232 <div class="doc_text">
3233
3234 <h5>Syntax:</h5>
3235 <pre>
3236   &lt;result&gt; = urem &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3237 </pre>
3238
3239 <h5>Overview:</h5>
3240 <p>The '<tt>urem</tt>' instruction returns the remainder from the unsigned
3241    division of its two arguments.</p>
3242
3243 <h5>Arguments:</h5>
3244 <p>The two arguments to the '<tt>urem</tt>' instruction must be
3245    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3246    values.  Both arguments must have identical types.</p>
3247
3248 <h5>Semantics:</h5>
3249 <p>This instruction returns the unsigned integer <i>remainder</i> of a division.
3250    This instruction always performs an unsigned division to get the
3251    remainder.</p>
3252
3253 <p>Note that unsigned integer remainder and signed integer remainder are
3254    distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p>
3255
3256 <p>Taking the remainder of a division by zero leads to undefined behavior.</p>
3257
3258 <h5>Example:</h5>
3259 <pre>
3260   &lt;result&gt; = urem i32 4, %var          <i>; yields {i32}:result = 4 % %var</i>
3261 </pre>
3262
3263 </div>
3264
3265 <!-- _______________________________________________________________________ -->
3266 <div class="doc_subsubsection">
3267   <a name="i_srem">'<tt>srem</tt>' Instruction</a>
3268 </div>
3269
3270 <div class="doc_text">
3271
3272 <h5>Syntax:</h5>
3273 <pre>
3274   &lt;result&gt; = srem &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3275 </pre>
3276
3277 <h5>Overview:</h5>
3278 <p>The '<tt>srem</tt>' instruction returns the remainder from the signed
3279    division of its two operands. This instruction can also take
3280    <a href="#t_vector">vector</a> versions of the values in which case the
3281    elements must be integers.</p>
3282
3283 <h5>Arguments:</h5>
3284 <p>The two arguments to the '<tt>srem</tt>' instruction must be
3285    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3286    values.  Both arguments must have identical types.</p>
3287
3288 <h5>Semantics:</h5>
3289 <p>This instruction returns the <i>remainder</i> of a division (where the result
3290    has the same sign as the dividend, <tt>op1</tt>), not the <i>modulo</i>
3291    operator (where the result has the same sign as the divisor, <tt>op2</tt>) of
3292    a value.  For more information about the difference,
3293    see <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
3294    Math Forum</a>. For a table of how this is implemented in various languages,
3295    please see <a href="http://en.wikipedia.org/wiki/Modulo_operation">
3296    Wikipedia: modulo operation</a>.</p>
3297
3298 <p>Note that signed integer remainder and unsigned integer remainder are
3299    distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p>
3300
3301 <p>Taking the remainder of a division by zero leads to undefined behavior.
3302    Overflow also leads to undefined behavior; this is a rare case, but can
3303    occur, for example, by taking the remainder of a 32-bit division of
3304    -2147483648 by -1.  (The remainder doesn't actually overflow, but this rule
3305    lets srem be implemented using instructions that return both the result of
3306    the division and the remainder.)</p>
3307
3308 <h5>Example:</h5>
3309 <pre>
3310   &lt;result&gt; = srem i32 4, %var          <i>; yields {i32}:result = 4 % %var</i>
3311 </pre>
3312
3313 </div>
3314
3315 <!-- _______________________________________________________________________ -->
3316 <div class="doc_subsubsection">
3317   <a name="i_frem">'<tt>frem</tt>' Instruction</a> </div>
3318
3319 <div class="doc_text">
3320
3321 <h5>Syntax:</h5>
3322 <pre>
3323   &lt;result&gt; = frem &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>frem</tt>' instruction returns the remainder from the division of
3328    its two operands.</p>
3329
3330 <h5>Arguments:</h5>
3331 <p>The two arguments to the '<tt>frem</tt>' instruction must be
3332    <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
3333    floating point values.  Both arguments must have identical types.</p>
3334
3335 <h5>Semantics:</h5>
3336 <p>This instruction returns the <i>remainder</i> of a division.  The remainder
3337    has the same sign as the dividend.</p>
3338
3339 <h5>Example:</h5>
3340 <pre>
3341   &lt;result&gt; = frem float 4.0, %var          <i>; yields {float}:result = 4.0 % %var</i>
3342 </pre>
3343
3344 </div>
3345
3346 <!-- ======================================================================= -->
3347 <div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary
3348 Operations</a> </div>
3349
3350 <div class="doc_text">
3351
3352 <p>Bitwise binary operators are used to do various forms of bit-twiddling in a
3353    program.  They are generally very efficient instructions and can commonly be
3354    strength reduced from other instructions.  They require two operands of the
3355    same type, execute an operation on them, and produce a single value.  The
3356    resulting value is the same type as its operands.</p>
3357
3358 </div>
3359
3360 <!-- _______________________________________________________________________ -->
3361 <div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>'
3362 Instruction</a> </div>
3363
3364 <div class="doc_text">
3365
3366 <h5>Syntax:</h5>
3367 <pre>
3368   &lt;result&gt; = shl &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3369 </pre>
3370
3371 <h5>Overview:</h5>
3372 <p>The '<tt>shl</tt>' instruction returns the first operand shifted to the left
3373    a specified number of bits.</p>
3374
3375 <h5>Arguments:</h5>
3376 <p>Both arguments to the '<tt>shl</tt>' instruction must be the
3377     same <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
3378     integer type.  '<tt>op2</tt>' is treated as an unsigned value.</p>
3379
3380 <h5>Semantics:</h5>
3381 <p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod
3382    2<sup>n</sup>, where <tt>n</tt> is the width of the result.  If <tt>op2</tt>
3383    is (statically or dynamically) negative or equal to or larger than the number
3384    of bits in <tt>op1</tt>, the result is undefined.  If the arguments are
3385    vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
3386    shift amount in <tt>op2</tt>.</p>
3387
3388 <h5>Example:</h5>
3389 <pre>
3390   &lt;result&gt; = shl i32 4, %var   <i>; yields {i32}: 4 &lt;&lt; %var</i>
3391   &lt;result&gt; = shl i32 4, 2      <i>; yields {i32}: 16</i>
3392   &lt;result&gt; = shl i32 1, 10     <i>; yields {i32}: 1024</i>
3393   &lt;result&gt; = shl i32 1, 32     <i>; undefined</i>
3394   &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>
3395 </pre>
3396
3397 </div>
3398
3399 <!-- _______________________________________________________________________ -->
3400 <div class="doc_subsubsection"> <a name="i_lshr">'<tt>lshr</tt>'
3401 Instruction</a> </div>
3402
3403 <div class="doc_text">
3404
3405 <h5>Syntax:</h5>
3406 <pre>
3407   &lt;result&gt; = lshr &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3408 </pre>
3409
3410 <h5>Overview:</h5>
3411 <p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first
3412    operand shifted to the right a specified number of bits with zero fill.</p>
3413
3414 <h5>Arguments:</h5>
3415 <p>Both arguments to the '<tt>lshr</tt>' instruction must be the same
3416    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3417    type. '<tt>op2</tt>' is treated as an unsigned value.</p>
3418
3419 <h5>Semantics:</h5>
3420 <p>This instruction always performs a logical shift right operation. The most
3421    significant bits of the result will be filled with zero bits after the shift.
3422    If <tt>op2</tt> is (statically or dynamically) equal to or larger than the
3423    number of bits in <tt>op1</tt>, the result is undefined. If the arguments are
3424    vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
3425    shift amount in <tt>op2</tt>.</p>
3426
3427 <h5>Example:</h5>
3428 <pre>
3429   &lt;result&gt; = lshr i32 4, 1   <i>; yields {i32}:result = 2</i>
3430   &lt;result&gt; = lshr i32 4, 2   <i>; yields {i32}:result = 1</i>
3431   &lt;result&gt; = lshr i8  4, 3   <i>; yields {i8}:result = 0</i>
3432   &lt;result&gt; = lshr i8 -2, 1   <i>; yields {i8}:result = 0x7FFFFFFF </i>
3433   &lt;result&gt; = lshr i32 1, 32  <i>; undefined</i>
3434   &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>
3435 </pre>
3436
3437 </div>
3438
3439 <!-- _______________________________________________________________________ -->
3440 <div class="doc_subsubsection"> <a name="i_ashr">'<tt>ashr</tt>'
3441 Instruction</a> </div>
3442 <div class="doc_text">
3443
3444 <h5>Syntax:</h5>
3445 <pre>
3446   &lt;result&gt; = ashr &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3447 </pre>
3448
3449 <h5>Overview:</h5>
3450 <p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first
3451    operand shifted to the right a specified number of bits with sign
3452    extension.</p>
3453
3454 <h5>Arguments:</h5>
3455 <p>Both arguments to the '<tt>ashr</tt>' instruction must be the same
3456    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3457    type.  '<tt>op2</tt>' is treated as an unsigned value.</p>
3458
3459 <h5>Semantics:</h5>
3460 <p>This instruction always performs an arithmetic shift right operation, The
3461    most significant bits of the result will be filled with the sign bit
3462    of <tt>op1</tt>.  If <tt>op2</tt> is (statically or dynamically) equal to or
3463    larger than the number of bits in <tt>op1</tt>, the result is undefined. If
3464    the arguments are vectors, each vector element of <tt>op1</tt> is shifted by
3465    the corresponding shift amount in <tt>op2</tt>.</p>
3466
3467 <h5>Example:</h5>
3468 <pre>
3469   &lt;result&gt; = ashr i32 4, 1   <i>; yields {i32}:result = 2</i>
3470   &lt;result&gt; = ashr i32 4, 2   <i>; yields {i32}:result = 1</i>
3471   &lt;result&gt; = ashr i8  4, 3   <i>; yields {i8}:result = 0</i>
3472   &lt;result&gt; = ashr i8 -2, 1   <i>; yields {i8}:result = -1</i>
3473   &lt;result&gt; = ashr i32 1, 32  <i>; undefined</i>
3474   &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>
3475 </pre>
3476
3477 </div>
3478
3479 <!-- _______________________________________________________________________ -->
3480 <div class="doc_subsubsection"> <a name="i_and">'<tt>and</tt>'
3481 Instruction</a> </div>
3482
3483 <div class="doc_text">
3484
3485 <h5>Syntax:</h5>
3486 <pre>
3487   &lt;result&gt; = and &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3488 </pre>
3489
3490 <h5>Overview:</h5>
3491 <p>The '<tt>and</tt>' instruction returns the bitwise logical and of its two
3492    operands.</p>
3493
3494 <h5>Arguments:</h5>
3495 <p>The two arguments to the '<tt>and</tt>' instruction must be
3496    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3497    values.  Both arguments must have identical types.</p>
3498
3499 <h5>Semantics:</h5>
3500 <p>The truth table used for the '<tt>and</tt>' instruction is:</p>
3501
3502 <table border="1" cellspacing="0" cellpadding="4">
3503   <tbody>
3504     <tr>
3505       <td>In0</td>
3506       <td>In1</td>
3507       <td>Out</td>
3508     </tr>
3509     <tr>
3510       <td>0</td>
3511       <td>0</td>
3512       <td>0</td>
3513     </tr>
3514     <tr>
3515       <td>0</td>
3516       <td>1</td>
3517       <td>0</td>
3518     </tr>
3519     <tr>
3520       <td>1</td>
3521       <td>0</td>
3522       <td>0</td>
3523     </tr>
3524     <tr>
3525       <td>1</td>
3526       <td>1</td>
3527       <td>1</td>
3528     </tr>
3529   </tbody>
3530 </table>
3531
3532 <h5>Example:</h5>
3533 <pre>
3534   &lt;result&gt; = and i32 4, %var         <i>; yields {i32}:result = 4 &amp; %var</i>
3535   &lt;result&gt; = and i32 15, 40          <i>; yields {i32}:result = 8</i>
3536   &lt;result&gt; = and i32 4, 8            <i>; yields {i32}:result = 0</i>
3537 </pre>
3538 </div>
3539 <!-- _______________________________________________________________________ -->
3540 <div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div>
3541
3542 <div class="doc_text">
3543
3544 <h5>Syntax:</h5>
3545 <pre>
3546   &lt;result&gt; = or &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3547 </pre>
3548
3549 <h5>Overview:</h5>
3550 <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive or of its
3551    two operands.</p>
3552
3553 <h5>Arguments:</h5>
3554 <p>The two arguments to the '<tt>or</tt>' instruction must be
3555    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3556    values.  Both arguments must have identical types.</p>
3557
3558 <h5>Semantics:</h5>
3559 <p>The truth table used for the '<tt>or</tt>' instruction is:</p>
3560
3561 <table border="1" cellspacing="0" cellpadding="4">
3562   <tbody>
3563     <tr>
3564       <td>In0</td>
3565       <td>In1</td>
3566       <td>Out</td>
3567     </tr>
3568     <tr>
3569       <td>0</td>
3570       <td>0</td>
3571       <td>0</td>
3572     </tr>
3573     <tr>
3574       <td>0</td>
3575       <td>1</td>
3576       <td>1</td>
3577     </tr>
3578     <tr>
3579       <td>1</td>
3580       <td>0</td>
3581       <td>1</td>
3582     </tr>
3583     <tr>
3584       <td>1</td>
3585       <td>1</td>
3586       <td>1</td>
3587     </tr>
3588   </tbody>
3589 </table>
3590
3591 <h5>Example:</h5>
3592 <pre>
3593   &lt;result&gt; = or i32 4, %var         <i>; yields {i32}:result = 4 | %var</i>
3594   &lt;result&gt; = or i32 15, 40          <i>; yields {i32}:result = 47</i>
3595   &lt;result&gt; = or i32 4, 8            <i>; yields {i32}:result = 12</i>
3596 </pre>
3597
3598 </div>
3599
3600 <!-- _______________________________________________________________________ -->
3601 <div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>'
3602 Instruction</a> </div>
3603
3604 <div class="doc_text">
3605
3606 <h5>Syntax:</h5>
3607 <pre>
3608   &lt;result&gt; = xor &lt;ty&gt; &lt;op1&gt;, &lt;op2&gt;   <i>; yields {ty}:result</i>
3609 </pre>
3610
3611 <h5>Overview:</h5>
3612 <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of
3613    its two operands.  The <tt>xor</tt> is used to implement the "one's
3614    complement" operation, which is the "~" operator in C.</p>
3615
3616 <h5>Arguments:</h5>
3617 <p>The two arguments to the '<tt>xor</tt>' instruction must be
3618    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
3619    values.  Both arguments must have identical types.</p>
3620
3621 <h5>Semantics:</h5>
3622 <p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
3623
3624 <table border="1" cellspacing="0" cellpadding="4">
3625   <tbody>
3626     <tr>
3627       <td>In0</td>
3628       <td>In1</td>
3629       <td>Out</td>
3630     </tr>
3631     <tr>
3632       <td>0</td>
3633       <td>0</td>
3634       <td>0</td>
3635     </tr>
3636     <tr>
3637       <td>0</td>
3638       <td>1</td>
3639       <td>1</td>
3640     </tr>
3641     <tr>
3642       <td>1</td>
3643       <td>0</td>
3644       <td>1</td>
3645     </tr>
3646     <tr>
3647       <td>1</td>
3648       <td>1</td>
3649       <td>0</td>
3650     </tr>
3651   </tbody>
3652 </table>
3653
3654 <h5>Example:</h5>
3655 <pre>
3656   &lt;result&gt; = xor i32 4, %var         <i>; yields {i32}:result = 4 ^ %var</i>
3657   &lt;result&gt; = xor i32 15, 40          <i>; yields {i32}:result = 39</i>
3658   &lt;result&gt; = xor i32 4, 8            <i>; yields {i32}:result = 12</i>
3659   &lt;result&gt; = xor i32 %V, -1          <i>; yields {i32}:result = ~%V</i>
3660 </pre>
3661
3662 </div>
3663
3664 <!-- ======================================================================= -->
3665 <div class="doc_subsection">
3666   <a name="vectorops">Vector Operations</a>
3667 </div>
3668
3669 <div class="doc_text">
3670
3671 <p>LLVM supports several instructions to represent vector operations in a
3672    target-independent manner.  These instructions cover the element-access and
3673    vector-specific operations needed to process vectors effectively.  While LLVM
3674    does directly support these vector operations, many sophisticated algorithms
3675    will want to use target-specific intrinsics to take full advantage of a
3676    specific target.</p>
3677
3678 </div>
3679
3680 <!-- _______________________________________________________________________ -->
3681 <div class="doc_subsubsection">
3682    <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
3683 </div>
3684
3685 <div class="doc_text">
3686
3687 <h5>Syntax:</h5>
3688 <pre>
3689   &lt;result&gt; = extractelement &lt;n x &lt;ty&gt;&gt; &lt;val&gt;, i32 &lt;idx&gt;    <i>; yields &lt;ty&gt;</i>
3690 </pre>
3691
3692 <h5>Overview:</h5>
3693 <p>The '<tt>extractelement</tt>' instruction extracts a single scalar element
3694    from a vector at a specified index.</p>
3695
3696
3697 <h5>Arguments:</h5>
3698 <p>The first operand of an '<tt>extractelement</tt>' instruction is a value
3699    of <a href="#t_vector">vector</a> type.  The second operand is an index
3700    indicating the position from which to extract the element.  The index may be
3701    a variable.</p>
3702
3703 <h5>Semantics:</h5>
3704 <p>The result is a scalar of the same type as the element type of
3705    <tt>val</tt>.  Its value is the value at position <tt>idx</tt> of
3706    <tt>val</tt>.  If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
3707    results are undefined.</p>
3708
3709 <h5>Example:</h5>
3710 <pre>
3711   &lt;result&gt; = extractelement &lt;4 x i32&gt; %vec, i32 0    <i>; yields i32</i>
3712 </pre>
3713
3714 </div>
3715
3716 <!-- _______________________________________________________________________ -->
3717 <div class="doc_subsubsection">
3718    <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
3719 </div>
3720
3721 <div class="doc_text">
3722
3723 <h5>Syntax:</h5>
3724 <pre>
3725   &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>
3726 </pre>
3727
3728 <h5>Overview:</h5>
3729 <p>The '<tt>insertelement</tt>' instruction inserts a scalar element into a
3730    vector at a specified index.</p>
3731
3732 <h5>Arguments:</h5>
3733 <p>The first operand of an '<tt>insertelement</tt>' instruction is a value
3734    of <a href="#t_vector">vector</a> type.  The second operand is a scalar value
3735    whose type must equal the element type of the first operand.  The third
3736    operand is an index indicating the position at which to insert the value.
3737    The index may be a variable.</p>
3738
3739 <h5>Semantics:</h5>
3740 <p>The result is a vector of the same type as <tt>val</tt>.  Its element values
3741    are those of <tt>val</tt> except at position <tt>idx</tt>, where it gets the
3742    value <tt>elt</tt>.  If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
3743    results are undefined.</p>
3744
3745 <h5>Example:</h5>
3746 <pre>
3747   &lt;result&gt; = insertelement &lt;4 x i32&gt; %vec, i32 1, i32 0    <i>; yields &lt;4 x i32&gt;</i>
3748 </pre>
3749
3750 </div>
3751
3752 <!-- _______________________________________________________________________ -->
3753 <div class="doc_subsubsection">
3754    <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
3755 </div>
3756
3757 <div class="doc_text">
3758
3759 <h5>Syntax:</h5>
3760 <pre>
3761   &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>
3762 </pre>
3763
3764 <h5>Overview:</h5>
3765 <p>The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
3766    from two input vectors, returning a vector with the same element type as the
3767    input and length that is the same as the shuffle mask.</p>
3768
3769 <h5>Arguments:</h5>
3770 <p>The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
3771    with types that match each other. The third argument is a shuffle mask whose
3772    element type is always 'i32'.  The result of the instruction is a vector
3773    whose length is the same as the shuffle mask and whose element type is the
3774    same as the element type of the first two operands.</p>
3775
3776 <p>The shuffle mask operand is required to be a constant vector with either
3777    constant integer or undef values.</p>
3778
3779 <h5>Semantics:</h5>
3780 <p>The elements of the two input vectors are numbered from left to right across
3781    both of the vectors.  The shuffle mask operand specifies, for each element of
3782    the result vector, which element of the two input vectors the result element
3783    gets.  The element selector may be undef (meaning "don't care") and the
3784    second operand may be undef if performing a shuffle from only one vector.</p>
3785
3786 <h5>Example:</h5>
3787 <pre>
3788   &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2,
3789                           &lt;4 x i32&gt; &lt;i32 0, i32 4, i32 1, i32 5&gt;  <i>; yields &lt;4 x i32&gt;</i>
3790   &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; undef,
3791                           &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.
3792   &lt;result&gt; = shufflevector &lt;8 x i32&gt; %v1, &lt;8 x i32&gt; undef,
3793                           &lt;4 x i32&gt; &lt;i32 0, i32 1, i32 2, i32 3&gt;  <i>; yields &lt;4 x i32&gt;</i>
3794   &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2,
3795                           &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>
3796 </pre>
3797
3798 </div>
3799
3800 <!-- ======================================================================= -->
3801 <div class="doc_subsection">
3802   <a name="aggregateops">Aggregate Operations</a>
3803 </div>
3804
3805 <div class="doc_text">
3806
3807 <p>LLVM supports several instructions for working with aggregate values.</p>
3808
3809 </div>
3810
3811 <!-- _______________________________________________________________________ -->
3812 <div class="doc_subsubsection">
3813    <a name="i_extractvalue">'<tt>extractvalue</tt>' Instruction</a>
3814 </div>
3815
3816 <div class="doc_text">
3817
3818 <h5>Syntax:</h5>
3819 <pre>
3820   &lt;result&gt; = extractvalue &lt;aggregate type&gt; &lt;val&gt;, &lt;idx&gt;{, &lt;idx&gt;}*
3821 </pre>
3822
3823 <h5>Overview:</h5>
3824 <p>The '<tt>extractvalue</tt>' instruction extracts the value of a struct field
3825    or array element from an aggregate value.</p>
3826
3827 <h5>Arguments:</h5>
3828 <p>The first operand of an '<tt>extractvalue</tt>' instruction is a value
3829    of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> type.  The
3830    operands are constant indices to specify which value to extract in a similar
3831    manner as indices in a
3832    '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
3833
3834 <h5>Semantics:</h5>
3835 <p>The result is the value at the position in the aggregate specified by the
3836    index operands.</p>
3837
3838 <h5>Example:</h5>
3839 <pre>
3840   &lt;result&gt; = extractvalue {i32, float} %agg, 0    <i>; yields i32</i>
3841 </pre>
3842
3843 </div>
3844
3845 <!-- _______________________________________________________________________ -->
3846 <div class="doc_subsubsection">
3847    <a name="i_insertvalue">'<tt>insertvalue</tt>' Instruction</a>
3848 </div>
3849
3850 <div class="doc_text">
3851
3852 <h5>Syntax:</h5>
3853 <pre>
3854   &lt;result&gt; = insertvalue &lt;aggregate type&gt; &lt;val&gt;, &lt;ty&gt; &lt;val&gt;, &lt;idx&gt;    <i>; yields &lt;n x &lt;ty&gt;&gt;</i>
3855 </pre>
3856
3857 <h5>Overview:</h5>
3858 <p>The '<tt>insertvalue</tt>' instruction inserts a value into a struct field or
3859    array element in an aggregate.</p>
3860
3861
3862 <h5>Arguments:</h5>
3863 <p>The first operand of an '<tt>insertvalue</tt>' instruction is a value
3864    of <a href="#t_struct">struct</a> or <a href="#t_array">array</a> type.  The
3865    second operand is a first-class value to insert.  The following operands are
3866    constant indices indicating the position at which to insert the value in a
3867    similar manner as indices in a
3868    '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.  The
3869    value to insert must have the same type as the value identified by the
3870    indices.</p>
3871
3872 <h5>Semantics:</h5>
3873 <p>The result is an aggregate of the same type as <tt>val</tt>.  Its value is
3874    that of <tt>val</tt> except that the value at the position specified by the
3875    indices is that of <tt>elt</tt>.</p>
3876
3877 <h5>Example:</h5>
3878 <pre>
3879   &lt;result&gt; = insertvalue {i32, float} %agg, i32 1, 0    <i>; yields {i32, float}</i>
3880 </pre>
3881
3882 </div>
3883
3884
3885 <!-- ======================================================================= -->
3886 <div class="doc_subsection">
3887   <a name="memoryops">Memory Access and Addressing Operations</a>
3888 </div>
3889
3890 <div class="doc_text">
3891
3892 <p>A key design point of an SSA-based representation is how it represents
3893    memory.  In LLVM, no memory locations are in SSA form, which makes things
3894    very simple.  This section describes how to read, write, and allocate
3895    memory in LLVM.</p>
3896
3897 </div>
3898
3899 <!-- _______________________________________________________________________ -->
3900 <div class="doc_subsubsection">
3901   <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
3902 </div>
3903
3904 <div class="doc_text">
3905
3906 <h5>Syntax:</h5>
3907 <pre>
3908   &lt;result&gt; = alloca &lt;type&gt;[, i32 &lt;NumElements&gt;][, align &lt;alignment&gt;]     <i>; yields {type*}:result</i>
3909 </pre>
3910
3911 <h5>Overview:</h5>
3912 <p>The '<tt>alloca</tt>' instruction allocates memory on the stack frame of the
3913    currently executing function, to be automatically released when this function
3914    returns to its caller. The object is always allocated in the generic address
3915    space (address space zero).</p>
3916
3917 <h5>Arguments:</h5>
3918 <p>The '<tt>alloca</tt>' instruction
3919    allocates <tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory on the
3920    runtime stack, returning a pointer of the appropriate type to the program.
3921    If "NumElements" is specified, it is the number of elements allocated,
3922    otherwise "NumElements" is defaulted to be one.  If a constant alignment is
3923    specified, the value result of the allocation is guaranteed to be aligned to
3924    at least that boundary.  If not specified, or if zero, the target can choose
3925    to align the allocation on any convenient boundary compatible with the
3926    type.</p>
3927
3928 <p>'<tt>type</tt>' may be any sized type.</p>
3929
3930 <h5>Semantics:</h5>
3931 <p>Memory is allocated; a pointer is returned.  The operation is undefined if
3932    there is insufficient stack space for the allocation.  '<tt>alloca</tt>'d
3933    memory is automatically released when the function returns.  The
3934    '<tt>alloca</tt>' instruction is commonly used to represent automatic
3935    variables that must have an address available.  When the function returns
3936    (either with the <tt><a href="#i_ret">ret</a></tt>
3937    or <tt><a href="#i_unwind">unwind</a></tt> instructions), the memory is
3938    reclaimed.  Allocating zero bytes is legal, but the result is undefined.</p>
3939
3940 <h5>Example:</h5>
3941 <pre>
3942   %ptr = alloca i32                             <i>; yields {i32*}:ptr</i>
3943   %ptr = alloca i32, i32 4                      <i>; yields {i32*}:ptr</i>
3944   %ptr = alloca i32, i32 4, align 1024          <i>; yields {i32*}:ptr</i>
3945   %ptr = alloca i32, align 1024                 <i>; yields {i32*}:ptr</i>
3946 </pre>
3947
3948 </div>
3949
3950 <!-- _______________________________________________________________________ -->
3951 <div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
3952 Instruction</a> </div>
3953
3954 <div class="doc_text">
3955
3956 <h5>Syntax:</h5>
3957 <pre>
3958   &lt;result&gt; = load &lt;ty&gt;* &lt;pointer&gt;[, align &lt;alignment&gt;]
3959   &lt;result&gt; = volatile load &lt;ty&gt;* &lt;pointer&gt;[, align &lt;alignment&gt;]
3960 </pre>
3961
3962 <h5>Overview:</h5>
3963 <p>The '<tt>load</tt>' instruction is used to read from memory.</p>
3964
3965 <h5>Arguments:</h5>
3966 <p>The argument to the '<tt>load</tt>' instruction specifies the memory address
3967    from which to load.  The pointer must point to
3968    a <a href="#t_firstclass">first class</a> type.  If the <tt>load</tt> is
3969    marked as <tt>volatile</tt>, then the optimizer is not allowed to modify the
3970    number or order of execution of this <tt>load</tt> with other
3971    volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
3972    instructions. </p>
3973
3974 <p>The optional constant "align" argument specifies the alignment of the
3975    operation (that is, the alignment of the memory address). A value of 0 or an
3976    omitted "align" argument means that the operation has the preferential
3977    alignment for the target. It is the responsibility of the code emitter to
3978    ensure that the alignment information is correct. Overestimating the
3979    alignment results in an undefined behavior. Underestimating the alignment may
3980    produce less efficient code. An alignment of 1 is always safe.</p>
3981
3982 <h5>Semantics:</h5>
3983 <p>The location of memory pointed to is loaded.  If the value being loaded is of
3984    scalar type then the number of bytes read does not exceed the minimum number
3985    of bytes needed to hold all bits of the type.  For example, loading an
3986    <tt>i24</tt> reads at most three bytes.  When loading a value of a type like
3987    <tt>i20</tt> with a size that is not an integral number of bytes, the result
3988    is undefined if the value was not originally written using a store of the
3989    same type.</p>
3990
3991 <h5>Examples:</h5>
3992 <pre>
3993   %ptr = <a href="#i_alloca">alloca</a> i32                               <i>; yields {i32*}:ptr</i>
3994   <a href="#i_store">store</a> i32 3, i32* %ptr                          <i>; yields {void}</i>
3995   %val = load i32* %ptr                           <i>; yields {i32}:val = i32 3</i>
3996 </pre>
3997
3998 </div>
3999
4000 <!-- _______________________________________________________________________ -->
4001 <div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
4002 Instruction</a> </div>
4003
4004 <div class="doc_text">
4005
4006 <h5>Syntax:</h5>
4007 <pre>
4008   store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;[, align &lt;alignment&gt;]                   <i>; yields {void}</i>
4009   volatile store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;[, align &lt;alignment&gt;]          <i>; yields {void}</i>
4010 </pre>
4011
4012 <h5>Overview:</h5>
4013 <p>The '<tt>store</tt>' instruction is used to write to memory.</p>
4014
4015 <h5>Arguments:</h5>
4016 <p>There are two arguments to the '<tt>store</tt>' instruction: a value to store
4017    and an address at which to store it.  The type of the
4018    '<tt>&lt;pointer&gt;</tt>' operand must be a pointer to
4019    the <a href="#t_firstclass">first class</a> type of the
4020    '<tt>&lt;value&gt;</tt>' operand. If the <tt>store</tt> is marked
4021    as <tt>volatile</tt>, then the optimizer is not allowed to modify the number
4022    or order of execution of this <tt>store</tt> with other
4023    volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
4024    instructions.</p>
4025
4026 <p>The optional constant "align" argument specifies the alignment of the
4027    operation (that is, the alignment of the memory address). A value of 0 or an
4028    omitted "align" argument means that the operation has the preferential
4029    alignment for the target. It is the responsibility of the code emitter to
4030    ensure that the alignment information is correct. Overestimating the
4031    alignment results in an undefined behavior. Underestimating the alignment may
4032    produce less efficient code. An alignment of 1 is always safe.</p>
4033
4034 <h5>Semantics:</h5>
4035 <p>The contents of memory are updated to contain '<tt>&lt;value&gt;</tt>' at the
4036    location specified by the '<tt>&lt;pointer&gt;</tt>' operand.  If
4037    '<tt>&lt;value&gt;</tt>' is of scalar type then the number of bytes written
4038    does not exceed the minimum number of bytes needed to hold all bits of the
4039    type.  For example, storing an <tt>i24</tt> writes at most three bytes.  When
4040    writing a value of a type like <tt>i20</tt> with a size that is not an
4041    integral number of bytes, it is unspecified what happens to the extra bits
4042    that do not belong to the type, but they will typically be overwritten.</p>
4043
4044 <h5>Example:</h5>
4045 <pre>
4046   %ptr = <a href="#i_alloca">alloca</a> i32                               <i>; yields {i32*}:ptr</i>
4047   store i32 3, i32* %ptr                          <i>; yields {void}</i>
4048   %val = <a href="#i_load">load</a> i32* %ptr                           <i>; yields {i32}:val = i32 3</i>
4049 </pre>
4050
4051 </div>
4052
4053 <!-- _______________________________________________________________________ -->
4054 <div class="doc_subsubsection">
4055    <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
4056 </div>
4057
4058 <div class="doc_text">
4059
4060 <h5>Syntax:</h5>
4061 <pre>
4062   &lt;result&gt; = getelementptr &lt;pty&gt;* &lt;ptrval&gt;{, &lt;ty&gt; &lt;idx&gt;}*
4063   &lt;result&gt; = getelementptr inbounds &lt;pty&gt;* &lt;ptrval&gt;{, &lt;ty&gt; &lt;idx&gt;}*
4064 </pre>
4065
4066 <h5>Overview:</h5>
4067 <p>The '<tt>getelementptr</tt>' instruction is used to get the address of a
4068    subelement of an aggregate data structure. It performs address calculation
4069    only and does not access memory.</p>
4070
4071 <h5>Arguments:</h5>
4072 <p>The first argument is always a pointer, and forms the basis of the
4073    calculation. The remaining arguments are indices that indicate which of the
4074    elements of the aggregate object are indexed. The interpretation of each
4075    index is dependent on the type being indexed into. The first index always
4076    indexes the pointer value given as the first argument, the second index
4077    indexes a value of the type pointed to (not necessarily the value directly
4078    pointed to, since the first index can be non-zero), etc. The first type
4079    indexed into must be a pointer value, subsequent types can be arrays, vectors
4080    and structs. Note that subsequent types being indexed into can never be
4081    pointers, since that would require loading the pointer before continuing
4082    calculation.</p>
4083
4084 <p>The type of each index argument depends on the type it is indexing into.
4085    When indexing into a (optionally packed) structure, only <tt>i32</tt> integer
4086    <b>constants</b> are allowed.  When indexing into an array, pointer or
4087    vector, integers of any width are allowed, and they are not required to be
4088    constant.</p>
4089
4090 <p>For example, let's consider a C code fragment and how it gets compiled to
4091    LLVM:</p>
4092
4093 <div class="doc_code">
4094 <pre>
4095 struct RT {
4096   char A;
4097   int B[10][20];
4098   char C;
4099 };
4100 struct ST {
4101   int X;
4102   double Y;
4103   struct RT Z;
4104 };
4105
4106 int *foo(struct ST *s) {
4107   return &amp;s[1].Z.B[5][13];
4108 }
4109 </pre>
4110 </div>
4111
4112 <p>The LLVM code generated by the GCC frontend is:</p>
4113
4114 <div class="doc_code">
4115 <pre>
4116 %RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8  }
4117 %ST = <a href="#namedtypes">type</a> { i32, double, %RT }
4118
4119 define i32* @foo(%ST* %s) {
4120 entry:
4121   %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13
4122   ret i32* %reg
4123 }
4124 </pre>
4125 </div>
4126
4127 <h5>Semantics:</h5>
4128 <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
4129    type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT
4130    }</tt>' type, a structure.  The second index indexes into the third element
4131    of the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]],
4132    i8 }</tt>' type, another structure.  The third index indexes into the second
4133    element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an
4134    array.  The two dimensions of the array are subscripted into, yielding an
4135    '<tt>i32</tt>' type.  The '<tt>getelementptr</tt>' instruction returns a
4136    pointer to this element, thus computing a value of '<tt>i32*</tt>' type.</p>
4137
4138 <p>Note that it is perfectly legal to index partially through a structure,
4139    returning a pointer to an inner element.  Because of this, the LLVM code for
4140    the given testcase is equivalent to:</p>
4141
4142 <pre>
4143   define i32* @foo(%ST* %s) {
4144     %t1 = getelementptr %ST* %s, i32 1                        <i>; yields %ST*:%t1</i>
4145     %t2 = getelementptr %ST* %t1, i32 0, i32 2                <i>; yields %RT*:%t2</i>
4146     %t3 = getelementptr %RT* %t2, i32 0, i32 1                <i>; yields [10 x [20 x i32]]*:%t3</i>
4147     %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5  <i>; yields [20 x i32]*:%t4</i>
4148     %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13        <i>; yields i32*:%t5</i>
4149     ret i32* %t5
4150   }
4151 </pre>
4152
4153 <p>If the <tt>inbounds</tt> keyword is present, the result value of the
4154    <tt>getelementptr</tt> is undefined if the base pointer is not an
4155    <i>in bounds</i> address of an allocated object, or if any of the addresses
4156    that would be formed by successive addition of the offsets implied by the
4157    indices to the base address with infinitely precise arithmetic are not an
4158    <i>in bounds</i> address of that allocated object.
4159    The <i>in bounds</i> addresses for an allocated object are all the addresses
4160    that point into the object, plus the address one byte past the end.</p>
4161
4162 <p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to
4163    the base address with silently-wrapping two's complement arithmetic, and
4164    the result value of the <tt>getelementptr</tt> may be outside the object
4165    pointed to by the base pointer. The result value may not necessarily be
4166    used to access memory though, even if it happens to point into allocated
4167    storage. See the <a href="#pointeraliasing">Pointer Aliasing Rules</a>
4168    section for more information.</p>
4169
4170 <p>The getelementptr instruction is often confusing.  For some more insight into
4171    how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p>
4172
4173 <h5>Example:</h5>
4174 <pre>
4175     <i>; yields [12 x i8]*:aptr</i>
4176     %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1
4177     <i>; yields i8*:vptr</i>
4178     %vptr = getelementptr {i32, &lt;2 x i8&gt;}* %svptr, i64 0, i32 1, i32 1
4179     <i>; yields i8*:eptr</i>
4180     %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1
4181     <i>; yields i32*:iptr</i>
4182     %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0
4183 </pre>
4184
4185 </div>
4186
4187 <!-- ======================================================================= -->
4188 <div class="doc_subsection"> <a name="convertops">Conversion Operations</a>
4189 </div>
4190
4191 <div class="doc_text">
4192
4193 <p>The instructions in this category are the conversion instructions (casting)
4194    which all take a single operand and a type. They perform various bit
4195    conversions on the operand.</p>
4196
4197 </div>
4198
4199 <!-- _______________________________________________________________________ -->
4200 <div class="doc_subsubsection">
4201    <a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
4202 </div>
4203 <div class="doc_text">
4204
4205 <h5>Syntax:</h5>
4206 <pre>
4207   &lt;result&gt; = trunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4208 </pre>
4209
4210 <h5>Overview:</h5>
4211 <p>The '<tt>trunc</tt>' instruction truncates its operand to the
4212    type <tt>ty2</tt>.</p>
4213
4214 <h5>Arguments:</h5>
4215 <p>The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must
4216    be an <a href="#t_integer">integer</a> type, and a type that specifies the
4217    size and type of the result, which must be
4218    an <a href="#t_integer">integer</a> type. The bit size of <tt>value</tt> must
4219    be larger than the bit size of <tt>ty2</tt>. Equal sized types are not
4220    allowed.</p>
4221
4222 <h5>Semantics:</h5>
4223 <p>The '<tt>trunc</tt>' instruction truncates the high order bits
4224    in <tt>value</tt> and converts the remaining bits to <tt>ty2</tt>. Since the
4225    source size must be larger than the destination size, <tt>trunc</tt> cannot
4226    be a <i>no-op cast</i>.  It will always truncate bits.</p>
4227
4228 <h5>Example:</h5>
4229 <pre>
4230   %X = trunc i32 257 to i8              <i>; yields i8:1</i>
4231   %Y = trunc i32 123 to i1              <i>; yields i1:true</i>
4232   %Z = trunc i32 122 to i1              <i>; yields i1:false</i>
4233 </pre>
4234
4235 </div>
4236
4237 <!-- _______________________________________________________________________ -->
4238 <div class="doc_subsubsection">
4239    <a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
4240 </div>
4241 <div class="doc_text">
4242
4243 <h5>Syntax:</h5>
4244 <pre>
4245   &lt;result&gt; = zext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4246 </pre>
4247
4248 <h5>Overview:</h5>
4249 <p>The '<tt>zext</tt>' instruction zero extends its operand to type
4250    <tt>ty2</tt>.</p>
4251
4252
4253 <h5>Arguments:</h5>
4254 <p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of
4255    <a href="#t_integer">integer</a> type, and a type to cast it to, which must
4256    also be of <a href="#t_integer">integer</a> type. The bit size of the
4257    <tt>value</tt> must be smaller than the bit size of the destination type,
4258    <tt>ty2</tt>.</p>
4259
4260 <h5>Semantics:</h5>
4261 <p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero
4262    bits until it reaches the size of the destination type, <tt>ty2</tt>.</p>
4263
4264 <p>When zero extending from i1, the result will always be either 0 or 1.</p>
4265
4266 <h5>Example:</h5>
4267 <pre>
4268   %X = zext i32 257 to i64              <i>; yields i64:257</i>
4269   %Y = zext i1 true to i32              <i>; yields i32:1</i>
4270 </pre>
4271
4272 </div>
4273
4274 <!-- _______________________________________________________________________ -->
4275 <div class="doc_subsubsection">
4276    <a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
4277 </div>
4278 <div class="doc_text">
4279
4280 <h5>Syntax:</h5>
4281 <pre>
4282   &lt;result&gt; = sext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4283 </pre>
4284
4285 <h5>Overview:</h5>
4286 <p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
4287
4288 <h5>Arguments:</h5>
4289 <p>The '<tt>sext</tt>' instruction takes a value to cast, which must be of
4290    <a href="#t_integer">integer</a> type, and a type to cast it to, which must
4291    also be of <a href="#t_integer">integer</a> type.  The bit size of the
4292    <tt>value</tt> must be smaller than the bit size of the destination type,
4293    <tt>ty2</tt>.</p>
4294
4295 <h5>Semantics:</h5>
4296 <p>The '<tt>sext</tt>' instruction performs a sign extension by copying the sign
4297    bit (highest order bit) of the <tt>value</tt> until it reaches the bit size
4298    of the type <tt>ty2</tt>.</p>
4299
4300 <p>When sign extending from i1, the extension always results in -1 or 0.</p>
4301
4302 <h5>Example:</h5>
4303 <pre>
4304   %X = sext i8  -1 to i16              <i>; yields i16   :65535</i>
4305   %Y = sext i1 true to i32             <i>; yields i32:-1</i>
4306 </pre>
4307
4308 </div>
4309
4310 <!-- _______________________________________________________________________ -->
4311 <div class="doc_subsubsection">
4312    <a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
4313 </div>
4314
4315 <div class="doc_text">
4316
4317 <h5>Syntax:</h5>
4318 <pre>
4319   &lt;result&gt; = fptrunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4320 </pre>
4321
4322 <h5>Overview:</h5>
4323 <p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
4324    <tt>ty2</tt>.</p>
4325
4326 <h5>Arguments:</h5>
4327 <p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
4328    point</a> value to cast and a <a href="#t_floating">floating point</a> type
4329    to cast it to. The size of <tt>value</tt> must be larger than the size of
4330    <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
4331    <i>no-op cast</i>.</p>
4332
4333 <h5>Semantics:</h5>
4334 <p>The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger
4335    <a href="#t_floating">floating point</a> type to a smaller
4336    <a href="#t_floating">floating point</a> type.  If the value cannot fit
4337    within the destination type, <tt>ty2</tt>, then the results are
4338    undefined.</p>
4339
4340 <h5>Example:</h5>
4341 <pre>
4342   %X = fptrunc double 123.0 to float         <i>; yields float:123.0</i>
4343   %Y = fptrunc double 1.0E+300 to float      <i>; yields undefined</i>
4344 </pre>
4345
4346 </div>
4347
4348 <!-- _______________________________________________________________________ -->
4349 <div class="doc_subsubsection">
4350    <a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
4351 </div>
4352 <div class="doc_text">
4353
4354 <h5>Syntax:</h5>
4355 <pre>
4356   &lt;result&gt; = fpext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4357 </pre>
4358
4359 <h5>Overview:</h5>
4360 <p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger
4361    floating point value.</p>
4362
4363 <h5>Arguments:</h5>
4364 <p>The '<tt>fpext</tt>' instruction takes a
4365    <a href="#t_floating">floating point</a> <tt>value</tt> to cast, and
4366    a <a href="#t_floating">floating point</a> type to cast it to. The source
4367    type must be smaller than the destination type.</p>
4368
4369 <h5>Semantics:</h5>
4370 <p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller
4371    <a href="#t_floating">floating point</a> type to a larger
4372    <a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be
4373    used to make a <i>no-op cast</i> because it always changes bits. Use
4374    <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p>
4375
4376 <h5>Example:</h5>
4377 <pre>
4378   %X = fpext float 3.1415 to double        <i>; yields double:3.1415</i>
4379   %Y = fpext float 1.0 to float            <i>; yields float:1.0 (no-op)</i>
4380 </pre>
4381
4382 </div>
4383
4384 <!-- _______________________________________________________________________ -->
4385 <div class="doc_subsubsection">
4386    <a name="i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a>
4387 </div>
4388 <div class="doc_text">
4389
4390 <h5>Syntax:</h5>
4391 <pre>
4392   &lt;result&gt; = fptoui &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4393 </pre>
4394
4395 <h5>Overview:</h5>
4396 <p>The '<tt>fptoui</tt>' converts a floating point <tt>value</tt> to its
4397    unsigned integer equivalent of type <tt>ty2</tt>.</p>
4398
4399 <h5>Arguments:</h5>
4400 <p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a
4401    scalar or vector <a href="#t_floating">floating point</a> value, and a type
4402    to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
4403    type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
4404    vector integer type with the same number of elements as <tt>ty</tt></p>
4405
4406 <h5>Semantics:</h5>
4407 <p>The '<tt>fptoui</tt>' instruction converts its
4408    <a href="#t_floating">floating point</a> operand into the nearest (rounding
4409    towards zero) unsigned integer value. If the value cannot fit
4410    in <tt>ty2</tt>, the results are undefined.</p>
4411
4412 <h5>Example:</h5>
4413 <pre>
4414   %X = fptoui double 123.0 to i32      <i>; yields i32:123</i>
4415   %Y = fptoui float 1.0E+300 to i1     <i>; yields undefined:1</i>
4416   %Z = fptoui float 1.04E+17 to i8     <i>; yields undefined:1</i>
4417 </pre>
4418
4419 </div>
4420
4421 <!-- _______________________________________________________________________ -->
4422 <div class="doc_subsubsection">
4423    <a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a>
4424 </div>
4425 <div class="doc_text">
4426
4427 <h5>Syntax:</h5>
4428 <pre>
4429   &lt;result&gt; = fptosi &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4430 </pre>
4431
4432 <h5>Overview:</h5>
4433 <p>The '<tt>fptosi</tt>' instruction converts
4434    <a href="#t_floating">floating point</a> <tt>value</tt> to
4435    type <tt>ty2</tt>.</p>
4436
4437 <h5>Arguments:</h5>
4438 <p>The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a
4439    scalar or vector <a href="#t_floating">floating point</a> value, and a type
4440    to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
4441    type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
4442    vector integer type with the same number of elements as <tt>ty</tt></p>
4443
4444 <h5>Semantics:</h5>
4445 <p>The '<tt>fptosi</tt>' instruction converts its
4446    <a href="#t_floating">floating point</a> operand into the nearest (rounding
4447    towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
4448    the results are undefined.</p>
4449
4450 <h5>Example:</h5>
4451 <pre>
4452   %X = fptosi double -123.0 to i32      <i>; yields i32:-123</i>
4453   %Y = fptosi float 1.0E-247 to i1      <i>; yields undefined:1</i>
4454   %Z = fptosi float 1.04E+17 to i8      <i>; yields undefined:1</i>
4455 </pre>
4456
4457 </div>
4458
4459 <!-- _______________________________________________________________________ -->
4460 <div class="doc_subsubsection">
4461    <a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a>
4462 </div>
4463 <div class="doc_text">
4464
4465 <h5>Syntax:</h5>
4466 <pre>
4467   &lt;result&gt; = uitofp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4468 </pre>
4469
4470 <h5>Overview:</h5>
4471 <p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned
4472    integer and converts that value to the <tt>ty2</tt> type.</p>
4473
4474 <h5>Arguments:</h5>
4475 <p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be a
4476    scalar or vector <a href="#t_integer">integer</a> value, and a type to cast
4477    it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
4478    type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
4479    floating point type with the same number of elements as <tt>ty</tt></p>
4480
4481 <h5>Semantics:</h5>
4482 <p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned
4483    integer quantity and converts it to the corresponding floating point
4484    value. If the value cannot fit in the floating point value, the results are
4485    undefined.</p>
4486
4487 <h5>Example:</h5>
4488 <pre>
4489   %X = uitofp i32 257 to float         <i>; yields float:257.0</i>
4490   %Y = uitofp i8 -1 to double          <i>; yields double:255.0</i>
4491 </pre>
4492
4493 </div>
4494
4495 <!-- _______________________________________________________________________ -->
4496 <div class="doc_subsubsection">
4497    <a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a>
4498 </div>
4499 <div class="doc_text">
4500
4501 <h5>Syntax:</h5>
4502 <pre>
4503   &lt;result&gt; = sitofp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4504 </pre>
4505
4506 <h5>Overview:</h5>
4507 <p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed integer
4508    and converts that value to the <tt>ty2</tt> type.</p>
4509
4510 <h5>Arguments:</h5>
4511 <p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be a
4512    scalar or vector <a href="#t_integer">integer</a> value, and a type to cast
4513    it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
4514    type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
4515    floating point type with the same number of elements as <tt>ty</tt></p>
4516
4517 <h5>Semantics:</h5>
4518 <p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed integer
4519    quantity and converts it to the corresponding floating point value. If the
4520    value cannot fit in the floating point value, the results are undefined.</p>
4521
4522 <h5>Example:</h5>
4523 <pre>
4524   %X = sitofp i32 257 to float         <i>; yields float:257.0</i>
4525   %Y = sitofp i8 -1 to double          <i>; yields double:-1.0</i>
4526 </pre>
4527
4528 </div>
4529
4530 <!-- _______________________________________________________________________ -->
4531 <div class="doc_subsubsection">
4532    <a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a>
4533 </div>
4534 <div class="doc_text">
4535
4536 <h5>Syntax:</h5>
4537 <pre>
4538   &lt;result&gt; = ptrtoint &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4539 </pre>
4540
4541 <h5>Overview:</h5>
4542 <p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to
4543    the integer type <tt>ty2</tt>.</p>
4544
4545 <h5>Arguments:</h5>
4546 <p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which
4547    must be a <a href="#t_pointer">pointer</a> value, and a type to cast it to
4548    <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.</p>
4549
4550 <h5>Semantics:</h5>
4551 <p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type
4552    <tt>ty2</tt> by interpreting the pointer value as an integer and either
4553    truncating or zero extending that value to the size of the integer type. If
4554    <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If
4555    <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they
4556    are the same size, then nothing is done (<i>no-op cast</i>) other than a type
4557    change.</p>
4558
4559 <h5>Example:</h5>
4560 <pre>
4561   %X = ptrtoint i32* %X to i8           <i>; yields truncation on 32-bit architecture</i>
4562   %Y = ptrtoint i32* %x to i64          <i>; yields zero extension on 32-bit architecture</i>
4563 </pre>
4564
4565 </div>
4566
4567 <!-- _______________________________________________________________________ -->
4568 <div class="doc_subsubsection">
4569    <a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a>
4570 </div>
4571 <div class="doc_text">
4572
4573 <h5>Syntax:</h5>
4574 <pre>
4575   &lt;result&gt; = inttoptr &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4576 </pre>
4577
4578 <h5>Overview:</h5>
4579 <p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to a
4580    pointer type, <tt>ty2</tt>.</p>
4581
4582 <h5>Arguments:</h5>
4583 <p>The '<tt>inttoptr</tt>' instruction takes an <a href="#t_integer">integer</a>
4584    value to cast, and a type to cast it to, which must be a
4585    <a href="#t_pointer">pointer</a> type.</p>
4586
4587 <h5>Semantics:</h5>
4588 <p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type
4589    <tt>ty2</tt> by applying either a zero extension or a truncation depending on
4590    the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the
4591    size of a pointer then a truncation is done. If <tt>value</tt> is smaller
4592    than the size of a pointer then a zero extension is done. If they are the
4593    same size, nothing is done (<i>no-op cast</i>).</p>
4594
4595 <h5>Example:</h5>
4596 <pre>
4597   %X = inttoptr i32 255 to i32*          <i>; yields zero extension on 64-bit architecture</i>
4598   %Y = inttoptr i32 255 to i32*          <i>; yields no-op on 32-bit architecture</i>
4599   %Z = inttoptr i64 0 to i32*            <i>; yields truncation on 32-bit architecture</i>
4600 </pre>
4601
4602 </div>
4603
4604 <!-- _______________________________________________________________________ -->
4605 <div class="doc_subsubsection">
4606    <a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a>
4607 </div>
4608 <div class="doc_text">
4609
4610 <h5>Syntax:</h5>
4611 <pre>
4612   &lt;result&gt; = bitcast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
4613 </pre>
4614
4615 <h5>Overview:</h5>
4616 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
4617    <tt>ty2</tt> without changing any bits.</p>
4618
4619 <h5>Arguments:</h5>
4620 <p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be a
4621    non-aggregate first class value, and a type to cast it to, which must also be
4622    a non-aggregate <a href="#t_firstclass">first class</a> type. The bit sizes
4623    of <tt>value</tt> and the destination type, <tt>ty2</tt>, must be
4624    identical. If the source type is a pointer, the destination type must also be
4625    a pointer.  This instruction supports bitwise conversion of vectors to
4626    integers and to vectors of other types (as long as they have the same
4627    size).</p>
4628
4629 <h5>Semantics:</h5>
4630 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
4631    <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with
4632    this conversion.  The conversion is done as if the <tt>value</tt> had been
4633    stored to memory and read back as type <tt>ty2</tt>. Pointer types may only
4634    be converted to other pointer types with this instruction. To convert
4635    pointers to other types, use the <a href="#i_inttoptr">inttoptr</a> or
4636    <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p>
4637
4638 <h5>Example:</h5>
4639 <pre>
4640   %X = bitcast i8 255 to i8              <i>; yields i8 :-1</i>
4641   %Y = bitcast i32* %x to sint*          <i>; yields sint*:%x</i>
4642   %Z = bitcast &lt;2 x int&gt; %V to i64;      <i>; yields i64: %V</i>
4643 </pre>
4644
4645 </div>
4646
4647 <!-- ======================================================================= -->
4648 <div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
4649
4650 <div class="doc_text">
4651
4652 <p>The instructions in this category are the "miscellaneous" instructions, which
4653    defy better classification.</p>
4654
4655 </div>
4656
4657 <!-- _______________________________________________________________________ -->
4658 <div class="doc_subsubsection"><a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
4659 </div>
4660
4661 <div class="doc_text">
4662
4663 <h5>Syntax:</h5>
4664 <pre>
4665   &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>
4666 </pre>
4667
4668 <h5>Overview:</h5>
4669 <p>The '<tt>icmp</tt>' instruction returns a boolean value or a vector of
4670    boolean values based on comparison of its two integer, integer vector, or
4671    pointer operands.</p>
4672
4673 <h5>Arguments:</h5>
4674 <p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is
4675    the condition code indicating the kind of comparison to perform. It is not a
4676    value, just a keyword. The possible condition code are:</p>
4677
4678 <ol>
4679   <li><tt>eq</tt>: equal</li>
4680   <li><tt>ne</tt>: not equal </li>
4681   <li><tt>ugt</tt>: unsigned greater than</li>
4682   <li><tt>uge</tt>: unsigned greater or equal</li>
4683   <li><tt>ult</tt>: unsigned less than</li>
4684   <li><tt>ule</tt>: unsigned less or equal</li>
4685   <li><tt>sgt</tt>: signed greater than</li>
4686   <li><tt>sge</tt>: signed greater or equal</li>
4687   <li><tt>slt</tt>: signed less than</li>
4688   <li><tt>sle</tt>: signed less or equal</li>
4689 </ol>
4690
4691 <p>The remaining two arguments must be <a href="#t_integer">integer</a> or
4692    <a href="#t_pointer">pointer</a> or integer <a href="#t_vector">vector</a>
4693    typed.  They must also be identical types.</p>
4694
4695 <h5>Semantics:</h5>
4696 <p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to the
4697    condition code given as <tt>cond</tt>. The comparison performed always yields
4698    either an <a href="#t_integer"><tt>i1</tt></a> or vector of <tt>i1</tt>
4699    result, as follows:</p>
4700
4701 <ol>
4702   <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
4703       <tt>false</tt> otherwise. No sign interpretation is necessary or
4704       performed.</li>
4705
4706   <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
4707       <tt>false</tt> otherwise. No sign interpretation is necessary or
4708       performed.</li>
4709
4710   <li><tt>ugt</tt>: interprets the operands as unsigned values and yields
4711       <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li>
4712
4713   <li><tt>uge</tt>: interprets the operands as unsigned values and yields
4714       <tt>true</tt> if <tt>op1</tt> is greater than or equal
4715       to <tt>op2</tt>.</li>
4716
4717   <li><tt>ult</tt>: interprets the operands as unsigned values and yields
4718       <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li>
4719
4720   <li><tt>ule</tt>: interprets the operands as unsigned values and yields
4721       <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
4722
4723   <li><tt>sgt</tt>: interprets the operands as signed values and yields
4724       <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li>
4725
4726   <li><tt>sge</tt>: interprets the operands as signed values and yields
4727       <tt>true</tt> if <tt>op1</tt> is greater than or equal
4728       to <tt>op2</tt>.</li>
4729
4730   <li><tt>slt</tt>: interprets the operands as signed values and yields
4731       <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li>
4732
4733   <li><tt>sle</tt>: interprets the operands as signed values and yields
4734       <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
4735 </ol>
4736
4737 <p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer
4738    values are compared as if they were integers.</p>
4739
4740 <p>If the operands are integer vectors, then they are compared element by
4741    element. The result is an <tt>i1</tt> vector with the same number of elements
4742    as the values being compared.  Otherwise, the result is an <tt>i1</tt>.</p>
4743
4744 <h5>Example:</h5>
4745 <pre>
4746   &lt;result&gt; = icmp eq i32 4, 5          <i>; yields: result=false</i>
4747   &lt;result&gt; = icmp ne float* %X, %X     <i>; yields: result=false</i>
4748   &lt;result&gt; = icmp ult i16  4, 5        <i>; yields: result=true</i>
4749   &lt;result&gt; = icmp sgt i16  4, 5        <i>; yields: result=false</i>
4750   &lt;result&gt; = icmp ule i16 -4, 5        <i>; yields: result=false</i>
4751   &lt;result&gt; = icmp sge i16  4, 5        <i>; yields: result=false</i>
4752 </pre>
4753
4754 <p>Note that the code generator does not yet support vector types with
4755    the <tt>icmp</tt> instruction.</p>
4756
4757 </div>
4758
4759 <!-- _______________________________________________________________________ -->
4760 <div class="doc_subsubsection"><a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
4761 </div>
4762
4763 <div class="doc_text">
4764
4765 <h5>Syntax:</h5>
4766 <pre>
4767   &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>
4768 </pre>
4769
4770 <h5>Overview:</h5>
4771 <p>The '<tt>fcmp</tt>' instruction returns a boolean value or vector of boolean
4772    values based on comparison of its operands.</p>
4773
4774 <p>If the operands are floating point scalars, then the result type is a boolean
4775 (<a href="#t_integer"><tt>i1</tt></a>).</p>
4776
4777 <p>If the operands are floating point vectors, then the result type is a vector
4778    of boolean with the same number of elements as the operands being
4779    compared.</p>
4780
4781 <h5>Arguments:</h5>
4782 <p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is
4783    the condition code indicating the kind of comparison to perform. It is not a
4784    value, just a keyword. The possible condition code are:</p>
4785
4786 <ol>
4787   <li><tt>false</tt>: no comparison, always returns false</li>
4788   <li><tt>oeq</tt>: ordered and equal</li>
4789   <li><tt>ogt</tt>: ordered and greater than </li>
4790   <li><tt>oge</tt>: ordered and greater than or equal</li>
4791   <li><tt>olt</tt>: ordered and less than </li>
4792   <li><tt>ole</tt>: ordered and less than or equal</li>
4793   <li><tt>one</tt>: ordered and not equal</li>
4794   <li><tt>ord</tt>: ordered (no nans)</li>
4795   <li><tt>ueq</tt>: unordered or equal</li>
4796   <li><tt>ugt</tt>: unordered or greater than </li>
4797   <li><tt>uge</tt>: unordered or greater than or equal</li>
4798   <li><tt>ult</tt>: unordered or less than </li>
4799   <li><tt>ule</tt>: unordered or less than or equal</li>
4800   <li><tt>une</tt>: unordered or not equal</li>
4801   <li><tt>uno</tt>: unordered (either nans)</li>
4802   <li><tt>true</tt>: no comparison, always returns true</li>
4803 </ol>
4804
4805 <p><i>Ordered</i> means that neither operand is a QNAN while
4806    <i>unordered</i> means that either operand may be a QNAN.</p>
4807
4808 <p>Each of <tt>val1</tt> and <tt>val2</tt> arguments must be either
4809    a <a href="#t_floating">floating point</a> type or
4810    a <a href="#t_vector">vector</a> of floating point type.  They must have
4811    identical types.</p>
4812
4813 <h5>Semantics:</h5>
4814 <p>The '<tt>fcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt>
4815    according to the condition code given as <tt>cond</tt>.  If the operands are
4816    vectors, then the vectors are compared element by element.  Each comparison
4817    performed always yields an <a href="#t_integer">i1</a> result, as
4818    follows:</p>
4819
4820 <ol>
4821   <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
4822
4823   <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
4824       <tt>op1</tt> is equal to <tt>op2</tt>.</li>
4825
4826   <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
4827       <tt>op1</tt> is greather than <tt>op2</tt>.</li>
4828
4829   <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
4830       <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
4831
4832   <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
4833       <tt>op1</tt> is less than <tt>op2</tt>.</li>
4834
4835   <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
4836       <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
4837
4838   <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
4839       <tt>op1</tt> is not equal to <tt>op2</tt>.</li>
4840
4841   <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
4842
4843   <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
4844       <tt>op1</tt> is equal to <tt>op2</tt>.</li>
4845
4846   <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
4847       <tt>op1</tt> is greater than <tt>op2</tt>.</li>
4848
4849   <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
4850       <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
4851
4852   <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
4853       <tt>op1</tt> is less than <tt>op2</tt>.</li>
4854
4855   <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
4856       <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
4857
4858   <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
4859       <tt>op1</tt> is not equal to <tt>op2</tt>.</li>
4860
4861   <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
4862
4863   <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li>
4864 </ol>
4865
4866 <h5>Example:</h5>
4867 <pre>
4868   &lt;result&gt; = fcmp oeq float 4.0, 5.0    <i>; yields: result=false</i>
4869   &lt;result&gt; = fcmp one float 4.0, 5.0    <i>; yields: result=true</i>
4870   &lt;result&gt; = fcmp olt float 4.0, 5.0    <i>; yields: result=true</i>
4871   &lt;result&gt; = fcmp ueq double 1.0, 2.0   <i>; yields: result=false</i>
4872 </pre>
4873
4874 <p>Note that the code generator does not yet support vector types with
4875    the <tt>fcmp</tt> instruction.</p>
4876
4877 </div>
4878
4879 <!-- _______________________________________________________________________ -->
4880 <div class="doc_subsubsection">
4881   <a name="i_phi">'<tt>phi</tt>' Instruction</a>
4882 </div>
4883
4884 <div class="doc_text">
4885
4886 <h5>Syntax:</h5>
4887 <pre>
4888   &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...
4889 </pre>
4890
4891 <h5>Overview:</h5>
4892 <p>The '<tt>phi</tt>' instruction is used to implement the &#966; node in the
4893    SSA graph representing the function.</p>
4894
4895 <h5>Arguments:</h5>
4896 <p>The type of the incoming values is specified with the first type field. After
4897    this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with
4898    one pair for each predecessor basic block of the current block.  Only values
4899    of <a href="#t_firstclass">first class</a> type may be used as the value
4900    arguments to the PHI node.  Only labels may be used as the label
4901    arguments.</p>
4902
4903 <p>There must be no non-phi instructions between the start of a basic block and
4904    the PHI instructions: i.e. PHI instructions must be first in a basic
4905    block.</p>
4906
4907 <p>For the purposes of the SSA form, the use of each incoming value is deemed to
4908    occur on the edge from the corresponding predecessor block to the current
4909    block (but after any definition of an '<tt>invoke</tt>' instruction's return
4910    value on the same edge).</p>
4911
4912 <h5>Semantics:</h5>
4913 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value
4914    specified by the pair corresponding to the predecessor basic block that
4915    executed just prior to the current block.</p>
4916
4917 <h5>Example:</h5>
4918 <pre>
4919 Loop:       ; Infinite loop that counts from 0 on up...
4920   %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
4921   %nextindvar = add i32 %indvar, 1
4922   br label %Loop
4923 </pre>
4924
4925 </div>
4926
4927 <!-- _______________________________________________________________________ -->
4928 <div class="doc_subsubsection">
4929    <a name="i_select">'<tt>select</tt>' Instruction</a>
4930 </div>
4931
4932 <div class="doc_text">
4933
4934 <h5>Syntax:</h5>
4935 <pre>
4936   &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>
4937
4938   <i>selty</i> is either i1 or {&lt;N x i1&gt;}
4939 </pre>
4940
4941 <h5>Overview:</h5>
4942 <p>The '<tt>select</tt>' instruction is used to choose one value based on a
4943    condition, without branching.</p>
4944
4945
4946 <h5>Arguments:</h5>
4947 <p>The '<tt>select</tt>' instruction requires an 'i1' value or a vector of 'i1'
4948    values indicating the condition, and two values of the
4949    same <a href="#t_firstclass">first class</a> type.  If the val1/val2 are
4950    vectors and the condition is a scalar, then entire vectors are selected, not
4951    individual elements.</p>
4952
4953 <h5>Semantics:</h5>
4954 <p>If the condition is an i1 and it evaluates to 1, the instruction returns the
4955    first value argument; otherwise, it returns the second value argument.</p>
4956
4957 <p>If the condition is a vector of i1, then the value arguments must be vectors
4958    of the same size, and the selection is done element by element.</p>
4959
4960 <h5>Example:</h5>
4961 <pre>
4962   %X = select i1 true, i8 17, i8 42          <i>; yields i8:17</i>
4963 </pre>
4964
4965 <p>Note that the code generator does not yet support conditions
4966    with vector type.</p>
4967
4968 </div>
4969
4970 <!-- _______________________________________________________________________ -->
4971 <div class="doc_subsubsection">
4972   <a name="i_call">'<tt>call</tt>' Instruction</a>
4973 </div>
4974
4975 <div class="doc_text">
4976
4977 <h5>Syntax:</h5>
4978 <pre>
4979   &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>]
4980 </pre>
4981
4982 <h5>Overview:</h5>
4983 <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
4984
4985 <h5>Arguments:</h5>
4986 <p>This instruction requires several arguments:</p>
4987
4988 <ol>
4989   <li>The optional "tail" marker indicates whether the callee function accesses
4990       any allocas or varargs in the caller.  If the "tail" marker is present,
4991       the function call is eligible for tail call optimization.  Note that calls
4992       may be marked "tail" even if they do not occur before
4993       a <a href="#i_ret"><tt>ret</tt></a> instruction.</li>
4994
4995   <li>The optional "cconv" marker indicates which <a href="#callingconv">calling
4996       convention</a> the call should use.  If none is specified, the call
4997       defaults to using C calling conventions.</li>
4998
4999   <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
5000       return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
5001       '<tt>inreg</tt>' attributes are valid here.</li>
5002
5003   <li>'<tt>ty</tt>': the type of the call instruction itself which is also the
5004       type of the return value.  Functions that return no value are marked
5005       <tt><a href="#t_void">void</a></tt>.</li>
5006
5007   <li>'<tt>fnty</tt>': shall be the signature of the pointer to function value
5008       being invoked.  The argument types must match the types implied by this
5009       signature.  This type can be omitted if the function is not varargs and if
5010       the function type does not return a pointer to a function.</li>
5011
5012   <li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to
5013       be invoked. In most cases, this is a direct function invocation, but
5014       indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer
5015       to function value.</li>
5016
5017   <li>'<tt>function args</tt>': argument list whose types match the function
5018       signature argument types. All arguments must be of
5019       <a href="#t_firstclass">first class</a> type. If the function signature
5020       indicates the function accepts a variable number of arguments, the extra
5021       arguments can be specified.</li>
5022
5023   <li>The optional <a href="#fnattrs">function attributes</a> list. Only
5024       '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
5025       '<tt>readnone</tt>' attributes are valid here.</li>
5026 </ol>
5027
5028 <h5>Semantics:</h5>
5029 <p>The '<tt>call</tt>' instruction is used to cause control flow to transfer to
5030    a specified function, with its incoming arguments bound to the specified
5031    values. Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called
5032    function, control flow continues with the instruction after the function
5033    call, and the return value of the function is bound to the result
5034    argument.</p>
5035
5036 <h5>Example:</h5>
5037 <pre>
5038   %retval = call i32 @test(i32 %argc)
5039   call i32 (i8 *, ...)* @printf(i8 * %msg, i32 12, i8 42)      <i>; yields i32</i>
5040   %X = tail call i32 @foo()                                    <i>; yields i32</i>
5041   %Y = tail call <a href="#callingconv">fastcc</a> i32 @foo()  <i>; yields i32</i>
5042   call void %foo(i8 97 signext)
5043
5044   %struct.A = type { i32, i8 }
5045   %r = call %struct.A @foo()                        <i>; yields { 32, i8 }</i>
5046   %gr = extractvalue %struct.A %r, 0                <i>; yields i32</i>
5047   %gr1 = extractvalue %struct.A %r, 1               <i>; yields i8</i>
5048   %Z = call void @foo() noreturn                    <i>; indicates that %foo never returns normally</i>
5049   %ZZ = call zeroext i32 @bar()                     <i>; Return value is %zero extended</i>
5050 </pre>
5051
5052 <p>llvm treats calls to some functions with names and arguments that match the
5053 standard C99 library as being the C99 library functions, and may perform
5054 optimizations or generate code for them under that assumption.  This is
5055 something we'd like to change in the future to provide better support for
5056 freestanding environments and non-C-based langauges.</p>
5057
5058 </div>
5059
5060 <!-- _______________________________________________________________________ -->
5061 <div class="doc_subsubsection">
5062   <a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
5063 </div>
5064
5065 <div class="doc_text">
5066
5067 <h5>Syntax:</h5>
5068 <pre>
5069   &lt;resultval&gt; = va_arg &lt;va_list*&gt; &lt;arglist&gt;, &lt;argty&gt;
5070 </pre>
5071
5072 <h5>Overview:</h5>
5073 <p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through
5074    the "variable argument" area of a function call.  It is used to implement the
5075    <tt>va_arg</tt> macro in C.</p>
5076
5077 <h5>Arguments:</h5>
5078 <p>This instruction takes a <tt>va_list*</tt> value and the type of the
5079    argument. It returns a value of the specified argument type and increments
5080    the <tt>va_list</tt> to point to the next argument.  The actual type
5081    of <tt>va_list</tt> is target specific.</p>
5082
5083 <h5>Semantics:</h5>
5084 <p>The '<tt>va_arg</tt>' instruction loads an argument of the specified type
5085    from the specified <tt>va_list</tt> and causes the <tt>va_list</tt> to point
5086    to the next argument.  For more information, see the variable argument
5087    handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
5088
5089 <p>It is legal for this instruction to be called in a function which does not
5090    take a variable number of arguments, for example, the <tt>vfprintf</tt>
5091    function.</p>
5092
5093 <p><tt>va_arg</tt> is an LLVM instruction instead of
5094    an <a href="#intrinsics">intrinsic function</a> because it takes a type as an
5095    argument.</p>
5096
5097 <h5>Example:</h5>
5098 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
5099
5100 <p>Note that the code generator does not yet fully support va_arg on many
5101    targets. Also, it does not currently support va_arg with aggregate types on
5102    any target.</p>
5103
5104 </div>
5105
5106 <!-- *********************************************************************** -->
5107 <div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
5108 <!-- *********************************************************************** -->
5109
5110 <div class="doc_text">
5111
5112 <p>LLVM supports the notion of an "intrinsic function".  These functions have
5113    well known names and semantics and are required to follow certain
5114    restrictions.  Overall, these intrinsics represent an extension mechanism for
5115    the LLVM language that does not require changing all of the transformations
5116    in LLVM when adding to the language (or the bitcode reader/writer, the
5117    parser, etc...).</p>
5118
5119 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
5120    prefix is reserved in LLVM for intrinsic names; thus, function names may not
5121    begin with this prefix.  Intrinsic functions must always be external
5122    functions: you cannot define the body of intrinsic functions.  Intrinsic
5123    functions may only be used in call or invoke instructions: it is illegal to
5124    take the address of an intrinsic function.  Additionally, because intrinsic
5125    functions are part of the LLVM language, it is required if any are added that
5126    they be documented here.</p>
5127
5128 <p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents a
5129    family of functions that perform the same operation but on different data
5130    types. Because LLVM can represent over 8 million different integer types,
5131    overloading is used commonly to allow an intrinsic function to operate on any
5132    integer type. One or more of the argument types or the result type can be
5133    overloaded to accept any integer type. Argument types may also be defined as
5134    exactly matching a previous argument's type or the result type. This allows
5135    an intrinsic function which accepts multiple arguments, but needs all of them
5136    to be of the same type, to only be overloaded with respect to a single
5137    argument or the result.</p>
5138
5139 <p>Overloaded intrinsics will have the names of its overloaded argument types
5140    encoded into its function name, each preceded by a period. Only those types
5141    which are overloaded result in a name suffix. Arguments whose type is matched
5142    against another type do not. For example, the <tt>llvm.ctpop</tt> function
5143    can take an integer of any width and returns an integer of exactly the same
5144    integer width. This leads to a family of functions such as
5145    <tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29
5146    %val)</tt>.  Only one type, the return type, is overloaded, and only one type
5147    suffix is required. Because the argument's type is matched against the return
5148    type, it does not require its own name suffix.</p>
5149
5150 <p>To learn how to add an intrinsic function, please see the
5151    <a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p>
5152
5153 </div>
5154
5155 <!-- ======================================================================= -->
5156 <div class="doc_subsection">
5157   <a name="int_varargs">Variable Argument Handling Intrinsics</a>
5158 </div>
5159
5160 <div class="doc_text">
5161
5162 <p>Variable argument support is defined in LLVM with
5163    the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
5164    intrinsic functions.  These functions are related to the similarly named
5165    macros defined in the <tt>&lt;stdarg.h&gt;</tt> header file.</p>
5166
5167 <p>All of these functions operate on arguments that use a target-specific value
5168    type "<tt>va_list</tt>".  The LLVM assembly language reference manual does
5169    not define what this type is, so all transformations should be prepared to
5170    handle these functions regardless of the type used.</p>
5171
5172 <p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a>
5173    instruction and the variable argument handling intrinsic functions are
5174    used.</p>
5175
5176 <div class="doc_code">
5177 <pre>
5178 define i32 @test(i32 %X, ...) {
5179   ; Initialize variable argument processing
5180   %ap = alloca i8*
5181   %ap2 = bitcast i8** %ap to i8*
5182   call void @llvm.va_start(i8* %ap2)
5183
5184   ; Read a single integer argument
5185   %tmp = va_arg i8** %ap, i32
5186
5187   ; Demonstrate usage of llvm.va_copy and llvm.va_end
5188   %aq = alloca i8*
5189   %aq2 = bitcast i8** %aq to i8*
5190   call void @llvm.va_copy(i8* %aq2, i8* %ap2)
5191   call void @llvm.va_end(i8* %aq2)
5192
5193   ; Stop processing of arguments.
5194   call void @llvm.va_end(i8* %ap2)
5195   ret i32 %tmp
5196 }
5197
5198 declare void @llvm.va_start(i8*)
5199 declare void @llvm.va_copy(i8*, i8*)
5200 declare void @llvm.va_end(i8*)
5201 </pre>
5202 </div>
5203
5204 </div>
5205
5206 <!-- _______________________________________________________________________ -->
5207 <div class="doc_subsubsection">
5208   <a name="int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
5209 </div>
5210
5211
5212 <div class="doc_text">
5213
5214 <h5>Syntax:</h5>
5215 <pre>
5216   declare void %llvm.va_start(i8* &lt;arglist&gt;)
5217 </pre>
5218
5219 <h5>Overview:</h5>
5220 <p>The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*&lt;arglist&gt;</tt>
5221    for subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt>.</p>
5222
5223 <h5>Arguments:</h5>
5224 <p>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
5225
5226 <h5>Semantics:</h5>
5227 <p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
5228    macro available in C.  In a target-dependent way, it initializes
5229    the <tt>va_list</tt> element to which the argument points, so that the next
5230    call to <tt>va_arg</tt> will produce the first variable argument passed to
5231    the function.  Unlike the C <tt>va_start</tt> macro, this intrinsic does not
5232    need to know the last argument of the function as the compiler can figure
5233    that out.</p>
5234
5235 </div>
5236
5237 <!-- _______________________________________________________________________ -->
5238 <div class="doc_subsubsection">
5239  <a name="int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
5240 </div>
5241
5242 <div class="doc_text">
5243
5244 <h5>Syntax:</h5>
5245 <pre>
5246   declare void @llvm.va_end(i8* &lt;arglist&gt;)
5247 </pre>
5248
5249 <h5>Overview:</h5>
5250 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*&lt;arglist&gt;</tt>,
5251    which has been initialized previously
5252    with <tt><a href="#int_va_start">llvm.va_start</a></tt>
5253    or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
5254
5255 <h5>Arguments:</h5>
5256 <p>The argument is a pointer to a <tt>va_list</tt> to destroy.</p>
5257
5258 <h5>Semantics:</h5>
5259 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
5260    macro available in C.  In a target-dependent way, it destroys
5261    the <tt>va_list</tt> element to which the argument points.  Calls
5262    to <a href="#int_va_start"><tt>llvm.va_start</tt></a>
5263    and <a href="#int_va_copy"> <tt>llvm.va_copy</tt></a> must be matched exactly
5264    with calls to <tt>llvm.va_end</tt>.</p>
5265
5266 </div>
5267
5268 <!-- _______________________________________________________________________ -->
5269 <div class="doc_subsubsection">
5270   <a name="int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
5271 </div>
5272
5273 <div class="doc_text">
5274
5275 <h5>Syntax:</h5>
5276 <pre>
5277   declare void @llvm.va_copy(i8* &lt;destarglist&gt;, i8* &lt;srcarglist&gt;)
5278 </pre>
5279
5280 <h5>Overview:</h5>
5281 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position
5282    from the source argument list to the destination argument list.</p>
5283
5284 <h5>Arguments:</h5>
5285 <p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
5286    The second argument is a pointer to a <tt>va_list</tt> element to copy
5287    from.</p>
5288
5289 <h5>Semantics:</h5>
5290 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
5291    macro available in C.  In a target-dependent way, it copies the
5292    source <tt>va_list</tt> element into the destination <tt>va_list</tt>
5293    element.  This intrinsic is necessary because
5294    the <tt><a href="#int_va_start"> llvm.va_start</a></tt> intrinsic may be
5295    arbitrarily complex and require, for example, memory allocation.</p>
5296
5297 </div>
5298
5299 <!-- ======================================================================= -->
5300 <div class="doc_subsection">
5301   <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
5302 </div>
5303
5304 <div class="doc_text">
5305
5306 <p>LLVM support for <a href="GarbageCollection.html">Accurate Garbage
5307 Collection</a> (GC) requires the implementation and generation of these
5308 intrinsics. These intrinsics allow identification of <a href="#int_gcroot">GC
5309 roots on the stack</a>, as well as garbage collector implementations that
5310 require <a href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a>
5311 barriers.  Front-ends for type-safe garbage collected languages should generate
5312 these intrinsics to make use of the LLVM garbage collectors.  For more details,
5313 see <a href="GarbageCollection.html">Accurate Garbage Collection with
5314 LLVM</a>.</p>
5315
5316 <p>The garbage collection intrinsics only operate on objects in the generic
5317    address space (address space zero).</p>
5318
5319 </div>
5320
5321 <!-- _______________________________________________________________________ -->
5322 <div class="doc_subsubsection">
5323   <a name="int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
5324 </div>
5325
5326 <div class="doc_text">
5327
5328 <h5>Syntax:</h5>
5329 <pre>
5330   declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
5331 </pre>
5332
5333 <h5>Overview:</h5>
5334 <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
5335    the code generator, and allows some metadata to be associated with it.</p>
5336
5337 <h5>Arguments:</h5>
5338 <p>The first argument specifies the address of a stack object that contains the
5339    root pointer.  The second pointer (which must be either a constant or a
5340    global value address) contains the meta-data to be associated with the
5341    root.</p>
5342
5343 <h5>Semantics:</h5>
5344 <p>At runtime, a call to this intrinsic stores a null pointer into the "ptrloc"
5345    location.  At compile-time, the code generator generates information to allow
5346    the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>'
5347    intrinsic may only be used in a function which <a href="#gc">specifies a GC
5348    algorithm</a>.</p>
5349
5350 </div>
5351
5352 <!-- _______________________________________________________________________ -->
5353 <div class="doc_subsubsection">
5354   <a name="int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
5355 </div>
5356
5357 <div class="doc_text">
5358
5359 <h5>Syntax:</h5>
5360 <pre>
5361   declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
5362 </pre>
5363
5364 <h5>Overview:</h5>
5365 <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
5366    locations, allowing garbage collector implementations that require read
5367    barriers.</p>
5368
5369 <h5>Arguments:</h5>
5370 <p>The second argument is the address to read from, which should be an address
5371    allocated from the garbage collector.  The first object is a pointer to the
5372    start of the referenced object, if needed by the language runtime (otherwise
5373    null).</p>
5374
5375 <h5>Semantics:</h5>
5376 <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
5377    instruction, but may be replaced with substantially more complex code by the
5378    garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic
5379    may only be used in a function which <a href="#gc">specifies a GC
5380    algorithm</a>.</p>
5381
5382 </div>
5383
5384 <!-- _______________________________________________________________________ -->
5385 <div class="doc_subsubsection">
5386   <a name="int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
5387 </div>
5388
5389 <div class="doc_text">
5390
5391 <h5>Syntax:</h5>
5392 <pre>
5393   declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
5394 </pre>
5395
5396 <h5>Overview:</h5>
5397 <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
5398    locations, allowing garbage collector implementations that require write
5399    barriers (such as generational or reference counting collectors).</p>
5400
5401 <h5>Arguments:</h5>
5402 <p>The first argument is the reference to store, the second is the start of the
5403    object to store it to, and the third is the address of the field of Obj to
5404    store to.  If the runtime does not require a pointer to the object, Obj may
5405    be null.</p>
5406
5407 <h5>Semantics:</h5>
5408 <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
5409    instruction, but may be replaced with substantially more complex code by the
5410    garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic
5411    may only be used in a function which <a href="#gc">specifies a GC
5412    algorithm</a>.</p>
5413
5414 </div>
5415
5416 <!-- ======================================================================= -->
5417 <div class="doc_subsection">
5418   <a name="int_codegen">Code Generator Intrinsics</a>
5419 </div>
5420
5421 <div class="doc_text">
5422
5423 <p>These intrinsics are provided by LLVM to expose special features that may
5424    only be implemented with code generator support.</p>
5425
5426 </div>
5427
5428 <!-- _______________________________________________________________________ -->
5429 <div class="doc_subsubsection">
5430   <a name="int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
5431 </div>
5432
5433 <div class="doc_text">
5434
5435 <h5>Syntax:</h5>
5436 <pre>
5437   declare i8  *@llvm.returnaddress(i32 &lt;level&gt;)
5438 </pre>
5439
5440 <h5>Overview:</h5>
5441 <p>The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a
5442    target-specific value indicating the return address of the current function
5443    or one of its callers.</p>
5444
5445 <h5>Arguments:</h5>
5446 <p>The argument to this intrinsic indicates which function to return the address
5447    for.  Zero indicates the calling function, one indicates its caller, etc.
5448    The argument is <b>required</b> to be a constant integer value.</p>
5449
5450 <h5>Semantics:</h5>
5451 <p>The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer
5452    indicating the return address of the specified call frame, or zero if it
5453    cannot be identified.  The value returned by this intrinsic is likely to be
5454    incorrect or 0 for arguments other than zero, so it should only be used for
5455    debugging purposes.</p>
5456
5457 <p>Note that calling this intrinsic does not prevent function inlining or other
5458    aggressive transformations, so the value returned may not be that of the
5459    obvious source-language caller.</p>
5460
5461 </div>
5462
5463 <!-- _______________________________________________________________________ -->
5464 <div class="doc_subsubsection">
5465   <a name="int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
5466 </div>
5467
5468 <div class="doc_text">
5469
5470 <h5>Syntax:</h5>
5471 <pre>
5472   declare i8 *@llvm.frameaddress(i32 &lt;level&gt;)
5473 </pre>
5474
5475 <h5>Overview:</h5>
5476 <p>The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the
5477    target-specific frame pointer value for the specified stack frame.</p>
5478
5479 <h5>Arguments:</h5>
5480 <p>The argument to this intrinsic indicates which function to return the frame
5481    pointer for.  Zero indicates the calling function, one indicates its caller,
5482    etc.  The argument is <b>required</b> to be a constant integer value.</p>
5483
5484 <h5>Semantics:</h5>
5485 <p>The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer
5486    indicating the frame address of the specified call frame, or zero if it
5487    cannot be identified.  The value returned by this intrinsic is likely to be
5488    incorrect or 0 for arguments other than zero, so it should only be used for
5489    debugging purposes.</p>
5490
5491 <p>Note that calling this intrinsic does not prevent function inlining or other
5492    aggressive transformations, so the value returned may not be that of the
5493    obvious source-language caller.</p>
5494
5495 </div>
5496
5497 <!-- _______________________________________________________________________ -->
5498 <div class="doc_subsubsection">
5499   <a name="int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
5500 </div>
5501
5502 <div class="doc_text">
5503
5504 <h5>Syntax:</h5>
5505 <pre>
5506   declare i8 *@llvm.stacksave()
5507 </pre>
5508
5509 <h5>Overview:</h5>
5510 <p>The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state
5511    of the function stack, for use
5512    with <a href="#int_stackrestore"> <tt>llvm.stackrestore</tt></a>.  This is
5513    useful for implementing language features like scoped automatic variable
5514    sized arrays in C99.</p>
5515
5516 <h5>Semantics:</h5>
5517 <p>This intrinsic returns a opaque pointer value that can be passed
5518    to <a href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>.  When
5519    an <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved
5520    from <tt>llvm.stacksave</tt>, it effectively restores the state of the stack
5521    to the state it was in when the <tt>llvm.stacksave</tt> intrinsic executed.
5522    In practice, this pops any <a href="#i_alloca">alloca</a> blocks from the
5523    stack that were allocated after the <tt>llvm.stacksave</tt> was executed.</p>
5524
5525 </div>
5526
5527 <!-- _______________________________________________________________________ -->
5528 <div class="doc_subsubsection">
5529   <a name="int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
5530 </div>
5531
5532 <div class="doc_text">
5533
5534 <h5>Syntax:</h5>
5535 <pre>
5536   declare void @llvm.stackrestore(i8 * %ptr)
5537 </pre>
5538
5539 <h5>Overview:</h5>
5540 <p>The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of
5541    the function stack to the state it was in when the
5542    corresponding <a href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic
5543    executed.  This is useful for implementing language features like scoped
5544    automatic variable sized arrays in C99.</p>
5545
5546 <h5>Semantics:</h5>
5547 <p>See the description
5548    for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>.</p>
5549
5550 </div>
5551
5552 <!-- _______________________________________________________________________ -->
5553 <div class="doc_subsubsection">
5554   <a name="int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
5555 </div>
5556
5557 <div class="doc_text">
5558
5559 <h5>Syntax:</h5>
5560 <pre>
5561   declare void @llvm.prefetch(i8* &lt;address&gt;, i32 &lt;rw&gt;, i32 &lt;locality&gt;)
5562 </pre>
5563
5564 <h5>Overview:</h5>
5565 <p>The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to
5566    insert a prefetch instruction if supported; otherwise, it is a noop.
5567    Prefetches have no effect on the behavior of the program but can change its
5568    performance characteristics.</p>
5569
5570 <h5>Arguments:</h5>
5571 <p><tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the
5572    specifier determining if the fetch should be for a read (0) or write (1),
5573    and <tt>locality</tt> is a temporal locality specifier ranging from (0) - no
5574    locality, to (3) - extremely local keep in cache.  The <tt>rw</tt>
5575    and <tt>locality</tt> arguments must be constant integers.</p>
5576
5577 <h5>Semantics:</h5>
5578 <p>This intrinsic does not modify the behavior of the program.  In particular,
5579    prefetches cannot trap and do not produce a value.  On targets that support
5580    this intrinsic, the prefetch can provide hints to the processor cache for
5581    better performance.</p>
5582
5583 </div>
5584
5585 <!-- _______________________________________________________________________ -->
5586 <div class="doc_subsubsection">
5587   <a name="int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
5588 </div>
5589
5590 <div class="doc_text">
5591
5592 <h5>Syntax:</h5>
5593 <pre>
5594   declare void @llvm.pcmarker(i32 &lt;id&gt;)
5595 </pre>
5596
5597 <h5>Overview:</h5>
5598 <p>The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program
5599    Counter (PC) in a region of code to simulators and other tools.  The method
5600    is target specific, but it is expected that the marker will use exported
5601    symbols to transmit the PC of the marker.  The marker makes no guarantees
5602    that it will remain with any specific instruction after optimizations.  It is
5603    possible that the presence of a marker will inhibit optimizations.  The
5604    intended use is to be inserted after optimizations to allow correlations of
5605    simulation runs.</p>
5606
5607 <h5>Arguments:</h5>
5608 <p><tt>id</tt> is a numerical id identifying the marker.</p>
5609
5610 <h5>Semantics:</h5>
5611 <p>This intrinsic does not modify the behavior of the program.  Backends that do
5612    not support this intrinisic may ignore it.</p>
5613
5614 </div>
5615
5616 <!-- _______________________________________________________________________ -->
5617 <div class="doc_subsubsection">
5618   <a name="int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
5619 </div>
5620
5621 <div class="doc_text">
5622
5623 <h5>Syntax:</h5>
5624 <pre>
5625   declare i64 @llvm.readcyclecounter( )
5626 </pre>
5627
5628 <h5>Overview:</h5>
5629 <p>The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle
5630    counter register (or similar low latency, high accuracy clocks) on those
5631    targets that support it.  On X86, it should map to RDTSC.  On Alpha, it
5632    should map to RPCC.  As the backing counters overflow quickly (on the order
5633    of 9 seconds on alpha), this should only be used for small timings.</p>
5634
5635 <h5>Semantics:</h5>
5636 <p>When directly supported, reading the cycle counter should not modify any
5637    memory.  Implementations are allowed to either return a application specific
5638    value or a system wide value.  On backends without support, this is lowered
5639    to a constant 0.</p>
5640
5641 </div>
5642
5643 <!-- ======================================================================= -->
5644 <div class="doc_subsection">
5645   <a name="int_libc">Standard C Library Intrinsics</a>
5646 </div>
5647
5648 <div class="doc_text">
5649
5650 <p>LLVM provides intrinsics for a few important standard C library functions.
5651    These intrinsics allow source-language front-ends to pass information about
5652    the alignment of the pointer arguments to the code generator, providing
5653    opportunity for more efficient code generation.</p>
5654
5655 </div>
5656
5657 <!-- _______________________________________________________________________ -->
5658 <div class="doc_subsubsection">
5659   <a name="int_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
5660 </div>
5661
5662 <div class="doc_text">
5663
5664 <h5>Syntax:</h5>
5665 <p>This is an overloaded intrinsic. You can use <tt>llvm.memcpy</tt> on any
5666    integer bit width. Not all targets support all bit widths however.</p>
5667
5668 <pre>
5669   declare void @llvm.memcpy.i8(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5670                                i8 &lt;len&gt;, i32 &lt;align&gt;)
5671   declare void @llvm.memcpy.i16(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5672                                 i16 &lt;len&gt;, i32 &lt;align&gt;)
5673   declare void @llvm.memcpy.i32(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5674                                 i32 &lt;len&gt;, i32 &lt;align&gt;)
5675   declare void @llvm.memcpy.i64(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5676                                 i64 &lt;len&gt;, i32 &lt;align&gt;)
5677 </pre>
5678
5679 <h5>Overview:</h5>
5680 <p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
5681    source location to the destination location.</p>
5682
5683 <p>Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
5684    intrinsics do not return a value, and takes an extra alignment argument.</p>
5685
5686 <h5>Arguments:</h5>
5687 <p>The first argument is a pointer to the destination, the second is a pointer
5688    to the source.  The third argument is an integer argument specifying the
5689    number of bytes to copy, and the fourth argument is the alignment of the
5690    source and destination locations.</p>
5691
5692 <p>If the call to this intrinisic has an alignment value that is not 0 or 1,
5693    then the caller guarantees that both the source and destination pointers are
5694    aligned to that boundary.</p>
5695
5696 <h5>Semantics:</h5>
5697 <p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
5698    source location to the destination location, which are not allowed to
5699    overlap.  It copies "len" bytes of memory over.  If the argument is known to
5700    be aligned to some boundary, this can be specified as the fourth argument,
5701    otherwise it should be set to 0 or 1.</p>
5702
5703 </div>
5704
5705 <!-- _______________________________________________________________________ -->
5706 <div class="doc_subsubsection">
5707   <a name="int_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
5708 </div>
5709
5710 <div class="doc_text">
5711
5712 <h5>Syntax:</h5>
5713 <p>This is an overloaded intrinsic. You can use llvm.memmove on any integer bit
5714    width. Not all targets support all bit widths however.</p>
5715
5716 <pre>
5717   declare void @llvm.memmove.i8(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5718                                 i8 &lt;len&gt;, i32 &lt;align&gt;)
5719   declare void @llvm.memmove.i16(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5720                                  i16 &lt;len&gt;, i32 &lt;align&gt;)
5721   declare void @llvm.memmove.i32(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5722                                  i32 &lt;len&gt;, i32 &lt;align&gt;)
5723   declare void @llvm.memmove.i64(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
5724                                  i64 &lt;len&gt;, i32 &lt;align&gt;)
5725 </pre>
5726
5727 <h5>Overview:</h5>
5728 <p>The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the
5729    source location to the destination location. It is similar to the
5730    '<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to
5731    overlap.</p>
5732
5733 <p>Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
5734    intrinsics do not return a value, and takes an extra alignment argument.</p>
5735
5736 <h5>Arguments:</h5>
5737 <p>The first argument is a pointer to the destination, the second is a pointer
5738    to the source.  The third argument is an integer argument specifying the
5739    number of bytes to copy, and the fourth argument is the alignment of the
5740    source and destination locations.</p>
5741
5742 <p>If the call to this intrinisic has an alignment value that is not 0 or 1,
5743    then the caller guarantees that the source and destination pointers are
5744    aligned to that boundary.</p>
5745
5746 <h5>Semantics:</h5>
5747 <p>The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the
5748    source location to the destination location, which may overlap.  It copies
5749    "len" bytes of memory over.  If the argument is known to be aligned to some
5750    boundary, this can be specified as the fourth argument, otherwise it should
5751    be set to 0 or 1.</p>
5752
5753 </div>
5754
5755 <!-- _______________________________________________________________________ -->
5756 <div class="doc_subsubsection">
5757   <a name="int_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
5758 </div>
5759
5760 <div class="doc_text">
5761
5762 <h5>Syntax:</h5>
5763 <p>This is an overloaded intrinsic. You can use llvm.memset on any integer bit
5764    width. Not all targets support all bit widths however.</p>
5765
5766 <pre>
5767   declare void @llvm.memset.i8(i8 * &lt;dest&gt;, i8 &lt;val&gt;,
5768                                i8 &lt;len&gt;, i32 &lt;align&gt;)
5769   declare void @llvm.memset.i16(i8 * &lt;dest&gt;, i8 &lt;val&gt;,
5770                                 i16 &lt;len&gt;, i32 &lt;align&gt;)
5771   declare void @llvm.memset.i32(i8 * &lt;dest&gt;, i8 &lt;val&gt;,
5772                                 i32 &lt;len&gt;, i32 &lt;align&gt;)
5773   declare void @llvm.memset.i64(i8 * &lt;dest&gt;, i8 &lt;val&gt;,
5774                                 i64 &lt;len&gt;, i32 &lt;align&gt;)
5775 </pre>
5776
5777 <h5>Overview:</h5>
5778 <p>The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a
5779    particular byte value.</p>
5780
5781 <p>Note that, unlike the standard libc function, the <tt>llvm.memset</tt>
5782    intrinsic does not return a value, and takes an extra alignment argument.</p>
5783
5784 <h5>Arguments:</h5>
5785 <p>The first argument is a pointer to the destination to fill, the second is the
5786    byte value to fill it with, the third argument is an integer argument
5787    specifying the number of bytes to fill, and the fourth argument is the known
5788    alignment of destination location.</p>
5789
5790 <p>If the call to this intrinisic has an alignment value that is not 0 or 1,
5791    then the caller guarantees that the destination pointer is aligned to that
5792    boundary.</p>
5793
5794 <h5>Semantics:</h5>
5795 <p>The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting
5796    at the destination location.  If the argument is known to be aligned to some
5797    boundary, this can be specified as the fourth argument, otherwise it should
5798    be set to 0 or 1.</p>
5799
5800 </div>
5801
5802 <!-- _______________________________________________________________________ -->
5803 <div class="doc_subsubsection">
5804   <a name="int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
5805 </div>
5806
5807 <div class="doc_text">
5808
5809 <h5>Syntax:</h5>
5810 <p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any
5811    floating point or vector of floating point type. Not all targets support all
5812    types however.</p>
5813
5814 <pre>
5815   declare float     @llvm.sqrt.f32(float %Val)
5816   declare double    @llvm.sqrt.f64(double %Val)
5817   declare x86_fp80  @llvm.sqrt.f80(x86_fp80 %Val)
5818   declare fp128     @llvm.sqrt.f128(fp128 %Val)
5819   declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
5820 </pre>
5821
5822 <h5>Overview:</h5>
5823 <p>The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand,
5824    returning the same value as the libm '<tt>sqrt</tt>' functions would.
5825    Unlike <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined
5826    behavior for negative numbers other than -0.0 (which allows for better
5827    optimization, because there is no need to worry about errno being
5828    set).  <tt>llvm.sqrt(-0.0)</tt> is defined to return -0.0 like IEEE sqrt.</p>
5829
5830 <h5>Arguments:</h5>
5831 <p>The argument and return value are floating point numbers of the same
5832    type.</p>
5833
5834 <h5>Semantics:</h5>
5835 <p>This function returns the sqrt of the specified operand if it is a
5836    nonnegative floating point number.</p>
5837
5838 </div>
5839
5840 <!-- _______________________________________________________________________ -->
5841 <div class="doc_subsubsection">
5842   <a name="int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
5843 </div>
5844
5845 <div class="doc_text">
5846
5847 <h5>Syntax:</h5>
5848 <p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any
5849    floating point or vector of floating point type. Not all targets support all
5850    types however.</p>
5851
5852 <pre>
5853   declare float     @llvm.powi.f32(float  %Val, i32 %power)
5854   declare double    @llvm.powi.f64(double %Val, i32 %power)
5855   declare x86_fp80  @llvm.powi.f80(x86_fp80  %Val, i32 %power)
5856   declare fp128     @llvm.powi.f128(fp128 %Val, i32 %power)
5857   declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128  %Val, i32 %power)
5858 </pre>
5859
5860 <h5>Overview:</h5>
5861 <p>The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the
5862    specified (positive or negative) power.  The order of evaluation of
5863    multiplications is not defined.  When a vector of floating point type is
5864    used, the second argument remains a scalar integer value.</p>
5865
5866 <h5>Arguments:</h5>
5867 <p>The second argument is an integer power, and the first is a value to raise to
5868    that power.</p>
5869
5870 <h5>Semantics:</h5>
5871 <p>This function returns the first value raised to the second power with an
5872    unspecified sequence of rounding operations.</p>
5873
5874 </div>
5875
5876 <!-- _______________________________________________________________________ -->
5877 <div class="doc_subsubsection">
5878   <a name="int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a>
5879 </div>
5880
5881 <div class="doc_text">
5882
5883 <h5>Syntax:</h5>
5884 <p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any
5885    floating point or vector of floating point type. Not all targets support all
5886    types however.</p>
5887
5888 <pre>
5889   declare float     @llvm.sin.f32(float  %Val)
5890   declare double    @llvm.sin.f64(double %Val)
5891   declare x86_fp80  @llvm.sin.f80(x86_fp80  %Val)
5892   declare fp128     @llvm.sin.f128(fp128 %Val)
5893   declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128  %Val)
5894 </pre>
5895
5896 <h5>Overview:</h5>
5897 <p>The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand.</p>
5898
5899 <h5>Arguments:</h5>
5900 <p>The argument and return value are floating point numbers of the same
5901    type.</p>
5902
5903 <h5>Semantics:</h5>
5904 <p>This function returns the sine of the specified operand, returning the same
5905    values as the libm <tt>sin</tt> functions would, and handles error conditions
5906    in the same way.</p>
5907
5908 </div>
5909
5910 <!-- _______________________________________________________________________ -->
5911 <div class="doc_subsubsection">
5912   <a name="int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a>
5913 </div>
5914
5915 <div class="doc_text">
5916
5917 <h5>Syntax:</h5>
5918 <p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any
5919    floating point or vector of floating point type. Not all targets support all
5920    types however.</p>
5921
5922 <pre>
5923   declare float     @llvm.cos.f32(float  %Val)
5924   declare double    @llvm.cos.f64(double %Val)
5925   declare x86_fp80  @llvm.cos.f80(x86_fp80  %Val)
5926   declare fp128     @llvm.cos.f128(fp128 %Val)
5927   declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128  %Val)
5928 </pre>
5929
5930 <h5>Overview:</h5>
5931 <p>The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand.</p>
5932
5933 <h5>Arguments:</h5>
5934 <p>The argument and return value are floating point numbers of the same
5935    type.</p>
5936
5937 <h5>Semantics:</h5>
5938 <p>This function returns the cosine of the specified operand, returning the same
5939    values as the libm <tt>cos</tt> functions would, and handles error conditions
5940    in the same way.</p>
5941
5942 </div>
5943
5944 <!-- _______________________________________________________________________ -->
5945 <div class="doc_subsubsection">
5946   <a name="int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a>
5947 </div>
5948
5949 <div class="doc_text">
5950
5951 <h5>Syntax:</h5>
5952 <p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any
5953    floating point or vector of floating point type. Not all targets support all
5954    types however.</p>
5955
5956 <pre>
5957   declare float     @llvm.pow.f32(float  %Val, float %Power)
5958   declare double    @llvm.pow.f64(double %Val, double %Power)
5959   declare x86_fp80  @llvm.pow.f80(x86_fp80  %Val, x86_fp80 %Power)
5960   declare fp128     @llvm.pow.f128(fp128 %Val, fp128 %Power)
5961   declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128  %Val, ppc_fp128 Power)
5962 </pre>
5963
5964 <h5>Overview:</h5>
5965 <p>The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the
5966    specified (positive or negative) power.</p>
5967
5968 <h5>Arguments:</h5>
5969 <p>The second argument is a floating point power, and the first is a value to
5970    raise to that power.</p>
5971
5972 <h5>Semantics:</h5>
5973 <p>This function returns the first value raised to the second power, returning
5974    the same values as the libm <tt>pow</tt> functions would, and handles error
5975    conditions in the same way.</p>
5976
5977 </div>
5978
5979 <!-- ======================================================================= -->
5980 <div class="doc_subsection">
5981   <a name="int_manip">Bit Manipulation Intrinsics</a>
5982 </div>
5983
5984 <div class="doc_text">
5985
5986 <p>LLVM provides intrinsics for a few important bit manipulation operations.
5987    These allow efficient code generation for some algorithms.</p>
5988
5989 </div>
5990
5991 <!-- _______________________________________________________________________ -->
5992 <div class="doc_subsubsection">
5993   <a name="int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
5994 </div>
5995
5996 <div class="doc_text">
5997
5998 <h5>Syntax:</h5>
5999 <p>This is an overloaded intrinsic function. You can use bswap on any integer
6000    type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p>
6001
6002 <pre>
6003   declare i16 @llvm.bswap.i16(i16 &lt;id&gt;)
6004   declare i32 @llvm.bswap.i32(i32 &lt;id&gt;)
6005   declare i64 @llvm.bswap.i64(i64 &lt;id&gt;)
6006 </pre>
6007
6008 <h5>Overview:</h5>
6009 <p>The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer
6010    values with an even number of bytes (positive multiple of 16 bits).  These
6011    are useful for performing operations on data that is not in the target's
6012    native byte order.</p>
6013
6014 <h5>Semantics:</h5>
6015 <p>The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high
6016    and low byte of the input i16 swapped.  Similarly,
6017    the <tt>llvm.bswap.i32</tt> intrinsic returns an i32 value that has the four
6018    bytes of the input i32 swapped, so that if the input bytes are numbered 0, 1,
6019    2, 3 then the returned i32 will have its bytes in 3, 2, 1, 0 order.
6020    The <tt>llvm.bswap.i48</tt>, <tt>llvm.bswap.i64</tt> and other intrinsics
6021    extend this concept to additional even-byte lengths (6 bytes, 8 bytes and
6022    more, respectively).</p>
6023
6024 </div>
6025
6026 <!-- _______________________________________________________________________ -->
6027 <div class="doc_subsubsection">
6028   <a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
6029 </div>
6030
6031 <div class="doc_text">
6032
6033 <h5>Syntax:</h5>
6034 <p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit
6035    width. Not all targets support all bit widths however.</p>
6036
6037 <pre>
6038   declare i8 @llvm.ctpop.i8(i8  &lt;src&gt;)
6039   declare i16 @llvm.ctpop.i16(i16 &lt;src&gt;)
6040   declare i32 @llvm.ctpop.i32(i32 &lt;src&gt;)
6041   declare i64 @llvm.ctpop.i64(i64 &lt;src&gt;)
6042   declare i256 @llvm.ctpop.i256(i256 &lt;src&gt;)
6043 </pre>
6044
6045 <h5>Overview:</h5>
6046 <p>The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set
6047    in a value.</p>
6048
6049 <h5>Arguments:</h5>
6050 <p>The only argument is the value to be counted.  The argument may be of any
6051    integer type.  The return type must match the argument type.</p>
6052
6053 <h5>Semantics:</h5>
6054 <p>The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.</p>
6055
6056 </div>
6057
6058 <!-- _______________________________________________________________________ -->
6059 <div class="doc_subsubsection">
6060   <a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a>
6061 </div>
6062
6063 <div class="doc_text">
6064
6065 <h5>Syntax:</h5>
6066 <p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any
6067    integer bit width. Not all targets support all bit widths however.</p>
6068
6069 <pre>
6070   declare i8 @llvm.ctlz.i8 (i8  &lt;src&gt;)
6071   declare i16 @llvm.ctlz.i16(i16 &lt;src&gt;)
6072   declare i32 @llvm.ctlz.i32(i32 &lt;src&gt;)
6073   declare i64 @llvm.ctlz.i64(i64 &lt;src&gt;)
6074   declare i256 @llvm.ctlz.i256(i256 &lt;src&gt;)
6075 </pre>
6076
6077 <h5>Overview:</h5>
6078 <p>The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of
6079    leading zeros in a variable.</p>
6080
6081 <h5>Arguments:</h5>
6082 <p>The only argument is the value to be counted.  The argument may be of any
6083    integer type. The return type must match the argument type.</p>
6084
6085 <h5>Semantics:</h5>
6086 <p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant)
6087    zeros in a variable.  If the src == 0 then the result is the size in bits of
6088    the type of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p>
6089
6090 </div>
6091
6092 <!-- _______________________________________________________________________ -->
6093 <div class="doc_subsubsection">
6094   <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a>
6095 </div>
6096
6097 <div class="doc_text">
6098
6099 <h5>Syntax:</h5>
6100 <p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any
6101    integer bit width. Not all targets support all bit widths however.</p>
6102
6103 <pre>
6104   declare i8 @llvm.cttz.i8 (i8  &lt;src&gt;)
6105   declare i16 @llvm.cttz.i16(i16 &lt;src&gt;)
6106   declare i32 @llvm.cttz.i32(i32 &lt;src&gt;)
6107   declare i64 @llvm.cttz.i64(i64 &lt;src&gt;)
6108   declare i256 @llvm.cttz.i256(i256 &lt;src&gt;)
6109 </pre>
6110
6111 <h5>Overview:</h5>
6112 <p>The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of
6113    trailing zeros.</p>
6114
6115 <h5>Arguments:</h5>
6116 <p>The only argument is the value to be counted.  The argument may be of any
6117    integer type.  The return type must match the argument type.</p>
6118
6119 <h5>Semantics:</h5>
6120 <p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant)
6121    zeros in a variable.  If the src == 0 then the result is the size in bits of
6122    the type of src.  For example, <tt>llvm.cttz(2) = 1</tt>.</p>
6123
6124 </div>
6125
6126 <!-- ======================================================================= -->
6127 <div class="doc_subsection">
6128   <a name="int_overflow">Arithmetic with Overflow Intrinsics</a>
6129 </div>
6130
6131 <div class="doc_text">
6132
6133 <p>LLVM provides intrinsics for some arithmetic with overflow operations.</p>
6134
6135 </div>
6136
6137 <!-- _______________________________________________________________________ -->
6138 <div class="doc_subsubsection">
6139   <a name="int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt>' Intrinsics</a>
6140 </div>
6141
6142 <div class="doc_text">
6143
6144 <h5>Syntax:</h5>
6145 <p>This is an overloaded intrinsic. You can use <tt>llvm.sadd.with.overflow</tt>
6146    on any integer bit width.</p>
6147
6148 <pre>
6149   declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
6150   declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
6151   declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
6152 </pre>
6153
6154 <h5>Overview:</h5>
6155 <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
6156    a signed addition of the two arguments, and indicate whether an overflow
6157    occurred during the signed summation.</p>
6158
6159 <h5>Arguments:</h5>
6160 <p>The arguments (%a and %b) and the first element of the result structure may
6161    be of integer types of any bit width, but they must have the same bit
6162    width. The second element of the result structure must be of
6163    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6164    undergo signed addition.</p>
6165
6166 <h5>Semantics:</h5>
6167 <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
6168    a signed addition of the two variables. They return a structure &mdash; the
6169    first element of which is the signed summation, and the second element of
6170    which is a bit specifying if the signed summation resulted in an
6171    overflow.</p>
6172
6173 <h5>Examples:</h5>
6174 <pre>
6175   %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
6176   %sum = extractvalue {i32, i1} %res, 0
6177   %obit = extractvalue {i32, i1} %res, 1
6178   br i1 %obit, label %overflow, label %normal
6179 </pre>
6180
6181 </div>
6182
6183 <!-- _______________________________________________________________________ -->
6184 <div class="doc_subsubsection">
6185   <a name="int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt>' Intrinsics</a>
6186 </div>
6187
6188 <div class="doc_text">
6189
6190 <h5>Syntax:</h5>
6191 <p>This is an overloaded intrinsic. You can use <tt>llvm.uadd.with.overflow</tt>
6192    on any integer bit width.</p>
6193
6194 <pre>
6195   declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
6196   declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
6197   declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
6198 </pre>
6199
6200 <h5>Overview:</h5>
6201 <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
6202    an unsigned addition of the two arguments, and indicate whether a carry
6203    occurred during the unsigned summation.</p>
6204
6205 <h5>Arguments:</h5>
6206 <p>The arguments (%a and %b) and the first element of the result structure may
6207    be of integer types of any bit width, but they must have the same bit
6208    width. The second element of the result structure must be of
6209    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6210    undergo unsigned addition.</p>
6211
6212 <h5>Semantics:</h5>
6213 <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
6214    an unsigned addition of the two arguments. They return a structure &mdash;
6215    the first element of which is the sum, and the second element of which is a
6216    bit specifying if the unsigned summation resulted in a carry.</p>
6217
6218 <h5>Examples:</h5>
6219 <pre>
6220   %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
6221   %sum = extractvalue {i32, i1} %res, 0
6222   %obit = extractvalue {i32, i1} %res, 1
6223   br i1 %obit, label %carry, label %normal
6224 </pre>
6225
6226 </div>
6227
6228 <!-- _______________________________________________________________________ -->
6229 <div class="doc_subsubsection">
6230   <a name="int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt>' Intrinsics</a>
6231 </div>
6232
6233 <div class="doc_text">
6234
6235 <h5>Syntax:</h5>
6236 <p>This is an overloaded intrinsic. You can use <tt>llvm.ssub.with.overflow</tt>
6237    on any integer bit width.</p>
6238
6239 <pre>
6240   declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
6241   declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
6242   declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
6243 </pre>
6244
6245 <h5>Overview:</h5>
6246 <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
6247    a signed subtraction of the two arguments, and indicate whether an overflow
6248    occurred during the signed subtraction.</p>
6249
6250 <h5>Arguments:</h5>
6251 <p>The arguments (%a and %b) and the first element of the result structure may
6252    be of integer types of any bit width, but they must have the same bit
6253    width. The second element of the result structure must be of
6254    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6255    undergo signed subtraction.</p>
6256
6257 <h5>Semantics:</h5>
6258 <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
6259    a signed subtraction of the two arguments. They return a structure &mdash;
6260    the first element of which is the subtraction, and the second element of
6261    which is a bit specifying if the signed subtraction resulted in an
6262    overflow.</p>
6263
6264 <h5>Examples:</h5>
6265 <pre>
6266   %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
6267   %sum = extractvalue {i32, i1} %res, 0
6268   %obit = extractvalue {i32, i1} %res, 1
6269   br i1 %obit, label %overflow, label %normal
6270 </pre>
6271
6272 </div>
6273
6274 <!-- _______________________________________________________________________ -->
6275 <div class="doc_subsubsection">
6276   <a name="int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt>' Intrinsics</a>
6277 </div>
6278
6279 <div class="doc_text">
6280
6281 <h5>Syntax:</h5>
6282 <p>This is an overloaded intrinsic. You can use <tt>llvm.usub.with.overflow</tt>
6283    on any integer bit width.</p>
6284
6285 <pre>
6286   declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
6287   declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
6288   declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
6289 </pre>
6290
6291 <h5>Overview:</h5>
6292 <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
6293    an unsigned subtraction of the two arguments, and indicate whether an
6294    overflow occurred during the unsigned subtraction.</p>
6295
6296 <h5>Arguments:</h5>
6297 <p>The arguments (%a and %b) and the first element of the result structure may
6298    be of integer types of any bit width, but they must have the same bit
6299    width. The second element of the result structure must be of
6300    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6301    undergo unsigned subtraction.</p>
6302
6303 <h5>Semantics:</h5>
6304 <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
6305    an unsigned subtraction of the two arguments. They return a structure &mdash;
6306    the first element of which is the subtraction, and the second element of
6307    which is a bit specifying if the unsigned subtraction resulted in an
6308    overflow.</p>
6309
6310 <h5>Examples:</h5>
6311 <pre>
6312   %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
6313   %sum = extractvalue {i32, i1} %res, 0
6314   %obit = extractvalue {i32, i1} %res, 1
6315   br i1 %obit, label %overflow, label %normal
6316 </pre>
6317
6318 </div>
6319
6320 <!-- _______________________________________________________________________ -->
6321 <div class="doc_subsubsection">
6322   <a name="int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt>' Intrinsics</a>
6323 </div>
6324
6325 <div class="doc_text">
6326
6327 <h5>Syntax:</h5>
6328 <p>This is an overloaded intrinsic. You can use <tt>llvm.smul.with.overflow</tt>
6329    on any integer bit width.</p>
6330
6331 <pre>
6332   declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
6333   declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
6334   declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
6335 </pre>
6336
6337 <h5>Overview:</h5>
6338
6339 <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
6340    a signed multiplication of the two arguments, and indicate whether an
6341    overflow occurred during the signed multiplication.</p>
6342
6343 <h5>Arguments:</h5>
6344 <p>The arguments (%a and %b) and the first element of the result structure may
6345    be of integer types of any bit width, but they must have the same bit
6346    width. The second element of the result structure must be of
6347    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6348    undergo signed multiplication.</p>
6349
6350 <h5>Semantics:</h5>
6351 <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
6352    a signed multiplication of the two arguments. They return a structure &mdash;
6353    the first element of which is the multiplication, and the second element of
6354    which is a bit specifying if the signed multiplication resulted in an
6355    overflow.</p>
6356
6357 <h5>Examples:</h5>
6358 <pre>
6359   %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
6360   %sum = extractvalue {i32, i1} %res, 0
6361   %obit = extractvalue {i32, i1} %res, 1
6362   br i1 %obit, label %overflow, label %normal
6363 </pre>
6364
6365 </div>
6366
6367 <!-- _______________________________________________________________________ -->
6368 <div class="doc_subsubsection">
6369   <a name="int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt>' Intrinsics</a>
6370 </div>
6371
6372 <div class="doc_text">
6373
6374 <h5>Syntax:</h5>
6375 <p>This is an overloaded intrinsic. You can use <tt>llvm.umul.with.overflow</tt>
6376    on any integer bit width.</p>
6377
6378 <pre>
6379   declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
6380   declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
6381   declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
6382 </pre>
6383
6384 <h5>Overview:</h5>
6385 <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
6386    a unsigned multiplication of the two arguments, and indicate whether an
6387    overflow occurred during the unsigned multiplication.</p>
6388
6389 <h5>Arguments:</h5>
6390 <p>The arguments (%a and %b) and the first element of the result structure may
6391    be of integer types of any bit width, but they must have the same bit
6392    width. The second element of the result structure must be of
6393    type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
6394    undergo unsigned multiplication.</p>
6395
6396 <h5>Semantics:</h5>
6397 <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
6398    an unsigned multiplication of the two arguments. They return a structure
6399    &mdash; the first element of which is the multiplication, and the second
6400    element of which is a bit specifying if the unsigned multiplication resulted
6401    in an overflow.</p>
6402
6403 <h5>Examples:</h5>
6404 <pre>
6405   %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
6406   %sum = extractvalue {i32, i1} %res, 0
6407   %obit = extractvalue {i32, i1} %res, 1
6408   br i1 %obit, label %overflow, label %normal
6409 </pre>
6410
6411 </div>
6412
6413 <!-- ======================================================================= -->
6414 <div class="doc_subsection">
6415   <a name="int_debugger">Debugger Intrinsics</a>
6416 </div>
6417
6418 <div class="doc_text">
6419
6420 <p>The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt>
6421    prefix), are described in
6422    the <a href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source
6423    Level Debugging</a> document.</p>
6424
6425 </div>
6426
6427 <!-- ======================================================================= -->
6428 <div class="doc_subsection">
6429   <a name="int_eh">Exception Handling Intrinsics</a>
6430 </div>
6431
6432 <div class="doc_text">
6433
6434 <p>The LLVM exception handling intrinsics (which all start with
6435    <tt>llvm.eh.</tt> prefix), are described in
6436    the <a href="ExceptionHandling.html#format_common_intrinsics">LLVM Exception
6437    Handling</a> document.</p>
6438
6439 </div>
6440
6441 <!-- ======================================================================= -->
6442 <div class="doc_subsection">
6443   <a name="int_trampoline">Trampoline Intrinsic</a>
6444 </div>
6445
6446 <div class="doc_text">
6447
6448 <p>This intrinsic makes it possible to excise one parameter, marked with
6449    the <tt>nest</tt> attribute, from a function.  The result is a callable
6450    function pointer lacking the nest parameter - the caller does not need to
6451    provide a value for it.  Instead, the value to use is stored in advance in a
6452    "trampoline", a block of memory usually allocated on the stack, which also
6453    contains code to splice the nest value into the argument list.  This is used
6454    to implement the GCC nested function address extension.</p>
6455
6456 <p>For example, if the function is
6457    <tt>i32 f(i8* nest %c, i32 %x, i32 %y)</tt> then the resulting function
6458    pointer has signature <tt>i32 (i32, i32)*</tt>.  It can be created as
6459    follows:</p>
6460
6461 <div class="doc_code">
6462 <pre>
6463   %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
6464   %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
6465   %p = call i8* @llvm.init.trampoline( i8* %tramp1, i8* bitcast (i32 (i8* nest , i32, i32)* @f to i8*), i8* %nval )
6466   %fp = bitcast i8* %p to i32 (i32, i32)*
6467 </pre>
6468 </div>
6469
6470 <p>The call <tt>%val = call i32 %fp( i32 %x, i32 %y )</tt> is then equivalent
6471    to <tt>%val = call i32 %f( i8* %nval, i32 %x, i32 %y )</tt>.</p>
6472
6473 </div>
6474
6475 <!-- _______________________________________________________________________ -->
6476 <div class="doc_subsubsection">
6477   <a name="int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a>
6478 </div>
6479
6480 <div class="doc_text">
6481
6482 <h5>Syntax:</h5>
6483 <pre>
6484   declare i8* @llvm.init.trampoline(i8* &lt;tramp&gt;, i8* &lt;func&gt;, i8* &lt;nval&gt;)
6485 </pre>
6486
6487 <h5>Overview:</h5>
6488 <p>This fills the memory pointed to by <tt>tramp</tt> with code and returns a
6489    function pointer suitable for executing it.</p>
6490
6491 <h5>Arguments:</h5>
6492 <p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all
6493    pointers.  The <tt>tramp</tt> argument must point to a sufficiently large and
6494    sufficiently aligned block of memory; this memory is written to by the
6495    intrinsic.  Note that the size and the alignment are target-specific - LLVM
6496    currently provides no portable way of determining them, so a front-end that
6497    generates this intrinsic needs to have some target-specific knowledge.
6498    The <tt>func</tt> argument must hold a function bitcast to
6499    an <tt>i8*</tt>.</p>
6500
6501 <h5>Semantics:</h5>
6502 <p>The block of memory pointed to by <tt>tramp</tt> is filled with target
6503    dependent code, turning it into a function.  A pointer to this function is
6504    returned, but needs to be bitcast to an <a href="#int_trampoline">appropriate
6505    function pointer type</a> before being called.  The new function's signature
6506    is the same as that of <tt>func</tt> with any arguments marked with
6507    the <tt>nest</tt> attribute removed.  At most one such <tt>nest</tt> argument
6508    is allowed, and it must be of pointer type.  Calling the new function is
6509    equivalent to calling <tt>func</tt> with the same argument list, but
6510    with <tt>nval</tt> used for the missing <tt>nest</tt> argument.  If, after
6511    calling <tt>llvm.init.trampoline</tt>, the memory pointed to
6512    by <tt>tramp</tt> is modified, then the effect of any later call to the
6513    returned function pointer is undefined.</p>
6514
6515 </div>
6516
6517 <!-- ======================================================================= -->
6518 <div class="doc_subsection">
6519   <a name="int_atomics">Atomic Operations and Synchronization Intrinsics</a>
6520 </div>
6521
6522 <div class="doc_text">
6523
6524 <p>These intrinsic functions expand the "universal IR" of LLVM to represent
6525    hardware constructs for atomic operations and memory synchronization.  This
6526    provides an interface to the hardware, not an interface to the programmer. It
6527    is aimed at a low enough level to allow any programming models or APIs
6528    (Application Programming Interfaces) which need atomic behaviors to map
6529    cleanly onto it. It is also modeled primarily on hardware behavior. Just as
6530    hardware provides a "universal IR" for source languages, it also provides a
6531    starting point for developing a "universal" atomic operation and
6532    synchronization IR.</p>
6533
6534 <p>These do <em>not</em> form an API such as high-level threading libraries,
6535    software transaction memory systems, atomic primitives, and intrinsic
6536    functions as found in BSD, GNU libc, atomic_ops, APR, and other system and
6537    application libraries.  The hardware interface provided by LLVM should allow
6538    a clean implementation of all of these APIs and parallel programming models.
6539    No one model or paradigm should be selected above others unless the hardware
6540    itself ubiquitously does so.</p>
6541
6542 </div>
6543
6544 <!-- _______________________________________________________________________ -->
6545 <div class="doc_subsubsection">
6546   <a name="int_memory_barrier">'<tt>llvm.memory.barrier</tt>' Intrinsic</a>
6547 </div>
6548 <div class="doc_text">
6549 <h5>Syntax:</h5>
6550 <pre>
6551   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; )
6552 </pre>
6553
6554 <h5>Overview:</h5>
6555 <p>The <tt>llvm.memory.barrier</tt> intrinsic guarantees ordering between
6556    specific pairs of memory access types.</p>
6557
6558 <h5>Arguments:</h5>
6559 <p>The <tt>llvm.memory.barrier</tt> intrinsic requires five boolean arguments.
6560    The first four arguments enables a specific barrier as listed below.  The
6561    fith argument specifies that the barrier applies to io or device or uncached
6562    memory.</p>
6563
6564 <ul>
6565   <li><tt>ll</tt>: load-load barrier</li>
6566   <li><tt>ls</tt>: load-store barrier</li>
6567   <li><tt>sl</tt>: store-load barrier</li>
6568   <li><tt>ss</tt>: store-store barrier</li>
6569   <li><tt>device</tt>: barrier applies to device and uncached memory also.</li>
6570 </ul>
6571
6572 <h5>Semantics:</h5>
6573 <p>This intrinsic causes the system to enforce some ordering constraints upon
6574    the loads and stores of the program. This barrier does not
6575    indicate <em>when</em> any events will occur, it only enforces
6576    an <em>order</em> in which they occur. For any of the specified pairs of load
6577    and store operations (f.ex.  load-load, or store-load), all of the first
6578    operations preceding the barrier will complete before any of the second
6579    operations succeeding the barrier begin. Specifically the semantics for each
6580    pairing is as follows:</p>
6581
6582 <ul>
6583   <li><tt>ll</tt>: All loads before the barrier must complete before any load
6584       after the barrier begins.</li>
6585   <li><tt>ls</tt>: All loads before the barrier must complete before any
6586       store after the barrier begins.</li>
6587   <li><tt>ss</tt>: All stores before the barrier must complete before any
6588       store after the barrier begins.</li>
6589   <li><tt>sl</tt>: All stores before the barrier must complete before any
6590       load after the barrier begins.</li>
6591 </ul>
6592
6593 <p>These semantics are applied with a logical "and" behavior when more than one
6594    is enabled in a single memory barrier intrinsic.</p>
6595
6596 <p>Backends may implement stronger barriers than those requested when they do
6597    not support as fine grained a barrier as requested.  Some architectures do
6598    not need all types of barriers and on such architectures, these become
6599    noops.</p>
6600
6601 <h5>Example:</h5>
6602 <pre>
6603 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
6604 %ptr      = bitcast i8* %mallocP to i32*
6605             store i32 4, %ptr
6606
6607 %result1  = load i32* %ptr      <i>; yields {i32}:result1 = 4</i>
6608             call void @llvm.memory.barrier( i1 false, i1 true, i1 false, i1 false )
6609                                 <i>; guarantee the above finishes</i>
6610             store i32 8, %ptr   <i>; before this begins</i>
6611 </pre>
6612
6613 </div>
6614
6615 <!-- _______________________________________________________________________ -->
6616 <div class="doc_subsubsection">
6617   <a name="int_atomic_cmp_swap">'<tt>llvm.atomic.cmp.swap.*</tt>' Intrinsic</a>
6618 </div>
6619
6620 <div class="doc_text">
6621
6622 <h5>Syntax:</h5>
6623 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.cmp.swap</tt> on
6624    any integer bit width and for different address spaces. Not all targets
6625    support all bit widths however.</p>
6626
6627 <pre>
6628   declare i8 @llvm.atomic.cmp.swap.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;cmp&gt;, i8 &lt;val&gt; )
6629   declare i16 @llvm.atomic.cmp.swap.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;cmp&gt;, i16 &lt;val&gt; )
6630   declare i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;cmp&gt;, i32 &lt;val&gt; )
6631   declare i64 @llvm.atomic.cmp.swap.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;cmp&gt;, i64 &lt;val&gt; )
6632 </pre>
6633
6634 <h5>Overview:</h5>
6635 <p>This loads a value in memory and compares it to a given value. If they are
6636    equal, it stores a new value into the memory.</p>
6637
6638 <h5>Arguments:</h5>
6639 <p>The <tt>llvm.atomic.cmp.swap</tt> intrinsic takes three arguments. The result
6640    as well as both <tt>cmp</tt> and <tt>val</tt> must be integer values with the
6641    same bit width. The <tt>ptr</tt> argument must be a pointer to a value of
6642    this integer type. While any bit width integer may be used, targets may only
6643    lower representations they support in hardware.</p>
6644
6645 <h5>Semantics:</h5>
6646 <p>This entire intrinsic must be executed atomically. It first loads the value
6647    in memory pointed to by <tt>ptr</tt> and compares it with the
6648    value <tt>cmp</tt>. If they are equal, <tt>val</tt> is stored into the
6649    memory. The loaded value is yielded in all cases. This provides the
6650    equivalent of an atomic compare-and-swap operation within the SSA
6651    framework.</p>
6652
6653 <h5>Examples:</h5>
6654 <pre>
6655 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
6656 %ptr      = bitcast i8* %mallocP to i32*
6657             store i32 4, %ptr
6658
6659 %val1     = add i32 4, 4
6660 %result1  = call i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* %ptr, i32 4, %val1 )
6661                                           <i>; yields {i32}:result1 = 4</i>
6662 %stored1  = icmp eq i32 %result1, 4       <i>; yields {i1}:stored1 = true</i>
6663 %memval1  = load i32* %ptr                <i>; yields {i32}:memval1 = 8</i>
6664
6665 %val2     = add i32 1, 1
6666 %result2  = call i32 @llvm.atomic.cmp.swap.i32.p0i32( i32* %ptr, i32 5, %val2 )
6667                                           <i>; yields {i32}:result2 = 8</i>
6668 %stored2  = icmp eq i32 %result2, 5       <i>; yields {i1}:stored2 = false</i>
6669
6670 %memval2  = load i32* %ptr                <i>; yields {i32}:memval2 = 8</i>
6671 </pre>
6672
6673 </div>
6674
6675 <!-- _______________________________________________________________________ -->
6676 <div class="doc_subsubsection">
6677   <a name="int_atomic_swap">'<tt>llvm.atomic.swap.*</tt>' Intrinsic</a>
6678 </div>
6679 <div class="doc_text">
6680 <h5>Syntax:</h5>
6681
6682 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.swap</tt> on any
6683    integer bit width. Not all targets support all bit widths however.</p>
6684
6685 <pre>
6686   declare i8 @llvm.atomic.swap.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;val&gt; )
6687   declare i16 @llvm.atomic.swap.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;val&gt; )
6688   declare i32 @llvm.atomic.swap.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;val&gt; )
6689   declare i64 @llvm.atomic.swap.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;val&gt; )
6690 </pre>
6691
6692 <h5>Overview:</h5>
6693 <p>This intrinsic loads the value stored in memory at <tt>ptr</tt> and yields
6694    the value from memory. It then stores the value in <tt>val</tt> in the memory
6695    at <tt>ptr</tt>.</p>
6696
6697 <h5>Arguments:</h5>
6698 <p>The <tt>llvm.atomic.swap</tt> intrinsic takes two arguments. Both
6699   the <tt>val</tt> argument and the result must be integers of the same bit
6700   width.  The first argument, <tt>ptr</tt>, must be a pointer to a value of this
6701   integer type. The targets may only lower integer representations they
6702   support.</p>
6703
6704 <h5>Semantics:</h5>
6705 <p>This intrinsic loads the value pointed to by <tt>ptr</tt>, yields it, and
6706    stores <tt>val</tt> back into <tt>ptr</tt> atomically. This provides the
6707    equivalent of an atomic swap operation within the SSA framework.</p>
6708
6709 <h5>Examples:</h5>
6710 <pre>
6711 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
6712 %ptr      = bitcast i8* %mallocP to i32*
6713             store i32 4, %ptr
6714
6715 %val1     = add i32 4, 4
6716 %result1  = call i32 @llvm.atomic.swap.i32.p0i32( i32* %ptr, i32 %val1 )
6717                                         <i>; yields {i32}:result1 = 4</i>
6718 %stored1  = icmp eq i32 %result1, 4     <i>; yields {i1}:stored1 = true</i>
6719 %memval1  = load i32* %ptr              <i>; yields {i32}:memval1 = 8</i>
6720
6721 %val2     = add i32 1, 1
6722 %result2  = call i32 @llvm.atomic.swap.i32.p0i32( i32* %ptr, i32 %val2 )
6723                                         <i>; yields {i32}:result2 = 8</i>
6724
6725 %stored2  = icmp eq i32 %result2, 8     <i>; yields {i1}:stored2 = true</i>
6726 %memval2  = load i32* %ptr              <i>; yields {i32}:memval2 = 2</i>
6727 </pre>
6728
6729 </div>
6730
6731 <!-- _______________________________________________________________________ -->
6732 <div class="doc_subsubsection">
6733   <a name="int_atomic_load_add">'<tt>llvm.atomic.load.add.*</tt>' Intrinsic</a>
6734
6735 </div>
6736
6737 <div class="doc_text">
6738
6739 <h5>Syntax:</h5>
6740 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.add</tt> on
6741    any integer bit width. Not all targets support all bit widths however.</p>
6742
6743 <pre>
6744   declare i8 @llvm.atomic.load.add.i8..p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
6745   declare i16 @llvm.atomic.load.add.i16..p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
6746   declare i32 @llvm.atomic.load.add.i32..p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
6747   declare i64 @llvm.atomic.load.add.i64..p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
6748 </pre>
6749
6750 <h5>Overview:</h5>
6751 <p>This intrinsic adds <tt>delta</tt> to the value stored in memory
6752    at <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p>
6753
6754 <h5>Arguments:</h5>
6755 <p>The intrinsic takes two arguments, the first a pointer to an integer value
6756    and the second an integer value. The result is also an integer value. These
6757    integer types can have any bit width, but they must all have the same bit
6758    width. The targets may only lower integer representations they support.</p>
6759
6760 <h5>Semantics:</h5>
6761 <p>This intrinsic does a series of operations atomically. It first loads the
6762    value stored at <tt>ptr</tt>. It then adds <tt>delta</tt>, stores the result
6763    to <tt>ptr</tt>. It yields the original value stored at <tt>ptr</tt>.</p>
6764
6765 <h5>Examples:</h5>
6766 <pre>
6767 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
6768 %ptr      = bitcast i8* %mallocP to i32*
6769             store i32 4, %ptr
6770 %result1  = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 4 )
6771                                 <i>; yields {i32}:result1 = 4</i>
6772 %result2  = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 2 )
6773                                 <i>; yields {i32}:result2 = 8</i>
6774 %result3  = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 5 )
6775                                 <i>; yields {i32}:result3 = 10</i>
6776 %memval1  = load i32* %ptr      <i>; yields {i32}:memval1 = 15</i>
6777 </pre>
6778
6779 </div>
6780
6781 <!-- _______________________________________________________________________ -->
6782 <div class="doc_subsubsection">
6783   <a name="int_atomic_load_sub">'<tt>llvm.atomic.load.sub.*</tt>' Intrinsic</a>
6784
6785 </div>
6786
6787 <div class="doc_text">
6788
6789 <h5>Syntax:</h5>
6790 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.sub</tt> on
6791    any integer bit width and for different address spaces. Not all targets
6792    support all bit widths however.</p>
6793
6794 <pre>
6795   declare i8 @llvm.atomic.load.sub.i8.p0i32( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
6796   declare i16 @llvm.atomic.load.sub.i16.p0i32( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
6797   declare i32 @llvm.atomic.load.sub.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
6798   declare i64 @llvm.atomic.load.sub.i64.p0i32( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
6799 </pre>
6800
6801 <h5>Overview:</h5>
6802 <p>This intrinsic subtracts <tt>delta</tt> to the value stored in memory at
6803    <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p>
6804
6805 <h5>Arguments:</h5>
6806 <p>The intrinsic takes two arguments, the first a pointer to an integer value
6807    and the second an integer value. The result is also an integer value. These
6808    integer types can have any bit width, but they must all have the same bit
6809    width. The targets may only lower integer representations they support.</p>
6810
6811 <h5>Semantics:</h5>
6812 <p>This intrinsic does a series of operations atomically. It first loads the
6813    value stored at <tt>ptr</tt>. It then subtracts <tt>delta</tt>, stores the
6814    result to <tt>ptr</tt>. It yields the original value stored
6815    at <tt>ptr</tt>.</p>
6816
6817 <h5>Examples:</h5>
6818 <pre>
6819 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
6820 %ptr      = bitcast i8* %mallocP to i32*
6821             store i32 8, %ptr
6822 %result1  = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 4 )
6823                                 <i>; yields {i32}:result1 = 8</i>
6824 %result2  = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 2 )
6825                                 <i>; yields {i32}:result2 = 4</i>
6826 %result3  = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 5 )
6827                                 <i>; yields {i32}:result3 = 2</i>
6828 %memval1  = load i32* %ptr      <i>; yields {i32}:memval1 = -3</i>
6829 </pre>
6830
6831 </div>
6832
6833 <!-- _______________________________________________________________________ -->
6834 <div class="doc_subsubsection">
6835   <a name="int_atomic_load_and">'<tt>llvm.atomic.load.and.*</tt>' Intrinsic</a><br>
6836   <a name="int_atomic_load_nand">'<tt>llvm.atomic.load.nand.*</tt>' Intrinsic</a><br>
6837   <a name="int_atomic_load_or">'<tt>llvm.atomic.load.or.*</tt>' Intrinsic</a><br>
6838   <a name="int_atomic_load_xor">'<tt>llvm.atomic.load.xor.*</tt>' Intrinsic</a><br>
6839 </div>
6840
6841 <div class="doc_text">
6842
6843 <h5>Syntax:</h5>
6844 <p>These are overloaded intrinsics. You can
6845   use <tt>llvm.atomic.load_and</tt>, <tt>llvm.atomic.load_nand</tt>,
6846   <tt>llvm.atomic.load_or</tt>, and <tt>llvm.atomic.load_xor</tt> on any integer
6847   bit width and for different address spaces. Not all targets support all bit
6848   widths however.</p>
6849
6850 <pre>
6851   declare i8 @llvm.atomic.load.and.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
6852   declare i16 @llvm.atomic.load.and.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
6853   declare i32 @llvm.atomic.load.and.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
6854   declare i64 @llvm.atomic.load.and.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
6855 </pre>
6856
6857 <pre>
6858   declare i8 @llvm.atomic.load.or.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
6859   declare i16 @llvm.atomic.load.or.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
6860   declare i32 @llvm.atomic.load.or.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
6861   declare i64 @llvm.atomic.load.or.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
6862 </pre>
6863
6864 <pre>
6865   declare i8 @llvm.atomic.load.nand.i8.p0i32( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
6866   declare i16 @llvm.atomic.load.nand.i16.p0i32( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
6867   declare i32 @llvm.atomic.load.nand.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
6868   declare i64 @llvm.atomic.load.nand.i64.p0i32( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
6869 </pre>
6870
6871 <pre>
6872   declare i8 @llvm.atomic.load.xor.i8.p0i32( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
6873   declare i16 @llvm.atomic.load.xor.i16.p0i32( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
6874   declare i32 @llvm.atomic.load.xor.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
6875   declare i64 @llvm.atomic.load.xor.i64.p0i32( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
6876 </pre>
6877
6878 <h5>Overview:</h5>
6879 <p>These intrinsics bitwise the operation (and, nand, or, xor) <tt>delta</tt> to
6880    the value stored in memory at <tt>ptr</tt>. It yields the original value
6881    at <tt>ptr</tt>.</p>
6882
6883 <h5>Arguments:</h5>
6884 <p>These intrinsics take two arguments, the first a pointer to an integer value
6885    and the second an integer value. The result is also an integer value. These
6886    integer types can have any bit width, but they must all have the same bit
6887    width. The targets may only lower integer representations they support.</p>
6888
6889 <h5>Semantics:</h5>
6890 <p>These intrinsics does a series of operations atomically. They first load the
6891    value stored at <tt>ptr</tt>. They then do the bitwise
6892    operation <tt>delta</tt>, store the result to <tt>ptr</tt>. They yield the
6893    original value stored at <tt>ptr</tt>.</p>
6894
6895 <h5>Examples:</h5>
6896 <pre>
6897 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
6898 %ptr      = bitcast i8* %mallocP to i32*
6899             store i32 0x0F0F, %ptr
6900 %result0  = call i32 @llvm.atomic.load.nand.i32.p0i32( i32* %ptr, i32 0xFF )
6901                                 <i>; yields {i32}:result0 = 0x0F0F</i>
6902 %result1  = call i32 @llvm.atomic.load.and.i32.p0i32( i32* %ptr, i32 0xFF )
6903                                 <i>; yields {i32}:result1 = 0xFFFFFFF0</i>
6904 %result2  = call i32 @llvm.atomic.load.or.i32.p0i32( i32* %ptr, i32 0F )
6905                                 <i>; yields {i32}:result2 = 0xF0</i>
6906 %result3  = call i32 @llvm.atomic.load.xor.i32.p0i32( i32* %ptr, i32 0F )
6907                                 <i>; yields {i32}:result3 = FF</i>
6908 %memval1  = load i32* %ptr      <i>; yields {i32}:memval1 = F0</i>
6909 </pre>
6910
6911 </div>
6912
6913 <!-- _______________________________________________________________________ -->
6914 <div class="doc_subsubsection">
6915   <a name="int_atomic_load_max">'<tt>llvm.atomic.load.max.*</tt>' Intrinsic</a><br>
6916   <a name="int_atomic_load_min">'<tt>llvm.atomic.load.min.*</tt>' Intrinsic</a><br>
6917   <a name="int_atomic_load_umax">'<tt>llvm.atomic.load.umax.*</tt>' Intrinsic</a><br>
6918   <a name="int_atomic_load_umin">'<tt>llvm.atomic.load.umin.*</tt>' Intrinsic</a><br>
6919 </div>
6920
6921 <div class="doc_text">
6922
6923 <h5>Syntax:</h5>
6924 <p>These are overloaded intrinsics. You can use <tt>llvm.atomic.load_max</tt>,
6925    <tt>llvm.atomic.load_min</tt>, <tt>llvm.atomic.load_umax</tt>, and
6926    <tt>llvm.atomic.load_umin</tt> on any integer bit width and for different
6927    address spaces. Not all targets support all bit widths however.</p>
6928
6929 <pre>
6930   declare i8 @llvm.atomic.load.max.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
6931   declare i16 @llvm.atomic.load.max.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
6932   declare i32 @llvm.atomic.load.max.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
6933   declare i64 @llvm.atomic.load.max.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
6934 </pre>
6935
6936 <pre>
6937   declare i8 @llvm.atomic.load.min.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
6938   declare i16 @llvm.atomic.load.min.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
6939   declare i32 @llvm.atomic.load.min.i32..p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
6940   declare i64 @llvm.atomic.load.min.i64..p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
6941 </pre>
6942
6943 <pre>
6944   declare i8 @llvm.atomic.load.umax.i8.p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
6945   declare i16 @llvm.atomic.load.umax.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
6946   declare i32 @llvm.atomic.load.umax.i32.p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
6947   declare i64 @llvm.atomic.load.umax.i64.p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
6948 </pre>
6949
6950 <pre>
6951   declare i8 @llvm.atomic.load.umin.i8..p0i8( i8* &lt;ptr&gt;, i8 &lt;delta&gt; )
6952   declare i16 @llvm.atomic.load.umin.i16.p0i16( i16* &lt;ptr&gt;, i16 &lt;delta&gt; )
6953   declare i32 @llvm.atomic.load.umin.i32..p0i32( i32* &lt;ptr&gt;, i32 &lt;delta&gt; )
6954   declare i64 @llvm.atomic.load.umin.i64..p0i64( i64* &lt;ptr&gt;, i64 &lt;delta&gt; )
6955 </pre>
6956
6957 <h5>Overview:</h5>
6958 <p>These intrinsics takes the signed or unsigned minimum or maximum of
6959    <tt>delta</tt> and the value stored in memory at <tt>ptr</tt>. It yields the
6960    original value at <tt>ptr</tt>.</p>
6961
6962 <h5>Arguments:</h5>
6963 <p>These intrinsics take two arguments, the first a pointer to an integer value
6964    and the second an integer value. The result is also an integer value. These
6965    integer types can have any bit width, but they must all have the same bit
6966    width. The targets may only lower integer representations they support.</p>
6967
6968 <h5>Semantics:</h5>
6969 <p>These intrinsics does a series of operations atomically. They first load the
6970    value stored at <tt>ptr</tt>. They then do the signed or unsigned min or
6971    max <tt>delta</tt> and the value, store the result to <tt>ptr</tt>. They
6972    yield the original value stored at <tt>ptr</tt>.</p>
6973
6974 <h5>Examples:</h5>
6975 <pre>
6976 %mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
6977 %ptr      = bitcast i8* %mallocP to i32*
6978             store i32 7, %ptr
6979 %result0  = call i32 @llvm.atomic.load.min.i32.p0i32( i32* %ptr, i32 -2 )
6980                                 <i>; yields {i32}:result0 = 7</i>
6981 %result1  = call i32 @llvm.atomic.load.max.i32.p0i32( i32* %ptr, i32 8 )
6982                                 <i>; yields {i32}:result1 = -2</i>
6983 %result2  = call i32 @llvm.atomic.load.umin.i32.p0i32( i32* %ptr, i32 10 )
6984                                 <i>; yields {i32}:result2 = 8</i>
6985 %result3  = call i32 @llvm.atomic.load.umax.i32.p0i32( i32* %ptr, i32 30 )
6986                                 <i>; yields {i32}:result3 = 8</i>
6987 %memval1  = load i32* %ptr      <i>; yields {i32}:memval1 = 30</i>
6988 </pre>
6989
6990 </div>
6991
6992
6993 <!-- ======================================================================= -->
6994 <div class="doc_subsection">
6995   <a name="int_memorymarkers">Memory Use Markers</a>
6996 </div>
6997
6998 <div class="doc_text">
6999
7000 <p>This class of intrinsics exists to information about the lifetime of memory
7001    objects and ranges where variables are immutable.</p>
7002
7003 </div>
7004
7005 <!-- _______________________________________________________________________ -->
7006 <div class="doc_subsubsection">
7007   <a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a>
7008 </div>
7009
7010 <div class="doc_text">
7011
7012 <h5>Syntax:</h5>
7013 <pre>
7014   declare void @llvm.lifetime.start(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
7015 </pre>
7016
7017 <h5>Overview:</h5>
7018 <p>The '<tt>llvm.lifetime.start</tt>' intrinsic specifies the start of a memory
7019    object's lifetime.</p>
7020
7021 <h5>Arguments:</h5>
7022 <p>The first argument is a constant integer representing the size of the
7023    object, or -1 if it is variable sized.  The second argument is a pointer to
7024    the object.</p>
7025
7026 <h5>Semantics:</h5>
7027 <p>This intrinsic indicates that before this point in the code, the value of the
7028    memory pointed to by <tt>ptr</tt> is dead.  This means that it is known to
7029    never be used and has an undefined value.  A load from the pointer that
7030    precedes this intrinsic can be replaced with
7031    <tt>'<a href="#undefvalues">undef</a>'</tt>.</p>
7032
7033 </div>
7034
7035 <!-- _______________________________________________________________________ -->
7036 <div class="doc_subsubsection">
7037   <a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a>
7038 </div>
7039
7040 <div class="doc_text">
7041
7042 <h5>Syntax:</h5>
7043 <pre>
7044   declare void @llvm.lifetime.end(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
7045 </pre>
7046
7047 <h5>Overview:</h5>
7048 <p>The '<tt>llvm.lifetime.end</tt>' intrinsic specifies the end of a memory
7049    object's lifetime.</p>
7050
7051 <h5>Arguments:</h5>
7052 <p>The first argument is a constant integer representing the size of the
7053    object, or -1 if it is variable sized.  The second argument is a pointer to
7054    the object.</p>
7055
7056 <h5>Semantics:</h5>
7057 <p>This intrinsic indicates that after this point in the code, the value of the
7058    memory pointed to by <tt>ptr</tt> is dead.  This means that it is known to
7059    never be used and has an undefined value.  Any stores into the memory object
7060    following this intrinsic may be removed as dead.
7061
7062 </div>
7063
7064 <!-- _______________________________________________________________________ -->
7065 <div class="doc_subsubsection">
7066   <a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a>
7067 </div>
7068
7069 <div class="doc_text">
7070
7071 <h5>Syntax:</h5>
7072 <pre>
7073   declare {}* @llvm.invariant.start(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;) readonly
7074 </pre>
7075
7076 <h5>Overview:</h5>
7077 <p>The '<tt>llvm.invariant.start</tt>' intrinsic specifies that the contents of
7078    a memory object will not change.</p>
7079
7080 <h5>Arguments:</h5>
7081 <p>The first argument is a constant integer representing the size of the
7082    object, or -1 if it is variable sized.  The second argument is a pointer to
7083    the object.</p>
7084
7085 <h5>Semantics:</h5>
7086 <p>This intrinsic indicates that until an <tt>llvm.invariant.end</tt> that uses
7087    the return value, the referenced memory location is constant and
7088    unchanging.</p>
7089
7090 </div>
7091
7092 <!-- _______________________________________________________________________ -->
7093 <div class="doc_subsubsection">
7094   <a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a>
7095 </div>
7096
7097 <div class="doc_text">
7098
7099 <h5>Syntax:</h5>
7100 <pre>
7101   declare void @llvm.invariant.end({}* &lt;start&gt;, i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
7102 </pre>
7103
7104 <h5>Overview:</h5>
7105 <p>The '<tt>llvm.invariant.end</tt>' intrinsic specifies that the contents of
7106    a memory object are mutable.</p>
7107
7108 <h5>Arguments:</h5>
7109 <p>The first argument is the matching <tt>llvm.invariant.start</tt> intrinsic.
7110    The second argument is a constant integer representing the size of the
7111    object, or -1 if it is variable sized and the third argument is a pointer
7112    to the object.</p>
7113
7114 <h5>Semantics:</h5>
7115 <p>This intrinsic indicates that the memory is mutable again.</p>
7116
7117 </div>
7118
7119 <!-- ======================================================================= -->
7120 <div class="doc_subsection">
7121   <a name="int_general">General Intrinsics</a>
7122 </div>
7123
7124 <div class="doc_text">
7125
7126 <p>This class of intrinsics is designed to be generic and has no specific
7127    purpose.</p>
7128
7129 </div>
7130
7131 <!-- _______________________________________________________________________ -->
7132 <div class="doc_subsubsection">
7133   <a name="int_var_annotation">'<tt>llvm.var.annotation</tt>' Intrinsic</a>
7134 </div>
7135
7136 <div class="doc_text">
7137
7138 <h5>Syntax:</h5>
7139 <pre>
7140   declare void @llvm.var.annotation(i8* &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7141 </pre>
7142
7143 <h5>Overview:</h5>
7144 <p>The '<tt>llvm.var.annotation</tt>' intrinsic.</p>
7145
7146 <h5>Arguments:</h5>
7147 <p>The first argument is a pointer to a value, the second is a pointer to a
7148    global string, the third is a pointer to a global string which is the source
7149    file name, and the last argument is the line number.</p>
7150
7151 <h5>Semantics:</h5>
7152 <p>This intrinsic allows annotation of local variables with arbitrary strings.
7153    This can be useful for special purpose optimizations that want to look for
7154    these annotations.  These have no other defined use, they are ignored by code
7155    generation and optimization.</p>
7156
7157 </div>
7158
7159 <!-- _______________________________________________________________________ -->
7160 <div class="doc_subsubsection">
7161   <a name="int_annotation">'<tt>llvm.annotation.*</tt>' Intrinsic</a>
7162 </div>
7163
7164 <div class="doc_text">
7165
7166 <h5>Syntax:</h5>
7167 <p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on
7168    any integer bit width.</p>
7169
7170 <pre>
7171   declare i8 @llvm.annotation.i8(i8 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7172   declare i16 @llvm.annotation.i16(i16 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7173   declare i32 @llvm.annotation.i32(i32 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7174   declare i64 @llvm.annotation.i64(i64 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7175   declare i256 @llvm.annotation.i256(i256 &lt;val&gt;, i8* &lt;str&gt;, i8* &lt;str&gt;, i32  &lt;int&gt; )
7176 </pre>
7177
7178 <h5>Overview:</h5>
7179 <p>The '<tt>llvm.annotation</tt>' intrinsic.</p>
7180
7181 <h5>Arguments:</h5>
7182 <p>The first argument is an integer value (result of some expression), the
7183    second is a pointer to a global string, the third is a pointer to a global
7184    string which is the source file name, and the last argument is the line
7185    number.  It returns the value of the first argument.</p>
7186
7187 <h5>Semantics:</h5>
7188 <p>This intrinsic allows annotations to be put on arbitrary expressions with
7189    arbitrary strings.  This can be useful for special purpose optimizations that
7190    want to look for these annotations.  These have no other defined use, they
7191    are ignored by code generation and optimization.</p>
7192
7193 </div>
7194
7195 <!-- _______________________________________________________________________ -->
7196 <div class="doc_subsubsection">
7197   <a name="int_trap">'<tt>llvm.trap</tt>' Intrinsic</a>
7198 </div>
7199
7200 <div class="doc_text">
7201
7202 <h5>Syntax:</h5>
7203 <pre>
7204   declare void @llvm.trap()
7205 </pre>
7206
7207 <h5>Overview:</h5>
7208 <p>The '<tt>llvm.trap</tt>' intrinsic.</p>
7209
7210 <h5>Arguments:</h5>
7211 <p>None.</p>
7212
7213 <h5>Semantics:</h5>
7214 <p>This intrinsics is lowered to the target dependent trap instruction. If the
7215    target does not have a trap instruction, this intrinsic will be lowered to
7216    the call of the <tt>abort()</tt> function.</p>
7217
7218 </div>
7219
7220 <!-- _______________________________________________________________________ -->
7221 <div class="doc_subsubsection">
7222   <a name="int_stackprotector">'<tt>llvm.stackprotector</tt>' Intrinsic</a>
7223 </div>
7224
7225 <div class="doc_text">
7226
7227 <h5>Syntax:</h5>
7228 <pre>
7229   declare void @llvm.stackprotector( i8* &lt;guard&gt;, i8** &lt;slot&gt; )
7230 </pre>
7231
7232 <h5>Overview:</h5>
7233 <p>The <tt>llvm.stackprotector</tt> intrinsic takes the <tt>guard</tt> and
7234    stores it onto the stack at <tt>slot</tt>. The stack slot is adjusted to
7235    ensure that it is placed on the stack before local variables.</p>
7236
7237 <h5>Arguments:</h5>
7238 <p>The <tt>llvm.stackprotector</tt> intrinsic requires two pointer
7239    arguments. The first argument is the value loaded from the stack
7240    guard <tt>@__stack_chk_guard</tt>. The second variable is an <tt>alloca</tt>
7241    that has enough space to hold the value of the guard.</p>
7242
7243 <h5>Semantics:</h5>
7244 <p>This intrinsic causes the prologue/epilogue inserter to force the position of
7245    the <tt>AllocaInst</tt> stack slot to be before local variables on the
7246    stack. This is to ensure that if a local variable on the stack is
7247    overwritten, it will destroy the value of the guard. When the function exits,
7248    the guard on the stack is checked against the original guard. If they're
7249    different, then the program aborts by calling the <tt>__stack_chk_fail()</tt>
7250    function.</p>
7251
7252 </div>
7253
7254 <!-- _______________________________________________________________________ -->
7255 <div class="doc_subsubsection">
7256   <a name="int_objectsize">'<tt>llvm.objectsize</tt>' Intrinsic</a>
7257 </div>
7258
7259 <div class="doc_text">
7260
7261 <h5>Syntax:</h5>
7262 <pre>
7263   declare i32 @llvm.objectsize.i32( i8* &lt;object&gt;, i1 &lt;type&gt; )
7264   declare i64 @llvm.objectsize.i64( i8* &lt;object&gt;, i1 &lt;type&gt; )
7265 </pre>
7266
7267 <h5>Overview:</h5>
7268 <p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information
7269    to the optimizers to either discover at compile time either a) when an
7270    operation like memcpy will either overflow a buffer that corresponds to
7271    an object, or b) to determine that a runtime check for overflow isn't
7272    necessary. An object in this context means an allocation of a
7273    specific class, structure, array, or other object.</p>
7274
7275 <h5>Arguments:</h5>
7276 <p>The <tt>llvm.objectsize</tt> intrinsic takes two arguments.  The first
7277    argument is a pointer to or into the <tt>object</tt>. The second argument
7278    is a boolean 0 or 1.  This argument determines whether you want the
7279    maximum (0) or minimum (1) bytes remaining.  This needs to be a literal 0 or
7280    1, variables are not allowed.</p>
7281
7282 <h5>Semantics:</h5>
7283 <p>The <tt>llvm.objectsize</tt> intrinsic is lowered to either a constant
7284    representing the size of the object concerned or <tt>i32/i64 -1 or 0</tt>
7285    (depending on the <tt>type</tt> argument if the size cannot be determined
7286    at compile time.</p>
7287
7288 </div>
7289
7290 <!-- *********************************************************************** -->
7291 <hr>
7292 <address>
7293   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
7294   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
7295   <a href="http://validator.w3.org/check/referer"><img
7296   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
7297
7298   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
7299   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
7300   Last modified: $Date$
7301 </address>
7302
7303 </body>
7304 </html>