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   <link rel="stylesheet" href="llvm.css" type="text/css">
   7 </head>
   8 <body>
   9
  10 <div class="doc_title">
  11   LLVM Language Reference Manual
  12 </div>
  13
  14 <ol>
  15   <li><a href="#abstract">Abstract</a></li>
  16   <li><a href="#introduction">Introduction</a></li>
  17   <li><a href="#identifiers">Identifiers</a></li>
  18   <li><a href="#typesystem">Type System</a>
  19     <ol>
  20       <li><a href="#t_primitive">Primitive Types</a>
  21         <ol>
  22           <li><a href="#t_classifications">Type Classifications</a></li>
  23         </ol></li>
  24       <li><a href="#t_derived">Derived Types</a>
  25         <ol>
  26           <li><a href="#t_array"  >Array Type</a></li>
  27           <li><a href="#t_function">Function Type</a></li>
  28           <li><a href="#t_pointer">Pointer Type</a></li>
  29           <li><a href="#t_struct" >Structure Type</a></li>
  30           <!-- <li><a href="#t_packed" >Packed Type</a> -->
  31         </ol></li>
  32     </ol></li>
  33   <li><a href="#highlevel">High Level Structure</a>
  34     <ol>
  35       <li><a href="#modulestructure">Module Structure</a></li>
  36       <li><a href="#globalvars">Global Variables</a></li>
  37       <li><a href="#functionstructure">Function Structure</a></li>
  38     </ol></li>
  39   <li><a href="#instref">Instruction Reference</a>
  40     <ol>
  41       <li><a href="#terminators">Terminator Instructions</a>
  42         <ol>
  43           <li><a href="#i_ret"   >'<tt>ret</tt>' Instruction</a></li>
  44           <li><a href="#i_br"    >'<tt>br</tt>' Instruction</a></li>
  45           <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
  46           <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
  47           <li><a href="#i_unwind"  >'<tt>unwind</tt>'  Instruction</a></li>
  48         </ol></li>
  49       <li><a href="#binaryops">Binary Operations</a>
  50         <ol>
  51           <li><a href="#i_add"  >'<tt>add</tt>' Instruction</a></li>
  52           <li><a href="#i_sub"  >'<tt>sub</tt>' Instruction</a></li>
  53           <li><a href="#i_mul"  >'<tt>mul</tt>' Instruction</a></li>
  54           <li><a href="#i_div"  >'<tt>div</tt>' Instruction</a></li>
  55           <li><a href="#i_rem"  >'<tt>rem</tt>' Instruction</a></li>
  56           <li><a href="#i_setcc">'<tt>set<i>cc</i></tt>' Instructions</a></li>
  57         </ol></li>
  58       <li><a href="#bitwiseops">Bitwise Binary Operations</a>
  59         <ol>
  60           <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
  61           <li><a href="#i_or" >'<tt>or</tt>'  Instruction</a></li>
  62           <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
  63           <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
  64           <li><a href="#i_shr">'<tt>shr</tt>' Instruction</a></li>
  65         </ol></li>
  66       <li><a href="#memoryops">Memory Access Operations</a>
  67         <ol>
  68           <li><a href="#i_malloc"  >'<tt>malloc</tt>'   Instruction</a></li>
  69           <li><a href="#i_free"    >'<tt>free</tt>'     Instruction</a></li>
  70           <li><a href="#i_alloca"  >'<tt>alloca</tt>'   Instruction</a></li>
  71           <li><a href="#i_load"    >'<tt>load</tt>'     Instruction</a></li>
  72           <li><a href="#i_store"   >'<tt>store</tt>'    Instruction</a></li>
  73           <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
  74         </ol></li>
  75       <li><a href="#otherops">Other Operations</a>
  76         <ol>
  77           <li><a href="#i_phi"  >'<tt>phi</tt>'   Instruction</a></li>
  78           <li><a href="#i_cast">'<tt>cast .. to</tt>' Instruction</a></li>
  79           <li><a href="#i_call" >'<tt>call</tt>'  Instruction</a></li>
  80           <li><a href="#i_vanext">'<tt>vanext</tt>' Instruction</a></li>
  81           <li><a href="#i_vaarg" >'<tt>vaarg</tt>'  Instruction</a></li>
  82         </ol>
  83     </ol>
  84   <li><a href="#intrinsics">Intrinsic Functions</a>
  85   <ol>
  86     <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
  87     <ol>
  88       <li><a href="#i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
  89       <li><a href="#i_va_end"  >'<tt>llvm.va_end</tt>'   Intrinsic</a></li>
  90       <li><a href="#i_va_copy" >'<tt>llvm.va_copy</tt>'  Intrinsic</a></li>
  91     </ol></li>
  92   </ol></li>
  93
  94 </ol>
  95
  96 <div class="doc_text">
  97   <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and <A href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></b><p>
  98 </div>
  99
 100 <!-- *********************************************************************** -->
 101 <div class="doc_section">
 102   <a name="abstract">Abstract
 103 </div>
 104 <!-- *********************************************************************** -->
 105
 106 <div class="doc_text">
 107
 108 <p>This document is a reference manual for the LLVM assembly language.  LLVM is
 109 an SSA based representation that provides type safety, low-level operations,
 110 flexibility, and the capability of representing 'all' high-level languages
 111 cleanly.  It is the common code representation used throughout all phases of the
 112 LLVM compilation strategy.</p>
 113
 114 </div>
 115
 116 <!-- *********************************************************************** -->
 117 <div class="doc_section">
 118   <a name="introduction">Introduction</a>
 119 </div>
 120 <!-- *********************************************************************** -->
 121
 122 <div class="doc_text">
 123
 124 <p>The LLVM code representation is designed to be used in three different forms:
 125 as an in-memory compiler IR, as an on-disk bytecode representation (suitable for
 126 fast loading by a Just-In-Time compiler), and as a human readable assembly
 127 language representation.  This allows LLVM to provide a powerful intermediate
 128 representation for efficient compiler transformations and analysis, while
 129 providing a natural means to debug and visualize the transformations.  The three
 130 different forms of LLVM are all equivalent.  This document describes the human
 131 readable representation and notation.</p>
 132
 133 <p>The LLVM representation aims to be a light-weight and low-level while being
 134 expressive, typed, and extensible at the same time.  It aims to be a "universal
 135 IR" of sorts, by being at a low enough level that high-level ideas may be
 136 cleanly mapped to it (similar to how microprocessors are "universal IR's",
 137 allowing many source languages to be mapped to them).  By providing type
 138 information, LLVM can be used as the target of optimizations: for example,
 139 through pointer analysis, it can be proven that a C automatic variable is never
 140 accessed outside of the current function... allowing it to be promoted to a
 141 simple SSA value instead of a memory location.</p>
 142
 143 </div>
 144
 145 <!-- _______________________________________________________________________ -->
 146 <div class="doc_subsubsection">
 147   <a name="wellformed">Well-Formedness</a>
 148 </div>
 149
 150 <div class="doc_text">
 151
 152 <p>It is important to note that this document describes 'well formed' LLVM
 153 assembly language.  There is a difference between what the parser accepts and
 154 what is considered 'well formed'.  For example, the following instruction is
 155 syntactically okay, but not well formed:</p>
 156
 157 <pre>
 158   %x = <a href="#i_add">add</a> int 1, %x
 159 </pre>
 160
 161 <p>...because the definition of <tt>%x</tt> does not dominate all of its uses.
 162 The LLVM infrastructure provides a verification pass that may be used to verify
 163 that an LLVM module is well formed.  This pass is automatically run by the
 164 parser after parsing input assembly, and by the optimizer before it outputs
 165 bytecode.  The violations pointed out by the verifier pass indicate bugs in
 166 transformation passes or input to the parser.</p>
 167
 168 <!-- Describe the typesetting conventions here. -->
 169
 170 </div>
 171
 172 <!-- *********************************************************************** -->
 173 <div class="doc_section">
 174   <a name="identifiers">Identifiers</a>
 175 </div>
 176 <!-- *********************************************************************** -->
 177
 178 <div class="doc_text">
 179
 180 <p>LLVM uses three different forms of identifiers, for different purposes:</p>
 181
 182 <ol>
 183
 184   <li>Numeric constants are represented as you would expect: 12, -3 123.421,
 185   etc.  Floating point constants have an optional hexidecimal notation.</li>
 186
 187   <li>Named values are represented as a string of characters with a '%' prefix.
 188   For example, %foo, %DivisionByZero, %a.really.long.identifier.  The actual
 189   regular expression used is '<tt>%[a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.
 190   Identifiers which require other characters in their names can be surrounded
 191   with quotes.  In this way, anything except a <tt>"</tt> character can be used
 192   in a name.</li>
 193
 194   <li>Unnamed values are represented as an unsigned numeric value with a '%'
 195   prefix.  For example, %12, %2, %44.</li>
 196
 197 </ol>
 198
 199 <p>LLVM requires the values start with a '%' sign for two reasons: Compilers
 200 don't need to worry about name clashes with reserved words, and the set of
 201 reserved words may be expanded in the future without penalty.  Additionally,
 202 unnamed identifiers allow a compiler to quickly come up with a temporary
 203 variable without having to avoid symbol table conflicts.</p>
 204
 205 <p>Reserved words in LLVM are very similar to reserved words in other languages.
 206 There are keywords for different opcodes ('<tt><a href="#i_add">add</a></tt>',
 207 '<tt><a href="#i_cast">cast</a></tt>', '<tt><a href="#i_ret">ret</a></tt>',
 208 etc...), for primitive type names ('<tt><a href="#t_void">void</a></tt>',
 209 '<tt><a href="#t_uint">uint</a></tt>', etc...), and others.  These reserved
 210 words cannot conflict with variable names, because none of them start with a '%'
 211 character.</p>
 212
 213 <p>Here is an example of LLVM code to multiply the integer variable
 214 '<tt>%X</tt>' by 8:</p>
 215
 216 <p>The easy way:</p>
 217
 218 <pre>
 219   %result = <a href="#i_mul">mul</a> uint %X, 8
 220 </pre>
 221
 222 <p>After strength reduction:</p>
 223
 224 <pre>
 225   %result = <a href="#i_shl">shl</a> uint %X, ubyte 3
 226 </pre>
 227
 228 <p>And the hard way:</p>
 229
 230 <pre>
 231   <a href="#i_add">add</a> uint %X, %X           <i>; yields {uint}:%0</i>
 232   <a href="#i_add">add</a> uint %0, %0           <i>; yields {uint}:%1</i>
 233   %result = <a href="#i_add">add</a> uint %1, %1
 234 </pre>
 235
 236 <p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important
 237 lexical features of LLVM:</p>
 238
 239 <ol>
 240   <li>Comments are delimited with a '<tt>;</tt>' and go until the end of
 241   line.</li>
 242
 243   <li>Unnamed temporaries are created when the result of a computation is not
 244   assigned to a named value.</li>
 245
 246   <li>Unnamed temporaries are numbered sequentially</li>
 247 </ol>
 248
 249 <p>...and it also show a convention that we follow in this document.  When
 250 demonstrating instructions, we will follow an instruction with a comment that
 251 defines the type and name of value produced.  Comments are shown in italic
 252 text.</p>
 253
 254 <p>The one non-intuitive notation for constants is the optional hexidecimal form
 255 of floating point constants.  For example, the form '<tt>double
 256 0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
 257 4.5e+15</tt>' which is also supported by the parser.  The only time hexadecimal
 258 floating point constants are useful (and the only time that they are generated
 259 by the disassembler) is when an FP constant has to be emitted that is not
 260 representable as a decimal floating point number exactly.  For example, NaN's,
 261 infinities, and other special cases are represented in their IEEE hexadecimal
 262 format so that assembly and disassembly do not cause any bits to change in the
 263 constants.</p>
 264
 265 </div>
 266
 267 <!-- *********************************************************************** -->
 268 <div class="doc_section">
 269   <a name="typesystem">Type System</a>
 270 </div>
 271 <!-- *********************************************************************** -->
 272
 273 <div class="doc_text">
 274
 275 <p>The LLVM type system is one of the most important features of the
 276 intermediate representation.  Being typed enables a number of optimizations to
 277 be performed on the IR directly, without having to do extra analyses on the side
 278 before the transformation.  A strong type system makes it easier to read the
 279 generated code and enables novel analyses and transformations that are not
 280 feasible to perform on normal three address code representations.</p>
 281
 282 <!-- The written form for the type system was heavily influenced by the
 283 syntactic problems with types in the C language<sup><a
 284 href="#rw_stroustrup">1</a></sup>.<p> -->
 285
 286 </div>
 287
 288 <!-- ======================================================================= -->
 289 <div class="doc_subsection">
 290   <a name="t_primitive">Primitive Types</a>
 291 </div>
 292
 293 <div class="doc_text">
 294
 295 <p>The primitive types are the fundemental building blocks of the LLVM system.
 296 The current set of primitive types are as follows:</p>
 297
 298 <p>
 299 <table border="0" align="center">
 300 <tr>
 301 <td>
 302
 303 <table border="1" cellspacing="0" cellpadding="4" align="center">
 304 <tr><td><tt>void</tt></td>  <td>No value</td></tr>
 305 <tr><td><tt>ubyte</tt></td> <td>Unsigned 8 bit value</td></tr>
 306 <tr><td><tt>ushort</tt></td><td>Unsigned 16 bit value</td></tr>
 307 <tr><td><tt>uint</tt></td>  <td>Unsigned 32 bit value</td></tr>
 308 <tr><td><tt>ulong</tt></td> <td>Unsigned 64 bit value</td></tr>
 309 <tr><td><tt>float</tt></td> <td>32 bit floating point value</td></tr>
 310 <tr><td><tt>label</tt></td> <td>Branch destination</td></tr>
 311 </table>
 312
 313 </td><td valign=top>
 314
 315 <table border="1" cellspacing="0" cellpadding="4" align=center">
 316 <tr><td><tt>bool</tt></td>  <td>True or False value</td></tr>
 317 <tr><td><tt>sbyte</tt></td> <td>Signed 8 bit value</td></tr>
 318 <tr><td><tt>short</tt></td> <td>Signed 16 bit value</td></tr>
 319 <tr><td><tt>int</tt></td>   <td>Signed 32 bit value</td></tr>
 320 <tr><td><tt>long</tt></td>  <td>Signed 64 bit value</td></tr>
 321 <tr><td><tt>double</tt></td><td>64 bit floating point value</td></tr>
 322 </table>
 323
 324 </td>
 325 </tr>
 326 </table>
 327 </p>
 328
 329 </div>
 330
 331 <!-- _______________________________________________________________________ -->
 332 <div class="doc_subsubsection">
 333   <a name="t_classifications">Type Classifications</a>
 334 </div>
 335
 336 <div class="doc_text">
 337
 338 <p>These different primitive types fall into a few useful classifications:</p>
 339
 340 <p>
 341 <table border="1" cellspacing="0" cellpadding="4" align="center">
 342 <tr>
 343   <td><a name="t_signed">signed</td>
 344   <td><tt>sbyte, short, int, long, float, double</tt></td>
 345 </tr>
 346 <tr>
 347   <td><a name="t_unsigned">unsigned</td>
 348   <td><tt>ubyte, ushort, uint, ulong</tt></td>
 349 </tr>
 350 <tr>
 351   <td><a name="t_integer">integer</td>
 352   <td><tt>ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td>
 353 </tr>
 354 <tr>
 355   <td><a name="t_integral">integral</td>
 356   <td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td>
 357 </tr>
 358 <tr>
 359   <td><a name="t_floating">floating point</td>
 360   <td><tt>float, double</tt></td>
 361 </tr>
 362 <tr>
 363   <td><a name="t_firstclass">first class</td>
 364   <td><tt>bool, ubyte, sbyte, ushort, short,<br>
 365           uint, int, ulong, long, float, double,
 366           <a href="#t_pointer">pointer</a></tt></td>
 367 </tr>
 368 </table>
 369 </p>
 370
 371 <p>The <a href="#t_firstclass">first class</a> types are perhaps the most
 372 important.  Values of these types are the only ones which can be produced by
 373 instructions, passed as arguments, or used as operands to instructions.  This
 374 means that all structures and arrays must be manipulated either by pointer or by
 375 component.</p>
 376
 377 </div>
 378
 379 <!-- ======================================================================= -->
 380 <div class="doc_subsection">
 381   <a name="t_derived">Derived Types</a>
 382 </div>
 383
 384 <div class="doc_text">
 385
 386 <p>The real power in LLVM comes from the derived types in the system.  This is
 387 what allows a programmer to represent arrays, functions, pointers, and other
 388 useful types.  Note that these derived types may be recursive: For example, it
 389 is possible to have a two dimensional array.</p>
 390
 391 </div>
 392
 393 <!-- _______________________________________________________________________ -->
 394 <div class="doc_subsubsection">
 395   <a name="t_array">Array Type</a>
 396 </div>
 397
 398 <div class="doc_text">
 399
 400 <h5>Overview:</h5>
 401
 402 <p>The array type is a very simple derived type that arranges elements
 403 sequentially in memory.  The array type requires a size (number of elements) and
 404 an underlying data type.</p>
 405
 406 <h5>Syntax:</h5>
 407
 408 <pre>
 409   [&lt;# elements&gt; x &lt;elementtype&gt;]
 410 </pre>
 411
 412 <p>The number of elements is a constant integer value, elementtype may be any
 413 type with a size.</p>
 414
 415 <h5>Examples:</h5>
 416
 417 <p>
 418    <tt>[40 x int ]</tt>: Array of 40 integer values.<br>
 419    <tt>[41 x int ]</tt>: Array of 41 integer values.<br>
 420    <tt>[40 x uint]</tt>: Array of 40 unsigned integer values.<p>
 421 </p>
 422
 423 <p>Here are some examples of multidimensional arrays:</p>
 424
 425 <p>
 426 <table border="0" cellpadding="0" cellspacing="0">
 427 <tr>
 428   <td><tt>[3 x [4 x int]]</tt></td>
 429   <td>: 3x4 array integer values.</td>
 430 </tr>
 431 <tr>
 432   <td><tt>[12 x [10 x float]]</tt></td>
 433   <td>: 12x10 array of single precision floating point values.</td>
 434 </tr>
 435 <tr>
 436   <td><tt>[2 x [3 x [4 x uint]]]</tt></td>
 437   <td>: 2x3x4 array of unsigned integer values.</td>
 438 </tr>
 439 </table>
 440 </p>
 441
 442 </div>
 443
 444 <!-- _______________________________________________________________________ -->
 445 <div class="doc_subsubsection">
 446   <a name="t_function">Function Type</a>
 447 </div>
 448
 449 <div class="doc_text">
 450
 451 <h5>Overview:</h5>
 452
 453 <p>The function type can be thought of as a function signature.  It consists of
 454 a return type and a list of formal parameter types.  Function types are usually
 455 used when to build virtual function tables (which are structures of pointers to
 456 functions), for indirect function calls, and when defining a function.</p>
 457
 458 <h5>Syntax:</h5>
 459
 460 <pre>
 461   &lt;returntype&gt; (&lt;parameter list&gt;)
 462 </pre>
 463
 464 <p>Where '<tt>&lt;parameter list&gt;</tt>' is a comma-separated list of type
 465 specifiers.  Optionally, the parameter list may include a type <tt>...</tt>,
 466 which indicates that the function takes a variable number of arguments.
 467 Variable argument functions can access their arguments with the <a
 468 href="#int_varargs">variable argument handling intrinsic</a> functions.</p>
 469
 470 <h5>Examples:</h5>
 471
 472 <p>
 473 <table border="0" cellpadding="0" cellspacing="0">
 474
 475 <tr>
 476   <td><tt>int (int)</tt></td>
 477   <td>: function taking an <tt>int</tt>, returning an <tt>int</tt></td>
 478 </tr>
 479 <tr>
 480   <td><tt>float (int, int *) *</tt></td>
 481   <td>: <a href="#t_pointer">Pointer</a> to a function that takes an
 482       <tt>int</tt> and a <a href="#t_pointer">pointer</a> to <tt>int</tt>,
 483       returning <tt>float</tt>.</td>
 484 </tr>
 485 <tr>
 486   <td><tt>int (sbyte *, ...)</tt></td>
 487   <td>: A vararg function that takes at least one <a
 488       href="#t_pointer">pointer</a> to <tt>sbyte</tt> (signed char in C), which
 489       returns an integer.  This is the signature for <tt>printf</tt> in
 490       LLVM.</td>
 491 </tr>
 492 </table>
 493 </p>
 494
 495 </div>
 496
 497 <!-- _______________________________________________________________________ -->
 498 <div class="doc_subsubsection">
 499   <a name="t_struct">Structure Type</a>
 500 </div>
 501
 502 <div class="doc_text">
 503
 504 <h5>Overview:</h5>
 505
 506 <p>The structure type is used to represent a collection of data members together
 507 in memory.  The packing of the field types is defined to match the ABI of the
 508 underlying processor.  The elements of a structure may be any type that has a
 509 size.</p>
 510
 511 <p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and
 512 '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with the
 513 '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
 514
 515 <h5>Syntax:</h5>
 516
 517 <pre>
 518   { &lt;type list&gt; }
 519 </pre>
 520
 521 <h5>Examples:</h5>
 522
 523 <p>
 524 <table border="0" cellpadding="0" cellspacing="0">
 525 <tr>
 526   <td><tt>{ int, int, int }</tt></td>
 527   <td>: a triple of three <tt>int</tt> values</td>
 528 </tr>
 529 <tr>
 530   <td><tt>{ float, int (int) * }</tt></td>
 531   <td>: A pair, where the first element is a <tt>float</tt> and the second
 532       element is a <a href="#t_pointer">pointer</a> to a <a
 533       href="t_function">function</a> that takes an <tt>int</tt>, returning an
 534       <tt>int</tt>.</td>
 535 </tr>
 536 </table>
 537 </p>
 538
 539 </div>
 540
 541 <!-- _______________________________________________________________________ -->
 542 <div class="doc_subsubsection">
 543   <a name="t_pointer">Pointer Type</a>
 544 </div>
 545
 546 <div class="doc_text">
 547
 548 <h5>Overview:</h5>
 549
 550 <p>As in many languages, the pointer type represents a pointer or reference to
 551 another object, which must live in memory.</p>
 552
 553 <h5>Syntax:</h5>
 554 <pre>
 555   &lt;type&gt; *
 556 </pre>
 557
 558 <h5>Examples:</h5>
 559
 560 <p>
 561 <table border="0" cellpadding="0" cellspacing="0">
 562 <tr>
 563   <td><tt>[4x int]*</tt></td>
 564   <td>: <a href="#t_pointer">pointer</a> to <a href="#t_array">array</a> of four
 565       <tt>int</tt> values</td>
 566 </tr>
 567 <tr>
 568   <td><tt>int (int *) *</tt></td>
 569   <td>: A <a href="#t_pointer">pointer</a> to a <a
 570       href="t_function">function</a> that takes an <tt>int</tt>, returning an
 571       <tt>int</tt>.</td>
 572 </tr>
 573 </table>
 574 </p>
 575
 576 </div>
 577
 578 <!-- _______________________________________________________________________ -->
 579 <!--
 580 <div class="doc_subsubsection">
 581   <a name="t_packed">Packed Type</a>
 582 </div>
 583
 584 <div class="doc_text">
 585
 586 Mention/decide that packed types work with saturation or not. Maybe have a packed+saturated type in addition to just a packed type.<p>
 587
 588 Packed types should be 'nonsaturated' because standard data types are not saturated.  Maybe have a saturated packed type?<p>
 589
 590 </div>
 591
 592 -->
 593
 594
 595 <!-- *********************************************************************** -->
 596 <div class="doc_section">
 597   <a name="highlevel">High Level Structure</a>
 598 </div>
 599 <!-- *********************************************************************** -->
 600
 601
 602 <!-- ======================================================================= -->
 603 <div class="doc_subsection">
 604   <a name="modulestructure">Module Structure</a>
 605 </div>
 606
 607 <div class="doc_text">
 608
 609 <p>LLVM programs are composed of "Module"s, each of which is a translation unit
 610 of the input programs.  Each module consists of functions, global variables, and
 611 symbol table entries.  Modules may be combined together with the LLVM linker,
 612 which merges function (and global variable) definitions, resolves forward
 613 declarations, and merges symbol table entries. Here is an example of the "hello
 614 world" module:</p>
 615
 616 <pre>
 617 <i>; Declare the string constant as a global constant...</i>
 618 <a href="#identifiers">%.LC0</a> = <a href="#linkage_internal">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x sbyte]</a> c"hello world\0A\00"          <i>; [13 x sbyte]*</i>
 619
 620 <i>; External declaration of the puts function</i>
 621 <a href="#functionstructure">declare</a> int %puts(sbyte*)                                            <i>; int(sbyte*)* </i>
 622
 623 <i>; Definition of main function</i>
 624 int %main() {                                                        <i>; int()* </i>
 625         <i>; Convert [13x sbyte]* to sbyte *...</i>
 626         %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, long 0, long 0 <i>; sbyte*</i>
 627
 628         <i>; Call puts function to write out the string to stdout...</i>
 629         <a href="#i_call">call</a> int %puts(sbyte* %cast210)                              <i>; int</i>
 630         <a href="#i_ret">ret</a> int 0
 631 }
 632 </pre>
 633
 634 <p>This example is made up of a <a href="#globalvars">global variable</a> named
 635 "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, and a
 636 <a href="#functionstructure">function definition</a> for "<tt>main</tt>".</p>
 637
 638 <a name="linkage">
 639 In general, a module is made up of a list of global values, where both functions
 640 and global variables are global values.  Global values are represented by a
 641 pointer to a memory location (in this case, a pointer to an array of char, and a
 642 pointer to a function), and have one of the following linkage types:<p>
 643
 644 <dl>
 645 <a name="linkage_internal">
 646 <dt><tt><b>internal</b></tt>
 647
 648 <dd>Global values with internal linkage are only directly accessible by objects
 649 in the current module.  In particular, linking code into a module with an
 650 internal global value may cause the internal to be renamed as necessary to avoid
 651 collisions.  Because the symbol is internal to the module, all references can be
 652 updated.  This corresponds to the notion of the '<tt>static</tt>' keyword in C,
 653 or the idea of "anonymous namespaces" in C++.<p>
 654
 655 <a name="linkage_linkonce">
 656 <dt><tt><b>linkonce</b></tt>:
 657
 658 <dd>"<tt>linkonce</tt>" linkage is similar to <tt>internal</tt> linkage, with
 659 the twist that linking together two modules defining the same <tt>linkonce</tt>
 660 globals will cause one of the globals to be discarded.  This is typically used
 661 to implement inline functions.  Unreferenced <tt>linkonce</tt> globals are
 662 allowed to be discarded.<p>
 663
 664 <a name="linkage_weak">
 665 <dt><tt><b>weak</b></tt>:
 666
 667 <dd>"<tt>weak</tt>" linkage is exactly the same as <tt>linkonce</tt> linkage,
 668 except that unreferenced <tt>weak</tt> globals may not be discarded.  This is
 669 used to implement constructs in C such as "<tt>int X;</tt>" at global scope.<p>
 670
 671 <a name="linkage_appending">
 672 <dt><tt><b>appending</b></tt>:
 673
 674 <dd>"<tt>appending</tt>" linkage may only applied to global variables of pointer
 675 to array type.  When two global variables with appending linkage are linked
 676 together, the two global arrays are appended together.  This is the LLVM,
 677 typesafe, equivalent of having the system linker append together "sections" with
 678 identical names when .o files are linked.<p>
 679
 680 <a name="linkage_external">
 681 <dt><tt><b>externally visible</b></tt>:
 682
 683 <dd>If none of the above identifiers are used, the global is externally visible,
 684 meaning that it participates in linkage and can be used to resolve external
 685 symbol references.<p>
 686
 687 </dl><p>
 688
 689 <p>For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
 690 another module defined a "<tt>.LC0</tt>" variable and was linked with this one,
 691 one of the two would be renamed, preventing a collision.  Since "<tt>main</tt>"
 692 and "<tt>puts</tt>" are external (i.e., lacking any linkage declarations), they
 693 are accessible outside of the current module.  It is illegal for a function
 694 <i>declaration</i> to have any linkage type other than "externally visible".</p>
 695
 696 </div>
 697
 698 <!-- ======================================================================= -->
 699 <div class="doc_subsection">
 700   <a name="globalvars">Global Variables</a>
 701 </div>
 702
 703 <div class="doc_text">
 704
 705 <p>Global variables define regions of memory allocated at compilation time
 706 instead of run-time.  Global variables may optionally be initialized.  A
 707 variable may be defined as a global "constant", which indicates that the
 708 contents of the variable will never be modified (opening options for
 709 optimization).  Constants must always have an initial value.</p>
 710
 711 <p>As SSA values, global variables define pointer values that are in scope
 712 (i.e. they dominate) for all basic blocks in the program.  Global variables
 713 always define a pointer to their "content" type because they describe a region
 714 of memory, and all memory objects in LLVM are accessed through pointers.</p>
 715
 716 </div>
 717
 718 <!-- ======================================================================= -->
 719 <div class="doc_subsection">
 720   <a name="functionstructure">Functions</a>
 721 </div>
 722
 723 <div class="doc_text">
 724
 725 <p>LLVM function definitions are composed of a (possibly empty) argument list,
 726 an opening curly brace, a list of basic blocks, and a closing curly brace.  LLVM
 727 function declarations are defined with the "<tt>declare</tt>" keyword, a
 728 function name, and a function signature.</p>
 729
 730 <p>A function definition contains a list of basic blocks, forming the CFG for
 731 the function.  Each basic block may optionally start with a label (giving the
 732 basic block a symbol table entry), contains a list of instructions, and ends
 733 with a <a href="#terminators">terminator</a> instruction (such as a branch or
 734 function return).</p>
 735
 736 <p>The first basic block in program is special in two ways: it is immediately
 737 executed on entrance to the function, and it is not allowed to have predecessor
 738 basic blocks (i.e. there can not be any branches to the entry block of a
 739 function).  Because the block can have no predecessors, it also cannot have any
 740 <a href="#i_phi">PHI nodes</a>.</p>
 741
 742 </div>
 743
 744 <!-- *********************************************************************** -->
 745 <div class="doc_section">
 746   <a name="instref">Instruction Reference</a>
 747 </div>
 748 <!-- *********************************************************************** -->
 749
 750 <div class="doc_text">
 751
 752 <p>The LLVM instruction set consists of several different classifications of
 753 instructions: <a href="#terminators">terminator instructions</a>, <a
 754 href="#binaryops">binary instructions</a>, <a href="#memoryops">memory
 755 instructions</a>, and <a href="#otherops">other instructions</a>.</p>
 756
 757 </div>
 758
 759 <!-- ======================================================================= -->
 760 <div class="doc_subsection">
 761   <a name="terminators">Terminator Instructions</a>
 762 </div>
 763
 764 <div class="doc_text">
 765
 766 <p>As mentioned <a href="#functionstructure">previously</a>, every basic block
 767 in a program ends with a "Terminator" instruction, which indicates which block
 768 should be executed after the current block is finished. These terminator
 769 instructions typically yield a '<tt>void</tt>' value: they produce control flow,
 770 not values (the one exception being the '<a
 771 href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
 772
 773 <p>There are five different terminator instructions: the '<a
 774 href="#i_ret"><tt>ret</tt></a>' instruction, the '<a
 775 href="#i_br"><tt>br</tt></a>' instruction, the '<a
 776 href="#i_switch"><tt>switch</tt></a>' instruction, the '<a
 777 href="#i_invoke"><tt>invoke</tt></a>' instruction, and the '<a
 778 href="#i_unwind"><tt>unwind</tt></a>' instruction.</p>
 779
 780 </div>
 781
 782 <!-- _______________________________________________________________________ -->
 783 <div class="doc_subsubsection">
 784   <a name="i_ret">'<tt>ret</tt>' Instruction</a>
 785 </div>
 786
 787 <div class="doc_text">
 788
 789 <h5>Syntax:</h5>
 790 <pre>
 791   ret &lt;type&gt; &lt;value&gt;       <i>; Return a value from a non-void function</i>
 792   ret void                 <i>; Return from void function</i>
 793 </pre>
 794
 795 <h5>Overview:</h5>
 796
 797 <p>The '<tt>ret</tt>' instruction is used to return control flow (and a value)
 798 from a function, back to the caller.</p>
 799
 800 <p>There are two forms of the '<tt>ret</tt>' instructruction: one that returns a
 801 value and then causes control flow, and one that just causes control flow to
 802 occur.</p>
 803
 804 <h5>Arguments:</h5>
 805
 806 <p>The '<tt>ret</tt>' instruction may return any '<a href="#t_firstclass">first
 807 class</a>' type.  Notice that a function is not <a href="#wellformed">well
 808 formed</a> if there exists a '<tt>ret</tt>' instruction inside of the function
 809 that returns a value that does not match the return type of the function.</p>
 810
 811 <h5>Semantics:</h5>
 812
 813 <p>When the '<tt>ret</tt>' instruction is executed, control flow returns back to
 814 the calling function's context.  If the caller is a "<a
 815 href="#i_call"><tt>call</tt></a> instruction, execution continues at the
 816 instruction after the call.  If the caller was an "<a
 817 href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at the
 818 beginning "normal" of the destination block.  If the instruction returns a
 819 value, that value shall set the call or invoke instruction's return value.</p>
 820
 821 <h5>Example:</h5>
 822 <pre>
 823   ret int 5                       <i>; Return an integer value of 5</i>
 824   ret void                        <i>; Return from a void function</i>
 825 </pre>
 826
 827 </div>
 828
 829 <!-- _______________________________________________________________________ -->
 830 <div class="doc_subsubsection">
 831   <a name="i_br">'<tt>br</tt>' Instruction</a>
 832 </div>
 833
 834 <div class="doc_text">
 835
 836 <h5>Syntax:</h5>
 837
 838 <pre>
 839   br bool &lt;cond&gt;, label &lt;iftrue&gt;, label &lt;iffalse&gt;
 840   br label &lt;dest&gt;          <i>; Unconditional branch</i>
 841 </pre>
 842
 843 <h5>Overview:</h5>
 844
 845 <p>The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
 846 different basic block in the current function.  There are two forms of this
 847 instruction, corresponding to a conditional branch and an unconditional
 848 branch.</p>
 849
 850 <h5>Arguments:</h5>
 851
 852 <p>The conditional branch form of the '<tt>br</tt>' instruction takes a single
 853 '<tt>bool</tt>' value and two '<tt>label</tt>' values.  The unconditional form
 854 of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
 855 target.</p>
 856
 857 <h5>Semantics:</h5>
 858
 859 <p>Upon execution of a conditional '<tt>br</tt>' instruction, the
 860 '<tt>bool</tt>' argument is evaluated.  If the value is <tt>true</tt>, control
 861 flows to the '<tt>iftrue</tt>' <tt>label</tt> argument.  If "cond" is
 862 <tt>false</tt>, control flows to the '<tt>iffalse</tt>' <tt>label</tt>
 863 argument.</p>
 864
 865 <h5>Example:</h5>
 866
 867 <pre>
 868 Test:
 869   %cond = <a href="#i_setcc">seteq</a> int %a, %b
 870   br bool %cond, label %IfEqual, label %IfUnequal
 871 IfEqual:
 872   <a href="#i_ret">ret</a> int 1
 873 IfUnequal:
 874   <a href="#i_ret">ret</a> int 0
 875 </pre>
 876
 877 </div>
 878
 879 <!-- _______________________________________________________________________ -->
 880 <div class="doc_subsubsection">
 881   <a name="i_switch">'<tt>switch</tt>' Instruction</a>
 882 </div>
 883
 884 <div class="doc_text">
 885
 886 <h5>Syntax:</h5>
 887
 888 <pre>
 889   switch uint &lt;value&gt;, label &lt;defaultdest&gt; [ int &lt;val&gt;, label &dest&gt;, ... ]
 890 </pre>
 891
 892 <h5>Overview:</h5>
 893
 894 <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
 895 several different places.  It is a generalization of the '<tt>br</tt>'
 896 instruction, allowing a branch to occur to one of many possible
 897 destinations.</p>
 898
 899 <h5>Arguments:</h5>
 900
 901 <p>The '<tt>switch</tt>' instruction uses three parameters: a '<tt>uint</tt>'
 902 comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
 903 an array of pairs of comparison value constants and '<tt>label</tt>'s.</p>
 904
 905 <h5>Semantics:</h5>
 906
 907 <p>The <tt>switch</tt> instruction specifies a table of values and destinations.
 908 When the '<tt>switch</tt>' instruction is executed, this table is searched for
 909 the given value.  If the value is found, the corresponding destination is
 910 branched to, otherwise the default value it transfered to.</p>
 911
 912 <h5>Implementation:</h5>
 913
 914 <p>Depending on properties of the target machine and the particular
 915 <tt>switch</tt> instruction, this instruction may be code generated as a series
 916 of chained conditional branches, or with a lookup table.</p>
 917
 918 <h5>Example:</h5>
 919
 920 <pre>
 921   <i>; Emulate a conditional br instruction</i>
 922   %Val = <a href="#i_cast">cast</a> bool %value to uint
 923   switch uint %Val, label %truedest [int 0, label %falsedest ]
 924
 925   <i>; Emulate an unconditional br instruction</i>
 926   switch uint 0, label %dest [ ]
 927
 928   <i>; Implement a jump table:</i>
 929   switch uint %val, label %otherwise [ int 0, label %onzero,
 930                                        int 1, label %onone,
 931                                        int 2, label %ontwo ]
 932 </pre>
 933
 934 </div>
 935
 936 <!-- _______________________________________________________________________ -->
 937 <div class="doc_subsubsection">
 938   <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
 939 </div>
 940
 941 <div class="doc_text">
 942
 943 <h5>Syntax:</h5>
 944
 945 <pre>
 946   &lt;result&gt; = invoke &lt;ptr to function ty&gt; %&lt;function ptr val&gt;(&lt;function args&gt;)
 947                  to label &lt;normal label&gt; except label &lt;exception label&gt;
 948 </pre>
 949
 950 <h5>Overview:</h5>
 951
 952 <p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified
 953 function, with the possibility of control flow transfer to either the
 954 '<tt>normal</tt>' <tt>label</tt> label or the '<tt>exception</tt>'
 955 <tt>label</tt>.  If the callee function returns with the "<tt><a
 956 href="#i_ret">ret</a></tt>" instruction, control flow will return to the
 957 "normal" label.  If the callee (or any indirect callees) returns with the "<a
 958 href="#i_unwind"><tt>unwind</tt></a>" instruction, control is interrupted, and
 959 continued at the dynamically nearest "except" label.</p>
 960
 961 <h5>Arguments:</h5>
 962
 963 <p>This instruction requires several arguments:</p>
 964
 965 <ol>
 966
 967 <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
 968 function value being invoked.  In most cases, this is a direct function
 969 invocation, but indirect <tt>invoke</tt>s are just as possible, branching off
 970 an arbitrary pointer to function value.
 971
 972 <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
 973 function to be invoked.
 974
 975 <li>'<tt>function args</tt>': argument list whose types match the function
 976 signature argument types.  If the function signature indicates the function
 977 accepts a variable number of arguments, the extra arguments can be specified.
 978
 979 <li>'<tt>normal label</tt>': the label reached when the called function executes
 980 a '<tt><a href="#i_ret">ret</a></tt>' instruction.
 981
 982 <li>'<tt>exception label</tt>': the label reached when a callee returns with the
 983 <a href="#i_unwind"><tt>unwind</tt></a> instruction.
 984 </ol>
 985
 986 <h5>Semantics:</h5>
 987
 988 <p>This instruction is designed to operate as a standard '<tt><a
 989 href="#i_call">call</a></tt>' instruction in most regards.  The primary
 990 difference is that it establishes an association with a label, which is used by the runtime library to unwind the stack.</p>
 991
 992 <p>This instruction is used in languages with destructors to ensure that proper
 993 cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
 994 exception.  Additionally, this is important for implementation of
 995 '<tt>catch</tt>' clauses in high-level languages that support them.</p>
 996
 997 <h5>Example:</h5>
 998
 999 <pre>
1000   %retval = invoke int %Test(int 15)
1001               to label %Continue
1002               except label %TestCleanup     <i>; {int}:retval set</i>
1003 </pre>
1004
1005 </div>
1006
1007 <!-- _______________________________________________________________________ -->
1008 <div class="doc_subsubsection">
1009   <a name="i_unwind">'<tt>unwind</tt>' Instruction</a>
1010 </div>
1011
1012 <div class="doc_text">
1013
1014 <h5>Syntax:</h5>
1015
1016 <pre>
1017   unwind
1018 </pre>
1019
1020 <h5>Overview:</h5>
1021
1022 <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow
1023 at the first callee in the dynamic call stack which used an <a
1024 href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call.  This is
1025 primarily used to implement exception handling.</p>
1026
1027 <h5>Semantics:</h5>
1028
1029 <p>The '<tt>unwind</tt>' intrinsic causes execution of the current function to
1030 immediately halt.  The dynamic call stack is then searched for the first <a
1031 href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack.  Once found,
1032 execution continues at the "exceptional" destination block specified by the
1033 <tt>invoke</tt> instruction.  If there is no <tt>invoke</tt> instruction in the
1034 dynamic call chain, undefined behavior results.</p>
1035
1036 </div>
1037
1038 <!-- ======================================================================= -->
1039 <div class="doc_subsection">
1040   <a name="binaryops">Binary Operations</a>
1041 </div>
1042
1043 <div class="doc_text">
1044
1045 <p>Binary operators are used to do most of the computation in a program.  They
1046 require two operands, execute an operation on them, and produce a single value.
1047 The result value of a binary operator is not necessarily the same type as its
1048 operands.</p>
1049
1050 <p>There are several different binary operators:</p>
1051
1052 </div>
1053
1054 <!-- _______________________________________________________________________ -->
1055 <div class="doc_subsubsection">
1056   <a name="i_add">'<tt>add</tt>' Instruction</a>
1057 </div>
1058
1059 <div class="doc_text">
1060
1061 <h5>Syntax:</h5>
1062
1063 <pre>
1064   &lt;result&gt; = add &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1065 </pre>
1066
1067 <h5>Overview:</h5>
1068
1069 <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
1070
1071 <h5>Arguments:</h5>
1072
1073 <p>The two arguments to the '<tt>add</tt>' instruction must be either <a
1074 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1075 values.  Both arguments must have identical types.</p>
1076
1077 <h5>Semantics:</h5>
1078
1079 <p>The value produced is the integer or floating point sum of the two
1080 operands.</p>
1081
1082 <h5>Example:</h5>
1083
1084 <pre>
1085   &lt;result&gt; = add int 4, %var          <i>; yields {int}:result = 4 + %var</i>
1086 </pre>
1087
1088 </div>
1089
1090 <!-- _______________________________________________________________________ -->
1091 <div class="doc_subsubsection">
1092   <a name="i_sub">'<tt>sub</tt>' Instruction</a>
1093 </div>
1094
1095 <div class="doc_text">
1096
1097 <h5>Syntax:</h5>
1098
1099 <pre>
1100   &lt;result&gt; = sub &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1101 </pre>
1102
1103 <h5>Overview:</h5>
1104
1105 <p>The '<tt>sub</tt>' instruction returns the difference of its two
1106 operands.</p>
1107
1108 <p>Note that the '<tt>sub</tt>' instruction is used to represent the
1109 '<tt>neg</tt>' instruction present in most other intermediate
1110 representations.</p>
1111
1112 <h5>Arguments:</h5>
1113
1114 <p>The two arguments to the '<tt>sub</tt>' instruction must be either <a
1115 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1116 values.  Both arguments must have identical types.</p>
1117
1118 <h5>Semantics:</h5>
1119
1120 <p>The value produced is the integer or floating point difference of the two
1121 operands.</p>
1122
1123 <h5>Example:</h5>
1124
1125 <pre>
1126   &lt;result&gt; = sub int 4, %var          <i>; yields {int}:result = 4 - %var</i>
1127   &lt;result&gt; = sub int 0, %val          <i>; yields {int}:result = -%var</i>
1128 </pre>
1129
1130 </div>
1131
1132 <!-- _______________________________________________________________________ -->
1133 <div class="doc_subsubsection">
1134   <a name="i_mul">'<tt>mul</tt>' Instruction</a>
1135 </div>
1136
1137 <div class="doc_text">
1138
1139 <h5>Syntax:</h5>
1140
1141 <pre>
1142   &lt;result&gt; = mul &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1143 </pre>
1144
1145 <h5>Overview:</h5>
1146
1147 <p>The  '<tt>mul</tt>' instruction returns the product of its two operands.</p>
1148
1149 <h5>Arguments:</h5>
1150
1151 <p>The two arguments to the '<tt>mul</tt>' instruction must be either <a
1152 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1153 values.  Both arguments must have identical types.</p>
1154
1155 <h5>Semantics:</h5>
1156
1157 <p>The value produced is the integer or floating point product of the two
1158 operands.</p>
1159
1160 <p>There is no signed vs unsigned multiplication.  The appropriate action is
1161 taken based on the type of the operand.</p>
1162
1163 <h5>Example:</h5>
1164
1165 <pre>
1166   &lt;result&gt; = mul int 4, %var          <i>; yields {int}:result = 4 * %var</i>
1167 </pre>
1168
1169 </div>
1170
1171 <!-- _______________________________________________________________________ -->
1172 <div class="doc_subsubsection">
1173   <a name="i_div">'<tt>div</tt>' Instruction</a>
1174 </div>
1175
1176 <div class="doc_text">
1177
1178 <h5>Syntax:</h5>
1179
1180 <pre>
1181   &lt;result&gt; = div &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1182 </pre>
1183
1184 <h5>Overview:</h5>
1185
1186 <p>The '<tt>div</tt>' instruction returns the quotient of its two operands.</p>
1187
1188 <h5>Arguments:</h5>
1189
1190 <p>The two arguments to the '<tt>div</tt>' instruction must be either <a
1191 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1192 values.  Both arguments must have identical types.</p>
1193
1194 <h5>Semantics:</h5>
1195
1196 <p>The value produced is the integer or floating point quotient of the two
1197 operands.</p>
1198
1199 <h5>Example:</h5>
1200
1201 <pre>
1202   &lt;result&gt; = div int 4, %var          <i>; yields {int}:result = 4 / %var</i>
1203 </pre>
1204
1205 </div>
1206
1207 <!-- _______________________________________________________________________ -->
1208 <div class="doc_subsubsection">
1209   <a name="i_rem">'<tt>rem</tt>' Instruction</a>
1210 </div>
1211
1212 <div class="doc_text">
1213
1214 <h5>Syntax:</h5>
1215
1216 <pre>
1217   &lt;result&gt; = rem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1218 </pre>
1219
1220 <h5>Overview:</h5>
1221
1222 <p>The '<tt>rem</tt>' instruction returns the remainder from the division of its
1223 two operands.</p>
1224
1225 <h5>Arguments:</h5>
1226
1227 <p>The two arguments to the '<tt>rem</tt>' instruction must be either <a
1228 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1229 values.  Both arguments must have identical types.</p>
1230
1231 <h5>Semantics:</h5>
1232
1233 <p>This returns the <i>remainder</i> of a division (where the result has the
1234 same sign as the divisor), not the <i>modulus</i> (where the result has the same
1235 sign as the dividend) of a value.  For more information about the difference,
1236 see: <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The Math
1237 Forum</a>.</p>
1238
1239 <h5>Example:</h5>
1240
1241 <pre>
1242   &lt;result&gt; = rem int 4, %var          <i>; yields {int}:result = 4 % %var</i>
1243 </pre>
1244
1245 </div>
1246
1247 <!-- _______________________________________________________________________ -->
1248 <div class="doc_subsubsection">
1249   <a name="i_setcc">'<tt>set<i>cc</i></tt>' Instructions</a>
1250 </div>
1251
1252 <div class="doc_text">
1253
1254 <h5>Syntax:</h5>
1255
1256 <pre>
1257   &lt;result&gt; = seteq &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1258   &lt;result&gt; = setne &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1259   &lt;result&gt; = setlt &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1260   &lt;result&gt; = setgt &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1261   &lt;result&gt; = setle &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1262   &lt;result&gt; = setge &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1263 </pre>
1264
1265 <h5>Overview:</h5>
1266
1267 <p>The '<tt>set<i>cc</i></tt>' family of instructions returns a boolean value
1268 based on a comparison of their two operands.</p>
1269
1270 <h5>Arguments:</h5>
1271
1272 <p>The two arguments to the '<tt>set<i>cc</i></tt>' instructions must be of <a
1273 href="#t_firstclass">first class</a> type (it is not possible to compare
1274 '<tt>label</tt>'s, '<tt>array</tt>'s, '<tt>structure</tt>' or '<tt>void</tt>'
1275 values, etc...).  Both arguments must have identical types.</p>
1276
1277 <h5>Semantics:</h5>
1278
1279 <p>The '<tt>seteq</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value
1280 if both operands are equal.<br>
1281
1282 The '<tt>setne</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1283 both operands are unequal.<br>
1284
1285 The '<tt>setlt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1286 the first operand is less than the second operand.<br>
1287
1288 The '<tt>setgt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1289 the first operand is greater than the second operand.<br>
1290
1291 The '<tt>setle</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1292 the first operand is less than or equal to the second operand.<br>
1293
1294 The '<tt>setge</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1295 the first operand is greater than or equal to the second operand.</p>
1296
1297 <h5>Example:</h5>
1298
1299 <pre>
1300   &lt;result&gt; = seteq int   4, 5        <i>; yields {bool}:result = false</i>
1301   &lt;result&gt; = setne float 4, 5        <i>; yields {bool}:result = true</i>
1302   &lt;result&gt; = setlt uint  4, 5        <i>; yields {bool}:result = true</i>
1303   &lt;result&gt; = setgt sbyte 4, 5        <i>; yields {bool}:result = false</i>
1304   &lt;result&gt; = setle sbyte 4, 5        <i>; yields {bool}:result = true</i>
1305   &lt;result&gt; = setge sbyte 4, 5        <i>; yields {bool}:result = false</i>
1306 </pre>
1307
1308 </div>
1309
1310 <!-- ======================================================================= -->
1311 <div class="doc_subsection">
1312   <a name="bitwiseops">Bitwise Binary Operations</a>
1313 </div>
1314
1315 <div class="doc_text">
1316
1317 <p>Bitwise binary operators are used to do various forms of bit-twiddling in a
1318 program.  They are generally very efficient instructions, and can commonly be
1319 strength reduced from other instructions.  They require two operands, execute an
1320 operation on them, and produce a single value.  The resulting value of the
1321 bitwise binary operators is always the same type as its first operand.</p>
1322
1323 </div>
1324
1325 <!-- _______________________________________________________________________ -->
1326 <div class="doc_subsubsection">
1327   <a name="i_and">'<tt>and</tt>' Instruction</a>
1328 </div>
1329
1330 <div class="doc_text">
1331
1332 <h5>Syntax:</h5>
1333
1334 <pre>
1335   &lt;result&gt; = and &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1336 </pre>
1337
1338 <h5>Overview:</h5>
1339
1340 <p>The '<tt>and</tt>' instruction returns the bitwise logical and of its two
1341 operands.</p>
1342
1343 <h5>Arguments:</h5>
1344
1345 <p>The two arguments to the '<tt>and</tt>' instruction must be <a
1346 href="#t_integral">integral</a> values.  Both arguments must have identical
1347 types.</p>
1348
1349 <h5>Semantics:</h5>
1350
1351 <p>The truth table used for the '<tt>and</tt>' instruction is:</p>
1352
1353 <p>
1354 <center>
1355 <table border="1" cellspacing="0" cellpadding="4">
1356 <tr><td>In0</td>  <td>In1</td>  <td>Out</td></tr>
1357 <tr><td>0</td>  <td>0</td>  <td>0</td></tr>
1358 <tr><td>0</td>  <td>1</td>  <td>0</td></tr>
1359 <tr><td>1</td>  <td>0</td>  <td>0</td></tr>
1360 <tr><td>1</td>  <td>1</td>  <td>1</td></tr>
1361 </table></center>
1362 </p>
1363
1364 <h5>Example:</h5>
1365
1366 <pre>
1367   &lt;result&gt; = and int 4, %var         <i>; yields {int}:result = 4 & %var</i>
1368   &lt;result&gt; = and int 15, 40          <i>; yields {int}:result = 8</i>
1369   &lt;result&gt; = and int 4, 8            <i>; yields {int}:result = 0</i>
1370 </pre>
1371
1372 </div>
1373
1374 <!-- _______________________________________________________________________ -->
1375 <div class="doc_subsubsection">
1376   <a name="i_or">'<tt>or</tt>' Instruction</a>
1377 </div>
1378
1379 <div class="doc_text">
1380
1381 <h5>Syntax:</h5>
1382
1383 <pre>
1384   &lt;result&gt; = or &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1385 </pre>
1386
1387 <h5>Overview:</h5>
1388
1389 <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive or of its
1390 two operands.</p>
1391
1392 <h5>Arguments:</h5>
1393
1394 <p>The two arguments to the '<tt>or</tt>' instruction must be <a
1395 href="#t_integral">integral</a> values.  Both arguments must have identical
1396 types.</p>
1397
1398 <h5>Semantics:</h5>
1399
1400 <p>The truth table used for the '<tt>or</tt>' instruction is:</p>
1401
1402 <p>
1403 <center><table border="1" cellspacing="0" cellpadding="4">
1404 <tr><td>In0</td>  <td>In1</td>  <td>Out</td></tr>
1405 <tr><td>0</td>  <td>0</td>  <td>0</td></tr>
1406 <tr><td>0</td>  <td>1</td>  <td>1</td></tr>
1407 <tr><td>1</td>  <td>0</td>  <td>1</td></tr>
1408 <tr><td>1</td>  <td>1</td>  <td>1</td></tr>
1409 </table></center>
1410 </p>
1411
1412 <h5>Example:</h5>
1413
1414 <pre>
1415   &lt;result&gt; = or int 4, %var         <i>; yields {int}:result = 4 | %var</i>
1416   &lt;result&gt; = or int 15, 40          <i>; yields {int}:result = 47</i>
1417   &lt;result&gt; = or int 4, 8            <i>; yields {int}:result = 12</i>
1418 </pre>
1419
1420 </div>
1421
1422 <!-- _______________________________________________________________________ -->
1423 <div class="doc_subsubsection">
1424   <a name="i_xor">'<tt>xor</tt>' Instruction</a>
1425 </div>
1426
1427 <div class="doc_text">
1428
1429 <h5>Syntax:</h5>
1430
1431 <pre>
1432   &lt;result&gt; = xor &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1433 </pre>
1434
1435 <h5>Overview:</h5>
1436
1437 <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of
1438 its two operands.  The <tt>xor</tt> is used to implement the "one's complement"
1439 operation, which is the "~" operator in C.</p>
1440
1441 <h5>Arguments:</h5>
1442
1443 <p>The two arguments to the '<tt>xor</tt>' instruction must be <a
1444 href="#t_integral">integral</a> values.  Both arguments must have identical
1445 types.</p>
1446
1447 <h5>Semantics:</h5>
1448
1449 <p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
1450
1451 <p>
1452 <center><table border="1" cellspacing="0" cellpadding="4">
1453 <tr><td>In0</td>  <td>In1</td>  <td>Out</td></tr>
1454 <tr><td>0</td>  <td>0</td>  <td>0</td></tr>
1455 <tr><td>0</td>  <td>1</td>  <td>1</td></tr>
1456 <tr><td>1</td>  <td>0</td>  <td>1</td></tr>
1457 <tr><td>1</td>  <td>1</td>  <td>0</td></tr>
1458 </table></center>
1459 <p>
1460
1461 <h5>Example:</h5>
1462
1463 <pre>
1464   &lt;result&gt; = xor int 4, %var         <i>; yields {int}:result = 4 ^ %var</i>
1465   &lt;result&gt; = xor int 15, 40          <i>; yields {int}:result = 39</i>
1466   &lt;result&gt; = xor int 4, 8            <i>; yields {int}:result = 12</i>
1467   &lt;result&gt; = xor int %V, -1          <i>; yields {int}:result = ~%V</i>
1468 </pre>
1469
1470 </div>
1471
1472 <!-- _______________________________________________________________________ -->
1473 <div class="doc_subsubsection">
1474   <a name="i_shl">'<tt>shl</tt>' Instruction</a>
1475 </div>
1476
1477 <div class="doc_text">
1478
1479 <h5>Syntax:</h5>
1480
1481 <pre>
1482   &lt;result&gt; = shl &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt;   <i>; yields {ty}:result</i>
1483 </pre>
1484
1485 <h5>Overview:</h5>
1486
1487 <p>The '<tt>shl</tt>' instruction returns the first operand shifted to the left
1488 a specified number of bits.</p>
1489
1490 <h5>Arguments:</h5>
1491
1492 <p>The first argument to the '<tt>shl</tt>' instruction must be an <a
1493 href="#t_integer">integer</a> type.  The second argument must be an
1494 '<tt>ubyte</tt>' type.</p>
1495
1496 <h5>Semantics:</h5>
1497
1498 <p>The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.</p>
1499
1500 <h5>Example:</h5>
1501
1502 <pre>
1503   &lt;result&gt; = shl int 4, ubyte %var   <i>; yields {int}:result = 4 << %var</i>
1504   &lt;result&gt; = shl int 4, ubyte 2      <i>; yields {int}:result = 16</i>
1505   &lt;result&gt; = shl int 1, ubyte 10     <i>; yields {int}:result = 1024</i>
1506 </pre>
1507
1508 </div>
1509
1510 <!-- _______________________________________________________________________ -->
1511 <div class="doc_subsubsection">
1512   <a name="i_shr">'<tt>shr</tt>' Instruction</a>
1513 </div>
1514
1515 <div class="doc_text">
1516
1517 <h5>Syntax:</h5>
1518
1519 <pre>
1520   &lt;result&gt; = shr &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt;   <i>; yields {ty}:result</i>
1521 </pre>
1522
1523 <h5>Overview:</h5>
1524
1525 <p>The '<tt>shr</tt>' instruction returns the first operand shifted to the right
1526 a specified number of bits.</p>
1527
1528 <h5>Arguments:</h5>
1529
1530 <p>The first argument to the '<tt>shr</tt>' instruction must be an <a
1531 href="#t_integer">integer</a> type.  The second argument must be an
1532 '<tt>ubyte</tt>' type.</p>
1533
1534 <h5>Semantics:</h5>
1535
1536 <p>If the first argument is a <a href="#t_signed">signed</a> type, the most
1537 significant bit is duplicated in the newly free'd bit positions.  If the first
1538 argument is unsigned, zero bits shall fill the empty positions.</p>
1539
1540 <h5>Example:</h5>
1541
1542 <pre>
1543   &lt;result&gt; = shr int 4, ubyte %var   <i>; yields {int}:result = 4 >> %var</i>
1544   &lt;result&gt; = shr uint 4, ubyte 1     <i>; yields {uint}:result = 2</i>
1545   &lt;result&gt; = shr int 4, ubyte 2      <i>; yields {int}:result = 1</i>
1546   &lt;result&gt; = shr sbyte 4, ubyte 3    <i>; yields {sbyte}:result = 0</i>
1547   &lt;result&gt; = shr sbyte -2, ubyte 1   <i>; yields {sbyte}:result = -1</i>
1548 </pre>
1549
1550 </div>
1551
1552 <!-- ======================================================================= -->
1553 <div class="doc_subsection">
1554   <a name="memoryops">Memory Access Operations</div>
1555 </div>
1556
1557 <div class="doc_text">
1558
1559 <p>A key design point of an SSA-based representation is how it represents
1560 memory.  In LLVM, no memory locations are in SSA form, which makes things very
1561 simple.  This section describes how to read, write, allocate and free memory in
1562 LLVM.</p>
1563
1564 </div>
1565
1566 <!-- _______________________________________________________________________ -->
1567 <div class="doc_subsubsection">
1568   <a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
1569 </div>
1570
1571 <div class="doc_text">
1572
1573 <h5>Syntax:</h5>
1574
1575 <pre>
1576   &lt;result&gt; = malloc &lt;type&gt;, uint &lt;NumElements&gt;     <i>; yields {type*}:result</i>
1577   &lt;result&gt; = malloc &lt;type&gt;                         <i>; yields {type*}:result</i>
1578 </pre>
1579
1580 <h5>Overview:</h5>
1581
1582 <p>The '<tt>malloc</tt>' instruction allocates memory from the system heap and
1583 returns a pointer to it.</p>
1584
1585 <h5>Arguments:</h5>
1586
1587 <p>The the '<tt>malloc</tt>' instruction allocates
1588 <tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory from the operating
1589 system, and returns a pointer of the appropriate type to the program.  The
1590 second form of the instruction is a shorter version of the first instruction
1591 that defaults to allocating one element.</p>
1592
1593 <p>'<tt>type</tt>' must be a sized type.</p>
1594
1595 <h5>Semantics:</h5>
1596
1597 <p>Memory is allocated using the system "<tt>malloc</tt>" function, and a
1598 pointer is returned.</p>
1599
1600 <h5>Example:</h5>
1601
1602 <pre>
1603   %array  = malloc [4 x ubyte ]                    <i>; yields {[%4 x ubyte]*}:array</i>
1604
1605   %size   = <a href="#i_add">add</a> uint 2, 2                          <i>; yields {uint}:size = uint 4</i>
1606   %array1 = malloc ubyte, uint 4                   <i>; yields {ubyte*}:array1</i>
1607   %array2 = malloc [12 x ubyte], uint %size        <i>; yields {[12 x ubyte]*}:array2</i>
1608 </pre>
1609
1610 </div>
1611
1612 <!-- _______________________________________________________________________ -->
1613 <div class="doc_subsubsection">
1614   <a name="i_free">'<tt>free</tt>' Instruction</a>
1615 </div>
1616
1617 <div class="doc_text">
1618
1619 <h5>Syntax:</h5>
1620
1621 <pre>
1622   free &lt;type&gt; &lt;value&gt;                              <i>; yields {void}</i>
1623 </pre>
1624
1625 <h5>Overview:</h5>
1626
1627 <p>The '<tt>free</tt>' instruction returns memory back to the unused memory
1628 heap, to be reallocated in the future.<p>
1629
1630 <h5>Arguments:</h5>
1631
1632 <p>'<tt>value</tt>' shall be a pointer value that points to a value that was
1633 allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' instruction.</p>
1634
1635 <h5>Semantics:</h5>
1636
1637 <p>Access to the memory pointed to by the pointer is not longer defined after
1638 this instruction executes.</p>
1639
1640 <h5>Example:</h5>
1641 <pre>
1642   %array  = <a href="#i_malloc">malloc</a> [4 x ubyte]                    <i>; yields {[4 x ubyte]*}:array</i>
1643             free   [4 x ubyte]* %array
1644 </pre>
1645
1646 </div>
1647
1648 <!-- _______________________________________________________________________ -->
1649 <div class="doc_subsubsection">
1650   <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
1651 </div>
1652
1653 <div class="doc_text">
1654
1655 <h5>Syntax:</h5>
1656
1657 <pre>
1658   &lt;result&gt; = alloca &lt;type&gt;, uint &lt;NumElements&gt;  <i>; yields {type*}:result</i>
1659   &lt;result&gt; = alloca &lt;type&gt;                      <i>; yields {type*}:result</i>
1660 </pre>
1661
1662 <h5>Overview:</h5>
1663
1664 <p>The '<tt>alloca</tt>' instruction allocates memory on the current stack frame
1665 of the procedure that is live until the current function returns to its
1666 caller.</p>
1667
1668 <h5>Arguments:</h5>
1669
1670 <p>The the '<tt>alloca</tt>' instruction allocates
1671 <tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory on the runtime stack,
1672 returning a pointer of the appropriate type to the program.  The second form of
1673 the instruction is a shorter version of the first that defaults to allocating
1674 one element.</p>
1675
1676 <p>'<tt>type</tt>' may be any sized type.</p>
1677
1678 <h5>Semantics:</h5>
1679
1680 <p>Memory is allocated, a pointer is returned.  '<tt>alloca</tt>'d memory is
1681 automatically released when the function returns.  The '<tt>alloca</tt>'
1682 instruction is commonly used to represent automatic variables that must have an
1683 address available.  When the function returns (either with the <tt><a
1684 href="#i_ret">ret</a></tt> or <tt><a href="#i_invoke">invoke</a></tt>
1685 instructions), the memory is reclaimed.</p>
1686
1687 <h5>Example:</h5>
1688
1689 <pre>
1690   %ptr = alloca int                              <i>; yields {int*}:ptr</i>
1691   %ptr = alloca int, uint 4                      <i>; yields {int*}:ptr</i>
1692 </pre>
1693
1694 </div>
1695
1696 <!-- _______________________________________________________________________ -->
1697 <div class="doc_subsubsection">
1698   <a name="i_load">'<tt>load</tt>' Instruction</a>
1699 </div>
1700
1701 <div class="doc_text">
1702
1703 <h5>Syntax:</h5>
1704
1705 <pre>
1706   &lt;result&gt; = load &lt;ty&gt;* &lt;pointer&gt;
1707   &lt;result&gt; = volatile load &lt;ty&gt;* &lt;pointer&gt;
1708 </pre>
1709
1710 <h5>Overview:</h5>
1711
1712 <p>The '<tt>load</tt>' instruction is used to read from memory.</p>
1713
1714 <h5>Arguments:</h5>
1715
1716 <p>The argument to the '<tt>load</tt>' instruction specifies the memory address
1717 to load from.  The pointer must point to a <a href="t_firstclass">first
1718 class</a> type.  If the <tt>load</tt> is marked as <tt>volatile</tt> then the
1719 optimizer is not allowed to modify the number or order of execution of this
1720 <tt>load</tt> with other volatile <tt>load</tt> and <tt><a
1721 href="#i_store">store</a></tt> instructions. </p>
1722
1723 <h5>Semantics:</h5>
1724
1725 <p>The location of memory pointed to is loaded.</p>
1726
1727 <h5>Examples:</h5>
1728
1729 <pre>
1730   %ptr = <a href="#i_alloca">alloca</a> int                               <i>; yields {int*}:ptr</i>
1731   <a href="#i_store">store</a> int 3, int* %ptr                          <i>; yields {void}</i>
1732   %val = load int* %ptr                           <i>; yields {int}:val = int 3</i>
1733 </pre>
1734
1735 </div>
1736
1737 <!-- _______________________________________________________________________ -->
1738 <div class="doc_subsubsection">
1739   <a name="i_store">'<tt>store</tt>' Instruction</a>
1740 </div>
1741
1742 <h5>Syntax:</h5>
1743
1744 <pre>
1745   store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;                   <i>; yields {void}</i>
1746   volatile store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;                   <i>; yields {void}</i>
1747 </pre>
1748
1749 <h5>Overview:</h5>
1750
1751 <p>The '<tt>store</tt>' instruction is used to write to memory.</p>
1752
1753 <h5>Arguments:</h5>
1754
1755 <p>There are two arguments to the '<tt>store</tt>' instruction: a value to store
1756 and an address to store it into.  The type of the '<tt>&lt;pointer&gt;</tt>'
1757 operand must be a pointer to the type of the '<tt>&lt;value&gt;</tt>' operand.
1758 If the <tt>store</tt> is marked as <tt>volatile</tt> then the optimizer is not
1759 allowed to modify the number or order of execution of this <tt>store</tt> with
1760 other volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
1761 instructions.</p>
1762
1763 <h5>Semantics:</h5>
1764
1765 <p>The contents of memory are updated to contain '<tt>&lt;value&gt;</tt>' at the
1766 location specified by the '<tt>&lt;pointer&gt;</tt>' operand.</p>
1767
1768 <h5>Example:</h5>
1769
1770 <pre>
1771   %ptr = <a href="#i_alloca">alloca</a> int                               <i>; yields {int*}:ptr</i>
1772   <a href="#i_store">store</a> int 3, int* %ptr                          <i>; yields {void}</i>
1773   %val = load int* %ptr                           <i>; yields {int}:val = int 3</i>
1774 </pre>
1775
1776 </div>
1777
1778 <!-- _______________________________________________________________________ -->
1779 <div class="doc_subsubsection">
1780   <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
1781 </div>
1782
1783 <div class="doc_text">
1784
1785 <h5>Syntax:</h5>
1786
1787 <pre>
1788   &lt;result&gt; = getelementptr &lt;ty&gt;* &lt;ptrval&gt;{, long &lt;aidx&gt;|, ubyte &lt;sidx&gt;}*
1789 </pre>
1790
1791 <h5>Overview:</h5>
1792
1793 <p>The '<tt>getelementptr</tt>' instruction is used to get the address of a
1794 subelement of an aggregate data structure.</p>
1795
1796 <h5>Arguments:</h5>
1797
1798 <p>This instruction takes a list of <tt>long</tt> values and <tt>ubyte</tt>
1799 constants that indicate what form of addressing to perform.  The actual types of
1800 the arguments provided depend on the type of the first pointer argument.  The
1801 '<tt>getelementptr</tt>' instruction is used to index down through the type
1802 levels of a structure.</p>
1803
1804 <p>For example, let's consider a C code fragment and how it gets compiled to
1805 LLVM:</p>
1806
1807 <pre>
1808 struct RT {
1809   char A;
1810   int B[10][20];
1811   char C;
1812 };
1813 struct ST {
1814   int X;
1815   double Y;
1816   struct RT Z;
1817 };
1818
1819 int *foo(struct ST *s) {
1820   return &amp;s[1].Z.B[5][13];
1821 }
1822 </pre>
1823
1824 <p>The LLVM code generated by the GCC frontend is:</p>
1825
1826 <pre>
1827 %RT = type { sbyte, [10 x [20 x int]], sbyte }
1828 %ST = type { int, double, %RT }
1829
1830 int* "foo"(%ST* %s) {
1831   %reg = getelementptr %ST* %s, long 1, ubyte 2, ubyte 1, long 5, long 13
1832   ret int* %reg
1833 }
1834 </pre>
1835
1836 <h5>Semantics:</h5>
1837
1838 <p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
1839 on the pointer type that is being index into.  <a href="t_pointer">Pointer</a>
1840 and <a href="t_array">array</a> types require '<tt>long</tt>' values, and <a
1841 href="t_struct">structure</a> types require '<tt>ubyte</tt>'
1842 <b>constants</b>.</p>
1843
1844 <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
1845 type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ int, double, %RT
1846 }</tt>' type, a structure.  The second index indexes into the third element of
1847 the structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]],
1848 sbyte }</tt>' type, another structure.  The third index indexes into the second
1849 element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
1850 array.  The two dimensions of the array are subscripted into, yielding an
1851 '<tt>int</tt>' type.  The '<tt>getelementptr</tt>' instruction return a pointer
1852 to this element, thus yielding a '<tt>int*</tt>' type.</p>
1853
1854 <p>Note that it is perfectly legal to index partially through a structure,
1855 returning a pointer to an inner element.  Because of this, the LLVM code for the
1856 given testcase is equivalent to:</p>
1857
1858 <pre>
1859 int* "foo"(%ST* %s) {
1860   %t1 = getelementptr %ST* %s , long 1                        <i>; yields %ST*:%t1</i>
1861   %t2 = getelementptr %ST* %t1, long 0, ubyte 2               <i>; yields %RT*:%t2</i>
1862   %t3 = getelementptr %RT* %t2, long 0, ubyte 1               <i>; yields [10 x [20 x int]]*:%t3</i>
1863   %t4 = getelementptr [10 x [20 x int]]* %t3, long 0, long 5  <i>; yields [20 x int]*:%t4</i>
1864   %t5 = getelementptr [20 x int]* %t4, long 0, long 13        <i>; yields int*:%t5</i>
1865   ret int* %t5
1866 }
1867 </pre>
1868
1869 <h5>Example:</h5>
1870
1871 <pre>
1872   <i>; yields [12 x ubyte]*:aptr</i>
1873   %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, ubyte 1
1874 </pre>
1875
1876 </div>
1877
1878 <!-- ======================================================================= -->
1879 <div class="doc_subsection">
1880   <a name="otherops">Other Operations</a>
1881 </div>
1882
1883 <div class="doc_text">
1884
1885 <p>The instructions in this catagory are the "miscellaneous" instructions, which
1886 defy better classification.</p>
1887
1888 </div>
1889
1890 <!-- _______________________________________________________________________ -->
1891 <div class="doc_subsubsection">
1892   <a name="i_phi">'<tt>phi</tt>' Instruction</a>
1893 </div>
1894
1895 <div class="doc_text">
1896
1897 <h5>Syntax:</h5>
1898
1899 <pre>
1900   &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...
1901 </pre>
1902
1903 <h5>Overview:</h5>
1904
1905 <p>The '<tt>phi</tt>' instruction is used to implement the &phi; node in the SSA
1906 graph representing the function.</p>
1907
1908 <h5>Arguments:</h5>
1909
1910 <p>The type of the incoming values are specified with the first type field.
1911 After this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments,
1912 with one pair for each predecessor basic block of the current block.  Only
1913 values of <a href="#t_firstclass">first class</a> type may be used as the value
1914 arguments to the PHI node.  Only labels may be used as the label arguments.</p>
1915
1916 <p>There must be no non-phi instructions between the start of a basic block and
1917 the PHI instructions: i.e. PHI instructions must be first in a basic block.</p>
1918
1919 <h5>Semantics:</h5>
1920
1921 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value
1922 specified by the parameter, depending on which basic block we came from in the
1923 last <a href="#terminators">terminator</a> instruction.</p>
1924
1925 <h5>Example:</h5>
1926
1927 <pre>
1928 Loop:       ; Infinite loop that counts from 0 on up...
1929   %indvar = phi uint [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
1930   %nextindvar = add uint %indvar, 1
1931   br label %Loop
1932 </pre>
1933
1934 </div>
1935
1936 <!-- _______________________________________________________________________ -->
1937 <div class="doc_subsubsection">
1938   <a name="i_cast">'<tt>cast .. to</tt>' Instruction</a>
1939 </div>
1940
1941 <div class="doc_text">
1942
1943 <h5>Syntax:</h5>
1944
1945 <pre>
1946   &lt;result&gt; = cast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
1947 </pre>
1948
1949 <h5>Overview:</h5>
1950
1951 <p>The '<tt>cast</tt>' instruction is used as the primitive means to convert
1952 integers to floating point, change data type sizes, and break type safety (by
1953 casting pointers).</p>
1954
1955 <h5>Arguments:</h5>
1956
1957 <p>The '<tt>cast</tt>' instruction takes a value to cast, which must be a first
1958 class value, and a type to cast it to, which must also be a <a
1959 href="#t_firstclass">first class</a> type.</p>
1960
1961 <h5>Semantics:</h5>
1962
1963 <p>This instruction follows the C rules for explicit casts when determining how
1964 the data being cast must change to fit in its new container.</p>
1965
1966 <p>When casting to bool, any value that would be considered true in the context
1967 of a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>'
1968 values, all else are '<tt>false</tt>'.</p>
1969
1970 <p>When extending an integral value from a type of one signness to another (for
1971 example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
1972 <b>source</b> value is signed, and zero-extended if the source value is
1973 unsigned.  <tt>bool</tt> values are always zero extended into either zero or
1974 one.</p>
1975
1976 <h5>Example:</h5>
1977
1978 <pre>
1979   %X = cast int 257 to ubyte              <i>; yields ubyte:1</i>
1980   %Y = cast int 123 to bool               <i>; yields bool:true</i>
1981 </pre>
1982
1983 </div>
1984
1985 <!-- _______________________________________________________________________ -->
1986 <div class="doc_subsubsection">
1987   <a name="i_call">'<tt>call</tt>' Instruction</a>
1988 </div>
1989
1990 <div class="doc_text">
1991
1992 <h5>Syntax:</h5>
1993
1994 <pre>
1995   &lt;result&gt; = call &lt;ty&gt;* &lt;fnptrval&gt;(&lt;param list&gt;)
1996 </pre>
1997
1998 <h5>Overview:</h5>
1999
2000 <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
2001
2002 <h5>Arguments:</h5>
2003
2004 <p>This instruction requires several arguments:</p>
2005
2006 <ol>
2007
2008   <li><p>'<tt>ty</tt>': shall be the signature of the pointer to function value
2009   being invoked.  The argument types must match the types implied by this
2010   signature.</p></li>
2011
2012   <li><p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function
2013   to be invoked. In most cases, this is a direct function invocation, but
2014   indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer to
2015   function values.</p></li>
2016
2017   <li><p>'<tt>function args</tt>': argument list whose types match the function
2018   signature argument types.  If the function signature indicates the function
2019   accepts a variable number of arguments, the extra arguments can be
2020   specified.</p></li>
2021
2022 </ol>
2023
2024 <h5>Semantics:</h5>
2025
2026 <p>The '<tt>call</tt>' instruction is used to cause control flow to transfer to
2027 a specified function, with its incoming arguments bound to the specified values.
2028 Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called function,
2029 control flow continues with the instruction after the function call, and the
2030 return value of the function is bound to the result argument.  This is a simpler
2031 case of the <a href="#i_invoke">invoke</a> instruction.</p>
2032
2033 <h5>Example:</h5>
2034
2035 <pre>
2036   %retval = call int %test(int %argc)
2037   call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);
2038 </pre>
2039
2040 </div>
2041
2042 <!-- _______________________________________________________________________ -->
2043 <div class="doc_subsubsection">
2044   <a name="i_vanext">'<tt>vanext</tt>' Instruction</a>
2045 </div>
2046
2047 <div class="doc_text">
2048
2049 <h5>Syntax:</h5>
2050
2051 <pre>
2052   &lt;resultarglist&gt; = vanext &lt;va_list&gt; &lt;arglist&gt;, &lt;argty&gt;
2053 </pre>
2054
2055 <h5>Overview:</h5>
2056
2057 <p>The '<tt>vanext</tt>' instruction is used to access arguments passed through
2058 the "variable argument" area of a function call.  It is used to implement the
2059 <tt>va_arg</tt> macro in C.</p>
2060
2061 <h5>Arguments:</h5>
2062
2063 <p>This instruction takes a <tt>valist</tt> value and the type of the argument.
2064 It returns another <tt>valist</tt>.</p>
2065
2066 <h5>Semantics:</h5>
2067
2068 <p>The '<tt>vanext</tt>' instruction advances the specified <tt>valist</tt> past
2069 an argument of the specified type.  In conjunction with the <a
2070 href="#i_vaarg"><tt>vaarg</tt></a> instruction, it is used to implement the
2071 <tt>va_arg</tt> macro available in C.  For more information, see the variable
2072 argument handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
2073
2074 <p>It is legal for this instruction to be called in a function which does not
2075 take a variable number of arguments, for example, the <tt>vfprintf</tt>
2076 function.</p>
2077
2078 <p><tt>vanext</tt> is an LLVM instruction instead of an <a
2079 href="#intrinsics">intrinsic function</a> because it takes an type as an
2080 argument.</p>
2081
2082 <h5>Example:</h5>
2083
2084 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
2085
2086 </div>
2087
2088 <!-- _______________________________________________________________________ -->
2089 <div class="doc_subsubsection">
2090   <a name="i_vaarg">'<tt>vaarg</tt>' Instruction</a>
2091 </div>
2092
2093 <div class="doc_text">
2094
2095 <h5>Syntax:</h5>
2096
2097 <pre>
2098   &lt;resultval&gt; = vaarg &lt;va_list&gt; &lt;arglist&gt;, &lt;argty&gt;
2099 </pre>
2100
2101 <h5>Overview:</h5>
2102
2103 <p>The '<tt>vaarg</tt>' instruction is used to access arguments passed through
2104 the "variable argument" area of a function call.  It is used to implement the
2105 <tt>va_arg</tt> macro in C.</p>
2106
2107 <h5>Arguments:</h5>
2108
2109 <p>This instruction takes a <tt>valist</tt> value and the type of the argument.
2110 It returns a value of the specified argument type.</p>
2111
2112 <h5>Semantics:</h5>
2113
2114 <p>The '<tt>vaarg</tt>' instruction loads an argument of the specified type from
2115 the specified <tt>va_list</tt>.  In conjunction with the <a
2116 href="#i_vanext"><tt>vanext</tt></a> instruction, it is used to implement the
2117 <tt>va_arg</tt> macro available in C.  For more information, see the variable
2118 argument handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
2119
2120 <p>It is legal for this instruction to be called in a function which does not
2121 take a variable number of arguments, for example, the <tt>vfprintf</tt>
2122 function.</p>
2123
2124 <p><tt>vaarg</tt> is an LLVM instruction instead of an <a
2125 href="#intrinsics">intrinsic function</a> because it takes an type as an
2126 argument.</p>
2127
2128 <h5>Example:</h5>
2129
2130 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
2131
2132 </div>
2133
2134 <!-- *********************************************************************** -->
2135 <div class="doc_section">
2136   <a name="intrinsics">Intrinsic Functions</a>
2137 </div>
2138 <!-- *********************************************************************** -->
2139
2140 <div class="doc_text">
2141
2142 <p>LLVM supports the notion of an "intrinsic function".  These functions have
2143 well known names and semantics, and are required to follow certain restrictions.
2144 Overall, these instructions represent an extension mechanism for the LLVM
2145 language that does not require changing all of the transformations in LLVM to
2146 add to the language (or the bytecode reader/writer, the parser, etc...).</p>
2147
2148 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix, this
2149 prefix is reserved in LLVM for intrinsic names, thus functions may not be named
2150 this.  Intrinsic functions must always be external functions: you cannot define
2151 the body of intrinsic functions.  Intrinsic functions may only be used in call
2152 or invoke instructions: it is illegal to take the address of an intrinsic
2153 function.  Additionally, because intrinsic functions are part of the LLVM
2154 language, it is required that they all be documented here if any are added.</p>
2155
2156 <p>Unless an intrinsic function is target-specific, there must be a lowering
2157 pass to eliminate the intrinsic or all backends must support the intrinsic
2158 function.</p>
2159
2160 </div>
2161
2162 <!-- ======================================================================= -->
2163 <div class="doc_subsection">
2164   <a name="int_varargs">Variable Argument Handling Intrinsics</a>
2165 </div>
2166
2167 <div class="doc_text">
2168
2169 <p>Variable argument support is defined in LLVM with the <a
2170 href="#i_vanext"><tt>vanext</tt></a> instruction and these three intrinsic
2171 functions.  These functions are related to the similarly named macros defined in
2172 the <tt>&lt;stdarg.h&gt;</tt> header file.</p>
2173
2174 <p>All of these functions operate on arguments that use a target-specific value
2175 type "<tt>va_list</tt>".  The LLVM assembly language reference manual does not
2176 define what this type is, so all transformations should be prepared to handle
2177 intrinsics with any type used.</p>
2178
2179 <p>This example shows how the <a href="#i_vanext"><tt>vanext</tt></a>
2180 instruction and the variable argument handling intrinsic functions are used.</p>
2181
2182 <pre>
2183 int %test(int %X, ...) {
2184   ; Initialize variable argument processing
2185   %ap = call sbyte*()* %<a href="#i_va_start">llvm.va_start</a>()
2186
2187   ; Read a single integer argument
2188   %tmp = vaarg sbyte* %ap, int
2189
2190   ; Advance to the next argument
2191   %ap2 = vanext sbyte* %ap, int
2192
2193   ; Demonstrate usage of llvm.va_copy and llvm.va_end
2194   %aq = call sbyte* (sbyte*)* %<a href="#i_va_copy">llvm.va_copy</a>(sbyte* %ap2)
2195   call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %aq)
2196
2197   ; Stop processing of arguments.
2198   call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %ap2)
2199   ret int %tmp
2200 }
2201 </pre>
2202
2203 </div>
2204
2205 <!-- _______________________________________________________________________ -->
2206 <div class="doc_subsubsection">
2207   <a name="i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
2208 </div>
2209
2210 <div class="doc_text">
2211
2212 <h5>Syntax:</h5>
2213
2214 <pre>
2215   call va_list ()* %llvm.va_start()
2216 </pre>
2217
2218 <h5>Overview:</h5>
2219
2220 <p>The '<tt>llvm.va_start</tt>' intrinsic returns a new <tt>&lt;arglist&gt;</tt>
2221 for subsequent use by the variable argument intrinsics.</p>
2222
2223 <h5>Semantics:</h5>
2224
2225 <p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
2226 macro available in C.  In a target-dependent way, it initializes and returns a
2227 <tt>va_list</tt> element, so that the next <tt>vaarg</tt> will produce the first
2228 variable argument passed to the function.  Unlike the C <tt>va_start</tt> macro,
2229 this intrinsic does not need to know the last argument of the function, the
2230 compiler can figure that out.</p>
2231
2232 <p>Note that this intrinsic function is only legal to be called from within the
2233 body of a variable argument function.</p>
2234
2235 </div>
2236
2237 <!-- _______________________________________________________________________ -->
2238 <div class="doc_subsubsection">
2239   <a name="i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
2240 </div>
2241
2242 <div class="doc_text">
2243
2244 <h5>Syntax:</h5>
2245
2246 <pre>
2247   call void (va_list)* %llvm.va_end(va_list &lt;arglist&gt;)
2248 </pre>
2249
2250 <h5>Overview:</h5>
2251
2252 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>&lt;arglist&gt;</tt> which
2253 has been initialized previously with <tt><a
2254 href="#i_va_start">llvm.va_start</a></tt> or <tt><a
2255 href="#i_va_copy">llvm.va_copy</a></tt>.</p>
2256
2257 <h5>Arguments:</h5>
2258
2259 <p>The argument is a <tt>va_list</tt> to destroy.</p>
2260
2261 <h5>Semantics:</h5>
2262
2263 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
2264 macro available in C.  In a target-dependent way, it destroys the
2265 <tt>va_list</tt>.  Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and
2266 <a href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly with
2267 calls to <tt>llvm.va_end</tt>.</p>
2268
2269 </div>
2270
2271 <!-- _______________________________________________________________________ -->
2272 <div class="doc_subsubsection">
2273   <a name="i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
2274 </div>
2275
2276 <div class="doc_text">
2277
2278 <h5>Syntax:</h5>
2279
2280 <pre>
2281   call va_list (va_list)* %llvm.va_copy(va_list &lt;destarglist&gt;)
2282 </pre>
2283
2284 <h5>Overview:</h5>
2285
2286 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position
2287 from the source argument list to the destination argument list.</p>
2288
2289 <h5>Arguments:</h5>
2290
2291 <p>The argument is the <tt>va_list</tt> to copy.</p>
2292
2293 <h5>Semantics:</h5>
2294
2295 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
2296 macro available in C.  In a target-dependent way, it copies the source
2297 <tt>va_list</tt> element into the returned list.  This intrinsic is necessary
2298 because the <tt><a href="i_va_start">llvm.va_start</a></tt> intrinsic may be
2299 arbitrarily complex and require memory allocation, for example.</p>
2300
2301 </div>
2302
2303 <!-- *********************************************************************** -->
2304
2305 <hr>
2306 <div class="doc_footer">
2307   <address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
2308   <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
2309   <br>
2310   Last modified: $Date$
2311 </div>
2312
2313 </body>
2314 </html>