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