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 <a href="#t_integral">integral</a> or
3143 <a href="#t_pointer">pointer</a> typed. They must also be identical types.</p>
3144 <h5>Semantics:</h5>
3145 <p>The '<tt>icmp</tt>' compares <tt>var1</tt> and <tt>var2</tt> according to
3146 the condition code given as <tt>cond</tt>. The comparison performed always
3147 yields a <a href="#t_bool">bool</a> result, as follows:
3148 <ol>
3149   <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
3150   <tt>false</tt> otherwise. No sign interpretation is necessary or performed.
3151   </li>
3152   <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
3153   <tt>false</tt> otherwise. No sign interpretation is necessary or performed.
3154   <li><tt>ugt</tt>: interprets the operands as unsigned values and yields
3155   <tt>true</tt> if <tt>var1</tt> is greater than <tt>var2</tt>.</li>
3156   <li><tt>uge</tt>: interprets the operands as unsigned values and yields
3157   <tt>true</tt> if <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3158   <li><tt>ult</tt>: interprets the operands as unsigned values and yields
3159   <tt>true</tt> if <tt>var1</tt> is less than <tt>var2</tt>.</li>
3160   <li><tt>ule</tt>: interprets the operands as unsigned values and yields
3161   <tt>true</tt> if <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3162   <li><tt>sgt</tt>: interprets the operands as signed values and yields
3163   <tt>true</tt> if <tt>var1</tt> is greater than <tt>var2</tt>.</li>
3164   <li><tt>sge</tt>: interprets the operands as signed values and yields
3165   <tt>true</tt> if <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3166   <li><tt>slt</tt>: interprets the operands as signed values and yields
3167   <tt>true</tt> if <tt>var1</tt> is less than <tt>var2</tt>.</li>
3168   <li><tt>sle</tt>: interprets the operands as signed values and yields
3169   <tt>true</tt> if <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3170   </li>
3171 </ol>
3172 <p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer
3173 values are treated as integers and then compared.</p>
3174 <p>If the operands are <a href="#t_packed">packed</a> typed, the elements of
3175 the vector are compared in turn and the predicate must hold for all
3176 elements.</p>
3177
3178 <h5>Example:</h5>
3179 <pre>  &lt;result&gt; = icmp eq i32 4, 5          <i>; yields: result=false</i>
3180   &lt;result&gt; = icmp ne float* %X, %X     <i>; yields: result=false</i>
3181   &lt;result&gt; = icmp ult i16  4, 5        <i>; yields: result=true</i>
3182   &lt;result&gt; = icmp sgt i16  4, 5        <i>; yields: result=false</i>
3183   &lt;result&gt; = icmp ule i16 -4, 5        <i>; yields: result=false</i>
3184   &lt;result&gt; = icmp sge i16  4, 5        <i>; yields: result=false</i>
3185 </pre>
3186 </div>
3187
3188 <!-- _______________________________________________________________________ -->
3189 <div class="doc_subsubsection"><a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
3190 </div>
3191 <div class="doc_text">
3192 <h5>Syntax:</h5>
3193 <pre>  &lt;result&gt; = fcmp &lt;cond&gt; &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
3194 </pre>
3195 <h5>Overview:</h5>
3196 <p>The '<tt>fcmp</tt>' instruction returns a boolean value based on comparison
3197 of its floating point operands.</p>
3198 <h5>Arguments:</h5>
3199 <p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is
3200 the condition code which indicates the kind of comparison to perform. It is not
3201 a value, just a keyword. The possibilities for the condition code are:
3202 <ol>
3203   <li><tt>false</tt>: no comparison, always returns false</li>
3204   <li><tt>oeq</tt>: ordered and equal</li>
3205   <li><tt>ogt</tt>: ordered and greater than </li>
3206   <li><tt>oge</tt>: ordered and greater than or equal</li>
3207   <li><tt>olt</tt>: ordered and less than </li>
3208   <li><tt>ole</tt>: ordered and less than or equal</li>
3209   <li><tt>one</tt>: ordered and not equal</li>
3210   <li><tt>ord</tt>: ordered (no nans)</li>
3211   <li><tt>ueq</tt>: unordered or equal</li>
3212   <li><tt>ugt</tt>: unordered or greater than </li>
3213   <li><tt>uge</tt>: unordered or greater than or equal</li>
3214   <li><tt>ult</tt>: unordered or less than </li>
3215   <li><tt>ule</tt>: unordered or less than or equal</li>
3216   <li><tt>une</tt>: unordered or not equal</li>
3217   <li><tt>uno</tt>: unordered (either nans)</li>
3218   <li><tt>true</tt>: no comparison, always returns true</li>
3219 </ol>
3220 <p>In the preceding, <i>ordered</i> means that neither operand is a QNAN while
3221 <i>unordered</i> means that either operand may be a QNAN.</p>
3222 <p>The <tt>val1</tt> and <tt>val2</tt> arguments must be
3223 <a href="#t_floating">floating point</a> typed.  They must have identical
3224 types.</p>
3225 <p>In the foregoing, <i>ordered</i> means that neither operand is a QNAN and
3226 <i>unordered</i> means that either operand is a QNAN.</p>
3227 <h5>Semantics:</h5>
3228 <p>The '<tt>fcmp</tt>' compares <tt>var1</tt> and <tt>var2</tt> according to
3229 the condition code given as <tt>cond</tt>. The comparison performed always
3230 yields a <a href="#t_bool">bool</a> result, as follows:
3231 <ol>
3232   <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
3233   <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3234   <tt>var1</tt> is equal to <tt>var2</tt>.</li>
3235   <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3236   <tt>var1</tt> is greather than <tt>var2</tt>.</li>
3237   <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3238   <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3239   <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3240   <tt>var1</tt> is less than <tt>var2</tt>.</li>
3241   <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3242   <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3243   <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3244   <tt>var1</tt> is not equal to <tt>var2</tt>.</li>
3245   <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
3246   <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
3247   <tt>var1</tt> is equal to <tt>var2</tt>.</li>
3248   <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
3249   <tt>var1</tt> is greater than <tt>var2</tt>.</li>
3250   <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
3251   <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3252   <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
3253   <tt>var1</tt> is less than <tt>var2</tt>.</li>
3254   <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
3255   <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3256   <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
3257   <tt>var1</tt> is not equal to <tt>var2</tt>.</li>
3258   <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
3259   <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li>
3260 </ol>
3261 <p>If the operands are <a href="#t_packed">packed</a> typed, the elements of
3262 the vector are compared in turn and the predicate must hold for all elements.
3263 </p>
3264
3265 <h5>Example:</h5>
3266 <pre>  &lt;result&gt; = fcmp oeq float 4.0, 5.0    <i>; yields: result=false</i>
3267   &lt;result&gt; = icmp one float 4.0, 5.0    <i>; yields: result=true</i>
3268   &lt;result&gt; = icmp olt float 4.0, 5.0    <i>; yields: result=true</i>
3269   &lt;result&gt; = icmp ueq double 1.0, 2.0   <i>; yields: result=false</i>
3270 </pre>
3271 </div>
3272
3273 <!-- _______________________________________________________________________ -->
3274 <div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>'
3275 Instruction</a> </div>
3276 <div class="doc_text">
3277 <h5>Syntax:</h5>
3278 <pre>  &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...<br></pre>
3279 <h5>Overview:</h5>
3280 <p>The '<tt>phi</tt>' instruction is used to implement the &#966; node in
3281 the SSA graph representing the function.</p>
3282 <h5>Arguments:</h5>
3283 <p>The type of the incoming values are specified with the first type
3284 field. After this, the '<tt>phi</tt>' instruction takes a list of pairs
3285 as arguments, with one pair for each predecessor basic block of the
3286 current block.  Only values of <a href="#t_firstclass">first class</a>
3287 type may be used as the value arguments to the PHI node.  Only labels
3288 may be used as the label arguments.</p>
3289 <p>There must be no non-phi instructions between the start of a basic
3290 block and the PHI instructions: i.e. PHI instructions must be first in
3291 a basic block.</p>
3292 <h5>Semantics:</h5>
3293 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the
3294 value specified by the parameter, depending on which basic block we
3295 came from in the last <a href="#terminators">terminator</a> instruction.</p>
3296 <h5>Example:</h5>
3297 <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>
3298 </div>
3299
3300 <!-- _______________________________________________________________________ -->
3301 <div class="doc_subsubsection">
3302    <a name="i_select">'<tt>select</tt>' Instruction</a>
3303 </div>
3304
3305 <div class="doc_text">
3306
3307 <h5>Syntax:</h5>
3308
3309 <pre>
3310   &lt;result&gt; = select bool &lt;cond&gt;, &lt;ty&gt; &lt;val1&gt;, &lt;ty&gt; &lt;val2&gt;             <i>; yields ty</i>
3311 </pre>
3312
3313 <h5>Overview:</h5>
3314
3315 <p>
3316 The '<tt>select</tt>' instruction is used to choose one value based on a
3317 condition, without branching.
3318 </p>
3319
3320
3321 <h5>Arguments:</h5>
3322
3323 <p>
3324 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.
3325 </p>
3326
3327 <h5>Semantics:</h5>
3328
3329 <p>
3330 If the boolean condition evaluates to true, the instruction returns the first
3331 value argument; otherwise, it returns the second value argument.
3332 </p>
3333
3334 <h5>Example:</h5>
3335
3336 <pre>
3337   %X = select bool true, i8 17, i8 42          <i>; yields i8:17</i>
3338 </pre>
3339 </div>
3340
3341
3342 <!-- _______________________________________________________________________ -->
3343 <div class="doc_subsubsection">
3344   <a name="i_call">'<tt>call</tt>' Instruction</a>
3345 </div>
3346
3347 <div class="doc_text">
3348
3349 <h5>Syntax:</h5>
3350 <pre>
3351   &lt;result&gt; = [tail] call [<a href="#callingconv">cconv</a>] &lt;ty&gt;* &lt;fnptrval&gt;(&lt;param list&gt;)
3352 </pre>
3353
3354 <h5>Overview:</h5>
3355
3356 <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
3357
3358 <h5>Arguments:</h5>
3359
3360 <p>This instruction requires several arguments:</p>
3361
3362 <ol>
3363   <li>
3364     <p>The optional "tail" marker indicates whether the callee function accesses
3365     any allocas or varargs in the caller.  If the "tail" marker is present, the
3366     function call is eligible for tail call optimization.  Note that calls may
3367     be marked "tail" even if they do not occur before a <a
3368     href="#i_ret"><tt>ret</tt></a> instruction.
3369   </li>
3370   <li>
3371     <p>The optional "cconv" marker indicates which <a href="callingconv">calling
3372     convention</a> the call should use.  If none is specified, the call defaults
3373     to using C calling conventions.
3374   </li>
3375   <li>
3376     <p>'<tt>ty</tt>': shall be the signature of the pointer to function value
3377     being invoked.  The argument types must match the types implied by this
3378     signature.  This type can be omitted if the function is not varargs and
3379     if the function type does not return a pointer to a function.</p>
3380   </li>
3381   <li>
3382     <p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to
3383     be invoked. In most cases, this is a direct function invocation, but
3384     indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer
3385     to function value.</p>
3386   </li>
3387   <li>
3388     <p>'<tt>function args</tt>': argument list whose types match the
3389     function signature argument types. All arguments must be of
3390     <a href="#t_firstclass">first class</a> type. If the function signature
3391     indicates the function accepts a variable number of arguments, the extra
3392     arguments can be specified.</p>
3393   </li>
3394 </ol>
3395
3396 <h5>Semantics:</h5>
3397
3398 <p>The '<tt>call</tt>' instruction is used to cause control flow to
3399 transfer to a specified function, with its incoming arguments bound to
3400 the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>'
3401 instruction in the called function, control flow continues with the
3402 instruction after the function call, and the return value of the
3403 function is bound to the result argument.  This is a simpler case of
3404 the <a href="#i_invoke">invoke</a> instruction.</p>
3405
3406 <h5>Example:</h5>
3407
3408 <pre>
3409   %retval = call i32 %test(i32 %argc)
3410   call i32(i8 *, ...) *%printf(i8 * %msg, i32 12, i8  42);
3411   %X = tail call i32 %foo()
3412   %Y = tail call <a href="#callingconv">fastcc</a> i32 %foo()
3413 </pre>
3414
3415 </div>
3416
3417 <!-- _______________________________________________________________________ -->
3418 <div class="doc_subsubsection">
3419   <a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
3420 </div>
3421
3422 <div class="doc_text">
3423
3424 <h5>Syntax:</h5>
3425
3426 <pre>
3427   &lt;resultval&gt; = va_arg &lt;va_list*&gt; &lt;arglist&gt;, &lt;argty&gt;
3428 </pre>
3429
3430 <h5>Overview:</h5>
3431
3432 <p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through
3433 the "variable argument" area of a function call.  It is used to implement the
3434 <tt>va_arg</tt> macro in C.</p>
3435
3436 <h5>Arguments:</h5>
3437
3438 <p>This instruction takes a <tt>va_list*</tt> value and the type of
3439 the argument. It returns a value of the specified argument type and
3440 increments the <tt>va_list</tt> to point to the next argument.  Again, the
3441 actual type of <tt>va_list</tt> is target specific.</p>
3442
3443 <h5>Semantics:</h5>
3444
3445 <p>The '<tt>va_arg</tt>' instruction loads an argument of the specified
3446 type from the specified <tt>va_list</tt> and causes the
3447 <tt>va_list</tt> to point to the next argument.  For more information,
3448 see the variable argument handling <a href="#int_varargs">Intrinsic
3449 Functions</a>.</p>
3450
3451 <p>It is legal for this instruction to be called in a function which does not
3452 take a variable number of arguments, for example, the <tt>vfprintf</tt>
3453 function.</p>
3454
3455 <p><tt>va_arg</tt> is an LLVM instruction instead of an <a
3456 href="#intrinsics">intrinsic function</a> because it takes a type as an
3457 argument.</p>
3458
3459 <h5>Example:</h5>
3460
3461 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
3462
3463 </div>
3464
3465 <!-- *********************************************************************** -->
3466 <div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
3467 <!-- *********************************************************************** -->
3468
3469 <div class="doc_text">
3470
3471 <p>LLVM supports the notion of an "intrinsic function".  These functions have
3472 well known names and semantics and are required to follow certain
3473 restrictions. Overall, these instructions represent an extension mechanism for
3474 the LLVM language that does not require changing all of the transformations in
3475 LLVM to add to the language (or the bytecode reader/writer, the parser,
3476 etc...).</p>
3477
3478 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
3479 prefix is reserved in LLVM for intrinsic names; thus, functions may not be named
3480 this.  Intrinsic functions must always be external functions: you cannot define
3481 the body of intrinsic functions.  Intrinsic functions may only be used in call
3482 or invoke instructions: it is illegal to take the address of an intrinsic
3483 function.  Additionally, because intrinsic functions are part of the LLVM
3484 language, it is required that they all be documented here if any are added.</p>
3485
3486
3487 <p>To learn how to add an intrinsic function, please see the <a
3488 href="ExtendingLLVM.html">Extending LLVM Guide</a>.
3489 </p>
3490
3491 </div>
3492
3493 <!-- ======================================================================= -->
3494 <div class="doc_subsection">
3495   <a name="int_varargs">Variable Argument Handling Intrinsics</a>
3496 </div>
3497
3498 <div class="doc_text">
3499
3500 <p>Variable argument support is defined in LLVM with the <a
3501  href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
3502 intrinsic functions.  These functions are related to the similarly
3503 named macros defined in the <tt>&lt;stdarg.h&gt;</tt> header file.</p>
3504
3505 <p>All of these functions operate on arguments that use a
3506 target-specific value type "<tt>va_list</tt>".  The LLVM assembly
3507 language reference manual does not define what this type is, so all
3508 transformations should be prepared to handle intrinsics with any type
3509 used.</p>
3510
3511 <p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a>
3512 instruction and the variable argument handling intrinsic functions are
3513 used.</p>
3514
3515 <pre>
3516 define i32 %test(i32 %X, ...) {
3517   ; Initialize variable argument processing
3518   %ap = alloca i8 *
3519   call void %<a href="#i_va_start">llvm.va_start</a>(i8 ** %ap)
3520
3521   ; Read a single integer argument
3522   %tmp = va_arg i8 ** %ap, i32
3523
3524   ; Demonstrate usage of llvm.va_copy and llvm.va_end
3525   %aq = alloca i8 *
3526   call void %<a href="#i_va_copy">llvm.va_copy</a>(i8 ** %aq, i8 ** %ap)
3527   call void %<a href="#i_va_end">llvm.va_end</a>(i8 ** %aq)
3528
3529   ; Stop processing of arguments.
3530   call void %<a href="#i_va_end">llvm.va_end</a>(i8 ** %ap)
3531   ret i32 %tmp
3532 }
3533 </pre>
3534 </div>
3535
3536 <!-- _______________________________________________________________________ -->
3537 <div class="doc_subsubsection">
3538   <a name="i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
3539 </div>
3540
3541
3542 <div class="doc_text">
3543 <h5>Syntax:</h5>
3544 <pre>  declare void %llvm.va_start(&lt;va_list&gt;* &lt;arglist&gt;)<br></pre>
3545 <h5>Overview:</h5>
3546 <P>The '<tt>llvm.va_start</tt>' intrinsic initializes
3547 <tt>*&lt;arglist&gt;</tt> for subsequent use by <tt><a
3548 href="#i_va_arg">va_arg</a></tt>.</p>
3549
3550 <h5>Arguments:</h5>
3551
3552 <P>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
3553
3554 <h5>Semantics:</h5>
3555
3556 <P>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
3557 macro available in C.  In a target-dependent way, it initializes the
3558 <tt>va_list</tt> element the argument points to, so that the next call to
3559 <tt>va_arg</tt> will produce the first variable argument passed to the function.
3560 Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the
3561 last argument of the function, the compiler can figure that out.</p>
3562
3563 </div>
3564
3565 <!-- _______________________________________________________________________ -->
3566 <div class="doc_subsubsection">
3567  <a name="i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
3568 </div>
3569
3570 <div class="doc_text">
3571 <h5>Syntax:</h5>
3572 <pre>  declare void %llvm.va_end(&lt;va_list*&gt; &lt;arglist&gt;)<br></pre>
3573 <h5>Overview:</h5>
3574 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>&lt;arglist&gt;</tt>
3575 which has been initialized previously with <tt><a href="#i_va_start">llvm.va_start</a></tt>
3576 or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
3577 <h5>Arguments:</h5>
3578 <p>The argument is a <tt>va_list</tt> to destroy.</p>
3579 <h5>Semantics:</h5>
3580 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
3581 macro available in C.  In a target-dependent way, it destroys the <tt>va_list</tt>.
3582 Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
3583  href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly
3584 with calls to <tt>llvm.va_end</tt>.</p>
3585 </div>
3586
3587 <!-- _______________________________________________________________________ -->
3588 <div class="doc_subsubsection">
3589   <a name="i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
3590 </div>
3591
3592 <div class="doc_text">
3593
3594 <h5>Syntax:</h5>
3595
3596 <pre>
3597   declare void %llvm.va_copy(&lt;va_list&gt;* &lt;destarglist&gt;,
3598                                           &lt;va_list&gt;* &lt;srcarglist&gt;)
3599 </pre>
3600
3601 <h5>Overview:</h5>
3602
3603 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position from
3604 the source argument list to the destination argument list.</p>
3605
3606 <h5>Arguments:</h5>
3607
3608 <p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
3609 The second argument is a pointer to a <tt>va_list</tt> element to copy from.</p>
3610
3611
3612 <h5>Semantics:</h5>
3613
3614 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> macro
3615 available in C.  In a target-dependent way, it copies the source
3616 <tt>va_list</tt> element into the destination list.  This intrinsic is necessary
3617 because the <tt><a href="i_va_begin">llvm.va_begin</a></tt> intrinsic may be
3618 arbitrarily complex and require memory allocation, for example.</p>
3619
3620 </div>
3621
3622 <!-- ======================================================================= -->
3623 <div class="doc_subsection">
3624   <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
3625 </div>
3626
3627 <div class="doc_text">
3628
3629 <p>
3630 LLVM support for <a href="GarbageCollection.html">Accurate Garbage
3631 Collection</a> requires the implementation and generation of these intrinsics.
3632 These intrinsics allow identification of <a href="#i_gcroot">GC roots on the
3633 stack</a>, as well as garbage collector implementations that require <a
3634 href="#i_gcread">read</a> and <a href="#i_gcwrite">write</a> barriers.
3635 Front-ends for type-safe garbage collected languages should generate these
3636 intrinsics to make use of the LLVM garbage collectors.  For more details, see <a
3637 href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>.
3638 </p>
3639 </div>
3640
3641 <!-- _______________________________________________________________________ -->
3642 <div class="doc_subsubsection">
3643   <a name="i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
3644 </div>
3645
3646 <div class="doc_text">
3647
3648 <h5>Syntax:</h5>
3649
3650 <pre>
3651   declare void %llvm.gcroot(&lt;ty&gt;** %ptrloc, &lt;ty2&gt;* %metadata)
3652 </pre>
3653
3654 <h5>Overview:</h5>
3655
3656 <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
3657 the code generator, and allows some metadata to be associated with it.</p>
3658
3659 <h5>Arguments:</h5>
3660
3661 <p>The first argument specifies the address of a stack object that contains the
3662 root pointer.  The second pointer (which must be either a constant or a global
3663 value address) contains the meta-data to be associated with the root.</p>
3664
3665 <h5>Semantics:</h5>
3666
3667 <p>At runtime, a call to this intrinsics stores a null pointer into the "ptrloc"
3668 location.  At compile-time, the code generator generates information to allow
3669 the runtime to find the pointer at GC safe points.
3670 </p>
3671
3672 </div>
3673
3674
3675 <!-- _______________________________________________________________________ -->
3676 <div class="doc_subsubsection">
3677   <a name="i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
3678 </div>
3679
3680 <div class="doc_text">
3681
3682 <h5>Syntax:</h5>
3683
3684 <pre>
3685   declare i8 * %llvm.gcread(i8 * %ObjPtr, i8 ** %Ptr)
3686 </pre>
3687
3688 <h5>Overview:</h5>
3689
3690 <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
3691 locations, allowing garbage collector implementations that require read
3692 barriers.</p>
3693
3694 <h5>Arguments:</h5>
3695
3696 <p>The second argument is the address to read from, which should be an address
3697 allocated from the garbage collector.  The first object is a pointer to the
3698 start of the referenced object, if needed by the language runtime (otherwise
3699 null).</p>
3700
3701 <h5>Semantics:</h5>
3702
3703 <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
3704 instruction, but may be replaced with substantially more complex code by the
3705 garbage collector runtime, as needed.</p>
3706
3707 </div>
3708
3709
3710 <!-- _______________________________________________________________________ -->
3711 <div class="doc_subsubsection">
3712   <a name="i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
3713 </div>
3714
3715 <div class="doc_text">
3716
3717 <h5>Syntax:</h5>
3718
3719 <pre>
3720   declare void %llvm.gcwrite(i8 * %P1, i8 * %Obj, i8 ** %P2)
3721 </pre>
3722
3723 <h5>Overview:</h5>
3724
3725 <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
3726 locations, allowing garbage collector implementations that require write
3727 barriers (such as generational or reference counting collectors).</p>
3728
3729 <h5>Arguments:</h5>
3730
3731 <p>The first argument is the reference to store, the second is the start of the
3732 object to store it to, and the third is the address of the field of Obj to
3733 store to.  If the runtime does not require a pointer to the object, Obj may be
3734 null.</p>
3735
3736 <h5>Semantics:</h5>
3737
3738 <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
3739 instruction, but may be replaced with substantially more complex code by the
3740 garbage collector runtime, as needed.</p>
3741
3742 </div>
3743
3744
3745
3746 <!-- ======================================================================= -->
3747 <div class="doc_subsection">
3748   <a name="int_codegen">Code Generator Intrinsics</a>
3749 </div>
3750
3751 <div class="doc_text">
3752 <p>
3753 These intrinsics are provided by LLVM to expose special features that may only
3754 be implemented with code generator support.
3755 </p>
3756
3757 </div>
3758
3759 <!-- _______________________________________________________________________ -->
3760 <div class="doc_subsubsection">
3761   <a name="i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
3762 </div>
3763
3764 <div class="doc_text">
3765
3766 <h5>Syntax:</h5>
3767 <pre>
3768   declare i8  *%llvm.returnaddress(i32 &lt;level&gt;)
3769 </pre>
3770
3771 <h5>Overview:</h5>
3772
3773 <p>
3774 The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a
3775 target-specific value indicating the return address of the current function
3776 or one of its callers.
3777 </p>
3778
3779 <h5>Arguments:</h5>
3780
3781 <p>
3782 The argument to this intrinsic indicates which function to return the address
3783 for.  Zero indicates the calling function, one indicates its caller, etc.  The
3784 argument is <b>required</b> to be a constant integer value.
3785 </p>
3786
3787 <h5>Semantics:</h5>
3788
3789 <p>
3790 The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer indicating
3791 the return address of the specified call frame, or zero if it cannot be
3792 identified.  The value returned by this intrinsic is likely to be incorrect or 0
3793 for arguments other than zero, so it should only be used for debugging purposes.
3794 </p>
3795
3796 <p>
3797 Note that calling this intrinsic does not prevent function inlining or other
3798 aggressive transformations, so the value returned may not be that of the obvious
3799 source-language caller.
3800 </p>
3801 </div>
3802
3803
3804 <!-- _______________________________________________________________________ -->
3805 <div class="doc_subsubsection">
3806   <a name="i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
3807 </div>
3808
3809 <div class="doc_text">
3810
3811 <h5>Syntax:</h5>
3812 <pre>
3813   declare i8  *%llvm.frameaddress(i32 &lt;level&gt;)
3814 </pre>
3815
3816 <h5>Overview:</h5>
3817
3818 <p>
3819 The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the
3820 target-specific frame pointer value for the specified stack frame.
3821 </p>
3822
3823 <h5>Arguments:</h5>
3824
3825 <p>
3826 The argument to this intrinsic indicates which function to return the frame
3827 pointer for.  Zero indicates the calling function, one indicates its caller,
3828 etc.  The argument is <b>required</b> to be a constant integer value.
3829 </p>
3830
3831 <h5>Semantics:</h5>
3832
3833 <p>
3834 The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer indicating
3835 the frame address of the specified call frame, or zero if it cannot be
3836 identified.  The value returned by this intrinsic is likely to be incorrect or 0
3837 for arguments other than zero, so it should only be used for debugging purposes.
3838 </p>
3839
3840 <p>
3841 Note that calling this intrinsic does not prevent function inlining or other
3842 aggressive transformations, so the value returned may not be that of the obvious
3843 source-language caller.
3844 </p>
3845 </div>
3846
3847 <!-- _______________________________________________________________________ -->
3848 <div class="doc_subsubsection">
3849   <a name="i_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
3850 </div>
3851
3852 <div class="doc_text">
3853
3854 <h5>Syntax:</h5>
3855 <pre>
3856   declare i8  *%llvm.stacksave()
3857 </pre>
3858
3859 <h5>Overview:</h5>
3860
3861 <p>
3862 The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state of
3863 the function stack, for use with <a href="#i_stackrestore">
3864 <tt>llvm.stackrestore</tt></a>.  This is useful for implementing language
3865 features like scoped automatic variable sized arrays in C99.
3866 </p>
3867
3868 <h5>Semantics:</h5>
3869
3870 <p>
3871 This intrinsic returns a opaque pointer value that can be passed to <a
3872 href="#i_stackrestore"><tt>llvm.stackrestore</tt></a>.  When an
3873 <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved from
3874 <tt>llvm.stacksave</tt>, it effectively restores the state of the stack to the
3875 state it was in when the <tt>llvm.stacksave</tt> intrinsic executed.  In
3876 practice, this pops any <a href="#i_alloca">alloca</a> blocks from the stack
3877 that were allocated after the <tt>llvm.stacksave</tt> was executed.
3878 </p>
3879
3880 </div>
3881
3882 <!-- _______________________________________________________________________ -->
3883 <div class="doc_subsubsection">
3884   <a name="i_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
3885 </div>
3886
3887 <div class="doc_text">
3888
3889 <h5>Syntax:</h5>
3890 <pre>
3891   declare void %llvm.stackrestore(i8 * %ptr)
3892 </pre>
3893
3894 <h5>Overview:</h5>
3895
3896 <p>
3897 The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of
3898 the function stack to the state it was in when the corresponding <a
3899 href="#llvm.stacksave"><tt>llvm.stacksave</tt></a> intrinsic executed.  This is
3900 useful for implementing language features like scoped automatic variable sized
3901 arrays in C99.
3902 </p>
3903
3904 <h5>Semantics:</h5>
3905
3906 <p>
3907 See the description for <a href="#i_stacksave"><tt>llvm.stacksave</tt></a>.
3908 </p>
3909
3910 </div>
3911
3912
3913 <!-- _______________________________________________________________________ -->
3914 <div class="doc_subsubsection">
3915   <a name="i_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
3916 </div>
3917
3918 <div class="doc_text">
3919
3920 <h5>Syntax:</h5>
3921 <pre>
3922   declare void %llvm.prefetch(i8  * &lt;address&gt;,
3923                                 i32 &lt;rw&gt;, i32 &lt;locality&gt;)
3924 </pre>
3925
3926 <h5>Overview:</h5>
3927
3928
3929 <p>
3930 The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to insert
3931 a prefetch instruction if supported; otherwise, it is a noop.  Prefetches have
3932 no
3933 effect on the behavior of the program but can change its performance
3934 characteristics.
3935 </p>
3936
3937 <h5>Arguments:</h5>
3938
3939 <p>
3940 <tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the specifier
3941 determining if the fetch should be for a read (0) or write (1), and
3942 <tt>locality</tt> is a temporal locality specifier ranging from (0) - no
3943 locality, to (3) - extremely local keep in cache.  The <tt>rw</tt> and
3944 <tt>locality</tt> arguments must be constant integers.
3945 </p>
3946
3947 <h5>Semantics:</h5>
3948
3949 <p>
3950 This intrinsic does not modify the behavior of the program.  In particular,
3951 prefetches cannot trap and do not produce a value.  On targets that support this
3952 intrinsic, the prefetch can provide hints to the processor cache for better
3953 performance.
3954 </p>
3955
3956 </div>
3957
3958 <!-- _______________________________________________________________________ -->
3959 <div class="doc_subsubsection">
3960   <a name="i_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
3961 </div>
3962
3963 <div class="doc_text">
3964
3965 <h5>Syntax:</h5>
3966 <pre>
3967   declare void %llvm.pcmarker( i32 &lt;id&gt; )
3968 </pre>
3969
3970 <h5>Overview:</h5>
3971
3972
3973 <p>
3974 The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program Counter
3975 (PC) in a region of
3976 code to simulators and other tools.  The method is target specific, but it is
3977 expected that the marker will use exported symbols to transmit the PC of the marker.
3978 The marker makes no guarantees that it will remain with any specific instruction
3979 after optimizations.  It is possible that the presence of a marker will inhibit
3980 optimizations.  The intended use is to be inserted after optimizations to allow
3981 correlations of simulation runs.
3982 </p>
3983
3984 <h5>Arguments:</h5>
3985
3986 <p>
3987 <tt>id</tt> is a numerical id identifying the marker.
3988 </p>
3989
3990 <h5>Semantics:</h5>
3991
3992 <p>
3993 This intrinsic does not modify the behavior of the program.  Backends that do not
3994 support this intrinisic may ignore it.
3995 </p>
3996
3997 </div>
3998
3999 <!-- _______________________________________________________________________ -->
4000 <div class="doc_subsubsection">
4001   <a name="i_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
4002 </div>
4003
4004 <div class="doc_text">
4005
4006 <h5>Syntax:</h5>
4007 <pre>
4008   declare i64 %llvm.readcyclecounter( )
4009 </pre>
4010
4011 <h5>Overview:</h5>
4012
4013
4014 <p>
4015 The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle
4016 counter register (or similar low latency, high accuracy clocks) on those targets
4017 that support it.  On X86, it should map to RDTSC.  On Alpha, it should map to RPCC.
4018 As the backing counters overflow quickly (on the order of 9 seconds on alpha), this
4019 should only be used for small timings.
4020 </p>
4021
4022 <h5>Semantics:</h5>
4023
4024 <p>
4025 When directly supported, reading the cycle counter should not modify any memory.
4026 Implementations are allowed to either return a application specific value or a
4027 system wide value.  On backends without support, this is lowered to a constant 0.
4028 </p>
4029
4030 </div>
4031
4032 <!-- ======================================================================= -->
4033 <div class="doc_subsection">
4034   <a name="int_libc">Standard C Library Intrinsics</a>
4035 </div>
4036
4037 <div class="doc_text">
4038 <p>
4039 LLVM provides intrinsics for a few important standard C library functions.
4040 These intrinsics allow source-language front-ends to pass information about the
4041 alignment of the pointer arguments to the code generator, providing opportunity
4042 for more efficient code generation.
4043 </p>
4044
4045 </div>
4046
4047 <!-- _______________________________________________________________________ -->
4048 <div class="doc_subsubsection">
4049   <a name="i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
4050 </div>
4051
4052 <div class="doc_text">
4053
4054 <h5>Syntax:</h5>
4055 <pre>
4056   declare void %llvm.memcpy.i32(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
4057                                 i32 &lt;len&gt;, i32 &lt;align&gt;)
4058   declare void %llvm.memcpy.i64(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
4059                                 i64 &lt;len&gt;, i32 &lt;align&gt;)
4060 </pre>
4061
4062 <h5>Overview:</h5>
4063
4064 <p>
4065 The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source
4066 location to the destination location.
4067 </p>
4068
4069 <p>
4070 Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
4071 intrinsics do not return a value, and takes an extra alignment argument.
4072 </p>
4073
4074 <h5>Arguments:</h5>
4075
4076 <p>
4077 The first argument is a pointer to the destination, the second is a pointer to
4078 the source.  The third argument is an integer argument
4079 specifying the number of bytes to copy, and the fourth argument is the alignment
4080 of the source and destination locations.
4081 </p>
4082
4083 <p>
4084 If the call to this intrinisic has an alignment value that is not 0 or 1, then
4085 the caller guarantees that both the source and destination pointers are aligned
4086 to that boundary.
4087 </p>
4088
4089 <h5>Semantics:</h5>
4090
4091 <p>
4092 The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source
4093 location to the destination location, which are not allowed to overlap.  It
4094 copies "len" bytes of memory over.  If the argument is known to be aligned to
4095 some boundary, this can be specified as the fourth argument, otherwise it should
4096 be set to 0 or 1.
4097 </p>
4098 </div>
4099
4100
4101 <!-- _______________________________________________________________________ -->
4102 <div class="doc_subsubsection">
4103   <a name="i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
4104 </div>
4105
4106 <div class="doc_text">
4107
4108 <h5>Syntax:</h5>
4109 <pre>
4110   declare void %llvm.memmove.i32(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
4111                                  i32 &lt;len&gt;, i32 &lt;align&gt;)
4112   declare void %llvm.memmove.i64(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
4113                                  i64 &lt;len&gt;, i32 &lt;align&gt;)
4114 </pre>
4115
4116 <h5>Overview:</h5>
4117
4118 <p>
4119 The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the source
4120 location to the destination location. It is similar to the
4121 '<tt>llvm.memcmp</tt>' intrinsic but allows the two memory locations to overlap.
4122 </p>
4123
4124 <p>
4125 Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
4126 intrinsics do not return a value, and takes an extra alignment argument.
4127 </p>
4128
4129 <h5>Arguments:</h5>
4130
4131 <p>
4132 The first argument is a pointer to the destination, the second is a pointer to
4133 the source.  The third argument is an integer argument
4134 specifying the number of bytes to copy, and the fourth argument is the alignment
4135 of the source and destination locations.
4136 </p>
4137
4138 <p>
4139 If the call to this intrinisic has an alignment value that is not 0 or 1, then
4140 the caller guarantees that the source and destination pointers are aligned to
4141 that boundary.
4142 </p>
4143
4144 <h5>Semantics:</h5>
4145
4146 <p>
4147 The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the source
4148 location to the destination location, which may overlap.  It
4149 copies "len" bytes of memory over.  If the argument is known to be aligned to
4150 some boundary, this can be specified as the fourth argument, otherwise it should
4151 be set to 0 or 1.
4152 </p>
4153 </div>
4154
4155
4156 <!-- _______________________________________________________________________ -->
4157 <div class="doc_subsubsection">
4158   <a name="i_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
4159 </div>
4160
4161 <div class="doc_text">
4162
4163 <h5>Syntax:</h5>
4164 <pre>
4165   declare void %llvm.memset.i32(i8 * &lt;dest&gt;, i8 &lt;val&gt;,
4166                                 i32 &lt;len&gt;, i32 &lt;align&gt;)
4167   declare void %llvm.memset.i64(i8 * &lt;dest&gt;, i8 &lt;val&gt;,
4168                                 i64 &lt;len&gt;, i32 &lt;align&gt;)
4169 </pre>
4170
4171 <h5>Overview:</h5>
4172
4173 <p>
4174 The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a particular
4175 byte value.
4176 </p>
4177
4178 <p>
4179 Note that, unlike the standard libc function, the <tt>llvm.memset</tt> intrinsic
4180 does not return a value, and takes an extra alignment argument.
4181 </p>
4182
4183 <h5>Arguments:</h5>
4184
4185 <p>
4186 The first argument is a pointer to the destination to fill, the second is the
4187 byte value to fill it with, the third argument is an integer
4188 argument specifying the number of bytes to fill, and the fourth argument is the
4189 known alignment of destination location.
4190 </p>
4191
4192 <p>
4193 If the call to this intrinisic has an alignment value that is not 0 or 1, then
4194 the caller guarantees that the destination pointer is aligned to that boundary.
4195 </p>
4196
4197 <h5>Semantics:</h5>
4198
4199 <p>
4200 The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting at
4201 the
4202 destination location.  If the argument is known to be aligned to some boundary,
4203 this can be specified as the fourth argument, otherwise it should be set to 0 or
4204 1.
4205 </p>
4206 </div>
4207
4208
4209 <!-- _______________________________________________________________________ -->
4210 <div class="doc_subsubsection">
4211   <a name="i_isunordered">'<tt>llvm.isunordered.*</tt>' Intrinsic</a>
4212 </div>
4213
4214 <div class="doc_text">
4215
4216 <h5>Syntax:</h5>
4217 <pre>
4218   declare bool %llvm.isunordered.f32(float Val1, float  Val2)
4219   declare bool %llvm.isunordered.f64(double Val1, double Val2)
4220 </pre>
4221
4222 <h5>Overview:</h5>
4223
4224 <p>
4225 The '<tt>llvm.isunordered</tt>' intrinsics return true if either or both of the
4226 specified floating point values is a NAN.
4227 </p>
4228
4229 <h5>Arguments:</h5>
4230
4231 <p>
4232 The arguments are floating point numbers of the same type.
4233 </p>
4234
4235 <h5>Semantics:</h5>
4236
4237 <p>
4238 If either or both of the arguments is a SNAN or QNAN, it returns true, otherwise
4239 false.
4240 </p>
4241 </div>
4242
4243
4244 <!-- _______________________________________________________________________ -->
4245 <div class="doc_subsubsection">
4246   <a name="i_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
4247 </div>
4248
4249 <div class="doc_text">
4250
4251 <h5>Syntax:</h5>
4252 <pre>
4253   declare float %llvm.sqrt.f32(float %Val)
4254   declare double %llvm.sqrt.f64(double %Val)
4255 </pre>
4256
4257 <h5>Overview:</h5>
4258
4259 <p>
4260 The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand,
4261 returning the same value as the libm '<tt>sqrt</tt>' function would.  Unlike
4262 <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined behavior for
4263 negative numbers (which allows for better optimization).
4264 </p>
4265
4266 <h5>Arguments:</h5>
4267
4268 <p>
4269 The argument and return value are floating point numbers of the same type.
4270 </p>
4271
4272 <h5>Semantics:</h5>
4273
4274 <p>
4275 This function returns the sqrt of the specified operand if it is a positive
4276 floating point number.
4277 </p>
4278 </div>
4279
4280 <!-- _______________________________________________________________________ -->
4281 <div class="doc_subsubsection">
4282   <a name="i_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
4283 </div>
4284
4285 <div class="doc_text">
4286
4287 <h5>Syntax:</h5>
4288 <pre>
4289   declare float  %llvm.powi.f32(float  %Val, i32 %power)
4290   declare double %llvm.powi.f64(double %Val, i32 %power)
4291 </pre>
4292
4293 <h5>Overview:</h5>
4294
4295 <p>
4296 The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the
4297 specified (positive or negative) power.  The order of evaluation of
4298 multiplications is not defined.
4299 </p>
4300
4301 <h5>Arguments:</h5>
4302
4303 <p>
4304 The second argument is an integer power, and the first is a value to raise to
4305 that power.
4306 </p>
4307
4308 <h5>Semantics:</h5>
4309
4310 <p>
4311 This function returns the first value raised to the second power with an
4312 unspecified sequence of rounding operations.</p>
4313 </div>
4314
4315
4316 <!-- ======================================================================= -->
4317 <div class="doc_subsection">
4318   <a name="int_manip">Bit Manipulation Intrinsics</a>
4319 </div>
4320
4321 <div class="doc_text">
4322 <p>
4323 LLVM provides intrinsics for a few important bit manipulation operations.
4324 These allow efficient code generation for some algorithms.
4325 </p>
4326
4327 </div>
4328
4329 <!-- _______________________________________________________________________ -->
4330 <div class="doc_subsubsection">
4331   <a name="i_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
4332 </div>
4333
4334 <div class="doc_text">
4335
4336 <h5>Syntax:</h5>
4337 <pre>
4338   declare i16 %llvm.bswap.i16(i16 &lt;id&gt;)
4339   declare i32 %llvm.bswap.i32(i32 &lt;id&gt;)
4340   declare i64 %llvm.bswap.i64(i64 &lt;id&gt;)
4341 </pre>
4342
4343 <h5>Overview:</h5>
4344
4345 <p>
4346 The '<tt>llvm.bwsap</tt>' family of intrinsics is used to byteswap a 16, 32 or
4347 64 bit quantity.  These are useful for performing operations on data that is not
4348 in the target's  native byte order.
4349 </p>
4350
4351 <h5>Semantics:</h5>
4352
4353 <p>
4354 The <tt>llvm.bswap.16</tt> intrinsic returns an i16 value that has the high
4355 and low byte of the input i16 swapped.  Similarly, the <tt>llvm.bswap.i32</tt>
4356 intrinsic returns an i32 value that has the four bytes of the input i32
4357 swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the returned
4358 i32 will have its bytes in 3, 2, 1, 0 order.  The <tt>llvm.bswap.i64</tt>
4359 intrinsic extends this concept to 64 bits.
4360 </p>
4361
4362 </div>
4363
4364 <!-- _______________________________________________________________________ -->
4365 <div class="doc_subsubsection">
4366   <a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
4367 </div>
4368
4369 <div class="doc_text">
4370
4371 <h5>Syntax:</h5>
4372 <pre>
4373   declare i8  %llvm.ctpop.i8 (i8  &lt;src&gt;)
4374   declare i16 %llvm.ctpop.i16(i16 &lt;src&gt;)
4375   declare i32 %llvm.ctpop.i32(i32 &lt;src&gt;)
4376   declare i64 %llvm.ctpop.i64(i64 &lt;src&gt;)
4377 </pre>
4378
4379 <h5>Overview:</h5>
4380
4381 <p>
4382 The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set in a
4383 value.
4384 </p>
4385
4386 <h5>Arguments:</h5>
4387
4388 <p>
4389 The only argument is the value to be counted.  The argument may be of any
4390 unsigned integer type.  The return type must match the argument type.
4391 </p>
4392
4393 <h5>Semantics:</h5>
4394
4395 <p>
4396 The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.
4397 </p>
4398 </div>
4399
4400 <!-- _______________________________________________________________________ -->
4401 <div class="doc_subsubsection">
4402   <a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a>
4403 </div>
4404
4405 <div class="doc_text">
4406
4407 <h5>Syntax:</h5>
4408 <pre>
4409   declare i8  %llvm.ctlz.i8 (i8  &lt;src&gt;)
4410   declare i16 %llvm.ctlz.i16(i16 &lt;src&gt;)
4411   declare i32 %llvm.ctlz.i32(i32 &lt;src&gt;)
4412   declare i64 %llvm.ctlz.i64(i64 &lt;src&gt;)
4413 </pre>
4414
4415 <h5>Overview:</h5>
4416
4417 <p>
4418 The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of
4419 leading zeros in a variable.
4420 </p>
4421
4422 <h5>Arguments:</h5>
4423
4424 <p>
4425 The only argument is the value to be counted.  The argument may be of any
4426 unsigned integer type. The return type must match the argument type.
4427 </p>
4428
4429 <h5>Semantics:</h5>
4430
4431 <p>
4432 The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant) zeros
4433 in a variable.  If the src == 0 then the result is the size in bits of the type
4434 of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.
4435 </p>
4436 </div>
4437
4438
4439
4440 <!-- _______________________________________________________________________ -->
4441 <div class="doc_subsubsection">
4442   <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a>
4443 </div>
4444
4445 <div class="doc_text">
4446
4447 <h5>Syntax:</h5>
4448 <pre>
4449   declare i8  %llvm.cttz.i8 (i8  &lt;src&gt;)
4450   declare i16 %llvm.cttz.i16(i16 &lt;src&gt;)
4451   declare i32 %llvm.cttz.i32(i32 &lt;src&gt;)
4452   declare i64 %llvm.cttz.i64(i64 &lt;src&gt;)
4453 </pre>
4454
4455 <h5>Overview:</h5>
4456
4457 <p>
4458 The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of
4459 trailing zeros.
4460 </p>
4461
4462 <h5>Arguments:</h5>
4463
4464 <p>
4465 The only argument is the value to be counted.  The argument may be of any
4466 unsigned integer type.  The return type must match the argument type.
4467 </p>
4468
4469 <h5>Semantics:</h5>
4470
4471 <p>
4472 The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant) zeros
4473 in a variable.  If the src == 0 then the result is the size in bits of the type
4474 of src.  For example, <tt>llvm.cttz(2) = 1</tt>.
4475 </p>
4476 </div>
4477
4478 <!-- ======================================================================= -->
4479 <div class="doc_subsection">
4480   <a name="int_debugger">Debugger Intrinsics</a>
4481 </div>
4482
4483 <div class="doc_text">
4484 <p>
4485 The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> prefix),
4486 are described in the <a
4487 href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source Level
4488 Debugging</a> document.
4489 </p>
4490 </div>
4491
4492
4493 <!-- *********************************************************************** -->
4494 <hr>
4495 <address>
4496   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
4497   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
4498   <a href="http://validator.w3.org/check/referer"><img
4499   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
4500
4501   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
4502   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
4503   Last modified: $Date$
4504 </address>
4505 </body>
4506 </html>