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