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 i8]</tt><br/>
 861     </td>
 862     <td class="left">
 863       Array of 40 32-bit integer values.<br/>
 864       Array of 41 32-bit integer values.<br/>
 865       Array of 40 8-bit 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 i16]]]</tt><br/>
 876     </td>
 877     <td class="left">
 878       3x4 array of 32-bit integer values.<br/>
 879       12x10 array of single precision floating point values.<br/>
 880       2x3x4 array of 16-bit 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> (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 i64&gt;</tt><br/>
1058     </td>
1059     <td class="left">
1060       Packed vector of 4 32-bit integer values.<br/>
1061       Packed vector of 8 floating-point values.<br/>
1062       Packed vector of 2 64-bit 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
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>Because the operands are the same width, the result of an integer
1774 multiplication is the same whether the operands should be deemed unsigned or
1775 signed.</p>
1776 <h5>Example:</h5>
1777 <pre>  &lt;result&gt; = mul i32 4, %var          <i>; yields {i32}:result = 4 * %var</i>
1778 </pre>
1779 </div>
1780 <!-- _______________________________________________________________________ -->
1781 <div class="doc_subsubsection"> <a name="i_udiv">'<tt>udiv</tt>' Instruction
1782 </a></div>
1783 <div class="doc_text">
1784 <h5>Syntax:</h5>
1785 <pre>  &lt;result&gt; = udiv &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1786 </pre>
1787 <h5>Overview:</h5>
1788 <p>The '<tt>udiv</tt>' instruction returns the quotient of its two
1789 operands.</p>
1790 <h5>Arguments:</h5>
1791 <p>The two arguments to the '<tt>udiv</tt>' instruction must be
1792 <a href="#t_integer">integer</a> values. Both arguments must have identical
1793 types. This instruction can also take <a href="#t_packed">packed</a> versions
1794 of the values in which case the elements must be integers.</p>
1795 <h5>Semantics:</h5>
1796 <p>The value produced is the unsigned integer quotient of the two operands. This
1797 instruction always performs an unsigned division operation, regardless of
1798 whether the arguments are unsigned or not.</p>
1799 <h5>Example:</h5>
1800 <pre>  &lt;result&gt; = udiv i32 4, %var          <i>; yields {i32}:result = 4 / %var</i>
1801 </pre>
1802 </div>
1803 <!-- _______________________________________________________________________ -->
1804 <div class="doc_subsubsection"> <a name="i_sdiv">'<tt>sdiv</tt>' Instruction
1805 </a> </div>
1806 <div class="doc_text">
1807 <h5>Syntax:</h5>
1808 <pre>  &lt;result&gt; = sdiv &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1809 </pre>
1810 <h5>Overview:</h5>
1811 <p>The '<tt>sdiv</tt>' instruction returns the quotient of its two
1812 operands.</p>
1813 <h5>Arguments:</h5>
1814 <p>The two arguments to the '<tt>sdiv</tt>' instruction must be
1815 <a href="#t_integer">integer</a> values.  Both arguments must have identical
1816 types. This instruction can also take <a href="#t_packed">packed</a> versions
1817 of the values in which case the elements must be integers.</p>
1818 <h5>Semantics:</h5>
1819 <p>The value produced is the signed integer quotient of the two operands. This
1820 instruction always performs a signed division operation, regardless of whether
1821 the arguments are signed or not.</p>
1822 <h5>Example:</h5>
1823 <pre>  &lt;result&gt; = sdiv i32 4, %var          <i>; yields {i32}:result = 4 / %var</i>
1824 </pre>
1825 </div>
1826 <!-- _______________________________________________________________________ -->
1827 <div class="doc_subsubsection"> <a name="i_fdiv">'<tt>fdiv</tt>'
1828 Instruction</a> </div>
1829 <div class="doc_text">
1830 <h5>Syntax:</h5>
1831 <pre>  &lt;result&gt; = fdiv &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1832 </pre>
1833 <h5>Overview:</h5>
1834 <p>The '<tt>fdiv</tt>' instruction returns the quotient of its two
1835 operands.</p>
1836 <h5>Arguments:</h5>
1837 <p>The two arguments to the '<tt>div</tt>' instruction must be
1838 <a href="#t_floating">floating point</a> values.  Both arguments must have
1839 identical types.  This instruction can also take <a href="#t_packed">packed</a>
1840 versions of the values in which case the elements must be floating point.</p>
1841 <h5>Semantics:</h5>
1842 <p>The value produced is the floating point quotient of the two operands.</p>
1843 <h5>Example:</h5>
1844 <pre>  &lt;result&gt; = fdiv float 4.0, %var          <i>; yields {float}:result = 4.0 / %var</i>
1845 </pre>
1846 </div>
1847 <!-- _______________________________________________________________________ -->
1848 <div class="doc_subsubsection"> <a name="i_urem">'<tt>urem</tt>' Instruction</a>
1849 </div>
1850 <div class="doc_text">
1851 <h5>Syntax:</h5>
1852 <pre>  &lt;result&gt; = urem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1853 </pre>
1854 <h5>Overview:</h5>
1855 <p>The '<tt>urem</tt>' instruction returns the remainder from the
1856 unsigned division of its two arguments.</p>
1857 <h5>Arguments:</h5>
1858 <p>The two arguments to the '<tt>urem</tt>' instruction must be
1859 <a href="#t_integer">integer</a> values. Both arguments must have identical
1860 types.</p>
1861 <h5>Semantics:</h5>
1862 <p>This instruction returns the unsigned integer <i>remainder</i> of a division.
1863 This instruction always performs an unsigned division to get the remainder,
1864 regardless of whether the arguments are unsigned or not.</p>
1865 <h5>Example:</h5>
1866 <pre>  &lt;result&gt; = urem i32 4, %var          <i>; yields {i32}:result = 4 % %var</i>
1867 </pre>
1868
1869 </div>
1870 <!-- _______________________________________________________________________ -->
1871 <div class="doc_subsubsection"> <a name="i_srem">'<tt>srem</tt>'
1872 Instruction</a> </div>
1873 <div class="doc_text">
1874 <h5>Syntax:</h5>
1875 <pre>  &lt;result&gt; = srem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1876 </pre>
1877 <h5>Overview:</h5>
1878 <p>The '<tt>srem</tt>' instruction returns the remainder from the
1879 signed division of its two operands.</p>
1880 <h5>Arguments:</h5>
1881 <p>The two arguments to the '<tt>srem</tt>' instruction must be
1882 <a href="#t_integer">integer</a> values.  Both arguments must have identical
1883 types.</p>
1884 <h5>Semantics:</h5>
1885 <p>This instruction returns the <i>remainder</i> of a division (where the result
1886 has the same sign as the divisor), not the <i>modulus</i> (where the
1887 result has the same sign as the dividend) of a value.  For more
1888 information about the difference, see <a
1889  href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
1890 Math Forum</a>.</p>
1891 <h5>Example:</h5>
1892 <pre>  &lt;result&gt; = srem i32 4, %var          <i>; yields {i32}:result = 4 % %var</i>
1893 </pre>
1894
1895 </div>
1896 <!-- _______________________________________________________________________ -->
1897 <div class="doc_subsubsection"> <a name="i_frem">'<tt>frem</tt>'
1898 Instruction</a> </div>
1899 <div class="doc_text">
1900 <h5>Syntax:</h5>
1901 <pre>  &lt;result&gt; = frem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1902 </pre>
1903 <h5>Overview:</h5>
1904 <p>The '<tt>frem</tt>' instruction returns the remainder from the
1905 division of its two operands.</p>
1906 <h5>Arguments:</h5>
1907 <p>The two arguments to the '<tt>frem</tt>' instruction must be
1908 <a href="#t_floating">floating point</a> values.  Both arguments must have
1909 identical types.</p>
1910 <h5>Semantics:</h5>
1911 <p>This instruction returns the <i>remainder</i> of a division.</p>
1912 <h5>Example:</h5>
1913 <pre>  &lt;result&gt; = frem float 4.0, %var          <i>; yields {float}:result = 4.0 % %var</i>
1914 </pre>
1915 </div>
1916
1917 <!-- ======================================================================= -->
1918 <div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary
1919 Operations</a> </div>
1920 <div class="doc_text">
1921 <p>Bitwise binary operators are used to do various forms of
1922 bit-twiddling in a program.  They are generally very efficient
1923 instructions and can commonly be strength reduced from other
1924 instructions.  They require two operands, execute an operation on them,
1925 and produce a single value.  The resulting value of the bitwise binary
1926 operators is always the same type as its first operand.</p>
1927 </div>
1928 <!-- _______________________________________________________________________ -->
1929 <div class="doc_subsubsection"> <a name="i_and">'<tt>and</tt>'
1930 Instruction</a> </div>
1931 <div class="doc_text">
1932 <h5>Syntax:</h5>
1933 <pre>  &lt;result&gt; = and &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1934 </pre>
1935 <h5>Overview:</h5>
1936 <p>The '<tt>and</tt>' instruction returns the bitwise logical and of
1937 its two operands.</p>
1938 <h5>Arguments:</h5>
1939 <p>The two arguments to the '<tt>and</tt>' instruction must be <a
1940  href="#t_integral">integral</a> values.  Both arguments must have
1941 identical types.</p>
1942 <h5>Semantics:</h5>
1943 <p>The truth table used for the '<tt>and</tt>' instruction is:</p>
1944 <p> </p>
1945 <div style="align: center">
1946 <table border="1" cellspacing="0" cellpadding="4">
1947   <tbody>
1948     <tr>
1949       <td>In0</td>
1950       <td>In1</td>
1951       <td>Out</td>
1952     </tr>
1953     <tr>
1954       <td>0</td>
1955       <td>0</td>
1956       <td>0</td>
1957     </tr>
1958     <tr>
1959       <td>0</td>
1960       <td>1</td>
1961       <td>0</td>
1962     </tr>
1963     <tr>
1964       <td>1</td>
1965       <td>0</td>
1966       <td>0</td>
1967     </tr>
1968     <tr>
1969       <td>1</td>
1970       <td>1</td>
1971       <td>1</td>
1972     </tr>
1973   </tbody>
1974 </table>
1975 </div>
1976 <h5>Example:</h5>
1977 <pre>  &lt;result&gt; = and i32 4, %var         <i>; yields {i32}:result = 4 &amp; %var</i>
1978   &lt;result&gt; = and i32 15, 40          <i>; yields {i32}:result = 8</i>
1979   &lt;result&gt; = and i32 4, 8            <i>; yields {i32}:result = 0</i>
1980 </pre>
1981 </div>
1982 <!-- _______________________________________________________________________ -->
1983 <div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div>
1984 <div class="doc_text">
1985 <h5>Syntax:</h5>
1986 <pre>  &lt;result&gt; = or &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1987 </pre>
1988 <h5>Overview:</h5>
1989 <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive
1990 or of its two operands.</p>
1991 <h5>Arguments:</h5>
1992 <p>The two arguments to the '<tt>or</tt>' instruction must be <a
1993  href="#t_integral">integral</a> values.  Both arguments must have
1994 identical types.</p>
1995 <h5>Semantics:</h5>
1996 <p>The truth table used for the '<tt>or</tt>' instruction is:</p>
1997 <p> </p>
1998 <div style="align: center">
1999 <table border="1" cellspacing="0" cellpadding="4">
2000   <tbody>
2001     <tr>
2002       <td>In0</td>
2003       <td>In1</td>
2004       <td>Out</td>
2005     </tr>
2006     <tr>
2007       <td>0</td>
2008       <td>0</td>
2009       <td>0</td>
2010     </tr>
2011     <tr>
2012       <td>0</td>
2013       <td>1</td>
2014       <td>1</td>
2015     </tr>
2016     <tr>
2017       <td>1</td>
2018       <td>0</td>
2019       <td>1</td>
2020     </tr>
2021     <tr>
2022       <td>1</td>
2023       <td>1</td>
2024       <td>1</td>
2025     </tr>
2026   </tbody>
2027 </table>
2028 </div>
2029 <h5>Example:</h5>
2030 <pre>  &lt;result&gt; = or i32 4, %var         <i>; yields {i32}:result = 4 | %var</i>
2031   &lt;result&gt; = or i32 15, 40          <i>; yields {i32}:result = 47</i>
2032   &lt;result&gt; = or i32 4, 8            <i>; yields {i32}:result = 12</i>
2033 </pre>
2034 </div>
2035 <!-- _______________________________________________________________________ -->
2036 <div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>'
2037 Instruction</a> </div>
2038 <div class="doc_text">
2039 <h5>Syntax:</h5>
2040 <pre>  &lt;result&gt; = xor &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
2041 </pre>
2042 <h5>Overview:</h5>
2043 <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive
2044 or of its two operands.  The <tt>xor</tt> is used to implement the
2045 "one's complement" operation, which is the "~" operator in C.</p>
2046 <h5>Arguments:</h5>
2047 <p>The two arguments to the '<tt>xor</tt>' instruction must be <a
2048  href="#t_integral">integral</a> values.  Both arguments must have
2049 identical types.</p>
2050 <h5>Semantics:</h5>
2051 <p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
2052 <p> </p>
2053 <div style="align: center">
2054 <table border="1" cellspacing="0" cellpadding="4">
2055   <tbody>
2056     <tr>
2057       <td>In0</td>
2058       <td>In1</td>
2059       <td>Out</td>
2060     </tr>
2061     <tr>
2062       <td>0</td>
2063       <td>0</td>
2064       <td>0</td>
2065     </tr>
2066     <tr>
2067       <td>0</td>
2068       <td>1</td>
2069       <td>1</td>
2070     </tr>
2071     <tr>
2072       <td>1</td>
2073       <td>0</td>
2074       <td>1</td>
2075     </tr>
2076     <tr>
2077       <td>1</td>
2078       <td>1</td>
2079       <td>0</td>
2080     </tr>
2081   </tbody>
2082 </table>
2083 </div>
2084 <p> </p>
2085 <h5>Example:</h5>
2086 <pre>  &lt;result&gt; = xor i32 4, %var         <i>; yields {i32}:result = 4 ^ %var</i>
2087   &lt;result&gt; = xor i32 15, 40          <i>; yields {i32}:result = 39</i>
2088   &lt;result&gt; = xor i32 4, 8            <i>; yields {i32}:result = 12</i>
2089   &lt;result&gt; = xor i32 %V, -1          <i>; yields {i32}:result = ~%V</i>
2090 </pre>
2091 </div>
2092 <!-- _______________________________________________________________________ -->
2093 <div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>'
2094 Instruction</a> </div>
2095 <div class="doc_text">
2096 <h5>Syntax:</h5>
2097 <pre>  &lt;result&gt; = shl &lt;ty&gt; &lt;var1&gt;, i8 &lt;var2&gt;   <i>; yields {ty}:result</i>
2098 </pre>
2099 <h5>Overview:</h5>
2100 <p>The '<tt>shl</tt>' instruction returns the first operand shifted to
2101 the left a specified number of bits.</p>
2102 <h5>Arguments:</h5>
2103 <p>The first argument to the '<tt>shl</tt>' instruction must be an <a
2104  href="#t_integer">integer</a> type.  The second argument must be an '<tt>i8</tt>'
2105 type.</p>
2106 <h5>Semantics:</h5>
2107 <p>The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.</p>
2108 <h5>Example:</h5>
2109 <pre>  &lt;result&gt; = shl i32 4, i8 %var   <i>; yields {i32}:result = 4 &lt;&lt; %var</i>
2110   &lt;result&gt; = shl i32 4, i8 2      <i>; yields {i32}:result = 16</i>
2111   &lt;result&gt; = shl i32 1, i8 10     <i>; yields {i32}:result = 1024</i>
2112 </pre>
2113 </div>
2114 <!-- _______________________________________________________________________ -->
2115 <div class="doc_subsubsection"> <a name="i_lshr">'<tt>lshr</tt>'
2116 Instruction</a> </div>
2117 <div class="doc_text">
2118 <h5>Syntax:</h5>
2119 <pre>  &lt;result&gt; = lshr &lt;ty&gt; &lt;var1&gt;, i8 &lt;var2&gt;   <i>; yields {ty}:result</i>
2120 </pre>
2121
2122 <h5>Overview:</h5>
2123 <p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first
2124 operand shifted to the right a specified number of bits.</p>
2125
2126 <h5>Arguments:</h5>
2127 <p>The first argument to the '<tt>lshr</tt>' instruction must be an <a
2128  href="#t_integer">integer</a> type.  The second argument must be an '<tt>i8</tt>' type.</p>
2129
2130 <h5>Semantics:</h5>
2131 <p>This instruction always performs a logical shift right operation. The
2132 <tt>var2</tt> most significant bits will be filled with zero bits after the
2133 shift.</p>
2134
2135 <h5>Example:</h5>
2136 <pre>
2137   &lt;result&gt; = lshr i32 4, i8 1   <i>; yields {i32}:result = 2</i>
2138   &lt;result&gt; = lshr i32 4, i8 2    <i>; yields {i32}:result = 1</i>
2139   &lt;result&gt; = lshr i8  4, i8 3  <i>; yields {i8 }:result = 0</i>
2140   &lt;result&gt; = lshr i8  -2, i8 1 <i>; yields {i8 }:result = 0x7FFFFFFF </i>
2141 </pre>
2142 </div>
2143
2144 <!-- ======================================================================= -->
2145 <div class="doc_subsubsection"> <a name="i_ashr">'<tt>ashr</tt>'
2146 Instruction</a> </div>
2147 <div class="doc_text">
2148
2149 <h5>Syntax:</h5>
2150 <pre>  &lt;result&gt; = ashr &lt;ty&gt; &lt;var1&gt;, i8 &lt;var2&gt;   <i>; yields {ty}:result</i>
2151 </pre>
2152
2153 <h5>Overview:</h5>
2154 <p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first
2155 operand shifted to the right a specified number of bits.</p>
2156
2157 <h5>Arguments:</h5>
2158 <p>The first argument to the '<tt>ashr</tt>' instruction must be an
2159 <a href="#t_integer">integer</a> type.  The second argument must be an
2160 '<tt>i8</tt>' type.</p>
2161
2162 <h5>Semantics:</h5>
2163 <p>This instruction always performs an arithmetic shift right operation,
2164 regardless of whether the arguments are signed or not. The <tt>var2</tt> most
2165 significant bits will be filled with the sign bit of <tt>var1</tt>.</p>
2166
2167 <h5>Example:</h5>
2168 <pre>
2169   &lt;result&gt; = ashr i32 4, i8 1    <i>; yields {i32}:result = 2</i>
2170   &lt;result&gt; = ashr i32 4, i8 2      <i>; yields {i32}:result = 1</i>
2171   &lt;result&gt; = ashr i8 4, i8 3    <i>; yields {i8}:result = 0</i>
2172   &lt;result&gt; = ashr i8  -2, i8 1   <i>; yields {i8 }:result = -1</i>
2173 </pre>
2174 </div>
2175
2176 <!-- ======================================================================= -->
2177 <div class="doc_subsection">
2178   <a name="vectorops">Vector Operations</a>
2179 </div>
2180
2181 <div class="doc_text">
2182
2183 <p>LLVM supports several instructions to represent vector operations in a
2184 target-independent manner.  This instructions cover the element-access and
2185 vector-specific operations needed to process vectors effectively.  While LLVM
2186 does directly support these vector operations, many sophisticated algorithms
2187 will want to use target-specific intrinsics to take full advantage of a specific
2188 target.</p>
2189
2190 </div>
2191
2192 <!-- _______________________________________________________________________ -->
2193 <div class="doc_subsubsection">
2194    <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
2195 </div>
2196
2197 <div class="doc_text">
2198
2199 <h5>Syntax:</h5>
2200
2201 <pre>
2202   &lt;result&gt; = extractelement &lt;n x &lt;ty&gt;&gt; &lt;val&gt;, i32 &lt;idx&gt;    <i>; yields &lt;ty&gt;</i>
2203 </pre>
2204
2205 <h5>Overview:</h5>
2206
2207 <p>
2208 The '<tt>extractelement</tt>' instruction extracts a single scalar
2209 element from a packed vector at a specified index.
2210 </p>
2211
2212
2213 <h5>Arguments:</h5>
2214
2215 <p>
2216 The first operand of an '<tt>extractelement</tt>' instruction is a
2217 value of <a href="#t_packed">packed</a> type.  The second operand is
2218 an index indicating the position from which to extract the element.
2219 The index may be a variable.</p>
2220
2221 <h5>Semantics:</h5>
2222
2223 <p>
2224 The result is a scalar of the same type as the element type of
2225 <tt>val</tt>.  Its value is the value at position <tt>idx</tt> of
2226 <tt>val</tt>.  If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
2227 results are undefined.
2228 </p>
2229
2230 <h5>Example:</h5>
2231
2232 <pre>
2233   %result = extractelement &lt;4 x i32&gt; %vec, i32 0    <i>; yields i32</i>
2234 </pre>
2235 </div>
2236
2237
2238 <!-- _______________________________________________________________________ -->
2239 <div class="doc_subsubsection">
2240    <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
2241 </div>
2242
2243 <div class="doc_text">
2244
2245 <h5>Syntax:</h5>
2246
2247 <pre>
2248   &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>
2249 </pre>
2250
2251 <h5>Overview:</h5>
2252
2253 <p>
2254 The '<tt>insertelement</tt>' instruction inserts a scalar
2255 element into a packed vector at a specified index.
2256 </p>
2257
2258
2259 <h5>Arguments:</h5>
2260
2261 <p>
2262 The first operand of an '<tt>insertelement</tt>' instruction is a
2263 value of <a href="#t_packed">packed</a> type.  The second operand is a
2264 scalar value whose type must equal the element type of the first
2265 operand.  The third operand is an index indicating the position at
2266 which to insert the value.  The index may be a variable.</p>
2267
2268 <h5>Semantics:</h5>
2269
2270 <p>
2271 The result is a packed vector of the same type as <tt>val</tt>.  Its
2272 element values are those of <tt>val</tt> except at position
2273 <tt>idx</tt>, where it gets the value <tt>elt</tt>.  If <tt>idx</tt>
2274 exceeds the length of <tt>val</tt>, the results are undefined.
2275 </p>
2276
2277 <h5>Example:</h5>
2278
2279 <pre>
2280   %result = insertelement &lt;4 x i32&gt; %vec, i32 1, i32 0    <i>; yields &lt;4 x i32&gt;</i>
2281 </pre>
2282 </div>
2283
2284 <!-- _______________________________________________________________________ -->
2285 <div class="doc_subsubsection">
2286    <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
2287 </div>
2288
2289 <div class="doc_text">
2290
2291 <h5>Syntax:</h5>
2292
2293 <pre>
2294   &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>
2295 </pre>
2296
2297 <h5>Overview:</h5>
2298
2299 <p>
2300 The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
2301 from two input vectors, returning a vector of the same type.
2302 </p>
2303
2304 <h5>Arguments:</h5>
2305
2306 <p>
2307 The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
2308 with types that match each other and types that match the result of the
2309 instruction.  The third argument is a shuffle mask, which has the same number
2310 of elements as the other vector type, but whose element type is always 'i32'.
2311 </p>
2312
2313 <p>
2314 The shuffle mask operand is required to be a constant vector with either
2315 constant integer or undef values.
2316 </p>
2317
2318 <h5>Semantics:</h5>
2319
2320 <p>
2321 The elements of the two input vectors are numbered from left to right across
2322 both of the vectors.  The shuffle mask operand specifies, for each element of
2323 the result vector, which element of the two input registers the result element
2324 gets.  The element selector may be undef (meaning "don't care") and the second
2325 operand may be undef if performing a shuffle from only one vector.
2326 </p>
2327
2328 <h5>Example:</h5>
2329
2330 <pre>
2331   %result = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2,
2332                           &lt;4 x i32&gt; &lt;i32 0, i32 4, i32 1, i32 5&gt;    <i>; yields &lt;4 x i32&gt;</i>
2333   %result = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; undef,
2334                           &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.
2335 </pre>
2336 </div>
2337
2338
2339 <!-- ======================================================================= -->
2340 <div class="doc_subsection">
2341   <a name="memoryops">Memory Access and Addressing Operations</a>
2342 </div>
2343
2344 <div class="doc_text">
2345
2346 <p>A key design point of an SSA-based representation is how it
2347 represents memory.  In LLVM, no memory locations are in SSA form, which
2348 makes things very simple.  This section describes how to read, write,
2349 allocate, and free memory in LLVM.</p>
2350
2351 </div>
2352
2353 <!-- _______________________________________________________________________ -->
2354 <div class="doc_subsubsection">
2355   <a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
2356 </div>
2357
2358 <div class="doc_text">
2359
2360 <h5>Syntax:</h5>
2361
2362 <pre>
2363   &lt;result&gt; = malloc &lt;type&gt;[, i32 &lt;NumElements&gt;][, align &lt;alignment&gt;]     <i>; yields {type*}:result</i>
2364 </pre>
2365
2366 <h5>Overview:</h5>
2367
2368 <p>The '<tt>malloc</tt>' instruction allocates memory from the system
2369 heap and returns a pointer to it.</p>
2370
2371 <h5>Arguments:</h5>
2372
2373 <p>The '<tt>malloc</tt>' instruction allocates
2374 <tt>sizeof(&lt;type&gt;)*NumElements</tt>
2375 bytes of memory from the operating system and returns a pointer of the
2376 appropriate type to the program.  If "NumElements" is specified, it is the
2377 number of elements allocated.  If an alignment is specified, the value result
2378 of the allocation is guaranteed to be aligned to at least that boundary.  If
2379 not specified, or if zero, the target can choose to align the allocation on any
2380 convenient boundary.</p>
2381
2382 <p>'<tt>type</tt>' must be a sized type.</p>
2383
2384 <h5>Semantics:</h5>
2385
2386 <p>Memory is allocated using the system "<tt>malloc</tt>" function, and
2387 a pointer is returned.</p>
2388
2389 <h5>Example:</h5>
2390
2391 <pre>
2392   %array  = malloc [4 x i8 ]                    <i>; yields {[%4 x i8]*}:array</i>
2393
2394   %size   = <a href="#i_add">add</a> i32 2, 2                          <i>; yields {i32}:size = i32 4</i>
2395   %array1 = malloc i8, i32 4                   <i>; yields {i8*}:array1</i>
2396   %array2 = malloc [12 x i8], i32 %size        <i>; yields {[12 x i8]*}:array2</i>
2397   %array3 = malloc i32, i32 4, align 1024         <i>; yields {i32*}:array3</i>
2398   %array4 = malloc i32, align 1024                 <i>; yields {i32*}:array4</i>
2399 </pre>
2400 </div>
2401
2402 <!-- _______________________________________________________________________ -->
2403 <div class="doc_subsubsection">
2404   <a name="i_free">'<tt>free</tt>' Instruction</a>
2405 </div>
2406
2407 <div class="doc_text">
2408
2409 <h5>Syntax:</h5>
2410
2411 <pre>
2412   free &lt;type&gt; &lt;value&gt;                              <i>; yields {void}</i>
2413 </pre>
2414
2415 <h5>Overview:</h5>
2416
2417 <p>The '<tt>free</tt>' instruction returns memory back to the unused
2418 memory heap to be reallocated in the future.</p>
2419
2420 <h5>Arguments:</h5>
2421
2422 <p>'<tt>value</tt>' shall be a pointer value that points to a value
2423 that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>'
2424 instruction.</p>
2425
2426 <h5>Semantics:</h5>
2427
2428 <p>Access to the memory pointed to by the pointer is no longer defined
2429 after this instruction executes.</p>
2430
2431 <h5>Example:</h5>
2432
2433 <pre>
2434   %array  = <a href="#i_malloc">malloc</a> [4 x i8]                    <i>; yields {[4 x i8]*}:array</i>
2435             free   [4 x i8]* %array
2436 </pre>
2437 </div>
2438
2439 <!-- _______________________________________________________________________ -->
2440 <div class="doc_subsubsection">
2441   <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
2442 </div>
2443
2444 <div class="doc_text">
2445
2446 <h5>Syntax:</h5>
2447
2448 <pre>
2449   &lt;result&gt; = alloca &lt;type&gt;[, i32 &lt;NumElements&gt;][, align &lt;alignment&gt;]     <i>; yields {type*}:result</i>
2450 </pre>
2451
2452 <h5>Overview:</h5>
2453
2454 <p>The '<tt>alloca</tt>' instruction allocates memory on the current
2455 stack frame of the procedure that is live until the current function
2456 returns to its caller.</p>
2457
2458 <h5>Arguments:</h5>
2459
2460 <p>The '<tt>alloca</tt>' instruction allocates <tt>sizeof(&lt;type&gt;)*NumElements</tt>
2461 bytes of memory on the runtime stack, returning a pointer of the
2462 appropriate type to the program.    If "NumElements" is specified, it is the
2463 number of elements allocated.  If an alignment is specified, the value result
2464 of the allocation is guaranteed to be aligned to at least that boundary.  If
2465 not specified, or if zero, the target can choose to align the allocation on any
2466 convenient boundary.</p>
2467
2468 <p>'<tt>type</tt>' may be any sized type.</p>
2469
2470 <h5>Semantics:</h5>
2471
2472 <p>Memory is allocated; a pointer is returned.  '<tt>alloca</tt>'d
2473 memory is automatically released when the function returns.  The '<tt>alloca</tt>'
2474 instruction is commonly used to represent automatic variables that must
2475 have an address available.  When the function returns (either with the <tt><a
2476  href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt>
2477 instructions), the memory is reclaimed.</p>
2478
2479 <h5>Example:</h5>
2480
2481 <pre>
2482   %ptr = alloca i32                              <i>; yields {i32*}:ptr</i>
2483   %ptr = alloca i32, i32 4                      <i>; yields {i32*}:ptr</i>
2484   %ptr = alloca i32, i32 4, align 1024          <i>; yields {i32*}:ptr</i>
2485   %ptr = alloca i32, align 1024                  <i>; yields {i32*}:ptr</i>
2486 </pre>
2487 </div>
2488
2489 <!-- _______________________________________________________________________ -->
2490 <div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
2491 Instruction</a> </div>
2492 <div class="doc_text">
2493 <h5>Syntax:</h5>
2494 <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>
2495 <h5>Overview:</h5>
2496 <p>The '<tt>load</tt>' instruction is used to read from memory.</p>
2497 <h5>Arguments:</h5>
2498 <p>The argument to the '<tt>load</tt>' instruction specifies the memory
2499 address from which to load.  The pointer must point to a <a
2500  href="#t_firstclass">first class</a> type.  If the <tt>load</tt> is
2501 marked as <tt>volatile</tt>, then the optimizer is not allowed to modify
2502 the number or order of execution of this <tt>load</tt> with other
2503 volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
2504 instructions. </p>
2505 <h5>Semantics:</h5>
2506 <p>The location of memory pointed to is loaded.</p>
2507 <h5>Examples:</h5>
2508 <pre>  %ptr = <a href="#i_alloca">alloca</a> i32                               <i>; yields {i32*}:ptr</i>
2509   <a
2510  href="#i_store">store</a> i32 3, i32* %ptr                          <i>; yields {void}</i>
2511   %val = load i32* %ptr                           <i>; yields {i32}:val = i32 3</i>
2512 </pre>
2513 </div>
2514 <!-- _______________________________________________________________________ -->
2515 <div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
2516 Instruction</a> </div>
2517 <div class="doc_text">
2518 <h5>Syntax:</h5>
2519 <pre>  store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;                   <i>; yields {void}</i>
2520   volatile store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;                   <i>; yields {void}</i>
2521 </pre>
2522 <h5>Overview:</h5>
2523 <p>The '<tt>store</tt>' instruction is used to write to memory.</p>
2524 <h5>Arguments:</h5>
2525 <p>There are two arguments to the '<tt>store</tt>' instruction: a value
2526 to store and an address in which to store it.  The type of the '<tt>&lt;pointer&gt;</tt>'
2527 operand must be a pointer to the type of the '<tt>&lt;value&gt;</tt>'
2528 operand. If the <tt>store</tt> is marked as <tt>volatile</tt>, then the
2529 optimizer is not allowed to modify the number or order of execution of
2530 this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a
2531  href="#i_store">store</a></tt> instructions.</p>
2532 <h5>Semantics:</h5>
2533 <p>The contents of memory are updated to contain '<tt>&lt;value&gt;</tt>'
2534 at the location specified by the '<tt>&lt;pointer&gt;</tt>' operand.</p>
2535 <h5>Example:</h5>
2536 <pre>  %ptr = <a href="#i_alloca">alloca</a> i32                               <i>; yields {i32*}:ptr</i>
2537   <a
2538  href="#i_store">store</a> i32 3, i32* %ptr                          <i>; yields {void}</i>
2539   %val = load i32* %ptr                           <i>; yields {i32}:val = i32 3</i>
2540 </pre>
2541 </div>
2542
2543 <!-- _______________________________________________________________________ -->
2544 <div class="doc_subsubsection">
2545    <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
2546 </div>
2547
2548 <div class="doc_text">
2549 <h5>Syntax:</h5>
2550 <pre>
2551   &lt;result&gt; = getelementptr &lt;ty&gt;* &lt;ptrval&gt;{, &lt;ty&gt; &lt;idx&gt;}*
2552 </pre>
2553
2554 <h5>Overview:</h5>
2555
2556 <p>
2557 The '<tt>getelementptr</tt>' instruction is used to get the address of a
2558 subelement of an aggregate data structure.</p>
2559
2560 <h5>Arguments:</h5>
2561
2562 <p>This instruction takes a list of integer operands that indicate what
2563 elements of the aggregate object to index to.  The actual types of the arguments
2564 provided depend on the type of the first pointer argument.  The
2565 '<tt>getelementptr</tt>' instruction is used to index down through the type
2566 levels of a structure or to a specific index in an array.  When indexing into a
2567 structure, only <tt>i32</tt> integer constants are allowed.  When indexing
2568 into an array or pointer, only integers of 32 or 64 bits are allowed, and will
2569 be sign extended to 64-bit values.</p>
2570
2571 <p>For example, let's consider a C code fragment and how it gets
2572 compiled to LLVM:</p>
2573
2574 <pre>
2575   struct RT {
2576     char A;
2577     i32 B[10][20];
2578     char C;
2579   };
2580   struct ST {
2581     i32 X;
2582     double Y;
2583     struct RT Z;
2584   };
2585
2586   define i32 *foo(struct ST *s) {
2587     return &amp;s[1].Z.B[5][13];
2588   }
2589 </pre>
2590
2591 <p>The LLVM code generated by the GCC frontend is:</p>
2592
2593 <pre>
2594   %RT = type { i8 , [10 x [20 x i32]], i8  }
2595   %ST = type { i32, double, %RT }
2596
2597   implementation
2598
2599   define i32* %foo(%ST* %s) {
2600   entry:
2601     %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13
2602     ret i32* %reg
2603   }
2604 </pre>
2605
2606 <h5>Semantics:</h5>
2607
2608 <p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
2609 on the pointer type that is being indexed into. <a href="#t_pointer">Pointer</a>
2610 and <a href="#t_array">array</a> types can use a 32-bit or 64-bit
2611 <a href="#t_integer">integer</a> type but the value will always be sign extended
2612 to 64-bits.  <a href="#t_struct">Structure</a> types, require <tt>i32</tt>
2613 <b>constants</b>.</p>
2614
2615 <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
2616 type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT
2617 }</tt>' type, a structure.  The second index indexes into the third element of
2618 the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]],
2619 i8  }</tt>' type, another structure.  The third index indexes into the second
2620 element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an
2621 array.  The two dimensions of the array are subscripted into, yielding an
2622 '<tt>i32</tt>' type.  The '<tt>getelementptr</tt>' instruction returns a pointer
2623 to this element, thus computing a value of '<tt>i32*</tt>' type.</p>
2624
2625 <p>Note that it is perfectly legal to index partially through a
2626 structure, returning a pointer to an inner element.  Because of this,
2627 the LLVM code for the given testcase is equivalent to:</p>
2628
2629 <pre>
2630   define i32* %foo(%ST* %s) {
2631     %t1 = getelementptr %ST* %s, i32 1                        <i>; yields %ST*:%t1</i>
2632     %t2 = getelementptr %ST* %t1, i32 0, i32 2               <i>; yields %RT*:%t2</i>
2633     %t3 = getelementptr %RT* %t2, i32 0, i32 1               <i>; yields [10 x [20 x i32]]*:%t3</i>
2634     %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5  <i>; yields [20 x i32]*:%t4</i>
2635     %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13        <i>; yields i32*:%t5</i>
2636     ret i32* %t5
2637   }
2638 </pre>
2639
2640 <p>Note that it is undefined to access an array out of bounds: array and
2641 pointer indexes must always be within the defined bounds of the array type.
2642 The one exception for this rules is zero length arrays.  These arrays are
2643 defined to be accessible as variable length arrays, which requires access
2644 beyond the zero'th element.</p>
2645
2646 <p>The getelementptr instruction is often confusing.  For some more insight
2647 into how it works, see <a href="GetElementPtr.html">the getelementptr
2648 FAQ</a>.</p>
2649
2650 <h5>Example:</h5>
2651
2652 <pre>
2653     <i>; yields [12 x i8]*:aptr</i>
2654     %aptr = getelementptr {i32, [12 x i8]}* %sptr, i64 0, i32 1
2655 </pre>
2656 </div>
2657
2658 <!-- ======================================================================= -->
2659 <div class="doc_subsection"> <a name="convertops">Conversion Operations</a>
2660 </div>
2661 <div class="doc_text">
2662 <p>The instructions in this category are the conversion instructions (casting)
2663 which all take a single operand and a type. They perform various bit conversions
2664 on the operand.</p>
2665 </div>
2666
2667 <!-- _______________________________________________________________________ -->
2668 <div class="doc_subsubsection">
2669    <a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
2670 </div>
2671 <div class="doc_text">
2672
2673 <h5>Syntax:</h5>
2674 <pre>
2675   &lt;result&gt; = trunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2676 </pre>
2677
2678 <h5>Overview:</h5>
2679 <p>
2680 The '<tt>trunc</tt>' instruction truncates its operand to the type <tt>ty2</tt>.
2681 </p>
2682
2683 <h5>Arguments:</h5>
2684 <p>
2685 The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must
2686 be an <a href="#t_integer">integer</a> type, and a type that specifies the size
2687 and type of the result, which must be an <a href="#t_integral">integral</a>
2688 type. The bit size of <tt>value</tt> must be larger than the bit size of
2689 <tt>ty2</tt>. Equal sized types are not allowed.</p>
2690
2691 <h5>Semantics:</h5>
2692 <p>
2693 The '<tt>trunc</tt>' instruction truncates the high order bits in <tt>value</tt>
2694 and converts the remaining bits to <tt>ty2</tt>. Since the source size must be
2695 larger than the destination size, <tt>trunc</tt> cannot be a <i>no-op cast</i>.
2696 It will always truncate bits.</p>
2697
2698 <h5>Example:</h5>
2699 <pre>
2700   %X = trunc i32 257 to i8              <i>; yields i8:1</i>
2701   %Y = trunc i32 123 to bool               <i>; yields bool:true</i>
2702 </pre>
2703 </div>
2704
2705 <!-- _______________________________________________________________________ -->
2706 <div class="doc_subsubsection">
2707    <a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
2708 </div>
2709 <div class="doc_text">
2710
2711 <h5>Syntax:</h5>
2712 <pre>
2713   &lt;result&gt; = zext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2714 </pre>
2715
2716 <h5>Overview:</h5>
2717 <p>The '<tt>zext</tt>' instruction zero extends its operand to type
2718 <tt>ty2</tt>.</p>
2719
2720
2721 <h5>Arguments:</h5>
2722 <p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of
2723 <a href="#t_integral">integral</a> type, and a type to cast it to, which must
2724 also be of <a href="#t_integral">integral</a> type. The bit size of the
2725 <tt>value</tt> must be smaller than the bit size of the destination type,
2726 <tt>ty2</tt>.</p>
2727
2728 <h5>Semantics:</h5>
2729 <p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero
2730 bits until it reaches the size of the destination type, <tt>ty2</tt>. When the
2731 the operand and the type are the same size, no bit filling is done and the
2732 cast is considered a <i>no-op cast</i> because no bits change (only the type
2733 changes).</p>
2734
2735 <p>When zero extending from bool, the result will alwasy be either 0 or 1.</p>
2736
2737 <h5>Example:</h5>
2738 <pre>
2739   %X = zext i32 257 to i64              <i>; yields i64:257</i>
2740   %Y = zext bool true to i32              <i>; yields i32:1</i>
2741 </pre>
2742 </div>
2743
2744 <!-- _______________________________________________________________________ -->
2745 <div class="doc_subsubsection">
2746    <a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
2747 </div>
2748 <div class="doc_text">
2749
2750 <h5>Syntax:</h5>
2751 <pre>
2752   &lt;result&gt; = sext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2753 </pre>
2754
2755 <h5>Overview:</h5>
2756 <p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
2757
2758 <h5>Arguments:</h5>
2759 <p>
2760 The '<tt>sext</tt>' instruction takes a value to cast, which must be of
2761 <a href="#t_integral">integral</a> type, and a type to cast it to, which must
2762 also be of <a href="#t_integral">integral</a> type.  The bit size of the
2763 <tt>value</tt> must be smaller than the bit size of the destination type,
2764 <tt>ty2</tt>.</p>
2765
2766 <h5>Semantics:</h5>
2767 <p>
2768 The '<tt>sext</tt>' instruction performs a sign extension by copying the sign
2769 bit (highest order bit) of the <tt>value</tt> until it reaches the bit size of
2770 the type <tt>ty2</tt>.  When the the operand and the type are the same size,
2771 no bit filling is done and the cast is considered a <i>no-op cast</i> because
2772 no bits change (only the type changes).</p>
2773
2774 <p>When sign extending from bool, the extension always results in -1 or 0.</p>
2775
2776 <h5>Example:</h5>
2777 <pre>
2778   %X = sext i8  -1 to i16              <i>; yields i16   :65535</i>
2779   %Y = sext bool true to i32             <i>; yields i32:-1</i>
2780 </pre>
2781 </div>
2782
2783 <!-- _______________________________________________________________________ -->
2784 <div class="doc_subsubsection">
2785    <a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
2786 </div>
2787
2788 <div class="doc_text">
2789
2790 <h5>Syntax:</h5>
2791
2792 <pre>
2793   &lt;result&gt; = fptrunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2794 </pre>
2795
2796 <h5>Overview:</h5>
2797 <p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
2798 <tt>ty2</tt>.</p>
2799
2800
2801 <h5>Arguments:</h5>
2802 <p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
2803   point</a> value to cast and a <a href="#t_floating">floating point</a> type to
2804 cast it to. The size of <tt>value</tt> must be larger than the size of
2805 <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
2806 <i>no-op cast</i>.</p>
2807
2808 <h5>Semantics:</h5>
2809 <p> The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger
2810 <a href="#t_floating">floating point</a> type to a smaller
2811 <a href="#t_floating">floating point</a> type.  If the value cannot fit within
2812 the destination type, <tt>ty2</tt>, then the results are undefined.</p>
2813
2814 <h5>Example:</h5>
2815 <pre>
2816   %X = fptrunc double 123.0 to float         <i>; yields float:123.0</i>
2817   %Y = fptrunc double 1.0E+300 to float      <i>; yields undefined</i>
2818 </pre>
2819 </div>
2820
2821 <!-- _______________________________________________________________________ -->
2822 <div class="doc_subsubsection">
2823    <a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
2824 </div>
2825 <div class="doc_text">
2826
2827 <h5>Syntax:</h5>
2828 <pre>
2829   &lt;result&gt; = fpext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2830 </pre>
2831
2832 <h5>Overview:</h5>
2833 <p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger
2834 floating point value.</p>
2835
2836 <h5>Arguments:</h5>
2837 <p>The '<tt>fpext</tt>' instruction takes a
2838 <a href="#t_floating">floating point</a> <tt>value</tt> to cast,
2839 and a <a href="#t_floating">floating point</a> type to cast it to. The source
2840 type must be smaller than the destination type.</p>
2841
2842 <h5>Semantics:</h5>
2843 <p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller
2844 <a href="t_floating">floating point</a> type to a larger
2845 <a href="t_floating">floating point</a> type. The <tt>fpext</tt> cannot be
2846 used to make a <i>no-op cast</i> because it always changes bits. Use
2847 <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p>
2848
2849 <h5>Example:</h5>
2850 <pre>
2851   %X = fpext float 3.1415 to double        <i>; yields double:3.1415</i>
2852   %Y = fpext float 1.0 to float            <i>; yields float:1.0 (no-op)</i>
2853 </pre>
2854 </div>
2855
2856 <!-- _______________________________________________________________________ -->
2857 <div class="doc_subsubsection">
2858    <a name="i_fp2uint">'<tt>fptoui .. to</tt>' Instruction</a>
2859 </div>
2860 <div class="doc_text">
2861
2862 <h5>Syntax:</h5>
2863 <pre>
2864   &lt;result&gt; = fp2uint &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2865 </pre>
2866
2867 <h5>Overview:</h5>
2868 <p>The '<tt>fp2uint</tt>' converts a floating point <tt>value</tt> to its
2869 unsigned integer equivalent of type <tt>ty2</tt>.
2870 </p>
2871
2872 <h5>Arguments:</h5>
2873 <p>The '<tt>fp2uint</tt>' instruction takes a value to cast, which must be a
2874 <a href="#t_floating">floating point</a> value, and a type to cast it to, which
2875 must be an <a href="#t_integral">integral</a> type.</p>
2876
2877 <h5>Semantics:</h5>
2878 <p> The '<tt>fp2uint</tt>' instruction converts its
2879 <a href="#t_floating">floating point</a> operand into the nearest (rounding
2880 towards zero) unsigned integer value. If the value cannot fit in <tt>ty2</tt>,
2881 the results are undefined.</p>
2882
2883 <p>When converting to bool, the conversion is done as a comparison against
2884 zero. If the <tt>value</tt> was zero, the bool result will be <tt>false</tt>.
2885 If the <tt>value</tt> was non-zero, the bool result will be <tt>true</tt>.</p>
2886
2887 <h5>Example:</h5>
2888 <pre>
2889   %X = fp2uint double 123.0 to i32         <i>; yields i32:123</i>
2890   %Y = fp2uint float 1.0E+300 to bool      <i>; yields bool:true</i>
2891   %X = fp2uint float 1.04E+17 to i8     <i>; yields undefined:1</i>
2892 </pre>
2893 </div>
2894
2895 <!-- _______________________________________________________________________ -->
2896 <div class="doc_subsubsection">
2897    <a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a>
2898 </div>
2899 <div class="doc_text">
2900
2901 <h5>Syntax:</h5>
2902 <pre>
2903   &lt;result&gt; = fptosi &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2904 </pre>
2905
2906 <h5>Overview:</h5>
2907 <p>The '<tt>fptosi</tt>' instruction converts
2908 <a href="#t_floating">floating point</a> <tt>value</tt> to type <tt>ty2</tt>.
2909 </p>
2910
2911
2912 <h5>Arguments:</h5>
2913 <p> The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a
2914 <a href="#t_floating">floating point</a> value, and a type to cast it to, which
2915 must also be an <a href="#t_integral">integral</a> type.</p>
2916
2917 <h5>Semantics:</h5>
2918 <p>The '<tt>fptosi</tt>' instruction converts its
2919 <a href="#t_floating">floating point</a> operand into the nearest (rounding
2920 towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
2921 the results are undefined.</p>
2922
2923 <p>When converting to bool, the conversion is done as a comparison against
2924 zero. If the <tt>value</tt> was zero, the bool result will be <tt>false</tt>.
2925 If the <tt>value</tt> was non-zero, the bool result will be <tt>true</tt>.</p>
2926
2927 <h5>Example:</h5>
2928 <pre>
2929   %X = fptosi double -123.0 to i32        <i>; yields i32:-123</i>
2930   %Y = fptosi float 1.0E-247 to bool      <i>; yields bool:true</i>
2931   %X = fptosi float 1.04E+17 to i8      <i>; yields undefined:1</i>
2932 </pre>
2933 </div>
2934
2935 <!-- _______________________________________________________________________ -->
2936 <div class="doc_subsubsection">
2937    <a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a>
2938 </div>
2939 <div class="doc_text">
2940
2941 <h5>Syntax:</h5>
2942 <pre>
2943   &lt;result&gt; = uitofp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2944 </pre>
2945
2946 <h5>Overview:</h5>
2947 <p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned
2948 integer and converts that value to the <tt>ty2</tt> type.</p>
2949
2950
2951 <h5>Arguments:</h5>
2952 <p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be an
2953 <a href="#t_integral">integral</a> value, and a type to cast it to, which must
2954 be a <a href="#t_floating">floating point</a> type.</p>
2955
2956 <h5>Semantics:</h5>
2957 <p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned
2958 integer quantity and converts it to the corresponding floating point value. If
2959 the value cannot fit in the floating point value, the results are undefined.</p>
2960
2961
2962 <h5>Example:</h5>
2963 <pre>
2964   %X = uitofp i32 257 to float         <i>; yields float:257.0</i>
2965   %Y = uitofp i8  -1 to double       <i>; yields double:255.0</i>
2966 </pre>
2967 </div>
2968
2969 <!-- _______________________________________________________________________ -->
2970 <div class="doc_subsubsection">
2971    <a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a>
2972 </div>
2973 <div class="doc_text">
2974
2975 <h5>Syntax:</h5>
2976 <pre>
2977   &lt;result&gt; = sitofp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2978 </pre>
2979
2980 <h5>Overview:</h5>
2981 <p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed
2982 integer and converts that value to the <tt>ty2</tt> type.</p>
2983
2984 <h5>Arguments:</h5>
2985 <p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be an
2986 <a href="#t_integral">integral</a> value, and a type to cast it to, which must be
2987 a <a href="#t_floating">floating point</a> type.</p>
2988
2989 <h5>Semantics:</h5>
2990 <p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed
2991 integer quantity and converts it to the corresponding floating point value. If
2992 the value cannot fit in the floating point value, the results are undefined.</p>
2993
2994 <h5>Example:</h5>
2995 <pre>
2996   %X = sitofp i32 257 to float         <i>; yields float:257.0</i>
2997   %Y = sitofp i8  -1 to double       <i>; yields double:-1.0</i>
2998 </pre>
2999 </div>
3000
3001 <!-- _______________________________________________________________________ -->
3002 <div class="doc_subsubsection">
3003    <a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a>
3004 </div>
3005 <div class="doc_text">
3006
3007 <h5>Syntax:</h5>
3008 <pre>
3009   &lt;result&gt; = ptrtoint &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
3010 </pre>
3011
3012 <h5>Overview:</h5>
3013 <p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to
3014 the integer type <tt>ty2</tt>.</p>
3015
3016 <h5>Arguments:</h5>
3017 <p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which
3018 must be a <a href="t_pointer">pointer</a> value, and a type to cast it to
3019 <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.
3020
3021 <h5>Semantics:</h5>
3022 <p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type
3023 <tt>ty2</tt> by interpreting the pointer value as an integer and either
3024 truncating or zero extending that value to the size of the integer type. If
3025 <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If
3026 <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they
3027 are the same size, then nothing is done (<i>no-op cast</i>).</p>
3028
3029 <h5>Example:</h5>
3030 <pre>
3031   %X = ptrtoint i32* %X to i8           <i>; yields truncation on 32-bit</i>
3032   %Y = ptrtoint i32* %x to i64          <i>; yields zero extend on 32-bit</i>
3033 </pre>
3034 </div>
3035
3036 <!-- _______________________________________________________________________ -->
3037 <div class="doc_subsubsection">
3038    <a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a>
3039 </div>
3040 <div class="doc_text">
3041
3042 <h5>Syntax:</h5>
3043 <pre>
3044   &lt;result&gt; = inttoptr &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
3045 </pre>
3046
3047 <h5>Overview:</h5>
3048 <p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to
3049 a pointer type, <tt>ty2</tt>.</p>
3050
3051 <h5>Arguments:</h5>
3052 <p>The '<tt>inttoptr</tt>' instruction takes an <a href="i_integer">integer</a>
3053 value to cast, and a type to cast it to, which must be a
3054 <a href="#t_pointer">pointer</a> type. </tt>
3055
3056 <h5>Semantics:</h5>
3057 <p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type
3058 <tt>ty2</tt> by applying either a zero extension or a truncation depending on
3059 the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the
3060 size of a pointer then a truncation is done. If <tt>value</tt> is smaller than
3061 the size of a pointer then a zero extension is done. If they are the same size,
3062 nothing is done (<i>no-op cast</i>).</p>
3063
3064 <h5>Example:</h5>
3065 <pre>
3066   %X = inttoptr i32 255 to i32*            <i>; yields zero extend on 64-bit</i>
3067   %X = inttoptr i32 255 to i32*            <i>; yields no-op on 32-bit </i>
3068   %Y = inttoptr i16 0 to i32*            <i>; yields zero extend on 32-bit</i>
3069 </pre>
3070 </div>
3071
3072 <!-- _______________________________________________________________________ -->
3073 <div class="doc_subsubsection">
3074    <a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a>
3075 </div>
3076 <div class="doc_text">
3077
3078 <h5>Syntax:</h5>
3079 <pre>
3080   &lt;result&gt; = bitcast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
3081 </pre>
3082
3083 <h5>Overview:</h5>
3084 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
3085 <tt>ty2</tt> without changing any bits.</p>
3086
3087 <h5>Arguments:</h5>
3088 <p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be
3089 a first class value, and a type to cast it to, which must also be a <a
3090   href="#t_firstclass">first class</a> type. The bit sizes of <tt>value</tt>
3091 and the destination type, <tt>ty2</tt>, must be identical.</p>
3092
3093 <h5>Semantics:</h5>
3094 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
3095 <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with
3096 this conversion.  The conversion is done as if the <tt>value</tt> had been
3097 stored to memory and read back as type <tt>ty2</tt>. Pointer types may only be
3098 converted to other pointer types with this instruction. To convert pointers to
3099 other types, use the <a href="#i_inttoptr">inttoptr</a> or
3100 <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p>
3101
3102 <h5>Example:</h5>
3103 <pre>
3104   %X = bitcast i8 255 to i8          <i>; yields i8 :-1</i>
3105   %Y = bitcast i32* %x to sint*          <i>; yields sint*:%x</i>
3106   %Z = bitcast <2xint> %V to i64;        <i>; yields i64: %V</i>
3107 </pre>
3108 </div>
3109
3110 <!-- ======================================================================= -->
3111 <div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
3112 <div class="doc_text">
3113 <p>The instructions in this category are the "miscellaneous"
3114 instructions, which defy better classification.</p>
3115 </div>
3116
3117 <!-- _______________________________________________________________________ -->
3118 <div class="doc_subsubsection"><a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
3119 </div>
3120 <div class="doc_text">
3121 <h5>Syntax:</h5>
3122 <pre>  &lt;result&gt; = icmp &lt;cond&gt; &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
3123 </pre>
3124 <h5>Overview:</h5>
3125 <p>The '<tt>icmp</tt>' instruction returns a boolean value based on comparison
3126 of its two integer operands.</p>
3127 <h5>Arguments:</h5>
3128 <p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is
3129 the condition code which indicates the kind of comparison to perform. It is not
3130 a value, just a keyword. The possibilities for the condition code are:
3131 <ol>
3132   <li><tt>eq</tt>: equal</li>
3133   <li><tt>ne</tt>: not equal </li>
3134   <li><tt>ugt</tt>: unsigned greater than</li>
3135   <li><tt>uge</tt>: unsigned greater or equal</li>
3136   <li><tt>ult</tt>: unsigned less than</li>
3137   <li><tt>ule</tt>: unsigned less or equal</li>
3138   <li><tt>sgt</tt>: signed greater than</li>
3139   <li><tt>sge</tt>: signed greater or equal</li>
3140   <li><tt>slt</tt>: signed less than</li>
3141   <li><tt>sle</tt>: signed less or equal</li>
3142 </ol>
3143 <p>The remaining two arguments must be <a href="#t_integral">integral</a> or
3144 <a href="#t_pointer">pointer</a> typed. They must also be identical types.</p>
3145 <h5>Semantics:</h5>
3146 <p>The '<tt>icmp</tt>' compares <tt>var1</tt> and <tt>var2</tt> according to
3147 the condition code given as <tt>cond</tt>. The comparison performed always
3148 yields a <a href="#t_bool">bool</a> result, as follows:
3149 <ol>
3150   <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
3151   <tt>false</tt> otherwise. No sign interpretation is necessary or performed.
3152   </li>
3153   <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
3154   <tt>false</tt> otherwise. No sign interpretation is necessary or performed.
3155   <li><tt>ugt</tt>: interprets the operands as unsigned values and yields
3156   <tt>true</tt> if <tt>var1</tt> is greater than <tt>var2</tt>.</li>
3157   <li><tt>uge</tt>: interprets the operands as unsigned values and yields
3158   <tt>true</tt> if <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3159   <li><tt>ult</tt>: interprets the operands as unsigned values and yields
3160   <tt>true</tt> if <tt>var1</tt> is less than <tt>var2</tt>.</li>
3161   <li><tt>ule</tt>: interprets the operands as unsigned values and yields
3162   <tt>true</tt> if <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3163   <li><tt>sgt</tt>: interprets the operands as signed values and yields
3164   <tt>true</tt> if <tt>var1</tt> is greater than <tt>var2</tt>.</li>
3165   <li><tt>sge</tt>: interprets the operands as signed values and yields
3166   <tt>true</tt> if <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3167   <li><tt>slt</tt>: interprets the operands as signed values and yields
3168   <tt>true</tt> if <tt>var1</tt> is less than <tt>var2</tt>.</li>
3169   <li><tt>sle</tt>: interprets the operands as signed values and yields
3170   <tt>true</tt> if <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3171   </li>
3172 </ol>
3173 <p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer
3174 values are treated as integers and then compared.</p>
3175 <p>If the operands are <a href="#t_packed">packed</a> typed, the elements of
3176 the vector are compared in turn and the predicate must hold for all
3177 elements.</p>
3178
3179 <h5>Example:</h5>
3180 <pre>  &lt;result&gt; = icmp eq i32 4, 5          <i>; yields: result=false</i>
3181   &lt;result&gt; = icmp ne float* %X, %X     <i>; yields: result=false</i>
3182   &lt;result&gt; = icmp ult i16  4, 5        <i>; yields: result=true</i>
3183   &lt;result&gt; = icmp sgt i16  4, 5        <i>; yields: result=false</i>
3184   &lt;result&gt; = icmp ule i16 -4, 5        <i>; yields: result=false</i>
3185   &lt;result&gt; = icmp sge i16  4, 5        <i>; yields: result=false</i>
3186 </pre>
3187 </div>
3188
3189 <!-- _______________________________________________________________________ -->
3190 <div class="doc_subsubsection"><a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
3191 </div>
3192 <div class="doc_text">
3193 <h5>Syntax:</h5>
3194 <pre>  &lt;result&gt; = fcmp &lt;cond&gt; &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
3195 </pre>
3196 <h5>Overview:</h5>
3197 <p>The '<tt>fcmp</tt>' instruction returns a boolean value based on comparison
3198 of its floating point operands.</p>
3199 <h5>Arguments:</h5>
3200 <p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is
3201 the condition code which indicates the kind of comparison to perform. It is not
3202 a value, just a keyword. The possibilities for the condition code are:
3203 <ol>
3204   <li><tt>false</tt>: no comparison, always returns false</li>
3205   <li><tt>oeq</tt>: ordered and equal</li>
3206   <li><tt>ogt</tt>: ordered and greater than </li>
3207   <li><tt>oge</tt>: ordered and greater than or equal</li>
3208   <li><tt>olt</tt>: ordered and less than </li>
3209   <li><tt>ole</tt>: ordered and less than or equal</li>
3210   <li><tt>one</tt>: ordered and not equal</li>
3211   <li><tt>ord</tt>: ordered (no nans)</li>
3212   <li><tt>ueq</tt>: unordered or equal</li>
3213   <li><tt>ugt</tt>: unordered or greater than </li>
3214   <li><tt>uge</tt>: unordered or greater than or equal</li>
3215   <li><tt>ult</tt>: unordered or less than </li>
3216   <li><tt>ule</tt>: unordered or less than or equal</li>
3217   <li><tt>une</tt>: unordered or not equal</li>
3218   <li><tt>uno</tt>: unordered (either nans)</li>
3219   <li><tt>true</tt>: no comparison, always returns true</li>
3220 </ol>
3221 <p>In the preceding, <i>ordered</i> means that neither operand is a QNAN while
3222 <i>unordered</i> means that either operand may be a QNAN.</p>
3223 <p>The <tt>val1</tt> and <tt>val2</tt> arguments must be
3224 <a href="#t_floating">floating point</a> typed.  They must have identical
3225 types.</p>
3226 <p>In the foregoing, <i>ordered</i> means that neither operand is a QNAN and
3227 <i>unordered</i> means that either operand is a QNAN.</p>
3228 <h5>Semantics:</h5>
3229 <p>The '<tt>fcmp</tt>' compares <tt>var1</tt> and <tt>var2</tt> according to
3230 the condition code given as <tt>cond</tt>. The comparison performed always
3231 yields a <a href="#t_bool">bool</a> result, as follows:
3232 <ol>
3233   <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
3234   <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3235   <tt>var1</tt> is equal to <tt>var2</tt>.</li>
3236   <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3237   <tt>var1</tt> is greather than <tt>var2</tt>.</li>
3238   <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3239   <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3240   <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3241   <tt>var1</tt> is less than <tt>var2</tt>.</li>
3242   <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3243   <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3244   <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3245   <tt>var1</tt> is not equal to <tt>var2</tt>.</li>
3246   <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
3247   <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
3248   <tt>var1</tt> is equal to <tt>var2</tt>.</li>
3249   <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
3250   <tt>var1</tt> is greater than <tt>var2</tt>.</li>
3251   <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
3252   <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3253   <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
3254   <tt>var1</tt> is less than <tt>var2</tt>.</li>
3255   <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
3256   <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3257   <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
3258   <tt>var1</tt> is not equal to <tt>var2</tt>.</li>
3259   <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
3260   <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li>
3261 </ol>
3262 <p>If the operands are <a href="#t_packed">packed</a> typed, the elements of
3263 the vector are compared in turn and the predicate must hold for all elements.
3264 </p>
3265
3266 <h5>Example:</h5>
3267 <pre>  &lt;result&gt; = fcmp oeq float 4.0, 5.0    <i>; yields: result=false</i>
3268   &lt;result&gt; = icmp one float 4.0, 5.0    <i>; yields: result=true</i>
3269   &lt;result&gt; = icmp olt float 4.0, 5.0    <i>; yields: result=true</i>
3270   &lt;result&gt; = icmp ueq double 1.0, 2.0   <i>; yields: result=false</i>
3271 </pre>
3272 </div>
3273
3274 <!-- _______________________________________________________________________ -->
3275 <div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>'
3276 Instruction</a> </div>
3277 <div class="doc_text">
3278 <h5>Syntax:</h5>
3279 <pre>  &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...<br></pre>
3280 <h5>Overview:</h5>
3281 <p>The '<tt>phi</tt>' instruction is used to implement the &#966; node in
3282 the SSA graph representing the function.</p>
3283 <h5>Arguments:</h5>
3284 <p>The type of the incoming values are specified with the first type
3285 field. After this, the '<tt>phi</tt>' instruction takes a list of pairs
3286 as arguments, with one pair for each predecessor basic block of the
3287 current block.  Only values of <a href="#t_firstclass">first class</a>
3288 type may be used as the value arguments to the PHI node.  Only labels
3289 may be used as the label arguments.</p>
3290 <p>There must be no non-phi instructions between the start of a basic
3291 block and the PHI instructions: i.e. PHI instructions must be first in
3292 a basic block.</p>
3293 <h5>Semantics:</h5>
3294 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the
3295 value specified by the parameter, depending on which basic block we
3296 came from in the last <a href="#terminators">terminator</a> instruction.</p>
3297 <h5>Example:</h5>
3298 <pre>Loop:       ; Infinite loop that counts from 0 on up...<br>  %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]<br>  %nextindvar = add i32 %indvar, 1<br>  br label %Loop<br></pre>
3299 </div>
3300
3301 <!-- _______________________________________________________________________ -->
3302 <div class="doc_subsubsection">
3303    <a name="i_select">'<tt>select</tt>' Instruction</a>
3304 </div>
3305
3306 <div class="doc_text">
3307
3308 <h5>Syntax:</h5>
3309
3310 <pre>
3311   &lt;result&gt; = select bool &lt;cond&gt;, &lt;ty&gt; &lt;val1&gt;, &lt;ty&gt; &lt;val2&gt;             <i>; yields ty</i>
3312 </pre>
3313
3314 <h5>Overview:</h5>
3315
3316 <p>
3317 The '<tt>select</tt>' instruction is used to choose one value based on a
3318 condition, without branching.
3319 </p>
3320
3321
3322 <h5>Arguments:</h5>
3323
3324 <p>
3325 The '<tt>select</tt>' instruction requires a boolean value indicating the condition, and two values of the same <a href="#t_firstclass">first class</a> type.
3326 </p>
3327
3328 <h5>Semantics:</h5>
3329
3330 <p>
3331 If the boolean condition evaluates to true, the instruction returns the first
3332 value argument; otherwise, it returns the second value argument.
3333 </p>
3334
3335 <h5>Example:</h5>
3336
3337 <pre>
3338   %X = select bool true, i8 17, i8 42          <i>; yields i8:17</i>
3339 </pre>
3340 </div>
3341
3342
3343 <!-- _______________________________________________________________________ -->
3344 <div class="doc_subsubsection">
3345   <a name="i_call">'<tt>call</tt>' Instruction</a>
3346 </div>
3347
3348 <div class="doc_text">
3349
3350 <h5>Syntax:</h5>
3351 <pre>
3352   &lt;result&gt; = [tail] call [<a href="#callingconv">cconv</a>] &lt;ty&gt;* &lt;fnptrval&gt;(&lt;param list&gt;)
3353 </pre>
3354
3355 <h5>Overview:</h5>
3356
3357 <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
3358
3359 <h5>Arguments:</h5>
3360
3361 <p>This instruction requires several arguments:</p>
3362
3363 <ol>
3364   <li>
3365     <p>The optional "tail" marker indicates whether the callee function accesses
3366     any allocas or varargs in the caller.  If the "tail" marker is present, the
3367     function call is eligible for tail call optimization.  Note that calls may
3368     be marked "tail" even if they do not occur before a <a
3369     href="#i_ret"><tt>ret</tt></a> instruction.
3370   </li>
3371   <li>
3372     <p>The optional "cconv" marker indicates which <a href="callingconv">calling
3373     convention</a> the call should use.  If none is specified, the call defaults
3374     to using C calling conventions.
3375   </li>
3376   <li>
3377     <p>'<tt>ty</tt>': shall be the signature of the pointer to function value
3378     being invoked.  The argument types must match the types implied by this
3379     signature.  This type can be omitted if the function is not varargs and
3380     if the function type does not return a pointer to a function.</p>
3381   </li>
3382   <li>
3383     <p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to
3384     be invoked. In most cases, this is a direct function invocation, but
3385     indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer
3386     to function value.</p>
3387   </li>
3388   <li>
3389     <p>'<tt>function args</tt>': argument list whose types match the
3390     function signature argument types. All arguments must be of
3391     <a href="#t_firstclass">first class</a> type. If the function signature
3392     indicates the function accepts a variable number of arguments, the extra
3393     arguments can be specified.</p>
3394   </li>
3395 </ol>
3396
3397 <h5>Semantics:</h5>
3398
3399 <p>The '<tt>call</tt>' instruction is used to cause control flow to
3400 transfer to a specified function, with its incoming arguments bound to
3401 the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>'
3402 instruction in the called function, control flow continues with the
3403 instruction after the function call, and the return value of the
3404 function is bound to the result argument.  This is a simpler case of
3405 the <a href="#i_invoke">invoke</a> instruction.</p>
3406
3407 <h5>Example:</h5>
3408
3409 <pre>
3410   %retval = call i32 %test(i32 %argc)
3411   call i32(i8 *, ...) *%printf(i8 * %msg, i32 12, i8  42);
3412   %X = tail call i32 %foo()
3413   %Y = tail call <a href="#callingconv">fastcc</a> i32 %foo()
3414 </pre>
3415
3416 </div>
3417
3418 <!-- _______________________________________________________________________ -->
3419 <div class="doc_subsubsection">
3420   <a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
3421 </div>
3422
3423 <div class="doc_text">
3424
3425 <h5>Syntax:</h5>
3426
3427 <pre>
3428   &lt;resultval&gt; = va_arg &lt;va_list*&gt; &lt;arglist&gt;, &lt;argty&gt;
3429 </pre>
3430
3431 <h5>Overview:</h5>
3432
3433 <p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through
3434 the "variable argument" area of a function call.  It is used to implement the
3435 <tt>va_arg</tt> macro in C.</p>
3436
3437 <h5>Arguments:</h5>
3438
3439 <p>This instruction takes a <tt>va_list*</tt> value and the type of
3440 the argument. It returns a value of the specified argument type and
3441 increments the <tt>va_list</tt> to point to the next argument.  Again, the
3442 actual type of <tt>va_list</tt> is target specific.</p>
3443
3444 <h5>Semantics:</h5>
3445
3446 <p>The '<tt>va_arg</tt>' instruction loads an argument of the specified
3447 type from the specified <tt>va_list</tt> and causes the
3448 <tt>va_list</tt> to point to the next argument.  For more information,
3449 see the variable argument handling <a href="#int_varargs">Intrinsic
3450 Functions</a>.</p>
3451
3452 <p>It is legal for this instruction to be called in a function which does not
3453 take a variable number of arguments, for example, the <tt>vfprintf</tt>
3454 function.</p>
3455
3456 <p><tt>va_arg</tt> is an LLVM instruction instead of an <a
3457 href="#intrinsics">intrinsic function</a> because it takes a type as an
3458 argument.</p>
3459
3460 <h5>Example:</h5>
3461
3462 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
3463
3464 </div>
3465
3466 <!-- *********************************************************************** -->
3467 <div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
3468 <!-- *********************************************************************** -->
3469
3470 <div class="doc_text">
3471
3472 <p>LLVM supports the notion of an "intrinsic function".  These functions have
3473 well known names and semantics and are required to follow certain
3474 restrictions. Overall, these instructions represent an extension mechanism for
3475 the LLVM language that does not require changing all of the transformations in
3476 LLVM to add to the language (or the bytecode reader/writer, the parser,
3477 etc...).</p>
3478
3479 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
3480 prefix is reserved in LLVM for intrinsic names; thus, functions may not be named
3481 this.  Intrinsic functions must always be external functions: you cannot define
3482 the body of intrinsic functions.  Intrinsic functions may only be used in call
3483 or invoke instructions: it is illegal to take the address of an intrinsic
3484 function.  Additionally, because intrinsic functions are part of the LLVM
3485 language, it is required that they all be documented here if any are added.</p>
3486
3487
3488 <p>To learn how to add an intrinsic function, please see the <a
3489 href="ExtendingLLVM.html">Extending LLVM Guide</a>.
3490 </p>
3491
3492 </div>
3493
3494 <!-- ======================================================================= -->
3495 <div class="doc_subsection">
3496   <a name="int_varargs">Variable Argument Handling Intrinsics</a>
3497 </div>
3498
3499 <div class="doc_text">
3500
3501 <p>Variable argument support is defined in LLVM with the <a
3502  href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
3503 intrinsic functions.  These functions are related to the similarly
3504 named macros defined in the <tt>&lt;stdarg.h&gt;</tt> header file.</p>
3505
3506 <p>All of these functions operate on arguments that use a
3507 target-specific value type "<tt>va_list</tt>".  The LLVM assembly
3508 language reference manual does not define what this type is, so all
3509 transformations should be prepared to handle intrinsics with any type
3510 used.</p>
3511
3512 <p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a>
3513 instruction and the variable argument handling intrinsic functions are
3514 used.</p>
3515
3516 <pre>
3517 define i32 %test(i32 %X, ...) {
3518   ; Initialize variable argument processing
3519   %ap = alloca i8 *
3520   call void %<a href="#i_va_start">llvm.va_start</a>(i8 ** %ap)
3521
3522   ; Read a single integer argument
3523   %tmp = va_arg i8 ** %ap, i32
3524
3525   ; Demonstrate usage of llvm.va_copy and llvm.va_end
3526   %aq = alloca i8 *
3527   call void %<a href="#i_va_copy">llvm.va_copy</a>(i8 ** %aq, i8 ** %ap)
3528   call void %<a href="#i_va_end">llvm.va_end</a>(i8 ** %aq)
3529
3530   ; Stop processing of arguments.
3531   call void %<a href="#i_va_end">llvm.va_end</a>(i8 ** %ap)
3532   ret i32 %tmp
3533 }
3534 </pre>
3535 </div>
3536
3537 <!-- _______________________________________________________________________ -->
3538 <div class="doc_subsubsection">
3539   <a name="i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
3540 </div>
3541
3542
3543 <div class="doc_text">
3544 <h5>Syntax:</h5>
3545 <pre>  declare void %llvm.va_start(&lt;va_list&gt;* &lt;arglist&gt;)<br></pre>
3546 <h5>Overview:</h5>
3547 <P>The '<tt>llvm.va_start</tt>' intrinsic initializes
3548 <tt>*&lt;arglist&gt;</tt> for subsequent use by <tt><a
3549 href="#i_va_arg">va_arg</a></tt>.</p>
3550
3551 <h5>Arguments:</h5>
3552
3553 <P>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
3554
3555 <h5>Semantics:</h5>
3556
3557 <P>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
3558 macro available in C.  In a target-dependent way, it initializes the
3559 <tt>va_list</tt> element the argument points to, so that the next call to
3560 <tt>va_arg</tt> will produce the first variable argument passed to the function.
3561 Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the
3562 last argument of the function, the compiler can figure that out.</p>
3563
3564 </div>
3565
3566 <!-- _______________________________________________________________________ -->
3567 <div class="doc_subsubsection">
3568  <a name="i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
3569 </div>
3570
3571 <div class="doc_text">
3572 <h5>Syntax:</h5>
3573 <pre>  declare void %llvm.va_end(&lt;va_list*&gt; &lt;arglist&gt;)<br></pre>
3574 <h5>Overview:</h5>
3575 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>&lt;arglist&gt;</tt>
3576 which has been initialized previously with <tt><a href="#i_va_start">llvm.va_start</a></tt>
3577 or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
3578 <h5>Arguments:</h5>
3579 <p>The argument is a <tt>va_list</tt> to destroy.</p>
3580 <h5>Semantics:</h5>
3581 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
3582 macro available in C.  In a target-dependent way, it destroys the <tt>va_list</tt>.
3583 Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
3584  href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly
3585 with calls to <tt>llvm.va_end</tt>.</p>
3586 </div>
3587
3588 <!-- _______________________________________________________________________ -->
3589 <div class="doc_subsubsection">
3590   <a name="i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
3591 </div>
3592
3593 <div class="doc_text">
3594
3595 <h5>Syntax:</h5>
3596
3597 <pre>
3598   declare void %llvm.va_copy(&lt;va_list&gt;* &lt;destarglist&gt;,
3599                                           &lt;va_list&gt;* &lt;srcarglist&gt;)
3600 </pre>
3601
3602 <h5>Overview:</h5>
3603
3604 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position from
3605 the source argument list to the destination argument list.</p>
3606
3607 <h5>Arguments:</h5>
3608
3609 <p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
3610 The second argument is a pointer to a <tt>va_list</tt> element to copy from.</p>
3611
3612
3613 <h5>Semantics:</h5>
3614
3615 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> macro
3616 available in C.  In a target-dependent way, it copies the source
3617 <tt>va_list</tt> element into the destination list.  This intrinsic is necessary
3618 because the <tt><a href="i_va_begin">llvm.va_begin</a></tt> intrinsic may be
3619 arbitrarily complex and require memory allocation, for example.</p>
3620
3621 </div>
3622
3623 <!-- ======================================================================= -->
3624 <div class="doc_subsection">
3625   <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
3626 </div>
3627
3628 <div class="doc_text">
3629
3630 <p>
3631 LLVM support for <a href="GarbageCollection.html">Accurate Garbage
3632 Collection</a> requires the implementation and generation of these intrinsics.
3633 These intrinsics allow identification of <a href="#i_gcroot">GC roots on the
3634 stack</a>, as well as garbage collector implementations that require <a
3635 href="#i_gcread">read</a> and <a href="#i_gcwrite">write</a> barriers.
3636 Front-ends for type-safe garbage collected languages should generate these
3637 intrinsics to make use of the LLVM garbage collectors.  For more details, see <a
3638 href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>.
3639 </p>
3640 </div>
3641
3642 <!-- _______________________________________________________________________ -->
3643 <div class="doc_subsubsection">
3644   <a name="i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
3645 </div>
3646
3647 <div class="doc_text">
3648
3649 <h5>Syntax:</h5>
3650
3651 <pre>
3652   declare void %llvm.gcroot(&lt;ty&gt;** %ptrloc, &lt;ty2&gt;* %metadata)
3653 </pre>
3654
3655 <h5>Overview:</h5>
3656
3657 <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
3658 the code generator, and allows some metadata to be associated with it.</p>
3659
3660 <h5>Arguments:</h5>
3661
3662 <p>The first argument specifies the address of a stack object that contains the
3663 root pointer.  The second pointer (which must be either a constant or a global
3664 value address) contains the meta-data to be associated with the root.</p>
3665
3666 <h5>Semantics:</h5>
3667
3668 <p>At runtime, a call to this intrinsics stores a null pointer into the "ptrloc"
3669 location.  At compile-time, the code generator generates information to allow
3670 the runtime to find the pointer at GC safe points.
3671 </p>
3672
3673 </div>
3674
3675
3676 <!-- _______________________________________________________________________ -->
3677 <div class="doc_subsubsection">
3678   <a name="i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
3679 </div>
3680
3681 <div class="doc_text">
3682
3683 <h5>Syntax:</h5>
3684
3685 <pre>
3686   declare i8 * %llvm.gcread(i8 * %ObjPtr, i8 ** %Ptr)
3687 </pre>
3688
3689 <h5>Overview:</h5>
3690
3691 <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
3692 locations, allowing garbage collector implementations that require read
3693 barriers.</p>
3694
3695 <h5>Arguments:</h5>
3696
3697 <p>The second argument is the address to read from, which should be an address
3698 allocated from the garbage collector.  The first object is a pointer to the
3699 start of the referenced object, if needed by the language runtime (otherwise
3700 null).</p>
3701
3702 <h5>Semantics:</h5>
3703
3704 <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
3705 instruction, but may be replaced with substantially more complex code by the
3706 garbage collector runtime, as needed.</p>
3707
3708 </div>
3709
3710
3711 <!-- _______________________________________________________________________ -->
3712 <div class="doc_subsubsection">
3713   <a name="i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
3714 </div>
3715
3716 <div class="doc_text">
3717
3718 <h5>Syntax:</h5>
3719
3720 <pre>
3721   declare void %llvm.gcwrite(i8 * %P1, i8 * %Obj, i8 ** %P2)
3722 </pre>
3723
3724 <h5>Overview:</h5>
3725
3726 <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
3727 locations, allowing garbage collector implementations that require write
3728 barriers (such as generational or reference counting collectors).</p>
3729
3730 <h5>Arguments:</h5>
3731
3732 <p>The first argument is the reference to store, the second is the start of the
3733 object to store it to, and the third is the address of the field of Obj to
3734 store to.  If the runtime does not require a pointer to the object, Obj may be
3735 null.</p>
3736
3737 <h5>Semantics:</h5>
3738
3739 <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
3740 instruction, but may be replaced with substantially more complex code by the
3741 garbage collector runtime, as needed.</p>
3742
3743 </div>
3744
3745
3746
3747 <!-- ======================================================================= -->
3748 <div class="doc_subsection">
3749   <a name="int_codegen">Code Generator Intrinsics</a>
3750 </div>
3751
3752 <div class="doc_text">
3753 <p>
3754 These intrinsics are provided by LLVM to expose special features that may only
3755 be implemented with code generator support.
3756 </p>
3757
3758 </div>
3759
3760 <!-- _______________________________________________________________________ -->
3761 <div class="doc_subsubsection">
3762   <a name="i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
3763 </div>
3764
3765 <div class="doc_text">
3766
3767 <h5>Syntax:</h5>
3768 <pre>
3769   declare i8  *%llvm.returnaddress(i32 &lt;level&gt;)
3770 </pre>
3771
3772 <h5>Overview:</h5>
3773
3774 <p>
3775 The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a
3776 target-specific value indicating the return address of the current function
3777 or one of its callers.
3778 </p>
3779
3780 <h5>Arguments:</h5>
3781
3782 <p>
3783 The argument to this intrinsic indicates which function to return the address
3784 for.  Zero indicates the calling function, one indicates its caller, etc.  The
3785 argument is <b>required</b> to be a constant integer value.
3786 </p>
3787
3788 <h5>Semantics:</h5>
3789
3790 <p>
3791 The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer indicating
3792 the return address of the specified call frame, or zero if it cannot be
3793 identified.  The value returned by this intrinsic is likely to be incorrect or 0
3794 for arguments other than zero, so it should only be used for debugging purposes.
3795 </p>
3796
3797 <p>
3798 Note that calling this intrinsic does not prevent function inlining or other
3799 aggressive transformations, so the value returned may not be that of the obvious
3800 source-language caller.
3801 </p>
3802 </div>
3803
3804
3805 <!-- _______________________________________________________________________ -->
3806 <div class="doc_subsubsection">
3807   <a name="i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
3808 </div>
3809
3810 <div class="doc_text">
3811
3812 <h5>Syntax:</h5>
3813 <pre>
3814   declare i8  *%llvm.frameaddress(i32 &lt;level&gt;)
3815 </pre>
3816
3817 <h5>Overview:</h5>
3818
3819 <p>
3820 The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the
3821 target-specific frame pointer value for the specified stack frame.
3822 </p>
3823
3824 <h5>Arguments:</h5>
3825
3826 <p>
3827 The argument to this intrinsic indicates which function to return the frame
3828 pointer for.  Zero indicates the calling function, one indicates its caller,
3829 etc.  The argument is <b>required</b> to be a constant integer value.
3830 </p>
3831
3832 <h5>Semantics:</h5>
3833
3834 <p>
3835 The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer indicating
3836 the frame address of the specified call frame, or zero if it cannot be
3837 identified.  The value returned by this intrinsic is likely to be incorrect or 0
3838 for arguments other than zero, so it should only be used for debugging purposes.
3839 </p>
3840
3841 <p>
3842 Note that calling this intrinsic does not prevent function inlining or other
3843 aggressive transformations, so the value returned may not be that of the obvious
3844 source-language caller.
3845 </p>
3846 </div>
3847
3848 <!-- _______________________________________________________________________ -->
3849 <div class="doc_subsubsection">
3850   <a name="i_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
3851 </div>
3852
3853 <div class="doc_text">
3854
3855 <h5>Syntax:</h5>
3856 <pre>
3857   declare i8  *%llvm.stacksave()
3858 </pre>
3859
3860 <h5>Overview:</h5>
3861
3862 <p>
3863 The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state of
3864 the function stack, for use with <a href="#i_stackrestore">
3865 <tt>llvm.stackrestore</tt></a>.  This is useful for implementing language
3866 features like scoped automatic variable sized arrays in C99.
3867 </p>
3868
3869 <h5>Semantics:</h5>
3870
3871 <p>
3872 This intrinsic returns a opaque pointer value that can be passed to <a
3873 href="#i_stackrestore"><tt>llvm.stackrestore</tt></a>.  When an
3874 <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved from
3875 <tt>llvm.stacksave</tt>, it effectively restores the state of the stack to the
3876 state it was in when the <tt>llvm.stacksave</tt> intrinsic executed.  In
3877 practice, this pops any <a href="#i_alloca">alloca</a> blocks from the stack
3878 that were allocated after the <tt>llvm.stacksave</tt> was executed.
3879 </p>
3880
3881 </div>
3882
3883 <!-- _______________________________________________________________________ -->
3884 <div class="doc_subsubsection">
3885   <a name="i_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
3886 </div>
3887
3888 <div class="doc_text">
3889
3890 <h5>Syntax:</h5>
3891 <pre>
3892   declare void %llvm.stackrestore(i8 * %ptr)
3893 </pre>
3894
3895 <h5>Overview:</h5>
3896
3897 <p>
3898 The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of
3899 the function stack to the state it was in when the corresponding <a
3900 href="#llvm.stacksave"><tt>llvm.stacksave</tt></a> intrinsic executed.  This is
3901 useful for implementing language features like scoped automatic variable sized
3902 arrays in C99.
3903 </p>
3904
3905 <h5>Semantics:</h5>
3906
3907 <p>
3908 See the description for <a href="#i_stacksave"><tt>llvm.stacksave</tt></a>.
3909 </p>
3910
3911 </div>
3912
3913
3914 <!-- _______________________________________________________________________ -->
3915 <div class="doc_subsubsection">
3916   <a name="i_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
3917 </div>
3918
3919 <div class="doc_text">
3920
3921 <h5>Syntax:</h5>
3922 <pre>
3923   declare void %llvm.prefetch(i8  * &lt;address&gt;,
3924                                 i32 &lt;rw&gt;, i32 &lt;locality&gt;)
3925 </pre>
3926
3927 <h5>Overview:</h5>
3928
3929
3930 <p>
3931 The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to insert
3932 a prefetch instruction if supported; otherwise, it is a noop.  Prefetches have
3933 no
3934 effect on the behavior of the program but can change its performance
3935 characteristics.
3936 </p>
3937
3938 <h5>Arguments:</h5>
3939
3940 <p>
3941 <tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the specifier
3942 determining if the fetch should be for a read (0) or write (1), and
3943 <tt>locality</tt> is a temporal locality specifier ranging from (0) - no
3944 locality, to (3) - extremely local keep in cache.  The <tt>rw</tt> and
3945 <tt>locality</tt> arguments must be constant integers.
3946 </p>
3947
3948 <h5>Semantics:</h5>
3949
3950 <p>
3951 This intrinsic does not modify the behavior of the program.  In particular,
3952 prefetches cannot trap and do not produce a value.  On targets that support this
3953 intrinsic, the prefetch can provide hints to the processor cache for better
3954 performance.
3955 </p>
3956
3957 </div>
3958
3959 <!-- _______________________________________________________________________ -->
3960 <div class="doc_subsubsection">
3961   <a name="i_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
3962 </div>
3963
3964 <div class="doc_text">
3965
3966 <h5>Syntax:</h5>
3967 <pre>
3968   declare void %llvm.pcmarker( i32 &lt;id&gt; )
3969 </pre>
3970
3971 <h5>Overview:</h5>
3972
3973
3974 <p>
3975 The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program Counter
3976 (PC) in a region of
3977 code to simulators and other tools.  The method is target specific, but it is
3978 expected that the marker will use exported symbols to transmit the PC of the marker.
3979 The marker makes no guarantees that it will remain with any specific instruction
3980 after optimizations.  It is possible that the presence of a marker will inhibit
3981 optimizations.  The intended use is to be inserted after optimizations to allow
3982 correlations of simulation runs.
3983 </p>
3984
3985 <h5>Arguments:</h5>
3986
3987 <p>
3988 <tt>id</tt> is a numerical id identifying the marker.
3989 </p>
3990
3991 <h5>Semantics:</h5>
3992
3993 <p>
3994 This intrinsic does not modify the behavior of the program.  Backends that do not
3995 support this intrinisic may ignore it.
3996 </p>
3997
3998 </div>
3999
4000 <!-- _______________________________________________________________________ -->
4001 <div class="doc_subsubsection">
4002   <a name="i_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
4003 </div>
4004
4005 <div class="doc_text">
4006
4007 <h5>Syntax:</h5>
4008 <pre>
4009   declare i64 %llvm.readcyclecounter( )
4010 </pre>
4011
4012 <h5>Overview:</h5>
4013
4014
4015 <p>
4016 The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle
4017 counter register (or similar low latency, high accuracy clocks) on those targets
4018 that support it.  On X86, it should map to RDTSC.  On Alpha, it should map to RPCC.
4019 As the backing counters overflow quickly (on the order of 9 seconds on alpha), this
4020 should only be used for small timings.
4021 </p>
4022
4023 <h5>Semantics:</h5>
4024
4025 <p>
4026 When directly supported, reading the cycle counter should not modify any memory.
4027 Implementations are allowed to either return a application specific value or a
4028 system wide value.  On backends without support, this is lowered to a constant 0.
4029 </p>
4030
4031 </div>
4032
4033 <!-- ======================================================================= -->
4034 <div class="doc_subsection">
4035   <a name="int_libc">Standard C Library Intrinsics</a>
4036 </div>
4037
4038 <div class="doc_text">
4039 <p>
4040 LLVM provides intrinsics for a few important standard C library functions.
4041 These intrinsics allow source-language front-ends to pass information about the
4042 alignment of the pointer arguments to the code generator, providing opportunity
4043 for more efficient code generation.
4044 </p>
4045
4046 </div>
4047
4048 <!-- _______________________________________________________________________ -->
4049 <div class="doc_subsubsection">
4050   <a name="i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
4051 </div>
4052
4053 <div class="doc_text">
4054
4055 <h5>Syntax:</h5>
4056 <pre>
4057   declare void %llvm.memcpy.i32(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
4058                                 i32 &lt;len&gt;, i32 &lt;align&gt;)
4059   declare void %llvm.memcpy.i64(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
4060                                 i64 &lt;len&gt;, i32 &lt;align&gt;)
4061 </pre>
4062
4063 <h5>Overview:</h5>
4064
4065 <p>
4066 The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source
4067 location to the destination location.
4068 </p>
4069
4070 <p>
4071 Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
4072 intrinsics do not return a value, and takes an extra alignment argument.
4073 </p>
4074
4075 <h5>Arguments:</h5>
4076
4077 <p>
4078 The first argument is a pointer to the destination, the second is a pointer to
4079 the source.  The third argument is an integer argument
4080 specifying the number of bytes to copy, and the fourth argument is the alignment
4081 of the source and destination locations.
4082 </p>
4083
4084 <p>
4085 If the call to this intrinisic has an alignment value that is not 0 or 1, then
4086 the caller guarantees that both the source and destination pointers are aligned
4087 to that boundary.
4088 </p>
4089
4090 <h5>Semantics:</h5>
4091
4092 <p>
4093 The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source
4094 location to the destination location, which are not allowed to overlap.  It
4095 copies "len" bytes of memory over.  If the argument is known to be aligned to
4096 some boundary, this can be specified as the fourth argument, otherwise it should
4097 be set to 0 or 1.
4098 </p>
4099 </div>
4100
4101
4102 <!-- _______________________________________________________________________ -->
4103 <div class="doc_subsubsection">
4104   <a name="i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
4105 </div>
4106
4107 <div class="doc_text">
4108
4109 <h5>Syntax:</h5>
4110 <pre>
4111   declare void %llvm.memmove.i32(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
4112                                  i32 &lt;len&gt;, i32 &lt;align&gt;)
4113   declare void %llvm.memmove.i64(i8 * &lt;dest&gt;, i8 * &lt;src&gt;,
4114                                  i64 &lt;len&gt;, i32 &lt;align&gt;)
4115 </pre>
4116
4117 <h5>Overview:</h5>
4118
4119 <p>
4120 The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the source
4121 location to the destination location. It is similar to the
4122 '<tt>llvm.memcmp</tt>' intrinsic but allows the two memory locations to overlap.
4123 </p>
4124
4125 <p>
4126 Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
4127 intrinsics do not return a value, and takes an extra alignment argument.
4128 </p>
4129
4130 <h5>Arguments:</h5>
4131
4132 <p>
4133 The first argument is a pointer to the destination, the second is a pointer to
4134 the source.  The third argument is an integer argument
4135 specifying the number of bytes to copy, and the fourth argument is the alignment
4136 of the source and destination locations.
4137 </p>
4138
4139 <p>
4140 If the call to this intrinisic has an alignment value that is not 0 or 1, then
4141 the caller guarantees that the source and destination pointers are aligned to
4142 that boundary.
4143 </p>
4144
4145 <h5>Semantics:</h5>
4146
4147 <p>
4148 The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the source
4149 location to the destination location, which may overlap.  It
4150 copies "len" bytes of memory over.  If the argument is known to be aligned to
4151 some boundary, this can be specified as the fourth argument, otherwise it should
4152 be set to 0 or 1.
4153 </p>
4154 </div>
4155
4156
4157 <!-- _______________________________________________________________________ -->
4158 <div class="doc_subsubsection">
4159   <a name="i_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
4160 </div>
4161
4162 <div class="doc_text">
4163
4164 <h5>Syntax:</h5>
4165 <pre>
4166   declare void %llvm.memset.i32(i8 * &lt;dest&gt;, i8 &lt;val&gt;,
4167                                 i32 &lt;len&gt;, i32 &lt;align&gt;)
4168   declare void %llvm.memset.i64(i8 * &lt;dest&gt;, i8 &lt;val&gt;,
4169                                 i64 &lt;len&gt;, i32 &lt;align&gt;)
4170 </pre>
4171
4172 <h5>Overview:</h5>
4173
4174 <p>
4175 The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a particular
4176 byte value.
4177 </p>
4178
4179 <p>
4180 Note that, unlike the standard libc function, the <tt>llvm.memset</tt> intrinsic
4181 does not return a value, and takes an extra alignment argument.
4182 </p>
4183
4184 <h5>Arguments:</h5>
4185
4186 <p>
4187 The first argument is a pointer to the destination to fill, the second is the
4188 byte value to fill it with, the third argument is an integer
4189 argument specifying the number of bytes to fill, and the fourth argument is the
4190 known alignment of destination location.
4191 </p>
4192
4193 <p>
4194 If the call to this intrinisic has an alignment value that is not 0 or 1, then
4195 the caller guarantees that the destination pointer is aligned to that boundary.
4196 </p>
4197
4198 <h5>Semantics:</h5>
4199
4200 <p>
4201 The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting at
4202 the
4203 destination location.  If the argument is known to be aligned to some boundary,
4204 this can be specified as the fourth argument, otherwise it should be set to 0 or
4205 1.
4206 </p>
4207 </div>
4208
4209
4210 <!-- _______________________________________________________________________ -->
4211 <div class="doc_subsubsection">
4212   <a name="i_isunordered">'<tt>llvm.isunordered.*</tt>' Intrinsic</a>
4213 </div>
4214
4215 <div class="doc_text">
4216
4217 <h5>Syntax:</h5>
4218 <pre>
4219   declare bool %llvm.isunordered.f32(float Val1, float  Val2)
4220   declare bool %llvm.isunordered.f64(double Val1, double Val2)
4221 </pre>
4222
4223 <h5>Overview:</h5>
4224
4225 <p>
4226 The '<tt>llvm.isunordered</tt>' intrinsics return true if either or both of the
4227 specified floating point values is a NAN.
4228 </p>
4229
4230 <h5>Arguments:</h5>
4231
4232 <p>
4233 The arguments are floating point numbers of the same type.
4234 </p>
4235
4236 <h5>Semantics:</h5>
4237
4238 <p>
4239 If either or both of the arguments is a SNAN or QNAN, it returns true, otherwise
4240 false.
4241 </p>
4242 </div>
4243
4244
4245 <!-- _______________________________________________________________________ -->
4246 <div class="doc_subsubsection">
4247   <a name="i_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
4248 </div>
4249
4250 <div class="doc_text">
4251
4252 <h5>Syntax:</h5>
4253 <pre>
4254   declare float %llvm.sqrt.f32(float %Val)
4255   declare double %llvm.sqrt.f64(double %Val)
4256 </pre>
4257
4258 <h5>Overview:</h5>
4259
4260 <p>
4261 The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand,
4262 returning the same value as the libm '<tt>sqrt</tt>' function would.  Unlike
4263 <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined behavior for
4264 negative numbers (which allows for better optimization).
4265 </p>
4266
4267 <h5>Arguments:</h5>
4268
4269 <p>
4270 The argument and return value are floating point numbers of the same type.
4271 </p>
4272
4273 <h5>Semantics:</h5>
4274
4275 <p>
4276 This function returns the sqrt of the specified operand if it is a positive
4277 floating point number.
4278 </p>
4279 </div>
4280
4281 <!-- _______________________________________________________________________ -->
4282 <div class="doc_subsubsection">
4283   <a name="i_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
4284 </div>
4285
4286 <div class="doc_text">
4287
4288 <h5>Syntax:</h5>
4289 <pre>
4290   declare float  %llvm.powi.f32(float  %Val, i32 %power)
4291   declare double %llvm.powi.f64(double %Val, i32 %power)
4292 </pre>
4293
4294 <h5>Overview:</h5>
4295
4296 <p>
4297 The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the
4298 specified (positive or negative) power.  The order of evaluation of
4299 multiplications is not defined.
4300 </p>
4301
4302 <h5>Arguments:</h5>
4303
4304 <p>
4305 The second argument is an integer power, and the first is a value to raise to
4306 that power.
4307 </p>
4308
4309 <h5>Semantics:</h5>
4310
4311 <p>
4312 This function returns the first value raised to the second power with an
4313 unspecified sequence of rounding operations.</p>
4314 </div>
4315
4316
4317 <!-- ======================================================================= -->
4318 <div class="doc_subsection">
4319   <a name="int_manip">Bit Manipulation Intrinsics</a>
4320 </div>
4321
4322 <div class="doc_text">
4323 <p>
4324 LLVM provides intrinsics for a few important bit manipulation operations.
4325 These allow efficient code generation for some algorithms.
4326 </p>
4327
4328 </div>
4329
4330 <!-- _______________________________________________________________________ -->
4331 <div class="doc_subsubsection">
4332   <a name="i_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
4333 </div>
4334
4335 <div class="doc_text">
4336
4337 <h5>Syntax:</h5>
4338 <pre>
4339   declare i16 %llvm.bswap.i16(i16 &lt;id&gt;)
4340   declare i32 %llvm.bswap.i32(i32 &lt;id&gt;)
4341   declare i64 %llvm.bswap.i64(i64 &lt;id&gt;)
4342 </pre>
4343
4344 <h5>Overview:</h5>
4345
4346 <p>
4347 The '<tt>llvm.bwsap</tt>' family of intrinsics is used to byteswap a 16, 32 or
4348 64 bit quantity.  These are useful for performing operations on data that is not
4349 in the target's  native byte order.
4350 </p>
4351
4352 <h5>Semantics:</h5>
4353
4354 <p>
4355 The <tt>llvm.bswap.16</tt> intrinsic returns an i16 value that has the high
4356 and low byte of the input i16 swapped.  Similarly, the <tt>llvm.bswap.i32</tt>
4357 intrinsic returns an i32 value that has the four bytes of the input i32
4358 swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the returned
4359 i32 will have its bytes in 3, 2, 1, 0 order.  The <tt>llvm.bswap.i64</tt>
4360 intrinsic extends this concept to 64 bits.
4361 </p>
4362
4363 </div>
4364
4365 <!-- _______________________________________________________________________ -->
4366 <div class="doc_subsubsection">
4367   <a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
4368 </div>
4369
4370 <div class="doc_text">
4371
4372 <h5>Syntax:</h5>
4373 <pre>
4374   declare i8  %llvm.ctpop.i8 (i8  &lt;src&gt;)
4375   declare i16 %llvm.ctpop.i16(i16 &lt;src&gt;)
4376   declare i32 %llvm.ctpop.i32(i32 &lt;src&gt;)
4377   declare i64 %llvm.ctpop.i64(i64 &lt;src&gt;)
4378 </pre>
4379
4380 <h5>Overview:</h5>
4381
4382 <p>
4383 The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set in a
4384 value.
4385 </p>
4386
4387 <h5>Arguments:</h5>
4388
4389 <p>
4390 The only argument is the value to be counted.  The argument may be of any
4391 integer type.  The return type must match the argument type.
4392 </p>
4393
4394 <h5>Semantics:</h5>
4395
4396 <p>
4397 The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.
4398 </p>
4399 </div>
4400
4401 <!-- _______________________________________________________________________ -->
4402 <div class="doc_subsubsection">
4403   <a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a>
4404 </div>
4405
4406 <div class="doc_text">
4407
4408 <h5>Syntax:</h5>
4409 <pre>
4410   declare i8  %llvm.ctlz.i8 (i8  &lt;src&gt;)
4411   declare i16 %llvm.ctlz.i16(i16 &lt;src&gt;)
4412   declare i32 %llvm.ctlz.i32(i32 &lt;src&gt;)
4413   declare i64 %llvm.ctlz.i64(i64 &lt;src&gt;)
4414 </pre>
4415
4416 <h5>Overview:</h5>
4417
4418 <p>
4419 The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of
4420 leading zeros in a variable.
4421 </p>
4422
4423 <h5>Arguments:</h5>
4424
4425 <p>
4426 The only argument is the value to be counted.  The argument may be of any
4427 integer type. The return type must match the argument type.
4428 </p>
4429
4430 <h5>Semantics:</h5>
4431
4432 <p>
4433 The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant) zeros
4434 in a variable.  If the src == 0 then the result is the size in bits of the type
4435 of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.
4436 </p>
4437 </div>
4438
4439
4440
4441 <!-- _______________________________________________________________________ -->
4442 <div class="doc_subsubsection">
4443   <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a>
4444 </div>
4445
4446 <div class="doc_text">
4447
4448 <h5>Syntax:</h5>
4449 <pre>
4450   declare i8  %llvm.cttz.i8 (i8  &lt;src&gt;)
4451   declare i16 %llvm.cttz.i16(i16 &lt;src&gt;)
4452   declare i32 %llvm.cttz.i32(i32 &lt;src&gt;)
4453   declare i64 %llvm.cttz.i64(i64 &lt;src&gt;)
4454 </pre>
4455
4456 <h5>Overview:</h5>
4457
4458 <p>
4459 The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of
4460 trailing zeros.
4461 </p>
4462
4463 <h5>Arguments:</h5>
4464
4465 <p>
4466 The only argument is the value to be counted.  The argument may be of any
4467 integer type.  The return type must match the argument type.
4468 </p>
4469
4470 <h5>Semantics:</h5>
4471
4472 <p>
4473 The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant) zeros
4474 in a variable.  If the src == 0 then the result is the size in bits of the type
4475 of src.  For example, <tt>llvm.cttz(2) = 1</tt>.
4476 </p>
4477 </div>
4478
4479 <!-- ======================================================================= -->
4480 <div class="doc_subsection">
4481   <a name="int_debugger">Debugger Intrinsics</a>
4482 </div>
4483
4484 <div class="doc_text">
4485 <p>
4486 The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> prefix),
4487 are described in the <a
4488 href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source Level
4489 Debugging</a> document.
4490 </p>
4491 </div>
4492
4493
4494 <!-- *********************************************************************** -->
4495 <hr>
4496 <address>
4497   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
4498   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
4499   <a href="http://validator.w3.org/check/referer"><img
4500   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
4501
4502   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
4503   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
4504   Last modified: $Date$
4505 </address>
4506 </body>
4507 </html>