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