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 be applied to global variables of
 675 pointer
 676 to array type.  When two global variables with appending linkage are linked
 677 together, the two global arrays are appended together.  This is the LLVM,
 678 typesafe, equivalent of having the system linker append together "sections" with
 679 identical names when .o files are linked.<p>
 680
 681 <a name="linkage_external">
 682 <dt><tt><b>externally visible</b></tt>:
 683
 684 <dd>If none of the above identifiers are used, the global is externally visible,
 685 meaning that it participates in linkage and can be used to resolve external
 686 symbol references.<p>
 687
 688 </dl><p>
 689
 690 <p>For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
 691 another module defined a "<tt>.LC0</tt>" variable and was linked with this one,
 692 one of the two would be renamed, preventing a collision.  Since "<tt>main</tt>"
 693 and "<tt>puts</tt>" are external (i.e., lacking any linkage declarations), they
 694 are accessible outside of the current module.  It is illegal for a function
 695 <i>declaration</i> to have any linkage type other than "externally visible".</p>
 696
 697 </div>
 698
 699 <!-- ======================================================================= -->
 700 <div class="doc_subsection">
 701   <a name="globalvars">Global Variables</a>
 702 </div>
 703
 704 <div class="doc_text">
 705
 706 <p>Global variables define regions of memory allocated at compilation time
 707 instead of run-time.  Global variables may optionally be initialized.  A
 708 variable may be defined as a global "constant", which indicates that the
 709 contents of the variable will never be modified (opening options for
 710 optimization).  Constants must always have an initial value.</p>
 711
 712 <p>As SSA values, global variables define pointer values that are in scope
 713 (i.e. they dominate) for all basic blocks in the program.  Global variables
 714 always define a pointer to their "content" type because they describe a region
 715 of memory, and all memory objects in LLVM are accessed through pointers.</p>
 716
 717 </div>
 718
 719 <!-- ======================================================================= -->
 720 <div class="doc_subsection">
 721   <a name="functionstructure">Functions</a>
 722 </div>
 723
 724 <div class="doc_text">
 725
 726 <p>LLVM function definitions are composed of a (possibly empty) argument list,
 727 an opening curly brace, a list of basic blocks, and a closing curly brace.  LLVM
 728 function declarations are defined with the "<tt>declare</tt>" keyword, a
 729 function name, and a function signature.</p>
 730
 731 <p>A function definition contains a list of basic blocks, forming the CFG for
 732 the function.  Each basic block may optionally start with a label (giving the
 733 basic block a symbol table entry), contains a list of instructions, and ends
 734 with a <a href="#terminators">terminator</a> instruction (such as a branch or
 735 function return).</p>
 736
 737 <p>The first basic block in program is special in two ways: it is immediately
 738 executed on entrance to the function, and it is not allowed to have predecessor
 739 basic blocks (i.e. there can not be any branches to the entry block of a
 740 function).  Because the block can have no predecessors, it also cannot have any
 741 <a href="#i_phi">PHI nodes</a>.</p>
 742
 743 </div>
 744
 745 <!-- *********************************************************************** -->
 746 <div class="doc_section">
 747   <a name="instref">Instruction Reference</a>
 748 </div>
 749 <!-- *********************************************************************** -->
 750
 751 <div class="doc_text">
 752
 753 <p>The LLVM instruction set consists of several different classifications of
 754 instructions: <a href="#terminators">terminator instructions</a>, <a
 755 href="#binaryops">binary instructions</a>, <a href="#memoryops">memory
 756 instructions</a>, and <a href="#otherops">other instructions</a>.</p>
 757
 758 </div>
 759
 760 <!-- ======================================================================= -->
 761 <div class="doc_subsection">
 762   <a name="terminators">Terminator Instructions</a>
 763 </div>
 764
 765 <div class="doc_text">
 766
 767 <p>As mentioned <a href="#functionstructure">previously</a>, every basic block
 768 in a program ends with a "Terminator" instruction, which indicates which block
 769 should be executed after the current block is finished. These terminator
 770 instructions typically yield a '<tt>void</tt>' value: they produce control flow,
 771 not values (the one exception being the '<a
 772 href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
 773
 774 <p>There are five different terminator instructions: the '<a
 775 href="#i_ret"><tt>ret</tt></a>' instruction, the '<a
 776 href="#i_br"><tt>br</tt></a>' instruction, the '<a
 777 href="#i_switch"><tt>switch</tt></a>' instruction, the '<a
 778 href="#i_invoke"><tt>invoke</tt></a>' instruction, and the '<a
 779 href="#i_unwind"><tt>unwind</tt></a>' instruction.</p>
 780
 781 </div>
 782
 783 <!-- _______________________________________________________________________ -->
 784 <div class="doc_subsubsection">
 785   <a name="i_ret">'<tt>ret</tt>' Instruction</a>
 786 </div>
 787
 788 <div class="doc_text">
 789
 790 <h5>Syntax:</h5>
 791 <pre>
 792   ret &lt;type&gt; &lt;value&gt;       <i>; Return a value from a non-void function</i>
 793   ret void                 <i>; Return from void function</i>
 794 </pre>
 795
 796 <h5>Overview:</h5>
 797
 798 <p>The '<tt>ret</tt>' instruction is used to return control flow (and a value)
 799 from a function, back to the caller.</p>
 800
 801 <p>There are two forms of the '<tt>ret</tt>' instructruction: one that returns a
 802 value and then causes control flow, and one that just causes control flow to
 803 occur.</p>
 804
 805 <h5>Arguments:</h5>
 806
 807 <p>The '<tt>ret</tt>' instruction may return any '<a href="#t_firstclass">first
 808 class</a>' type.  Notice that a function is not <a href="#wellformed">well
 809 formed</a> if there exists a '<tt>ret</tt>' instruction inside of the function
 810 that returns a value that does not match the return type of the function.</p>
 811
 812 <h5>Semantics:</h5>
 813
 814 <p>When the '<tt>ret</tt>' instruction is executed, control flow returns back to
 815 the calling function's context.  If the caller is a "<a
 816 href="#i_call"><tt>call</tt></a> instruction, execution continues at the
 817 instruction after the call.  If the caller was an "<a
 818 href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at the
 819 beginning "normal" of the destination block.  If the instruction returns a
 820 value, that value shall set the call or invoke instruction's return value.</p>
 821
 822 <h5>Example:</h5>
 823 <pre>
 824   ret int 5                       <i>; Return an integer value of 5</i>
 825   ret void                        <i>; Return from a void function</i>
 826 </pre>
 827
 828 </div>
 829
 830 <!-- _______________________________________________________________________ -->
 831 <div class="doc_subsubsection">
 832   <a name="i_br">'<tt>br</tt>' Instruction</a>
 833 </div>
 834
 835 <div class="doc_text">
 836
 837 <h5>Syntax:</h5>
 838
 839 <pre>
 840   br bool &lt;cond&gt;, label &lt;iftrue&gt;, label &lt;iffalse&gt;
 841   br label &lt;dest&gt;          <i>; Unconditional branch</i>
 842 </pre>
 843
 844 <h5>Overview:</h5>
 845
 846 <p>The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
 847 different basic block in the current function.  There are two forms of this
 848 instruction, corresponding to a conditional branch and an unconditional
 849 branch.</p>
 850
 851 <h5>Arguments:</h5>
 852
 853 <p>The conditional branch form of the '<tt>br</tt>' instruction takes a single
 854 '<tt>bool</tt>' value and two '<tt>label</tt>' values.  The unconditional form
 855 of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
 856 target.</p>
 857
 858 <h5>Semantics:</h5>
 859
 860 <p>Upon execution of a conditional '<tt>br</tt>' instruction, the
 861 '<tt>bool</tt>' argument is evaluated.  If the value is <tt>true</tt>, control
 862 flows to the '<tt>iftrue</tt>' <tt>label</tt> argument.  If "cond" is
 863 <tt>false</tt>, control flows to the '<tt>iffalse</tt>' <tt>label</tt>
 864 argument.</p>
 865
 866 <h5>Example:</h5>
 867
 868 <pre>
 869 Test:
 870   %cond = <a href="#i_setcc">seteq</a> int %a, %b
 871   br bool %cond, label %IfEqual, label %IfUnequal
 872 IfEqual:
 873   <a href="#i_ret">ret</a> int 1
 874 IfUnequal:
 875   <a href="#i_ret">ret</a> int 0
 876 </pre>
 877
 878 </div>
 879
 880 <!-- _______________________________________________________________________ -->
 881 <div class="doc_subsubsection">
 882   <a name="i_switch">'<tt>switch</tt>' Instruction</a>
 883 </div>
 884
 885 <div class="doc_text">
 886
 887 <h5>Syntax:</h5>
 888
 889 <pre>
 890   switch uint &lt;value&gt;, label &lt;defaultdest&gt; [ int &lt;val&gt;, label &dest&gt;, ... ]
 891 </pre>
 892
 893 <h5>Overview:</h5>
 894
 895 <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
 896 several different places.  It is a generalization of the '<tt>br</tt>'
 897 instruction, allowing a branch to occur to one of many possible
 898 destinations.</p>
 899
 900 <h5>Arguments:</h5>
 901
 902 <p>The '<tt>switch</tt>' instruction uses three parameters: a '<tt>uint</tt>'
 903 comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
 904 an array of pairs of comparison value constants and '<tt>label</tt>'s.</p>
 905
 906 <h5>Semantics:</h5>
 907
 908 <p>The <tt>switch</tt> instruction specifies a table of values and destinations.
 909 When the '<tt>switch</tt>' instruction is executed, this table is searched for
 910 the given value.  If the value is found, the corresponding destination is
 911 branched to, otherwise the default value it transfered to.</p>
 912
 913 <h5>Implementation:</h5>
 914
 915 <p>Depending on properties of the target machine and the particular
 916 <tt>switch</tt> instruction, this instruction may be code generated as a series
 917 of chained conditional branches, or with a lookup table.</p>
 918
 919 <h5>Example:</h5>
 920
 921 <pre>
 922   <i>; Emulate a conditional br instruction</i>
 923   %Val = <a href="#i_cast">cast</a> bool %value to uint
 924   switch uint %Val, label %truedest [int 0, label %falsedest ]
 925
 926   <i>; Emulate an unconditional br instruction</i>
 927   switch uint 0, label %dest [ ]
 928
 929   <i>; Implement a jump table:</i>
 930   switch uint %val, label %otherwise [ int 0, label %onzero,
 931                                        int 1, label %onone,
 932                                        int 2, label %ontwo ]
 933 </pre>
 934
 935 </div>
 936
 937 <!-- _______________________________________________________________________ -->
 938 <div class="doc_subsubsection">
 939   <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
 940 </div>
 941
 942 <div class="doc_text">
 943
 944 <h5>Syntax:</h5>
 945
 946 <pre>
 947   &lt;result&gt; = invoke &lt;ptr to function ty&gt; %&lt;function ptr val&gt;(&lt;function args&gt;)
 948                  to label &lt;normal label&gt; except label &lt;exception label&gt;
 949 </pre>
 950
 951 <h5>Overview:</h5>
 952
 953 <p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified
 954 function, with the possibility of control flow transfer to either the
 955 '<tt>normal</tt>' <tt>label</tt> label or the '<tt>exception</tt>'
 956 <tt>label</tt>.  If the callee function returns with the "<tt><a
 957 href="#i_ret">ret</a></tt>" instruction, control flow will return to the
 958 "normal" label.  If the callee (or any indirect callees) returns with the "<a
 959 href="#i_unwind"><tt>unwind</tt></a>" instruction, control is interrupted, and
 960 continued at the dynamically nearest "except" label.</p>
 961
 962 <h5>Arguments:</h5>
 963
 964 <p>This instruction requires several arguments:</p>
 965
 966 <ol>
 967
 968 <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
 969 function value being invoked.  In most cases, this is a direct function
 970 invocation, but indirect <tt>invoke</tt>s are just as possible, branching off
 971 an arbitrary pointer to function value.
 972
 973 <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
 974 function to be invoked.
 975
 976 <li>'<tt>function args</tt>': argument list whose types match the function
 977 signature argument types.  If the function signature indicates the function
 978 accepts a variable number of arguments, the extra arguments can be specified.
 979
 980 <li>'<tt>normal label</tt>': the label reached when the called function executes
 981 a '<tt><a href="#i_ret">ret</a></tt>' instruction.
 982
 983 <li>'<tt>exception label</tt>': the label reached when a callee returns with the
 984 <a href="#i_unwind"><tt>unwind</tt></a> instruction.
 985 </ol>
 986
 987 <h5>Semantics:</h5>
 988
 989 <p>This instruction is designed to operate as a standard '<tt><a
 990 href="#i_call">call</a></tt>' instruction in most regards.  The primary
 991 difference is that it establishes an association with a label, which is used by the runtime library to unwind the stack.</p>
 992
 993 <p>This instruction is used in languages with destructors to ensure that proper
 994 cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
 995 exception.  Additionally, this is important for implementation of
 996 '<tt>catch</tt>' clauses in high-level languages that support them.</p>
 997
 998 <h5>Example:</h5>
 999
1000 <pre>
1001   %retval = invoke int %Test(int 15)
1002               to label %Continue
1003               except label %TestCleanup     <i>; {int}:retval set</i>
1004 </pre>
1005
1006 </div>
1007
1008 <!-- _______________________________________________________________________ -->
1009 <div class="doc_subsubsection">
1010   <a name="i_unwind">'<tt>unwind</tt>' Instruction</a>
1011 </div>
1012
1013 <div class="doc_text">
1014
1015 <h5>Syntax:</h5>
1016
1017 <pre>
1018   unwind
1019 </pre>
1020
1021 <h5>Overview:</h5>
1022
1023 <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow
1024 at the first callee in the dynamic call stack which used an <a
1025 href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call.  This is
1026 primarily used to implement exception handling.</p>
1027
1028 <h5>Semantics:</h5>
1029
1030 <p>The '<tt>unwind</tt>' intrinsic causes execution of the current function to
1031 immediately halt.  The dynamic call stack is then searched for the first <a
1032 href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack.  Once found,
1033 execution continues at the "exceptional" destination block specified by the
1034 <tt>invoke</tt> instruction.  If there is no <tt>invoke</tt> instruction in the
1035 dynamic call chain, undefined behavior results.</p>
1036
1037 </div>
1038
1039 <!-- ======================================================================= -->
1040 <div class="doc_subsection">
1041   <a name="binaryops">Binary Operations</a>
1042 </div>
1043
1044 <div class="doc_text">
1045
1046 <p>Binary operators are used to do most of the computation in a program.  They
1047 require two operands, execute an operation on them, and produce a single value.
1048 The result value of a binary operator is not necessarily the same type as its
1049 operands.</p>
1050
1051 <p>There are several different binary operators:</p>
1052
1053 </div>
1054
1055 <!-- _______________________________________________________________________ -->
1056 <div class="doc_subsubsection">
1057   <a name="i_add">'<tt>add</tt>' Instruction</a>
1058 </div>
1059
1060 <div class="doc_text">
1061
1062 <h5>Syntax:</h5>
1063
1064 <pre>
1065   &lt;result&gt; = add &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1066 </pre>
1067
1068 <h5>Overview:</h5>
1069
1070 <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
1071
1072 <h5>Arguments:</h5>
1073
1074 <p>The two arguments to the '<tt>add</tt>' instruction must be either <a
1075 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1076 values.  Both arguments must have identical types.</p>
1077
1078 <h5>Semantics:</h5>
1079
1080 <p>The value produced is the integer or floating point sum of the two
1081 operands.</p>
1082
1083 <h5>Example:</h5>
1084
1085 <pre>
1086   &lt;result&gt; = add int 4, %var          <i>; yields {int}:result = 4 + %var</i>
1087 </pre>
1088
1089 </div>
1090
1091 <!-- _______________________________________________________________________ -->
1092 <div class="doc_subsubsection">
1093   <a name="i_sub">'<tt>sub</tt>' Instruction</a>
1094 </div>
1095
1096 <div class="doc_text">
1097
1098 <h5>Syntax:</h5>
1099
1100 <pre>
1101   &lt;result&gt; = sub &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1102 </pre>
1103
1104 <h5>Overview:</h5>
1105
1106 <p>The '<tt>sub</tt>' instruction returns the difference of its two
1107 operands.</p>
1108
1109 <p>Note that the '<tt>sub</tt>' instruction is used to represent the
1110 '<tt>neg</tt>' instruction present in most other intermediate
1111 representations.</p>
1112
1113 <h5>Arguments:</h5>
1114
1115 <p>The two arguments to the '<tt>sub</tt>' instruction must be either <a
1116 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1117 values.  Both arguments must have identical types.</p>
1118
1119 <h5>Semantics:</h5>
1120
1121 <p>The value produced is the integer or floating point difference of the two
1122 operands.</p>
1123
1124 <h5>Example:</h5>
1125
1126 <pre>
1127   &lt;result&gt; = sub int 4, %var          <i>; yields {int}:result = 4 - %var</i>
1128   &lt;result&gt; = sub int 0, %val          <i>; yields {int}:result = -%var</i>
1129 </pre>
1130
1131 </div>
1132
1133 <!-- _______________________________________________________________________ -->
1134 <div class="doc_subsubsection">
1135   <a name="i_mul">'<tt>mul</tt>' Instruction</a>
1136 </div>
1137
1138 <div class="doc_text">
1139
1140 <h5>Syntax:</h5>
1141
1142 <pre>
1143   &lt;result&gt; = mul &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1144 </pre>
1145
1146 <h5>Overview:</h5>
1147
1148 <p>The  '<tt>mul</tt>' instruction returns the product of its two operands.</p>
1149
1150 <h5>Arguments:</h5>
1151
1152 <p>The two arguments to the '<tt>mul</tt>' instruction must be either <a
1153 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1154 values.  Both arguments must have identical types.</p>
1155
1156 <h5>Semantics:</h5>
1157
1158 <p>The value produced is the integer or floating point product of the two
1159 operands.</p>
1160
1161 <p>There is no signed vs unsigned multiplication.  The appropriate action is
1162 taken based on the type of the operand.</p>
1163
1164 <h5>Example:</h5>
1165
1166 <pre>
1167   &lt;result&gt; = mul int 4, %var          <i>; yields {int}:result = 4 * %var</i>
1168 </pre>
1169
1170 </div>
1171
1172 <!-- _______________________________________________________________________ -->
1173 <div class="doc_subsubsection">
1174   <a name="i_div">'<tt>div</tt>' Instruction</a>
1175 </div>
1176
1177 <div class="doc_text">
1178
1179 <h5>Syntax:</h5>
1180
1181 <pre>
1182   &lt;result&gt; = div &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1183 </pre>
1184
1185 <h5>Overview:</h5>
1186
1187 <p>The '<tt>div</tt>' instruction returns the quotient of its two operands.</p>
1188
1189 <h5>Arguments:</h5>
1190
1191 <p>The two arguments to the '<tt>div</tt>' instruction must be either <a
1192 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1193 values.  Both arguments must have identical types.</p>
1194
1195 <h5>Semantics:</h5>
1196
1197 <p>The value produced is the integer or floating point quotient of the two
1198 operands.</p>
1199
1200 <h5>Example:</h5>
1201
1202 <pre>
1203   &lt;result&gt; = div int 4, %var          <i>; yields {int}:result = 4 / %var</i>
1204 </pre>
1205
1206 </div>
1207
1208 <!-- _______________________________________________________________________ -->
1209 <div class="doc_subsubsection">
1210   <a name="i_rem">'<tt>rem</tt>' Instruction</a>
1211 </div>
1212
1213 <div class="doc_text">
1214
1215 <h5>Syntax:</h5>
1216
1217 <pre>
1218   &lt;result&gt; = rem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1219 </pre>
1220
1221 <h5>Overview:</h5>
1222
1223 <p>The '<tt>rem</tt>' instruction returns the remainder from the division of its
1224 two operands.</p>
1225
1226 <h5>Arguments:</h5>
1227
1228 <p>The two arguments to the '<tt>rem</tt>' instruction must be either <a
1229 href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1230 values.  Both arguments must have identical types.</p>
1231
1232 <h5>Semantics:</h5>
1233
1234 <p>This returns the <i>remainder</i> of a division (where the result has the
1235 same sign as the divisor), not the <i>modulus</i> (where the result has the same
1236 sign as the dividend) of a value.  For more information about the difference,
1237 see: <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The Math
1238 Forum</a>.</p>
1239
1240 <h5>Example:</h5>
1241
1242 <pre>
1243   &lt;result&gt; = rem int 4, %var          <i>; yields {int}:result = 4 % %var</i>
1244 </pre>
1245
1246 </div>
1247
1248 <!-- _______________________________________________________________________ -->
1249 <div class="doc_subsubsection">
1250   <a name="i_setcc">'<tt>set<i>cc</i></tt>' Instructions</a>
1251 </div>
1252
1253 <div class="doc_text">
1254
1255 <h5>Syntax:</h5>
1256
1257 <pre>
1258   &lt;result&gt; = seteq &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1259   &lt;result&gt; = setne &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1260   &lt;result&gt; = setlt &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1261   &lt;result&gt; = setgt &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1262   &lt;result&gt; = setle &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1263   &lt;result&gt; = setge &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
1264 </pre>
1265
1266 <h5>Overview:</h5>
1267
1268 <p>The '<tt>set<i>cc</i></tt>' family of instructions returns a boolean value
1269 based on a comparison of their two operands.</p>
1270
1271 <h5>Arguments:</h5>
1272
1273 <p>The two arguments to the '<tt>set<i>cc</i></tt>' instructions must be of <a
1274 href="#t_firstclass">first class</a> type (it is not possible to compare
1275 '<tt>label</tt>'s, '<tt>array</tt>'s, '<tt>structure</tt>' or '<tt>void</tt>'
1276 values, etc...).  Both arguments must have identical types.</p>
1277
1278 <h5>Semantics:</h5>
1279
1280 <p>The '<tt>seteq</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value
1281 if both operands are equal.<br>
1282
1283 The '<tt>setne</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1284 both operands are unequal.<br>
1285
1286 The '<tt>setlt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1287 the first operand is less than the second operand.<br>
1288
1289 The '<tt>setgt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1290 the first operand is greater than the second operand.<br>
1291
1292 The '<tt>setle</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1293 the first operand is less than or equal to the second operand.<br>
1294
1295 The '<tt>setge</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
1296 the first operand is greater than or equal to the second operand.</p>
1297
1298 <h5>Example:</h5>
1299
1300 <pre>
1301   &lt;result&gt; = seteq int   4, 5        <i>; yields {bool}:result = false</i>
1302   &lt;result&gt; = setne float 4, 5        <i>; yields {bool}:result = true</i>
1303   &lt;result&gt; = setlt uint  4, 5        <i>; yields {bool}:result = true</i>
1304   &lt;result&gt; = setgt sbyte 4, 5        <i>; yields {bool}:result = false</i>
1305   &lt;result&gt; = setle sbyte 4, 5        <i>; yields {bool}:result = true</i>
1306   &lt;result&gt; = setge sbyte 4, 5        <i>; yields {bool}:result = false</i>
1307 </pre>
1308
1309 </div>
1310
1311 <!-- ======================================================================= -->
1312 <div class="doc_subsection">
1313   <a name="bitwiseops">Bitwise Binary Operations</a>
1314 </div>
1315
1316 <div class="doc_text">
1317
1318 <p>Bitwise binary operators are used to do various forms of bit-twiddling in a
1319 program.  They are generally very efficient instructions, and can commonly be
1320 strength reduced from other instructions.  They require two operands, execute an
1321 operation on them, and produce a single value.  The resulting value of the
1322 bitwise binary operators is always the same type as its first operand.</p>
1323
1324 </div>
1325
1326 <!-- _______________________________________________________________________ -->
1327 <div class="doc_subsubsection">
1328   <a name="i_and">'<tt>and</tt>' Instruction</a>
1329 </div>
1330
1331 <div class="doc_text">
1332
1333 <h5>Syntax:</h5>
1334
1335 <pre>
1336   &lt;result&gt; = and &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1337 </pre>
1338
1339 <h5>Overview:</h5>
1340
1341 <p>The '<tt>and</tt>' instruction returns the bitwise logical and of its two
1342 operands.</p>
1343
1344 <h5>Arguments:</h5>
1345
1346 <p>The two arguments to the '<tt>and</tt>' instruction must be <a
1347 href="#t_integral">integral</a> values.  Both arguments must have identical
1348 types.</p>
1349
1350 <h5>Semantics:</h5>
1351
1352 <p>The truth table used for the '<tt>and</tt>' instruction is:</p>
1353
1354 <p>
1355 <center>
1356 <table border="1" cellspacing="0" cellpadding="4">
1357 <tr><td>In0</td>  <td>In1</td>  <td>Out</td></tr>
1358 <tr><td>0</td>  <td>0</td>  <td>0</td></tr>
1359 <tr><td>0</td>  <td>1</td>  <td>0</td></tr>
1360 <tr><td>1</td>  <td>0</td>  <td>0</td></tr>
1361 <tr><td>1</td>  <td>1</td>  <td>1</td></tr>
1362 </table></center>
1363 </p>
1364
1365 <h5>Example:</h5>
1366
1367 <pre>
1368   &lt;result&gt; = and int 4, %var         <i>; yields {int}:result = 4 & %var</i>
1369   &lt;result&gt; = and int 15, 40          <i>; yields {int}:result = 8</i>
1370   &lt;result&gt; = and int 4, 8            <i>; yields {int}:result = 0</i>
1371 </pre>
1372
1373 </div>
1374
1375 <!-- _______________________________________________________________________ -->
1376 <div class="doc_subsubsection">
1377   <a name="i_or">'<tt>or</tt>' Instruction</a>
1378 </div>
1379
1380 <div class="doc_text">
1381
1382 <h5>Syntax:</h5>
1383
1384 <pre>
1385   &lt;result&gt; = or &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1386 </pre>
1387
1388 <h5>Overview:</h5>
1389
1390 <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive or of its
1391 two operands.</p>
1392
1393 <h5>Arguments:</h5>
1394
1395 <p>The two arguments to the '<tt>or</tt>' instruction must be <a
1396 href="#t_integral">integral</a> values.  Both arguments must have identical
1397 types.</p>
1398
1399 <h5>Semantics:</h5>
1400
1401 <p>The truth table used for the '<tt>or</tt>' instruction is:</p>
1402
1403 <p>
1404 <center><table border="1" cellspacing="0" cellpadding="4">
1405 <tr><td>In0</td>  <td>In1</td>  <td>Out</td></tr>
1406 <tr><td>0</td>  <td>0</td>  <td>0</td></tr>
1407 <tr><td>0</td>  <td>1</td>  <td>1</td></tr>
1408 <tr><td>1</td>  <td>0</td>  <td>1</td></tr>
1409 <tr><td>1</td>  <td>1</td>  <td>1</td></tr>
1410 </table></center>
1411 </p>
1412
1413 <h5>Example:</h5>
1414
1415 <pre>
1416   &lt;result&gt; = or int 4, %var         <i>; yields {int}:result = 4 | %var</i>
1417   &lt;result&gt; = or int 15, 40          <i>; yields {int}:result = 47</i>
1418   &lt;result&gt; = or int 4, 8            <i>; yields {int}:result = 12</i>
1419 </pre>
1420
1421 </div>
1422
1423 <!-- _______________________________________________________________________ -->
1424 <div class="doc_subsubsection">
1425   <a name="i_xor">'<tt>xor</tt>' Instruction</a>
1426 </div>
1427
1428 <div class="doc_text">
1429
1430 <h5>Syntax:</h5>
1431
1432 <pre>
1433   &lt;result&gt; = xor &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1434 </pre>
1435
1436 <h5>Overview:</h5>
1437
1438 <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of
1439 its two operands.  The <tt>xor</tt> is used to implement the "one's complement"
1440 operation, which is the "~" operator in C.</p>
1441
1442 <h5>Arguments:</h5>
1443
1444 <p>The two arguments to the '<tt>xor</tt>' instruction must be <a
1445 href="#t_integral">integral</a> values.  Both arguments must have identical
1446 types.</p>
1447
1448 <h5>Semantics:</h5>
1449
1450 <p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
1451
1452 <p>
1453 <center><table border="1" cellspacing="0" cellpadding="4">
1454 <tr><td>In0</td>  <td>In1</td>  <td>Out</td></tr>
1455 <tr><td>0</td>  <td>0</td>  <td>0</td></tr>
1456 <tr><td>0</td>  <td>1</td>  <td>1</td></tr>
1457 <tr><td>1</td>  <td>0</td>  <td>1</td></tr>
1458 <tr><td>1</td>  <td>1</td>  <td>0</td></tr>
1459 </table></center>
1460 <p>
1461
1462 <h5>Example:</h5>
1463
1464 <pre>
1465   &lt;result&gt; = xor int 4, %var         <i>; yields {int}:result = 4 ^ %var</i>
1466   &lt;result&gt; = xor int 15, 40          <i>; yields {int}:result = 39</i>
1467   &lt;result&gt; = xor int 4, 8            <i>; yields {int}:result = 12</i>
1468   &lt;result&gt; = xor int %V, -1          <i>; yields {int}:result = ~%V</i>
1469 </pre>
1470
1471 </div>
1472
1473 <!-- _______________________________________________________________________ -->
1474 <div class="doc_subsubsection">
1475   <a name="i_shl">'<tt>shl</tt>' Instruction</a>
1476 </div>
1477
1478 <div class="doc_text">
1479
1480 <h5>Syntax:</h5>
1481
1482 <pre>
1483   &lt;result&gt; = shl &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt;   <i>; yields {ty}:result</i>
1484 </pre>
1485
1486 <h5>Overview:</h5>
1487
1488 <p>The '<tt>shl</tt>' instruction returns the first operand shifted to the left
1489 a specified number of bits.</p>
1490
1491 <h5>Arguments:</h5>
1492
1493 <p>The first argument to the '<tt>shl</tt>' instruction must be an <a
1494 href="#t_integer">integer</a> type.  The second argument must be an
1495 '<tt>ubyte</tt>' type.</p>
1496
1497 <h5>Semantics:</h5>
1498
1499 <p>The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.</p>
1500
1501 <h5>Example:</h5>
1502
1503 <pre>
1504   &lt;result&gt; = shl int 4, ubyte %var   <i>; yields {int}:result = 4 << %var</i>
1505   &lt;result&gt; = shl int 4, ubyte 2      <i>; yields {int}:result = 16</i>
1506   &lt;result&gt; = shl int 1, ubyte 10     <i>; yields {int}:result = 1024</i>
1507 </pre>
1508
1509 </div>
1510
1511 <!-- _______________________________________________________________________ -->
1512 <div class="doc_subsubsection">
1513   <a name="i_shr">'<tt>shr</tt>' Instruction</a>
1514 </div>
1515
1516 <div class="doc_text">
1517
1518 <h5>Syntax:</h5>
1519
1520 <pre>
1521   &lt;result&gt; = shr &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt;   <i>; yields {ty}:result</i>
1522 </pre>
1523
1524 <h5>Overview:</h5>
1525
1526 <p>The '<tt>shr</tt>' instruction returns the first operand shifted to the right
1527 a specified number of bits.</p>
1528
1529 <h5>Arguments:</h5>
1530
1531 <p>The first argument to the '<tt>shr</tt>' instruction must be an <a
1532 href="#t_integer">integer</a> type.  The second argument must be an
1533 '<tt>ubyte</tt>' type.</p>
1534
1535 <h5>Semantics:</h5>
1536
1537 <p>If the first argument is a <a href="#t_signed">signed</a> type, the most
1538 significant bit is duplicated in the newly free'd bit positions.  If the first
1539 argument is unsigned, zero bits shall fill the empty positions.</p>
1540
1541 <h5>Example:</h5>
1542
1543 <pre>
1544   &lt;result&gt; = shr int 4, ubyte %var   <i>; yields {int}:result = 4 >> %var</i>
1545   &lt;result&gt; = shr uint 4, ubyte 1     <i>; yields {uint}:result = 2</i>
1546   &lt;result&gt; = shr int 4, ubyte 2      <i>; yields {int}:result = 1</i>
1547   &lt;result&gt; = shr sbyte 4, ubyte 3    <i>; yields {sbyte}:result = 0</i>
1548   &lt;result&gt; = shr sbyte -2, ubyte 1   <i>; yields {sbyte}:result = -1</i>
1549 </pre>
1550
1551 </div>
1552
1553 <!-- ======================================================================= -->
1554 <div class="doc_subsection">
1555   <a name="memoryops">Memory Access Operations</div>
1556 </div>
1557
1558 <div class="doc_text">
1559
1560 <p>A key design point of an SSA-based representation is how it represents
1561 memory.  In LLVM, no memory locations are in SSA form, which makes things very
1562 simple.  This section describes how to read, write, allocate and free memory in
1563 LLVM.</p>
1564
1565 </div>
1566
1567 <!-- _______________________________________________________________________ -->
1568 <div class="doc_subsubsection">
1569   <a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
1570 </div>
1571
1572 <div class="doc_text">
1573
1574 <h5>Syntax:</h5>
1575
1576 <pre>
1577   &lt;result&gt; = malloc &lt;type&gt;, uint &lt;NumElements&gt;     <i>; yields {type*}:result</i>
1578   &lt;result&gt; = malloc &lt;type&gt;                         <i>; yields {type*}:result</i>
1579 </pre>
1580
1581 <h5>Overview:</h5>
1582
1583 <p>The '<tt>malloc</tt>' instruction allocates memory from the system heap and
1584 returns a pointer to it.</p>
1585
1586 <h5>Arguments:</h5>
1587
1588 <p>The the '<tt>malloc</tt>' instruction allocates
1589 <tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory from the operating
1590 system, and returns a pointer of the appropriate type to the program.  The
1591 second form of the instruction is a shorter version of the first instruction
1592 that defaults to allocating one element.</p>
1593
1594 <p>'<tt>type</tt>' must be a sized type.</p>
1595
1596 <h5>Semantics:</h5>
1597
1598 <p>Memory is allocated using the system "<tt>malloc</tt>" function, and a
1599 pointer is returned.</p>
1600
1601 <h5>Example:</h5>
1602
1603 <pre>
1604   %array  = malloc [4 x ubyte ]                    <i>; yields {[%4 x ubyte]*}:array</i>
1605
1606   %size   = <a href="#i_add">add</a> uint 2, 2                          <i>; yields {uint}:size = uint 4</i>
1607   %array1 = malloc ubyte, uint 4                   <i>; yields {ubyte*}:array1</i>
1608   %array2 = malloc [12 x ubyte], uint %size        <i>; yields {[12 x ubyte]*}:array2</i>
1609 </pre>
1610
1611 </div>
1612
1613 <!-- _______________________________________________________________________ -->
1614 <div class="doc_subsubsection">
1615   <a name="i_free">'<tt>free</tt>' Instruction</a>
1616 </div>
1617
1618 <div class="doc_text">
1619
1620 <h5>Syntax:</h5>
1621
1622 <pre>
1623   free &lt;type&gt; &lt;value&gt;                              <i>; yields {void}</i>
1624 </pre>
1625
1626 <h5>Overview:</h5>
1627
1628 <p>The '<tt>free</tt>' instruction returns memory back to the unused memory
1629 heap, to be reallocated in the future.<p>
1630
1631 <h5>Arguments:</h5>
1632
1633 <p>'<tt>value</tt>' shall be a pointer value that points to a value that was
1634 allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' instruction.</p>
1635
1636 <h5>Semantics:</h5>
1637
1638 <p>Access to the memory pointed to by the pointer is not longer defined after
1639 this instruction executes.</p>
1640
1641 <h5>Example:</h5>
1642 <pre>
1643   %array  = <a href="#i_malloc">malloc</a> [4 x ubyte]                    <i>; yields {[4 x ubyte]*}:array</i>
1644             free   [4 x ubyte]* %array
1645 </pre>
1646
1647 </div>
1648
1649 <!-- _______________________________________________________________________ -->
1650 <div class="doc_subsubsection">
1651   <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
1652 </div>
1653
1654 <div class="doc_text">
1655
1656 <h5>Syntax:</h5>
1657
1658 <pre>
1659   &lt;result&gt; = alloca &lt;type&gt;, uint &lt;NumElements&gt;  <i>; yields {type*}:result</i>
1660   &lt;result&gt; = alloca &lt;type&gt;                      <i>; yields {type*}:result</i>
1661 </pre>
1662
1663 <h5>Overview:</h5>
1664
1665 <p>The '<tt>alloca</tt>' instruction allocates memory on the current stack frame
1666 of the procedure that is live until the current function returns to its
1667 caller.</p>
1668
1669 <h5>Arguments:</h5>
1670
1671 <p>The the '<tt>alloca</tt>' instruction allocates
1672 <tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory on the runtime stack,
1673 returning a pointer of the appropriate type to the program.  The second form of
1674 the instruction is a shorter version of the first that defaults to allocating
1675 one element.</p>
1676
1677 <p>'<tt>type</tt>' may be any sized type.</p>
1678
1679 <h5>Semantics:</h5>
1680
1681 <p>Memory is allocated, a pointer is returned.  '<tt>alloca</tt>'d memory is
1682 automatically released when the function returns.  The '<tt>alloca</tt>'
1683 instruction is commonly used to represent automatic variables that must have an
1684 address available.  When the function returns (either with the <tt><a
1685 href="#i_ret">ret</a></tt> or <tt><a href="#i_invoke">invoke</a></tt>
1686 instructions), the memory is reclaimed.</p>
1687
1688 <h5>Example:</h5>
1689
1690 <pre>
1691   %ptr = alloca int                              <i>; yields {int*}:ptr</i>
1692   %ptr = alloca int, uint 4                      <i>; yields {int*}:ptr</i>
1693 </pre>
1694
1695 </div>
1696
1697 <!-- _______________________________________________________________________ -->
1698 <div class="doc_subsubsection">
1699   <a name="i_load">'<tt>load</tt>' Instruction</a>
1700 </div>
1701
1702 <div class="doc_text">
1703
1704 <h5>Syntax:</h5>
1705
1706 <pre>
1707   &lt;result&gt; = load &lt;ty&gt;* &lt;pointer&gt;
1708   &lt;result&gt; = volatile load &lt;ty&gt;* &lt;pointer&gt;
1709 </pre>
1710
1711 <h5>Overview:</h5>
1712
1713 <p>The '<tt>load</tt>' instruction is used to read from memory.</p>
1714
1715 <h5>Arguments:</h5>
1716
1717 <p>The argument to the '<tt>load</tt>' instruction specifies the memory address
1718 to load from.  The pointer must point to a <a href="t_firstclass">first
1719 class</a> type.  If the <tt>load</tt> is marked as <tt>volatile</tt> then the
1720 optimizer is not allowed to modify the number or order of execution of this
1721 <tt>load</tt> with other volatile <tt>load</tt> and <tt><a
1722 href="#i_store">store</a></tt> instructions. </p>
1723
1724 <h5>Semantics:</h5>
1725
1726 <p>The location of memory pointed to is loaded.</p>
1727
1728 <h5>Examples:</h5>
1729
1730 <pre>
1731   %ptr = <a href="#i_alloca">alloca</a> int                               <i>; yields {int*}:ptr</i>
1732   <a href="#i_store">store</a> int 3, int* %ptr                          <i>; yields {void}</i>
1733   %val = load int* %ptr                           <i>; yields {int}:val = int 3</i>
1734 </pre>
1735
1736 </div>
1737
1738 <!-- _______________________________________________________________________ -->
1739 <div class="doc_subsubsection">
1740   <a name="i_store">'<tt>store</tt>' Instruction</a>
1741 </div>
1742
1743 <h5>Syntax:</h5>
1744
1745 <pre>
1746   store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;                   <i>; yields {void}</i>
1747   volatile store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;                   <i>; yields {void}</i>
1748 </pre>
1749
1750 <h5>Overview:</h5>
1751
1752 <p>The '<tt>store</tt>' instruction is used to write to memory.</p>
1753
1754 <h5>Arguments:</h5>
1755
1756 <p>There are two arguments to the '<tt>store</tt>' instruction: a value to store
1757 and an address to store it into.  The type of the '<tt>&lt;pointer&gt;</tt>'
1758 operand must be a pointer to the type of the '<tt>&lt;value&gt;</tt>' operand.
1759 If the <tt>store</tt> is marked as <tt>volatile</tt> then the optimizer is not
1760 allowed to modify the number or order of execution of this <tt>store</tt> with
1761 other volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
1762 instructions.</p>
1763
1764 <h5>Semantics:</h5>
1765
1766 <p>The contents of memory are updated to contain '<tt>&lt;value&gt;</tt>' at the
1767 location specified by the '<tt>&lt;pointer&gt;</tt>' operand.</p>
1768
1769 <h5>Example:</h5>
1770
1771 <pre>
1772   %ptr = <a href="#i_alloca">alloca</a> int                               <i>; yields {int*}:ptr</i>
1773   <a href="#i_store">store</a> int 3, int* %ptr                          <i>; yields {void}</i>
1774   %val = load int* %ptr                           <i>; yields {int}:val = int 3</i>
1775 </pre>
1776
1777 </div>
1778
1779 <!-- _______________________________________________________________________ -->
1780 <div class="doc_subsubsection">
1781   <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
1782 </div>
1783
1784 <div class="doc_text">
1785
1786 <h5>Syntax:</h5>
1787
1788 <pre>
1789   &lt;result&gt; = getelementptr &lt;ty&gt;* &lt;ptrval&gt;{, long &lt;aidx&gt;|, ubyte &lt;sidx&gt;}*
1790 </pre>
1791
1792 <h5>Overview:</h5>
1793
1794 <p>The '<tt>getelementptr</tt>' instruction is used to get the address of a
1795 subelement of an aggregate data structure.</p>
1796
1797 <h5>Arguments:</h5>
1798
1799 <p>This instruction takes a list of <tt>long</tt> values and <tt>ubyte</tt>
1800 constants that indicate what form of addressing to perform.  The actual types of
1801 the arguments provided depend on the type of the first pointer argument.  The
1802 '<tt>getelementptr</tt>' instruction is used to index down through the type
1803 levels of a structure.</p>
1804
1805 <p>For example, let's consider a C code fragment and how it gets compiled to
1806 LLVM:</p>
1807
1808 <pre>
1809 struct RT {
1810   char A;
1811   int B[10][20];
1812   char C;
1813 };
1814 struct ST {
1815   int X;
1816   double Y;
1817   struct RT Z;
1818 };
1819
1820 int *foo(struct ST *s) {
1821   return &amp;s[1].Z.B[5][13];
1822 }
1823 </pre>
1824
1825 <p>The LLVM code generated by the GCC frontend is:</p>
1826
1827 <pre>
1828 %RT = type { sbyte, [10 x [20 x int]], sbyte }
1829 %ST = type { int, double, %RT }
1830
1831 int* "foo"(%ST* %s) {
1832   %reg = getelementptr %ST* %s, long 1, ubyte 2, ubyte 1, long 5, long 13
1833   ret int* %reg
1834 }
1835 </pre>
1836
1837 <h5>Semantics:</h5>
1838
1839 <p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
1840 on the pointer type that is being index into.  <a href="t_pointer">Pointer</a>
1841 and <a href="t_array">array</a> types require '<tt>long</tt>' values, and <a
1842 href="t_struct">structure</a> types require '<tt>ubyte</tt>'
1843 <b>constants</b>.</p>
1844
1845 <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
1846 type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ int, double, %RT
1847 }</tt>' type, a structure.  The second index indexes into the third element of
1848 the structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]],
1849 sbyte }</tt>' type, another structure.  The third index indexes into the second
1850 element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
1851 array.  The two dimensions of the array are subscripted into, yielding an
1852 '<tt>int</tt>' type.  The '<tt>getelementptr</tt>' instruction return a pointer
1853 to this element, thus yielding a '<tt>int*</tt>' type.</p>
1854
1855 <p>Note that it is perfectly legal to index partially through a structure,
1856 returning a pointer to an inner element.  Because of this, the LLVM code for the
1857 given testcase is equivalent to:</p>
1858
1859 <pre>
1860 int* "foo"(%ST* %s) {
1861   %t1 = getelementptr %ST* %s , long 1                        <i>; yields %ST*:%t1</i>
1862   %t2 = getelementptr %ST* %t1, long 0, ubyte 2               <i>; yields %RT*:%t2</i>
1863   %t3 = getelementptr %RT* %t2, long 0, ubyte 1               <i>; yields [10 x [20 x int]]*:%t3</i>
1864   %t4 = getelementptr [10 x [20 x int]]* %t3, long 0, long 5  <i>; yields [20 x int]*:%t4</i>
1865   %t5 = getelementptr [20 x int]* %t4, long 0, long 13        <i>; yields int*:%t5</i>
1866   ret int* %t5
1867 }
1868 </pre>
1869
1870 <h5>Example:</h5>
1871
1872 <pre>
1873   <i>; yields [12 x ubyte]*:aptr</i>
1874   %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, ubyte 1
1875 </pre>
1876
1877 </div>
1878
1879 <!-- ======================================================================= -->
1880 <div class="doc_subsection">
1881   <a name="otherops">Other Operations</a>
1882 </div>
1883
1884 <div class="doc_text">
1885
1886 <p>The instructions in this catagory are the "miscellaneous" instructions, which
1887 defy better classification.</p>
1888
1889 </div>
1890
1891 <!-- _______________________________________________________________________ -->
1892 <div class="doc_subsubsection">
1893   <a name="i_phi">'<tt>phi</tt>' Instruction</a>
1894 </div>
1895
1896 <div class="doc_text">
1897
1898 <h5>Syntax:</h5>
1899
1900 <pre>
1901   &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...
1902 </pre>
1903
1904 <h5>Overview:</h5>
1905
1906 <p>The '<tt>phi</tt>' instruction is used to implement the &phi; node in the SSA
1907 graph representing the function.</p>
1908
1909 <h5>Arguments:</h5>
1910
1911 <p>The type of the incoming values are specified with the first type field.
1912 After this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments,
1913 with one pair for each predecessor basic block of the current block.  Only
1914 values of <a href="#t_firstclass">first class</a> type may be used as the value
1915 arguments to the PHI node.  Only labels may be used as the label arguments.</p>
1916
1917 <p>There must be no non-phi instructions between the start of a basic block and
1918 the PHI instructions: i.e. PHI instructions must be first in a basic block.</p>
1919
1920 <h5>Semantics:</h5>
1921
1922 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value
1923 specified by the parameter, depending on which basic block we came from in the
1924 last <a href="#terminators">terminator</a> instruction.</p>
1925
1926 <h5>Example:</h5>
1927
1928 <pre>
1929 Loop:       ; Infinite loop that counts from 0 on up...
1930   %indvar = phi uint [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
1931   %nextindvar = add uint %indvar, 1
1932   br label %Loop
1933 </pre>
1934
1935 </div>
1936
1937 <!-- _______________________________________________________________________ -->
1938 <div class="doc_subsubsection">
1939   <a name="i_cast">'<tt>cast .. to</tt>' Instruction</a>
1940 </div>
1941
1942 <div class="doc_text">
1943
1944 <h5>Syntax:</h5>
1945
1946 <pre>
1947   &lt;result&gt; = cast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
1948 </pre>
1949
1950 <h5>Overview:</h5>
1951
1952 <p>The '<tt>cast</tt>' instruction is used as the primitive means to convert
1953 integers to floating point, change data type sizes, and break type safety (by
1954 casting pointers).</p>
1955
1956 <h5>Arguments:</h5>
1957
1958 <p>The '<tt>cast</tt>' instruction takes a value to cast, which must be a first
1959 class value, and a type to cast it to, which must also be a <a
1960 href="#t_firstclass">first class</a> type.</p>
1961
1962 <h5>Semantics:</h5>
1963
1964 <p>This instruction follows the C rules for explicit casts when determining how
1965 the data being cast must change to fit in its new container.</p>
1966
1967 <p>When casting to bool, any value that would be considered true in the context
1968 of a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>'
1969 values, all else are '<tt>false</tt>'.</p>
1970
1971 <p>When extending an integral value from a type of one signness to another (for
1972 example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
1973 <b>source</b> value is signed, and zero-extended if the source value is
1974 unsigned.  <tt>bool</tt> values are always zero extended into either zero or
1975 one.</p>
1976
1977 <h5>Example:</h5>
1978
1979 <pre>
1980   %X = cast int 257 to ubyte              <i>; yields ubyte:1</i>
1981   %Y = cast int 123 to bool               <i>; yields bool:true</i>
1982 </pre>
1983
1984 </div>
1985
1986 <!-- _______________________________________________________________________ -->
1987 <div class="doc_subsubsection">
1988   <a name="i_call">'<tt>call</tt>' Instruction</a>
1989 </div>
1990
1991 <div class="doc_text">
1992
1993 <h5>Syntax:</h5>
1994
1995 <pre>
1996   &lt;result&gt; = call &lt;ty&gt;* &lt;fnptrval&gt;(&lt;param list&gt;)
1997 </pre>
1998
1999 <h5>Overview:</h5>
2000
2001 <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
2002
2003 <h5>Arguments:</h5>
2004
2005 <p>This instruction requires several arguments:</p>
2006
2007 <ol>
2008
2009   <li><p>'<tt>ty</tt>': shall be the signature of the pointer to function value
2010   being invoked.  The argument types must match the types implied by this
2011   signature.</p></li>
2012
2013   <li><p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function
2014   to be invoked. In most cases, this is a direct function invocation, but
2015   indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer to
2016   function values.</p></li>
2017
2018   <li><p>'<tt>function args</tt>': argument list whose types match the function
2019   signature argument types.  If the function signature indicates the function
2020   accepts a variable number of arguments, the extra arguments can be
2021   specified.</p></li>
2022
2023 </ol>
2024
2025 <h5>Semantics:</h5>
2026
2027 <p>The '<tt>call</tt>' instruction is used to cause control flow to transfer to
2028 a specified function, with its incoming arguments bound to the specified values.
2029 Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called function,
2030 control flow continues with the instruction after the function call, and the
2031 return value of the function is bound to the result argument.  This is a simpler
2032 case of the <a href="#i_invoke">invoke</a> instruction.</p>
2033
2034 <h5>Example:</h5>
2035
2036 <pre>
2037   %retval = call int %test(int %argc)
2038   call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);
2039 </pre>
2040
2041 </div>
2042
2043 <!-- _______________________________________________________________________ -->
2044 <div class="doc_subsubsection">
2045   <a name="i_vanext">'<tt>vanext</tt>' Instruction</a>
2046 </div>
2047
2048 <div class="doc_text">
2049
2050 <h5>Syntax:</h5>
2051
2052 <pre>
2053   &lt;resultarglist&gt; = vanext &lt;va_list&gt; &lt;arglist&gt;, &lt;argty&gt;
2054 </pre>
2055
2056 <h5>Overview:</h5>
2057
2058 <p>The '<tt>vanext</tt>' instruction is used to access arguments passed through
2059 the "variable argument" area of a function call.  It is used to implement the
2060 <tt>va_arg</tt> macro in C.</p>
2061
2062 <h5>Arguments:</h5>
2063
2064 <p>This instruction takes a <tt>valist</tt> value and the type of the argument.
2065 It returns another <tt>valist</tt>.</p>
2066
2067 <h5>Semantics:</h5>
2068
2069 <p>The '<tt>vanext</tt>' instruction advances the specified <tt>valist</tt> past
2070 an argument of the specified type.  In conjunction with the <a
2071 href="#i_vaarg"><tt>vaarg</tt></a> instruction, it is used to implement the
2072 <tt>va_arg</tt> macro available in C.  For more information, see the variable
2073 argument handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
2074
2075 <p>It is legal for this instruction to be called in a function which does not
2076 take a variable number of arguments, for example, the <tt>vfprintf</tt>
2077 function.</p>
2078
2079 <p><tt>vanext</tt> is an LLVM instruction instead of an <a
2080 href="#intrinsics">intrinsic function</a> because it takes an type as an
2081 argument.</p>
2082
2083 <h5>Example:</h5>
2084
2085 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
2086
2087 </div>
2088
2089 <!-- _______________________________________________________________________ -->
2090 <div class="doc_subsubsection">
2091   <a name="i_vaarg">'<tt>vaarg</tt>' Instruction</a>
2092 </div>
2093
2094 <div class="doc_text">
2095
2096 <h5>Syntax:</h5>
2097
2098 <pre>
2099   &lt;resultval&gt; = vaarg &lt;va_list&gt; &lt;arglist&gt;, &lt;argty&gt;
2100 </pre>
2101
2102 <h5>Overview:</h5>
2103
2104 <p>The '<tt>vaarg</tt>' instruction is used to access arguments passed through
2105 the "variable argument" area of a function call.  It is used to implement the
2106 <tt>va_arg</tt> macro in C.</p>
2107
2108 <h5>Arguments:</h5>
2109
2110 <p>This instruction takes a <tt>valist</tt> value and the type of the argument.
2111 It returns a value of the specified argument type.</p>
2112
2113 <h5>Semantics:</h5>
2114
2115 <p>The '<tt>vaarg</tt>' instruction loads an argument of the specified type from
2116 the specified <tt>va_list</tt>.  In conjunction with the <a
2117 href="#i_vanext"><tt>vanext</tt></a> instruction, it is used to implement the
2118 <tt>va_arg</tt> macro available in C.  For more information, see the variable
2119 argument handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
2120
2121 <p>It is legal for this instruction to be called in a function which does not
2122 take a variable number of arguments, for example, the <tt>vfprintf</tt>
2123 function.</p>
2124
2125 <p><tt>vaarg</tt> is an LLVM instruction instead of an <a
2126 href="#intrinsics">intrinsic function</a> because it takes an type as an
2127 argument.</p>
2128
2129 <h5>Example:</h5>
2130
2131 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
2132
2133 </div>
2134
2135 <!-- *********************************************************************** -->
2136 <div class="doc_section">
2137   <a name="intrinsics">Intrinsic Functions</a>
2138 </div>
2139 <!-- *********************************************************************** -->
2140
2141 <div class="doc_text">
2142
2143 <p>LLVM supports the notion of an "intrinsic function".  These functions have
2144 well known names and semantics, and are required to follow certain restrictions.
2145 Overall, these instructions represent an extension mechanism for the LLVM
2146 language that does not require changing all of the transformations in LLVM to
2147 add to the language (or the bytecode reader/writer, the parser, etc...).</p>
2148
2149 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix, this
2150 prefix is reserved in LLVM for intrinsic names, thus functions may not be named
2151 this.  Intrinsic functions must always be external functions: you cannot define
2152 the body of intrinsic functions.  Intrinsic functions may only be used in call
2153 or invoke instructions: it is illegal to take the address of an intrinsic
2154 function.  Additionally, because intrinsic functions are part of the LLVM
2155 language, it is required that they all be documented here if any are added.</p>
2156
2157 <p>Unless an intrinsic function is target-specific, there must be a lowering
2158 pass to eliminate the intrinsic or all backends must support the intrinsic
2159 function.</p>
2160
2161 </div>
2162
2163 <!-- ======================================================================= -->
2164 <div class="doc_subsection">
2165   <a name="int_varargs">Variable Argument Handling Intrinsics</a>
2166 </div>
2167
2168 <div class="doc_text">
2169
2170 <p>Variable argument support is defined in LLVM with the <a
2171 href="#i_vanext"><tt>vanext</tt></a> instruction and these three intrinsic
2172 functions.  These functions are related to the similarly named macros defined in
2173 the <tt>&lt;stdarg.h&gt;</tt> header file.</p>
2174
2175 <p>All of these functions operate on arguments that use a target-specific value
2176 type "<tt>va_list</tt>".  The LLVM assembly language reference manual does not
2177 define what this type is, so all transformations should be prepared to handle
2178 intrinsics with any type used.</p>
2179
2180 <p>This example shows how the <a href="#i_vanext"><tt>vanext</tt></a>
2181 instruction and the variable argument handling intrinsic functions are used.</p>
2182
2183 <pre>
2184 int %test(int %X, ...) {
2185   ; Initialize variable argument processing
2186   %ap = call sbyte*()* %<a href="#i_va_start">llvm.va_start</a>()
2187
2188   ; Read a single integer argument
2189   %tmp = vaarg sbyte* %ap, int
2190
2191   ; Advance to the next argument
2192   %ap2 = vanext sbyte* %ap, int
2193
2194   ; Demonstrate usage of llvm.va_copy and llvm.va_end
2195   %aq = call sbyte* (sbyte*)* %<a href="#i_va_copy">llvm.va_copy</a>(sbyte* %ap2)
2196   call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %aq)
2197
2198   ; Stop processing of arguments.
2199   call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %ap2)
2200   ret int %tmp
2201 }
2202 </pre>
2203
2204 </div>
2205
2206 <!-- _______________________________________________________________________ -->
2207 <div class="doc_subsubsection">
2208   <a name="i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
2209 </div>
2210
2211 <div class="doc_text">
2212
2213 <h5>Syntax:</h5>
2214
2215 <pre>
2216   call va_list ()* %llvm.va_start()
2217 </pre>
2218
2219 <h5>Overview:</h5>
2220
2221 <p>The '<tt>llvm.va_start</tt>' intrinsic returns a new <tt>&lt;arglist&gt;</tt>
2222 for subsequent use by the variable argument intrinsics.</p>
2223
2224 <h5>Semantics:</h5>
2225
2226 <p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
2227 macro available in C.  In a target-dependent way, it initializes and returns a
2228 <tt>va_list</tt> element, so that the next <tt>vaarg</tt> will produce the first
2229 variable argument passed to the function.  Unlike the C <tt>va_start</tt> macro,
2230 this intrinsic does not need to know the last argument of the function, the
2231 compiler can figure that out.</p>
2232
2233 <p>Note that this intrinsic function is only legal to be called from within the
2234 body of a variable argument function.</p>
2235
2236 </div>
2237
2238 <!-- _______________________________________________________________________ -->
2239 <div class="doc_subsubsection">
2240   <a name="i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
2241 </div>
2242
2243 <div class="doc_text">
2244
2245 <h5>Syntax:</h5>
2246
2247 <pre>
2248   call void (va_list)* %llvm.va_end(va_list &lt;arglist&gt;)
2249 </pre>
2250
2251 <h5>Overview:</h5>
2252
2253 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>&lt;arglist&gt;</tt> which
2254 has been initialized previously with <tt><a
2255 href="#i_va_start">llvm.va_start</a></tt> or <tt><a
2256 href="#i_va_copy">llvm.va_copy</a></tt>.</p>
2257
2258 <h5>Arguments:</h5>
2259
2260 <p>The argument is a <tt>va_list</tt> to destroy.</p>
2261
2262 <h5>Semantics:</h5>
2263
2264 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
2265 macro available in C.  In a target-dependent way, it destroys the
2266 <tt>va_list</tt>.  Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and
2267 <a href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly with
2268 calls to <tt>llvm.va_end</tt>.</p>
2269
2270 </div>
2271
2272 <!-- _______________________________________________________________________ -->
2273 <div class="doc_subsubsection">
2274   <a name="i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
2275 </div>
2276
2277 <div class="doc_text">
2278
2279 <h5>Syntax:</h5>
2280
2281 <pre>
2282   call va_list (va_list)* %llvm.va_copy(va_list &lt;destarglist&gt;)
2283 </pre>
2284
2285 <h5>Overview:</h5>
2286
2287 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position
2288 from the source argument list to the destination argument list.</p>
2289
2290 <h5>Arguments:</h5>
2291
2292 <p>The argument is the <tt>va_list</tt> to copy.</p>
2293
2294 <h5>Semantics:</h5>
2295
2296 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
2297 macro available in C.  In a target-dependent way, it copies the source
2298 <tt>va_list</tt> element into the returned list.  This intrinsic is necessary
2299 because the <tt><a href="i_va_start">llvm.va_start</a></tt> intrinsic may be
2300 arbitrarily complex and require memory allocation, for example.</p>
2301
2302 </div>
2303
2304 <!-- *********************************************************************** -->
2305
2306 <hr>
2307 <div class="doc_footer">
2308   <address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
2309   <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
2310   <br>
2311   Last modified: $Date$
2312 </div>
2313
2314 </body>
2315 </html>