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