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