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