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">Functions</a></li>
  27       <li><a href="#moduleasm">Module-Level Inline Assembly</a></li>
  28     </ol>
  29   </li>
  30   <li><a href="#typesystem">Type System</a>
  31     <ol>
  32       <li><a href="#t_primitive">Primitive Types</a>
  33         <ol>
  34           <li><a href="#t_classifications">Type Classifications</a></li>
  35         </ol>
  36       </li>
  37       <li><a href="#t_derived">Derived Types</a>
  38         <ol>
  39           <li><a href="#t_array">Array Type</a></li>
  40           <li><a href="#t_function">Function Type</a></li>
  41           <li><a href="#t_pointer">Pointer Type</a></li>
  42           <li><a href="#t_struct">Structure Type</a></li>
  43           <li><a href="#t_packed">Packed Type</a></li>
  44           <li><a href="#t_opaque">Opaque Type</a></li>
  45         </ol>
  46       </li>
  47     </ol>
  48   </li>
  49   <li><a href="#constants">Constants</a>
  50     <ol>
  51       <li><a href="#simpleconstants">Simple Constants</a>
  52       <li><a href="#aggregateconstants">Aggregate Constants</a>
  53       <li><a href="#globalconstants">Global Variable and Function Addresses</a>
  54       <li><a href="#undefvalues">Undefined Values</a>
  55       <li><a href="#constantexprs">Constant Expressions</a>
  56     </ol>
  57   </li>
  58   <li><a href="#othervalues">Other Values</a>
  59     <ol>
  60       <li><a href="#inlineasm">Inline Assembler Expressions</a>
  61     </ol>
  62   </li>
  63   <li><a href="#instref">Instruction Reference</a>
  64     <ol>
  65       <li><a href="#terminators">Terminator Instructions</a>
  66         <ol>
  67           <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li>
  68           <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
  69           <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
  70           <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
  71           <li><a href="#i_unwind">'<tt>unwind</tt>'  Instruction</a></li>
  72           <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
  73         </ol>
  74       </li>
  75       <li><a href="#binaryops">Binary Operations</a>
  76         <ol>
  77           <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li>
  78           <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li>
  79           <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li>
  80           <li><a href="#i_udiv">'<tt>udiv</tt>' Instruction</a></li>
  81           <li><a href="#i_sdiv">'<tt>sdiv</tt>' Instruction</a></li>
  82           <li><a href="#i_fdiv">'<tt>fdiv</tt>' Instruction</a></li>
  83           <li><a href="#i_urem">'<tt>urem</tt>' Instruction</a></li>
  84           <li><a href="#i_srem">'<tt>srem</tt>' Instruction</a></li>
  85           <li><a href="#i_frem">'<tt>frem</tt>' Instruction</a></li>
  86         </ol>
  87       </li>
  88       <li><a href="#bitwiseops">Bitwise Binary Operations</a>
  89         <ol>
  90           <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
  91           <li><a href="#i_or">'<tt>or</tt>'  Instruction</a></li>
  92           <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
  93           <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
  94           <li><a href="#i_lshr">'<tt>lshr</tt>' Instruction</a></li>
  95           <li><a href="#i_ashr">'<tt>ashr</tt>' Instruction</a></li>
  96         </ol>
  97       </li>
  98       <li><a href="#vectorops">Vector Operations</a>
  99         <ol>
 100           <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li>
 101           <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li>
 102           <li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li>
 103         </ol>
 104       </li>
 105       <li><a href="#memoryops">Memory Access and Addressing Operations</a>
 106         <ol>
 107           <li><a href="#i_malloc">'<tt>malloc</tt>'   Instruction</a></li>
 108           <li><a href="#i_free">'<tt>free</tt>'     Instruction</a></li>
 109           <li><a href="#i_alloca">'<tt>alloca</tt>'   Instruction</a></li>
 110          <li><a href="#i_load">'<tt>load</tt>'     Instruction</a></li>
 111          <li><a href="#i_store">'<tt>store</tt>'    Instruction</a></li>
 112          <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
 113         </ol>
 114       </li>
 115       <li><a href="#convertops">Conversion Operations</a>
 116         <ol>
 117           <li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li>
 118           <li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li>
 119           <li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li>
 120           <li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li>
 121           <li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li>
 122           <li><a href="#i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a></li>
 123           <li><a href="#i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a></li>
 124           <li><a href="#i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a></li>
 125           <li><a href="#i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a></li>
 126           <li><a href="#i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a></li>
 127           <li><a href="#i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a></li>
 128           <li><a href="#i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a></li>
 129         </ol>
 130       <li><a href="#otherops">Other Operations</a>
 131         <ol>
 132           <li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li>
 133           <li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li>
 134           <li><a href="#i_phi">'<tt>phi</tt>'   Instruction</a></li>
 135           <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
 136           <li><a href="#i_call">'<tt>call</tt>'  Instruction</a></li>
 137           <li><a href="#i_va_arg">'<tt>va_arg</tt>'  Instruction</a></li>
 138         </ol>
 139       </li>
 140     </ol>
 141   </li>
 142   <li><a href="#intrinsics">Intrinsic Functions</a>
 143     <ol>
 144       <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
 145         <ol>
 146           <li><a href="#i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
 147           <li><a href="#i_va_end">'<tt>llvm.va_end</tt>'   Intrinsic</a></li>
 148           <li><a href="#i_va_copy">'<tt>llvm.va_copy</tt>'  Intrinsic</a></li>
 149         </ol>
 150       </li>
 151       <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a>
 152         <ol>
 153           <li><a href="#i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
 154           <li><a href="#i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
 155           <li><a href="#i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
 156         </ol>
 157       </li>
 158       <li><a href="#int_codegen">Code Generator Intrinsics</a>
 159         <ol>
 160           <li><a href="#i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
 161           <li><a href="#i_frameaddress">'<tt>llvm.frameaddress</tt>'   Intrinsic</a></li>
 162           <li><a href="#i_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a></li>
 163           <li><a href="#i_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li>
 164           <li><a href="#i_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
 165           <li><a href="#i_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
 166           <li><a href="#i_readcyclecounter"><tt>llvm.readcyclecounter</tt>' Intrinsic</a></li>
 167         </ol>
 168       </li>
 169       <li><a href="#int_libc">Standard C Library Intrinsics</a>
 170         <ol>
 171           <li><a href="#i_memcpy">'<tt>llvm.memcpy.*</tt>' Intrinsic</a></li>
 172           <li><a href="#i_memmove">'<tt>llvm.memmove.*</tt>' Intrinsic</a></li>
 173           <li><a href="#i_memset">'<tt>llvm.memset.*</tt>' Intrinsic</a></li>
 174           <li><a href="#i_isunordered">'<tt>llvm.isunordered.*</tt>' Intrinsic</a></li>
 175           <li><a href="#i_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a></li>
 176           <li><a href="#i_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a></li>
 177         </ol>
 178       </li>
 179       <li><a href="#int_manip">Bit Manipulation Intrinsics</a>
 180         <ol>
 181           <li><a href="#i_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a></li>
 182           <li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li>
 183           <li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li>
 184           <li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li>
 185         </ol>
 186       </li>
 187       <li><a href="#int_debugger">Debugger intrinsics</a></li>
 188     </ol>
 189   </li>
 190 </ol>
 191
 192 <div class="doc_author">
 193   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
 194             and <a href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></p>
 195 </div>
 196
 197 <!-- *********************************************************************** -->
 198 <div class="doc_section"> <a name="abstract">Abstract </a></div>
 199 <!-- *********************************************************************** -->
 200
 201 <div class="doc_text">
 202 <p>This document is a reference manual for the LLVM assembly language.
 203 LLVM is an SSA based representation that provides type safety,
 204 low-level operations, flexibility, and the capability of representing
 205 'all' high-level languages cleanly.  It is the common code
 206 representation used throughout all phases of the LLVM compilation
 207 strategy.</p>
 208 </div>
 209
 210 <!-- *********************************************************************** -->
 211 <div class="doc_section"> <a name="introduction">Introduction</a> </div>
 212 <!-- *********************************************************************** -->
 213
 214 <div class="doc_text">
 215
 216 <p>The LLVM code representation is designed to be used in three
 217 different forms: as an in-memory compiler IR, as an on-disk bytecode
 218 representation (suitable for fast loading by a Just-In-Time compiler),
 219 and as a human readable assembly language representation.  This allows
 220 LLVM to provide a powerful intermediate representation for efficient
 221 compiler transformations and analysis, while providing a natural means
 222 to debug and visualize the transformations.  The three different forms
 223 of LLVM are all equivalent.  This document describes the human readable
 224 representation and notation.</p>
 225
 226 <p>The LLVM representation aims to be light-weight and low-level
 227 while being expressive, typed, and extensible at the same time.  It
 228 aims to be a "universal IR" of sorts, by being at a low enough level
 229 that high-level ideas may be cleanly mapped to it (similar to how
 230 microprocessors are "universal IR's", allowing many source languages to
 231 be mapped to them).  By providing type information, LLVM can be used as
 232 the target of optimizations: for example, through pointer analysis, it
 233 can be proven that a C automatic variable is never accessed outside of
 234 the current function... allowing it to be promoted to a simple SSA
 235 value instead of a memory location.</p>
 236
 237 </div>
 238
 239 <!-- _______________________________________________________________________ -->
 240 <div class="doc_subsubsection"> <a name="wellformed">Well-Formedness</a> </div>
 241
 242 <div class="doc_text">
 243
 244 <p>It is important to note that this document describes 'well formed'
 245 LLVM assembly language.  There is a difference between what the parser
 246 accepts and what is considered 'well formed'.  For example, the
 247 following instruction is syntactically okay, but not well formed:</p>
 248
 249 <pre>
 250   %x = <a href="#i_add">add</a> int 1, %x
 251 </pre>
 252
 253 <p>...because the definition of <tt>%x</tt> does not dominate all of
 254 its uses. The LLVM infrastructure provides a verification pass that may
 255 be used to verify that an LLVM module is well formed.  This pass is
 256 automatically run by the parser after parsing input assembly and by
 257 the optimizer before it outputs bytecode.  The violations pointed out
 258 by the verifier pass indicate bugs in transformation passes or input to
 259 the parser.</p>
 260
 261 <!-- Describe the typesetting conventions here. --> </div>
 262
 263 <!-- *********************************************************************** -->
 264 <div class="doc_section"> <a name="identifiers">Identifiers</a> </div>
 265 <!-- *********************************************************************** -->
 266
 267 <div class="doc_text">
 268
 269 <p>LLVM uses three different forms of identifiers, for different
 270 purposes:</p>
 271
 272 <ol>
 273   <li>Named values are represented as a string of characters with a '%' prefix.
 274   For example, %foo, %DivisionByZero, %a.really.long.identifier.  The actual
 275   regular expression used is '<tt>%[a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.
 276   Identifiers which require other characters in their names can be surrounded
 277   with quotes.  In this way, anything except a <tt>"</tt> character can be used
 278   in a name.</li>
 279
 280   <li>Unnamed values are represented as an unsigned numeric value with a '%'
 281   prefix.  For example, %12, %2, %44.</li>
 282
 283   <li>Constants, which are described in a <a href="#constants">section about
 284   constants</a>, below.</li>
 285 </ol>
 286
 287 <p>LLVM requires that values start with a '%' sign for two reasons: Compilers
 288 don't need to worry about name clashes with reserved words, and the set of
 289 reserved words may be expanded in the future without penalty.  Additionally,
 290 unnamed identifiers allow a compiler to quickly come up with a temporary
 291 variable without having to avoid symbol table conflicts.</p>
 292
 293 <p>Reserved words in LLVM are very similar to reserved words in other
 294 languages. There are keywords for different opcodes
 295 ('<tt><a href="#i_add">add</a></tt>',
 296  '<tt><a href="#i_bitcast">bitcast</a></tt>',
 297  '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names ('<tt><a
 298 href="#t_void">void</a></tt>', '<tt><a href="#t_uint">uint</a></tt>', etc...),
 299 and others.  These reserved words cannot conflict with variable names, because
 300 none of them start with a '%' character.</p>
 301
 302 <p>Here is an example of LLVM code to multiply the integer variable
 303 '<tt>%X</tt>' by 8:</p>
 304
 305 <p>The easy way:</p>
 306
 307 <pre>
 308   %result = <a href="#i_mul">mul</a> uint %X, 8
 309 </pre>
 310
 311 <p>After strength reduction:</p>
 312
 313 <pre>
 314   %result = <a href="#i_shl">shl</a> uint %X, ubyte 3
 315 </pre>
 316
 317 <p>And the hard way:</p>
 318
 319 <pre>
 320   <a href="#i_add">add</a> uint %X, %X           <i>; yields {uint}:%0</i>
 321   <a href="#i_add">add</a> uint %0, %0           <i>; yields {uint}:%1</i>
 322   %result = <a href="#i_add">add</a> uint %1, %1
 323 </pre>
 324
 325 <p>This last way of multiplying <tt>%X</tt> by 8 illustrates several
 326 important lexical features of LLVM:</p>
 327
 328 <ol>
 329
 330   <li>Comments are delimited with a '<tt>;</tt>' and go until the end of
 331   line.</li>
 332
 333   <li>Unnamed temporaries are created when the result of a computation is not
 334   assigned to a named value.</li>
 335
 336   <li>Unnamed temporaries are numbered sequentially</li>
 337
 338 </ol>
 339
 340 <p>...and it also shows a convention that we follow in this document.  When
 341 demonstrating instructions, we will follow an instruction with a comment that
 342 defines the type and name of value produced.  Comments are shown in italic
 343 text.</p>
 344
 345 </div>
 346
 347 <!-- *********************************************************************** -->
 348 <div class="doc_section"> <a name="highlevel">High Level Structure</a> </div>
 349 <!-- *********************************************************************** -->
 350
 351 <!-- ======================================================================= -->
 352 <div class="doc_subsection"> <a name="modulestructure">Module Structure</a>
 353 </div>
 354
 355 <div class="doc_text">
 356
 357 <p>LLVM programs are composed of "Module"s, each of which is a
 358 translation unit of the input programs.  Each module consists of
 359 functions, global variables, and symbol table entries.  Modules may be
 360 combined together with the LLVM linker, which merges function (and
 361 global variable) definitions, resolves forward declarations, and merges
 362 symbol table entries. Here is an example of the "hello world" module:</p>
 363
 364 <pre><i>; Declare the string constant as a global constant...</i>
 365 <a href="#identifiers">%.LC0</a> = <a href="#linkage_internal">internal</a> <a
 366  href="#globalvars">constant</a> <a href="#t_array">[13 x sbyte]</a> c"hello world\0A\00"          <i>; [13 x sbyte]*</i>
 367
 368 <i>; External declaration of the puts function</i>
 369 <a href="#functionstructure">declare</a> int %puts(sbyte*)                                            <i>; int(sbyte*)* </i>
 370
 371 <i>; Global variable / Function body section separator</i>
 372 implementation
 373
 374 <i>; Definition of main function</i>
 375 int %main() {                                                        <i>; int()* </i>
 376         <i>; Convert [13x sbyte]* to sbyte *...</i>
 377         %cast210 = <a
 378  href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, long 0, long 0 <i>; sbyte*</i>
 379
 380         <i>; Call puts function to write out the string to stdout...</i>
 381         <a
 382  href="#i_call">call</a> int %puts(sbyte* %cast210)                              <i>; int</i>
 383         <a
 384  href="#i_ret">ret</a> int 0<br>}<br></pre>
 385
 386 <p>This example is made up of a <a href="#globalvars">global variable</a>
 387 named "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>"
 388 function, and a <a href="#functionstructure">function definition</a>
 389 for "<tt>main</tt>".</p>
 390
 391 <p>In general, a module is made up of a list of global values,
 392 where both functions and global variables are global values.  Global values are
 393 represented by a pointer to a memory location (in this case, a pointer to an
 394 array of char, and a pointer to a function), and have one of the following <a
 395 href="#linkage">linkage types</a>.</p>
 396
 397 <p>Due to a limitation in the current LLVM assembly parser (it is limited by
 398 one-token lookahead), modules are split into two pieces by the "implementation"
 399 keyword.  Global variable prototypes and definitions must occur before the
 400 keyword, and function definitions must occur after it.  Function prototypes may
 401 occur either before or after it.  In the future, the implementation keyword may
 402 become a noop, if the parser gets smarter.</p>
 403
 404 </div>
 405
 406 <!-- ======================================================================= -->
 407 <div class="doc_subsection">
 408   <a name="linkage">Linkage Types</a>
 409 </div>
 410
 411 <div class="doc_text">
 412
 413 <p>
 414 All Global Variables and Functions have one of the following types of linkage:
 415 </p>
 416
 417 <dl>
 418
 419   <dt><tt><b><a name="linkage_internal">internal</a></b></tt> </dt>
 420
 421   <dd>Global values with internal linkage are only directly accessible by
 422   objects in the current module.  In particular, linking code into a module with
 423   an internal global value may cause the internal to be renamed as necessary to
 424   avoid collisions.  Because the symbol is internal to the module, all
 425   references can be updated.  This corresponds to the notion of the
 426   '<tt>static</tt>' keyword in C, or the idea of "anonymous namespaces" in C++.
 427   </dd>
 428
 429   <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt>: </dt>
 430
 431   <dd>"<tt>linkonce</tt>" linkage is similar to <tt>internal</tt> linkage, with
 432   the twist that linking together two modules defining the same
 433   <tt>linkonce</tt> globals will cause one of the globals to be discarded.  This
 434   is typically used to implement inline functions.  Unreferenced
 435   <tt>linkonce</tt> globals are allowed to be discarded.
 436   </dd>
 437
 438   <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt>
 439
 440   <dd>"<tt>weak</tt>" linkage is exactly the same as <tt>linkonce</tt> linkage,
 441   except that unreferenced <tt>weak</tt> globals may not be discarded.  This is
 442   used to implement constructs in C such as "<tt>int X;</tt>" at global scope.
 443   </dd>
 444
 445   <dt><tt><b><a name="linkage_appending">appending</a></b></tt>: </dt>
 446
 447   <dd>"<tt>appending</tt>" linkage may only be applied to global variables of
 448   pointer to array type.  When two global variables with appending linkage are
 449   linked together, the two global arrays are appended together.  This is the
 450   LLVM, typesafe, equivalent of having the system linker append together
 451   "sections" with identical names when .o files are linked.
 452   </dd>
 453
 454   <dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt>
 455
 456   <dd>If none of the above identifiers are used, the global is externally
 457   visible, meaning that it participates in linkage and can be used to resolve
 458   external symbol references.
 459   </dd>
 460
 461   <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt>: </dt>
 462
 463   <dd>"<tt>extern_weak</tt>" TBD
 464   </dd>
 465
 466   <p>
 467   The next two types of linkage are targeted for Microsoft Windows platform
 468   only. They are designed to support importing (exporting) symbols from (to)
 469   DLLs.
 470   </p>
 471
 472   <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt>: </dt>
 473
 474   <dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function
 475     or variable via a global pointer to a pointer that is set up by the DLL
 476     exporting the symbol. On Microsoft Windows targets, the pointer name is
 477     formed by combining <code>_imp__</code> and the function or variable name.
 478   </dd>
 479
 480   <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt>: </dt>
 481
 482   <dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global
 483     pointer to a pointer in a DLL, so that it can be referenced with the
 484     <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer
 485     name is formed by combining <code>_imp__</code> and the function or variable
 486     name.
 487   </dd>
 488
 489 </dl>
 490
 491 <p><a name="linkage_external">For example, since the "<tt>.LC0</tt>"
 492 variable is defined to be internal, if another module defined a "<tt>.LC0</tt>"
 493 variable and was linked with this one, one of the two would be renamed,
 494 preventing a collision.  Since "<tt>main</tt>" and "<tt>puts</tt>" are
 495 external (i.e., lacking any linkage declarations), they are accessible
 496 outside of the current module.  It is illegal for a function <i>declaration</i>
 497 to have any linkage type other than "externally visible".</a></p>
 498
 499 </div>
 500
 501 <!-- ======================================================================= -->
 502 <div class="doc_subsection">
 503   <a name="callingconv">Calling Conventions</a>
 504 </div>
 505
 506 <div class="doc_text">
 507
 508 <p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a>
 509 and <a href="#i_invoke">invokes</a> can all have an optional calling convention
 510 specified for the call.  The calling convention of any pair of dynamic
 511 caller/callee must match, or the behavior of the program is undefined.  The
 512 following calling conventions are supported by LLVM, and more may be added in
 513 the future:</p>
 514
 515 <dl>
 516   <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt>
 517
 518   <dd>This calling convention (the default if no other calling convention is
 519   specified) matches the target C calling conventions.  This calling convention
 520   supports varargs function calls and tolerates some mismatch in the declared
 521   prototype and implemented declaration of the function (as does normal C).
 522   </dd>
 523
 524   <dt><b>"<tt>csretcc</tt>" - The C struct return calling convention</b>:</dt>
 525
 526   <dd>This calling convention matches the target C calling conventions, except
 527   that functions with this convention are required to take a pointer as their
 528   first argument, and the return type of the function must be void.  This is
 529   used for C functions that return aggregates by-value.  In this case, the
 530   function has been transformed to take a pointer to the struct as the first
 531   argument to the function.  For targets where the ABI specifies specific
 532   behavior for structure-return calls, the calling convention can be used to
 533   distinguish between struct return functions and other functions that take a
 534   pointer to a struct as the first argument.
 535   </dd>
 536
 537   <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt>
 538
 539   <dd>This calling convention attempts to make calls as fast as possible
 540   (e.g. by passing things in registers).  This calling convention allows the
 541   target to use whatever tricks it wants to produce fast code for the target,
 542   without having to conform to an externally specified ABI.  Implementations of
 543   this convention should allow arbitrary tail call optimization to be supported.
 544   This calling convention does not support varargs and requires the prototype of
 545   all callees to exactly match the prototype of the function definition.
 546   </dd>
 547
 548   <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt>
 549
 550   <dd>This calling convention attempts to make code in the caller as efficient
 551   as possible under the assumption that the call is not commonly executed.  As
 552   such, these calls often preserve all registers so that the call does not break
 553   any live ranges in the caller side.  This calling convention does not support
 554   varargs and requires the prototype of all callees to exactly match the
 555   prototype of the function definition.
 556   </dd>
 557
 558   <dt><b>"<tt>cc &lt;<em>n</em>&gt;</tt>" - Numbered convention</b>:</dt>
 559
 560   <dd>Any calling convention may be specified by number, allowing
 561   target-specific calling conventions to be used.  Target specific calling
 562   conventions start at 64.
 563   </dd>
 564 </dl>
 565
 566 <p>More calling conventions can be added/defined on an as-needed basis, to
 567 support pascal conventions or any other well-known target-independent
 568 convention.</p>
 569
 570 </div>
 571
 572 <!-- ======================================================================= -->
 573 <div class="doc_subsection">
 574   <a name="globalvars">Global Variables</a>
 575 </div>
 576
 577 <div class="doc_text">
 578
 579 <p>Global variables define regions of memory allocated at compilation time
 580 instead of run-time.  Global variables may optionally be initialized, may have
 581 an explicit section to be placed in, and may
 582 have an optional explicit alignment specified.  A
 583 variable may be defined as a global "constant," which indicates that the
 584 contents of the variable will <b>never</b> be modified (enabling better
 585 optimization, allowing the global data to be placed in the read-only section of
 586 an executable, etc).  Note that variables that need runtime initialization
 587 cannot be marked "constant" as there is a store to the variable.</p>
 588
 589 <p>
 590 LLVM explicitly allows <em>declarations</em> of global variables to be marked
 591 constant, even if the final definition of the global is not.  This capability
 592 can be used to enable slightly better optimization of the program, but requires
 593 the language definition to guarantee that optimizations based on the
 594 'constantness' are valid for the translation units that do not include the
 595 definition.
 596 </p>
 597
 598 <p>As SSA values, global variables define pointer values that are in
 599 scope (i.e. they dominate) all basic blocks in the program.  Global
 600 variables always define a pointer to their "content" type because they
 601 describe a region of memory, and all memory objects in LLVM are
 602 accessed through pointers.</p>
 603
 604 <p>LLVM allows an explicit section to be specified for globals.  If the target
 605 supports it, it will emit globals to the section specified.</p>
 606
 607 <p>An explicit alignment may be specified for a global.  If not present, or if
 608 the alignment is set to zero, the alignment of the global is set by the target
 609 to whatever it feels convenient.  If an explicit alignment is specified, the
 610 global is forced to have at least that much alignment.  All alignments must be
 611 a power of 2.</p>
 612
 613 </div>
 614
 615
 616 <!-- ======================================================================= -->
 617 <div class="doc_subsection">
 618   <a name="functionstructure">Functions</a>
 619 </div>
 620
 621 <div class="doc_text">
 622
 623 <p>LLVM function definitions consist of an optional <a href="#linkage">linkage
 624 type</a>, an optional <a href="#callingconv">calling convention</a>, a return
 625 type, a function name, a (possibly empty) argument list, an optional section,
 626 an optional alignment, an opening curly brace,
 627 a list of basic blocks, and a closing curly brace.  LLVM function declarations
 628 are defined with the "<tt>declare</tt>" keyword, an optional <a
 629 href="#callingconv">calling convention</a>, a return type, a function name,
 630 a possibly empty list of arguments, and an optional alignment.</p>
 631
 632 <p>A function definition contains a list of basic blocks, forming the CFG for
 633 the function.  Each basic block may optionally start with a label (giving the
 634 basic block a symbol table entry), contains a list of instructions, and ends
 635 with a <a href="#terminators">terminator</a> instruction (such as a branch or
 636 function return).</p>
 637
 638 <p>The first basic block in a program is special in two ways: it is immediately
 639 executed on entrance to the function, and it is not allowed to have predecessor
 640 basic blocks (i.e. there can not be any branches to the entry block of a
 641 function).  Because the block can have no predecessors, it also cannot have any
 642 <a href="#i_phi">PHI nodes</a>.</p>
 643
 644 <p>LLVM functions are identified by their name and type signature.  Hence, two
 645 functions with the same name but different parameter lists or return values are
 646 considered different functions, and LLVM will resolve references to each
 647 appropriately.</p>
 648
 649 <p>LLVM allows an explicit section to be specified for functions.  If the target
 650 supports it, it will emit functions to the section specified.</p>
 651
 652 <p>An explicit alignment may be specified for a function.  If not present, or if
 653 the alignment is set to zero, the alignment of the function is set by the target
 654 to whatever it feels convenient.  If an explicit alignment is specified, the
 655 function is forced to have at least that much alignment.  All alignments must be
 656 a power of 2.</p>
 657
 658 </div>
 659
 660 <!-- ======================================================================= -->
 661 <div class="doc_subsection">
 662   <a name="moduleasm">Module-Level Inline Assembly</a>
 663 </div>
 664
 665 <div class="doc_text">
 666 <p>
 667 Modules may contain "module-level inline asm" blocks, which corresponds to the
 668 GCC "file scope inline asm" blocks.  These blocks are internally concatenated by
 669 LLVM and treated as a single unit, but may be separated in the .ll file if
 670 desired.  The syntax is very simple:
 671 </p>
 672
 673 <div class="doc_code"><pre>
 674   module asm "inline asm code goes here"
 675   module asm "more can go here"
 676 </pre></div>
 677
 678 <p>The strings can contain any character by escaping non-printable characters.
 679    The escape sequence used is simply "\xx" where "xx" is the two digit hex code
 680    for the number.
 681 </p>
 682
 683 <p>
 684   The inline asm code is simply printed to the machine code .s file when
 685   assembly code is generated.
 686 </p>
 687 </div>
 688
 689
 690 <!-- *********************************************************************** -->
 691 <div class="doc_section"> <a name="typesystem">Type System</a> </div>
 692 <!-- *********************************************************************** -->
 693
 694 <div class="doc_text">
 695
 696 <p>The LLVM type system is one of the most important features of the
 697 intermediate representation.  Being typed enables a number of
 698 optimizations to be performed on the IR directly, without having to do
 699 extra analyses on the side before the transformation.  A strong type
 700 system makes it easier to read the generated code and enables novel
 701 analyses and transformations that are not feasible to perform on normal
 702 three address code representations.</p>
 703
 704 </div>
 705
 706 <!-- ======================================================================= -->
 707 <div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div>
 708 <div class="doc_text">
 709 <p>The primitive types are the fundamental building blocks of the LLVM
 710 system. The current set of primitive types is as follows:</p>
 711
 712 <table class="layout">
 713   <tr class="layout">
 714     <td class="left">
 715       <table>
 716         <tbody>
 717         <tr><th>Type</th><th>Description</th></tr>
 718         <tr><td><tt>void</tt></td><td>No value</td></tr>
 719         <tr><td><tt>ubyte</tt></td><td>Unsigned 8-bit value</td></tr>
 720         <tr><td><tt>ushort</tt></td><td>Unsigned 16-bit value</td></tr>
 721         <tr><td><tt>uint</tt></td><td>Unsigned 32-bit value</td></tr>
 722         <tr><td><tt>ulong</tt></td><td>Unsigned 64-bit value</td></tr>
 723         <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
 724         <tr><td><tt>label</tt></td><td>Branch destination</td></tr>
 725         </tbody>
 726       </table>
 727     </td>
 728     <td class="right">
 729       <table>
 730         <tbody>
 731           <tr><th>Type</th><th>Description</th></tr>
 732           <tr><td><tt>bool</tt></td><td>True or False value</td></tr>
 733           <tr><td><tt>sbyte</tt></td><td>Signed 8-bit value</td></tr>
 734           <tr><td><tt>short</tt></td><td>Signed 16-bit value</td></tr>
 735           <tr><td><tt>int</tt></td><td>Signed 32-bit value</td></tr>
 736           <tr><td><tt>long</tt></td><td>Signed 64-bit value</td></tr>
 737           <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
 738         </tbody>
 739       </table>
 740     </td>
 741   </tr>
 742 </table>
 743 </div>
 744
 745 <!-- _______________________________________________________________________ -->
 746 <div class="doc_subsubsection"> <a name="t_classifications">Type
 747 Classifications</a> </div>
 748 <div class="doc_text">
 749 <p>These different primitive types fall into a few useful
 750 classifications:</p>
 751
 752 <table border="1" cellspacing="0" cellpadding="4">
 753   <tbody>
 754     <tr><th>Classification</th><th>Types</th></tr>
 755     <tr>
 756       <td><a name="t_signed">signed</a></td>
 757       <td><tt>sbyte, short, int, long, float, double</tt></td>
 758     </tr>
 759     <tr>
 760       <td><a name="t_unsigned">unsigned</a></td>
 761       <td><tt>ubyte, ushort, uint, ulong</tt></td>
 762     </tr>
 763     <tr>
 764       <td><a name="t_integer">integer</a></td>
 765       <td><tt>ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td>
 766     </tr>
 767     <tr>
 768       <td><a name="t_integral">integral</a></td>
 769       <td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long</tt>
 770       </td>
 771     </tr>
 772     <tr>
 773       <td><a name="t_floating">floating point</a></td>
 774       <td><tt>float, double</tt></td>
 775     </tr>
 776     <tr>
 777       <td><a name="t_firstclass">first class</a></td>
 778       <td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long,<br>
 779       float, double, <a href="#t_pointer">pointer</a>,
 780       <a href="#t_packed">packed</a></tt></td>
 781     </tr>
 782   </tbody>
 783 </table>
 784
 785 <p>The <a href="#t_firstclass">first class</a> types are perhaps the
 786 most important.  Values of these types are the only ones which can be
 787 produced by instructions, passed as arguments, or used as operands to
 788 instructions.  This means that all structures and arrays must be
 789 manipulated either by pointer or by component.</p>
 790 </div>
 791
 792 <!-- ======================================================================= -->
 793 <div class="doc_subsection"> <a name="t_derived">Derived Types</a> </div>
 794
 795 <div class="doc_text">
 796
 797 <p>The real power in LLVM comes from the derived types in the system.
 798 This is what allows a programmer to represent arrays, functions,
 799 pointers, and other useful types.  Note that these derived types may be
 800 recursive: For example, it is possible to have a two dimensional array.</p>
 801
 802 </div>
 803
 804 <!-- _______________________________________________________________________ -->
 805 <div class="doc_subsubsection"> <a name="t_array">Array Type</a> </div>
 806
 807 <div class="doc_text">
 808
 809 <h5>Overview:</h5>
 810
 811 <p>The array type is a very simple derived type that arranges elements
 812 sequentially in memory.  The array type requires a size (number of
 813 elements) and an underlying data type.</p>
 814
 815 <h5>Syntax:</h5>
 816
 817 <pre>
 818   [&lt;# elements&gt; x &lt;elementtype&gt;]
 819 </pre>
 820
 821 <p>The number of elements is a constant integer value; elementtype may
 822 be any type with a size.</p>
 823
 824 <h5>Examples:</h5>
 825 <table class="layout">
 826   <tr class="layout">
 827     <td class="left">
 828       <tt>[40 x int ]</tt><br/>
 829       <tt>[41 x int ]</tt><br/>
 830       <tt>[40 x uint]</tt><br/>
 831     </td>
 832     <td class="left">
 833       Array of 40 integer values.<br/>
 834       Array of 41 integer values.<br/>
 835       Array of 40 unsigned integer values.<br/>
 836     </td>
 837   </tr>
 838 </table>
 839 <p>Here are some examples of multidimensional arrays:</p>
 840 <table class="layout">
 841   <tr class="layout">
 842     <td class="left">
 843       <tt>[3 x [4 x int]]</tt><br/>
 844       <tt>[12 x [10 x float]]</tt><br/>
 845       <tt>[2 x [3 x [4 x uint]]]</tt><br/>
 846     </td>
 847     <td class="left">
 848       3x4 array of integer values.<br/>
 849       12x10 array of single precision floating point values.<br/>
 850       2x3x4 array of unsigned integer values.<br/>
 851     </td>
 852   </tr>
 853 </table>
 854
 855 <p>Note that 'variable sized arrays' can be implemented in LLVM with a zero
 856 length array.  Normally, accesses past the end of an array are undefined in
 857 LLVM (e.g. it is illegal to access the 5th element of a 3 element array).
 858 As a special case, however, zero length arrays are recognized to be variable
 859 length.  This allows implementation of 'pascal style arrays' with the  LLVM
 860 type "{ int, [0 x float]}", for example.</p>
 861
 862 </div>
 863
 864 <!-- _______________________________________________________________________ -->
 865 <div class="doc_subsubsection"> <a name="t_function">Function Type</a> </div>
 866 <div class="doc_text">
 867 <h5>Overview:</h5>
 868 <p>The function type can be thought of as a function signature.  It
 869 consists of a return type and a list of formal parameter types.
 870 Function types are usually used to build virtual function tables
 871 (which are structures of pointers to functions), for indirect function
 872 calls, and when defining a function.</p>
 873 <p>
 874 The return type of a function type cannot be an aggregate type.
 875 </p>
 876 <h5>Syntax:</h5>
 877 <pre>  &lt;returntype&gt; (&lt;parameter list&gt;)<br></pre>
 878 <p>...where '<tt>&lt;parameter list&gt;</tt>' is a comma-separated list of type
 879 specifiers.  Optionally, the parameter list may include a type <tt>...</tt>,
 880 which indicates that the function takes a variable number of arguments.
 881 Variable argument functions can access their arguments with the <a
 882  href="#int_varargs">variable argument handling intrinsic</a> functions.</p>
 883 <h5>Examples:</h5>
 884 <table class="layout">
 885   <tr class="layout">
 886     <td class="left">
 887       <tt>int (int)</tt> <br/>
 888       <tt>float (int, int *) *</tt><br/>
 889       <tt>int (sbyte *, ...)</tt><br/>
 890     </td>
 891     <td class="left">
 892       function taking an <tt>int</tt>, returning an <tt>int</tt><br/>
 893       <a href="#t_pointer">Pointer</a> to a function that takes an
 894       <tt>int</tt> and a <a href="#t_pointer">pointer</a> to <tt>int</tt>,
 895       returning <tt>float</tt>.<br/>
 896       A vararg function that takes at least one <a href="#t_pointer">pointer</a>
 897       to <tt>sbyte</tt> (signed char in C), which returns an integer.  This is
 898       the signature for <tt>printf</tt> in LLVM.<br/>
 899     </td>
 900   </tr>
 901 </table>
 902
 903 </div>
 904 <!-- _______________________________________________________________________ -->
 905 <div class="doc_subsubsection"> <a name="t_struct">Structure Type</a> </div>
 906 <div class="doc_text">
 907 <h5>Overview:</h5>
 908 <p>The structure type is used to represent a collection of data members
 909 together in memory.  The packing of the field types is defined to match
 910 the ABI of the underlying processor.  The elements of a structure may
 911 be any type that has a size.</p>
 912 <p>Structures are accessed using '<tt><a href="#i_load">load</a></tt>
 913 and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a
 914 field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>'
 915 instruction.</p>
 916 <h5>Syntax:</h5>
 917 <pre>  { &lt;type list&gt; }<br></pre>
 918 <h5>Examples:</h5>
 919 <table class="layout">
 920   <tr class="layout">
 921     <td class="left">
 922       <tt>{ int, int, int }</tt><br/>
 923       <tt>{ float, int (int) * }</tt><br/>
 924     </td>
 925     <td class="left">
 926       a triple of three <tt>int</tt> values<br/>
 927       A pair, where the first element is a <tt>float</tt> and the second element
 928       is a <a href="#t_pointer">pointer</a> to a <a href="#t_function">function</a>
 929       that takes an <tt>int</tt>, returning an <tt>int</tt>.<br/>
 930     </td>
 931   </tr>
 932 </table>
 933 </div>
 934
 935 <!-- _______________________________________________________________________ -->
 936 <div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div>
 937 <div class="doc_text">
 938 <h5>Overview:</h5>
 939 <p>As in many languages, the pointer type represents a pointer or
 940 reference to another object, which must live in memory.</p>
 941 <h5>Syntax:</h5>
 942 <pre>  &lt;type&gt; *<br></pre>
 943 <h5>Examples:</h5>
 944 <table class="layout">
 945   <tr class="layout">
 946     <td class="left">
 947       <tt>[4x int]*</tt><br/>
 948       <tt>int (int *) *</tt><br/>
 949     </td>
 950     <td class="left">
 951       A <a href="#t_pointer">pointer</a> to <a href="#t_array">array</a> of
 952       four <tt>int</tt> values<br/>
 953       A <a href="#t_pointer">pointer</a> to a <a
 954       href="#t_function">function</a> that takes an <tt>int*</tt>, returning an
 955       <tt>int</tt>.<br/>
 956     </td>
 957   </tr>
 958 </table>
 959 </div>
 960
 961 <!-- _______________________________________________________________________ -->
 962 <div class="doc_subsubsection"> <a name="t_packed">Packed Type</a> </div>
 963 <div class="doc_text">
 964
 965 <h5>Overview:</h5>
 966
 967 <p>A packed type is a simple derived type that represents a vector
 968 of elements.  Packed types are used when multiple primitive data
 969 are operated in parallel using a single instruction (SIMD).
 970 A packed type requires a size (number of
 971 elements) and an underlying primitive data type.  Vectors must have a power
 972 of two length (1, 2, 4, 8, 16 ...).  Packed types are
 973 considered <a href="#t_firstclass">first class</a>.</p>
 974
 975 <h5>Syntax:</h5>
 976
 977 <pre>
 978   &lt; &lt;# elements&gt; x &lt;elementtype&gt; &gt;
 979 </pre>
 980
 981 <p>The number of elements is a constant integer value; elementtype may
 982 be any integral or floating point type.</p>
 983
 984 <h5>Examples:</h5>
 985
 986 <table class="layout">
 987   <tr class="layout">
 988     <td class="left">
 989       <tt>&lt;4 x int&gt;</tt><br/>
 990       <tt>&lt;8 x float&gt;</tt><br/>
 991       <tt>&lt;2 x uint&gt;</tt><br/>
 992     </td>
 993     <td class="left">
 994       Packed vector of 4 integer values.<br/>
 995       Packed vector of 8 floating-point values.<br/>
 996       Packed vector of 2 unsigned integer values.<br/>
 997     </td>
 998   </tr>
 999 </table>
1000 </div>
1001
1002 <!-- _______________________________________________________________________ -->
1003 <div class="doc_subsubsection"> <a name="t_opaque">Opaque Type</a> </div>
1004 <div class="doc_text">
1005
1006 <h5>Overview:</h5>
1007
1008 <p>Opaque types are used to represent unknown types in the system.  This
1009 corresponds (for example) to the C notion of a foward declared structure type.
1010 In LLVM, opaque types can eventually be resolved to any type (not just a
1011 structure type).</p>
1012
1013 <h5>Syntax:</h5>
1014
1015 <pre>
1016   opaque
1017 </pre>
1018
1019 <h5>Examples:</h5>
1020
1021 <table class="layout">
1022   <tr class="layout">
1023     <td class="left">
1024       <tt>opaque</tt>
1025     </td>
1026     <td class="left">
1027       An opaque type.<br/>
1028     </td>
1029   </tr>
1030 </table>
1031 </div>
1032
1033
1034 <!-- *********************************************************************** -->
1035 <div class="doc_section"> <a name="constants">Constants</a> </div>
1036 <!-- *********************************************************************** -->
1037
1038 <div class="doc_text">
1039
1040 <p>LLVM has several different basic types of constants.  This section describes
1041 them all and their syntax.</p>
1042
1043 </div>
1044
1045 <!-- ======================================================================= -->
1046 <div class="doc_subsection"><a name="simpleconstants">Simple Constants</a></div>
1047
1048 <div class="doc_text">
1049
1050 <dl>
1051   <dt><b>Boolean constants</b></dt>
1052
1053   <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
1054   constants of the <tt><a href="#t_primitive">bool</a></tt> type.
1055   </dd>
1056
1057   <dt><b>Integer constants</b></dt>
1058
1059   <dd>Standard integers (such as '4') are constants of the <a
1060   href="#t_integer">integer</a> type.  Negative numbers may be used with signed
1061   integer types.
1062   </dd>
1063
1064   <dt><b>Floating point constants</b></dt>
1065
1066   <dd>Floating point constants use standard decimal notation (e.g. 123.421),
1067   exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal
1068   notation (see below).  Floating point constants must have a <a
1069   href="#t_floating">floating point</a> type. </dd>
1070
1071   <dt><b>Null pointer constants</b></dt>
1072
1073   <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant
1074   and must be of <a href="#t_pointer">pointer type</a>.</dd>
1075
1076 </dl>
1077
1078 <p>The one non-intuitive notation for constants is the optional hexadecimal form
1079 of floating point constants.  For example, the form '<tt>double
1080 0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
1081 4.5e+15</tt>'.  The only time hexadecimal floating point constants are required
1082 (and the only time that they are generated by the disassembler) is when a
1083 floating point constant must be emitted but it cannot be represented as a
1084 decimal floating point number.  For example, NaN's, infinities, and other
1085 special values are represented in their IEEE hexadecimal format so that
1086 assembly and disassembly do not cause any bits to change in the constants.</p>
1087
1088 </div>
1089
1090 <!-- ======================================================================= -->
1091 <div class="doc_subsection"><a name="aggregateconstants">Aggregate Constants</a>
1092 </div>
1093
1094 <div class="doc_text">
1095 <p>Aggregate constants arise from aggregation of simple constants
1096 and smaller aggregate constants.</p>
1097
1098 <dl>
1099   <dt><b>Structure constants</b></dt>
1100
1101   <dd>Structure constants are represented with notation similar to structure
1102   type definitions (a comma separated list of elements, surrounded by braces
1103   (<tt>{}</tt>)).  For example: "<tt>{ int 4, float 17.0, int* %G }</tt>",
1104   where "<tt>%G</tt>" is declared as "<tt>%G = external global int</tt>".  Structure constants
1105   must have <a href="#t_struct">structure type</a>, and the number and
1106   types of elements must match those specified by the type.
1107   </dd>
1108
1109   <dt><b>Array constants</b></dt>
1110
1111   <dd>Array constants are represented with notation similar to array type
1112   definitions (a comma separated list of elements, surrounded by square brackets
1113   (<tt>[]</tt>)).  For example: "<tt>[ int 42, int 11, int 74 ]</tt>".  Array
1114   constants must have <a href="#t_array">array type</a>, and the number and
1115   types of elements must match those specified by the type.
1116   </dd>
1117
1118   <dt><b>Packed constants</b></dt>
1119
1120   <dd>Packed constants are represented with notation similar to packed type
1121   definitions (a comma separated list of elements, surrounded by
1122   less-than/greater-than's (<tt>&lt;&gt;</tt>)).  For example: "<tt>&lt; int 42,
1123   int 11, int 74, int 100 &gt;</tt>".  Packed constants must have <a
1124   href="#t_packed">packed type</a>, and the number and types of elements must
1125   match those specified by the type.
1126   </dd>
1127
1128   <dt><b>Zero initialization</b></dt>
1129
1130   <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a
1131   value to zero of <em>any</em> type, including scalar and aggregate types.
1132   This is often used to avoid having to print large zero initializers (e.g. for
1133   large arrays) and is always exactly equivalent to using explicit zero
1134   initializers.
1135   </dd>
1136 </dl>
1137
1138 </div>
1139
1140 <!-- ======================================================================= -->
1141 <div class="doc_subsection">
1142   <a name="globalconstants">Global Variable and Function Addresses</a>
1143 </div>
1144
1145 <div class="doc_text">
1146
1147 <p>The addresses of <a href="#globalvars">global variables</a> and <a
1148 href="#functionstructure">functions</a> are always implicitly valid (link-time)
1149 constants.  These constants are explicitly referenced when the <a
1150 href="#identifiers">identifier for the global</a> is used and always have <a
1151 href="#t_pointer">pointer</a> type. For example, the following is a legal LLVM
1152 file:</p>
1153
1154 <pre>
1155   %X = global int 17
1156   %Y = global int 42
1157   %Z = global [2 x int*] [ int* %X, int* %Y ]
1158 </pre>
1159
1160 </div>
1161
1162 <!-- ======================================================================= -->
1163 <div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div>
1164 <div class="doc_text">
1165   <p>The string '<tt>undef</tt>' is recognized as a type-less constant that has
1166   no specific value.  Undefined values may be of any type and be used anywhere
1167   a constant is permitted.</p>
1168
1169   <p>Undefined values indicate to the compiler that the program is well defined
1170   no matter what value is used, giving the compiler more freedom to optimize.
1171   </p>
1172 </div>
1173
1174 <!-- ======================================================================= -->
1175 <div class="doc_subsection"><a name="constantexprs">Constant Expressions</a>
1176 </div>
1177
1178 <div class="doc_text">
1179
1180 <p>Constant expressions are used to allow expressions involving other constants
1181 to be used as constants.  Constant expressions may be of any <a
1182 href="#t_firstclass">first class</a> type and may involve any LLVM operation
1183 that does not have side effects (e.g. load and call are not supported).  The
1184 following is the syntax for constant expressions:</p>
1185
1186 <dl>
1187   <dt><b><tt>trunc ( CST to TYPE )</tt></b></dt>
1188   <dd>Truncate a constant to another type. The bit size of CST must be larger
1189   than the bit size of TYPE. Both types must be integral.</dd>
1190
1191   <dt><b><tt>zext ( CST to TYPE )</tt></b></dt>
1192   <dd>Zero extend a constant to another type. The bit size of CST must be
1193   smaller or equal to the bit size of TYPE.  Both types must be integral.</dd>
1194
1195   <dt><b><tt>sext ( CST to TYPE )</tt></b></dt>
1196   <dd>Sign extend a constant to another type. The bit size of CST must be
1197   smaller or equal to the bit size of TYPE.  Both types must be integral.</dd>
1198
1199   <dt><b><tt>fptrunc ( CST to TYPE )</tt></b></dt>
1200   <dd>Truncate a floating point constant to another floating point type. The
1201   size of CST must be larger than the size of TYPE. Both types must be
1202   floating point.</dd>
1203
1204   <dt><b><tt>fpext ( CST to TYPE )</tt></b></dt>
1205   <dd>Floating point extend a constant to another type. The size of CST must be
1206   smaller or equal to the size of TYPE. Both types must be floating point.</dd>
1207
1208   <dt><b><tt>fp2uint ( CST to TYPE )</tt></b></dt>
1209   <dd>Convert a floating point constant to the corresponding unsigned integer
1210   constant. TYPE must be an integer type. CST must be floating point. If the
1211   value won't fit in the integer type, the results are undefined.</dd>
1212
1213   <dt><b><tt>fptosi ( CST to TYPE )</tt></b></dt>
1214   <dd>Convert a floating point constant to the corresponding signed integer
1215   constant. TYPE must be an integer type. CST must be floating point. If the
1216   value won't fit in the integer type, the results are undefined.</dd>
1217
1218   <dt><b><tt>uitofp ( CST to TYPE )</tt></b></dt>
1219   <dd>Convert an unsigned integer constant to the corresponding floating point
1220   constant. TYPE must be floating point. CST must be of integer type. If the
1221   value won't fit in the floating point type, the results are undefined.</dd>
1222
1223   <dt><b><tt>sitofp ( CST to TYPE )</tt></b></dt>
1224   <dd>Convert a signed integer constant to the corresponding floating point
1225   constant. TYPE must be floating point. CST must be of integer type. If the
1226   value won't fit in the floating point type, the results are undefined.</dd>
1227
1228   <dt><b><tt>ptrtoint ( CST to TYPE )</tt></b></dt>
1229   <dd>Convert a pointer typed constant to the corresponding integer constant
1230   TYPE must be an integer type. CST must be of pointer type. The CST value is
1231   zero extended, truncated, or unchanged to make it fit in TYPE.</dd>
1232
1233   <dt><b><tt>inttoptr ( CST to TYPE )</tt></b></dt>
1234   <dd>Convert a integer constant to a pointer constant.  TYPE must be a
1235   pointer type.  CST must be of integer type. The CST value is zero extended,
1236   truncated, or unchanged to make it fit in a pointer size. This one is
1237   <i>really</i> dangerous!</dd>
1238
1239   <dt><b><tt>bitcast ( CST to TYPE )</tt></b></dt>
1240   <dd>Convert a constant, CST, to another TYPE. The size of CST and TYPE must be
1241   identical (same number of bits). The conversion is done as if the CST value
1242   was stored to memory and read back as TYPE. In other words, no bits change
1243   with this operator, just the type.  This can be used for conversion of
1244   packed types to any other type, as long as they have the same bit width. For
1245   pointers it is only valid to cast to another pointer type.
1246   </dd>
1247
1248   <dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
1249
1250   <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
1251   constants.  As with the <a href="#i_getelementptr">getelementptr</a>
1252   instruction, the index list may have zero or more indexes, which are required
1253   to make sense for the type of "CSTPTR".</dd>
1254
1255   <dt><b><tt>select ( COND, VAL1, VAL2 )</tt></b></dt>
1256
1257   <dd>Perform the <a href="#i_select">select operation</a> on
1258   constants.</dd>
1259
1260   <dt><b><tt>icmp COND ( VAL1, VAL2 )</tt></b></dt>
1261   <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd>
1262
1263   <dt><b><tt>fcmp COND ( VAL1, VAL2 )</tt></b></dt>
1264   <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd>
1265
1266   <dt><b><tt>extractelement ( VAL, IDX )</tt></b></dt>
1267
1268   <dd>Perform the <a href="#i_extractelement">extractelement
1269   operation</a> on constants.
1270
1271   <dt><b><tt>insertelement ( VAL, ELT, IDX )</tt></b></dt>
1272
1273   <dd>Perform the <a href="#i_insertelement">insertelement
1274     operation</a> on constants.</dd>
1275
1276
1277   <dt><b><tt>shufflevector ( VEC1, VEC2, IDXMASK )</tt></b></dt>
1278
1279   <dd>Perform the <a href="#i_shufflevector">shufflevector
1280     operation</a> on constants.</dd>
1281
1282   <dt><b><tt>OPCODE ( LHS, RHS )</tt></b></dt>
1283
1284   <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may
1285   be any of the <a href="#binaryops">binary</a> or <a href="#bitwiseops">bitwise
1286   binary</a> operations.  The constraints on operands are the same as those for
1287   the corresponding instruction (e.g. no bitwise operations on floating point
1288   values are allowed).</dd>
1289 </dl>
1290 </div>
1291
1292 <!-- *********************************************************************** -->
1293 <div class="doc_section"> <a name="othervalues">Other Values</a> </div>
1294 <!-- *********************************************************************** -->
1295
1296 <!-- ======================================================================= -->
1297 <div class="doc_subsection">
1298 <a name="inlineasm">Inline Assembler Expressions</a>
1299 </div>
1300
1301 <div class="doc_text">
1302
1303 <p>
1304 LLVM supports inline assembler expressions (as opposed to <a href="#moduleasm">
1305 Module-Level Inline Assembly</a>) through the use of a special value.  This
1306 value represents the inline assembler as a string (containing the instructions
1307 to emit), a list of operand constraints (stored as a string), and a flag that
1308 indicates whether or not the inline asm expression has side effects.  An example
1309 inline assembler expression is:
1310 </p>
1311
1312 <pre>
1313   int(int) asm "bswap $0", "=r,r"
1314 </pre>
1315
1316 <p>
1317 Inline assembler expressions may <b>only</b> be used as the callee operand of
1318 a <a href="#i_call"><tt>call</tt> instruction</a>.  Thus, typically we have:
1319 </p>
1320
1321 <pre>
1322   %X = call int asm "<a href="#i_bswap">bswap</a> $0", "=r,r"(int %Y)
1323 </pre>
1324
1325 <p>
1326 Inline asms with side effects not visible in the constraint list must be marked
1327 as having side effects.  This is done through the use of the
1328 '<tt>sideeffect</tt>' keyword, like so:
1329 </p>
1330
1331 <pre>
1332   call void asm sideeffect "eieio", ""()
1333 </pre>
1334
1335 <p>TODO: The format of the asm and constraints string still need to be
1336 documented here.  Constraints on what can be done (e.g. duplication, moving, etc
1337 need to be documented).
1338 </p>
1339
1340 </div>
1341
1342 <!-- *********************************************************************** -->
1343 <div class="doc_section"> <a name="instref">Instruction Reference</a> </div>
1344 <!-- *********************************************************************** -->
1345
1346 <div class="doc_text">
1347
1348 <p>The LLVM instruction set consists of several different
1349 classifications of instructions: <a href="#terminators">terminator
1350 instructions</a>, <a href="#binaryops">binary instructions</a>,
1351 <a href="#bitwiseops">bitwise binary instructions</a>, <a
1352  href="#memoryops">memory instructions</a>, and <a href="#otherops">other
1353 instructions</a>.</p>
1354
1355 </div>
1356
1357 <!-- ======================================================================= -->
1358 <div class="doc_subsection"> <a name="terminators">Terminator
1359 Instructions</a> </div>
1360
1361 <div class="doc_text">
1362
1363 <p>As mentioned <a href="#functionstructure">previously</a>, every
1364 basic block in a program ends with a "Terminator" instruction, which
1365 indicates which block should be executed after the current block is
1366 finished. These terminator instructions typically yield a '<tt>void</tt>'
1367 value: they produce control flow, not values (the one exception being
1368 the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
1369 <p>There are six different terminator instructions: the '<a
1370  href="#i_ret"><tt>ret</tt></a>' instruction, the '<a href="#i_br"><tt>br</tt></a>'
1371 instruction, the '<a href="#i_switch"><tt>switch</tt></a>' instruction,
1372 the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the '<a
1373  href="#i_unwind"><tt>unwind</tt></a>' instruction, and the '<a
1374  href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p>
1375
1376 </div>
1377
1378 <!-- _______________________________________________________________________ -->
1379 <div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>'
1380 Instruction</a> </div>
1381 <div class="doc_text">
1382 <h5>Syntax:</h5>
1383 <pre>  ret &lt;type&gt; &lt;value&gt;       <i>; Return a value from a non-void function</i>
1384   ret void                 <i>; Return from void function</i>
1385 </pre>
1386 <h5>Overview:</h5>
1387 <p>The '<tt>ret</tt>' instruction is used to return control flow (and a
1388 value) from a function back to the caller.</p>
1389 <p>There are two forms of the '<tt>ret</tt>' instruction: one that
1390 returns a value and then causes control flow, and one that just causes
1391 control flow to occur.</p>
1392 <h5>Arguments:</h5>
1393 <p>The '<tt>ret</tt>' instruction may return any '<a
1394  href="#t_firstclass">first class</a>' type.  Notice that a function is
1395 not <a href="#wellformed">well formed</a> if there exists a '<tt>ret</tt>'
1396 instruction inside of the function that returns a value that does not
1397 match the return type of the function.</p>
1398 <h5>Semantics:</h5>
1399 <p>When the '<tt>ret</tt>' instruction is executed, control flow
1400 returns back to the calling function's context.  If the caller is a "<a
1401  href="#i_call"><tt>call</tt></a>" instruction, execution continues at
1402 the instruction after the call.  If the caller was an "<a
1403  href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues
1404 at the beginning of the "normal" destination block.  If the instruction
1405 returns a value, that value shall set the call or invoke instruction's
1406 return value.</p>
1407 <h5>Example:</h5>
1408 <pre>  ret int 5                       <i>; Return an integer value of 5</i>
1409   ret void                        <i>; Return from a void function</i>
1410 </pre>
1411 </div>
1412 <!-- _______________________________________________________________________ -->
1413 <div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div>
1414 <div class="doc_text">
1415 <h5>Syntax:</h5>
1416 <pre>  br bool &lt;cond&gt;, label &lt;iftrue&gt;, label &lt;iffalse&gt;<br>  br label &lt;dest&gt;          <i>; Unconditional branch</i>
1417 </pre>
1418 <h5>Overview:</h5>
1419 <p>The '<tt>br</tt>' instruction is used to cause control flow to
1420 transfer to a different basic block in the current function.  There are
1421 two forms of this instruction, corresponding to a conditional branch
1422 and an unconditional branch.</p>
1423 <h5>Arguments:</h5>
1424 <p>The conditional branch form of the '<tt>br</tt>' instruction takes a
1425 single '<tt>bool</tt>' value and two '<tt>label</tt>' values.  The
1426 unconditional form of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>'
1427 value as a target.</p>
1428 <h5>Semantics:</h5>
1429 <p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>bool</tt>'
1430 argument is evaluated.  If the value is <tt>true</tt>, control flows
1431 to the '<tt>iftrue</tt>' <tt>label</tt> argument.  If "cond" is <tt>false</tt>,
1432 control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p>
1433 <h5>Example:</h5>
1434 <pre>Test:<br>  %cond = <a href="#i_icmp">icmp</a> eq, int %a, %b<br>  br bool %cond, label %IfEqual, label %IfUnequal<br>IfEqual:<br>  <a
1435  href="#i_ret">ret</a> int 1<br>IfUnequal:<br>  <a href="#i_ret">ret</a> int 0<br></pre>
1436 </div>
1437 <!-- _______________________________________________________________________ -->
1438 <div class="doc_subsubsection">
1439    <a name="i_switch">'<tt>switch</tt>' Instruction</a>
1440 </div>
1441
1442 <div class="doc_text">
1443 <h5>Syntax:</h5>
1444
1445 <pre>
1446   switch &lt;intty&gt; &lt;value&gt;, label &lt;defaultdest&gt; [ &lt;intty&gt; &lt;val&gt;, label &lt;dest&gt; ... ]
1447 </pre>
1448
1449 <h5>Overview:</h5>
1450
1451 <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
1452 several different places.  It is a generalization of the '<tt>br</tt>'
1453 instruction, allowing a branch to occur to one of many possible
1454 destinations.</p>
1455
1456
1457 <h5>Arguments:</h5>
1458
1459 <p>The '<tt>switch</tt>' instruction uses three parameters: an integer
1460 comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
1461 an array of pairs of comparison value constants and '<tt>label</tt>'s.  The
1462 table is not allowed to contain duplicate constant entries.</p>
1463
1464 <h5>Semantics:</h5>
1465
1466 <p>The <tt>switch</tt> instruction specifies a table of values and
1467 destinations. When the '<tt>switch</tt>' instruction is executed, this
1468 table is searched for the given value.  If the value is found, control flow is
1469 transfered to the corresponding destination; otherwise, control flow is
1470 transfered to the default destination.</p>
1471
1472 <h5>Implementation:</h5>
1473
1474 <p>Depending on properties of the target machine and the particular
1475 <tt>switch</tt> instruction, this instruction may be code generated in different
1476 ways.  For example, it could be generated as a series of chained conditional
1477 branches or with a lookup table.</p>
1478
1479 <h5>Example:</h5>
1480
1481 <pre>
1482  <i>; Emulate a conditional br instruction</i>
1483  %Val = <a href="#i_zext">zext</a> bool %value to int
1484  switch int %Val, label %truedest [int 0, label %falsedest ]
1485
1486  <i>; Emulate an unconditional br instruction</i>
1487  switch uint 0, label %dest [ ]
1488
1489  <i>; Implement a jump table:</i>
1490  switch uint %val, label %otherwise [ uint 0, label %onzero
1491                                       uint 1, label %onone
1492                                       uint 2, label %ontwo ]
1493 </pre>
1494 </div>
1495
1496 <!-- _______________________________________________________________________ -->
1497 <div class="doc_subsubsection">
1498   <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
1499 </div>
1500
1501 <div class="doc_text">
1502
1503 <h5>Syntax:</h5>
1504
1505 <pre>
1506   &lt;result&gt; = invoke [<a href="#callingconv">cconv</a>] &lt;ptr to function ty&gt; %&lt;function ptr val&gt;(&lt;function args&gt;)
1507                 to label &lt;normal label&gt; unwind label &lt;exception label&gt;
1508 </pre>
1509
1510 <h5>Overview:</h5>
1511
1512 <p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified
1513 function, with the possibility of control flow transfer to either the
1514 '<tt>normal</tt>' label or the
1515 '<tt>exception</tt>' label.  If the callee function returns with the
1516 "<tt><a href="#i_ret">ret</a></tt>" instruction, control flow will return to the
1517 "normal" label.  If the callee (or any indirect callees) returns with the "<a
1518 href="#i_unwind"><tt>unwind</tt></a>" instruction, control is interrupted and
1519 continued at the dynamically nearest "exception" label.</p>
1520
1521 <h5>Arguments:</h5>
1522
1523 <p>This instruction requires several arguments:</p>
1524
1525 <ol>
1526   <li>
1527     The optional "cconv" marker indicates which <a href="callingconv">calling
1528     convention</a> the call should use.  If none is specified, the call defaults
1529     to using C calling conventions.
1530   </li>
1531   <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
1532   function value being invoked.  In most cases, this is a direct function
1533   invocation, but indirect <tt>invoke</tt>s are just as possible, branching off
1534   an arbitrary pointer to function value.
1535   </li>
1536
1537   <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
1538   function to be invoked. </li>
1539
1540   <li>'<tt>function args</tt>': argument list whose types match the function
1541   signature argument types.  If the function signature indicates the function
1542   accepts a variable number of arguments, the extra arguments can be
1543   specified. </li>
1544
1545   <li>'<tt>normal label</tt>': the label reached when the called function
1546   executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
1547
1548   <li>'<tt>exception label</tt>': the label reached when a callee returns with
1549   the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li>
1550
1551 </ol>
1552
1553 <h5>Semantics:</h5>
1554
1555 <p>This instruction is designed to operate as a standard '<tt><a
1556 href="#i_call">call</a></tt>' instruction in most regards.  The primary
1557 difference is that it establishes an association with a label, which is used by
1558 the runtime library to unwind the stack.</p>
1559
1560 <p>This instruction is used in languages with destructors to ensure that proper
1561 cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
1562 exception.  Additionally, this is important for implementation of
1563 '<tt>catch</tt>' clauses in high-level languages that support them.</p>
1564
1565 <h5>Example:</h5>
1566 <pre>
1567   %retval = invoke int %Test(int 15)             to label %Continue
1568               unwind label %TestCleanup     <i>; {int}:retval set</i>
1569   %retval = invoke <a href="#callingconv">coldcc</a> int %Test(int 15)             to label %Continue
1570               unwind label %TestCleanup     <i>; {int}:retval set</i>
1571 </pre>
1572 </div>
1573
1574
1575 <!-- _______________________________________________________________________ -->
1576
1577 <div class="doc_subsubsection"> <a name="i_unwind">'<tt>unwind</tt>'
1578 Instruction</a> </div>
1579
1580 <div class="doc_text">
1581
1582 <h5>Syntax:</h5>
1583 <pre>
1584   unwind
1585 </pre>
1586
1587 <h5>Overview:</h5>
1588
1589 <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow
1590 at the first callee in the dynamic call stack which used an <a
1591 href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call.  This is
1592 primarily used to implement exception handling.</p>
1593
1594 <h5>Semantics:</h5>
1595
1596 <p>The '<tt>unwind</tt>' intrinsic causes execution of the current function to
1597 immediately halt.  The dynamic call stack is then searched for the first <a
1598 href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack.  Once found,
1599 execution continues at the "exceptional" destination block specified by the
1600 <tt>invoke</tt> instruction.  If there is no <tt>invoke</tt> instruction in the
1601 dynamic call chain, undefined behavior results.</p>
1602 </div>
1603
1604 <!-- _______________________________________________________________________ -->
1605
1606 <div class="doc_subsubsection"> <a name="i_unreachable">'<tt>unreachable</tt>'
1607 Instruction</a> </div>
1608
1609 <div class="doc_text">
1610
1611 <h5>Syntax:</h5>
1612 <pre>
1613   unreachable
1614 </pre>
1615
1616 <h5>Overview:</h5>
1617
1618 <p>The '<tt>unreachable</tt>' instruction has no defined semantics.  This
1619 instruction is used to inform the optimizer that a particular portion of the
1620 code is not reachable.  This can be used to indicate that the code after a
1621 no-return function cannot be reached, and other facts.</p>
1622
1623 <h5>Semantics:</h5>
1624
1625 <p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p>
1626 </div>
1627
1628
1629
1630 <!-- ======================================================================= -->
1631 <div class="doc_subsection"> <a name="binaryops">Binary Operations</a> </div>
1632 <div class="doc_text">
1633 <p>Binary operators are used to do most of the computation in a
1634 program.  They require two operands, execute an operation on them, and
1635 produce a single value.  The operands might represent
1636 multiple data, as is the case with the <a href="#t_packed">packed</a> data type.
1637 The result value of a binary operator is not
1638 necessarily the same type as its operands.</p>
1639 <p>There are several different binary operators:</p>
1640 </div>
1641 <!-- _______________________________________________________________________ -->
1642 <div class="doc_subsubsection"> <a name="i_add">'<tt>add</tt>'
1643 Instruction</a> </div>
1644 <div class="doc_text">
1645 <h5>Syntax:</h5>
1646 <pre>  &lt;result&gt; = add &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1647 </pre>
1648 <h5>Overview:</h5>
1649 <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
1650 <h5>Arguments:</h5>
1651 <p>The two arguments to the '<tt>add</tt>' instruction must be either <a
1652  href="#t_integer">integer</a> or <a href="#t_floating">floating point</a> values.
1653  This instruction can also take <a href="#t_packed">packed</a> versions of the values.
1654 Both arguments must have identical types.</p>
1655 <h5>Semantics:</h5>
1656 <p>The value produced is the integer or floating point sum of the two
1657 operands.</p>
1658 <h5>Example:</h5>
1659 <pre>  &lt;result&gt; = add int 4, %var          <i>; yields {int}:result = 4 + %var</i>
1660 </pre>
1661 </div>
1662 <!-- _______________________________________________________________________ -->
1663 <div class="doc_subsubsection"> <a name="i_sub">'<tt>sub</tt>'
1664 Instruction</a> </div>
1665 <div class="doc_text">
1666 <h5>Syntax:</h5>
1667 <pre>  &lt;result&gt; = sub &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1668 </pre>
1669 <h5>Overview:</h5>
1670 <p>The '<tt>sub</tt>' instruction returns the difference of its two
1671 operands.</p>
1672 <p>Note that the '<tt>sub</tt>' instruction is used to represent the '<tt>neg</tt>'
1673 instruction present in most other intermediate representations.</p>
1674 <h5>Arguments:</h5>
1675 <p>The two arguments to the '<tt>sub</tt>' instruction must be either <a
1676  href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1677 values.
1678 This instruction can also take <a href="#t_packed">packed</a> versions of the values.
1679 Both arguments must have identical types.</p>
1680 <h5>Semantics:</h5>
1681 <p>The value produced is the integer or floating point difference of
1682 the two operands.</p>
1683 <h5>Example:</h5>
1684 <pre>  &lt;result&gt; = sub int 4, %var          <i>; yields {int}:result = 4 - %var</i>
1685   &lt;result&gt; = sub int 0, %val          <i>; yields {int}:result = -%var</i>
1686 </pre>
1687 </div>
1688 <!-- _______________________________________________________________________ -->
1689 <div class="doc_subsubsection"> <a name="i_mul">'<tt>mul</tt>'
1690 Instruction</a> </div>
1691 <div class="doc_text">
1692 <h5>Syntax:</h5>
1693 <pre>  &lt;result&gt; = mul &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1694 </pre>
1695 <h5>Overview:</h5>
1696 <p>The  '<tt>mul</tt>' instruction returns the product of its two
1697 operands.</p>
1698 <h5>Arguments:</h5>
1699 <p>The two arguments to the '<tt>mul</tt>' instruction must be either <a
1700  href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
1701 values.
1702 This instruction can also take <a href="#t_packed">packed</a> versions of the values.
1703 Both arguments must have identical types.</p>
1704 <h5>Semantics:</h5>
1705 <p>The value produced is the integer or floating point product of the
1706 two operands.</p>
1707 <p>There is no signed vs unsigned multiplication.  The appropriate
1708 action is taken based on the type of the operand.</p>
1709 <h5>Example:</h5>
1710 <pre>  &lt;result&gt; = mul int 4, %var          <i>; yields {int}:result = 4 * %var</i>
1711 </pre>
1712 </div>
1713 <!-- _______________________________________________________________________ -->
1714 <div class="doc_subsubsection"> <a name="i_udiv">'<tt>udiv</tt>' Instruction
1715 </a></div>
1716 <div class="doc_text">
1717 <h5>Syntax:</h5>
1718 <pre>  &lt;result&gt; = udiv &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1719 </pre>
1720 <h5>Overview:</h5>
1721 <p>The '<tt>udiv</tt>' instruction returns the quotient of its two
1722 operands.</p>
1723 <h5>Arguments:</h5>
1724 <p>The two arguments to the '<tt>udiv</tt>' instruction must be
1725 <a href="#t_integer">integer</a> values. Both arguments must have identical
1726 types. This instruction can also take <a href="#t_packed">packed</a> versions
1727 of the values in which case the elements must be integers.</p>
1728 <h5>Semantics:</h5>
1729 <p>The value produced is the unsigned integer quotient of the two operands. This
1730 instruction always performs an unsigned division operation, regardless of
1731 whether the arguments are unsigned or not.</p>
1732 <h5>Example:</h5>
1733 <pre>  &lt;result&gt; = udiv uint 4, %var          <i>; yields {uint}:result = 4 / %var</i>
1734 </pre>
1735 </div>
1736 <!-- _______________________________________________________________________ -->
1737 <div class="doc_subsubsection"> <a name="i_sdiv">'<tt>sdiv</tt>' Instruction
1738 </a> </div>
1739 <div class="doc_text">
1740 <h5>Syntax:</h5>
1741 <pre>  &lt;result&gt; = sdiv &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1742 </pre>
1743 <h5>Overview:</h5>
1744 <p>The '<tt>sdiv</tt>' instruction returns the quotient of its two
1745 operands.</p>
1746 <h5>Arguments:</h5>
1747 <p>The two arguments to the '<tt>sdiv</tt>' instruction must be
1748 <a href="#t_integer">integer</a> values.  Both arguments must have identical
1749 types. This instruction can also take <a href="#t_packed">packed</a> versions
1750 of the values in which case the elements must be integers.</p>
1751 <h5>Semantics:</h5>
1752 <p>The value produced is the signed integer quotient of the two operands. This
1753 instruction always performs a signed division operation, regardless of whether
1754 the arguments are signed or not.</p>
1755 <h5>Example:</h5>
1756 <pre>  &lt;result&gt; = sdiv int 4, %var          <i>; yields {int}:result = 4 / %var</i>
1757 </pre>
1758 </div>
1759 <!-- _______________________________________________________________________ -->
1760 <div class="doc_subsubsection"> <a name="i_fdiv">'<tt>fdiv</tt>'
1761 Instruction</a> </div>
1762 <div class="doc_text">
1763 <h5>Syntax:</h5>
1764 <pre>  &lt;result&gt; = fdiv &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1765 </pre>
1766 <h5>Overview:</h5>
1767 <p>The '<tt>fdiv</tt>' instruction returns the quotient of its two
1768 operands.</p>
1769 <h5>Arguments:</h5>
1770 <p>The two arguments to the '<tt>div</tt>' instruction must be
1771 <a href="#t_floating">floating point</a> values.  Both arguments must have
1772 identical types.  This instruction can also take <a href="#t_packed">packed</a>
1773 versions of the values in which case the elements must be floating point.</p>
1774 <h5>Semantics:</h5>
1775 <p>The value produced is the floating point quotient of the two operands.</p>
1776 <h5>Example:</h5>
1777 <pre>  &lt;result&gt; = fdiv float 4.0, %var          <i>; yields {float}:result = 4.0 / %var</i>
1778 </pre>
1779 </div>
1780 <!-- _______________________________________________________________________ -->
1781 <div class="doc_subsubsection"> <a name="i_urem">'<tt>urem</tt>' Instruction</a>
1782 </div>
1783 <div class="doc_text">
1784 <h5>Syntax:</h5>
1785 <pre>  &lt;result&gt; = urem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1786 </pre>
1787 <h5>Overview:</h5>
1788 <p>The '<tt>urem</tt>' instruction returns the remainder from the
1789 unsigned division of its two arguments.</p>
1790 <h5>Arguments:</h5>
1791 <p>The two arguments to the '<tt>urem</tt>' instruction must be
1792 <a href="#t_integer">integer</a> values. Both arguments must have identical
1793 types.</p>
1794 <h5>Semantics:</h5>
1795 <p>This instruction returns the unsigned integer <i>remainder</i> of a division.
1796 This instruction always performs an unsigned division to get the remainder,
1797 regardless of whether the arguments are unsigned or not.</p>
1798 <h5>Example:</h5>
1799 <pre>  &lt;result&gt; = urem uint 4, %var          <i>; yields {uint}:result = 4 % %var</i>
1800 </pre>
1801
1802 </div>
1803 <!-- _______________________________________________________________________ -->
1804 <div class="doc_subsubsection"> <a name="i_srem">'<tt>srem</tt>'
1805 Instruction</a> </div>
1806 <div class="doc_text">
1807 <h5>Syntax:</h5>
1808 <pre>  &lt;result&gt; = srem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1809 </pre>
1810 <h5>Overview:</h5>
1811 <p>The '<tt>srem</tt>' instruction returns the remainder from the
1812 signed division of its two operands.</p>
1813 <h5>Arguments:</h5>
1814 <p>The two arguments to the '<tt>srem</tt>' instruction must be
1815 <a href="#t_integer">integer</a> values.  Both arguments must have identical
1816 types.</p>
1817 <h5>Semantics:</h5>
1818 <p>This instruction returns the <i>remainder</i> of a division (where the result
1819 has the same sign as the divisor), not the <i>modulus</i> (where the
1820 result has the same sign as the dividend) of a value.  For more
1821 information about the difference, see <a
1822  href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
1823 Math Forum</a>.</p>
1824 <h5>Example:</h5>
1825 <pre>  &lt;result&gt; = srem int 4, %var          <i>; yields {int}:result = 4 % %var</i>
1826 </pre>
1827
1828 </div>
1829 <!-- _______________________________________________________________________ -->
1830 <div class="doc_subsubsection"> <a name="i_frem">'<tt>frem</tt>'
1831 Instruction</a> </div>
1832 <div class="doc_text">
1833 <h5>Syntax:</h5>
1834 <pre>  &lt;result&gt; = frem &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1835 </pre>
1836 <h5>Overview:</h5>
1837 <p>The '<tt>frem</tt>' instruction returns the remainder from the
1838 division of its two operands.</p>
1839 <h5>Arguments:</h5>
1840 <p>The two arguments to the '<tt>frem</tt>' instruction must be
1841 <a href="#t_floating">floating point</a> values.  Both arguments must have
1842 identical types.</p>
1843 <h5>Semantics:</h5>
1844 <p>This instruction returns the <i>remainder</i> of a division.</p>
1845 <h5>Example:</h5>
1846 <pre>  &lt;result&gt; = frem float 4.0, %var          <i>; yields {float}:result = 4.0 % %var</i>
1847 </pre>
1848 </div>
1849
1850 <!-- ======================================================================= -->
1851 <div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary
1852 Operations</a> </div>
1853 <div class="doc_text">
1854 <p>Bitwise binary operators are used to do various forms of
1855 bit-twiddling in a program.  They are generally very efficient
1856 instructions and can commonly be strength reduced from other
1857 instructions.  They require two operands, execute an operation on them,
1858 and produce a single value.  The resulting value of the bitwise binary
1859 operators is always the same type as its first operand.</p>
1860 </div>
1861 <!-- _______________________________________________________________________ -->
1862 <div class="doc_subsubsection"> <a name="i_and">'<tt>and</tt>'
1863 Instruction</a> </div>
1864 <div class="doc_text">
1865 <h5>Syntax:</h5>
1866 <pre>  &lt;result&gt; = and &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1867 </pre>
1868 <h5>Overview:</h5>
1869 <p>The '<tt>and</tt>' instruction returns the bitwise logical and of
1870 its two operands.</p>
1871 <h5>Arguments:</h5>
1872 <p>The two arguments to the '<tt>and</tt>' instruction must be <a
1873  href="#t_integral">integral</a> values.  Both arguments must have
1874 identical types.</p>
1875 <h5>Semantics:</h5>
1876 <p>The truth table used for the '<tt>and</tt>' instruction is:</p>
1877 <p> </p>
1878 <div style="align: center">
1879 <table border="1" cellspacing="0" cellpadding="4">
1880   <tbody>
1881     <tr>
1882       <td>In0</td>
1883       <td>In1</td>
1884       <td>Out</td>
1885     </tr>
1886     <tr>
1887       <td>0</td>
1888       <td>0</td>
1889       <td>0</td>
1890     </tr>
1891     <tr>
1892       <td>0</td>
1893       <td>1</td>
1894       <td>0</td>
1895     </tr>
1896     <tr>
1897       <td>1</td>
1898       <td>0</td>
1899       <td>0</td>
1900     </tr>
1901     <tr>
1902       <td>1</td>
1903       <td>1</td>
1904       <td>1</td>
1905     </tr>
1906   </tbody>
1907 </table>
1908 </div>
1909 <h5>Example:</h5>
1910 <pre>  &lt;result&gt; = and int 4, %var         <i>; yields {int}:result = 4 &amp; %var</i>
1911   &lt;result&gt; = and int 15, 40          <i>; yields {int}:result = 8</i>
1912   &lt;result&gt; = and int 4, 8            <i>; yields {int}:result = 0</i>
1913 </pre>
1914 </div>
1915 <!-- _______________________________________________________________________ -->
1916 <div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div>
1917 <div class="doc_text">
1918 <h5>Syntax:</h5>
1919 <pre>  &lt;result&gt; = or &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1920 </pre>
1921 <h5>Overview:</h5>
1922 <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive
1923 or of its two operands.</p>
1924 <h5>Arguments:</h5>
1925 <p>The two arguments to the '<tt>or</tt>' instruction must be <a
1926  href="#t_integral">integral</a> values.  Both arguments must have
1927 identical types.</p>
1928 <h5>Semantics:</h5>
1929 <p>The truth table used for the '<tt>or</tt>' instruction is:</p>
1930 <p> </p>
1931 <div style="align: center">
1932 <table border="1" cellspacing="0" cellpadding="4">
1933   <tbody>
1934     <tr>
1935       <td>In0</td>
1936       <td>In1</td>
1937       <td>Out</td>
1938     </tr>
1939     <tr>
1940       <td>0</td>
1941       <td>0</td>
1942       <td>0</td>
1943     </tr>
1944     <tr>
1945       <td>0</td>
1946       <td>1</td>
1947       <td>1</td>
1948     </tr>
1949     <tr>
1950       <td>1</td>
1951       <td>0</td>
1952       <td>1</td>
1953     </tr>
1954     <tr>
1955       <td>1</td>
1956       <td>1</td>
1957       <td>1</td>
1958     </tr>
1959   </tbody>
1960 </table>
1961 </div>
1962 <h5>Example:</h5>
1963 <pre>  &lt;result&gt; = or int 4, %var         <i>; yields {int}:result = 4 | %var</i>
1964   &lt;result&gt; = or int 15, 40          <i>; yields {int}:result = 47</i>
1965   &lt;result&gt; = or int 4, 8            <i>; yields {int}:result = 12</i>
1966 </pre>
1967 </div>
1968 <!-- _______________________________________________________________________ -->
1969 <div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>'
1970 Instruction</a> </div>
1971 <div class="doc_text">
1972 <h5>Syntax:</h5>
1973 <pre>  &lt;result&gt; = xor &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {ty}:result</i>
1974 </pre>
1975 <h5>Overview:</h5>
1976 <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive
1977 or of its two operands.  The <tt>xor</tt> is used to implement the
1978 "one's complement" operation, which is the "~" operator in C.</p>
1979 <h5>Arguments:</h5>
1980 <p>The two arguments to the '<tt>xor</tt>' instruction must be <a
1981  href="#t_integral">integral</a> values.  Both arguments must have
1982 identical types.</p>
1983 <h5>Semantics:</h5>
1984 <p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
1985 <p> </p>
1986 <div style="align: center">
1987 <table border="1" cellspacing="0" cellpadding="4">
1988   <tbody>
1989     <tr>
1990       <td>In0</td>
1991       <td>In1</td>
1992       <td>Out</td>
1993     </tr>
1994     <tr>
1995       <td>0</td>
1996       <td>0</td>
1997       <td>0</td>
1998     </tr>
1999     <tr>
2000       <td>0</td>
2001       <td>1</td>
2002       <td>1</td>
2003     </tr>
2004     <tr>
2005       <td>1</td>
2006       <td>0</td>
2007       <td>1</td>
2008     </tr>
2009     <tr>
2010       <td>1</td>
2011       <td>1</td>
2012       <td>0</td>
2013     </tr>
2014   </tbody>
2015 </table>
2016 </div>
2017 <p> </p>
2018 <h5>Example:</h5>
2019 <pre>  &lt;result&gt; = xor int 4, %var         <i>; yields {int}:result = 4 ^ %var</i>
2020   &lt;result&gt; = xor int 15, 40          <i>; yields {int}:result = 39</i>
2021   &lt;result&gt; = xor int 4, 8            <i>; yields {int}:result = 12</i>
2022   &lt;result&gt; = xor int %V, -1          <i>; yields {int}:result = ~%V</i>
2023 </pre>
2024 </div>
2025 <!-- _______________________________________________________________________ -->
2026 <div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>'
2027 Instruction</a> </div>
2028 <div class="doc_text">
2029 <h5>Syntax:</h5>
2030 <pre>  &lt;result&gt; = shl &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt;   <i>; yields {ty}:result</i>
2031 </pre>
2032 <h5>Overview:</h5>
2033 <p>The '<tt>shl</tt>' instruction returns the first operand shifted to
2034 the left a specified number of bits.</p>
2035 <h5>Arguments:</h5>
2036 <p>The first argument to the '<tt>shl</tt>' instruction must be an <a
2037  href="#t_integer">integer</a> type.  The second argument must be an '<tt>ubyte</tt>'
2038 type.</p>
2039 <h5>Semantics:</h5>
2040 <p>The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.</p>
2041 <h5>Example:</h5>
2042 <pre>  &lt;result&gt; = shl int 4, ubyte %var   <i>; yields {int}:result = 4 &lt;&lt; %var</i>
2043   &lt;result&gt; = shl int 4, ubyte 2      <i>; yields {int}:result = 16</i>
2044   &lt;result&gt; = shl int 1, ubyte 10     <i>; yields {int}:result = 1024</i>
2045 </pre>
2046 </div>
2047 <!-- _______________________________________________________________________ -->
2048 <div class="doc_subsubsection"> <a name="i_lshr">'<tt>lshr</tt>'
2049 Instruction</a> </div>
2050 <div class="doc_text">
2051 <h5>Syntax:</h5>
2052 <pre>  &lt;result&gt; = lshr &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt;   <i>; yields {ty}:result</i>
2053 </pre>
2054
2055 <h5>Overview:</h5>
2056 <p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first
2057 operand shifted to the right a specified number of bits.</p>
2058
2059 <h5>Arguments:</h5>
2060 <p>The first argument to the '<tt>lshr</tt>' instruction must be an <a
2061  href="#t_integer">integer</a> type.  The second argument must be an '<tt>ubyte</tt>' type.</p>
2062
2063 <h5>Semantics:</h5>
2064 <p>This instruction always performs a logical shift right operation, regardless
2065 of whether the arguments are unsigned or not. The <tt>var2</tt> most significant
2066 bits will be filled with zero bits after the shift.</p>
2067
2068 <h5>Example:</h5>
2069 <pre>
2070   &lt;result&gt; = lshr uint 4, ubyte 1   <i>; yields {uint}:result = 2</i>
2071   &lt;result&gt; = lshr int 4, ubyte 2    <i>; yields {uint}:result = 1</i>
2072   &lt;result&gt; = lshr sbyte 4, ubyte 3  <i>; yields {sbyte}:result = 0</i>
2073   &lt;result&gt; = lshr sbyte -2, ubyte 1 <i>; yields {sbyte}:result = 0x7FFFFFFF </i>
2074 </pre>
2075 </div>
2076
2077 <!-- ======================================================================= -->
2078 <div class="doc_subsubsection"> <a name="i_ashr">'<tt>ashr</tt>'
2079 Instruction</a> </div>
2080 <div class="doc_text">
2081
2082 <h5>Syntax:</h5>
2083 <pre>  &lt;result&gt; = ashr &lt;ty&gt; &lt;var1&gt;, ubyte &lt;var2&gt;   <i>; yields {ty}:result</i>
2084 </pre>
2085
2086 <h5>Overview:</h5>
2087 <p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first
2088 operand shifted to the right a specified number of bits.</p>
2089
2090 <h5>Arguments:</h5>
2091 <p>The first argument to the '<tt>ashr</tt>' instruction must be an
2092 <a href="#t_integer">integer</a> type.  The second argument must be an
2093 '<tt>ubyte</tt>' type.</p>
2094
2095 <h5>Semantics:</h5>
2096 <p>This instruction always performs an arithmetic shift right operation,
2097 regardless of whether the arguments are signed or not. The <tt>var2</tt> most
2098 significant bits will be filled with the sign bit of <tt>var1</tt>.</p>
2099
2100 <h5>Example:</h5>
2101 <pre>
2102   &lt;result&gt; = ashr uint 4, ubyte 1    <i>; yields {uint}:result = 2</i>
2103   &lt;result&gt; = ashr int 4, ubyte 2      <i>; yields {int}:result = 1</i>
2104   &lt;result&gt; = ashr ubyte 4, ubyte 3    <i>; yields {ubyte}:result = 0</i>
2105   &lt;result&gt; = ashr sbyte -2, ubyte 1   <i>; yields {sbyte}:result = -1</i>
2106 </pre>
2107 </div>
2108
2109 <!-- ======================================================================= -->
2110 <div class="doc_subsection">
2111   <a name="vectorops">Vector Operations</a>
2112 </div>
2113
2114 <div class="doc_text">
2115
2116 <p>LLVM supports several instructions to represent vector operations in a
2117 target-independent manner.  This instructions cover the element-access and
2118 vector-specific operations needed to process vectors effectively.  While LLVM
2119 does directly support these vector operations, many sophisticated algorithms
2120 will want to use target-specific intrinsics to take full advantage of a specific
2121 target.</p>
2122
2123 </div>
2124
2125 <!-- _______________________________________________________________________ -->
2126 <div class="doc_subsubsection">
2127    <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
2128 </div>
2129
2130 <div class="doc_text">
2131
2132 <h5>Syntax:</h5>
2133
2134 <pre>
2135   &lt;result&gt; = extractelement &lt;n x &lt;ty&gt;&gt; &lt;val&gt;, uint &lt;idx&gt;    <i>; yields &lt;ty&gt;</i>
2136 </pre>
2137
2138 <h5>Overview:</h5>
2139
2140 <p>
2141 The '<tt>extractelement</tt>' instruction extracts a single scalar
2142 element from a packed vector at a specified index.
2143 </p>
2144
2145
2146 <h5>Arguments:</h5>
2147
2148 <p>
2149 The first operand of an '<tt>extractelement</tt>' instruction is a
2150 value of <a href="#t_packed">packed</a> type.  The second operand is
2151 an index indicating the position from which to extract the element.
2152 The index may be a variable.</p>
2153
2154 <h5>Semantics:</h5>
2155
2156 <p>
2157 The result is a scalar of the same type as the element type of
2158 <tt>val</tt>.  Its value is the value at position <tt>idx</tt> of
2159 <tt>val</tt>.  If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
2160 results are undefined.
2161 </p>
2162
2163 <h5>Example:</h5>
2164
2165 <pre>
2166   %result = extractelement &lt;4 x int&gt; %vec, uint 0    <i>; yields int</i>
2167 </pre>
2168 </div>
2169
2170
2171 <!-- _______________________________________________________________________ -->
2172 <div class="doc_subsubsection">
2173    <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
2174 </div>
2175
2176 <div class="doc_text">
2177
2178 <h5>Syntax:</h5>
2179
2180 <pre>
2181   &lt;result&gt; = insertelement &lt;n x &lt;ty&gt;&gt; &lt;val&gt;, &lt;ty&gt; &lt;elt&gt, uint &lt;idx&gt;    <i>; yields &lt;n x &lt;ty&gt;&gt;</i>
2182 </pre>
2183
2184 <h5>Overview:</h5>
2185
2186 <p>
2187 The '<tt>insertelement</tt>' instruction inserts a scalar
2188 element into a packed vector at a specified index.
2189 </p>
2190
2191
2192 <h5>Arguments:</h5>
2193
2194 <p>
2195 The first operand of an '<tt>insertelement</tt>' instruction is a
2196 value of <a href="#t_packed">packed</a> type.  The second operand is a
2197 scalar value whose type must equal the element type of the first
2198 operand.  The third operand is an index indicating the position at
2199 which to insert the value.  The index may be a variable.</p>
2200
2201 <h5>Semantics:</h5>
2202
2203 <p>
2204 The result is a packed vector of the same type as <tt>val</tt>.  Its
2205 element values are those of <tt>val</tt> except at position
2206 <tt>idx</tt>, where it gets the value <tt>elt</tt>.  If <tt>idx</tt>
2207 exceeds the length of <tt>val</tt>, the results are undefined.
2208 </p>
2209
2210 <h5>Example:</h5>
2211
2212 <pre>
2213   %result = insertelement &lt;4 x int&gt; %vec, int 1, uint 0    <i>; yields &lt;4 x int&gt;</i>
2214 </pre>
2215 </div>
2216
2217 <!-- _______________________________________________________________________ -->
2218 <div class="doc_subsubsection">
2219    <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
2220 </div>
2221
2222 <div class="doc_text">
2223
2224 <h5>Syntax:</h5>
2225
2226 <pre>
2227   &lt;result&gt; = shufflevector &lt;n x &lt;ty&gt;&gt; &lt;v1&gt;, &lt;n x &lt;ty&gt;&gt; &lt;v2&gt;, &lt;n x uint&gt; &lt;mask&gt;    <i>; yields &lt;n x &lt;ty&gt;&gt;</i>
2228 </pre>
2229
2230 <h5>Overview:</h5>
2231
2232 <p>
2233 The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
2234 from two input vectors, returning a vector of the same type.
2235 </p>
2236
2237 <h5>Arguments:</h5>
2238
2239 <p>
2240 The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
2241 with types that match each other and types that match the result of the
2242 instruction.  The third argument is a shuffle mask, which has the same number
2243 of elements as the other vector type, but whose element type is always 'uint'.
2244 </p>
2245
2246 <p>
2247 The shuffle mask operand is required to be a constant vector with either
2248 constant integer or undef values.
2249 </p>
2250
2251 <h5>Semantics:</h5>
2252
2253 <p>
2254 The elements of the two input vectors are numbered from left to right across
2255 both of the vectors.  The shuffle mask operand specifies, for each element of
2256 the result vector, which element of the two input registers the result element
2257 gets.  The element selector may be undef (meaning "don't care") and the second
2258 operand may be undef if performing a shuffle from only one vector.
2259 </p>
2260
2261 <h5>Example:</h5>
2262
2263 <pre>
2264   %result = shufflevector &lt;4 x int&gt; %v1, &lt;4 x int&gt; %v2,
2265                           &lt;4 x uint&gt; &lt;uint 0, uint 4, uint 1, uint 5&gt;    <i>; yields &lt;4 x int&gt;</i>
2266   %result = shufflevector &lt;4 x int&gt; %v1, &lt;4 x int&gt; undef,
2267                           &lt;4 x uint&gt; &lt;uint 0, uint 1, uint 2, uint 3&gt;  <i>; yields &lt;4 x int&gt;</i> - Identity shuffle.
2268 </pre>
2269 </div>
2270
2271
2272 <!-- ======================================================================= -->
2273 <div class="doc_subsection">
2274   <a name="memoryops">Memory Access and Addressing Operations</a>
2275 </div>
2276
2277 <div class="doc_text">
2278
2279 <p>A key design point of an SSA-based representation is how it
2280 represents memory.  In LLVM, no memory locations are in SSA form, which
2281 makes things very simple.  This section describes how to read, write,
2282 allocate, and free memory in LLVM.</p>
2283
2284 </div>
2285
2286 <!-- _______________________________________________________________________ -->
2287 <div class="doc_subsubsection">
2288   <a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
2289 </div>
2290
2291 <div class="doc_text">
2292
2293 <h5>Syntax:</h5>
2294
2295 <pre>
2296   &lt;result&gt; = malloc &lt;type&gt;[, uint &lt;NumElements&gt;][, align &lt;alignment&gt;]     <i>; yields {type*}:result</i>
2297 </pre>
2298
2299 <h5>Overview:</h5>
2300
2301 <p>The '<tt>malloc</tt>' instruction allocates memory from the system
2302 heap and returns a pointer to it.</p>
2303
2304 <h5>Arguments:</h5>
2305
2306 <p>The '<tt>malloc</tt>' instruction allocates
2307 <tt>sizeof(&lt;type&gt;)*NumElements</tt>
2308 bytes of memory from the operating system and returns a pointer of the
2309 appropriate type to the program.  If "NumElements" is specified, it is the
2310 number of elements allocated.  If an alignment is specified, the value result
2311 of the allocation is guaranteed to be aligned to at least that boundary.  If
2312 not specified, or if zero, the target can choose to align the allocation on any
2313 convenient boundary.</p>
2314
2315 <p>'<tt>type</tt>' must be a sized type.</p>
2316
2317 <h5>Semantics:</h5>
2318
2319 <p>Memory is allocated using the system "<tt>malloc</tt>" function, and
2320 a pointer is returned.</p>
2321
2322 <h5>Example:</h5>
2323
2324 <pre>
2325   %array  = malloc [4 x ubyte ]                    <i>; yields {[%4 x ubyte]*}:array</i>
2326
2327   %size   = <a href="#i_add">add</a> uint 2, 2                          <i>; yields {uint}:size = uint 4</i>
2328   %array1 = malloc ubyte, uint 4                   <i>; yields {ubyte*}:array1</i>
2329   %array2 = malloc [12 x ubyte], uint %size        <i>; yields {[12 x ubyte]*}:array2</i>
2330   %array3 = malloc int, uint 4, align 1024         <i>; yields {int*}:array3</i>
2331   %array4 = malloc int, align 1024                 <i>; yields {int*}:array4</i>
2332 </pre>
2333 </div>
2334
2335 <!-- _______________________________________________________________________ -->
2336 <div class="doc_subsubsection">
2337   <a name="i_free">'<tt>free</tt>' Instruction</a>
2338 </div>
2339
2340 <div class="doc_text">
2341
2342 <h5>Syntax:</h5>
2343
2344 <pre>
2345   free &lt;type&gt; &lt;value&gt;                              <i>; yields {void}</i>
2346 </pre>
2347
2348 <h5>Overview:</h5>
2349
2350 <p>The '<tt>free</tt>' instruction returns memory back to the unused
2351 memory heap to be reallocated in the future.</p>
2352
2353 <h5>Arguments:</h5>
2354
2355 <p>'<tt>value</tt>' shall be a pointer value that points to a value
2356 that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>'
2357 instruction.</p>
2358
2359 <h5>Semantics:</h5>
2360
2361 <p>Access to the memory pointed to by the pointer is no longer defined
2362 after this instruction executes.</p>
2363
2364 <h5>Example:</h5>
2365
2366 <pre>
2367   %array  = <a href="#i_malloc">malloc</a> [4 x ubyte]                    <i>; yields {[4 x ubyte]*}:array</i>
2368             free   [4 x ubyte]* %array
2369 </pre>
2370 </div>
2371
2372 <!-- _______________________________________________________________________ -->
2373 <div class="doc_subsubsection">
2374   <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
2375 </div>
2376
2377 <div class="doc_text">
2378
2379 <h5>Syntax:</h5>
2380
2381 <pre>
2382   &lt;result&gt; = alloca &lt;type&gt;[, uint &lt;NumElements&gt;][, align &lt;alignment&gt;]     <i>; yields {type*}:result</i>
2383 </pre>
2384
2385 <h5>Overview:</h5>
2386
2387 <p>The '<tt>alloca</tt>' instruction allocates memory on the current
2388 stack frame of the procedure that is live until the current function
2389 returns to its caller.</p>
2390
2391 <h5>Arguments:</h5>
2392
2393 <p>The '<tt>alloca</tt>' instruction allocates <tt>sizeof(&lt;type&gt;)*NumElements</tt>
2394 bytes of memory on the runtime stack, returning a pointer of the
2395 appropriate type to the program.    If "NumElements" is specified, it is the
2396 number of elements allocated.  If an alignment is specified, the value result
2397 of the allocation is guaranteed to be aligned to at least that boundary.  If
2398 not specified, or if zero, the target can choose to align the allocation on any
2399 convenient boundary.</p>
2400
2401 <p>'<tt>type</tt>' may be any sized type.</p>
2402
2403 <h5>Semantics:</h5>
2404
2405 <p>Memory is allocated; a pointer is returned.  '<tt>alloca</tt>'d
2406 memory is automatically released when the function returns.  The '<tt>alloca</tt>'
2407 instruction is commonly used to represent automatic variables that must
2408 have an address available.  When the function returns (either with the <tt><a
2409  href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt>
2410 instructions), the memory is reclaimed.</p>
2411
2412 <h5>Example:</h5>
2413
2414 <pre>
2415   %ptr = alloca int                              <i>; yields {int*}:ptr</i>
2416   %ptr = alloca int, uint 4                      <i>; yields {int*}:ptr</i>
2417   %ptr = alloca int, uint 4, align 1024          <i>; yields {int*}:ptr</i>
2418   %ptr = alloca int, align 1024                  <i>; yields {int*}:ptr</i>
2419 </pre>
2420 </div>
2421
2422 <!-- _______________________________________________________________________ -->
2423 <div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
2424 Instruction</a> </div>
2425 <div class="doc_text">
2426 <h5>Syntax:</h5>
2427 <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>
2428 <h5>Overview:</h5>
2429 <p>The '<tt>load</tt>' instruction is used to read from memory.</p>
2430 <h5>Arguments:</h5>
2431 <p>The argument to the '<tt>load</tt>' instruction specifies the memory
2432 address from which to load.  The pointer must point to a <a
2433  href="#t_firstclass">first class</a> type.  If the <tt>load</tt> is
2434 marked as <tt>volatile</tt>, then the optimizer is not allowed to modify
2435 the number or order of execution of this <tt>load</tt> with other
2436 volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
2437 instructions. </p>
2438 <h5>Semantics:</h5>
2439 <p>The location of memory pointed to is loaded.</p>
2440 <h5>Examples:</h5>
2441 <pre>  %ptr = <a href="#i_alloca">alloca</a> int                               <i>; yields {int*}:ptr</i>
2442   <a
2443  href="#i_store">store</a> int 3, int* %ptr                          <i>; yields {void}</i>
2444   %val = load int* %ptr                           <i>; yields {int}:val = int 3</i>
2445 </pre>
2446 </div>
2447 <!-- _______________________________________________________________________ -->
2448 <div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
2449 Instruction</a> </div>
2450 <div class="doc_text">
2451 <h5>Syntax:</h5>
2452 <pre>  store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;                   <i>; yields {void}</i>
2453   volatile store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;                   <i>; yields {void}</i>
2454 </pre>
2455 <h5>Overview:</h5>
2456 <p>The '<tt>store</tt>' instruction is used to write to memory.</p>
2457 <h5>Arguments:</h5>
2458 <p>There are two arguments to the '<tt>store</tt>' instruction: a value
2459 to store and an address in which to store it.  The type of the '<tt>&lt;pointer&gt;</tt>'
2460 operand must be a pointer to the type of the '<tt>&lt;value&gt;</tt>'
2461 operand. If the <tt>store</tt> is marked as <tt>volatile</tt>, then the
2462 optimizer is not allowed to modify the number or order of execution of
2463 this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a
2464  href="#i_store">store</a></tt> instructions.</p>
2465 <h5>Semantics:</h5>
2466 <p>The contents of memory are updated to contain '<tt>&lt;value&gt;</tt>'
2467 at the location specified by the '<tt>&lt;pointer&gt;</tt>' operand.</p>
2468 <h5>Example:</h5>
2469 <pre>  %ptr = <a href="#i_alloca">alloca</a> int                               <i>; yields {int*}:ptr</i>
2470   <a
2471  href="#i_store">store</a> int 3, int* %ptr                          <i>; yields {void}</i>
2472   %val = load int* %ptr                           <i>; yields {int}:val = int 3</i>
2473 </pre>
2474 </div>
2475
2476 <!-- _______________________________________________________________________ -->
2477 <div class="doc_subsubsection">
2478    <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
2479 </div>
2480
2481 <div class="doc_text">
2482 <h5>Syntax:</h5>
2483 <pre>
2484   &lt;result&gt; = getelementptr &lt;ty&gt;* &lt;ptrval&gt;{, &lt;ty&gt; &lt;idx&gt;}*
2485 </pre>
2486
2487 <h5>Overview:</h5>
2488
2489 <p>
2490 The '<tt>getelementptr</tt>' instruction is used to get the address of a
2491 subelement of an aggregate data structure.</p>
2492
2493 <h5>Arguments:</h5>
2494
2495 <p>This instruction takes a list of integer operands that indicate what
2496 elements of the aggregate object to index to.  The actual types of the arguments
2497 provided depend on the type of the first pointer argument.  The
2498 '<tt>getelementptr</tt>' instruction is used to index down through the type
2499 levels of a structure or to a specific index in an array.  When indexing into a
2500 structure, only <tt>uint</tt> integer constants are allowed.  When indexing
2501 into an array or pointer, only integers of 32 or 64 bits are allowed, and will
2502 be sign extended to 64-bit values.</p>
2503
2504 <p>For example, let's consider a C code fragment and how it gets
2505 compiled to LLVM:</p>
2506
2507 <pre>
2508   struct RT {
2509     char A;
2510     int B[10][20];
2511     char C;
2512   };
2513   struct ST {
2514     int X;
2515     double Y;
2516     struct RT Z;
2517   };
2518
2519   int *foo(struct ST *s) {
2520     return &amp;s[1].Z.B[5][13];
2521   }
2522 </pre>
2523
2524 <p>The LLVM code generated by the GCC frontend is:</p>
2525
2526 <pre>
2527   %RT = type { sbyte, [10 x [20 x int]], sbyte }
2528   %ST = type { int, double, %RT }
2529
2530   implementation
2531
2532   int* %foo(%ST* %s) {
2533   entry:
2534     %reg = getelementptr %ST* %s, int 1, uint 2, uint 1, int 5, int 13
2535     ret int* %reg
2536   }
2537 </pre>
2538
2539 <h5>Semantics:</h5>
2540
2541 <p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
2542 on the pointer type that is being indexed into. <a href="#t_pointer">Pointer</a>
2543 and <a href="#t_array">array</a> types can use a 32-bit or 64-bit
2544 <a href="#t_integer">integer</a> type but the value will always be sign extended
2545 to 64-bits.  <a href="#t_struct">Structure</a> types, require <tt>uint</tt>
2546 <b>constants</b>.</p>
2547
2548 <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
2549 type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ int, double, %RT
2550 }</tt>' type, a structure.  The second index indexes into the third element of
2551 the structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]],
2552 sbyte }</tt>' type, another structure.  The third index indexes into the second
2553 element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
2554 array.  The two dimensions of the array are subscripted into, yielding an
2555 '<tt>int</tt>' type.  The '<tt>getelementptr</tt>' instruction returns a pointer
2556 to this element, thus computing a value of '<tt>int*</tt>' type.</p>
2557
2558 <p>Note that it is perfectly legal to index partially through a
2559 structure, returning a pointer to an inner element.  Because of this,
2560 the LLVM code for the given testcase is equivalent to:</p>
2561
2562 <pre>
2563   int* %foo(%ST* %s) {
2564     %t1 = getelementptr %ST* %s, int 1                        <i>; yields %ST*:%t1</i>
2565     %t2 = getelementptr %ST* %t1, int 0, uint 2               <i>; yields %RT*:%t2</i>
2566     %t3 = getelementptr %RT* %t2, int 0, uint 1               <i>; yields [10 x [20 x int]]*:%t3</i>
2567     %t4 = getelementptr [10 x [20 x int]]* %t3, int 0, int 5  <i>; yields [20 x int]*:%t4</i>
2568     %t5 = getelementptr [20 x int]* %t4, int 0, int 13        <i>; yields int*:%t5</i>
2569     ret int* %t5
2570   }
2571 </pre>
2572
2573 <p>Note that it is undefined to access an array out of bounds: array and
2574 pointer indexes must always be within the defined bounds of the array type.
2575 The one exception for this rules is zero length arrays.  These arrays are
2576 defined to be accessible as variable length arrays, which requires access
2577 beyond the zero'th element.</p>
2578
2579 <p>The getelementptr instruction is often confusing.  For some more insight
2580 into how it works, see <a href="GetElementPtr.html">the getelementptr
2581 FAQ</a>.</p>
2582
2583 <h5>Example:</h5>
2584
2585 <pre>
2586     <i>; yields [12 x ubyte]*:aptr</i>
2587     %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, uint 1
2588 </pre>
2589 </div>
2590
2591 <!-- ======================================================================= -->
2592 <div class="doc_subsection"> <a name="convertops">Conversion Operations</a>
2593 </div>
2594 <div class="doc_text">
2595 <p>The instructions in this category are the conversion instructions (casting)
2596 which all take a single operand and a type. They perform various bit conversions
2597 on the operand.</p>
2598 </div>
2599
2600 <!-- _______________________________________________________________________ -->
2601 <div class="doc_subsubsection">
2602    <a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
2603 </div>
2604 <div class="doc_text">
2605
2606 <h5>Syntax:</h5>
2607 <pre>
2608   &lt;result&gt; = trunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2609 </pre>
2610
2611 <h5>Overview:</h5>
2612 <p>
2613 The '<tt>trunc</tt>' instruction truncates its operand to the type <tt>ty2</tt>.
2614 </p>
2615
2616 <h5>Arguments:</h5>
2617 <p>
2618 The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must
2619 be an <a href="#t_integer">integer</a> type, and a type that specifies the size
2620 and type of the result, which must be an <a href="#t_integral">integral</a>
2621 type. The bit size of <tt>value</tt> must be larger than the bit size of
2622 <tt>ty2</tt>. Equal sized types are not allowed.</p>
2623
2624 <h5>Semantics:</h5>
2625 <p>
2626 The '<tt>trunc</tt>' instruction truncates the high order bits in <tt>value</tt>
2627 and converts the remaining bits to <tt>ty2</tt>. Since the source size must be
2628 larger than the destination size, <tt>trunc</tt> cannot be a <i>no-op cast</i>.
2629 It will always truncate bits.</p>
2630
2631 <h5>Example:</h5>
2632 <pre>
2633   %X = trunc int 257 to ubyte              <i>; yields ubyte:1</i>
2634   %Y = trunc int 123 to bool               <i>; yields bool:true</i>
2635 </pre>
2636 </div>
2637
2638 <!-- _______________________________________________________________________ -->
2639 <div class="doc_subsubsection">
2640    <a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
2641 </div>
2642 <div class="doc_text">
2643
2644 <h5>Syntax:</h5>
2645 <pre>
2646   &lt;result&gt; = zext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2647 </pre>
2648
2649 <h5>Overview:</h5>
2650 <p>The '<tt>zext</tt>' instruction zero extends its operand to type
2651 <tt>ty2</tt>.</p>
2652
2653
2654 <h5>Arguments:</h5>
2655 <p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of
2656 <a href="#t_integral">integral</a> type, and a type to cast it to, which must
2657 also be of <a href="#t_integral">integral</a> type. The bit size of the
2658 <tt>value</tt> must be smaller than the bit size of the destination type,
2659 <tt>ty2</tt>.</p>
2660
2661 <h5>Semantics:</h5>
2662 <p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero
2663 bits until it reaches the size of the destination type, <tt>ty2</tt>. When the
2664 the operand and the type are the same size, no bit filling is done and the
2665 cast is considered a <i>no-op cast</i> because no bits change (only the type
2666 changes).</p>
2667
2668 <p>When zero extending from bool, the result will alwasy be either 0 or 1.</p>
2669
2670 <h5>Example:</h5>
2671 <pre>
2672   %X = zext int 257 to ulong              <i>; yields ulong:257</i>
2673   %Y = zext bool true to int              <i>; yields int:1</i>
2674 </pre>
2675 </div>
2676
2677 <!-- _______________________________________________________________________ -->
2678 <div class="doc_subsubsection">
2679    <a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
2680 </div>
2681 <div class="doc_text">
2682
2683 <h5>Syntax:</h5>
2684 <pre>
2685   &lt;result&gt; = sext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2686 </pre>
2687
2688 <h5>Overview:</h5>
2689 <p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
2690
2691 <h5>Arguments:</h5>
2692 <p>
2693 The '<tt>sext</tt>' instruction takes a value to cast, which must be of
2694 <a href="#t_integral">integral</a> type, and a type to cast it to, which must
2695 also be of <a href="#t_integral">integral</a> type.  The bit size of the
2696 <tt>value</tt> must be smaller than the bit size of the destination type,
2697 <tt>ty2</tt>.</p>
2698
2699 <h5>Semantics:</h5>
2700 <p>
2701 The '<tt>sext</tt>' instruction performs a sign extension by copying the sign
2702 bit (highest order bit) of the <tt>value</tt> until it reaches the bit size of
2703 the type <tt>ty2</tt>.  When the the operand and the type are the same size,
2704 no bit filling is done and the cast is considered a <i>no-op cast</i> because
2705 no bits change (only the type changes).</p>
2706
2707 <p>When sign extending from bool, the extension always results in -1 or 0.</p>
2708
2709 <h5>Example:</h5>
2710 <pre>
2711   %X = sext sbyte -1 to ushort           <i>; yields ushort:65535</i>
2712   %Y = sext bool true to int             <i>; yields int:-1</i>
2713 </pre>
2714 </div>
2715
2716 <!-- _______________________________________________________________________ -->
2717 <div class="doc_subsubsection">
2718    <a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
2719 </div>
2720
2721 <div class="doc_text">
2722
2723 <h5>Syntax:</h5>
2724
2725 <pre>
2726   &lt;result&gt; = fptrunc &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2727 </pre>
2728
2729 <h5>Overview:</h5>
2730 <p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
2731 <tt>ty2</tt>.</p>
2732
2733
2734 <h5>Arguments:</h5>
2735 <p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
2736   point</a> value to cast and a <a href="#t_floating">floating point</a> type to
2737 cast it to. The size of <tt>value</tt> must be larger than the size of
2738 <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
2739 <i>no-op cast</i>.</p>
2740
2741 <h5>Semantics:</h5>
2742 <p> The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger
2743 <a href="#t_floating">floating point</a> type to a smaller
2744 <a href="#t_floating">floating point</a> type.  If the value cannot fit within
2745 the destination type, <tt>ty2</tt>, then the results are undefined.</p>
2746
2747 <h5>Example:</h5>
2748 <pre>
2749   %X = fptrunc double 123.0 to float         <i>; yields float:123.0</i>
2750   %Y = fptrunc double 1.0E+300 to float      <i>; yields undefined</i>
2751 </pre>
2752 </div>
2753
2754 <!-- _______________________________________________________________________ -->
2755 <div class="doc_subsubsection">
2756    <a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
2757 </div>
2758 <div class="doc_text">
2759
2760 <h5>Syntax:</h5>
2761 <pre>
2762   &lt;result&gt; = fpext &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2763 </pre>
2764
2765 <h5>Overview:</h5>
2766 <p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger
2767 floating point value.</p>
2768
2769 <h5>Arguments:</h5>
2770 <p>The '<tt>fpext</tt>' instruction takes a
2771 <a href="#t_floating">floating point</a> <tt>value</tt> to cast,
2772 and a <a href="#t_floating">floating point</a> type to cast it to. The source
2773 type must be smaller than the destination type.</p>
2774
2775 <h5>Semantics:</h5>
2776 <p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller
2777 <a href="t_floating">floating point</a> type to a larger
2778 <a href="t_floating">floating point</a> type. The <tt>fpext</tt> cannot be
2779 used to make a <i>no-op cast</i> because it always changes bits. Use
2780 <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p>
2781
2782 <h5>Example:</h5>
2783 <pre>
2784   %X = fpext float 3.1415 to double        <i>; yields double:3.1415</i>
2785   %Y = fpext float 1.0 to float            <i>; yields float:1.0 (no-op)</i>
2786 </pre>
2787 </div>
2788
2789 <!-- _______________________________________________________________________ -->
2790 <div class="doc_subsubsection">
2791    <a name="i_fp2uint">'<tt>fptoui .. to</tt>' Instruction</a>
2792 </div>
2793 <div class="doc_text">
2794
2795 <h5>Syntax:</h5>
2796 <pre>
2797   &lt;result&gt; = fp2uint &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2798 </pre>
2799
2800 <h5>Overview:</h5>
2801 <p>The '<tt>fp2uint</tt>' converts a floating point <tt>value</tt> to its
2802 unsigned integer equivalent of type <tt>ty2</tt>.
2803 </p>
2804
2805 <h5>Arguments:</h5>
2806 <p>The '<tt>fp2uint</tt>' instruction takes a value to cast, which must be a
2807 <a href="#t_floating">floating point</a> value, and a type to cast it to, which
2808 must be an <a href="#t_integral">integral</a> type.</p>
2809
2810 <h5>Semantics:</h5>
2811 <p> The '<tt>fp2uint</tt>' instruction converts its
2812 <a href="#t_floating">floating point</a> operand into the nearest (rounding
2813 towards zero) unsigned integer value. If the value cannot fit in <tt>ty2</tt>,
2814 the results are undefined.</p>
2815
2816 <p>When converting to bool, the conversion is done as a comparison against
2817 zero. If the <tt>value</tt> was zero, the bool result will be <tt>false</tt>.
2818 If the <tt>value</tt> was non-zero, the bool result will be <tt>true</tt>.</p>
2819
2820 <h5>Example:</h5>
2821 <pre>
2822   %X = fp2uint double 123.0 to int         <i>; yields int:123</i>
2823   %Y = fp2uint float 1.0E+300 to bool      <i>; yields bool:true</i>
2824   %X = fp2uint float 1.04E+17 to ubyte     <i>; yields undefined:1</i>
2825 </pre>
2826 </div>
2827
2828 <!-- _______________________________________________________________________ -->
2829 <div class="doc_subsubsection">
2830    <a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a>
2831 </div>
2832 <div class="doc_text">
2833
2834 <h5>Syntax:</h5>
2835 <pre>
2836   &lt;result&gt; = fptosi &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2837 </pre>
2838
2839 <h5>Overview:</h5>
2840 <p>The '<tt>fptosi</tt>' instruction converts
2841 <a href="#t_floating">floating point</a> <tt>value</tt> to type <tt>ty2</tt>.
2842 </p>
2843
2844
2845 <h5>Arguments:</h5>
2846 <p> The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a
2847 <a href="#t_floating">floating point</a> value, and a type to cast it to, which
2848 must also be an <a href="#t_integral">integral</a> type.</p>
2849
2850 <h5>Semantics:</h5>
2851 <p>The '<tt>fptosi</tt>' instruction converts its
2852 <a href="#t_floating">floating point</a> operand into the nearest (rounding
2853 towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
2854 the results are undefined.</p>
2855
2856 <p>When converting to bool, the conversion is done as a comparison against
2857 zero. If the <tt>value</tt> was zero, the bool result will be <tt>false</tt>.
2858 If the <tt>value</tt> was non-zero, the bool result will be <tt>true</tt>.</p>
2859
2860 <h5>Example:</h5>
2861 <pre>
2862   %X = fptosi double -123.0 to int        <i>; yields int:-123</i>
2863   %Y = fptosi float 1.0E-247 to bool      <i>; yields bool:true</i>
2864   %X = fptosi float 1.04E+17 to sbyte     <i>; yields undefined:1</i>
2865 </pre>
2866 </div>
2867
2868 <!-- _______________________________________________________________________ -->
2869 <div class="doc_subsubsection">
2870    <a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a>
2871 </div>
2872 <div class="doc_text">
2873
2874 <h5>Syntax:</h5>
2875 <pre>
2876   &lt;result&gt; = uitofp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2877 </pre>
2878
2879 <h5>Overview:</h5>
2880 <p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned
2881 integer and converts that value to the <tt>ty2</tt> type.</p>
2882
2883
2884 <h5>Arguments:</h5>
2885 <p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be an
2886 <a href="#t_integral">integral</a> value, and a type to cast it to, which must
2887 be a <a href="#t_floating">floating point</a> type.</p>
2888
2889 <h5>Semantics:</h5>
2890 <p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned
2891 integer quantity and converts it to the corresponding floating point value. If
2892 the value cannot fit in the floating point value, the results are undefined.</p>
2893
2894
2895 <h5>Example:</h5>
2896 <pre>
2897   %X = uitofp int 257 to float         <i>; yields float:257.0</i>
2898   %Y = uitofp sbyte -1 to double       <i>; yields double:255.0</i>
2899 </pre>
2900 </div>
2901
2902 <!-- _______________________________________________________________________ -->
2903 <div class="doc_subsubsection">
2904    <a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a>
2905 </div>
2906 <div class="doc_text">
2907
2908 <h5>Syntax:</h5>
2909 <pre>
2910   &lt;result&gt; = sitofp &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2911 </pre>
2912
2913 <h5>Overview:</h5>
2914 <p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed
2915 integer and converts that value to the <tt>ty2</tt> type.</p>
2916
2917 <h5>Arguments:</h5>
2918 <p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be an
2919 <a href="#t_integral">integral</a> value, and a type to cast it to, which must be
2920 a <a href="#t_floating">floating point</a> type.</p>
2921
2922 <h5>Semantics:</h5>
2923 <p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed
2924 integer quantity and converts it to the corresponding floating point value. If
2925 the value cannot fit in the floating point value, the results are undefined.</p>
2926
2927 <h5>Example:</h5>
2928 <pre>
2929   %X = sitofp int 257 to float         <i>; yields float:257.0</i>
2930   %Y = sitofp sbyte -1 to double       <i>; yields double:-1.0</i>
2931 </pre>
2932 </div>
2933
2934 <!-- _______________________________________________________________________ -->
2935 <div class="doc_subsubsection">
2936    <a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a>
2937 </div>
2938 <div class="doc_text">
2939
2940 <h5>Syntax:</h5>
2941 <pre>
2942   &lt;result&gt; = ptrtoint &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2943 </pre>
2944
2945 <h5>Overview:</h5>
2946 <p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to
2947 the integer type <tt>ty2</tt>.</p>
2948
2949 <h5>Arguments:</h5>
2950 <p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which
2951 must be a <a href="t_pointer">pointer</a> value, and a type to cast it to
2952 <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.
2953
2954 <h5>Semantics:</h5>
2955 <p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type
2956 <tt>ty2</tt> by interpreting the pointer value as an integer and either
2957 truncating or zero extending that value to the size of the integer type. If
2958 <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If
2959 <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they
2960 are the same size, then nothing is done (<i>no-op cast</i>).</p>
2961
2962 <h5>Example:</h5>
2963 <pre>
2964   %X = ptrtoint int* %X to sbyte          <i>; yields truncation on 32-bit</i>
2965   %Y = ptrtoint int* %x to ulong          <i>; yields zero extend on 32-bit</i>
2966 </pre>
2967 </div>
2968
2969 <!-- _______________________________________________________________________ -->
2970 <div class="doc_subsubsection">
2971    <a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a>
2972 </div>
2973 <div class="doc_text">
2974
2975 <h5>Syntax:</h5>
2976 <pre>
2977   &lt;result&gt; = inttoptr &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
2978 </pre>
2979
2980 <h5>Overview:</h5>
2981 <p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to
2982 a pointer type, <tt>ty2</tt>.</p>
2983
2984 <h5>Arguments:</h5>
2985 <p>The '<tt>inttoptr</tt>' instruction takes an <a href="i_integer">integer</a>
2986 value to cast, and a type to cast it to, which must be a
2987 <a href="#t_pointer">pointer</a> type. </tt>
2988
2989 <h5>Semantics:</h5>
2990 <p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type
2991 <tt>ty2</tt> by applying either a zero extension or a truncation depending on
2992 the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the
2993 size of a pointer then a truncation is done. If <tt>value</tt> is smaller than
2994 the size of a pointer then a zero extension is done. If they are the same size,
2995 nothing is done (<i>no-op cast</i>).</p>
2996
2997 <h5>Example:</h5>
2998 <pre>
2999   %X = inttoptr int 255 to int*            <i>; yields zero extend on 64-bit</i>
3000   %X = inttoptr int 255 to int*            <i>; yields no-op on 32-bit </i>
3001   %Y = inttoptr short 0 to int*            <i>; yields zero extend on 32-bit</i>
3002 </pre>
3003 </div>
3004
3005 <!-- _______________________________________________________________________ -->
3006 <div class="doc_subsubsection">
3007    <a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a>
3008 </div>
3009 <div class="doc_text">
3010
3011 <h5>Syntax:</h5>
3012 <pre>
3013   &lt;result&gt; = bitcast &lt;ty&gt; &lt;value&gt; to &lt;ty2&gt;             <i>; yields ty2</i>
3014 </pre>
3015
3016 <h5>Overview:</h5>
3017 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
3018 <tt>ty2</tt> without changing any bits.</p>
3019
3020 <h5>Arguments:</h5>
3021 <p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be
3022 a first class value, and a type to cast it to, which must also be a <a
3023   href="#t_firstclass">first class</a> type. The bit sizes of <tt>value</tt>
3024 and the destination type, <tt>ty2</tt>, must be identical.</p>
3025
3026 <h5>Semantics:</h5>
3027 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
3028 <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with
3029 this conversion.  The conversion is done as if the <tt>value</tt> had been
3030 stored to memory and read back as type <tt>ty2</tt>. Pointer types may only be
3031 converted to other pointer types with this instruction. To convert pointers to
3032 other types, use the <a href="#i_inttoptr">inttoptr</a> or
3033 <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p>
3034
3035 <h5>Example:</h5>
3036 <pre>
3037   %X = bitcast ubyte 255 to sbyte         <i>; yields sbyte:-1</i>
3038   %Y = bitcast uint* %x to sint*          <i>; yields sint*:%x</i>
3039   %Z = bitcast <2xint> %V to long;        <i>; yields long: %V</i>
3040 </pre>
3041 </div>
3042
3043 <!-- ======================================================================= -->
3044 <div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
3045 <div class="doc_text">
3046 <p>The instructions in this category are the "miscellaneous"
3047 instructions, which defy better classification.</p>
3048 </div>
3049
3050 <!-- _______________________________________________________________________ -->
3051 <div class="doc_subsubsection"><a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
3052 </div>
3053 <div class="doc_text">
3054 <h5>Syntax:</h5>
3055 <pre>  &lt;result&gt; = icmp &lt;cond&gt; &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
3056 </pre>
3057 <h5>Overview:</h5>
3058 <p>The '<tt>icmp</tt>' instruction returns a boolean value based on comparison
3059 of its two integer operands.</p>
3060 <h5>Arguments:</h5>
3061 <p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is
3062 the condition code which indicates the kind of comparison to perform. It is not
3063 a value, just a keyword. The possibilities for the condition code are:
3064 <ol>
3065   <li><tt>eq</tt>: equal</li>
3066   <li><tt>ne</tt>: not equal </li>
3067   <li><tt>ugt</tt>: unsigned greater than</li>
3068   <li><tt>uge</tt>: unsigned greater or equal</li>
3069   <li><tt>ult</tt>: unsigned less than</li>
3070   <li><tt>ule</tt>: unsigned less or equal</li>
3071   <li><tt>sgt</tt>: signed greater than</li>
3072   <li><tt>sge</tt>: signed greater or equal</li>
3073   <li><tt>slt</tt>: signed less than</li>
3074   <li><tt>sle</tt>: signed less or equal</li>
3075 </ol>
3076 <p>The remaining two arguments must be of <a href="#t_integral">integral</a>,
3077 <a href="#t_pointer">pointer</a> or a <a href="#t_packed">packed</a> integral
3078 type. They must have identical types.</p>
3079 <h5>Semantics:</h5>
3080 <p>The '<tt>icmp</tt>' compares <tt>var1</tt> and <tt>var2</tt> according to
3081 the condition code given as <tt>cond</tt>. The comparison performed always
3082 yields a <a href="#t_bool">bool</a> result, as follows:
3083 <ol>
3084   <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
3085   <tt>false</tt> otherwise. No sign interpretation is necessary or performed.
3086   </li>
3087   <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
3088   <tt>false</tt> otherwise. No sign interpretation is necessary or performed.
3089   <li><tt>ugt</tt>: interprets the operands as unsigned values and yields
3090   <tt>true</tt> if <tt>var1</tt> is greater than <tt>var2</tt>.</li>
3091   <li><tt>uge</tt>: interprets the operands as unsigned values and yields
3092   <tt>true</tt> if <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3093   <li><tt>ult</tt>: interprets the operands as unsigned values and yields
3094   <tt>true</tt> if <tt>var1</tt> is less than <tt>var2</tt>.</li>
3095   <li><tt>ule</tt>: interprets the operands as unsigned values and yields
3096   <tt>true</tt> if <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3097   <li><tt>sgt</tt>: interprets the operands as signed values and yields
3098   <tt>true</tt> if <tt>var1</tt> is greater than <tt>var2</tt>.</li>
3099   <li><tt>sge</tt>: interprets the operands as signed values and yields
3100   <tt>true</tt> if <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3101   <li><tt>slt</tt>: interprets the operands as signed values and yields
3102   <tt>true</tt> if <tt>var1</tt> is less than <tt>var2</tt>.</li>
3103   <li><tt>sle</tt>: interprets the operands as signed values and yields
3104   <tt>true</tt> if <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3105   </li>
3106 </ol>
3107 <p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer
3108 values are treated as integers and then compared.</p>
3109 <p>If the operands are <a href="#t_packed">packed</a> typed, the elements of
3110 the vector are compared in turn and the predicate must hold for all
3111 elements.</p>
3112
3113 <h5>Example:</h5>
3114 <pre>  &lt;result&gt; = icmp eq int 4, 5           <i>; yields: result=false</i>
3115   &lt;result&gt; = icmp ne float* %X, %X      <i>; yields: result=false</i>
3116   &lt;result&gt; = icmp ult short 4, 5        <i>; yields: result=true</i>
3117   &lt;result&gt; = icmp sgt sbyte 4, 5        <i>; yields: result=false</i>
3118   &lt;result&gt; = icmp ule sbyte -4, 5       <i>; yields: result=false</i>
3119   &lt;result&gt; = icmp sge sbyte 4, 5        <i>; yields: result=false</i>
3120 </pre>
3121 </div>
3122
3123 <!-- _______________________________________________________________________ -->
3124 <div class="doc_subsubsection"><a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
3125 </div>
3126 <div class="doc_text">
3127 <h5>Syntax:</h5>
3128 <pre>  &lt;result&gt; = fcmp &lt;cond&gt; &lt;ty&gt; &lt;var1&gt;, &lt;var2&gt;   <i>; yields {bool}:result</i>
3129 </pre>
3130 <h5>Overview:</h5>
3131 <p>The '<tt>fcmp</tt>' instruction returns a boolean value based on comparison
3132 of its floating point operands.</p>
3133 <h5>Arguments:</h5>
3134 <p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is
3135 the condition code which indicates the kind of comparison to perform. It is not
3136 a value, just a keyword. The possibilities for the condition code are:
3137 <ol>
3138   <li><tt>false</tt>: no comparison, always returns false</li>
3139   <li><tt>oeq</tt>: ordered and equal</li>
3140   <li><tt>ogt</tt>: ordered and greater than </li>
3141   <li><tt>oge</tt>: ordered and greater than or equal</li>
3142   <li><tt>olt</tt>: ordered and less than </li>
3143   <li><tt>ole</tt>: ordered and less than or equal</li>
3144   <li><tt>one</tt>: ordered and not equal</li>
3145   <li><tt>ord</tt>: ordered (no nans)</li>
3146   <li><tt>ueq</tt>: unordered or equal</li>
3147   <li><tt>ugt</tt>: unordered or greater than </li>
3148   <li><tt>uge</tt>: unordered or greater than or equal</li>
3149   <li><tt>ult</tt>: unordered or less than </li>
3150   <li><tt>ule</tt>: unordered or less than or equal</li>
3151   <li><tt>une</tt>: unordered or not equal</li>
3152   <li><tt>uno</tt>: unordered (either nans)</li>
3153   <li><tt>true</tt>: no comparison, always returns true</li>
3154 </ol>
3155 <p>In the preceding, <i>ordered</i> means that neither operand is a QNAN while
3156 <i>unordered</i> means that either operand may be a QNAN.</p>
3157 <p>The <tt>val1</tt> and <tt>val2</tt> arguments must be of
3158 <a href="#t_floating">floating point</a>, or a <a href="#t_packed">packed</a>
3159 floating point type. They must have identical types.</p>
3160 <p>In the foregoing, <i>ordered</i> means that neither operand is a QNAN and
3161 <i>unordered</i> means that either operand is a QNAN.</p>
3162 <h5>Semantics:</h5>
3163 <p>The '<tt>fcmp</tt>' compares <tt>var1</tt> and <tt>var2</tt> according to
3164 the condition code given as <tt>cond</tt>. The comparison performed always
3165 yields a <a href="#t_bool">bool</a> result, as follows:
3166 <ol>
3167   <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
3168   <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3169   <tt>var1</tt> is equal to <tt>var2</tt>.</li>
3170   <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3171   <tt>var1</tt> is greather than <tt>var2</tt>.</li>
3172   <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3173   <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3174   <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3175   <tt>var1</tt> is less than <tt>var2</tt>.</li>
3176   <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3177   <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3178   <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
3179   <tt>var1</tt> is not equal to <tt>var2</tt>.</li>
3180   <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
3181   <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
3182   <tt>var1</tt> is equal to <tt>var2</tt>.</li>
3183   <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
3184   <tt>var1</tt> is greater than <tt>var2</tt>.</li>
3185   <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
3186   <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
3187   <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
3188   <tt>var1</tt> is less than <tt>var2</tt>.</li>
3189   <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
3190   <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
3191   <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
3192   <tt>var1</tt> is not equal to <tt>var2</tt>.</li>
3193   <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
3194   <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li>
3195 </ol>
3196 <p>If the operands are <a href="#t_packed">packed</a> typed, the elements of
3197 the vector are compared in turn and the predicate must hold for all elements.
3198 </p>
3199
3200 <h5>Example:</h5>
3201 <pre>  &lt;result&gt; = fcmp oeq float 4.0, 5.0    <i>; yields: result=false</i>
3202   &lt;result&gt; = icmp one float 4.0, 5.0    <i>; yields: result=true</i>
3203   &lt;result&gt; = icmp olt float 4.0, 5.0    <i>; yields: result=true</i>
3204   &lt;result&gt; = icmp ueq double 1.0, 2.0   <i>; yields: result=false</i>
3205 </pre>
3206 </div>
3207
3208 <!-- _______________________________________________________________________ -->
3209 <div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>'
3210 Instruction</a> </div>
3211 <div class="doc_text">
3212 <h5>Syntax:</h5>
3213 <pre>  &lt;result&gt; = phi &lt;ty&gt; [ &lt;val0&gt;, &lt;label0&gt;], ...<br></pre>
3214 <h5>Overview:</h5>
3215 <p>The '<tt>phi</tt>' instruction is used to implement the &#966; node in
3216 the SSA graph representing the function.</p>
3217 <h5>Arguments:</h5>
3218 <p>The type of the incoming values are specified with the first type
3219 field. After this, the '<tt>phi</tt>' instruction takes a list of pairs
3220 as arguments, with one pair for each predecessor basic block of the
3221 current block.  Only values of <a href="#t_firstclass">first class</a>
3222 type may be used as the value arguments to the PHI node.  Only labels
3223 may be used as the label arguments.</p>
3224 <p>There must be no non-phi instructions between the start of a basic
3225 block and the PHI instructions: i.e. PHI instructions must be first in
3226 a basic block.</p>
3227 <h5>Semantics:</h5>
3228 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the
3229 value specified by the parameter, depending on which basic block we
3230 came from in the last <a href="#terminators">terminator</a> instruction.</p>
3231 <h5>Example:</h5>
3232 <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>
3233 </div>
3234
3235 <!-- _______________________________________________________________________ -->
3236 <div class="doc_subsubsection">
3237    <a name="i_select">'<tt>select</tt>' Instruction</a>
3238 </div>
3239
3240 <div class="doc_text">
3241
3242 <h5>Syntax:</h5>
3243
3244 <pre>
3245   &lt;result&gt; = select bool &lt;cond&gt;, &lt;ty&gt; &lt;val1&gt;, &lt;ty&gt; &lt;val2&gt;             <i>; yields ty</i>
3246 </pre>
3247
3248 <h5>Overview:</h5>
3249
3250 <p>
3251 The '<tt>select</tt>' instruction is used to choose one value based on a
3252 condition, without branching.
3253 </p>
3254
3255
3256 <h5>Arguments:</h5>
3257
3258 <p>
3259 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.
3260 </p>
3261
3262 <h5>Semantics:</h5>
3263
3264 <p>
3265 If the boolean condition evaluates to true, the instruction returns the first
3266 value argument; otherwise, it returns the second value argument.
3267 </p>
3268
3269 <h5>Example:</h5>
3270
3271 <pre>
3272   %X = select bool true, ubyte 17, ubyte 42          <i>; yields ubyte:17</i>
3273 </pre>
3274 </div>
3275
3276
3277 <!-- _______________________________________________________________________ -->
3278 <div class="doc_subsubsection">
3279   <a name="i_call">'<tt>call</tt>' Instruction</a>
3280 </div>
3281
3282 <div class="doc_text">
3283
3284 <h5>Syntax:</h5>
3285 <pre>
3286   &lt;result&gt; = [tail] call [<a href="#callingconv">cconv</a>] &lt;ty&gt;* &lt;fnptrval&gt;(&lt;param list&gt;)
3287 </pre>
3288
3289 <h5>Overview:</h5>
3290
3291 <p>The '<tt>call</tt>' instruction represents a simple function call.</p>
3292
3293 <h5>Arguments:</h5>
3294
3295 <p>This instruction requires several arguments:</p>
3296
3297 <ol>
3298   <li>
3299     <p>The optional "tail" marker indicates whether the callee function accesses
3300     any allocas or varargs in the caller.  If the "tail" marker is present, the
3301     function call is eligible for tail call optimization.  Note that calls may
3302     be marked "tail" even if they do not occur before a <a
3303     href="#i_ret"><tt>ret</tt></a> instruction.
3304   </li>
3305   <li>
3306     <p>The optional "cconv" marker indicates which <a href="callingconv">calling
3307     convention</a> the call should use.  If none is specified, the call defaults
3308     to using C calling conventions.
3309   </li>
3310   <li>
3311     <p>'<tt>ty</tt>': shall be the signature of the pointer to function value
3312     being invoked.  The argument types must match the types implied by this
3313     signature.  This type can be omitted if the function is not varargs and
3314     if the function type does not return a pointer to a function.</p>
3315   </li>
3316   <li>
3317     <p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to
3318     be invoked. In most cases, this is a direct function invocation, but
3319     indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer
3320     to function value.</p>
3321   </li>
3322   <li>
3323     <p>'<tt>function args</tt>': argument list whose types match the
3324     function signature argument types. All arguments must be of
3325     <a href="#t_firstclass">first class</a> type. If the function signature
3326     indicates the function accepts a variable number of arguments, the extra
3327     arguments can be specified.</p>
3328   </li>
3329 </ol>
3330
3331 <h5>Semantics:</h5>
3332
3333 <p>The '<tt>call</tt>' instruction is used to cause control flow to
3334 transfer to a specified function, with its incoming arguments bound to
3335 the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>'
3336 instruction in the called function, control flow continues with the
3337 instruction after the function call, and the return value of the
3338 function is bound to the result argument.  This is a simpler case of
3339 the <a href="#i_invoke">invoke</a> instruction.</p>
3340
3341 <h5>Example:</h5>
3342
3343 <pre>
3344   %retval = call int %test(int %argc)
3345   call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42);
3346   %X = tail call int %foo()
3347   %Y = tail call <a href="#callingconv">fastcc</a> int %foo()
3348 </pre>
3349
3350 </div>
3351
3352 <!-- _______________________________________________________________________ -->
3353 <div class="doc_subsubsection">
3354   <a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
3355 </div>
3356
3357 <div class="doc_text">
3358
3359 <h5>Syntax:</h5>
3360
3361 <pre>
3362   &lt;resultval&gt; = va_arg &lt;va_list*&gt; &lt;arglist&gt;, &lt;argty&gt;
3363 </pre>
3364
3365 <h5>Overview:</h5>
3366
3367 <p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through
3368 the "variable argument" area of a function call.  It is used to implement the
3369 <tt>va_arg</tt> macro in C.</p>
3370
3371 <h5>Arguments:</h5>
3372
3373 <p>This instruction takes a <tt>va_list*</tt> value and the type of
3374 the argument. It returns a value of the specified argument type and
3375 increments the <tt>va_list</tt> to point to the next argument.  Again, the
3376 actual type of <tt>va_list</tt> is target specific.</p>
3377
3378 <h5>Semantics:</h5>
3379
3380 <p>The '<tt>va_arg</tt>' instruction loads an argument of the specified
3381 type from the specified <tt>va_list</tt> and causes the
3382 <tt>va_list</tt> to point to the next argument.  For more information,
3383 see the variable argument handling <a href="#int_varargs">Intrinsic
3384 Functions</a>.</p>
3385
3386 <p>It is legal for this instruction to be called in a function which does not
3387 take a variable number of arguments, for example, the <tt>vfprintf</tt>
3388 function.</p>
3389
3390 <p><tt>va_arg</tt> is an LLVM instruction instead of an <a
3391 href="#intrinsics">intrinsic function</a> because it takes a type as an
3392 argument.</p>
3393
3394 <h5>Example:</h5>
3395
3396 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
3397
3398 </div>
3399
3400 <!-- *********************************************************************** -->
3401 <div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
3402 <!-- *********************************************************************** -->
3403
3404 <div class="doc_text">
3405
3406 <p>LLVM supports the notion of an "intrinsic function".  These functions have
3407 well known names and semantics and are required to follow certain
3408 restrictions. Overall, these instructions represent an extension mechanism for
3409 the LLVM language that does not require changing all of the transformations in
3410 LLVM to add to the language (or the bytecode reader/writer, the parser,
3411 etc...).</p>
3412
3413 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
3414 prefix is reserved in LLVM for intrinsic names; thus, functions may not be named
3415 this.  Intrinsic functions must always be external functions: you cannot define
3416 the body of intrinsic functions.  Intrinsic functions may only be used in call
3417 or invoke instructions: it is illegal to take the address of an intrinsic
3418 function.  Additionally, because intrinsic functions are part of the LLVM
3419 language, it is required that they all be documented here if any are added.</p>
3420
3421
3422 <p>To learn how to add an intrinsic function, please see the <a
3423 href="ExtendingLLVM.html">Extending LLVM Guide</a>.
3424 </p>
3425
3426 </div>
3427
3428 <!-- ======================================================================= -->
3429 <div class="doc_subsection">
3430   <a name="int_varargs">Variable Argument Handling Intrinsics</a>
3431 </div>
3432
3433 <div class="doc_text">
3434
3435 <p>Variable argument support is defined in LLVM with the <a
3436  href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
3437 intrinsic functions.  These functions are related to the similarly
3438 named macros defined in the <tt>&lt;stdarg.h&gt;</tt> header file.</p>
3439
3440 <p>All of these functions operate on arguments that use a
3441 target-specific value type "<tt>va_list</tt>".  The LLVM assembly
3442 language reference manual does not define what this type is, so all
3443 transformations should be prepared to handle intrinsics with any type
3444 used.</p>
3445
3446 <p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a>
3447 instruction and the variable argument handling intrinsic functions are
3448 used.</p>
3449
3450 <pre>
3451 int %test(int %X, ...) {
3452   ; Initialize variable argument processing
3453   %ap = alloca sbyte*
3454   call void %<a href="#i_va_start">llvm.va_start</a>(sbyte** %ap)
3455
3456   ; Read a single integer argument
3457   %tmp = va_arg sbyte** %ap, int
3458
3459   ; Demonstrate usage of llvm.va_copy and llvm.va_end
3460   %aq = alloca sbyte*
3461   call void %<a href="#i_va_copy">llvm.va_copy</a>(sbyte** %aq, sbyte** %ap)
3462   call void %<a href="#i_va_end">llvm.va_end</a>(sbyte** %aq)
3463
3464   ; Stop processing of arguments.
3465   call void %<a href="#i_va_end">llvm.va_end</a>(sbyte** %ap)
3466   ret int %tmp
3467 }
3468 </pre>
3469 </div>
3470
3471 <!-- _______________________________________________________________________ -->
3472 <div class="doc_subsubsection">
3473   <a name="i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
3474 </div>
3475
3476
3477 <div class="doc_text">
3478 <h5>Syntax:</h5>
3479 <pre>  declare void %llvm.va_start(&lt;va_list&gt;* &lt;arglist&gt;)<br></pre>
3480 <h5>Overview:</h5>
3481 <P>The '<tt>llvm.va_start</tt>' intrinsic initializes
3482 <tt>*&lt;arglist&gt;</tt> for subsequent use by <tt><a
3483 href="#i_va_arg">va_arg</a></tt>.</p>
3484
3485 <h5>Arguments:</h5>
3486
3487 <P>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
3488
3489 <h5>Semantics:</h5>
3490
3491 <P>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
3492 macro available in C.  In a target-dependent way, it initializes the
3493 <tt>va_list</tt> element the argument points to, so that the next call to
3494 <tt>va_arg</tt> will produce the first variable argument passed to the function.
3495 Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the
3496 last argument of the function, the compiler can figure that out.</p>
3497
3498 </div>
3499
3500 <!-- _______________________________________________________________________ -->
3501 <div class="doc_subsubsection">
3502  <a name="i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
3503 </div>
3504
3505 <div class="doc_text">
3506 <h5>Syntax:</h5>
3507 <pre>  declare void %llvm.va_end(&lt;va_list*&gt; &lt;arglist&gt;)<br></pre>
3508 <h5>Overview:</h5>
3509 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>&lt;arglist&gt;</tt>
3510 which has been initialized previously with <tt><a href="#i_va_start">llvm.va_start</a></tt>
3511 or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
3512 <h5>Arguments:</h5>
3513 <p>The argument is a <tt>va_list</tt> to destroy.</p>
3514 <h5>Semantics:</h5>
3515 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
3516 macro available in C.  In a target-dependent way, it destroys the <tt>va_list</tt>.
3517 Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
3518  href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly
3519 with calls to <tt>llvm.va_end</tt>.</p>
3520 </div>
3521
3522 <!-- _______________________________________________________________________ -->
3523 <div class="doc_subsubsection">
3524   <a name="i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
3525 </div>
3526
3527 <div class="doc_text">
3528
3529 <h5>Syntax:</h5>
3530
3531 <pre>
3532   declare void %llvm.va_copy(&lt;va_list&gt;* &lt;destarglist&gt;,
3533                                           &lt;va_list&gt;* &lt;srcarglist&gt;)
3534 </pre>
3535
3536 <h5>Overview:</h5>
3537
3538 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position from
3539 the source argument list to the destination argument list.</p>
3540
3541 <h5>Arguments:</h5>
3542
3543 <p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
3544 The second argument is a pointer to a <tt>va_list</tt> element to copy from.</p>
3545
3546
3547 <h5>Semantics:</h5>
3548
3549 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> macro
3550 available in C.  In a target-dependent way, it copies the source
3551 <tt>va_list</tt> element into the destination list.  This intrinsic is necessary
3552 because the <tt><a href="i_va_begin">llvm.va_begin</a></tt> intrinsic may be
3553 arbitrarily complex and require memory allocation, for example.</p>
3554
3555 </div>
3556
3557 <!-- ======================================================================= -->
3558 <div class="doc_subsection">
3559   <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
3560 </div>
3561
3562 <div class="doc_text">
3563
3564 <p>
3565 LLVM support for <a href="GarbageCollection.html">Accurate Garbage
3566 Collection</a> requires the implementation and generation of these intrinsics.
3567 These intrinsics allow identification of <a href="#i_gcroot">GC roots on the
3568 stack</a>, as well as garbage collector implementations that require <a
3569 href="#i_gcread">read</a> and <a href="#i_gcwrite">write</a> barriers.
3570 Front-ends for type-safe garbage collected languages should generate these
3571 intrinsics to make use of the LLVM garbage collectors.  For more details, see <a
3572 href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>.
3573 </p>
3574 </div>
3575
3576 <!-- _______________________________________________________________________ -->
3577 <div class="doc_subsubsection">
3578   <a name="i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
3579 </div>
3580
3581 <div class="doc_text">
3582
3583 <h5>Syntax:</h5>
3584
3585 <pre>
3586   declare void %llvm.gcroot(&lt;ty&gt;** %ptrloc, &lt;ty2&gt;* %metadata)
3587 </pre>
3588
3589 <h5>Overview:</h5>
3590
3591 <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
3592 the code generator, and allows some metadata to be associated with it.</p>
3593
3594 <h5>Arguments:</h5>
3595
3596 <p>The first argument specifies the address of a stack object that contains the
3597 root pointer.  The second pointer (which must be either a constant or a global
3598 value address) contains the meta-data to be associated with the root.</p>
3599
3600 <h5>Semantics:</h5>
3601
3602 <p>At runtime, a call to this intrinsics stores a null pointer into the "ptrloc"
3603 location.  At compile-time, the code generator generates information to allow
3604 the runtime to find the pointer at GC safe points.
3605 </p>
3606
3607 </div>
3608
3609
3610 <!-- _______________________________________________________________________ -->
3611 <div class="doc_subsubsection">
3612   <a name="i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
3613 </div>
3614
3615 <div class="doc_text">
3616
3617 <h5>Syntax:</h5>
3618
3619 <pre>
3620   declare sbyte* %llvm.gcread(sbyte* %ObjPtr, sbyte** %Ptr)
3621 </pre>
3622
3623 <h5>Overview:</h5>
3624
3625 <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
3626 locations, allowing garbage collector implementations that require read
3627 barriers.</p>
3628
3629 <h5>Arguments:</h5>
3630
3631 <p>The second argument is the address to read from, which should be an address
3632 allocated from the garbage collector.  The first object is a pointer to the
3633 start of the referenced object, if needed by the language runtime (otherwise
3634 null).</p>
3635
3636 <h5>Semantics:</h5>
3637
3638 <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
3639 instruction, but may be replaced with substantially more complex code by the
3640 garbage collector runtime, as needed.</p>
3641
3642 </div>
3643
3644
3645 <!-- _______________________________________________________________________ -->
3646 <div class="doc_subsubsection">
3647   <a name="i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
3648 </div>
3649
3650 <div class="doc_text">
3651
3652 <h5>Syntax:</h5>
3653
3654 <pre>
3655   declare void %llvm.gcwrite(sbyte* %P1, sbyte* %Obj, sbyte** %P2)
3656 </pre>
3657
3658 <h5>Overview:</h5>
3659
3660 <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
3661 locations, allowing garbage collector implementations that require write
3662 barriers (such as generational or reference counting collectors).</p>
3663
3664 <h5>Arguments:</h5>
3665
3666 <p>The first argument is the reference to store, the second is the start of the
3667 object to store it to, and the third is the address of the field of Obj to
3668 store to.  If the runtime does not require a pointer to the object, Obj may be
3669 null.</p>
3670
3671 <h5>Semantics:</h5>
3672
3673 <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
3674 instruction, but may be replaced with substantially more complex code by the
3675 garbage collector runtime, as needed.</p>
3676
3677 </div>
3678
3679
3680
3681 <!-- ======================================================================= -->
3682 <div class="doc_subsection">
3683   <a name="int_codegen">Code Generator Intrinsics</a>
3684 </div>
3685
3686 <div class="doc_text">
3687 <p>
3688 These intrinsics are provided by LLVM to expose special features that may only
3689 be implemented with code generator support.
3690 </p>
3691
3692 </div>
3693
3694 <!-- _______________________________________________________________________ -->
3695 <div class="doc_subsubsection">
3696   <a name="i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
3697 </div>
3698
3699 <div class="doc_text">
3700
3701 <h5>Syntax:</h5>
3702 <pre>
3703   declare sbyte *%llvm.returnaddress(uint &lt;level&gt;)
3704 </pre>
3705
3706 <h5>Overview:</h5>
3707
3708 <p>
3709 The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a
3710 target-specific value indicating the return address of the current function
3711 or one of its callers.
3712 </p>
3713
3714 <h5>Arguments:</h5>
3715
3716 <p>
3717 The argument to this intrinsic indicates which function to return the address
3718 for.  Zero indicates the calling function, one indicates its caller, etc.  The
3719 argument is <b>required</b> to be a constant integer value.
3720 </p>
3721
3722 <h5>Semantics:</h5>
3723
3724 <p>
3725 The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer indicating
3726 the return address of the specified call frame, or zero if it cannot be
3727 identified.  The value returned by this intrinsic is likely to be incorrect or 0
3728 for arguments other than zero, so it should only be used for debugging purposes.
3729 </p>
3730
3731 <p>
3732 Note that calling this intrinsic does not prevent function inlining or other
3733 aggressive transformations, so the value returned may not be that of the obvious
3734 source-language caller.
3735 </p>
3736 </div>
3737
3738
3739 <!-- _______________________________________________________________________ -->
3740 <div class="doc_subsubsection">
3741   <a name="i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
3742 </div>
3743
3744 <div class="doc_text">
3745
3746 <h5>Syntax:</h5>
3747 <pre>
3748   declare sbyte *%llvm.frameaddress(uint &lt;level&gt;)
3749 </pre>
3750
3751 <h5>Overview:</h5>
3752
3753 <p>
3754 The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the
3755 target-specific frame pointer value for the specified stack frame.
3756 </p>
3757
3758 <h5>Arguments:</h5>
3759
3760 <p>
3761 The argument to this intrinsic indicates which function to return the frame
3762 pointer for.  Zero indicates the calling function, one indicates its caller,
3763 etc.  The argument is <b>required</b> to be a constant integer value.
3764 </p>
3765
3766 <h5>Semantics:</h5>
3767
3768 <p>
3769 The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer indicating
3770 the frame address of the specified call frame, or zero if it cannot be
3771 identified.  The value returned by this intrinsic is likely to be incorrect or 0
3772 for arguments other than zero, so it should only be used for debugging purposes.
3773 </p>
3774
3775 <p>
3776 Note that calling this intrinsic does not prevent function inlining or other
3777 aggressive transformations, so the value returned may not be that of the obvious
3778 source-language caller.
3779 </p>
3780 </div>
3781
3782 <!-- _______________________________________________________________________ -->
3783 <div class="doc_subsubsection">
3784   <a name="i_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
3785 </div>
3786
3787 <div class="doc_text">
3788
3789 <h5>Syntax:</h5>
3790 <pre>
3791   declare sbyte *%llvm.stacksave()
3792 </pre>
3793
3794 <h5>Overview:</h5>
3795
3796 <p>
3797 The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state of
3798 the function stack, for use with <a href="#i_stackrestore">
3799 <tt>llvm.stackrestore</tt></a>.  This is useful for implementing language
3800 features like scoped automatic variable sized arrays in C99.
3801 </p>
3802
3803 <h5>Semantics:</h5>
3804
3805 <p>
3806 This intrinsic returns a opaque pointer value that can be passed to <a
3807 href="#i_stackrestore"><tt>llvm.stackrestore</tt></a>.  When an
3808 <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved from
3809 <tt>llvm.stacksave</tt>, it effectively restores the state of the stack to the
3810 state it was in when the <tt>llvm.stacksave</tt> intrinsic executed.  In
3811 practice, this pops any <a href="#i_alloca">alloca</a> blocks from the stack
3812 that were allocated after the <tt>llvm.stacksave</tt> was executed.
3813 </p>
3814
3815 </div>
3816
3817 <!-- _______________________________________________________________________ -->
3818 <div class="doc_subsubsection">
3819   <a name="i_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
3820 </div>
3821
3822 <div class="doc_text">
3823
3824 <h5>Syntax:</h5>
3825 <pre>
3826   declare void %llvm.stackrestore(sbyte* %ptr)
3827 </pre>
3828
3829 <h5>Overview:</h5>
3830
3831 <p>
3832 The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of
3833 the function stack to the state it was in when the corresponding <a
3834 href="#llvm.stacksave"><tt>llvm.stacksave</tt></a> intrinsic executed.  This is
3835 useful for implementing language features like scoped automatic variable sized
3836 arrays in C99.
3837 </p>
3838
3839 <h5>Semantics:</h5>
3840
3841 <p>
3842 See the description for <a href="#i_stacksave"><tt>llvm.stacksave</tt></a>.
3843 </p>
3844
3845 </div>
3846
3847
3848 <!-- _______________________________________________________________________ -->
3849 <div class="doc_subsubsection">
3850   <a name="i_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
3851 </div>
3852
3853 <div class="doc_text">
3854
3855 <h5>Syntax:</h5>
3856 <pre>
3857   declare void %llvm.prefetch(sbyte * &lt;address&gt;,
3858                                 uint &lt;rw&gt;, uint &lt;locality&gt;)
3859 </pre>
3860
3861 <h5>Overview:</h5>
3862
3863
3864 <p>
3865 The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to insert
3866 a prefetch instruction if supported; otherwise, it is a noop.  Prefetches have
3867 no
3868 effect on the behavior of the program but can change its performance
3869 characteristics.
3870 </p>
3871
3872 <h5>Arguments:</h5>
3873
3874 <p>
3875 <tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the specifier
3876 determining if the fetch should be for a read (0) or write (1), and
3877 <tt>locality</tt> is a temporal locality specifier ranging from (0) - no
3878 locality, to (3) - extremely local keep in cache.  The <tt>rw</tt> and
3879 <tt>locality</tt> arguments must be constant integers.
3880 </p>
3881
3882 <h5>Semantics:</h5>
3883
3884 <p>
3885 This intrinsic does not modify the behavior of the program.  In particular,
3886 prefetches cannot trap and do not produce a value.  On targets that support this
3887 intrinsic, the prefetch can provide hints to the processor cache for better
3888 performance.
3889 </p>
3890
3891 </div>
3892
3893 <!-- _______________________________________________________________________ -->
3894 <div class="doc_subsubsection">
3895   <a name="i_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
3896 </div>
3897
3898 <div class="doc_text">
3899
3900 <h5>Syntax:</h5>
3901 <pre>
3902   declare void %llvm.pcmarker( uint &lt;id&gt; )
3903 </pre>
3904
3905 <h5>Overview:</h5>
3906
3907
3908 <p>
3909 The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program Counter
3910 (PC) in a region of
3911 code to simulators and other tools.  The method is target specific, but it is
3912 expected that the marker will use exported symbols to transmit the PC of the marker.
3913 The marker makes no guarantees that it will remain with any specific instruction
3914 after optimizations.  It is possible that the presence of a marker will inhibit
3915 optimizations.  The intended use is to be inserted after optimizations to allow
3916 correlations of simulation runs.
3917 </p>
3918
3919 <h5>Arguments:</h5>
3920
3921 <p>
3922 <tt>id</tt> is a numerical id identifying the marker.
3923 </p>
3924
3925 <h5>Semantics:</h5>
3926
3927 <p>
3928 This intrinsic does not modify the behavior of the program.  Backends that do not
3929 support this intrinisic may ignore it.
3930 </p>
3931
3932 </div>
3933
3934 <!-- _______________________________________________________________________ -->
3935 <div class="doc_subsubsection">
3936   <a name="i_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
3937 </div>
3938
3939 <div class="doc_text">
3940
3941 <h5>Syntax:</h5>
3942 <pre>
3943   declare ulong %llvm.readcyclecounter( )
3944 </pre>
3945
3946 <h5>Overview:</h5>
3947
3948
3949 <p>
3950 The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle
3951 counter register (or similar low latency, high accuracy clocks) on those targets
3952 that support it.  On X86, it should map to RDTSC.  On Alpha, it should map to RPCC.
3953 As the backing counters overflow quickly (on the order of 9 seconds on alpha), this
3954 should only be used for small timings.
3955 </p>
3956
3957 <h5>Semantics:</h5>
3958
3959 <p>
3960 When directly supported, reading the cycle counter should not modify any memory.
3961 Implementations are allowed to either return a application specific value or a
3962 system wide value.  On backends without support, this is lowered to a constant 0.
3963 </p>
3964
3965 </div>
3966
3967 <!-- ======================================================================= -->
3968 <div class="doc_subsection">
3969   <a name="int_libc">Standard C Library Intrinsics</a>
3970 </div>
3971
3972 <div class="doc_text">
3973 <p>
3974 LLVM provides intrinsics for a few important standard C library functions.
3975 These intrinsics allow source-language front-ends to pass information about the
3976 alignment of the pointer arguments to the code generator, providing opportunity
3977 for more efficient code generation.
3978 </p>
3979
3980 </div>
3981
3982 <!-- _______________________________________________________________________ -->
3983 <div class="doc_subsubsection">
3984   <a name="i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
3985 </div>
3986
3987 <div class="doc_text">
3988
3989 <h5>Syntax:</h5>
3990 <pre>
3991   declare void %llvm.memcpy.i32(sbyte* &lt;dest&gt;, sbyte* &lt;src&gt;,
3992                                 uint &lt;len&gt;, uint &lt;align&gt;)
3993   declare void %llvm.memcpy.i64(sbyte* &lt;dest&gt;, sbyte* &lt;src&gt;,
3994                                 ulong &lt;len&gt;, uint &lt;align&gt;)
3995 </pre>
3996
3997 <h5>Overview:</h5>
3998
3999 <p>
4000 The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source
4001 location to the destination location.
4002 </p>
4003
4004 <p>
4005 Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
4006 intrinsics do not return a value, and takes an extra alignment argument.
4007 </p>
4008
4009 <h5>Arguments:</h5>
4010
4011 <p>
4012 The first argument is a pointer to the destination, the second is a pointer to
4013 the source.  The third argument is an integer argument
4014 specifying the number of bytes to copy, and the fourth argument is the alignment
4015 of the source and destination locations.
4016 </p>
4017
4018 <p>
4019 If the call to this intrinisic has an alignment value that is not 0 or 1, then
4020 the caller guarantees that both the source and destination pointers are aligned
4021 to that boundary.
4022 </p>
4023
4024 <h5>Semantics:</h5>
4025
4026 <p>
4027 The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source
4028 location to the destination location, which are not allowed to overlap.  It
4029 copies "len" bytes of memory over.  If the argument is known to be aligned to
4030 some boundary, this can be specified as the fourth argument, otherwise it should
4031 be set to 0 or 1.
4032 </p>
4033 </div>
4034
4035
4036 <!-- _______________________________________________________________________ -->
4037 <div class="doc_subsubsection">
4038   <a name="i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
4039 </div>
4040
4041 <div class="doc_text">
4042
4043 <h5>Syntax:</h5>
4044 <pre>
4045   declare void %llvm.memmove.i32(sbyte* &lt;dest&gt;, sbyte* &lt;src&gt;,
4046                                  uint &lt;len&gt;, uint &lt;align&gt;)
4047   declare void %llvm.memmove.i64(sbyte* &lt;dest&gt;, sbyte* &lt;src&gt;,
4048                                  ulong &lt;len&gt;, uint &lt;align&gt;)
4049 </pre>
4050
4051 <h5>Overview:</h5>
4052
4053 <p>
4054 The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the source
4055 location to the destination location. It is similar to the
4056 '<tt>llvm.memcmp</tt>' intrinsic but allows the two memory locations to overlap.
4057 </p>
4058
4059 <p>
4060 Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
4061 intrinsics do not return a value, and takes an extra alignment argument.
4062 </p>
4063
4064 <h5>Arguments:</h5>
4065
4066 <p>
4067 The first argument is a pointer to the destination, the second is a pointer to
4068 the source.  The third argument is an integer argument
4069 specifying the number of bytes to copy, and the fourth argument is the alignment
4070 of the source and destination locations.
4071 </p>
4072
4073 <p>
4074 If the call to this intrinisic has an alignment value that is not 0 or 1, then
4075 the caller guarantees that the source and destination pointers are aligned to
4076 that boundary.
4077 </p>
4078
4079 <h5>Semantics:</h5>
4080
4081 <p>
4082 The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the source
4083 location to the destination location, which may overlap.  It
4084 copies "len" bytes of memory over.  If the argument is known to be aligned to
4085 some boundary, this can be specified as the fourth argument, otherwise it should
4086 be set to 0 or 1.
4087 </p>
4088 </div>
4089
4090
4091 <!-- _______________________________________________________________________ -->
4092 <div class="doc_subsubsection">
4093   <a name="i_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
4094 </div>
4095
4096 <div class="doc_text">
4097
4098 <h5>Syntax:</h5>
4099 <pre>
4100   declare void %llvm.memset.i32(sbyte* &lt;dest&gt;, ubyte &lt;val&gt;,
4101                                 uint &lt;len&gt;, uint &lt;align&gt;)
4102   declare void %llvm.memset.i64(sbyte* &lt;dest&gt;, ubyte &lt;val&gt;,
4103                                 ulong &lt;len&gt;, uint &lt;align&gt;)
4104 </pre>
4105
4106 <h5>Overview:</h5>
4107
4108 <p>
4109 The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a particular
4110 byte value.
4111 </p>
4112
4113 <p>
4114 Note that, unlike the standard libc function, the <tt>llvm.memset</tt> intrinsic
4115 does not return a value, and takes an extra alignment argument.
4116 </p>
4117
4118 <h5>Arguments:</h5>
4119
4120 <p>
4121 The first argument is a pointer to the destination to fill, the second is the
4122 byte value to fill it with, the third argument is an integer
4123 argument specifying the number of bytes to fill, and the fourth argument is the
4124 known alignment of destination location.
4125 </p>
4126
4127 <p>
4128 If the call to this intrinisic has an alignment value that is not 0 or 1, then
4129 the caller guarantees that the destination pointer is aligned to that boundary.
4130 </p>
4131
4132 <h5>Semantics:</h5>
4133
4134 <p>
4135 The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting at
4136 the
4137 destination location.  If the argument is known to be aligned to some boundary,
4138 this can be specified as the fourth argument, otherwise it should be set to 0 or
4139 1.
4140 </p>
4141 </div>
4142
4143
4144 <!-- _______________________________________________________________________ -->
4145 <div class="doc_subsubsection">
4146   <a name="i_isunordered">'<tt>llvm.isunordered.*</tt>' Intrinsic</a>
4147 </div>
4148
4149 <div class="doc_text">
4150
4151 <h5>Syntax:</h5>
4152 <pre>
4153   declare bool %llvm.isunordered.f32(float Val1, float  Val2)
4154   declare bool %llvm.isunordered.f64(double Val1, double Val2)
4155 </pre>
4156
4157 <h5>Overview:</h5>
4158
4159 <p>
4160 The '<tt>llvm.isunordered</tt>' intrinsics return true if either or both of the
4161 specified floating point values is a NAN.
4162 </p>
4163
4164 <h5>Arguments:</h5>
4165
4166 <p>
4167 The arguments are floating point numbers of the same type.
4168 </p>
4169
4170 <h5>Semantics:</h5>
4171
4172 <p>
4173 If either or both of the arguments is a SNAN or QNAN, it returns true, otherwise
4174 false.
4175 </p>
4176 </div>
4177
4178
4179 <!-- _______________________________________________________________________ -->
4180 <div class="doc_subsubsection">
4181   <a name="i_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
4182 </div>
4183
4184 <div class="doc_text">
4185
4186 <h5>Syntax:</h5>
4187 <pre>
4188   declare float %llvm.sqrt.f32(float %Val)
4189   declare double %llvm.sqrt.f64(double %Val)
4190 </pre>
4191
4192 <h5>Overview:</h5>
4193
4194 <p>
4195 The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand,
4196 returning the same value as the libm '<tt>sqrt</tt>' function would.  Unlike
4197 <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined behavior for
4198 negative numbers (which allows for better optimization).
4199 </p>
4200
4201 <h5>Arguments:</h5>
4202
4203 <p>
4204 The argument and return value are floating point numbers of the same type.
4205 </p>
4206
4207 <h5>Semantics:</h5>
4208
4209 <p>
4210 This function returns the sqrt of the specified operand if it is a positive
4211 floating point number.
4212 </p>
4213 </div>
4214
4215 <!-- _______________________________________________________________________ -->
4216 <div class="doc_subsubsection">
4217   <a name="i_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
4218 </div>
4219
4220 <div class="doc_text">
4221
4222 <h5>Syntax:</h5>
4223 <pre>
4224   declare float  %llvm.powi.f32(float  %Val, int %power)
4225   declare double %llvm.powi.f64(double %Val, int %power)
4226 </pre>
4227
4228 <h5>Overview:</h5>
4229
4230 <p>
4231 The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the
4232 specified (positive or negative) power.  The order of evaluation of
4233 multiplications is not defined.
4234 </p>
4235
4236 <h5>Arguments:</h5>
4237
4238 <p>
4239 The second argument is an integer power, and the first is a value to raise to
4240 that power.
4241 </p>
4242
4243 <h5>Semantics:</h5>
4244
4245 <p>
4246 This function returns the first value raised to the second power with an
4247 unspecified sequence of rounding operations.</p>
4248 </div>
4249
4250
4251 <!-- ======================================================================= -->
4252 <div class="doc_subsection">
4253   <a name="int_manip">Bit Manipulation Intrinsics</a>
4254 </div>
4255
4256 <div class="doc_text">
4257 <p>
4258 LLVM provides intrinsics for a few important bit manipulation operations.
4259 These allow efficient code generation for some algorithms.
4260 </p>
4261
4262 </div>
4263
4264 <!-- _______________________________________________________________________ -->
4265 <div class="doc_subsubsection">
4266   <a name="i_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
4267 </div>
4268
4269 <div class="doc_text">
4270
4271 <h5>Syntax:</h5>
4272 <pre>
4273   declare ushort %llvm.bswap.i16(ushort &lt;id&gt;)
4274   declare uint   %llvm.bswap.i32(uint &lt;id&gt;)
4275   declare ulong  %llvm.bswap.i64(ulong &lt;id&gt;)
4276 </pre>
4277
4278 <h5>Overview:</h5>
4279
4280 <p>
4281 The '<tt>llvm.bwsap</tt>' family of intrinsics is used to byteswap a 16, 32 or
4282 64 bit quantity.  These are useful for performing operations on data that is not
4283 in the target's  native byte order.
4284 </p>
4285
4286 <h5>Semantics:</h5>
4287
4288 <p>
4289 The <tt>llvm.bswap.16</tt> intrinsic returns a ushort value that has the high and low
4290 byte of the input ushort swapped.  Similarly, the <tt>llvm.bswap.i32</tt> intrinsic
4291 returns a uint value that has the four bytes of the input uint swapped, so that
4292 if the input bytes are numbered 0, 1, 2, 3 then the returned uint will have its
4293 bytes in 3, 2, 1, 0 order.  The <tt>llvm.bswap.i64</tt> intrinsic extends this concept
4294 to 64 bits.
4295 </p>
4296
4297 </div>
4298
4299 <!-- _______________________________________________________________________ -->
4300 <div class="doc_subsubsection">
4301   <a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
4302 </div>
4303
4304 <div class="doc_text">
4305
4306 <h5>Syntax:</h5>
4307 <pre>
4308   declare ubyte  %llvm.ctpop.i8 (ubyte &lt;src&gt;)
4309   declare ushort %llvm.ctpop.i16(ushort &lt;src&gt;)
4310   declare uint   %llvm.ctpop.i32(uint &lt;src&gt;)
4311   declare ulong  %llvm.ctpop.i64(ulong &lt;src&gt;)
4312 </pre>
4313
4314 <h5>Overview:</h5>
4315
4316 <p>
4317 The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set in a
4318 value.
4319 </p>
4320
4321 <h5>Arguments:</h5>
4322
4323 <p>
4324 The only argument is the value to be counted.  The argument may be of any
4325 unsigned integer type.  The return type must match the argument type.
4326 </p>
4327
4328 <h5>Semantics:</h5>
4329
4330 <p>
4331 The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.
4332 </p>
4333 </div>
4334
4335 <!-- _______________________________________________________________________ -->
4336 <div class="doc_subsubsection">
4337   <a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a>
4338 </div>
4339
4340 <div class="doc_text">
4341
4342 <h5>Syntax:</h5>
4343 <pre>
4344   declare ubyte  %llvm.ctlz.i8 (ubyte &lt;src&gt;)
4345   declare ushort %llvm.ctlz.i16(ushort &lt;src&gt;)
4346   declare uint   %llvm.ctlz.i32(uint &lt;src&gt;)
4347   declare ulong  %llvm.ctlz.i64(ulong &lt;src&gt;)
4348 </pre>
4349
4350 <h5>Overview:</h5>
4351
4352 <p>
4353 The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of
4354 leading zeros in a variable.
4355 </p>
4356
4357 <h5>Arguments:</h5>
4358
4359 <p>
4360 The only argument is the value to be counted.  The argument may be of any
4361 unsigned integer type. The return type must match the argument type.
4362 </p>
4363
4364 <h5>Semantics:</h5>
4365
4366 <p>
4367 The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant) zeros
4368 in a variable.  If the src == 0 then the result is the size in bits of the type
4369 of src. For example, <tt>llvm.ctlz(int 2) = 30</tt>.
4370 </p>
4371 </div>
4372
4373
4374
4375 <!-- _______________________________________________________________________ -->
4376 <div class="doc_subsubsection">
4377   <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a>
4378 </div>
4379
4380 <div class="doc_text">
4381
4382 <h5>Syntax:</h5>
4383 <pre>
4384   declare ubyte  %llvm.cttz.i8 (ubyte &lt;src&gt;)
4385   declare ushort %llvm.cttz.i16(ushort &lt;src&gt;)
4386   declare uint   %llvm.cttz.i32(uint &lt;src&gt;)
4387   declare ulong  %llvm.cttz.i64(ulong &lt;src&gt;)
4388 </pre>
4389
4390 <h5>Overview:</h5>
4391
4392 <p>
4393 The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of
4394 trailing zeros.
4395 </p>
4396
4397 <h5>Arguments:</h5>
4398
4399 <p>
4400 The only argument is the value to be counted.  The argument may be of any
4401 unsigned integer type.  The return type must match the argument type.
4402 </p>
4403
4404 <h5>Semantics:</h5>
4405
4406 <p>
4407 The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant) zeros
4408 in a variable.  If the src == 0 then the result is the size in bits of the type
4409 of src.  For example, <tt>llvm.cttz(2) = 1</tt>.
4410 </p>
4411 </div>
4412
4413 <!-- ======================================================================= -->
4414 <div class="doc_subsection">
4415   <a name="int_debugger">Debugger Intrinsics</a>
4416 </div>
4417
4418 <div class="doc_text">
4419 <p>
4420 The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> prefix),
4421 are described in the <a
4422 href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source Level
4423 Debugging</a> document.
4424 </p>
4425 </div>
4426
4427
4428 <!-- *********************************************************************** -->
4429 <hr>
4430 <address>
4431   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
4432   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
4433   <a href="http://validator.w3.org/check/referer"><img
4434   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
4435
4436   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
4437   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
4438   Last modified: $Date$
4439 </address>
4440 </body>
4441 </html>