docs/LangRef.html

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