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